gstack/bin/gstack-approval-classes

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
 * gstack-approval-classes — changes that need the owner's approval (field list 2, W2).
 *
 *   gstack-approval-classes [check] [--base <ref>] [--head <ref>] [--diff-base <sha>] [--json]
 *   gstack-approval-classes init [--force]
 *   gstack-approval-classes validate
 *
 * `check` reads the classes from the committed `origin/<base>` copy of
 * .gstack/approval-classes.json (never the working tree) and the migration
 * rule from the base's ship policy, scans the branch's changes since the
 * merge base, and prints `APPROVAL_CLASS: <class> <file>:<line>` per hit, one
 * `APPROVAL_SCOPE: <class>@<digest12>` per declared class with hits, and
 * `APPROVAL_CLASSES: ok | found=<n> | none` last. Built-in detectors only
 * report. Exit 0 ok or none, 1 found, 3 when the base file is invalid or the
 * base is unresolvable. Enforcement is gstack-ship-receipt write
 * (APPROVAL_CITATION_MISSING). Logic: lib/approval-classes.ts.
 */
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { APPROVAL_CLASSES_PATH, exampleApprovalClassesJson, loadWorkingApprovalClasses, renderApprovalScan, runApprovalScan } from '../lib/approval-classes';
import { EXIT, exitTableHelp } from '../lib/headless-artifacts';
import { resultLine } from '../lib/result-codes';
import { resolveBaseBranch } from '../lib/ship-policy';

const HELP = `gstack-approval-classes — changes that need the owner's approval (docs/ship-policy.md#approval-classes)

  check [--base <ref>] [--head <ref>] [--diff-base <sha>] [--json]
        changes since the merge base with origin/<base> (default origin/HEAD's branch), at --head or the
        working tree; classes come only from the committed ${APPROVAL_CLASSES_PATH} on origin/<base>
  init [--force]        write an example ${APPROVAL_CLASSES_PATH}
  validate              schema and containment check of the working-tree file (before you commit it)

A declared class with hits needs a line in the PR body that gstack-ship-receipt write can resolve:
  Approved by <owner> <YYYY-MM-DD> via <plan sha|comment or review URL|ref> [for <class>@<digest12>]

${exitTableHelp()}`;

function flag(args: string[], name: string): string | undefined {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
}

function main(argv: string[]): number {
  if (argv.includes('--help') || argv.includes('-h')) { process.stdout.write(HELP + '\n'); return EXIT.ok; }
  const cmd = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'check';
  const rest = cmd === argv[0] ? argv.slice(1) : argv;
  const root = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 15_000 });
  if (root.status !== 0) { process.stderr.write('gstack-approval-classes: not inside a git repository\n'); return EXIT.usage; }
  const repoRoot = root.stdout.trim();
  const file = path.join(repoRoot, APPROVAL_CLASSES_PATH);

  if (cmd === 'init') {
    if (fs.existsSync(file) && !rest.includes('--force')) { process.stderr.write(`gstack-approval-classes: ${APPROVAL_CLASSES_PATH} exists (pass --force to overwrite)\n`); return EXIT.refused; }
    fs.mkdirSync(path.dirname(file), { recursive: true });
    fs.writeFileSync(file, exampleApprovalClassesJson());
    process.stdout.write(`APPROVAL_CLASSES_INIT: ${APPROVAL_CLASSES_PATH} (edit, commit and merge it; check reads only the base copy)\n`);
    return EXIT.ok;
  }
  if (cmd === 'validate') {
    const load = loadWorkingApprovalClasses(repoRoot);
    if ('absent' in load) { process.stdout.write(`APPROVAL_CLASSES: none (no ${APPROVAL_CLASSES_PATH})\n`); return EXIT.ok; }
    if ('errors' in load) { for (const e of load.errors) process.stderr.write(resultLine('gstack-approval-classes validate', 'APPROVAL_CLASSES_INVALID', `${e.message} at ${e.path || '<root>'}`) + '\n'); return EXIT.refused; }
    if ('unavailable' in load || !load.config) return EXIT.fail;
    process.stdout.write(`APPROVAL_CLASSES_VALID: ${APPROVAL_CLASSES_PATH} classes=${load.config.classes.length}\n`);
    return EXIT.ok;
  }
  if (cmd !== 'check') { process.stderr.write(`gstack-approval-classes: unknown command ${cmd}\n${HELP}\n`); return EXIT.usage; }

  const json = rest.includes('--json');
  const base = resolveBaseBranch(repoRoot, flag(rest, '--base'));
  const outcome = runApprovalScan({ repoRoot, base, head: flag(rest, '--head'), diffBase: flag(rest, '--diff-base') });
  if ('unavailable' in outcome) { process.stderr.write(resultLine('gstack-approval-classes', 'APPROVAL_SOURCE_UNAVAILABLE', `${outcome.unavailable}; classes are read only from the base, so nothing was checked`) + '\n'); return EXIT.refused; }
  if ('errors' in outcome) { for (const e of outcome.errors) process.stderr.write(resultLine('gstack-approval-classes', 'APPROVAL_CLASSES_INVALID', `${e.message} at ${e.path || '<root>'} (${outcome.source})`) + '\n'); return EXIT.refused; }
  if ('error' in outcome && outcome.unreadable) { process.stderr.write(resultLine('gstack-approval-classes', 'APPROVAL_SOURCE_UNAVAILABLE', `${outcome.error}, so nothing was checked`) + '\n'); return EXIT.refused; }
  if ('error' in outcome) { process.stderr.write(`gstack-approval-classes: ${outcome.error}\n`); return EXIT.usage; }
  const { scan, absent } = outcome;
  process.stdout.write(json ? JSON.stringify({ ...scan, absent }) + '\n' : renderApprovalScan(scan, absent));
  if (scan.hits.length) { process.stderr.write(resultLine('gstack-approval-classes', 'APPROVAL_CLASS_FOUND', `${scan.scopes.map(s => s.token).join(', ')} need an Approved by line`) + '\n'); return EXIT.fail; }
  return EXIT.ok;
}

process.exitCode = main(process.argv.slice(2));