Skip to content

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

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

/**
 * @file Generate the drift-prone reference tables in packages/cli/README.md from
 * the sources of truth, so they can't fall out of sync again:
 *   - the Commands table    <- `astryx manifest --json` (the live command set)
 *   - the Error codes table <- the error-codes EnumDoc (== ERROR_CODES, enforced
 *                              by the docs drift harness)
 *
 * Content is written between `<!-- BEGIN GENERATED: <name> -->` and
 * `<!-- END GENERATED: <name> -->` markers. `--check` verifies the committed
 * README matches (CI gate); without it, the README is rewritten in place.
 *
 * @input astryx manifest + foundation/response/error-codes.doc.mjs
 * @output packages/cli/README.md (between generated markers)
 * @position packages/cli/scripts — README table generator
 *
 * Usage:
 *   node packages/cli/scripts/generate-cli-readme.mjs          # write
 *   node packages/cli/scripts/generate-cli-readme.mjs --check   # CI gate
 */

import {spawnSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
import prettier from 'prettier';

const HERE = path.dirname(fileURLToPath(import.meta.url));
const CLI_ROOT = path.resolve(HERE, '..');
const BIN = path.join(CLI_ROOT, 'clients/cli/bin/astryx.mjs');
const README = path.join(CLI_ROOT, 'README.md');

function getManifest() {
  const res = spawnSync('node', [BIN, 'manifest', '--json'], {
    encoding: 'utf8',
    maxBuffer: 64 * 1024 * 1024,
  });
  // Report a CLI that failed to boot as itself. Without this, the parse below
  // turns it into "Unexpected end of JSON input", which says nothing useful
  // when this runs as a CI gate.
  if (res.error) throw res.error;
  if (res.status !== 0 || !res.stdout.trim()) {
    throw new Error(
      `\`astryx manifest --json\` failed (exit ${res.status}).\n${res.stderr}`,
    );
  }
  return JSON.parse(res.stdout).data;
}

/** @param {string} rel @returns {Promise<any>} */
async function loadDoc(rel) {
  const mod = await import(pathToFileURL(path.join(CLI_ROOT, rel)).href);
  return mod.doc ?? mod.docs;
}

/** @param {string[]} headers @param {string[][]} rows */
function table(headers, rows) {
  const esc = (/** @type {unknown} */ s) => String(s).replace(/\|/g, '\\|');
  const head = `| ${headers.join(' | ')} |`;
  const sep = `| ${headers.map(() => '---').join(' | ')} |`;
  const body = rows.map(r => `| ${r.map(esc).join(' | ')} |`).join('\n');
  return [head, sep, body].join('\n');
}

/** @param {string} content @param {string} name @param {string} block */
function replaceBlock(content, name, block) {
  const begin = `<!-- BEGIN GENERATED: ${name} -->`;
  const end = `<!-- END GENERATED: ${name} -->`;
  const re = new RegExp(
    `${begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
  );
  if (!re.test(content)) throw new Error(`README markers for "${name}" not found`);
  return content.replace(re, `${begin}\n\n${block}\n\n${end}`);
}

/**
 * A command's `outsideProject` value for the commands table. A group that
 * only holds subcommands declares none, so it shows its subcommands' value when
 * they agree, and `by subcommand` when they differ.
 * @param {any} command a manifest command
 * @returns {string}
 */
function outsideProject(command) {
  if (command.outsideProject) return `\`${command.outsideProject}\``;
  /** @type {Set<string>} */
  const values = new Set();
  const walk = (/** @type {any[]} */ subs) => {
    for (const sub of subs) {
      if (sub.outsideProject) values.add(sub.outsideProject);
      walk(sub.subcommands ?? []);
    }
  };
  walk(command.subcommands ?? []);
  return values.size === 1 ? `\`${[...values][0]}\`` : 'by subcommand';
}

async function build() {
  const manifest = getManifest();
  const commandRows = manifest.commands
    .filter((/** @type {any} */ c) => c.name !== 'manifest')
    .map((/** @type {any} */ c) => [`\`${c.name}\``, c.description, outsideProject(c)]);

  const errorCodes = await loadDoc('foundation/response/error-codes.doc.mjs');
  // Experimental codes are documented under `astryx docs cli/experimental`,
  // not in the stable table (spec:AST-017 FR27).
  const errorRows = errorCodes.members
    .filter((/** @type {any} */ m) => m.stability !== 'experimental')
    .map((/** @type {any} */ m) => [`\`${m.value}\``, m.description]);

  const responseTypes = await loadDoc(
    'foundation/response/response-types.doc.mjs',
  );
  // Experimental response types are documented under `astryx docs
  // cli/experimental`, not in the stable table (spec:AST-017 FR27).
  const rtRows = responseTypes.members
    .filter((/** @type {any} */ m) => m.stability !== 'experimental')
    .map((/** @type {any} */ m) => [`\`${m.value}\``, m.description]);

  let content = fs.readFileSync(README, 'utf8');
  content = replaceBlock(
    content,
    'commands',
    table(['Command', 'Description', 'Outside a project'], commandRows),
  );
  content = replaceBlock(content, 'error-codes', table(['Code', 'Meaning'], errorRows));
  content = replaceBlock(content, 'response-types', table(['Type', 'What `data` carries'], rtRows));

  // Format through the repo's prettier config so the generated tables match what
  // the commit hook (lint-staged prettier over *.md) would produce; otherwise
  // `--check` would flag the file as drifted right after a commit reformats it.
  const config = (await prettier.resolveConfig(README)) ?? {};
  return prettier.format(content, {...config, parser: 'markdown', filepath: README});
}

async function main() {
  const check = process.argv.includes('--check');
  const next = await build();
  const current = fs.readFileSync(README, 'utf8');
  if (check) {
    if (current !== next) {
      console.error(
        'README generated tables are out of date. Run: pnpm -F @astryxdesign/cli readme',
      );
      process.exit(1);
    }
    console.log('README generated tables are in sync.');
  } else {
    fs.writeFileSync(README, next);
    console.log('README generated tables written.');
  }
}

main();