Skip to content

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.md
new file mode 100644
index 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.
+
+@josephfarina
diff --git a/packages/cli/clients/cli/commands/build-theme.flag-docs.test.mjs b/packages/cli/clients/cli/commands/build-theme.flag-docs.test.mjs
new file mode 100644
index 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.mjs
index 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: [