Skip to content

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

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

/**
 * @file `pnpm check:cli-structure` is the evidence cli-surface INV6 names for
 * the command layout, so it must fail when a command's file or CommandDoc is
 * missing or sits at the wrong path.
 */

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 {fileURLToPath} from 'node:url';
import {afterEach, describe, expect, it} from 'vitest';
import {checkCommandLayout} from './check-cli-structure.mjs';

const REPO_ROOT = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)),
  '..',
);

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

/**
 * A CLI tree with an index.mjs registry. `docs` maps a command name to its
 * subcommand names; each becomes a CommandDoc at its INV6 path.
 *
 * @param {{
 *   registry?: Record<string, string>,
 *   inline?: string[],
 *   files?: string[],
 *   docs?: Record<string, string[]>,
 *   extraDocs?: Record<string, string>,
 * }} tree
 * @returns {string} the tree's `packages/cli` equivalent
 */
function cliTree({
  registry = {},
  inline = [],
  files = [],
  docs = {},
  extraDocs = {},
}) {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-structure-'));
  roots.push(root);
  const commands = path.join(root, 'clients/cli/commands');
  fs.mkdirSync(commands, {recursive: true});
  const entries = Object.entries(registry)
    .map(
      ([name, file]) => `  {name: '${name}', path: '${file}', register: 'r'},`,
    )
    .join('\n');
  const calls = inline.map(name => `program.command('${name}');`).join('\n');
  fs.writeFileSync(
    path.join(root, 'clients/cli/index.mjs'),
    `const commands = [\n${entries}\n];\n${calls}\n`,
  );
  for (const file of files) {
    const target = path.join(root, 'clients/cli', file);
    fs.mkdirSync(path.dirname(target), {recursive: true});
    fs.writeFileSync(target, 'export {};\n');
  }
  const writeDoc = (/** @type {string} */ file, /** @type {object} */ doc) => {
    fs.mkdirSync(path.dirname(path.join(commands, file)), {recursive: true});
    fs.writeFileSync(
      path.join(commands, file),
      `export const doc = ${JSON.stringify(doc)};\n`,
    );
  };
  for (const [name, subcommands] of Object.entries(docs)) {
    writeDoc(`${name.replaceAll(' ', '-')}.doc.mjs`, {
      type: 'command',
      name,
      subcommands,
    });
  }
  for (const [file, name] of Object.entries(extraDocs)) {
    writeDoc(file, {type: 'command', name});
  }
  return root;
}

/** A conforming tree: a flat command, and a group with nested subcommands. */
const CONFORMING = {
  registry: {
    alpha: './commands/alpha.mjs',
    beta: './commands/beta/index.mjs',
  },
  files: ['commands/alpha.mjs', 'commands/beta/index.mjs'],
  docs: {
    alpha: [],
    beta: ['one'],
    'beta one': ['deep'],
    'beta one deep': [],
  },
};

describe('checkCommandLayout', () => {
  it('accepts commands, groups, and nested subcommands at their INV6 paths', async () => {
    const {errors, commands} = await checkCommandLayout(cliTree(CONFORMING));
    expect(errors).toEqual([]);
    expect(commands).toBe(4);
  });

  it('fails when a command has no CommandDoc', async () => {
    const docs = {...CONFORMING.docs};
    delete docs['beta one deep'];
    const {errors} = await checkCommandLayout(cliTree({...CONFORMING, docs}));
    expect(errors).toEqual([
      'command "beta one deep" has no CommandDoc at clients/cli/commands/beta-one-deep.doc.mjs',
    ]);
  });

  it('fails when a command is registered from another file', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({
        ...CONFORMING,
        registry: {...CONFORMING.registry, alpha: './commands/build-alpha.mjs'},
        files: [...CONFORMING.files, 'commands/build-alpha.mjs'],
      }),
    );
    expect(errors).toEqual([
      'command "alpha" is registered from clients/cli/commands/build-alpha.mjs, not clients/cli/commands/alpha.mjs',
    ]);
  });

  it('names the folder form too when a group is registered from another file', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({
        ...CONFORMING,
        registry: {...CONFORMING.registry, beta: './commands/build-beta.mjs'},
        files: [...CONFORMING.files, 'commands/build-beta.mjs'],
      }),
    );
    expect(errors).toEqual([
      'command "beta" is registered from clients/cli/commands/build-beta.mjs, not clients/cli/commands/beta.mjs or clients/cli/commands/beta/index.mjs',
    ]);
  });

  it('fails when a command with no subcommands uses the folder form', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({
        ...CONFORMING,
        registry: {...CONFORMING.registry, alpha: './commands/alpha/index.mjs'},
        files: ['commands/alpha/index.mjs', 'commands/beta/index.mjs'],
      }),
    );
    expect(errors).toEqual([
      'command "alpha" is registered from clients/cli/commands/alpha/index.mjs, but only a group (a CommandDoc that lists subcommands) uses a folder; move it to clients/cli/commands/alpha.mjs',
    ]);
  });

  it('accepts a group in a flat file', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({
        ...CONFORMING,
        registry: {...CONFORMING.registry, beta: './commands/beta.mjs'},
        files: ['commands/alpha.mjs', 'commands/beta.mjs'],
      }),
    );
    expect(errors).toEqual([]);
  });

  it('fails when the registered file is missing', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({...CONFORMING, files: ['commands/beta/index.mjs']}),
    );
    expect(errors).toEqual([
      'command "alpha" is registered from clients/cli/commands/alpha.mjs, which does not exist',
    ]);
  });

  it('fails when a command is registered by hand in index.mjs', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({
        ...CONFORMING,
        inline: ['gamma'],
        docs: {...CONFORMING.docs, gamma: []},
      }),
    );
    expect(errors).toEqual([
      'command "gamma" is registered in clients/cli/index.mjs, not in its own clients/cli/commands/gamma.mjs',
    ]);
  });

  it('fails when a CommandDoc documents a different command', async () => {
    const tree = cliTree(CONFORMING);
    fs.writeFileSync(
      path.join(tree, 'clients/cli/commands/beta-one.doc.mjs'),
      `export const doc = ${JSON.stringify({type: 'command', name: 'beta uno'})};\n`,
    );
    const {errors} = await checkCommandLayout(tree);
    expect(errors).toEqual([
      'clients/cli/commands/beta-one.doc.mjs documents "beta uno", not "beta one"',
      'clients/cli/commands/beta-one-deep.doc.mjs is not the CommandDoc of any registered command',
    ]);
  });

  it('fails when a CommandDoc sits at no registered command path', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({...CONFORMING, extraDocs: {'beta_two.doc.mjs': 'beta two'}}),
    );
    expect(errors).toEqual([
      'clients/cli/commands/beta_two.doc.mjs is not the CommandDoc of any registered command',
    ]);
  });

  it('fails when a CommandDoc sits inside a group folder', async () => {
    const {errors} = await checkCommandLayout(
      cliTree({...CONFORMING, extraDocs: {'beta/beta-one.doc.mjs': 'beta one'}}),
    );
    expect(errors).toEqual([
      'clients/cli/commands/beta/beta-one.doc.mjs is not the CommandDoc of any registered command',
    ]);
  });

  it('fails when index.mjs has no command registry', async () => {
    const tree = cliTree(CONFORMING);
    fs.writeFileSync(path.join(tree, 'clients/cli/index.mjs'), 'export {};\n');
    const {errors} = await checkCommandLayout(tree);
    expect(errors[0]).toBe(
      'found no `commands` registry in clients/cli/index.mjs — has it moved? Update this check.',
    );
  });
});

describe('the repository', () => {
  it('puts every command and CommandDoc at its INV6 path', async () => {
    const {errors, commands} = await checkCommandLayout(
      path.join(REPO_ROOT, 'packages/cli'),
    );
    expect(commands).toBeGreaterThan(0);
    expect(errors).toEqual([]);
  });

  it('passes pnpm check:cli-structure', () => {
    const res = spawnSync(
      process.execPath,
      [path.join(REPO_ROOT, 'scripts/check-cli-structure.mjs')],
      {encoding: 'utf8'},
    );
    expect(res.status, res.stderr).toBe(0);
    expect(res.stdout).toMatch(/\d+ command\(s\) checked for INV6/);
  });
});