@syv-ai/rulecast 0.3.0 → 0.4.0

package/README.md

@@ -89,19 +89,96 @@ A refusal only ever rests on the text the agent is writing, never on a reconstru
 
 | Command | Does |
 |---|---|
-| `rulecast init` | Interactive setup |
-| `rulecast install` / `uninstall` | Add or remove the agent hooks |
-| `rulecast run` | Check staged files, changed files, or everything |
+| `rulecast init` | Set rulecast up: config, catalog rules, agent hooks |
+| `rulecast install` / `uninstall` | Add (or upgrade) or remove the agent hooks |
+| `rulecast run` | Check staged files (the default), changed files, or everything |
+| `rulecast list` | Show every configured rule: where it comes from, what it matches, what it cites |
 | `rulecast test` | Run each rule's good/bad examples; `--against` says how much it would flag |
-| `rulecast validate` | Check the config and print diagnostics |
-| `rulecast doctor` | Compile, check the environment, dry-run every rule |
+| `rulecast validate` | Check the config (and a rules manifest) and print diagnostics |
+| `rulecast doctor` | Compile, check the environment and hooks, dry-run every rule |
 | `rulecast autoupdate` | Move pinned rule repos to their latest tag |
 | `rulecast try-repo` | Run a rule repo against your project without configuring it |
 | `rulecast clean` | Delete the cache |
 | `rulecast warm` | Build detector caches ahead of time |
-| `rulecast hook <adapter>` | Answer an agent hook on stdin |
+| `rulecast hook <adapter>` | Answer an agent hook on stdin (the agent runs this, not you) |
 
-`rulecast run` is also how you use rulecast in CI. `--from-ref main` checks only what a branch changed, which matters most for `llm` rules — they judge changed files only.
+`rulecast <command> --help` prints a command's flags; `rulecast --version` prints the version.
+
+## Git hooks and CI
+
+The same rule reports the same line the same way in an agent hook, a git hook and CI. What counts as new is a match on a line you changed; a violation that was already there is backlog, shown and never failing.
+
+- **Pre-commit:** `rulecast run` with no file flags checks the staged files, reads their content from the index (what is being committed, not the working tree), and judges it against `HEAD`. `llm` rules are skipped unless you pass `--llm`, and one line says so: a commit should not cost money.
+- **Pre-push and CI:** `rulecast run --from-ref A --to-ref B` checks the files changed between the merge base with `A` and `B`, reading them at `B`. Without `--to-ref` it reads the working tree.
+- `rulecast run --files F...` judges files whole, with no baseline. Use the hook below rather than `--files` from a hook manager.
+
+rulecast installs no git hooks itself: lefthook, husky and pre-commit already own `.git/hooks`. Add `@syv-ai/rulecast` to the project's devDependencies (the agent hooks need it there anyway), and wire it into the one you use.
+
+**pre-commit** (`.pre-commit-config.yaml`):
+
+```yaml
+minimum_pre_commit_version: "3.2.0"
+repos:
+  - repo: https://github.com/syv-ai/rulecast
+    rev: v0.4.0
+    hooks:
+      - id: rulecast
+      - id: rulecast-push
+```
+
+**lefthook** (`lefthook.yml`):
+
+```yaml
+pre-commit:
+  jobs:
+    - name: rulecast
+      run: npx --no-install rulecast run
+pre-push:
+  jobs:
+    - name: rulecast
+      run: npx --no-install rulecast run --from-ref "$(git merge-base origin/HEAD HEAD)" --to-ref HEAD
+```
+
+**GitHub Actions:**
+
+```yaml
+on: pull_request
+jobs:
+  rulecast:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # rulecast needs the merge base with the target branch
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npx rulecast run --from-ref origin/${{ github.base_ref }} --format sarif > rulecast.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always() # rulecast exits 1 on findings, which is when the upload matters
+        with:
+          sarif_file: rulecast.sarif
+```
+
+A shallow clone has no merge base; rulecast says so and names `fetch-depth: 0`. `--from-ref` runs `llm` rules, which judge changed files only.
+
+`command` scripts, and `oxlint`, are handed a scratch copy of each file in staged and `--to-ref` runs, because the content to judge is not the file on disk. `ruff` and `eslint` get it on stdin under the real path, so path-keyed configuration still applies.
+
+## Turning a rule off
+
+- **A whole rule:** `enabled: false` on the rule. Under a rule repo's entry, `- id: <rule>` with `enabled: false` switches a catalog rule off and keeps the line.
+- **One finding:** a comment on the matched line or the line above it, in the file's own comment syntax. The reason is required; an ignore without one suppresses nothing.
+
+  ```python
+  # rulecast-ignore: python/no-httpexception-in-services legacy endpoint, removed in #412
+  raise HTTPException(404)
+  ```
+
+`rulecast run --all-files --summary` counts the ignores, and an ignore or a config change made during an agent session is reported to you when the agent stops: the agent cannot quietly edit its way past a rule.
 
 ## Adopting a rule on a codebase that already breaks it
 
@@ -143,7 +220,7 @@ rulecast up itself:
 
 ```text
 Set up rulecast in this project. Read
-https://raw.githubusercontent.com/syv-ai/rulecast/v0.3.0/agents/SETUP.md
+https://raw.githubusercontent.com/syv-ai/rulecast/v0.4.0/agents/SETUP.md
 and follow it. Show me every file it creates or changes before I commit anything.
 ```
 
@@ -183,7 +260,7 @@ The budget is what shapes the design: one detector run per kind per event, kinds
 
 ## Status
 
-0.1. Everything above works and is tested. The config format may still change before 1.0 — `minimum_rulecast_version` exists so a rule can say what it needs.
+0.4. Everything above works and is tested. Before 1.0 the config format and the output of `rulecast run` may still change; `minimum_rulecast_version` exists so a rule can say what it needs.
 
 Next: adapters for Codex, Cursor and OpenCode; Biome; an Azure OpenAI provider.
 

package/dist/{chunk-HZUATJ53.js → chunk-DQUCE2IK.js}

@@ -1,8 +1,31 @@
+// src/core/version.ts
+var VERSION = "0.4.0";
+function parseVersion(text) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+function isOlder(running, minimum) {
+  const a = parseVersion(running);
+  const b = parseVersion(minimum);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i];
+  }
+  return false;
+}
+
 // src/core/detection/per-rule.ts
 import { readFile, stat } from "fs/promises";
 import path from "path";
 
 // src/core/errors.ts
+import {
+  ZodDefault,
+  ZodEffects,
+  ZodNullable,
+  ZodObject,
+  ZodOptional
+} from "zod";
 var DeadlineError = class extends Error {
 };
 function isNotFound(error) {
@@ -11,11 +34,75 @@ function isNotFound(error) {
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function formatZodError(error) {
-  return error.issues.map((issue) => `${issue.path.length ? issue.path.join(".") : "(root)"}: ${issue.message}`).join("; ");
+function formatZodError(error, options = {}) {
+  const where = (path7) => [options.prefix, ...path7.map(String)].filter((part) => part !== void 0 && part !== "").join(".");
+  const describe = (issue) => {
+    const at = where(issue.path);
+    const label = at === "" ? "" : `${at}: `;
+    if (issue.code === "unrecognized_keys") {
+      const known = options.schema === void 0 ? [] : keysAt(options.schema, issue.path);
+      const missing = missingAt(error.issues, issue.path);
+      const standIn = issue.keys.length === 1 && missing.length === 1 ? missing[0] : null;
+      return issue.keys.map((key) => {
+        const guess = closest(key, known) ?? standIn;
+        return `${label}unknown key "${key}"${guess === null ? "" : ` (did you mean "${guess}"?)`}`;
+      }).join("; ");
+    }
+    const message = issue.message === "Required" ? "required" : issue.message;
+    return `${label}${message}`;
+  };
+  const ordered = [
+    ...error.issues.filter((issue) => issue.code === "unrecognized_keys"),
+    ...error.issues.filter((issue) => issue.code !== "unrecognized_keys")
+  ];
+  return ordered.map(describe).join("; ");
+}
+function keysAt(schema, path7) {
+  let current = schema;
+  const unwrap = (type) => {
+    if (type instanceof ZodOptional || type instanceof ZodNullable) return unwrap(type.unwrap());
+    if (type instanceof ZodDefault) return unwrap(type._def.innerType);
+    if (type instanceof ZodEffects) return unwrap(type.innerType());
+    return type;
+  };
+  for (const segment of path7) {
+    const object2 = current === void 0 ? void 0 : unwrap(current);
+    current = object2 instanceof ZodObject ? object2.shape[String(segment)] : void 0;
+  }
+  const object = current === void 0 ? void 0 : unwrap(current);
+  return object instanceof ZodObject ? Object.keys(object.shape) : [];
+}
+function missingAt(issues, path7) {
+  return issues.filter(
+    (issue) => issue.code === "invalid_type" && issue.received === "undefined" && issue.path.length === path7.length + 1 && path7.every((segment, index) => issue.path[index] === segment)
+  ).map((issue) => String(issue.path.at(-1)));
+}
+function closest(key, known) {
+  let best = null;
+  for (const candidate of known) {
+    const distance = levenshtein(key, candidate);
+    if (distance <= 2 && (best === null || distance < best.distance)) best = { key: candidate, distance };
+  }
+  return best?.key ?? null;
+}
+function levenshtein(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = above;
+    }
+  }
+  return row[b.length];
 }
 
 // src/core/detection/per-rule.ts
+function pastDeadline(error, input) {
+  return error instanceof DeadlineError || input.signal.aborted || Date.now() > input.deadlineAt;
+}
 function perRule(detect) {
   return async (input) => {
     const result = { findings: [], errors: [] };
@@ -24,7 +111,7 @@ function perRule(detect) {
         try {
           for (const match of await detect(rule, input)) result.findings.push({ rule: rule.id, match });
         } catch (error) {
-          if (error instanceof DeadlineError || input.signal.aborted || Date.now() > input.deadlineAt) throw error;
+          if (pastDeadline(error, input)) throw error;
           result.errors.push({ rule: rule.id, message: errorMessage(error) });
         }
       })
@@ -40,6 +127,17 @@ async function readSourceFile(cwd, file) {
     throw error;
   }
 }
+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;
+  };
+}
 async function fileBytes(cwd, file) {
   try {
     return (await stat(path.resolve(cwd, file))).size;
@@ -48,6 +146,30 @@ async function fileBytes(cwd, file) {
   }
 }
 
+// src/core/detection/positions.ts
+function lineStarts(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return starts;
+}
+function positionAt(starts, offset) {
+  let low = 0;
+  let high = starts.length - 1;
+  while (low < high) {
+    const mid = low + high + 1 >> 1;
+    if (starts[mid] <= offset) low = mid;
+    else high = mid - 1;
+  }
+  return { line: low + 1, column: offset - starts[low] + 1 };
+}
+function offsetAt(starts, line, column, length) {
+  const index = Math.min(Math.max(line, 1), starts.length) - 1;
+  const offset = starts[index] + Math.max(column, 1) - 1;
+  return Math.min(Math.max(offset, 0), length);
+}
+
 // src/detectors/llm/models.ts
 var ALIASES = {
   haiku: {
@@ -171,14 +293,14 @@ function keyAvailability(settings, env, fallback, path7) {
 
 // src/detectors/llm/providers/anthropic.ts
 var API = "https://api.anthropic.com";
-var VERSION = "2023-06-01";
+var VERSION2 = "2023-06-01";
 var anthropicProvider = {
   name: "anthropic",
   async ask(request) {
     const key = apiKey(request);
     const reply = await postJson(
       endpoint(request.settings.baseUrl, API, "/v1/messages"),
-      { "x-api-key": key, "anthropic-version": VERSION },
+      { "x-api-key": key, "anthropic-version": VERSION2 },
       {
         model: request.model,
         max_tokens: 4096,
@@ -403,22 +525,6 @@ function emptyDelivery() {
   };
 }
 
-// src/core/version.ts
-var VERSION2 = "0.3.0";
-function parseVersion(text) {
-  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text);
-  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
-}
-function isOlder(running, minimum) {
-  const a = parseVersion(running);
-  const b = parseVersion(minimum);
-  if (!a || !b) return false;
-  for (let i = 0; i < 3; i++) {
-    if (a[i] !== b[i]) return a[i] < b[i];
-  }
-  return false;
-}
-
 // src/core/template.ts
 var VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
 var CORE_VARIABLES = ["file", "line", "column", "text", "rule"];
@@ -458,6 +564,18 @@ var GROUP_FROM = 3;
 var GROUP_MIN_LITERAL = 40;
 var MAX_LOCATION_PAD = 40;
 var BACKLOG_HINT = "  see all of it: rulecast run --all-files --summary";
+var BACKLOG_HEADING = "backlog in files you touched (not from your edit; leave it unless asked):";
+var WARNINGS_HEADING = "rulecast warnings:";
+var CONVENTIONS_TITLE = "rulecast: conventions for the files you are working on";
+var NOTICES_HEADING = "rulecast notices (for the user):";
+var backlogLine = (summary) => `  ${summary.rule} \xD7${summary.count} in ${summary.file}`;
+var backlogMoreLine = (count) => `  \u2026and ${count} more`;
+var warningLine = (warning) => `  - ${warning}`;
+var overflowLines = (rules, path7) => [
+  `\u2026${plural(rules, "rule")} and the conventions they cite did not fit here.`,
+  "Every finding, with the doc sections it cites, is in:",
+  `  ${path7}`
+];
 var WRAP = 96;
 var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 function header(delivery) {
@@ -468,7 +586,7 @@ function header(delivery) {
     return `rulecast: ${plural(rules, "rule")} violated${where}`;
   }
   if (delivery.references.length > 0 || delivery.preexistingSummary.length > 0) {
-    return "rulecast: conventions for the files you are working on";
+    return CONVENTIONS_TITLE;
   }
   return null;
 }
@@ -545,12 +663,66 @@ function ruleBlock(rule, findings, template, dropped, options) {
   }
   return out;
 }
-function measureRuleBlock(rule, findings, template, options) {
-  return ruleBlock(rule, findings, template, { count: 0, files: 0 }, options).join("\n").length + 1;
+var linesCost = (lines) => lines.reduce((sum, line) => sum + line.length + 1, 0);
+function measureRuleBlock(rule, shown, all, template, options) {
+  const shownFiles = new Set(shown.map((finding) => finding.file));
+  const rest = all.slice(shown.length);
+  const cut = { count: rest.length, files: new Set(rest.map((f) => f.file).filter((f) => !shownFiles.has(f))).size };
+  return linesCost([...ruleBlock(rule, shown, template, cut, options), ""]);
 }
+var OVERFLOW_PATH_ALLOWANCE = 192;
+var deliveryCost = {
+  /**
+   * The title and the blank line under it, at its longest — two things about it are not known yet.
+   * It names a file when every *delivered* finding is in one, and the budget may cut a rule down to
+   * findings in a single file however many files it fired in; so the longest file name is charged.
+   * And if the budget drops every rule that fired, no findings are left and the conventions title
+   * prints instead; so with `conventions` the longer of the two is charged.
+   */
+  header(rules, files, conventions) {
+    const longest = [...files].reduce((most, file) => file.length > most.length ? file : most, "");
+    const where = longest === "" ? "" : ` in ${longest}`;
+    const violated = rules > 0 ? linesCost([`rulecast: ${plural(rules, "rule")} violated${where}`, ""]) : 0;
+    return Math.max(violated, conventions ? linesCost([CONVENTIONS_TITLE, ""]) : 0);
+  },
+  /**
+   * One reference's line, at its longest — the "not included, too long" form, naming the file when
+   * it has an absolute location. Every other state prints a shorter line, so this bounds them all.
+   */
+  referenceLine(ref, location) {
+    return linesCost(referenceLines({ ref, state: "read", reason: "budget", location }));
+  },
+  /** What a reference given in full adds over its one-line price: the content and the blank line. */
+  referenceContent(ref, content, location) {
+    return linesCost(referenceLines({ ref, state: "full", content })) - deliveryCost.referenceLine(ref, location);
+  },
+  /** The blank line that closes the references, once. */
+  referencesEnd: 1,
+  /** The warnings heading, once. */
+  warningsFrame: linesCost([WARNINGS_HEADING]),
+  warning(text) {
+    return linesCost([warningLine(text)]);
+  },
+  /**
+   * The backlog's heading, its hint, the blank line after, and the "…and N more" line at its
+   * longest — printed only when summaries are cut, and charged up front so a cut cannot overflow.
+   */
+  backlogFrame(summaries) {
+    return linesCost([BACKLOG_HEADING, backlogMoreLine(summaries), BACKLOG_HINT, ""]);
+  },
+  backlogSummary(summary) {
+    return linesCost([backlogLine(summary)]);
+  },
+  /** The lines naming the overflow file, and the blank line before them. */
+  overflowNotice(rules) {
+    return linesCost(["", ...overflowLines(rules, "x".repeat(OVERFLOW_PATH_ALLOWANCE))]);
+  }
+};
 function renderAgentText(delivery, options) {
   const title = header(delivery);
-  if (title === null && delivery.warnings.length === 0) return "";
+  const notices = options.notices === false ? [] : delivery.notices ?? [];
+  const warnings = options.warnings === false ? [] : delivery.warnings;
+  if (title === null && warnings.length === 0 && notices.length === 0) return "";
   const out = [];
   if (title !== null) out.push(title, "");
   const byRule = /* @__PURE__ */ new Map();
@@ -564,25 +736,23 @@ function renderAgentText(delivery, options) {
     out.push("");
   }
   if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) {
-    out.push("backlog in files you touched (not from your edit):");
-    for (const summary of delivery.preexistingSummary) {
-      out.push(`  ${summary.rule} \xD7${summary.count} in ${summary.file}`);
-    }
-    if (delivery.omitted.preexisting > 0) out.push(`  \u2026and ${delivery.omitted.preexisting} more`);
+    out.push(BACKLOG_HEADING);
+    for (const summary of delivery.preexistingSummary) out.push(backlogLine(summary));
+    if (delivery.omitted.preexisting > 0) out.push(backlogMoreLine(delivery.omitted.preexisting));
     out.push(BACKLOG_HINT, "");
   }
   for (const reference of delivery.references) out.push(...referenceLines(reference));
   if (out.length > 0 && out.at(-1) !== "") out.push("");
-  if (delivery.warnings.length > 0) {
-    out.push("rulecast warnings:", ...delivery.warnings.map((warning) => `  - ${warning}`));
+  if (warnings.length > 0) {
+    out.push(WARNINGS_HEADING, ...warnings.map(warningLine));
   }
   if (delivery.overflowPath !== null) {
     if (out.at(-1) !== "") out.push("");
-    out.push(
-      `\u2026${plural(delivery.omitted.rules, "rule")} and the conventions they cite did not fit here.`,
-      "Every finding, with the doc sections it cites, is in:",
-      `  ${delivery.overflowPath}`
-    );
+    out.push(...overflowLines(delivery.omitted.rules, delivery.overflowPath));
+  }
+  if (notices.length > 0) {
+    if (out.length > 0 && out.at(-1) !== "") out.push("");
+    out.push(NOTICES_HEADING, ...notices.map(warningLine));
   }
   while (out.at(-1) === "") out.pop();
   return out.join("\n");
@@ -759,8 +929,8 @@ function fileOf(spec) {
 async function compileRule(input, context) {
   const { data } = input;
   const minimum = data.minimum_rulecast_version;
-  if (minimum !== void 0 && isOlder(VERSION2, minimum)) {
-    return `requires rulecast ${minimum} or newer (running ${VERSION2})`;
+  if (minimum !== void 0 && isOlder(VERSION, minimum)) {
+    return `requires rulecast ${minimum} or newer (running ${VERSION})`;
   }
   let detector = null;
   let defaultStages = ["touch"];
@@ -769,7 +939,8 @@ async function compileRule(input, context) {
     const implementation = context.registry.get(kind);
     if (!implementation) return `unknown detector "${kind}"`;
     const parsed = await implementation.schema.safeParseAsync(rawConfig ?? {});
-    if (!parsed.success) return `detect.${kind}: ${formatZodError(parsed.error)}`;
+    if (!parsed.success)
+      return formatZodError(parsed.error, { prefix: `detect.${kind}`, schema: implementation.schema });
     detector = { kind, config: parsed.data, captures: implementation.captures(parsed.data) };
     defaultStages = implementation.events(parsed.data);
   }
@@ -832,7 +1003,9 @@ async function compileRule(input, context) {
     severity: data.severity ?? "error",
     scope: data.scope ?? "instance",
     refuseWrite: data.refuse_write === true,
+    enabled: data.enabled !== false,
     stages,
+    patterns: { files: data.files ?? "", exclude: data.exclude ?? "^$" },
     matches: (file) => global(file) && filter(file),
     detector,
     message: data.message ?? null,
@@ -880,37 +1053,18 @@ function detectorCacheDir(stateDir, kind) {
   return path6.join(stateDir, "cache", kind);
 }
 
-// src/core/detection/positions.ts
-function lineStarts(text) {
-  const starts = [0];
-  for (let i = 0; i < text.length; i++) {
-    if (text.charCodeAt(i) === 10) starts.push(i + 1);
-  }
-  return starts;
-}
-function positionAt(starts, offset) {
-  let low = 0;
-  let high = starts.length - 1;
-  while (low < high) {
-    const mid = low + high + 1 >> 1;
-    if (starts[mid] <= offset) low = mid;
-    else high = mid - 1;
-  }
-  return { line: low + 1, column: offset - starts[low] + 1 };
-}
-function offsetAt(starts, line, column, length) {
-  const index = Math.min(Math.max(line, 1), starts.length) - 1;
-  const offset = starts[index] + Math.max(column, 1) - 1;
-  return Math.min(Math.max(offset, 0), length);
-}
-
 export {
   DeadlineError,
   isNotFound,
   errorMessage,
   formatZodError,
+  VERSION,
+  parseVersion,
+  isOlder,
+  pastDeadline,
   perRule,
   readSourceFile,
+  sourceReader,
   fileBytes,
   onPath,
   CORE_VARIABLES,
@@ -927,11 +1081,8 @@ export {
   LLM_PROVIDERS,
   defaultDetectorSettings,
   emptyDelivery,
-  VERSION2 as VERSION,
-  parseVersion,
-  isOlder,
-  BACKLOG_HINT,
   measureRuleBlock,
+  deliveryCost,
   renderAgentText,
   tagsOf,
   compileFilter,