@syv-ai/rulecast 0.2.0 → 0.4.0

package/README.md

@@ -89,24 +89,148 @@ 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 validate` | Check the config and print diagnostics |
-| `rulecast doctor` | Compile, check the environment, dry-run every rule |
+| `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 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
+
+`rulecast run --all-files --summary` tells you how much you already owe:
+
+```text
+backlog: 57 violations in 31 files
+
+  rule                            violations  files
+  python/routes-never-call-crud           57     31
+
+  worst files                     violations
+  app/api/routes/orders.py                12
+  app/api/routes/users.py                  9
+```
+
+Watch the count, not the rate. Here is one real codebase on one rule, on `main`:
+
+| date | violating / total |
+|---|---|
+| 2026-01-15 | 61 / 80 |
+| 2026-06-01 | 58 / 143 |
+| 2026-09-25 | 57 / 194 |
+
+The rate fell from 76% to 29% and the count did not move. New code complied; the old violations were
+never fixed, only diluted. A team watching the percentage would have believed it was winning.
+
+Per-edit enforcement does not touch that stock — it only stops it growing. Fix it a file at a time:
+edits to files that already followed the rule broke it 2% of the time, against 37% in files that
+mostly did not, so a file you clean tends to stay clean. (One rule across 19 files: suggestive, not
+proven.)
 
 If something is configured but quiet, `rulecast doctor` says why: it compiles the config, reports whether each rule's linter, parser, script or API key is actually there, says where the hooks and caches live, and runs every rule against one file it matches.
 
 ## Agents
 
-rulecast ships docs written for coding agents, not for people:
+rulecast ships docs written for coding agents, not for people. Paste this to yours and it will set
+rulecast up itself:
+
+```text
+Set up rulecast in this project. Read
+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.
+```
+
+If your agent cannot fetch a URL, this is the whole of it: run
+`npx @syv-ai/rulecast init --yes --agent <your agent, e.g. claude-code>`, then show me
+`.rulecast-config.yaml` and the other files it listed. Never edit hook settings by hand —
+`rulecast install` and `rulecast uninstall` own them.
+
+Once it is set up, ask the same agent to draft rules for your own conventions; `init` prints the
+prompt to paste.
 
 - [`agents/SETUP.md`](https://github.com/syv-ai/rulecast/blob/main/agents/SETUP.md) — give this to your agent and it will set rulecast up itself.
 - [`agents/DRAFT-RULES.md`](https://github.com/syv-ai/rulecast/blob/main/agents/DRAFT-RULES.md) — it reads your `AGENTS.md`, proposes one rule per convention that code can visibly break, shows you what each would flag today, and asks you to keep, edit or drop it.
@@ -136,9 +260,9 @@ 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; rule tests (good and bad examples run by `rulecast test`); an Azure OpenAI provider.
+Next: adapters for Codex, Cursor and OpenCode; Biome; an Azure OpenAI provider.
 
 ## License
 

package/dist/{chunk-ZEFEQKG5.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.2.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"];
@@ -457,6 +563,19 @@ function templateBindings(template) {
 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) {
@@ -467,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;
 }
@@ -544,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();
@@ -562,25 +735,24 @@ function renderAgentText(delivery, options) {
     out.push(...ruleBlock(rule, findings, delivery.templates[rule], omittedFor(delivery.omitted, rule), options));
     out.push("");
   }
-  for (const summary of delivery.preexistingSummary) {
-    out.push(`pre-existing (not blocking): ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+  if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) {
+    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, "");
   }
-  if (delivery.omitted.preexisting > 0) {
-    out.push(`\u2026and ${delivery.omitted.preexisting} more pre-existing (not blocking)`);
-  }
-  if (delivery.preexistingSummary.length > 0 || delivery.omitted.preexisting > 0) out.push("");
   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");
@@ -757,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"];
@@ -767,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);
   }
@@ -788,6 +961,8 @@ async function compileRule(input, context) {
     if (unknown) return `unknown template variable "${unknown}"`;
   } else {
     if (data.refuse_write) return "refuse_write needs detect: there is nothing to refuse a write for";
+    if (data.scope) return "scope needs detect: there is nothing to classify";
+    if (data.examples) return "examples need detect: there is nothing to run them against";
     if (stages.some((stage) => stage !== "touch")) return "rules without detect need stages: [touch]";
     if (data.message !== void 0) return "message needs detect";
     if (!data.context?.length) return "rules without detect need context";
@@ -800,6 +975,9 @@ async function compileRule(input, context) {
     excludeTypes: data.exclude_types ?? []
   });
   if (typeof filter === "string") return filter;
+  for (const example of [...data.examples?.good ?? [], ...data.examples?.bad ?? []]) {
+    if (!filter(example.path)) return `example path "${example.path}" does not match this rule's files`;
+  }
   const references = [];
   for (const reference of data.context ?? []) {
     let spec;
@@ -823,12 +1001,16 @@ async function compileRule(input, context) {
     description: data.description ?? null,
     source: input.source,
     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,
-    context: references
+    context: references,
+    examples: data.examples ?? null
   };
 }
 
@@ -871,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,
@@ -918,10 +1081,8 @@ export {
   LLM_PROVIDERS,
   defaultDetectorSettings,
   emptyDelivery,
-  VERSION2 as VERSION,
-  parseVersion,
-  isOlder,
   measureRuleBlock,
+  deliveryCost,
   renderAgentText,
   tagsOf,
   compileFilter,