@gobing-ai/ts-rule-engine 0.3.1 → 0.3.2

package/README.md

@@ -1,8 +1,12 @@
 # @gobing-ai/ts-rule-engine
 
-Constraint rule loading, evaluation, formatting, and fix generation for Bun/TypeScript projects.
+Constraint rule loading, evaluation, formatting, and fix generation for Bun/TypeScript projects. Rules are defined as declarative YAML/JSON, evaluated through a typed evaluator host, and results are rendered or converted into candidate fixes. Preset composition, extension loading, and bundled rule categories make the engine zero-config ready out of the box.
 
-This package is a library. It does not ship a CLI. Downstream tools can use it to load rule presets, evaluate a workspace, format findings, collect fix candidates, and optionally apply those fixes.
+## Install
+
+```bash
+bun add @gobing-ai/ts-rule-engine
+```
 
 ## Briefing
 
@@ -11,64 +15,152 @@ This package is a library. It does not ship a CLI. Downstream tools can use it t
 ```mermaid
 erDiagram
     RULE_ENGINE ||--|| RULE_ENGINE_HOST : uses
+    RULE_ENGINE_HOST ||--o{ CAPABILITY_REGISTRY : owns
+    CAPABILITY_REGISTRY ||--o{ EVALUATOR : registers
+    CAPABILITY_REGISTRY ||--o{ RESOLVER : registers
+    CAPABILITY_REGISTRY ||--o{ FORMATTER : registers
     RULE_ENGINE ||--o{ CONSTRAINT_RULE : evaluates
-    RULE_ENGINE_HOST ||--o{ EVALUATOR : registers
-    RULE_ENGINE_HOST ||--o{ RESOLVER : registers
-    RULE_ENGINE_HOST ||--o{ FORMATTER : registers
-    RULE_ENGINE ||--o{ FIXER : owns
+    RULE_ENGINE ||--o{ FIXER_PROVIDER : owns
     PRESET ||--o{ CONSTRAINT_RULE : composes
-    PRESET ||--o{ EXTENSION : declares
-    EXTENSION }o--|| RULE_ENGINE_HOST : loads_into
+    PRESET ||--o{ EXTENSION_REF : declares
+    EXTENSION_REF }o--|| RULE_ENGINE_HOST : loads_into
     EVALUATOR ||--o{ FINDING : emits
-    FIXER ||--o{ FIX : emits
+    FIXER_PROVIDER ||--o{ FIX : emits
     FORMATTER ||--|| RESULT : renders
 ```
 
 | Entity | One-line Description |
 |--------|----------------------|
-| `RuleEngine` | Orchestrates the evaluation workflow for enabled rules in a target workspace. |
-| `RuleEngineHost` | Holds named capability registries for evaluators, resolvers, and formatters. |
-| `ConstraintRule` | Declarative policy unit with matching scope, severity, evaluator config, and optional fix config. |
-| `Preset` | YAML/JSON composition unit that collects rule categories, other presets, disabled rules, and extension refs. |
-| `Evaluator` | Executes one rule type and emits findings plus any evaluator-native fixes. |
-| `Resolver` | Maps source paths to related test paths or skeletons for rules such as `test-location`. |
-| `Formatter` | Renders a `RuleEngineResult` as text, JSON, or a downstream custom report format. |
-| `Fixer` | Produces file edits from findings when a rule opts into manual or automatic fix modes. |
-| `Extension` | Trusted local module declared by presets to register custom resolvers, evaluators, or formatters. |
+| `RuleEngine` | Orchestrates evaluation of enabled rules against a workspace directory. Supports opt-in early exit via `stopOnFirst` parameter. Accepts an optional `EventBus<RuleEngineEvents>` for structured in-process observability. |
+| `RuleEngineHost` | Capability host backed by `CapabilityRegistry` from `@gobing-ai/ts-runtime/plugin` — holds evaluators, resolvers, and formatters, each with origin tracking for safe override detection. |
+| `CapabilityRegistry<T>` | Generic named registry (shared with `ts-rule-engine`, `ts-dual-workflow-engine`) that tags each entry with its `origin` (`'builtin'`, `'extension'`, `'caller'`). |
+| `ConstraintRule` | Declarative policy unit: id, severity, include/exclude globs, evaluator type + config, and optional fix config. |
+| `Preset` | YAML/JSON composition: extends rule categories and other presets, declares `disable`/`overrides`, and exposes extension modules. |
+| `ExtensionRef` | Resolved extension: a capability kind (`resolvers` / `evaluators` / `fixers` / `formatters`), an absolute module path, and its source preset name. |
+| `Evaluator` | Implements one rule type (e.g. `regex`, `coverage-gate`, `import-boundary`), emitting findings and optional evaluator-native fixes. |
+| `Resolver` | Maps a source file path to an expected test path for rules such as `test-location`; supports TypeScript, Python, Go, and Rust conventions. |
+| `Formatter` | Renders a `RuleEngineResult` as text (for CLI) or JSON (for automation). |
+| `FixerProvider` | Produces byte-range file edits from findings and a fix config; invoked when a rule's fix mode is non-`none` and the caller's authority allows it. |
 | `Finding` | Structured policy violation or evaluator error with severity, location, and machine-readable code. |
-| `Fix` | Candidate byte-range or file-level edit returned separately from findings and applied only on request. |
-| `RuleEngineResult` | Aggregate output containing all findings and fixes for one evaluation run. |
-
-## Install
-
-```bash
-bun add @gobing-ai/ts-rule-engine
-```
-
+| `Fix` | Candidate byte-range replacement; collected separately from findings, written only on explicit `applyFixes()`. |
+| `RuleEngineResult` | Aggregate `{ findings, fixes }` returned from a single evaluation run. |
+| `RuleEngineEvents` | Typed event map for rule-engine observability. All events prefixed `rule.` — see [Observability](#observability). |
+| `bundledRulesRoot()` | Resolves the absolute path to the bundled `rules/` directory shipped with this package — portable defaults usable as the lowest-priority preset root. |
 ## Mental Model
 
 ```mermaid
 flowchart TD
-    Files["YAML / JSON rule files"] --> Loader["loadRuleFile() / loadPreset()"]
+    Bundled["bundled rules/ directory"] --> Loader["loadRuleFile() / loadPreset()"]
+    Files["project .spur/rules/ YAML/JSON"] --> Loader
     Loader --> Rules["ConstraintRule[]"]
-    Rules --> Engine["RuleEngine"]
-    Engine --> Host["RuleEngineHost registries"]
-    Host --> Evaluators["evaluators by type"]
-    Host --> Resolvers["test path resolvers"]
-    Host --> Formatters["text / json formatters"]
+    Presets["Preset extends + extensions"] --> Extensions["loadExtensionsIntoHost()"]
+    Extensions --> Host["RuleEngineHost registries"]
+    Rules --> Engine["RuleEngine.evaluateWithFixes()"]
+    Host --> Engine
     Engine --> Result["{ findings, fixes }"]
     Result --> Formatter["TextFormatter / JsonFormatter"]
-    Result --> Apply["applyFixes()"]
+    Result --> Apply["engine.applyFixes()"]
 ```
 
 Core concepts:
 
 - `ConstraintRule`: one policy check. It has an `id`, `severity`, evaluator type/config, optional include/exclude globs, and optional fix config.
-- `RuleEngine`: runs enabled rules against a `workdir`.
-- `RuleEngineHost`: registry container for evaluators, formatters, and test-path resolvers.
+- `RuleEngine`: runs enabled rules against a `workdir`. The constructor auto-registers built-in evaluators, formatters, and resolvers.
+- `RuleEngineHost`: capability container backed by three `CapabilityRegistry` instances from `@gobing-ai/ts-runtime/plugin`. Each entry tracks its origin (`'builtin'` / `'extension'` / `'caller'`) so the engine can detect and report conflicting registrations.
 - `RuleEvaluator`: implementation of one rule type, such as `regex`, `path`, or `coverage-gate`.
-- `Fix`: byte-range replacement candidate. Fixes are collected separately from findings and are only written when you call `applyFixes()`.
+- `Fix`: byte-range replacement candidate. Fixes are collected separately from findings and only written when you call `applyFixes()`.
 - Preset: YAML/JSON file that composes rule categories and can expose extension modules.
+- `bundledRulesRoot()`: resolves the path to the `rules/` directory shipped with this package. Pass it as the lowest-priority root to `loadPreset()` so project-local and user-global roots shadow individual files while inheriting the rest.
+
+## Execution Flow
+
+When a rule is evaluated, the following sequence shows how the loader, host, engine, evaluator, and (optionally) the fixer pipeline cooperate.
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Loader as loadPreset / loadRuleFile
+    participant Engine as RuleEngine
+    participant Host as RuleEngineHost
+    participant Registry as CapabilityRegistry
+    participant Evaluator as RuleEvaluator
+    participant Fixer as RuleFixerProvider
+    participant FS as FileSystem
+
+    Note over Caller,Loader: 1. Rule loading
+    Caller->>Loader: loadPreset("recommended", { roots })
+    Loader->>Loader: merge roots (project → user-global → bundled)
+    Loader->>Loader: walk categories, read YAML/JSON
+    Loader->>Loader: Zod-validate, normalize severities, dedupe
+    Loader-->>Caller: { rules: ConstraintRule[], extensions: ExtensionRef[] }
+
+    Note over Caller,Host: 2. Extension registration (optional)
+    Caller->>Host: loadExtensionsIntoHost(host, extensions, { allowExtensions })
+    Host->>Host: import each extension module
+    Host->>Registry: register(name, impl, "extension")
+    Registry-->>Host: (origin-tracked entry)
+
+    Note over Caller,FS: 3. Evaluation
+    Caller->>Engine: evaluateWithFixes(rules, workdir, maxFixMode, stopOnFirst?)
+    loop For each enabled rule (exits early when stopOnFirst threshold met)
+        Engine->>Host: host.evaluators.get(evaluator.type)
+        Host->>Registry: get(type)
+        Registry-->>Engine: RuleEvaluator
+        Engine->>Evaluator: evaluate(rule, { rule, workdir })
+        Evaluator->>FS: scan files, read content
+        FS-->>Evaluator: file content / paths
+        Evaluator-->>Engine: { findings: Finding[], fixes: Fix[] }
+
+        opt rule.fix mode ≠ none and findings exist
+            Engine->>Fixer: fixers.get(evaluatorType)
+            Fixer->>Fixer: resolve effective mode (min(rule, caller))
+            Fixer->>FS: read / write (dry-run or real)
+            Fixer-->>Engine: Fix[]
+        end
+    end
+    Engine-->>Caller: RuleEngineResult { findings, fixes }
+
+    Note over Caller,FS: 4. Output / fix application
+    alt Format for display
+        Caller->>Caller: new TextFormatter().format(result)
+    else Apply fixes
+        Caller->>Engine: applyFixes(workdir, fixes, dryRun)
+        Engine->>FS: write byte-range replacements
+        FS-->>Engine: FixApplicationResult { diff, applied, deferred }
+    end
+```
+
+The key design decisions visible in this flow:
+
+- **Rule loading is lazy**: `loadPreset()` resolves and validates rules at load time but does not evaluate. No filesystem scanning happens until `evaluate()`.
+- **Evaluators are stateless plugins**: each evaluator receives `(rule, context)` and returns findings. The engine owns the loop, error boundary, and fixer dispatch.
+- **Fixes are opt-in and authority-gated**: the effective fix mode is `min(rule.fix.mode, caller.maxFixMode)`. Fixes are never written during evaluation — only when the caller explicitly calls `applyFixes()`.
+- **Extension loading is trust-gated**: the `allowExtensions` flag must be explicitly `true`. Without it, `loadExtensionsIntoHost()` throws, preventing untrusted code from registering capabilities.
+- **Origins prevent silent override**: each `CapabilityRegistry` entry records its origin. A preset extension cannot silently replace a built-in evaluator — conflicts are surfaced.
+
+## Quick Start
+
+```ts
+import { RuleEngine, TextFormatter, type ConstraintRule } from '@gobing-ai/ts-rule-engine';
+
+const rules: ConstraintRule[] = [
+  {
+    id: 'no-console-log',
+    description: 'Do not commit console.log calls',
+    enabled: true,
+    severity: 'error',
+    include: ['src/**/*.ts'],
+    evaluator: {
+      type: 'regex',
+      config: {
+        mode: 'forbid',
+        pattern: 'console\\.log\\(',
+      },
+    },
+  },
+];
+```
+
 
 ## Quick Start
 
@@ -95,12 +187,13 @@ const rules: ConstraintRule[] = [
 const engine = new RuleEngine();
 const result = await engine.evaluate(rules, process.cwd());
 
+// Or stop early after the first error finding:
+const fastResult = await engine.evaluate(rules, process.cwd(), 'error');
+
 console.log(new TextFormatter().format(result));
-process.exitCode = result.findings.some((finding) => finding.severity === 'error') ? 1 : 0;
 ```
 
 ## Rule Files
-
 Rule files can be YAML, JSON, or a single rule object. File loads honor a top-level `$schema` ref by default, then validate the internal Zod schema. The `$schema` value is resolved from the bundled package schema (shipped under `node_modules/@gobing-ai/ts-rule-engine/schemas/`) — no network access. Quote the value, since YAML treats a leading `@` as reserved. Relative paths and (opt-in) remote URLs are also supported; see `@gobing-ai/ts-runtime` → *Structured config* for the full resolution rules. A multi-rule YAML file looks like this:
 
 ```yaml
@@ -143,7 +236,32 @@ const { rules, extensions } = await loadRuleFile('.rules/typescript.yaml');
 
 ## Presets
 
-Presets compose category folders, other presets, and rule-file subpaths across one or more roots. Preset loads also honor top-level `$schema` refs by default, resolved from the bundled package schema (no network access).
+Presets compose category folders, other presets, and rule-file subpaths across one or more roots. Preset loads honor top-level `$schema` refs resolved from the bundled `schemas/` directory — no network access.
+
+### Bundled Rules
+
+The package ships a `rules/` directory with portable defaults. Call `bundledRulesRoot()` to get its absolute path and pass it as the lowest-priority root:
+
+```ts
+import { loadPreset, bundledRulesRoot } from '@gobing-ai/ts-rule-engine';
+
+const roots = ['.spur/rules', bundledRulesRoot()].filter(Boolean);
+const { rules, extensions } = await loadPreset('recommended', { roots });
+```
+
+Shipped categories:
+
+| Preset / Category | Path | What it covers |
+|-------------------|------|----------------|
+| `recommended` | `rules/recommended.yaml` | Extends `typescript` + `structure` + `quality` — general-use baseline. |
+| `spur-dev` | `rules/spur-dev.yaml` | Extends `typescript` + `quality` — stricter development preset, no `test-location`. |
+| `typescript/` | `rules/typescript/` | TypeScript hygiene rules (e.g. no `biome-ignore` suppressions). |
+| `structure/` | `rules/structure/` | Project structure rules (e.g. `test-location`). |
+| `quality/` | `rules/quality/` | Quality gates (e.g. `coverage-gate`, `tsdoc-exports`). |
+
+Use `listBundledRuleFiles()` to enumerate all shipped rule assets, useful for copying them into a writable user-global rules directory on first run.
+
+### Project-Local Presets
 
 Example layout:
 
@@ -248,19 +366,20 @@ rules:
       - "src/**/*.ts"
 ```
 
-Built-in fixer providers:
+Built-in fixer providers (`RegexFixerProvider`, `PathFixerProvider`, `TestStubFixer`):
 
 | Evaluator type | Fix behavior |
 | -------------- | ------------ |
-| `regex`, `rg` | Replaces line matches using `fix.replacement`. |
-| `path`, `file-exist` | Deletes files for `must: absent` rules in `auto` mode. |
-| `test-location` | Creates a missing test file using the selected resolver's skeleton when available. |
+| `regex`, `rg` | Replaces line matches using `fix.replacement` (`RegexFixerProvider`). |
+| `path`, `file-exist` | Deletes files for `must: absent` rules in `auto` mode (`PathFixerProvider`). |
+| `test-location` | Creates a missing test file using the selected resolver's skeleton (`TestStubFixer`). Never overwrites existing files. |
 
 ## Built-in Evaluators
 
 | Type | Purpose | Notes |
 | ---- | ------- | ----- |
-| `regex`, `rg` | Match or require text patterns in files. | Pure JS file scanning. Supports inline `(?i)` flags and `multiline`. |
+| `regex` | Match or require text patterns in files (JS `RegExp` engine). | Pure JS file scanning. Supports lookbehind/backreferences, inline `(?i)` flags, and `multiline`. Not ReDoS-bounded. |
+| `rg` | Match or require text patterns in files (real ripgrep engine). | Runs the `rg` CLI: ReDoS-immune, parallel, prunes heavy trees (`node_modules`, `dist`, …) during traversal. Ripgrep dialect — **no** lookbehind/backreferences. Requires the `rg` CLI. See [Rules Migration](#rules-migration). |
 | `path`, `file-exist` | Check required or forbidden paths. | Supports explicit `paths` or glob-style `must: present/absent`. |
 | `exit-code` | Run a command and evaluate its exit code. | Uses `ProcessExecutor`; inject one through `new RuleEngine({ processExecutor })` for tests. |
 | `forbidden-import` | Block forbidden imports/usages. | Useful for package boundary rules. |
@@ -385,6 +504,88 @@ rules:
     include: ["src/**/*.ts"]
 ```
 
+## Rules Migration
+
+The `rg` evaluator now runs the **real ripgrep CLI** instead of being a JS-`RegExp` alias of `regex`. Ripgrep's Rust regex engine is ReDoS-immune, runs in parallel, and prunes heavy trees (`node_modules`, `dist`, …) during traversal — a meaningful speedup on large workspaces. The trade-off is a stricter dialect: ripgrep has **no lookbehind and no backreferences**.
+
+This section explains how to move existing `regex` rules onto `rg` safely.
+
+### What changed
+
+| | `regex` (JS `RegExp`) | `rg` (ripgrep) |
+| --- | --- | --- |
+| Engine | In-process `new RegExp(...)` | `rg` CLI subprocess |
+| Performance | Walks files in-process | Parallel, prunes `node_modules`/`dist`/… during traversal |
+| ReDoS | Not bounded — a pathological pattern can hang | Linear-time — immune |
+| Lookbehind `(?<=…)` / `(?<!…)` | Supported | **Not supported** |
+| Backreferences `\1`, `\k<name>` | Supported | **Not supported** |
+| Inline `(?i)` flags, `multiline` | Supported | Supported (`(?i)` is native; `multiline` → `rg -U --multiline-dotall`) |
+| `mode: forbid` / `mode: require` | Supported | Supported (`require` → `rg --files-without-match`) |
+
+The rule config shape is identical (`pattern`, `mode`, `multiline`, `include`, `exclude`), so most rules migrate by changing one word: `type: regex` → `type: rg`.
+
+### The migration guard: `rg-evaluator-patterns-are-ripgrep-dialect`
+
+A built-in meta rule scans your `.spur/rules/**/*.yaml` and **fails the gate** if any `type: rg` rule uses a construct ripgrep cannot compile (lookbehind or backreference). This catches an incompatible migration at lint time instead of letting it explode at scan time. A violation looks like:
+
+```text
+INVALID: .spur/rules/typescript/my-rule.yaml: rules[0] rg pattern uses lookbehind (unsupported by ripgrep) — use type: regex
+```
+
+The fix is exactly what the message says: keep that rule on `type: regex`. The two evaluators coexist — use `rg` for the speed/safety win where the pattern allows, and `regex` where you genuinely need lookbehind/backreferences.
+
+### Migration steps
+
+1. **Ensure `rg` is installed** in every environment that runs the gate (CI included), the same way `sg` is required. A missing `rg` makes the rule fail loud, not silently pass.
+
+2. **Convert eligible rules.** For each `type: regex` rule, change it to `type: rg` *unless* its `pattern` uses lookbehind or a backreference:
+
+   ```yaml
+   # Before — JS RegExp engine
+   - id: no-debugger
+     description: Do not commit debugger statements
+     evaluator:
+       type: regex
+       config:
+         mode: forbid
+         pattern: "\\bdebugger\\b"
+     include: ["src/**/*.ts"]
+
+   # After — real ripgrep (pattern is dialect-compatible)
+   - id: no-debugger
+     description: Do not commit debugger statements
+     evaluator:
+       type: rg
+       config:
+         mode: forbid
+         pattern: "\\bdebugger\\b"
+     include: ["src/**/*.ts"]
+   ```
+
+3. **Leave incompatible rules on `regex`.** A pattern such as `(?<=const\s)X` (lookbehind) or `(\w+)\s+\1` (backreference) stays `type: regex`. The migration guard will flag it if you convert it by mistake.
+
+4. **Run the gate.** `rg-evaluator-patterns-are-ripgrep-dialect` runs as part of `spur rule run` (the pre-check preset). A clean run means every `rg` rule is dialect-safe.
+
+   ```bash
+   spur rule run --preset recommended-pre-check --fail-on warning
+   ```
+
+### Automated conversion
+
+`@gobing-ai/ts-rule-engine` exports `isRipgrepCompatiblePattern(pattern)` so a downstream tool can decide per rule whether to rewrite `type: regex` → `type: rg`:
+
+```ts
+import { isRipgrepCompatiblePattern } from "@gobing-ai/ts-rule-engine";
+
+const verdict = isRipgrepCompatiblePattern("(?<=foo)bar");
+// → { compatible: false, feature: "lookbehind" }  → keep this rule on `type: regex`
+
+isRipgrepCompatiblePattern("\\bdebugger\\b");
+// → { compatible: true }  → safe to rewrite to `type: rg`
+```
+
+This is the same check the migration guard uses, so a converter built on it and the spur rule never disagree.
+
 ## Test-Path Resolvers
 
 The `test-location` evaluator can require source files to have corresponding test files. The resolver is selected by `evaluator.config.resolver`.
@@ -501,7 +702,7 @@ const evaluator: RuleEvaluator & { name: string } = {
 export default evaluator;
 ```
 
-Load extensions:
+Load extensions (uses the shared `loadExtensionModules` from `@gobing-ai/ts-runtime/plugin`):
 
 ```ts
 const loaded = await loadPreset('local', { roots: ['.spur/rules'] });
@@ -515,13 +716,25 @@ await loadExtensionsIntoHost(engine.host, loaded.extensions, {
 
 Supported extension kinds:
 
-| Kind | Registry | Required shape |
-| ---- | -------- | -------------- |
-| `resolvers` | `host.resolvers` | object with `name` and `resolveTestPath()` |
-| `evaluators` | `host.evaluators` | object with `name` and `evaluate()` |
-| `formatters` | `host.formatters` | object with `name` and `format()` |
+| Kind | Host Registry | Required shape | Origin |
+| ---- | ------------ | -------------- | ------ |
+| `resolvers` | `host.resolvers` (`CapabilityRegistry<TestPathResolver>`) | object with `name` and `resolveTestPath()` | `'extension'` |
+| `evaluators` | `host.evaluators` (`CapabilityRegistry<RuleEvaluator>`) | object with `name` and `evaluate()` | `'extension'` |
+| `formatters` | `host.formatters` (`CapabilityRegistry<ResultFormatter>`) | object with `name` and `format()` | `'extension'` |
+
+## Traversal Control (`stopOnFirst`)
+
+By default, the engine evaluates every enabled rule exhaustively. Pass `stopOnFirst: 'error' | 'warning' | 'info'` to break early when the severity threshold is met:
 
-`fixers` can be declared in preset metadata but are not loaded into `RuleEngineHost` by `loadExtensionsIntoHost()` because fixer providers live on the engine's fixer map.
+```ts
+// Stop after the first error-level finding — skip remaining rules.
+await engine.evaluate(rules, workdir, 'error');
+
+// Same behavior via evaluateWithFixes.
+await engine.evaluateWithFixes(rules, workdir, 'auto', 'error');
+```
+
+The threshold compares findings against `SEVERITY_RANK` (`error: 3 > warning: 2 > info: 1`). Omitting the parameter preserves exhaustive evaluation.
 
 ## Formatting Results
 
@@ -555,13 +768,70 @@ const errors = result.findings.filter((finding) => finding.kind === 'error');
 const violations = result.findings.filter((finding) => finding.kind !== 'error');
 ```
 
+## Observability
+
+The rule engine uses a **three-layer observability model** (ADR-015):
+
+| Layer | Tool | Consumer |
+|-------|------|----------|
+| Logs | `getLogger('rule-engine')` | Human-readable debugging / file output |
+| Traces | `traceAsync('rule.run')` + `addSpanEvent` per rule | Distributed perf correlation (OTel) |
+| Events | `EventBus<RuleEngineEvents>` | Programmatic in-process subscription (progress bars, CI dashboards) |
+
+All three layers are **additive** — EventBus does not replace logging or tracing. A consumer who wants a progress bar subscribes to events; a consumer who wants traces attaches an OTel collector; both work independently.
+
+### Event Map
+
+`RuleEngineEvents` is a typed event map. All events are prefixed `rule.`:
+
+| Event | Payload | When |
+|-------|---------|------|
+| `rule.run.start` | `{ rules, total }` | Before the first rule is evaluated |
+| `rule.eval.start` | `{ ruleId, index, total }` | Before a single rule's evaluator is invoked |
+| `rule.eval.done` | `{ ruleId, findings, durationMs }` | After a single rule evaluation finishes successfully |
+| `rule.eval.error` | `{ ruleId, error }` | When a rule evaluator throws (distinct from a violation finding) |
+| `rule.run.done` | `{ rules, findings, durationMs, stoppedEarly }` | After the last rule finishes (or short-circuited) |
+
+### Usage
+
+Pass an `EventBus` to the engine constructor:
+
+```ts
+import { RuleEngine } from '@gobing-ai/ts-rule-engine';
+import { EventBus } from '@gobing-ai/ts-infra';
+import type { RuleEngineEvents } from '@gobing-ai/ts-rule-engine';
+
+const bus = new EventBus<RuleEngineEvents>();
+
+bus.on('rule.eval.done', (data) => {
+  console.log(`Rule ${data.ruleId}: ${data.findings} findings (${data.durationMs}ms)`);
+});
+
+bus.on('rule.run.done', (data) => {
+  console.log(`Run complete: ${data.findings} total findings${data.stoppedEarly ? ' (stopped early)' : ''}`);
+});
+
+const engine = new RuleEngine({ events: bus });
+const result = await engine.evaluate(rules, workdir);
+```
+
+### Zero-overhead default
+
+When no `events` option is provided, the engine incurs zero observability overhead — no emit calls, no handler invocations. The event bus is purely opt-in.
+
+### `rule.eval.error` vs violation findings
+
+`rule.eval.error` is emitted when an evaluator **throws** — it signals a crash, not a policy violation. The engine still produces a `kind: 'error'` finding for the thrown rule. A normal policy violation emits **no** `rule.eval.error`. Don't conflate the two: subscribe to `rule.eval.error` for crash alerting, and inspect findings for policy results.
+
 ## Package Boundary
 
-This package owns rule definitions, preset loading, evaluators, formatters, test-path resolvers, and fix application. It does not own:
+This package owns rule definitions, preset loading, evaluators, formatters, test-path resolvers, fixer providers, extension loading, the `CapabilityRegistry` re-export from `@gobing-ai/ts-runtime/plugin`, and bundled rule presets.
+
+It does **not** own:
 
-- CLI argument parsing
-- process exit policy
-- repository-specific rule catalogs
-- publishing or CI integration
+- CLI argument parsing or process exit policy
+- `ProcessExecutor` implementation (injected via `RuleEngineOptions`)
+- Repository-specific rule catalogs (project rules live in `.spur/rules/`)
+- CI integration or publishing workflows
 
-Those concerns should live in downstream tools that consume this library.
+Downstream tools (e.g. `spur`) consume the library and add their own CLI, config discovery, and execution policy.

package/dist/config/extensions.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from '@gobing-ai/ts-infra';
 import type { RuleEngineHost } from '../host/rule-engine-host';
 /** A capability kind a preset extension can contribute. */
 export type ExtensionKind = 'resolvers' | 'evaluators' | 'fixers' | 'formatters';
@@ -19,9 +20,7 @@ export interface LoadExtensionsOptions {
      */
     allowExtensions?: boolean;
     /** Optional sink for non-fatal warnings (e.g. built-in overrides). */
-    logger?: {
-        warn: (message: string) => void;
-    };
+    logger?: Pick<Logger, 'warn'>;
     /** Optional module loader seam for tests or embedders with custom import policy. */
     moduleLoader?: (absPath: string) => Promise<Record<string, unknown>>;
 }
@@ -37,13 +36,17 @@ export declare function collectExtensions(sourceName: string, sourceDir: string,
  * Import each extension module and register its export on the matching host
  * registry.
  *
- * A module must default-export (or named-export `extension`) an object with a
- * `name: string` and the capability implementation. Loading is gated by
+ * Delegates generic loading (trust gate, path guard, module import, export-shape
+ * validation) to the shared ``loadExtensionModules`` from ts-runtime/plugin, then
+ * routes each capability to the correct host registry based on ``ref.kind``.
+ *
+ * A module must default-export (or named-export ``extension``) an object with a
+ * ``name: string`` and the capability implementation. Loading is gated by
  * {@link LoadExtensionsOptions.allowExtensions}; when refs are present but
  * loading is not allowed, this throws so the requirement is never silently dropped.
  *
- * @throws When extensions are present but `allowExtensions` is not true, or when
- *   a module cannot be imported or lacks a valid `name`.
+ * @throws When extensions are present but ``allowExtensions`` is not true, or when
+ *   a module cannot be imported or lacks a valid ``name``.
  */
 export declare function loadExtensionsIntoHost(host: RuleEngineHost, refs: readonly ExtensionRef[], options?: LoadExtensionsOptions): Promise<void>;
 //# sourceMappingURL=extensions.d.ts.map

package/dist/config/extensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEjF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAC7C,oFAAoF;IACpF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxE;AASD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC7E,YAAY,EAAE,CAShB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAoCf"}
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAOlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEjF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,oFAAoF;IACpF,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxE;AASD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC7E,YAAY,EAAE,CAShB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/dist/config/extensions.js

@@ -1,4 +1,6 @@
-import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { basenamePath, dirnamePath, resolvePath, SEP } from '@gobing-ai/ts-runtime';
+import { loadExtensionModules } from '@gobing-ai/ts-runtime/plugin';
 /** Host registries that can receive extension capabilities (fixers live on the engine, not the host). */
 const HOST_REGISTRY_BY_KIND = {
     resolvers: 'resolvers',
@@ -18,7 +20,7 @@ export function collectExtensions(sourceName, sourceDir, extensions) {
     const refs = [];
     for (const kind of ['resolvers', 'evaluators', 'fixers', 'formatters']) {
         for (const path of extensions[kind] ?? []) {
-            refs.push({ kind, presetName: sourceName, absPath: resolve(sourceDir, path) });
+            refs.push({ kind, presetName: sourceName, absPath: resolvePath(sourceDir, path) });
         }
     }
     return refs;
@@ -27,41 +29,64 @@ export function collectExtensions(sourceName, sourceDir, extensions) {
  * Import each extension module and register its export on the matching host
  * registry.
  *
- * A module must default-export (or named-export `extension`) an object with a
- * `name: string` and the capability implementation. Loading is gated by
+ * Delegates generic loading (trust gate, path guard, module import, export-shape
+ * validation) to the shared ``loadExtensionModules`` from ts-runtime/plugin, then
+ * routes each capability to the correct host registry based on ``ref.kind``.
+ *
+ * A module must default-export (or named-export ``extension``) an object with a
+ * ``name: string`` and the capability implementation. Loading is gated by
  * {@link LoadExtensionsOptions.allowExtensions}; when refs are present but
  * loading is not allowed, this throws so the requirement is never silently dropped.
  *
- * @throws When extensions are present but `allowExtensions` is not true, or when
- *   a module cannot be imported or lacks a valid `name`.
+ * @throws When extensions are present but ``allowExtensions`` is not true, or when
+ *   a module cannot be imported or lacks a valid ``name``.
  */
 export async function loadExtensionsIntoHost(host, refs, options = {}) {
     if (refs.length === 0)
         return;
-    if (options.allowExtensions !== true) {
-        const first = refs[0];
-        throw new Error(`preset "${first.presetName}" declares ${first.kind} extension "${first.absPath}", but extensions are disabled — pass allowExtensions: true to load preset extension modules`);
-    }
-    const loadModule = options.moduleLoader ?? defaultModuleLoader;
+    // Normalize file:// URLs to file paths so dirname/basename produce valid
+    // path components that isAbsolute() accepts (e.g. import.meta.url in tests).
+    const toFilePath = (p) => (p.startsWith('file://') ? fileURLToPath(p) : p);
+    // Defense-in-depth: pre-validate `..` traversal in caller-supplied absPath
+    // before the basename adaptation strips it.  The shared loader's
+    // assertRelativeExtensionPath also runs on the derived (basename) path.
     for (const ref of refs) {
-        const moduleExports = await loadModule(ref.absPath);
-        const candidate = moduleExports.default ?? moduleExports.extension;
-        if (candidate === null ||
-            typeof candidate !== 'object' ||
-            typeof candidate.name !== 'string') {
-            throw new Error(`preset "${ref.presetName}" extension "${ref.absPath}" must export an object with a string "name"`);
+        const segments = toFilePath(ref.absPath).split(SEP);
+        if (segments.includes('..')) {
+            throw new Error(`extension path "${ref.absPath}" declared by "${ref.presetName}" must not contain ".." traversal`);
         }
-        const name = candidate.name;
-        const registryKey = HOST_REGISTRY_BY_KIND[ref.kind];
+    }
+    // Adapt rule-engine ExtensionRef → shared ExtensionRef so the generic loader
+    // governs every import.  The shared loader resolves (baseDir, path) →
+    // absPath internally; we supply dirname/basename so the resolved path
+    // reconstructs the caller's original absPath.
+    const sharedRefs = refs.map((ref) => {
+        const fp = toFilePath(ref.absPath);
+        return {
+            kind: ref.kind,
+            path: `./${basenamePath(fp)}`,
+            baseDir: dirnamePath(fp),
+            sourceName: ref.presetName,
+        };
+    });
+    const moduleLoader = options.moduleLoader ?? defaultModuleLoader;
+    const sharedOptions = {
+        allowExtensions: options.allowExtensions,
+        logger: options.logger,
+        moduleLoader,
+    };
+    await loadExtensionModules(sharedRefs, sharedOptions, async (sharedRef, extension) => {
+        const name = extension.name;
+        const registryKey = HOST_REGISTRY_BY_KIND[sharedRef.kind];
         if (registryKey === undefined) {
-            throw new Error(`preset "${ref.presetName}" ${ref.kind} extensions are not supported`);
+            throw new Error(`"${sharedRef.sourceName}" ${sharedRef.kind} extensions are not supported`);
         }
         const registry = host[registryKey];
         if (options.logger && registry.has?.(name)) {
-            options.logger.warn(`preset "${ref.presetName}" ${ref.kind} extension overrides existing "${name}"`);
+            options.logger.warn(`"${sharedRef.sourceName}" ${sharedRef.kind} extension overrides existing "${name}"`);
         }
-        registry.register(name, candidate, 'extension');
-    }
+        registry.register(name, extension, 'extension');
+    });
 }
 async function defaultModuleLoader(absPath) {
     return (await import(absPath));