Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
18.8 KB
Raw Blame
// 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 {requireNatively} from '../../test-utils/native-require.mjs';

const require = requireNatively(import.meta.url);
/** @type {typeof import('../config/project.mjs')} */
const {Project} = require('../config/project.mjs');
/** @type {typeof import('../fs/paths.mjs')} */
const {CLI_ROOT} = require('../fs/paths.mjs');
/** @type {typeof import('../discovery/component-loader.mjs')} */
const {
  loadComponentDoc,
  loadDocs,
} = require('../discovery/component-loader.mjs');
/** @type {typeof import('./read.mjs')} */
const {compileDocFile, readDocView} = require('./read.mjs');
/** @type {typeof import('./import.mjs')} */
const {importDocModule, importNativeModule} = require('./import.mjs');
/** @type {typeof import('./inputs.mjs')} */
const {collectDocInputs} = require('./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, checked, says what it exports instead', 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} has no default export or \`docs\` export (it exports \`unrelated\`), so it documents nothing. Fix: export the doc object as the default export`,
    );
  });

  it('says a checked doc file is empty', async () => {
    const file = write('Blank.doc.mjs', '// nothing yet\n');
    await expect(loadComponentDoc(file)).rejects.toThrow(
      `${file} is empty, so it documents nothing.`,
    );
  });

  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 while it is unchanged, 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('reads an installed TypeScript doc through the unchecked reader too', () => {
    // Outside vitest's own loader: a plain import cannot strip types under
    // node_modules, so every reader takes a `.ts` doc through jiti.
    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')).toBe('ok Typed');
    expect(run('loadComponentDoc')).toMatch(/^(ok Typed|threw .*is invalid)/);
  });
});

describe('an edited doc file, read again in the same process', () => {
  /** @param {string} displayName */
  const doc = displayName =>
    `export default {type: 'component', name: 'Edited', displayName: ${JSON.stringify(displayName)}, usage: {description: 'd'}, props: []};\n`;

  it('reads the new content, and shares each version while it is unchanged', async () => {
    const file = write('Edited.doc.mjs', doc('First'));
    const first = await loadDocs(file);
    expect(first.displayName).toBe('First');
    expect(await loadDocs(file)).toBe(first);
    fs.writeFileSync(file, doc('Second, longer'));
    const second = await loadDocs(file);
    expect(second.displayName).toBe('Second, longer');
    expect(await loadDocs(file)).toBe(second);
    expect((await loadComponentDoc(file)).displayName).toBe('Second, longer');
  });

  it('reads an edited TypeScript doc again', async () => {
    const file = write('Edited.doc.ts', doc('First'));
    expect((await loadComponentDoc(file)).displayName).toBe('First');
    fs.writeFileSync(file, doc('Second, longer'));
    expect((await loadComponentDoc(file)).displayName).toBe('Second, longer');
  });

  it('reads an edited TypeScript doc again, one jiti read shared by every importer', async () => {
    const file = write('Pair.doc.ts', doc('First'));
    const before = await importNativeModule(file);
    expect(before.default.displayName).toBe('First');
    fs.writeFileSync(file, doc('Second, longer'));
    // The unchecked reader first, then the checked one: both read the edit.
    expect((await loadDocs(file)).displayName).toBe('Second, longer');
    expect((await loadComponentDoc(file)).displayName).toBe('Second, longer');
    const after = await importNativeModule(file);
    expect(after).not.toBe(before);
    expect(await importDocModule(file)).toBe(after);
    expect(await importNativeModule(file)).toBe(after);
  });

  it('lowers an edited file again for a whole-project compile', async () => {
    const file = write('Edited.doc.mjs', doc('First'));
    const read = () => compileDocFile(file, {root: 'components'});
    expect((await read()).view.displayName).toBe('First');
    fs.writeFileSync(file, doc('Second, longer'));
    expect((await read()).view.displayName).toBe('Second, longer');
  });

  it('reads a fix after an edit that broke the file', async () => {
    const file = write('Edited.doc.mjs', doc('First'));
    expect((await loadDocs(file)).displayName).toBe('First');
    fs.writeFileSync(file, 'export default {;\n');
    await expect(loadDocs(file)).rejects.toThrow();
    fs.writeFileSync(file, doc('Fixed again'));
    expect((await loadDocs(file)).displayName).toBe('Fixed again');
  });

  it.each([
    ['a CommonJS doc', 'Edited.doc.js', {type: 'commonjs'}],
    [
      'a CommonJS doc in a package without a "type"',
      'Edited.doc.js',
      {name: 'kit'},
    ],
    ['an ES module doc', 'Edited.doc.mjs', {name: 'kit'}],
  ])(
    'reads %s again with each importer, in a real Node process',
    (_what, name, packageJson) => {
      const cjs = name.endsWith('.js');
      const source = (/** @type {string} */ displayName) =>
        cjs
          ? doc(displayName).replace('export default', 'module.exports =')
          : doc(displayName);
      const dir = path.join(tmpDir, 'kit');
      fs.mkdirSync(dir);
      fs.writeFileSync(
        path.join(dir, 'package.json'),
        JSON.stringify(packageJson),
      );
      const file = path.join(dir, name);
      fs.writeFileSync(file, source('First'));
      const importers = pathToFileURL(
        path.join(CLI_ROOT, 'foundation/doc-compiler/import.mjs'),
      ).href;
      const run = spawnSync(
        process.execPath,
        [
          '--input-type=module',
          '-e',
          `import fs from 'node:fs';
const m = await import(${JSON.stringify(importers)});
const names = ['importNativeModule', 'importTemplateModule', 'importDocModule'];
const file = process.env.DOC_FILE;
const inOrder = async () => {
  const mods = [];
  for (const n of names) mods.push(await m[n](file));
  return mods;
};
const atOnce = async () => {
  try {
    return await Promise.all(names.map(n => m[n](file)));
  } catch (error) {
    return names.map(() => ({default: {displayName: error.code ?? error.name}}));
  }
};
const before = await inOrder();
fs.writeFileSync(file, process.env.EDITED);
const after = await inOrder();
fs.writeFileSync(file, process.env.EDITED_AGAIN);
const again = await atOnce();
const racing = file.replace('Edited', 'Racing');
fs.writeFileSync(racing, process.env.FIRST);
const firstRead = m.importNativeModule(racing);
fs.writeFileSync(racing, process.env.EDITED);
let race;
try {
  const [first, fresh] = await Promise.all([firstRead, m.importTemplateModule(racing)]);
  race = {first: first.default.displayName, fresh: fresh.default.displayName};
} catch (error) {
  race = {error: error.code ?? error.name};
}
const shown = mods => Object.fromEntries(names.map((n, i) => [n, mods[i].default.displayName]));
const keys = mod => Object.keys(mod).sort().join();
process.stdout.write(JSON.stringify({before: shown(before), after: shown(after), again: shown(again), race, sameExports: before.every((mod, i) => keys(mod) === keys(after[i]))}));`,
        ],
        {
          encoding: 'utf8',
          env: {
            ...process.env,
            DOC_FILE: file,
            FIRST: source('First'),
            EDITED: source('Second, longer'),
            EDITED_AGAIN: source('Third, the longest'),
          },
        },
      );
      expect(run.stderr).not.toMatch(/Error/);
      const all = (/** @type {string} */ displayName) => ({
        importNativeModule: displayName,
        importTemplateModule: displayName,
        importDocModule: displayName,
      });
      // `after` reads one importer at a time, so no other importer's read
      // changes what it sees. `again` reads with all three at once. `race`
      // starts a fresh read while a first read of the same file still
      // imports; that first read can show either version.
      expect(JSON.parse(run.stdout)).toEqual({
        before: all('First'),
        after: all('Second, longer'),
        again: all('Third, the longest'),
        race: {
          first: expect.stringMatching(/^(First|Second, longer)$/),
          fresh: 'Second, longer',
        },
        sameExports: true,
      });
    },
  );
});