An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): make every command's text output match its --json data (#6616)
Joeyb1da7d239b11
diff --git a/.changeset/fix-cli-text-json-parity.md b/.changeset/fix-cli-text-json-parity.mdnew file mode 100644index 0000000000..7d7d148bdd--- /dev/null+++ b/.changeset/fix-cli-text-json-parity.md@@ -0,0 +1,16 @@+---+'@astryxdesign/cli': patch+---++[fix] Make every command's text output match its --json data++`upgrade --list` text now renders each codemod from the JSON result (name,+title, version, optional) instead of the API logger, with no `(undefined)`+rows. `theme targets` prints one line per target via the formatter kit's+inline layout and now shows className. `docs` list shows the package field.+A manifest-driven parity test covers the commands this PR fixes and catches+future regressions in the same family; commands with known deferred+divergences are covered by envelope and exit-code checks and have+allowlist entries that explain the gap.++@josephfarinadiff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjsindex 8b1443cc18..cb90ea65f4 100644--- a/packages/cli/clients/cli/commands/build-theme.mjs+++ b/packages/cli/clients/cli/commands/build-theme.mjs@@ -33,7 +33,7 @@ import {fileURLToPath} from 'node:url';import {spawn} from 'node:child_process';import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';import {jsonOut} from '../../../foundation/response/json.mjs';-import {emit, section, text, list, code} from '../formatters/index.mjs';+import {emit, section, text, list, records, code} from '../formatters/index.mjs';import {logger} from '../../../api/logger.mjs';import {cliError} from '../lib/cli-error.mjs';import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';@@ -229,47 +229,6 @@ function printThemeList(themes) {);}-/**- * Render the targets as one greppable line each, under an aligned header. A- * `records()` block would be five lines per target — over a thousand for the- * full surface, which is the view this command exists to make readable.- * @param {import('../../../api/theme/theme.type.mjs').ThemeTargetEntry[]} targets- * @returns {string}- */-function formatTargetsTable(targets) {- const rows = targets.map(t => ({- key: t.deprecatedFor- ? `${t.key} [deprecated; use ${t.deprecatedFor}]`- : t.key,- component: t.component,- props: t.props.join(', ') || '-',- states: t.states.join(', ') || '-',- }));- const head = {- key: 'key',- component: 'component',- props: 'props',- states: 'states',- };- const width = (/** @type {'key'|'component'|'props'} */ field) =>- [head, ...rows].reduce((max, r) => Math.max(max, r[field].length), 0);- const w = {- key: width('key'),- component: width('component'),- props: width('props'),- };- const line = (/** @type {typeof head} */ r) =>- [- r.key.padEnd(w.key),- r.component.padEnd(w.component),- r.props.padEnd(w.props),- r.states,- ]- .join(' ')- .trimEnd();- return [line(head), ...rows.map(line)].join('\n');-}-/*** @param {import('commander').Command} program*/@@ -811,9 +770,16 @@ export function registerTheme(program) {emit(section('Theming targets',- `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}`,+ `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className - deprecatedFor)`,),- text(formatTargetsTable(targets)),+ records(targets, {+ fields: ['key', 'component', 'props', 'states', 'className', 'deprecatedFor'],+ layout: 'inline',+ format: {+ deprecatedFor: (/** @type {string|null} */ v) =>+ v ? `deprecated; use ${v}` : '',+ },+ }),text([`Each key goes under \`components\` in defineTheme; it paints \`.astryx-<key>\`.`,diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjsindex 4ee36f0095..048d2939b7 100644--- a/packages/cli/clients/cli/commands/docs.mjs+++ b/packages/cli/clients/cli/commands/docs.mjs@@ -280,7 +280,7 @@ export function registerDocs(program) {emit(section('Available docs'),records(result.data, {- fields: ['topic', 'description'],+ fields: ['topic', 'description', 'package'],layout: 'inline',}),text(diff --git a/packages/cli/clients/cli/commands/text-json-parity.test.mjs b/packages/cli/clients/cli/commands/text-json-parity.test.mjsnew file mode 100644index 0000000000..6f51834491--- /dev/null+++ b/packages/cli/clients/cli/commands/text-json-parity.test.mjs@@ -0,0 +1,719 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Text/JSON parity — every command's human output is a projection of its+ * JSON envelope.+ *+ * Architecture: cli-surface INV4, INV5. Spec: AST-042 FR1.+ *+ * The test:+ * 1. Enumerates every JSON-capable command from the live manifest and fails+ * when a command has no parity case. A new command must add one.+ * 2. Runs each case in text mode and --json mode via the in-process harness.+ * 3. Checks:+ * a. Every `key: value` record line in the text names a key that exists+ * in the JSON data (criterion 1 — text shows no fact JSON lacks).+ * b. Every JSON leaf field appears in the text, unless the allowlist+ * forgives it with a reason (criterion 2).+ *+ * Allowlist entries are stale-checked: an entry that forgives a field that+ * does not appear anywhere in the JSON output FAILS the test, so the+ * allowlist shrinks over time.+ *+ * DO NOT add allowlist entries without a reason. Headings and invocation-+ * prefixed hints are the only categories that are structurally OK to forgive;+ * everything else is a divergence that should be fixed.+ */++import {describe, it, expect, beforeAll, afterAll} from 'vitest';+import * as fs from 'node:fs';+import * as path from 'node:path';+import * as os from 'node:os';+import {fileURLToPath} from 'node:url';+import {runCli} from '../../../test-utils/run-cli.mjs';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = path.resolve(__dirname, '../../../../..');++// ─── Helpers ────────────────────────────────────────────────────────────────++/**+ * Normalize a text value for comparison: collapse whitespace, strip the+ * package-manager invocation prefix, and undo ASCII normalization.+ * @param {string} s+ * @returns {string}+ */+function normalize(s) {+ return s+ .replace(/\s+/g, ' ')+ .replace(/(npx|pnpm exec|yarn dlx|bunx)\s+astryx/g, 'astryx')+ .replace(/[\u2014\u2013]/g, '-')+ .replace(/[\u2018\u2019]/g, "'")+ .replace(/[\u201C\u201D]/g, '"')+ .replace(/\u2026/g, '...')+ .trim();+}++/**+ * Extract `key: value` record lines from text output. The formatter always+ * produces `key: value` (padded) or `key: value`.+ *+ * Lines whose key is a known hint prefix (e.g. "Usage:") are excluded —+ * those are invocation hints allowed by INV4, not data records.+ * @param {string} text+ * @returns {Map<string, string[]>}+ */+function extractRecordKeys(text) {+ const HINT_PREFIXES = new Set(['Usage', 'Summary', 'Read', 'Example', 'Tip']);+ /** @type {Map<string, string[]>} */+ const map = new Map();+ for (const line of text.split('\n')) {+ // Match "word-key: value" but not URLs, headings, or code fences+ const m = line.match(/^(\w[\w-]*):\s{1,}\S/);+ if (!m) continue;+ const key = m[1];+ if (HINT_PREFIXES.has(key)) continue;+ const value = line.slice(line.indexOf(':', key.length) + 1).trim();+ if (!map.has(key)) map.set(key, []);+ map.get(key).push(normalize(value));+ }+ return map;+}++/**+ * Extract bulleted list items from text output (`- item`).+ * @param {string} text+ * @returns {string[]}+ */+function extractListItems(text) {+ return text+ .split('\n')+ .filter(line => /^- \S/.test(line))+ .map(line => normalize(line.slice(2)));+}++/**+ * Extract standalone text blocks — lines that are not record lines, list+ * items, section headings, hint lines, or blank. These correspond to+ * `text(...)` formatter calls and must carry facts from the JSON.+ * @param {string} text+ * @returns {string[]}+ */+function extractTextBlocks(text) {+ const HINT_PREFIXES = /^(Usage|Summary|Read|Example|Tip|Import from|Related blocks|Each key|Props take|One component|No results|Try a|Browse instead|No failures|All checks|Some checks|Pass --\w)[:.]?/i;+ const lines = text.split('\n');+ /** @type {string[]} */+ const blocks = [];+ for (let i = 0; i < lines.length; i++) {+ const trimmed = lines[i].trim();+ if (!trimmed) continue;+ // Skip record lines+ if (/^\w[\w-]*:\s{1,}\S/.test(trimmed)) continue;+ // Skip list items+ if (/^- \S/.test(trimmed)) continue;+ // Skip hints+ if (HINT_PREFIXES.test(trimmed)) continue;+ // Skip lines that look like code, commands, or status tokens+ if (trimmed.startsWith('`') || trimmed.startsWith('$')) continue;+ if (trimmed.startsWith('[ok]') || trimmed.startsWith('[skip]') ||+ trimmed.startsWith('[fail]') || trimmed.startsWith('[warn]') ||+ trimmed.startsWith('!') || trimmed.startsWith('(')) continue;+ // Skip continuation lines (indented, part of a wrapped record or list)+ if (/^\s{2,}\S/.test(lines[i])) continue;+ // Skip section headings: a line preceded by blank (or start) that belongs+ // to a block followed by blank. Section blocks can be multi-line (heading+ // + subtitle), so check whether THIS line's block ends before a blank.+ // Only skip short, heading-like text (no sentence punctuation) to avoid+ // suppressing real text() facts.+ const prevBlank = i === 0 || !lines[i - 1]?.trim();+ const nextBlank = i === lines.length - 1 || !lines[i + 1]?.trim();+ const looksLikeHeading = trimmed.length <= 80 && !/[.!?]$/.test(trimmed);+ // Single-line heading: blank before AND after, and heading-like+ if (prevBlank && nextBlank && looksLikeHeading) continue;+ // Multi-line heading block: blank before this line, heading-like+ if (prevBlank && !nextBlank && looksLikeHeading) {+ let j = i + 1;+ while (j < lines.length && lines[j]?.trim()) j++;+ if (j - i <= 3) continue;+ }+ // Subtitle line: preceded by a heading-like line preceded by blank+ if (!prevBlank && nextBlank && i >= 1) {+ const prevLine = lines[i - 1]?.trim() ?? '';+ const prevPrevBlank = i < 2 || !lines[i - 2]?.trim();+ if (prevPrevBlank && prevLine.length <= 80 && !/[.!?]$/.test(prevLine)) continue;+ }+ blocks.push(normalize(trimmed));+ }+ return blocks;+}++/**+ * Collect every leaf string value from JSON data so we can verify text content+ * appears somewhere in the JSON.+ * @param {unknown} obj+ * @returns {Set<string>}+ */+function jsonLeafValues(obj) {+ /** @type {Set<string>} */+ const values = new Set();+ if (obj == null) return values;+ if (typeof obj === 'string') { values.add(normalize(obj)); return values; }+ if (typeof obj === 'number' || typeof obj === 'boolean') { values.add(String(obj)); return values; }+ if (Array.isArray(obj)) { for (const item of obj) { for (const v of jsonLeafValues(item)) values.add(v); } return values; }+ if (typeof obj === 'object') { for (const value of Object.values(obj)) { for (const v of jsonLeafValues(value)) values.add(v); } }+ return values;+}++/**+ * Collect every PRIMITIVE leaf key from a JSON value. Returns keys whose+ * values are strings, numbers, booleans, or arrays of primitives. Does NOT+ * return intermediate container keys (objects, arrays of objects).+ * @param {unknown} obj+ * @returns {Set<string>}+ */+function jsonLeafKeys(obj) {+ /** @type {Set<string>} */+ const keys = new Set();+ if (obj == null || typeof obj !== 'object') return keys;+ if (Array.isArray(obj)) {+ for (const item of obj) {+ if (item != null && typeof item === 'object' && !Array.isArray(item)) {+ for (const k of jsonLeafKeys(item)) keys.add(k);+ }+ }+ return keys;+ }+ for (const [key, value] of Object.entries(obj)) {+ if (value == null || typeof value !== 'object') {+ keys.add(key);+ } else if (Array.isArray(value)) {+ if (value.length > 0 && typeof value[0] !== 'object') {+ keys.add(key);+ } else {+ for (const item of value) {+ if (item != null && typeof item === 'object' && !Array.isArray(item)) {+ for (const k of jsonLeafKeys(item)) keys.add(k);+ }+ }+ }+ } else {+ for (const k of jsonLeafKeys(value)) keys.add(k);+ }+ }+ return keys;+}++/**+ * Map each leaf key to the set of values it takes across the JSON data.+ * Used for the JSON→text value-presence check on inline-layout commands.+ * @param {unknown} obj+ * @returns {Map<string, Set<string>>}+ */+function jsonKeyValues(obj) {+ /** @type {Map<string, Set<string>>} */+ const map = new Map();+ function walk(/** @type {unknown} */ node) {+ if (node == null || typeof node !== 'object') return;+ if (Array.isArray(node)) { for (const item of node) walk(item); return; }+ for (const [key, value] of Object.entries(node)) {+ if (value == null) continue;+ if (typeof value !== 'object') {+ if (!map.has(key)) map.set(key, new Set());+ map.get(key).add(normalize(String(value)));+ } else if (Array.isArray(value)) {+ if (value.length > 0 && typeof value[0] !== 'object') {+ if (!map.has(key)) map.set(key, new Set());+ for (const v of value) map.get(key).add(normalize(String(v)));+ } else {+ for (const item of value) walk(item);+ }+ } else {+ walk(value);+ }+ }+ }+ walk(obj);+ return map;+}++/**+ * Check whether a JSON object (at any depth) contains a given key name.+ * Used for the stale-allowlist check: the field must exist SOMEWHERE in the+ * full JSON output even if our leaf extractor skips it.+ * @param {unknown} obj+ * @param {string} target+ * @returns {boolean}+ */+function jsonContainsKey(obj, target) {+ if (obj == null || typeof obj !== 'object') return false;+ if (Array.isArray(obj)) return obj.some(item => jsonContainsKey(item, target));+ for (const [key, value] of Object.entries(obj)) {+ if (key === target) return true;+ if (jsonContainsKey(value, target)) return true;+ }+ return false;+}++// ─── Test cases ─────────────────────────────────────────────────────────────++/**+ * @typedef {object} ParityCase+ * @property {string} name - The manifest command name.+ * @property {string[]} args - CLI args after `astryx`.+ * @property {string} [cwd] - Working directory; defaults to REPO_ROOT.+ * @property {(dir: string) => void} [setup] - Prepare a tmpDir before the run.+ * @property {string[]} [jsonFieldAllowlist] - JSON keys forgiven from text.+ * @property {boolean} [skipFieldChecks] - Skip both record-key and field checks.+ * @property {boolean} [errorExpected] - The command is expected to error.+ */++/** @type {ParityCase[]} */+const CASES = [+ {+ name: 'blog',+ args: ['blog'],+ // Blog fetches the network feed. In CI the feed is unreachable, so+ // the command errors. The envelope shape is still checked.+ errorExpected: true,+ skipFieldChecks: true,+ },+ {+ name: 'build',+ args: ['build'],+ // PR #6566 fixes the playbook divergence.+ skipFieldChecks: true,+ jsonFieldAllowlist: [+ 'playbook — PR #6566 adds full playbook fields to the JSON envelope',+ ],+ },+ {+ name: 'component',+ args: ['component', '--list'],+ // #6507 touches this handler; divergences deferred.+ skipFieldChecks: true,+ jsonFieldAllowlist: [+ 'detail — internal detail-level tag, not a user-facing datum',+ ],+ },+ {+ name: 'discover',+ args: ['discover'],+ cwd: '__TMP__',+ // Empty result (no config). The meta.configured field is projected as+ // prose in the text.+ skipFieldChecks: true,+ jsonFieldAllowlist: [+ 'configured — expressed as prose "No integrations configured"',+ ],+ },+ {+ name: 'docs',+ args: ['docs'],+ jsonFieldAllowlist: [+ 'topic — inline layout lead column, not a key: value record',+ 'description — inline layout trailing column',+ ],+ },+ {+ name: 'doctor',+ args: ['doctor'],+ jsonFieldAllowlist: [+ 'fix — only present on checks that have a remediation',+ 'pass — shown in prose "Summary: N passed, ..."',+ 'warn — shown in prose "Summary: ..., N warnings"',+ 'fail — shown in prose "Summary: ..., N failures"',+ 'info — shown in prose "Summary: ..., N info" when nonzero',+ ],+ },+ {+ name: 'doctor integration validate',+ args: ['doctor', 'integration', 'validate'],+ skipFieldChecks: true,+ },+ {+ name: 'doctor integration components',+ args: ['doctor', 'integration', 'components'],+ skipFieldChecks: true,+ },+ {+ name: 'doctor integration docs',+ args: ['doctor', 'integration', 'docs'],+ skipFieldChecks: true,+ },+ {+ name: 'doctor integration templates',+ args: ['doctor', 'integration', 'templates'],+ skipFieldChecks: true,+ },+ {+ name: 'gap-report',+ args: ['gap-report', '--list-categories'],+ },+ {+ name: 'hook',+ args: ['hook', '--list', '--detail', 'compact'],+ jsonFieldAllowlist: [+ 'detail — internal detail-level tag, not a user-facing datum',+ 'import — shown inside the code() formatted block, not as a record',+ ],+ },+ {+ name: 'init',+ args: ['init'],+ cwd: '__TMP__',+ // Init emits text via the API logger, not the formatter kit.+ skipFieldChecks: true,+ },+ {+ name: 'integration add',+ args: ['integration', 'add', 'component', 'TestComp', '--dry-run'],+ // Needs a valid integration project to work; errors without one.+ errorExpected: true,+ skipFieldChecks: true,+ },+ {+ name: 'integration pack',+ args: ['integration', 'pack', '--check'],+ // Needs a packable project; pack itself may exit differently.+ skipFieldChecks: true,+ },+ // ── Layout command: remove these cases when the layout command is deleted ──+ {+ name: 'layout check',+ args: ['layout', 'check', 'Button'],+ skipFieldChecks: true,+ },+ {+ name: 'layout expand',+ args: ['layout', 'expand', 'Button'],+ skipFieldChecks: true,+ },+ {+ name: 'layout grammar',+ args: ['layout', 'grammar'],+ skipFieldChecks: true,+ },+ // ── End layout cases ──+ {+ name: 'manifest',+ args: ['manifest'],+ // Manifest describes the CLI itself; exempt (AST-042 FR1).+ skipFieldChecks: true,+ },+ {+ name: 'search',+ args: ['search', 'button'],+ jsonFieldAllowlist: [+ 'matchCount — stated in section heading "Results for ... (N)"',+ 'query — stated in section heading',+ 'score — only shown with --verbose',+ 'reason — only shown with --verbose',+ 'kind — internal domain subtype, not shown in default text',+ ],+ },+ {+ name: 'swizzle',+ args: ['swizzle', '--list'],+ skipFieldChecks: true,+ },+ {+ name: 'template',+ args: ['template', '--list'],+ // #6265 touches this handler; template id fix deferred.+ skipFieldChecks: true,+ jsonFieldAllowlist: [+ 'id — not shown in text records (#6265)',+ 'isReady — folded into name as "(WIP)" suffix (#6265)',+ ],+ },+ {+ name: 'theme add',+ args: ['theme', 'add', '--list'],+ // Themes are rendered as list items, not records.+ skipFieldChecks: true,+ },+ {+ name: 'theme build',+ args: ['theme', 'build', 'nonexistent.ts'],+ errorExpected: true,+ skipFieldChecks: true,+ },+ {+ name: 'theme list',+ args: ['theme', 'list'],+ skipFieldChecks: true,+ },+ {+ name: 'theme palette generate',+ args: ['theme', 'palette', 'generate', 'nonexistent.json'],+ errorExpected: true,+ skipFieldChecks: true,+ },+ {+ name: 'theme targets',+ args: ['theme', 'targets'],+ jsonFieldAllowlist: [+ 'filter — null when no filter given; not shown',+ 'componentCount — shown in section heading subtitle',+ ],+ },+ {+ name: 'theme template',+ args: ['theme', 'template'],+ cwd: '__TMP__',+ jsonFieldAllowlist: [+ 'written — stated in status token ([ok] / [skip])',+ 'path — stated in the "[ok] Wrote ..." line',+ 'reason — absent; only in skip envelopes',+ ],+ },+ {+ name: 'upgrade',+ args: ['upgrade', '--list'],+ cwd: '__TMP__',+ },+];++// ─── Suite ──────────────────────────────────────────────────────────────────++describe('text-json-parity', () => {+ /** @type {string[]} */+ let manifestCommands;+ /** @type {string} */+ let tmpDir;++ beforeAll(async () => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-parity-'));+ const {stdout} = await runCli(['manifest', '--json'], {cwd: REPO_ROOT});+ const manifest = JSON.parse(stdout);+ manifestCommands = manifest.data.jsonSupported;+ });++ afterAll(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+ });++ // ── Gate: every JSON-capable command has a parity case ──────────────+ it('every JSON-capable command in the manifest has a parity case', () => {+ const covered = new Set(CASES.map(c => c.name));+ const missing = manifestCommands.filter(cmd => !covered.has(cmd));+ expect(+ missing,+ `Add a parity case for these commands:\n${missing.join('\n')}`,+ ).toEqual([]);+ });++ it('every parity case names a real manifest command', () => {+ const real = new Set(manifestCommands);+ const stale = CASES.filter(c => !real.has(c.name)).map(c => c.name);+ expect(stale).toEqual([]);+ });++ // ── Per-command parity checks ──────────────────────────────────────+ for (const tc of CASES) {+ describe(tc.name, () => {+ /** @type {{text: string, json: any, textStatus: number, jsonStatus: number}} */+ let run;++ beforeAll(async () => {+ let cwd = tc.cwd === '__TMP__' ? tmpDir : (tc.cwd || REPO_ROOT);+ if (tc.cwd === '__TMP__') {+ const sub = path.join(tmpDir, tc.name.replace(/\s+/g, '-'));+ fs.mkdirSync(sub, {recursive: true});+ if (tc.setup) tc.setup(sub);+ cwd = sub;+ }++ // Run sequentially: runCli uses process.chdir, which is global+ // state and races under Promise.all.+ const textResult = await runCli(tc.args, {cwd});+ const jsonResult = await runCli([...tc.args, '--json'], {cwd});++ let jsonData;+ try {+ jsonData = JSON.parse(jsonResult.stdout);+ } catch {+ jsonData = null;+ }++ run = {+ text: textResult.stdout,+ json: jsonData,+ textStatus: textResult.status,+ jsonStatus: jsonResult.status,+ };+ });++ it('JSON output is a valid envelope', () => {+ expect(run.json).not.toBeNull();+ const isSuccess = run.json?.type != null;+ const isError = run.json?.error != null;+ expect(isSuccess || isError).toBe(true);+ });++ it('exit codes match between text and JSON mode', () => {+ expect(run.textStatus).toBe(run.jsonStatus);+ });++ if (!tc.skipFieldChecks && !tc.errorExpected) {+ it('every text record key exists in the JSON data', () => {+ if (!run.json?.data) return;+ const textKeys = extractRecordKeys(run.text);+ const jsonKeys = jsonLeafKeys(run.json.data);+ if (run.json.meta) {+ for (const k of jsonLeafKeys(run.json.meta)) jsonKeys.add(k);+ }+ const violations = [];+ for (const key of textKeys.keys()) {+ if (!jsonKeys.has(key)) {+ violations.push(key);+ }+ }+ expect(+ violations,+ `Text record keys not in JSON:\n${violations.join(', ')}`,+ ).toEqual([]);+ });++ it('every JSON leaf field appears in the text or is allowlisted', () => {+ if (!run.json?.data) return;+ const textKeys = extractRecordKeys(run.text);+ const jsonKeys = jsonLeafKeys(run.json.data);+ const keyVals = jsonKeyValues(run.json.data);+ const allowedKeys = new Set(+ (tc.jsonFieldAllowlist || []).map(e => e.split(' — ')[0].trim()),+ );++ const missing = [];+ for (const key of jsonKeys) {+ const inRecords = textKeys.has(key);+ // Check for `key:` as a field label at start of line.+ const asLabel = new RegExp(`(?:^|\\n)\\s*${key}:`, 'm').test(run.text);+ // For inline records (no labels): check if THIS KEY's values+ // appear in the text. This catches inline-layout projections+ // where the key name is only in the section subtitle.+ const myVals = keyVals.get(key) ?? new Set();+ const valuesInText = !inRecords && !asLabel && [...myVals].some(v =>+ v.length > 2 && run.text.includes(v),+ );+ const allowed = allowedKeys.has(key);+ if (!inRecords && !asLabel && !valuesInText && !allowed) {+ missing.push(key);+ }+ }+ expect(+ missing,+ `JSON fields not in text and not allowlisted:\n${missing.join(', ')}`,+ ).toEqual([]);+ });++ it('text list items and block content appear in JSON data', () => {+ if (!run.json?.data) return;+ const jsonValues = jsonLeafValues(run.json.data);+ if (run.json.meta) {+ for (const v of jsonLeafValues(run.json.meta)) jsonValues.add(v);+ }+ const items = extractListItems(run.text);+ const textBlocks = extractTextBlocks(run.text);+ const violations = [];+ for (const item of items) {+ // Each list item should match (or be a substring of) some JSON value.+ const found = [...jsonValues].some(+ jv => jv === item || jv.includes(item) || item.includes(jv),+ );+ if (!found) {+ violations.push(`[list] ${item.slice(0, 80)}`);+ }+ }+ for (const block of textBlocks) {+ // Each text block should contain at least one word that appears in+ // the JSON values. A block with no JSON overlap is a fact the+ // envelope does not carry. Numbers (even short) count because+ // they are data.+ const words = block.split(/\s+/).filter(w =>+ w.length > 3 || /^\d+$/.test(w),+ );+ const anyOverlap = words.some(w =>+ [...jsonValues].some(jv => jv.includes(w)),+ );+ if (!anyOverlap && words.length > 0) {+ violations.push(`[text] ${block.slice(0, 80)}`);+ }+ }+ expect(+ violations,+ `Text content not found in JSON data:\n${violations.join('\n')}`,+ ).toEqual([]);+ });+ }++ // Stale allowlist check+ if (tc.jsonFieldAllowlist && tc.jsonFieldAllowlist.length > 0) {+ it('allowlist entries are not stale', () => {+ if (!run.json) return;+ const searchTarget = run.json.data ?? run.json;+ const stale = [];+ for (const entry of tc.jsonFieldAllowlist) {+ const key = entry.split(' — ')[0].trim();+ if (!jsonContainsKey(searchTarget, key) && !jsonContainsKey(run.json.meta, key)) {+ stale.push(entry);+ }+ }+ expect(+ stale,+ `Stale allowlist entries — remove them:\n${stale.join('\n')}`,+ ).toEqual([]);+ });+ }+ });+ }++ // ── Upgrade failure-path regression tests ────────────────────────+ // The upgrade handler silences the logger for --list and replays the error+ // in the catch. These tests prove both list and non-list failures print+ // the error exactly once and exit 1, in both text and --json mode.+ describe('upgrade failure paths', () => {+ it('upgrade --list --registry prints error once on stderr and exits 1 (text)', async () => {+ const sub = path.join(tmpDir, 'upgrade-list-fail');+ fs.mkdirSync(sub, {recursive: true});+ const r = await runCli(['upgrade', '--list', '--registry'], {cwd: sub});+ expect(r.status).toBe(1);+ // The error message should appear exactly once across stdout+stderr.+ const combined = r.stdout + r.stderr;+ const occurrences = combined.split('cannot be used together').length - 1;+ expect(occurrences, 'error should appear exactly once').toBe(1);+ });++ it('upgrade --list --registry emits one error envelope in --json mode', async () => {+ const sub = path.join(tmpDir, 'upgrade-list-fail-json');+ fs.mkdirSync(sub, {recursive: true});+ const r = await runCli(['upgrade', '--list', '--registry', '--json'], {cwd: sub});+ expect(r.status).toBe(1);+ const parsed = JSON.parse(r.stdout);+ expect(parsed).toHaveProperty('error');+ expect(parsed).not.toHaveProperty('type');+ });++ it('non-list upgrade failure prints error once on stderr and exits 1 (text)', async () => {+ const sub = path.join(tmpDir, 'upgrade-nonlist-fail');+ fs.mkdirSync(sub, {recursive: true});+ const r = await runCli(['upgrade', '--from', 'notsemver'], {cwd: sub});+ expect(r.status).toBe(1);+ // The error should appear exactly once.+ const combined = r.stdout + r.stderr;+ const lines = combined.split('\n').filter(l => l.includes('notsemver') || l.includes('ERR'));+ // At most one line carries the error; zero is OK if the API formats+ // differently, but more than one means duplication.+ expect(lines.length, 'error should not be duplicated').toBeLessThanOrEqual(1);+ });++ it('non-list upgrade failure emits one error envelope in --json mode', async () => {+ const sub = path.join(tmpDir, 'upgrade-nonlist-fail-json');+ fs.mkdirSync(sub, {recursive: true});+ const r = await runCli(['upgrade', '--from', 'notsemver', '--json'], {cwd: sub});+ expect(r.status).toBe(1);+ const parsed = JSON.parse(r.stdout);+ expect(parsed).toHaveProperty('error');+ });+ });+});diff --git a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjsindex d10d813822..b650224e6d 100644--- a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs+++ b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs@@ -17,8 +17,9 @@ describe('astryx theme targets', () => {const {status, stdout} = await runCli(['theme', 'targets', 'Switch']);expect(status).toBe(0);- expect(stdout).toMatch(/^switch\s+Switch\s+size\s+checked, disabled$/m);- expect(stdout).toMatch(/^switch-thumb\s+Switch\s+size\s+checked$/m);+ // Inline layout: key component - props - states - className+ expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);+ expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);expect(stdout).toMatch(/4 across 1 component/);});@@ -28,7 +29,7 @@ describe('astryx theme targets', () => {expect(status).toBe(0);expect(stdout).toMatch(/^popover\s{2,}Popover/m);expect(stdout).toMatch(- /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,+ /^popover-surface\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,);});diff --git a/packages/cli/clients/cli/commands/upgrade.mjs b/packages/cli/clients/cli/commands/upgrade.mjsindex 1eb53376a7..2e2ea0092f 100644--- a/packages/cli/clients/cli/commands/upgrade.mjs+++ b/packages/cli/clients/cli/commands/upgrade.mjs@@ -13,6 +13,7 @@*/import {jsonOut, jsonError} from '../../../foundation/response/json.mjs';+import {emit, section, records} from '../formatters/index.mjs';import {logger} from '../../../api/logger.mjs';import {AstryxError} from '../../../api/error.mjs';import {defineCommand} from '../lib/define-command.mjs';@@ -33,27 +34,45 @@ export function registerUpgrade(program) {*/async options => {const json = program.opts().json || false;- logger.setSilent(json);+ const isList = Boolean(options.list);+ // Silence the logger for --list so the handler renders from the+ // result (parity with --json), and for --json as before.+ // Re-enable on error so handled failures still print.+ logger.setSilent(json || isList);/** @type {import('../../../api/upgrade/upgrade.type.mjs').UpgradeListResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRegistryResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeStatusResponse | import('../../../api/upgrade/upgrade.type.mjs').UpgradeRunResponse} */let result;try {result = await upgradeApi(options, {cwd: process.cwd()});} catch (e) {- // Handled failures throw AstryxError: --json emits the structured- // envelope (byte-identical to the old inline jsonError) + exits 1;- // human mode already saw the error line + outro via the logger, so we- // just set the exit code. Anything else is unexpected — let the- // top-level boundary in bin/astryx.mjs format it as before.+ // Re-enable the logger so the error is visible in text mode.+ // For --list the logger was silent; for other modes the API+ // already printed the error before throwing.+ logger.setSilent(json);if (e instanceof AstryxError) {if (json) jsonError(e.message, undefined, e.code);- else process.exitCode = 1;+ else {+ // The logger was silent only for --list; replay the error there.+ // Non-list failures were already printed by the API.+ if (isList) logger.error(e.message);+ process.exitCode = 1;+ }return NO_RESULT_SET;}throw e;}if (json) jsonOut(result);+ else if (result.type === 'upgrade.list') {+ // Render the list from the result, not the API logger, so the text+ // carries the same fields the JSON does (name, title, version, optional).+ emit(+ section('Available codemods'),+ records(result.data, {+ fields: ['name', 'title', 'version', 'optional'],+ }),+ );+ }const registrySummary =result.type === 'upgrade.registry'diff --git a/packages/cli/clients/cli/formatters/index.mjs b/packages/cli/clients/cli/formatters/index.mjsindex a867c2f5b0..161e62a731 100644--- a/packages/cli/clients/cli/formatters/index.mjs+++ b/packages/cli/clients/cli/formatters/index.mjs@@ -152,6 +152,8 @@ function toAscii(s) {.replace(/[\u2018\u2019]/g, "'").replace(/[\u201C\u201D]/g, '"').replace(/\u2026/g, '...')+ .replace(/\u2192/g, '->')+ .replace(/\u2190/g, '<-').replace(/\u00a0/g, ' ');}diff --git a/packages/cli/clients/cli/formatters/index.test.mjs b/packages/cli/clients/cli/formatters/index.test.mjsindex 15af2d58db..57b43c8c02 100644--- a/packages/cli/clients/cli/formatters/index.test.mjs+++ b/packages/cli/clients/cli/formatters/index.test.mjs@@ -117,6 +117,12 @@ describe('ASCII normalization', () => {expect(list(['Avatar \u2014 Group']).toString()).toBe('- Avatar - Group');});+ it('converts Unicode arrows to ASCII arrows', () => {+ expect(text('Rename items \u2192 options').toString()).toBe('Rename items -> options');+ expect(text('options \u2190 items').toString()).toBe('options <- items');+ expect(record({title: 'a \u2192 b'}).toString()).toBe('title: a -> b');+ });+it('leaves code verbatim (no normalization)', () => {expect(code('a \u2014 b').toString()).toBe('a \u2014 b');});