@kevinrabun/judges-cli 3.124.0

package/dist/config.js

@@ -0,0 +1,694 @@
+// ─── Configuration Module ────────────────────────────────────────────────────
+// Loads and validates .judgesrc / .judgesrc.json project configuration.
+// Supports cascading config: child directories override parent settings.
+// ──────────────────────────────────────────────────────────────────────────────
+import { existsSync, readFileSync } from "fs";
+import { resolve, dirname, join } from "path";
+import { registerPlugin } from "./plugins.js";
+import { ConfigError } from "./errors.js";
+import { normalizeLanguage } from "./language-patterns.js";
+import { matchGlobPath } from "./tools/command-safety.js";
+// Expand ${ENV_VAR} placeholders in config strings
+export function expandEnvPlaceholders(content) {
+    if (!content)
+        return content;
+    return content.replace(/\$\{([^}]{1,100})\}/g, (_match, varName) => {
+        const envVal = process.env[varName];
+        return envVal !== undefined ? envVal : "";
+    });
+}
+const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low", "info"]);
+const VALID_FORMATS = new Set(["text", "json", "sarif", "markdown", "html", "junit", "codeclimate"]);
+/** Numeric rank for severity comparison (lower = stricter). */
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+function severityRank(s) {
+    return SEVERITY_RANK[s] ?? 4;
+}
+/**
+ * Validate a JudgeDefinition object. Returns an array of error messages. Empty
+ * array means validation passed.
+ */
+export function validateJudgeDefinition(def) {
+    const errors = [];
+    const requiredStringFields = [
+        "id",
+        "name",
+        "domain",
+        "description",
+        "rulePrefix",
+        "tableDescription",
+        "promptDescription",
+        "systemPrompt",
+    ];
+    for (const field of requiredStringFields) {
+        const val = def[field];
+        if (typeof val !== "string" || val.trim().length === 0) {
+            errors.push(`Missing or invalid field: ${String(field)}`);
+        }
+    }
+    return errors;
+}
+/**
+ * Parse a JSON string into a JudgesConfig, with validation.
+ */
+export function parseConfig(jsonStr) {
+    let raw;
+    try {
+        raw = JSON.parse(jsonStr);
+    }
+    catch {
+        throw new ConfigError("Invalid .judgesrc: not valid JSON");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new ConfigError("Invalid .judgesrc: root must be a JSON object");
+    }
+    const obj = raw;
+    const config = {};
+    // extends
+    if (obj.extends !== undefined) {
+        if (typeof obj.extends === "string") {
+            config.extends = obj.extends;
+        }
+        else if (Array.isArray(obj.extends) && obj.extends.every((e) => typeof e === "string")) {
+            config.extends = obj.extends;
+        }
+        else {
+            throw new ConfigError('Invalid .judgesrc: "extends" must be a string or array of strings');
+        }
+    }
+    // disabledRules
+    if (obj.disabledRules !== undefined) {
+        if (!Array.isArray(obj.disabledRules) || !obj.disabledRules.every((r) => typeof r === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "disabledRules" must be an array of strings');
+        }
+        config.disabledRules = obj.disabledRules;
+    }
+    // disabledJudges
+    if (obj.disabledJudges !== undefined) {
+        if (!Array.isArray(obj.disabledJudges) || !obj.disabledJudges.every((r) => typeof r === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "disabledJudges" must be an array of strings');
+        }
+        config.disabledJudges = obj.disabledJudges;
+    }
+    // minSeverity
+    if (obj.minSeverity !== undefined) {
+        if (typeof obj.minSeverity !== "string" || !VALID_SEVERITIES.has(obj.minSeverity)) {
+            throw new ConfigError('Invalid .judgesrc: "minSeverity" must be one of critical, high, medium, low, info');
+        }
+        config.minSeverity = obj.minSeverity;
+    }
+    // languages
+    if (obj.languages !== undefined) {
+        if (!Array.isArray(obj.languages) || !obj.languages.every((l) => typeof l === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "languages" must be an array of strings');
+        }
+        config.languages = obj.languages;
+    }
+    // ruleOverrides
+    if (obj.ruleOverrides !== undefined) {
+        if (typeof obj.ruleOverrides !== "object" || obj.ruleOverrides === null || Array.isArray(obj.ruleOverrides)) {
+            throw new ConfigError('Invalid .judgesrc: "ruleOverrides" must be an object');
+        }
+        const overrides = {};
+        for (const [key, val] of Object.entries(obj.ruleOverrides)) {
+            if (typeof val !== "object" || val === null) {
+                throw new ConfigError(`Invalid .judgesrc: ruleOverrides["${key}"] must be an object`);
+            }
+            const entry = val;
+            const override = {};
+            if (entry.disabled !== undefined) {
+                override.disabled = Boolean(entry.disabled);
+            }
+            if (entry.severity !== undefined) {
+                if (typeof entry.severity !== "string" || !VALID_SEVERITIES.has(entry.severity)) {
+                    throw new ConfigError(`Invalid .judgesrc: ruleOverrides["${key}"].severity must be a valid severity`);
+                }
+                override.severity = entry.severity;
+            }
+            overrides[key] = override;
+        }
+        config.ruleOverrides = overrides;
+    }
+    // exclude
+    if (obj.exclude !== undefined) {
+        if (!Array.isArray(obj.exclude) || !obj.exclude.every((e) => typeof e === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "exclude" must be an array of strings');
+        }
+        config.exclude = obj.exclude;
+    }
+    // include
+    if (obj.include !== undefined) {
+        if (!Array.isArray(obj.include) || !obj.include.every((e) => typeof e === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "include" must be an array of strings');
+        }
+        config.include = obj.include;
+    }
+    // maxFiles
+    if (obj.maxFiles !== undefined) {
+        if (typeof obj.maxFiles !== "number" || !Number.isInteger(obj.maxFiles) || obj.maxFiles < 1) {
+            throw new ConfigError('Invalid .judgesrc: "maxFiles" must be an integer >= 1');
+        }
+        config.maxFiles = obj.maxFiles;
+    }
+    // preset
+    if (obj.preset !== undefined) {
+        if (typeof obj.preset !== "string") {
+            throw new ConfigError('Invalid .judgesrc: "preset" must be a string');
+        }
+        config.preset = obj.preset;
+    }
+    // failOnFindings
+    if (obj.failOnFindings !== undefined) {
+        if (typeof obj.failOnFindings !== "boolean") {
+            throw new ConfigError('Invalid .judgesrc: "failOnFindings" must be a boolean');
+        }
+        config.failOnFindings = obj.failOnFindings;
+    }
+    // baseline
+    if (obj.baseline !== undefined) {
+        if (typeof obj.baseline !== "string") {
+            throw new ConfigError('Invalid .judgesrc: "baseline" must be a string (file path)');
+        }
+        config.baseline = obj.baseline;
+    }
+    // format
+    if (obj.format !== undefined) {
+        if (typeof obj.format !== "string" || !VALID_FORMATS.has(obj.format)) {
+            throw new ConfigError('Invalid .judgesrc: "format" must be one of text, json, sarif, markdown, html, junit, codeclimate');
+        }
+        config.format = obj.format;
+    }
+    // plugins
+    if (obj.plugins !== undefined) {
+        if (!Array.isArray(obj.plugins) || !obj.plugins.every((p) => typeof p === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "plugins" must be an array of strings (module specifiers)');
+        }
+        config.plugins = obj.plugins;
+    }
+    // failOnScoreBelow
+    if (obj.failOnScoreBelow !== undefined) {
+        if (typeof obj.failOnScoreBelow !== "number" || obj.failOnScoreBelow < 0 || obj.failOnScoreBelow > 10) {
+            throw new ConfigError('Invalid .judgesrc: "failOnScoreBelow" must be a number between 0 and 10');
+        }
+        config.failOnScoreBelow = obj.failOnScoreBelow;
+    }
+    // judgeWeights
+    if (obj.judgeWeights !== undefined) {
+        if (typeof obj.judgeWeights !== "object" || obj.judgeWeights === null || Array.isArray(obj.judgeWeights)) {
+            throw new ConfigError('Invalid .judgesrc: "judgeWeights" must be an object mapping judge IDs to numbers');
+        }
+        const weights = {};
+        for (const [key, val] of Object.entries(obj.judgeWeights)) {
+            if (typeof val !== "number" || val < 0) {
+                throw new ConfigError(`Invalid .judgesrc: judgeWeights["${key}"] must be a non-negative number`);
+            }
+            weights[key] = val;
+        }
+        config.judgeWeights = weights;
+    }
+    // overrides
+    if (obj.overrides !== undefined) {
+        if (!Array.isArray(obj.overrides)) {
+            throw new ConfigError('Invalid .judgesrc: "overrides" must be an array of override objects');
+        }
+        const parsedOverrides = [];
+        for (let i = 0; i < obj.overrides.length; i++) {
+            const entry = obj.overrides[i];
+            if (typeof entry !== "object" || entry === null || typeof entry.files !== "string") {
+                throw new ConfigError(`Invalid .judgesrc: overrides[${i}] must have a "files" glob string`);
+            }
+            // Clone the entry, strip 'files', parse the rest as partial config
+            const { files, ...rest } = entry;
+            let partial = {};
+            if (Object.keys(rest).length > 0) {
+                try {
+                    partial = parseConfig(JSON.stringify(rest));
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    throw new ConfigError(`Invalid .judgesrc: overrides[${i}]: ${msg}`);
+                }
+            }
+            parsedOverrides.push({ files: files, ...partial });
+        }
+        config.overrides = parsedOverrides;
+    }
+    // languageProfiles
+    if (obj.languageProfiles !== undefined) {
+        if (typeof obj.languageProfiles !== "object" ||
+            obj.languageProfiles === null ||
+            Array.isArray(obj.languageProfiles)) {
+            throw new ConfigError('Invalid .judgesrc: "languageProfiles" must be an object mapping language names to config overrides');
+        }
+        const profiles = {};
+        for (const [lang, val] of Object.entries(obj.languageProfiles)) {
+            if (typeof val !== "object" || val === null) {
+                throw new ConfigError(`Invalid .judgesrc: languageProfiles["${lang}"] must be an object`);
+            }
+            try {
+                const partial = parseConfig(JSON.stringify(val));
+                profiles[lang] = partial;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new ConfigError(`Invalid .judgesrc: languageProfiles["${lang}"]: ${msg}`);
+            }
+        }
+        config.languageProfiles = profiles;
+    }
+    // escalationThreshold
+    if (obj.escalationThreshold !== undefined) {
+        if (typeof obj.escalationThreshold !== "number" || obj.escalationThreshold < 0 || obj.escalationThreshold > 1) {
+            throw new ConfigError('Invalid .judgesrc: "escalationThreshold" must be a number between 0 and 1');
+        }
+        config.escalationThreshold = obj.escalationThreshold;
+    }
+    // customRules
+    if (obj.customRules !== undefined) {
+        if (!Array.isArray(obj.customRules)) {
+            throw new ConfigError('Invalid .judgesrc: "customRules" must be an array');
+        }
+        for (let i = 0; i < obj.customRules.length; i++) {
+            const rule = obj.customRules[i];
+            if (typeof rule !== "object" || rule === null) {
+                throw new ConfigError(`Invalid .judgesrc: customRules[${i}] must be an object`);
+            }
+            if (typeof rule.id !== "string" || typeof rule.pattern !== "string" || typeof rule.title !== "string") {
+                throw new ConfigError(`Invalid .judgesrc: customRules[${i}] requires id, pattern, and title (strings)`);
+            }
+            if (typeof rule.severity !== "string" || !VALID_SEVERITIES.has(rule.severity)) {
+                throw new ConfigError(`Invalid .judgesrc: customRules[${i}].severity must be one of critical, high, medium, low, info`);
+            }
+        }
+        config.customRules = obj.customRules;
+    }
+    // lockedRules
+    if (obj.lockedRules !== undefined) {
+        if (!Array.isArray(obj.lockedRules) || !obj.lockedRules.every((r) => typeof r === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "lockedRules" must be an array of strings');
+        }
+        config.lockedRules = obj.lockedRules;
+    }
+    // lockedJudges
+    if (obj.lockedJudges !== undefined) {
+        if (!Array.isArray(obj.lockedJudges) || !obj.lockedJudges.every((r) => typeof r === "string")) {
+            throw new ConfigError('Invalid .judgesrc: "lockedJudges" must be an array of strings');
+        }
+        config.lockedJudges = obj.lockedJudges;
+    }
+    // lockedMinSeverity
+    if (obj.lockedMinSeverity !== undefined) {
+        if (typeof obj.lockedMinSeverity !== "string" || !VALID_SEVERITIES.has(obj.lockedMinSeverity)) {
+            throw new ConfigError('Invalid .judgesrc: "lockedMinSeverity" must be one of critical, high, medium, low, info');
+        }
+        config.lockedMinSeverity = obj.lockedMinSeverity;
+    }
+    return config;
+}
+/**
+ * Create a default (empty) configuration.
+ */
+export function defaultConfig() {
+    return {};
+}
+// ─── Cascading Config ───────────────────────────────────────────────────────
+/** Config file names to search for, in priority order. */
+const CONFIG_NAMES = [".judgesrc", ".judgesrc.json"];
+/**
+ * Discover .judgesrc files by walking up from `startDir` to `rootDir`.
+ * Returns configs from root → leaf order (leaf overrides root).
+ */
+export function discoverCascadingConfigs(startDir, rootDir) {
+    const configs = [];
+    let current = resolve(startDir);
+    const stop = rootDir ? resolve(rootDir) : undefined;
+    // Walk up the directory tree
+    const visited = new Set();
+    while (current && !visited.has(current)) {
+        visited.add(current);
+        for (const name of CONFIG_NAMES) {
+            const p = join(current, name);
+            if (existsSync(p)) {
+                try {
+                    let cfg = parseConfig(readFileSync(p, "utf-8"));
+                    // Resolve extends relative to the config file's directory
+                    cfg = resolveExtendsConfig(cfg, current);
+                    configs.push({ dir: current, config: cfg });
+                }
+                catch {
+                    // Skip invalid config files
+                }
+                break; // Only use the first matching file per directory
+            }
+        }
+        if (stop && current === stop)
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            break; // reached filesystem root
+        current = parent;
+    }
+    // Reverse so root comes first — leaf configs override root configs
+    configs.reverse();
+    return configs.map((c) => c.config);
+}
+/**
+ * Merge multiple configs (root → leaf order). Later entries override earlier.
+ * Arrays (disabledRules, disabledJudges, languages, exclude, include, plugins) are
+ * concatenated (union). Scalars (minSeverity, maxFiles, preset, failOnFindings,
+ * baseline, format) use the leaf value.
+ * ruleOverrides are deep-merged.
+ *
+ * Org-level policy enforcement:
+ * - `lockedRules`: locked rules cannot be added to `disabledRules`
+ * - `lockedJudges`: locked judges cannot be added to `disabledJudges`
+ * - `lockedMinSeverity`: child configs cannot set a more lenient minSeverity
+ */
+export function mergeConfigs(...configs) {
+    const merged = {};
+    for (const cfg of configs) {
+        // Accumulate locked fields (union across all configs — once locked, always locked)
+        if (cfg.lockedRules) {
+            merged.lockedRules = [...new Set([...(merged.lockedRules ?? []), ...cfg.lockedRules])];
+        }
+        if (cfg.lockedJudges) {
+            merged.lockedJudges = [...new Set([...(merged.lockedJudges ?? []), ...cfg.lockedJudges])];
+        }
+        if (cfg.lockedMinSeverity !== undefined) {
+            // Keep the strictest lock (lowest severity index = strictest)
+            if (!merged.lockedMinSeverity || severityRank(cfg.lockedMinSeverity) < severityRank(merged.lockedMinSeverity)) {
+                merged.lockedMinSeverity = cfg.lockedMinSeverity;
+            }
+        }
+        // Concatenate arrays (deduplicated)
+        if (cfg.disabledRules) {
+            merged.disabledRules = [...new Set([...(merged.disabledRules ?? []), ...cfg.disabledRules])];
+        }
+        if (cfg.disabledJudges) {
+            merged.disabledJudges = [...new Set([...(merged.disabledJudges ?? []), ...cfg.disabledJudges])];
+        }
+        if (cfg.languages) {
+            merged.languages = [...new Set([...(merged.languages ?? []), ...cfg.languages])];
+        }
+        if (cfg.exclude) {
+            merged.exclude = [...new Set([...(merged.exclude ?? []), ...cfg.exclude])];
+        }
+        if (cfg.include) {
+            merged.include = [...new Set([...(merged.include ?? []), ...cfg.include])];
+        }
+        if (cfg.plugins) {
+            merged.plugins = [...new Set([...(merged.plugins ?? []), ...cfg.plugins])];
+        }
+        // Scalars: leaf wins
+        if (cfg.minSeverity !== undefined)
+            merged.minSeverity = cfg.minSeverity;
+        if (cfg.maxFiles !== undefined)
+            merged.maxFiles = cfg.maxFiles;
+        if (cfg.preset !== undefined)
+            merged.preset = cfg.preset;
+        if (cfg.failOnFindings !== undefined)
+            merged.failOnFindings = cfg.failOnFindings;
+        if (cfg.baseline !== undefined)
+            merged.baseline = cfg.baseline;
+        if (cfg.format !== undefined)
+            merged.format = cfg.format;
+        if (cfg.failOnScoreBelow !== undefined)
+            merged.failOnScoreBelow = cfg.failOnScoreBelow;
+        // Deep-merge ruleOverrides
+        if (cfg.ruleOverrides) {
+            merged.ruleOverrides = { ...(merged.ruleOverrides ?? {}), ...cfg.ruleOverrides };
+        }
+        // Deep-merge judgeWeights
+        if (cfg.judgeWeights) {
+            merged.judgeWeights = { ...(merged.judgeWeights ?? {}), ...cfg.judgeWeights };
+        }
+        // Overrides: concatenate (later entries take precedence naturally)
+        if (cfg.overrides) {
+            merged.overrides = [...(merged.overrides ?? []), ...cfg.overrides];
+        }
+    }
+    // ── Enforce org-level locked policies ──────────────────────────────
+    // Remove locked rules from disabledRules (they must stay enabled)
+    if (merged.lockedRules?.length && merged.disabledRules?.length) {
+        const locked = new Set(merged.lockedRules);
+        merged.disabledRules = merged.disabledRules.filter((r) => !locked.has(r));
+        if (merged.disabledRules.length === 0)
+            delete merged.disabledRules;
+    }
+    // Remove locked judges from disabledJudges (they must stay enabled)
+    if (merged.lockedJudges?.length && merged.disabledJudges?.length) {
+        const locked = new Set(merged.lockedJudges);
+        merged.disabledJudges = merged.disabledJudges.filter((j) => !locked.has(j));
+        if (merged.disabledJudges.length === 0)
+            delete merged.disabledJudges;
+    }
+    // Enforce minSeverity floor — child cannot be more lenient than the lock
+    if (merged.lockedMinSeverity && merged.minSeverity) {
+        if (severityRank(merged.minSeverity) > severityRank(merged.lockedMinSeverity)) {
+            merged.minSeverity = merged.lockedMinSeverity;
+        }
+    }
+    return merged;
+}
+/** Lightweight loader for tests and CLI helpers.
+ * Reads a JSON config file, expands env placeholders (${VARS}), and parses it.
+ * Returns {} on any failure to keep CLI flows resilient.
+ */
+export async function loadConfigFile(path) {
+    try {
+        const content = readFileSync(path, "utf-8");
+        const expanded = expandEnvPlaceholders(content);
+        return parseConfig(expanded);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve `extends` references in a config. Each value in `extends` is treated
+ * as a file path (relative to `baseDir`). The referenced configs are loaded
+ * and merged (left-to-right), then the current config is applied on top.
+ *
+ * Circular extends are detected and rejected with a ConfigError.
+ *
+ * @param config - The config to resolve
+ * @param baseDir - Directory for resolving relative extends paths
+ * @param seen - Set of already-resolved paths (for cycle detection)
+ * @returns The fully resolved and merged config
+ */
+export function resolveExtendsConfig(config, baseDir, seen = new Set()) {
+    if (!config.extends)
+        return config;
+    const extendsList = Array.isArray(config.extends) ? config.extends : [config.extends];
+    const baseConfigs = [];
+    for (const ext of extendsList) {
+        const resolvedPath = resolve(baseDir, ext);
+        if (seen.has(resolvedPath)) {
+            throw new ConfigError(`Circular extends detected: ${resolvedPath}`);
+        }
+        if (!existsSync(resolvedPath)) {
+            throw new ConfigError(`Extended config not found: ${resolvedPath}`);
+        }
+        seen.add(resolvedPath);
+        try {
+            const content = readFileSync(resolvedPath, "utf-8");
+            let parentConfig = parseConfig(content);
+            // Recursively resolve the parent's extends (with cycle detection)
+            parentConfig = resolveExtendsConfig(parentConfig, dirname(resolvedPath), seen);
+            baseConfigs.push(parentConfig);
+        }
+        catch (e) {
+            if (e instanceof ConfigError)
+                throw e;
+            throw new ConfigError(`Failed to load extended config ${resolvedPath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // Merge: bases first (left-to-right), then current config on top
+    const { extends: _ext, ...currentWithoutExtends } = config;
+    return mergeConfigs(...baseConfigs, currentWithoutExtends);
+}
+/**
+ * Load a cascading config for a specific file path.
+ * Walks from the file's directory up to rootDir, merging all .judgesrc files.
+ */
+export function loadCascadingConfig(filePath, rootDir) {
+    const dir = dirname(resolve(filePath));
+    const configs = discoverCascadingConfigs(dir, rootDir);
+    return configs.length > 0 ? mergeConfigs(...configs) : {};
+}
+// ─── Plugin Loading ─────────────────────────────────────────────────────────
+/**
+ * Validate that a value looks like a JudgeDefinition.
+ * Checks required string fields (id, name, domain, description, systemPrompt,
+ * rulePrefix) and an optional analyze function.
+ */
+export function isValidJudgeDefinition(val) {
+    if (typeof val !== "object" || val === null)
+        return false;
+    const obj = val;
+    return (typeof obj.id === "string" &&
+        typeof obj.name === "string" &&
+        typeof obj.domain === "string" &&
+        typeof obj.description === "string" &&
+        typeof obj.systemPrompt === "string" &&
+        typeof obj.rulePrefix === "string" &&
+        (obj.analyze === undefined || typeof obj.analyze === "function"));
+}
+/**
+ * Validate that a value looks like a JudgesPlugin.
+ */
+function isValidPlugin(val) {
+    if (typeof val !== "object" || val === null)
+        return false;
+    const obj = val;
+    return typeof obj.name === "string" && typeof obj.version === "string";
+}
+/**
+ * Load and register plugins from module specifiers declared in config.
+ *
+ * Each plugin is a module specifier (npm package name or relative/absolute
+ * file path) that must export one of:
+ *   - `default: JudgesPlugin`       — a full plugin object (name, version, judges, rules, hooks)
+ *   - `plugin: JudgesPlugin`        — named export
+ *   - `judges: JudgeDefinition[]`   — an array of judge definitions (auto-wrapped)
+ *   - `default: JudgeDefinition[]`  — default export as an array (auto-wrapped)
+ *
+ * Plugins that export a full JudgesPlugin object are registered via
+ * registerPlugin() to enable hooks, custom rules, and full lifecycle.
+ * Simple judge arrays are wrapped into a minimal plugin automatically.
+ *
+ * @param pluginSpecifiers - Array of module specifiers from config.plugins
+ * @param baseDir - Base directory for resolving relative paths
+ * @param logError - Optional error logger (defaults to console.error)
+ * @returns Array of plugin judge definitions that were loaded
+ */
+export async function loadPluginJudges(pluginSpecifiers, baseDir, logError = console.error) {
+    const loaded = [];
+    for (const specifier of pluginSpecifiers) {
+        try {
+            // Resolve relative paths against baseDir
+            const resolvedSpec = specifier.startsWith(".") || specifier.startsWith("/")
+                ? resolve(baseDir ?? process.cwd(), specifier)
+                : specifier;
+            // Dynamic import the module
+            const mod = (await import(resolvedSpec));
+            // Strategy 1: Full JudgesPlugin export (best — gets hooks, rules, etc.)
+            const pluginObj = isValidPlugin(mod.default) ? mod.default : isValidPlugin(mod.plugin) ? mod.plugin : null;
+            if (pluginObj) {
+                const reg = registerPlugin(pluginObj);
+                if (pluginObj.judges) {
+                    loaded.push(...pluginObj.judges);
+                }
+                if (!reg.rulesRegistered && !reg.judgesRegistered) {
+                    logError(`Plugin "${specifier}": registered but has no rules or judges`);
+                }
+                continue;
+            }
+            // Strategy 2: Bare JudgeDefinition array — wrap into a minimal plugin
+            let candidates = [];
+            if (Array.isArray(mod.judges)) {
+                candidates = mod.judges;
+            }
+            else if (Array.isArray(mod.default)) {
+                candidates = mod.default;
+            }
+            const validJudges = candidates.filter(isValidJudgeDefinition);
+            if (validJudges.length > 0) {
+                registerPlugin({
+                    name: specifier,
+                    version: "0.0.0",
+                    judges: validJudges,
+                });
+                loaded.push(...validJudges);
+                continue;
+            }
+            logError(`Plugin "${specifier}": no valid plugin or judge definitions found. ` +
+                `Export a JudgesPlugin object or an array of JudgeDefinition objects.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logError(`Plugin "${specifier}": failed to load — ${msg}`);
+        }
+    }
+    return loaded;
+}
+/**
+ * Synchronously validate plugin specifiers without loading them.
+ * Returns an array of validation error messages (empty if all valid).
+ */
+export function validatePluginSpecifiers(specifiers) {
+    const errors = [];
+    const seen = new Set();
+    for (const spec of specifiers) {
+        if (typeof spec !== "string" || spec.trim().length === 0) {
+            errors.push(`Invalid plugin specifier: must be a non-empty string`);
+            continue;
+        }
+        if (seen.has(spec)) {
+            errors.push(`Duplicate plugin specifier: "${spec}"`);
+        }
+        seen.add(spec);
+    }
+    return errors;
+}
+// ─── Per-File Config Overrides ──────────────────────────────────────────────
+/**
+ * Apply path-scoped overrides to a base config for a specific file.
+ *
+ * Each override entry carries a glob `files` pattern (e.g. `"**\/*.test.ts"`).
+ * If the file path matches, the override's partial config is merged on top
+ * of the base config. Multiple matching overrides are applied in order.
+ *
+ * @param config  - The resolved base config
+ * @param filePath - The relative file path to match against override globs
+ * @returns A new config with matching overrides applied
+ */
+export function applyOverridesForFile(config, filePath) {
+    if (!config.overrides || config.overrides.length === 0) {
+        return config;
+    }
+    // Normalize path separators for glob matching
+    const normalized = filePath.replace(/\\/g, "/");
+    const matchingOverrides = [];
+    for (const override of config.overrides) {
+        if (globMatch(normalized, override.files)) {
+            // Extract config fields (everything except 'files')
+            const { files: _files, ...partial } = override;
+            matchingOverrides.push(partial);
+        }
+    }
+    if (matchingOverrides.length === 0) {
+        return config;
+    }
+    // Merge: base config first, then matching overrides in order
+    const { overrides: _overrides, ...baseWithoutOverrides } = config;
+    return mergeConfigs(baseWithoutOverrides, ...matchingOverrides);
+}
+/**
+ * Simple glob matcher supporting `*`, `**`, and `?`.
+ * - `*` matches any characters except `/`
+ * - `**` matches any characters including `/` (directory recursion)
+ * - `?` matches exactly one character except `/`
+ */
+function globMatch(path, pattern) {
+    return matchGlobPath(path, pattern);
+}
+// ─── Language Profile Application ────────────────────────────────────────────
+/**
+ * Apply language-specific config overrides from languageProfiles.
+ * The language string is normalised to a LangFamily before lookup.
+ *
+ * @param config   - Base config (may include languageProfiles)
+ * @param language - The detected language (e.g. "typescript", "python")
+ * @returns A new config with the matching language profile merged on top
+ */
+export function applyLanguageProfile(config, language) {
+    if (!config.languageProfiles)
+        return config;
+    const normalised = normalizeLanguage(language);
+    const profile = config.languageProfiles[normalised];
+    if (!profile)
+        return config;
+    const { languageProfiles: _lp, ...baseWithoutProfiles } = config;
+    return mergeConfigs(baseWithoutProfiles, profile);
+}