@gobing-ai/ts-rule-engine 0.2.6 → 0.2.7

package/src/fixers/fixers.ts

@@ -0,0 +1,294 @@
+/**
+ * Core fixer pipeline: provider contracts, built-in fixer implementations,
+ * and the byte-range fix application function.
+ *
+ * @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 type { TestPathResolver } from '../resolvers/test-path-resolver';
+import type { ConstraintFinding, ConstraintRule, Fix, FixMode, RuleContext } from '../types';
+import { TestStubFixer } from './test-stub-fixer';
+
+/** Numeric ordering for fix authority; higher means more write authority. */
+export const FIX_MODE_RANK: Record<FixMode, number> = {
+    none: 0,
+    suggest: 1,
+    auto: 2,
+};
+
+/** Result of resolving effective fix authority for a rule. */
+export interface EffectiveFix {
+    /** Effective mode after all downgrades. */
+    readonly mode: FixMode;
+    /** Optional replacement text configured by the rule author. */
+    readonly replacement?: string;
+    /** Optional provider-specific parameters. */
+    readonly params?: Record<string, unknown>;
+}
+
+/** Input passed to a rule fixer provider. */
+export interface RuleFixerInput {
+    /** Rule that produced the findings. */
+    readonly rule: ConstraintRule;
+    /** Rule execution context. */
+    readonly context: RuleContext;
+    /** Findings emitted for this rule. */
+    readonly findings: ConstraintFinding[];
+    /** Effective fix metadata after authority enforcement. */
+    readonly fix: EffectiveFix;
+}
+
+/** Provider that turns findings into byte-range fixes. */
+export interface RuleFixerProvider {
+    /** Produce fixes for mechanically fixable findings. */
+    createFixes(input: RuleFixerInput): Fix[] | Promise<Fix[]>;
+}
+
+/** Result of applying or previewing a batch of fixes. */
+export interface FixApplicationResult {
+    /** Files changed in memory or on disk. */
+    readonly changedFiles: string[];
+    /** Fixes successfully applied. */
+    readonly applied: Fix[];
+    /** Fixes skipped because they overlapped an already-applied edit. */
+    readonly deferred: Fix[];
+    /** Unified diff when dry-run mode is requested. */
+    readonly diff: string;
+}
+
+/** Dependencies required for the built-in fixer registry. */
+export interface BuiltInFixersDeps {
+    /** Resolver registry, required for TestStubFixer. */
+    resolvers: CapabilityRegistry<TestPathResolver>;
+}
+
+/** Registry of built-in rule fixer providers keyed by evaluator type. */
+export function builtInFixers(host?: BuiltInFixersDeps, exec?: ProcessExecutor): Map<string, RuleFixerProvider> {
+    const regexFixer = new RegexFixerProvider();
+    const pathFixer = new PathFixerProvider();
+    const entries: Array<[string, RuleFixerProvider]> = [
+        ['regex', regexFixer],
+        ['rg', regexFixer],
+        ['path', pathFixer],
+        ['file-exist', pathFixer],
+    ];
+    if (host && exec) {
+        entries.push(['test-location', new TestStubFixer({ resolvers: host.resolvers, processExecutor: exec })]);
+    }
+    return new Map(entries);
+}
+
+/** 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);
+}
+
+/** Apply byte-range fixes to files, optionally returning a dry-run diff only. */
+export async function applyFixes(
+    workdir: string,
+    fixes: readonly Fix[],
+    dryRun = false,
+    fs: NodeFileSystem = new NodeFileSystem(),
+): Promise<FixApplicationResult> {
+    const byFile = new Map<string, Fix[]>();
+    for (const fix of fixes) {
+        const list = byFile.get(fix.filePath) ?? [];
+        list.push(fix);
+        byFile.set(fix.filePath, list);
+    }
+
+    const applied: Fix[] = [];
+    const deferred: Fix[] = [];
+    const changedFiles: string[] = [];
+    const diffs: string[] = [];
+
+    for (const [filePath, fileFixes] of byFile) {
+        const absPath = resolveWorkdirPath(workdir, filePath);
+        if (!isInsideWorkdir(workdir, absPath)) {
+            deferred.push(...fileFixes);
+            continue;
+        }
+
+        const fileExists = await fs.exists(absPath);
+        const original = fileExists ? await fs.readFile(absPath) : '';
+        const selected = selectNonOverlappingFixes(fileFixes);
+        deferred.push(...selected.deferred);
+
+        let next = original;
+        for (const fix of [...selected.applied].sort((a, b) => b.start - a.start)) {
+            if (!fileExists && (fix.start !== 0 || fix.end !== 0)) {
+                deferred.push(fix);
+                continue;
+            }
+            if (!isValidRange(fix.start, fix.end, original.length)) {
+                deferred.push(fix);
+                continue;
+            }
+            next = `${next.slice(0, fix.start)}${fix.replacement}${next.slice(fix.end)}`;
+            applied.push(fix);
+        }
+
+        if (next === original) {
+            continue;
+        }
+
+        changedFiles.push(filePath);
+        diffs.push(createUnifiedDiff(filePath, original, next));
+
+        if (!dryRun) {
+            const isFullDeletion =
+                next.length === 0 && selected.applied.some((fix) => fix.start === 0 && fix.end === original.length);
+            if (isFullDeletion) {
+                await fs.unlink(absPath);
+            } else {
+                await fs.writeFile(absPath, next);
+            }
+        }
+    }
+
+    return { changedFiles, applied, deferred, diff: diffs.join('\n') };
+}
+
+/** Create a coarse unified diff string for dry-run CLI output. */
+export function createUnifiedDiff(filePath: string, before: string, after: string): string {
+    const beforeLines = before.split('\n');
+    const afterLines = after.split('\n');
+    const lines = [`--- ${filePath}`, `+++ ${filePath}`, `@@ -1,${beforeLines.length} +1,${afterLines.length} @@`];
+    lines.push(...beforeLines.map((line) => `-${line}`));
+    lines.push(...afterLines.map((line) => `+${line}`));
+    return lines.join('\n');
+}
+
+/** Select the maximal non-overlapping set of fixes, ordered by ascending start offset. */
+function selectNonOverlappingFixes(fixes: readonly Fix[]): { applied: Fix[]; deferred: Fix[] } {
+    const applied: Fix[] = [];
+    const deferred: Fix[] = [];
+    const ordered = [...fixes].sort((a, b) => a.start - b.start || a.end - b.end);
+    let lastEnd = -1;
+    for (const fix of ordered) {
+        if (fix.start < lastEnd) {
+            deferred.push(fix);
+            continue;
+        }
+        applied.push(fix);
+        lastEnd = fix.end;
+    }
+    return { applied, deferred };
+}
+
+/** 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));
+}
+
+/** Return true when [start, end] is a valid byte range for a string of contentLength bytes. */
+function isValidRange(start: number, end: number, contentLength: number): boolean {
+    return start >= 0 && end >= start && end <= contentLength;
+}
+
+/**
+ * Fixer provider for `regex` / `rg` evaluators.
+ *
+ * For each finding with a known line number, reads the file and emits a Fix that
+ * replaces every regex match on that line using `rule.fix.replacement` as the
+ * 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[]> {
+        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'>;
+        const replacement = fix.replacement;
+        const pattern = rule.evaluator.config?.pattern;
+        if (typeof pattern !== 'string' || pattern.length === 0) return [];
+        const flags = flagsFromRule(rule);
+        const regex = new RegExp(pattern, flags.includes('g') ? flags : `${flags}g`);
+
+        const fixes: Fix[] = [];
+        for (const finding of findings) {
+            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);
+            const line = getLineRange(source, finding.line);
+            if (!line) continue;
+            for (const match of source.slice(line.start, line.end).matchAll(regex)) {
+                if (match.index === undefined) continue;
+                const matched = match[0];
+                fixes.push({
+                    ruleId: rule.id,
+                    filePath: finding.filePath,
+                    start: line.start + match.index,
+                    end: line.start + match.index + matched.length,
+                    replacement: matched.replace(new RegExp(pattern, flags), replacement),
+                    mode: fixMode,
+                });
+            }
+        }
+        return fixes;
+    }
+}
+
+/**
+ * Fixer provider for `path` / `file-exist` evaluators.
+ *
+ * In `auto` mode, when a rule requires a file to be absent (`must: absent`),
+ * emits a Fix that replaces the entire file content with an empty string.
+ * `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[]> {
+        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);
+            fixes.push({
+                ruleId: rule.id,
+                filePath: finding.filePath,
+                start: 0,
+                end: content.length,
+                replacement: '',
+                mode: 'auto' as const,
+            });
+        }
+        return fixes;
+    }
+}
+
+/** Extract regex flags from a rule's evaluator config. */
+function flagsFromRule(rule: ConstraintRule): string {
+    const raw = rule.evaluator.config?.flags;
+    if (typeof raw !== 'string') return '';
+    if (raw.startsWith('(?') && raw.endsWith(')')) {
+        return raw.slice(2, -1).replace(/[^imsuy]/g, '');
+    }
+    return raw.replace(/[^imsuy]/g, '');
+}
+
+/** Return the byte range [start, end) of a one-based line number within source. */
+function getLineRange(source: string, oneBasedLine: number): { start: number; end: number } | null {
+    if (oneBasedLine < 1) return null;
+    let start = 0;
+    for (let line = 1; line < oneBasedLine; line += 1) {
+        const next = source.indexOf('\n', start);
+        if (next === -1) return null;
+        start = next + 1;
+    }
+    const newline = source.indexOf('\n', start);
+    return { start, end: newline === -1 ? source.length : newline };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Fixer that generates test file skeletons for source files missing tests.
+ *
+ * Resolver-aware: selects the correct {@link TestPathResolver} from
+ * `rule.evaluator.config.resolver`. Passes empty exports to the resolver's
+ * `generateSkeleton` — AST / sg discovery is intentionally omitted here to
+ * keep the shared package dependency-free; callers that need export-aware
+ * skeletons should register a custom resolver that performs its own discovery.
+ * Never overwrites an existing test file.
+ *
+ * @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 type { TestPathResolver } from '../resolvers/test-path-resolver';
+import type { Fix } from '../types';
+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>;
+}
+
+/** Real file-system implementation backed by the runtime FileSystem seam. */
+export const realFileSystem: TestStubFileSystem = new NodeFileSystem();
+
+/** Dependencies injected into {@link TestStubFixer}. */
+export interface TestStubFixerDeps {
+    /** Resolver registry from the engine host. */
+    readonly resolvers: CapabilityRegistry<TestPathResolver>;
+    /** Process executor (reserved for future export discovery). */
+    readonly processExecutor: ProcessExecutor;
+    /** Optional file-system override for testing. */
+    readonly fileSystem?: TestStubFileSystem;
+}
+
+/** 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;
+    const normalized = filePath.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) return null;
+    return normalized;
+}
+
+/**
+ * Fixer provider for the `test-location` evaluator.
+ *
+ * Emits a create-file Fix (start=0, end=0) for each finding whose source file
+ * has no corresponding test file yet. The test path and skeleton content are
+ * produced by the resolver named in `rule.evaluator.config.resolver`
+ * (default: `typescript`).
+ */
+export class TestStubFixer implements RuleFixerProvider {
+    private readonly resolvers: CapabilityRegistry<TestPathResolver>;
+    private readonly fs: TestStubFileSystem;
+
+    constructor(deps: TestStubFixerDeps) {
+        this.resolvers = deps.resolvers;
+        // processExecutor is accepted for interface parity but export discovery
+        // is not performed in this shared-package implementation — see module doc.
+        this.fs = deps.fileSystem ?? realFileSystem;
+    }
+
+    /** Produce create-file fixes for missing test stubs. */
+    async createFixes(input: RuleFixerInput): Promise<Fix[]> {
+        const { rule, context, findings, fix } = input;
+
+        if (fix.mode === 'none') return [];
+
+        const resolverName = (rule.evaluator.config?.resolver as string | undefined) ?? 'typescript';
+        let resolver: TestPathResolver;
+        try {
+            resolver = this.resolvers.get(resolverName);
+        } catch {
+            // Resolver not registered — return no fixes rather than silently falling back.
+            return [];
+        }
+
+        const result: Fix[] = [];
+
+        for (const finding of findings) {
+            if (!finding.filePath) continue;
+
+            const srcRelPath = normalizeFindingPath(finding.filePath);
+            if (!srcRelPath) continue;
+
+            let testRelPath: string;
+            try {
+                testRelPath = resolver.resolveTestPath(srcRelPath);
+            } catch {
+                continue;
+            }
+
+            const absTestPath = join(context.workdir, testRelPath);
+            if (await this.fs.exists(absTestPath)) continue;
+
+            // Export discovery is intentionally omitted — pass empty exports array.
+            // Resolvers that need per-export stubs should perform their own discovery.
+            const skeleton = resolver.generateSkeleton?.(srcRelPath, []) ?? '';
+            if (!skeleton) continue;
+
+            result.push({
+                ruleId: rule.id,
+                filePath: testRelPath,
+                start: 0,
+                end: 0,
+                replacement: skeleton,
+                // fix.mode !== 'none' is guaranteed by the guard at the top of this method.
+                mode: fix.mode as Exclude<typeof fix.mode, 'none'>,
+            });
+        }
+
+        return result;
+    }
+}

package/src/host/builtins.ts

@@ -3,13 +3,22 @@ import { AgentDetectionEvaluator } from '../evaluators/agent-detection-evaluator
 import { CoverageGateEvaluator } from '../evaluators/coverage-gate-evaluator';
 import { ExitCodeEvaluator } from '../evaluators/exit-code-evaluator';
 import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluator';
+import { ImportBoundaryEvaluator } from '../evaluators/import-boundary-evaluator';
 import { PathEvaluator } from '../evaluators/path-evaluator';
 import { RegexEvaluator } from '../evaluators/regex-evaluator';
+import { SchemaArtifactEvaluator } from '../evaluators/schema-artifact-evaluator';
 import { SecretsScannerEvaluator } from '../evaluators/secrets-scanner-evaluator';
+import { SgEvaluator } from '../evaluators/sg-evaluator';
 import { TestLocationEvaluator } from '../evaluators/test-location-evaluator';
 import { TsdocExportEvaluator } from '../evaluators/tsdoc-export-evaluator';
 import { JsonFormatter } from '../formatters/json';
 import { TextFormatter } from '../formatters/text';
+import {
+    GoTestPathResolver,
+    PythonTestPathResolver,
+    RustTestPathResolver,
+    TypeScriptTestPathResolver,
+} from '../resolvers/test-path-resolver';
 import type { RuleEngineHost } from './rule-engine-host';
 
 /** Register bundled evaluators and formatters on a host. */
@@ -26,7 +35,14 @@ export function registerBuiltins(host: RuleEngineHost, executor?: ProcessExecuto
     host.evaluators.register('agent-detection', new AgentDetectionEvaluator(), 'builtin');
     host.evaluators.register('coverage-gate', new CoverageGateEvaluator(), 'builtin');
     host.evaluators.register('tsdoc-export', new TsdocExportEvaluator(), 'builtin');
-    host.evaluators.register('test-location', new TestLocationEvaluator(), 'builtin');
+    host.resolvers.register('typescript', new TypeScriptTestPathResolver(), 'builtin');
+    host.resolvers.register('python', new PythonTestPathResolver(), 'builtin');
+    host.resolvers.register('go', new GoTestPathResolver(), 'builtin');
+    host.resolvers.register('rust', new RustTestPathResolver(), 'builtin');
+    host.evaluators.register('test-location', new TestLocationEvaluator(host.resolvers), 'builtin');
+    host.evaluators.register('sg', new SgEvaluator(executor), 'builtin');
+    host.evaluators.register('schema-artifact', new SchemaArtifactEvaluator(), 'builtin');
+    host.evaluators.register('import-boundary', new ImportBoundaryEvaluator(), 'builtin');
     host.formatters.register('text', new TextFormatter(), 'builtin');
     host.formatters.register('json', new JsonFormatter(), 'builtin');
 }

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

@@ -1,3 +1,4 @@
+import type { TestPathResolver } from '../resolvers/test-path-resolver';
 import type { ResultFormatter, RuleEvaluator } from '../types';
 import { CapabilityRegistry } from './capability-registry';
 
@@ -7,9 +8,12 @@ export class RuleEngineHost {
     readonly evaluators: CapabilityRegistry<RuleEvaluator>;
     /** Formatter registry keyed by formatter name. */
     readonly formatters: CapabilityRegistry<ResultFormatter>;
+    /** Test-path resolver registry keyed by language name. */
+    readonly resolvers: CapabilityRegistry<TestPathResolver>;
 
     constructor() {
         this.evaluators = new CapabilityRegistry<RuleEvaluator>('evaluator');
         this.formatters = new CapabilityRegistry<ResultFormatter>('formatter');
+        this.resolvers = new CapabilityRegistry<TestPathResolver>('resolver');
     }
 }

package/src/index.ts

@@ -1,7 +1,11 @@
+export * from './config/extensions';
 export * from './config/loader';
 export * from './engine';
+export * from './fixers/fixers';
+export * from './fixers/test-stub-fixer';
 export * from './formatters/json';
 export * from './formatters/text';
 export * from './host/capability-registry';
 export * from './host/rule-engine-host';
+export * from './resolvers/test-path-resolver';
 export * from './types';

package/src/resolvers/test-path-resolver.ts

@@ -0,0 +1,133 @@
+/**
+ * Pluggable test-path resolution for the test-location evaluator.
+ *
+ * Each implementation maps a source file path to its conventional test file path
+ * for one language, so the same evaluator works across TypeScript, Python, Go, and
+ * Rust projects. Resolvers are registered on the host and selected per rule via
+ * `evaluator.config.resolver`.
+ */
+
+/** Metadata about an exported symbol, used when generating a test skeleton. */
+export interface ExportInfo {
+    /** Symbol name. */
+    readonly name: string;
+    /** Declaration kind. */
+    readonly kind: 'function' | 'class' | 'const' | 'type' | 'interface' | 'unknown';
+    /** One-based source line, when known. */
+    readonly line?: number;
+}
+
+/** Maps source files to expected test files for a project type. */
+export interface TestPathResolver {
+    /** Language name this resolver handles (registry key). */
+    readonly name: string;
+    /** Compute the expected test file path for a source file. */
+    resolveTestPath(srcRelPath: string): string;
+    /** Optionally generate a test skeleton for a source file. */
+    generateSkeleton?(srcRelPath: string, exports: ExportInfo[]): string;
+}
+
+/**
+ * TypeScript conventions:
+ *   src/foo/bar.ts → tests/foo/bar.test.ts
+ *   packages/core/src/foo/bar.ts → packages/core/tests/foo/bar.test.ts
+ */
+export class TypeScriptTestPathResolver implements TestPathResolver {
+    /** Registry key. */
+    readonly name = 'typescript';
+
+    constructor() {}
+
+    /** Map a TS/JS source path to its `tests/…test.ts` counterpart. */
+    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`;
+    }
+}
+
+/**
+ * Python conventions (pytest):
+ *   src/foo/bar.py → tests/foo/test_bar.py
+ */
+export class PythonTestPathResolver implements TestPathResolver {
+    /** Registry key. */
+    readonly name = 'python';
+
+    constructor() {}
+
+    /** Map a Python source path to its `tests/…/test_*.py` counterpart. */
+    resolveTestPath(srcRelPath: string): string {
+        if (!srcRelPath) throw new Error('empty source path');
+        if (srcRelPath.endsWith('_test.py') || srcRelPath.includes('/test_') || srcRelPath.startsWith('test_')) {
+            return srcRelPath;
+        }
+        if (srcRelPath.startsWith('tests/')) return srcRelPath;
+        if (!srcRelPath.endsWith('.py')) throw new Error(`unsupported extension for python resolver: ${srcRelPath}`);
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const pkg = srcRelPath.slice(0, srcIdx);
+            return `${pkg}/tests/${testify(srcRelPath.slice(srcIdx + '/src/'.length))}`;
+        }
+        if (srcRelPath.startsWith('src/')) return `tests/${testify(srcRelPath.slice(4))}`;
+        return `tests/${testify(srcRelPath)}`;
+    }
+}
+
+/**
+ * Go conventions:
+ *   foo/bar.go → foo/bar_test.go (sibling)
+ */
+export class GoTestPathResolver implements TestPathResolver {
+    /** Registry key. */
+    readonly name = 'go';
+
+    constructor() {}
+
+    /** Map a Go source path to its sibling `_test.go` file. */
+    resolveTestPath(srcRelPath: string): string {
+        if (!srcRelPath) throw new Error('empty source path');
+        if (srcRelPath.endsWith('_test.go')) return srcRelPath;
+        if (!srcRelPath.endsWith('.go')) throw new Error(`unsupported extension for go resolver: ${srcRelPath}`);
+        return srcRelPath.replace(/\.go$/, '_test.go');
+    }
+}
+
+/**
+ * Rust conventions (Cargo integration tests):
+ *   crate/src/foo.rs → crate/tests/foo.rs
+ */
+export class RustTestPathResolver implements TestPathResolver {
+    /** Registry key. */
+    readonly name = 'rust';
+
+    constructor() {}
+
+    /** Map a Rust source path to its `tests/` integration-test counterpart. */
+    resolveTestPath(srcRelPath: string): string {
+        if (!srcRelPath) throw new Error('empty source path');
+        if (srcRelPath.startsWith('tests/') || srcRelPath.includes('/tests/')) return srcRelPath;
+        if (!srcRelPath.endsWith('.rs')) throw new Error(`unsupported extension for rust resolver: ${srcRelPath}`);
+        const srcIdx = srcRelPath.indexOf('/src/');
+        if (srcIdx !== -1) {
+            const crate = srcRelPath.slice(0, srcIdx);
+            return `${crate}/tests/${srcRelPath.slice(srcIdx + '/src/'.length)}`;
+        }
+        if (srcRelPath.startsWith('src/')) return `tests/${srcRelPath.slice(4)}`;
+        return `tests/${srcRelPath}`;
+    }
+}
+
+/** Prefix the basename of a Python source path with `test_`. */
+function testify(rel: string): string {
+    const lastSlash = rel.lastIndexOf('/');
+    const dir = lastSlash >= 0 ? rel.slice(0, lastSlash + 1) : '';
+    const base = lastSlash >= 0 ? rel.slice(lastSlash + 1) : rel;
+    return `${dir}test_${base}`;
+}

package/src/types.ts

@@ -56,6 +56,18 @@ export interface ConstraintRuleFile {
     rules: ConstraintRule[];
 }
 
+/** Relative module paths a preset contributes per capability kind. */
+export interface PresetExtensions {
+    /** Test-path resolver module paths. */
+    resolvers?: string[];
+    /** Evaluator module paths. */
+    evaluators?: string[];
+    /** Fixer module paths. */
+    fixers?: string[];
+    /** Formatter module paths. */
+    formatters?: string[];
+}
+
 /** Preset definition that composes category folders or other presets. */
 export interface PresetDefinition {
     /** Preset name. */
@@ -66,6 +78,8 @@ export interface PresetDefinition {
     disable?: string[];
     /** Per-rule overrides. */
     overrides?: Record<string, { fix?: { mode: FixMode } }>;
+    /** Custom capability modules contributed by this preset (opt-in to load). */
+    extensions?: PresetExtensions;
 }
 
 /** Candidate fix emitted by an evaluator or fixer. */
@@ -84,6 +98,16 @@ export interface Fix {
     mode: Exclude<FixMode, 'none'>;
 }
 
+/**
+ * What a finding represents.
+ *
+ * - `violation`: the rule ran and the project breached its policy (the default).
+ * - `error`: the rule could not run — a misconfiguration or runtime fault in the
+ *   evaluator itself. These are not policy breaches and callers may surface them
+ *   separately (e.g. "rule misconfigured") rather than as project violations.
+ */
+export type FindingKind = 'violation' | 'error';
+
 /** Finding emitted by a constraint rule. */
 export interface ConstraintFinding {
     /** Rule identifier. */
@@ -100,6 +124,8 @@ export interface ConstraintFinding {
     column?: number;
     /** Machine-readable evaluator/source code. */
     code?: string;
+    /** Whether this is a policy violation or an evaluator error. Absent means `violation`. */
+    kind?: FindingKind;
 }
 
 /** Aggregate result returned by a rule evaluator. */
@@ -194,4 +220,12 @@ export const PresetDefinitionSchema = z.object({
     overrides: z
         .record(z.string(), z.object({ fix: z.object({ mode: z.enum(['none', 'suggest', 'auto']) }).optional() }))
         .optional(),
+    extensions: z
+        .object({
+            resolvers: z.array(z.string()).optional(),
+            evaluators: z.array(z.string()).optional(),
+            fixers: z.array(z.string()).optional(),
+            formatters: z.array(z.string()).optional(),
+        })
+        .optional(),
 });