@afokapu/atdd-bun 0.10.83 → 0.10.85

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.83",
+  "version": "0.10.85",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
@@ -1260,8 +1260,8 @@
     "src/ci.ts": "2a5e5052c4b99eb5c7282c7db2af3846ad6f3ca7d1eaefe924441116f765f37b",
     "src/cli.ts": "995e41b3cb44c04f65f4d599f0fc51b93b17b7558b7c7dcfabed64de3d455250",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
-    "src/enforce.ts": "7e6b3a1fc7c90f8e1836ab3e4655778fb569a63be5e7c199de44024fc003e6be",
-    "src/hooks.ts": "5c7dd77c370e745ad7a6f308fa0cfaeeb066560540403d2a4f56543a570116cc",
+    "src/enforce.ts": "e0c10519aeecd7080f2900ea230fad2f09482af47c1cee885d5de71573e29732",
+    "src/hooks.ts": "f20024340979de799ed977b8d2483ca09c494ef952dcea2cc7c4c39e6e10679c",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
     "src/integrity.ts": "f5ad22759eec675454df82cdcf791b1f081951f08ca5084ebdcb8cd82aa1ecef",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.83",
+  "version": "0.10.85",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/enforce.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { link, mkdir, mkdtemp, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { availableParallelism, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { topologyFor } from "./topology";
 
@@ -125,6 +125,119 @@ export async function undeclaredEmissions(implementation: string, violations: Pi
   return [...new Set(violations.map(v => v.rule_id).filter(id => !declared.has(id)))].sort();
 }
 
+// Detector concurrency is resource control, never verification: it changes when detectors run, not what they find.
+
+/** A positive integer from the environment, else `fallback`. Any other value fails closed. */
+function detectorLimit(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  if (!/^[1-9]\d*$/.test(raw)) throw new Error(`${name} must be a positive integer, got ${JSON.stringify(raw)}`);
+  return Number(raw);
+}
+
+/** How many detectors one run may have in flight. */
+const runDetectorLimit = () => detectorLimit("ATDD_BUN_MAX_DETECTORS", Math.max(2, Math.floor(availableParallelism() / 2)));
+/** How many detectors all atdd-bun runs on this host may have in flight together. */
+const hostDetectorLimit = () => detectorLimit("ATDD_BUN_HOST_DETECTORS", availableParallelism());
+/** A held slot is a lease: its holder refreshes it every lease interval, and one not refreshed for the stale age is
+ * free whatever pid it names, since a killed holder's pid can be reused by an unrelated live process. */
+function slotLease(): { leaseMs: number; staleMs: number } {
+  const leaseMs = detectorLimit("ATDD_BUN_DETECTOR_LEASE_MS", 5_000), staleMs = detectorLimit("ATDD_BUN_DETECTOR_STALE_MS", 60_000);
+  if (staleMs <= leaseMs) throw new Error(`ATDD_BUN_DETECTOR_STALE_MS (${staleMs}) must exceed ATDD_BUN_DETECTOR_LEASE_MS (${leaseMs})`);
+  return { leaseMs, staleMs };
+}
+const slotDirectory = () => process.env.ATDD_BUN_DETECTOR_SLOTS_DIR ?? join(tmpdir(), "atdd-bun-detector-slots");
+
+/** Map `work` over `items` with at most `limit` in flight; results keep the order of `items`. */
+async function pooled<T, R>(items: T[], limit: number, work: (item: T) => Promise<R>): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+  const worker = async () => { while (next < items.length) { const index = next++; results[index] = await work(items[index]); } };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+const errorCode = (error: unknown) => (error as NodeJS.ErrnoException).code;
+const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch (error) { return errorCode(error) === "EPERM"; } };
+const ownerPid = async (path: string) => Number((await readFile(path, "utf8").catch(() => "")).split(" ")[0]) || undefined;
+
+/** Hard-link the fully written claim to the slot path: atomic and exclusive, like O_EXCL, so a reader never sees a half-written owner. */
+async function claim(staging: string, slot: string): Promise<boolean> {
+  try { await link(staging, slot); return true; } catch (error) { if (errorCode(error) === "EEXIST") return false; throw error; }
+}
+
+/** Whether a slot file is a live lease: its owner runs and refreshed it within the stale age. Undefined when absent. */
+async function leaseHeld(path: string, staleMs: number): Promise<boolean | undefined> {
+  const info = await stat(path).catch(() => undefined);
+  if (!info) return undefined;
+  const owner = await ownerPid(path);
+  return owner !== undefined && alive(owner) && Date.now() - info.mtimeMs < staleMs;
+}
+
+/** Free a slot whose owner is gone or whose lease expired. Moving it aside first means two reclaimers cannot both
+ * delete it; a live lease claimed in the meantime is put back. */
+async function reclaimIfStale(slot: string, token: string, staleMs: number): Promise<void> {
+  if (await leaseHeld(slot, staleMs) !== false) return;
+  const aside = `${slot}.reclaim-${token.replace(" ", "-")}`;
+  try { await rename(slot, aside); } catch { return; }
+  if (await leaseHeld(aside, staleMs)) await link(aside, slot).catch(() => undefined);
+  await rm(aside, { force: true });
+}
+
+const touch = (path: string) => { const now = new Date(); return utimes(path, now, now); };
+
+/** Keep a claimed slot's lease fresh until it is released. */
+function holdLease(slot: string, token: string, leaseMs: number): () => Promise<void> {
+  const timer = setInterval(() => void touch(slot).catch(() => undefined), leaseMs);
+  timer.unref();
+  return async () => { clearInterval(timer); await release(slot, token); };
+}
+
+const warned = new Set<string>();
+function warnUnusable(directory: string, error: unknown): void {
+  if (warned.has(directory)) return;
+  warned.add(directory);
+  process.stderr.write(`atdd-bun: detector slot directory ${directory} is unusable (${(error as Error).message}); bounding detectors by the per-run cap only\n`);
+}
+
+/** Take one of the host-wide detector slots, waiting with a small backoff while all are leased. Returns the release.
+ * A slot directory that cannot be used at all degrades to the per-run cap, reported on stderr. */
+async function acquireHostSlot(): Promise<() => Promise<void>> {
+  const limit = hostDetectorLimit(), { leaseMs, staleMs } = slotLease(), directory = slotDirectory();
+  const token = `${process.pid} ${crypto.randomUUID()}`, staging = join(directory, `.claim-${token.replace(" ", "-")}`);
+  try {
+    await mkdir(directory, { recursive: true });
+    await writeFile(staging, token);
+    for (let delay = 5; ; delay = Math.min(delay * 2, 200)) {
+      // A claim links this file, so it must be fresh: a waiter's slot starts its lease at the claim.
+      await touch(staging);
+      for (let index = 0; index < limit; index++) {
+        const slot = join(directory, `slot-${index}`);
+        if (await claim(staging, slot)) return holdLease(slot, token, leaseMs);
+        await reclaimIfStale(slot, token, staleMs);
+        if (await claim(staging, slot)) return holdLease(slot, token, leaseMs);
+      }
+      await Bun.sleep(delay);
+    }
+  } catch (error) {
+    warnUnusable(directory, error);
+    return async () => undefined;
+  } finally {
+    await rm(staging, { force: true }).catch(() => undefined);
+  }
+}
+
+/** Release only a slot this claim still owns. */
+async function release(slot: string, token: string): Promise<void> {
+  if (await readFile(slot, "utf8").catch(() => "") === token) await rm(slot, { force: true });
+}
+
+/** Run `work` while holding one host-wide detector slot. */
+async function withHostSlot<T>(work: () => Promise<T>): Promise<T> {
+  const release = await acquireHostSlot();
+  try { return await work(); } finally { await release(); }
+}
+
 export async function runImplementation(
   implementation: string,
   config: Required<Pick<EnforcementConfig, "scanRoots" | "excludes">> & { profiles?: ConcreteProfile[] },
@@ -134,23 +247,26 @@ export async function runImplementation(
   const report = join(scratch, "violations.json");
   try {
     const bun = Bun.which("bun") ?? process.execPath, topology = await topologyFor(config.scanRoots[0] ?? process.cwd());
-    const child = Bun.spawn({
-      cmd: [bun, detector],
-      cwd: config.scanRoots[0] ?? process.cwd(),
-      stdout: "pipe",
-      stderr: "pipe",
-      env: {
-        ...process.env,
-        ATDD_SCAN_ROOTS: JSON.stringify(config.scanRoots),
-        ATDD_SCAN_EXCLUDES: JSON.stringify(config.excludes),
-        ATDD_PLAN_ROOT: topology.planRoot,
-        ATDD_VIOLATIONS_REPORT: report,
-        // The profiles this run selected, so a detector shared by several profiles can tell a planning run from
-        // one that has reached RED or GREEN. Absent on a direct call, where detectors keep their full behaviour.
-        ...(config.profiles ? { ATDD_PROFILES: JSON.stringify(config.profiles) } : {}),
-      },
+    // One host-wide slot per detector process, so concurrent runs cannot together exhaust the machine.
+    const { exitCode, child } = await withHostSlot(async () => {
+      const child = Bun.spawn({
+        cmd: [bun, detector],
+        cwd: config.scanRoots[0] ?? process.cwd(),
+        stdout: "pipe",
+        stderr: "pipe",
+        env: {
+          ...process.env,
+          ATDD_SCAN_ROOTS: JSON.stringify(config.scanRoots),
+          ATDD_SCAN_EXCLUDES: JSON.stringify(config.excludes),
+          ATDD_PLAN_ROOT: topology.planRoot,
+          ATDD_VIOLATIONS_REPORT: report,
+          // The profiles this run selected, so a detector shared by several profiles can tell a planning run from
+          // one that has reached RED or GREEN. Absent on a direct call, where detectors keep their full behaviour.
+          ...(config.profiles ? { ATDD_PROFILES: JSON.stringify(config.profiles) } : {}),
+        },
+      });
+      return { exitCode: await child.exited, child };
     });
-    const exitCode = await child.exited;
     if (exitCode !== 0) {
       const stderr = await new Response(child.stderr).text();
       throw new Error(`${implementation} failed to run (exit ${exitCode}): ${stderr.trim()}`);
@@ -175,8 +291,8 @@ export async function enforce(config: EnforcementConfig = {}): Promise<Violation
   // is validated on every run, so a misspelled atdd-bun.yaml fails whichever profile is requested.
   const requested = config.profiles ?? ["all"], enabled = await enabledProfiles(root);
   const selected = requested.includes("all") ? [...new Set([...requested.filter(p => p !== "all"), ...enabled])] : requested;
-  const results = await Promise.all(
-    implementationsFor(selected).map((implementation) => runImplementation(implementation, { scanRoots, excludes, profiles: selected as ConcreteProfile[] })),
+  const results = await pooled(implementationsFor(selected), runDetectorLimit(),
+    (implementation) => runImplementation(implementation, { scanRoots, excludes, profiles: selected as ConcreteProfile[] }),
   );
   return results.flat().sort((left, right) =>
     left.rule_id.localeCompare(right.rule_id) || left.file.localeCompare(right.file) || left.line - right.line,

package/src/hooks.ts

@@ -1,9 +1,9 @@
-import { chmod, mkdir, mkdtemp, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { tmpdir } from "node:os";
-import { concreteProfiles, enabledProfiles, enforce, normalizeProfileName } from "./enforce";
-import { activationContextDigest, canonicalFindingPath, compareFindings, contextDigest, isStrictProfileExpansion, parseRatchetPolicy } from "./ratchet";
+import { concreteProfiles, enabledProfiles, enforce, normalizeProfileName, profileConventions } from "./enforce";
+import { activationContextDigest, canonicalFindingPath, compareFindings, contextDigest, findingFingerprint, isStrictProfileExpansion, parseRatchetPolicy, type FindingIdentity } from "./ratchet";
 import { topologyFor } from "./topology";
 import { JOURNEY_DOCS_DIR } from "./journey-docs";
 
@@ -113,8 +113,9 @@ async function strictPushGate(root: string, candidate: string, range: string) {
   const candidateRoot = await mkdtemp(join(tmpdir(), "atdd-strict-push-candidate-"));
   try {
     await checkoutCommit(root, candidateRoot, candidate, "strict pre-push candidate");
-    const changed = await files(candidateRoot, ["diff", "--name-only", range]);
-    return await validation(candidateRoot, changed, true);
+    // The same affected-area selection as pre-commit, judged against the candidate's own registry policy.
+    const changed = await files(candidateRoot, ["diff", "--name-only", range]), cfg = await policy(candidateRoot);
+    return await validation(candidateRoot, changed, false, changed.some(path => isRegistry(cfg, path)));
   } catch (error) { return bad(`strict pre-push gate failed closed: ${String(error)}`); }
   finally { await git(root, ["worktree", "remove", "--force", candidateRoot]); await rm(candidateRoot, { recursive: true, force: true }); }
 }
@@ -170,6 +171,49 @@ async function existingBranchProtectedBase(root: string, candidate: string, remo
   return { base: tip && tip !== remoteBase.toLowerCase() ? tip : null };
 }
 
+/** Ratchet findings depend only on the scanned tree, the toolkit scanning it and the selected profiles, so they are cached
+ * under the Git common directory. An entry is advisory: unreadable, malformed or differently keyed means recompute, never clean. */
+const packageRoot = resolve(import.meta.dir, ".."), toolkitInputs = ["package.json", "relationships.yaml", "src", "lib", "detectors", "conventions", "planner-nodes", "planner-schemas"];
+export type ToolkitIdentity = { version: string; digest: string };
+async function toolkitFiles() {
+  const found = new Set<string>();
+  for (const input of toolkitInputs) {
+    const path = join(packageRoot, input);
+    if (!existsSync(path)) continue;
+    if ((await stat(path)).isFile()) { found.add(input); continue; }
+    for await (const file of new Bun.Glob("**/*").scan({ cwd: path, onlyFiles: true, dot: true })) found.add(`${input}/${file.replaceAll("\\", "/")}`);
+  }
+  // Companion conventions (the Flow lifecycle) live outside this package but still shape findings.
+  for (const { path } of Object.values(profileConventions).flat()) found.add(path);
+  return [...found].sort();
+}
+async function computeToolkitIdentity(): Promise<ToolkitIdentity> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  for (const file of await toolkitFiles()) { const full = resolve(packageRoot, file); hasher.update(`${file}\0`).update(existsSync(full) ? await readFile(full) : "\0missing").update("\0"); }
+  const version = (JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")) as { version?: unknown }).version;
+  return { version: typeof version === "string" ? version : "unknown", digest: hasher.digest("hex") };
+}
+let identity: Promise<ToolkitIdentity> | undefined;
+/** The running toolkit's package version and a digest of every detector/convention input, computed once per process. */
+export function toolkitIdentity(): Promise<ToolkitIdentity> { return identity ??= computeToolkitIdentity(); }
+const cachedEntry = (text: string, key: string): FindingIdentity[] | null => {
+  const entry = JSON.parse(text) as { schema?: unknown; key?: unknown; findings?: unknown };
+  if (entry?.schema !== "atdd-bun.findings-cache/v1" || JSON.stringify(entry.key) !== key || !Array.isArray(entry.findings)) return null;
+  const valid = entry.findings.every(finding => finding && typeof finding.rule_id === "string" && typeof finding.file === "string" && findingFingerprint(finding));
+  return valid ? entry.findings : null;
+};
+/** Findings for one exact tree: reuse a valid entry, otherwise compute and record the result for the next push. */
+async function cachedFindings(directory: string | null, tree: string, toolkit: ToolkitIdentity | null, profiles: string[], compute: () => Promise<FindingIdentity[]>): Promise<FindingIdentity[]> {
+  if (!directory || !toolkit || !/^[0-9a-f]{40}$/i.test(tree)) return compute();
+  const key = JSON.stringify({ schema: "atdd-bun.findings-cache-key/v1", tree: tree.toLowerCase(), version: toolkit.version, digest: toolkit.digest, profiles: stable(profiles) });
+  const file = join(directory, `${new Bun.CryptoHasher("sha256").update(key).digest("hex")}.json`);
+  const hit = await readFile(file, "utf8").then(text => cachedEntry(text, key)).catch(() => null);
+  if (hit) return hit;
+  const findings = await compute(), scratch = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  await mkdir(directory, { recursive: true }).then(() => writeFile(scratch, JSON.stringify({ schema: "atdd-bun.findings-cache/v1", key: JSON.parse(key), findings }))).then(() => rename(scratch, file)).catch(() => rm(scratch, { force: true }));
+  return findings;
+}
+
 async function ratchetPushGate(root: string, remoteBase: string, candidate: string, protectedBranches: string[], remote: string | undefined): Promise<{ ok: boolean; message: string } | null> {
   let base = remoteBase;
   if (!/^[0-9a-f]{40}$/i.test(candidate)) return bad("ratchet reject-new requires an exact local candidate commit");
@@ -213,13 +257,17 @@ async function ratchetPushGate(root: string, remoteBase: string, candidate: stri
       // Only a protected tip judged under the same profile/context as the candidate is comparable; otherwise the remote tip alone decides.
       if (contextDigest(protectedConfig, candidateProfiles) === contextDigest(candidateConfig, candidateProfiles)) protectedUsed = protectedBase;
     }
-    const [baseFindings, candidateFindings, protectedFindings] = await Promise.all([
-      enforce({ root: baseRoot, profiles: candidateProfiles as any }),
-      enforce({ root: candidateRoot, profiles: candidateProfiles as any }),
-      protectedUsed ? enforce({ root: protectedRoot, profiles: candidateProfiles as any }) : Promise.resolve([]),
-    ]);
-    const carriedBase = [...normalize(baseFindings, baseRoot), ...normalize(protectedFindings, protectedRoot)];
-    const delta = compareFindings(carriedBase, normalize(candidateFindings, candidateRoot));
+    // Findings of an exact tree are reused across pushes; uncached enforcements run one at a time to cap peak processes.
+    const common = await git(root, ["rev-parse", "--git-common-dir"]), cacheDirectory = common.code || !common.out ? null : join(resolve(root, common.out), "atdd-bun", "findings-cache");
+    const toolkit = await toolkitIdentity().catch(() => null);
+    const findingsAt = async (directory: string, commit: string) => {
+      const tree = await git(root, ["rev-parse", "--verify", `${commit}^{tree}`]);
+      return cachedFindings(cacheDirectory, tree.code ? "" : tree.out, toolkit, candidateProfiles, async () => normalize(await enforce({ root: directory, profiles: candidateProfiles as any }), directory));
+    };
+    const baseFindings = await findingsAt(baseRoot, base);
+    const protectedFindings = protectedUsed ? await findingsAt(protectedRoot, protectedUsed) : [];
+    const candidateFindings = await findingsAt(candidateRoot, candidate);
+    const delta = compareFindings([...baseFindings, ...protectedFindings], candidateFindings);
     return { ok: delta.new.length === 0, message: JSON.stringify({ schema: "atdd-bun.ratchet-report/v1", mode: policy.mode, base, ...(protectedUsed ? { protected_base: protectedUsed } : {}), candidate, profiles: candidateProfiles, context: contextDigest(candidateConfig, candidateProfiles), ...delta }) };
   } catch (error) { return bad(`ratchet pre-push gate failed closed: ${String(error)}`); }
   finally {