@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/api/doctor/doctor.test.mjs

@@ -6,14 +6,28 @@
  * invariant (the counts must always add up to the number of checks).
  */
 
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+  AUTHORING_ROOT,
+  AUTHORING_SELF_DOCS,
+  auditAuthoringSelfDocs,
+} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {docs} from '../docs/docs.mjs';
+import {auditCliSelfDocs} from '../../foundation/discovery/cli-self-docs.mjs';
 import {
   doctor,
+  checkAuthoringDocs,
+  checkCliDocs,
+  checkDocsTree,
+  checkDocsProgressiveDisclosure,
   checkImplicitIntegrations,
+  checkProviderIdentity,
+  checkIntegrationIssues,
   checkVersionAlignment,
   checkPackageManager,
 } from './doctor.mjs';
@@ -72,6 +86,27 @@ describe('doctor leaf', () => {
   }, SLOW);
 });
 
+describe('integration issue check', () => {
+  it('surfaces cross-package replacement warnings', () => {
+    const check = checkIntegrationIssues({
+      integrationIssues: [
+        {
+          package: '@acme/later',
+          code: 'ambiguous_template_replacement',
+          severity: 'warning',
+          message: 'Later configured replacement wins.',
+        },
+      ],
+    });
+
+    expect(check).toMatchObject({
+      id: 'integration-issues',
+      status: 'warn',
+      message: expect.stringContaining('Later configured replacement wins.'),
+    });
+  });
+});
+
 describe('doctor leaf — degradation & error paths', () => {
   it('does not crash on multiple config files; reports a config FAIL', async () => {
     const dir = mkProject({
@@ -214,6 +249,77 @@ describe('checkPackageManager', () => {
   });
 });
 
+describe('checkProviderIdentity', () => {
+  /** @param {object} [fields] */
+  const loaded = (fields = {}) => ({
+    name: '@acme/widgets',
+    providerId: '@acme/widgets',
+    version: '1.0.0',
+    __spec: '@acme/widgets',
+    __packageDir: '/abs/node_modules/@acme/widgets',
+    __manifestFile: '/abs/node_modules/@acme/widgets/astryx.integration.mjs',
+    ...fields,
+  });
+
+  it('skips when the project could not be read', () => {
+    expect(checkProviderIdentity({integrations: null}).status).toBe('info');
+  });
+
+  it('reports none when nothing is loaded', () => {
+    const c = checkProviderIdentity({integrations: []});
+    expect(c.status).toBe('info');
+    expect(c.message).toContain('None');
+  });
+
+  it('passes when each loaded integration has its own provider ID', () => {
+    const c = checkProviderIdentity({
+      integrations: [
+        loaded(),
+        loaded({
+          name: '@acme/charts',
+          providerId: '@acme/charts',
+          __spec: '@acme/charts',
+        }),
+      ],
+    });
+    expect(c.status).toBe('pass');
+    expect(c.message).toContain('2 loaded integrations');
+  });
+
+  it('warns and names both packages when a later claimant is set aside', () => {
+    const message =
+      '@acme/renamed@2.0.0 and @acme/widgets@1.0.0 both claim provider ID ' +
+      '"@acme/widgets". @acme/widgets@1.0.0 loads first and is used; ' +
+      '@acme/renamed@2.0.0 contributes nothing until one package changes ' +
+      'its providerId.';
+    const c = checkProviderIdentity({
+      integrations: [
+        loaded(),
+        loaded({
+          name: '@acme/renamed',
+          version: '2.0.0',
+          __spec: '@acme/renamed',
+          __providerConflict: {
+            providerId: '@acme/widgets',
+            claimedBy: '@acme/widgets',
+            message,
+          },
+        }),
+      ],
+    });
+    expect(c.status).toBe('warn');
+    expect(c.message).toBe(message);
+    expect(c.fix).toContain('providerId');
+  });
+
+  it('is part of the report doctor returns', async () => {
+    const r = await doctor({cwd});
+    expect(r.data.checks.map(check => check.id)).toContain(
+      'provider-identity',
+    );
+  }, SLOW);
+});
+
 describe('checkImplicitIntegrations', () => {
   /** @param {object} [fields] */
   const autolinked = (fields = {}) => ({
@@ -297,3 +403,506 @@ describe('checkImplicitIntegrations', () => {
     expect(r.data.checks.map(c => c.id)).toContain('implicit-integrations');
   }, SLOW);
 });
+
+describe('checkDocsProgressiveDisclosure', () => {
+  it('passes when every topic index and section fits one read', async () => {
+    const c = await checkDocsProgressiveDisclosure({
+      docsCatalog: DocsCatalog.fromBuiltins(),
+      docsCatalogIssues: [],
+    });
+    expect(c).toMatchObject({id: 'docs-progressive-disclosure', status: 'pass'});
+    expect(c.message).toMatch(/^\d+ topics: /);
+  }, SLOW);
+
+  it('warns on an invalid doc an integration contributed', async () => {
+    const c = await checkDocsProgressiveDisclosure({
+      docsCatalogIssues: [
+        {
+          package: '@acme/widgets',
+          code: 'invalid_doc',
+          severity: 'error',
+          message: 'bad.doc.mjs exports no doc',
+        },
+      ],
+    });
+    expect(c.status).toBe('warn');
+    expect(c.message).toBe('@acme/widgets: bad.doc.mjs exports no doc');
+  });
+
+  it('warns when the docs catalog cannot be built', async () => {
+    const c = await checkDocsProgressiveDisclosure({docsCatalogError: 'boom'});
+    expect(c.status).toBe('warn');
+    expect(c.message).toContain('boom');
+  });
+
+  it('names a section over the budget and a topic that fails to load', async () => {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-docs-'));
+    tmpDirs.push(dir);
+    const huge = {
+      name: 'huge',
+      title: 'Huge',
+      description: 'Too big for one read.',
+      sections: [
+        {title: 'Small', content: [{type: 'prose', text: 'Fits.'}]},
+        {title: 'Everything', content: [{type: 'prose', text: 'x'.repeat(40 * 1024)}]},
+      ],
+    };
+    fs.writeFileSync(
+      path.join(dir, 'huge.doc.mjs'),
+      `export const docs = ${JSON.stringify(huge)};\n`,
+    );
+    fs.writeFileSync(path.join(dir, 'broken.doc.mjs'), 'export const docs = {;\n');
+    const c = await checkDocsProgressiveDisclosure({
+      docsCatalog: DocsCatalog.fromBuiltins({
+        huge: path.join(dir, 'huge.doc.mjs'),
+        broken: path.join(dir, 'broken.doc.mjs'),
+      }),
+      docsCatalogIssues: [],
+    });
+    expect(c.status).toBe('warn');
+    expect(c.message).toMatch(/^2 problems: /);
+    expect(c.message).toContain('huge everything: 41 KB, over the 32 KB one read may return');
+    expect(c.message).toContain('broken: ');
+    expect(c.message).not.toContain('huge small');
+  });
+});
+
+describe('checkAuthoringDocs', () => {
+  it('passes when every authoring self-doc is reachable and fits one read', async () => {
+    const c = await checkAuthoringDocs();
+    expect(c).toMatchObject({id: 'authoring-docs', status: 'pass'});
+    expect(c.message).toContain('astryx docs authoring');
+  }, SLOW);
+});
+
+describe('checkCliDocs', () => {
+  const CLI_DOCS_FIX =
+    'Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).';
+
+  /** A doc tree under the working directory, as the CLI root. */
+  function writeRoot(/** @type {Record<string, any>} */ docsByPath) {
+    const root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-cli-docs-'));
+    tmpDirs.push(root);
+    for (const [rel, doc] of Object.entries(docsByPath)) {
+      const file = path.join(root, rel);
+      fs.mkdirSync(path.dirname(file), {recursive: true});
+      fs.writeFileSync(file, `export const doc = ${JSON.stringify(doc)};\n`);
+    }
+    return root;
+  }
+
+  it(
+    'passes on this repo, counting where each CLI doc is read',
+    async () => {
+      const audit = await auditCliSelfDocs();
+      expect(await checkCliDocs()).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'pass',
+        message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`astryx docs cli\` tree and ${audit.authoring} in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails on a doc with no namespace and one no topic reads, and names the fix',
+    async () => {
+      const root = writeRoot({
+        'api/alpha/alpha.doc.mjs': {
+          type: 'function',
+          kind: 'api',
+          name: 'alpha',
+          displayName: 'alpha()',
+          summary: 'The alpha function.',
+          params: [],
+          returns: [{type: 'alpha', description: 'The alpha.'}],
+        },
+        'clients/cli/commands/beta.doc.mjs': {
+          type: 'command',
+          name: 'beta',
+          displayName: 'astryx beta',
+          namespace: 'cli',
+          summary: 'Do beta',
+        },
+      });
+      expect(
+        await checkCliDocs(undefined, {root, authoringSources: []}),
+      ).toEqual({
+        id: 'cli-docs',
+        label: 'CLI docs',
+        status: 'fail',
+        message:
+          '2 problems: api/alpha/alpha.doc.mjs has no namespace, so no `astryx docs` topic reads it; clients/cli/commands/beta.doc.mjs has namespace "cli", which no `astryx docs` topic reads',
+        fix: CLI_DOCS_FIX,
+      });
+    },
+    SLOW,
+  );
+});
+
+describe('checkDocsTree', () => {
+  it(
+    'passes on this repo: every CLI doc in a cli group has one route',
+    async () => {
+      const {loadDocsTree} = await import(
+        '../../foundation/doc-compiler/tree.mjs'
+      );
+      const tree = await loadDocsTree({fresh: true});
+      const nodes = [...tree.nodes.values()];
+      const namespaces = nodes.filter(node => node.kind === 'namespace').length;
+      expect(await checkDocsTree()).toEqual({
+        id: 'docs-tree',
+        label: 'Docs tree',
+        status: 'pass',
+        message: expect.stringMatching(
+          /^The docs tree has \d+ docs in \d+ sections \(\d+ at the top\), each at one route\.$/,
+        ),
+      });
+    },
+    SLOW,
+  );
+
+  it('fails on a tree with a broken placement, and names the fix', async () => {
+    const {buildDocsTree} = await import(
+      '../../foundation/doc-compiler/tree.mjs'
+    );
+    const tree = buildDocsTree({
+      namespaces: [
+        {
+          provider: '@acme/kit',
+          providerId: '@acme/kit',
+          source: '@acme/kit/tree/guides.doc.mjs',
+          doc: {
+            type: 'namespace',
+            name: 'guides',
+            title: 'Guides',
+            summary: 'Every guide.',
+            slots: {all: {title: 'All', accepts: {kinds: ['generic']}}},
+          },
+        },
+      ],
+      docs: [
+        {
+          provider: '@acme/kit',
+          providerId: '@acme/kit',
+          source: '@acme/kit/tree/setup.doc.mjs',
+          kind: 'generic',
+          name: 'setup',
+          title: 'Setup',
+          summary: 'Set it up.',
+          group: null,
+          placement: {parent: 'namespace:guidez'},
+        },
+      ],
+    });
+    const c = await checkDocsTree(undefined, {tree});
+    // New findings warn (0.6 compatibility): a broken tree is named, not fatal.
+    expect(c).toMatchObject({id: 'docs-tree', status: 'warn'});
+    expect(c.message).toContain(
+      '@acme/kit/tree/setup.doc.mjs: placement.parent "namespace:guidez" names no namespace; @acme/kit declares "guides".',
+    );
+    expect(c.fix).toMatch(/a placement names a namespace of its own package/);
+  });
+});
+
+describe('checkAuthoringDocs against the public authoring surface', () => {
+  const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
+  const NAMESPACE_TYPES =
+    'NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in `astryx docs authoring`';
+  const SURFACE_FIX =
+    'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+  /** A copy of this repo's authoring tree, to break one piece of at a time. */
+  function copyAuthoring() {
+    const root = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-doctor-authoring-'),
+    );
+    tmpDirs.push(root);
+    fs.cpSync(AUTHORING_ROOT, root, {
+      recursive: true,
+      filter: src => !src.endsWith('.test.mjs'),
+    });
+    return root;
+  }
+
+  /** @param {string} source */
+  const without = source => AUTHORING_SELF_DOCS.filter(s => s !== source);
+
+  /** @param {string} text */
+  const escape = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  it(
+    'passes on this repo and prints exactly what it printed before',
+    async () => {
+      expect(await checkAuthoringDocs()).toEqual({
+        id: 'authoring-docs',
+        label: 'Authoring docs',
+        status: 'pass',
+        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`astryx docs authoring\`.`,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'passes on an unchanged copy of the tree, and writes nothing to it',
+    async () => {
+      const root = copyAuthoring();
+      const before = snapshot(root);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'pass',
+      });
+      expect(snapshot(root)).toEqual(before);
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when the NamespaceDoc self-doc is left out of AUTHORING_SELF_DOCS',
+    async () => {
+      const root = copyAuthoring();
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: without(NAMESPACE),
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toBe(
+        `2 problems: ${NAMESPACE} is not in \`astryx docs authoring\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    "fails when the topic's index no longer exposes the NamespaceDoc section",
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      const topicKeys = new Set(
+        index.data.sections
+          .map((/** @type {any} */ s) => s.id)
+          .filter((/** @type {string} */ id) => id !== 'namespace-doc'),
+      );
+      const c = await checkAuthoringDocs(undefined, {topicKeys});
+      expect(c).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE_TYPES}: ${NAMESPACE} renders section "namespace-doc", which the topic's index does not list`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'fails when @astryxdesign/cli/authoring stops exporting NamespaceDoc',
+    async () => {
+      const root = copyAuthoring();
+      const index = path.join(root, 'index.d.ts');
+      const before = fs.readFileSync(index, 'utf8');
+      const after = before.replace(
+        /^export type \{NamespaceDoc\} from .*\n/m,
+        '',
+      );
+      expect(after).not.toBe(before);
+      fs.writeFileSync(index, after);
+      expect(await checkAuthoringDocs(undefined, {root})).toMatchObject({
+        status: 'fail',
+        message: `${NAMESPACE} documents NamespaceDoc, which @astryxdesign/cli/authoring does not export`,
+        fix: SURFACE_FIX,
+      });
+    },
+    SLOW,
+  );
+
+  it.each([
+    [
+      'the graph-fields doc',
+      'doctypes/base/graph-fields.doc.mjs',
+      'doctypes/base/type.ts',
+      [
+        'AuthoredDocKind',
+        'DocAudience',
+        'DocPlacement',
+        'AuthoredDocGraphFields',
+      ],
+    ],
+    [
+      'the identity doc',
+      'identity/identity.doc.mjs',
+      'identity/type.ts',
+      [
+        'ProviderId',
+        'ArtifactId',
+        'DocId',
+        'ProviderInstance',
+        'AuthoredDocEntry',
+      ],
+    ],
+    [
+      'the semantic-block doc',
+      'doctypes/reference/reference.doc.mjs',
+      'doctypes/reference/type.ts',
+      [
+        'WorkflowStep',
+        'WorkflowDocBlock',
+        'CollectionDocBlock',
+        'ReferenceDocBlock',
+      ],
+    ],
+  ])(
+    'fails when %s is removed, which the self-doc audit alone passes',
+    async (_what, source, module, names) => {
+      const root = copyAuthoring();
+      fs.rmSync(path.join(root, source));
+      const sources = without(source);
+      expect(await auditAuthoringSelfDocs({root, sources})).toEqual({
+        sections: sources.length,
+        unreachable: [],
+        failed: [],
+        oversized: [],
+      });
+      const c = await checkAuthoringDocs(undefined, {root, sources});
+      expect(c.status).toBe('fail');
+      expect(c.fix).toBe(SURFACE_FIX);
+      expect(c.message).toMatch(
+        new RegExp(
+          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`astryx docs authoring\`: no self-doc sits beside ${escape(module)}$`,
+        ),
+      );
+      for (const name of names) {
+        expect(c.message).toMatch(new RegExp(`(^|, )${name}(,| from)`));
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps the message and fix of a failure only the self-doc audit reports',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'identity', 'broken.doc.mjs'),
+        'export const doc = {;\n',
+      );
+      const c = await checkAuthoringDocs(undefined, {
+        root,
+        sources: [...AUTHORING_SELF_DOCS, 'identity/broken.doc.mjs'],
+      });
+      expect(c.status).toBe('fail');
+      expect(c.message).toMatch(/^identity\/broken\.doc\.mjs failed to load: /);
+      expect(c.fix).toBe(
+        'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'reports a topic it cannot read rather than skipping the comparison',
+    async () => {
+      const spy = vi
+        .spyOn(DocsCatalog, 'fromBuiltins')
+        .mockImplementationOnce(() => {
+          throw new Error('no built-in docs');
+        });
+      try {
+        expect(await checkAuthoringDocs()).toMatchObject({
+          status: 'fail',
+          message:
+            '`astryx docs authoring` could not be read: no built-in docs',
+          fix: SURFACE_FIX,
+        });
+      } finally {
+        spy.mockRestore();
+      }
+    },
+    SLOW,
+  );
+
+  it(
+    'fails rather than passes when the surface exports no types at all',
+    async () => {
+      const root = copyAuthoring();
+      fs.writeFileSync(
+        path.join(root, 'index.d.ts'),
+        "export {parseDoc} from './doctypes/parse.mjs';\n",
+      );
+      const c = await checkAuthoringDocs(undefined, {root});
+      expect(c.status).toBe('fail');
+      expect(c.message).toContain(
+        '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+      );
+    },
+    SLOW,
+  );
+});
+
+/**
+ * Every file under `root` with its contents.
+ * @param {string} root
+ * @returns {Record<string, string>}
+ */
+function snapshot(root) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else out[path.relative(root, full)] = fs.readFileSync(full, 'utf8');
+    }
+  };
+  walk(root);
+  return out;
+}
+
+describe('doctor docs checks', () => {
+  it('runs both docs checks and they pass on the repo', async () => {
+    const r = await doctor({cwd});
+    const byId = Object.fromEntries(r.data.checks.map(c => [c.id, c.status]));
+    expect(byId['authoring-docs']).toBe('pass');
+    expect(byId['docs-progressive-disclosure']).toBe('pass');
+  }, SLOW);
+});
+
+describe('checkDocsProgressiveDisclosure languages', () => {
+  it('checks every overlay a topic ships, not only English', async () => {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-lang-'));
+    tmpDirs.push(dir);
+    const deploying = {
+      name: 'deploying',
+      title: 'Deploying',
+      description: 'Ship it.',
+      sections: [{title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]}],
+    };
+    fs.writeFileSync(
+      path.join(dir, 'deploying.doc.mjs'),
+      `export const docs = ${JSON.stringify(deploying)};\n`,
+    );
+    fs.writeFileSync(
+      path.join(dir, 'deploying.doc.zh.mjs'),
+      "throw new Error('zh overlay broken');\n",
+    );
+    fs.writeFileSync(
+      path.join(dir, 'deploying.doc.dense.mjs'),
+      `export const docsDense = ${JSON.stringify({
+        sections: [
+          {
+            section: 'Overview',
+            title: 'Overview',
+            content: [{type: 'prose', text: 'x'.repeat(40 * 1024)}],
+          },
+        ],
+      })};\n`,
+    );
+    const c = await checkDocsProgressiveDisclosure({
+      docsCatalog: DocsCatalog.fromBuiltins({deploying: path.join(dir, 'deploying.doc.mjs')}),
+      docsCatalogIssues: [],
+    });
+    expect(c.status).toBe('warn');
+    expect(c.message).toContain('deploying [zh]: zh overlay broken');
+    expect(c.message).toContain('deploying [dense] overview: 41 KB');
+    expect(c.message).not.toMatch(/deploying overview:/);
+  });
+});

package/api/gap-report/gap-report.doc.mjs

@@ -10,6 +10,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'gapReport',
+  namespace: 'cli/api',
   displayName: 'gapReport()',
   summary: 'Route a design-system gap through the fan-out handler composition.',
   description:
@@ -32,17 +33,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Component or general design-system area. Required unless listCategories is true.',
+        'Component or general design-system area, up to 120 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.category',
       type: 'GapReportCategory',
-      description: 'Fixed category from the reported category vocabulary.',
+      description:
+        'Fixed category from the reported category vocabulary. Required unless listCategories is true.',
     },
     {
       name: 'options.reason',
       type: 'string',
-      description: 'What capability was missing or difficult.',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.detail',
@@ -65,7 +68,8 @@ export const doc = {
     {
       name: 'options.listCategories',
       type: 'boolean',
-      description: 'Return categories without resolving a route or writing.',
+      description:
+        'Return categories without resolving a route or writing; the component and every other option are ignored.',
       default: 'false',
     },
     {