rulereceipt 0.1.25 → 0.1.26

package/dist/browser/analyze.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Entry point for the in-browser checker on the site.
+ *
+ * The privacy claim on that page — "your file never leaves this page" — is
+ * only true because everything reachable from here is pure string work.
+ * parseClaudeMdText and classifyRules touch no Node API, no network, and
+ * no storage. If anything in this dependency chain ever gains an import
+ * that does, the page's claim becomes false and must change with it.
+ *
+ * Deliberately returns counts and a small sample, never the file: nothing
+ * here should make it easy to accidentally send the text somewhere.
+ */
+export interface Breakdown {
+    kind: string;
+    count: number;
+}
+export interface AnalysisResult {
+    /** Everything the parser pulled out of the file, rules and non-rules alike. */
+    parsed: number;
+    /** Items carrying no instruction — documentation, tables, listings. */
+    notRules: number;
+    /** Items that are genuinely directives. */
+    realRules: number;
+    /** Real rules a check can answer by looking at what ran. */
+    checkable: number;
+    /** Real rules that need a person. */
+    judgment: number;
+    /** Share of the whole file that isn't an instruction, 0-100. */
+    notRulesPct: number;
+    /** Share of REAL rules that are mechanically answerable, 0-100. */
+    checkablePct: number;
+    byKind: Breakdown[];
+    /** A few non-rule titles, so the number is inspectable rather than asserted. */
+    notRuleSamples: string[];
+    /** A few judgment-call titles, same reason. */
+    judgmentSamples: string[];
+}
+/** Measured across 559 real public rules files. Shown for comparison. */
+export declare const CORPUS: {
+    files: number;
+    parsed: number;
+    notRulesPct: number;
+    checkablePct: number;
+};
+export declare function analyze(text: string): AnalysisResult;

package/dist/browser/analyze.js

@@ -0,0 +1,49 @@
+import { parseClaudeMdText } from "../parsers/claudeMdParser.js";
+import { classifyRules } from "../checks/classify.js";
+/** Measured across 559 real public rules files. Shown for comparison. */
+export const CORPUS = {
+    files: 559,
+    parsed: 23704,
+    notRulesPct: 62.9,
+    checkablePct: 43.5,
+};
+function pct(part, whole) {
+    return whole === 0 ? 0 : Math.round((part / whole) * 1000) / 10;
+}
+export function analyze(text) {
+    const rules = parseClaudeMdText(text, "project");
+    const classified = classifyRules(rules);
+    const counts = new Map();
+    const notRuleSamples = [];
+    const judgmentSamples = [];
+    for (const c of classified) {
+        counts.set(c.kind, (counts.get(c.kind) ?? 0) + 1);
+        const title = c.rule.title.trim();
+        if (!title)
+            continue;
+        if (c.kind === "notARule" && notRuleSamples.length < 4)
+            notRuleSamples.push(title);
+        if (c.kind === "judgment" && judgmentSamples.length < 4)
+            judgmentSamples.push(title);
+    }
+    const parsed = classified.length;
+    const notRules = counts.get("notARule") ?? 0;
+    const judgment = counts.get("judgment") ?? 0;
+    const realRules = parsed - notRules;
+    const checkable = realRules - judgment;
+    const byKind = [...counts.entries()]
+        .map(([kind, count]) => ({ kind, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        parsed,
+        notRules,
+        realRules,
+        checkable,
+        judgment,
+        notRulesPct: pct(notRules, parsed),
+        checkablePct: pct(checkable, realRules),
+        byKind,
+        notRuleSamples,
+        judgmentSamples,
+    };
+}

package/dist/cli.js

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { join, dirname, resolve, isAbsolute } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { readLatestTranscript, readTranscriptFromFile, findLatestSessionFile } from "./parsers/transcriptParser.js";
 import { loadRules } from "./rules.js";
 import { classifyRules } from "./checks/classify.js";

package/dist/parsers/claudeMdParser.d.ts

@@ -1,2 +1,11 @@
 import type { Rule } from "../types.js";
-export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export declare function parseClaudeMdText(raw: string, source: "global" | "project"): Rule[];

package/dist/parsers/claudeMdParser.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 /**
  * Real CLAUDE.md/AGENTS.md files use several different conventions for
  * organizing rules. Verified against real files and templates: Anthropic's
@@ -67,14 +66,16 @@ function normalizeSetextHeaders(lines) {
     }
     return out;
 }
-export function parseClaudeMd(filePath, source) {
-    let raw;
-    try {
-        raw = readFileSync(filePath, "utf-8");
-    }
-    catch {
-        return [];
-    }
+/**
+ * The actual parser, taking text rather than a path.
+ *
+ * Split out from parseClaudeMd so the parsing logic carries no filesystem
+ * dependency and can run anywhere a string can — including a browser, for
+ * the client-side checker on the site. That checker's privacy claim
+ * ("your file never leaves the page") is only true because nothing in
+ * this function or in classify.ts touches Node APIs; keep it that way.
+ */
+export function parseClaudeMdText(raw, source) {
     const lines = normalizeSetextHeaders(raw.split("\n"));
     const rules = [];
     // `current` accumulates a numbered-header rule, a bold-rule-header rule,

package/dist/parsers/readClaudeMd.d.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export declare function parseClaudeMd(filePath: string, source: "global" | "project"): Rule[];

package/dist/parsers/readClaudeMd.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { parseClaudeMdText } from "./claudeMdParser.js";
+/**
+ * The filesystem half of rules-file parsing, deliberately kept in its own
+ * module.
+ *
+ * claudeMdParser.ts must stay free of Node imports so it can be bundled
+ * for the browser — the in-page checker on the site claims the pasted file
+ * never leaves the page, and that is only true while nothing reachable
+ * from the parser can perform I/O. Keeping the one readFileSync here
+ * means a bundler cannot pull `node:fs` in behind it, and a future import
+ * that breaks the guarantee has to be added here, visibly, rather than
+ * appearing by accident in the parser.
+ */
+/**
+ * Reads a rules file from disk. Thin wrapper: an unreadable file is an
+ * empty rule list, never a throw, because a missing global CLAUDE.md is a
+ * normal state rather than an error.
+ */
+export function parseClaudeMd(filePath, source) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    return parseClaudeMdText(raw, source);
+}

package/dist/rules.d.ts

@@ -5,5 +5,15 @@ import type { Rule } from "./types.js";
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export declare function loadRules(cwd: string): Rule[];

package/dist/rules.js

@@ -1,9 +1,62 @@
 import { homedir } from "node:os";
 import { dirname, join, parse } from "node:path";
-import { existsSync } from "node:fs";
-import { parseClaudeMd } from "./parsers/claudeMdParser.js";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { parseClaudeMd } from "./parsers/readClaudeMd.js";
 import { findClaudeHomeDirNames } from "./parsers/transcriptParser.js";
-const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md"];
+/**
+ * Every place Claude Code actually reads a rule from, at one directory
+ * level. Order mirrors the documented load order, broadest first.
+ *
+ * Real gap found 2026-09-02: only the two bare filenames were read. A
+ * project with four rules files reported "1 rules checked · all passed" —
+ * three files invisible, with nothing saying so. A clean report on rules
+ * the tool never opened is the most misleading result this can produce,
+ * worse than no report, because it looks like evidence.
+ */
+const RULE_FILE_NAMES = ["CLAUDE.md", "AGENTS.md", "CLAUDE.local.md", "AGENTS.local.md"];
+const RULE_SUBDIR_FILES = [join(".claude", "CLAUDE.md"), join(".claude", "AGENTS.md")];
+const RULE_DIRS = [join(".claude", "rules")];
+/**
+ * Lists the markdown files in a rules directory, if it exists.
+ *
+ * Sorted so the same project always produces the same rule order — rule
+ * ids are positional, and an unstable order would renumber rules between
+ * runs on different machines, making two reports of the same session
+ * impossible to compare. Non-markdown files are skipped: a rules
+ * directory legitimately holds README fragments and notes.
+ */
+function markdownFilesIn(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        if (!statSync(dir).isDirectory())
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.toLowerCase().endsWith(".md"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** Every rules file at one directory level, in documented load order. */
+function ruleFilesAtLevel(dir) {
+    const found = [];
+    for (const rel of RULE_SUBDIR_FILES) {
+        const p = join(dir, rel);
+        if (existsSync(p))
+            found.push(p);
+    }
+    for (const rel of RULE_DIRS)
+        found.push(...markdownFilesIn(join(dir, rel)));
+    for (const name of RULE_FILE_NAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            found.push(p);
+    }
+    return found;
+}
 /**
  * Walks from the working directory up toward the repository root,
  * collecting rules files at every level.
@@ -25,11 +78,7 @@ function findProjectRuleFiles(cwd) {
     const home = homedir();
     let dir = cwd;
     for (;;) {
-        for (const name of RULE_FILE_NAMES) {
-            const p = join(dir, name);
-            if (existsSync(p))
-                found.push(p);
-        }
+        found.push(...ruleFilesAtLevel(dir));
         // stop AT the repo root (inclusive) — its rules do apply
         if (existsSync(join(dir, ".git")))
             break;
@@ -48,9 +97,26 @@ function findProjectRuleFiles(cwd) {
  * global CLAUDE.md under its own home dir (e.g. ~/.claude-office/CLAUDE.md).
  * Real gap found 2026-08-30, same root cause as the transcript-lookup fix
  * in transcriptParser.ts: hardcoding one home-dir name misses any variant.
+ *
+ * Also reads ~/.claude/rules/*.md, the documented location for personal
+ * rules that apply across every project.
+ *
+ * NOT covered, and stated rather than left silent: machine-wide managed
+ * enterprise policy files (/Library/Application Support/ClaudeCode,
+ * /etc/claude-code, C:\Program Files\ClaudeCode). Those are deployed by
+ * IT, exist on no development machine this can be tested against, and
+ * guessing at their location would be the kind of unverified assumption
+ * this project has already been bitten by twice.
  */
 export function loadRules(cwd) {
-    const rules = findClaudeHomeDirNames().flatMap((dirName) => parseClaudeMd(join(homedir(), dirName, "CLAUDE.md"), "global"));
+    const rules = [];
+    for (const dirName of findClaudeHomeDirNames()) {
+        const base = join(homedir(), dirName);
+        rules.push(...parseClaudeMd(join(base, "CLAUDE.md"), "global"));
+        for (const file of markdownFilesIn(join(base, "rules"))) {
+            rules.push(...parseClaudeMd(file, "global"));
+        }
+    }
     for (const path of findProjectRuleFiles(cwd)) {
         rules.push(...parseClaudeMd(path, "project"));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulereceipt",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Checks whether a Claude Code session actually followed your CLAUDE.md / AGENTS.md rules, with evidence.",
   "repository": {
     "type": "git",