@syv-ai/rulecast 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,18 +1,125 @@
-import { A as Adapter, D as DetectorRuleInput, a as DetectorRun, M as Match, b as Detector, c as AnyDetector, d as AdapterInput, e as Delivery, E as Event } from './types-2oz2AlwA.js';
-export { f as AdapterInstall, C as Cache, g as ChangeSet, h as CheckResult, i as CompiledDetector, j as CompiledRule, k as DeliveredReference, l as DetectorCheck, m as DetectorEvent, n as DetectorRegistry, o as DetectorResult, p as DetectorRule, q as DetectorSettings, r as DetectorWarm, s as EventKind, F as Finding, I as InstallScope, L as LLM_PROVIDERS, t as LlmFinding, u as LlmProvider, v as LlmProviderName, w as LlmRequest, x as LlmSettings, y as LlmUnavailableError, O as Omitted, R as ReferenceMode, z as ResolvedReference, S as Severity, T as TouchRule, W as WriteIntent, B as createRegistry, G as defaultDetectorSettings, H as emptyDelivery, J as isDetectorRule } from './types-2oz2AlwA.js';
+import { A as Adapter, e as Delivery, g as DetectorRun, h as DetectorRuleInput, M as Match, i as Detector, j as AnyDetector, k as AdapterInput, E as Event } from './types-Dcra5LXR.js';
+export { l as AdapterInstall, m as Cache, n as ChangeSet, b as CheckResult, o as CompiledDetector, a as CompiledRule, p as ContentSource, q as DeliveredReference, s as DetectorCheck, t as DetectorEvent, D as DetectorRegistry, u as DetectorResult, d as DetectorRule, c as DetectorSettings, v as DetectorWarm, w as EventKind, F as Finding, I as InstallScope, x as LLM_PROVIDERS, y as LlmFinding, f as LlmProvider, L as LlmProviderName, z as LlmRequest, B as LlmSettings, G as LlmUnavailableError, O as Omitted, H as ReferenceMode, J as ReferenceSpec, K as RenderOptions, N as ResolvedReference, P as RuleExample, Q as RuleExamples, T as RuleScope, U as Severity, S as Stage, V as TouchRule, W as WriteIntent, X as createRegistry, Y as defaultDetectorSettings, Z as emptyDelivery, _ as isDetectorRule, r as renderAgentText } from './types-Dcra5LXR.js';
 import 'zod';
 
 declare const claudeCodeAdapter: Adapter;
 
+/**
+ * How much of a rule a repository already owes, per rule and per file.
+ *
+ * Counts, never rates. One codebase went from 61 violations in 80 files to 57 in 194 over eight
+ * months: the rate fell from 76% to 29% and the count did not move, because new code complied and
+ * the old violations were only diluted. A team watching the rate would have believed it was fixing
+ * the problem. So this reports the stock and leaves the division to nobody.
+ */
+interface BacklogSummary {
+    /** Violations descending, then rule ascending. */
+    rules: {
+        rule: string;
+        violations: number;
+        files: number;
+    }[];
+    /** Violations descending, then file ascending. */
+    files: {
+        file: string;
+        violations: number;
+    }[];
+    totalViolations: number;
+    /** Distinct files with at least one violation — not the sum of the per-rule file counts. */
+    totalFiles: number;
+}
+/**
+ * Both halves of a delivery count.
+ *
+ * `--all-files` has no baseline, so every violation arrives as a finding. `--from-ref` classifies
+ * against the merge base, and there most of the backlog is in `preexistingSummary` — which is
+ * exactly the set this exists to give a number to.
+ */
+declare function summarise(delivery: Delivery): BacklogSummary;
+declare function renderBacklog(summary: BacklogSummary, options: {
+    topFiles: number;
+    note?: boolean;
+}): string;
+
 /** Every agent adapter rulecast ships. */
 declare const ADAPTERS: readonly Adapter[];
 declare function adapterByName(name: string): Adapter | undefined;
 
+/**
+ * A path an external tool reported, made repo-relative with forward slashes.
+ *
+ * Two things a tool does that naive relativisation gets wrong. SARIF requires `uri` to be
+ * percent-encoded, so a `file://` URI has to be decoded rather than sliced. And resolving a path —
+ * Python's `Path.resolve()`, eslint — follows symlinks, so a project under a symlinked root, which
+ * is every macOS temp directory and plenty of real checkouts, comes back as a realpath that does
+ * not sit under `cwd`. Either way the finding would be attributed to a path no rule selected and
+ * silently dropped, so the realpath of the root is tried before giving up.
+ *
+ * `command` and `linter` each carried a byte-identical copy of the root-and-realpath half of this.
+ *
+ * A factory, because the realpath is a filesystem call: a tool that reports thousands of findings
+ * resolves its root once, not once per finding.
+ */
+declare function repoRelativeTo(cwd: string): (file: string) => string;
+/** One path; for many from the same tool, take `repoRelativeTo(cwd)` once. */
+declare function repoRelative(file: string, cwd: string): string;
+
+/**
+ * Whether this error is the clock rather than the rule.
+ *
+ * It decides which of two very different things a detector reports. Rethrowing lets the core record
+ * a timeout, which is logged and tried again at the next verify; swallowing it into
+ * `DetectorResult.errors` is a rule error, which disables the rule for the whole session (§14).
+ *
+ * The signal alone cannot tell the two apart. Its abort timer only runs when the event loop is free,
+ * and synchronous work — `ast-grep` parses in native code that no timeout interrupts — is what keeps
+ * it busy. So the wall clock is the authority, and every detector that catches its own errors has to
+ * ask this rather than `signal.aborted`.
+ */
+declare function pastDeadline(error: unknown, input: Pick<DetectorRun<unknown>, "signal" | "deadlineAt">): boolean;
 /** Turns a per-rule function into a detector run; an error in one rule does not affect the others. */
 declare function perRule<Config>(detect: (rule: DetectorRuleInput<Config>, input: DetectorRun<Config>) => Promise<Match[]>): Detector<Config>["run"];
+/**
+ * Reads each file at most once for the life of the returned function, for a detector that hands
+ * paths to another program and reads the files only to quote them (`{{text}}`, a prompt).
+ *
+ * Not for a detector that declares `guards`: those read only through `DetectorRun.read`, which is
+ * what lets them judge content the agent proposed and that is not on disk (docs/conventions.md).
+ * `linter` and `llm` each carried a byte-identical copy of this.
+ */
+declare function sourceReader(cwd: string): (file: string) => Promise<string | null>;
+
+declare function lineStarts(text: string): number[];
+/** 1-based line and column of a string offset. */
+declare function positionAt(starts: number[], offset: number): {
+    line: number;
+    column: number;
+};
+/** String offset of a 1-based line and column, clamped to a file of `length` characters. */
+declare function offsetAt(starts: number[], line: number, column: number, length: number): number;
+
+/**
+ * Runs a checker and returns what it printed.
+ *
+ * A non-zero exit is not a failure: a linter or a command rule exits non-zero precisely when it
+ * found something, and the output is the answer. What is a failure is a binary that is not there —
+ * reported as `notFound`, which the caller words for its own user — and an error that carries no
+ * output at all, such as a permission failure. An abort is rethrown untouched, so the caller can tell the clock from
+ * the rule (`pastDeadline`).
+ *
+ * `command` and `linter` each carried a copy of this, `maxBuffer` and comment included. `llm`'s CLI
+ * providers do not use it: they write a prompt to stdin, keep stderr and the exit code, and a
+ * missing binary is a whole-run `LlmUnavailableError` there rather than a rule error.
+ */
+declare function runTool(command: string, args: readonly string[], options: {
+    cwd: string;
+    signal: AbortSignal;
+    notFound: string;
+    stdin?: string;
+}): Promise<string>;
 
 /** The running rulecast version. test/core/version.test.ts keeps it equal to package.json. */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.4.0";
 
 declare const builtinDetectors: readonly AnyDetector[];
 
@@ -71,4 +178,4 @@ interface DetectorFixture {
  */
 declare function detectorContract(detector: AnyDetector, fixture: DetectorFixture): ContractCase[];
 
-export { ADAPTERS, Adapter, type AdapterFixture, AdapterInput, AnyDetector, type ContractCase, Delivery, Detector, type DetectorFixture, DetectorRuleInput, DetectorRun, Event, Match, VERSION, adapterByName, adapterContract, builtinDetectors, claudeCodeAdapter, detectorContract, perRule };
+export { ADAPTERS, Adapter, type AdapterFixture, AdapterInput, AnyDetector, type BacklogSummary, type ContractCase, Delivery, Detector, type DetectorFixture, DetectorRuleInput, DetectorRun, Event, Match, VERSION, adapterByName, adapterContract, builtinDetectors, claudeCodeAdapter, detectorContract, lineStarts, offsetAt, pastDeadline, perRule, positionAt, renderBacklog, repoRelative, repoRelativeTo, runTool, sourceReader, summarise };

package/dist/index.js

@@ -3,18 +3,29 @@ import {
   adapterByName,
   builtinDetectors,
   claudeCodeAdapter,
-  createRegistry
-} from "./chunk-C6C5EER7.js";
+  createRegistry,
+  renderBacklog,
+  repoRelative,
+  repoRelativeTo,
+  runTool,
+  summarise
+} from "./chunk-IKONOTME.js";
 import {
   LlmUnavailableError,
   VERSION,
   defaultDetectorSettings,
   emptyDelivery,
   isDetectorRule,
+  lineStarts,
   memoryCache,
+  offsetAt,
+  pastDeadline,
   perRule,
-  readSourceFile
-} from "./chunk-ZEFEQKG5.js";
+  positionAt,
+  readSourceFile,
+  renderAgentText,
+  sourceReader
+} from "./chunk-DQUCE2IK.js";
 
 // src/testing/adapter-contract.ts
 import assert from "assert/strict";
@@ -118,6 +129,16 @@ function adapterContract(adapter, fixture) {
             const twice = install.merge(structuredClone(once.settings), command, 5e3);
             assert.deepEqual(twice.settings, once.settings, "merging twice must change nothing");
             assert.deepEqual(twice.added, [], "merging twice must add nothing");
+            if (twice.updated !== void 0) assert.deepEqual(twice.updated, [], "merging twice must update nothing");
+            const upgraded = install.merge(structuredClone(once.settings), install.command(true), 5e3);
+            assert.deepEqual(upgraded.added, [], "merging another command over installed hooks must add nothing");
+            if (upgraded.updated !== void 0) {
+              assert.deepEqual(
+                [...upgraded.updated].sort(),
+                [...once.added].sort(),
+                "merging another command must report every hook it rewrote"
+              );
+            }
             const removed = install.remove(structuredClone(once.settings));
             assert.deepEqual(removed.settings, original, "remove must return the settings merge was given");
             assert.deepEqual([...removed.removed].sort(), [...once.added].sort(), "remove must name what merge added");
@@ -297,5 +318,16 @@ export {
   detectorContract,
   emptyDelivery,
   isDetectorRule,
-  perRule
+  lineStarts,
+  offsetAt,
+  pastDeadline,
+  perRule,
+  positionAt,
+  renderAgentText,
+  renderBacklog,
+  repoRelative,
+  repoRelativeTo,
+  runTool,
+  sourceReader,
+  summarise
 };

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { n as DetectorRegistry, K as Config, j as CompiledRule, e as Delivery, h as CheckResult, q as DetectorSettings, E as Event, v as LlmProviderName, u as LlmProvider } from './types-2oz2AlwA.js';
-export { N as RuleEntry, P as Stage } from './types-2oz2AlwA.js';
+import { D as DetectorRegistry, C as Config, a as CompiledRule, b as CheckResult, c as DetectorSettings, d as DetectorRule, M as Match, E as Event, e as Delivery, L as LlmProviderName, f as LlmProvider } from './types-Dcra5LXR.js';
+export { R as RuleEntry, S as Stage, r as renderAgentText } from './types-Dcra5LXR.js';
 import 'zod';
 
 type Checkout = {
@@ -47,7 +47,7 @@ interface CompileOptions {
 /** The project config and the manifests of its pinned repos → ready rules plus diagnostics (spec §5). */
 declare function compile(options: CompileOptions): Promise<CompiledProject>;
 /** A manifest on its own (validate, the init catalog): references resolve against `dir`. */
-declare function compileManifest(dir: string, registry: DetectorRegistry): Promise<{
+declare function compileManifest(dir: string, registry: DetectorRegistry, file?: string): Promise<{
     rules: CompiledRule[];
     diagnostics: Diagnostic[];
 }>;
@@ -55,11 +55,6 @@ declare function compileManifest(dir: string, registry: DetectorRegistry): Promi
 declare const CONFIG_FILE = ".rulecast-config.yaml";
 declare const MANIFEST_FILE = ".rulecast-rules.yaml";
 
-interface RenderOptions {
-    maxMatchesPerRule: number;
-}
-declare function renderAgentText(delivery: Delivery, options: RenderOptions): string;
-
 interface CheckOptions {
     project: CompiledProject;
     registry: DetectorRegistry;
@@ -89,6 +84,12 @@ declare function cacheHome(env: Env): string;
  */
 declare function projectStateDir(home: string, root: string): string;
 
+interface IgnoredFinding {
+    rule: DetectorRule;
+    match: Match;
+    reason: string;
+}
+
 interface PipelineOptions {
     /** Compiled by the caller: hooks never fetch rule repos, the CLI does (spec §4). */
     project: CompiledProject;
@@ -100,7 +101,7 @@ interface PipelineOptions {
     maxContextChars: number | null;
     /** Recently accessed files the agent re-attaches after compaction (adapter.restoredFiles); reset re-delivers their touch context. */
     restoredFiles?: number;
-    /** Detector kinds to skip entirely (run --no-llm). */
+    /** Detector kinds to skip entirely: the metered ones, for a staged run or --no-llm (commands/run.ts). */
     skipDetectorKinds?: ReadonlySet<string>;
     /** Run only these rules (rulecast run RULE_ID); touch rules are unaffected. */
     onlyRules?: ReadonlySet<string>;
@@ -115,6 +116,8 @@ interface PipelineResult {
     failed: boolean;
     /** Detector kinds whose results were dropped at the edit deadline (§13). */
     deadlineMissed: string[];
+    /** Findings a `rulecast-ignore` comment dropped (core/suppress.ts); absent when nothing was detected. */
+    ignored?: IgnoredFinding[];
 }
 declare function runPipeline(options: PipelineOptions): Promise<PipelineResult>;
 
@@ -133,4 +136,4 @@ declare function resolveModel(model: string, provider: LlmProviderName): string
  */
 declare function providerByName(name: LlmProviderName): LlmProvider;
 
-export { CONFIG_FILE, type Checkout, type CompileOptions, type CompiledProject, Config, type Diagnostic, type Env, type KindCheckResult, MANIFEST_FILE, MODEL_ALIASES, type PipelineOptions, type PipelineResult, type RepoProvider, cacheHome, cachedRepos, checkDetectors, checkableKinds, compile, compileManifest, fetchingRepos, fixedRepo, projectStateDir, providerByName, renderAgentText, resolveModel, runPipeline };
+export { CONFIG_FILE, type Checkout, type CompileOptions, type CompiledProject, Config, type Diagnostic, type Env, type KindCheckResult, MANIFEST_FILE, MODEL_ALIASES, type PipelineOptions, type PipelineResult, type RepoProvider, cacheHome, cachedRepos, checkDetectors, checkableKinds, compile, compileManifest, fetchingRepos, fixedRepo, projectStateDir, providerByName, resolveModel, runPipeline };

package/dist/internal.js

@@ -11,13 +11,13 @@ import {
   fixedRepo,
   projectStateDir,
   runPipeline
-} from "./chunk-RODZRI7B.js";
+} from "./chunk-WUFU4LW2.js";
 import {
   MODEL_ALIASES,
   providerByName,
   renderAgentText,
   resolveModel
-} from "./chunk-ZEFEQKG5.js";
+} from "./chunk-DQUCE2IK.js";
 export {
   CONFIG_FILE,
   MANIFEST_FILE,

package/dist/{types-2oz2AlwA.d.ts → types-Dcra5LXR.d.ts}

@@ -19,6 +19,19 @@ interface WriteIntent {
         all: boolean;
     };
 }
+/**
+ * Where a run reads the current content of a file from. The working tree for every hook; the index
+ * for `rulecast run` on staged files, so a commit is judged as it will be committed; a commit for
+ * `--to-ref`, so a push is judged as it will be pushed.
+ */
+type ContentSource = {
+    kind: "worktree";
+} | {
+    kind: "index";
+} | {
+    kind: "commit";
+    ref: string;
+};
 interface Event {
     kind: EventKind;
     /** Repo-relative paths (adapters may give absolute ones; the hook command converts them). Empty for prompt and reset. */
@@ -29,6 +42,8 @@ interface Event {
     completeRead?: boolean;
     /** verify from the CLI: the commit the baseline is read from (the merge base for --from-ref). */
     baseCommit?: string;
+    /** verify from the CLI: where current content is read from. Absent: the working tree. */
+    content?: ContentSource;
     session?: {
         id: string;
         agentId?: string;
@@ -88,6 +103,12 @@ interface DetectorRun<Config> {
      * is not on disk and never will be if the write is refused.
      */
     read(file: string): Promise<string | null>;
+    /**
+     * False when the files are not as they are on disk — a staged run reads the index, `--to-ref` a
+     * commit — and this detector declared `takesContent`: it must read through `read` and hand the
+     * text to its tool under the file's path, never let the tool open the path. Absent: true.
+     */
+    fromDisk?: boolean;
     /** File absent = no baseline, the whole file is new. */
     changes: ReadonlyMap<string, ChangeSet>;
     cache: Cache;
@@ -158,6 +179,40 @@ interface Detector<Config> {
      * not on disk, so ruff, eslint, ast-grep's CLI or a `command` script would judge the old one.
      */
     guards?: boolean;
+    /**
+     * Each file costs money or a third party sees it (§6, Consent). The core never preselects such a
+     * rule in `init`, never runs it as a side effect — no fingerprint run on `touch`, no `doctor` dry
+     * run, no `rulecast test` without a rule id — and budgets the files it is given per event.
+     *
+     * The core asks this rather than a kind name, the way it asks `guards`, so a second metered
+     * detector needs no edit to the core.
+     */
+    metered?: boolean;
+    /** For `init`'s consent line: what one rule of this kind costs and where the file goes. */
+    cost?(config: Config): string;
+    /**
+     * Most files this detector is given in one verify; the most recently edited are kept (§6).
+     * `setting` names the config key that raises it, because a warning that does not name its lever
+     * leaves nobody knowing what to do.
+     */
+    fileBudget?(settings: DetectorSettings): {
+        max: number;
+        setting: string;
+    };
+    /** Added to a verify timeout's warning, when this kind can legitimately need far longer. */
+    timeoutHint?: string;
+    /**
+     * A match is the whole file rather than a range in it, so any write to a matching file is
+     * evidence for `refuse_write`, not only a write that inserts the matched text.
+     */
+    wholeFile?: boolean;
+    /**
+     * This rule's tool can be handed a file's content under its real path (ruff `--stdin-filename`,
+     * a model prompt). When the content is not the working tree, such a rule is run with
+     * `fromDisk: false`; one that cannot is given a scratch copy instead, which configuration keyed
+     * on the file's path no longer matches (spec §12).
+     */
+    takesContent?(config: Config): boolean;
     run(input: DetectorRun<Config>): Promise<DetectorResult>;
     /** Optional: build expensive caches ahead of events (rulecast warm, §13). */
     warm?(input: DetectorWarm<Config>): Promise<void>;
@@ -212,6 +267,11 @@ interface Delivery {
     omitted: Omitted;
     /** Absolute path of the untrimmed delivery, written when even the floor did not fit; null when it did. */
     overflowPath: string | null;
+    /**
+     * For the user, not the agent (spec §9, Oversight): the config changed this session, ignores were
+     * added. Attached after the budget is spent and never part of agent context under a hook adapter.
+     */
+    notices?: string[];
 }
 interface AdapterInput {
     /** The agent's directory; the project root is found from it. */
@@ -232,9 +292,14 @@ interface AdapterInstall {
     }[];
     /** The hook command; local: rulecast is installed in the project's node_modules. */
     command(local: boolean): string;
+    /**
+     * Adds the hooks. `updated` (optional, for adapters that can tell): the adapter's own hooks whose
+     * command differed from `command` and were rewritten — an older install upgraded in place.
+     */
     merge(settings: unknown, command: string, verifyMs: number): {
         settings: unknown;
         added: string[];
+        updated?: string[];
     };
     remove(settings: unknown): {
         settings: unknown;
@@ -264,6 +329,30 @@ declare function emptyDelivery(): Delivery;
 
 declare const STAGES: readonly ["touch", "edit", "verify"];
 type Stage = (typeof STAGES)[number];
+declare const RULE_SCOPES: readonly ["instance", "container"];
+type RuleScope = (typeof RULE_SCOPES)[number];
+/**
+ * One inline example: a file the rule would see, and what is in it.
+ *
+ * `path` is required and has no useful default — `files`, `exclude`, the type tags and `ast-grep`'s
+ * language selection are all functions of it, so an example without one would be testing a
+ * different rule than the one that will run.
+ */
+declare const exampleSchema: z.ZodObject<{
+    path: z.ZodString;
+    code: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    path: string;
+}, {
+    code: string;
+    path: string;
+}>;
+type RuleExample = z.infer<typeof exampleSchema>;
+type RuleExamples = {
+    good: RuleExample[];
+    bad: RuleExample[];
+};
 /** A config entry selecting a rule from a rule repo; every key but id overrides the manifest rule's. */
 declare const overrideSchema: z.ZodObject<{
     alias: z.ZodOptional<z.ZodString>;
@@ -277,7 +366,15 @@ declare const overrideSchema: z.ZodObject<{
     stages: z.ZodOptional<z.ZodArray<z.ZodEnum<["touch", "edit", "verify"]>, "atleastone">>;
     minimum_rulecast_version: z.ZodOptional<z.ZodString>;
     severity: z.ZodOptional<z.ZodEnum<["error", "warning"]>>;
+    /**
+     * What the convention belongs to (§8). `instance`: the token the detector matched, classified by
+     * whether the agent's edit touched it. `container`: the node the match spans, classified by
+     * whether that node already violated the rule at the baseline.
+     */
+    scope: z.ZodOptional<z.ZodEnum<["instance", "container"]>>;
     refuse_write: z.ZodOptional<z.ZodBoolean>;
+    /** false: compiled and listed, selected for nothing. The way to switch a catalog rule off without deleting it. */
+    enabled: z.ZodOptional<z.ZodBoolean>;
     detect: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
     message: z.ZodOptional<z.ZodString>;
     context: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
@@ -290,11 +387,52 @@ declare const overrideSchema: z.ZodObject<{
         path: string;
         mode?: "inject" | "read" | undefined;
     }>]>, "many">>;
+    /** Code the rule must flag (`bad`) and must not (`good`), run by `rulecast test`. */
+    examples: z.ZodOptional<z.ZodObject<{
+        good: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            path: string;
+        }, {
+            code: string;
+            path: string;
+        }>, "many">>;
+        bad: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            code: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            path: string;
+        }, {
+            code: string;
+            path: string;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        good: {
+            code: string;
+            path: string;
+        }[];
+        bad: {
+            code: string;
+            path: string;
+        }[];
+    }, {
+        good?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+        bad?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+    }>>;
     id: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    name?: string | undefined;
     message?: string | undefined;
+    name?: string | undefined;
     alias?: string | undefined;
     description?: string | undefined;
     files?: string | undefined;
@@ -305,16 +443,28 @@ declare const overrideSchema: z.ZodObject<{
     stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
     minimum_rulecast_version?: string | undefined;
     severity?: "error" | "warning" | undefined;
+    scope?: "instance" | "container" | undefined;
     refuse_write?: boolean | undefined;
+    enabled?: boolean | undefined;
     detect?: Record<string, unknown> | undefined;
     context?: (string | {
         path: string;
         mode?: "inject" | "read" | undefined;
     })[] | undefined;
+    examples?: {
+        good: {
+            code: string;
+            path: string;
+        }[];
+        bad: {
+            code: string;
+            path: string;
+        }[];
+    } | undefined;
 }, {
     id: string;
-    name?: string | undefined;
     message?: string | undefined;
+    name?: string | undefined;
     alias?: string | undefined;
     description?: string | undefined;
     files?: string | undefined;
@@ -325,12 +475,24 @@ declare const overrideSchema: z.ZodObject<{
     stages?: ["touch" | "edit" | "verify", ...("touch" | "edit" | "verify")[]] | undefined;
     minimum_rulecast_version?: string | undefined;
     severity?: "error" | "warning" | undefined;
+    scope?: "instance" | "container" | undefined;
     refuse_write?: boolean | undefined;
+    enabled?: boolean | undefined;
     detect?: Record<string, unknown> | undefined;
     context?: (string | {
         path: string;
         mode?: "inject" | "read" | undefined;
     })[] | undefined;
+    examples?: {
+        good?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+        bad?: {
+            code: string;
+            path: string;
+        }[] | undefined;
+    } | undefined;
 }>;
 type RuleEntry = z.infer<typeof overrideSchema>;
 declare const configSchema: z.ZodEffects<z.ZodObject<{
@@ -570,13 +732,31 @@ interface CompiledRule {
     /** "local", or the rule repo label ("syv-ai/rulecast@v0.2.0"). */
     source: string;
     severity: Severity;
+    /**
+     * How a finding of this rule is classified against the baseline (spec §8). `instance` — the
+     * default, and every rule before 0.2 — is new when the match touches a changed line. `container`
+     * is new when the node the match spans was not already violating the rule at the baseline.
+     */
+    scope: RuleScope;
     /** Refuse the agent's write when this rule fires on what it is writing (spec §9, Guard). */
     refuseWrite: boolean;
+    /** false: switched off with `enabled: false`; never selected for an event (spec §4). */
+    enabled: boolean;
     stages: Stage[];
+    /** The rule's own `files` and `exclude`, as written, for `rulecast list`; `matches` is what decides. */
+    patterns: {
+        files: string;
+        exclude: string;
+    };
     matches(file: string): boolean;
     detector: CompiledDetector | null;
     message: string | null;
     context: ReferenceSpec[];
+    /**
+     * Inline good/bad examples, run by `rulecast test`. `null` when the rule declared none, which
+     * `validate` and `test` report differently from a rule that declared an empty set.
+     */
+    examples: RuleExamples | null;
 }
 /**
  * A rule that runs a detector. compileRule enforces the split — a rule with `detect` must also
@@ -594,6 +774,23 @@ type TouchRule = CompiledRule & {
 /** Whether this rule runs a detector, as a type guard so the narrowing survives a filter. */
 declare function isDetectorRule(rule: CompiledRule): rule is DetectorRule;
 
+interface RenderOptions {
+    maxMatchesPerRule: number;
+    /**
+     * Print `delivery.notices` (default true). A hook adapter passes false and shows them to the user
+     * itself; `--format agent` serves agents without hooks, where nobody else would see them. Notices
+     * are attached after the budget is spent, so they are never priced: no budgeted delivery has any.
+     */
+    notices?: boolean;
+    /**
+     * Print `delivery.warnings` (default true). Rule and detector problems are the human's to fix; a
+     * hook adapter that can reach the user passes false and shows them there. Not printing them only
+     * ever spends less than the budget reserved for them.
+     */
+    warnings?: boolean;
+}
+declare function renderAgentText(delivery: Delivery, options: RenderOptions): string;
+
 /** What the model is asked to answer with (spec §6). */
 declare const responseSchema: z.ZodObject<{
     findings: z.ZodArray<z.ZodObject<{
@@ -669,4 +866,4 @@ interface LlmProvider {
     }): Promise<LlmAvailability>;
 }
 
-export { type Adapter as A, createRegistry as B, type Cache as C, type DetectorRuleInput as D, type Event as E, type Finding as F, defaultDetectorSettings as G, emptyDelivery as H, type InstallScope as I, isDetectorRule as J, type Config as K, LLM_PROVIDERS as L, type Match as M, type RuleEntry as N, type Omitted as O, type Stage as P, type ReferenceMode as R, type Severity as S, type TouchRule as T, type WriteIntent as W, type DetectorRun as a, type Detector as b, type AnyDetector as c, type AdapterInput as d, type Delivery as e, type AdapterInstall as f, type ChangeSet as g, type CheckResult as h, type CompiledDetector as i, type CompiledRule as j, type DeliveredReference as k, type DetectorCheck as l, type DetectorEvent as m, type DetectorRegistry as n, type DetectorResult as o, type DetectorRule as p, type DetectorSettings as q, type DetectorWarm as r, type EventKind as s, type LlmFinding as t, type LlmProvider as u, type LlmProviderName as v, type LlmRequest as w, type LlmSettings as x, LlmUnavailableError as y, type ResolvedReference as z };
+export { type Adapter as A, type LlmSettings as B, type Config as C, type DetectorRegistry as D, type Event as E, type Finding as F, LlmUnavailableError as G, type ReferenceMode as H, type InstallScope as I, type ReferenceSpec as J, type RenderOptions as K, type LlmProviderName as L, type Match as M, type ResolvedReference as N, type Omitted as O, type RuleExample as P, type RuleExamples as Q, type RuleEntry as R, type Stage as S, type RuleScope as T, type Severity as U, type TouchRule as V, type WriteIntent as W, createRegistry as X, defaultDetectorSettings as Y, emptyDelivery as Z, isDetectorRule as _, type CompiledRule as a, type CheckResult as b, type DetectorSettings as c, type DetectorRule as d, type Delivery as e, type LlmProvider as f, type DetectorRun as g, type DetectorRuleInput as h, type Detector as i, type AnyDetector as j, type AdapterInput as k, type AdapterInstall as l, type Cache as m, type ChangeSet as n, type CompiledDetector as o, type ContentSource as p, type DeliveredReference as q, renderAgentText as r, type DetectorCheck as s, type DetectorEvent as t, type DetectorResult as u, type DetectorWarm as v, type EventKind as w, LLM_PROVIDERS as x, type LlmFinding as y, type LlmRequest as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syv-ai/rulecast",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Deliver project conventions to coding agents at the moment they matter.",
   "keywords": [
     "claude-code",
@@ -35,7 +35,8 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
-    }
+    },
+    "./cli": "./dist/cli.js"
   },
   "files": [
     "dist"