@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9dbb6c1

package/clients/cli/commands/discover.text-projection.test.mjs

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` text output projects every field of its JSON entry.
+ *
+ * The text views of `discover.list` and `discover.detail` are renderings of the
+ * same entries `--json` returns, so each entry key must appear as a `key:` line
+ * carrying the same value.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+let tmpDir;
+let project;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-text-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({name: 'proj', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(project, 'astryx.config.mjs'),
+    `export default {integrations: ['@test/kit']};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '3.1.4'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  for (const name of ['Dial', 'Gauge']) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.doc.mjs`),
+      `export const docs = {name: '${name}', usage: {description: 'A ${name}.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.tsx`),
+      `export function ${name}() { return null; }\n`,
+    );
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * @param {Record<string, unknown>} entry
+ * @param {string} text
+ */
+function expectEveryField(entry, text) {
+  const lines = text.split('\n');
+  for (const [key, value] of Object.entries(entry)) {
+    const rendered = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(lines).toContainEqual(
+      expect.stringMatching(new RegExp(`^${key}:\\s+${escape(rendered)}$`)),
+    );
+  }
+}
+
+/** @param {string} s */
+function escape(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+describe('astryx discover text output', () => {
+  it('lists every field of each discover.list entry', async () => {
+    const asJson = await runCli(['discover', '--json'], {cwd: project});
+    const [entry] = JSON.parse(asJson.stdout).data;
+    expect(Object.keys(entry)).toEqual(
+      expect.arrayContaining(['name', 'category', 'components', 'version']),
+    );
+
+    const {status, stdout} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expectEveryField(entry, stdout);
+  });
+
+  it('shows every field of the discover.detail entry', async () => {
+    const asJson = await runCli(['discover', '@test/kit', '--json'], {
+      cwd: project,
+    });
+    const {data} = JSON.parse(asJson.stdout);
+
+    const {status, stdout} = await runCli(['discover', '@test/kit'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expectEveryField(data, stdout);
+  });
+});

package/clients/cli/commands/docs.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'docs',
   displayName: 'astryx docs',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print reference docs',
   description:
     'Reads the reference docs: with no topic it lists every topic; a topic prints that ' +

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration components',
   displayName: 'astryx doctor integration components',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Warn when integration component names conflict with Core',
   description:
     'Compares one local or installed integration with Core component names. A ' +

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -7,7 +7,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Classify integration doc overlaps with Core topics',
   description:
     'Reports intentional Core topic replacements and extensions as information. ' +

package/clients/cli/commands/doctor-integration-templates.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration templates',
   displayName: 'astryx doctor integration templates',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Warn when integration template ids conflict with Core',
   description:
     'Compares one local or installed integration with the built-in Core page and ' +

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration validate',
   displayName: 'astryx doctor integration validate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Validate an integration manifest and its contributions',
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +

package/clients/cli/commands/doctor-integration.doc.mjs

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration',
   displayName: 'astryx doctor integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Check an integration package while authoring it',
   description:
     'The integration-authoring diagnostics group. Validate a manifest and all ' +

package/clients/cli/commands/doctor-integration.package-json.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {validateIntegration} from '../../../api/integration/validate-integration.mjs';
+
+const NO_MANIFEST = 'No astryx.integration.* found next to package.json.';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-pkgjson-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "@acme/widgets",}\n');
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  templates: './templates',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('doctor integration with a malformed package.json', () => {
+  it('keeps a null name for the no-manifest case only', async () => {
+    const result = await validateIntegration(undefined, {cwd: tmpDir});
+
+    expect(result.data.name).toBe('(local package)');
+    expect(result.data.issues.map(issue => issue.code)).toEqual([
+      'invalid_package_json',
+    ]);
+  });
+
+  for (const leaf of ['validate', 'templates', 'components', 'docs']) {
+    it(`${leaf} prints the package.json error instead of "no manifest"`, async () => {
+      const text = await runCli(['doctor', 'integration', leaf], tmpDir);
+      const json = await runCli(
+        ['doctor', 'integration', leaf, '--json'],
+        tmpDir,
+      );
+
+      expect(text.status).toBe(1);
+      expect(json.status).toBe(1);
+      expect(text.stdout).not.toContain(NO_MANIFEST);
+      expect(text.stdout).toContain('invalid_package_json');
+      expect(JSON.parse(json.stdout).data.issues).toContainEqual(
+        expect.objectContaining({code: 'invalid_package_json'}),
+      );
+    });
+  }
+});

package/clients/cli/commands/doctor-integration.test.mjs

@@ -44,7 +44,7 @@ function writeIntegration({
   const stem = path.join(tmpDir, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
+    `${stem}.doc.mjs`,
     `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
   );
   fs.writeFileSync(
@@ -124,7 +124,12 @@ describe('doctor integration — command', () => {
       return true;
     });
 
-    await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+    ]);
 
     const output = writes.join('');
     expect(output).toContain('validate [package]');
@@ -136,7 +141,9 @@ describe('doctor integration — command', () => {
 
   it('explains the optional package argument in every leaf help', () => {
     const program = createProgram();
-    const doctor = program.commands.find(command => command.name() === 'doctor');
+    const doctor = program.commands.find(
+      command => command.name() === 'doctor',
+    );
     const integration = doctor?.commands.find(
       command => command.name() === 'integration',
     );
@@ -152,7 +159,10 @@ describe('doctor integration — command', () => {
   });
 
   it('templates explains how to check an installed package when no local manifest exists', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
     process.chdir(tmpDir);
 
     await createProgram().parseAsync([
@@ -278,9 +288,7 @@ describe('doctor integration — command', () => {
     const output = logCalls.join('\n');
     expect(output).toContain('[warn]');
     expect(output).toContain(core.name);
-    expect(output).toContain(
-      `component ${core.name} --package @acme/widgets`,
-    );
+    expect(output).toContain(`component ${core.name} --package @acme/widgets`);
     expect(process.exitCode).toBeUndefined();
   });
 

package/clients/cli/commands/doctor.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'doctor',
   displayName: 'astryx doctor',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +

package/clients/cli/commands/doctor.mjs

@@ -17,7 +17,7 @@ import {
   validateIntegration,
 } from '../../../api/integration/validate-integration.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text} from '../formatters/index.mjs';
+import {emit, section, record, records, text} from '../formatters/index.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as doctorCommand} from './doctor.doc.mjs';
 import {doc as doctorIntegrationGroup} from './doctor-integration.doc.mjs';
@@ -55,7 +55,7 @@ function integrationLabel(data) {
  * @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
-  const {pass, warn, fail, info} = report.summary;
+  const {warn, fail} = report.summary;
   const closing =
     fail > 0
       ? 'Some checks failed. Address the items marked [fail] above.'
@@ -63,18 +63,15 @@ function printHuman(report) {
         ? 'No failures — but review the [warn] warnings above when you can.'
         : 'All checks passed. Your Astryx setup looks healthy.';
 
+  // Field names are the JSON keys, so text and --json map one to one.
   emit(
     section('astryx doctor — diagnosing your setup'),
     records(report.checks, {
-      fields: ['status', 'label', 'message', 'fix'],
-      labels: {label: 'check'},
+      fields: ['id', 'status', 'label', 'message', 'fix'],
       format: {status: statusToken},
     }),
-    text(
-      `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
-        `${fail} failure${fail === 1 ? '' : 's'}` +
-        (info ? `, ${info} info` : ''),
-    ),
+    section('summary'),
+    record(report.summary, {fields: ['pass', 'warn', 'fail', 'info']}),
     text(closing),
   );
 }
@@ -290,13 +287,6 @@ export function registerDoctor(program) {
     fn: doctorFn,
     action: async () => runProjectDoctor(program),
   });
-  doctorCmd.addHelpText(
-    'after',
-    '\nExit code:\n' +
-      '  0  no failures (warnings are allowed) — safe as a CI gate\n' +
-      '  1  one or more checks failed\n',
-  );
-
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {

package/clients/cli/commands/doctor.test.mjs

@@ -354,3 +354,45 @@ describe('doctor — command', () => {
     }
   });
 });
+
+describe('doctor — text output mirrors the JSON', () => {
+  /** @param {string} line */
+  const field = line => /^(\w+):\s+(.*)$/.exec(line)?.slice(1) ?? [line, ''];
+
+  it('prints every check and summary field under its JSON key', async () => {
+    const prevCwd = process.cwd();
+    const prevExit = process.exitCode;
+    process.chdir(tmpDir);
+    try {
+      await createProgram().parseAsync(['node', 'astryx', '--json', 'doctor']);
+      const {checks, summary} = JSON.parse(logCalls.join('\n')).data;
+      logCalls = [];
+      await createProgram().parseAsync(['node', 'astryx', 'doctor']);
+      const blocks = logCalls
+        .join('\n')
+        .split(/\n{2,}/)
+        .map(block => block.split('\n').map(field));
+
+      for (const check of checks) {
+        const block = blocks.find(fields =>
+          fields.some(([key, value]) => key === 'id' && value === check.id),
+        );
+        expect(block, `no text record for check ${check.id}`).toBeDefined();
+        expect(
+          /** @type {string[][]} */ (block).map(([key]) => key).sort(),
+        ).toEqual(Object.keys(check).sort());
+      }
+
+      const heading = blocks.findIndex(
+        fields => fields.length === 1 && fields[0][0] === 'summary',
+      );
+      expect(heading, 'no summary section').toBeGreaterThan(-1);
+      expect(blocks[heading + 1]).toEqual(
+        Object.entries(summary).map(([key, count]) => [key, String(count)]),
+      );
+    } finally {
+      process.chdir(prevCwd);
+      process.exitCode = prevExit;
+    }
+  }, 60_000);
+});

package/clients/cli/commands/gap-report.doc.mjs

@@ -10,27 +10,37 @@ export const doc = {
   type: 'command',
   name: 'gap-report',
   displayName: 'astryx gap-report',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Route a design-system gap to its owning package',
   description:
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',
   fn: 'gapReport',
-  args: [{name: 'component', param: 'component', required: false}],
+  args: [
+    {
+      name: 'component',
+      param: 'component',
+      required: false,
+      description:
+        'Component or design-system area the gap is about, up to 120 characters. Required unless --list-categories is set.',
+    },
+  ],
   options: [
     {
       flag: '--category <category>',
       param: 'options.category',
-      description: 'Gap category (run --list-categories for values)',
+      description:
+        'Gap category (run --list-categories for values). Required unless --list-categories is set.',
     },
     {
       flag: '--reason <reason>',
       param: 'options.reason',
-      description: 'What capability was missing or difficult',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless --list-categories is set.',
     },
     {
       flag: '--additional-context <text>',
       param: 'options.detail',
-      description: 'Optional additional context',
+      description: 'Optional additional context, up to 8000 characters',
     },
     {
       flag: '--package <pkg>',
@@ -45,7 +55,8 @@ export const doc = {
     {
       flag: '--list-categories',
       param: 'options.listCategories',
-      description: 'List valid report categories without filing',
+      description:
+        'List valid report categories without filing; the component and the other gap-report options are ignored',
     },
   ],
   examples: [

package/clients/cli/commands/gap-report.test.mjs

@@ -196,3 +196,75 @@ export default {};\n`,
     });
   });
 });
+
+describe('gap-report control docs', () => {
+  const REQUIRED = 'Required unless --list-categories is set.';
+
+  it('help and manifest say which inputs are required and how long they may be', async () => {
+    const help = await runCli(['gap-report', '--help']);
+    expect(help.status).toBe(0);
+    const manifest = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const entry = manifest.data.commands.find(
+      (/** @type {{name: string}} */ command) => command.name === 'gap-report',
+    );
+    /** @param {string} flag @returns {string} */
+    const option = flag =>
+      entry.options.find(
+        (/** @type {{flag: string}} */ item) => item.flag.split(' ')[0] === flag,
+      )?.description ?? '';
+    const component = entry.arguments[0].description;
+
+    for (const text of [component, option('--category'), option('--reason')]) {
+      expect(text).toContain(REQUIRED);
+      expect(help.stdout).toContain(text);
+    }
+    expect(option('--list-categories')).toContain(
+      'the component and the other gap-report options are ignored',
+    );
+
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-limits-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const base = {cwd, category: /** @type {const} */ ('docs_gap'), reason: 'x'};
+      /** @type {Array<[string, (value: string) => Promise<unknown>]>} */
+      const limits = [
+        [component, value => gapReport(value, base)],
+        [option('--reason'), value => gapReport('Button', {...base, reason: value})],
+        [
+          option('--additional-context'),
+          value => gapReport('Button', {...base, detail: value}),
+        ],
+      ];
+      for (const [text, call] of limits) {
+        const limit = Number(/up to (\d+) characters/.exec(text)?.[1]);
+        expect(limit, text).toBeGreaterThan(0);
+        await expect(call('x'.repeat(limit))).resolves.toMatchObject({
+          type: 'gap-report.file',
+        });
+        await expect(call('x'.repeat(limit + 1))).rejects.toMatchObject({
+          code: 'ERR_INVALID_ARGUMENT',
+        });
+      }
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+
+  it('enforces the documented requirement', async () => {
+    for (const [component, options] of [
+      [undefined, {category: 'docs_gap', reason: 'x'}],
+      ['Button', {reason: 'x'}],
+      ['Button', {category: 'docs_gap'}],
+    ]) {
+      await expect(gapReport(component, options)).rejects.toMatchObject({
+        code: 'ERR_MISSING_ARGUMENT',
+      });
+    }
+    await expect(
+      gapReport(undefined, {listCategories: true, category: 'not_real', package: 'nope'}),
+    ).resolves.toMatchObject({type: 'gap-report.categories'});
+  });
+});

package/clients/cli/commands/hook/index.mjs

@@ -20,7 +20,6 @@ import {defineCommand} from '../../lib/define-command.mjs';
 import {resultSet} from '../../../../foundation/debug/index.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
 import {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {findRelatedBlocks} from '../../../../api/template/template.mjs';
 import {doc as hookCommand} from '../hook.doc.mjs';
 import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
 
@@ -169,24 +168,15 @@ export function registerHook(program) {
                   )
                 : formatHookFull(result.data);
 
-          // Show related block templates from relatedComponents
-          const relatedComps = result.data.relatedComponents || [];
-          /** @type {import('../../../../api/template/template.mjs').DiscoveredTemplate[]} */
-          const allBlocks = [];
-          for (const comp of relatedComps) {
-            const blocks = await findRelatedBlocks(comp);
-            for (const b of blocks) {
-              if (!allBlocks.some(existing => existing.dirName === b.dirName)) {
-                allBlocks.push(b);
-              }
-            }
-          }
-
+          // Text projects the envelope only. Block templates are JSON-backed
+          // under `component <name> --blocks`.
+          const related = result.data.relatedComponents ?? [];
           emit(
             code(doc),
-            allBlocks.length > 0 && section('Related block templates'),
-            allBlocks.length > 0 &&
-              records(allBlocks, {fields: ['dirName', 'description']}),
+            related.length > 0 &&
+              text(
+                `Block templates: ${run} component <name> --blocks for ${related.join(', ')}`,
+              ),
           );
           break;
         }

package/clients/cli/commands/hook.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'hook',
   displayName: 'astryx hook',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List hooks or print hook docs',
   description:
     'Resolves a hook by name and prints its authored doc, or lists the catalog grouped ' +

package/clients/cli/commands/hook.text-projection.test.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx hook <name>` text is a projection of `hook.detail`: it shows
+ * nothing the JSON envelope does not carry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+
+const HOOK = 'useAnnounce';
+
+describe('hook detail text projection', () => {
+  it('prints no block templates that the JSON envelope lacks', async () => {
+    const json = await runCli(['--json', 'hook', HOOK]);
+    expect(json.status).toBe(0);
+    const envelope = JSON.parse(json.stdout);
+    expect(envelope.type).toBe('hook.detail');
+    const related = envelope.data.relatedComponents;
+    expect(related.length).toBeGreaterThan(0);
+
+    const blockNames = [];
+    for (const component of related) {
+      for (const block of await findRelatedBlocks(component)) {
+        blockNames.push(block.dirName);
+      }
+    }
+    expect(blockNames.length).toBeGreaterThan(0);
+
+    const text = await runCli(['hook', HOOK]);
+    expect(text.status).toBe(0);
+    const shownButNotInJson = blockNames.filter(
+      name => text.stdout.includes(name) && !json.stdout.includes(name),
+    );
+    expect(shownButNotInJson).toEqual([]);
+  });
+
+  it('points at the JSON-backed block lookup for each related component', async () => {
+    const text = await runCli(['hook', HOOK]);
+    expect(text.stdout).toMatch(/component <name> --blocks/);
+    expect(text.stdout).toContain('VisuallyHidden');
+    expect(text.stdout).toContain('Toast');
+  });
+});