@gobing-ai/ts-rule-engine 0.5.21 → 0.5.23

package/README.md

@@ -485,6 +485,80 @@ rules:
     include: ["src/**/*.ts"]
 ```
 
+## Fixture Verification
+
+`verifyRuleFixtures` asserts a rule's own fixtures against the **real** evaluators — the same
+`RuleEngine`, the same registered evaluator implementations — so a fixture's expectation is checked
+by the code it documents, not by a second implementation of the same idea. One rule is evaluated
+against one prepared workdir at a time, independently, sequentially, and with fixes disabled.
+
+```ts
+import { verifyRuleFixtures } from '@gobing-ai/ts-rule-engine';
+
+const result = await verifyRuleFixtures({
+    ruleFile: '.spur/rules/quality/verify-confidence.yaml',
+    fixtureDir: '.spur/rules/fixtures/verify-confidence',
+    cases: [
+        {
+            path: 'should-fire/.spur/run/0101-verdict.json',
+            workdir: '/tmp/staged/0101',
+            ruleIds: ['verify-confidence-level'],
+            expect: 'fire',
+        },
+    ],
+});
+```
+
+`RuleFixtureVerificationOptions`:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `ruleFile` | `string` | Rule file loaded through `loadRuleFile`; always a physical path, because the loader has no filesystem port. |
+| `fixtureDir` | `string` | Root the case `path`s resolve under. Absent is an explicit skip. |
+| `cases` | `RuleFixtureCase[]` | Prepared cases: `{ path, workdir, ruleIds, expect }`. Each case is staged by the caller. |
+| `fileSystem` | `FileSystem?` | Port for the existence check and evaluation. Defaults to `createNodeFileSystem()`. |
+| `processExecutor` | `ProcessExecutor?` | Executor handed to process-backed evaluators. Defaults to `nodeBunFactory.createProcessExecutor()`. |
+
+`RuleFixtureVerificationResult` carries `pass`, `skipped`, and one `RuleFixtureCaseResult` per
+case/rule pair (`path`, `ruleId`, `expect`, `pass`, `findings`, `processes`, optional `error`).
+
+What each expectation means:
+
+- `expect: 'fire'` requires a genuine violation finding; `expect: 'pass'` requires zero findings.
+- An evaluator error never satisfies an expected violation — it fails the pair either way.
+- An `exit-code` rule is additionally asserted on the recorded process result: a normal exit must
+differ from (fire) or equal (pass) the rule's configured `successCode` (default `0`). A timeout,
+signal, spawn failure or any non-`exit` outcome fails the pair regardless of expectation, and the
+captured stdout/stderr and findings are retained in the failure diagnostic.
+
+Failure is never silent:
+
+| Situation | Outcome |
+|-----------|---------|
+| Absent optional `fixtureDir` | `pass: true, skipped: true, cases: []` — nothing was asserted. |
+| Existing `fixtureDir` that is not a directory | Throws instead of silently skipping. |
+| Present but empty `cases` | Failure: an empty case set cannot pass vacuously. |
+| Unknown or disabled rule ID | Failure naming the rule ID. |
+| Absent case workdir, or case `path` missing under `fixtureDir` | Failure naming the case. |
+| `ruleFile` declares extension modules | Throws — this verifier supports built-in rules only, and never silently ignores an extension. |
+| Unreadable rule file, or a case selecting no rule IDs | Throws. |
+
+### Repository gate
+
+A consuming repository wires this into its own gate with a thin adapter, because enumeration,
+staging and reporting are repository-specific. `bun run verify-rule-fixtures`
+(`scripts/verify-rule-fixtures.ts` in this workspace) enumerates every declared fixture directory,
+stages each case into an OS-temp workdir, evaluates it, prints a per-set and per-expectation
+summary, and writes a machine-readable report to `.spur/run/rule-fixtures-report.json` before
+exiting non-zero on any mismatch. It reads checked-in fixtures only, never evaluates the live
+repository as a case, removes its scratch workdirs in a `finally`, and fails — rather than skips —
+on a deleted declared directory or an unrecognized fixture shape.
+
+The adapter also checks SHA-256 content pins in `scripts/rule-fixture-hashes.json`, including
+support files, so empty or replaced fixtures cannot pass solely through a rule's fail-safe branch.
+Update the corresponding pin alongside each intentional fixture edit; the gate reports changed
+paths and still evaluates the real rules.
+
 ## 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**.
@@ -939,4 +1013,4 @@ It does **not** own:
 - Repository-specific rule catalogs (project rules live in `.spur/rules/`)
 - CI integration or publishing workflows
 
-Downstream tools (e.g. `spur`) consume the library and add their own CLI, config discovery, run-id stamping, and execution policy.
+Downstream tools (e.g. `spur`) consume the library and add their own CLI, config discovery, run-id stamping, and execution policy.

package/dist/evaluators/glob-match.js

@@ -44,7 +44,7 @@ export function matchesGlob(path, pattern) {
     if (pattern.startsWith('**/')) {
         const suffix = pattern.slice(3);
         if (suffix.indexOf('*') === -1) {
-            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
+            return normalized === suffix || normalized.endsWith(`/${suffix}`);
         }
     }
     if (pattern === normalized)

package/dist/evaluators/ripgrep-evaluator.js

@@ -5,7 +5,7 @@ import { configString, DEFAULT_EXCLUDES } from './file-utils.js';
  * Evaluates source files against a regex using the `rg` (ripgrep) CLI.
  *
  * This is the real ripgrep-backed engine registered under the `rg` rule type. Unlike
- * the {@link import('./regex-evaluator.js').RegexEvaluator} (`regex` type, JS `RegExp`),
+ * the {@link import('./regex-evaluator').RegexEvaluator} (`regex` type, JS `RegExp`),
  * it runs ripgrep's linear-time Rust regex engine: ReDoS-immune, parallel, and pruning
  * heavy trees during traversal. The dialect differs from JS `RegExp` — no lookbehind or
  * backreferences — so rule patterns must be ripgrep-compatible (enforced by the

package/dist/fixture-verifier.d.ts

@@ -0,0 +1,68 @@
+import { type FileSystem, type ProcessExecutor, type ProcessResult } from '@gobing-ai/ts-runtime';
+import type { ConstraintFinding } from './types';
+/** One prepared fixture case: a staged workdir plus the rules it must satisfy. */
+export interface RuleFixtureCase {
+    /** Fixture-relative source path this case asserts; used for the existence check and diagnostics. */
+    path: string;
+    /** Prepared working directory the evaluator runs in. */
+    workdir: string;
+    /** Rule IDs evaluated independently against this workdir. */
+    ruleIds: string[];
+    /** Required outcome for every selected rule. */
+    expect: 'fire' | 'pass';
+}
+/** Options for {@link verifyRuleFixtures}. */
+export interface RuleFixtureVerificationOptions {
+    /** Rule file holding the selected rules. Always read from disk: the loader has no filesystem port. */
+    ruleFile: string;
+    /** Fixture root the case `path`s resolve under. Absent → the whole verification is skipped. */
+    fixtureDir: string;
+    /** Prepared cases to assert, in order. */
+    cases: RuleFixtureCase[];
+    /** Filesystem port for fixture checks and evaluation. Defaults to `createNodeFileSystem()`. */
+    fileSystem?: FileSystem;
+    /** Executor for process-backed evaluators. Defaults to `nodeBunFactory.createProcessExecutor()`. */
+    processExecutor?: ProcessExecutor;
+}
+/** Outcome of one case/rule pair. */
+export interface RuleFixtureCaseResult {
+    /** Fixture-relative source path from the case declaration. */
+    path: string;
+    /** Rule ID this result asserts. */
+    ruleId: string;
+    /** Expected outcome declared by the case. */
+    expect: 'fire' | 'pass';
+    /** Whether the recorded evaluation matched the expectation. */
+    pass: boolean;
+    /** Findings the engine recorded for this pair. */
+    findings: ConstraintFinding[];
+    /** Process results recorded while evaluating this pair, in invocation order. */
+    processes: ProcessResult[];
+    /** Failure reason; absent when `pass` is true. */
+    error?: string;
+}
+/** Aggregate verification result. */
+export interface RuleFixtureVerificationResult {
+    /** True when every case/rule pair passed (also true for a skipped run). */
+    pass: boolean;
+    /** True when the optional fixture directory is absent, so nothing was asserted. */
+    skipped: boolean;
+    /** Per case/rule results. */
+    cases: RuleFixtureCaseResult[];
+}
+/**
+ * Verify prepared rule fixtures against the real evaluators.
+ *
+ * Loads `ruleFile`, then evaluates one selected rule against one case workdir at a
+ * time: expected-`fire` cases need a genuine violation, expected-`pass` cases need
+ * zero findings, and evaluator errors always fail. Exit-code rules are additionally
+ * asserted on the process result the evaluator produced — the recorded normal exit
+ * must differ from (fire) or equal (pass) the configured `successCode` (default 0),
+ * and timeout / signal / launch failure always fails.
+ *
+ * An absent `fixtureDir` yields `pass=true, skipped=true, cases=[]`; a present but
+ * empty case set fails. Invalid configuration (no selected rule IDs, extension
+ * declarations, unreadable rule file) throws.
+ */
+export declare function verifyRuleFixtures(options: RuleFixtureVerificationOptions): Promise<RuleFixtureVerificationResult>;
+//# sourceMappingURL=fixture-verifier.d.ts.map

package/dist/fixture-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-verifier.d.ts","sourceRoot":"","sources":["../src/fixture-verifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,UAAU,EAGf,KAAK,eAAe,EACpB,KAAK,aAAa,EACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,SAAS,CAAC;AAEjE,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC5B,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,8CAA8C;AAC9C,MAAM,WAAW,8BAA8B;IAC3C,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,oGAAoG;IACpG,eAAe,CAAC,EAAE,eAAe,CAAC;CACrC;AAED,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IAClC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;IACd,kDAAkD;IAClD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,gFAAgF;IAChF,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,6BAA6B;IAC1C,2EAA2E;IAC3E,IAAI,EAAE,OAAO,CAAC;IACd,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,KAAK,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACpC,OAAO,EAAE,8BAA8B,GACxC,OAAO,CAAC,6BAA6B,CAAC,CA0ExC"}

package/dist/fixture-verifier.js

@@ -0,0 +1,151 @@
+import { createNodeFileSystem, joinPath, nodeBunFactory, } from '@gobing-ai/ts-runtime';
+import { loadRuleFile } from './config/loader.js';
+import { RuleEngine } from './engine.js';
+/**
+ * Verify prepared rule fixtures against the real evaluators.
+ *
+ * Loads `ruleFile`, then evaluates one selected rule against one case workdir at a
+ * time: expected-`fire` cases need a genuine violation, expected-`pass` cases need
+ * zero findings, and evaluator errors always fail. Exit-code rules are additionally
+ * asserted on the process result the evaluator produced — the recorded normal exit
+ * must differ from (fire) or equal (pass) the configured `successCode` (default 0),
+ * and timeout / signal / launch failure always fails.
+ *
+ * An absent `fixtureDir` yields `pass=true, skipped=true, cases=[]`; a present but
+ * empty case set fails. Invalid configuration (no selected rule IDs, extension
+ * declarations, unreadable rule file) throws.
+ */
+export async function verifyRuleFixtures(options) {
+    const { ruleFile, fixtureDir, cases } = options;
+    const fileSystem = options.fileSystem ?? createNodeFileSystem();
+    const fixtureStat = await fileSystem.stat(fixtureDir);
+    if (fixtureStat === null)
+        return { pass: true, skipped: true, cases: [] };
+    if (!fixtureStat.isDirectory())
+        throw new Error(`Fixture root "${fixtureDir}" is not a directory`);
+    if (cases.length === 0)
+        return { pass: false, skipped: false, cases: [] };
+    for (const fixtureCase of cases) {
+        if (fixtureCase.ruleIds.length === 0) {
+            throw new Error(`Rule fixture case "${fixtureCase.path}" selects no rule IDs`);
+        }
+    }
+    const loaded = await loadRuleFile(ruleFile);
+    if (loaded.extensions.length > 0) {
+        throw new Error(`Rule file "${ruleFile}" declares extension modules; verifyRuleFixtures supports built-in rules only`);
+    }
+    const rulesById = new Map(loaded.rules.filter((rule) => rule.enabled !== false).map((rule) => [rule.id, rule]));
+    // Captured per pair: the wrapper records the original ProcessResult so exit-code
+    // rules can be asserted on the real process outcome without touching evaluators.
+    const processes = [];
+    const executor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
+    const engine = new RuleEngine({
+        fileSystem,
+        processExecutor: {
+            run: async (runOptions) => {
+                const result = await executor.run(runOptions);
+                processes.push(result);
+                return result;
+            },
+            runStreaming: (runOptions) => executor.runStreaming(runOptions),
+        },
+    });
+    const results = [];
+    for (const fixtureCase of cases) {
+        const setupError = await caseSetupError(fileSystem, fixtureDir, fixtureCase);
+        for (const ruleId of fixtureCase.ruleIds) {
+            const rule = rulesById.get(ruleId);
+            if (setupError !== undefined || rule === undefined) {
+                results.push({
+                    path: fixtureCase.path,
+                    ruleId,
+                    expect: fixtureCase.expect,
+                    pass: false,
+                    findings: [],
+                    processes: [],
+                    error: setupError ?? `rule "${ruleId}" is not an enabled rule in "${ruleFile}"`,
+                });
+                continue;
+            }
+            processes.length = 0;
+            const findings = (await engine.evaluate([rule], fixtureCase.workdir)).findings;
+            const recorded = [...processes];
+            const verdict = judgeCase(fixtureCase.expect, rule, findings, recorded);
+            results.push({
+                path: fixtureCase.path,
+                ruleId,
+                expect: fixtureCase.expect,
+                pass: verdict.pass,
+                findings,
+                processes: recorded,
+                ...(verdict.error !== undefined ? { error: verdict.error } : {}),
+            });
+        }
+    }
+    return { pass: results.every((result) => result.pass), skipped: false, cases: results };
+}
+/** Fail a case whose declared source or prepared workdir is absent. */
+async function caseSetupError(fileSystem, fixtureDir, fixtureCase) {
+    const sourceStat = await fileSystem.stat(joinPath(fixtureDir, fixtureCase.path));
+    if (sourceStat === null)
+        return `case source "${fixtureCase.path}" is missing under "${fixtureDir}"`;
+    const workdirStat = await fileSystem.stat(fixtureCase.workdir);
+    if (workdirStat === null || !workdirStat.isDirectory()) {
+        return `case workdir "${fixtureCase.workdir}" is missing`;
+    }
+    return undefined;
+}
+/** Assert findings — and, for exit-code rules, the recorded process result — against the expectation. */
+function judgeCase(expect, rule, findings, processes) {
+    const evaluatorErrors = findings.filter((finding) => finding.kind === 'error');
+    if (evaluatorErrors.length > 0) {
+        return { pass: false, error: `evaluator error: ${evaluatorErrors.map((f) => f.message).join('; ')}` };
+    }
+    const violations = findings.filter((finding) => finding.kind !== 'error');
+    if (rule.evaluator.type === 'exit-code')
+        return judgeExitCodeCase(expect, rule, processes);
+    if (expect === 'fire') {
+        return violations.length > 0
+            ? { pass: true }
+            : { pass: false, error: 'expected fire but the rule reported no violation' };
+    }
+    return violations.length === 0
+        ? { pass: true }
+        : { pass: false, error: `expected pass but the rule reported ${violations.length} violation(s)` };
+}
+/** Judge an exit-code pair on the recorded normal exit versus the rule's configured `successCode`. */
+function judgeExitCodeCase(expect, rule, processes) {
+    const configured = rule.evaluator.config?.successCode;
+    const successCode = typeof configured === 'number' ? configured : 0;
+    const [execution] = processes;
+    if (execution === undefined)
+        return { pass: false, error: 'exit-code: no process result recorded' };
+    const abnormal = execution.exitCode === null || (execution.outcome !== undefined && execution.outcome !== 'exit');
+    if (abnormal) {
+        const signal = execution.signal !== undefined ? ` (signal ${execution.signal})` : '';
+        return {
+            pass: false,
+            error: `exit-code: process did not complete normally (outcome ${execution.outcome ?? 'unknown'}${signal})${processDiagnostics(execution)}`,
+        };
+    }
+    // The evaluator reports a violation exactly when the exit differs from the
+    // configured success code, so the exit comparison is the assertion for both halves.
+    if (expect === 'fire') {
+        return execution.exitCode === successCode
+            ? {
+                pass: false,
+                error: `expected fire but exit ${execution.exitCode} equals successCode ${successCode}${processDiagnostics(execution)}`,
+            }
+            : { pass: true };
+    }
+    return execution.exitCode === successCode
+        ? { pass: true }
+        : {
+            pass: false,
+            error: `expected pass but exit ${execution.exitCode} differs from successCode ${successCode}${processDiagnostics(execution)}`,
+        };
+}
+/** Append the recorded streams to an exit-code failure diagnostic. */
+function processDiagnostics(execution) {
+    return `\nstdout: ${execution.stdout}\nstderr: ${execution.stderr}`;
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { isRipgrepCompatiblePattern } from './evaluators/ripgrep-evaluator';
 export type { RuleEngineEvents } from './events';
 export * from './fixers/fixers';
 export * from './fixers/test-stub-fixer';
+export * from './fixture-verifier';
 export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/bundled-rules';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAClH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAClH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './engine.js';
 export { isRipgrepCompatiblePattern } from './evaluators/ripgrep-evaluator.js';
 export * from './fixers/fixers.js';
 export * from './fixers/test-stub-fixer.js';
+export * from './fixture-verifier.js';
 export * from './formatters/json.js';
 export * from './formatters/text.js';
 export * from './host/bundled-rules.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.5.21",
+    "version": "0.5.23",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -51,10 +51,10 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-rule-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.5.21",
-        "@gobing-ai/ts-infra": "^0.5.21",
-        "@gobing-ai/ts-runtime": "^0.5.21",
-        "@gobing-ai/ts-db": "^0.5.21",
+        "@gobing-ai/ts-ai-runner": "^0.5.23",
+        "@gobing-ai/ts-infra": "^0.5.23",
+        "@gobing-ai/ts-runtime": "^0.5.23",
+        "@gobing-ai/ts-db": "^0.5.23",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/src/evaluators/glob-match.ts

@@ -44,7 +44,7 @@ export function matchesGlob(path: string, pattern: string): boolean {
     if (pattern.startsWith('**/')) {
         const suffix = pattern.slice(3);
         if (suffix.indexOf('*') === -1) {
-            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
+            return normalized === suffix || normalized.endsWith(`/${suffix}`);
         }
     }
     if (pattern === normalized) return true;

package/src/fixture-verifier.ts

@@ -0,0 +1,236 @@
+import {
+    createNodeFileSystem,
+    type FileSystem,
+    joinPath,
+    nodeBunFactory,
+    type ProcessExecutor,
+    type ProcessResult,
+} from '@gobing-ai/ts-runtime';
+import { loadRuleFile } from './config/loader';
+import { RuleEngine } from './engine';
+import type { ConstraintFinding, ConstraintRule } from './types';
+
+/** One prepared fixture case: a staged workdir plus the rules it must satisfy. */
+export interface RuleFixtureCase {
+    /** Fixture-relative source path this case asserts; used for the existence check and diagnostics. */
+    path: string;
+    /** Prepared working directory the evaluator runs in. */
+    workdir: string;
+    /** Rule IDs evaluated independently against this workdir. */
+    ruleIds: string[];
+    /** Required outcome for every selected rule. */
+    expect: 'fire' | 'pass';
+}
+
+/** Options for {@link verifyRuleFixtures}. */
+export interface RuleFixtureVerificationOptions {
+    /** Rule file holding the selected rules. Always read from disk: the loader has no filesystem port. */
+    ruleFile: string;
+    /** Fixture root the case `path`s resolve under. Absent → the whole verification is skipped. */
+    fixtureDir: string;
+    /** Prepared cases to assert, in order. */
+    cases: RuleFixtureCase[];
+    /** Filesystem port for fixture checks and evaluation. Defaults to `createNodeFileSystem()`. */
+    fileSystem?: FileSystem;
+    /** Executor for process-backed evaluators. Defaults to `nodeBunFactory.createProcessExecutor()`. */
+    processExecutor?: ProcessExecutor;
+}
+
+/** Outcome of one case/rule pair. */
+export interface RuleFixtureCaseResult {
+    /** Fixture-relative source path from the case declaration. */
+    path: string;
+    /** Rule ID this result asserts. */
+    ruleId: string;
+    /** Expected outcome declared by the case. */
+    expect: 'fire' | 'pass';
+    /** Whether the recorded evaluation matched the expectation. */
+    pass: boolean;
+    /** Findings the engine recorded for this pair. */
+    findings: ConstraintFinding[];
+    /** Process results recorded while evaluating this pair, in invocation order. */
+    processes: ProcessResult[];
+    /** Failure reason; absent when `pass` is true. */
+    error?: string;
+}
+
+/** Aggregate verification result. */
+export interface RuleFixtureVerificationResult {
+    /** True when every case/rule pair passed (also true for a skipped run). */
+    pass: boolean;
+    /** True when the optional fixture directory is absent, so nothing was asserted. */
+    skipped: boolean;
+    /** Per case/rule results. */
+    cases: RuleFixtureCaseResult[];
+}
+
+/**
+ * Verify prepared rule fixtures against the real evaluators.
+ *
+ * Loads `ruleFile`, then evaluates one selected rule against one case workdir at a
+ * time: expected-`fire` cases need a genuine violation, expected-`pass` cases need
+ * zero findings, and evaluator errors always fail. Exit-code rules are additionally
+ * asserted on the process result the evaluator produced — the recorded normal exit
+ * must differ from (fire) or equal (pass) the configured `successCode` (default 0),
+ * and timeout / signal / launch failure always fails.
+ *
+ * An absent `fixtureDir` yields `pass=true, skipped=true, cases=[]`; a present but
+ * empty case set fails. Invalid configuration (no selected rule IDs, extension
+ * declarations, unreadable rule file) throws.
+ */
+export async function verifyRuleFixtures(
+    options: RuleFixtureVerificationOptions,
+): Promise<RuleFixtureVerificationResult> {
+    const { ruleFile, fixtureDir, cases } = options;
+    const fileSystem = options.fileSystem ?? createNodeFileSystem();
+    const fixtureStat = await fileSystem.stat(fixtureDir);
+    if (fixtureStat === null) return { pass: true, skipped: true, cases: [] };
+    if (!fixtureStat.isDirectory()) throw new Error(`Fixture root "${fixtureDir}" is not a directory`);
+    if (cases.length === 0) return { pass: false, skipped: false, cases: [] };
+    for (const fixtureCase of cases) {
+        if (fixtureCase.ruleIds.length === 0) {
+            throw new Error(`Rule fixture case "${fixtureCase.path}" selects no rule IDs`);
+        }
+    }
+
+    const loaded = await loadRuleFile(ruleFile);
+    if (loaded.extensions.length > 0) {
+        throw new Error(
+            `Rule file "${ruleFile}" declares extension modules; verifyRuleFixtures supports built-in rules only`,
+        );
+    }
+    const rulesById = new Map(
+        loaded.rules.filter((rule) => rule.enabled !== false).map((rule) => [rule.id, rule] as const),
+    );
+
+    // Captured per pair: the wrapper records the original ProcessResult so exit-code
+    // rules can be asserted on the real process outcome without touching evaluators.
+    const processes: ProcessResult[] = [];
+    const executor = options.processExecutor ?? nodeBunFactory.createProcessExecutor();
+    const engine = new RuleEngine({
+        fileSystem,
+        processExecutor: {
+            run: async (runOptions) => {
+                const result = await executor.run(runOptions);
+                processes.push(result);
+                return result;
+            },
+            runStreaming: (runOptions) => executor.runStreaming(runOptions),
+        },
+    });
+
+    const results: RuleFixtureCaseResult[] = [];
+    for (const fixtureCase of cases) {
+        const setupError = await caseSetupError(fileSystem, fixtureDir, fixtureCase);
+        for (const ruleId of fixtureCase.ruleIds) {
+            const rule = rulesById.get(ruleId);
+            if (setupError !== undefined || rule === undefined) {
+                results.push({
+                    path: fixtureCase.path,
+                    ruleId,
+                    expect: fixtureCase.expect,
+                    pass: false,
+                    findings: [],
+                    processes: [],
+                    error: setupError ?? `rule "${ruleId}" is not an enabled rule in "${ruleFile}"`,
+                });
+                continue;
+            }
+
+            processes.length = 0;
+            const findings = (await engine.evaluate([rule], fixtureCase.workdir)).findings;
+            const recorded = [...processes];
+            const verdict = judgeCase(fixtureCase.expect, rule, findings, recorded);
+            results.push({
+                path: fixtureCase.path,
+                ruleId,
+                expect: fixtureCase.expect,
+                pass: verdict.pass,
+                findings,
+                processes: recorded,
+                ...(verdict.error !== undefined ? { error: verdict.error } : {}),
+            });
+        }
+    }
+
+    return { pass: results.every((result) => result.pass), skipped: false, cases: results };
+}
+
+/** Fail a case whose declared source or prepared workdir is absent. */
+async function caseSetupError(
+    fileSystem: FileSystem,
+    fixtureDir: string,
+    fixtureCase: RuleFixtureCase,
+): Promise<string | undefined> {
+    const sourceStat = await fileSystem.stat(joinPath(fixtureDir, fixtureCase.path));
+    if (sourceStat === null) return `case source "${fixtureCase.path}" is missing under "${fixtureDir}"`;
+    const workdirStat = await fileSystem.stat(fixtureCase.workdir);
+    if (workdirStat === null || !workdirStat.isDirectory()) {
+        return `case workdir "${fixtureCase.workdir}" is missing`;
+    }
+    return undefined;
+}
+
+/** Assert findings — and, for exit-code rules, the recorded process result — against the expectation. */
+function judgeCase(
+    expect: 'fire' | 'pass',
+    rule: ConstraintRule,
+    findings: ConstraintFinding[],
+    processes: ProcessResult[],
+): { pass: boolean; error?: string } {
+    const evaluatorErrors = findings.filter((finding) => finding.kind === 'error');
+    if (evaluatorErrors.length > 0) {
+        return { pass: false, error: `evaluator error: ${evaluatorErrors.map((f) => f.message).join('; ')}` };
+    }
+    const violations = findings.filter((finding) => finding.kind !== 'error');
+    if (rule.evaluator.type === 'exit-code') return judgeExitCodeCase(expect, rule, processes);
+    if (expect === 'fire') {
+        return violations.length > 0
+            ? { pass: true }
+            : { pass: false, error: 'expected fire but the rule reported no violation' };
+    }
+    return violations.length === 0
+        ? { pass: true }
+        : { pass: false, error: `expected pass but the rule reported ${violations.length} violation(s)` };
+}
+
+/** Judge an exit-code pair on the recorded normal exit versus the rule's configured `successCode`. */
+function judgeExitCodeCase(
+    expect: 'fire' | 'pass',
+    rule: ConstraintRule,
+    processes: ProcessResult[],
+): { pass: boolean; error?: string } {
+    const configured = rule.evaluator.config?.successCode;
+    const successCode = typeof configured === 'number' ? configured : 0;
+    const [execution] = processes;
+    if (execution === undefined) return { pass: false, error: 'exit-code: no process result recorded' };
+    const abnormal = execution.exitCode === null || (execution.outcome !== undefined && execution.outcome !== 'exit');
+    if (abnormal) {
+        const signal = execution.signal !== undefined ? ` (signal ${execution.signal})` : '';
+        return {
+            pass: false,
+            error: `exit-code: process did not complete normally (outcome ${execution.outcome ?? 'unknown'}${signal})${processDiagnostics(execution)}`,
+        };
+    }
+    // The evaluator reports a violation exactly when the exit differs from the
+    // configured success code, so the exit comparison is the assertion for both halves.
+    if (expect === 'fire') {
+        return execution.exitCode === successCode
+            ? {
+                  pass: false,
+                  error: `expected fire but exit ${execution.exitCode} equals successCode ${successCode}${processDiagnostics(execution)}`,
+              }
+            : { pass: true };
+    }
+    return execution.exitCode === successCode
+        ? { pass: true }
+        : {
+              pass: false,
+              error: `expected pass but exit ${execution.exitCode} differs from successCode ${successCode}${processDiagnostics(execution)}`,
+          };
+}
+
+/** Append the recorded streams to an exit-code failure diagnostic. */
+function processDiagnostics(execution: ProcessResult): string {
+    return `\nstdout: ${execution.stdout}\nstderr: ${execution.stderr}`;
+}

package/src/index.ts

@@ -11,6 +11,7 @@ export { isRipgrepCompatiblePattern } from './evaluators/ripgrep-evaluator';
 export type { RuleEngineEvents } from './events';
 export * from './fixers/fixers';
 export * from './fixers/test-stub-fixer';
+export * from './fixture-verifier';
 export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/bundled-rules';