@gobing-ai/ts-rule-engine 0.2.6 → 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.js

@@ -34,9 +34,12 @@ export async function loadRuleFile(filePath) {
     return normalizeRuleFile(await readStructuredFile(resolve(filePath)), dirname(resolve(filePath)));
 }
 async function loadPresetEntry(merged, entry, seen) {
-    // Sub-preset reference — recurse (cycle-guarded).
+    // Sub-preset reference — recurse, erroring on a genuine cycle.
     const presetPath = findMergedPreset(merged, entry);
-    if (presetPath !== null && !seen.has(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) {
@@ -170,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/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"}

package/dist/evaluators/exit-code-evaluator.js

@@ -6,28 +6,41 @@ export class ExitCodeEvaluator {
     constructor(executor = new NodeProcessExecutor()) {
         this.executor = executor;
     }
-    /** Run configured command and emit a finding on non-zero exit. */
+    /** Run configured command and emit a finding unless the exit code matches `successCode`. */
     async evaluate(rule, context) {
         const config = rule.evaluator.config ?? {};
         const command = stringConfig(config, 'command');
         const args = arrayConfig(config, 'args', []);
-        const result = await this.executor.run({ command, args, cwd: context.workdir, rejectOnError: false });
-        if (result.exitCode === 0)
+        const successCode = numberConfig(config, 'successCode', 0);
+        const timeout = numberConfig(config, 'timeout', 60_000);
+        const result = await this.executor.run({
+            command,
+            args,
+            cwd: context.workdir,
+            timeout,
+            rejectOnError: false,
+            label: 'exit-code',
+        });
+        if (result.exitCode === successCode)
             return { findings: [], fixes: [] };
+        const template = stringConfig(config, 'message', `Command failed (exit {code}): ${command} ${args.join(' ')}`.trim());
+        const message = template.replaceAll('{code}', String(result.exitCode));
         return {
-            findings: [
-                createFinding(rule, `Command failed: ${command} ${args.join(' ')}`.trim(), null, {
-                    code: 'exit-code:failed',
-                }),
-            ],
+            findings: [createFinding(rule, message, null, { code: 'exit-code:failed' })],
             fixes: [],
         };
     }
 }
-function stringConfig(config, key) {
+function numberConfig(config, key, fallback) {
+    const value = config[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function stringConfig(config, key, fallback) {
     const value = config[key];
     if (typeof value === 'string')
         return value;
+    if (fallback !== undefined)
+        return fallback;
     throw new Error(`exit-code evaluator requires string config "${key}"`);
 }
 function arrayConfig(config, key, fallback) {

package/dist/evaluators/forbidden-import-evaluator.d.ts

@@ -1,8 +1,21 @@
 import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
-/** Detects imports matching forbidden package or path prefixes. */
+/**
+ * Detects forbidden imports / API usage.
+ *
+ * Two config shapes are supported:
+ * - Simple: `{ patterns: string[] }` — substring match against any import specifier,
+ *   scoped by the rule's own `include` / `exclude`.
+ * - Structured: `{ forbidden: [...], scope: { include, exclude } }` — each forbidden
+ *   entry is an exact `specifier` (also matching require/dynamic forms unless
+ *   `includeRequire:false`) or a raw `pattern`, scoped by `scope.include` /
+ *   `scope.exclude` globs.
+ */
 export declare class ForbiddenImportEvaluator implements RuleEvaluator {
-    constructor();
-    /** Evaluate import declarations against configured forbidden prefixes. */
+    /** Evaluate import/usage against the configured forbidden set. */
     evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+    /** Legacy path: `{ patterns: string[] }`, substring-matched against import specifiers. */
+    private evaluateSimple;
+    /** Structured path: `{ forbidden: [...], scope: { include, exclude } }`. */
+    private evaluateStructured;
 }
 //# sourceMappingURL=forbidden-import-evaluator.d.ts.map

package/dist/evaluators/forbidden-import-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forbidden-import-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/forbidden-import-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB,mEAAmE;AACnE,qBAAa,wBAAyB,YAAW,aAAa;;IAG1D,0EAA0E;IACpE,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA4B5F"}
+{"version":3,"file":"forbidden-import-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/forbidden-import-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAclB;;;;;;;;;;GAUG;AACH,qBAAa,wBAAyB,YAAW,aAAa;IAC1D,kEAAkE;IAC5D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOzF,0FAA0F;YAC5E,cAAc;IA+B5B,4EAA4E;YAC9D,kBAAkB;CAoCnC"}

package/dist/evaluators/forbidden-import-evaluator.js

@@ -1,11 +1,26 @@
 import { createFinding, } from '../types.js';
-import { discoverFiles, readWorkdirFile } from './file-utils.js';
-/** Detects imports matching forbidden package or path prefixes. */
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils.js';
+/**
+ * Detects forbidden imports / API usage.
+ *
+ * Two config shapes are supported:
+ * - Simple: `{ patterns: string[] }` — substring match against any import specifier,
+ *   scoped by the rule's own `include` / `exclude`.
+ * - Structured: `{ forbidden: [...], scope: { include, exclude } }` — each forbidden
+ *   entry is an exact `specifier` (also matching require/dynamic forms unless
+ *   `includeRequire:false`) or a raw `pattern`, scoped by `scope.include` /
+ *   `scope.exclude` globs.
+ */
 export class ForbiddenImportEvaluator {
-    constructor() { }
-    /** Evaluate import declarations against configured forbidden prefixes. */
+    /** Evaluate import/usage against the configured forbidden set. */
     async evaluate(rule, context) {
         const config = rule.evaluator.config ?? {};
+        return Array.isArray(config.forbidden)
+            ? this.evaluateStructured(rule, context, config)
+            : this.evaluateSimple(rule, context, config);
+    }
+    /** Legacy path: `{ patterns: string[] }`, substring-matched against import specifiers. */
+    async evaluateSimple(rule, context, config) {
         const forbidden = arrayConfig(config, 'patterns');
         const files = await discoverFiles({
             workdir: context.workdir,
@@ -16,8 +31,7 @@ export class ForbiddenImportEvaluator {
         for (const file of files) {
             const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
             for (const [index, line] of lines.entries()) {
-                const imported = /(?:from\s+|import\s*\(|^\s*import\s*)['"](?<specifier>[^'"]+)['"]/.exec(line)?.groups
-                    ?.specifier;
+                const imported = importSpecifier(line);
                 if (imported === undefined)
                     continue;
                 const matched = forbidden.find((pattern) => imported.includes(pattern));
@@ -31,6 +45,54 @@ export class ForbiddenImportEvaluator {
         }
         return { findings, fixes: [] };
     }
+    /** Structured path: `{ forbidden: [...], scope: { include, exclude } }`. */
+    async evaluateStructured(rule, context, config) {
+        const scope = config.scope;
+        const include = stringArray(scope?.include);
+        if (include === undefined) {
+            throw new Error('forbidden-import evaluator requires string[] config "scope.include"');
+        }
+        const exclude = stringArray(scope?.exclude) ?? [];
+        const entries = config.forbidden.map(compileEntry);
+        // Discover all source files, then apply scope globs precisely (discoverFiles'
+        // include matching is intentionally loose, so it cannot do `**`-anchored scoping).
+        const files = (await discoverFiles({ workdir: context.workdir }))
+            .filter((file) => include.some((glob) => matchesGlob(file, glob)))
+            .filter((file) => !exclude.some((glob) => matchesGlob(file, glob)));
+        const findings = [];
+        for (const file of files) {
+            const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
+            for (const [index, line] of lines.entries()) {
+                const hit = entries.find((entry) => entry.regex.test(line));
+                if (hit !== undefined) {
+                    findings.push(createFinding(rule, `Forbidden import/usage of "${hit.label}"`, file, {
+                        line: index + 1,
+                        code: 'import:forbidden',
+                    }));
+                }
+            }
+        }
+        return { findings, fixes: [] };
+    }
+}
+/** Extract the specifier from an import/require/dynamic-import line, if any. */
+function importSpecifier(line) {
+    return /(?:from\s+|import\s*\(|^\s*import\s*)['"](?<specifier>[^'"]+)['"]/.exec(line)?.groups?.specifier;
+}
+/** Compile a forbidden entry into a line-matching regex. */
+function compileEntry(entry) {
+    if ('specifier' in entry) {
+        const spec = escapeRegExp(entry.specifier);
+        const boundary = `(?:/|['"])`;
+        const source = entry.includeRequire === false
+            ? `from\\s+['"]${spec}${boundary}`
+            : `(?:from\\s+|require\\(\\s*|import\\(\\s*)['"]${spec}${boundary}`;
+        return { regex: new RegExp(source), label: entry.specifier };
+    }
+    return { regex: new RegExp(entry.pattern), label: entry.pattern };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function arrayConfig(config, key) {
     const value = config[key];
@@ -40,3 +102,6 @@ function arrayConfig(config, key) {
         return [value];
     throw new Error(`forbidden-import evaluator requires string[] config "${key}"`);
 }
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+}

package/dist/evaluators/import-boundary-evaluator.d.ts

@@ -0,0 +1,19 @@
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * Enforces architectural import boundaries without spawning a subprocess.
+ *
+ * Files matching a boundary's `scope` glob are scanned in-memory. Each forbidden
+ * entry is either a string (matched as an import-specifier substring) or an object
+ * with a `pattern` regex and an optional `mode` (`import` | `usage`).
+ *
+ * ## Options (in `evaluator.config`)
+ * - `boundaries` — non-empty array of boundary declarations:
+ *   - `scope` — glob pattern selecting files this boundary applies to.
+ *   - `forbidden` — array of strings or `{ pattern, mode?, syntax? }` objects.
+ *   - `exclude` — optional globs within the scope to ignore.
+ */
+export declare class ImportBoundaryEvaluator implements RuleEvaluator {
+    /** Evaluate import boundaries across all in-scope files. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=import-boundary-evaluator.d.ts.map

package/dist/evaluators/import-boundary-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-boundary-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/import-boundary-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AA4BlB;;;;;;;;;;;;GAYG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IACzD,4DAA4D;IACtD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAuC5F"}

package/dist/evaluators/import-boundary-evaluator.js

@@ -0,0 +1,85 @@
+import { createFinding, } from '../types.js';
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils.js';
+/**
+ * Enforces architectural import boundaries without spawning a subprocess.
+ *
+ * Files matching a boundary's `scope` glob are scanned in-memory. Each forbidden
+ * entry is either a string (matched as an import-specifier substring) or an object
+ * with a `pattern` regex and an optional `mode` (`import` | `usage`).
+ *
+ * ## Options (in `evaluator.config`)
+ * - `boundaries` — non-empty array of boundary declarations:
+ *   - `scope` — glob pattern selecting files this boundary applies to.
+ *   - `forbidden` — array of strings or `{ pattern, mode?, syntax? }` objects.
+ *   - `exclude` — optional globs within the scope to ignore.
+ */
+export class ImportBoundaryEvaluator {
+    /** Evaluate import boundaries across all in-scope files. */
+    async evaluate(rule, context) {
+        const config = rule.evaluator.config ?? {};
+        const boundaries = config.boundaries;
+        if (!Array.isArray(boundaries) || boundaries.length === 0) {
+            throw new Error('import-boundary evaluator requires non-empty array config "boundaries"');
+        }
+        const compiled = boundaries.map((b) => compileBoundary(b));
+        // Discover all files once; filter per boundary below.
+        const allFiles = await discoverFiles({ workdir: context.workdir });
+        const findings = [];
+        for (const boundary of compiled) {
+            const inScope = allFiles
+                .filter((file) => matchesGlob(file, boundary.scope))
+                .filter((file) => !boundary.excludePatterns.some((ex) => matchesGlob(file, ex)));
+            for (const file of inScope) {
+                const content = await readWorkdirFile(context.workdir, file);
+                const lines = content.split('\n');
+                for (const [index, line] of lines.entries()) {
+                    for (const entry of boundary.forbidden) {
+                        if (entry.importOnly && !isImportLine(line))
+                            continue;
+                        if (entry.regex.test(line)) {
+                            findings.push(createFinding(rule, `forbidden in boundary "${boundary.scope}": ${entry.label}`, file, {
+                                line: index + 1,
+                                code: 'import-boundary:violation',
+                            }));
+                        }
+                    }
+                }
+            }
+        }
+        return { findings, fixes: [] };
+    }
+}
+/** Compile a raw boundary declaration into a scan-ready form. */
+function compileBoundary(decl) {
+    return {
+        scope: decl.scope,
+        excludePatterns: decl.exclude ?? [],
+        forbidden: decl.forbidden.map((entry) => compileEntry(entry)),
+    };
+}
+/** Compile one forbidden entry into a regex + metadata. */
+function compileEntry(entry) {
+    if (typeof entry === 'string') {
+        // String form: match as an import specifier substring.
+        const escaped = escapeRegExp(entry);
+        return {
+            regex: new RegExp(`(?:from\\s+|require\\(\\s*|import\\(\\s*)['"](?:[^'"]*)?${escaped}(?:[^'"]*)?['"]`),
+            label: entry,
+            importOnly: true,
+        };
+    }
+    // Object form with `pattern`.
+    const importOnly = (entry.mode ?? 'import') !== 'usage';
+    return {
+        regex: new RegExp(entry.pattern),
+        label: entry.pattern,
+        importOnly,
+    };
+}
+/** Return true when a source line is an import/export/require/dynamic-import statement. */
+function isImportLine(line) {
+    return /(?:^\s*import\b|^\s*export\b.*\bfrom\b|(?:from|require|import)\s*\(?\s*['"])/.test(line);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/evaluators/path-evaluator.d.ts

@@ -1,9 +1,22 @@
 import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
-/** Evaluates file or directory existence constraints. */
+/**
+ * Evaluates file/directory presence constraints.
+ *
+ * Two config shapes are supported:
+ * - Glob form: `{ must: 'present' | 'absent' }` scoped by the rule's `include` /
+ *   `exclude` globs. `present` flags each include glob that matches zero files;
+ *   `absent` flags each in-scope file that exists.
+ * - Explicit form: `{ paths: string[], mode?: 'require' | 'forbid' }` — checks the
+ *   exact paths relative to the workdir (`require` = must exist, `forbid` = must not).
+ */
 export declare class PathEvaluator implements RuleEvaluator {
     private readonly fs;
     constructor();
-    /** Evaluate required or forbidden paths. */
+    /** Evaluate required or forbidden paths in either config form. */
     evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+    /** Glob form driven by `must` + the rule's include/exclude globs. */
+    private evaluateGlob;
+    /** Explicit form: exact `paths` checked with `mode` require/forbid. */
+    private evaluateExplicit;
 }
 //# sourceMappingURL=path-evaluator.d.ts.map

package/dist/evaluators/path-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/path-evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAElB,yDAAyD;AACzD,qBAAa,aAAc,YAAW,aAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;;IAMpC,4CAA4C;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAgB5F"}
+{"version":3,"file":"path-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/path-evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;GASG;AACH,qBAAa,aAAc,YAAW,aAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;;IAMpC,kEAAkE;IAC5D,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IASzF,qEAAqE;YACvD,YAAY;IAuC1B,uEAAuE;YACzD,gBAAgB;CAmBjC"}