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 '@agent-device/host-kit/command';
import {
  checkLockfileInstallSync,
  STALE_NODE_MODULES_MESSAGE,
  type LockfileInstallSyncResult,
} from './lockfile-install-sync.ts';
import { parseScriptArgs } from '../lib/cli-args.ts';
import { runEntrypoint } from '../lib/cli-entrypoint.ts';
import {
  assertCatalogComplete,
  CHECK_CATALOG,
  getCheckSpec,
  resolveCommand,
  type CheckSpec,
} from './checks.ts';
import { MANUAL_ONLY_OWNERS } from '../gate/declarations.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[];
    checkLockfileSync?: (cwd: string) => LockfileInstallSyncResult;
  } = {},
): Promise<number> {
  const cwd = options.cwd ?? repoRoot;
  const checkLockfileSync = options.checkLockfileSync ?? checkLockfileInstallSync;
  // Fail before any gate can misdiagnose a stale worktree install (#1956).
  const lockfileSync = checkLockfileSync(cwd);
  if (lockfileSync.status === 'out-of-sync') {
    reportStaleInstall(lockfileSync.reason, cwd);
    return 1;
  }
  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 relatedSelected = plan.checks.includes('vitest-related');
  const ciJobs = skipped.length > 0 ? ciJobsByCheck() : new Map<CheckId, string[]>();
  for (const spec of skipped) {
    process.stdout.write(`\n[skip] ${spec.id} — ${describeOwner(spec.id, ciJobs)}\n`);
  }
  for (const spec of runnable) {
    if (isCoveredByRelatedTests(spec, relatedSelected)) {
      process.stdout.write(`\n[dedupe] ${spec.id} — covered by related tests or GitHub CI\n`);
      continue;
    }
    const command = resolveCommand(spec, pkg.scripts, args.base, options.changedFiles ?? []);
    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 reportStaleInstall(reason: 'install-missing' | 'stale', cwd: string): void {
  process.stderr.write(`\ncheck:affected: ${STALE_NODE_MODULES_MESSAGE}\n`);
  process.stderr.write(
    reason === 'install-missing'
      ? '(no node_modules/.pnpm/lock.yaml found — this checkout was never installed)\n'
      : '(node_modules/.pnpm/lock.yaml disagrees with pnpm-lock.yaml)\n',
  );
  process.stderr.write(`Worktree: ${cwd}\n`);
  process.stderr.write('Run `pnpm install --frozen-lockfile` in this worktree, then retry.\n');
}

// Where a check the local run skips is authoritative. A parked check has no automatic
// lane; say so instead of printing an empty job list.
function describeOwner(id: CheckId, ciJobs: ReadonlyMap<CheckId, string[]>): string {
  const parked = MANUAL_ONLY_OWNERS[id];
  if (parked) return `parked, workflow_dispatch only (${parked.lane})`;
  return `GitHub-authoritative (jobs: ${(ciJobs.get(id) ?? []).join(', ')})`;
}

function isCoveredByRelatedTests(spec: CheckSpec, relatedSelected: boolean): boolean {
  return relatedSelected && (spec.id === 'unit' || spec.id === 'provider-integration');
}

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());
}