@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

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

@@ -1,687 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for the doc compiler: lowering, linking, the compiled-node
- * contract, the lenses, and the rule that readers go through the compiler.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import jscodeshift from 'jscodeshift';
-import {describe, expect, it} from 'vitest';
-import {parseDoc} from '../../authoring/doctypes/parse.mjs';
-import {
-  COMPILED_DOC_SCHEMA_VERSION,
-  linkReferenceTopic,
-  lowerReferenceTopic,
-} from './compile.mjs';
-import {parseCompiledReferenceNode} from './ir.mjs';
-import {detailView, indexView, readerSections, sectionView} from './lenses.mjs';
-
-const CLI_ROOT = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '../..',
-);
-
-/**
- * @param {string} name
- * @param {any[]} sections
- * @param {object} [fields]
- */
-function authored(name, sections, fields = {}) {
-  return parseDoc(
-    {
-      name,
-      title: `${name} title`,
-      description: `About ${name}.`,
-      ...fields,
-      sections,
-    },
-    `${name}.doc.mjs`,
-  );
-}
-
-/** @param {any} doc @param {object} [more] */
-const file = (doc, more = {}) => ({file: `${doc.name}.doc.mjs`, doc, ...more});
-
-/**
- * @param {any} base
- * @param {any[]} [extensions]
- * @param {string | null} [lang]
- */
-const input = (base, extensions = [], lang = null) => ({
-  id: base.doc?.name ?? 'demo',
-  provider: '@acme/base',
-  replaces: null,
-  lang,
-  base,
-  extensions,
-});
-
-const prose = (/** @type {string} */ text) => ({type: 'prose', text});
-
-const demo = () =>
-  authored('demo', [
-    {title: 'Quick Start', content: [prose('Start here.')]},
-    {title: 'Props', content: [prose('Every prop.')]},
-  ]);
-
-/** @param {string} name @param {string} text */
-const extension = (name, text) => ({
-  ...file(
-    authored(name, [{title: 'Quick Start', content: [prose(text)]}], {
-      extends: 'demo',
-    }),
-  ),
-  provider: `@acme/${name}`,
-});
-
-describe('lowerReferenceTopic', () => {
-  it('lays the overlay over authored titles and keys every section', () => {
-    const overlay = {
-      description: '演示。',
-      sections: [
-        {
-          section: 'Quick Start',
-          title: '快速开始',
-          content: [prose('从这里开始。')],
-        },
-      ],
-    };
-    const node = lowerReferenceTopic(input(file(demo(), {overlay}), [], 'zh'));
-    expect(node.schemaVersion).toBe(COMPILED_DOC_SCHEMA_VERSION);
-    expect(node.stage).toBe('lowered');
-    expect(node.doc.description).toBe('演示。');
-    expect(
-      node.doc.sections.map((/** @type {any} */ s) => [s.id, s.title]),
-    ).toEqual([
-      ['quick-start', '快速开始'],
-      ['props', 'Props'],
-    ]);
-    expect(node.sourceTitles).toEqual({
-      'quick-start': 'Quick Start',
-      props: 'Props',
-    });
-    expect(parseCompiledReferenceNode(node)).toBe(node);
-  });
-
-  it('merges extensions by key in order and names every provider', () => {
-    const acme = authored(
-      'demo-acme',
-      [
-        {title: 'Quick Start', content: [prose('Acme start.')]},
-        {title: 'Acme Palettes', content: [prose('Palettes.')]},
-      ],
-      {extends: 'demo'},
-    );
-    const node = lowerReferenceTopic(
-      input(file(demo()), [{...file(acme), provider: '@acme/ext'}]),
-    );
-    expect(node.doc.sections.map((/** @type {any} */ s) => s.id)).toEqual([
-      'quick-start',
-      'props',
-      'acme-palettes',
-    ]);
-    expect(node.doc.sections[0].content).toEqual([prose('Acme start.')]);
-    expect(node.provenance).toEqual({
-      provider: '@acme/base',
-      replaces: null,
-      extensions: ['@acme/ext'],
-    });
-  });
-
-  it('applies extensions in configuration order, so the last one wins', () => {
-    const node = lowerReferenceTopic(
-      input(file(demo()), [
-        extension('one', 'First.'),
-        extension('two', 'Second.'),
-      ]),
-    );
-    expect(node.doc.sections[0].content).toEqual([prose('Second.')]);
-    expect(node.provenance.extensions).toEqual(['@acme/one', '@acme/two']);
-  });
-
-  it('reports problems in the order a reader meets them', () => {
-    const broken = new Error('extension failed to load');
-    const invalidBase = file(
-      authored('demo', [{title: 'Only', content: [prose('x')]}]),
-    );
-    invalidBase.doc = {...invalidBase.doc, title: ''};
-    expect(() =>
-      lowerReferenceTopic(
-        input(invalidBase, [
-          {file: 'ext.doc.mjs', error: broken, provider: '@acme/ext'},
-        ]),
-      ),
-    ).toThrow(/demo\.doc\.mjs is invalid/);
-
-    const overlayError = new Error('overlay failed to load');
-    expect(() =>
-      lowerReferenceTopic(input(file(demo(), {overlayError}), [], 'zh')),
-    ).toThrow(overlayError);
-
-    expect(() =>
-      lowerReferenceTopic(
-        input(file(demo()), [
-          {file: 'ext.doc.mjs', error: broken, provider: '@acme/ext'},
-        ]),
-      ),
-    ).toThrow(broken);
-  });
-
-  it('carries authored values the way JSON does', () => {
-    const doc = {
-      ...demo(),
-      when: new Date(0),
-      render: () => 1,
-      note: undefined,
-    };
-    doc.sections = [
-      {...doc.sections[0], previewType: undefined},
-      doc.sections[1],
-    ];
-    const node = lowerReferenceTopic(input(file(doc)));
-    expect(node.doc.when).toBe('1970-01-01T00:00:00.000Z');
-    expect('render' in node.doc).toBe(false);
-    expect('note' in node.doc).toBe(false);
-    expect('previewType' in node.doc.sections[0]).toBe(false);
-    expect(parseCompiledReferenceNode(node)).toBe(node);
-  });
-});
-
-describe('linking and lenses', () => {
-  const tokens = () =>
-    lowerReferenceTopic(
-      input(
-        file(
-          authored('tokens', [
-            {
-              title: 'Spacing',
-              previewType: 'spacing-bar',
-              content: [
-                {type: 'table', headers: ['Token'], rows: [['--space-1']]},
-              ],
-            },
-          ]),
-          {overlay: {sections: [{section: 'Spacing', title: '间距'}]}},
-        ),
-        [],
-        'zh',
-      ),
-    );
-  const guide = () =>
-    lowerReferenceTopic(
-      input(
-        file(
-          authored('guide', [
-            {
-              title: 'By Title',
-              content: [
-                {type: 'token-ref', topic: 'tokens', section: 'SPACING'},
-              ],
-            },
-            {
-              title: 'By Key',
-              content: [
-                {type: 'token-ref', topic: 'tokens', section: 'spacing'},
-              ],
-            },
-            {
-              title: 'No Topic',
-              content: [{type: 'token-ref', topic: 'nope', section: 'x'}],
-            },
-            {
-              title: 'No Section',
-              content: [{type: 'token-ref', topic: 'tokens', section: 'nope'}],
-            },
-          ]),
-        ),
-        [],
-        'zh',
-      ),
-    );
-  const targets = async (/** @type {string} */ name) =>
-    name === 'tokens' ? tokens() : null;
-
-  it('resolves a reference by key or authored title in the reading language', async () => {
-    const linked = await linkReferenceTopic(guide(), targets);
-    expect(linked.stage).toBe('linked');
-    expect(parseCompiledReferenceNode(linked)).toBe(linked);
-    const [byTitle, byKey, noTopic, noSection] = detailView(linked).sections;
-    for (const section of [byTitle, byKey]) {
-      expect(section.content).toEqual([
-        {type: 'table', headers: ['Token'], rows: [['--space-1']]},
-      ]);
-      expect(section.previewType).toBe('spacing-bar');
-    }
-    expect(noTopic.content).toEqual([
-      prose('[token-ref: unknown topic "nope"]'),
-    ]);
-    expect(noSection.content).toEqual([
-      prose('[token-ref: section "nope" not found in "tokens"]'),
-    ]);
-  });
-
-  it('takes the preview type of the last reference that has one', async () => {
-    const palette = lowerReferenceTopic(
-      input(
-        file(
-          authored('palette', [
-            {
-              title: 'Spacing',
-              previewType: 'spacing-bar',
-              content: [{type: 'table', headers: ['S'], rows: [['1']]}],
-            },
-            {title: 'Plain', content: [prose('No preview.')]},
-            {
-              title: 'Radius',
-              previewType: 'radius-box',
-              content: [{type: 'table', headers: ['R'], rows: [['2']]}],
-            },
-          ]),
-        ),
-      ),
-    );
-    const both = lowerReferenceTopic(
-      input(
-        file(
-          authored('guide', [
-            {
-              title: 'Both',
-              content: ['spacing', 'plain', 'radius'].map(section => ({
-                type: 'token-ref',
-                topic: 'palette',
-                section,
-              })),
-            },
-          ]),
-        ),
-      ),
-    );
-    const [section] = detailView(
-      await linkReferenceTopic(both, async () => palette),
-    ).sections;
-    expect(section.previewType).toBe('radius-box');
-    expect(Object.keys(section)).toEqual([
-      'title',
-      'content',
-      'id',
-      'previewType',
-    ]);
-    expect(section.content.map((/** @type {any} */ b) => b.type)).toEqual([
-      'table',
-      'prose',
-      'table',
-    ]);
-  });
-
-  it('gives every inlined copy of a referenced section its own blocks', async () => {
-    const shared = tokens();
-    const sameTarget = async (/** @type {string} */ name) =>
-      name === 'tokens' ? shared : null;
-    const twice = lowerReferenceTopic(
-      input(
-        file(
-          authored('guide', [
-            {
-              title: 'First',
-              content: [
-                {type: 'token-ref', topic: 'tokens', section: 'spacing'},
-              ],
-            },
-            {
-              title: 'Second',
-              content: [
-                {type: 'token-ref', topic: 'tokens', section: 'spacing'},
-              ],
-            },
-          ]),
-        ),
-        [],
-        'zh',
-      ),
-    );
-    const [first, second] = detailView(
-      await linkReferenceTopic(twice, sameTarget),
-    ).sections;
-    expect(first.content).toEqual(second.content);
-    expect(first.content[0]).not.toBe(second.content[0]);
-    expect(first.content[0]).not.toBe(shared.doc.sections[0].content[0]);
-  });
-
-  it('hands out views that share nothing with the node', async () => {
-    const lowered = lowerReferenceTopic(
-      input(file({...demo(), extra: {tags: ['a']}})),
-    );
-    // Authored sections hold only scalars besides content; a node read back
-    // from JSON may hold more, and the lens copies that too.
-    lowered.doc.sections[0] = {
-      ...lowered.doc.sections[0],
-      meta: {level: 1},
-      content: [{type: 'table', headers: ['A'], rows: [['1']]}],
-    };
-    const node = await linkReferenceTopic(lowered, async () => null);
-    const view = detailView(node);
-    expect(JSON.stringify(view)).toBe(JSON.stringify(node.doc));
-    expect(view.extra).not.toBe(node.doc.extra);
-    expect(view.sections[0].meta).not.toBe(node.doc.sections[0].meta);
-    expect(view.sections[0].content[0]).not.toBe(
-      node.doc.sections[0].content[0],
-    );
-    expect(view.sections[0].content[0].rows).not.toBe(
-      node.doc.sections[0].content[0].rows,
-    );
-  });
-
-  it('reads the index and section lookups without linking', () => {
-    const node = guide();
-    expect(indexView(node).sections.map(s => s.id)).toEqual([
-      'by-title',
-      'by-key',
-      'no-topic',
-      'no-section',
-    ]);
-    expect(readerSections(node).map(s => s.title)).toEqual([
-      'By Title',
-      'By Key',
-      'No Topic',
-      'No Section',
-    ]);
-    expect(() => sectionView(node, node.doc.sections[0])).toThrow(
-      /before it was linked/,
-    );
-    expect(() => detailView(node)).toThrow(/must be linked/);
-  });
-});
-
-describe('parseCompiledReferenceNode', () => {
-  const node = () => lowerReferenceTopic(input(file(demo())));
-  const linked = async () =>
-    linkReferenceTopic(
-      lowerReferenceTopic(
-        input(
-          file(
-            authored('guide', [
-              {
-                title: 'Ref',
-                content: [{type: 'token-ref', topic: 'nope', section: 'x'}],
-              },
-            ]),
-          ),
-        ),
-      ),
-      async () => null,
-    );
-
-  it('returns a valid node as given', () => {
-    const value = JSON.parse(JSON.stringify(node()));
-    expect(parseCompiledReferenceNode(value)).toBe(value);
-  });
-
-  it('names an unsupported schema version', () => {
-    expect(() =>
-      parseCompiledReferenceNode({...node(), schemaVersion: 99}),
-    ).toThrow(/schema version 99 is not supported/);
-  });
-
-  it('rejects a node that lost an authored title or duplicated a key', () => {
-    expect(() =>
-      parseCompiledReferenceNode({...node(), sourceTitles: {}}),
-    ).toThrow(/no authored title for section "quick-start"/);
-    const twice = node();
-    twice.doc.sections[1] = {...twice.doc.sections[1], id: 'quick-start'};
-    expect(() => parseCompiledReferenceNode(twice)).toThrow(
-      /two sections have the key/,
-    );
-  });
-
-  it.each([
-    [
-      'a function in a block',
-      (/** @type {any} */ n) => {
-        n.doc.sections[0].content[0].text = () => 1;
-      },
-      /a function is not JSON/,
-    ],
-    [
-      'a Date',
-      (/** @type {any} */ n) => {
-        n.doc.when = new Date(0);
-      },
-      /a Date is not JSON/,
-    ],
-    [
-      'an undefined value',
-      (/** @type {any} */ n) => {
-        n.doc.note = undefined;
-      },
-      /undefined is not JSON/,
-    ],
-    [
-      'a symbol key',
-      (/** @type {any} */ n) => {
-        n.doc[Symbol('x')] = 1;
-      },
-      /symbol keys/,
-    ],
-    [
-      'a cycle',
-      (/** @type {any} */ n) => {
-        n.doc.self = n.doc;
-      },
-      /refers back to itself/,
-    ],
-    [
-      'a block that is a number',
-      (/** @type {any} */ n) => {
-        n.doc.sections[0].content.push(42);
-      },
-      /expected a block with a type/,
-    ],
-    [
-      'a null block',
-      (/** @type {any} */ n) => {
-        n.doc.sections[0].content.push(null);
-      },
-      /expected a block with a type/,
-    ],
-    [
-      'a block with no type',
-      (/** @type {any} */ n) => {
-        n.doc.sections[0].content.push({text: 'x'});
-      },
-      /expected a block with a type/,
-    ],
-    [
-      'a path in the provenance',
-      (/** @type {any} */ n) => {
-        n.provenance.provider = '/home/me/acme';
-      },
-      /naming packages, not paths/,
-    ],
-    [
-      'a resolution on a lowered node',
-      (/** @type {any} */ n) => {
-        n.doc.sections[0].content.push({
-          type: 'token-ref',
-          topic: 't',
-          section: 's',
-          resolved: {status: 'unknown-topic'},
-        });
-      },
-      /a lowered node carries no resolution/,
-    ],
-  ])('rejects %s', (_, mutate, message) => {
-    const value = node();
-    mutate(value);
-    expect(() => parseCompiledReferenceNode(value)).toThrow(message);
-  });
-
-  it('rejects a linked node with an unresolved or malformed reference', async () => {
-    const unresolved = await linked();
-    delete unresolved.doc.sections[0].content[0].resolved;
-    expect(() => parseCompiledReferenceNode(unresolved)).toThrow(
-      /a linked node resolves every reference/,
-    );
-    const malformed = await linked();
-    malformed.doc.sections[0].content[0] = {
-      ...malformed.doc.sections[0].content[0],
-      resolved: {status: 'maybe'},
-    };
-    expect(() => parseCompiledReferenceNode(malformed)).toThrow(
-      /token reference to "nope"/,
-    );
-  });
-});
-
-describe('readers go through the compiler', () => {
-  /** Compiler functions, by module. ESLint enforces the same list. */
-  const RESTRICTED = {
-    'foundation/discovery/docs-discovery.mjs': ['mergeTopic'],
-    'foundation/discovery/docs-section-key.mjs': ['withSectionKeys'],
-    'foundation/doc-compiler/compile.mjs': [
-      'lowerReferenceTopic',
-      'linkReferenceTopic',
-      'linkReferenceSection',
-    ],
-  };
-  /** The docs adapter and leaves drive the compiler; nothing else does. */
-  const ALLOWED = {
-    'api/docs/_adapter.mjs': ['lowerReferenceTopic', 'linkReferenceTopic'],
-    'api/docs/detail/detail.mjs': ['linkReferenceTopic'],
-    'api/docs/detail/section/section.mjs': ['linkReferenceSection'],
-  };
-  const j = jscodeshift.withParser('babel');
-
-  /**
-   * Every import of a compiler function that `rel` may not make: named under
-   * any alias, namespace, re-export, and dynamic import().
-   * @param {string} source
-   * @param {string} rel path under packages/cli
-   * @returns {string[]}
-   */
-  function forbiddenImports(source, rel) {
-    /** @type {string[]} */
-    const allowed = ALLOWED[/** @type {keyof typeof ALLOWED} */ (rel)] ?? [];
-    /** @type {string[]} */
-    const found = [];
-    /** @param {unknown} specifier @returns {string[]} */
-    const bannedFrom = specifier => {
-      if (typeof specifier !== 'string' || !specifier.startsWith('.')) {
-        return [];
-      }
-      const target = path.posix.normalize(
-        path.posix.join(path.posix.dirname(rel), specifier),
-      );
-      const names =
-        RESTRICTED[/** @type {keyof typeof RESTRICTED} */ (target)] ?? [];
-      return names.filter(name => !allowed.includes(name));
-    };
-    /** @param {any} node */
-    const checkStatic = node => {
-      const banned = bannedFrom(node.source?.value);
-      if (banned.length === 0) return;
-      if (node.type === 'ExportAllDeclaration') {
-        found.push(`${rel}: export * from ${node.source.value}`);
-        return;
-      }
-      for (const spec of node.specifiers ?? []) {
-        const name =
-          spec.type === 'ImportNamespaceSpecifier'
-            ? '*'
-            : spec.type === 'ImportDefaultSpecifier'
-              ? 'default'
-              : (spec.imported ?? spec.local)?.name;
-        if (name === '*' || name === 'default' || banned.includes(name)) {
-          found.push(`${rel}: ${name} from ${node.source.value}`);
-        }
-      }
-    };
-    /** @param {any} node */
-    const checkDynamic = node => {
-      const specifier = node.source?.value ?? node.arguments?.[0]?.value;
-      if (bannedFrom(specifier).length > 0) {
-        found.push(`${rel}: import(${specifier})`);
-      }
-    };
-    const root = j(source);
-    root.find(j.ImportDeclaration).forEach(p => checkStatic(p.node));
-    root
-      .find(j.ExportNamedDeclaration)
-      .forEach(p => p.node.source && checkStatic(p.node));
-    root.find(j.ExportAllDeclaration).forEach(p => checkStatic(p.node));
-    root.find(j.ImportExpression).forEach(p => checkDynamic(p.node));
-    root
-      .find(j.CallExpression, {callee: {type: 'Import'}})
-      .forEach(p => checkDynamic(p.node));
-    return found;
-  }
-
-  /** @param {string} dir @returns {string[]} */
-  const sources = dir =>
-    fs.readdirSync(dir, {withFileTypes: true}).flatMap(entry => {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        return entry.name === 'node_modules' ? [] : sources(full);
-      }
-      return entry.name.endsWith('.mjs') && !entry.name.endsWith('.test.mjs')
-        ? [full]
-        : [];
-    });
-
-  it('keeps compiler functions out of api/ and clients/', () => {
-    const offenders = ['api', 'clients']
-      .flatMap(dir => sources(path.join(CLI_ROOT, dir)))
-      .flatMap(full =>
-        forbiddenImports(
-          fs.readFileSync(full, 'utf8'),
-          path.relative(CLI_ROOT, full).split(path.sep).join('/'),
-        ),
-      );
-    expect(offenders).toEqual([]);
-  });
-
-  it('catches every way around the rule', () => {
-    const doctor = 'api/doctor/doctor.mjs';
-    const discovery = '../../foundation/discovery/docs-discovery.mjs';
-    expect(
-      forbiddenImports(
-        `import {mergeTopic as merge} from '${discovery}'; merge({}, {});`,
-        doctor,
-      ),
-    ).toHaveLength(1);
-    expect(
-      forbiddenImports(
-        `import * as dd from '${discovery}'; dd['mergeTopic']({}, {});`,
-        doctor,
-      ),
-    ).toHaveLength(1);
-    expect(
-      forbiddenImports(
-        `async function f() { const dd = await import('${discovery}'); dd.mergeTopic.call(null, {}, {}); }`,
-        doctor,
-      ),
-    ).toHaveLength(1);
-    expect(
-      forbiddenImports(
-        `export {withSectionKeys} from '../../foundation/discovery/docs-section-key.mjs';`,
-        doctor,
-      ),
-    ).toHaveLength(1);
-    expect(
-      forbiddenImports(`import {DocsCatalog} from '${discovery}';`, doctor),
-    ).toEqual([]);
-    const leaf = 'api/docs/detail/detail.mjs';
-    const compiler = '../../../foundation/doc-compiler/compile.mjs';
-    expect(
-      forbiddenImports(`import {linkReferenceTopic} from '${compiler}';`, leaf),
-    ).toEqual([]);
-    expect(
-      forbiddenImports(
-        `import {lowerReferenceTopic} from '${compiler}';`,
-        leaf,
-      ),
-    ).toHaveLength(1);
-  });
-});

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

@@ -1,9 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * Validate a compiled reference node.
- * @param {unknown} value
- * @returns {import('./compile.mjs').CompiledReferenceNode}
- */
-export function parseCompiledReferenceNode(value: unknown): import("./compile.mjs").CompiledReferenceNode;