@a2f0/agent-tool 0.1.28 → 0.1.30

package/README.md

@@ -69,7 +69,7 @@ from a clone:
 mise install
 bun install --frozen-lockfile
 bun src/index.ts --help
-bun test
+bun test --parallel
 ```
 
 [Development](docs/development.md) covers the source layout, the full
@@ -81,7 +81,7 @@ validation suite, and release procedures.
   PR checks/threads, cleanup, CI aggregate gates, release verification, durable
   validation receipts, and toolchain/protection diagnostics.
 - [CLI reference](docs/reference.md): existing review, version, skill installation,
-  command capture, configuration, and distribution contracts.
+  command capture, import-graph checks, configuration, and distribution contracts.
 - [Development](docs/development.md): setup, source layout, validation, and release
   procedures for this package.
 - [Images](docs/images.md): declarative brand sources and generated outputs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
@@ -28,7 +28,7 @@
     "start": "bun src/index.ts",
     "agent:run": "bun src/index.ts run",
     "agent:logs": "bun src/index.ts logs",
-    "test": "bun test src scripts",
+    "test": "bun test --parallel src scripts",
     "typecheck": "tsc --noEmit",
     "generate": "bun scripts/build/bundle-skills.ts",
     "build": "bun run generate && bun build --compile --minify src/index.ts --outfile dist/agent-tool"

package/src/bun/dependencies.ts

@@ -7,7 +7,7 @@ import { assert, flag, option, output } from "../workflows/core";
 import { bunExecute } from "./execute";
 import { pinnedBun, type BunExecutable } from "./toolchain";
 import { lockedWorkspaceVersions, lostWorkspaceReferences } from "../version/lockfileVersions";
-import { packageDirectories, workspacePackage } from "./workspace";
+import { packageDirectories, workspacePackage } from "../system/workspace";
 
 const SECTIONS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"] as const;
 type Section = typeof SECTIONS[number];

package/src/bun/execute.ts

@@ -8,7 +8,7 @@ import { CLASSES } from "../permissions/catalog";
 import { checkPermissions } from "../permissions/install";
 import { projectCommands } from "../permissions/project";
 import { pinnedBun } from "./toolchain";
-import { workspacePackage } from "./workspace";
+import { workspacePackage } from "../system/workspace";
 
 const USAGE = `Usage:
   agent-tool bun test [--cwd <dir>] [--log] [-- args...]

package/src/bun/toolchain.ts

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { outsideExecutable } from "../review/executable";
+import { outsideExecutable } from "../system/executable";
 import { assert } from "../workflows/core";
 
 export interface BunExecutable { path: string; version: string; source: "mise" | "path"; pinned: string | null }

package/src/bun/workspace.ts

@@ -1,40 +1,2 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import path from "node:path";
-import { assert } from "../workflows/core";
-
-/** The checkout root, where the workspace manifest and its lockfile live. */
-export function projectRoot(directory: string): string {
-  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf8" });
-  assert(result.status === 0, "Run Bun commands inside a Git checkout.");
-  return realpathSync(result.stdout.trim());
-}
-
-/** The root package and its declared Bun workspaces: the packages that share the root lockfile. */
-export function packageDirectories(root: string): string[] {
-  const manifest = path.join(root, "package.json");
-  if (!existsSync(manifest)) return [];
-  const value = JSON.parse(readFileSync(manifest, "utf8")) as { workspaces?: unknown };
-  const patterns = Array.isArray(value.workspaces) ? value.workspaces : (value.workspaces as { packages?: unknown } | undefined)?.packages;
-  const list = (Array.isArray(patterns) ? patterns : []).filter((pattern): pattern is string => typeof pattern === "string");
-  // `!pattern` entries exclude directories that the other patterns match.
-  const excluded = list.filter(pattern => pattern.startsWith("!")).map(pattern => new Bun.Glob(pattern.slice(1).replace(/\/$/, "")));
-  const directories = new Set([root]);
-  for (const pattern of list.filter(pattern => !pattern.startsWith("!"))) {
-    for (const match of new Bun.Glob(`${pattern.replace(/\/$/, "")}/package.json`).scanSync({ cwd: root, onlyFiles: true })) {
-      const relative = path.dirname(match);
-      if (!match.split("/").includes("node_modules") && !excluded.some(glob => glob.match(relative))) directories.add(path.join(root, relative));
-    }
-  }
-  return [...directories];
-}
-
-/** Resolve a package directory that belongs to the checkout's workspace, refusing standalone packages. */
-export function workspacePackage(directory: string): { root: string; directory: string } {
-  const resolved = realpathSync(directory);
-  const root = projectRoot(resolved);
-  // Harness rules come from the invoking checkout; --cwd may not reach another repository.
-  assert(root === projectRoot(process.cwd()), "--cwd must name a package in this checkout.");
-  assert(packageDirectories(root).some(item => realpathSync(item) === resolved), "Use the root package or a declared workspace; standalone packages keep their own lockfiles.");
-  return { root, directory: resolved };
-}
+// Moved to the primitives layer; re-exported so existing deep imports keep working.
+export { packageDirectories, projectRoot, workspacePackage } from "../system/workspace";

package/src/cli.ts

@@ -5,6 +5,7 @@ import { DEFAULT_CONFIG, loadConfig } from "./config";
 import { doctor } from "./doctor";
 import { checkTerraformPlan } from "./dependencies/terraformPlan";
 import { dependencyDiff } from "./dependencies/diff";
+import { checkGraph } from "./graph/check";
 import { review } from "./harnesses";
 import { runAgentToolAction } from "./runAgentToolAction";
 import { BUNDLED_SKILLS } from "./skills/bundled";
@@ -72,6 +73,7 @@ Usage: agent-tool [--repo <directory>] [--config <file>] <command>
   permissions check [--harness <all|claude|codex>]
   images list [target...]               JSON files each image target writes
   images build [target...] [--out <dir>]  Render assets/brand/*.svg per agent-tool.json
+  graph check                           Import cycles and layer violations per agent-tool.json
   init                                  Create agent-tool.json without overwriting
   config show
   doctor                                JSON versions and supported review flags
@@ -149,6 +151,11 @@ export function main(argv = process.argv.slice(2)): number | Promise<number> {
       output(action === "list" ? listImages(images, names) : await buildImages(process.cwd(), images, names, out)); return 0;
     });
   }
+  if (command === "graph") {
+    usage(args.length === 1 && args[0] === "check", "Usage: agent-tool graph check");
+    const report = checkGraph(process.cwd(), loadConfig().graph);
+    output(report); return report.ok ? 0 : 1;
+  }
   if (command === "skills") {
     const action = args.shift();
     if (action === "list") { usage(args.length === 0, "Usage: agent-tool skills list"); output(Object.keys(BUNDLED_SKILLS)); return 0; }

package/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { GRAPH_DEFAULTS, parseGraph, type GraphConfig } from "./graph/config";
 import { parseImages, type ImagesConfig } from "./images/config";
 import { CLASSES, type PermissionClass } from "./permissions/catalog";
 import { WORKFLOW_DEFAULTS, validateWorkflowConfig, type WorkflowConfig } from "./workflows/config";
@@ -17,6 +18,7 @@ export interface AgentToolConfig extends WorkflowConfig {
   versions: { packages: string[] | null; bundles: string[]; lockfile: "bun.lock" | null; validate: string[][]; commitMessage: string };
   pr: { rejectClaudeBranding: boolean };
   images: ImagesConfig;
+  graph: GraphConfig;
   permissions: { executables: Record<string, PermissionClass> };
 }
 
@@ -36,6 +38,7 @@ export const DEFAULT_CONFIG: AgentToolConfig = {
   versions: { packages: null, bundles: [], lockfile: "bun.lock", validate: [], commitMessage: "chore: bump package versions" },
   pr: { rejectClaudeBranding: false },
   images: { targets: {} },
+  graph: structuredClone(GRAPH_DEFAULTS),
   permissions: { executables: {} },
 };
 
@@ -69,6 +72,7 @@ export function parseConfig(source: string): AgentToolConfig {
     Object.assign(result[section], settings);
   }
   if (input.images !== undefined) result.images = parseImages(input.images);
+  if (input.graph !== undefined) result.graph = parseGraph(input.graph);
   if (input.branch !== undefined && !Object.hasOwn(input.branch as object, "enforce")) result.branch.enforce = true;
   const invalid = (setting: string): never => { throw new Error(`Invalid config setting '${setting}'.`); };
   if (typeof result.subject.conventional !== "boolean") invalid("subject.conventional");

package/src/graph/check.ts

@@ -0,0 +1,139 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import type { GraphConfig } from "./config";
+import { relativeImports } from "./scan";
+
+/** Extensions `graph check` scans; declaration files (`.d.ts`, `.d.mts`, `.d.cts`) are skipped. */
+const SOURCE = /\.(?:ts|tsx|mts|cts)$/;
+const DECLARATION = /\.d\.(?:ts|mts|cts)$/;
+// TypeScript resolves an emitted-JavaScript extension to its source.
+const EMITTED: Record<string, string[]> = { ".js": [".ts", ".tsx"], ".jsx": [".tsx"], ".mjs": [".mts"], ".cjs": [".cts"] };
+
+export type Graph = ReadonlyMap<string, ReadonlySet<string>>;
+
+export interface GraphReport {
+  ok: boolean;
+  files: number;
+  imports: number;
+  cycles: string[][];
+  violations: string[];
+  unlayered: string[];
+}
+
+const matcher = (patterns: readonly string[]) => {
+  const globs = patterns.map(pattern => new Bun.Glob(pattern));
+  return (file: string) => globs.some(glob => glob.match(file));
+};
+
+/** Repository-relative POSIX paths of the scanned sources, sorted. */
+export function sourceFiles(root: string, config: GraphConfig): string[] {
+  const excluded = matcher(config.exclude);
+  const files = new Set<string>();
+  for (const pattern of config.include) {
+    // Hidden directories hold sources too; Git metadata and installed packages never do.
+    for (const file of new Bun.Glob(pattern).scanSync({ cwd: root, onlyFiles: true, dot: true })) {
+      const relative = file.split(path.sep).join("/");
+      const parts = relative.split("/");
+      if (SOURCE.test(relative) && !DECLARATION.test(relative) && !parts.includes("node_modules") && !parts.includes(".git") && !excluded(relative)) files.add(relative);
+    }
+  }
+  return [...files].sort();
+}
+
+function isFile(root: string, file: string): boolean {
+  try { return statSync(path.join(root, file)).isFile(); } catch { return false; }
+}
+
+/**
+ * The scanned-or-not source file a relative specifier names: the exact path, an
+ * emitted `.js`/`.jsx`/`.mjs`/`.cjs` name's TypeScript source, an extensionless
+ * `.ts` or `.tsx`, or a directory's `index.ts`/`index.tsx`, in TypeScript's order.
+ */
+export function resolveImport(root: string, from: string, specifier: string): string | undefined {
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier)).replace(/\/+$/, "");
+  if (base.startsWith("../") || base === "..") return undefined;
+  // `.`, `..`, and a trailing slash name a directory, so only its index can match.
+  const directory = /(?:^|\/)\.{1,2}$|\/$/.test(specifier);
+  // `.` is the repository root itself, whose index has no directory prefix.
+  const prefix = base === "." ? "" : `${base}/`;
+  const extension = path.posix.extname(base);
+  const stem = base.slice(0, base.length - extension.length);
+  const candidates = [
+    ...(directory ? [] : [base, ...(EMITTED[extension] ?? []).map(source => stem + source), `${base}.ts`, `${base}.tsx`]),
+    `${prefix}index.ts`, `${prefix}index.tsx`,
+  ];
+  return candidates.find(candidate => SOURCE.test(candidate) && !DECLARATION.test(candidate) && isFile(root, candidate));
+}
+
+/** Edges between scanned files; imports of files outside the scan are leaves. */
+export function importGraph(root: string, files: readonly string[], read = (file: string) => readFileSync(path.join(root, file), "utf8")): Map<string, Set<string>> {
+  const scanned = new Set(files);
+  const graph = new Map<string, Set<string>>();
+  for (const file of files) {
+    const targets = new Set<string>();
+    for (const specifier of relativeImports(read(file))) {
+      const target = resolveImport(root, file, specifier);
+      if (target && scanned.has(target)) targets.add(target);
+    }
+    graph.set(file, targets);
+  }
+  return graph;
+}
+
+/** Each cycle once, rotated to start at its smallest module; at least one per strongly connected component. */
+export function findCycles(graph: Graph): string[][] {
+  const cycles = new Map<string, string[]>();
+  const done = new Set<string>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const visit = (file: string) => {
+    if (onStack.has(file)) {
+      const cycle = stack.slice(stack.indexOf(file));
+      const start = cycle.indexOf([...cycle].sort()[0]!);
+      const rotated = [...cycle.slice(start), ...cycle.slice(0, start)];
+      cycles.set(rotated.join(" -> "), rotated);
+      return;
+    }
+    if (done.has(file)) return;
+    stack.push(file); onStack.add(file);
+    for (const target of [...(graph.get(file) ?? [])].sort()) visit(target);
+    stack.pop(); onStack.delete(file);
+    done.add(file);
+  };
+  for (const file of [...graph.keys()].sort()) visit(file);
+  return [...cycles.values()].sort((a, b) => a.join(" -> ").localeCompare(b.join(" -> ")));
+}
+
+/**
+ * Layer and test-only violations. A file belongs to the first layer, lowest first,
+ * with a matching glob; production files may import only their own layer or lower
+ * ones, and never a test-only file. Test-only files may import anything.
+ */
+export function layerViolations(graph: Graph, config: Pick<GraphConfig, "tests" | "layers">): { violations: string[]; unlayered: string[] } {
+  const isTest = matcher(config.tests);
+  const layers = config.layers.map(layer => matcher(layer.include));
+  const layerOf = (file: string) => layers.findIndex(owns => owns(file));
+  const violations: string[] = [];
+  const unlayered = new Set<string>();
+  for (const [file, targets] of graph) {
+    if (isTest(file)) continue;
+    const from = layerOf(file);
+    if (layers.length && from === -1) unlayered.add(file);
+    for (const target of targets) {
+      if (isTest(target)) { violations.push(`${file} imports test-only ${target}`); continue; }
+      const to = layerOf(target);
+      if (from !== -1 && to > from) violations.push(`${file} (${config.layers[from]!.name}) imports ${target} (${config.layers[to]!.name})`);
+    }
+  }
+  return { violations: violations.sort(), unlayered: [...unlayered].sort() };
+}
+
+export function checkGraph(root: string, config: GraphConfig): GraphReport {
+  if (config.include.length === 0) throw new Error("graph.include is empty; list the sources to scan in the graph section of agent-tool.json.");
+  const files = sourceFiles(root, config);
+  const graph = importGraph(root, files);
+  const cycles = findCycles(graph);
+  const { violations, unlayered } = layerViolations(graph, config);
+  const imports = [...graph.values()].reduce((total, targets) => total + targets.size, 0);
+  return { ok: cycles.length === 0 && violations.length === 0 && unlayered.length === 0, files: files.length, imports, cycles, violations, unlayered };
+}

package/src/graph/config.ts

@@ -0,0 +1,43 @@
+/** The data-only `graph` section of agent-tool.json: which TypeScript files `graph check` scans and their layers. */
+
+export interface GraphLayer { name: string; include: string[] }
+export interface GraphConfig { include: string[]; exclude: string[]; tests: string[]; layers: GraphLayer[] }
+
+export const GRAPH_DEFAULTS: GraphConfig = { include: [], exclude: [], tests: [], layers: [] };
+
+function fail(setting: string): never { throw new Error(`Invalid config setting '${setting}'.`); }
+function object(value: unknown, setting: string, allowed: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Record<string, unknown>;
+}
+
+/** Repository-relative glob: no absolute paths, backslashes, negations, or `.`/`..` segments. */
+function globs(value: unknown, setting: string): string[] {
+  if (!Array.isArray(value)) fail(setting);
+  for (const pattern of value) {
+    if (typeof pattern !== "string" || !pattern || pattern.startsWith("/") || pattern.startsWith("!") || pattern.includes("\\")
+      || pattern.split("/").some(part => !part || part === "." || part === "..")) fail(setting);
+  }
+  return [...value] as string[];
+}
+
+export function parseGraph(value: unknown): GraphConfig {
+  const input = object(value, "graph", Object.keys(GRAPH_DEFAULTS));
+  const result = structuredClone(GRAPH_DEFAULTS);
+  for (const key of ["include", "exclude", "tests"] as const) if (input[key] !== undefined) result[key] = globs(input[key], `graph.${key}`);
+  if (input.layers !== undefined) {
+    if (!Array.isArray(input.layers)) fail("graph.layers");
+    result.layers = input.layers.map((entry, index) => {
+      const setting = `graph.layers[${index}]`;
+      const layer = object(entry, setting, ["name", "include"]);
+      if (typeof layer.name !== "string" || !/^[\w.-]+$/.test(layer.name)) fail(`${setting}.name`);
+      const include = globs(layer.include, `${setting}.include`);
+      if (include.length === 0) fail(`${setting}.include`);
+      return { name: layer.name, include };
+    });
+    const names = result.layers.map(layer => layer.name);
+    if (new Set(names).size !== names.length) throw new Error("graph.layers names must be unique.");
+  }
+  return result;
+}

package/src/graph/scan.ts

@@ -0,0 +1,122 @@
+/**
+ * Import specifiers of a TypeScript source, type-only imports included. TypeScript 7
+ * has no JS compiler API and Bun.Transpiler.scanImports drops type-only imports, so
+ * this tokenizes just enough of the language to tell code from comments, strings,
+ * template text, and regular expression literals, then matches import forms.
+ */
+
+/** Whether a `/` after this code starts a regular expression literal rather than a division. */
+function startsRegex(before: string): boolean {
+  const code = before.trimEnd();
+  // `<` is left out so JSX closing tags (`</a>`) do not read as expressions; `a++ / b` divides.
+  // A postfix `!` after an operand is a non-null assertion (`value! / 2`), not logical not.
+  if (/(?:\+\+|--|[\w$)\]]!)$/.test(code)) return false;
+  return code === "" || /[(,=:[!&|?{};+\-*%>~^]$/.test(code)
+    || /(?<![.$\w])(?:return|typeof|case|in|of|delete|void|throw|new|yield|await|else|do)$/.test(code);
+}
+
+// A string or template right after one of these is a module specifier.
+const SPECIFIER_CONTEXT = /(?:(?<![.$\w])from|(?<![.$\w])import\s*\(?|(?<![.$\w])require\s*\()\s*$/;
+const CALL_CONTEXT = /(?<![.$\w])(?:import|require)\s*\(\s*$/;
+// A `)` closing the condition of one of these is followed by a statement, so a `/` there starts a regex.
+const CONTROL = /(?<![.$\w])(?:if|while|for(?:\s+await)?|with)\s*$/;
+
+/**
+ * Blanks comments, template-literal text, regular expression bodies, and every string
+ * that is not a module specifier, keeping the code inside `${...}` interpolations,
+ * which can import too. Offsets and line breaks are preserved.
+ */
+export function stripNonCode(source: string): string {
+  const out = source.split("");
+  const blank = (from: number, to: number) => { for (let i = from; i < to; i++) if (out[i] !== "\n") out[i] = " "; };
+  // The code before offset i with whitespace runs (including blanked comments) collapsed, so a
+  // long comment between `from` and its specifier cannot push `from` out of view.
+  const before = (i: number) => {
+    let text = "";
+    for (let j = i - 1; j >= 0 && text.length < 40; j--) {
+      if (/\s/.test(out[j]!)) { if (!text.startsWith(" ")) text = ` ${text}`; } else text = out[j] + text;
+    }
+    return text;
+  };
+  const lastCode = (i: number) => { let j = i - 1; while (j >= 0 && /\s/.test(out[j]!)) j--; return j; };
+  const regexAt = (i: number) => {
+    const last = out[lastCode(i)];
+    if (last === ")") return controlClose.has(lastCode(i));
+    // `}/>` closes a JSX element whose last attribute is an expression (`<A x={1}/>`).
+    if (last === "}" && source[i + 1] === ">") return false;
+    return startsRegex(before(i));
+  };
+  // Open parentheses, each true when it opened a control-flow condition, and the offsets of `)`s that closed one.
+  const parens: boolean[] = [];
+  const controlClose = new Set<number>();
+  // Each entry is the brace depth of an open interpolation; template text resumes when it closes.
+  const interpolations: number[] = [];
+  let depth = 0;
+  let i = 0;
+  if (source.startsWith("#!")) { i = source.indexOf("\n"); if (i === -1) i = source.length; blank(0, i); }
+  const skipTemplateText = () => {
+    const start = i;
+    while (i < source.length) {
+      if (source[i] === "\\") { i += 2; continue; }
+      if (source[i] === "`") { blank(start, i); i++; return; }
+      if (source[i] === "$" && source[i + 1] === "{") { blank(start, i); interpolations.push(depth); depth++; i += 2; return; }
+      i++;
+    }
+    blank(start, source.length);
+  };
+  while (i < source.length) {
+    const char = source[i]!;
+    if (char === "/" && source[i + 1] === "/") {
+      const end = source.indexOf("\n", i);
+      const stop = end === -1 ? source.length : end;
+      blank(i, stop); i = stop;
+    } else if (char === "/" && source[i + 1] === "*") {
+      const end = source.indexOf("*/", i + 2);
+      const stop = end === -1 ? source.length : end + 2;
+      blank(i, stop); i = stop;
+    } else if (char === "/" && regexAt(i)) {
+      // Skip to the closing slash, honoring escapes and character classes, where `/` is literal.
+      const start = ++i;
+      let inClass = false;
+      while (i < source.length && source[i] !== "\n" && (inClass || source[i] !== "/")) {
+        if (source[i] === "\\") i++;
+        else if (source[i] === "[") inClass = true;
+        else if (source[i] === "]") inClass = false;
+        i++;
+      }
+      blank(start, Math.min(i, source.length));
+      i++;
+    } else if (char === "\"" || char === "'") {
+      const specifier = SPECIFIER_CONTEXT.test(before(i));
+      const start = ++i;
+      while (i < source.length && source[i] !== char && source[i] !== "\n") i += source[i] === "\\" ? 2 : 1;
+      if (!specifier) blank(start, Math.min(i, source.length));
+      i++;
+    } else if (char === "`") {
+      // A substitution-free template right after `import(` or `require(` is a specifier; keep it.
+      const close = source.indexOf("`", i + 1);
+      const literal = close === -1 ? "" : source.slice(i + 1, close);
+      if (close !== -1 && !literal.includes("${") && !literal.includes("\\") && CALL_CONTEXT.test(before(i))) i = close + 1;
+      else { i++; skipTemplateText(); }
+    } else if (char === "(") { parens.push(CONTROL.test(before(i))); i++; }
+    else if (char === ")") { if (parens.pop()) controlClose.add(i); i++; }
+    else if (char === "{") { depth++; i++; }
+    else if (char === "}") {
+      depth--; i++;
+      if (interpolations.at(-1) === depth) { interpolations.pop(); skipTemplateText(); }
+    } else i++;
+  }
+  return out.join("");
+}
+
+const SPECIFIER = /(?<![.$\w])(?:import|export)(?:\s+type\b)?\s*(?:[\w*{}\s,$"']*?\bfrom\s*)?["']([^"'\n]+)["']|(?<![.$\w])(?:import|require)\s*\(\s*["'`]([^"'`\n]+)["'`]\s*[,)]/g;
+
+/** Every module specifier in source order, bare packages included. */
+export function importSpecifiers(source: string): string[] {
+  return [...stripNonCode(source).matchAll(SPECIFIER)].map(match => (match[1] ?? match[2])!);
+}
+
+/** Relative specifiers (`./` or `../`) in source order; bare packages are leaves of the graph. */
+export function relativeImports(source: string): string[] {
+  return importSpecifiers(source).filter(specifier => specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../"));
+}

package/src/permissions/catalog.ts

@@ -19,7 +19,7 @@ export type Decision = "allow" | "ask";
 export interface CatalogEntry { command: string; class: PermissionClass; applyClass?: PermissionClass }
 
 export const CATALOG: CatalogEntry[] = [
-  ...["--help", "--version", "logs", "runs list", "doctor", "config show", "branch check", "branch status", "commits check", "checks binaries", "repo context", "policy check", "toolchain check", "ci gate", "release plan", "release verify", "pr context", "pr checks", "pr logs", "pr preflight", "pr threads list", "versions plan", "versions check", "dependencies check-terraform-plan", "dependencies diff", "skills list", "skills check", "hooks check", "images list", "permissions show", "permissions check"]
+  ...["--help", "--version", "logs", "runs list", "doctor", "config show", "branch check", "branch status", "commits check", "checks binaries", "repo context", "policy check", "toolchain check", "ci gate", "release plan", "release verify", "pr context", "pr checks", "pr logs", "pr preflight", "pr threads list", "versions plan", "versions check", "dependencies check-terraform-plan", "dependencies diff", "skills list", "skills check", "hooks check", "images list", "graph check", "permissions show", "permissions check"]
     .map(command => ({ command, class: "read" as const })),
   ...["bun install", "bun update", "bun remove", "bun test", "branch create", "versions bump", "versions prepare", "versions resolve-conflicts", "images build", "review", "init"]
     .map(command => ({ command, class: "local" as const })),

package/src/review/executable.ts

@@ -1,32 +1,8 @@
-import { accessSync, constants, realpathSync, statSync } from "node:fs";
-import path from "node:path";
+import { outsideExecutable } from "../system/executable";
 import type { ReviewerEnv } from "./runReview";
 
-function within(root: string, candidate: string): boolean {
-  const relative = path.relative(root, candidate);
-  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
-}
-
-/**
- * Find a PATH executable whose entry and target both lie outside the
- * repository. `candidate` keeps the PATH entry, which multi-call binaries such
- * as `bunx` need; `resolved` is its real file.
- */
-export function outsideExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): { candidate: string; resolved: string } | undefined {
-  const root = realpathSync(repositoryRoot);
-  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
-    if (!path.isAbsolute(directory)) continue;
-    const candidate = path.join(directory, name);
-    try {
-      accessSync(candidate, constants.X_OK);
-      const resolved = realpathSync(candidate);
-      if (!statSync(resolved).isFile() || within(root, candidate) || within(root, resolved)) continue;
-      return { candidate, resolved };
-    } catch { /* Continue searching outside the repository. */ }
-  }
-  // Never fall back to a predictable path or PATH resolution after rejection.
-  return undefined;
-}
+// The generic PATH lookup lives in the primitives layer; re-exported for existing callers.
+export { outsideExecutable };
 
 /** Never launch a reviewer binary supplied by the repository being reviewed. */
 export function reviewExecutable(name: string, env: ReviewerEnv, repositoryRoot = process.cwd()): string | undefined {

package/src/system/executable.ts

@@ -0,0 +1,28 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+function within(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+/**
+ * Find a PATH executable whose entry and target both lie outside the
+ * repository. `candidate` keeps the PATH entry, which multi-call binaries such
+ * as `bunx` need; `resolved` is its real file.
+ */
+export function outsideExecutable(name: string, env: Record<string, string | undefined>, repositoryRoot = process.cwd()): { candidate: string; resolved: string } | undefined {
+  const root = realpathSync(repositoryRoot);
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, name);
+    try {
+      accessSync(candidate, constants.X_OK);
+      const resolved = realpathSync(candidate);
+      if (!statSync(resolved).isFile() || within(root, candidate) || within(root, resolved)) continue;
+      return { candidate, resolved };
+    } catch { /* Continue searching outside the repository. */ }
+  }
+  // Never fall back to a predictable path or PATH resolution after rejection.
+  return undefined;
+}

package/src/system/workspace.ts

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { assert } from "../workflows/core";
+
+/** The checkout root, where the workspace manifest and its lockfile live. */
+export function projectRoot(directory: string): string {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf8" });
+  assert(result.status === 0, "Run Bun commands inside a Git checkout.");
+  return realpathSync(result.stdout.trim());
+}
+
+/** The root package and its declared Bun workspaces: the packages that share the root lockfile. */
+export function packageDirectories(root: string): string[] {
+  const manifest = path.join(root, "package.json");
+  if (!existsSync(manifest)) return [];
+  const value = JSON.parse(readFileSync(manifest, "utf8")) as { workspaces?: unknown };
+  const patterns = Array.isArray(value.workspaces) ? value.workspaces : (value.workspaces as { packages?: unknown } | undefined)?.packages;
+  const list = (Array.isArray(patterns) ? patterns : []).filter((pattern): pattern is string => typeof pattern === "string");
+  // `!pattern` entries exclude directories that the other patterns match.
+  const excluded = list.filter(pattern => pattern.startsWith("!")).map(pattern => new Bun.Glob(pattern.slice(1).replace(/\/$/, "")));
+  const directories = new Set([root]);
+  for (const pattern of list.filter(pattern => !pattern.startsWith("!"))) {
+    for (const match of new Bun.Glob(`${pattern.replace(/\/$/, "")}/package.json`).scanSync({ cwd: root, onlyFiles: true })) {
+      const relative = path.dirname(match);
+      if (!match.split("/").includes("node_modules") && !excluded.some(glob => glob.match(relative))) directories.add(path.join(root, relative));
+    }
+  }
+  return [...directories];
+}
+
+/** Resolve a package directory that belongs to the checkout's workspace, refusing standalone packages. */
+export function workspacePackage(directory: string): { root: string; directory: string } {
+  const resolved = realpathSync(directory);
+  const root = projectRoot(resolved);
+  // Harness rules come from the invoking checkout; --cwd may not reach another repository.
+  assert(root === projectRoot(process.cwd()), "--cwd must name a package in this checkout.");
+  assert(packageDirectories(root).some(item => realpathSync(item) === resolved), "Use the root package or a declared workspace; standalone packages keep their own lockfiles.");
+  return { root, directory: resolved };
+}

package/src/version/lockfileVersions.ts

@@ -1,6 +1,6 @@
 import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
-import { packageDirectories } from "../bun/workspace";
+import { packageDirectories } from "../system/workspace";
 import { manifestPath, readVersion, workspacePackages } from "./packageVersion";
 
 function field(value: unknown, key: string): unknown {

package/src/version/versionPreparationGit.ts

@@ -2,7 +2,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { gitEnvironment } from "../git/environment";
-import { outsideExecutable } from "../review/executable";
+import { outsideExecutable } from "../system/executable";
 
 /** Helper Git operations run without hooks or replace objects. */
 export function git(rootDir: string, args: readonly string[]): string {