@astryxdesign/cli 0.6.3-canary.ebaebc4 → 0.6.3-canary.ee13359

package/clients/cli/commands/discover.broken-integration.test.mjs

@@ -69,11 +69,12 @@ describe('astryx discover with a manifest that fails to load', () => {
 
     expect(status).toBe(0);
     expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @test/broken',
+      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
     );
     expect(stdout).not.toContain('No integrations configured.');
-    expect(stdout).toContain('No external components found in configured integrations.');
+    expect(stdout).toContain(
+      'No external components found in configured integrations.',
+    );
   });
 
   it('reports meta.configured=true in --json, with the nudge suppressed', async () => {
@@ -87,6 +88,53 @@ describe('astryx discover with a manifest that fails to load', () => {
   });
 });
 
+describe('astryx discover with a configured package that is not installed', () => {
+  beforeEach(() => {
+    const healthy = path.join(project, 'node_modules', '@test', 'healthy');
+    fs.mkdirSync(path.join(healthy, 'components'), {recursive: true});
+    fs.writeFileSync(
+      path.join(healthy, 'package.json'),
+      JSON.stringify({name: '@test/healthy', version: '2.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'astryx.integration.mjs'),
+      `export default {components: './components'};\n`,
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'components', 'Widget.doc.mjs'),
+      `export const docs = {name: 'Widget', usage: {description: 'A widget.'}, props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(healthy, 'components', 'Widget.tsx'),
+      `export function Widget() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(project, 'astryx.config.mjs'),
+      `export default {integrations: ['@test/missing', '@test/healthy']};\n`,
+    );
+  });
+
+  it('still lists the healthy package and exits 0', async () => {
+    const {status, stdout} = await runCli(['discover', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).data).toEqual([
+      expect.objectContaining({name: '@test/healthy', components: ['Widget']}),
+    ]);
+  });
+
+  it('names the missing package in the stderr nudge', async () => {
+    const {status, stderr} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stderr).toContain(
+      'Warning: @test/missing has 1 integration issue(s). Run: astryx doctor\n',
+    );
+  });
+});
+
 describe('astryx search with a manifest that fails to load', () => {
   // search needs a resolvable @astryxdesign/core; without one it errors out
   // before it can list anything, which is not the case under test.
@@ -101,8 +149,7 @@ describe('astryx search with a manifest that fails to load', () => {
 
     expect(status).toBe(0);
     expect(stderr).toContain(
-      'Warning: @test/broken has 1 integration issue(s). ' +
-        'Run: astryx doctor integration validate @test/broken',
+      'Warning: @test/broken has 1 integration issue(s). Run: astryx doctor',
     );
 
     const asJson = await runCli(['search', 'button', '--json'], {cwd: project});

package/clients/cli/commands/discover.components-flag.test.mjs

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover --components` does what its doc says.
+ *
+ * The flag only lifts the package list's component summary (the first 10
+ * names plus "+N more") so every component prints. It changes nothing in
+ * `--json`, whose entries always carry the full array.
+ */
+
+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';
+import {doc} from './discover.doc.mjs';
+import {doc as discoverFn} from '../../../api/discover/discover.doc.mjs';
+
+const NAMES = Array.from({length: 12}, (_, i) => `Part${String(i).padStart(2, '0')}`);
+
+let tmpDir;
+let project;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-components-'));
+  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: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  for (const name of NAMES) {
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.doc.mjs`),
+      `export const docs = {name: '${name}', usage: {description: 'A part.'}};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', `${name}.tsx`),
+      `export function ${name}() { return null; }\n`,
+    );
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} stdout */
+function componentsLine(stdout) {
+  return stdout.split('\n').find(line => line.startsWith('components:'));
+}
+
+describe('astryx discover --components', () => {
+  it('lists every component where the default list shows the first 10', async () => {
+    const summary = await runCli(['discover'], {cwd: project});
+    const full = await runCli(['discover', '--components'], {cwd: project});
+
+    expect(componentsLine(summary.stdout)).toMatch(
+      new RegExp(`${NAMES[9]}, \\+2 more$`),
+    );
+    expect(componentsLine(full.stdout)).toMatch(new RegExp(`${NAMES.join(', ')}$`));
+  });
+
+  it('leaves the --json response unchanged', async () => {
+    const plain = await runCli(['discover', '--json'], {cwd: project});
+    const flagged = await runCli(['discover', '--components', '--json'], {
+      cwd: project,
+    });
+
+    expect(JSON.parse(flagged.stdout)).toEqual(JSON.parse(plain.stdout));
+  });
+
+  it('is documented as that behavior, with an example', () => {
+    const option = doc.options?.find(o => o.flag === '--components');
+    const param = discoverFn.params?.find(p => p.name === 'options.components');
+
+    for (const description of [option?.description, param?.description]) {
+      expect(description).toMatch(/every component/i);
+      expect(description).toMatch(/first 10/);
+      expect(description).not.toMatch(/components only/i);
+    }
+    expect(doc.examples?.some(e => /\s--components\b/.test(e.cli))).toBe(true);
+  });
+});

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

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'discover',
   displayName: 'astryx discover',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Discover external packages and components',
   description:
     'Explores components contributed by configured external packages and integrations. ' +
@@ -25,18 +25,20 @@ export const doc = {
     {
       flag: '--components',
       param: 'options.components',
-      description: 'List components only',
+      description:
+        'In the package list, print every component of each package instead of the first 10 and a "+N more" count. No effect on --json output or on a package, component, or search query.',
     },
   ],
   examples: [
     {label: 'List packages', cli: 'astryx discover --json'},
+    {label: 'List every component of each package', cli: 'astryx discover --components'},
     {label: 'Browse a package', cli: 'astryx discover @acme/ui'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown package or component, a malformed doc, or an empty free-text query',
+      when: 'unknown package or component, a malformed doc, or a blank query when packages are discovered',
     },
   ],
   related: ['component', 'search', 'template'],

package/clients/cli/commands/discover.mjs

@@ -83,7 +83,7 @@ export function registerDiscover(program) {
       // doctor integration validate. Best-effort; suppressed in --json mode.
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
@@ -122,11 +122,11 @@ export function registerDiscover(program) {
             break;
           }
 
-          // One record per package — fields mirror the JSON entry. The default
+          // One record per package, every field of the JSON entry. The default
           // view summarizes each package's components (first N + "+N more");
           // --components lists them all (record comma-joins the full array).
           /** @type {import('../formatters/index.mjs').RecordOptions} */
-          const listOpts = {fields: ['displayName', 'name', 'description', 'components']};
+          const listOpts = {};
           if (!options.components) {
             listOpts.format = {
               components: (/** @type {string[]} */ comps) => {
@@ -155,7 +155,7 @@ export function registerDiscover(program) {
         case 'discover.detail': {
           const d = result.data;
           emit(
-            record(d, {fields: ['displayName', 'name', 'description', 'components']}),
+            record(d),
             text(`Usage: ${run} discover ${d.name}/<ComponentName>`),
           );
           break;

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,13 +12,17 @@ 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 ' +
-    'full doc; `--index` lists its sections instead, each with the key to read it by; a ' +
-    'topic plus a section prints that section (by key, exact title, or a unique part of ' +
-    'a title).',
+    'Reads the reference docs one level at a time: with no topic it lists every topic; a ' +
+    'topic lists its sections, each with the key to read it by (a topic with one section ' +
+    'prints whole); a topic plus a section prints that section; `--full` prints the whole ' +
+    'topic, as does `--dense`. With `--json`, a topic returns its whole doc, as docs() ' +
+    'does, and `--index` its section index. A route ' +
+    'opens a node of the docs tree: `cli` lists its guides and reference, ' +
+    '`cli/api/functions` lists every API function, and `cli/api/functions/search` prints ' +
+    'one.',
   fn: 'docs',
   args: [
     {name: 'topic', param: 'topic', required: false},
@@ -28,20 +32,28 @@ export const doc = {
     {
       flag: '--index',
       param: 'options.index',
-      description: "List the topic's sections and their keys instead of printing the whole topic",
+      description: "List the topic's sections and their keys, even for a topic with one section",
+    },
+    {
+      flag: '--full',
+      description:
+        'Print the whole topic instead of its sections (text; `--json` returns the whole topic unless --index). Cannot be set with --index',
     },
   ],
   examples: [
     {label: 'List topics', cli: 'astryx docs'},
-    {label: 'One topic as JSON', cli: 'astryx docs spacing --json'},
-    {label: "A topic's sections", cli: 'astryx docs theme --index'},
+    {label: "A topic's sections", cli: 'astryx docs theme'},
+    {label: 'A whole topic as JSON', cli: 'astryx docs spacing --json'},
     {label: 'One section', cli: 'astryx docs theme quick-start'},
+    {label: 'The CLI docs tree', cli: 'astryx docs cli'},
+    {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown topic, or a section that matches no section or more than one',
+      when: 'unknown topic or route, or a section that matches no section or more than one',
     },
   ],
   related: ['search', 'component', 'hook', 'template'],