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

package/src/evaluators/ripgrep-evaluator.ts

@@ -0,0 +1,167 @@
+import { NodeProcessExecutor, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { configString, DEFAULT_EXCLUDES } from './file-utils';
+
+/**
+ * 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').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
+ * `rg-dialect` spur rule; see {@link isRipgrepCompatiblePattern}).
+ *
+ * ## Options (in `evaluator.config`)
+ * - `pattern` — ripgrep regex to search for (required).
+ * - `mode` — `forbid` (default): each match is a finding. `require`: a finding per file
+ *   that lacks the pattern.
+ * - `multiline` — when `true`, patterns may span lines (`rg -U --multiline-dotall`).
+ *
+ * Inline flags like `(?i)` are passed through to ripgrep, which supports them natively.
+ *
+ * The rule's `include` globs and `exclude` globs (plus {@link DEFAULT_EXCLUDES}) are
+ * forwarded as `--glob` / `--glob '!…'` so ripgrep prunes during traversal rather than
+ * walking everything — the same skip-list the in-process discovery path uses, applied
+ * regardless of whether the workspace is a git repo or has a `.gitignore`.
+ */
+export class RipgrepEvaluator implements RuleEvaluator {
+    private readonly executor: ProcessExecutor;
+
+    constructor(executor: ProcessExecutor = new NodeProcessExecutor()) {
+        this.executor = executor;
+    }
+
+    /** Run ripgrep and emit findings for matches (forbid) or absent files (require). */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = rule.evaluator.config ?? {};
+        const pattern = configString(config, 'pattern', undefined, { evaluator: 'rg' });
+        const mode = configString(config, 'mode', 'forbid');
+        const multiline = config.multiline === true;
+
+        const args = buildArgs(pattern, mode, multiline, rule.include ?? [], rule.exclude ?? []);
+        const result = await this.executor.run({
+            command: 'rg',
+            args,
+            cwd: context.workdir,
+            timeout: 60_000,
+            rejectOnError: false,
+            label: 'rg',
+        });
+
+        // ripgrep exits 0 with matches, 1 when none, 2 on error. Treat 2 (or any non-0/1
+        // with stderr) as a hard failure so a broken pattern or missing `rg` fails loud.
+        if (result.exitCode !== 0 && result.exitCode !== 1) {
+            const detail = result.stderr.trim();
+            throw new Error(`rg failed (exit ${result.exitCode})${detail.length > 0 ? `: ${detail}` : ''}`);
+        }
+
+        return mode === 'require'
+            ? { findings: requireFindings(rule, pattern, result.stdout), fixes: [] }
+            : { findings: forbidFindings(rule, pattern, result.stdout), fixes: [] };
+    }
+}
+
+/** Build the ripgrep argument list for the given mode and scope. */
+function buildArgs(pattern: string, mode: string, multiline: boolean, include: string[], exclude: string[]): string[] {
+    const args: string[] = [];
+    if (multiline) args.push('-U', '--multiline-dotall');
+
+    if (mode === 'require') {
+        // Files lacking the pattern, one path per line.
+        args.push('--files-without-match');
+    } else {
+        // Structured events carrying file + line_number for precise findings.
+        args.push('--json');
+    }
+
+    // Scope: includes as positive globs, DEFAULT_EXCLUDES + rule excludes as negated globs
+    // so ripgrep prunes during traversal (not after) regardless of .gitignore presence.
+    for (const glob of include) args.push('--glob', glob);
+    for (const dir of DEFAULT_EXCLUDES) args.push('--glob', `!**/${dir}/**`);
+    for (const glob of exclude) args.push('--glob', `!${glob}`);
+
+    // `--` guards against a pattern that begins with `-`.
+    args.push('--', pattern);
+    return args;
+}
+
+/** Parse `rg --json` match events into one finding per matched line. */
+function forbidFindings(rule: ConstraintRule, pattern: string, stdout: string): ReturnType<typeof createFinding>[] {
+    const findings: ReturnType<typeof createFinding>[] = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) continue;
+        let event: RipgrepEvent;
+        try {
+            event = JSON.parse(trimmed) as RipgrepEvent;
+        } catch {
+            continue; // Skip non-JSON noise.
+        }
+        if (event.type !== 'match') continue;
+        const file = event.data?.path?.text;
+        const lineNumber = event.data?.line_number;
+        if (typeof file !== 'string' || typeof lineNumber !== 'number') continue;
+        findings.push(
+            createFinding(rule, `forbidden pattern found: ${pattern}`, file, {
+                line: lineNumber,
+                code: 'rg:found',
+            }),
+        );
+    }
+    return findings;
+}
+
+/** Build one finding per file path printed by `rg --files-without-match`. */
+function requireFindings(rule: ConstraintRule, pattern: string, stdout: string): ReturnType<typeof createFinding>[] {
+    const findings: ReturnType<typeof createFinding>[] = [];
+    for (const line of stdout.split('\n')) {
+        const file = line.trim();
+        if (file.length === 0) continue;
+        findings.push(createFinding(rule, `required pattern not found: ${pattern}`, file, { code: 'rg:missing' }));
+    }
+    return findings;
+}
+
+/** Minimal shape of a `rg --json` event (only the fields this evaluator reads). */
+interface RipgrepEvent {
+    type: string;
+    data?: {
+        path?: { text?: string };
+        line_number?: number;
+    };
+}
+
+/** JS-`RegExp`-only constructs that ripgrep's Rust regex engine does not support. */
+const JS_ONLY_REGEX_FEATURES: { readonly name: string; readonly test: RegExp }[] = [
+    { name: 'lookbehind', test: /\(\?<[=!]/ },
+    { name: 'backreference', test: /\\[1-9]/ },
+    { name: 'named backreference', test: /\\k<[^>]+>/ },
+];
+
+/**
+ * Report whether a regex `pattern` is safe to run under ripgrep's engine.
+ *
+ * ripgrep's Rust `regex` crate is linear-time and therefore omits features that require
+ * backtracking — lookbehind and backreferences. A pattern using them works under the JS
+ * `regex` evaluator but fails to compile under `rg`. The `rg-dialect` spur rule and the
+ * downstream rule-file converter use this to keep incompatible patterns on the `regex`
+ * type instead of silently breaking them on `rg`.
+ *
+ * @returns `{ compatible: true }` or `{ compatible: false, feature }` naming the first
+ *   unsupported construct found.
+ */
+export function isRipgrepCompatiblePattern(
+    pattern: string,
+): { compatible: true } | { compatible: false; feature: string } {
+    for (const { name, test } of JS_ONLY_REGEX_FEATURES) {
+        if (test.test(pattern)) return { compatible: false, feature: name };
+    }
+    return { compatible: true };
+}

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

@@ -1,5 +1,4 @@
-import { resolve } from 'node:path';
-import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { joinPath, NodeFileSystem } from '@gobing-ai/ts-runtime';
 import {
     type ConstraintRule,
     createFinding,
@@ -7,6 +6,7 @@ import {
     type RuleEvaluationResult,
     type RuleEvaluator,
 } from '../types';
+import { stringArray } from './file-utils';
 
 /**
  * Evaluates JSON schema artifact files for structural integrity.
@@ -42,7 +42,7 @@ export class SchemaArtifactEvaluator implements RuleEvaluator {
         const requireRequiredArray = config.requireRequiredArray === true;
 
         // Check existence.
-        const absolutePath = resolve(context.workdir, file);
+        const absolutePath = joinPath(context.workdir, file);
         const exists = await this.fs.exists(absolutePath);
         if (!exists) {
             return {
@@ -127,8 +127,3 @@ export class SchemaArtifactEvaluator implements RuleEvaluator {
         return { findings, fixes: [] };
     }
 }
-
-/** Return a string array if value is a string array, otherwise undefined. */
-function stringArray(value: unknown): string[] | undefined {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
-}

package/src/evaluators/sg-evaluator.ts

@@ -6,7 +6,7 @@ import {
     type RuleEvaluationResult,
     type RuleEvaluator,
 } from '../types';
-import { matchesGlob } from './file-utils';
+import { DEFAULT_EXCLUDES, matchesGlob } from './file-utils';
 
 /**
  * Evaluates source code against an ast-grep pattern using the `sg` CLI.
@@ -15,8 +15,16 @@ import { matchesGlob } from './file-utils';
  * - `pattern` — ast-grep pattern to search for (required).
  * - `language` — language for ast-grep parsing (default: `typescript`).
  *
- * Include globs from the rule are forwarded to sg via `--glob` arguments.
- * Exclude globs from the rule are applied in-process after parsing sg output.
+ * Scope is forwarded to `sg` via `--globs` so the subprocess **prunes during traversal**
+ * rather than walking everything and filtering after:
+ * - the rule's `include` globs become positive `--globs` patterns;
+ * - {@link DEFAULT_EXCLUDES} (`node_modules`, `dist`, …) and the rule's `exclude` globs
+ *   become negated `--globs '!…'` patterns, so heavy generated trees are never descended
+ *   into even when a rule forgets to exclude them. ast-grep takes the later glob on
+ *   precedence, so exclusions are appended after includes.
+ *
+ * The rule's `exclude` is also re-applied in-process as a belt-and-suspenders against any
+ * difference between ast-grep's glob semantics and {@link matchesGlob}.
  */
 export class SgEvaluator implements RuleEvaluator {
     private readonly executor: ProcessExecutor;
@@ -38,8 +46,17 @@ export class SgEvaluator implements RuleEvaluator {
         const exclude = rule.exclude ?? [];
 
         const args: string[] = ['run', '--pattern', pattern, '--lang', language, '--json'];
+        // Positive include globs first.
         for (const glob of include) {
-            args.push(`--glob=${glob}`);
+            args.push('--globs', glob);
+        }
+        // Negated globs prune at traversal time. Default excludes go first so a rule's own
+        // exclude (later → higher precedence in ast-grep) can still re-include if intended.
+        for (const dir of DEFAULT_EXCLUDES) {
+            args.push('--globs', `!**/${dir}/**`);
+        }
+        for (const glob of exclude) {
+            args.push('--globs', `!${glob}`);
         }
 
         const result = await this.executor.run({

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

@@ -1,5 +1,5 @@
-import type { CapabilityRegistry } from '../host/capability-registry';
-import type { TestPathResolver } from '../resolvers/test-path-resolver';
+import type { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
+import { type TestPathResolver, TypeScriptTestPathResolver } from '../resolvers/test-path-resolver';
 import {
     type ConstraintRule,
     createFinding,
@@ -111,17 +111,4 @@ export class TestLocationEvaluator implements RuleEvaluator {
 }
 
 /** Built-in TypeScript convention used when no resolver registry is injected. */
-const TYPESCRIPT_FALLBACK: TestPathResolver = {
-    name: 'typescript',
-    resolveTestPath(srcRelPath: string): string {
-        if (srcRelPath.includes('.test.') || srcRelPath.includes('.spec.')) return srcRelPath;
-        const srcIdx = srcRelPath.indexOf('/src/');
-        if (srcIdx !== -1) {
-            const pkg = srcRelPath.slice(0, srcIdx);
-            const rel = srcRelPath.slice(srcIdx + '/src/'.length).replace(/\.(ts|tsx|js|jsx)$/, '.test.ts');
-            return `${pkg}/tests/${rel}`;
-        }
-        const withoutExt = srcRelPath.replace(/\.(ts|tsx|js|jsx)$/, '');
-        return `tests/${withoutExt.replace(/^src\//, '')}.test.ts`;
-    },
-};
+const TYPESCRIPT_FALLBACK: TestPathResolver = new TypeScriptTestPathResolver();

package/src/events.ts

@@ -0,0 +1,13 @@
+/** Typed event map for rule-engine run observability. All events prefixed `rule.`. */
+export type RuleEngineEvents = {
+    /** Emitted before the first rule is evaluated. */
+    'rule.run.start': (data: { rules: number; total: number }) => void;
+    /** Emitted immediately before a single rule's evaluator is invoked. */
+    'rule.eval.start': (data: { ruleId: string; index: number; total: number }) => void;
+    /** Emitted after a single rule evaluation finishes successfully. */
+    'rule.eval.done': (data: { ruleId: string; findings: number; durationMs: number }) => void;
+    /** Emitted when a rule evaluator throws (in addition to the `kind:'error'` finding). */
+    'rule.eval.error': (data: { ruleId: string; error: string }) => void;
+    /** Emitted after the last rule finishes (or was short-circuited). */
+    'rule.run.done': (data: { rules: number; findings: number; durationMs: number; stoppedEarly: boolean }) => void;
+};

package/src/fixers/fixers.ts

@@ -5,9 +5,15 @@
  * @module rule-engine/fixers
  */
 
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { NodeFileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
-import type { CapabilityRegistry } from '../host/capability-registry';
+import {
+    isAbsolutePath,
+    joinPath,
+    NodeFileSystem,
+    type ProcessExecutor,
+    relativePath,
+    resolvePath,
+} from '@gobing-ai/ts-runtime';
+import type { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
 import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import type { ConstraintFinding, ConstraintRule, Fix, FixMode, RuleContext } from '../types';
 import { TestStubFixer } from './test-stub-fixer';
@@ -83,7 +89,7 @@ export function builtInFixers(host?: BuiltInFixersDeps, exec?: ProcessExecutor):
 
 /** Resolve a workdir-relative or absolute path to an absolute path. */
 export function resolveWorkdirPath(workdir: string, filePath: string): string {
-    return isAbsolute(filePath) ? filePath : join(workdir, filePath);
+    return isAbsolutePath(filePath) ? filePath : joinPath(workdir, filePath);
 }
 
 /** Apply byte-range fixes to files, optionally returning a dry-run diff only. */
@@ -181,8 +187,8 @@ function selectNonOverlappingFixes(fixes: readonly Fix[]): { applied: Fix[]; def
 
 /** Return true when absPath is at or below workdir. */
 function isInsideWorkdir(workdir: string, absPath: string): boolean {
-    const rel = relative(resolve(workdir), resolve(absPath));
-    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+    const rel = relativePath(resolvePath(workdir), resolvePath(absPath));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolutePath(rel));
 }
 
 /** Return true when [start, end] is a valid byte range for a string of contentLength bytes. */

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

@@ -11,9 +11,8 @@
  * @module rule-engine/fixers/test-stub-fixer
  */
 
-import { isAbsolute, join } from 'node:path';
-import { NodeFileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
-import type { CapabilityRegistry } from '../host/capability-registry';
+import { isAbsolutePath, joinPath, NodeFileSystem, type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import type { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
 import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import type { Fix } from '../types';
 import type { RuleFixerInput, RuleFixerProvider } from './fixers';
@@ -39,7 +38,7 @@ export interface TestStubFixerDeps {
 
 /** Normalize a finding path to a repository-relative POSIX path, or return null when invalid. */
 function normalizeFindingPath(filePath: string): string | null {
-    if (!filePath || isAbsolute(filePath)) return null;
+    if (!filePath || isAbsolutePath(filePath)) return null;
     const normalized = filePath.replaceAll('\\', '/').replace(/^\.\//, '');
     if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) return null;
     return normalized;
@@ -94,7 +93,7 @@ export class TestStubFixer implements RuleFixerProvider {
                 continue;
             }
 
-            const absTestPath = join(context.workdir, testRelPath);
+            const absTestPath = joinPath(context.workdir, testRelPath);
             if (await this.fs.exists(absTestPath)) continue;
 
             // Export discovery is intentionally omitted — pass empty exports array.

package/src/host/builtins.ts

@@ -6,6 +6,7 @@ import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluat
 import { ImportBoundaryEvaluator } from '../evaluators/import-boundary-evaluator';
 import { PathEvaluator } from '../evaluators/path-evaluator';
 import { RegexEvaluator } from '../evaluators/regex-evaluator';
+import { RipgrepEvaluator } from '../evaluators/ripgrep-evaluator';
 import { SchemaArtifactEvaluator } from '../evaluators/schema-artifact-evaluator';
 import { SecretsScannerEvaluator } from '../evaluators/secrets-scanner-evaluator';
 import { SgEvaluator } from '../evaluators/sg-evaluator';
@@ -23,10 +24,11 @@ import type { RuleEngineHost } from './rule-engine-host';
 
 /** Register bundled evaluators and formatters on a host. */
 export function registerBuiltins(host: RuleEngineHost, executor?: ProcessExecutor): void {
-    const regex = new RegexEvaluator();
     const path = new PathEvaluator();
-    host.evaluators.register('regex', regex, 'builtin');
-    host.evaluators.register('rg', regex, 'builtin');
+    // `regex` = JS RegExp engine; `rg` = real ripgrep engine (ReDoS-immune, prunes during
+    // traversal). The two are honestly named distinct engines, not aliases.
+    host.evaluators.register('regex', new RegexEvaluator(), 'builtin');
+    host.evaluators.register('rg', new RipgrepEvaluator(executor), 'builtin');
     host.evaluators.register('path', path, 'builtin');
     host.evaluators.register('file-exist', path, 'builtin');
     host.evaluators.register('forbidden-import', new ForbiddenImportEvaluator(), 'builtin');

package/src/host/bundled-rules.ts

@@ -15,7 +15,7 @@ const defaultFs = new NodeSyncFileSystem();
  * Resolve the absolute path to the rule presets bundled with
  * `@gobing-ai/ts-rule-engine`.
  *
- * The directory ships portable presets (`recommended`, `spur-dev`) and category
+ * The directory ships a generic example preset and category
  * folders (`typescript`, `structure`, `quality`) so a consumer gets a working
  * default ruleset without authoring any files. Pass the returned path as the
  * lowest-priority entry to {@link loadPreset}'s `roots`, letting project-local

package/src/host/rule-engine-host.ts

@@ -1,6 +1,6 @@
+import { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
 import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import type { ResultFormatter, RuleEvaluator } from '../types';
-import { CapabilityRegistry } from './capability-registry';
 
 /** Host container for rule-engine capabilities. */
 export class RuleEngineHost {

package/src/index.ts

@@ -1,12 +1,19 @@
+// Public re-export of the shared plugin registry (ADR-010). Sourced directly from
+// the shared plugin core; the former host/capability-registry.ts shim was removed
+// once the one-release back-compat window closed.
+export { type CapabilityEntry, type CapabilityOrigin, CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
 export * from './config/extensions';
 export * from './config/loader';
 export * from './engine';
+// Public dialect helper for the `rg` (ripgrep) evaluator — consumed by the downstream
+// rule-file converter and the rg-dialect rule to keep JS-only patterns off the `rg` type.
+export { isRipgrepCompatiblePattern } from './evaluators/ripgrep-evaluator';
+export type { RuleEngineEvents } from './events';
 export * from './fixers/fixers';
 export * from './fixers/test-stub-fixer';
 export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/bundled-rules';
-export * from './host/capability-registry';
 export * from './host/rule-engine-host';
 export * from './resolvers/test-path-resolver';
 export * from './types';

package/src/types.ts

@@ -4,6 +4,13 @@ import { z } from 'zod';
 /** Finding severity emitted by the rule engine. */
 export type RuleSeverity = 'error' | 'warning' | 'info';
 
+/** Numeric rank for severity comparison; higher = more severe. */
+export const SEVERITY_RANK: Record<RuleSeverity, number> = {
+    error: 3,
+    warning: 2,
+    info: 1,
+};
+
 /** Fix authority level for candidate fixes. */
 export type FixMode = 'none' | 'suggest' | 'auto';
 

package/dist/host/capability-registry.d.ts

@@ -1,10 +0,0 @@
-/**
- * Compatibility re-export (ADR-010 / task 0008).
- *
- * The capability registry now lives in the shared plugin core
- * (`@gobing-ai/ts-runtime/plugin`). This module re-exports it from the original
- * path so the public barrel and existing importers keep working unchanged. New
- * code should import from `@gobing-ai/ts-runtime/plugin` directly.
- */
-export { type CapabilityEntry, type CapabilityOrigin, CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';
-//# sourceMappingURL=capability-registry.d.ts.map

package/dist/host/capability-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../../src/host/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/host/capability-registry.js

@@ -1,9 +0,0 @@
-/**
- * Compatibility re-export (ADR-010 / task 0008).
- *
- * The capability registry now lives in the shared plugin core
- * (`@gobing-ai/ts-runtime/plugin`). This module re-exports it from the original
- * path so the public barrel and existing importers keep working unchanged. New
- * code should import from `@gobing-ai/ts-runtime/plugin` directly.
- */
-export { CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';

package/rules/recommended.yaml

@@ -1,10 +0,0 @@
-# Recommended preset — portable rule categories for TypeScript projects.
-# Use with: spur rule run --preset recommended
-#
-# Bundled with @gobing-ai/ts-rule-engine. A project may override individual rule
-# files by placing same-named files under its local .spur/rules/ root.
-name: recommended
-extends:
-  - typescript
-  - structure
-  - quality

package/rules/spur-dev.yaml

@@ -1,6 +0,0 @@
-# Development preset — stricter rules for development workflow.
-# Use with: spur rule run --preset spur-dev --rule coverage-gate --fail-on warning
-name: spur-dev
-extends:
-  - typescript
-  - quality

package/src/host/capability-registry.ts

@@ -1,9 +0,0 @@
-/**
- * Compatibility re-export (ADR-010 / task 0008).
- *
- * The capability registry now lives in the shared plugin core
- * (`@gobing-ai/ts-runtime/plugin`). This module re-exports it from the original
- * path so the public barrel and existing importers keep working unchanged. New
- * code should import from `@gobing-ai/ts-runtime/plugin` directly.
- */
-export { type CapabilityEntry, type CapabilityOrigin, CapabilityRegistry } from '@gobing-ai/ts-runtime/plugin';