@eduardbar/drift 1.0.0 → 1.2.0

package/dist/git.js

@@ -12,22 +12,23 @@ import { randomUUID } from 'node:crypto';
  *
  * Throws if the directory is not a git repo or the ref is invalid.
  */
-export function extractFilesAtRef(projectPath, ref) {
-    // Verify git repo
+function verifyGitRepo(projectPath) {
     try {
         execSync('git rev-parse --git-dir', { cwd: projectPath, stdio: 'pipe' });
     }
     catch {
         throw new Error(`Not a git repository: ${projectPath}`);
     }
-    // Verify ref exists
+}
+function verifyRefExists(projectPath, ref) {
     try {
         execSync(`git rev-parse --verify ${ref}`, { cwd: projectPath, stdio: 'pipe' });
     }
     catch {
         throw new Error(`Invalid git ref: '${ref}'. Run 'git log --oneline' to see available commits.`);
     }
-    // List all .ts files tracked at this ref (excluding .d.ts)
+}
+function listTsFilesAtRef(projectPath, ref) {
     let fileList;
     try {
         fileList = execSync(`git ls-tree -r --name-only ${ref}`, { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' });
@@ -35,30 +36,35 @@ export function extractFilesAtRef(projectPath, ref) {
     catch {
         throw new Error(`Failed to list files at ref '${ref}'`);
     }
-    const tsFiles = fileList
+    return fileList
         .split('\n')
         .map(f => f.trim())
         .filter(f => (f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js') || f.endsWith('.jsx')) && !f.endsWith('.d.ts'));
+}
+function extractFile(projectPath, ref, filePath, tempDir) {
+    let content;
+    try {
+        content = execSync(`git show ${ref}:${filePath}`, { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' });
+    }
+    catch {
+        return;
+    }
+    const destPath = join(tempDir, filePath.split('/').join(sep));
+    const destDir = destPath.substring(0, destPath.lastIndexOf(sep));
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(destPath, content, 'utf-8');
+}
+export function extractFilesAtRef(projectPath, ref) {
+    verifyGitRepo(projectPath);
+    verifyRefExists(projectPath, ref);
+    const tsFiles = listTsFilesAtRef(projectPath, ref);
     if (tsFiles.length === 0) {
         throw new Error(`No TypeScript files found at ref '${ref}'`);
     }
-    // Create temp directory
     const tempDir = join(tmpdir(), `drift-diff-${randomUUID()}`);
     mkdirSync(tempDir, { recursive: true });
-    // Extract each file
     for (const filePath of tsFiles) {
-        let content;
-        try {
-            content = execSync(`git show ${ref}:${filePath}`, { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' });
-        }
-        catch {
-            // File may not exist at this ref — skip
-            continue;
-        }
-        const destPath = join(tempDir, filePath.split('/').join(sep));
-        const destDir = destPath.substring(0, destPath.lastIndexOf(sep));
-        mkdirSync(destDir, { recursive: true });
-        writeFileSync(destPath, content, 'utf-8');
+        extractFile(projectPath, ref, filePath, tempDir);
     }
     return tempDir;
 }

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { analyzeProject, analyzeFile, RULE_WEIGHTS } from './analyzer.js';
 export { buildReport, formatMarkdown } from './reporter.js';
 export { computeDiff } from './diff.js';
-export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff, DriftConfig } from './types.js';
+export { generateReview, formatReviewMarkdown } from './review.js';
+export { generateArchitectureMap, generateArchitectureSvg } from './map.js';
+export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff, DriftConfig, RepoQualityScore, MaintenanceRiskMetrics, DriftPlugin, DriftPluginRule, } from './types.js';
+export { loadHistory, saveSnapshot } from './snapshot.js';
+export type { SnapshotEntry, SnapshotHistory } from './snapshot.js';
+export { DEFAULT_SAAS_POLICY, defaultSaasStorePath, resolveSaasPolicy, ingestSnapshotFromReport, getSaasSummary, generateSaasDashboardHtml, } from './saas.js';
+export type { SaasPolicy, SaasStore, SaasSummary, SaasSnapshot, IngestOptions, } from './saas.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,8 @@
 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 { generateArchitectureMap, generateArchitectureSvg } from './map.js';
+export { loadHistory, saveSnapshot } from './snapshot.js';
+export { DEFAULT_SAAS_POLICY, defaultSaasStorePath, resolveSaasPolicy, ingestSnapshotFromReport, getSaasSummary, generateSaasDashboardHtml, } from './saas.js';
 //# sourceMappingURL=index.js.map

package/dist/map.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,191 @@
+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';
+    return first;
+}
+function esc(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function generateArchitectureSvg(targetPath, config) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { allowJs: true, jsx: 1 },
+    });
+    project.addSourceFilesAtPaths([
+        `${targetPath}/**/*.ts`,
+        `${targetPath}/**/*.tsx`,
+        `${targetPath}/**/*.js`,
+        `${targetPath}/**/*.jsx`,
+        `!${targetPath}/**/node_modules/**`,
+        `!${targetPath}/**/dist/**`,
+        `!${targetPath}/**/.next/**`,
+        `!${targetPath}/**/*.d.ts`,
+    ]);
+    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());
+        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;
+    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>`;
+}
+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, config);
+    const outPath = resolve(outputFile);
+    writeFileSync(outPath, svg, 'utf8');
+    return outPath;
+}
+//# sourceMappingURL=map.js.map

package/dist/metrics.d.ts

@@ -0,0 +1,4 @@
+import type { DriftReport, FileReport, MaintenanceRiskMetrics, RepoQualityScore } from './types.js';
+export declare function computeRepoQuality(targetPath: string, files: FileReport[]): RepoQualityScore;
+export declare function computeMaintenanceRisk(report: DriftReport): MaintenanceRiskMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.js

@@ -0,0 +1,176 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, relative } from 'node:path';
+const ARCH_RULES = new Set([
+    'circular-dependency',
+    'layer-violation',
+    'cross-boundary-import',
+    'controller-no-db',
+    'service-no-http',
+]);
+const COMPLEXITY_RULES = new Set([
+    'large-file',
+    'large-function',
+    'high-complexity',
+    'deep-nesting',
+    'too-many-params',
+    'max-function-lines',
+]);
+const AI_RULES = new Set([
+    'over-commented',
+    'hardcoded-config',
+    'inconsistent-error-handling',
+    'unnecessary-abstraction',
+    'naming-inconsistency',
+    'comment-contradiction',
+    'ai-code-smell',
+]);
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function listFilesRecursively(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    const stack = [root];
+    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 {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+function hasNearbyTest(targetPath, filePath) {
+    const rel = relative(targetPath, filePath).replace(/\\/g, '/');
+    const noExt = rel.replace(/\.[^.]+$/, '');
+    const candidates = [
+        `${noExt}.test.ts`,
+        `${noExt}.test.tsx`,
+        `${noExt}.spec.ts`,
+        `${noExt}.spec.tsx`,
+        `${noExt}.test.js`,
+        `${noExt}.spec.js`,
+    ];
+    return candidates.some((candidate) => existsSync(join(targetPath, candidate)));
+}
+function getCommitTouchCount(targetPath, filePath) {
+    try {
+        const rel = relative(targetPath, filePath).replace(/\\/g, '/');
+        const output = execSync(`git rev-list --count HEAD -- "${rel}"`, {
+            cwd: targetPath,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return Number(output) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+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);
+}
+export function computeRepoQuality(targetPath, files) {
+    const allIssues = files.flatMap((file) => file.issues);
+    const sourceFiles = files.filter((file) => !file.path.endsWith('package.json'));
+    const totalFiles = Math.max(sourceFiles.length, 1);
+    const testingCandidates = listFilesRecursively(targetPath).filter((filePath) => /\.(ts|tsx|js|jsx)$/.test(filePath) &&
+        !/\.test\.|\.spec\./.test(filePath) &&
+        !filePath.includes('node_modules'));
+    const withoutTests = testingCandidates.filter((filePath) => !hasNearbyTest(targetPath, filePath)).length;
+    const testing = testingCandidates.length === 0
+        ? 100
+        : clamp(100 - Math.round((withoutTests / testingCandidates.length) * 100), 0, 100);
+    const dimensions = {
+        architecture: qualityFromIssues(totalFiles, allIssues, ARCH_RULES),
+        complexity: qualityFromIssues(totalFiles, allIssues, COMPLEXITY_RULES),
+        'ai-patterns': qualityFromIssues(totalFiles, allIssues, AI_RULES),
+        testing,
+    };
+    const overall = Math.round((dimensions.architecture +
+        dimensions.complexity +
+        dimensions['ai-patterns'] +
+        dimensions.testing) / 4);
+    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,
+        };
+    })
+        .filter((hotspot) => hotspot.risk > 0)
+        .sort((a, b) => b.risk - a.risk)
+        .slice(0, 10);
+    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 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';
+    return {
+        score,
+        level,
+        hotspots,
+        signals: {
+            highComplexityFiles,
+            filesWithoutNearbyTests,
+            frequentChangeFiles,
+        },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/plugins.d.ts

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

package/dist/plugins.js

@@ -0,0 +1,74 @@
+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');
+}
+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 undefined;
+}
+function resolvePluginSpecifier(projectRoot, pluginId) {
+    if (pluginId.startsWith('.') || pluginId.startsWith('/')) {
+        const abs = isAbsolute(pluginId) ? pluginId : resolve(projectRoot, pluginId);
+        if (existsSync(abs))
+            return abs;
+        if (existsSync(`${abs}.js`))
+            return `${abs}.js`;
+        if (existsSync(`${abs}.cjs`))
+            return `${abs}.cjs`;
+        if (existsSync(`${abs}.mjs`))
+            return `${abs}.mjs`;
+        if (existsSync(`${abs}.ts`))
+            return `${abs}.ts`;
+        return abs;
+    }
+    return pluginId;
+}
+export function loadPlugins(projectRoot, pluginIds) {
+    if (!pluginIds || pluginIds.length === 0) {
+        return { plugins: [], errors: [] };
+    }
+    const loaded = [];
+    const errors = [];
+    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[] }`,
+                });
+                continue;
+            }
+            loaded.push({ id: pluginId, plugin });
+        }
+        catch (error) {
+            errors.push({
+                pluginId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { plugins: loaded, errors };
+}
+//# sourceMappingURL=plugins.js.map

package/dist/printer.js

@@ -111,6 +111,26 @@ function formatFixSuggestion(issue) {
             'Pick one naming convention (camelCase for variables/functions, PascalCase for types)',
             'Rename snake_case identifiers to camelCase to match TypeScript conventions',
         ],
+        'controller-no-db': [
+            'Move DB access to a service/repository and inject it into the controller',
+            'Keep controllers focused on transport and orchestration only',
+        ],
+        'service-no-http': [
+            'Move HTTP concerns to adapters/clients and keep services framework-agnostic',
+            'Inject interfaces for outbound calls instead of calling fetch/express directly',
+        ],
+        'max-function-lines': [
+            'Split the function into smaller units with clear responsibilities',
+            'Extract branch-heavy chunks into dedicated helpers',
+        ],
+        'ai-code-smell': [
+            'Address the listed AI-smell signals in this file before adding more code',
+            'Prioritize consistency: naming, error handling, and abstraction level',
+        ],
+        'plugin-error': [
+            'Fix or remove the failing plugin in drift.config.*',
+            'Validate plugin contract: export { name, rules[] } and detector functions',
+        ],
     };
     return suggestions[issue.rule] ?? ['Review and fix manually'];
 }

package/dist/report.js

@@ -638,6 +638,8 @@ export function generateHtmlReport(report) {
     const projColor = scoreColor(report.totalScore);
     const projLabel = scoreLabel(report.totalScore);
     const projGrade = scoreGrade(report.totalScore);
+    const quality = report.quality;
+    const risk = report.maintenanceRisk;
     const filesWithIssues = report.files.filter(f => f.issues.length > 0).length;
     // ── Top rules for sidebar ──────────────────────────────────────────────
     const topRules = Object.entries(report.summary.byRule)
@@ -648,6 +650,16 @@ export function generateHtmlReport(report) {
           <span class="rule-name">${escapeHtml(rule)}</span>
           <span class="rule-count">${count}</span>
         </button>`).join('');
+    const hotspotsHtml = risk.hotspots.length === 0
+        ? '<div class="empty-state" style="padding:0.8rem">No hotspots detected.</div>'
+        : risk.hotspots.slice(0, 5).map((hotspot) => `
+      <div class="issue-row" style="grid-template-columns: 62px 1fr;grid-template-rows:auto auto;">
+        <span class="issue-line">R${hotspot.risk}</span>
+        <div class="issue-rule-msg">
+          <span class="issue-rule">hotspot</span>
+          <span class="issue-msg">${escapeHtml(hotspot.file)} (${hotspot.reasons.join(', ')})</span>
+        </div>
+      </div>`).join('');
     // ── File sections ──────────────────────────────────────────────────────
     const fileSections = report.files
         .filter(f => f.issues.length > 0)
@@ -755,6 +767,21 @@ export function generateHtmlReport(report) {
           </div>
         </div>
 
+        <div class="sidebar-block">
+          <div class="sidebar-label">Repo Quality</div>
+          <div style="font-size:1.1rem;font-weight:700;color:${scoreColor(100 - quality.overall)}">${quality.overall}/100</div>
+          <div style="font-size:0.72rem;color:var(--muted)">Architecture ${quality.dimensions.architecture} · Complexity ${quality.dimensions.complexity}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">AI patterns ${quality.dimensions['ai-patterns']} · Testing ${quality.dimensions.testing}</div>
+        </div>
+
+        <div class="sidebar-block">
+          <div class="sidebar-label">Maintenance Risk</div>
+          <div style="font-size:1.1rem;font-weight:700;color:${scoreColor(risk.score)}">${risk.score}/100 (${risk.level.toUpperCase()})</div>
+          <div style="font-size:0.72rem;color:var(--muted)">High complexity: ${risk.signals.highComplexityFiles}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">No tests: ${risk.signals.filesWithoutNearbyTests}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">Frequent changes: ${risk.signals.frequentChangeFiles}</div>
+        </div>
+
         <!-- Severity filters -->
         <div class="sidebar-block">
           <div class="sidebar-label">Severity</div>
@@ -804,6 +831,13 @@ export function generateHtmlReport(report) {
         <div class="main-header">
           <span id="issue-counter" style="color:var(--muted);font-size:0.75rem">Loading…</span>
         </div>
+        <section class="file-section" open>
+          <summary>
+            <span class="file-name">Risk hotspots</span>
+            <span class="file-score" style="color:${scoreColor(risk.score)}">${risk.score}/100</span>
+          </summary>
+          <div class="issues-list">${hotspotsHtml}</div>
+        </section>
         ${fileSections || noIssues}
       </main>