TypeScript Project References: Teach AI Agents the Real Build Graph

import fs from "node:fs";
import path from "node:path";

type Node = { dir: string; refs: string[] };

export function loadRefGraph(root: string): Map<string, Node> {
  const graph = new Map<string, Node>();
  const walk = (dir: string) => {
    const cfgPath = path.join(dir, "tsconfig.json");
    if (!fs.existsSync(cfgPath)) return;
    const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
    const refs = (cfg.references ?? []).map((r: { path: string }) =>
      path.resolve(dir, r.path)
    );
    graph.set(path.resolve(dir), { dir: path.resolve(dir), refs });
    for (const r of refs) walk(r);
  };
  walk(root);
  return graph;
}

export function affectedProjects(graph: Map<string, Node>, files: string[]) {
  const seeds = files.map((f) => projectForFile(graph, f));
  // upstream consumers via reverse edges
  return closure(graph, seeds);
}

export function assertBottomUp(planFiles: string[], graph: Map<string, Node>) {
  const order = topoSort(affectedProjects(graph, planFiles));
  // Plan must list packages in topo order (deps before dependents)
  const planned = planFiles.map((f) => projectForFile(graph, f));
  let lastIdx = -1;
  for (const p of planned) {
    const idx = order.indexOf(p);
    if (idx < lastIdx) throw new Error(`out_of_order_edit:${p}`);
    lastIdx = idx;
  }
}

# ✅ Affected build only
pnpm exec tsc -b packages/auth packages/api --verbose

# ❌ Full monorepo panic on every agent PR
pnpm exec tsc -b

export function findCycles(graph: Map<string, Node>): string[][] {
  // Tarjan or Kahn — fail the agent plan if new cycle edges appear in the diff
  return tarjan(graph);
}