@gobing-ai/ts-rule-engine 0.3.20 → 0.3.21

package/dist/fixers/fixers.d.ts

@@ -4,7 +4,7 @@
  *
  * @module rule-engine/fixers
  */
-import { NodeFileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type FileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { RuleEngineHost } from '../host/rule-engine-host';
 import type { Fix, FixMode, RuleFixerInput, RuleFixerProvider } from '../types';
 export type { EffectiveFix, RuleFixerInput, RuleFixerProvider } from '../types';
@@ -26,7 +26,7 @@ export declare function registerBuiltinFixers(host: RuleEngineHost, exec?: Proce
 /** Resolve a workdir-relative or absolute path to an absolute path. */
 export declare function resolveWorkdirPath(workdir: string, filePath: string): string;
 /** Apply byte-range fixes to files, optionally returning a dry-run diff only. */
-export declare function applyFixes(workdir: string, fixes: readonly Fix[], dryRun?: boolean, fs?: NodeFileSystem): Promise<FixApplicationResult>;
+export declare function applyFixes(workdir: string, fixes: readonly Fix[], dryRun?: boolean, fs?: FileSystem): Promise<FixApplicationResult>;
 /** Create a coarse unified diff string for dry-run CLI output. */
 export declare function createUnifiedDiff(filePath: string, before: string, after: string): string;
 /**
@@ -37,7 +37,6 @@ export declare function createUnifiedDiff(filePath: string, before: string, afte
  * replacement string (supports `$1` / `$&` back-references).
  */
 export declare class RegexFixerProvider implements RuleFixerProvider {
-    private readonly fs;
     /** Produce fixes for regex-evaluator findings. */
     createFixes({ rule, context, findings, fix }: RuleFixerInput): Promise<Fix[]>;
 }
@@ -49,7 +48,6 @@ export declare class RegexFixerProvider implements RuleFixerProvider {
  * `applyFixes` interprets a zero-length result spanning the full file as a deletion.
  */
 export declare class PathFixerProvider implements RuleFixerProvider {
-    private readonly fs;
     /** Produce deletion fixes for path-evaluator findings. */
     createFixes({ rule, context, findings, fix }: RuleFixerInput): Promise<Fix[]>;
 }

package/dist/fixers/fixers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixers.d.ts","sourceRoot":"","sources":["../../src/fixers/fixers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGH,cAAc,EACd,KAAK,eAAe,EAGvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAkB,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAIhG,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEhF,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAIjD,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAcxF;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,GAAG,EAAE,EACrB,MAAM,UAAQ,EACd,EAAE,GAAE,cAAqC,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CA0D/B;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzF;AA8BD;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IACxD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAE3C,kDAAkD;IAC5C,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAkCtF;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;IAE3C,0DAA0D;IACpD,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAoBtF"}
+{"version":3,"file":"fixers.d.ts","sourceRoot":"","sources":["../../src/fixers/fixers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEH,KAAK,UAAU,EAGf,KAAK,eAAe,EAGvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAkB,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAIhG,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEhF,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAIjD,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,IAAI,CAcxF;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,GAAG,EAAE,EACrB,MAAM,UAAQ,EACd,EAAE,GAAE,UAAmC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CA0D/B;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOzF;AA8BD;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IACxD,kDAAkD;IAC5C,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAoCtF;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACvD,0DAA0D;IACpD,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAoBtF"}

package/dist/fixers/fixers.js

@@ -4,7 +4,7 @@
  *
  * @module rule-engine/fixers
  */
-import { isAbsolutePath, joinPath, NodeFileSystem, relativePath, resolvePath, } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, isAbsolutePath, joinPath, relativePath, resolvePath, } from '@gobing-ai/ts-runtime';
 import { TestStubFixer } from './test-stub-fixer.js';
 /** Numeric ordering for fix authority; higher means more write authority. */
 export const FIX_MODE_RANK = {
@@ -29,7 +29,7 @@ export function resolveWorkdirPath(workdir, filePath) {
     return isAbsolutePath(filePath) ? filePath : joinPath(workdir, filePath);
 }
 /** Apply byte-range fixes to files, optionally returning a dry-run diff only. */
-export async function applyFixes(workdir, fixes, dryRun = false, fs = new NodeFileSystem()) {
+export async function applyFixes(workdir, fixes, dryRun = false, fs = createNodeFileSystem()) {
     const byFile = new Map();
     for (const fix of fixes) {
         const list = byFile.get(fix.filePath) ?? [];
@@ -71,7 +71,7 @@ export async function applyFixes(workdir, fixes, dryRun = false, fs = new NodeFi
         if (!dryRun) {
             const isFullDeletion = next.length === 0 && selected.applied.some((fix) => fix.start === 0 && fix.end === original.length);
             if (isFullDeletion) {
-                await fs.unlink(absPath);
+                await fs.deleteFile(absPath);
             }
             else {
                 await fs.writeFile(absPath, next);
@@ -122,9 +122,9 @@ function isValidRange(start, end, contentLength) {
  * replacement string (supports `$1` / `$&` back-references).
  */
 export class RegexFixerProvider {
-    fs = new NodeFileSystem();
     /** Produce fixes for regex-evaluator findings. */
     async createFixes({ rule, context, findings, fix }) {
+        const fs = context.fileSystem ?? createNodeFileSystem();
         if (fix.mode === 'none' || fix.replacement === undefined)
             return [];
         // After the guard above, mode is guaranteed to not be 'none'.
@@ -142,9 +142,9 @@ export class RegexFixerProvider {
             const absPath = resolveWorkdirPath(context.workdir, finding.filePath);
             if (!isInsideWorkdir(context.workdir, absPath) || finding.line == null)
                 continue;
-            if (!(await this.fs.exists(absPath)))
+            if (!(await fs.exists(absPath)))
                 continue;
-            const source = await this.fs.readFile(absPath);
+            const source = await fs.readFile(absPath);
             const line = getLineRange(source, finding.line);
             if (!line)
                 continue;
@@ -173,9 +173,9 @@ export class RegexFixerProvider {
  * `applyFixes` interprets a zero-length result spanning the full file as a deletion.
  */
 export class PathFixerProvider {
-    fs = new NodeFileSystem();
     /** Produce deletion fixes for path-evaluator findings. */
     async createFixes({ rule, context, findings, fix }) {
+        const fs = context.fileSystem ?? createNodeFileSystem();
         if (fix.mode !== 'auto' || rule.evaluator.config?.must !== 'absent')
             return [];
         const fixes = [];
@@ -183,11 +183,9 @@ export class PathFixerProvider {
             if (!finding.filePath)
                 continue;
             const absPath = resolveWorkdirPath(context.workdir, finding.filePath);
-            if (!isInsideWorkdir(context.workdir, absPath))
+            if (!(await fs.exists(absPath)))
                 continue;
-            if (!(await this.fs.exists(absPath)))
-                continue;
-            const content = await this.fs.readFile(absPath);
+            const content = await fs.readFile(absPath);
             fixes.push({
                 ruleId: rule.id,
                 filePath: finding.filePath,

package/dist/fixers/test-stub-fixer.d.ts

@@ -18,7 +18,7 @@ import type { RuleFixerInput, RuleFixerProvider } from './fixers';
 /** File-system seam for dependency injection in tests. */
 export interface TestStubFileSystem {
     /** Resolve to true if the path exists on disk. */
-    exists(path: string): Promise<boolean>;
+    exists(path: string): boolean | Promise<boolean>;
 }
 /** Real file-system implementation backed by the runtime FileSystem seam. */
 export declare const realFileSystem: TestStubFileSystem;

package/dist/fixers/test-stub-fixer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-stub-fixer.d.ts","sourceRoot":"","sources":["../../src/fixers/test-stub-fixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA4C,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElE,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IAC/B,kDAAkD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,6EAA6E;AAC7E,eAAO,MAAM,cAAc,EAAE,kBAAyC,CAAC;AAEvE,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAC5C;AAUD;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;gBAE5B,IAAI,EAAE,iBAAiB;IAOnC,wDAAwD;IAClD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAkD3D"}
+{"version":3,"file":"test-stub-fixer.d.ts","sourceRoot":"","sources":["../../src/fixers/test-stub-fixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElE,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IAC/B,kDAAkD;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAED,6EAA6E;AAC7E,eAAO,MAAM,cAAc,EAAE,kBAA2C,CAAC;AAEzE,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IACzD,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAC5C;AAUD;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,iBAAiB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;gBAE5B,IAAI,EAAE,iBAAiB;IAOnC,wDAAwD;IAClD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;CAkD3D"}

package/dist/fixers/test-stub-fixer.js

@@ -10,9 +10,9 @@
  *
  * @module rule-engine/fixers/test-stub-fixer
  */
-import { isAbsolutePath, joinPath, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, isAbsolutePath, joinPath } from '@gobing-ai/ts-runtime';
 /** Real file-system implementation backed by the runtime FileSystem seam. */
-export const realFileSystem = new NodeFileSystem();
+export const realFileSystem = createNodeFileSystem();
 /** Normalize a finding path to a repository-relative POSIX path, or return null when invalid. */
 function normalizeFindingPath(filePath) {
     if (!filePath || isAbsolutePath(filePath))

package/dist/host/bundled-rules.d.ts

@@ -13,7 +13,7 @@
  * which makes it robust to the build's `src`→`dist` layout shift. Returns `null`
  * if the directory is absent (e.g. a partial install that excluded the assets).
  */
-export declare function bundledRulesRoot(): string | null;
+export declare function bundledRulesRoot(): Promise<string | null>;
 /**
  * List the relative paths of every bundled rule asset (presets and category rule
  * files), each as a `/`-joined path relative to {@link bundledRulesRoot}.
@@ -22,5 +22,5 @@ export declare function bundledRulesRoot(): string | null;
  * (e.g. a per-user global rules directory) on first run. Returns an empty array
  * when no bundled directory is present.
  */
-export declare function listBundledRuleFiles(): string[];
+export declare function listBundledRuleFiles(): Promise<string[]>;
 //# sourceMappingURL=bundled-rules.d.ts.map

package/dist/host/bundled-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundled-rules.d.ts","sourceRoot":"","sources":["../../src/host/bundled-rules.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAoBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAI/C"}
+{"version":3,"file":"bundled-rules.d.ts","sourceRoot":"","sources":["../../src/host/bundled-rules.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO/D;AAiBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAI9D"}

package/dist/host/bundled-rules.js

@@ -1,4 +1,4 @@
-import { dirnamePath, joinPath, NodeSyncFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, dirnamePath, joinPath } from '@gobing-ai/ts-runtime';
 /**
  * Directory name holding the rule presets and category folders bundled with this
  * package. Lives at the package root (sibling to `dist/`), shipped via the
@@ -7,7 +7,8 @@ import { dirnamePath, joinPath, NodeSyncFileSystem } from '@gobing-ai/ts-runtime
 const BUNDLED_RULES_DIR = 'rules';
 /** Memoized result so the upward filesystem walk runs at most once per process. */
 let cachedRoot;
-const defaultFs = new NodeSyncFileSystem();
+/** In-flight resolution to prevent racing concurrent calls. */
+let resolving;
 /**
  * Resolve the absolute path to the rule presets bundled with
  * `@gobing-ai/ts-rule-engine`.
@@ -23,27 +24,30 @@ const defaultFs = new NodeSyncFileSystem();
  * which makes it robust to the build's `src`→`dist` layout shift. Returns `null`
  * if the directory is absent (e.g. a partial install that excluded the assets).
  */
-export function bundledRulesRoot() {
-    return bundledRulesRootWithFs(defaultFs);
-}
-function bundledRulesRootWithFs(fs) {
+export async function bundledRulesRoot() {
     if (cachedRoot !== undefined)
         return cachedRoot;
+    if (resolving !== undefined)
+        return resolving;
+    resolving = bundledRulesRootWithFs(createNodeFileSystem());
+    cachedRoot = await resolving;
+    resolving = undefined;
+    return cachedRoot;
+}
+async function bundledRulesRootWithFs(fs) {
     let dir = import.meta.dirname;
-    // Walk to filesystem root at most; the package root is only a few levels up.
     while (true) {
         const candidate = joinPath(dir, BUNDLED_RULES_DIR);
-        if (fs.stat(candidate)?.isDirectory() === true) {
-            cachedRoot = candidate;
-            return cachedRoot;
+        const st = await fs.stat(candidate);
+        if (st?.isDirectory() === true) {
+            return candidate;
         }
         const parent = dirnamePath(dir);
         if (parent === dir)
             break;
         dir = parent;
     }
-    cachedRoot = null;
-    return cachedRoot;
+    return null;
 }
 /**
  * List the relative paths of every bundled rule asset (presets and category rule
@@ -53,20 +57,21 @@ function bundledRulesRootWithFs(fs) {
  * (e.g. a per-user global rules directory) on first run. Returns an empty array
  * when no bundled directory is present.
  */
-export function listBundledRuleFiles() {
-    const root = bundledRulesRoot();
+export async function listBundledRuleFiles() {
+    const root = await bundledRulesRoot();
     if (root === null)
         return [];
-    return walk(defaultFs, root, '').sort();
+    return (await walk(createNodeFileSystem(), root, '')).sort();
 }
 /** Recursively collect YAML/JSON files under `dir`, returning paths relative to the walk origin. */
-function walk(fs, dir, relPrefix) {
+async function walk(fs, dir, relPrefix) {
     const acc = [];
-    for (const entry of fs.readDir(dir)) {
+    for (const entry of await fs.readDir(dir)) {
         const abs = joinPath(dir, entry);
         const rel = relPrefix.length > 0 ? `${relPrefix}/${entry}` : entry;
-        if (fs.stat(abs)?.isDirectory() === true) {
-            acc.push(...walk(fs, abs, rel));
+        const st = await fs.stat(abs);
+        if (st?.isDirectory() === true) {
+            acc.push(...(await walk(fs, abs, rel)));
         }
         else if (/\.(ya?ml|json)$/i.test(entry)) {
             acc.push(rel);

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { FileSystem } from '@gobing-ai/ts-runtime';
 import { z } from 'zod';
 /** Finding severity emitted by the rule engine. */
 export type RuleSeverity = 'error' | 'warning' | 'info';
@@ -141,6 +142,13 @@ export interface RuleContext {
     workdir: string;
     /** Rule being evaluated. */
     rule: ConstraintRule;
+    /**
+     * Filesystem port (ADR-011 union-return {@link FileSystem}); defaults to
+     * `createNodeFileSystem()` when constructed by `RuleEngine`. Evaluators and
+     * fixer providers MUST read files through this port rather than constructing
+     * their own filesystem instance, so a host can inject a virtual fs in tests.
+     */
+    fileSystem?: FileSystem;
 }
 /** Evaluator implementation contract. */
 export interface RuleEvaluator {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.3.20",
+    "version": "0.3.21",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -49,10 +49,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.3.20",
-        "@gobing-ai/ts-infra": "^0.3.20",
-        "@gobing-ai/ts-runtime": "^0.3.20",
-        "@gobing-ai/ts-db": "^0.3.20",
+        "@gobing-ai/ts-ai-runner": "^0.3.21",
+        "@gobing-ai/ts-infra": "^0.3.21",
+        "@gobing-ai/ts-runtime": "^0.3.21",
+        "@gobing-ai/ts-db": "^0.3.21",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/src/config/loader.ts

@@ -1,9 +1,10 @@
 import {
     basenamePath,
+    createNodeFileSystem,
     dirnamePath,
+    type FileSystem,
     joinPath,
     loadStructuredConfig,
-    NodeFileSystem,
     relativePath,
     resolvePath,
     SEP,
@@ -33,6 +34,8 @@ export interface RuleLoaderOptions {
     validateSchema?: boolean;
     /** Optional fetch implementation for remote HTTP(S) schema refs. */
     fetch?: (input: string) => Promise<Response>;
+    /** Filesystem for reading roots. Defaults to `createNodeFileSystem()`; inject to test without disk. */
+    fileSystem?: FileSystem;
 }
 
 /** Options for loading a single rule file directly from disk. */
@@ -67,7 +70,10 @@ interface MergedRoots {
  * the rest of a preset's categories from the lower-priority roots.
  */
 export async function loadPreset(name: string, options: RuleLoaderOptions): Promise<LoadedPreset> {
-    const merged = await buildMergedRoots(options.roots.map((root) => resolvePath(root)));
+    const merged = await buildMergedRoots(
+        options.roots.map((root) => resolvePath(root)),
+        options.fileSystem,
+    );
     const presetPath = findMergedPreset(merged, name);
     if (presetPath === null) return { rules: [], extensions: [] };
     const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath, options)) as PresetDefinition;
@@ -205,8 +211,10 @@ async function loadPresetEntry(
  * Roots are processed in the order supplied (highest priority first). The first
  * root to provide a given relative path owns that file; later roots are shadowed.
  */
-async function buildMergedRoots(roots: readonly string[]): Promise<MergedRoots> {
-    const fs = new NodeFileSystem();
+async function buildMergedRoots(
+    roots: readonly string[],
+    fs: FileSystem = createNodeFileSystem(),
+): Promise<MergedRoots> {
     const files = new Map<string, string>();
     const categories = new Set<string>();
     for (const root of roots) {
@@ -258,7 +266,7 @@ function mergedFilesInCategory(merged: MergedRoots, category: string): string[]
 }
 
 /** Recursively collect YAML/JSON file paths under a directory, skipping root-level `presets/`. */
-async function walkYamlFiles(fs: NodeFileSystem, dir: string, depth = 0): Promise<string[]> {
+async function walkYamlFiles(fs: FileSystem, dir: string, depth = 0): Promise<string[]> {
     const stat = await fs.stat(dir);
     if (stat === null || !stat.isDirectory()) return [];
     const acc: string[] = [];
@@ -276,7 +284,7 @@ async function walkYamlFiles(fs: NodeFileSystem, dir: string, depth = 0): Promis
 }
 
 /** List immediate subdirectory names of a root (excluding `presets`). */
-async function listImmediateDirs(fs: NodeFileSystem, dir: string): Promise<string[]> {
+async function listImmediateDirs(fs: FileSystem, dir: string): Promise<string[]> {
     const stat = await fs.stat(dir);
     if (stat === null || !stat.isDirectory()) return [];
     const dirs: string[] = [];

package/src/engine.ts

@@ -1,6 +1,6 @@
 import type { EventBus, Logger } from '@gobing-ai/ts-infra';
 import { addSpanEvent, getLogger, traceAsync } from '@gobing-ai/ts-infra';
-import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, type FileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { RuleEngineEvents } from './events';
 import {
     applyFixes as applyFixesImpl,
@@ -19,6 +19,12 @@ import { createFinding, SEVERITY_RANK } from './types';
 export interface RuleEngineOptions {
     /** Optional executor supplied to process-backed evaluators. */
     processExecutor?: ProcessExecutor;
+    /**
+     * Filesystem port (ADR-011 union-return {@link FileSystem}); defaults to
+     * `createNodeFileSystem()`. Threaded through {@link RuleContext} to every
+     * evaluator and fixer provider so hosts can inject a virtual fs in tests.
+     */
+    fileSystem?: FileSystem;
     /** Optional preconfigured host. */
     host?: RuleEngineHost;
     /** Optional event bus for structured run observability (R-A4). */
@@ -43,6 +49,7 @@ export class RuleEngine {
     private readonly persistence: RulePersistenceAdapter | undefined;
     private readonly runId: string;
     private readonly runMeta: Record<string, unknown> | undefined;
+    private readonly fileSystem: FileSystem;
 
     constructor(options: RuleEngineOptions = {}) {
         this.host = options.host ?? new RuleEngineHost();
@@ -53,6 +60,7 @@ export class RuleEngine {
         this.persistence = options.persistence;
         this.runId = options.runId ?? crypto.randomUUID();
         this.runMeta = options.runMeta;
+        this.fileSystem = options.fileSystem ?? createNodeFileSystem();
     }
 
     /** Register or replace an evaluator. */
@@ -155,7 +163,7 @@ export class RuleEngine {
                     try {
                         const result = await this.host.evaluators
                             .get(rule.evaluator.type)
-                            .evaluate(rule, { rule, workdir });
+                            .evaluate(rule, { rule, workdir, fileSystem: this.fileSystem });
                         ruleFindings = result.findings;
                         ruleEvalFixes = result.fixes;
                     } catch (error) {
@@ -210,7 +218,7 @@ export class RuleEngine {
                             };
                             const providerFixes = await provider.createFixes({
                                 rule,
-                                context: { rule, workdir },
+                                context: { rule, workdir, fileSystem: this.fileSystem },
                                 findings: ruleFindings,
                                 fix: effectiveFix,
                             });
@@ -272,7 +280,7 @@ export class RuleEngine {
      * @returns Application details and optional diff.
      */
     async applyFixes(workdir: string, fixes: readonly Fix[], dryRun = false): Promise<FixApplicationResult> {
-        return applyFixesImpl(workdir, fixes, dryRun);
+        return applyFixesImpl(workdir, fixes, dryRun, this.fileSystem);
     }
 }
 

package/src/evaluators/config-access.ts

@@ -0,0 +1,76 @@
+/**
+ * Typed accessors for a rule's `evaluator.config` bag and inline-flag parsing.
+ *
+ * Required keys fail loudly (throw, naming the evaluator) so misconfigured rules
+ * surface at evaluation time rather than silently scanning the wrong set.
+ */
+
+/** Return the value as a `string[]` when every item is a string, otherwise undefined. */
+export function stringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
+}
+
+/** Optional accessor context — names the evaluator in "required config" errors for rule authors. */
+export interface ConfigAccessorOptions {
+    /** Evaluator name surfaced in the error, e.g. `"regex evaluator requires string config \"pattern\""`. */
+    evaluator?: string;
+}
+
+function requiredConfigError(kind: string, key: string, evaluator?: string): Error {
+    const who = evaluator !== undefined ? `${evaluator} evaluator` : 'evaluator';
+    return new Error(`${who} requires ${kind} config "${key}"`);
+}
+
+/**
+ * Read a string entry from a rule's evaluator config. Returns the value when it is a string,
+ * the `fallback` when one is supplied, otherwise throws — so required keys fail loudly.
+ */
+export function configString(
+    config: Record<string, unknown>,
+    key: string,
+    fallback?: string,
+    options: ConfigAccessorOptions = {},
+): string {
+    const value = config[key];
+    if (typeof value === 'string') return value;
+    if (fallback !== undefined) return fallback;
+    throw requiredConfigError('string', key, options.evaluator);
+}
+
+/**
+ * Read a string-array entry from a rule's evaluator config. A bare string is coerced to a
+ * single-element array. Returns the `fallback` when one is supplied and the value is absent;
+ * otherwise throws — so required keys fail loudly.
+ */
+export function configArray(
+    config: Record<string, unknown>,
+    key: string,
+    fallback?: string[],
+    options: ConfigAccessorOptions = {},
+): string[] {
+    const value = config[key];
+    if (Array.isArray(value) && value.every((item) => typeof item === 'string')) return value as string[];
+    if (typeof value === 'string') return [value];
+    if (fallback !== undefined) return fallback;
+    throw requiredConfigError('string[]', key, options.evaluator);
+}
+
+/** Read a finite-number entry from a rule's evaluator config, falling back when absent or invalid. */
+export function configNumber(config: Record<string, unknown>, key: string, fallback: number): number {
+    const value = config[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * Split a leading ripgrep/PCRE-style `(?flags)` inline group off a regex source.
+ *
+ * Returns the JS-relevant flags found in the group (filtered to `imsu`) and the
+ * remaining source with the group removed. When no leading group is present, returns
+ * empty flags and the source unchanged. Shared by evaluators that accept inline flags.
+ */
+export function parseInlineFlags(source: string): { flags: string; rest: string } {
+    const match = /^\(\?([a-z]+)\)/.exec(source);
+    if (!match) return { flags: '', rest: source };
+    const flags = [...(match[1] ?? '')].filter((flag) => 'imsu'.includes(flag)).join('');
+    return { flags, rest: source.slice(match[0].length) };
+}

package/src/evaluators/coverage-gate-evaluator.ts

@@ -1,4 +1,4 @@
-import { isAbsolutePath, NodeFileSystem, relativePath, resolvePath } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, isAbsolutePath, relativePath, resolvePath } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -44,20 +44,20 @@ interface CoverageGateConfig {
  * error, so the gate degrades gracefully when coverage was not generated.
  */
 export class CoverageGateEvaluator implements RuleEvaluator {
-    private readonly fs: NodeFileSystem;
-
+    /** Evaluate per-file coverage against the configured threshold. */
+    // Explicit constructor avoids a V8 function-coverage phantom (synthesized default ctor).
     constructor() {
-        this.fs = new NodeFileSystem();
+        // no-op; all state comes from evaluate() context
     }
 
-    /** Evaluate per-file coverage against the configured threshold. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const fs = context.fileSystem ?? createNodeFileSystem();
         const config = (rule.evaluator.config ?? {}) as CoverageGateConfig;
         const lcovPath = config.lcovPath
             ? resolvePath(context.workdir, config.lcovPath)
             : resolvePath(context.workdir, 'coverage', 'lcov.info');
 
-        if (!(await this.fs.exists(lcovPath))) {
+        if (!(await fs.exists(lcovPath))) {
             return {
                 findings: [
                     createFinding(rule, 'No lcov file found — coverage not generated. Skipping gate.', lcovPath, {
@@ -67,8 +67,7 @@ export class CoverageGateEvaluator implements RuleEvaluator {
                 fixes: [],
             };
         }
-
-        const coverage = parseLcov(await this.fs.readFile(lcovPath));
+        const coverage = parseLcov(await fs.readFile(lcovPath));
         const threshold = config.threshold ?? 90;
         const exemptions = new Map((config.exemptions ?? []).map((entry) => [entry.path, entry]));
         const findings = [];