npm - tamperward - Versions diffs - 1.1.0-rc.2 → 1.2.0 - Mend

tamperward 1.1.0-rc.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -92,15 +92,18 @@ with the same engine it ships.
   per-line old/new line numbers correct across multiple hunks.
 - `src/git/build.ts` — the git adapter: range / staged / worktree views, enriching
   `before`/`after` with full file content for the AST detectors.
-- `src/detectors/` — the **eight mechanical rules**: `no-verify`, `ts-any-cast`,
+- `src/detectors/` — the **nine mechanical rules**: `no-verify`, `ts-any-cast`,
   `lint-suppression`, `test-skip`, `coverage-lowering`, `ci-tampering`,
   `hook-tampering`, `test-deletion` (the last counts `it()/test()` via the TS AST,
-  and handles delete / rename-out-of-glob / shell mutation).
+  and handles delete / rename-out-of-glob / shell mutation), and `snapshot-rewrite`
+  (a `warn`: re-recording a snapshot/golden expectation from current output — the one
+  rule built from measured demand, after the affordance experiment put the move at a
+  70% attempt and 100% through rate; see `harness/PREDICTION-affordance.md`).
 - `src/engine.ts` — runs the enabled rules over `Change[]`; honours `policy.ignore`.
 - `src/cli/` — `tamperward check --staged | --worktree | --diff <base>...<head>`,
   exit 1 on any blocking finding.
-- `test/` — 158 tests, including the AST-vs-regex, self-hosting precision, and
-  pre-go-live audit regression cases.
+- `test/` — 226 tests, including the AST-vs-regex, self-hosting precision, and
+  pre-go-live audit regression cases, and the renderer accessibility contract.
 - `src/adapters/claude/` + `src/cli/hook.ts` — the agent layer: `tamperward hook claude`
   (PreToolUse deny, fail-closed) and `tamperward sweep claude` (Stop sweep, compared against
@@ -120,6 +123,24 @@ npx tamperward check --staged                # pre-commit view
 npx tamperward check --diff "main...HEAD"    # CI view — the authority for main
 ```
+### Reading the verdict
+One verdict, rendered for whoever is reading it. `--format` picks the view; the default,
+`auto`, picks `github` when `GITHUB_ACTIONS=true` and `text` otherwise, so the CI wiring
+stays a single line.
+| Format | Where it goes |
+| --- | --- |
+| `text` | The terminal. Blocking findings first, then by file and line, wrapped to the terminal width. |
+| `github` | An inline annotation per finding — so it lands **on the line** in *Files changed*, not four clicks deep in a job log — plus a job-summary table on the run page. The full text output still goes to the log. |
+| `json` | The findings verbatim, plus a summary count. |
+Severity is always spelled out (`BLOCK` / `warn`) and never carried by colour or a glyph
+alone, so the output reads the same piped, in a CI log, on a colour-blind reader's
+terminal, and through a screen reader. Colour honours
+[`NO_COLOR`](https://no-color.org) and `FORCE_COLOR`, and is off whenever stdout is not a
+terminal.
 From a clone:
 ```bash

package/dist/cli/index.js CHANGED Viewed

@@ -182,7 +182,18 @@ function parseHunk(lines, start) {
 // src/git/build.ts
 function git(args, cwd) {
-  return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (e) {
+    const err = e;
+    const detail = String(err.stderr ?? "").trim();
+    throw new Error(detail ? `git ${args[0]}: ${detail}` : err.message ?? `git ${args[0]} failed`);
+  }
 }
 function blobAt(rev, path, cwd) {
   try {
@@ -414,6 +425,10 @@ function defaultPolicy() {
         "**/package.json"
       ],
       ci: [".github/workflows/**"],
+      // Recorded expected outputs. An assertion stored as data is still an assertion;
+      // rewriting it from current output is the snapshot-update move the affordance
+      // experiment measured at a 70% attempt / 100% through rate (snapshot-rewrite).
+      snapshots: ["**/*.snap", "**/__snapshots__/**", "**/golden/**", "**/*.golden.*"],
       hooks: [".husky/**", "**/lefthook.*", ".tamperward.yml", "**/.tamperward.yml"]
     },
     rules: {
@@ -429,6 +444,9 @@ function defaultPolicy() {
       "ci-tampering": { severity: "block" },
       "hook-tampering": { severity: "block" },
       "no-verify": { severity: "block" },
+      // mechanical but intent-ambiguous: updating a snapshot is the legitimate workflow
+      // when intended output changes. WARN until the §7 evidence path earns block.
+      "snapshot-rewrite": { severity: "warn" },
       // heuristic — warn until precision is measured (SPEC §7)
       "assertion-weakening": { severity: "warn" },
       "guard-removal": { severity: "warn" }
@@ -659,10 +677,14 @@ function underCoverageKey(node) {
   }
   return false;
 }
+function asExpression(src) {
+  const t = src.trim();
+  return t.startsWith("{") ? `(${t})` : src;
+}
 function parseThresholds(src) {
   const res = { paths: /* @__PURE__ */ new Map(), present: false };
   try {
-    const sf = ts2.createSourceFile("cfg.ts", src, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
+    const sf = ts2.createSourceFile("cfg.ts", asExpression(src), ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TS);
     const visit = (node) => {
       if (ts2.isPropertyAssignment(node) && ts2.isObjectLiteralExpression(node.initializer)) {
         const key2 = keyName(node.name);
@@ -1208,6 +1230,63 @@ var testDeletion = {
   }
 };
+// src/detectors/snapshot-rewrite.ts
+var RULE8 = "snapshot-rewrite";
+var RUNNER2 = /\b(?:jest|vitest|playwright|ava)\b/;
+var UPDATE_ANY = /--update-?[sS]napshots?\b/;
+var UPDATE_WITH_RUNNER = /(?:^|\s)(?:-u|--update)(?:\s|$)/;
+var REGEN_SCRIPT = /\b(?:update|regen(?:erate)?|re?bless)[-_.]?(?:golden|snapshots?|baselines?|expected)\b/i;
+var MUTATE = /(?:^|\s)(?:rm|cp|mv|tee|truncate|dd)(?:\s|$)|sed\s+-i|>{1,2}/;
+function namesProtectedSnapshot(seg, policy) {
+  for (const t of tokens(seg)) {
+    const path = unquote(t).replace(/^>{1,2}/, "");
+    if (isProtected(path, policy, "snapshots")) return path;
+  }
+  return null;
+}
+var snapshotRewrite = {
+  id: RULE8,
+  surface: ["command", "file"],
+  certainty: "mechanical",
+  run(changes, policy) {
+    const out = [];
+    const warn = (input) => out.push(makeFinding(RULE8, policy, { ...input, defaultSeverity: "warn" }));
+    for (const c of changes) {
+      if (c.kind === "command") {
+        for (const seg of segments(c.raw)) {
+          let why = null;
+          if (UPDATE_ANY.test(seg)) why = "the snapshot-update flag rewrites every failing snapshot to match current output";
+          else if (RUNNER2.test(seg) && UPDATE_WITH_RUNNER.test(seg)) why = "running the test runner in update mode rewrites failing snapshots to match current output";
+          else if (REGEN_SCRIPT.test(seg)) why = "a regeneration script rewrites the recorded expected output from current output";
+          else {
+            const path = MUTATE.test(seg) ? namesProtectedSnapshot(seg, policy) : null;
+            if (path) why = `the command overwrites or removes the protected snapshot ${path}`;
+          }
+          if (why) {
+            warn({
+              message: `Snapshot rewrite: ${why}.`,
+              evidence: seg,
+              remediation: "A snapshot is an assertion. If the test failure is a bug, fix the code; only update the snapshot when the INTENDED output changed, and have a human confirm the new expectation is correct."
+            });
+          }
+        }
+        continue;
+      }
+      const wasSnap = c.oldPath != null && isProtected(c.oldPath, policy, "snapshots");
+      const isSnap = isProtected(c.path, policy, "snapshots");
+      if (c.op === "add" || !isSnap && !wasSnap) continue;
+      const what = c.op === "delete" ? "deleted" : c.op === "rename" && !isSnap ? `renamed out of the protected snapshot set (to ${c.path})` : "rewritten";
+      warn({
+        file: c.op === "rename" && !isSnap ? c.oldPath : c.path,
+        message: `A recorded expected output was ${what}.`,
+        evidence: c.op === "rename" ? `${c.oldPath} -> ${c.path}` : c.path,
+        remediation: "If the intended output genuinely changed, a human should confirm the new expectation against the requirement; if the test was failing, fix the code instead of re-recording the expectation from it."
+      });
+    }
+    return out;
+  }
+};
 // src/detectors/index.ts
 var allDetectors = [
   noVerify,
@@ -1217,7 +1296,8 @@ var allDetectors = [
   coverageLowering,
   ciTampering,
   hookTampering,
-  testDeletion
+  testDeletion,
+  snapshotRewrite
 ];
 // src/engine.ts
@@ -1362,46 +1442,226 @@ function oobFromEnv(env = process.env) {
   return (env.TAMPERWARD_OOB_SIGNOFF ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 }
-// src/cli/report.ts
-function report(input) {
-  const { findings, scanned, ignoredFiles } = input;
-  if (input.json) {
-    process.stdout.write(JSON.stringify({ findings, scanned, ignoredFiles }, null, 2) + "\n");
-    return;
+// src/cli/render/text.ts
+var ESC = "\x1B";
+var RESET = `${ESC}[0m`;
+var BOLD = `${ESC}[1m`;
+var DIM = `${ESC}[2m`;
+var RED = `${ESC}[31m`;
+var YELLOW = `${ESC}[33m`;
+var GREEN = `${ESC}[32m`;
+function colourEnabled(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+  if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+  if (env.TERM === "dumb") return false;
+  return Boolean(stream.isTTY);
+}
+function terminalWidth(stream = process.stdout) {
+  const c = stream.columns;
+  if (!c || c < 40) return 80;
+  return Math.min(c, 100);
+}
+function paint(s, code, on) {
+  return on ? code + s + RESET : s;
+}
+function wrap(text, width) {
+  const out = [];
+  let cur = "";
+  for (const w of text.split(/\s+/).filter(Boolean)) {
+    if (cur === "") cur = w;
+    else if (cur.length + 1 + w.length <= width) cur += " " + w;
+    else {
+      out.push(cur);
+      cur = w;
+    }
   }
-  const ignoredNote = ignoredFiles > 0 ? `, ${ignoredFiles} file(s) ignored by policy` : "";
+  if (cur) out.push(cur);
+  return out.length ? out : [""];
+}
+function clip(s, max) {
+  const one = s.replace(/\s+/g, " ").trim();
+  return one.length > max ? one.slice(0, Math.max(1, max - 1)) + "\u2026" : one;
+}
+function orderFindings(findings) {
+  return [...findings].sort((a, b) => {
+    if (a.severity !== b.severity) return a.severity === "block" ? -1 : 1;
+    const fa = a.file ?? "";
+    const fb = b.file ?? "";
+    if (fa !== fb) return fa < fb ? -1 : 1;
+    return (a.line ?? 0) - (b.line ?? 0);
+  });
+}
+function countsPhrase(blocks, warns) {
+  const parts = [];
+  if (blocks) parts.push(`${blocks} blocking`);
+  if (warns) parts.push(`${warns} warning${warns === 1 ? "" : "s"}`);
+  return parts.join(", ");
+}
+function scopePhrase(scanned, ignoredFiles) {
+  const ignored = ignoredFiles > 0 ? `, ${ignoredFiles} file${ignoredFiles === 1 ? "" : "s"} ignored by policy` : "";
+  return `${scanned} change${scanned === 1 ? "" : "s"} scanned${ignored}`;
+}
+var SIGNOFF_NOTE = "A blocking finding clears only with a human sign-off. In CI that sign-off is out-of-band \u2014 a PR label applied by a reviewer \u2014 never a file committed on the branch under review. See SPEC \xA75.4.";
+function renderText(input, opts) {
+  const { scanned, ignoredFiles } = input;
+  const findings = orderFindings(input.findings);
+  const blocks = findings.filter((f) => f.severity === "block");
+  const warns = findings.filter((f) => f.severity === "warn");
+  const c = opts.colour;
+  const out = [];
   if (findings.length === 0) {
-    process.stdout.write(`tamperward: clean \u2014 no integrity findings (${scanned} change(s) scanned${ignoredNote}).
-`);
-    return;
+    return `${paint("tamperward: clean", GREEN, c)} \u2014 no integrity findings (${scopePhrase(scanned, ignoredFiles)}).
+`;
+  }
+  const headColour = blocks.length ? RED : YELLOW;
+  out.push(paint(`tamperward: ${countsPhrase(blocks.length, warns.length)}`, BOLD + headColour, c));
+  out.push(paint(`(${scopePhrase(scanned, ignoredFiles)})`, DIM, c));
+  out.push("");
+  const LABEL = "sign-off".length;
+  const pad = (k) => (k + " ".repeat(LABEL)).slice(0, LABEL);
+  const body = Math.max(20, opts.width - LABEL - 6);
+  for (const f of findings) {
+    const isBlock = f.severity === "block";
+    const mark = paint(isBlock ? "BLOCK" : "warn ", isBlock ? BOLD + RED : YELLOW, c);
+    const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "(command)";
+    out.push(`  ${mark}  ${paint(f.rule, BOLD, c)}  ${paint(loc, DIM, c)}`);
+    for (const l of wrap(f.message, opts.width - 4)) out.push(`    ${l}`);
+    const row = (key2, lines) => {
+      lines.forEach((l, i) => out.push(`    ${paint(pad(i === 0 ? key2 : ""), DIM, c)}  ${l}`));
+    };
+    row("evidence", [paint(clip(f.evidence, body), DIM, c)]);
+    row("instead", wrap(f.remediation, body));
+    if (f.signoff.required) row("sign-off", [f.signoff.command]);
+    out.push("");
+  }
+  if (blocks.length > 0) {
+    out.push(
+      wrap(SIGNOFF_NOTE, opts.width - 2).map((l) => paint(l, DIM, c)).join("\n")
+    );
   }
+  return out.join("\n").replace(/\n+$/, "") + "\n";
+}
+// src/cli/render/github.ts
+import { appendFileSync as appendFileSync2 } from "node:fs";
+function escData(s) {
+  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escProp(s) {
+  return escData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function annotations(findings) {
+  return orderFindings(findings).map((f) => {
+    const kind = f.severity === "block" ? "error" : "warning";
+    const props = [];
+    if (f.file) {
+      props.push(`file=${escProp(f.file)}`);
+      if (f.line) props.push(`line=${f.line}`);
+    }
+    props.push(`title=${escProp(`tamperward: ${f.rule}`)}`);
+    const body = `${f.message} Instead: ${f.remediation}` + (f.signoff.required ? ` Sign-off: ${f.signoff.command}` : "");
+    return `::${kind} ${props.join(",")}::${escData(body)}`;
+  });
+}
+function cell(s) {
+  return s.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+}
+function locationCell(f, env) {
+  if (!f.file) return "`(command)`";
+  const label = `${f.file}${f.line ? `:${f.line}` : ""}`;
+  const server = env.GITHUB_SERVER_URL;
+  const repo = env.GITHUB_REPOSITORY;
+  const sha = env.GITHUB_SHA;
+  if (!server || !repo || !sha) return `\`${cell(label)}\``;
+  const frag = f.line ? `#L${f.line}` : "";
+  return `[\`${cell(label)}\`](${server}/${repo}/blob/${sha}/${f.file}${frag})`;
+}
+function renderSummary(input, env = process.env) {
+  const findings = orderFindings(input.findings);
   const blocks = findings.filter((f) => f.severity === "block");
   const warns = findings.filter((f) => f.severity === "warn");
+  const scope = scopePhrase(input.scanned, input.ignoredFiles);
+  if (findings.length === 0) {
+    return `## Tamperward: clean
+No integrity findings (${scope}).
+`;
+  }
+  const out = [
+    `## Tamperward: ${countsPhrase(blocks.length, warns.length)}`,
+    "",
+    `${scope}. Every finding below is also annotated on the diff in **Files changed**.`,
+    "",
+    "| Severity | Rule | Location | Finding | Instead |",
+    "| --- | --- | --- | --- | --- |"
+  ];
   for (const f of findings) {
-    const mark = f.severity === "block" ? "BLOCK" : "warn";
-    const loc = f.file ? ` ${f.file}${f.line ? `:${f.line}` : ""}` : "";
-    process.stdout.write(`
-[${mark}] ${f.rule}${loc}
-`);
-    process.stdout.write(`  ${f.message}
-`);
-    process.stdout.write(`  evidence: ${f.evidence}
-`);
-    process.stdout.write(`  fix:      ${f.remediation}
-`);
-    if (f.signoff.required) process.stdout.write(`  sign-off: ${f.signoff.command}
-`);
+    const sev = f.severity === "block" ? "**BLOCK**" : "warn";
+    out.push(
+      `| ${sev} | \`${cell(f.rule)}\` | ${locationCell(f, env)} | ${cell(f.message)} | ${cell(f.remediation)} |`
+    );
   }
-  process.stdout.write(
-    `
-tamperward: ${blocks.length} blocking, ${warns.length} warning (${scanned} change(s) scanned${ignoredNote}).
-`
-  );
-  if (blocks.length > 0) {
+  const needSignoff = findings.filter((f) => f.signoff.required);
+  if (needSignoff.length) {
+    out.push("", "### Clearing a blocking finding", "", SIGNOFF_NOTE, "");
+    const seen = /* @__PURE__ */ new Set();
+    for (const f of needSignoff) {
+      if (seen.has(f.signoff.command)) continue;
+      seen.add(f.signoff.command);
+      out.push(`- \`${cell(f.signoff.command)}\``);
+    }
+  }
+  return out.join("\n") + "\n";
+}
+function writeSummary(md, env = process.env) {
+  const path = env.GITHUB_STEP_SUMMARY;
+  if (!path) return false;
+  try {
+    appendFileSync2(path, md + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isGitHubActions(env = process.env) {
+  return env.GITHUB_ACTIONS === "true";
+}
+// src/cli/report.ts
+var FORMATS = ["auto", "text", "json", "github"];
+function isFormat(s) {
+  return FORMATS.includes(s);
+}
+function resolveFormat(input, env = process.env) {
+  if (input.json) return "json";
+  if (input.format && input.format !== "auto") return input.format;
+  return isGitHubActions(env) ? "github" : "text";
+}
+function report(input) {
+  const { findings, scanned, ignoredFiles } = input;
+  const format = resolveFormat(input);
+  if (format === "json") {
+    const blocks = findings.filter((f) => f.severity === "block").length;
     process.stdout.write(
-      "A blocking finding clears only with a human sign-off. In CI, sign-off is out-of-band (a reviewed PR label), never a committed file \u2014 see SPEC \xA75.4.\n"
+      JSON.stringify(
+        // `findings`, `scanned` and `ignoredFiles` keep their exact prior shape; `summary`
+        // is additive, so an existing consumer reading only the old keys is unaffected.
+        { findings, scanned, ignoredFiles, summary: { block: blocks, warn: findings.length - blocks } },
+        null,
+        2
+      ) + "\n"
     );
+    return;
+  }
+  const text = renderText(
+    { findings, scanned, ignoredFiles },
+    { colour: colourEnabled(), width: terminalWidth() }
+  );
+  if (format === "github") {
+    for (const a of annotations(findings)) process.stdout.write(a + "\n");
+    writeSummary(renderSummary({ findings, scanned, ignoredFiles }));
   }
+  process.stdout.write(text);
 }
 // src/cli/check.ts
@@ -1439,7 +1699,7 @@ function check(opts) {
     process.stderr.write(`tamperward: ${cleared.length} blocking finding(s) cleared by ${how}: ${cleared.map((f) => f.rule + (f.file ? `(${f.file})` : "")).join(", ")}
 `);
   }
-  report({ findings, scanned: changes.length, ignoredFiles, json: opts.json });
+  report({ findings, scanned: changes.length, ignoredFiles, json: opts.json, format: opts.format });
   return hasBlocking(findings) ? 1 : 0;
 }
 function runCheck(opts) {
@@ -1456,7 +1716,7 @@ function runCheck(opts) {
 }
 // src/cli/hook.ts
-import { readFileSync as readFileSync6, appendFileSync as appendFileSync2 } from "node:fs";
+import { readFileSync as readFileSync6, appendFileSync as appendFileSync3 } from "node:fs";
 // src/adapters/claude/changes.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
@@ -1631,7 +1891,7 @@ function recordDenylog(blocks) {
   const log = process.env.TAMPERWARD_DENYLOG;
   if (!log) return;
   try {
-    appendFileSync2(log, blocks.map((b) => b.rule).join(",") + "\n");
+    appendFileSync3(log, blocks.map((b) => b.rule).join(",") + "\n");
   } catch {
   }
 }
@@ -1782,7 +2042,12 @@ function parseCheck(args) {
     if (a === "--staged") o.staged = true;
     else if (a === "--worktree") o.worktree = true;
     else if (a === "--json") o.json = true;
-    else if (a === "--diff") o.diff = args[++i];
+    else if (a === "--format") {
+      const v = args[++i];
+      if (v !== void 0 && isFormat(v)) o.format = v;
+      else process.stderr.write(`tamperward: unknown --format "${v ?? ""}" (expected ${FORMATS.join(" | ")})
+`);
+    } else if (a === "--diff") o.diff = args[++i];
     else if (a === "--cwd") o.cwd = args[++i];
     else {
       process.stderr.write(`tamperward: unknown flag "${a}"
@@ -1798,7 +2063,18 @@ Usage:
   tamperward check --staged                 check staged changes (pre-commit)
   tamperward check --worktree               check working-tree changes (stop sweep)
   tamperward check --diff <base>...<head>   check a commit range (CI authority)
-  tamperward check ... --json               machine-readable output
+  tamperward check ... --json               machine-readable output (alias for --format json)
+  tamperward check ... --format <fmt>       text | json | github | auto (default)
+Formats:
+  text    grouped, wrapped, colour-optional terminal output. Severity is always
+          spelled out ("BLOCK" / "warn"), never carried by colour alone. Honours
+          NO_COLOR and FORCE_COLOR; colour is off when stdout is not a terminal.
+  github  GitHub Actions view: one inline annotation per finding (so it shows up
+          on the line in "Files changed") plus a job-summary table on the run
+          page, alongside the same text output in the log.
+  json    the findings verbatim, plus a summary count.
+  auto    github when GITHUB_ACTIONS=true, otherwise text.
   tamperward hook claude                    PreToolUse gate (reads hook JSON on stdin)
   tamperward sweep claude                   Stop sweep (re-scan the turn's working tree)
   tamperward allow <rule> --reason "..."    record a human sign-off (local audit ledger)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tamperward",
-  "version": "1.1.0-rc.2",
+  "version": "1.2.0",
   "description": "The deterministic agent-integrity gate. One ruleset, evaluated on the actual diff/commands as a verdict, enforced everywhere a change can be made.",
   "license": "Apache-2.0",
   "author": "hexrift",