Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): fail theme build on private variables (#6872)

Joey9eb7c761c0a3
diff --git a/.changeset/theme-build-private-vars-fail.md b/.changeset/theme-build-private-vars-fail.md
new file mode 100644
index 0000000000..1d98268c13
--- /dev/null
+++ b/.changeset/theme-build-private-vars-fail.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': minor
+---
+
+[breaking] IFIX-0006 -> CLN-0012 makes `theme build` exit 1 when it reports private `--_*` variables.
+
+The old contract reported private-variable errors but exited 0. The corrected contract keeps the same warnings, receipts, generated files, and `--check` output, but exits 1.
+
+To migrate, a CI step that relied on exit 0 must fix the theme's private `--_*` inputs.
+
+@josephfarina
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index 8b79f5db10..54c2710bef 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -23,9 +23,10 @@
* the selected theme's parsed bindings and inheritance, never from comment or
* string contents. A registry that cannot be preserved fails before output
* generation, including in check mode. Errors throw AstryxError (with a stable
- * code). Human progress is emitted through the shared `logger`
- * (silent by default), so the CLI keeps its exact output while a programmatic
- * caller stays quiet.
+ * code). Private-variable diagnostics keep their released warnings and generated
+ * files; an internal callback lets the CLI make only the process status fail.
+ * Human progress is emitted through the shared `logger` (silent by default), so
+ * the CLI keeps its exact output while a programmatic caller stays quiet.
*
* The installed `@astryxdesign/core` is an independently versioned optional
* peer, so it can be older than the CLI. A theme that uses only baseline
@@ -2315,7 +2316,7 @@ function validateHeadingTypeAugmentationSupport(themeDef) {
* `logger` (silent by default).
*
* @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any}} [options] -
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void}} [options] -
* `out` overrides the output CSS path; `check` compares against on-disk outputs
* instead of writing. `iconsSpecifier` overrides the icon registry import
* specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
@@ -2472,6 +2473,7 @@ async function themeBuildInternal(
logger.error(` [error] ${source}${e}`);
}
if (privateVarErrors.length > 0) {
+ options.__onPrivateVarError?.();
logger.error(
`\n ${source}${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`,
);
@@ -3230,7 +3232,7 @@ async function preloadFamilySource(filePath, loader, interception) {
finally { patch.undo(); }
}
-/** @param {string[]} files @param {{familyKey: string, check?: boolean, iconsSpecifier?: string}} options @param {{cwd?: string}} [ctx] */
+/** @param {string[]} files @param {{familyKey: string, check?: boolean, iconsSpecifier?: string, __onPrivateVarError?: () => void}} options @param {{cwd?: string}} [ctx] */
export async function themeBuildFamily(
files,
options,
@@ -3267,7 +3269,7 @@ export async function themeBuildFamily(
}
const file = source.file;
// prettier-ignore
- const member = await themeBuildInternal(file, {iconsSpecifier: options.iconsSpecifier, __prepareFamily: true, __familyLoader: familyLoader, __familyInterception: familyInterception}, {cwd});
+ const member = await themeBuildInternal(file, {iconsSpecifier: options.iconsSpecifier, __prepareFamily: true, __familyLoader: familyLoader, __familyInterception: familyInterception, __onPrivateVarError: options.__onPrivateVarError}, {cwd});
if (!member || member.type) {
throw new AstryxError(
`Theme family member "${file}" did not produce a complete build plan.`,
diff --git a/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs b/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
index a438e2a2af..239fe326dc 100644
--- a/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.adaptations.test.mjs
@@ -519,7 +519,11 @@ describe('theme build adaptations', () => {
);
const result = await build(project, themeFile);
+ expect(result.code).toBe(1);
expect(`${result.stdout}${result.stderr}`).toContain('private var');
+ expect(fs.existsSync(path.join(themesDir, 'rule-private.css'))).toBe(true);
+ expect(fs.existsSync(path.join(themesDir, 'rule-private.js'))).toBe(true);
+ expect(fs.existsSync(path.join(themesDir, 'rule-private.d.ts'))).toBe(true);
});
it('rejects cycles across co-matching rules before writing output', async () => {
diff --git a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
index 0c74b83af1..ea3a79f40b 100644
--- a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs
@@ -71,9 +71,9 @@ function run(args) {
}
describe('theme command human output is plain ASCII', () => {
- it('a standalone build: ok, warning, error, notice, and font help lines', async () => {
+ it('a private-variable build keeps its output and exits 1', async () => {
const short = await run(['build', 'ocean.mjs']);
- expect(short.code).toBe(0);
+ expect(short.code).toBe(1);
expect(short.stdout).toContain(
'[note] Fonts named but not loaded: "Inter"',
);
@@ -84,7 +84,7 @@ describe('theme command human output is plain ASCII', () => {
dir,
);
- expect(result.code).toBe(0);
+ expect(result.code).toBe(1);
expect(result.stdout).toContain('[ok] ocean.css');
expect(result.stderr).toContain('[warn] Unknown component "progressbar"');
expect(result.stderr).toContain('[error] Component "button"');
@@ -93,10 +93,37 @@ describe('theme command human output is plain ASCII', () => {
expect(nonAscii(result)).toEqual([]);
});
+ it('JSON build and check keep their receipts and exit 1', async () => {
+ const built = await runCli(['--json', 'theme', 'build', 'ocean.mjs'], dir);
+ expect(built.code).toBe(1);
+ expect(built.stderr).toBe('');
+ const receipt = JSON.parse(built.stdout);
+ expect(receipt.type).toBe('theme.build');
+ expect(receipt.data.name).toBe('ocean');
+ expect(receipt.data.warnings).toEqual(
+ expect.arrayContaining([expect.stringContaining('--_button-radius')]),
+ );
+
+ const checked = await runCli(
+ ['--json', 'theme', 'build', 'ocean.mjs', '--check'],
+ dir,
+ );
+ expect(checked.code).toBe(1);
+ expect(checked.stderr).toBe('');
+ expect(JSON.parse(checked.stdout)).toMatchObject({
+ type: 'theme.build.check',
+ data: {name: 'ocean', upToDate: true, stale: []},
+ });
+
+ for (const extension of ['css', 'css.d.ts', 'js', 'd.ts']) {
+ expect(fs.existsSync(path.join(dir, `ocean.${extension}`))).toBe(true);
+ }
+ });
+
it('--check, up to date and stale', async () => {
await run(['build', 'ocean.mjs']);
const upToDate = await run(['build', 'ocean.mjs', '--check']);
- expect(upToDate.code).toBe(0);
+ expect(upToDate.code).toBe(1);
expect(upToDate.stdout).toContain('[ok] Theme outputs are up to date');
expect(nonAscii(upToDate)).toEqual([]);
@@ -109,7 +136,7 @@ describe('theme command human output is plain ASCII', () => {
it('a batch build and check', async () => {
const built = await run(['build', 'ocean.mjs', 'ocean-calm.mjs']);
- expect(built.code).toBe(0);
+ expect(built.code).toBe(1);
expect(built.stdout).toContain('[ok] Built 2 themes.');
expect(nonAscii(built)).toEqual([]);
@@ -119,7 +146,7 @@ describe('theme command human output is plain ASCII', () => {
'ocean-calm.mjs',
'--check',
]);
- expect(checked.code).toBe(0);
+ expect(checked.code).toBe(1);
expect(checked.stdout).toContain('[ok] Checked 2 themes.');
expect(nonAscii(checked)).toEqual([]);
});
@@ -134,7 +161,7 @@ describe('theme command human output is plain ASCII', () => {
'ocean-family',
];
const built = await run(familyArgs);
- expect(built.code).toBe(0);
+ expect(built.code).toBe(1);
expect(built.stdout).toContain('[ok] ocean-family.css');
expect(nonAscii(built)).toEqual([]);
diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjs
index 85ca478235..9274b7509c 100644
--- a/packages/cli/clients/cli/commands/build-theme.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.mjs
@@ -6,9 +6,11 @@
* Thin CLI wrapper. The `build` compiler lives in the programmatic API
* (../../api/theme/build/build.mjs); `list`/`add` delegate to the
* ../../api/theme/list/list.mjs and ../../api/theme/add/add.mjs leaves. This
- * file only parses options, injects a logger, renders human output, and maps
- * AstryxError → cliError. Watch mode (a human-interactive, long-running loop)
- * stays here because it re-invokes `theme build` as a child process.
+ * file only parses options, injects a logger, renders human output, maps
+ * AstryxError → cliError, and turns reported private-variable errors into exit 1
+ * after preserving the build output. Watch mode (a human-interactive,
+ * long-running loop) stays here because it re-invokes `theme build` as a child
+ * process.
*
* The command surface (group + subcommand descriptions, args, flags) is sourced
* from the colocated CommandDocs via `defineCommand`; this file supplies only
@@ -632,6 +634,10 @@ export function registerTheme(program) {
// [ok]/[warn] lines, and the install instructions are all emitted from
// inside themeBuild via the shared logger.
logger.setSilent(json);
+ let privateVarError = false;
+ const onPrivateVarError = () => {
+ privateVarError = true;
+ };
if (options.family) {
try {
@@ -641,11 +647,15 @@ export function registerTheme(program) {
familyKey: /** @type {string} */ (options.familyKey),
check: options.check,
iconsSpecifier: options.iconsSpecifier,
+ __onPrivateVarError: onPrivateVarError,
},
{cwd: process.cwd()},
);
if (json) jsonOut(result);
- if (result.type === 'theme.build.check' && !result.data.upToDate) {
+ if (
+ privateVarError ||
+ (result.type === 'theme.build.check' && !result.data.upToDate)
+ ) {
process.exitCode = 1;
}
return NO_RESULT_SET;
@@ -673,6 +683,7 @@ export function registerTheme(program) {
out: options.out,
check: options.check,
iconsSpecifier: options.iconsSpecifier,
+ __onPrivateVarError: onPrivateVarError,
};
let result;
if (report) {
@@ -752,10 +763,10 @@ export function registerTheme(program) {
);
}
- // In --check mode a stale/missing output is a failure: exit non-zero
- // (after emitting the receipt) so CI can gate on it. The receipt is
- // already printed above (shared logger or --json envelope).
- if (options.check && stale) {
+ // Private-variable diagnostics are build failures even though the released
+ // output and generated files stay unchanged. Stale --check output is also
+ // a failure after its receipt has been emitted.
+ if (privateVarError || (options.check && stale)) {
process.exitCode = 1;
}