callstack__agent-device/scripts/check-affected/run.ts

// Entry point for `pnpm check:affected --base <ref>`.
//
// Derives the affected local check set from the diff against <ref>, prints a
// stable machine-readable plan (with per-check reasoning), and optionally runs
// the locally-runnable checks. Fails open to the full set on anything it cannot
// classify. Existing GitHub CI stays authoritative.

import fs from 'node:fs';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { runCmdStreaming, runCmdSync } from '../../src/utils/exec.ts';
import { parseScriptArgs } from '../lib/cli-args.ts';
import { runEntrypoint } from '../lib/cli-entrypoint.ts';
import { DEFAULT_VITEST_MAX_WORKERS } from '../lib/vitest-concurrency.ts';
import {
  assertCatalogComplete,
  CHECK_CATALOG,
  getCheckSpec,
  resolveCommand,
  type CheckSpec,
} from './checks.ts';
import { loadModel, owningLanes } from '../gate/model.ts';
import { ALL_CHECKS, selectChecks, type CheckId, type CheckPlan } from './model.ts';

// Which GitHub jobs run each check, read off the workflows rather than declared
// next to the check. A skipped check tells the reader where it is authoritative,
// and that pointer is only useful if it cannot drift from the workflows.
function ciJobsByCheck(): Map<CheckId, string[]> {
  return owningLanes(loadModel(repoRoot, []));
}

type Args = { base: string; head: string; json: boolean; run: boolean };

const repoRoot = runCmdSync('git', ['rev-parse', '--show-toplevel']).stdout.trim();

const USAGE = 'Usage: pnpm check:affected [--base <ref>] [--head <ref>] [--json] [--run]\n';

function parseArgs(argv: readonly string[]): Args {
  const values = parseScriptArgs(argv, USAGE, {
    base: { type: 'string', default: 'origin/main' },
    head: { type: 'string', default: 'HEAD' },
    json: { type: 'boolean', default: false },
    run: { type: 'boolean', default: false },
  });
  return {
    base: values.base ?? 'origin/main',
    head: values.head ?? 'HEAD',
    json: Boolean(values.json),
    run: Boolean(values.run),
  };
}

function gitLines(args: string[], cwd: string): string[] {
  return runCmdSync('git', args, { cwd }).stdout.split('\n').filter(Boolean);
}

// Collect every changed file a local plan must account for. The committed diff
// (base..head via merge-base) is the baseline; `--no-renames` keeps BOTH sides
// of a rename so a moved file cannot look docs-only by its destination alone.
// In local mode (head === HEAD) we also fold in working-tree changes and
// untracked files, which the committed diff never sees — ignoring uncommitted
// edits would be an unsafe narrowing of the local feedback loop. The staged
// (`--cached`) and unstaged diffs are collected separately and unioned: a
// single `git diff HEAD` nets index against working tree, so a staged add and
// an unstaged delete of the same file would cancel and hide it.
export function readChangedFiles(base: string, head: string, cwd: string = repoRoot): string[] {
  const files = new Set<string>(
    gitLines(['diff', '--name-only', '--no-renames', '--merge-base', base, head], cwd),
  );
  if (head === 'HEAD') {
    for (const args of [
      ['diff', '--name-only', '--no-renames', '--cached'], // staged vs HEAD
      ['diff', '--name-only', '--no-renames'], // unstaged (working tree vs index)
      ['ls-files', '--others', '--exclude-standard'], // untracked
    ]) {
      for (const file of gitLines(args, cwd)) files.add(file);
    }
  }
  return [...files].sort();
}

type PackageJson = {
  scripts: Record<string, string>;
  exports?: Record<string, { import?: string }>;
};

function loadPackageJson(): PackageJson {
  return JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as PackageJson;
}

// Public package surface = the source files behind package.json `exports`.
function packageEntryFiles(pkg: PackageJson): string[] {
  return Object.values(pkg.exports ?? {})
    .map((entry) => entry.import)
    .filter((target): target is string => typeof target === 'string')
    .map((target) => target.replace(/^\.\/dist\//, '').replace(/\.js$/, '.ts'));
}

function printPlanJson(plan: CheckPlan, args: Args): void {
  const ciJobs = ciJobsByCheck();
  const checks = plan.checks.map((id) => {
    const spec = getCheckSpec(id);
    return {
      id,
      label: spec.label,
      ciJobs: ciJobs.get(id) ?? [],
      localRunnable: spec.localRunnable,
      reasons: plan.reasons.filter((reason) => reason.check === id),
    };
  });
  const notSelected = ALL_CHECKS.filter((id) => !plan.checks.includes(id));
  process.stdout.write(
    `${JSON.stringify(
      {
        base: args.base,
        head: args.head,
        failOpen: plan.failOpen,
        failOpenReasons: plan.failOpenReasons,
        docsOnlyPaths: plan.docsOnlyPaths,
        checks,
        notSelected,
      },
      null,
      2,
    )}\n`,
  );
}

function writeLine(line: string): void {
  process.stdout.write(`${line}\n`);
}

function printCheckLine(plan: CheckPlan, id: (typeof plan.checks)[number]): void {
  const spec = getCheckSpec(id);
  const local = spec.localRunnable ? '' : ' (GitHub-authoritative; not run locally)';
  writeLine(`  - ${id}: ${spec.label}${local}`);
  if (plan.failOpen) return;
  for (const reason of plan.reasons.filter((entry) => entry.check === id)) {
    writeLine(`      · ${reason.path} [${reason.rule}] — ${reason.detail}`);
  }
}

function printFailOpen(plan: CheckPlan): void {
  writeLine('Fail-open: selecting the full check set.');
  for (const reason of plan.failOpenReasons) {
    writeLine(`  ! ${reason.path} [${reason.rule}] — ${reason.detail}`);
  }
}

function printSelected(plan: CheckPlan): void {
  if (plan.checks.length === 0) {
    writeLine('No local checks selected.');
    return;
  }
  writeLine(`Selected ${plan.checks.length} check(s):`);
  for (const id of plan.checks) printCheckLine(plan, id);
}

function printPlanHuman(plan: CheckPlan, args: Args): void {
  writeLine(`check:affected — diff ${args.base}...${args.head}`);
  if (plan.failOpen) printFailOpen(plan);
  printSelected(plan);
  if (plan.docsOnlyPaths.length > 0) {
    writeLine(`Docs-only changes ignored: ${plan.docsOnlyPaths.length} file(s).`);
  }
}

// How a resolved command is executed. Injectable so the entrypoint's `--run`
// propagation (order, skip of GitHub-authoritative checks, stop-on-failure) is
// testable without spawning real processes.
export type CommandExecutor = (command: string[], cwd: string) => Promise<number>;

const streamingExecutor: CommandExecutor = async (command, cwd) => {
  const result = await runCmdStreaming(command[0]!, command.slice(1), {
    cwd,
    allowFailure: true,
    onStdoutChunk: (chunk) => void process.stdout.write(chunk),
    onStderrChunk: (chunk) => void process.stderr.write(chunk),
  });
  return result.exitCode;
};

export async function runChecks(
  plan: CheckPlan,
  pkg: PackageJson,
  args: Args,
  options: { cwd?: string; execute?: CommandExecutor; changedFiles?: readonly string[] } = {},
): Promise<number> {
  const cwd = options.cwd ?? repoRoot;
  const execute = options.execute ?? streamingExecutor;
  const runnable = plan.checks.map(getCheckSpec).filter((spec: CheckSpec) => spec.localRunnable);
  const skipped = plan.checks.map(getCheckSpec).filter((spec: CheckSpec) => !spec.localRunnable);
  const coverageSelected = plan.checks.includes('coverage');
  const ciJobs = skipped.length > 0 ? ciJobsByCheck() : new Map<CheckId, string[]>();
  for (const spec of skipped) {
    const jobs = ciJobs.get(spec.id) ?? [];
    process.stdout.write(`\n[skip] ${spec.id} — GitHub-authoritative (jobs: ${jobs.join(', ')})\n`);
  }
  for (const spec of runnable) {
    if (isCoveredByAffectedCoverage(spec, coverageSelected)) {
      process.stdout.write(`\n[dedupe] ${spec.id} — covered by affected LCOV or GitHub CI\n`);
      continue;
    }
    const commands = resolveCheckCommands(spec, pkg, args, options.changedFiles ?? []);
    for (const command of commands) {
      process.stdout.write(`\n[run] ${spec.id}: ${command.join(' ')}\n`);
      const exitCode = await execute(command, cwd);
      if (exitCode !== 0) {
        process.stderr.write(`\ncheck:affected: ${spec.id} failed.\n`);
        return 1;
      }
    }
  }
  process.stdout.write('\ncheck:affected: all runnable checks passed.\n');
  return 0;
}

function isCoveredByAffectedCoverage(spec: CheckSpec, coverageSelected: boolean): boolean {
  return (
    coverageSelected &&
    (spec.id === 'vitest-related' || spec.id === 'unit' || spec.id === 'provider-integration')
  );
}

function resolveCheckCommands(
  spec: CheckSpec,
  pkg: PackageJson,
  args: Args,
  changedFiles: readonly string[],
): string[][] {
  return spec.id === 'coverage'
    ? resolveAffectedCoverageCommands(pkg.scripts, args.base, changedFiles)
    : [resolveCommand(spec, pkg.scripts, args.base, changedFiles)];
}

function resolveAffectedCoverageCommands(
  scripts: Readonly<Record<string, string>>,
  base: string,
  changedFiles: readonly string[],
): string[][] {
  if (!('check:coverage-changed' in scripts)) {
    throw new Error('Required package.json script "check:coverage-changed" does not exist.');
  }
  return [
    [
      'pnpm',
      'exec',
      'vitest',
      'related',
      '--run',
      '--passWithNoTests',
      // `related` spans every configured Vitest project for broad diffs. The
      // machine-derived default can start enough projects concurrently to
      // starve otherwise-green subprocess/provider tests past their exact
      // timeout budgets. Bound this aggregate feedback lane without changing
      // the suites' own timeout or serialization contracts.
      `--maxWorkers=${DEFAULT_VITEST_MAX_WORKERS}`,
      '--coverage',
      '--coverage.reporter=lcov',
      '--coverage.thresholds.statements=0',
      '--coverage.thresholds.lines=0',
      ...changedFiles,
    ],
    ['pnpm', 'run', 'check:coverage-changed', '--base', base],
  ];
}

async function main(argv = process.argv.slice(2)): Promise<number> {
  assertCatalogComplete();
  const args = parseArgs(argv);
  const pkg = loadPackageJson();
  // Validate every catalog command resolves before selecting, so a broken
  // catalog fails loudly rather than silently dropping a gate.
  for (const spec of CHECK_CATALOG) resolveCommand(spec, pkg.scripts, args.base);
  const changedFiles = readChangedFiles(args.base, args.head);
  const plan = selectChecks({
    changedFiles,
    packageEntryFiles: packageEntryFiles(pkg),
  });

  if (args.json) printPlanJson(plan, args);
  else printPlanHuman(plan, args);

  if (args.run) return await runChecks(plan, pkg, args, { changedFiles });
  return 0;
}

if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
  runEntrypoint('check:affected', () => main());
}