@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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

@@ -0,0 +1,313 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file readDocView and the loaders built on it: every component and hook read
+ *   is the authored doc, compiled losslessly, and each reader keeps its own
+ *   strictness.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {Project} from '../config/project.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {loadComponentDoc, loadDocs} from '../discovery/component-loader.mjs';
+import {compileDocFile, readDocView} from './read.mjs';
+import {collectDocInputs} from './inputs.mjs';
+
+const REPO_ROOT = path.resolve(CLI_ROOT, '..', '..');
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doc-read-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * @param {string} name
+ * @param {string} text
+ */
+function write(name, text) {
+  const file = path.join(tmpDir, name);
+  fs.writeFileSync(file, text);
+  return file;
+}
+
+/** Drop what JSON drops, keep key order: the compiled form of a value. */
+const asJson = (/** @type {unknown} */ value) =>
+  JSON.parse(JSON.stringify(value));
+
+describe('component and hook reads over what this repo ships', () => {
+  it('are the authored docs, compiled without loss', async () => {
+    const dir = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-doc-read-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"consumer"}');
+      const {inputs} = await collectDocInputs(await Project.load(dir));
+      const docs = inputs.filter(
+        input => input.root === 'components' || input.root === 'hooks',
+      );
+      expect(docs.length).toBeGreaterThan(200);
+      for (const input of docs) {
+        const mod = await import(pathToFileURL(input.file).href);
+        const authored = mod.default ?? mod.docs;
+        const root = /** @type {'components' | 'hooks'} */ (input.root);
+        // Byte-for-byte what JSON output has always printed for the doc.
+        expect(JSON.stringify(await loadDocs(input.file, {root}))).toBe(
+          JSON.stringify(authored),
+        );
+        // A checked load passes every shipped doc.
+        await expect(loadComponentDoc(input.file, {root})).resolves.toEqual(
+          asJson(authored),
+        );
+      }
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  }, 180_000);
+});
+
+describe('readDocView', () => {
+  const card =
+    "export default {type: 'component', name: 'Card', displayName: 'Card', usage: {description: 'A card.'}, props: []};\n";
+
+  it('freezes the node a whole-project compile collects', async () => {
+    const file = write('Card.doc.mjs', card);
+    const {node} = await compileDocFile(
+      file,
+      {root: 'components', check: true},
+      {node: true},
+    );
+    expect(node).not.toBeNull();
+    expect(Object.isFrozen(node)).toBe(true);
+    expect(Object.isFrozen(node?.doc.props)).toBe(true);
+  });
+
+  it("keeps each reader's strictness for a doc that fails its parser", async () => {
+    const file = write(
+      'Bad.doc.mjs',
+      "export default {type: 'component', name: 'Bad'};\n",
+    );
+    await expect(loadDocs(file)).resolves.toEqual({
+      type: 'component',
+      name: 'Bad',
+    });
+    await expect(loadComponentDoc(file)).rejects.toThrow(`${file} is invalid`);
+  });
+
+  it('passes on what a file throws when it is imported, unchanged', async () => {
+    const file = write('Throws.doc.mjs', "throw new RangeError('no way');\n");
+    for (const read of [loadDocs, loadComponentDoc]) {
+      await expect(read(file)).rejects.toThrow(RangeError);
+      await expect(read(file)).rejects.toThrow('no way');
+    }
+  });
+
+  it("reads a file with no doc as undefined, or as its parser's error when checked", async () => {
+    const file = write('Empty.doc.mjs', 'export const unrelated = 1;\n');
+    await expect(loadDocs(file)).resolves.toBeUndefined();
+    await expect(loadComponentDoc(file)).rejects.toThrow(`${file} is invalid`);
+  });
+
+  it('applies the translation a module exports for the reading language', async () => {
+    const file = write(
+      'Card.doc.mjs',
+      card + "export const docsZh = {usage: {description: '卡片。'}};\n",
+    );
+    expect((await loadDocs(file, {zh: true})).usage.description).toBe('卡片。');
+    expect((await loadDocs(file, {lang: 'zh'})).usage.description).toBe(
+      '卡片。',
+    );
+    expect((await loadDocs(file)).usage.description).toBe('A card.');
+    expect((await loadDocs(file, {dense: true})).usage.description).toBe(
+      'A card.',
+    );
+  });
+
+  it('reads a narrower set of exports when a reader always has', async () => {
+    const file = write(
+      'Both.doc.mjs',
+      card +
+        "export const docs = {name: 'Legacy', description: 'Old.', props: []};\n",
+    );
+    expect((await readDocView(file, {root: 'components'})).name).toBe('Card');
+    expect(
+      (await readDocView(file, {root: 'components', exports: ['docs']})).name,
+    ).toBe('Legacy');
+  });
+
+  it('reads each file once per process, and retries a file that failed to load', async () => {
+    const file = write('Card.doc.mjs', card);
+    const before = await compileDocFile(file, {root: 'components'});
+    expect(await compileDocFile(file, {root: 'components'})).toBe(before);
+    const broken = write('Broken.doc.mjs', 'export default {;\n');
+    const failed = await compileDocFile(broken, {root: 'components'});
+    expect(failed.loadFailure).toBeInstanceOf(Error);
+    expect(await compileDocFile(broken, {root: 'components'})).not.toBe(failed);
+  });
+
+  it('prints what the module holds: no JSON anywhere a reader looks', async () => {
+    const file = write(
+      'Odd.doc.mjs',
+      `const doc = {
+  type: 'component', name: 'Odd', displayName: 'Odd', usage: {description: 'd'},
+  props: undefined, big: 10n, when: new Date(0), limit: Infinity,
+  examples: [{title: 'x', code() { return 1; }}],
+  get lazy() { throw new Error('never read'); },
+};
+doc.self = doc;
+export default doc;
+`,
+    );
+    const view = await loadDocs(file);
+    expect(Object.keys(view)).toContain('props');
+    expect(view.props).toBeUndefined();
+    expect(view.big).toBe(10n);
+    expect(view.when).toBeInstanceOf(Date);
+    expect(view.limit).toBe(Infinity);
+    expect(typeof view.examples[0].code).toBe('function');
+    expect(view.self).toBe(view);
+    expect(() => view.lazy).toThrow('never read');
+    // A checked read of a valid doc with odd values is no different.
+    const ok = write(
+      'Big.doc.mjs',
+      "export default {type: 'component', name: 'Big', displayName: 'Big', usage: {description: 'd'}, props: [], playground: {seed: 10n}};\n",
+    );
+    expect((await loadComponentDoc(ok)).playground.seed).toBe(10n);
+  });
+
+  it("hands readers the module's own doc, as main always did", async () => {
+    const file = write(
+      'Deep.doc.mjs',
+      `let deep = {};
+const root = deep;
+for (let i = 0; i < 5000; i++) deep = deep.next = {};
+const doc = new Proxy(
+  {type: 'component', name: 'Deep', displayName: 'Deep', usage: {description: 'd'}, props: [], root},
+  {get: (target, key) => (key === 'displayName' ? 'From the proxy' : target[key])},
+);
+export default doc;
+`,
+    );
+    const mod = await import(pathToFileURL(file).href);
+    const view = await loadDocs(file);
+    expect(view).toBe(mod.default);
+    expect(view.displayName).toBe('From the proxy');
+    expect(await loadComponentDoc(file)).toBe(mod.default);
+  });
+
+  it('translates and checks afresh on every read, as main did', async () => {
+    const file = write(
+      'Counted.doc.mjs',
+      `let reads = 0;
+export default {
+  type: 'component', name: 'Counted', displayName: 'Counted', props: [],
+  get usage() { reads += 1; return {description: 'read ' + reads}; },
+};
+export const docsZh = {get props() { throw new TypeError('bad translation'); }};
+`,
+    );
+    const first = await loadDocs(file, {lang: 'zh'}).catch(error => error);
+    const second = await loadDocs(file, {lang: 'zh'}).catch(error => error);
+    expect(first).toBeInstanceOf(TypeError);
+    expect(second).not.toBe(first);
+    const template = write(
+      'Block.doc.mjs',
+      "export default {type: 'block', name: 'Block', description: 'd', componentsUsed: ['A']};\n",
+    );
+    const read = () =>
+      readDocView(template, {
+        root: 'templates',
+        exports: ['default'],
+        strict: true,
+        value: 'parsed',
+      });
+    const one = await read();
+    one.componentsUsed.push('mutated');
+    expect((await read()).componentsUsed).toEqual(['A']);
+  });
+
+  it('treats any thrown value as a failure, undefined included, as main did', async () => {
+    const strict = write(
+      'ThrowsUndefined.doc.mjs',
+      "export default {type: 'component', name: 'ThrowsUndefined', displayName: 'T', props: [], get usage() { throw undefined; }};\n",
+    );
+    await expect(loadComponentDoc(strict)).rejects.toBeUndefined();
+    const translated = write(
+      'ZhUndefined.doc.mjs',
+      "export default {type: 'component', name: 'ZhUndefined', displayName: 'Z', props: [], usage: {description: 'd'}};\nexport const docsZh = {get usage() { throw undefined; }};\n",
+    );
+    await expect(loadDocs(translated, {lang: 'zh'})).rejects.toBeUndefined();
+    const imported = write('ImportUndefined.doc.mjs', 'throw undefined;\n');
+    await expect(loadDocs(imported)).rejects.toBeUndefined();
+    const bare = write(
+      'NullProto.doc.mjs',
+      'const e = Object.create(null);\ne.tag = 1;\nthrow e;\n',
+    );
+    const thrown = await loadDocs(bare).catch(error => error);
+    expect(Object.getPrototypeOf(thrown)).toBeNull();
+    expect(thrown.tag).toBe(1);
+  });
+
+  it('never lets a message that is not a path break a read', async () => {
+    const file = write(
+      'Odd.doc.mjs',
+      "throw new Error('Could not read file:///tmp/data/100%-coverage.json');\n",
+    );
+    await expect(loadDocs(file)).rejects.toThrow('100%-coverage.json');
+    const empty = write('Empty.doc.mjs', "throw new Error('');\n");
+    const {diagnostics} = await compileDocFile(empty, {root: 'components'});
+    expect(diagnostics[0].message).not.toBe('');
+  });
+
+  it('reads an empty export as that value, and checks it as that value', async () => {
+    const file = write('Null.doc.mjs', 'export default null;\n');
+    await expect(
+      readDocView(file, {root: 'templates', exports: ['default']}),
+    ).resolves.toBeNull();
+    await expect(
+      readDocView(file, {
+        root: 'templates',
+        exports: ['default'],
+        strict: true,
+        label: 'Template "t"',
+      }),
+    ).rejects.toThrow(/received null/);
+  });
+
+  it('keeps the unchecked readers on a plain import', () => {
+    // Outside vitest's own loader: a plain import cannot strip types under
+    // node_modules, and the checked loader (jiti) can, as on main.
+    const dir = path.join(tmpDir, 'node_modules', 'kit');
+    fs.mkdirSync(dir, {recursive: true});
+    const file = path.join(dir, 'Typed.doc.ts');
+    fs.writeFileSync(
+      file,
+      "export default {name: 'Typed'} as {name: string};\n",
+    );
+    const loader = path.join(
+      CLI_ROOT,
+      'foundation/discovery/component-loader.mjs',
+    );
+    const run = (/** @type {string} */ call) =>
+      spawnSync(
+        process.execPath,
+        [
+          '--input-type=module',
+          '-e',
+          `const m = await import(${JSON.stringify(pathToFileURL(loader).href)});
+try { const d = await m.${call}(${JSON.stringify(file)}); console.log('ok', d.name); }
+catch (e) { console.log('threw', e.message.split('\\n')[0]); }`,
+        ],
+        {encoding: 'utf8'},
+      ).stdout.trim();
+    expect(run('loadDocs')).toMatch(/^threw .*node_modules/);
+    expect(run('loadComponentDoc')).toMatch(/^(ok Typed|threw .*is invalid)/);
+  });
+});

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

@@ -0,0 +1,33 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Where a file ships: its package's name and its path inside that package.
+ * Never a location on this machine: a file outside any package is named by
+ * its folder and file name.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+export function packageSource(file: string): string;
+/**
+ * The name of the package a file ships in; for a package.json with no name,
+ * its folder's name; outside any package, `unknown`.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+export function packageOf(file: string): string;
+/**
+ * Replace every absolute path in a message with where that file ships, so a
+ * diagnostic never carries a location on this machine.
+ * @param {string} message
+ * @returns {string}
+ */
+export function scrubPaths(message: string): string;
+/**
+ * The nearest package a directory belongs to: the nearest package.json that
+ * names a package, else the nearest package.json at all (named by its folder).
+ */
+export type PackageRoot = {
+    dir: string;
+    name: string;
+};

package/foundation/doc-compiler/source.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Where an authored file ships: its package and its path inside it.
+ *
+ * @input An absolute file path.
+ * @output `<package name>/<path inside the package>`, found by walking up to
+ *   the nearest package.json that names a package.
+ * @position Used by the doc compiler for provenance and diagnostics, so no
+ *   compiled node or diagnostic carries a machine-specific path.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The nearest package a directory belongs to: the nearest package.json that
+ * names a package, else the nearest package.json at all (named by its folder).
+ * @typedef {{dir: string, name: string}} PackageRoot
+ */
+
+/** @type {Map<string, {named: PackageRoot | null, any: PackageRoot | null}>} */
+const packageRoots = new Map();
+
+/**
+ * Where a file ships: its package's name and its path inside that package.
+ * Never a location on this machine: a file outside any package is named by
+ * its folder and file name.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+export function packageSource(file) {
+  const {named, any} = packageRootsOf(path.dirname(path.resolve(file)));
+  const root = named ?? any;
+  if (root == null) {
+    return `${folderName(path.dirname(path.resolve(file)))}/${path.basename(file)}`;
+  }
+  const inside = path
+    .relative(root.dir, path.resolve(file))
+    .split(path.sep)
+    .join('/');
+  return `${root.name}/${inside}`;
+}
+
+/**
+ * The name of the package a file ships in; for a package.json with no name,
+ * its folder's name; outside any package, `unknown`.
+ * @param {string} file absolute path
+ * @returns {string}
+ */
+export function packageOf(file) {
+  const {named, any} = packageRootsOf(path.dirname(path.resolve(file)));
+  return (named ?? any)?.name ?? 'unknown';
+}
+
+/**
+ * Replace every absolute path in a message with where that file ships, so a
+ * diagnostic never carries a location on this machine.
+ * @param {string} message
+ * @returns {string}
+ */
+export function scrubPaths(message) {
+  return message
+    .replace(/file:\/\/(\/[^\s'"`)]+)/gu, (_, file) =>
+      packageSource(safeDecode(file)),
+    )
+    .replace(/(?<![\w:/.-])((?:\/[^\s'"`:()/]+)+)/gu, (_, file) =>
+      packageSource(file),
+    )
+    .replace(/(?<![\w])([A-Za-z]:\\[^\s'"`:()]+)/gu, (_, file) =>
+      packageSource(file),
+    );
+}
+
+/** @param {string} dir */
+function folderName(dir) {
+  const name = path
+    .basename(dir)
+    .toLowerCase()
+    .replace(/[^a-z0-9._~-]+/gu, '-');
+  return name.replace(/^[._]+/u, '') || 'unknown';
+}
+
+/**
+ * @param {string} dir
+ * @returns {{named: PackageRoot | null, any: PackageRoot | null}}
+ */
+function packageRootsOf(dir) {
+  const cached = packageRoots.get(dir);
+  if (cached !== undefined) return cached;
+  /** @type {PackageRoot | null} */
+  let here = null;
+  let named = false;
+  const manifest = path.join(dir, 'package.json');
+  if (fs.existsSync(manifest)) {
+    here = {dir, name: folderName(dir)};
+    try {
+      const {name} = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+      if (typeof name === 'string' && name !== '') {
+        here = {dir, name};
+        named = true;
+      }
+    } catch {
+      // An unreadable package.json names no package; keep walking up.
+    }
+  }
+  const parent = path.dirname(dir);
+  const above =
+    named || parent === dir ? {named: null, any: null} : packageRootsOf(parent);
+  const found = named
+    ? {named: here, any: here}
+    : {named: above.named, any: here ?? above.any};
+  packageRoots.set(dir, found);
+  return found;
+}
+
+/**
+ * A file URL path decoded, or as written when it is not valid percent-encoding
+ * (a message may hold any text).
+ * @param {string} text
+ */
+function safeDecode(text) {
+  try {
+    return decodeURI(text);
+  } catch {
+    return text;
+  }
+}