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

package/src/evaluators/secrets-scanner-evaluator.ts

@@ -1,3 +1,4 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -61,7 +62,8 @@ export class SecretsScannerEvaluator implements RuleEvaluator {
         const scope = config.scope as { include?: unknown; exclude?: unknown } | undefined;
         const include = stringArray(scope?.include) ?? rule.include;
         const exclude = stringArray(scope?.exclude) ?? rule.exclude;
-        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'loose' });
+        const fs = context.fileSystem ?? createNodeFileSystem();
+        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'loose', fs });
 
         const findings = [];
         for (const { file, content } of files) {

package/src/evaluators/test-location-evaluator.ts

@@ -1,6 +1,8 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import type { CapabilityRegistry } from '@gobing-ai/ts-runtime/extension';
 import { type TestPathResolver, TypeScriptTestPathResolver } from '../resolvers/test-path-resolver';
 import {
+    type ConstraintFinding,
     type ConstraintRule,
     createFinding,
     type RuleContext,
@@ -45,8 +47,9 @@ export class TestLocationEvaluator implements RuleEvaluator {
         const forbid = config.forbid ?? [];
         const include = rule.include ?? ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'];
         const exclude = rule.exclude ?? [];
-        const allFiles = await discoverFiles({ workdir: context.workdir });
-        const findings = [];
+        const findings: ConstraintFinding[] = [];
+        const fs = context.fileSystem ?? createNodeFileSystem();
+        const allFiles = await discoverFiles({ workdir: context.workdir, fs });
 
         const testPatterns = config.requireCorrespondingTest ? [expected] : include;
         const testFiles = allFiles.filter((file) => testPatterns.some((pattern) => matchesGlob(file, pattern)));

package/src/evaluators/tsdoc-export-evaluator.ts

@@ -1,3 +1,4 @@
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -54,7 +55,8 @@ export class TsdocExportEvaluator implements RuleEvaluator {
         const exclude = rule.exclude ?? [];
         // Single, strict glob scoping — collapses the previous double-scoping (loose
         // discoverFiles prefilter + per-file matchesGlob) into one pass.
-        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'glob' });
+        const fs = context.fileSystem ?? createNodeFileSystem();
+        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'glob', fs });
 
         const findings = [];
         for (const { file, content } of files) {
@@ -94,19 +96,31 @@ function findExports(lines: string[], requested: ReadonlySet<ExportKind>): Expor
 /**
  * True when a JSDoc block precedes a declaration.
  *
- * Skips decorator lines (`@Component(...)`) so a documented but decorated class
- * is not falsely flagged, then checks whether the nearest preceding non-decorator
- * line closes (or is) a JSDoc comment.
+ * Walks backward from the line before the declaration, skipping blank lines,
+ * JSDoc body lines (`* …`), and decorator / JSDoc-tag lines (`@…`), then
+ * checks whether the nearest meaningful line closes (or is) a JSDoc comment.
  */
 function precededByJsdoc(lines: string[], declarationLine: number): boolean {
     let cursor = declarationLine - 2; // zero-based line above the declaration
     while (cursor >= 0) {
         const prev = lines[cursor]?.trim() ?? '';
-        if (prev.startsWith('@')) {
-            cursor -= 1; // decorator — keep walking up
+        // Blank line between JSDoc closing fence and declaration — keep walking.
+        if (prev === '') {
+            cursor -= 1;
             continue;
         }
-        return prev.endsWith('*/') || prev.startsWith('/**');
+        // JSDoc closing or single-line fence — found it.
+        if (prev.endsWith('*/') || prev.startsWith('/**')) {
+            return true;
+        }
+        // JSDoc body line (* …) or decorator / tag (@…).  Check after the
+        // fence so `*/` is never misidentified as a body line.
+        if (prev.startsWith('*') || prev.startsWith('@')) {
+            cursor -= 1;
+            continue;
+        }
+        // Non-JSDoc, non-decorator line — no JSDoc precedes this declaration.
+        return false;
     }
     return false;
 }

package/src/fixers/fixers.ts

@@ -6,9 +6,10 @@
  */
 
 import {
+    createNodeFileSystem,
+    type FileSystem,
     isAbsolutePath,
     joinPath,
-    NodeFileSystem,
     type ProcessExecutor,
     relativePath,
     resolvePath,
@@ -66,7 +67,7 @@ export async function applyFixes(
     workdir: string,
     fixes: readonly Fix[],
     dryRun = false,
-    fs: NodeFileSystem = new NodeFileSystem(),
+    fs: FileSystem = createNodeFileSystem(),
 ): Promise<FixApplicationResult> {
     const byFile = new Map<string, Fix[]>();
     for (const fix of fixes) {
@@ -117,7 +118,7 @@ export async function applyFixes(
             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);
             }
@@ -173,10 +174,10 @@ function isValidRange(start: number, end: number, contentLength: number): boolea
  * replacement string (supports `$1` / `$&` back-references).
  */
 export class RegexFixerProvider implements RuleFixerProvider {
-    private readonly fs = new NodeFileSystem();
-
     /** Produce fixes for regex-evaluator findings. */
     async createFixes({ rule, context, findings, fix }: RuleFixerInput): Promise<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'.
         const fixMode = fix.mode as Exclude<FixMode, 'none'>;
@@ -191,8 +192,8 @@ export class RegexFixerProvider implements RuleFixerProvider {
             if (!finding.filePath) continue;
             const absPath = resolveWorkdirPath(context.workdir, finding.filePath);
             if (!isInsideWorkdir(context.workdir, absPath) || finding.line == null) continue;
-            if (!(await this.fs.exists(absPath))) continue;
-            const source = await this.fs.readFile(absPath);
+            if (!(await fs.exists(absPath))) continue;
+            const source = await fs.readFile(absPath);
             const line = getLineRange(source, finding.line);
             if (!line) continue;
             for (const match of source.slice(line.start, line.end).matchAll(regex)) {
@@ -220,18 +221,16 @@ export class RegexFixerProvider implements RuleFixerProvider {
  * `applyFixes` interprets a zero-length result spanning the full file as a deletion.
  */
 export class PathFixerProvider implements RuleFixerProvider {
-    private readonly fs = new NodeFileSystem();
-
     /** Produce deletion fixes for path-evaluator findings. */
     async createFixes({ rule, context, findings, fix }: RuleFixerInput): Promise<Fix[]> {
+        const fs = context.fileSystem ?? createNodeFileSystem();
         if (fix.mode !== 'auto' || rule.evaluator.config?.must !== 'absent') return [];
         const fixes: Fix[] = [];
         for (const finding of findings) {
             if (!finding.filePath) continue;
             const absPath = resolveWorkdirPath(context.workdir, finding.filePath);
-            if (!isInsideWorkdir(context.workdir, absPath)) continue;
-            if (!(await this.fs.exists(absPath))) continue;
-            const content = await this.fs.readFile(absPath);
+            if (!(await fs.exists(absPath))) continue;
+            const content = await fs.readFile(absPath);
             fixes.push({
                 ruleId: rule.id,
                 filePath: finding.filePath,

package/src/fixers/test-stub-fixer.ts

@@ -11,7 +11,7 @@
  * @module rule-engine/fixers/test-stub-fixer
  */
 
-import { isAbsolutePath, joinPath, NodeFileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, isAbsolutePath, joinPath, type ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { CapabilityRegistry } from '@gobing-ai/ts-runtime/extension';
 import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import type { Fix } from '../types';
@@ -20,11 +20,11 @@ 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 const realFileSystem: TestStubFileSystem = new NodeFileSystem();
+export const realFileSystem: TestStubFileSystem = createNodeFileSystem();
 
 /** Dependencies injected into {@link TestStubFixer}. */
 export interface TestStubFixerDeps {

package/src/host/bundled-rules.ts

@@ -1,4 +1,4 @@
-import { dirnamePath, joinPath, NodeSyncFileSystem, type SyncFileSystem } from '@gobing-ai/ts-runtime';
+import { createNodeFileSystem, dirnamePath, type FileSystem, joinPath } from '@gobing-ai/ts-runtime';
 
 /**
  * Directory name holding the rule presets and category folders bundled with this
@@ -9,7 +9,8 @@ const BUNDLED_RULES_DIR = 'rules';
 
 /** Memoized result so the upward filesystem walk runs at most once per process. */
 let cachedRoot: string | null | undefined;
-const defaultFs = new NodeSyncFileSystem();
+/** In-flight resolution to prevent racing concurrent calls. */
+let resolving: Promise<string | null> | undefined;
 
 /**
  * Resolve the absolute path to the rule presets bundled with
@@ -26,26 +27,28 @@ 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(): string | null {
-    return bundledRulesRootWithFs(defaultFs);
+export async function bundledRulesRoot(): Promise<string | null> {
+    if (cachedRoot !== undefined) return cachedRoot;
+    if (resolving !== undefined) return resolving;
+    resolving = bundledRulesRootWithFs(createNodeFileSystem());
+    cachedRoot = await resolving;
+    resolving = undefined;
+    return cachedRoot;
 }
 
-function bundledRulesRootWithFs(fs: SyncFileSystem): string | null {
-    if (cachedRoot !== undefined) return cachedRoot;
+async function bundledRulesRootWithFs(fs: FileSystem): Promise<string | null> {
     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;
 }
 
 /**
@@ -56,20 +59,21 @@ function bundledRulesRootWithFs(fs: SyncFileSystem): string | null {
  * (e.g. a per-user global rules directory) on first run. Returns an empty array
  * when no bundled directory is present.
  */
-export function listBundledRuleFiles(): string[] {
-    const root = bundledRulesRoot();
+export async function listBundledRuleFiles(): Promise<string[]> {
+    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: SyncFileSystem, dir: string, relPrefix: string): string[] {
+async function walk(fs: FileSystem, dir: string, relPrefix: string): Promise<string[]> {
     const acc: string[] = [];
-    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/src/types.ts

@@ -1,3 +1,4 @@
+import type { FileSystem } from '@gobing-ai/ts-runtime';
 import { assertRelativeExtensionPath } from '@gobing-ai/ts-runtime/extension';
 import { z } from 'zod';
 
@@ -156,6 +157,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. */