@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/foundation/discovery/cli-self-docs.test.mjs

@@ -0,0 +1,395 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the CLI's own typed docs. Every command, API function,
+ * schema, and enum doc this package ships declares the group that reads it,
+ * and each way one can fail to be read is reported: no namespace, a namespace
+ * nothing reads, a clash with the authoring topic's list, a doc that does not
+ * load, and a leaf too large for one read. What `astryx docs <route>` prints
+ * for one doc is pinned here; where the tree puts it is tree.test.mjs's job.
+ *
+ * @input This package's own docs, and fixture doc trees written under the
+ *   working directory.
+ * @output Assertions on the audit and on each doc's rendered content.
+ * @position packages/cli/foundation/discovery — tests for cli-self-docs.mjs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {afterAll, describe, expect, it} from 'vitest';
+import {
+  CLI_DOC_NAMESPACES,
+  auditCliSelfDocs,
+  cliDocIndex,
+  cliDocSection,
+  discoverCliSelfDocSources,
+} from './cli-self-docs.mjs';
+import {routeSegment} from './docs-section-key.mjs';
+
+const SLOW = 60_000;
+
+/** @type {string[]} */
+const tmpRoots = [];
+afterAll(() => {
+  for (const root of tmpRoots) fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** Write `files` (relative path -> content) under a fresh directory. */
+function writeTree(/** @type {Record<string, string>} */ files) {
+  const root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-cli-docs-'));
+  tmpRoots.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const file = path.join(root, rel);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, content);
+  }
+  return root;
+}
+
+const docModule = (/** @type {any} */ doc) =>
+  `export const doc = ${JSON.stringify(doc, null, 2)};\n`;
+
+const command = (/** @type {string} */ name, extra = {}) => ({
+  type: 'command',
+  name,
+  displayName: `astryx ${name}`,
+  namespace: 'cli/commands',
+  summary: `Do ${name}`,
+  ...extra,
+});
+
+const fn = (/** @type {string} */ name, extra = {}) => ({
+  type: 'function',
+  kind: 'api',
+  name,
+  displayName: `${name}()`,
+  namespace: 'cli/api',
+  summary: `The ${name} function.`,
+  importPath: '@astryxdesign/cli/api',
+  params: [],
+  returns: [{type: name, description: 'The result.'}],
+  ...extra,
+});
+
+const enumDoc = (/** @type {string} */ name, extra = {}) => ({
+  type: 'enum',
+  name,
+  displayName: name,
+  namespace: 'cli/api',
+  description: `The ${name}.`,
+  members: [{value: 'A', description: 'The a.'}],
+  ...extra,
+});
+
+const schema = (/** @type {string} */ name, extra = {}) => ({
+  type: 'schema',
+  name,
+  displayName: name,
+  namespace: 'authoring',
+  description: `The ${name} file.`,
+  fields: [{name: 'x', type: 'string', description: 'The x.'}],
+  ...extra,
+});
+
+/** Audit a fixture tree with nothing in the authoring topic's list. */
+const audit = (/** @type {string} */ root, authoringSources = []) =>
+  auditCliSelfDocs({root, authoringSources});
+
+describe('the CLI docs this package ships', () => {
+  it(
+    'each declare a namespace something reads, and none fails, clashes, or overflows',
+    async () => {
+      const result = await auditCliSelfDocs();
+      expect({
+        missing: result.missing,
+        unknown: result.unknown,
+        misfiled: result.misfiled,
+        failed: result.failed,
+        oversized: result.oversized,
+      }).toEqual({
+        missing: [],
+        unknown: [],
+        misfiled: [],
+        failed: [],
+        oversized: [],
+      });
+      expect(result.docs).toBeGreaterThan(0);
+      expect(result.tree + result.authoring).toBe(result.docs);
+    },
+    SLOW,
+  );
+});
+
+describe('auditCliSelfDocs', () => {
+  it('reports a doc with no namespace, and one nothing reads', async () => {
+    const root = writeTree({
+      'api/alpha/alpha.doc.mjs': docModule(fn('alpha', {namespace: undefined})),
+      'clients/cli/commands/beta.doc.mjs': docModule(
+        command('beta', {namespace: 'cli'}),
+      ),
+      'api/gamma/gamma.doc.mjs': docModule(fn('gamma')),
+    });
+    const result = await audit(root);
+    expect(result.missing).toEqual(['api/alpha/alpha.doc.mjs']);
+    expect(result.unknown).toEqual([
+      {source: 'clients/cli/commands/beta.doc.mjs', namespace: 'cli'},
+    ]);
+    expect(result.tree).toBe(1);
+  });
+
+  it('holds the authoring namespace to the authoring topic list', async () => {
+    const root = writeTree({
+      'authoring/x/x.doc.mjs': docModule(schema('x')),
+      'authoring/y/y.doc.mjs': docModule(schema('y', {namespace: 'cli/api'})),
+      'authoring/z/z.doc.mjs': docModule(schema('z')),
+    });
+    const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
+    expect(result.misfiled.map(entry => entry.message)).toEqual([
+      'authoring/x/x.doc.mjs has namespace "authoring", but `astryx docs authoring` does not list it',
+      'authoring/y/y.doc.mjs is read in `astryx docs authoring`, but its namespace is "cli/api"',
+    ]);
+    expect(result.authoring).toBe(1);
+    expect(result.tree).toBe(0);
+  });
+
+  it('reports a doc that fails to load, and skips fixture directories', async () => {
+    const root = writeTree({
+      'api/bad/bad.doc.mjs': 'throw new Error("boom");\n',
+      'api/__fixtures__/ghost.doc.mjs': docModule(fn('ghost')),
+      'foundation/.hidden/hidden.doc.mjs': docModule(fn('hidden')),
+      'foundation/codes.doc.mjs': docModule(enumDoc('codes')),
+    });
+    expect(discoverCliSelfDocSources(root)).toEqual([
+      'api/bad/bad.doc.mjs',
+      'foundation/codes.doc.mjs',
+    ]);
+    const result = await audit(root);
+    expect(result.failed).toEqual([
+      expect.objectContaining({
+        source: 'api/bad/bad.doc.mjs',
+        error: expect.stringContaining('boom'),
+      }),
+    ]);
+    expect(result.tree).toBe(1);
+  });
+
+  it('reports a tree doc too large for one read', async () => {
+    const root = writeTree({
+      'api/big/big.doc.mjs': docModule(
+        fn('big', {description: 'x'.repeat(2_000)}),
+      ),
+      'api/small/small.doc.mjs': docModule(fn('small')),
+    });
+    const result = await auditCliSelfDocs({root, authoringSources: [], budget: 1_000});
+    expect(result.oversized.map(entry => entry.key)).toEqual(['big']);
+  });
+
+  it('names every namespace a CLI doc may declare, and what reads it', () => {
+    expect(CLI_DOC_NAMESPACES).toEqual({
+      'cli/commands': {reader: 'tree'},
+      'cli/api': {reader: 'tree'},
+      authoring: {reader: 'authoring'},
+    });
+  });
+});
+
+/**
+ * An index whose routes are the ones the docs tree gives the CLI's own docs.
+ * @param {any[]} docs
+ */
+const indexOf = docs =>
+  cliDocIndex(docs, (kind, name) =>
+    kind === 'command'
+      ? `cli/commands/${routeSegment(name)}`
+      : kind === 'function'
+        ? `cli/api/functions/${routeSegment(name)}`
+        : null,
+  );
+
+describe('cliDocSection', () => {
+  it('links a command and the function it runs by identity, never by route', () => {
+    const docs = [fn('docs', {command: 'docs'}), command('docs', {fn: 'docs'})];
+    const index = indexOf(docs);
+    expect(JSON.stringify(cliDocSection(docs[1], index).content)).toContain(
+      'It runs `docs()` from `@astryxdesign/cli/api`. Read it with {@link function:docs}.',
+    );
+    expect(JSON.stringify(cliDocSection(docs[0], index).content)).toContain(
+      '`astryx docs` runs it. Read it with {@link command:docs}.',
+    );
+  });
+
+  it("links a function to the command its command line starts with, or to none", () => {
+    const docs = [
+      fn('integrationAddTheme', {command: 'integration add theme'}),
+      command('integration add'),
+      fn('gone', {command: 'gone away'}),
+    ];
+    const index = cliDocIndex(docs);
+    expect(JSON.stringify(cliDocSection(docs[0], index).content)).toContain(
+      '`astryx integration add theme` runs it. Read it with {@link command:integration add}.',
+    );
+    expect(JSON.stringify(cliDocSection(docs[2], index).content)).not.toContain(
+      'runs it',
+    );
+  });
+
+  it('renders a command: usage, arguments, options, examples, exit codes, subcommands', () => {
+    const docs = [
+      command('grp', {subcommands: ['sub', 'gone']}),
+      command('grp sub', {
+        description: 'The long form.',
+        fn: 'grpSub',
+        args: [
+          {name: 'files', required: true, variadic: true, description: 'Files.'},
+        ],
+        options: [
+          {flag: '--fast', description: 'Go fast'},
+          {
+            flag: '--mode <m>',
+            description: 'Mode',
+            choices: ['a', 'b'],
+            default: 'a',
+          },
+          {flag: '--limit <n>', param: 'options.limit'},
+          {flag: '--dry', description: 'Dry run.', default: false},
+        ],
+        examples: [
+          {label: 'Run it', cli: 'astryx grp sub x'},
+          {cli: 'astryx grp sub y'},
+        ],
+        exitCodes: [{code: 1, when: 'it fails'}],
+      }),
+      fn('grpSub', {
+        params: [{name: 'options.limit', type: 'number', description: 'Max.'}],
+      }),
+    ];
+    // `grp gone` has no doc, so it gets no line.
+    const index = cliDocIndex(docs, (kind, name) =>
+      kind === 'command' && name === 'grp gone'
+        ? null
+        : kind === 'command'
+          ? `cli/commands/${routeSegment(name)}`
+          : `cli/api/functions/${routeSegment(name)}`,
+    );
+    const group = cliDocSection(docs[0], index);
+    const sub = cliDocSection(docs[1], index);
+    expect(group.content).toContainEqual({
+      type: 'list',
+      style: 'unordered',
+      items: ['`astryx grp sub`: {@link command:grp sub}'],
+    });
+    expect(sub).toMatchObject({id: 'grp-sub', title: 'astryx grp sub'});
+    expect(sub.content).toEqual([
+      {type: 'prose', text: 'Do grp sub'},
+      {type: 'prose', text: 'The long form.'},
+      {type: 'code', lang: 'bash', code: 'astryx grp sub <files...>'},
+      {
+        type: 'table',
+        headers: ['Argument', 'Description'],
+        rows: [['`files`', 'Files.']],
+      },
+      {
+        type: 'table',
+        headers: ['Option', 'Description'],
+        rows: [
+          ['`--fast`', 'Go fast'],
+          ['`--mode <m>`', 'Mode. One of: `a`, `b`. Default: `a`.'],
+          ['`--limit <n>`', 'Max.'],
+          ['`--dry`', 'Dry run.'],
+        ],
+      },
+      {
+        type: 'code',
+        lang: 'bash',
+        code: '# Run it\nastryx grp sub x\nastryx grp sub y',
+      },
+      {
+        type: 'table',
+        headers: ['Exit code', 'When'],
+        rows: [['1', 'it fails']],
+      },
+      {
+        type: 'prose',
+        text: 'It runs `grpSub()` from `@astryxdesign/cli/api`. Read it with {@link function:grpSub}.',
+      },
+    ]);
+  });
+
+  it('marks required parameters and adds a Default column when a parameter has a default', () => {
+    const beta = fn('beta', {
+      params: [
+        {name: 'slug', type: 'string', description: 'The slug.', required: true},
+        {name: 'options.limit', type: 'number', description: 'How many.', default: '20'},
+      ],
+    });
+    const table = cliDocSection(beta, indexOf([beta])).content.find(
+      (/** @type {any} */ block) => block.type === 'table',
+    );
+    expect(table).toEqual({
+      type: 'table',
+      headers: ['Parameter', 'Type', 'Default', 'Description'],
+      rows: [
+        ['`slug` (required)', '`string`', '', 'The slug.'],
+        ['`options.limit`', '`number`', '20', 'How many.'],
+      ],
+    });
+  });
+
+  it('renders an API function, an enum, and a schema', () => {
+    const alpha = fn('alpha', {
+      description: 'Longer.',
+      signature: 'alpha(x: string): Promise<Alpha>',
+      params: [{name: 'x', type: 'string', description: 'The x.'}],
+      throws: [{code: 'ERR_X', when: 'x is bad'}],
+      examples: [{label: 'Call it', code: "await alpha('x');"}],
+    });
+    const codes = enumDoc('codes', {
+      members: [
+        {value: 'A', description: 'The a.'},
+        {value: 'B', description: 'The b.', deprecated: 'Use A.'},
+      ],
+    });
+    const output = schema('output', {namespace: 'cli/api'});
+    const index = indexOf([alpha, codes, output]);
+    expect(cliDocSection(alpha, index).content).toEqual([
+      {type: 'prose', text: 'The alpha function.'},
+      {type: 'prose', text: 'Longer.'},
+      {type: 'code', lang: 'ts', code: 'alpha(x: string): Promise<Alpha>'},
+      {type: 'prose', text: 'Import it from `@astryxdesign/cli/api`.'},
+      {
+        type: 'table',
+        headers: ['Parameter', 'Type', 'Description'],
+        rows: [['`x`', '`string`', 'The x.']],
+      },
+      {
+        type: 'table',
+        headers: ['Returns', 'Description'],
+        rows: [['`alpha`', 'The result.']],
+      },
+      {
+        type: 'table',
+        headers: ['Throws', 'When'],
+        rows: [['`ERR_X`', 'x is bad']],
+      },
+      {type: 'code', lang: 'ts', label: 'Call it', code: "await alpha('x');"},
+    ]);
+    expect(cliDocSection(codes, index)).toEqual({
+      id: 'codes',
+      title: 'codes',
+      content: [
+        {type: 'prose', text: 'The codes.'},
+        {
+          type: 'table',
+          headers: ['Value', 'Meaning'],
+          rows: [
+            ['`A`', 'The a.'],
+            ['`B`', 'The b. Deprecated: Use A.'],
+          ],
+        },
+      ],
+    });
+    const rendered = cliDocSection(output, index);
+    expect(rendered.id).toBe('output');
+    expect(JSON.stringify(rendered.content)).toContain('The output file.');
+  });
+});

package/foundation/discovery/component-discovery.d.mts

@@ -124,6 +124,44 @@ export function discoverIntegrationComponents(integration: {
     issuesUrl: string | undefined;
     group: string | null;
 }>;
+/**
+ * Load and validate every discovered integration component independently.
+ * Invalid metadata or a missing same-stem source removes only that component;
+ * callers can report the returned errors while retaining valid siblings.
+ *
+ * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @returns {Promise<{
+ *   components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null}>,
+ *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
+ *   errors: Array<{name: string, message: string}>,
+ * }>}
+ */
+export function discoverValidIntegrationComponents(integration: {
+    name: string;
+    components?: string;
+    issuesUrl?: string;
+}): Promise<{
+    components: Array<{
+        name: string;
+        package: string;
+        docPath: string;
+        sourcePath: string;
+        issuesUrl: string | undefined;
+        group: string | null;
+    }>;
+    discovered: Array<{
+        name: string;
+        package: string;
+        docPath: string;
+        sourcePath: string | null;
+        issuesUrl: string | undefined;
+        group: string | null;
+    }>;
+    errors: Array<{
+        name: string;
+        message: string;
+    }>;
+}>;
 /**
  * Find an integration component's doc file by name within a loaded
  * integration's resolved `components` dir. Honors the same-stem convention
@@ -175,4 +213,4 @@ export function discoverOwnedComponents(coreDir: string, loadedIntegrations?: Ar
     issuesUrl: string | undefined;
 }>;
 /** The owner package name for built-in (core) components. */
-export const CORE_PACKAGE: "@astryxdesign/core";
+export const CORE_PACKAGE: import("../../authoring/index.js").ProviderId;

package/foundation/discovery/component-discovery.mjs

@@ -7,11 +7,13 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {existsCaseExact} from '../fs/paths.mjs';
+import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
+import {loadComponentDoc} from './component-loader.mjs';
 
 const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
 
 /** The owner package name for built-in (core) components. */
-export const CORE_PACKAGE = '@astryxdesign/core';
+export const CORE_PACKAGE = CORE_PROVIDER_ID;
 
 /** Conventional doc-file suffixes for integration components (same-stem). */
 const INTEGRATION_DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];
@@ -691,6 +693,53 @@ export function discoverIntegrationComponents(integration) {
   return [...byName.values()];
 }
 
+/**
+ * Load and validate every discovered integration component independently.
+ * Invalid metadata or a missing same-stem source removes only that component;
+ * callers can report the returned errors while retaining valid siblings.
+ *
+ * @param {{name: string, components?: string, issuesUrl?: string}} integration
+ * @returns {Promise<{
+ *   components: Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null}>,
+ *   discovered: Array<{name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>,
+ *   errors: Array<{name: string, message: string}>,
+ * }>}
+ */
+export async function discoverValidIntegrationComponents(integration) {
+  const discovered = discoverIntegrationComponents(integration);
+  /** @type {Array<{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null}>} */
+  const components = [];
+  /** @type {Array<{name: string, message: string}>} */
+  const errors = [];
+
+  for (const record of discovered) {
+    if (record.sourcePath == null) {
+      errors.push({
+        name: record.name,
+        message: `Component "${record.name}" is missing its same-stem source file ${record.name}.tsx.`,
+      });
+      continue;
+    }
+    try {
+      await loadComponentDoc(record.docPath);
+      components.push(
+        /** @type {{name: string, package: string, docPath: string, sourcePath: string, issuesUrl: string|undefined, group: string|null}} */ (
+          record
+        ),
+      );
+    } catch (err) {
+      errors.push({
+        name: record.name,
+        message: `Component "${record.name}" has invalid metadata: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      });
+    }
+  }
+
+  return {components, discovered, errors};
+}
+
 /**
  * Find an integration component's doc file by name within a loaded
  * integration's resolved `components` dir. Honors the same-stem convention

package/foundation/discovery/component-loader.d.mts

@@ -2,49 +2,46 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Load a component doc through the shared load/validation boundary.
+ * Load a component or hook doc and check it against its kind's parser.
  *
- * This is the typed counterpart to {@link loadDocs}: it loads `.doc.ts` via
- * jiti (and `.doc.mjs`/`.doc.js` via native import) and validates via
- * `parseDoc`, which accepts BOTH formats, so this loader reads whichever the
- * file uses:
- *   - NEW: a stamped default export (`export default {type: 'component', ...}`
- *     / `'function'` / `'generic'`) — the same single-export convention the
- *     other authoring parsers use for config/integration/template. These carry
- *     a stamped `type` and validate against the matching per-kind parser.
- *   - OLD: the legacy loose `export const docs = {...}` (no `type`), validated
- *     against the permissive legacy union.
- * The default export wins when both are present. Throws a readable
- * `formatZodError`-style message on failure. Translations (`docsZh`/
- * `docsDense`) are merged exactly as {@link loadDocs} does so callers see
- * identical output.
+ * Reads `.doc.ts` through jiti and `.doc.mjs`/`.doc.js` natively. Both formats
+ * load: a stamped default export (`export default {type: 'component', ...}`)
+ * checked against its kind, and the legacy `export const docs = {...}` checked
+ * against the permissive legacy union. The default export wins when both are
+ * present. Throws the parser's readable message when the doc fails.
  *
  * @param {string} docPath absolute path to a `.doc.{ts,mjs,js}` file
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
- * @returns {Promise<object>} the validated (and optionally translated) doc
+ * @param {LoadDocOptions} [opts]
+ * @returns {Promise<any>} the checked (and optionally translated) doc
  */
-export function loadComponentDoc(docPath: string, { zh, dense, lang }?: {
-    zh?: boolean;
-    dense?: boolean;
-    lang?: string;
-}): Promise<object>;
+export function loadComponentDoc(docPath: string, opts?: LoadDocOptions): Promise<any>;
 /**
- * @param {any} docs
- * @param {any} translation
- * @returns {any}
- */
-export function mergeTranslation(docs: any, translation: any): any;
-/**
- * Load the typed docs object from a .doc.mjs file.
- * Supports --lang flag: 'zh' for Chinese, 'dense' for compressed format.
- * Also supports legacy --zh and --dense flags.
- * Translations are merged onto the base docs, keeping structure intact.
+ * Load a component or hook doc without checking it. Supports `lang` ('zh' for
+ * Chinese, 'dense' for compressed) and the legacy `zh`/`dense` flags; the
+ * translation is laid over the doc, keeping its structure. A file that exports
+ * no doc reads as `undefined`.
  * @param {string} readmePath
- * @param {{zh?: boolean, dense?: boolean, lang?: string}} [opts]
+ * @param {LoadDocOptions} [opts]
  * @returns {Promise<any>}
  */
-export function loadDocs(readmePath: string, { zh, dense, lang }?: {
-    zh?: boolean;
-    dense?: boolean;
-    lang?: string;
-}): Promise<any>;
+export function loadDocs(readmePath: string, opts?: LoadDocOptions): Promise<any>;
+export { mergeTranslation } from "../doc-compiler/overlays.mjs";
+export type LoadDocOptions = {
+    /**
+     * legacy flag for `lang: 'zh'`
+     */
+    zh?: boolean | undefined;
+    /**
+     * legacy flag for `lang: 'dense'`
+     */
+    dense?: boolean | undefined;
+    /**
+     * wins over the legacy flags
+     */
+    lang?: string | null | undefined;
+    /**
+     * which root reads the doc
+     * (default: components)
+     */
+    root?: "hooks" | "components" | undefined;
+};