@afokapu/atdd-bun 0.10.92 → 0.10.94

package/detectors/bun_tester_discipline_detector/test_header.mjs

@@ -25,19 +25,10 @@
 // suite. Both levels are parsed here.
 import { excludedPath } from "../../lib/scan.mjs";
 import { readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, join, extname, sep } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 
 export const DEFAULT_EXCLUDES = ["node_modules", "dist", "build", ".next", ".git", "_generated"];
 export const TEST_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
-
-// atdd-bun generates atdd-bun.integrity.test.ts and forbids editing it, so no tester rule judges it. It is recognised by
-// its content, the package's template with the version filled in, never by name or header: a copy of either earns nothing.
-const INTEGRITY_TEMPLATE = (() => { try { return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../templates/agents/atdd-bun.integrity.test.ts"), "utf8"); } catch { return null; } })();
-function isGeneratedIntegrityTest(path) {
-  if (!INTEGRITY_TEMPLATE || !path.endsWith("atdd-bun.integrity.test.ts")) return false;
-  try { return readFileSync(path, "utf8").replace(/^(\/\/ Generated by @afokapu\/atdd-bun )\S+?(\. Do not edit)/, "$1{{VERSION}}$2") === INTEGRITY_TEMPLATE; } catch { return false; }
-}
 export const PHASES = new Set(["RED", "UNIT", "SMOKE", "E2E"]);
 export const LAYERS = new Set(["domain", "application", "integration", "presentation", "assembly"]);
 
@@ -59,7 +50,7 @@ function isExcluded(path, excludes) {
 export function* walkTests(root, excludes) {
   let st;
   try { st = statSync(root); } catch { return; }
-  if (st.isFile()) { if (TEST_RE.test(root) && !isGeneratedIntegrityTest(root)) yield root; return; }
+  if (st.isFile()) { if (TEST_RE.test(root)) yield root; return; }
   let names;
   try { names = readdirSync(root); } catch { return; }
   for (const name of names) {
@@ -68,7 +59,7 @@ export function* walkTests(root, excludes) {
     let cst;
     try { cst = statSync(full); } catch { continue; }
     if (cst.isDirectory()) yield* walkTests(full, excludes);
-    else if (TEST_RE.test(full) && !isGeneratedIntegrityTest(full)) yield full;
+    else if (TEST_RE.test(full)) yield full;
   }
 }
 

package/integrity.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.10.92",
+  "version": "0.10.94",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
@@ -711,7 +711,7 @@
     "detectors/bun_tester_discipline_detector/fixtures/dirty/unresolvable_binding.test.ts": "fd878356127cd66c05a1ab2c461982366f3a757895decf19cf24634f2c476d44",
     "detectors/bun_tester_discipline_detector/fixtures/dirty/vacuous.red.test.ts": "deea6befc7f87aa54b52df40f1032e4b547cb1336da3aec985c76aeb5097364a",
     "detectors/bun_tester_discipline_detector/fixtures/dirty/wrongruntime.test.ts": "041e421ef2b2810545020b5945733822dcae416d3360657217d3bab901cc2cdd",
-    "detectors/bun_tester_discipline_detector/test_header.mjs": "f66c371c6428eccc88b2d336e5960b44dbe3b3e81bc3eb48d3ba78d889ba6a70",
+    "detectors/bun_tester_discipline_detector/test_header.mjs": "830f85456da04bfcb74332ecf7419373a9802ef42f04aa9ea06e2ba9206bfc03",
     "detectors/bun_ts_metrics_detector/atdd.implementation.yaml": "6ced804a5fdc82b6cd52be21ebacefa5d3261fca03a391178b2bf21186776364",
     "detectors/bun_ts_metrics_detector/checks/_map.json": "ed7c198564a80252f92e8ba2f50352daa1476ea88a23bfc0b3630e58c688f95d",
     "detectors/bun_ts_metrics_detector/checks/ts_complexity_cyclomatic.mjs": "56640b3a0f565c45a73b7c174adb1d6b4b6ac24d286a907bc1426f013cd6039e",
@@ -1263,7 +1263,7 @@
     "src/enforce.ts": "e0c10519aeecd7080f2900ea230fad2f09482af47c1cee885d5de71573e29732",
     "src/hooks.ts": "b96b5fee3a03c2f4c317d6725d6d21ed3133db18d0cdcdda72183cf05c7b6639",
     "src/index.ts": "4081f8b08d1d3ee9e15a9964143e53d9cfb94a5616ab3e58a180d24cc16dc381",
-    "src/integrity.ts": "19066185f99839c9e95c57f9bfbcd34df58cf8f4c33de86264c89e03b1085abf",
+    "src/integrity.ts": "f1ede7cb04924ae88e11917047277e264af6596b9759e381bd9c497cd34a797d",
     "src/journey-docs.ts": "994d229376244c84212cff951032823068a76565dd2fd427b9d44e341bd14853",
     "src/planner-kernel.ts": "5d3f5305fb59becb2cc97d8a03aca6b104f385805d91cc0410856e289dd6fbb1",
     "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
@@ -1276,7 +1276,8 @@
     "src/telemetry-plan.ts": "cdb1e8bfff414f3ea81977388973da2cf6d89567d9e060dc9d5989a33600f153",
     "src/topology.ts": "9779ee48e1c453abb76363163d4ab363463fa14e359571139f6d1f1fcc51ae2c",
     "templates/agents/AGENTS.block.md": "84d19dfabedb1e05ccfb7b19a38644e87f193ae2b74755897f75f13971bb687e",
-    "templates/agents/atdd-bun.integrity.test.ts": "76eb5f59c50d2fc3f4835c0adf85db4046597c25b1deb0432e6acb2ee1a617d8",
+    "templates/agents/atdd-bun.integrity.acceptance.yaml": "3fec7c6236c9bf7a5af2a9aeba2dc62e48319f38157a37a69b41cca675277d92",
+    "templates/agents/atdd-bun.integrity.test.ts": "15ba901c49792427f790255f7b28b55a61ef955bd101209cbe087d8421ad666f",
     "templates/docs/site.css": "482b3427e3a3cb02a85dc85cfbeac80592dfd53abf42fc92d6ea7071f22afc95",
     "templates/github/atdd-bun-release.yml": "d9547e9e6ef3ae010d53d55314f6a54567f88bd900f7e50d994cd308601d2684",
     "templates/github/atdd-bun.yml": "6b766ae25ac86f3c87c91b31726461d0ba13d3383e55bbc9c9d1fe79ec26fcba"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.10.92",
+  "version": "0.10.94",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"
@@ -35,7 +35,7 @@
     "bun": ">=1.3.0"
   },
   "dependencies": {
-    "@afokapu/atdd-flow": "^0.3.41",
+    "@afokapu/atdd-flow": "^0.3.49",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "typescript": "6.0.3"

package/src/integrity.ts

@@ -1,9 +1,10 @@
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { instructionPaths } from "./agent";
 import { renderWorkflow } from "./ci";
 import { defaultHookPolicy, enforcementIdentity, hookEvents, hooksStatus, isToolkitSourceCheckout, lockedToolkit, renderHook, type HookPolicy } from "./hooks";
+import { topologyFor } from "./topology";
 
 /**
  * Integrity: the files an agent could change to weaken enforcement must stay canonical.
@@ -18,6 +19,10 @@ const PACKAGE = "@afokapu/atdd-bun";
 const ownRoot = resolve(import.meta.dir, "..");
 export const MANIFEST = "integrity.json";
 export const TEST_FILE = "atdd-bun.integrity.test.ts";
+export const CATALOG_FILE = "atdd-bun.integrity.acceptance.yaml";
+const INTEGRITY_ACCEPTANCE = "acc:atdd-bun:E001-UNIT-001-enforcement-surfaces-canonical";
+const CATALOG_MARKER = "# atdd-bun generated integrity catalog";
+const CATALOG_POINTER = "// atdd-bun integrity catalog: ";
 const WORKFLOW = ".github/workflows/atdd-bun.yml";
 const BLOCK = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->/;
 // Agent blocks are guidance rather than enforcement surfaces, so their writer version remains upgrade-tolerant.
@@ -31,6 +36,10 @@ export async function testFilePath(repo: string) {
   const root = text.split(/^\[/m).find(section => section.startsWith("test]"))?.match(/^\s*root\s*=\s*["']([^"']+)["']/m)?.[1];
   return join(repo, root ?? ".", TEST_FILE);
 }
+/** Where the generated integrity test's acceptance is declared: beneath the configured plan root. */
+export async function catalogFilePath(repo: string) {
+  return join(repo, (await topologyFor(repo)).planRoot, CATALOG_FILE);
+}
 const git = async (root: string, args: string[]) => { const child = Bun.spawn({ cmd: ["git", ...args], cwd: root, stdout: "pipe", stderr: "pipe" }); const out = (await new Response(child.stdout).text()).trim(); return { code: await child.exited, out }; };
 
 async function filesBelow(dir: string, base = dir): Promise<string[]> {
@@ -92,26 +101,43 @@ async function checkDependency(root: string): Promise<IntegrityFinding[]> {
   return findings;
 }
 
-async function renderIntegrityTest(root: string, packageRoot: string) {
+async function renderIntegrityPair(root: string, packageRoot: string) {
   const version = (await Bun.file(join(packageRoot, "package.json")).json() as { version: string }).version;
-  const { digest } = await enforcementIdentity(root);
-  return (await readFile(join(packageRoot, "templates/agents/atdd-bun.integrity.test.ts"), "utf8")).replace("{{VERSION}}", version).replace("{{IDENTITY}}", digest);
+  const { digest } = await enforcementIdentity(root), catalogPath = await catalogFilePath(root);
+  const catalog = relative(root, catalogPath).split(sep).join("/");
+  const render = async (file: string) => (await readFile(join(packageRoot, "templates/agents", file), "utf8"))
+    .replaceAll("{{VERSION}}", version).replaceAll("{{IDENTITY}}", digest).replaceAll("{{CATALOG}}", catalog);
+  return { test: await render(TEST_FILE), catalog: await render(CATALOG_FILE), catalogPath };
+}
+
+type Surface = { file: string; path: string; expected: (() => Promise<string>) | null };
+const RESTORE_GENERATED = "bun run atdd-bun init --replace";
+
+/** A generated surface is missing, or, when an expected rendering is given, stale against it. */
+async function surfaceFinding({ file, path, expected }: Surface): Promise<IntegrityFinding | null> {
+  if (!existsSync(path)) return { file, detail: "is missing", restore: RESTORE_GENERATED };
+  if (expected && canonical(await readFile(path, "utf8")) !== canonical(await expected())) return { file, detail: "is stale; it must match the exact lock/config/profile identity", restore: RESTORE_GENERATED };
+  return null;
+}
+
+/** The catalog path comes from the configured plan root, or, uncompared, only from the generated test's exact pointer. */
+async function integrityCatalogPath(root: string, testPath: string, pair: { catalogPath: string } | null) {
+  if (pair) return pair.catalogPath;
+  return existsSync(testPath) ? priorCatalogPath(root, await readFile(testPath, "utf8")) : null;
 }
 
 /** The generated enforcement surfaces are byte-identical to this exact lock/config/profile identity. */
 async function checkEnforcementGenerated(root: string, packageRoot: string, compare = true): Promise<IntegrityFinding[]> {
-  const findings: IntegrityFinding[] = [], restore = "bun run atdd-bun init --replace";
-  for (const event of hookEvents) {
-    const file = `.githooks/${event}`, path = join(root, file);
-    if (!existsSync(path)) findings.push({ file, detail: "is missing", restore });
-    else if (compare && canonical(await readFile(path, "utf8")) !== canonical(await renderHook(event, root))) findings.push({ file, detail: "is stale; it must match the exact lock/config/profile identity", restore });
-  }
-  const workflow = join(root, WORKFLOW);
-  if (!existsSync(workflow)) findings.push({ file: WORKFLOW, detail: "is missing", restore });
-  else if (compare && canonical(await readFile(workflow, "utf8")) !== canonical(await renderWorkflow(root))) findings.push({ file: WORKFLOW, detail: "is stale; it must match the exact lock/config/profile identity", restore });
-  const test = relative(root, await testFilePath(root)), testPath = join(root, test);
-  if (!existsSync(testPath)) findings.push({ file: test, detail: "is missing", restore });
-  else if (compare && canonical(await readFile(testPath, "utf8")) !== canonical(await renderIntegrityTest(root, packageRoot))) findings.push({ file: test, detail: "is stale; it must match the exact lock/config/profile identity", restore });
+  // Without comparison the config may be unreadable: render nothing that depends on it, only check presence.
+  const pair = compare ? await renderIntegrityPair(root, packageRoot) : null;
+  const surfaces: Surface[] = hookEvents.map(event => ({ file: `.githooks/${event}`, path: join(root, ".githooks", event), expected: compare ? () => renderHook(event, root) : null }));
+  surfaces.push({ file: WORKFLOW, path: join(root, WORKFLOW), expected: compare ? () => renderWorkflow(root) : null });
+  const testPath = await testFilePath(root);
+  surfaces.push({ file: relative(root, testPath), path: testPath, expected: pair ? async () => pair.test : null });
+  const catalogPath = await integrityCatalogPath(root, testPath, pair);
+  if (catalogPath) surfaces.push({ file: relative(root, catalogPath).split(sep).join("/"), path: catalogPath, expected: pair ? async () => pair.catalog : null });
+  const findings: IntegrityFinding[] = [];
+  for (const surface of surfaces) { const finding = await surfaceFinding(surface); if (finding) findings.push(finding); }
   return findings;
 }
 
@@ -278,12 +304,42 @@ export function formatIntegrity(findings: IntegrityFinding[]): string {
   ].join("\n");
 }
 
-/** Write the generated integrity test into a repository. */
+function priorCatalogPath(root: string, generatedTest: string): string | null {
+  const pointer = generatedTest.split(/\r?\n/).find(line => line.startsWith(CATALOG_POINTER))?.slice(CATALOG_POINTER.length);
+  if (!pointer || pointer.startsWith("/") || pointer.replaceAll("\\", "/").split("/").includes("..") || basename(pointer) !== CATALOG_FILE) return null;
+  const path = resolve(root, pointer);
+  return path.startsWith(`${resolve(root)}${sep}`) ? path : null;
+}
+
+function isOwnedCatalog(text: string): boolean {
+  return text.includes(CATALOG_MARKER) && text.includes(`urn: ${INTEGRITY_ACCEPTANCE}`) && text.startsWith("# Generated by @afokapu/atdd-bun ");
+}
+
+/** Write the generated integrity test and its plan binding into a repository. */
 export async function integrityInit(repo = process.cwd(), replace = false) {
-  const output = await testFilePath(repo);
+  const root = resolve(repo), output = await testFilePath(root);
   if (existsSync(output) && !replace) return { ok: false, message: `${output} exists; use --replace` };
+  const previous = existsSync(output) ? priorCatalogPath(root, await readFile(output, "utf8")) : null;
+  const pair = await renderIntegrityPair(root, ownRoot);
+  if (previous && previous !== pair.catalogPath && existsSync(previous)) {
+    const text = await readFile(previous, "utf8").catch(() => "");
+    if (isOwnedCatalog(text)) await rm(previous);
+  }
   await mkdir(dirname(output), { recursive: true });
-  await writeFile(output, await renderIntegrityTest(repo, ownRoot));
+  await mkdir(dirname(pair.catalogPath), { recursive: true });
+  await writeFile(pair.catalogPath, pair.catalog);
+  await writeFile(output, pair.test);
   return { ok: true, message: output };
 }
-export async function integrityStatus(repo = process.cwd()) { const output = await testFilePath(repo); if (!existsSync(output)) return { ok: false, message: `${output} is missing; run: bun run atdd-bun init --replace` }; try { return canonical(await readFile(output, "utf8")) === canonical(await renderIntegrityTest(repo, ownRoot)) ? { ok: true, message: output } : { ok: false, message: `${output} is stale; run: bun run atdd-bun init --replace` }; } catch (error) { return { ok: false, message: `${output} cannot be verified: ${String(error)}; run: bun run atdd-bun init --replace` }; } }
+export async function integrityStatus(repo = process.cwd()) {
+  const root = resolve(repo), output = await testFilePath(root);
+  if (!existsSync(output)) return { ok: false, message: `${output} is missing; run: bun run atdd-bun init --replace` };
+  try {
+    const pair = await renderIntegrityPair(root, ownRoot);
+    if (canonical(await readFile(output, "utf8")) !== canonical(pair.test)) return { ok: false, message: `${output} is stale; run: bun run atdd-bun init --replace` };
+    if (!existsSync(pair.catalogPath)) return { ok: false, message: `${pair.catalogPath} is missing; run: bun run atdd-bun init --replace` };
+    return canonical(await readFile(pair.catalogPath, "utf8")) === canonical(pair.catalog)
+      ? { ok: true, message: output }
+      : { ok: false, message: `${pair.catalogPath} is stale; run: bun run atdd-bun init --replace` };
+  } catch (error) { return { ok: false, message: `${output} cannot be verified: ${String(error)}; run: bun run atdd-bun init --replace` }; }
+}

package/templates/agents/atdd-bun.integrity.acceptance.yaml

@@ -0,0 +1,27 @@
+# Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun init --replace`.
+# atdd-bun enforcement identity: {{IDENTITY}}
+# atdd-bun generated integrity catalog
+acceptances:
+  - identity:
+      urn: acc:atdd-bun:E001-UNIT-001-enforcement-surfaces-canonical
+      id: E001-UNIT-001-enforcement-surfaces-canonical
+      purpose: Verify the installed toolkit, policy, and generated enforcement surfaces remain canonical.
+      phase: GREEN
+    harness:
+      type: unit
+      category: backend
+      language_hint: typescript
+    given:
+      abstract:
+        - The repository has installed ATDD Bun and generated its enforcement surfaces.
+    when:
+      abstract: The generated integrity test inspects the installed toolkit, policy, and generated files.
+      action: invoke
+      target: registerIntegrityTest
+    then:
+      abstract:
+        - Every protected enforcement surface matches the exact installed package and policy identity.
+      assertions:
+        - type: equals
+          target: integrity finding count
+          value: 0

package/templates/agents/atdd-bun.integrity.test.ts

@@ -1,5 +1,10 @@
 // Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun integrity init --replace`.
 // atdd-bun enforcement identity: {{IDENTITY}}
+// atdd-bun integrity catalog: {{CATALOG}}
+// URN: test:atdd-bun:integrity:E001-UNIT-001-enforcement-surfaces-canonical
+// Acceptance: acc:atdd-bun:E001-UNIT-001-enforcement-surfaces-canonical
+// Phase: UNIT
+// Layer: integration
 // Fails loudly when the installed package, its generated files, or atdd-bun.yaml were changed.
 import { registerIntegrityTest } from "@afokapu/atdd-bun/register";