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

package/src/engine.ts

@@ -1,7 +1,15 @@
 import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import {
+    applyFixes as applyFixesImpl,
+    builtInFixers,
+    type EffectiveFix,
+    FIX_MODE_RANK,
+    type FixApplicationResult,
+    type RuleFixerProvider,
+} from './fixers/fixers';
 import { registerBuiltins } from './host/builtins';
 import { RuleEngineHost } from './host/rule-engine-host';
-import type { ConstraintFinding, ConstraintRule, RuleEngineResult, RuleEvaluator } from './types';
+import type { ConstraintFinding, ConstraintRule, Fix, FixMode, RuleEngineResult, RuleEvaluator } from './types';
 import { createFinding } from './types';
 
 /** Options for constructing a RuleEngine. */
@@ -17,9 +25,13 @@ export class RuleEngine {
     /** Capability host used by this engine. */
     readonly host: RuleEngineHost;
 
+    /** Fixer providers keyed by evaluator type. */
+    private readonly fixers: Map<string, RuleFixerProvider>;
+
     constructor(options: RuleEngineOptions = {}) {
         this.host = options.host ?? new RuleEngineHost();
         registerBuiltins(this.host, options.processExecutor);
+        this.fixers = builtInFixers(this.host, options.processExecutor);
     }
 
     /** Register or replace an evaluator. */
@@ -30,7 +42,7 @@ export class RuleEngine {
     /** Evaluate all enabled rules against a working directory. */
     async evaluate(rules: ConstraintRule[], workdir: string): Promise<RuleEngineResult> {
         const findings: ConstraintFinding[] = [];
-        const fixes = [];
+        const fixes: Fix[] = [];
         for (const rule of rules) {
             if (rule.enabled === false) continue;
             try {
@@ -41,10 +53,95 @@ export class RuleEngine {
                 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: ConstraintRule[],
+        workdir: string,
+        maxFixMode: FixMode = 'auto',
+    ): Promise<RuleEngineResult> {
+        const findings: ConstraintFinding[] = [];
+        const fixes: Fix[] = [];
+
+        for (const rule of rules) {
+            if (rule.enabled === false) continue;
+
+            let ruleFindings: ConstraintFinding[] = [];
+            let ruleEvalFixes: Fix[] = [];
+            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: 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: string, fixes: readonly Fix[], dryRun = false): Promise<FixApplicationResult> {
+        return applyFixesImpl(workdir, fixes, dryRun);
+    }
+}
+
+/** Return the lower-authority mode between what the rule requests and what the caller allows. */
+function effectiveFixMode(ruleMode: FixMode, requestedMode: FixMode): FixMode {
+    if (requestedMode === 'none' || ruleMode === 'none') return 'none';
+    return FIX_MODE_RANK[ruleMode] <= FIX_MODE_RANK[requestedMode] ? ruleMode : requestedMode;
 }

package/src/evaluators/coverage-gate-evaluator.ts

@@ -0,0 +1,137 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { NodeFileSystem } from '@gobing-ai/ts-runtime';
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { matchesGlob } from './file-utils';
+
+/** Single-file coverage extracted from an lcov record. */
+interface FileCoverage {
+    linesFound: number;
+    linesHit: number;
+}
+
+/** Per-file threshold override with justification. */
+interface CoverageExemption {
+    path: string;
+    threshold: number;
+    reason: string;
+}
+
+/** Evaluator config shape extracted from `rule.evaluator.config`. */
+interface CoverageGateConfig {
+    lcovPath?: string;
+    threshold?: number;
+    include?: string[];
+    exclude?: string[];
+    exemptions?: CoverageExemption[];
+}
+
+/**
+ * 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 implements RuleEvaluator {
+    private readonly fs: NodeFileSystem;
+
+    constructor() {
+        this.fs = new NodeFileSystem();
+    }
+
+    /** Evaluate per-file coverage against the configured threshold. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = (rule.evaluator.config ?? {}) as CoverageGateConfig;
+        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: string): Map<string, FileCoverage> {
+    const result = new Map<string, FileCoverage>();
+    let file: string | null = 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: string): boolean {
+    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: string, filePath: string): string {
+    const normalized = isAbsolute(filePath) ? relative(workdir, filePath) : filePath;
+    return normalized.replaceAll('\\', '/');
+}

package/src/evaluators/exit-code-evaluator.ts

@@ -11,27 +11,45 @@ import {
 export class ExitCodeEvaluator implements RuleEvaluator {
     constructor(private readonly executor: ProcessExecutor = new NodeProcessExecutor()) {}
 
-    /** 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: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         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) return { findings: [], fixes: [] };
+        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: Record<string, unknown>, key: string): string {
+function numberConfig(config: Record<string, unknown>, key: string, fallback: number): number {
+    const value = config[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function stringConfig(config: Record<string, unknown>, key: string, fallback?: string): string {
     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}"`);
 }
 

package/src/evaluators/file-utils.ts

@@ -53,3 +53,41 @@ export function matchesAny(path: string, patterns: string[] | undefined): boolea
         return clean.length === 0 || path.includes(clean) || path.endsWith(clean);
     });
 }
+
+/**
+ * Segment-aware glob matching with `**` (any depth) and `*` (single segment).
+ *
+ * Stricter than {@link matchesAny}: it anchors the whole path, so `apps/**` does
+ * not match `vendor/apps/x`. Used by evaluators that enforce path policies
+ * (coverage scoping, test-file location) where a loose match would change findings.
+ */
+export function matchesGlob(path: string, pattern: string): boolean {
+    const normalized = path.replaceAll('\\', '/');
+    if (pattern.startsWith('**/')) {
+        const suffix = pattern.slice(3);
+        if (suffix.indexOf('*') === -1) {
+            return normalized.endsWith(suffix) || normalized.endsWith(`/${suffix}`);
+        }
+    }
+    if (pattern === normalized) return true;
+    return matchSegments(normalized.split('/'), pattern.split('/'), 0, 0);
+}
+
+/** Recursive segment-level glob matcher backing {@link matchesGlob}. */
+function matchSegments(file: string[], pattern: string[], fi: number, pi: number): boolean {
+    if (pi >= pattern.length) return fi >= file.length;
+    if (fi >= file.length) return pattern.slice(pi).every((segment) => segment === '**');
+    const pat = pattern[pi] ?? '';
+    if (pat === '**') {
+        return matchSegments(file, pattern, fi, pi + 1) || matchSegments(file, pattern, fi + 1, pi);
+    }
+    if (!matchSegment(file[fi] ?? '', pat)) return false;
+    return matchSegments(file, pattern, fi + 1, pi + 1);
+}
+
+/** Match one path segment against a pattern segment where `*` matches any run of non-`/` chars. */
+function matchSegment(segment: string, pattern: string): boolean {
+    if (pattern.indexOf('*') === -1) return segment === pattern;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
+    return new RegExp(`^${escaped}$`).test(segment);
+}

package/src/evaluators/forbidden-import-evaluator.ts

@@ -5,15 +5,45 @@ import {
     type RuleEvaluationResult,
     type RuleEvaluator,
 } from '../types';
-import { discoverFiles, readWorkdirFile } from './file-utils';
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils';
 
-/** Detects imports matching forbidden package or path prefixes. */
-export class ForbiddenImportEvaluator implements RuleEvaluator {
-    constructor() {}
+/** A forbidden entry: either an exact import specifier or a raw source pattern. */
+type ForbiddenEntry =
+    | { specifier: string; includeRequire?: boolean }
+    | { pattern: string; matchMode?: 'import' | 'usage' };
+
+/** Compiled scan entry derived from config. */
+interface ScanEntry {
+    regex: RegExp;
+    label: string;
+}
 
-    /** Evaluate import declarations against configured forbidden 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 class ForbiddenImportEvaluator implements RuleEvaluator {
+    /** Evaluate import/usage against the configured forbidden set. */
     async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
         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. */
+    private async evaluateSimple(
+        rule: ConstraintRule,
+        context: RuleContext,
+        config: Record<string, unknown>,
+    ): Promise<RuleEvaluationResult> {
         const forbidden = arrayConfig(config, 'patterns');
         const files = await discoverFiles({
             workdir: context.workdir,
@@ -24,8 +54,7 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         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));
                 if (matched !== undefined) {
@@ -40,6 +69,67 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         }
         return { findings, fixes: [] };
     }
+
+    /** Structured path: `{ forbidden: [...], scope: { include, exclude } }`. */
+    private async evaluateStructured(
+        rule: ConstraintRule,
+        context: RuleContext,
+        config: Record<string, unknown>,
+    ): Promise<RuleEvaluationResult> {
+        const scope = config.scope as { include?: unknown; exclude?: unknown } | undefined;
+        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 as ForbiddenEntry[]).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: string): string | undefined {
+    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: ForbiddenEntry): ScanEntry {
+    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: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
 function arrayConfig(config: Record<string, unknown>, key: string): string[] {
@@ -48,3 +138,7 @@ function arrayConfig(config: Record<string, unknown>, key: string): string[] {
     if (typeof value === 'string') return [value];
     throw new Error(`forbidden-import evaluator requires string[] config "${key}"`);
 }
+
+function stringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
+}

package/src/evaluators/import-boundary-evaluator.ts

@@ -0,0 +1,135 @@
+import {
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils';
+
+/**
+ * A forbidden entry within a boundary declaration.
+ *
+ * - String form: substring match against any import/export/require/dynamic-import specifier.
+ * - Object form: regex `pattern` matched against the full line (mode `usage`) or import lines
+ *   only (mode `import`).
+ */
+type ForbiddenEntry =
+    | string
+    | {
+          /** Regex pattern to match against lines. */
+          pattern: string;
+          /** `import` = restrict to import/export/require lines; `usage` = any line. Default: `import`. */
+          mode?: 'import' | 'usage';
+          /** Explicit syntax hint (informational, not enforced differently from `mode`). */
+          syntax?: string;
+      };
+
+/** A compiled boundary ready for file scanning. */
+interface CompiledBoundary {
+    scope: string;
+    excludePatterns: string[];
+    forbidden: Array<{ regex: RegExp; label: string; importOnly: boolean }>;
+}
+
+/**
+ * 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 implements RuleEvaluator {
+    /** Evaluate import boundaries across all in-scope files. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        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 as unknown as BoundaryDecl[]).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: [] };
+    }
+}
+
+/** Raw shape of one boundary declaration from the config. */
+interface BoundaryDecl {
+    scope: string;
+    forbidden: ForbiddenEntry[];
+    exclude?: string[];
+}
+
+/** Compile a raw boundary declaration into a scan-ready form. */
+function compileBoundary(decl: BoundaryDecl): CompiledBoundary {
+    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: ForbiddenEntry): { regex: RegExp; label: string; importOnly: boolean } {
+    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: string): boolean {
+    return /(?:^\s*import\b|^\s*export\b.*\bfrom\b|(?:from|require|import)\s*\(?\s*['"])/.test(line);
+}
+
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}