@eduardbar/drift 1.2.0 → 1.4.0

package/dist/map.js

@@ -3,15 +3,54 @@ import { resolve, relative } from 'node:path';
 import { Project } from 'ts-morph';
 import { detectLayerViolations } from './rules/phase3-arch.js';
 import { RULE_WEIGHTS } from './analyzer.js';
+import { detectCycleEdges } from './map-cycles.js';
+import { renderArchitectureSvg } from './map-svg.js';
 function detectLayer(relPath) {
     const normalized = relPath.replace(/\\/g, '/').replace(/^\.\//, '');
     const first = normalized.split('/')[0] || 'root';
     return first;
 }
-function esc(value) {
-    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+function appendFileLayerContext(filePath, targetPath, layers, fileImportGraph) {
+    const rel = relative(targetPath, filePath).replace(/\\/g, '/');
+    const layerName = detectLayer(rel);
+    if (!layers.has(layerName)) {
+        layers.set(layerName, { name: layerName, files: new Set() });
+    }
+    layers.get(layerName).files.add(rel);
+    if (!fileImportGraph.has(filePath)) {
+        fileImportGraph.set(filePath, new Set());
+    }
+    return { rel, layerName };
 }
-export function generateArchitectureSvg(targetPath, config) {
+function registerImportEdge(layerName, importedLayer, edges, layerAdjacency) {
+    if (importedLayer === layerName)
+        return;
+    const key = `${layerName}->${importedLayer}`;
+    edges.set(key, (edges.get(key) ?? 0) + 1);
+    if (!layerAdjacency.has(layerName)) {
+        layerAdjacency.set(layerName, new Set());
+    }
+    layerAdjacency.get(layerName).add(importedLayer);
+}
+function buildEdgeList(edges, cycleEdges, violationEdges) {
+    const edgeList = [...edges.entries()].map(([key, count]) => {
+        const [from, to] = key.split('->');
+        const kind = violationEdges.has(key)
+            ? 'violation'
+            : cycleEdges.has(key)
+                ? 'cycle'
+                : 'normal';
+        return { key, from, to, count, kind };
+    });
+    for (const key of violationEdges) {
+        if (edges.has(key))
+            continue;
+        const [from, to] = key.split('->');
+        edgeList.push({ key, from, to, count: 1, kind: 'violation' });
+    }
+    return edgeList;
+}
+function createArchitectureProject(targetPath) {
     const project = new Project({
         skipAddingFilesFromTsConfig: true,
         compilerOptions: { allowJs: true, jsx: 1 },
@@ -26,19 +65,16 @@ export function generateArchitectureSvg(targetPath, config) {
         `!${targetPath}/**/.next/**`,
         `!${targetPath}/**/*.d.ts`,
     ]);
+    return project;
+}
+function collectArchitectureGraph(project, targetPath) {
     const layers = new Map();
     const edges = new Map();
     const layerAdjacency = new Map();
     const fileImportGraph = new Map();
     for (const file of project.getSourceFiles()) {
         const filePath = file.getFilePath();
-        const rel = relative(targetPath, filePath).replace(/\\/g, '/');
-        const layerName = detectLayer(rel);
-        if (!layers.has(layerName))
-            layers.set(layerName, { name: layerName, files: new Set() });
-        layers.get(layerName).files.add(rel);
-        if (!fileImportGraph.has(filePath))
-            fileImportGraph.set(filePath, new Set());
+        const { layerName } = appendFileLayerContext(filePath, targetPath, layers, fileImportGraph);
         for (const decl of file.getImportDeclarations()) {
             const imported = decl.getModuleSpecifierSourceFile();
             if (!imported)
@@ -46,140 +82,44 @@ export function generateArchitectureSvg(targetPath, config) {
             fileImportGraph.get(filePath).add(imported.getFilePath());
             const importedRel = relative(targetPath, imported.getFilePath()).replace(/\\/g, '/');
             const importedLayer = detectLayer(importedRel);
-            if (importedLayer === layerName)
-                continue;
-            const key = `${layerName}->${importedLayer}`;
-            edges.set(key, (edges.get(key) ?? 0) + 1);
-            if (!layerAdjacency.has(layerName))
-                layerAdjacency.set(layerName, new Set());
-            layerAdjacency.get(layerName).add(importedLayer);
-        }
-    }
-    const cycleEdges = detectCycleEdges(layerAdjacency);
-    const violationEdges = new Set();
-    if (config?.layers && config.layers.length > 0) {
-        const violations = detectLayerViolations(fileImportGraph, config.layers, targetPath, RULE_WEIGHTS);
-        for (const issues of violations.values()) {
-            for (const issue of issues) {
-                const match = issue.message.match(/Layer '([^']+)' must not import from layer '([^']+)'/);
-                if (!match)
-                    continue;
-                const from = match[1];
-                const to = match[2];
-                violationEdges.add(`${from}->${to}`);
-                if (!layers.has(from))
-                    layers.set(from, { name: from, files: new Set() });
-                if (!layers.has(to))
-                    layers.set(to, { name: to, files: new Set() });
-            }
+            registerImportEdge(layerName, importedLayer, edges, layerAdjacency);
         }
     }
-    const edgeList = [...edges.entries()].map(([key, count]) => {
-        const [from, to] = key.split('->');
-        const kind = violationEdges.has(key)
-            ? 'violation'
-            : cycleEdges.has(key)
-                ? 'cycle'
-                : 'normal';
-        return { key, from, to, count, kind };
-    });
-    for (const key of violationEdges) {
-        if (edges.has(key))
-            continue;
-        const [from, to] = key.split('->');
-        edgeList.push({ key, from, to, count: 1, kind: 'violation' });
-    }
-    const layerList = [...layers.values()].sort((a, b) => a.name.localeCompare(b.name));
-    const width = 960;
-    const rowHeight = 90;
-    const height = Math.max(180, layerList.length * rowHeight + 120);
-    const boxWidth = 240;
-    const boxHeight = 50;
-    const left = 100;
-    const boxes = layerList.map((layer, index) => {
-        const y = 60 + index * rowHeight;
-        return {
-            ...layer,
-            x: left,
-            y,
-        };
-    });
-    const boxByName = new Map(boxes.map((box) => [box.name, box]));
-    const lines = edgeList.map((edge) => {
-        const a = boxByName.get(edge.from);
-        const b = boxByName.get(edge.to);
-        if (!a || !b)
-            return '';
-        const startX = a.x + boxWidth;
-        const startY = a.y + boxHeight / 2;
-        const endX = b.x;
-        const endY = b.y + boxHeight / 2;
-        const stroke = edge.kind === 'violation'
-            ? '#ef4444'
-            : edge.kind === 'cycle'
-                ? '#f59e0b'
-                : '#64748b';
-        const widthPx = edge.kind === 'normal' ? 2 : 3;
-        return `
-      <line x1="${startX}" y1="${startY}" x2="${endX}" y2="${endY}" stroke="${stroke}" stroke-width="${widthPx}" marker-end="url(#arrow)" data-edge="${esc(edge.key)}" data-kind="${edge.kind}" />
-      <text x="${(startX + endX) / 2}" y="${(startY + endY) / 2 - 4}" fill="#94a3b8" font-size="11" text-anchor="middle">${edge.count}</text>`;
-    }).join('');
-    const nodes = boxes.map((box) => `
-    <g>
-      <rect x="${box.x}" y="${box.y}" width="${boxWidth}" height="${boxHeight}" rx="8" fill="#0f172a" stroke="#334155" />
-      <text x="${box.x + 12}" y="${box.y + 22}" fill="#e2e8f0" font-size="13" font-family="monospace">${esc(box.name)}</text>
-      <text x="${box.x + 12}" y="${box.y + 38}" fill="#94a3b8" font-size="11" font-family="monospace">${box.files.size} file(s)</text>
-    </g>`).join('');
-    const cycleCount = edgeList.filter((edge) => edge.kind === 'cycle').length;
-    const violationCount = edgeList.filter((edge) => edge.kind === 'violation').length;
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
-  <defs>
-    <marker id="arrow" markerWidth="10" markerHeight="10" refX="6" refY="3" orient="auto">
-      <path d="M0,0 L0,6 L7,3 z" fill="#64748b"/>
-    </marker>
-  </defs>
-  <rect x="0" y="0" width="${width}" height="${height}" fill="#020617" />
-  <text x="28" y="34" fill="#f8fafc" font-size="16" font-family="monospace">drift architecture map</text>
-  <text x="28" y="54" fill="#94a3b8" font-size="11" font-family="monospace">Layers inferred from top-level directories</text>
-  <text x="28" y="72" fill="#94a3b8" font-size="11" font-family="monospace">Cycle edges: ${cycleCount} | Layer violations: ${violationCount}</text>
-  <line x1="520" y1="66" x2="560" y2="66" stroke="#f59e0b" stroke-width="3" /><text x="567" y="69" fill="#94a3b8" font-size="11" font-family="monospace">cycle</text>
-  <line x1="630" y1="66" x2="670" y2="66" stroke="#ef4444" stroke-width="3" /><text x="677" y="69" fill="#94a3b8" font-size="11" font-family="monospace">violation</text>
-  ${lines}
-  ${nodes}
-</svg>`;
+    return { layers, edges, layerAdjacency, fileImportGraph };
 }
-function detectCycleEdges(adjacency) {
-    const visited = new Set();
-    const inStack = new Set();
-    const stack = [];
-    const cycleEdges = new Set();
-    function dfs(node) {
-        visited.add(node);
-        inStack.add(node);
-        stack.push(node);
-        for (const neighbor of adjacency.get(node) ?? []) {
-            if (!visited.has(neighbor)) {
-                dfs(neighbor);
-                continue;
-            }
-            if (!inStack.has(neighbor))
+function collectViolationEdges(config, fileImportGraph, targetPath, layers) {
+    const violationEdges = new Set();
+    if (!config?.layers?.length)
+        return violationEdges;
+    const violations = detectLayerViolations(fileImportGraph, config.layers, targetPath, RULE_WEIGHTS);
+    for (const issues of violations.values()) {
+        for (const issue of issues) {
+            const match = issue.message.match(/Layer '([^']+)' must not import from layer '([^']+)'/);
+            if (!match)
                 continue;
-            const startIndex = stack.indexOf(neighbor);
-            if (startIndex >= 0) {
-                for (let i = startIndex; i < stack.length - 1; i++) {
-                    cycleEdges.add(`${stack[i]}->${stack[i + 1]}`);
-                }
-            }
-            cycleEdges.add(`${node}->${neighbor}`);
+            const from = match[1];
+            const to = match[2];
+            violationEdges.add(`${from}->${to}`);
+            if (!layers.has(from))
+                layers.set(from, { name: from, files: new Set() });
+            if (!layers.has(to))
+                layers.set(to, { name: to, files: new Set() });
         }
-        stack.pop();
-        inStack.delete(node);
-    }
-    for (const node of adjacency.keys()) {
-        if (!visited.has(node))
-            dfs(node);
     }
-    return cycleEdges;
+    return violationEdges;
+}
+export function generateArchitectureSvg(targetPath, config) {
+    const project = createArchitectureProject(targetPath);
+    const { layers, edges, layerAdjacency, fileImportGraph } = collectArchitectureGraph(project, targetPath);
+    const cycleEdges = detectCycleEdges(layerAdjacency);
+    const violationEdges = collectViolationEdges(config, fileImportGraph, targetPath, layers);
+    const edgeList = buildEdgeList(edges, cycleEdges, violationEdges);
+    return renderArchitectureSvg({
+        layers,
+        edgeList,
+        cycleCount: edgeList.filter((edge) => edge.kind === 'cycle').length,
+        violationCount: edgeList.filter((edge) => edge.kind === 'violation').length,
+    });
 }
 export function generateArchitectureMap(targetPath, outputFile = 'architecture.svg', config) {
     const resolvedTarget = resolve(targetPath);

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