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

package/dist/config/extensions.d.ts

@@ -0,0 +1,46 @@
+import type { RuleEngineHost } from '../host/rule-engine-host';
+/** A capability kind a preset extension can contribute. */
+export type ExtensionKind = 'resolvers' | 'evaluators' | 'fixers' | 'formatters';
+/** A single extension module reference, resolved to an absolute path. */
+export interface ExtensionRef {
+    /** Capability registry the module registers into. */
+    readonly kind: ExtensionKind;
+    /** Absolute path to the module to import. */
+    readonly absPath: string;
+    /** Name of the preset that declared this extension (for diagnostics). */
+    readonly presetName: string;
+}
+/** Options controlling preset-extension loading. */
+export interface LoadExtensionsOptions {
+    /**
+     * Whether to actually import extension modules. Defaults to `false`: loading
+     * arbitrary code referenced by a preset is a trust decision the caller must
+     * make explicitly. When refs exist and this is false, loading throws.
+     */
+    allowExtensions?: boolean;
+    /** Optional sink for non-fatal warnings (e.g. built-in overrides). */
+    logger?: {
+        warn: (message: string) => void;
+    };
+}
+/**
+ * Collect extension refs declared by a preset's `extensions` block.
+ *
+ * Paths are resolved relative to the preset file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}.
+ */
+export declare function collectPresetExtensions(presetName: string, presetDir: string, extensions: Partial<Record<ExtensionKind, string[] | undefined>> | undefined): ExtensionRef[];
+/**
+ * Import each extension module and register its export on the matching host
+ * registry.
+ *
+ * A module must default-export (or named-export `extension`) an object with a
+ * `name: string` and the capability implementation. Loading is gated by
+ * {@link LoadExtensionsOptions.allowExtensions}; when refs are present but
+ * loading is not allowed, this throws so the requirement is never silently dropped.
+ *
+ * @throws When extensions are present but `allowExtensions` is not true, or when
+ *   a module cannot be imported or lacks a valid `name`.
+ */
+export declare function loadExtensionsIntoHost(host: RuleEngineHost, refs: readonly ExtensionRef[], options?: LoadExtensionsOptions): Promise<void>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/config/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/config/extensions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEjF,yEAAyE;AACzE,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAChD;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC7E,YAAY,EAAE,CAShB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GACpC,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/config/extensions.js

@@ -0,0 +1,63 @@
+import { resolve } from 'node:path';
+/** Host registries that can receive extension capabilities (fixers live on the engine, not the host). */
+const HOST_REGISTRY_BY_KIND = {
+    resolvers: 'resolvers',
+    evaluators: 'evaluators',
+    formatters: 'formatters',
+};
+/**
+ * Collect extension refs declared by a preset's `extensions` block.
+ *
+ * Paths are resolved relative to the preset file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}.
+ */
+export function collectPresetExtensions(presetName, presetDir, extensions) {
+    if (extensions === undefined)
+        return [];
+    const refs = [];
+    for (const kind of ['resolvers', 'evaluators', 'fixers', 'formatters']) {
+        for (const path of extensions[kind] ?? []) {
+            refs.push({ kind, presetName, absPath: resolve(presetDir, path) });
+        }
+    }
+    return refs;
+}
+/**
+ * Import each extension module and register its export on the matching host
+ * registry.
+ *
+ * A module must default-export (or named-export `extension`) an object with a
+ * `name: string` and the capability implementation. Loading is gated by
+ * {@link LoadExtensionsOptions.allowExtensions}; when refs are present but
+ * loading is not allowed, this throws so the requirement is never silently dropped.
+ *
+ * @throws When extensions are present but `allowExtensions` is not true, or when
+ *   a module cannot be imported or lacks a valid `name`.
+ */
+export async function loadExtensionsIntoHost(host, refs, options = {}) {
+    if (refs.length === 0)
+        return;
+    if (options.allowExtensions !== true) {
+        const first = refs[0];
+        throw new Error(`preset "${first.presetName}" declares ${first.kind} extension "${first.absPath}", but extensions are disabled — pass allowExtensions: true to load preset extension modules`);
+    }
+    for (const ref of refs) {
+        const moduleExports = (await import(ref.absPath));
+        const candidate = moduleExports.default ?? moduleExports.extension;
+        if (candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof candidate.name !== 'string') {
+            throw new Error(`preset "${ref.presetName}" extension "${ref.absPath}" must export an object with a string "name"`);
+        }
+        const name = candidate.name;
+        const registryKey = HOST_REGISTRY_BY_KIND[ref.kind];
+        if (registryKey === undefined) {
+            throw new Error(`preset "${ref.presetName}" ${ref.kind} extensions are not supported`);
+        }
+        const registry = host[registryKey];
+        if (options.logger && registry.has?.(name)) {
+            options.logger.warn(`preset "${ref.presetName}" ${ref.kind} extension overrides existing "${name}"`);
+        }
+        registry.register(name, candidate, 'extension');
+    }
+}

package/dist/config/loader.d.ts

@@ -1,12 +1,22 @@
 import { type ConstraintRule } from '../types';
 /** Options for loading rule presets. */
 export interface RuleLoaderOptions {
-    /** Project working directory. */
-    workdir: string;
-    /** Rule root directory. Defaults to ".spur/rules". */
-    rulesRoot?: string;
+    /**
+     * Ordered rule root directories, highest priority first. Presets, category
+     * folders, and rule files are resolved across all roots: the highest-priority
+     * root that provides a given relative path wins, and gaps are filled from
+     * lower-priority roots. The caller owns root discovery and ordering — this
+     * loader stays agnostic to any project layout convention.
+     */
+    roots: string[];
 }
-/** Load and normalize a preset by name. */
+/**
+ * Load and normalize a preset by name, resolving across one or more rule roots.
+ *
+ * Roots are merged in order: the first root to provide a relative path owns it,
+ * so a caller can layer project-local rules over shared/global rules and inherit
+ * the rest of a preset's categories from the lower-priority roots.
+ */
 export declare function loadPresetRules(name: string, options: RuleLoaderOptions): Promise<ConstraintRule[]>;
 /** Load a direct rule file from disk. */
 export declare function loadRuleFile(filePath: string): Promise<ConstraintRule[]>;

package/dist/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,cAAc,EAMtB,MAAM,UAAU,CAAC;AAElB,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2CAA2C;AAC3C,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAoBzG;AAED,yCAAyC;AACzC,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE9E"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,cAAc,EAMtB,MAAM,UAAU,CAAC;AAElB,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAC9B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;CACnB;AAUD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAkBzG;AAED,yCAAyC;AACzC,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE9E"}

package/dist/config/loader.js

@@ -1,18 +1,23 @@
-import { basename, dirname, extname, join, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { NodeFileSystem } from '@gobing-ai/ts-runtime';
 import { parse } from 'yaml';
 import { ConstraintRuleFileSchema, ConstraintRuleSchema, PresetDefinitionSchema, } from '../types.js';
-/** Load and normalize a preset by name. */
+/**
+ * Load and normalize a preset by name, resolving across one or more rule roots.
+ *
+ * Roots are merged in order: the first root to provide a relative path owns it,
+ * so a caller can layer project-local rules over shared/global rules and inherit
+ * the rest of a preset's categories from the lower-priority roots.
+ */
 export async function loadPresetRules(name, options) {
-    const fs = new NodeFileSystem();
-    const root = resolve(options.workdir, options.rulesRoot ?? '.spur/rules');
-    const presetPath = await findDefinitionPath(root, name);
+    const merged = await buildMergedRoots(options.roots.map((root) => resolve(root)));
+    const presetPath = findMergedPreset(merged, name);
     if (presetPath === null)
         return [];
     const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath));
     const rules = [];
     for (const entry of preset.extends) {
-        rules.push(...(await loadPresetEntry(root, entry, new Set([name]))));
+        rules.push(...(await loadPresetEntry(merged, entry, new Set([name]))));
     }
     const disabled = new Set(preset.disable ?? []);
     const normalized = rules.filter((rule) => !disabled.has(rule.id));
@@ -22,52 +27,134 @@ export async function loadPresetRules(name, options) {
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    await fs.exists(root);
     return normalized;
 }
 /** Load a direct rule file from disk. */
 export async function loadRuleFile(filePath) {
     return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
 }
-async function loadPresetEntry(root, entry, seen) {
-    const presetPath = await findDefinitionPath(root, entry);
-    if (presetPath !== null && !seen.has(entry)) {
+async function loadPresetEntry(merged, entry, seen) {
+    // Sub-preset reference — recurse, erroring on a genuine cycle.
+    const presetPath = findMergedPreset(merged, entry);
+    if (presetPath !== null) {
+        if (seen.has(entry)) {
+            throw new Error(`Circular preset dependency detected: ${[...seen, entry].join(' → ')}`);
+        }
         seen.add(entry);
         const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath));
         if (preset.success) {
             const rules = [];
             for (const child of preset.data.extends)
-                rules.push(...(await loadPresetEntry(root, child, seen)));
+                rules.push(...(await loadPresetEntry(merged, child, seen)));
             return rules.filter((rule) => !(preset.data.disable ?? []).includes(rule.id));
         }
     }
-    const categoryDir = resolve(root, entry);
-    const fs = new NodeFileSystem();
-    if (!(await fs.exists(categoryDir)))
-        return [];
-    const entries = (await fs.readDir(categoryDir)).filter((file) => /\.(ya?ml|json)$/i.test(file)).sort();
-    const rules = [];
-    for (const file of entries) {
-        rules.push(...(await loadRuleFile(join(categoryDir, file))));
+    // Category folder reference — load every winning file under that prefix.
+    if (merged.categories.has(entry)) {
+        const rules = [];
+        for (const absPath of mergedFilesInCategory(merged, entry)) {
+            rules.push(...(await loadRuleFile(absPath)));
+        }
+        return rules;
     }
-    return rules;
+    // Sub-path reference — a single winning rule file within a category.
+    const subPath = findMergedFile(merged, entry);
+    if (subPath !== null)
+        return loadRuleFile(subPath);
+    return [];
 }
-async function findDefinitionPath(root, name) {
+/**
+ * Build the merged view across ordered roots.
+ *
+ * Roots are processed in the order supplied (highest priority first). The first
+ * root to provide a given relative path owns that file; later roots are shadowed.
+ */
+async function buildMergedRoots(roots) {
     const fs = new NodeFileSystem();
-    const candidates = [
-        resolve(root, `${name}.yaml`),
-        resolve(root, `${name}.yml`),
-        resolve(root, `${name}.json`),
-        resolve(root, name, 'index.yaml'),
-        resolve(root, name, 'index.yml'),
-        resolve(root, name, 'index.json'),
-    ];
-    for (const candidate of candidates) {
-        if (await fs.exists(candidate))
-            return candidate;
+    const files = new Map();
+    const categories = new Set();
+    for (const root of roots) {
+        for (const absPath of await walkYamlFiles(fs, root)) {
+            const relPath = relative(root, absPath).split(sep).join('/');
+            const slashIdx = relPath.indexOf('/');
+            if (slashIdx > 0)
+                categories.add(relPath.slice(0, slashIdx));
+            if (!files.has(relPath))
+                files.set(relPath, absPath);
+        }
+        for (const dir of await listImmediateDirs(fs, root))
+            categories.add(dir);
+    }
+    return { files, categories };
+}
+/** Find a preset definition across roots: `<name>.{yaml,yml,json}` or `<name>/index.*`. */
+function findMergedPreset(merged, name) {
+    return firstHit(merged, [
+        `${name}.yaml`,
+        `${name}.yml`,
+        `${name}.json`,
+        `${name}/index.yaml`,
+        `${name}/index.yml`,
+        `${name}/index.json`,
+    ]);
+}
+/** Find a single rule file by sub-path entry (e.g. `typescript/tsdoc-exports`). */
+function findMergedFile(merged, entry) {
+    const hasExt = /\.(ya?ml|json)$/i.test(entry);
+    return firstHit(merged, hasExt ? [entry] : [`${entry}.yaml`, `${entry}.yml`, `${entry}.json`]);
+}
+/** Return the winning absolute path for the first matching relative candidate. */
+function firstHit(merged, relCandidates) {
+    for (const rel of relCandidates) {
+        const hit = merged.files.get(rel);
+        if (hit !== undefined)
+            return hit;
     }
     return null;
 }
+/** Winning files under a category prefix, sorted by relative path. */
+function mergedFilesInCategory(merged, category) {
+    const prefix = `${category}/`;
+    return [...merged.files.entries()]
+        .filter(([relPath]) => relPath.startsWith(prefix))
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([, absPath]) => absPath);
+}
+/** Recursively collect YAML/JSON file paths under a directory, skipping root-level `presets/`. */
+async function walkYamlFiles(fs, dir, depth = 0) {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory())
+        return [];
+    const acc = [];
+    for (const entry of (await fs.readDir(dir)).sort()) {
+        if (depth === 0 && entry === 'presets')
+            continue;
+        const fullPath = join(dir, entry);
+        const entryStat = await fs.stat(fullPath);
+        if (entryStat?.isDirectory()) {
+            acc.push(...(await walkYamlFiles(fs, fullPath, depth + 1)));
+        }
+        else if (entryStat?.isFile() && /\.(ya?ml|json)$/i.test(entry)) {
+            acc.push(fullPath);
+        }
+    }
+    return acc;
+}
+/** List immediate subdirectory names of a root (excluding `presets`). */
+async function listImmediateDirs(fs, dir) {
+    const stat = await fs.stat(dir);
+    if (stat === null || !stat.isDirectory())
+        return [];
+    const dirs = [];
+    for (const entry of await fs.readDir(dir)) {
+        if (entry === 'presets')
+            continue;
+        const entryStat = await fs.stat(join(dir, entry));
+        if (entryStat?.isDirectory())
+            dirs.push(entry);
+    }
+    return dirs;
+}
 async function readStructuredFile(path) {
     const content = await new NodeFileSystem().readFile(path);
     return extname(path) === '.json' ? JSON.parse(content) : parse(content);
@@ -86,9 +173,16 @@ function normalizeFileRules(file, sourceDir) {
         ...rule,
         severity: rule.severity ?? file.severity ?? 'error',
         include: rule.include ?? file.include,
-        exclude: rule.exclude ?? file.exclude,
+        // File-level excludes always apply; a rule's own excludes add to (not replace) them.
+        exclude: mergeExcludes(file.exclude, rule.exclude),
     }, {}, sourceDir));
 }
+/** Union of file-level and rule-level excludes, de-duplicated. Returns undefined when both empty. */
+function mergeExcludes(fileExclude, ruleExclude) {
+    if (fileExclude === undefined && ruleExclude === undefined)
+        return undefined;
+    return [...new Set([...(fileExclude ?? []), ...(ruleExclude ?? [])])];
+}
 function normalizeRule(rule, _defaults, _sourceDir) {
     return {
         ...rule,

package/dist/engine.d.ts

@@ -1,6 +1,7 @@
 import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type FixApplicationResult } from './fixers/fixers';
 import { RuleEngineHost } from './host/rule-engine-host';
-import type { ConstraintRule, RuleEngineResult, RuleEvaluator } from './types';
+import type { ConstraintRule, Fix, FixMode, RuleEngineResult, RuleEvaluator } from './types';
 /** Options for constructing a RuleEngine. */
 export interface RuleEngineOptions {
     /** Optional executor supplied to process-backed evaluators. */
@@ -12,10 +13,34 @@ export interface RuleEngineOptions {
 export declare class RuleEngine {
     /** Capability host used by this engine. */
     readonly host: RuleEngineHost;
+    /** Fixer providers keyed by evaluator type. */
+    private readonly fixers;
     constructor(options?: RuleEngineOptions);
     /** Register or replace an evaluator. */
     registerEvaluator(type: string, evaluator: RuleEvaluator): void;
     /** Evaluate all enabled rules against a working directory. */
     evaluate(rules: ConstraintRule[], workdir: string): Promise<RuleEngineResult>;
+    /**
+     * Evaluate all enabled rules and collect candidate fixes.
+     *
+     * For each rule with findings and a non-none fix mode, looks up the fixer
+     * provider by evaluator type and calls `createFixes`. The effective fix mode
+     * is the minimum of the rule's configured mode and `maxFixMode`.
+     *
+     * @param rules - Normalized rule definitions to evaluate.
+     * @param workdir - Working directory to scan.
+     * @param maxFixMode - Highest fix authority requested by the caller.
+     * @returns Findings plus fixes allowed by the requested authority.
+     */
+    evaluateWithFixes(rules: ConstraintRule[], workdir: string, maxFixMode?: FixMode): Promise<RuleEngineResult>;
+    /**
+     * Apply or preview candidate byte-range fixes.
+     *
+     * @param workdir - Working directory that fix file paths are relative to.
+     * @param fixes - Fixes to apply.
+     * @param dryRun - When true, return a diff without writing files.
+     * @returns Application details and optional diff.
+     */
+    applyFixes(workdir: string, fixes: readonly Fix[], dryRun?: boolean): Promise<FixApplicationResult>;
 }
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAqB,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGlG,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mCAAmC;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,4EAA4E;AAC5E,qBAAa,UAAU;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,OAAO,GAAE,iBAAsB;IAK3C,wCAAwC;IACxC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAI/D,8DAA8D;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmBtF"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAKH,KAAK,oBAAoB,EAE5B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAqB,cAAc,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGhH,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAC9B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mCAAmC;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,4EAA4E;AAC5E,qBAAa,UAAU;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAE5C,OAAO,GAAE,iBAAsB;IAM3C,wCAAwC;IACxC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,IAAI;IAI/D,8DAA8D;IACxD,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBnF;;;;;;;;;;;OAWG;IACG,iBAAiB,CACnB,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,OAAgB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;IAkD5B;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,EAAE,EAAE,MAAM,UAAQ,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAG1G"}

package/dist/engine.js

@@ -1,3 +1,4 @@
+import { applyFixes as applyFixesImpl, builtInFixers, FIX_MODE_RANK, } from './fixers/fixers.js';
 import { registerBuiltins } from './host/builtins.js';
 import { RuleEngineHost } from './host/rule-engine-host.js';
 import { createFinding } from './types.js';
@@ -5,9 +6,12 @@ import { createFinding } from './types.js';
 export class RuleEngine {
     /** Capability host used by this engine. */
     host;
+    /** Fixer providers keyed by evaluator type. */
+    fixers;
     constructor(options = {}) {
         this.host = options.host ?? new RuleEngineHost();
         registerBuiltins(this.host, options.processExecutor);
+        this.fixers = builtInFixers(this.host, options.processExecutor);
     }
     /** Register or replace an evaluator. */
     registerEvaluator(type, evaluator) {
@@ -28,9 +32,84 @@ export class RuleEngine {
             catch (error) {
                 findings.push(createFinding(rule, error instanceof Error ? error.message : String(error), null, {
                     code: `evaluator:${rule.evaluator.type}`,
+                    kind: 'error',
                 }));
             }
         }
         return { findings, fixes };
     }
+    /**
+     * Evaluate all enabled rules and collect candidate fixes.
+     *
+     * For each rule with findings and a non-none fix mode, looks up the fixer
+     * provider by evaluator type and calls `createFixes`. The effective fix mode
+     * is the minimum of the rule's configured mode and `maxFixMode`.
+     *
+     * @param rules - Normalized rule definitions to evaluate.
+     * @param workdir - Working directory to scan.
+     * @param maxFixMode - Highest fix authority requested by the caller.
+     * @returns Findings plus fixes allowed by the requested authority.
+     */
+    async evaluateWithFixes(rules, workdir, maxFixMode = 'auto') {
+        const findings = [];
+        const fixes = [];
+        for (const rule of rules) {
+            if (rule.enabled === false)
+                continue;
+            let ruleFindings = [];
+            let ruleEvalFixes = [];
+            try {
+                const result = await this.host.evaluators.get(rule.evaluator.type).evaluate(rule, { rule, workdir });
+                ruleFindings = result.findings;
+                ruleEvalFixes = result.fixes;
+            }
+            catch (error) {
+                ruleFindings = [
+                    createFinding(rule, error instanceof Error ? error.message : String(error), null, {
+                        code: `evaluator:${rule.evaluator.type}`,
+                        kind: 'error',
+                    }),
+                ];
+            }
+            findings.push(...ruleFindings);
+            fixes.push(...ruleEvalFixes);
+            const ruleMode = rule.fix?.mode ?? 'none';
+            const effectiveMode = effectiveFixMode(ruleMode, maxFixMode);
+            if (effectiveMode !== 'none' && ruleFindings.length > 0) {
+                const provider = this.fixers.get(rule.evaluator.type);
+                if (provider) {
+                    const effectiveFix = {
+                        mode: effectiveMode,
+                        ...(rule.fix?.replacement !== undefined ? { replacement: rule.fix.replacement } : {}),
+                        ...(rule.fix?.params !== undefined ? { params: rule.fix.params } : {}),
+                    };
+                    const providerFixes = await provider.createFixes({
+                        rule,
+                        context: { rule, workdir },
+                        findings: ruleFindings,
+                        fix: effectiveFix,
+                    });
+                    fixes.push(...providerFixes);
+                }
+            }
+        }
+        return { findings, fixes };
+    }
+    /**
+     * Apply or preview candidate byte-range fixes.
+     *
+     * @param workdir - Working directory that fix file paths are relative to.
+     * @param fixes - Fixes to apply.
+     * @param dryRun - When true, return a diff without writing files.
+     * @returns Application details and optional diff.
+     */
+    async applyFixes(workdir, fixes, dryRun = false) {
+        return applyFixesImpl(workdir, fixes, dryRun);
+    }
+}
+/** Return the lower-authority mode between what the rule requests and what the caller allows. */
+function effectiveFixMode(ruleMode, requestedMode) {
+    if (requestedMode === 'none' || ruleMode === 'none')
+        return 'none';
+    return FIX_MODE_RANK[ruleMode] <= FIX_MODE_RANK[requestedMode] ? ruleMode : requestedMode;
 }

package/dist/evaluators/coverage-gate-evaluator.d.ts

@@ -0,0 +1,21 @@
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * Coverage gate evaluator — reads an lcov tracefile and enforces per-file line
+ * coverage thresholds.
+ *
+ * Config (`evaluator.config`):
+ * - `lcovPath`: path to lcov.info (default: `coverage/lcov.info`)
+ * - `threshold`: default line-coverage percentage (default: `90`)
+ * - `include` / `exclude`: glob patterns scoping the check
+ * - `exemptions`: per-file threshold overrides with a reason
+ *
+ * A missing lcov file is reported as a single non-blocking finding rather than an
+ * error, so the gate degrades gracefully when coverage was not generated.
+ */
+export declare class CoverageGateEvaluator implements RuleEvaluator {
+    private readonly fs;
+    constructor();
+    /** Evaluate per-file coverage against the configured threshold. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=coverage-gate-evaluator.d.ts.map

package/dist/evaluators/coverage-gate-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/coverage-gate-evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAyBlB;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;;IAMpC,mEAAmE;IAC7D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA0C5F"}

package/dist/evaluators/coverage-gate-evaluator.js

@@ -0,0 +1,103 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { createFinding, } from '../types.js';
+import { matchesGlob } from './file-utils.js';
+/**
+ * Coverage gate evaluator — reads an lcov tracefile and enforces per-file line
+ * coverage thresholds.
+ *
+ * Config (`evaluator.config`):
+ * - `lcovPath`: path to lcov.info (default: `coverage/lcov.info`)
+ * - `threshold`: default line-coverage percentage (default: `90`)
+ * - `include` / `exclude`: glob patterns scoping the check
+ * - `exemptions`: per-file threshold overrides with a reason
+ *
+ * A missing lcov file is reported as a single non-blocking finding rather than an
+ * error, so the gate degrades gracefully when coverage was not generated.
+ */
+export class CoverageGateEvaluator {
+    fs;
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+    /** Evaluate per-file coverage against the configured threshold. */
+    async evaluate(rule, context) {
+        const config = (rule.evaluator.config ?? {});
+        const lcovPath = config.lcovPath
+            ? resolve(context.workdir, config.lcovPath)
+            : resolve(context.workdir, 'coverage', 'lcov.info');
+        if (!(await this.fs.exists(lcovPath))) {
+            return {
+                findings: [
+                    createFinding(rule, 'No lcov file found — coverage not generated. Skipping gate.', lcovPath, {
+                        code: 'coverage:missing-lcov',
+                    }),
+                ],
+                fixes: [],
+            };
+        }
+        const coverage = parseLcov(await this.fs.readFile(lcovPath));
+        const threshold = config.threshold ?? 90;
+        const exemptions = new Map((config.exemptions ?? []).map((entry) => [entry.path, entry]));
+        const findings = [];
+        for (const [rawPath, cov] of coverage) {
+            if (cov.linesFound === 0)
+                continue;
+            const filePath = normalizeLcovSourcePath(context.workdir, rawPath);
+            if (config.include !== undefined && !config.include.some((p) => matchesGlob(filePath, p)))
+                continue;
+            if (config.exclude?.some((p) => matchesGlob(filePath, p)))
+                continue;
+            if (isAlwaysExcluded(filePath))
+                continue;
+            const pct = Math.round((cov.linesHit / cov.linesFound) * 100);
+            const exemption = exemptions.get(filePath);
+            const effectiveThreshold = exemption?.threshold ?? threshold;
+            if (pct >= effectiveThreshold)
+                continue;
+            const message = exemption
+                ? `${pct}% line coverage (exemption: ${effectiveThreshold}%, reason: ${exemption.reason})`
+                : `${pct}% line coverage (threshold: ${effectiveThreshold}%)`;
+            findings.push(createFinding(rule, message, filePath, { code: 'coverage:below-threshold' }));
+        }
+        return { findings, fixes: [] };
+    }
+}
+/** Parse an lcov tracefile into a map of source path → coverage counts. */
+function parseLcov(raw) {
+    const result = new Map();
+    let file = null;
+    let linesFound = 0;
+    let linesHit = 0;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('SF:')) {
+            file = trimmed.slice(3);
+            linesFound = 0;
+            linesHit = 0;
+        }
+        else if (trimmed.startsWith('LF:')) {
+            linesFound = Number(trimmed.slice(3));
+        }
+        else if (trimmed.startsWith('LH:')) {
+            linesHit = Number(trimmed.slice(3));
+        }
+        else if (trimmed === 'end_of_record' && file !== null) {
+            result.set(file, { linesFound, linesHit });
+            file = null;
+        }
+    }
+    return result;
+}
+/** Standard exclusions applied regardless of config (tests, generated, deps). */
+function isAlwaysExcluded(filePath) {
+    return (filePath.includes('node_modules') ||
+        filePath.includes('.test.') ||
+        filePath.includes('.spec.') ||
+        filePath.includes('__tests__'));
+}
+/** Normalize an lcov `SF:` path to a workdir-relative forward-slash path. */
+function normalizeLcovSourcePath(workdir, filePath) {
+    const normalized = isAbsolute(filePath) ? relative(workdir, filePath) : filePath;
+    return normalized.replaceAll('\\', '/');
+}

package/dist/evaluators/exit-code-evaluator.d.ts

@@ -4,7 +4,7 @@ import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type
 export declare class ExitCodeEvaluator implements RuleEvaluator {
     private readonly executor;
     constructor(executor?: ProcessExecutor);
-    /** Run configured command and emit a finding on non-zero exit. */
+    /** Run configured command and emit a finding unless the exit code matches `successCode`. */
     evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
 }
 //# sourceMappingURL=exit-code-evaluator.d.ts.map

package/dist/evaluators/exit-code-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exit-code-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/exit-code-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAElB,2EAA2E;AAC3E,qBAAa,iBAAkB,YAAW,aAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,eAA2C;IAElF,kEAAkE;IAC5D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAe5F"}
+{"version":3,"file":"exit-code-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/exit-code-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAElB,2EAA2E;AAC3E,qBAAa,iBAAkB,YAAW,aAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,eAA2C;IAElF,4FAA4F;IACtF,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2B5F"}