An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): document theme build flag defaults and refusals (#6546)
Joey53fbd99e4cb1
diff --git a/.changeset/cli-spec-theme-build-flag-docs.md b/.changeset/cli-spec-theme-build-flag-docs.mdnew file mode 100644index 0000000000..eb1cd87add--- /dev/null+++ b/.changeset/cli-spec-theme-build-flag-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `astryx theme build --help` and the capability manifest now state each flag's default and which flag combinations are refused (`--family` with `--out` or `--watch`, `--check` with `--watch`, `--watch` with `--json`, `--out` with more than one file), with the error code the refusal returns.++@josephfarinadiff --git a/packages/cli/clients/cli/commands/build-theme.flag-docs.test.mjs b/packages/cli/clients/cli/commands/build-theme.flag-docs.test.mjsnew file mode 100644index 0000000000..59ecbfbe13--- /dev/null+++ b/packages/cli/clients/cli/commands/build-theme.flag-docs.test.mjs@@ -0,0 +1,110 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Every `theme build` flag interaction is discoverable.+ *+ * Each combination the command refuses is refused before any work, and the+ * refusal is named in the machine-readable manifest's description of at least+ * one of the flags involved. Flags that fill in a value when omitted state+ * their default there too.+ */++import {describe, it, expect, beforeAll, afterAll} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {runCli} from '../../../test-utils/run-cli.mjs';+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';++/** @type {string} */+let dir;+/** @type {Map<string, string>} flag token -> manifest description */+let descriptions;++beforeAll(async () => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-flag-docs-'));+ // Refusals happen before a theme loads; the files only need to exist.+ for (const name of ['a.mjs', 'b.mjs']) {+ fs.writeFileSync(path.join(dir, name), 'export default {};\n');+ }++ const manifest = JSON.parse(+ (await runCli(['--json', 'manifest'], dir)).stdout,+ ).data;+ const theme = manifest.commands.find(command => command.name === 'theme');+ const build = theme.subcommands.find(+ command => command.name === 'theme build',+ );+ descriptions = new Map(+ build.options.map(option => [+ /** @type {string} */ (option.flag.match(/--[a-z-]+/)?.[0]),+ option.description,+ ]),+ );+});++afterAll(() => {+ fs.rmSync(dir, {recursive: true, force: true});+});++/** @param {string} flag */+function description(flag) {+ const text = descriptions.get(flag);+ expect(text, `manifest has no ${flag} option`).toBeDefined();+ return /** @type {string} */ (text);+}++/**+ * Whether `a`'s description names `b`, or `b`'s names `a`. `b` may also be a+ * pattern for a condition that is not a flag.+ * @param {string} a+ * @param {string | RegExp} b+ */+function documented(a, b) {+ const partner = typeof b === 'string' ? new RegExp(`${b}\\b`) : b;+ if (partner.test(description(a))) return true;+ return (+ typeof b === 'string' &&+ descriptions.has(b) &&+ new RegExp(`${a}\\b`).test(description(b))+ );+}++const REFUSED = [+ {+ pair: ['--family', '--out'],+ args: ['--family', 'a.mjs', 'b.mjs', '--family-key', 'k', '--out', 'x.css'],+ },+ {+ pair: ['--family', '--watch'],+ args: ['--family', 'a.mjs', 'b.mjs', '--family-key', 'k', '--watch'],+ },+ {pair: ['--family', '--family-key'], args: ['--family', 'a.mjs', 'b.mjs']},+ {pair: ['--family-key', '--family'], args: ['a.mjs', '--family-key', 'k']},+ {pair: ['--check', '--watch'], args: ['a.mjs', '--check', '--watch']},+ {+ pair: ['--out', /several|more than one|single theme|one theme/i],+ args: ['a.mjs', 'b.mjs', '--out', 'x.css'],+ },+ {pair: ['--watch', '--json'], args: ['a.mjs', '--watch']},+];++describe('theme build flag interactions are documented', () => {+ for (const {pair, args} of REFUSED) {+ const [a, b] = pair;+ it(`${a} with ${String(b)} is refused and documented`, async () => {+ const result = await runCli(['--json', 'theme', 'build', ...args], dir);++ expect(result.code).toBe(1);+ expect(JSON.parse(result.stdout).code).toBe(+ ERROR_CODES.ERR_THEME_INVALID,+ );+ expect(documented(a, b)).toBe(true);+ });+ }++ it('flags that fill in an omitted value state their default', () => {+ expect(description('--out')).toMatch(/default/i);+ expect(description('--icons-specifier')).toMatch(/default/i);+ });+});diff --git a/packages/cli/clients/cli/commands/theme-build.doc.mjs b/packages/cli/clients/cli/commands/theme-build.doc.mjsindex d195524983..27de8b3e5c 100644--- a/packages/cli/clients/cli/commands/theme-build.doc.mjs+++ b/packages/cli/clients/cli/commands/theme-build.doc.mjs@@ -28,34 +28,35 @@ export const doc = {{flag: '--family',description:- 'Build the selected extension family into one keyed CSS, JS, and declaration set',+ 'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',},{flag: '--family-key <key>',description:- 'Lower-kebab filename stem required with --family; must differ from every member name',+ 'Lower-kebab filename stem required with --family and refused without it; must differ from every member name (ERR_THEME_INVALID)',},{flag: '-o, --out <path>',param: 'options.out',- description: 'Output CSS file path (single theme only)',+ description:+ 'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',},{flag: '--icons-specifier <specifier>',param: 'options.iconsSpecifier',description:- 'Override the icon-registry import in the generated JS module (for example, ./icons.mjs)',+ "Override the icon-registry import in the generated JS module, for example ./icons.mjs (default: the specifier in the theme source's own import). With --family it applies to every member's icon import",},{flag: '-w, --watch',description:- 'Rebuild automatically when a theme file changes (Ctrl-C to stop)',+ 'Rebuild automatically when a theme file changes (Ctrl-C to stop). Refused with --check, --family, or --json (ERR_THEME_INVALID)',},{flag: '-c, --check',param: 'options.check',description:- 'Verify the committed outputs match the source without writing; exit non-zero if stale',+ 'Verify the committed outputs match the source without writing; exit non-zero if stale. Composes with --family and several files; refused with --watch (ERR_THEME_INVALID)',},],examples: [