Skip to content

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

TypeScript
9.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Every authored descriptor becomes exactly one compiler input.
 *
 * The repo check is the completeness oracle for what Core and the CLI ship:
 * every `.doc.mjs` under a descriptor root is read once, and nothing else is.
 */

import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {Project} from '../config/project.mjs';
import {CLI_ROOT} from '../fs/paths.mjs';
import {collectDocInputs, packageSource} from './inputs.mjs';

const REPO_ROOT = path.resolve(CLI_ROOT, '..', '..');
const SKIP = new Set(['__tests__', '__fixtures__', 'fixtures', 'node_modules']);

/**
 * Every `.doc.mjs` under a directory, by real path.
 * @param {string} dir
 * @param {Set<string>} into
 */
function docFiles(dir, into) {
  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      if (!SKIP.has(entry.name)) docFiles(full, into);
    } else if (entry.name.endsWith('.doc.mjs')) {
      into.add(fs.realpathSync(full));
    }
  }
  return into;
}

let tmpDir;

beforeEach(() => {
  // Inside the repo, so the project finds this checkout's Core.
  tmpDir = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-doc-inputs-'));
  fs.writeFileSync(
    path.join(tmpDir, 'package.json'),
    JSON.stringify({name: 'consumer', version: '1.0.0'}),
  );
});

afterEach(() => {
  fs.rmSync(tmpDir, {recursive: true, force: true});
});

describe('collectDocInputs over what this repo ships', () => {
  it('reads every descriptor Core and the CLI ship exactly once', async () => {
    const {inputs, problems} = await collectDocInputs(
      await Project.load(tmpDir),
    );
    expect(problems).toEqual([]);

    // What ships comes from the packages themselves, not from the module under
    // test: Core's source, and every directory the CLI's package.json ships.
    const shipped = new Set();
    docFiles(path.join(REPO_ROOT, 'packages', 'core', 'src'), shipped);
    const {files} = JSON.parse(
      fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
    );
    for (const entry of files) {
      if (entry.startsWith('!')) continue;
      const full = path.join(CLI_ROOT, entry);
      if (fs.statSync(full).isDirectory()) docFiles(full, shipped);
    }
    const read = inputs.map(input => input.file);
    const rel = (/** @type {string} */ file) => path.relative(REPO_ROOT, file);
    expect(read.filter(file => !shipped.has(file)).map(rel)).toEqual([]);
    expect([...shipped].filter(file => !read.includes(file)).map(rel)).toEqual(
      [],
    );
    expect(new Set(read).size).toBe(read.length);
    expect(new Set(inputs.map(input => input.id)).size).toBe(inputs.length);
  }, 120_000);

  it('pins the core docs that `component <Name>` reads but the list leaves out', async () => {
    const {inputs} = await collectDocInputs(await Project.load(tmpDir));
    // Each is readable by name; listing them would change `component --list`,
    // so a new entry here is a decision, not a silent drift.
    expect(
      inputs
        .filter(input => input.listed === false)
        .map(input => input.name)
        .sort(),
    ).toEqual([
      'Chat',
      'ChatComposerTokenElement',
      'ContextMenuItem',
      'Indicator',
      'Layer',
      'NavMenu',
      'Resizable',
      'SyntaxTheme',
      'createAnimator',
      'createDragToSnapPoints',
      'createPanGesture',
    ]);
  });

  it('keys templates by type and directory, not by their display title', async () => {
    const {inputs} = await collectDocInputs(await Project.load(tmpDir));
    const byName = new Map(
      inputs
        .filter(input => input.root === 'templates')
        .map(input => [input.name, input]),
    );
    // A showcase shares its title with the block it shows; both stay inputs.
    expect(byName.get('block/BannerStatuses')?.source).toBe(
      '@astryxdesign/cli/assets/templates/blocks/components/Banner/BannerStatuses.doc.mjs',
    );
    expect(byName.get('block/BannerShowcase')?.source).toBe(
      '@astryxdesign/cli/assets/templates/blocks/components/Banner/BannerShowcase.doc.mjs',
    );
  });
});

describe('collectDocInputs over an integration', () => {
  /**
   * @param {string} rel
   * @param {string} text
   */
  function write(rel, text) {
    const file = path.join(tmpDir, 'node_modules', '@acme', 'kit', rel);
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, text);
  }

  it('lists each descriptor once, owned by the package, with where it ships', async () => {
    fs.writeFileSync(
      path.join(tmpDir, 'package.json'),
      JSON.stringify({
        name: 'consumer',
        version: '1.0.0',
        dependencies: {'@acme/kit': '^1.0.0'},
      }),
    );
    write(
      'package.json',
      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
    );
    write(
      'astryx.integration.mjs',
      "export default {components: './components', templates: './templates', docs: './docs', themes: './themes'};\n",
    );
    write(
      'components/AcmeCard.tsx',
      'export function AcmeCard() { return null; }\n',
    );
    write(
      'components/AcmeCard.doc.mjs',
      "export default {type: 'component', name: 'AcmeCard', displayName: 'Acme Card', usage: {description: 'A card.'}, props: []};\n",
    );
    write(
      'templates/hero.tsx',
      'export default function Hero() { return null; }\n',
    );
    write(
      'templates/hero.doc.mjs',
      "export default {type: 'block', name: 'Hero block', description: 'A hero.'};\n",
    );
    const topic = (/** @type {object} */ fields) =>
      `export default ${JSON.stringify({
        type: 'generic',
        title: 'Acme',
        description: 'Acme notes.',
        sections: [{title: 'Acme', content: [{type: 'prose', text: 'Hi.'}]}],
        ...fields,
      })};\n`;
    write('docs/acme-guide.doc.mjs', topic({name: 'acme-guide'}));
    write(
      'docs/theme-notes.doc.mjs',
      topic({name: 'theme-notes', extends: 'theme'}),
    );
    write('themes/ocean/oceanTheme.ts', 'export const oceanTheme = {};\n');
    write(
      'themes/ocean/oceanTheme.doc.mjs',
      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Blue.', maintained: true};\n",
    );

    const project = await Project.load(tmpDir);
    expect(await project.issues()).toEqual([]);
    const {inputs, problems} = await collectDocInputs(project);
    expect(problems).toEqual([]);
    expect(
      inputs
        .filter(input => input.owner === '@acme/kit')
        .map(({id, source, role}) => ({id, source, role})),
    ).toEqual([
      {
        id: '@acme/kit:components:AcmeCard',
        source: '@acme/kit/components/AcmeCard.doc.mjs',
        role: undefined,
      },
      {
        id: '@acme/kit:templates:block/hero',
        source: '@acme/kit/templates/hero.doc.mjs',
        role: undefined,
      },
      {
        id: '@acme/kit:themes:ocean',
        source: '@acme/kit/themes/ocean/oceanTheme.doc.mjs',
        role: undefined,
      },
      {
        id: '@acme/kit:docs:theme+theme-notes',
        source: '@acme/kit/docs/theme-notes.doc.mjs',
        role: 'extension',
      },
      {
        id: '@acme/kit:docs:acme-guide',
        source: '@acme/kit/docs/acme-guide.doc.mjs',
        role: 'base',
      },
    ]);
  });
});

describe('collectDocInputs problems', () => {
  /** @param {object} overrides */
  const project = overrides =>
    /** @type {any} */ ({
      cwd: os.tmpdir(),
      components: async () => [],
      templates: async () => [],
      themes: async () => [],
      iconSets: async () => ({sets: []}),
      docs: async () => ({entries: () => []}),
      ...overrides,
    });

  it('reports a file two roots both claim, and reads it once', async () => {
    const file = path.join(tmpDir, 'Shared.doc.mjs');
    fs.writeFileSync(file, 'export default {};\n');
    const {inputs, problems} = await collectDocInputs(
      project({
        components: async () => [
          {name: 'Shared', package: '@acme/kit', docPath: file},
        ],
        templates: async () => [
          {
            type: 'block',
            dirName: 'shared',
            package: '@acme/kit',
            docPath: file,
          },
        ],
      }),
    );
    expect(
      inputs.filter(input => input.file === fs.realpathSync(file)),
    ).toHaveLength(1);
    expect(problems).toEqual([
      {
        code: 'duplicate_file',
        provider: '@acme/kit',
        source: expect.stringMatching(/\/Shared\.doc\.mjs$/),
        message: expect.stringContaining(
          'is read as templates "block/shared" and as components "Shared"',
        ),
      },
    ]);
  });

  it('reports two files under one input id', async () => {
    const one = path.join(tmpDir, 'a', 'Card.doc.mjs');
    const two = path.join(tmpDir, 'b', 'Card.doc.mjs');
    for (const file of [one, two]) {
      fs.mkdirSync(path.dirname(file), {recursive: true});
      fs.writeFileSync(file, 'export default {};\n');
    }
    const {problems} = await collectDocInputs(
      project({
        components: async () => [
          {name: 'Card', package: '@acme/kit', docPath: one},
          {name: 'Card', package: '@acme/kit', docPath: two},
        ],
      }),
    );
    expect(problems).toEqual([
      {
        code: 'duplicate_id',
        provider: '@acme/kit',
        source: expect.stringMatching(/\/Card\.doc\.mjs$/),
        message: expect.stringContaining('both read as components "Card"'),
      },
    ]);
  });
});

describe('packageSource', () => {
  it('names the package a file ships in and its path inside it', () => {
    expect(
      packageSource(path.join(CLI_ROOT, 'api', 'docs', 'docs.doc.mjs')),
    ).toBe('@astryxdesign/cli/api/docs/docs.doc.mjs');
  });
});