Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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',