@gobing-ai/ts-rule-engine 0.2.8 → 0.2.9

package/src/config/extensions.ts

@@ -36,21 +36,22 @@ const HOST_REGISTRY_BY_KIND: Partial<Record<ExtensionKind, 'resolvers' | 'evalua
 };
 
 /**
- * Collect extension refs declared by a preset's `extensions` block.
+ * Collect extension refs declared by a preset's or rule file's `extensions` block.
  *
- * Paths are resolved relative to the preset file's directory. Use the returned
- * refs with {@link loadExtensionsIntoHost}.
+ * Paths are resolved relative to the declaring file's directory. Use the returned
+ * refs with {@link loadExtensionsIntoHost}. Rule files and presets are treated
+ * identically — both flow through the same trust gate at load time.
  */
-export function collectPresetExtensions(
-    presetName: string,
-    presetDir: string,
+export function collectExtensions(
+    sourceName: string,
+    sourceDir: string,
     extensions: Partial<Record<ExtensionKind, string[] | undefined>> | undefined,
 ): ExtensionRef[] {
     if (extensions === undefined) return [];
     const refs: ExtensionRef[] = [];
     for (const kind of ['resolvers', 'evaluators', 'fixers', 'formatters'] as ExtensionKind[]) {
         for (const path of extensions[kind] ?? []) {
-            refs.push({ kind, presetName, absPath: resolve(presetDir, path) });
+            refs.push({ kind, presetName: sourceName, absPath: resolve(sourceDir, path) });
         }
     }
     return refs;

package/src/config/loader.ts

@@ -5,10 +5,11 @@ import {
     type ConstraintRuleFile,
     ConstraintRuleFileSchema,
     ConstraintRuleSchema,
+    type FixMode,
     type PresetDefinition,
     PresetDefinitionSchema,
 } from '../types';
-import { collectPresetExtensions, type ExtensionRef } from './extensions';
+import { collectExtensions, type ExtensionRef } from './extensions';
 
 /** Options for loading rule presets. */
 export interface RuleLoaderOptions {
@@ -62,31 +63,76 @@ export async function loadPreset(name: string, options: RuleLoaderOptions): Prom
     if (presetPath === null) return { rules: [], extensions: [] };
     const preset = PresetDefinitionSchema.parse(await readStructuredFile(presetPath, options)) as PresetDefinition;
     const rules: ConstraintRule[] = [];
-    const extensions = collectPresetExtensions(preset.name, dirname(presetPath), preset.extensions);
+    const extensions = collectExtensions(preset.name, dirname(presetPath), preset.extensions);
     for (const entry of preset.extends) {
         const loaded = await loadPresetEntry(merged, entry, new Set([name]), options);
         rules.push(...loaded.rules);
         extensions.push(...loaded.extensions);
     }
-    const disabled = new Set(preset.disable ?? []);
-    const normalized = rules.filter((rule) => !disabled.has(rule.id));
-    for (const rule of normalized) {
-        const override = preset.overrides?.[rule.id];
+    return { rules: applyPresetControls(preset.name, rules, preset.disable, preset.overrides), extensions };
+}
+
+/** Collapse rules sharing an id to a single entry; later definitions win (last-wins merge). */
+function dedupeById(rules: readonly ConstraintRule[]): ConstraintRule[] {
+    const byId = new Map<string, ConstraintRule>();
+    for (const rule of rules) byId.set(rule.id, rule);
+    return [...byId.values()];
+}
+
+/** Apply a preset's local disable and override controls after composing its children. */
+function applyPresetControls(
+    presetName: string,
+    rules: readonly ConstraintRule[],
+    disabledIds: readonly string[] | undefined,
+    overrides: PresetDefinition['overrides'],
+): ConstraintRule[] {
+    const disabled = new Set(disabledIds ?? []);
+    const controlled = dedupeById(rules).filter((rule) => !disabled.has(rule.id));
+    for (const rule of controlled) {
+        const override = overrides?.[rule.id];
         if (override?.fix !== undefined) {
+            assertFixModeNotPromoted(presetName, rule, override.fix.mode);
             rule.fix = { ...(rule.fix ?? { mode: 'none' }), ...override.fix };
         }
     }
-    return { rules: normalized, extensions };
+    return controlled;
+}
+
+/** Fix-mode authority ordering; an override may lower but never raise a rule's mode. */
+const FIX_MODE_AUTHORITY: Record<FixMode, number> = { none: 0, suggest: 1, auto: 2 };
+
+/** Throw when a preset override would escalate a rule's fix authority above its authored level. */
+function assertFixModeNotPromoted(presetName: string, rule: ConstraintRule, overrideMode: FixMode): void {
+    const ruleMode = rule.fix?.mode ?? 'none';
+    if (FIX_MODE_AUTHORITY[overrideMode] > FIX_MODE_AUTHORITY[ruleMode]) {
+        throw new Error(
+            `Preset "${presetName}" override for rule "${rule.id}" raises fix mode from "${ruleMode}" to "${overrideMode}"; overrides may only lower fix authority`,
+        );
+    }
 }
 
 export async function loadPresetRules(name: string, options: RuleLoaderOptions): Promise<ConstraintRule[]> {
     return (await loadPreset(name, options)).rules;
 }
 
-/** Load a direct rule file from disk. */
-export async function loadRuleFile(filePath: string, options: RuleFileLoadOptions = {}): Promise<ConstraintRule[]> {
+/**
+ * Load a direct rule file from disk.
+ *
+ * Returns the normalized rules plus any extension modules the file declares in an
+ * `extensions` block, resolved to absolute paths. Rule-file extensions are treated
+ * exactly like preset extensions — pass the refs to {@link loadExtensionsIntoHost},
+ * which enforces the same `allowExtensions` trust gate. A single-rule file (one rule
+ * object, not a `rules:` array) cannot declare extensions and yields `extensions: []`.
+ */
+export async function loadRuleFile(filePath: string, options: RuleFileLoadOptions = {}): Promise<LoadedPreset> {
     const resolved = resolve(filePath);
-    return normalizeRuleFile(await readStructuredFile(resolved, options), dirname(resolved));
+    const raw = await readStructuredFile(resolved, options);
+    const rules = normalizeRuleFile(raw, resolved);
+    const parsed = ConstraintRuleFileSchema.safeParse(raw);
+    const extensions = parsed.success
+        ? collectExtensions(basename(resolved), dirname(resolved), parsed.data.extensions)
+        : [];
+    return { rules, extensions };
 }
 
 async function loadPresetEntry(
@@ -105,13 +151,16 @@ async function loadPresetEntry(
         const preset = PresetDefinitionSchema.safeParse(await readStructuredFile(presetPath, options));
         if (preset.success) {
             const rules: ConstraintRule[] = [];
-            const extensions = collectPresetExtensions(preset.data.name, dirname(presetPath), preset.data.extensions);
+            const extensions = collectExtensions(preset.data.name, dirname(presetPath), preset.data.extensions);
             for (const child of preset.data.extends) {
                 const loaded = await loadPresetEntry(merged, child, nextSeen, options);
                 rules.push(...loaded.rules);
                 extensions.push(...loaded.extensions);
             }
-            return { rules: rules.filter((rule) => !(preset.data.disable ?? []).includes(rule.id)), extensions };
+            return {
+                rules: applyPresetControls(preset.data.name, rules, preset.data.disable, preset.data.overrides),
+                extensions,
+            };
         }
     }
 
@@ -119,7 +168,7 @@ async function loadPresetEntry(
     if (merged.categories.has(entry)) {
         const rules: ConstraintRule[] = [];
         for (const absPath of mergedFilesInCategory(merged, entry)) {
-            rules.push(...normalizeRuleFile(await readStructuredFile(absPath, options), dirname(absPath)));
+            rules.push(...normalizeRuleFile(await readStructuredFile(absPath, options), absPath));
         }
         return { rules, extensions: [] };
     }
@@ -128,7 +177,7 @@ async function loadPresetEntry(
     const subPath = findMergedFile(merged, entry);
     if (subPath !== null)
         return {
-            rules: normalizeRuleFile(await readStructuredFile(subPath, options), dirname(subPath)),
+            rules: normalizeRuleFile(await readStructuredFile(subPath, options), subPath),
             extensions: [],
         };
 
@@ -234,25 +283,47 @@ async function readStructuredFile(
     });
 }
 
-function normalizeRuleFile(raw: unknown, sourceDir: string): ConstraintRule[] {
+/** A rule as parsed by Zod: severity may be absent until normalization fills it. */
+type ParsedRule = Omit<ConstraintRule, 'severity'> & { severity?: ConstraintRule['severity'] };
+
+function normalizeRuleFile(raw: unknown, filePath: string): ConstraintRule[] {
+    const sourceDir = dirname(filePath);
     const maybeFile = ConstraintRuleFileSchema.safeParse(raw);
     if (maybeFile.success) return normalizeFileRules(maybeFile.data, sourceDir);
     const maybeRule = ConstraintRuleSchema.safeParse(raw);
-    if (maybeRule.success) return [normalizeRule(maybeRule.data, {}, sourceDir)];
-    throw new Error(`Invalid rule file: ${basename(sourceDir)}`);
+    if (maybeRule.success) return [normalizeRule(maybeRule.data, sourceDir)];
+    // Surface the schema diagnostics that best fit the input: a `rules:` array means
+    // the author intended a rule file, so report against that schema; otherwise the
+    // single-rule schema. Include field paths so the offending key is obvious.
+    const isRuleFileShape = typeof raw === 'object' && raw !== null && 'rules' in raw;
+    const issues = (isRuleFileShape ? maybeFile.error : maybeRule.error).issues;
+    throw new Error(`Invalid rule file "${basename(filePath)}": ${formatIssues(issues)}`);
 }
 
-function normalizeFileRules(file: ConstraintRuleFile, sourceDir: string): ConstraintRule[] {
+/** Render Zod issues as `path: message` fragments for actionable diagnostics. */
+function formatIssues(issues: readonly { path: PropertyKey[]; message: string }[]): string {
+    return issues
+        .map((issue) => {
+            const path = issue.path.map(String).join('.');
+            return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+        })
+        .join('; ');
+}
+
+/** A rule file as parsed by Zod: rule severities may be absent until normalization. */
+type ParsedRuleFile = Omit<ConstraintRuleFile, 'rules'> & { rules: ParsedRule[] };
+
+function normalizeFileRules(file: ParsedRuleFile, sourceDir: string): ConstraintRule[] {
     return file.rules.map((rule) =>
         normalizeRule(
             {
                 ...rule,
-                severity: rule.severity ?? file.severity ?? 'error',
+                // Rule-level severity wins, then the file-level default, then 'error'.
+                severity: rule.severity ?? file.severity,
                 include: rule.include ?? file.include,
                 // File-level excludes always apply; a rule's own excludes add to (not replace) them.
                 exclude: mergeExcludes(file.exclude, rule.exclude),
             },
-            {},
             sourceDir,
         ),
     );
@@ -264,7 +335,7 @@ function mergeExcludes(fileExclude?: string[], ruleExclude?: string[]): string[]
     return [...new Set([...(fileExclude ?? []), ...(ruleExclude ?? [])])];
 }
 
-function normalizeRule(rule: ConstraintRule, _defaults: Partial<ConstraintRule>, _sourceDir: string): ConstraintRule {
+function normalizeRule(rule: ParsedRule, _sourceDir: string): ConstraintRule {
     return {
         ...rule,
         enabled: rule.enabled ?? true,

package/src/engine.ts

@@ -39,26 +39,16 @@ export class RuleEngine {
         this.host.evaluators.register(type, evaluator, 'extension');
     }
 
-    /** Evaluate all enabled rules against a working directory. */
+    /**
+     * Evaluate all enabled rules against a working directory.
+     *
+     * Thin delegate to {@link evaluateWithFixes} with `maxFixMode = 'none'`; the fix
+     * branch in that path is short-circuited by `effectiveFixMode` so callers see only
+     * findings, never auto-generated fixes. Keeps the rule loop and error-finding
+     * semantics in one place.
+     */
     async evaluate(rules: ConstraintRule[], workdir: string): Promise<RuleEngineResult> {
-        const findings: ConstraintFinding[] = [];
-        const fixes: Fix[] = [];
-        for (const rule of rules) {
-            if (rule.enabled === false) continue;
-            try {
-                const result = await this.host.evaluators.get(rule.evaluator.type).evaluate(rule, { rule, workdir });
-                findings.push(...result.findings);
-                fixes.push(...result.fixes);
-            } catch (error) {
-                findings.push(
-                    createFinding(rule, error instanceof Error ? error.message : String(error), null, {
-                        code: `evaluator:${rule.evaluator.type}`,
-                        kind: 'error',
-                    }),
-                );
-            }
-        }
-        return { findings, fixes };
+        return this.evaluateWithFixes(rules, workdir, 'none');
     }
 
     /**

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

@@ -100,8 +100,8 @@ export class CoverageGateEvaluator implements RuleEvaluator {
 function parseLcov(raw: string): Map<string, FileCoverage> {
     const result = new Map<string, FileCoverage>();
     let file: string | null = null;
-    let linesFound = 0;
-    let linesHit = 0;
+    let linesFound: number | null = 0;
+    let linesHit: number | null = 0;
     for (const line of raw.split('\n')) {
         const trimmed = line.trim();
         if (trimmed.startsWith('SF:')) {
@@ -109,17 +109,27 @@ function parseLcov(raw: string): Map<string, FileCoverage> {
             linesFound = 0;
             linesHit = 0;
         } else if (trimmed.startsWith('LF:')) {
-            linesFound = Number(trimmed.slice(3));
+            linesFound = parseCount(trimmed.slice(3));
         } else if (trimmed.startsWith('LH:')) {
-            linesHit = Number(trimmed.slice(3));
+            linesHit = parseCount(trimmed.slice(3));
         } else if (trimmed === 'end_of_record' && file !== null) {
-            result.set(file, { linesFound, linesHit });
+            // Skip records with malformed counts: a non-numeric LF:/LH: would
+            // otherwise yield NaN coverage and a spurious below-threshold finding.
+            if (linesFound !== null && linesHit !== null) {
+                result.set(file, { linesFound, linesHit });
+            }
             file = null;
         }
     }
     return result;
 }
 
+/** Parse an lcov count field; return null for non-finite or negative values. */
+function parseCount(raw: string): number | null {
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
 /** Standard exclusions applied regardless of config (tests, generated, deps). */
 function isAlwaysExcluded(filePath: string): boolean {
     return (

package/src/evaluators/file-utils.ts

@@ -34,6 +34,74 @@ export async function readWorkdirFile(workdir: string, filePath: string, fs = ne
     return await fs.readFile(resolve(workdir, filePath));
 }
 
+/** A discovered in-scope file paired with its contents. */
+export interface ScannedFile {
+    /** Workdir-relative path. */
+    readonly file: string;
+    /** Full file contents. */
+    readonly content: string;
+}
+
+/** How `scanFiles` matches `include` / `exclude` against discovered paths. */
+export type ScanMatchMode = 'loose' | 'glob';
+
+/** Options for {@link scanFiles}. */
+export interface ScanFilesOptions {
+    /** Working directory to walk. */
+    workdir: string;
+    /** Include patterns; semantics depend on `matchMode`. Undefined/empty = all files. */
+    include?: string[];
+    /** Exclude patterns; semantics depend on `matchMode`. */
+    exclude?: string[];
+    /**
+     * Scope matching policy:
+     * - `loose` — substring/suffix fragments via {@link matchesAny} (back-compat for
+     *   evaluators that historically accepted bare fragments like `.ts` or `src/`).
+     * - `glob` — anchored `**`/`*` globs via {@link matchesGlob}.
+     *
+     * The two are NOT interchangeable: a bare `src/` matches different sets under each.
+     * Each evaluator declares the mode that preserves its existing behavior.
+     */
+    matchMode: ScanMatchMode;
+    /** Filesystem adapter. */
+    fs?: FileSystem;
+}
+
+/**
+ * Discover in-scope files and read each once — the shared scaffolding behind the
+ * line-scanning evaluators. Owns discovery, scope filtering (per `matchMode`), and
+ * reads, so each evaluator is left with only its own matcher.
+ *
+ * Scope is a parameter, not assumed one-per-rule: callers that scan under several
+ * scopes (e.g. import boundaries) pass no `include` here and apply their own globs to
+ * the returned paths.
+ */
+export async function scanFiles(options: ScanFilesOptions): Promise<ScannedFile[]> {
+    const fs = options.fs ?? new NodeFileSystem();
+    const files =
+        options.matchMode === 'loose'
+            ? await discoverFiles({ workdir: options.workdir, include: options.include, exclude: options.exclude, fs })
+            : await discoverFilesByGlob(options.workdir, options.include, options.exclude, fs);
+    const scanned: ScannedFile[] = [];
+    for (const file of files) {
+        scanned.push({ file, content: await readWorkdirFile(options.workdir, file, fs) });
+    }
+    return scanned;
+}
+
+/** Discover files then filter with anchored globs (strict mode for {@link scanFiles}). */
+async function discoverFilesByGlob(
+    workdir: string,
+    include: string[] | undefined,
+    exclude: string[] | undefined,
+    fs: FileSystem,
+): Promise<string[]> {
+    const all = await discoverFiles({ workdir, fs });
+    return all
+        .filter((file) => include === undefined || include.length === 0 || include.some((g) => matchesGlob(file, g)))
+        .filter((file) => exclude === undefined || !exclude.some((g) => matchesGlob(file, g)));
+}
+
 /** Ensure a path is workdir-relative for findings. */
 export function relativeToWorkdir(workdir: string, path: string): string {
     return relative(workdir, resolve(path));
@@ -91,3 +159,27 @@ function matchSegment(segment: string, pattern: string): boolean {
     const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replaceAll('*', '[^/]*');
     return new RegExp(`^${escaped}$`).test(segment);
 }
+
+/** Escape a string for safe literal use inside a `RegExp` source. */
+export function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Return the value as a `string[]` when every item is a string, otherwise undefined. */
+export function stringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? (value as string[]) : undefined;
+}
+
+/**
+ * Split a leading ripgrep/PCRE-style `(?flags)` inline group off a regex source.
+ *
+ * Returns the JS-relevant flags found in the group (filtered to `imsu`) and the
+ * remaining source with the group removed. When no leading group is present, returns
+ * empty flags and the source unchanged. Shared by evaluators that accept inline flags.
+ */
+export function parseInlineFlags(source: string): { flags: string; rest: string } {
+    const match = /^\(\?([a-z]+)\)/.exec(source);
+    if (!match) return { flags: '', rest: source };
+    const flags = [...(match[1] ?? '')].filter((flag) => 'imsu'.includes(flag)).join('');
+    return { flags, rest: source.slice(match[0].length) };
+}

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

@@ -5,7 +5,7 @@ import {
     type RuleEvaluationResult,
     type RuleEvaluator,
 } from '../types';
-import { discoverFiles, matchesGlob, readWorkdirFile } from './file-utils';
+import { escapeRegExp, scanFiles, stringArray } from './file-utils';
 
 /** A forbidden entry: either an exact import specifier or a raw source pattern. */
 type ForbiddenEntry =
@@ -28,6 +28,11 @@ interface ScanEntry {
  *   entry is an exact `specifier` (also matching require/dynamic forms unless
  *   `includeRequire:false`) or a raw `pattern`, scoped by `scope.include` /
  *   `scope.exclude` globs.
+ *
+ * Trust assumption: rule config is trusted input. A raw `pattern` is compiled with
+ * `new RegExp` and run per line without a backtracking bound, so a
+ * catastrophic-backtracking pattern is the rule author's responsibility. Runtime
+ * ReDoS hardening is deferred (see task 0003).
  */
 export class ForbiddenImportEvaluator implements RuleEvaluator {
     /** Evaluate import/usage against the configured forbidden set. */
@@ -45,14 +50,15 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         config: Record<string, unknown>,
     ): Promise<RuleEvaluationResult> {
         const forbidden = arrayConfig(config, 'patterns');
-        const files = await discoverFiles({
+        const files = await scanFiles({
             workdir: context.workdir,
             include: rule.include ?? ['.ts', '.tsx', '.js', '.jsx'],
             exclude: rule.exclude,
+            matchMode: 'loose',
         });
         const findings = [];
-        for (const file of files) {
-            const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
+        for (const { file, content } of files) {
+            const lines = content.split('\n');
             for (const [index, line] of lines.entries()) {
                 const imported = importSpecifier(line);
                 if (imported === undefined) continue;
@@ -84,15 +90,12 @@ export class ForbiddenImportEvaluator implements RuleEvaluator {
         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)));
+        // Anchored `**`-glob scoping: scanFiles' 'glob' mode applies matchesGlob precisely.
+        const files = await scanFiles({ workdir: context.workdir, include, exclude, matchMode: 'glob' });
 
         const findings = [];
-        for (const file of files) {
-            const lines = (await readWorkdirFile(context.workdir, file)).split('\n');
+        for (const { file, content } of files) {
+            const lines = content.split('\n');
             for (const [index, line] of lines.entries()) {
                 const hit = entries.find((entry) => entry.regex.test(line));
                 if (hit !== undefined) {
@@ -128,17 +131,9 @@ function compileEntry(entry: ForbiddenEntry): ScanEntry {
     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[] {
     const value = config[key];
     if (Array.isArray(value) && value.every((item) => typeof item === 'string')) return value;
     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

@@ -5,25 +5,7 @@ import {
     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;
-      };
+import { escapeRegExp, matchesGlob, scanFiles } from './file-utils';
 
 /** A compiled boundary ready for file scanning. */
 interface CompiledBoundary {
@@ -44,6 +26,11 @@ interface CompiledBoundary {
  *   - `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.
+ *
+ * Trust assumption: rule config is trusted input. A `pattern` is compiled with
+ * `new RegExp` and run per line without a backtracking bound, so a
+ * catastrophic-backtracking pattern is the rule author's responsibility. Runtime
+ * ReDoS hardening is deferred (see task 0003).
  */
 export class ImportBoundaryEvaluator implements RuleEvaluator {
     /** Evaluate import boundaries across all in-scope files. */
@@ -54,19 +41,18 @@ export class ImportBoundaryEvaluator implements RuleEvaluator {
             throw new Error('import-boundary evaluator requires non-empty array config "boundaries"');
         }
 
-        const compiled = (boundaries as unknown as BoundaryDecl[]).map((b) => compileBoundary(b));
+        const compiled = boundaries.map((boundary, index) => compileBoundary(boundary, index));
 
-        // Discover all files once; filter per boundary below.
-        const allFiles = await discoverFiles({ workdir: context.workdir });
+        // Scan all files once (read up front); apply each boundary's globs in-memory below.
+        const allFiles = await scanFiles({ workdir: context.workdir, matchMode: 'glob' });
 
         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)));
+                .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);
+            for (const { file, content } of inScope) {
                 const lines = content.split('\n');
                 for (const [index, line] of lines.entries()) {
                     for (const entry of boundary.forbidden) {
@@ -88,24 +74,37 @@ export class ImportBoundaryEvaluator implements RuleEvaluator {
     }
 }
 
-/** 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 {
+function compileBoundary(decl: unknown, index: number): CompiledBoundary {
+    if (!isRecord(decl)) {
+        throw new Error(`import-boundary evaluator requires object config "boundaries[${index}]"`);
+    }
+    const scope = decl.scope;
+    if (typeof scope !== 'string' || scope.length === 0) {
+        throw new Error(`import-boundary evaluator requires string config "boundaries[${index}].scope"`);
+    }
+    const forbidden = decl.forbidden;
+    if (!Array.isArray(forbidden) || forbidden.length === 0) {
+        throw new Error(`import-boundary evaluator requires non-empty array config "boundaries[${index}].forbidden"`);
+    }
+    const exclude = decl.exclude;
+    if (exclude !== undefined && !isStringArray(exclude)) {
+        throw new Error(`import-boundary evaluator requires string[] config "boundaries[${index}].exclude"`);
+    }
+
     return {
-        scope: decl.scope,
-        excludePatterns: decl.exclude ?? [],
-        forbidden: decl.forbidden.map((entry) => compileEntry(entry)),
+        scope,
+        excludePatterns: exclude ?? [],
+        forbidden: forbidden.map((entry, entryIndex) => compileEntry(entry, index, entryIndex)),
     };
 }
 
 /** Compile one forbidden entry into a regex + metadata. */
-function compileEntry(entry: ForbiddenEntry): { regex: RegExp; label: string; importOnly: boolean } {
+function compileEntry(
+    entry: unknown,
+    boundaryIndex: number,
+    entryIndex: number,
+): { regex: RegExp; label: string; importOnly: boolean } {
     if (typeof entry === 'string') {
         // String form: match as an import specifier substring.
         const escaped = escapeRegExp(entry);
@@ -116,6 +115,17 @@ function compileEntry(entry: ForbiddenEntry): { regex: RegExp; label: string; im
         };
     }
 
+    if (!isRecord(entry) || typeof entry.pattern !== 'string' || entry.pattern.length === 0) {
+        throw new Error(
+            `import-boundary evaluator requires string config "boundaries[${boundaryIndex}].forbidden[${entryIndex}].pattern"`,
+        );
+    }
+    if (entry.mode !== undefined && entry.mode !== 'import' && entry.mode !== 'usage') {
+        throw new Error(
+            `import-boundary evaluator requires "import" or "usage" config "boundaries[${boundaryIndex}].forbidden[${entryIndex}].mode"`,
+        );
+    }
+
     // Object form with `pattern`.
     const importOnly = (entry.mode ?? 'import') !== 'usage';
     return {
@@ -130,6 +140,12 @@ 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, '\\$&');
+/** Return true when value is a plain object-ish config record. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Return true when every array item is a string. */
+function isStringArray(value: unknown): value is string[] {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }