@syv-ai/rulecast 0.2.0 → 0.4.0

package/dist/{chunk-C6C5EER7.js → chunk-IKONOTME.js}

@@ -8,13 +8,14 @@ import {
   lineStarts,
   offsetAt,
   onPath,
+  pastDeadline,
   perRule,
   positionAt,
   providerByName,
-  readSourceFile,
   renderAgentText,
-  resolveModel
-} from "./chunk-ZEFEQKG5.js";
+  resolveModel,
+  sourceReader
+} from "./chunk-DQUCE2IK.js";
 
 // src/core/detection/registry.ts
 function createRegistry(detectors) {
@@ -29,6 +30,61 @@ function createRegistry(detectors) {
   };
 }
 
+// src/core/detection/tool.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var exec = promisify(execFile);
+async function runTool(command, args, options) {
+  try {
+    const running = exec(command, [...args], {
+      cwd: options.cwd,
+      signal: options.signal,
+      // A whole-repository run of a linter on a large project prints megabytes of JSON.
+      maxBuffer: 64 * 1024 * 1024
+    });
+    running.child.stdin?.on("error", () => {
+    });
+    if (options.stdin === void 0) running.child.stdin?.end();
+    else running.child.stdin?.end(options.stdin);
+    const result = await running;
+    return result.stdout;
+  } catch (error) {
+    if (options.signal.aborted) throw error;
+    if (isNotFound(error)) throw new Error(options.notFound);
+    const failure = error;
+    if (typeof failure.stdout !== "string") throw error;
+    return failure.stdout;
+  }
+}
+
+// src/core/detection/paths.ts
+import { realpathSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function repoRelativeTo(cwd) {
+  const roots = rootsOf(cwd);
+  return (file) => {
+    const withoutScheme = file.startsWith("file://") ? fileURLToPath(file) : file;
+    if (!path.isAbsolute(withoutScheme)) return withoutScheme.split(path.sep).join("/");
+    for (const root of roots) {
+      const relative = path.relative(root, withoutScheme);
+      if (!relative.startsWith("..") && !path.isAbsolute(relative)) return relative.split(path.sep).join("/");
+    }
+    return path.relative(cwd, withoutScheme).split(path.sep).join("/");
+  };
+}
+function repoRelative(file, cwd) {
+  return repoRelativeTo(cwd)(file);
+}
+function rootsOf(root) {
+  try {
+    const real = realpathSync(root);
+    return real === root ? [root] : [root, real];
+  } catch {
+    return [root];
+  }
+}
+
 // src/detectors/ast-grep/languages.ts
 var LANGUAGES = {
   css: { builtin: "Css" },
@@ -180,7 +236,7 @@ var astGrepDetector = {
             if (source === null) continue;
             root = parser.parse(source).root();
           } catch (error) {
-            if (input.signal.aborted) throw error;
+            if (pastDeadline(error, input)) throw error;
             const message = errorMessage(error);
             for (const rule of rules) {
               if (rule.files.includes(file) && !result.errors.some((existing) => existing.rule === rule.id)) {
@@ -196,7 +252,7 @@ var astGrepDetector = {
                 result.findings.push({ rule: rule.id, match: matchOf(file, node, variables.get(rule.id)) });
               }
             } catch (error) {
-              if (input.signal.aborted) throw error;
+              if (pastDeadline(error, input)) throw error;
               if (!result.errors.some((existing) => existing.rule === rule.id)) {
                 result.errors.push({ rule: rule.id, message: errorMessage(error) });
               }
@@ -215,15 +271,10 @@ var astGrepDetector = {
 };
 
 // src/detectors/command/detector.ts
-import { execFile } from "child_process";
 import { access, constants } from "fs/promises";
 import path2 from "path";
-import { promisify } from "util";
 
 // src/detectors/command/results.ts
-import { realpathSync } from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
 var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function parseJson(output) {
   try {
@@ -232,23 +283,6 @@ function parseJson(output) {
     throw new Error("output is not JSON");
   }
 }
-function repoRelative(file, cwd) {
-  const withoutScheme = file.startsWith("file://") ? fileURLToPath(file) : file;
-  if (!path.isAbsolute(withoutScheme)) return withoutScheme.split(path.sep).join("/");
-  for (const root of rootsOf(cwd)) {
-    const relative = path.relative(root, withoutScheme);
-    if (!relative.startsWith("..") && !path.isAbsolute(relative)) return relative.split(path.sep).join("/");
-  }
-  return path.relative(cwd, withoutScheme).split(path.sep).join("/");
-}
-function rootsOf(root) {
-  try {
-    const real = realpathSync(root);
-    return real === root ? [root] : [root, real];
-  } catch {
-    return [root];
-  }
-}
 function capturesOf2(source, names, where) {
   const captures = {};
   for (const name of names) {
@@ -259,6 +293,7 @@ function capturesOf2(source, names, where) {
   return captures;
 }
 function matchesFromJson(output, captures, cwd) {
+  const relative = repoRelativeTo(cwd);
   const parsed = parseJson(output);
   if (!Array.isArray(parsed)) throw new Error("output is not a JSON array of results");
   return parsed.map((result, index) => {
@@ -267,7 +302,7 @@ function matchesFromJson(output, captures, cwd) {
     if (typeof result.file !== "string") throw new Error(`${where}: "file" must be a string`);
     if (typeof result.line !== "number") throw new Error(`${where}: "line" must be a number`);
     return {
-      file: repoRelative(result.file, cwd),
+      file: relative(result.file),
       line: result.line,
       endLine: typeof result.endLine === "number" ? result.endLine : result.line,
       column: typeof result.column === "number" ? result.column : 1,
@@ -277,6 +312,7 @@ function matchesFromJson(output, captures, cwd) {
   });
 }
 function matchesFromSarif(output, captures, cwd) {
+  const relative = repoRelativeTo(cwd);
   const parsed = parseJson(output);
   if (!isObject(parsed) || !Array.isArray(parsed.runs)) throw new Error("output is not SARIF 2.1.0");
   const matches = [];
@@ -296,7 +332,7 @@ function matchesFromSarif(output, captures, cwd) {
       const message = isObject(result.message) && typeof result.message.text === "string" ? result.message.text : "";
       const source = isObject(result.properties) ? { ...result, ...result.properties } : result;
       matches.push({
-        file: repoRelative(artifact.uri, cwd),
+        file: relative(artifact.uri),
         line,
         endLine: typeof region.endLine === "number" ? region.endLine : line,
         column: typeof region.startColumn === "number" ? region.startColumn : 1,
@@ -325,7 +361,6 @@ var commandSchema = z2.object({
 }).strict();
 
 // src/detectors/command/detector.ts
-var exec = promisify(execFile);
 var FILES = "{{files}}";
 function argvFor(run, files) {
   if (!run.includes(FILES)) return [...run, ...files];
@@ -356,17 +391,11 @@ var commandDetector = {
   run: perRule(async (rule, input) => {
     if (rule.files.length === 0) return [];
     const [command, ...rest] = argvFor(rule.config.run, rule.files);
-    let stdout;
-    try {
-      const result = await exec(command, rest, { cwd: input.cwd, signal: input.signal, maxBuffer: 64 * 1024 * 1024 });
-      stdout = result.stdout;
-    } catch (error) {
-      if (input.signal.aborted) throw error;
-      if (isNotFound(error)) throw new Error(`command not found: ${command}`);
-      const failure = error;
-      if (typeof failure.stdout !== "string") throw error;
-      stdout = failure.stdout;
-    }
+    const stdout = await runTool(command, rest, {
+      cwd: input.cwd,
+      signal: input.signal,
+      notFound: `command not found: ${command}`
+    });
     return rule.config.output === "sarif" ? matchesFromSarif(stdout, rule.config.captures, input.cwd) : matchesFromJson(stdout, rule.config.captures, input.cwd);
   }),
   async check(input) {
@@ -384,10 +413,6 @@ var commandDetector = {
   }
 };
 
-// src/detectors/linter/detector.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-
 // src/detectors/linter/resolve.ts
 import { access as access2, constants as constants2 } from "fs/promises";
 import path3 from "path";
@@ -432,8 +457,6 @@ var linterSchema = z3.object({
 }).strict();
 
 // src/detectors/linter/tools.ts
-import { realpathSync as realpathSync2 } from "fs";
-import path4 from "path";
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function json(tool, stdout) {
   try {
@@ -442,22 +465,6 @@ function json(tool, stdout) {
     throw new Error(`${tool} output is not JSON`);
   }
 }
-function relativeTo(roots, file) {
-  if (!path4.isAbsolute(file)) return file.split(path4.sep).join("/");
-  for (const root of roots) {
-    const relative = path4.relative(root, file);
-    if (!relative.startsWith("..") && !path4.isAbsolute(relative)) return relative.split(path4.sep).join("/");
-  }
-  return path4.relative(roots[0], file).split(path4.sep).join("/");
-}
-function rootsOf2(root) {
-  try {
-    const real = realpathSync2(root);
-    return real === root ? [root] : [root, real];
-  } catch {
-    return [root];
-  }
-}
 var number = (value, fallback) => typeof value === "number" ? value : fallback;
 var text = (value) => typeof value === "string" ? value : "";
 function oxlintRuleId(code) {
@@ -468,16 +475,17 @@ var TOOLS = {
   ruff: {
     events: ["edit", "verify"],
     args: (files) => ["check", "--output-format", "json", "--force-exclude", "--", ...files],
+    stdinArgs: (file) => ["check", "--output-format", "json", "--force-exclude", "--stdin-filename", file, "-"],
     parse(stdout, root) {
       const parsed = json("ruff", stdout);
       if (!Array.isArray(parsed)) throw new Error("ruff output is not a JSON array of diagnostics");
-      const roots = rootsOf2(root);
+      const relative = repoRelativeTo(root);
       return parsed.filter(isObject2).map((result) => {
         const start = isObject2(result.location) ? result.location : {};
         const end = isObject2(result.end_location) ? result.end_location : {};
         const line = number(start.row, 1);
         return {
-          file: relativeTo(roots, text(result.filename)),
+          file: relative(text(result.filename)),
           line,
           column: number(start.column, 1),
           endLine: number(end.row, line),
@@ -496,13 +504,13 @@ var TOOLS = {
       if (!isObject2(parsed) || !Array.isArray(parsed.diagnostics)) {
         throw new Error("oxlint output is not JSON with diagnostics");
       }
-      const roots = rootsOf2(root);
+      const relative = repoRelativeTo(root);
       return parsed.diagnostics.filter(isObject2).map((diagnostic) => {
         const label = Array.isArray(diagnostic.labels) ? diagnostic.labels[0] : void 0;
         const span = isObject2(label) && isObject2(label.span) ? label.span : {};
         const line = number(span.line, 1);
         return {
-          file: relativeTo(roots, text(diagnostic.filename)),
+          file: relative(text(diagnostic.filename)),
           line,
           column: number(span.column, 1),
           endLine: line,
@@ -517,17 +525,18 @@ var TOOLS = {
     // eslint is the slow one: spec §6 keeps it off the edit hook by default.
     events: ["verify"],
     args: (files) => ["--format=json", "--no-error-on-unmatched-pattern", "--", ...files],
+    stdinArgs: (file) => ["--format=json", "--stdin", "--stdin-filename", file],
     parse(stdout, root) {
       const parsed = json("eslint", stdout);
       if (!Array.isArray(parsed)) throw new Error("eslint output is not a JSON array of file results");
-      const roots = rootsOf2(root);
+      const relative = repoRelativeTo(root);
       const findings = [];
       for (const file of parsed.filter(isObject2)) {
         const messages = Array.isArray(file.messages) ? file.messages : [];
         for (const message of messages.filter(isObject2)) {
           const line = number(message.line, 1);
           findings.push({
-            file: relativeTo(roots, text(file.filePath)),
+            file: relative(text(file.filePath)),
             line,
             column: number(message.column, 1),
             endLine: number(message.endLine, line),
@@ -543,18 +552,6 @@ var TOOLS = {
 };
 
 // src/detectors/linter/detector.ts
-var exec2 = promisify2(execFile2);
-function sourceReader(cwd) {
-  const cache = /* @__PURE__ */ new Map();
-  return (file) => {
-    let source = cache.get(file);
-    if (source === void 0) {
-      source = readSourceFile(cwd, file);
-      cache.set(file, source);
-    }
-    return source;
-  };
-}
 function excerpt(source, finding) {
   if (source === null) return "";
   const starts = lineStarts(source);
@@ -568,41 +565,45 @@ function excerpt(source, finding) {
   }
   return source.slice(from, Math.max(from, to)).replace(/\n$/, "");
 }
-async function runTool(tool, files, cwd, signal) {
+async function runLinter(tool, files, cwd, signal) {
   const resolved = await resolveTool(tool, cwd);
   const args = [...resolved.prefix, ...TOOLS[tool].args(files)];
-  let stdout;
-  try {
-    const result = await exec2(resolved.command, args, { cwd, signal, maxBuffer: 64 * 1024 * 1024 });
-    stdout = result.stdout;
-  } catch (error) {
-    if (signal.aborted) throw error;
-    if (isNotFound(error)) throw new Error(`${tool} is not installed`);
-    const failure = error;
-    if (typeof failure.stdout !== "string") throw error;
-    stdout = failure.stdout;
-  }
+  const stdout = await runTool(resolved.command, args, { cwd, signal, notFound: `${tool} is not installed` });
   return TOOLS[tool].parse(stdout, cwd);
 }
+async function runLinterOnContent(tool, files, read, cwd, signal) {
+  const resolved = await resolveTool(tool, cwd);
+  const findings = [];
+  for (const file of files) {
+    const stdin = await read(file);
+    if (stdin === null) continue;
+    const args = [...resolved.prefix, ...TOOLS[tool].stdinArgs(file)];
+    const stdout = await runTool(resolved.command, args, { cwd, signal, notFound: `${tool} is not installed`, stdin });
+    findings.push(...TOOLS[tool].parse(stdout, cwd));
+  }
+  return findings;
+}
 var linterDetector = {
   kind: "linter",
   schema: linterSchema,
   captures: () => ["message", "ruleId"],
   // A copy: compileRule stores this as the rule's stages, and module-level data must not escape into it.
   events: (config) => [...TOOLS[config.tool].events],
+  takesContent: (config) => TOOLS[config.tool].stdinArgs !== void 0,
   async run(input) {
     const result = { findings: [], errors: [] };
     const byTool = /* @__PURE__ */ new Map();
     for (const rule of input.rules) {
       byTool.set(rule.config.tool, [...byTool.get(rule.config.tool) ?? [], rule]);
     }
-    const read = sourceReader(input.cwd);
+    const onDisk = input.fromDisk !== false;
+    const read = onDisk ? sourceReader(input.cwd) : input.read;
     await Promise.all(
       [...byTool].map(async ([tool, rules]) => {
         const files = [...new Set(rules.flatMap((rule) => rule.files))].sort();
         if (files.length === 0) return;
         try {
-          const findings = await runTool(tool, files, input.cwd, input.signal);
+          const findings = onDisk ? await runLinter(tool, files, input.cwd, input.signal) : await runLinterOnContent(tool, files, read, input.cwd, input.signal);
           for (const finding of findings) {
             const match = {
               file: finding.file,
@@ -619,7 +620,7 @@ var linterDetector = {
             }
           }
         } catch (error) {
-          if (input.signal.aborted) throw error;
+          if (pastDeadline(error, input)) throw error;
           const message = errorMessage(error);
           for (const rule of rules) result.errors.push({ rule: rule.id, message });
         }
@@ -722,17 +723,6 @@ var llmSchema = z4.object({
 }).strict();
 
 // src/detectors/llm/detector.ts
-function sourceReader2(cwd) {
-  const cache = /* @__PURE__ */ new Map();
-  return (file) => {
-    let source = cache.get(file);
-    if (source === void 0) {
-      source = readSourceFile(cwd, file);
-      cache.set(file, source);
-    }
-    return source;
-  };
-}
 function changedLinesOf(changes, file) {
   const change = changes.get(file);
   if (change === void 0) return null;
@@ -824,6 +814,15 @@ var llmDetector = {
   // verify only by default (spec §6): a model call is far too slow for an edit hook. A rule opts
   // in with `stages: [edit, verify]`.
   events: () => ["verify"],
+  // The prompt carries the file's text, so content that is not on disk needs no scratch copy.
+  takesContent: () => true,
+  // Spec §6, Consent: an llm rule sends file contents to a third party and costs money per file.
+  // Everything the core does differently for it follows from these, not from the name "llm".
+  metered: true,
+  cost: (config) => `llm \xB7 ${config.model} \xB7 sends file contents to your provider`,
+  fileBudget: (settings) => ({ max: settings.llm.maxFilesPerVerify, setting: "llm.max_files_per_verify" }),
+  // A field trial measured a single haiku call on a 135-line file at 89 s against a 60 s default.
+  timeoutHint: "an llm rule on a large file can need 120000 or more",
   async run(input) {
     const result = { findings: [], errors: [] };
     const settings = input.settings.llm;
@@ -833,13 +832,14 @@ var llmDetector = {
     } catch (error) {
       return { findings: [], errors: [{ rule: null, message: errorMessage(error) }] };
     }
-    const calls = await groupCalls(input.rules, input.changes, sourceReader2(input.cwd));
+    const read = input.fromDisk === false ? input.read : sourceReader(input.cwd);
+    const calls = await groupCalls(input.rules, input.changes, read);
     const outcomes = await Promise.all(
       calls.map(async (call) => {
         try {
           return { call, findings: await runCall(call, provider, settings, input) };
         } catch (error) {
-          if (input.signal.aborted) throw error;
+          if (pastDeadline(error, input)) throw error;
           return { call, error };
         }
       })
@@ -923,6 +923,8 @@ var pathDetector = {
   captures: () => [],
   events: () => ["edit", "verify"],
   guards: true,
+  // The match is the file itself, and writing it is what the rule forbids.
+  wholeFile: true,
   run: perRule(async (rule, input) => {
     const matches = [];
     for (const file of rule.files) {
@@ -1162,18 +1164,38 @@ function hooksOf(settings) {
   if (!isObject3(hooks)) throw new SettingsError('"hooks" must be an object');
   return hooks;
 }
-function mergeHooks(settings, command, verifyMs) {
+function mergeHooks(settings, command, verifyMs, keep) {
   const merged = { ...hooksOf(settings) };
   const added = [];
+  const updated = [];
   for (const { event, matcher: matcher2, timeout } of hookGroups(verifyMs)) {
     const groups = merged[event] ?? [];
     if (!Array.isArray(groups)) throw new SettingsError(`"hooks.${event}" must be an array`);
-    if (installed(groups, matcher2)) continue;
+    if (installed(groups, matcher2)) {
+      let changed = false;
+      const rewritten = groups.map((group) => {
+        if (!isObject3(group) || group.matcher !== matcher2 || !Array.isArray(group.hooks)) return group;
+        return {
+          ...group,
+          hooks: group.hooks.map((hook2) => {
+            const current = hook2.command;
+            if (!isRulecastHook(hook2) || current === command || current === keep) return hook2;
+            changed = true;
+            return { ...hook2, command };
+          })
+        };
+      });
+      if (changed) {
+        merged[event] = rewritten;
+        updated.push(matcher2 === void 0 ? event : `${event} (${matcher2})`);
+      }
+      continue;
+    }
     const hook = { type: "command", command, timeout };
     merged[event] = [...groups, matcher2 === void 0 ? { hooks: [hook] } : { matcher: matcher2, hooks: [hook] }];
     added.push(matcher2 === void 0 ? event : `${event} (${matcher2})`);
   }
-  return { settings: { ...settings, hooks: merged }, added };
+  return { settings: { ...settings, hooks: merged }, added, updated };
 }
 function removeHooks(settings) {
   const hooks = hooksOf(settings);
@@ -1206,9 +1228,11 @@ function removeHooks(settings) {
 // src/adapters/claude-code/adapter.ts
 var CONTEXT_LIMIT = 1e4;
 var CONTEXT_BUDGET = 9e3;
-var BLOCK_PREAMBLE = "This project's rulecast rules (.rulecast-config.yaml) found problems in code changed in this session. Fix them before you finish.";
+var BLOCK_PREAMBLE = `This project's rulecast rules (.rulecast-config.yaml) found problems in code changed in this session. Fix them before you finish. If you believe a finding is wrong, say so to the user rather than changing .rulecast-config.yaml; add a "rulecast-ignore: <rule> <reason>" comment only if they agree.`;
 var CAP_PREAMBLE = "rulecast: the agent stopped with these findings unresolved (stop gate limit reached).";
 var DENY_PREAMBLE = "This project's rulecast rules (.rulecast-config.yaml) refuse this write. Change what you are writing, or the file you are writing it to, and try again.";
+var NOT_INSTALLED = "rulecast is configured in this project but not installed. Run npm install (or pnpm install), then rulecast doctor.";
+var LOCAL_COMMAND = `B="$CLAUDE_PROJECT_DIR"/node_modules/.bin/rulecast; [ -x "$B" ] && exec "$B" hook claude-code; grep -q '"hook_event_name": *"SessionStart"' && printf '%s' '${JSON.stringify({ systemMessage: NOT_INSTALLED })}'; exit 0`;
 function cutNotice(delivery, event) {
   if (delivery.overflowPath !== null) {
     return `
@@ -1238,8 +1262,12 @@ var claudeCodeAdapter = {
   restoredFiles: 5,
   parse: parseClaudeCode,
   format(delivery, event, options) {
-    const text2 = renderAgentText(delivery, options);
-    if (text2 === "") return NONE;
+    const text2 = renderAgentText(delivery, { ...options, notices: false, warnings: false });
+    const problems = delivery.warnings.length === 0 ? [] : ["rulecast problems:", ...delivery.warnings.map((w) => `  - ${w}`)];
+    const notices = [...delivery.notices ?? [], ...problems].join("\n");
+    const userOnly = event.kind === "guard" ? NONE : json2({ systemMessage: notices });
+    if (text2 === "") return notices === "" ? NONE : userOnly;
+    const withNotices = (value) => notices === "" ? value : { ...value, systemMessage: notices };
     switch (event.kind) {
       case "guard":
         return json2({
@@ -1253,23 +1281,36 @@ ${text2}`, delivery, event)
         });
       case "touch":
       case "edit":
-        return json2({
-          hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: withinLimit(text2, delivery, event) }
-        });
+        return json2(
+          withNotices({
+            hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: withinLimit(text2, delivery, event) }
+          })
+        );
       case "reset":
-        return json2({
-          hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: withinLimit(text2, delivery, event) }
-        });
+        return json2(
+          withNotices({
+            hookSpecificOutput: {
+              hookEventName: "SessionStart",
+              additionalContext: withinLimit(text2, delivery, event)
+            }
+          })
+        );
       case "verify":
         if (delivery.stop === "block")
-          return json2({ decision: "block", reason: withinLimit(`${BLOCK_PREAMBLE}
+          return json2(
+            withNotices({ decision: "block", reason: withinLimit(`${BLOCK_PREAMBLE}
 
-${text2}`, delivery, event) });
-        if (delivery.stop === "capReached")
-          return json2({ systemMessage: withinLimit(`${CAP_PREAMBLE}
+${text2}`, delivery, event) })
+          );
+        if (delivery.stop === "capReached") {
+          const cap = withinLimit(`${CAP_PREAMBLE}
 
-${text2}`, delivery, event) });
-        return NONE;
+${text2}`, delivery, event);
+          return json2({ systemMessage: notices === "" ? cap : `${notices}
+
+${cap}` });
+        }
+        return notices === "" ? NONE : json2({ systemMessage: notices });
       default:
         return NONE;
     }
@@ -1280,8 +1321,11 @@ ${text2}`, delivery, event) });
       { scope: "shared", file: ".claude/settings.json" },
       { scope: "personal", file: ".claude/settings.local.json" }
     ],
-    command: (local) => local ? '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/rulecast hook claude-code' : "rulecast hook claude-code",
-    merge: mergeHooks,
+    command: (local) => local ? LOCAL_COMMAND : "rulecast hook claude-code",
+    // The guarded command is never rewritten to the bare one. It is right with or without
+    // node_modules, and `install` in a clone that has not installed yet would otherwise swap the
+    // committed command for one that exits 127 on every hook.
+    merge: (settings, command, verifyMs) => mergeHooks(settings, command, verifyMs, LOCAL_COMMAND),
     remove: removeHooks
   }
 };
@@ -1292,10 +1336,74 @@ function adapterByName(name) {
   return ADAPTERS.find((adapter) => adapter.name === name);
 }
 
+// src/adapters/cli/backlog.ts
+function summarise(delivery) {
+  const byRule = /* @__PURE__ */ new Map();
+  const byFile = /* @__PURE__ */ new Map();
+  const add = (rule, file, count) => {
+    const entry = byRule.get(rule) ?? { violations: 0, files: /* @__PURE__ */ new Set() };
+    entry.violations += count;
+    entry.files.add(file);
+    byRule.set(rule, entry);
+    byFile.set(file, (byFile.get(file) ?? 0) + count);
+  };
+  for (const finding of delivery.findings) add(finding.rule, finding.file, finding.count);
+  for (const summary of delivery.preexistingSummary) add(summary.rule, summary.file, summary.count);
+  const rules = [...byRule].map(([rule, entry]) => ({ rule, violations: entry.violations, files: entry.files.size })).sort((a, b) => b.violations - a.violations || (a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
+  const files = [...byFile].map(([file, violations]) => ({ file, violations })).sort((a, b) => b.violations - a.violations || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return {
+    rules,
+    files,
+    totalViolations: rules.reduce((sum, entry) => sum + entry.violations, 0),
+    totalFiles: files.length
+  };
+}
+var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function table(header, rows) {
+  const widths = header.map((_, column) => Math.max(...[header, ...rows].map((row) => row[column].length)));
+  const line = (row) => `  ${row.map((cell, column) => column === 0 ? cell.padEnd(widths[column]) : cell.padStart(widths[column])).join("  ")}`;
+  return [line(header), ...rows.map(line)];
+}
+function renderBacklog(summary, options) {
+  if (summary.totalViolations === 0) return "backlog: no violations";
+  const out = [
+    `backlog: ${plural(summary.totalViolations, "violation")} in ${plural(summary.totalFiles, "file")}`,
+    "",
+    ...table(
+      ["rule", "violations", "files"],
+      summary.rules.map((entry) => [entry.rule, String(entry.violations), String(entry.files)])
+    )
+  ];
+  const shown = summary.files.slice(0, options.topFiles);
+  if (shown.length > 0) {
+    out.push(
+      "",
+      ...table(
+        ["worst files", "violations"],
+        shown.map((entry) => [entry.file, String(entry.violations)])
+      )
+    );
+    const rest = summary.files.length - shown.length;
+    if (rest > 0) out.push(`  \u2026and ${plural(rest, "more file")}`);
+  }
+  if (options.note === false) return out.join("\n");
+  out.push(
+    "",
+    "This is the stock, not a rate. Enforcement on edits does not reduce it.",
+    "Remediate a file at a time: a file that already follows a rule rarely breaks it."
+  );
+  return out.join("\n");
+}
+
 export {
   createRegistry,
+  runTool,
+  repoRelativeTo,
+  repoRelative,
   builtinDetectors,
   claudeCodeAdapter,
   ADAPTERS,
-  adapterByName
+  adapterByName,
+  summarise,
+  renderBacklog
 };