rulereceipt 0.1.19 → 0.1.20

package/README.md

@@ -1,8 +1,20 @@
 # RuleReceipt
 
+[![CI](https://github.com/rulereceipt/rulereceipt/actions/workflows/ci.yml/badge.svg)](https://github.com/rulereceipt/rulereceipt/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/rulereceipt/rulereceipt/actions/workflows/codeql.yml/badge.svg)](https://github.com/rulereceipt/rulereceipt/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/rulereceipt/rulereceipt/badge)](https://scorecard.dev/viewer/?uri=github.com/rulereceipt/rulereceipt)
+[![npm](https://img.shields.io/npm/v/rulereceipt)](https://www.npmjs.com/package/rulereceipt)
+[![provenance](https://img.shields.io/badge/npm-provenance%20signed-blue)](https://www.npmjs.com/package/rulereceipt#provenance)
+
 Checks whether a Claude Code session actually followed the rules in your
 CLAUDE.md / AGENTS.md — with evidence, not just a vibe.
 
+Every release from 0.1.19 on is built and published by GitHub Actions and
+signed with [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify the published package was built from this repository at
+a specific commit. No publishing token exists to be stolen. Check it
+yourself with `npm audit signatures` after installing.
+
 Licensed source-available software — see [LICENSE](./LICENSE) and
 [NOTICE.md](./NOTICE.md) before reusing this code.
 
@@ -56,6 +68,31 @@ Published and live on npm, actively developed.
    that exact file. (It proves the report matches the file, not that the
    file is an unmodified record — see SECURITY.md.)
 
+## Exit codes
+
+`check` exits **1** when a rule was actually broken, and **0** otherwise,
+so CI can gate on it. Rules that need human judgment report UNCLEAR and
+never affect the exit code — most rules in a real CLAUDE.md need judgment,
+and gating on those would make every build red on day one.
+
+`--exit-zero` prints the report without failing the build. `--require-session`
+does the opposite and is the one to use anywhere automated: it fails when
+there is no session, or an empty one, instead of reporting a pass for a
+check that never actually ran.
+
+### A limit worth knowing before you wire this into CI
+
+Claude Code writes its session transcript to the machine the agent ran on
+— your laptop. A CI runner is a fresh machine that has never seen it, so a
+CI job cannot check a session that happened on your laptop unless you
+deliberately make that transcript available to the job. See
+[templates/rulereceipt-ci.yml](./templates/rulereceipt-ci.yml), which
+explains the options and, if you use it, fails loudly rather than passing
+on a session it never found.
+
+For most people the honest answer is simpler: run `rulereceipt check --html`
+locally and attach the report to the PR.
+
 ## Sharing a report
 
 `rulereceipt check --html` writes one self-contained HTML file. No
@@ -89,6 +126,8 @@ rulereceipt check              # check the latest session in this project
 rulereceipt check --markdown   # same, formatted for pasting into a PR/Slack
 rulereceipt check --html       # write a shareable single-file HTML report you can send
 rulereceipt check --html report.html       # ...to a specific path
+rulereceipt check --require-session        # fail if there's no session, instead of passing silently
+rulereceipt check --exit-zero              # report failures without failing the build
 rulereceipt check --llm        # opt-in: grade judgment rules with your own Claude key
 rulereceipt check --share      # opt-in: send anonymous pass/fail/unclear counts
 rulereceipt check --telemetry  # opt-in: send one random per-machine ID

package/dist/cli.js

@@ -121,7 +121,7 @@ function writeHtmlReport(results, meta, cwd, target) {
     }
 }
 async function runCheck(opts) {
-    const { markdown, share, email, emailAlways, llm, telemetry, html, transcriptOverride } = opts;
+    const { markdown, share, email, emailAlways, llm, telemetry, html, exitZero, requireSession, transcriptOverride } = opts;
     const cwd = process.cwd();
     const rules = loadRules(cwd);
     if (rules.length === 0) {
@@ -139,9 +139,34 @@ async function runCheck(opts) {
         console.log("No Claude Code session found for this project yet.\n" +
             "Run Claude Code here at least once, then try `rulereceipt check` again — " +
             "or pass --transcript <path-to-.jsonl> directly if your session lives somewhere non-standard.");
+        // Exiting 0 here is right for a person running this locally for the
+        // first time — nothing is wrong, there is simply nothing yet. It is
+        // dangerous anywhere automated, where a silent 0 reads as "checked,
+        // all clear" when nothing was checked at all. --require-session makes
+        // that case fail loudly. See the note in templates/rulereceipt-ci.yml.
+        if (requireSession) {
+            console.error("\n--require-session was set and no session was found, so nothing could be checked. " +
+                "Failing rather than reporting a pass for a check that never ran.");
+            process.exitCode = 1;
+        }
         return;
     }
     const events = transcriptOverride ? readTranscriptFromFile(sessionFilePath) : readLatestTranscript(cwd);
+    // A session file with nothing in it produces a report full of PASSes,
+    // because no forbidden action appears in an empty session. That is
+    // technically true and badly misleading: "we found no proof of
+    // wrongdoing" gets printed as "you're fine." Same shape as the rule this
+    // tool already enforces on itself — an absence of evidence is not
+    // evidence. Say so out loud, and fail where a machine is reading it.
+    if (events.length === 0) {
+        console.log("\n⚠ This session file contains no recorded activity, so there was nothing to check against.\n" +
+            "  Every result below reflects an empty session, not a clean one.");
+        if (requireSession) {
+            console.error("\n--require-session was set and the session was empty. Failing rather than reporting a pass for a check that had no evidence.");
+            process.exitCode = 1;
+            return;
+        }
+    }
     const classifications = classifyRules(rules);
     const deterministic = classifications.filter((c) => c.kind === "deterministic");
     const ifEditThenTest = classifications.filter((c) => c.kind === "ifEditThenTest");
@@ -201,6 +226,23 @@ async function runCheck(opts) {
     if (isTelemetryEnabled(telemetry)) {
         await sendTelemetryPing();
     }
+    // Exit non-zero when a rule was actually broken, so CI can gate on it.
+    //
+    // This was a real shipped falsehood (found 2026-08-31):
+    // templates/rulereceipt-ci.yml told people to copy a workflow and said
+    // "rulereceipt already exits non-zero on FAIL, this just wires that
+    // into CI" — while `check` always exited 0. Anyone who used that
+    // template had a job that passed even as the agent broke their rules,
+    // which is worse than having no check at all, because it reads as
+    // evidence that nothing went wrong.
+    //
+    // Only FAIL counts. UNCLEAR must not, and that isn't a softening: most
+    // rules in a real CLAUDE.md need judgment, so without --llm they
+    // legitimately report UNCLEAR. Gating on those would make every build
+    // red on day one and the check would be deleted within a week.
+    if (!exitZero && results.some((r) => r.status === "FAIL")) {
+        process.exitCode = 1;
+    }
 }
 function runDemo(markdown) {
     const meta = { sessionFilePath: null, ruleCount: DEMO_RESULTS.length };
@@ -222,6 +264,8 @@ program
     .option("--llm", "opt-in: grade rules that need judgment (not just pattern matching) using your own Anthropic key. Without this flag, those rules report UNCLEAR and nothing is sent anywhere — deterministic checks always run with no key regardless.")
     .option("--telemetry", "opt-in: send an anonymous install-count ping (a random per-machine ID, never rule text or results) so real distinct-install counts are knowable. Off by default. DO_NOT_TRACK=1 or RULERECEIPT_NO_TELEMETRY=1 overrides this flag back off.")
     .option("--html [path]", `write a shareable single-file HTML report you can email, attach to a ticket, or print to PDF. Defaults to ./${DEFAULT_HTML_REPORT_NAME}. Written locally — nothing is uploaded.`)
+    .option("--exit-zero", "always exit 0, even when a rule was broken. Without this, `check` exits 1 on any FAIL so CI can gate on it (rules needing human judgment report UNCLEAR and never affect the exit code).")
+    .option("--require-session", "fail (exit 1) if no session is found, or the session is empty, instead of reporting a pass for a check that never actually ran. Use this anywhere automated.")
     .option("--transcript <path>", "manual override: check this exact .jsonl session file instead of auto-detecting one. Useful if your Claude Code session lives somewhere non-standard that auto-detection doesn't cover.")
     .action((opts) => {
     runCheck({
@@ -233,6 +277,8 @@ program
         telemetry: Boolean(opts.telemetry),
         // commander gives `true` for a bare --html and the string for --html <path>
         html: opts.html ?? false,
+        exitZero: Boolean(opts.exitZero),
+        requireSession: Boolean(opts.requireSession),
         transcriptOverride: opts.transcript,
     }).catch((err) => {
         console.error("Something went wrong:", err instanceof Error ? err.message : err);

package/dist/report/generateReport.js

@@ -67,6 +67,31 @@ export function generateReport(results, meta) {
     lines.push(`checked: ${new Date().toISOString()}`);
     return lines.join("\n");
 }
+/**
+ * Makes a value safe to place inside a markdown table cell.
+ *
+ * The previous version escaped only `|`, which broke a real table three
+ * separate ways (first found by CodeQL js/incomplete-sanitization, the
+ * other two while fixing it):
+ *
+ * 1. Backslash was not escaped, so evidence containing a literal `\|`
+ *    became `\\|` — rendering as a backslash followed by a live column
+ *    separator, splitting the row. Backslash must be escaped FIRST, or
+ *    it re-escapes the pipes added afterwards.
+ * 2. The rule TITLE was not escaped at all, so any rule whose title
+ *    contains a pipe broke the table. Titles come from a user's
+ *    CLAUDE.md, and pipes appear naturally in shell examples.
+ * 3. Newlines were not handled. stripControlChars deliberately keeps
+ *    `\n` so multi-line evidence stays readable in the terminal, but a
+ *    newline inside a table cell ends the row and destroys everything
+ *    below it. Rendered as a literal <br> instead.
+ */
+function escapeMarkdownCell(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/\|/g, "\\|")
+        .replace(/\r?\n/g, "<br>");
+}
 export function generateMarkdownReport(results, meta) {
     const clean = results.map(sanitize);
     const lines = [];
@@ -75,8 +100,8 @@ export function generateMarkdownReport(results, meta) {
     lines.push("| Status | Rule | Evidence |");
     lines.push("|---|---|---|");
     for (const r of clean) {
-        const evidence = (r.evidence || "").replace(/\|/g, "\\|");
-        lines.push(`| ${MARK[r.status]} ${r.status} | ${ruleLabel(r, clean)} | ${evidence} |`);
+        const evidence = escapeMarkdownCell(r.evidence || "");
+        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(ruleLabel(r, clean))} | ${evidence} |`);
     }
     lines.push("");
     const hash = computeTranscriptHash(meta.sessionFilePath);

package/dist/telemetry.d.ts

@@ -15,5 +15,15 @@ export declare function isTelemetryEnabled(telemetryFlag: boolean): boolean;
  * session content, or even pass/fail counts (that's what opt-in --share is
  * for). A send failure must never affect the `check` command's own exit
  * code or output; this is best-effort and silent on failure.
+ *
+ * CodeQL flags this as js/file-access-to-http ("outbound network request
+ * depends on file data"), which is technically accurate and not a real
+ * issue: the file it reads is ~/.rulereceipt/telemetry-id, whose entire
+ * contents are a random UUID this tool generated and wrote itself. No
+ * user content, no path, and nothing derived from the session ever
+ * reaches this request. Reviewed and dismissed deliberately rather than
+ * left open — a permanently red alert list is one nobody reads. If the
+ * payload here ever grows beyond `{ id }`, that decision is void and
+ * this needs re-reviewing.
  */
 export declare function sendTelemetryPing(): Promise<void>;

package/dist/telemetry.js

@@ -61,6 +61,16 @@ export function isTelemetryEnabled(telemetryFlag) {
  * session content, or even pass/fail counts (that's what opt-in --share is
  * for). A send failure must never affect the `check` command's own exit
  * code or output; this is best-effort and silent on failure.
+ *
+ * CodeQL flags this as js/file-access-to-http ("outbound network request
+ * depends on file data"), which is technically accurate and not a real
+ * issue: the file it reads is ~/.rulereceipt/telemetry-id, whose entire
+ * contents are a random UUID this tool generated and wrote itself. No
+ * user content, no path, and nothing derived from the session ever
+ * reaches this request. Reviewed and dismissed deliberately rather than
+ * left open — a permanently red alert list is one nobody reads. If the
+ * payload here ever grows beyond `{ id }`, that decision is void and
+ * this needs re-reviewing.
  */
 export async function sendTelemetryPing() {
     const id = getOrCreateTelemetryId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",
@@ -45,16 +45,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.32.0",
-    "commander": "^12.1.0",
-    "nodemailer": "^9.0.5"
+    "commander": "^15.0.0",
+    "nodemailer": "^9.0.6"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.4.0",
     "@types/nodemailer": "^8.0.1",
-    "eslint": "^9.0.0",
+    "eslint": "^10.9.1",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vitest": "^4.1.11"
   }
 }