Skip to content

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

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

/**
 * @file Tests for the CLI's own typed docs. Every command, API function,
 * schema, and enum doc this package ships declares the group that reads it,
 * and each way one can fail to be read is reported: no namespace, a namespace
 * nothing reads, a clash with the authoring topic's list, a doc that does not
 * load, and a leaf too large for one read. What `astryx docs <route>` prints
 * for one doc is pinned here; where the tree puts it is tree.test.mjs's job.
 *
 * @input This package's own docs, and fixture doc trees written under the
 *   working directory.
 * @output Assertions on the audit and on each doc's rendered content.
 * @position packages/cli/foundation/discovery — tests for cli-self-docs.mjs.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {afterAll, describe, expect, it} from 'vitest';
import {
  CLI_DOC_NAMESPACES,
  auditCliSelfDocs,
  cliDocIndex,
  cliDocSection,
  discoverCliSelfDocSources,
} from './cli-self-docs.mjs';
import {routeSegment} from './docs-section-key.mjs';
import {formatCliCommand} from '../env/package-manager.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

const SLOW = 60_000;

/** @type {string[]} */
const tmpRoots = [];
afterAll(() => {
  for (const root of tmpRoots) fs.rmSync(root, {recursive: true, force: true});
});

/** Write `files` (relative path -> content) under a fresh directory. */
function writeTree(/** @type {Record<string, string>} */ files) {
  const root = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-cli-docs-'));
  tmpRoots.push(root);
  for (const [rel, content] of Object.entries(files)) {
    const file = path.join(root, rel);
    fs.mkdirSync(path.dirname(file), {recursive: true});
    fs.writeFileSync(file, content);
  }
  return root;
}

const docModule = (/** @type {any} */ doc) =>
  `export const doc = ${JSON.stringify(doc, null, 2)};\n`;

const command = (/** @type {string} */ name, extra = {}) => ({
  type: 'command',
  name,
  displayName: `astryx ${name}`,
  namespace: 'cli/commands',
  summary: `Do ${name}`,
  ...extra,
});

const fn = (/** @type {string} */ name, extra = {}) => ({
  type: 'function',
  kind: 'api',
  name,
  displayName: `${name}()`,
  namespace: 'cli/api',
  summary: `The ${name} function.`,
  importPath: '@astryxdesign/cli/api',
  params: [],
  returns: [{type: name, description: 'The result.'}],
  ...extra,
});

const enumDoc = (/** @type {string} */ name, extra = {}) => ({
  type: 'enum',
  name,
  displayName: name,
  namespace: 'cli/api',
  description: `The ${name}.`,
  members: [{value: 'A', description: 'The a.'}],
  ...extra,
});

const schema = (/** @type {string} */ name, extra = {}) => ({
  type: 'schema',
  name,
  displayName: name,
  namespace: 'authoring',
  description: `The ${name} file.`,
  fields: [{name: 'x', type: 'string', description: 'The x.'}],
  ...extra,
});

/** Audit a fixture tree with nothing in the authoring topic's list. */
const audit = (/** @type {string} */ root, authoringSources = []) =>
  auditCliSelfDocs({root, authoringSources});

describe('the CLI docs this package ships', () => {
  it(
    'each declare a namespace something reads, and none fails, clashes, or overflows',
    async () => {
      const result = await auditCliSelfDocs();
      expect({
        missing: result.missing,
        unknown: result.unknown,
        misfiled: result.misfiled,
        failed: result.failed,
        oversized: result.oversized,
      }).toEqual({
        missing: [],
        unknown: [],
        misfiled: [],
        failed: [],
        oversized: [],
      });
      expect(result.docs).toBeGreaterThan(0);
      expect(result.tree + result.authoring).toBe(result.docs);
    },
    SLOW,
  );
});

describe('auditCliSelfDocs', () => {
  it('reports a doc with no namespace, and one nothing reads', async () => {
    const root = writeTree({
      'api/alpha/alpha.doc.mjs': docModule(fn('alpha', {namespace: undefined})),
      'clients/cli/commands/beta.doc.mjs': docModule(
        command('beta', {namespace: 'cli'}),
      ),
      'api/gamma/gamma.doc.mjs': docModule(fn('gamma')),
    });
    const result = await audit(root);
    expect(result.missing).toEqual(['api/alpha/alpha.doc.mjs']);
    expect(result.unknown).toEqual([
      {source: 'clients/cli/commands/beta.doc.mjs', namespace: 'cli'},
    ]);
    expect(result.tree).toBe(1);
  });

  it('holds the authoring namespace to the authoring topic list', async () => {
    const root = writeTree({
      'authoring/x/x.doc.mjs': docModule(schema('x')),
      'authoring/y/y.doc.mjs': docModule(schema('y', {namespace: 'cli/api'})),
      'authoring/z/z.doc.mjs': docModule(schema('z')),
    });
    const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
    expect(result.misfiled.map(entry => entry.message)).toEqual([
      `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
      `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "cli/api"`,
    ]);
    expect(result.authoring).toBe(1);
    expect(result.tree).toBe(0);
  });

  it('reports a doc that fails to load, and skips fixture directories', async () => {
    const root = writeTree({
      'api/bad/bad.doc.mjs': 'throw new Error("boom");\n',
      'api/__fixtures__/ghost.doc.mjs': docModule(fn('ghost')),
      'foundation/.hidden/hidden.doc.mjs': docModule(fn('hidden')),
      'foundation/codes.doc.mjs': docModule(enumDoc('codes')),
    });
    expect(discoverCliSelfDocSources(root)).toEqual([
      'api/bad/bad.doc.mjs',
      'foundation/codes.doc.mjs',
    ]);
    const result = await audit(root);
    expect(result.failed).toEqual([
      expect.objectContaining({
        source: 'api/bad/bad.doc.mjs',
        error: expect.stringContaining('boom'),
      }),
    ]);
    expect(result.tree).toBe(1);
  });

  it('reports a tree doc too large for one read', async () => {
    const root = writeTree({
      'api/big/big.doc.mjs': docModule(
        fn('big', {description: 'x'.repeat(2_000)}),
      ),
      'api/small/small.doc.mjs': docModule(fn('small')),
    });
    const result = await auditCliSelfDocs({root, authoringSources: [], budget: 1_000});
    expect(result.oversized.map(entry => entry.key)).toEqual(['big']);
  });

  it('names every namespace a CLI doc may declare, and what reads it', () => {
    expect(CLI_DOC_NAMESPACES).toEqual({
      'cli/commands': {reader: 'tree'},
      'cli/api': {reader: 'tree'},
      authoring: {reader: 'authoring'},
    });
  });
});

/**
 * An index whose routes are the ones the docs tree gives the CLI's own docs.
 * @param {any[]} docs
 */
const indexOf = docs =>
  cliDocIndex(docs, (kind, name) =>
    kind === 'command'
      ? `cli/commands/${routeSegment(name)}`
      : kind === 'function'
        ? `cli/api/functions/${routeSegment(name)}`
        : null,
  );

describe('cliDocSection', () => {
  it('links a command and the function it runs by identity, never by route', () => {
    const docs = [fn('docs', {command: 'docs'}), command('docs', {fn: 'docs'})];
    const index = indexOf(docs);
    expect(JSON.stringify(cliDocSection(docs[1], index).content)).toContain(
      'It runs `docs()` from `@astryxdesign/cli/api`. Read it with {@link function:docs}.',
    );
    expect(JSON.stringify(cliDocSection(docs[0], index).content)).toContain(
      '`astryx docs` runs it. Read it with {@link command:docs}.',
    );
  });

  it("links a function to the command its command line starts with, or to none", () => {
    const docs = [
      fn('integrationAddTheme', {command: 'integration add theme'}),
      command('integration add'),
      fn('gone', {command: 'gone away'}),
    ];
    const index = cliDocIndex(docs);
    expect(JSON.stringify(cliDocSection(docs[0], index).content)).toContain(
      '`astryx integration add theme` runs it. Read it with {@link command:integration add}.',
    );
    expect(JSON.stringify(cliDocSection(docs[2], index).content)).not.toContain(
      'runs it',
    );
  });

  it('renders a command: usage, arguments, options, examples, exit codes, subcommands', () => {
    const docs = [
      command('grp', {subcommands: ['sub', 'gone']}),
      command('grp sub', {
        description: 'The long form.',
        fn: 'grpSub',
        args: [
          {name: 'files', required: true, variadic: true, description: 'Files.'},
        ],
        options: [
          {flag: '--fast', description: 'Go fast'},
          {
            flag: '--mode <m>',
            description: 'Mode',
            choices: ['a', 'b'],
            default: 'a',
          },
          {flag: '--limit <n>', param: 'options.limit'},
          {flag: '--dry', description: 'Dry run.', default: false},
        ],
        examples: [
          {label: 'Run it', cli: 'astryx grp sub x'},
          {cli: 'astryx grp sub y'},
        ],
        exitCodes: [{code: 1, when: 'it fails'}],
      }),
      fn('grpSub', {
        params: [{name: 'options.limit', type: 'number', description: 'Max.'}],
      }),
    ];
    // `grp gone` has no doc, so it gets no line.
    const index = cliDocIndex(docs, (kind, name) =>
      kind === 'command' && name === 'grp gone'
        ? null
        : kind === 'command'
          ? `cli/commands/${routeSegment(name)}`
          : `cli/api/functions/${routeSegment(name)}`,
    );
    const group = cliDocSection(docs[0], index);
    const sub = cliDocSection(docs[1], index);
    expect(group.content).toContainEqual({
      type: 'list',
      style: 'unordered',
      items: ['`astryx grp sub`: {@link command:grp sub}'],
    });
    expect(sub).toMatchObject({id: 'grp-sub', title: 'astryx grp sub'});
    expect(sub.content).toEqual([
      {type: 'prose', text: 'Do grp sub'},
      {type: 'prose', text: 'The long form.'},
      {type: 'code', lang: 'bash', code: 'astryx grp sub <files...>'},
      {
        type: 'table',
        headers: ['Argument', 'Description'],
        rows: [['`files`', 'Files.']],
      },
      {
        type: 'table',
        headers: ['Option', 'Description'],
        rows: [
          ['`--fast`', 'Go fast'],
          ['`--mode <m>`', 'Mode. One of: `a`, `b`. Default: `a`.'],
          ['`--limit <n>`', 'Max.'],
          ['`--dry`', 'Dry run.'],
        ],
      },
      {
        type: 'code',
        lang: 'bash',
        code: '# Run it\nastryx grp sub x\nastryx grp sub y',
      },
      {
        type: 'table',
        headers: ['Exit code', 'When'],
        rows: [['1', 'it fails']],
      },
      {
        type: 'prose',
        text: 'It runs `grpSub()` from `@astryxdesign/cli/api`. Read it with {@link function:grpSub}.',
      },
    ]);
  });

  it('marks required parameters and adds a Default column when a parameter has a default', () => {
    const beta = fn('beta', {
      params: [
        {name: 'slug', type: 'string', description: 'The slug.', required: true},
        {name: 'options.limit', type: 'number', description: 'How many.', default: '20'},
      ],
    });
    const table = cliDocSection(beta, indexOf([beta])).content.find(
      (/** @type {any} */ block) => block.type === 'table',
    );
    expect(table).toEqual({
      type: 'table',
      headers: ['Parameter', 'Type', 'Default', 'Description'],
      rows: [
        ['`slug` (required)', '`string`', '', 'The slug.'],
        ['`options.limit`', '`number`', '20', 'How many.'],
      ],
    });
  });

  it('renders an API function, an enum, and a schema', () => {
    const alpha = fn('alpha', {
      description: 'Longer.',
      signature: 'alpha(x: string): Promise<Alpha>',
      params: [{name: 'x', type: 'string', description: 'The x.'}],
      throws: [{code: 'ERR_X', when: 'x is bad'}],
      examples: [{label: 'Call it', code: "await alpha('x');"}],
    });
    const codes = enumDoc('codes', {
      members: [
        {value: 'A', description: 'The a.'},
        {value: 'B', description: 'The b.', deprecated: 'Use A.'},
      ],
    });
    const output = schema('output', {namespace: 'cli/api'});
    const index = indexOf([alpha, codes, output]);
    expect(cliDocSection(alpha, index).content).toEqual([
      {type: 'prose', text: 'The alpha function.'},
      {type: 'prose', text: 'Longer.'},
      {type: 'code', lang: 'ts', code: 'alpha(x: string): Promise<Alpha>'},
      {type: 'prose', text: 'Import it from `@astryxdesign/cli/api`.'},
      {
        type: 'table',
        headers: ['Parameter', 'Type', 'Description'],
        rows: [['`x`', '`string`', 'The x.']],
      },
      {
        type: 'table',
        headers: ['Returns', 'Description'],
        rows: [['`alpha`', 'The result.']],
      },
      {
        type: 'table',
        headers: ['Throws', 'When'],
        rows: [['`ERR_X`', 'x is bad']],
      },
      {type: 'code', lang: 'ts', label: 'Call it', code: "await alpha('x');"},
    ]);
    expect(cliDocSection(codes, index)).toEqual({
      id: 'codes',
      title: 'codes',
      content: [
        {type: 'prose', text: 'The codes.'},
        {
          type: 'table',
          headers: ['Value', 'Meaning'],
          rows: [
            ['`A`', 'The a.'],
            ['`B`', 'The b. Deprecated: Use A.'],
          ],
        },
      ],
    });
    const rendered = cliDocSection(output, index);
    expect(rendered.id).toBe('output');
    expect(JSON.stringify(rendered.content)).toContain('The output file.');
  });
});