@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/foundation/doc-compiler/lower-doc.test.mjs

@@ -0,0 +1,495 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file lowerDoc, the compiled-node parsers, and diagnostics: every doc kind
+ *   lowers into one sealed node shape, and every failure has one diagnostic.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  COMPILED_DOC_KINDS,
+  COMPILED_DOC_SCHEMA_VERSION,
+  lowerDoc,
+} from './compile.mjs';
+import {
+  DIAGNOSTIC_CODES,
+  diagnostic,
+  diagnosticProblem,
+  sortDiagnostics,
+} from './diagnostics.mjs';
+import {parseCompiledDocNode, parseCompiledDocsBundle} from './ir.mjs';
+
+/**
+ * @param {any} doc
+ * @param {object} [more]
+ * @returns {any}
+ */
+const input = (doc, more = {}) => ({
+  id: '@acme/kit:components:Card',
+  root: 'components',
+  provider: '@acme/kit',
+  source: '@acme/kit/src/Card.doc.mjs',
+  lang: null,
+  file: {file: 'Card.doc.mjs', doc},
+  ...more,
+});
+
+const card = {
+  type: 'component',
+  name: 'Card',
+  displayName: 'Card',
+  usage: {description: 'A card.'},
+  props: [{name: 'title', type: 'string', description: 'The title.'}],
+};
+
+describe('lowerDoc', () => {
+  it('lowers each root into its kind, with package provenance and JSON doc', () => {
+    const cases = [
+      ['components', card, 'component'],
+      [
+        'components',
+        {name: 'Old', description: 'Legacy.', props: []},
+        'component',
+      ],
+      [
+        'hooks',
+        {
+          type: 'function',
+          kind: 'hook',
+          name: 'useThing',
+          displayName: 'useThing',
+          description: 'Does a thing.',
+          params: [],
+          returns: [],
+        },
+        'function',
+      ],
+      [
+        'templates',
+        {type: 'page', name: 'Home', description: 'A page.'},
+        'page',
+      ],
+      [
+        'templates',
+        {type: 'block', name: 'Hero', description: 'A block.'},
+        'block',
+      ],
+      [
+        'themes',
+        {
+          type: 'theme',
+          name: 'ocean',
+          displayName: 'Ocean',
+          description: 'Blue.',
+          maintained: true,
+        },
+        'theme',
+      ],
+      [
+        'self-docs',
+        {type: 'enum', name: 'codes', description: 'Codes.', values: []},
+        'enum',
+      ],
+    ];
+    for (const [root, doc, kind] of cases) {
+      const {node, diagnostics} = lowerDoc(input(doc, {root}));
+      expect({root, kind: node?.kind}).toEqual({root, kind});
+      expect(node?.provenance).toEqual({
+        provider: '@acme/kit',
+        source: '@acme/kit/src/Card.doc.mjs',
+      });
+      expect(node?.schemaVersion).toBe(COMPILED_DOC_SCHEMA_VERSION);
+      expect(() => parseCompiledDocNode(node)).not.toThrow();
+      // Legacy and stamped docs parse cleanly; nothing to report.
+      expect(diagnostics.filter(d => d.code !== 'invalid_doc')).toEqual([]);
+    }
+  });
+
+  it('carries the authored doc as JSON: key order kept, undefined dropped', () => {
+    const {node} = lowerDoc(
+      input({
+        ...card,
+        playground: {defaults: {onOpenChange: undefined, size: 'md'}},
+      }),
+    );
+    expect(Object.keys(node?.doc)).toEqual([
+      'type',
+      'name',
+      'displayName',
+      'usage',
+      'props',
+      'playground',
+    ]);
+    expect(node?.doc.playground).toEqual({defaults: {size: 'md'}});
+  });
+
+  it('lays the translation for the reading language over the doc', () => {
+    const {node} = lowerDoc(
+      input(card, {
+        lang: 'zh',
+        file: {
+          file: 'Card.doc.mjs',
+          doc: card,
+          overlay: {
+            usage: {description: '卡片。'},
+            propDescriptions: {title: '标题。'},
+          },
+        },
+      }),
+    );
+    expect(node?.lang).toBe('zh');
+    expect(node?.doc.usage.description).toBe('卡片。');
+    expect(node?.doc.props[0]).toEqual({
+      name: 'title',
+      type: 'string',
+      description: '标题。',
+    });
+  });
+
+  it('keeps a doc that fails its parser, and reports why', () => {
+    const {node, diagnostics, failure} = lowerDoc(
+      input({type: 'component', name: 'Card'}),
+    );
+    expect(node?.doc).toEqual({type: 'component', name: 'Card'});
+    expect(diagnostics.map(d => d.code)).toEqual(['invalid_doc']);
+    expect(failure).toBeInstanceOf(Error);
+    expect(diagnostics[0].message).toBe(/** @type {Error} */ (failure).message);
+  });
+
+  it("keeps a doc of another kind, in its root's kind, and names the mismatch", () => {
+    const {node, diagnostics} = lowerDoc(
+      input({type: 'page', name: 'Home', description: 'A page.'}),
+    );
+    expect(node?.kind).toBe('component');
+    expect(diagnostics.map(d => d.code)).toEqual(['wrong_kind']);
+  });
+
+  it('yields no node, and records what failed, when the file cannot be read', () => {
+    const thrown = new SyntaxError('Unexpected token');
+    const loaded = lowerDoc(
+      input(card, {file: {file: 'Card.doc.mjs', error: thrown}}),
+    );
+    expect(loaded.node).toBeNull();
+    expect(loaded.loadFailure).toBe(thrown);
+    expect(loaded.diagnostics.map(d => d.code)).toEqual(['load_failed']);
+    const empty = lowerDoc(
+      input(card, {file: {file: 'Card.doc.mjs', doc: null}}),
+    );
+    expect(empty).toMatchObject({
+      node: null,
+      missing: true,
+      missingValue: null,
+    });
+    expect(empty.diagnostics.map(d => d.code)).toEqual(['missing_export']);
+    const overlaid = lowerDoc(
+      input(card, {
+        file: {file: 'Card.doc.mjs', doc: card, overlayError: thrown},
+      }),
+    );
+    expect(overlaid).toMatchObject({node: null, overlayFailure: thrown});
+    expect(overlaid.view).toBeUndefined();
+    expect(overlaid.diagnostics.map(d => d.code)).toEqual(['overlay_failed']);
+  });
+
+  it('keeps the parse failure first when the translation also breaks', () => {
+    const {failure, overlayFailure, diagnostics} = lowerDoc(
+      input(
+        {type: 'component', name: 'Card'},
+        {
+          lang: 'zh',
+          file: {
+            file: 'Card.doc.mjs',
+            doc: {type: 'component', name: 'Card'},
+            overlay: {
+              get props() {
+                throw new TypeError('bad translation');
+              },
+            },
+          },
+        },
+      ),
+    );
+    expect(/** @type {Error} */ (failure).message).toMatch(
+      /Card\.doc\.mjs is invalid/,
+    );
+    expect(overlayFailure).toBeInstanceOf(TypeError);
+    expect(diagnostics.map(d => d.code)).toEqual([
+      'invalid_doc',
+      'overlay_failed',
+    ]);
+  });
+
+  it('refuses a theme descriptor outside the themes root, as readers always did', () => {
+    const theme = {
+      type: 'theme',
+      name: 'ocean',
+      displayName: 'Ocean',
+      description: 'd',
+      maintained: true,
+    };
+    for (const root of ['components', 'hooks', 'self-docs']) {
+      const {failure} = lowerDoc(
+        input(theme, {root, label: '/x/Ocean.doc.mjs'}),
+      );
+      expect(/** @type {Error} */ (failure).message).toBe(
+        '/x/Ocean.doc.mjs has unsupported type "theme".',
+      );
+    }
+  });
+
+  it('hands readers the authored value, and only the node goes through JSON', () => {
+    const cyclic = /** @type {any} */ ({
+      ...card,
+      big: 10n,
+      when: new Date(0),
+      fn() {},
+    });
+    cyclic.self = cyclic;
+    cyclic.gone = undefined;
+    const {view, node, diagnostics} = lowerDoc(input(cyclic));
+    expect(view).toBe(cyclic);
+    expect(node).toBeNull();
+    expect(diagnostics.at(-1)?.code).toBe('not_json');
+    expect(diagnostics.at(-1)?.message).not.toMatch(/^\//);
+    const read = lowerDoc(input(cyclic), {check: false, node: false});
+    expect(read).toEqual({node: null, diagnostics: [], view: cyclic});
+  });
+
+  it('never puts a machine path in a diagnostic', () => {
+    const {diagnostics} = lowerDoc(
+      input(
+        {type: 'component', name: 'Card'},
+        {label: '/home/someone/kit/Card.doc.mjs'},
+      ),
+    );
+    expect(diagnostics[0].message).not.toContain('/home/someone');
+  });
+
+  it('refuses a value JSON cannot hold', () => {
+    const cyclic = /** @type {any} */ ({...card});
+    cyclic.self = cyclic;
+    for (const doc of [cyclic, {...card, big: 1n}]) {
+      const {node, diagnostics} = lowerDoc(input(doc));
+      expect(node).toBeNull();
+      expect(diagnostics.at(-1)?.code).toBe('not_json');
+    }
+  });
+
+  it("carries the parser's result only when asked to", () => {
+    const block = {
+      type: 'block',
+      name: 'Hero',
+      description: 'A block.',
+      extra: 1,
+    };
+    const authored = lowerDoc(input(block, {root: 'templates'}));
+    const parsed = lowerDoc(input(block, {root: 'templates', useParsed: true}));
+    expect(authored.node?.doc.extra).toBe(1);
+    expect(parsed.node?.doc).toEqual(
+      expect.objectContaining({type: 'block', name: 'Hero'}),
+    );
+  });
+});
+
+describe('diagnostics', () => {
+  it('fixes phase, severity, scope, and remediation per code', () => {
+    for (const [code, rule] of Object.entries(DIAGNOSTIC_CODES)) {
+      const d = diagnostic(code, {message: 'x'});
+      expect(d).toEqual({
+        code,
+        phase: rule.phase,
+        severity: rule.severity,
+        scope: rule.scope,
+        provider: null,
+        source: null,
+        field: null,
+        message: 'x',
+        remediation: rule.remediation,
+      });
+      expect(diagnosticProblem(d)).toBeNull();
+    }
+    expect(() => diagnostic('nope', {message: 'x'})).toThrow(/Unknown/);
+    for (const name of [
+      'toString',
+      'constructor',
+      '__proto__',
+      'hasOwnProperty',
+    ]) {
+      expect(() => diagnostic(name, {message: 'x'})).toThrow(/Unknown/);
+      expect(
+        diagnosticProblem({
+          ...diagnostic('invalid_doc', {message: 'x'}),
+          code: name,
+        }),
+      ).toMatch(/not a compiler diagnostic code/);
+    }
+  });
+
+  it('rejects a diagnostic a reader reinterpreted', () => {
+    const d = diagnostic('invalid_doc', {message: 'x'});
+    expect(diagnosticProblem({...d, severity: 'warning'})).toMatch(
+      /always has severity/,
+    );
+    expect(diagnosticProblem({...d, code: 'made_up'})).toMatch(
+      /not a compiler diagnostic code/,
+    );
+    expect(diagnosticProblem({...d, extra: 1})).toMatch(/unknown fields/);
+    expect(diagnosticProblem({...d, source: ''})).toMatch(/source/);
+    for (const source of [
+      '/tmp/x/Card.doc.mjs',
+      'C:\\x\\Card.doc.mjs',
+      '@acme/kit/../x',
+    ]) {
+      expect(diagnosticProblem({...d, source})).toMatch(
+        /not a location on one machine/,
+      );
+    }
+  });
+
+  it('sorts by source, then phase, code, field, and message', () => {
+    const at = (
+      /** @type {string} */ code,
+      /** @type {string|null} */ source,
+      field = null,
+    ) => diagnostic(code, {source, field, message: `${code} ${field}`});
+    const list = [
+      at('unresolved_reference', 'b/x', 'sections.b'),
+      at('invalid_doc', 'b/x'),
+      at('load_failed', 'b/x'),
+      at('unresolved_reference', 'b/x', 'sections.a'),
+      at('invalid_doc', null),
+      at('duplicate_id', 'a/x'),
+    ];
+    const sorted = sortDiagnostics(list);
+    expect(sorted.map(d => `${d.source}:${d.code}:${d.field}`)).toEqual([
+      'a/x:duplicate_id:null',
+      'b/x:load_failed:null',
+      'b/x:invalid_doc:null',
+      'b/x:unresolved_reference:sections.a',
+      'b/x:unresolved_reference:sections.b',
+      'null:invalid_doc:null',
+    ]);
+    expect(sortDiagnostics([...list].reverse())).toEqual(sorted);
+  });
+});
+
+describe('parseCompiledDocNode and parseCompiledDocsBundle', () => {
+  const node = () =>
+    /** @type {any} */ (structuredClone(lowerDoc(input(card)).node));
+  const bundle = () => ({
+    schemaVersion: COMPILED_DOC_SCHEMA_VERSION,
+    lang: null,
+    nodes: [node()],
+    diagnostics: [diagnostic('unresolved_reference', {message: 'x'})],
+  });
+
+  it('accepts a node of every kind and a bundle, as given', () => {
+    const value = bundle();
+    expect(parseCompiledDocsBundle(value)).toBe(value);
+    expect(COMPILED_DOC_KINDS).toHaveLength(10);
+    // A namespace doc, which the docs tree reads, lowers to a node too.
+    const namespace = {...node(), kind: 'namespace'};
+    expect(parseCompiledDocNode(namespace)).toBe(namespace);
+  });
+
+  it('names schema skew with its own diagnostic, before anything else', () => {
+    for (const parse of [parseCompiledDocNode, parseCompiledDocsBundle]) {
+      try {
+        parse({schemaVersion: 99, nope: true});
+        throw new Error('expected a throw');
+      } catch (error) {
+        expect(/** @type {any} */ (error).message).toMatch(
+          /schema version 99 is not supported/,
+        );
+        expect(/** @type {any} */ (error).diagnostic.code).toBe(
+          'unsupported_schema',
+        );
+      }
+    }
+  });
+
+  it.each([
+    [
+      'an unknown field',
+      (/** @type {any} */ n) => (n.extra = 1),
+      /unknown fields: extra/,
+    ],
+    [
+      'an unknown kind',
+      (/** @type {any} */ n) => (n.kind = 'workflow'),
+      /not a compiled doc kind/,
+    ],
+    [
+      'a machine path as provider',
+      (/** @type {any} */ n) => (n.provenance.provider = '/home/x'),
+      /not a machine path/,
+    ],
+    [
+      'a machine path as source',
+      (/** @type {any} */ n) => (n.provenance.source = 'C:\\x\\Card.doc.mjs'),
+      /not a machine path/,
+    ],
+    [
+      'a source that climbs out of its package',
+      (/** @type {any} */ n) => (n.provenance.source = '@acme/kit/../x'),
+      /not a machine path/,
+    ],
+    [
+      'a stage other than lowered',
+      (/** @type {any} */ n) => (n.stage = 'linked'),
+      /stage/,
+    ],
+    [
+      'a doc without a name',
+      (/** @type {any} */ n) => delete n.doc.name,
+      /doc with a name/,
+    ],
+    [
+      'a page node without a page doc',
+      (/** @type {any} */ n) => {
+        n.kind = 'page';
+        n.doc.type = 'block';
+      },
+      /a page node holds a page doc/,
+    ],
+    [
+      'a function in the doc',
+      (/** @type {any} */ n) => (n.doc.render = () => null),
+      /is not JSON/,
+    ],
+    [
+      'undefined in the doc',
+      (/** @type {any} */ n) => (n.doc.gone = undefined),
+      /undefined is not JSON/,
+    ],
+  ])('rejects %s', (_name, mutate, message) => {
+    const value = node();
+    mutate(value);
+    expect(() => parseCompiledDocNode(value)).toThrow(message);
+    try {
+      parseCompiledDocNode(value);
+    } catch (error) {
+      expect(/** @type {any} */ (error).diagnostic.code).toBe('invalid_bundle');
+    }
+  });
+
+  it('rejects a bundle with a duplicate id, a bad node, or a reinterpreted diagnostic', () => {
+    const twice = bundle();
+    twice.nodes.push(node());
+    expect(() => parseCompiledDocsBundle(twice)).toThrow(/appears twice/);
+    const bad = bundle();
+    bad.nodes[0].kind = 'nope';
+    expect(() => parseCompiledDocsBundle(bad)).toThrow(/nodes\[0\]\.kind/);
+    const reinterpreted = bundle();
+    reinterpreted.diagnostics[0] = {
+      ...reinterpreted.diagnostics[0],
+      severity: 'error',
+    };
+    expect(() => parseCompiledDocsBundle(reinterpreted)).toThrow(
+      /diagnostics\[0\]/,
+    );
+    expect(() => parseCompiledDocsBundle({...bundle(), extra: 1})).toThrow(
+      /unknown fields/,
+    );
+  });
+});

package/foundation/doc-compiler/overlays.d.mts

@@ -0,0 +1,37 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file Translation overlays for component and hook docs.
+ *
+ * @input An authored component or hook doc and the translation its module
+ *   exports for the reading language (`docsZh`, `docsDense`).
+ * @output The doc in that language: translated text laid over the authored
+ *   doc, never dropping a prop, param, or field the translation has not
+ *   caught up with.
+ * @position Used by ./compile.mjs when it lowers a component or hook doc, so
+ *   every reader sees one overlay rule. Reference topics overlay by section in
+ *   ./compile.mjs instead.
+ */
+/**
+ * The translation a doc module exports for `lang`, or null.
+ * @param {Record<string, any>} mod
+ * @param {string | null} lang
+ * @returns {any}
+ */
+export function translationFor(mod: Record<string, any>, lang: string | null): any;
+/**
+ * Lay a translation over an authored component or hook doc. A translation
+ * that carries props is a full translated doc, overlaid prop by prop; any other
+ * is a set of translated strings merged onto the doc.
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+export function overlayAuthoredDoc(docs: any, translation: any): any;
+/**
+ * @param {any} docs
+ * @param {any} translation
+ * @returns {any}
+ */
+export function mergeTranslation(docs: any, translation: any): any;