@eduardbar/drift 1.3.0 → 1.4.0

package/dist/metrics.js

@@ -25,6 +25,19 @@ const AI_RULES = new Set([
     'comment-contradiction',
     'ai-code-smell',
 ]);
+const ISSUE_WEIGHT_PER_FILE = 20;
+const DIMENSION_COUNT = 4;
+const MAX_COMPLEXITY_RISK = 40;
+const COMPLEXITY_RISK_PER_ISSUE = 10;
+const MISSING_TESTS_RISK = 25;
+const FREQUENT_CHANGE_THRESHOLD = 8;
+const FREQUENT_CHANGE_RISK = 20;
+const HIGH_DRIFT_THRESHOLD = 50;
+const HIGH_DRIFT_RISK = 15;
+const HOTSPOT_LIMIT = 10;
+const LEVEL_CRITICAL_THRESHOLD = 75;
+const LEVEL_HIGH_THRESHOLD = 55;
+const LEVEL_MEDIUM_THRESHOLD = 30;
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
@@ -33,21 +46,20 @@ function listFilesRecursively(root) {
         return [];
     const out = [];
     const stack = [root];
+    const shouldSkipDirectory = (name) => name === 'node_modules' || name === 'dist' || name === '.git' || name === '.next' || name === 'build';
     while (stack.length > 0) {
         const current = stack.pop();
         const entries = readdirSync(current);
         for (const entry of entries) {
             const full = join(current, entry);
             const stat = statSync(full);
-            if (stat.isDirectory()) {
-                if (entry === 'node_modules' || entry === 'dist' || entry === '.git' || entry === '.next' || entry === 'build') {
-                    continue;
-                }
-                stack.push(full);
-            }
-            else {
+            if (!stat.isDirectory()) {
                 out.push(full);
+                continue;
             }
+            if (shouldSkipDirectory(entry))
+                continue;
+            stack.push(full);
         }
     }
     return out;
@@ -83,7 +95,51 @@ function qualityFromIssues(totalFiles, issues, rules) {
     const count = issues.filter((issue) => rules.has(issue.rule)).length;
     if (totalFiles === 0)
         return 100;
-    return clamp(100 - Math.round((count / totalFiles) * 20), 0, 100);
+    return clamp(100 - Math.round((count / totalFiles) * ISSUE_WEIGHT_PER_FILE), 0, 100);
+}
+function riskLevelFromScore(score) {
+    if (score >= LEVEL_CRITICAL_THRESHOLD)
+        return 'critical';
+    if (score >= LEVEL_HIGH_THRESHOLD)
+        return 'high';
+    if (score >= LEVEL_MEDIUM_THRESHOLD)
+        return 'medium';
+    return 'low';
+}
+function evaluateHotspot(targetPath, file) {
+    const complexityIssues = file.issues.filter((issue) => issue.rule === 'high-complexity' ||
+        issue.rule === 'deep-nesting' ||
+        issue.rule === 'large-function' ||
+        issue.rule === 'max-function-lines').length;
+    const changeFrequency = getCommitTouchCount(targetPath, file.path);
+    const hasTests = hasNearbyTest(targetPath, file.path);
+    const reasons = [];
+    let risk = 0;
+    if (complexityIssues > 0) {
+        risk += Math.min(MAX_COMPLEXITY_RISK, complexityIssues * COMPLEXITY_RISK_PER_ISSUE);
+        reasons.push('high complexity signals');
+    }
+    if (!hasTests) {
+        risk += MISSING_TESTS_RISK;
+        reasons.push('no nearby tests');
+    }
+    if (changeFrequency >= FREQUENT_CHANGE_THRESHOLD) {
+        risk += FREQUENT_CHANGE_RISK;
+        reasons.push('frequently changed file');
+    }
+    if (file.score >= HIGH_DRIFT_THRESHOLD) {
+        risk += HIGH_DRIFT_RISK;
+        reasons.push('high drift score');
+    }
+    return {
+        file: file.path,
+        driftScore: file.score,
+        complexityIssues,
+        hasNearbyTests: hasTests,
+        changeFrequency,
+        risk: clamp(risk, 0, 100),
+        reasons,
+    };
 }
 export function computeRepoQuality(targetPath, files) {
     const allIssues = files.flatMap((file) => file.issues);
@@ -105,63 +161,22 @@ export function computeRepoQuality(targetPath, files) {
     const overall = Math.round((dimensions.architecture +
         dimensions.complexity +
         dimensions['ai-patterns'] +
-        dimensions.testing) / 4);
+        dimensions.testing) / DIMENSION_COUNT);
     return { overall, dimensions };
 }
 export function computeMaintenanceRisk(report) {
-    const allFiles = report.files;
-    const hotspots = allFiles
-        .map((file) => {
-        const complexityIssues = file.issues.filter((issue) => issue.rule === 'high-complexity' ||
-            issue.rule === 'deep-nesting' ||
-            issue.rule === 'large-function' ||
-            issue.rule === 'max-function-lines').length;
-        const changeFrequency = getCommitTouchCount(report.targetPath, file.path);
-        const hasTests = hasNearbyTest(report.targetPath, file.path);
-        const reasons = [];
-        let risk = 0;
-        if (complexityIssues > 0) {
-            risk += Math.min(40, complexityIssues * 10);
-            reasons.push('high complexity signals');
-        }
-        if (!hasTests) {
-            risk += 25;
-            reasons.push('no nearby tests');
-        }
-        if (changeFrequency >= 8) {
-            risk += 20;
-            reasons.push('frequently changed file');
-        }
-        if (file.score >= 50) {
-            risk += 15;
-            reasons.push('high drift score');
-        }
-        return {
-            file: file.path,
-            driftScore: file.score,
-            complexityIssues,
-            hasNearbyTests: hasTests,
-            changeFrequency,
-            risk: clamp(risk, 0, 100),
-            reasons,
-        };
-    })
+    const hotspots = report.files
+        .map((file) => evaluateHotspot(report.targetPath, file))
         .filter((hotspot) => hotspot.risk > 0)
         .sort((a, b) => b.risk - a.risk)
-        .slice(0, 10);
+        .slice(0, HOTSPOT_LIMIT);
     const highComplexityFiles = hotspots.filter((hotspot) => hotspot.complexityIssues > 0).length;
     const filesWithoutNearbyTests = hotspots.filter((hotspot) => !hotspot.hasNearbyTests).length;
-    const frequentChangeFiles = hotspots.filter((hotspot) => hotspot.changeFrequency >= 8).length;
+    const frequentChangeFiles = hotspots.filter((hotspot) => hotspot.changeFrequency >= FREQUENT_CHANGE_THRESHOLD).length;
     const score = hotspots.length === 0
         ? 0
         : Math.round(hotspots.reduce((sum, hotspot) => sum + hotspot.risk, 0) / hotspots.length);
-    const level = score >= 75
-        ? 'critical'
-        : score >= 55
-            ? 'high'
-            : score >= 30
-                ? 'medium'
-                : 'low';
+    const level = riskLevelFromScore(score);
     return {
         score,
         level,

package/dist/output-metadata.d.ts

@@ -0,0 +1,13 @@
+export declare const OUTPUT_SCHEMA: {
+    readonly report: "schemas/drift-report.v1.json";
+    readonly trust: "schemas/drift-trust.v1.json";
+    readonly ai: "schemas/drift-ai-output.v1.json";
+};
+type OutputMetadata = {
+    $schema: string;
+    toolVersion: string;
+};
+type JsonOutputWithMetadata<T extends object> = T & OutputMetadata;
+export declare function withOutputMetadata<T extends object>(payload: T, schema: string): JsonOutputWithMetadata<T>;
+export {};
+//# sourceMappingURL=output-metadata.d.ts.map

package/dist/output-metadata.js

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+const TOOL_VERSION = version;
+export const OUTPUT_SCHEMA = {
+    report: 'schemas/drift-report.v1.json',
+    trust: 'schemas/drift-trust.v1.json',
+    ai: 'schemas/drift-ai-output.v1.json',
+};
+export function withOutputMetadata(payload, schema) {
+    return {
+        ...payload,
+        $schema: schema,
+        toolVersion: TOOL_VERSION,
+    };
+}
+//# sourceMappingURL=output-metadata.js.map

package/dist/plugins-capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { DriftPlugin } from './types.js';
+import type { PluginValidationContext } from './plugins-rules.js';
+export declare function validateCapabilities(capabilitiesCandidate: unknown, context: PluginValidationContext): DriftPlugin['capabilities'] | undefined;
+//# sourceMappingURL=plugins-capabilities.d.ts.map

package/dist/plugins-capabilities.js

@@ -0,0 +1,21 @@
+import { pushError } from './plugins-messages.js';
+export function validateCapabilities(capabilitiesCandidate, context) {
+    const { pluginId, pluginName, errors } = context;
+    if (capabilitiesCandidate === undefined)
+        return undefined;
+    if (!capabilitiesCandidate || typeof capabilitiesCandidate !== 'object' || Array.isArray(capabilitiesCandidate)) {
+        pushError(errors, pluginId, `Plugin '${pluginName}' has invalid capabilities metadata. Expected an object map like { "fixes": true } when provided.`, { pluginName, code: 'plugin-capabilities-invalid' });
+        return undefined;
+    }
+    const entries = Object.entries(capabilitiesCandidate);
+    for (const [capabilityKey, capabilityValue] of entries) {
+        const capabilityType = typeof capabilityValue;
+        if (capabilityType !== 'string' && capabilityType !== 'number' && capabilityType !== 'boolean') {
+            pushError(errors, pluginId, `Plugin '${pluginName}' capability '${capabilityKey}' has invalid value type '${capabilityType}'. Allowed: string | number | boolean.`, { pluginName, code: 'plugin-capabilities-value-invalid' });
+        }
+    }
+    if (errors.length > 0)
+        return undefined;
+    return capabilitiesCandidate;
+}
+//# sourceMappingURL=plugins-capabilities.js.map

package/dist/plugins-messages.d.ts

@@ -0,0 +1,10 @@
+import type { PluginLoadError, PluginLoadWarning } from './types.js';
+type PluginMessageOptions = {
+    pluginName?: string;
+    ruleId?: string;
+    code?: string;
+};
+export declare function pushError(errors: PluginLoadError[], pluginId: string, message: string, options?: PluginMessageOptions): void;
+export declare function pushWarning(warnings: PluginLoadWarning[], pluginId: string, message: string, options?: PluginMessageOptions): void;
+export {};
+//# sourceMappingURL=plugins-messages.d.ts.map

package/dist/plugins-messages.js

@@ -0,0 +1,16 @@
+function pushLoadMessage(pluginId, message, options) {
+    return {
+        pluginId,
+        pluginName: options?.pluginName,
+        ruleId: options?.ruleId,
+        code: options?.code,
+        message,
+    };
+}
+export function pushError(errors, pluginId, message, options) {
+    errors.push(pushLoadMessage(pluginId, message, options));
+}
+export function pushWarning(warnings, pluginId, message, options) {
+    warnings.push(pushLoadMessage(pluginId, message, options));
+}
+//# sourceMappingURL=plugins-messages.js.map

package/dist/plugins-rules.d.ts

@@ -0,0 +1,9 @@
+import type { DriftPluginRule, PluginLoadError, PluginLoadWarning } from './types.js';
+export type PluginValidationContext = {
+    pluginId: string;
+    pluginName: string;
+    errors: PluginLoadError[];
+    warnings: PluginLoadWarning[];
+};
+export declare function normalizeRules(rulesCandidate: unknown, isLegacyPlugin: boolean, context: PluginValidationContext): DriftPluginRule[] | undefined;
+//# sourceMappingURL=plugins-rules.d.ts.map

package/dist/plugins-rules.js

@@ -0,0 +1,137 @@
+import { pushError, pushWarning } from './plugins-messages.js';
+const VALID_SEVERITIES = ['error', 'warning', 'info'];
+const MAX_FIX_ARITY = 3;
+const RULE_ID_REQUIRED = /^[a-z][a-z0-9]*(?:[-_/][a-z0-9]+)*$/;
+function resolveRawRuleId(rawRule) {
+    if (typeof rawRule.id === 'string')
+        return rawRule.id.trim();
+    if (typeof rawRule.name === 'string')
+        return rawRule.name.trim();
+    return '';
+}
+function ensureRuleId(rawRuleId, ruleIndex, context) {
+    if (rawRuleId)
+        return true;
+    pushError(context.errors, context.pluginId, `Invalid rule at index ${ruleIndex}. Expected 'id' or 'name' as a non-empty string.`, { pluginName: context.pluginName, code: 'plugin-rule-id-missing' });
+    return false;
+}
+function ensureDetectFunction(detect, context) {
+    if (typeof detect === 'function')
+        return true;
+    pushError(context.errors, context.pluginId, `Rule '${context.ruleId}' is invalid. Expected 'detect(file, context)' function.`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-detect-invalid' });
+    return false;
+}
+function warnDetectArity(detect, context) {
+    if (detect.length <= 2)
+        return;
+    pushWarning(context.warnings, context.pluginId, `Rule '${context.ruleId}' detect() declares ${detect.length} parameters. Expected 1-2 parameters (file, context).`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-detect-arity' });
+}
+function validateRuleIdentifierFormat(rawRuleId, strictRuleId, context) {
+    if (RULE_ID_REQUIRED.test(rawRuleId))
+        return;
+    const ruleLabel = rawRuleId || 'unknown-rule';
+    if (strictRuleId) {
+        pushError(context.errors, context.pluginId, `Rule id '${ruleLabel}' is invalid. Use lowercase letters, numbers, and separators (-, _, /), starting with a letter.`, { pluginName: context.pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-invalid' });
+        return;
+    }
+    pushWarning(context.warnings, context.pluginId, `Rule id '${ruleLabel}' uses a legacy format. For forward compatibility, migrate to lowercase kebab-case and set apiVersion: 1.`, { pluginName: context.pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-format-legacy' });
+}
+function resolveRuleSeverity(rawSeverity, context) {
+    if (rawSeverity === undefined)
+        return undefined;
+    if (typeof rawSeverity === 'string' && VALID_SEVERITIES.includes(rawSeverity)) {
+        return rawSeverity;
+    }
+    pushError(context.errors, context.pluginId, `Rule '${context.ruleId}' has invalid severity '${String(rawSeverity)}'. Allowed: error, warning, info.`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-severity-invalid' });
+    return undefined;
+}
+function resolveRuleWeight(rawWeight, context) {
+    if (rawWeight === undefined)
+        return undefined;
+    if (typeof rawWeight === 'number' && Number.isFinite(rawWeight) && rawWeight >= 0 && rawWeight <= 100) {
+        return rawWeight;
+    }
+    pushError(context.errors, context.pluginId, `Rule '${context.ruleId}' has invalid weight '${String(rawWeight)}'. Expected a finite number between 0 and 100.`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-weight-invalid' });
+    return undefined;
+}
+function resolveRuleFix(rawFix, context) {
+    if (rawFix === undefined)
+        return undefined;
+    if (typeof rawFix !== 'function') {
+        pushError(context.errors, context.pluginId, `Rule '${context.ruleId}' has invalid fix. Expected a function when provided.`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-fix-invalid' });
+        return undefined;
+    }
+    if (rawFix.length > MAX_FIX_ARITY) {
+        pushWarning(context.warnings, context.pluginId, `Rule '${context.ruleId}' fix() declares ${rawFix.length} parameters. Expected up to ${MAX_FIX_ARITY} (issue, file, context).`, { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-fix-arity' });
+    }
+    return rawFix;
+}
+function normalizeRule(rawRule, context) {
+    const { pluginId, pluginName, ruleIndex, strictRuleId, errors, warnings } = context;
+    const rawRuleId = resolveRawRuleId(rawRule);
+    const messageContext = { pluginId, pluginName, ruleId: rawRuleId, errors, warnings };
+    if (!ensureRuleId(rawRuleId, ruleIndex, messageContext))
+        return undefined;
+    if (!ensureDetectFunction(rawRule.detect, messageContext))
+        return undefined;
+    validateRuleIdentifierFormat(rawRuleId, strictRuleId, messageContext);
+    warnDetectArity(rawRule.detect, messageContext);
+    const ruleValidationContext = { pluginId, pluginName, ruleId: rawRuleId, errors };
+    const severity = resolveRuleSeverity(rawRule.severity, ruleValidationContext);
+    const weight = resolveRuleWeight(rawRule.weight, ruleValidationContext);
+    const fix = resolveRuleFix(rawRule.fix, messageContext);
+    return {
+        id: rawRuleId,
+        name: rawRuleId,
+        detect: rawRule.detect,
+        severity,
+        weight,
+        fix,
+    };
+}
+function ensureUniqueRuleId(rule, seenRuleIds, context) {
+    const normalizedRuleId = rule.id ?? rule.name;
+    if (seenRuleIds.has(normalizedRuleId)) {
+        pushError(context.errors, context.pluginId, `Plugin '${context.pluginName}' defines duplicate rule id '${normalizedRuleId}'. Rule ids must be unique within a plugin.`, { pluginName: context.pluginName, ruleId: normalizedRuleId, code: 'plugin-rule-id-duplicate' });
+        return false;
+    }
+    seenRuleIds.add(normalizedRuleId);
+    return true;
+}
+function normalizeRulesArray(rulesCandidate, context, strictRuleId) {
+    const normalizedRules = [];
+    const seenRuleIds = new Set();
+    for (const [ruleIndex, rawRule] of rulesCandidate.entries()) {
+        if (!rawRule || typeof rawRule !== 'object') {
+            pushError(context.errors, context.pluginId, `Invalid rule at index ${ruleIndex} in plugin '${context.pluginName}'. Expected an object.`, { pluginName: context.pluginName, code: 'plugin-rule-shape-invalid' });
+            continue;
+        }
+        const normalized = normalizeRule(rawRule, {
+            pluginId: context.pluginId,
+            pluginName: context.pluginName,
+            ruleIndex,
+            strictRuleId,
+            errors: context.errors,
+            warnings: context.warnings,
+        });
+        if (!normalized)
+            continue;
+        if (ensureUniqueRuleId(normalized, seenRuleIds, context)) {
+            normalizedRules.push(normalized);
+        }
+    }
+    return normalizedRules;
+}
+export function normalizeRules(rulesCandidate, isLegacyPlugin, context) {
+    if (!Array.isArray(rulesCandidate)) {
+        pushError(context.errors, context.pluginId, `Invalid plugin '${context.pluginName}'. Expected 'rules' to be an array.`, { pluginName: context.pluginName, code: 'plugin-rules-not-array' });
+        return undefined;
+    }
+    const normalizedRules = normalizeRulesArray(rulesCandidate, context, !isLegacyPlugin);
+    if (normalizedRules.length === 0) {
+        pushError(context.errors, context.pluginId, `Plugin '${context.pluginName}' has no valid rules after validation.`, { pluginName: context.pluginName, code: 'plugin-rules-empty' });
+        return undefined;
+    }
+    return normalizedRules;
+}
+//# sourceMappingURL=plugins-rules.js.map

package/dist/plugins.d.ts

@@ -1,4 +1,4 @@
-import type { PluginLoadError, PluginLoadWarning, LoadedPlugin } from './types.js';
+import type { LoadedPlugin, PluginLoadError, PluginLoadWarning } from './types.js';
 export declare function loadPlugins(projectRoot: string, pluginIds: string[] | undefined): {
     plugins: LoadedPlugin[];
     errors: PluginLoadError[];

package/dist/plugins.js

@@ -1,171 +1,72 @@
 import { existsSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { normalizeRules } from './plugins-rules.js';
+import { validateCapabilities } from './plugins-capabilities.js';
+import { pushError, pushWarning } from './plugins-messages.js';
 const require = createRequire(import.meta.url);
-const VALID_SEVERITIES = ['error', 'warning', 'info'];
 const SUPPORTED_PLUGIN_API_VERSION = 1;
-const RULE_ID_REQUIRED = /^[a-z][a-z0-9]*(?:[-_/][a-z0-9]+)*$/;
 function normalizePluginExport(mod) {
     if (mod && typeof mod === 'object' && 'default' in mod) {
         return mod.default ?? mod;
     }
     return mod;
 }
-function pushError(errors, pluginId, message, options) {
-    errors.push({
-        pluginId,
-        pluginName: options?.pluginName,
-        ruleId: options?.ruleId,
-        code: options?.code,
-        message,
-    });
-}
-function pushWarning(warnings, pluginId, message, options) {
-    warnings.push({
-        pluginId,
-        pluginName: options?.pluginName,
-        ruleId: options?.ruleId,
-        code: options?.code,
-        message,
-    });
-}
-function normalizeRule(pluginId, pluginName, rawRule, ruleIndex, options, errors, warnings) {
-    const rawRuleId = typeof rawRule.id === 'string'
-        ? rawRule.id.trim()
-        : typeof rawRule.name === 'string'
-            ? rawRule.name.trim()
-            : '';
-    const ruleLabel = rawRuleId || `rule#${ruleIndex + 1}`;
-    if (!rawRuleId) {
-        pushError(errors, pluginId, `Invalid rule at index ${ruleIndex}. Expected 'id' or 'name' as a non-empty string.`, { pluginName, code: 'plugin-rule-id-missing' });
-        return undefined;
-    }
-    if (typeof rawRule.detect !== 'function') {
-        pushError(errors, pluginId, `Rule '${rawRuleId}' is invalid. Expected 'detect(file, context)' function.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-detect-invalid' });
-        return undefined;
-    }
-    if (rawRule.detect.length > 2) {
-        pushWarning(warnings, pluginId, `Rule '${rawRuleId}' detect() declares ${rawRule.detect.length} parameters. Expected 1-2 parameters (file, context).`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-detect-arity' });
-    }
-    if (!RULE_ID_REQUIRED.test(rawRuleId)) {
-        if (options.strictRuleId) {
-            pushError(errors, pluginId, `Rule id '${ruleLabel}' is invalid. Use lowercase letters, numbers, and separators (-, _, /), starting with a letter.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-invalid' });
-            return undefined;
-        }
-        pushWarning(warnings, pluginId, `Rule id '${ruleLabel}' uses a legacy format. For forward compatibility, migrate to lowercase kebab-case and set apiVersion: ${SUPPORTED_PLUGIN_API_VERSION}.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-format-legacy' });
-    }
-    let severity;
-    if (rawRule.severity !== undefined) {
-        if (typeof rawRule.severity === 'string' && VALID_SEVERITIES.includes(rawRule.severity)) {
-            severity = rawRule.severity;
-        }
-        else {
-            pushError(errors, pluginId, `Rule '${rawRuleId}' has invalid severity '${String(rawRule.severity)}'. Allowed: error, warning, info.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-severity-invalid' });
-        }
-    }
-    let weight;
-    if (rawRule.weight !== undefined) {
-        if (typeof rawRule.weight === 'number' && Number.isFinite(rawRule.weight) && rawRule.weight >= 0 && rawRule.weight <= 100) {
-            weight = rawRule.weight;
-        }
-        else {
-            pushError(errors, pluginId, `Rule '${rawRuleId}' has invalid weight '${String(rawRule.weight)}'. Expected a finite number between 0 and 100.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-weight-invalid' });
-        }
+function ensureObjectCandidate(pluginId, candidate, errors) {
+    if (candidate && typeof candidate === 'object') {
+        return candidate;
     }
-    let fix;
-    if (rawRule.fix !== undefined) {
-        if (typeof rawRule.fix === 'function') {
-            fix = rawRule.fix;
-            if (rawRule.fix.length > 3) {
-                pushWarning(warnings, pluginId, `Rule '${rawRuleId}' fix() declares ${rawRule.fix.length} parameters. Expected up to 3 (issue, file, context).`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-fix-arity' });
-            }
-        }
-        else {
-            pushError(errors, pluginId, `Rule '${rawRuleId}' has invalid fix. Expected a function when provided.`, { pluginName, ruleId: rawRuleId, code: 'plugin-rule-fix-invalid' });
-        }
-    }
-    return {
-        id: rawRuleId,
-        name: rawRuleId,
-        detect: rawRule.detect,
-        severity,
-        weight,
-        fix,
-    };
+    pushError(errors, pluginId, `Invalid plugin contract in '${pluginId}'. Expected an object export with shape { name, rules[] }`, { code: 'plugin-shape-invalid' });
+    return undefined;
 }
-function validatePluginContract(pluginId, candidate) {
-    const errors = [];
-    const warnings = [];
-    if (!candidate || typeof candidate !== 'object') {
-        pushError(errors, pluginId, `Invalid plugin contract in '${pluginId}'. Expected an object export with shape { name, rules[] }`, { code: 'plugin-shape-invalid' });
-        return { errors, warnings };
-    }
-    const plugin = candidate;
+function ensurePluginName(pluginId, plugin, errors) {
     const pluginName = typeof plugin.name === 'string' ? plugin.name.trim() : '';
-    if (!pluginName) {
-        pushError(errors, pluginId, `Invalid plugin contract in '${pluginId}'. Expected 'name' as a non-empty string.`, { code: 'plugin-name-missing' });
-        return { errors, warnings };
-    }
+    if (pluginName)
+        return pluginName;
+    pushError(errors, pluginId, `Invalid plugin contract in '${pluginId}'. Expected 'name' as a non-empty string.`, { code: 'plugin-name-missing' });
+    return undefined;
+}
+function validateApiVersion(plugin, context) {
+    const { pluginId, pluginName, errors, warnings } = context;
     const hasExplicitApiVersion = plugin.apiVersion !== undefined;
     const isLegacyPlugin = !hasExplicitApiVersion;
     if (isLegacyPlugin) {
         pushWarning(warnings, pluginId, `Plugin '${pluginName}' does not declare 'apiVersion'. Assuming ${SUPPORTED_PLUGIN_API_VERSION} for backward compatibility; please add apiVersion: ${SUPPORTED_PLUGIN_API_VERSION}.`, { pluginName, code: 'plugin-api-version-implicit' });
+        return { hasExplicitApiVersion, isLegacyPlugin, isSupported: true };
     }
-    else if (typeof plugin.apiVersion !== 'number' || !Number.isInteger(plugin.apiVersion) || plugin.apiVersion <= 0) {
+    if (typeof plugin.apiVersion !== 'number' || !Number.isInteger(plugin.apiVersion) || plugin.apiVersion <= 0) {
         pushError(errors, pluginId, `Plugin '${pluginName}' has invalid apiVersion '${String(plugin.apiVersion)}'. Expected a positive integer (for example: ${SUPPORTED_PLUGIN_API_VERSION}).`, { pluginName, code: 'plugin-api-version-invalid' });
-        return { errors, warnings };
+        return { hasExplicitApiVersion, isLegacyPlugin, isSupported: false };
     }
-    else if (plugin.apiVersion !== SUPPORTED_PLUGIN_API_VERSION) {
+    if (plugin.apiVersion !== SUPPORTED_PLUGIN_API_VERSION) {
         pushError(errors, pluginId, `Plugin '${pluginName}' targets apiVersion ${plugin.apiVersion}, but this drift build supports apiVersion ${SUPPORTED_PLUGIN_API_VERSION}.`, { pluginName, code: 'plugin-api-version-unsupported' });
-        return { errors, warnings };
+        return { hasExplicitApiVersion, isLegacyPlugin, isSupported: false };
     }
-    let capabilities;
-    if (plugin.capabilities !== undefined) {
-        if (!plugin.capabilities || typeof plugin.capabilities !== 'object' || Array.isArray(plugin.capabilities)) {
-            pushError(errors, pluginId, `Plugin '${pluginName}' has invalid capabilities metadata. Expected an object map like { "fixes": true } when provided.`, { pluginName, code: 'plugin-capabilities-invalid' });
-            return { errors, warnings };
-        }
-        const entries = Object.entries(plugin.capabilities);
-        for (const [capabilityKey, capabilityValue] of entries) {
-            const capabilityType = typeof capabilityValue;
-            if (capabilityType !== 'string' && capabilityType !== 'number' && capabilityType !== 'boolean') {
-                pushError(errors, pluginId, `Plugin '${pluginName}' capability '${capabilityKey}' has invalid value type '${capabilityType}'. Allowed: string | number | boolean.`, { pluginName, code: 'plugin-capabilities-value-invalid' });
-            }
-        }
-        if (errors.length > 0) {
-            return { errors, warnings };
-        }
-        capabilities = plugin.capabilities;
-    }
-    if (!Array.isArray(plugin.rules)) {
-        pushError(errors, pluginId, `Invalid plugin '${pluginName}'. Expected 'rules' to be an array.`, { pluginName, code: 'plugin-rules-not-array' });
+    return { hasExplicitApiVersion, isLegacyPlugin, isSupported: true };
+}
+function validatePluginContractData(pluginId, candidate) {
+    const errors = [];
+    const warnings = [];
+    const plugin = ensureObjectCandidate(pluginId, candidate, errors);
+    if (!plugin)
         return { errors, warnings };
-    }
-    const normalizedRules = [];
-    const seenRuleIds = new Set();
-    for (const [ruleIndex, rawRule] of plugin.rules.entries()) {
-        if (!rawRule || typeof rawRule !== 'object') {
-            pushError(errors, pluginId, `Invalid rule at index ${ruleIndex} in plugin '${pluginName}'. Expected an object.`, { pluginName, code: 'plugin-rule-shape-invalid' });
-            continue;
-        }
-        const normalized = normalizeRule(pluginId, pluginName, rawRule, ruleIndex, { strictRuleId: !isLegacyPlugin }, errors, warnings);
-        if (normalized) {
-            if (seenRuleIds.has(normalized.id ?? normalized.name)) {
-                pushError(errors, pluginId, `Plugin '${pluginName}' defines duplicate rule id '${normalized.id ?? normalized.name}'. Rule ids must be unique within a plugin.`, { pluginName, ruleId: normalized.id ?? normalized.name, code: 'plugin-rule-id-duplicate' });
-                continue;
-            }
-            seenRuleIds.add(normalized.id ?? normalized.name);
-            normalizedRules.push(normalized);
-        }
-    }
-    if (normalizedRules.length === 0) {
-        pushError(errors, pluginId, `Plugin '${pluginName}' has no valid rules after validation.`, { pluginName, code: 'plugin-rules-empty' });
+    const pluginName = ensurePluginName(pluginId, plugin, errors);
+    if (!pluginName)
+        return { errors, warnings };
+    const context = { pluginId, pluginName, errors, warnings };
+    const apiVersion = validateApiVersion(plugin, context);
+    if (!apiVersion.isSupported)
+        return { errors, warnings };
+    const capabilities = validateCapabilities(plugin.capabilities, context);
+    if (errors.length > 0)
+        return { errors, warnings };
+    const normalizedRules = normalizeRules(plugin.rules, apiVersion.isLegacyPlugin, context);
+    if (!normalizedRules)
         return { errors, warnings };
-    }
     return {
         plugin: {
             name: pluginName,
-            apiVersion: hasExplicitApiVersion ? plugin.apiVersion : SUPPORTED_PLUGIN_API_VERSION,
+            apiVersion: apiVersion.hasExplicitApiVersion ? plugin.apiVersion : SUPPORTED_PLUGIN_API_VERSION,
             capabilities,
             rules: normalizedRules,
         },
@@ -173,6 +74,9 @@ function validatePluginContract(pluginId, candidate) {
         warnings,
     };
 }
+function validatePluginContract(pluginId, candidate) {
+    return validatePluginContractData(pluginId, candidate);
+}
 function resolvePluginSpecifier(projectRoot, pluginId) {
     if (pluginId.startsWith('.') || pluginId.startsWith('/')) {
         const abs = isAbsolute(pluginId) ? pluginId : resolve(projectRoot, pluginId);
@@ -205,9 +109,8 @@ export function loadPlugins(projectRoot, pluginIds) {
             const validation = validatePluginContract(pluginId, normalized);
             errors.push(...validation.errors);
             warnings.push(...validation.warnings);
-            if (!validation.plugin) {
+            if (!validation.plugin)
                 continue;
-            }
             loaded.push({ id: pluginId, plugin: validation.plugin });
         }
         catch (error) {