rulereceipt 0.1.66 → 0.1.67

package/dist/browser/analyze.d.ts

@@ -44,3 +44,4 @@ export declare const CORPUS: {
 };
 export declare function analyze(text: string): AnalysisResult;
 export { evaluateBrowserSession, checkSessionInBrowser, type BrowserSessionSummary } from "./evaluateBrowser.js";
+export { shareText, shareLinks, cardSvg, type CardData } from "../card.js";

package/dist/browser/analyze.js

@@ -50,3 +50,8 @@ export function analyze(text) {
 // Client-side SESSION check for the browser demo: drop a session .jsonl +
 // paste rules, get per-rule verdicts, nothing uploaded. Same checkers as the CLI.
 export { evaluateBrowserSession, checkSessionInBrowser } from "./evaluateBrowser.js";
+// Share the browser result: caption (counts only), compose links, and a
+// self-contained SVG card. card.ts is pure string work — no Node, no network —
+// so it can run in the page without breaking the "nothing leaves this page"
+// promise. Counts only, never rule text or the session.
+export { shareText, shareLinks, cardSvg } from "../card.js";

package/dist/card.js

@@ -12,9 +12,16 @@
 const SITE = "rulereceipt.dev";
 /** The share caption. Counts only, unless showRules adds the broken rule names. */
 export function shareText(d, showRules = false) {
-    const base = d.broken > 0
-        ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in ${d.days} days (${d.sessions} session${d.sessions === 1 ? "" : "s"}) — now it can't.`
-        : `RuleReceipt checked ${d.sessions} of my agent session${d.sessions === 1 ? "" : "s"} over ${d.days} days against my written rules: ${d.broken} broken.`;
+    // A single dropped session (the browser demo) has no "over N days" span, so
+    // it gets a "this session" caption rather than the history-mode one.
+    const single = d.sessions === 1;
+    const base = single
+        ? d.broken > 0
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in this session — now it can't.`
+            : `RuleReceipt checked one of my agent's sessions against my written rules: ${d.broken} broken.`
+        : d.broken > 0
+            ? `${d.who} broke my written rules ${d.broken} time${d.broken === 1 ? "" : "s"} in ${d.days} days (${d.sessions} sessions) — now it can't.`
+            : `RuleReceipt checked ${d.sessions} of my agent sessions over ${d.days} days against my written rules: ${d.broken} broken.`;
     const tail = `Checked with RuleReceipt — runs locally, nothing uploaded. ${SITE}`;
     if (showRules && d.broken > 0 && d.brokenTitles && d.brokenTitles.length > 0) {
         const list = d.brokenTitles.slice(0, 3).map((t) => `“${t.replace(/\s+/g, " ").trim().slice(0, 50)}”`).join(", ");
@@ -41,7 +48,9 @@ function esc(s) {
 /** A self-contained SVG card. Counts only — never rule text, paths or code. */
 export function cardSvg(d) {
     const headline = d.broken > 0 ? `${d.who} broke your rules ${d.broken}×` : `0 rules broken`;
-    const sub = `${d.sessions} session${d.sessions === 1 ? "" : "s"} · last ${d.days} days`;
+    const sub = d.days > 0
+        ? `${d.sessions} session${d.sessions === 1 ? "" : "s"} · last ${d.days} days`
+        : `${d.sessions} session${d.sessions === 1 ? "" : "s"}`;
     const stats = `${d.followed} followed · ${d.judgment} need judgment`;
     return `<svg xmlns="http://www.w3.org/2000/svg" width="800" height="418" viewBox="0 0 800 418" role="img" aria-label="RuleReceipt summary">
   <rect width="800" height="418" fill="#0b0d10"/>

package/dist/checks/doctor.d.ts

@@ -11,11 +11,25 @@ export interface HookEntry {
      */
     matcher?: string;
 }
+/**
+ * A hook command registered more than once on the same event within a single
+ * settings file — so it fires that many times per event. Cross-file repetition
+ * (a global and a project settings file both registering it) is legitimate
+ * layering and is NOT reported: only a genuinely redundant in-file duplicate is,
+ * to avoid a false "you have a problem" on a normal setup.
+ */
+export interface DuplicateHook {
+    sourceFile: string;
+    event: string;
+    command: string;
+    count: number;
+}
 export interface DoctorResult {
     filesScanned: string[];
     filesFound: string[];
     hooks: HookEntry[];
     newSinceLastRun: HookEntry[];
+    duplicates: DuplicateHook[];
 }
 /**
  * Lists every Claude Code hook and VS Code folderOpen task this machine

package/dist/checks/doctor.js

@@ -140,5 +140,22 @@ export function runDoctor(cwd) {
     const previousKeys = new Set(previous.map((h) => `${h.sourceFile}|${h.event}|${h.command}`));
     const newSinceLastRun = hooks.filter((h) => !previousKeys.has(`${h.sourceFile}|${h.event}|${h.command}`));
     saveSnapshot(cwd, hooks);
-    return { filesScanned, filesFound, hooks, newSinceLastRun };
+    return { filesScanned, filesFound, hooks, newSinceLastRun, duplicates: findDuplicates(hooks) };
+}
+/**
+ * Same command on the same event within ONE file, counted. Keyed by
+ * file+event+command so the global-plus-project case never registers as a
+ * duplicate — that is intended layering, not a misconfiguration.
+ */
+function findDuplicates(hooks) {
+    const counts = new Map();
+    for (const h of hooks) {
+        const key = `${h.sourceFile}|${h.event}|${h.command}`;
+        const existing = counts.get(key);
+        if (existing)
+            existing.count += 1;
+        else
+            counts.set(key, { sourceFile: h.sourceFile, event: h.event, command: h.command, count: 1 });
+    }
+    return [...counts.values()].filter((d) => d.count > 1);
 }

package/dist/cli.js

@@ -750,6 +750,14 @@ function runDoctorCommand() {
     if (result.newSinceLastRun.length > 0) {
         console.log(`${result.newSinceLastRun.length} of these are new since the last time doctor ran here.`);
     }
+    if (result.duplicates.length > 0) {
+        console.log("");
+        console.log(`⚠ ${result.duplicates.length} duplicate hook${result.duplicates.length === 1 ? "" : "s"} — the same command is registered more than once on one event, so it runs that many times:`);
+        for (const d of result.duplicates) {
+            console.log(`  ${d.event} — ${d.command}  (×${d.count})`);
+            console.log(`     in ${d.sourceFile} — remove the extra copy so it fires once.`);
+        }
+    }
 }
 program
     .command("hook")

package/dist/evaluate.d.ts

@@ -20,3 +20,4 @@ export interface Evaluation {
  * a transcript comes from, and a hook is handed one it must not second-guess.
  */
 export declare function evaluateSession(cwd: string, rules: Rule[], events: TranscriptEvent[], llm: boolean, needsLlmResult: (rule: Rule) => CheckResult): Promise<Evaluation>;
+export declare function attachSourceLocation(results: CheckResult[], rules: Rule[]): CheckResult[];

package/dist/evaluate.js

@@ -98,9 +98,35 @@ export async function evaluateSession(cwd, rules, events, llm, needsLlmResult) {
     const judgmentResults = llm
         ? await runJudgmentChecks(judgment, events)
         : judgment.map(({ rule }) => needsLlmResult(rule));
+    const results = [...deterministicResults, ...judgmentResults, ...scopeResults, ...future.map(futureResult)];
     return {
-        results: [...deterministicResults, ...judgmentResults, ...scopeResults, ...future.map(futureResult)],
+        results: attachSourceLocation(results, rules),
         notARule: of("notARule"),
         stale: staleOverrides(overrides, rules),
     };
 }
+/**
+ * Copies each rule's source file/line onto its verdict — but ONLY when the
+ * (source, id, title) triple maps to exactly one loaded rule. Rule ids are
+ * positional and two files can legitimately reuse "1" or "S1.1", so a blind
+ * id-match could point a report at the wrong line. A wrong "CLAUDE.md:42" is
+ * worse than none, so an ambiguous or unlocated rule simply carries no line.
+ */
+function locationKey(source, id, title) {
+    return `${source}\u0000${id}\u0000${title}`;
+}
+export function attachSourceLocation(results, rules) {
+    const byKey = new Map();
+    for (const rule of rules) {
+        if (rule.sourcePath === undefined)
+            continue;
+        const key = locationKey(rule.source, rule.id, rule.title);
+        byKey.set(key, byKey.has(key) ? null : rule); // second hit => ambiguous => null
+    }
+    return results.map((r) => {
+        const rule = byKey.get(locationKey(r.ruleSource, r.ruleId, r.ruleTitle));
+        if (!rule)
+            return r;
+        return { ...r, sourcePath: rule.sourcePath, sourceLine: rule.sourceLine };
+    });
+}

package/dist/parsers/claudeMdParser.js

@@ -75,7 +75,12 @@ function stripHtmlComments(raw) {
         spans.push(m);
         return `\u0000CODE${spans.length - 1}\u0000`;
     });
-    const stripped = masked.replace(/<!--[\s\S]*?-->/g, "");
+    // A removed comment is replaced by the SAME number of newlines it spanned,
+    // not by nothing. Rule source lines are tracked by line index (2026-09-29),
+    // so a multi-line comment that collapsed to nothing would shift every rule
+    // below it and make the reported "CLAUDE.md:42" wrong. Blank lines left in a
+    // rule body are trimmed at its edges and harmless within it.
+    const stripped = masked.replace(/<!--[\s\S]*?-->/g, (m) => "\n".repeat((m.match(/\n/g) ?? []).length));
     return stripped.replace(/\u0000CODE(\d+)\u0000/g, (_, i) => spans[Number(i)]);
 }
 function normalizeSetextHeaders(lines) {
@@ -152,6 +157,8 @@ export function parseClaudeMdText(raw, source) {
     let currentIsMarkedRule = false; // true for numbered/bold rules: bullets in their body stay as body text
     let bodyLines = [];
     let pendingSectionTitle = null;
+    let pendingSectionLine = 0; // 1-based line of the plain header awaiting its prose rule
+    let lineNo = 0; // 1-based index of the line currently being read
     let sectionCount = 0;
     let sectionId = "S0"; // "S0" before any header is seen; null while a header is pending its first rule
     let bulletIndex = 0;
@@ -178,7 +185,7 @@ export function parseClaudeMdText(raw, source) {
             bodyLines.push(line);
         }
         else if (pendingSectionTitle !== null && line.trim() !== "") {
-            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source };
+            current = { id: `${assignSectionId()}.0`, title: pendingSectionTitle, text: "", source, sourceLine: pendingSectionLine };
             bodyLines = [line];
             pendingSectionTitle = null;
         }
@@ -187,6 +194,7 @@ export function parseClaudeMdText(raw, source) {
         }
     };
     for (const line of lines) {
+        lineNo += 1;
         // Fence state is tracked before any structural match, so nothing inside a
         // code block is ever read as a heading, a bullet, or a rule marker.
         const fence = line.match(FENCE_LINE);
@@ -210,7 +218,7 @@ export function parseClaudeMdText(raw, source) {
         if (numbered) {
             flush();
             pendingSectionTitle = null;
-            current = { id: numbered[1], title: numbered[2].trim(), text: "", source };
+            current = { id: numbered[1], title: numbered[2].trim(), text: "", source, sourceLine: lineNo };
             currentIsMarkedRule = true;
             continue;
         }
@@ -218,7 +226,7 @@ export function parseClaudeMdText(raw, source) {
         if (bold) {
             flush();
             pendingSectionTitle = null;
-            current = { id: bold[1], title: bold[2].trim(), text: "", source };
+            current = { id: bold[1], title: bold[2].trim(), text: "", source, sourceLine: lineNo };
             currentIsMarkedRule = true;
             continue;
         }
@@ -228,6 +236,7 @@ export function parseClaudeMdText(raw, source) {
             sectionId = null;
             bulletIndex = 0;
             pendingSectionTitle = plain[1].trim();
+            pendingSectionLine = lineNo;
             currentIsMarkedRule = false;
             continue;
         }
@@ -239,7 +248,7 @@ export function parseClaudeMdText(raw, source) {
             else {
                 bulletIndex += 1;
                 const text = bullet[1].trim();
-                rules.push({ id: `${assignSectionId()}.${bulletIndex}`, title: text, text, source });
+                rules.push({ id: `${assignSectionId()}.${bulletIndex}`, title: text, text, source, sourceLine: lineNo });
             }
             continue;
         }
@@ -253,13 +262,27 @@ export function parseClaudeMdText(raw, source) {
     // headers, no bullets, no bold-rule markers) is split one rule per
     // blank-line-separated paragraph, so a genuinely unstructured file
     // still yields checkable rules instead of silently returning nothing.
-    const paragraphs = raw
-        .split(/\n\s*\n/)
-        .map((p) => p.trim())
-        .filter((p) => p.length > 0);
-    return paragraphs.map((p, i) => {
+    // Track the line each paragraph starts on so the fallback rules carry a
+    // source line too. Split on the raw text and walk cumulative line counts.
+    const chunks = raw.split(/\n\s*\n/);
+    const out = [];
+    let lineCursor = 1;
+    let n = 0;
+    for (const chunk of chunks) {
+        const startLine = lineCursor;
+        lineCursor += (chunk.match(/\n/g) ?? []).length; // lines consumed by this chunk
+        // account for the blank separator the split removed (one newline minimum)
+        lineCursor += 1;
+        const p = chunk.trim();
+        if (p.length === 0)
+            continue;
+        n += 1;
         const firstLine = p.split("\n")[0].trim();
         const title = firstLine.length > 100 ? `${firstLine.slice(0, 100).trim()}…` : firstLine;
-        return { id: String(i + 1), title, text: p, source };
-    });
+        // Best-effort line for the freeform fallback: any leading blank lines in the
+        // chunk push the real first line down.
+        const leadBlank = (chunk.match(/^(?:[ \t]*\n)*/)?.[0].match(/\n/g) ?? []).length;
+        out.push({ id: String(n), title, text: p, source, sourceLine: startLine + leadBlank });
+    }
+    return out;
 }

package/dist/parsers/readClaudeMd.js

@@ -81,6 +81,24 @@ export function readPathScope(raw) {
     }
     return undefined;
 }
+/**
+ * How many leading lines `stripFrontmatter` removes, so a source line computed
+ * on the stripped text can be mapped back to the real file line. Zero when
+ * there is no frontmatter block.
+ */
+function frontmatterLineOffset(raw) {
+    if (!/^---\r?\n/.test(raw))
+        return 0;
+    const end = raw.indexOf("\n---", 3);
+    if (end === -1)
+        return 0;
+    const after = raw.indexOf("\n", end + 1);
+    if (after === -1)
+        return 0;
+    // stripFrontmatter returns raw.slice(after + 1): everything up to and
+    // including that newline is gone. Count the newlines removed.
+    return (raw.slice(0, after + 1).match(/\n/g) ?? []).length;
+}
 export function parseClaudeMd(filePath, source) {
     let raw;
     try {
@@ -89,7 +107,13 @@ export function parseClaudeMd(filePath, source) {
     catch {
         return [];
     }
+    const offset = frontmatterLineOffset(raw);
     const rules = parseClaudeMdText(stripFrontmatter(raw), source);
     const paths = readPathScope(raw);
-    return paths ? rules.map((r) => ({ ...r, paths })) : rules;
+    return rules.map((r) => ({
+        ...r,
+        sourcePath: filePath,
+        sourceLine: r.sourceLine === undefined ? undefined : r.sourceLine + offset,
+        ...(paths ? { paths } : {}),
+    }));
 }

package/dist/report/generateReport.js

@@ -1,5 +1,20 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+/**
+ * Where a rule lives, for the report — "~/proj/CLAUDE.md:42", or just the path
+ * when the parser could not place a line, or "" when the rule's location was
+ * ambiguous and deliberately omitted (see attachSourceLocation). The home dir
+ * is compressed to ~ so the line stays readable; the JSON report keeps the full
+ * absolute path.
+ */
+function locationOf(r) {
+    if (!r.sourcePath)
+        return "";
+    const home = homedir();
+    const path = r.sourcePath.startsWith(home) ? `~${r.sourcePath.slice(home.length)}` : r.sourcePath;
+    return r.sourceLine ? `${path}:${r.sourceLine}` : path;
+}
 const MARK = { PASS: "✓", FAIL: "✕", UNCLEAR: "?" };
 /**
  * A CLAUDE.md rule title, or evidence text pulled from session content, is
@@ -196,6 +211,9 @@ export function generateReport(results, meta) {
             lines.push("");
             for (const r of inBucket) {
                 lines.push(`  ${ruleLabel(r, clean)}`);
+                const loc = locationOf(r);
+                if (loc)
+                    lines.push(`    ↳ ${loc}`);
                 // An entry that does not share the hoisted text still says its own
                 // piece — that difference is the only per-rule information there is.
                 if (r.evidence && r.evidence !== shared)
@@ -207,6 +225,9 @@ export function generateReport(results, meta) {
         }
         for (const r of inBucket) {
             lines.push(`${MARK[r.status]} ${r.status.padEnd(7)} ${ruleLabel(r, clean)}`);
+            const loc = locationOf(r);
+            if (loc)
+                lines.push(`  ↳ ${loc}`);
             if (r.evidence)
                 lines.push(`  evidence: ${r.evidence}`);
             // What this method was ALLOWED to conclude, travelling with the
@@ -259,7 +280,9 @@ export function generateMarkdownReport(results, meta) {
     lines.push("|---|---|---|");
     for (const r of clean) {
         const evidence = escapeMarkdownCell(r.evidence || "");
-        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(ruleLabel(r, clean))} | ${evidence} |`);
+        const loc = locationOf(r);
+        const label = loc ? `${ruleLabel(r, clean)}<br>\`${loc}\`` : ruleLabel(r, clean);
+        lines.push(`| ${MARK[r.status]} ${r.status} | ${escapeMarkdownCell(label)} | ${evidence} |`);
     }
     lines.push("");
     const hash = computeTranscriptHash(meta.sessionFilePath);
@@ -302,6 +325,10 @@ export function generateJsonReport(results, meta, toolVersion, editedRuleFiles =
             ruleId: r.ruleId,
             ruleTitle: r.ruleTitle,
             ruleSource: r.ruleSource,
+            // Absolute path + 1-based line of the rule's heading, when unambiguous
+            // (see attachSourceLocation). A consumer can jump straight to the rule.
+            sourcePath: r.sourcePath ?? null,
+            sourceLine: r.sourceLine ?? null,
             status: r.status,
             outcome: r.outcome ?? null,
             method: r.method ?? null,

package/dist/types.d.ts

@@ -11,6 +11,15 @@ export interface Rule {
      * against a rule it was never shown. Absent = always loaded.
      */
     paths?: string[];
+    /**
+     * Absolute path of the rules file this rule was read from, and the 1-based
+     * line where its heading/marker sits. Added 2026-09-29 so a report can say
+     * exactly where a rule lives ("CLAUDE.md:42 — Never push to main"): a verdict
+     * you can walk to the source of is a verdict you can trust. Optional — memory
+     * rules and the freeform-paragraph fallback carry a path but may omit a line.
+     */
+    sourcePath?: string;
+    sourceLine?: number;
 }
 export interface TranscriptTextEvent {
     role: "user" | "assistant";
@@ -149,6 +158,14 @@ export interface CheckResult {
      * anthropics/claude-code#90542.
      */
     polarityInferred?: boolean;
+    /**
+     * Where the checked rule lives — the rules file's absolute path and the
+     * 1-based line of its heading. Copied from the rule in `evaluateSession`,
+     * and ONLY when the (source, id, title) triple maps to exactly one loaded
+     * rule, so a report never points at the wrong line. Absent otherwise.
+     */
+    sourcePath?: string;
+    sourceLine?: number;
 }
 /**
  * A FAIL may only be constructed from a forbidding rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "description": "Checks whether your AI coding agent followed your rules, with evidence. Works with Claude Code (Codex in testing); reads CLAUDE.md, AGENTS.md, Cursor, Copilot and Windsurf rules.",
   "repository": {
     "type": "git",