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

package/src/evaluators/file-discovery.ts

@@ -0,0 +1,132 @@
+/**
+ * File discovery and reading for evaluators — the shared scaffolding behind the
+ * line-scanning rules. Owns directory walks, scope filtering, and per-file reads
+ * so each evaluator is left with only its own matcher.
+ */
+
+import {
+    createNodeFileSystem,
+    dirnamePath,
+    type FileSystem,
+    relativePath,
+    resolvePath,
+    walkDir,
+} from '@gobing-ai/ts-runtime';
+import { matchesAny, matchesGlob } from './glob-match';
+
+/** Options for source-file discovery. */
+export interface SourceDiscoveryOptions {
+    /** Working directory. */
+    workdir: string;
+    /** Include path fragments or suffixes. */
+    include?: string[];
+    /** Exclude path fragments. */
+    exclude?: string[];
+    /** Filesystem adapter. */
+    fs?: FileSystem;
+}
+
+/**
+ * Directory names pruned from every file walk — heavy or generated trees that no rule
+ * should scan. Shared so subprocess-backed evaluators (e.g. `sg`) can forward the same
+ * skip-list to the external tool instead of relying on each rule to remember it.
+ */
+export const DEFAULT_EXCLUDES = new Set(['.git', 'node_modules', 'dist', '.coverage', '.astro', '.wrangler']);
+
+/** Resolve source files for evaluators using conservative path-fragment matching. */
+export async function discoverFiles(options: SourceDiscoveryOptions): Promise<string[]> {
+    const fs = options.fs ?? createNodeFileSystem();
+    const allFiles = await walkDir(options.workdir, fs, DEFAULT_EXCLUDES);
+    return allFiles
+        .map((path) => relativePath(options.workdir, path))
+        .filter((path) => !path.split('/').some((segment) => DEFAULT_EXCLUDES.has(segment)))
+        .filter(
+            (path) =>
+                matchesAny(path, options.include) &&
+                (options.exclude === undefined || !matchesAny(path, options.exclude)),
+        );
+}
+
+/** Read a file from a workdir-relative path. */
+export async function readWorkdirFile(workdir: string, filePath: string, fs = createNodeFileSystem()): Promise<string> {
+    return await fs.readFile(resolvePath(workdir, filePath));
+}
+
+/** A discovered in-scope file paired with its contents. */
+export interface ScannedFile {
+    /** Workdir-relative path. */
+    readonly file: string;
+    /** Full file contents. */
+    readonly content: string;
+}
+
+/** How `scanFiles` matches `include` / `exclude` against discovered paths. */
+export type ScanMatchMode = 'loose' | 'glob';
+
+/** Options for {@link scanFiles}. */
+export interface ScanFilesOptions {
+    /** Working directory to walk. */
+    workdir: string;
+    /** Include patterns; semantics depend on `matchMode`. Undefined/empty = all files. */
+    include?: string[];
+    /** Exclude patterns; semantics depend on `matchMode`. */
+    exclude?: string[];
+    /**
+     * Scope matching policy:
+     * - `loose` — substring/suffix fragments via {@link matchesAny} (back-compat for
+     *   evaluators that historically accepted bare fragments like `.ts` or `src/`).
+     * - `glob` — anchored `**`/`*` globs via {@link matchesGlob}.
+     *
+     * The two are NOT interchangeable: a bare `src/` matches different sets under each.
+     * Each evaluator declares the mode that preserves its existing behavior.
+     */
+    matchMode: ScanMatchMode;
+    /** Filesystem adapter. */
+    fs?: FileSystem;
+}
+
+/**
+ * Discover in-scope files and read each once — the shared scaffolding behind the
+ * line-scanning evaluators. Owns discovery, scope filtering (per `matchMode`), and
+ * reads, so each evaluator is left with only its own matcher.
+ *
+ * Scope is a parameter, not assumed one-per-rule: callers that scan under several
+ * scopes (e.g. import boundaries) pass no `include` here and apply their own globs to
+ * the returned paths.
+ */
+export async function scanFiles(options: ScanFilesOptions): Promise<ScannedFile[]> {
+    const fs = options.fs ?? createNodeFileSystem();
+    const files =
+        options.matchMode === 'loose'
+            ? await discoverFiles({ workdir: options.workdir, include: options.include, exclude: options.exclude, fs })
+            : await discoverFilesByGlob(options.workdir, options.include, options.exclude, fs);
+    const scanned: ScannedFile[] = [];
+    for (const file of files) {
+        scanned.push({ file, content: await readWorkdirFile(options.workdir, file, fs) });
+    }
+    return scanned;
+}
+
+/** Discover files then filter with anchored globs (strict mode for {@link scanFiles}). */
+async function discoverFilesByGlob(
+    workdir: string,
+    include: string[] | undefined,
+    exclude: string[] | undefined,
+    fs: FileSystem,
+): Promise<string[]> {
+    const all = await discoverFiles({ workdir, fs });
+    return all
+        .filter((file) => include === undefined || include.length === 0 || include.some((g) => matchesGlob(file, g)))
+        .filter((file) => exclude === undefined || !exclude.some((g) => matchesGlob(file, g)));
+}
+
+/** Ensure a path is workdir-relative for findings. */
+export function relativeToWorkdir(workdir: string, path: string): string {
+    return relativePath(workdir, resolvePath(path));
+}
+
+/** Return parent directory for a workdir-relative path. */
+export function relativeParent(path: string): string {
+    const parent = dirnamePath(path);
+    return parent === '.' ? '' : parent;
+}

package/src/evaluators/file-utils.ts

@@ -1,263 +1,34 @@
-import {
-    dirnamePath,
-    type LegacyFileSystem as FileSystem,
-    NodeFileSystem,
-    relativePath,
-    resolvePath,
-    walkDir,
-} from '@gobing-ai/ts-runtime';
-
-/** Options for source-file discovery. */
-export interface SourceDiscoveryOptions {
-    /** Working directory. */
-    workdir: string;
-    /** Include path fragments or suffixes. */
-    include?: string[];
-    /** Exclude path fragments. */
-    exclude?: string[];
-    /** Filesystem adapter. */
-    fs?: FileSystem;
-}
-
-/**
- * Directory names pruned from every file walk — heavy or generated trees that no rule
- * should scan. Shared so subprocess-backed evaluators (e.g. `sg`) can forward the same
- * skip-list to the external tool instead of relying on each rule to remember it.
- */
-export const DEFAULT_EXCLUDES = new Set(['.git', 'node_modules', 'dist', '.coverage', '.astro', '.wrangler']);
-
-/** Resolve source files for evaluators using conservative path-fragment matching. */
-export async function discoverFiles(options: SourceDiscoveryOptions): Promise<string[]> {
-    const fs = options.fs ?? new NodeFileSystem();
-    const allFiles = await walkDir(options.workdir, fs, DEFAULT_EXCLUDES);
-    return allFiles
-        .map((path) => relativePath(options.workdir, path))
-        .filter((path) => !path.split('/').some((segment) => DEFAULT_EXCLUDES.has(segment)))
-        .filter(
-            (path) =>
-                matchesAny(path, options.include) &&
-                (options.exclude === undefined || !matchesAny(path, options.exclude)),
-        );
-}
-
-/** Read a file from a workdir-relative path. */
-export async function readWorkdirFile(workdir: string, filePath: string, fs = new NodeFileSystem()): Promise<string> {
-    return await fs.readFile(resolvePath(workdir, filePath));
-}
-
-/** A discovered in-scope file paired with its contents. */
-export interface ScannedFile {
-    /** Workdir-relative path. */
-    readonly file: string;
-    /** Full file contents. */
-    readonly content: string;
-}
-
-/** How `scanFiles` matches `include` / `exclude` against discovered paths. */
-export type ScanMatchMode = 'loose' | 'glob';
-
-/** Options for {@link scanFiles}. */
-export interface ScanFilesOptions {
-    /** Working directory to walk. */
-    workdir: string;
-    /** Include patterns; semantics depend on `matchMode`. Undefined/empty = all files. */
-    include?: string[];
-    /** Exclude patterns; semantics depend on `matchMode`. */
-    exclude?: string[];
-    /**
-     * Scope matching policy:
-     * - `loose` — substring/suffix fragments via {@link matchesAny} (back-compat for
-     *   evaluators that historically accepted bare fragments like `.ts` or `src/`).
-     * - `glob` — anchored `**`/`*` globs via {@link matchesGlob}.
-     *
-     * The two are NOT interchangeable: a bare `src/` matches different sets under each.
-     * Each evaluator declares the mode that preserves its existing behavior.
-     */
-    matchMode: ScanMatchMode;
-    /** Filesystem adapter. */
-    fs?: FileSystem;
-}
-
 /**
- * Discover in-scope files and read each once — the shared scaffolding behind the
- * line-scanning evaluators. Owns discovery, scope filtering (per `matchMode`), and
- * reads, so each evaluator is left with only its own matcher.
+ * Aggregating barrel for evaluator file utilities — kept so existing imports
+ * (`./file-utils`) stay stable. The implementation now lives in three focused
+ * modules by concern:
  *
- * Scope is a parameter, not assumed one-per-rule: callers that scan under several
- * scopes (e.g. import boundaries) pass no `include` here and apply their own globs to
- * the returned paths.
- */
-export async function scanFiles(options: ScanFilesOptions): Promise<ScannedFile[]> {
-    const fs = options.fs ?? new NodeFileSystem();
-    const files =
-        options.matchMode === 'loose'
-            ? await discoverFiles({ workdir: options.workdir, include: options.include, exclude: options.exclude, fs })
-            : await discoverFilesByGlob(options.workdir, options.include, options.exclude, fs);
-    const scanned: ScannedFile[] = [];
-    for (const file of files) {
-        scanned.push({ file, content: await readWorkdirFile(options.workdir, file, fs) });
-    }
-    return scanned;
-}
-
-/** Discover files then filter with anchored globs (strict mode for {@link scanFiles}). */
-async function discoverFilesByGlob(
-    workdir: string,
-    include: string[] | undefined,
-    exclude: string[] | undefined,
-    fs: FileSystem,
-): Promise<string[]> {
-    const all = await discoverFiles({ workdir, fs });
-    return all
-        .filter((file) => include === undefined || include.length === 0 || include.some((g) => matchesGlob(file, g)))
-        .filter((file) => exclude === undefined || !exclude.some((g) => matchesGlob(file, g)));
-}
-
-/** Ensure a path is workdir-relative for findings. */
-export function relativeToWorkdir(workdir: string, path: string): string {
-    return relativePath(workdir, resolvePath(path));
-}
-
-/** Return parent directory for a workdir-relative path. */
-export function relativeParent(path: string): string {
-    const parent = dirnamePath(path);
-    return parent === '.' ? '' : parent;
-}
-
-/**
- * Return true when a path matches any supplied pattern.
- *
- * Each pattern is matched in two passes, most-specific first:
- *  1. If it contains a glob metachar (`*`), try anchored {@link matchesGlob} —
- *     so `packages/**\/*.ts` resolves segment-by-segment instead of collapsing
- *     to a bare fragment (the latter silently matched nothing, leaving every
- *     glob-scoped loose-mode rule scanning zero files).
- *  2. Otherwise (or if the glob did not match), fall back to the legacy
- *     fragment/suffix substring test, where stars are stripped — preserving
- *     bare fragments like `.ts`, `src/`, `/tests/` that loose-mode evaluators
- *     have always accepted, and keeping unanchored patterns like `*.ts`
- *     (→ suffix `.ts`) matching nested paths.
- */
-export function matchesAny(path: string, patterns: string[] | undefined): boolean {
-    if (patterns === undefined || patterns.length === 0) return true;
-    const normalizedPath = path.replaceAll('\\', '/');
-    return patterns.some((pattern) => {
-        const normalized = pattern.replaceAll('\\', '/');
-        if (normalized.includes('*') && matchesGlob(normalizedPath, normalized)) return true;
-        const clean = normalized.replaceAll('**/', '').replaceAll('*', '');
-        return clean.length === 0 || normalizedPath.includes(clean) || normalizedPath.endsWith(clean);
-    });
-}
-
-/**
- * Segment-aware glob matching with `**` (any depth) and `*` (single segment).
+ * - `./glob-match`      — path-pattern matching (`matchesAny`, `matchesGlob`, `escapeRegExp`)
+ * - `./file-discovery`  — directory walks, scope filtering, per-file reads
+ * - `./config-access`   — typed `evaluator.config` accessors + inline-flag parsing
  *
- * Stricter than {@link matchesAny}: it anchors the whole path, so `apps/**` does
- * not match `vendor/apps/x`. Used by evaluators that enforce path policies
- * (coverage scoping, test-file location) where a loose match would change findings.
- */
-export function matchesGlob(path: string, pattern: string): boolean {
-    const normalized = path.replaceAll('\\', '/');
-    if (pattern.startsWith('**/')) {
-        const suffix = pattern.slice(3);
-        if (suffix.indexOf('*') === -1) {
-            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
-        }
-    }
-    if (pattern === normalized) return true;
-    return matchSegments(normalized.split('/'), pattern.split('/'), 0, 0);
-}
-
-/** Recursive segment-level glob matcher backing {@link matchesGlob}. */
-function matchSegments(file: string[], pattern: string[], fi: number, pi: number): boolean {
-    if (pi >= pattern.length) return fi >= file.length;
-    if (fi >= file.length) return pattern.slice(pi).every((segment) => segment === '**');
-    const pat = pattern[pi] ?? '';
-    if (pat === '**') {
-        return matchSegments(file, pattern, fi, pi + 1) || matchSegments(file, pattern, fi + 1, pi);
-    }
-    if (!matchSegment(file[fi] ?? '', pat)) return false;
-    return matchSegments(file, pattern, fi + 1, pi + 1);
-}
-
-/** Match one path segment against a pattern segment where `*` matches any run of non-`/` chars. */
-function matchSegment(segment: string, pattern: string): boolean {
-    if (pattern.indexOf('*') === -1) return segment === pattern;
-    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
-    return new RegExp(`^${escaped}$`).test(segment);
-}
-
-/** Escape a string for safe literal use inside a `RegExp` source. */
-export function escapeRegExp(value: string): string {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/** 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.
+ * Prefer importing from the specific module in new code; this barrel exists for
+ * back-compat and as a convenience surface.
  */
-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) };
-}
+export {
+    type ConfigAccessorOptions,
+    configArray,
+    configNumber,
+    configString,
+    parseInlineFlags,
+    stringArray,
+} from './config-access';
+export {
+    DEFAULT_EXCLUDES,
+    discoverFiles,
+    readWorkdirFile,
+    relativeParent,
+    relativeToWorkdir,
+    type ScanFilesOptions,
+    type ScanMatchMode,
+    type ScannedFile,
+    type SourceDiscoveryOptions,
+    scanFiles,
+} from './file-discovery';
+export { escapeRegExp, matchesAny, matchesGlob } from './glob-match';

package/src/evaluators/forbidden-import-evaluator.ts

@@ -1,3 +1,4 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -36,6 +37,11 @@ interface ScanEntry {
  */
 export class ForbiddenImportEvaluator implements RuleEvaluator {
     /** Evaluate import/usage against the configured forbidden set. */
+    // Explicit constructor avoids a V8 function-coverage phantom (synthesized default ctor).
+    constructor() {
+        // no-op; all state comes from evaluate() context
+    }
+
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         const config = rule.evaluator.config ?? {};
         return Array.isArray(config.forbidden)
@@ -50,11 +56,13 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         config: Record<string, unknown>,
     ): Promise<RuleEvaluationResult> {
         const forbidden = configArray(config, 'patterns', undefined, { evaluator: 'forbidden-import' });
+        const fs = context.fileSystem ?? createNodeFileSystem();
         const files = await scanFiles({
             workdir: context.workdir,
             include: rule.include ?? ['.ts', '.tsx', '.js', '.jsx'],
             exclude: rule.exclude,
             matchMode: 'loose',
+            fs,
         });
         const findings = [];
         for (const { file, content } of files) {
@@ -89,10 +97,10 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         }
         const exclude = stringArray(scope?.exclude) ?? [];
         const entries = (config.forbidden as ForbiddenEntry[]).map(compileEntry);
+        const fs = context.fileSystem ?? createNodeFileSystem();
 
         // Anchored `**`-glob scoping: scanFiles' 'glob' mode applies matchesGlob precisely.
-        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'glob' });
-
+        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'glob', fs });
         const findings = [];
         for (const { file, content } of files) {
             const lines = content.split('\n');

package/src/evaluators/glob-match.ts

@@ -0,0 +1,76 @@
+/**
+ * Path-pattern matching for evaluators — two deliberately distinct algorithms.
+ *
+ * {@link matchesAny} is the loose, back-compatible fragment/suffix matcher;
+ * {@link matchesGlob} is the strict, anchored segment-aware glob matcher. They
+ * are NOT interchangeable (a bare `src/` matches different sets under each), so
+ * each evaluator picks the one that preserves its existing behavior.
+ */
+
+/**
+ * Return true when a path matches any supplied pattern.
+ *
+ * Each pattern is matched in two passes, most-specific first:
+ *  1. If it contains a glob metachar (`*`), try anchored {@link matchesGlob} —
+ *     so `packages/**\/*.ts` resolves segment-by-segment instead of collapsing
+ *     to a bare fragment (the latter silently matched nothing, leaving every
+ *     glob-scoped loose-mode rule scanning zero files).
+ *  2. Otherwise (or if the glob did not match), fall back to the legacy
+ *     fragment/suffix substring test, where stars are stripped — preserving
+ *     bare fragments like `.ts`, `src/`, `/tests/` that loose-mode evaluators
+ *     have always accepted, and keeping unanchored patterns like `*.ts`
+ *     (→ suffix `.ts`) matching nested paths.
+ */
+export function matchesAny(path: string, patterns: string[] | undefined): boolean {
+    if (patterns === undefined || patterns.length === 0) return true;
+    const normalizedPath = path.replaceAll('\\', '/');
+    return patterns.some((pattern) => {
+        const normalized = pattern.replaceAll('\\', '/');
+        if (normalized.includes('*') && matchesGlob(normalizedPath, normalized)) return true;
+        const clean = normalized.replaceAll('**/', '').replaceAll('*', '');
+        return clean.length === 0 || normalizedPath.includes(clean) || normalizedPath.endsWith(clean);
+    });
+}
+
+/**
+ * Segment-aware glob matching with `**` (any depth) and `*` (single segment).
+ *
+ * Stricter than {@link matchesAny}: it anchors the whole path, so `apps/**` does
+ * not match `vendor/apps/x`. Used by evaluators that enforce path policies
+ * (coverage scoping, test-file location) where a loose match would change findings.
+ */
+export function matchesGlob(path: string, pattern: string): boolean {
+    const normalized = path.replaceAll('\\', '/');
+    if (pattern.startsWith('**/')) {
+        const suffix = pattern.slice(3);
+        if (suffix.indexOf('*') === -1) {
+            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
+        }
+    }
+    if (pattern === normalized) return true;
+    return matchSegments(normalized.split('/'), pattern.split('/'), 0, 0);
+}
+
+/** Recursive segment-level glob matcher backing {@link matchesGlob}. */
+function matchSegments(file: string[], pattern: string[], fi: number, pi: number): boolean {
+    if (pi >= pattern.length) return fi >= file.length;
+    if (fi >= file.length) return pattern.slice(pi).every((segment) => segment === '**');
+    const pat = pattern[pi] ?? '';
+    if (pat === '**') {
+        return matchSegments(file, pattern, fi, pi + 1) || matchSegments(file, pattern, fi + 1, pi);
+    }
+    if (!matchSegment(file[fi] ?? '', pat)) return false;
+    return matchSegments(file, pattern, fi + 1, pi + 1);
+}
+
+/** Match one path segment against a pattern segment where `*` matches any run of non-`/` chars. */
+function matchSegment(segment: string, pattern: string): boolean {
+    if (pattern.indexOf('*') === -1) return segment === pattern;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
+    return new RegExp(`^${escaped}$`).test(segment);
+}
+
+/** Escape a string for safe literal use inside a `RegExp` source. */
+export function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/evaluators/import-boundary-evaluator.ts

@@ -1,3 +1,4 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -44,7 +45,8 @@ export class ImportBoundaryEvaluator implements RuleEvaluator {
         const compiled = boundaries.map((boundary, index) => compileBoundary(boundary, index));
 
         // Scan all files once (read up front); apply each boundary's globs in-memory below.
-        const allFiles = await scanFiles({ workdir: context.workdir, matchMode: 'glob' });
+        const fs = context.fileSystem ?? createNodeFileSystem();
+        const allFiles = await scanFiles({ workdir: context.workdir, matchMode: 'glob', fs });
 
         const findings = [];
         for (const boundary of compiled) {

package/src/evaluators/path-evaluator.ts

@@ -1,4 +1,4 @@
-import { joinPath, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, joinPath } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -19,13 +19,12 @@ import { configArray, configString, discoverFiles, matchesGlob } from './file-ut
  *   exact paths relative to the workdir (`require` = must exist, `forbid` = must not).
  */
 export class PathEvaluator implements RuleEvaluator {
-    private readonly fs: NodeFileSystem;
-
+    /** Evaluate required or forbidden paths in either config form. */
+    // 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 required or forbidden paths in either config form. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         const config = rule.evaluator.config ?? {};
         const must = config.must;
@@ -43,7 +42,8 @@ export class PathEvaluator implements RuleEvaluator {
     ): Promise<RuleEvaluationResult> {
         const include = rule.include ?? ['**'];
         const exclude = rule.exclude ?? [];
-        const files = await discoverFiles({ workdir: context.workdir });
+        const fs = context.fileSystem ?? createNodeFileSystem();
+        const files = await discoverFiles({ workdir: context.workdir, fs });
         const inScope = (file: string) =>
             include.some((glob) => matchesGlob(file, glob)) && !exclude.some((glob) => matchesGlob(file, glob));
         const findings = [];
@@ -83,9 +83,10 @@ export class PathEvaluator implements RuleEvaluator {
     ): Promise<RuleEvaluationResult> {
         const paths = configArray(config, 'paths', undefined, { evaluator: 'path' });
         const mode = configString(config, 'mode', 'require');
+        const fs = context.fileSystem ?? createNodeFileSystem();
         const findings = [];
         for (const path of paths) {
-            const exists = await this.fs.exists(joinPath(context.workdir, path));
+            const exists = await fs.exists(joinPath(context.workdir, path));
             if (mode === 'forbid' && exists) {
                 findings.push(createFinding(rule, `Forbidden path exists: ${path}`, path, { code: 'path:forbidden' }));
             }

package/src/evaluators/regex-evaluator.ts

@@ -1,3 +1,4 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -31,11 +32,13 @@ export class RegexEvaluator implements RuleEvaluator {
         );
         const mode = configString(config, 'mode', 'forbid');
         const regex = new RegExp(pattern, flags);
+        const fs = context.fileSystem ?? createNodeFileSystem();
         const files = await scanFiles({
             workdir: context.workdir,
             include: rule.include,
             exclude: rule.exclude,
             matchMode: 'loose',
+            fs,
         });
         const findings = [];
 

package/src/evaluators/schema-artifact-evaluator.ts

@@ -1,4 +1,4 @@
-import { joinPath, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, joinPath } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -22,14 +22,14 @@ import { stringArray } from './file-utils';
  * - `requireRequiredArray` — enforce that `required` is a non-empty array (default: `false`).
  */
 export class SchemaArtifactEvaluator implements RuleEvaluator {
-    private readonly fs: NodeFileSystem;
-
+    /** Evaluate the configured JSON schema artifact. */
+    // 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 the configured JSON schema artifact. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const fs = context.fileSystem ?? createNodeFileSystem();
         const config = rule.evaluator.config ?? {};
         const file = config.file;
         if (typeof file !== 'string' || file.length === 0) {
@@ -41,9 +41,10 @@ export class SchemaArtifactEvaluator implements RuleEvaluator {
         const requiredDefs = stringArray(config.requiredDefs);
         const requireRequiredArray = config.requireRequiredArray === true;
 
-        // Check existence.
         const absolutePath = joinPath(context.workdir, file);
-        const exists = await this.fs.exists(absolutePath);
+
+        // Check existence.
+        const exists = await fs.exists(absolutePath);
         if (!exists) {
             return {
                 findings: [
@@ -58,7 +59,7 @@ export class SchemaArtifactEvaluator implements RuleEvaluator {
         // Read and parse.
         let schema: Record<string, unknown>;
         try {
-            const raw = await this.fs.readFile(absolutePath);
+            const raw = await fs.readFile(absolutePath);
             schema = JSON.parse(raw) as Record<string, unknown>;
         } catch (err) {
             return {