@eduardbar/drift 1.1.0 → 1.3.0

package/dist/diff.js

@@ -1,7 +1,22 @@
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function normalizeIssueText(value) {
+    return value
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 /**
  * Compute the diff between two DriftReports.
  *
- * Issues are matched by (rule + line + column) as a unique key within a file.
+ * Issues are matched in two passes:
+ * 1) strict location key (rule + line + column)
+ * 2) normalized content key (rule + severity + line + message + snippet)
+ *
+ * This keeps deterministic matching while preventing false churn caused by
+ * cross-platform line ending changes and small column offset noise.
  * A "new" issue exists in `current` but not in `base`.
  * A "resolved" issue exists in `base` but not in `current`.
  */
@@ -11,11 +26,60 @@ function computeFileDiff(filePath, baseFile, currentFile) {
     const scoreDelta = scoreAfter - scoreBefore;
     const baseIssues = baseFile?.issues ?? [];
     const currentIssues = currentFile?.issues ?? [];
-    const issueKey = (i) => `${i.rule}:${i.line}:${i.column}`;
-    const baseKeys = new Set(baseIssues.map(issueKey));
-    const currentKeys = new Set(currentIssues.map(issueKey));
-    const newIssues = currentIssues.filter(i => !baseKeys.has(issueKey(i)));
-    const resolvedIssues = baseIssues.filter(i => !currentKeys.has(issueKey(i)));
+    const strictIssueKey = (i) => `${i.rule}:${i.line}:${i.column}`;
+    const normalizedIssueKey = (i) => {
+        const normalizedMessage = normalizeIssueText(i.message);
+        const normalizedSnippetPrefix = normalizeIssueText(i.snippet).slice(0, 80);
+        return `${i.rule}:${i.severity}:${i.line}:${normalizedMessage}:${normalizedSnippetPrefix}`;
+    };
+    const matchedBaseIndexes = new Set();
+    const matchedCurrentIndexes = new Set();
+    const baseStrictIndex = new Map();
+    for (const [index, issue] of baseIssues.entries()) {
+        const key = strictIssueKey(issue);
+        const bucket = baseStrictIndex.get(key);
+        if (bucket)
+            bucket.push(index);
+        else
+            baseStrictIndex.set(key, [index]);
+    }
+    for (const [currentIndex, issue] of currentIssues.entries()) {
+        const key = strictIssueKey(issue);
+        const bucket = baseStrictIndex.get(key);
+        if (!bucket || bucket.length === 0)
+            continue;
+        const matchedIndex = bucket.shift();
+        if (matchedIndex === undefined)
+            continue;
+        matchedBaseIndexes.add(matchedIndex);
+        matchedCurrentIndexes.add(currentIndex);
+    }
+    const baseNormalizedIndex = new Map();
+    for (const [index, issue] of baseIssues.entries()) {
+        if (matchedBaseIndexes.has(index))
+            continue;
+        const key = normalizedIssueKey(issue);
+        const bucket = baseNormalizedIndex.get(key);
+        if (bucket)
+            bucket.push(index);
+        else
+            baseNormalizedIndex.set(key, [index]);
+    }
+    for (const [currentIndex, issue] of currentIssues.entries()) {
+        if (matchedCurrentIndexes.has(currentIndex))
+            continue;
+        const key = normalizedIssueKey(issue);
+        const bucket = baseNormalizedIndex.get(key);
+        if (!bucket || bucket.length === 0)
+            continue;
+        const matchedIndex = bucket.shift();
+        if (matchedIndex === undefined)
+            continue;
+        matchedBaseIndexes.add(matchedIndex);
+        matchedCurrentIndexes.add(currentIndex);
+    }
+    const newIssues = currentIssues.filter((_, index) => !matchedCurrentIndexes.has(index));
+    const resolvedIssues = baseIssues.filter((_, index) => !matchedBaseIndexes.has(index));
     if (scoreDelta !== 0 || newIssues.length > 0 || resolvedIssues.length > 0) {
         return {
             path: filePath,
@@ -30,11 +94,11 @@ function computeFileDiff(filePath, baseFile, currentFile) {
 }
 export function computeDiff(base, current, baseRef) {
     const fileDiffs = [];
-    const baseByPath = new Map(base.files.map(f => [f.path, f]));
-    const currentByPath = new Map(current.files.map(f => [f.path, f]));
+    const baseByPath = new Map(base.files.map(f => [normalizePath(f.path), f]));
+    const currentByPath = new Map(current.files.map(f => [normalizePath(f.path), f]));
     const allPaths = new Set([
-        ...base.files.map(f => f.path),
-        ...current.files.map(f => f.path),
+        ...base.files.map(f => normalizePath(f.path)),
+        ...current.files.map(f => normalizePath(f.path)),
     ]);
     for (const filePath of allPaths) {
         const baseFile = baseByPath.get(filePath);

package/dist/git.js

@@ -54,6 +54,15 @@ function extractFile(projectPath, ref, filePath, tempDir) {
     mkdirSync(destDir, { recursive: true });
     writeFileSync(destPath, content, 'utf-8');
 }
+function extractArchiveAtRef(projectPath, ref, tempDir) {
+    try {
+        execSync(`git archive --format=tar ${ref} | tar -x -C "${tempDir}"`, { cwd: projectPath, stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function extractFilesAtRef(projectPath, ref) {
     verifyGitRepo(projectPath);
     verifyRefExists(projectPath, ref);
@@ -63,6 +72,9 @@ export function extractFilesAtRef(projectPath, ref) {
     }
     const tempDir = join(tmpdir(), `drift-diff-${randomUUID()}`);
     mkdirSync(tempDir, { recursive: true });
+    if (extractArchiveAtRef(projectPath, ref, tempDir)) {
+        return tempDir;
+    }
     for (const filePath of tsFiles) {
         extractFile(projectPath, ref, filePath, tempDir);
     }

package/dist/index.d.ts

@@ -2,8 +2,12 @@ export { analyzeProject, analyzeFile, RULE_WEIGHTS } from './analyzer.js';
 export { buildReport, formatMarkdown } from './reporter.js';
 export { computeDiff } from './diff.js';
 export { generateReview, formatReviewMarkdown } from './review.js';
+export { buildTrustReport, formatTrustConsole, formatTrustMarkdown, formatTrustJson, shouldFailByMaxRisk, shouldFailTrustGate, normalizeMergeRiskLevel, MERGE_RISK_ORDER, } from './trust.js';
+export { computeTrustKpis, computeTrustKpisFromReports, formatTrustKpiConsole, formatTrustKpiJson, } from './trust-kpi.js';
 export { generateArchitectureMap, generateArchitectureSvg } from './map.js';
-export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff, DriftConfig, RepoQualityScore, MaintenanceRiskMetrics, DriftPlugin, DriftPluginRule, } from './types.js';
+export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff, DriftConfig, RepoQualityScore, MaintenanceRiskMetrics, DriftTrustReport, TrustReason, TrustFixPriority, TrustDiffContext, TrustKpiReport, TrustKpiDiagnostic, TrustDiffTrendSummary, TrustScoreStats, MergeRiskLevel, DriftPlugin, DriftPluginRule, } from './types.js';
 export { loadHistory, saveSnapshot } from './snapshot.js';
 export type { SnapshotEntry, SnapshotHistory } from './snapshot.js';
+export { DEFAULT_SAAS_POLICY, defaultSaasStorePath, resolveSaasPolicy, SaasActorRequiredError, SaasPermissionError, getRequiredRoleForOperation, assertSaasPermission, getSaasEffectiveLimits, getOrganizationEffectiveLimits, changeOrganizationPlan, listOrganizationPlanChanges, getOrganizationUsageSnapshot, ingestSnapshotFromReport, listSaasSnapshots, getSaasSummary, generateSaasDashboardHtml, } from './saas.js';
+export type { SaasRole, SaasPlan, SaasPolicy, SaasPolicyOverrides, SaasStore, SaasSummary, SaasSnapshot, SaasQueryOptions, IngestOptions, SaasPlanChange, SaasOperation, SaasPermissionContext, SaasPermissionResult, SaasEffectiveLimits, SaasOrganizationUsageSnapshot, ChangeOrganizationPlanOptions, SaasUsageQueryOptions, SaasPlanChangeQueryOptions, } from './saas.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,6 +2,9 @@ export { analyzeProject, analyzeFile, RULE_WEIGHTS } from './analyzer.js';
 export { buildReport, formatMarkdown } from './reporter.js';
 export { computeDiff } from './diff.js';
 export { generateReview, formatReviewMarkdown } from './review.js';
+export { buildTrustReport, formatTrustConsole, formatTrustMarkdown, formatTrustJson, shouldFailByMaxRisk, shouldFailTrustGate, normalizeMergeRiskLevel, MERGE_RISK_ORDER, } from './trust.js';
+export { computeTrustKpis, computeTrustKpisFromReports, formatTrustKpiConsole, formatTrustKpiJson, } from './trust-kpi.js';
 export { generateArchitectureMap, generateArchitectureSvg } from './map.js';
 export { loadHistory, saveSnapshot } from './snapshot.js';
+export { DEFAULT_SAAS_POLICY, defaultSaasStorePath, resolveSaasPolicy, SaasActorRequiredError, SaasPermissionError, getRequiredRoleForOperation, assertSaasPermission, getSaasEffectiveLimits, getOrganizationEffectiveLimits, changeOrganizationPlan, listOrganizationPlanChanges, getOrganizationUsageSnapshot, ingestSnapshotFromReport, listSaasSnapshots, getSaasSummary, generateSaasDashboardHtml, } from './saas.js';
 //# sourceMappingURL=index.js.map

package/dist/map.d.ts

@@ -1,3 +1,4 @@
-export declare function generateArchitectureSvg(targetPath: string): string;
-export declare function generateArchitectureMap(targetPath: string, outputFile?: string): string;
+import type { DriftConfig } from './types.js';
+export declare function generateArchitectureSvg(targetPath: string, config?: DriftConfig): string;
+export declare function generateArchitectureMap(targetPath: string, outputFile?: string, config?: DriftConfig): string;
 //# sourceMappingURL=map.d.ts.map

package/dist/map.js

@@ -1,6 +1,8 @@
 import { writeFileSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { Project } from 'ts-morph';
+import { detectLayerViolations } from './rules/phase3-arch.js';
+import { RULE_WEIGHTS } from './analyzer.js';
 function detectLayer(relPath) {
     const normalized = relPath.replace(/\\/g, '/').replace(/^\.\//, '');
     const first = normalized.split('/')[0] || 'root';
@@ -9,7 +11,7 @@ function detectLayer(relPath) {
 function esc(value) {
     return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
-export function generateArchitectureSvg(targetPath) {
+export function generateArchitectureSvg(targetPath, config) {
     const project = new Project({
         skipAddingFilesFromTsConfig: true,
         compilerOptions: { allowJs: true, jsx: 1 },
@@ -26,24 +28,67 @@ export function generateArchitectureSvg(targetPath) {
     ]);
     const layers = new Map();
     const edges = new Map();
+    const layerAdjacency = new Map();
+    const fileImportGraph = new Map();
     for (const file of project.getSourceFiles()) {
-        const rel = relative(targetPath, file.getFilePath()).replace(/\\/g, '/');
+        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());
         for (const decl of file.getImportDeclarations()) {
             const imported = decl.getModuleSpecifierSourceFile();
             if (!imported)
                 continue;
+            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() });
+            }
+        }
+    }
+    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;
@@ -60,19 +105,24 @@ export function generateArchitectureSvg(targetPath) {
         };
     });
     const boxByName = new Map(boxes.map((box) => [box.name, box]));
-    const lines = [...edges.entries()].map(([key, count]) => {
-        const [from, to] = key.split('->');
-        const a = boxByName.get(from);
-        const b = boxByName.get(to);
+    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="#64748b" stroke-width="2" marker-end="url(#arrow)" />
-      <text x="${(startX + endX) / 2}" y="${(startY + endY) / 2 - 4}" fill="#94a3b8" font-size="11" text-anchor="middle">${count}</text>`;
+      <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>
@@ -80,6 +130,8 @@ export function generateArchitectureSvg(targetPath) {
       <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">
@@ -89,13 +141,49 @@ export function generateArchitectureSvg(targetPath) {
   <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>`;
 }
-export function generateArchitectureMap(targetPath, outputFile = 'architecture.svg') {
+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))
+                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}`);
+        }
+        stack.pop();
+        inStack.delete(node);
+    }
+    for (const node of adjacency.keys()) {
+        if (!visited.has(node))
+            dfs(node);
+    }
+    return cycleEdges;
+}
+export function generateArchitectureMap(targetPath, outputFile = 'architecture.svg', config) {
     const resolvedTarget = resolve(targetPath);
-    const svg = generateArchitectureSvg(resolvedTarget);
+    const svg = generateArchitectureSvg(resolvedTarget, config);
     const outPath = resolve(outputFile);
     writeFileSync(outPath, svg, 'utf8');
     return outPath;

package/dist/plugins.d.ts

@@ -1,6 +1,7 @@
-import type { PluginLoadError, LoadedPlugin } from './types.js';
+import type { PluginLoadError, PluginLoadWarning, LoadedPlugin } from './types.js';
 export declare function loadPlugins(projectRoot: string, pluginIds: string[] | undefined): {
     plugins: LoadedPlugin[];
     errors: PluginLoadError[];
+    warnings: PluginLoadWarning[];
 };
 //# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.js

@@ -2,28 +2,176 @@ import { existsSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-function isPluginShape(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const candidate = value;
-    if (typeof candidate.name !== 'string')
-        return false;
-    if (!Array.isArray(candidate.rules))
-        return false;
-    return candidate.rules.every((rule) => rule &&
-        typeof rule === 'object' &&
-        typeof rule.name === 'string' &&
-        typeof rule.detect === 'function');
-}
+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 (isPluginShape(mod))
-        return mod;
     if (mod && typeof mod === 'object' && 'default' in mod) {
-        const maybeDefault = mod.default;
-        if (isPluginShape(maybeDefault))
-            return maybeDefault;
+        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' });
+        }
+    }
+    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,
+    };
+}
+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;
+    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 };
+    }
+    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' });
+    }
+    else 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 };
+    }
+    else 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 };
+    }
+    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 { 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' });
+        return { errors, warnings };
     }
-    return undefined;
+    return {
+        plugin: {
+            name: pluginName,
+            apiVersion: hasExplicitApiVersion ? plugin.apiVersion : SUPPORTED_PLUGIN_API_VERSION,
+            capabilities,
+            rules: normalizedRules,
+        },
+        errors,
+        warnings,
+    };
 }
 function resolvePluginSpecifier(projectRoot, pluginId) {
     if (pluginId.startsWith('.') || pluginId.startsWith('/')) {
@@ -44,31 +192,32 @@ function resolvePluginSpecifier(projectRoot, pluginId) {
 }
 export function loadPlugins(projectRoot, pluginIds) {
     if (!pluginIds || pluginIds.length === 0) {
-        return { plugins: [], errors: [] };
+        return { plugins: [], errors: [], warnings: [] };
     }
     const loaded = [];
     const errors = [];
+    const warnings = [];
     for (const pluginId of pluginIds) {
         const resolved = resolvePluginSpecifier(projectRoot, pluginId);
         try {
             const mod = require(resolved);
-            const plugin = normalizePluginExport(mod);
-            if (!plugin) {
-                errors.push({
-                    pluginId,
-                    message: `Invalid plugin contract in '${pluginId}'. Expected: { name, rules[] }`,
-                });
+            const normalized = normalizePluginExport(mod);
+            const validation = validatePluginContract(pluginId, normalized);
+            errors.push(...validation.errors);
+            warnings.push(...validation.warnings);
+            if (!validation.plugin) {
                 continue;
             }
-            loaded.push({ id: pluginId, plugin });
+            loaded.push({ id: pluginId, plugin: validation.plugin });
         }
         catch (error) {
             errors.push({
                 pluginId,
+                code: 'plugin-load-failed',
                 message: error instanceof Error ? error.message : String(error),
             });
         }
     }
-    return { plugins: loaded, errors };
+    return { plugins: loaded, errors, warnings };
 }
 //# sourceMappingURL=plugins.js.map

package/dist/printer.js

@@ -131,6 +131,10 @@ function formatFixSuggestion(issue) {
             'Fix or remove the failing plugin in drift.config.*',
             'Validate plugin contract: export { name, rules[] } and detector functions',
         ],
+        'plugin-warning': [
+            'Review plugin validation warnings and align with the recommended contract',
+            'Use explicit rule ids and valid severity/weight values',
+        ],
     };
     return suggestions[issue.rule] ?? ['Review and fix manually'];
 }

package/dist/review.js

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path';
+import { relative, resolve } from 'node:path';
 import { analyzeProject } from './analyzer.js';
 import { loadConfig } from './config.js';
 import { buildReport } from './reporter.js';
@@ -48,7 +48,7 @@ export async function generateReview(projectPath, baseRef) {
             ...baseReport,
             files: baseReport.files.map((file) => ({
                 ...file,
-                path: file.path.replace(tempDir, resolvedPath),
+                path: resolve(resolvedPath, relative(tempDir, file.path)),
             })),
         };
         const diff = computeDiff(remappedBase, currentReport, baseRef);

package/dist/rules/comments.js

@@ -1,4 +1,4 @@
-import { hasIgnoreComment } from './shared.js';
+import { hasIgnoreComment, getFileLines } from './shared.js';
 const TRIVIAL_COMMENT_PATTERNS = [
     { comment: /\/\/\s*return\b/i, code: /^\s*return\b/ },
     { comment: /\/\/\s*(increment|increase|add\s+1|plus\s+1)\b/i, code: /\+\+|(\+= ?1)\b/ },
@@ -31,7 +31,7 @@ function checkLineForContradiction(commentLine, nextLine, lineNumber, file) {
 }
 export function detectCommentContradiction(file) {
     const issues = [];
-    const lines = file.getFullText().split('\n');
+    const lines = getFileLines(file);
     for (let i = 0; i < lines.length - 1; i++) {
         const commentLine = lines[i].trim();
         const nextLine = lines[i + 1];

package/dist/rules/complexity.js

@@ -1,5 +1,5 @@
 import { SyntaxKind } from 'ts-morph';
-import { hasIgnoreComment, getSnippet } from './shared.js';
+import { hasIgnoreComment, getSnippet, collectFunctionLikes } from './shared.js';
 const COMPLEXITY_THRESHOLD = 10;
 const INCREMENT_KINDS = [
     SyntaxKind.IfStatement,
@@ -24,12 +24,7 @@ function getCyclomaticComplexity(fn) {
 }
 export function detectHighComplexity(file) {
     const issues = [];
-    const fns = [
-        ...file.getFunctions(),
-        ...file.getDescendantsOfKind(SyntaxKind.ArrowFunction),
-        ...file.getDescendantsOfKind(SyntaxKind.FunctionExpression),
-        ...file.getClasses().flatMap((c) => c.getMethods()),
-    ];
+    const fns = collectFunctionLikes(file);
     for (const fn of fns) {
         const complexity = getCyclomaticComplexity(fn);
         if (complexity > COMPLEXITY_THRESHOLD) {