@syv-ai/rulecast 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,9 +1,45 @@
-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, D as Delivery, a as DetectorRuleInput, b as DetectorRun, M as Match, c as Detector, d as AnyDetector, e as AdapterInput, E as Event } from './types-C8b7hrnG.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, B as RuleScope, S as Severity, T as TouchRule, W as WriteIntent, G as createRegistry, H as defaultDetectorSettings, J as emptyDelivery, K as isDetectorRule } from './types-C8b7hrnG.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;
+}): string;
+
 /** Every agent adapter rulecast ships. */
 declare const ADAPTERS: readonly Adapter[];
 declare function adapterByName(name: string): Adapter | undefined;
@@ -12,7 +48,7 @@ declare function adapterByName(name: string): Adapter | undefined;
 declare function perRule<Config>(detect: (rule: DetectorRuleInput<Config>, input: DetectorRun<Config>) => Promise<Match[]>): Detector<Config>["run"];
 
 /** 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.3.0";
 
 declare const builtinDetectors: readonly AnyDetector[];
 
@@ -71,4 +107,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, perRule, renderBacklog, summarise };

package/dist/index.js

@@ -3,8 +3,10 @@ import {
   adapterByName,
   builtinDetectors,
   claudeCodeAdapter,
-  createRegistry
-} from "./chunk-C6C5EER7.js";
+  createRegistry,
+  renderBacklog,
+  summarise
+} from "./chunk-KOUHBT7F.js";
 import {
   LlmUnavailableError,
   VERSION,
@@ -14,7 +16,7 @@ import {
   memoryCache,
   perRule,
   readSourceFile
-} from "./chunk-ZEFEQKG5.js";
+} from "./chunk-HZUATJ53.js";
 
 // src/testing/adapter-contract.ts
 import assert from "assert/strict";
@@ -297,5 +299,7 @@ export {
   detectorContract,
   emptyDelivery,
   isDetectorRule,
-  perRule
+  perRule,
+  renderBacklog,
+  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 { n as DetectorRegistry, N as Config, j as CompiledRule, D as Delivery, h as CheckResult, q as DetectorSettings, E as Event, v as LlmProviderName, u as LlmProvider } from './types-C8b7hrnG.js';
+export { P as RuleEntry, Q as Stage } from './types-C8b7hrnG.js';
 import 'zod';
 
 type Checkout = {

package/dist/internal.js

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

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

@@ -264,6 +264,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,6 +301,12 @@ 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>;
     detect: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
     message: z.ZodOptional<z.ZodString>;
@@ -290,6 +320,47 @@ 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;
@@ -305,12 +376,23 @@ 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;
     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;
@@ -325,12 +407,23 @@ 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;
     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,6 +663,12 @@ 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;
     stages: Stage[];
@@ -577,6 +676,11 @@ interface CompiledRule {
     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
@@ -669,4 +773,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 RuleScope as B, type Cache as C, type Delivery as D, type Event as E, type Finding as F, createRegistry as G, defaultDetectorSettings as H, type InstallScope as I, emptyDelivery as J, isDetectorRule as K, LLM_PROVIDERS as L, type Match as M, type Config as N, type Omitted as O, type RuleEntry as P, type Stage as Q, type ReferenceMode as R, type Severity as S, type TouchRule as T, type WriteIntent as W, type DetectorRuleInput as a, type DetectorRun as b, type Detector as c, type AnyDetector as d, type AdapterInput 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syv-ai/rulecast",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deliver project conventions to coding agents at the moment they matter.",
   "keywords": [
     "claude-code",