@afokapu/atdd-bun 0.10.50 → 0.10.51

package/README.md

@@ -122,6 +122,27 @@ release: { enabled: false }
 
 When enabled without overrides, a primary checkout at `~/Github/<repo>` uses linked worktrees at `~/Github/worktrees/<repo>/<branch>`. The defaults use `primary_directory: .` (the current primary checkout) and `root: ../worktrees/{repo}`; `{repo}` expands to the primary checkout's directory name. Repositories that need another layout can set either field explicitly.
 
+## Exact-base finding ratchet (opt-in)
+
+Strict enforcement is the default: `bun run atdd-bun all` still fails for every finding. A consumer may opt into an exact-base comparison for one explicit profile set:
+
+```yaml
+# atdd-bun.yaml
+ratchet:
+  mode: report       # or reject-new
+  profiles: [coder, tester]
+```
+
+Run it only against a full reviewed base SHA:
+
+```sh
+bun run atdd-bun coder tester --ratchet --base <40-character-reviewed-main-sha>
+```
+
+The command runs the same installed detectors against an isolated exact base and the clean candidate, emits a redacted JSON `carried`/`new`/`resolved` fingerprint report, and never writes or accepts a baseline. `report` records debt without changing command success; `reject-new` exits non-zero only when the candidate adds a finding absent from the equivalent base. The declared `ratchet.profiles` must exactly match the command's effective profiles. Base and candidate profile/context digests must match or comparison fails closed; profile/config adoption is separately governed. Use debt-remediation branches to remove carried findings. Direct implementation profiles can opt in only through this explicit policy and do not alter configured merge profiles or `profiles:`.
+
+Fingerprints are SHA-256 of a versioned rule, normalized repository-relative path, and semantic subject where supplied; line/column, rendered evidence, source text, absolute paths, and runtime data are excluded. Ratchet findings are unrelated to Bun `test.failing()` or JUnit/behavioral-test baselines.
+
 ## Docs-site theme
 
 A repository that publishes its AsciiDoc docs as a site does not need its own theme.

package/integrity.json

@@ -1,9 +1,9 @@
 {
-  "version": "0.10.50",
+  "version": "0.10.51",
   "files": {
     "HOOK_AUDIT.md": "5329d840db37671b1918f688ead26865473b87db73dbc75f7c8b2a8bbe8d6d43",
     "PLANNER_PORT.md": "fb5935bac8b7ac18994de21e43ace3a5ef8cd55f85b0e3349fca261280054f11",
-    "README.md": "91e481217865f4bbb2711d89f02ce095cd2f60414b00b10e4874bfadb363e10b",
+    "README.md": "16cac8c84aa9b11018b4b1cc2984faa74c06bee1d7ce1360fb234154bbce2d9f",
     "bunfig.toml": "b9fc65eca9014c5179380259d70e76385a6a80788fa9a2df5fb3eaa5554fd2fe",
     "conventions/_profiles/architecture.yaml": "f1808768b720a4e476047e4a0912002ca673946562cea9aeef5d0c214828d93a",
     "conventions/_profiles/coder.yaml": "3fb191556a64c9ebcf249516afa189afca24da9b22fd40b2fc66908196cdfb78",
@@ -1195,7 +1195,7 @@
     "relationships.yaml": "5860a308ebc3ee7fa8172fc2c6633984000ab3003f0ae4b6fa28db48879eda22",
     "src/agent.ts": "39ca8b3183063c60e00eb96e5629d0397aeb83cc82d4c4bc32c01715c906649b",
     "src/ci.ts": "67e54d2cbfc44a9e42837d5e750af526d6255c539d3c452a4d5fca3226c0d9ac",
-    "src/cli.ts": "521aa363813f84877a97189d1a629b5db26c22f672e0386fb88f26d540918414",
+    "src/cli.ts": "8f5d69bdd5940c7213f8b7c342fd94c1dc9387d56dad7458ce6e9286d88181d3",
     "src/docs-capability.ts": "bdeeb414649049b1cd4fa8008cada3a576318be51c43bec91bfa46a8e250c270",
     "src/enforce.ts": "7e6b3a1fc7c90f8e1836ab3e4655778fb569a63be5e7c199de44024fc003e6be",
     "src/hooks.ts": "0b4ca8c857e637bbd144e737e78eda924e3cba7b038c0abe5e6916d200d73068",
@@ -1206,6 +1206,7 @@
     "src/planner-schema-validator.ts": "ce529c0936171075e93c7539b3655fe895a98dd2973ebda5775958e6ebc316d9",
     "src/planner-validators.ts": "99adeb65f579af923c11f21a8f55cfb9993b007fd8df59c5f764696b55379cfc",
     "src/profile-registry.ts": "5a7761d324181ae27deb51f198d63648a4c99e858b4de98b54d35e6cf8a39fe7",
+    "src/ratchet.ts": "c4ebf34350bc3909db93754f2c92de065325763859bd3040dfaf3d6b204ef33e",
     "src/register.ts": "6a2f1c6b8df0dc9c8f45df8ec9fac2be29044e048b08c8ffe423410e94dadedd",
     "src/release.ts": "7b0fe444ee81f476f53b9c21b6c347ef588ee616c60211419cf984132be768ba",
     "src/setup.ts": "38233265afedc63499bbef3b5403889651add335a70efd3813254ba53f4fc4fe",

package/package.json

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

package/src/cli.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env bun
-import { enforce, flowCompatibilityDiagnostic, normalizeProfileName, profileNames, type Profile } from "./enforce";
+import { enforce, enabledProfiles, flowCompatibilityDiagnostic, normalizeProfileName, profileNames, type Profile } from "./enforce";
+import { compareFindings, contextDigest, parseRatchetPolicy } from "./ratchet";
+import { existsSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
 import { agentInit, agentStatus } from "./agent";
@@ -14,7 +19,7 @@ const args = process.argv.slice(2);
 const usage = {
   command: "atdd-bun",
   usage: [
-    "atdd-bun [profile ...] [--root <path>]",
+    "atdd-bun [profile ...] [--root <path>] [--ratchet --base <full-sha>]",
     "atdd-bun init [--replace]",
     "atdd-bun hooks <install|uninstall|status> [--replace]",
     "atdd-bun worktree <start|finish|status>",
@@ -109,10 +114,11 @@ if (args[0] === "release") {
 const valueAfter = (flag: string) => args[args.indexOf(flag) + 1];
 const root = args.includes("--root") ? valueAfter("--root") : process.cwd();
 if (args.includes("--root") && !root) fail("--root requires a path");
+if (args.includes("--base") && !valueAfter("--base")) fail("--base requires a full commit SHA");
 const positional: string[] = [];
 for (let index = 0; index < args.length; index += 1) {
   const arg = args[index];
-  if (arg === "--root" || arg === "--profile") { index += 1; continue; }
+  if (arg === "--root" || arg === "--profile" || arg === "--base") { index += 1; continue; }
   if (!arg.startsWith("-")) positional.push(arg);
 }
 const profileValue = args.includes("--profile") ? valueAfter("--profile") : undefined;
@@ -122,9 +128,55 @@ const normalizedRequested = requested.map(normalizeProfileName);
 const invalid = normalizedRequested.find(profile => !profileNames.includes(profile as Profile));
 if (invalid) fail("unknown command or profile: " + invalid);
 if (requested.includes("workflow")) console.error(flowCompatibilityDiagnostic);
-const violations = await enforce({ root, profiles: normalizedRequested as Profile[] });
-for (const violation of violations) {
-  console.error([violation.file, violation.line, violation.col].join(":") + " " + violation.rule_id + " — " + violation.evidence);
+const printViolations = (violations: Awaited<ReturnType<typeof enforce>>) => {
+  for (const violation of violations) console.error([violation.file, violation.line, violation.col].join(":") + " " + violation.rule_id + " — " + violation.evidence);
+};
+const configAt = async (directory: string) => {
+  const file = join(directory, "atdd-bun.yaml");
+  return existsSync(file) ? Bun.YAML.parse(await readFile(file, "utf8")) as Record<string, unknown> : {};
+};
+const git = async (directory: string, gitArgs: string[]) => {
+  const child = Bun.spawn({ cmd: ["git", ...gitArgs], cwd: directory, stdout: "pipe", stderr: "pipe" });
+  return { code: await child.exited, out: (await new Response(child.stdout).text()).trim(), err: (await new Response(child.stderr).text()).trim() };
+};
+const stable = (items: string[]) => [...new Set(items)].sort();
+if (!args.includes("--ratchet")) {
+  const violations = await enforce({ root, profiles: normalizedRequested as Profile[] });
+  printViolations(violations);
+  if (violations.length) console.error("\nUse the rule ID and evidence above to correct the affected artifact. Run atdd-bun help for commands and profiles.");
+  process.exitCode = violations.length ? 1 : 0;
+} else {
+  const base = valueAfter("--base");
+  if (!base || !/^[0-9a-f]{40}$/i.test(base)) fail("--ratchet requires --base <full-40-character-sha>");
+  const candidateRoot = resolve(root), candidateConfig = await configAt(candidateRoot), policy = parseRatchetPolicy(candidateConfig);
+  if (!policy) fail("--ratchet requires an explicit atdd-bun.yaml ratchet policy");
+  const candidateProfiles = normalizedRequested.includes("all") ? await enabledProfiles(candidateRoot) : normalizedRequested;
+  if (stable(policy.profiles).join(",") !== stable(candidateProfiles).join(",")) fail("ratchet.profiles must exactly equal the selected profiles");
+  if ((await git(candidateRoot, ["status", "--porcelain"])).out) fail("--ratchet requires a porcelain-clean candidate worktree");
+  const resolved = await git(candidateRoot, ["rev-parse", "--verify", `${base}^{commit}`]);
+  if (resolved.code || resolved.out.toLowerCase() !== base.toLowerCase()) fail(`ratchet base ${base} is unavailable or not a full exact commit`);
+  if ((await git(candidateRoot, ["merge-base", "--is-ancestor", base, "HEAD"])).code !== 0) fail("ratchet base must be an ancestor of candidate HEAD");
+  const scratch = await mkdtemp(join(tmpdir(), "atdd-ratchet-"));
+  try {
+    const added = await git(candidateRoot, ["worktree", "add", "--detach", "--no-checkout", scratch, base]);
+    if (added.code) { console.error(`could not materialize ratchet base: ${added.err || added.out}`); process.exitCode = 1; }
+    else {
+      const checkedOut = await git(scratch, ["checkout", "--detach", base]);
+      if (checkedOut.code) { console.error(`could not checkout ratchet base: ${checkedOut.err || checkedOut.out}`); process.exitCode = 1; }
+      else {
+        const baseConfig = await configAt(scratch), baseProfiles = normalizedRequested.includes("all") ? await enabledProfiles(scratch) : normalizedRequested;
+        if (stable(baseProfiles).join(",") !== stable(candidateProfiles).join(",") || contextDigest(baseConfig, baseProfiles) !== contextDigest(candidateConfig, candidateProfiles)) { console.error("ratchet base and candidate profile/context differ; use a separately governed adoption path"); process.exitCode = 1; }
+        else {
+          const [baseFindings, candidateFindings] = await Promise.all([enforce({ root: scratch, profiles: candidateProfiles as Profile[] }), enforce({ root: candidateRoot, profiles: candidateProfiles as Profile[] })]);
+          const normalize = (findings: Awaited<ReturnType<typeof enforce>>, directory: string) => findings.map(finding => ({ ...finding, file: relative(directory, finding.file).replaceAll("\\", "/") }));
+          const delta = compareFindings(normalize(baseFindings, scratch), normalize(candidateFindings, candidateRoot));
+          console.log(JSON.stringify({ schema: "atdd-bun.ratchet-report/v1", mode: policy.mode, base, candidate: (await git(candidateRoot, ["rev-parse", "HEAD"])).out, profiles: stable(candidateProfiles), context: contextDigest(candidateConfig, candidateProfiles), ...delta }, null, 2));
+          if (policy.mode === "reject-new" && delta.new.length) process.exitCode = 1;
+        }
+      }
+    }
+  } finally {
+    await git(candidateRoot, ["worktree", "remove", "--force", scratch]);
+    await rm(scratch, { recursive: true, force: true });
+  }
 }
-if (violations.length) console.error("\nUse the rule ID and evidence above to correct the affected artifact. Run atdd-bun help for commands and profiles.");
-process.exitCode = violations.length ? 1 : 0;

package/src/ratchet.ts

@@ -0,0 +1,54 @@
+/** Pure v1 primitives for the opt-in exact-base finding ratchet. No baseline is written or accepted. */
+export type RatchetMode = "report" | "reject-new";
+export type RatchetPolicy = { mode: RatchetMode; profiles: string[] };
+export type FindingIdentity = {
+  rule_id: string;
+  file: string;
+  subject?: string;
+  line?: number;
+  col?: number;
+  evidence?: string;
+  source_line?: string;
+};
+
+const canonical = (value: unknown): string => {
+  if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (typeof value === "object") return `{${Object.entries(value as Record<string, unknown>).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(",")}}`;
+  throw new Error(`cannot canonicalize ${typeof value}`);
+};
+const sha256 = (value: unknown) => new Bun.CryptoHasher("sha256").update(canonical(value)).digest("hex");
+const normalizedPath = (path: string) => {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized) || normalized.split("/").includes("..")) throw new Error(`ratchet finding path must be normalized and repository-relative: ${path}`);
+  return normalized;
+};
+
+/** Stable semantic identity: presentation position and rendered evidence deliberately do not participate. */
+export function findingFingerprint(finding: FindingIdentity): string {
+  const path = normalizedPath(finding.file), subject = finding.subject ?? path;
+  if (!finding.rule_id || !subject) throw new Error("ratchet finding requires rule_id and semantic subject");
+  return sha256({ format: "atdd-bun.finding-fingerprint/v1", rule_id: finding.rule_id, path, subject });
+}
+
+/** The selected profiles and every policy key except ratchet itself must agree across exact base and candidate. */
+export function contextDigest(config: Record<string, unknown>, profiles: string[]): string {
+  const { ratchet: _ratchet, ...policy } = config;
+  return sha256({ format: "atdd-bun.ratchet-context/v1", profiles: [...profiles].sort(), policy });
+}
+
+export function parseRatchetPolicy(config: Record<string, unknown>): RatchetPolicy | null {
+  if (config.ratchet === undefined) return null;
+  const value = config.ratchet;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("atdd-bun.yaml ratchet must be a mapping");
+  const mode = (value as Record<string, unknown>).mode, profiles = (value as Record<string, unknown>).profiles;
+  if (mode !== "report" && mode !== "reject-new") throw new Error("atdd-bun.yaml ratchet.mode must be report or reject-new");
+  if (!Array.isArray(profiles) || !profiles.length || !profiles.every(profile => typeof profile === "string")) throw new Error("atdd-bun.yaml ratchet.profiles must be a non-empty list of profile names");
+  return { mode, profiles: [...new Set(profiles)].sort() };
+}
+
+export function compareFindings(base: FindingIdentity[], candidate: FindingIdentity[]) {
+  const baseSet = new Set(base.map(findingFingerprint)), candidateSet = new Set(candidate.map(findingFingerprint));
+  const list = (source: Set<string>, absent: Set<string>) => [...source].filter(item => !absent.has(item)).sort();
+  return { carried: [...baseSet].filter(item => candidateSet.has(item)).sort(), new: list(candidateSet, baseSet), resolved: list(baseSet, candidateSet) };
+}