An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): document every theme build receipt field (#6545)
Joey27e601b892f9
diff --git a/.changeset/cli-spec-theme-build-receipt-doc.md b/.changeset/cli-spec-theme-build-receipt-doc.mdnew file mode 100644index 0000000000..72087586a6--- /dev/null+++ b/.changeset/cli-spec-theme-build-receipt-doc.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] The `themeBuild()` reference and the `theme.build` response-type entry (and the CLI README table generated from it) now document every field of the receipt by name, including `notices`, the advisories (such as a font the theme names but does not load) that had no documentation.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex ec349cf985..8bea47e594 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -426,7 +426,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `hook.list` | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. || `hook.detail` | One hook's full authored HookDoc. || `hook.detail.params` | Just one hook's parameters table (HookParamDoc[]). |-| `theme.build` | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings. |+| `theme.build` | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load). || `theme.build.check` | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing. || `theme.build.batch` | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. || `theme.list` | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package. |diff --git a/packages/cli/api/theme/build/build.receipt-doc.test.mjs b/packages/cli/api/theme/build/build.receipt-doc.test.mjsnew file mode 100644index 0000000000..09bbdbe3fe--- /dev/null+++ b/packages/cli/api/theme/build/build.receipt-doc.test.mjs@@ -0,0 +1,111 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * Every field `themeBuild()` returns is named in its FunctionDoc and in the+ * response-types doc.+ *+ * The receipt is a stable machine-readable response, so each field needs+ * consumer documentation, not only a typedef. The fields are read off a real+ * build, so a field added to the receipt without documentation fails here.+ */++import {describe, it, expect, beforeAll, afterEach} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {themeBuild} from './build.mjs';+import {doc} from '../themeBuild.doc.mjs';+import {doc as responseTypes} from '../../../foundation/response/response-types.doc.mjs';+import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';++/** @type {string[]} */+const dirs = [];++beforeAll(() => {+ ensureCoreBuilt();+}, 200_000);++afterEach(() => {+ for (const dir of dirs.splice(0)) {+ fs.rmSync(dir, {recursive: true, force: true});+ }+});++/** @returns {string} a temp dir holding a theme that exercises every field */+function themeDir() {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-receipt-doc-'));+ dirs.push(dir);+ fs.writeFileSync(+ path.join(dir, 'ocean.mjs'),+ `export default {+ name: 'ocean',+ tokens: {'--color-background-body': '#ffffff', '--font-family-body': '"Inter", sans-serif'},+ components: {progressbar: {base: {color: 'red'}}},+};+`,+ );+ return dir;+}++/** @param {string} type */+function returnsDescription(type) {+ const entry = doc.returns?.find(r => r.type === type);+ expect(entry, `themeBuild doc has no ${type} return`).toBeDefined();+ return /** @type {{description: string}} */ (entry).description;+}++/** @param {string} description @param {string[]} fields */+function undocumented(description, fields) {+ return fields.filter(+ field => !new RegExp(String.raw`\b${field}\b`).test(description),+ );+}++describe('themeBuild() consumer docs name every receipt field', () => {+ it('theme.build', async () => {+ const dir = themeDir();+ const result = await themeBuild('ocean.mjs', {}, {cwd: dir});++ expect(result?.type).toBe('theme.build');+ const data = /** @type {Record<string, any>} */ (result?.data);+ // The theme is chosen so the optional arrays are non-empty.+ expect(data.warnings.length).toBeGreaterThan(0);+ expect(data.notices.length).toBeGreaterThan(0);++ const fields = [+ ...Object.keys(data),+ ...Object.keys(data.outputs),+ 'variantsDts',+ ];+ expect(undocumented(returnsDescription('theme.build'), fields)).toEqual([]);+ });++ it('theme.build in the response-types doc', async () => {+ const dir = themeDir();+ const result = await themeBuild('ocean.mjs', {}, {cwd: dir});+ const data = /** @type {Record<string, any>} */ (result?.data);+ const member = responseTypes.members.find(m => m.value === 'theme.build');+ expect(member, 'response-types has no theme.build member').toBeDefined();++ const fields = [+ ...Object.keys(data),+ ...Object.keys(data.outputs),+ 'variantsDts',+ ];+ expect(+ undocumented(/** @type {{description: string}} */ (member).description, fields),+ ).toEqual([]);+ });++ it('theme.build.check', async () => {+ const dir = themeDir();+ const result = await themeBuild('ocean.mjs', {check: true}, {cwd: dir});++ expect(result?.type).toBe('theme.build.check');+ const data = /** @type {Record<string, any>} */ (result?.data);+ const fields = [...Object.keys(data), ...Object.keys(data.stale[0])];+ expect(+ undocumented(returnsDescription('theme.build.check'), fields),+ ).toEqual([]);+ });+});diff --git a/packages/cli/api/theme/themeBuild.doc.mjs b/packages/cli/api/theme/themeBuild.doc.mjsindex 111231070f..e87b034bca 100644--- a/packages/cli/api/theme/themeBuild.doc.mjs+++ b/packages/cli/api/theme/themeBuild.doc.mjs@@ -73,7 +73,7 @@ export const doc = {{type: 'theme.build',description:- 'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and validation warnings—including exact canonical replacements for deprecated component target keys. Resolves to null instead when the theme produced no CSS (nothing to build).',+ 'Build receipt {name, tokenCount, componentCount, sizeKB, outputs, warnings, notices}: the theme name; how many tokens (portable plus theme-local) and component targets it overrides; the CSS size in KB; the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}; warnings, the defects the author should fix, including exact canonical replacements for deprecated component target keys and declarations the generator dropped; and notices, advisories about a correct theme, such as a font it names but does not load. Resolves to null instead when the theme produced no CSS (nothing to build).',},{type: 'theme.build.check',diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex e532864f0c..067f8a4c8a 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -198,7 +198,7 @@ export const doc = {{value: 'theme.build',description:- 'A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.',+ 'A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).',},{value: 'theme.build.check',