@eduardbar/drift 0.3.0 → 0.5.0

package/dist/cli.js

@@ -4,7 +4,10 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { analyzeProject } from './analyzer.js';
 import { buildReport, formatMarkdown, formatAIOutput } from './reporter.js';
-import { printConsole } from './printer.js';
+import { printConsole, printDiff } from './printer.js';
+import { loadConfig } from './config.js';
+import { extractFilesAtRef, cleanupTempDir } from './git.js';
+import { computeDiff } from './diff.js';
 const program = new Command();
 program
     .name('drift')
@@ -18,10 +21,11 @@ program
     .option('--ai', 'Output AI-optimized JSON for LLM consumption')
     .option('--fix', 'Show fix suggestions for each issue')
     .option('--min-score <n>', 'Exit with code 1 if overall score exceeds this threshold', '0')
-    .action((targetPath, options) => {
+    .action(async (targetPath, options) => {
     const resolvedPath = resolve(targetPath ?? '.');
     process.stderr.write(`\nScanning ${resolvedPath}...\n`);
-    const files = analyzeProject(resolvedPath);
+    const config = await loadConfig(resolvedPath);
+    const files = analyzeProject(resolvedPath, config);
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`);
     const report = buildReport(resolvedPath, files);
     if (options.ai) {
@@ -46,5 +50,50 @@ program
         process.exit(1);
     }
 });
+program
+    .command('diff [ref]')
+    .description('Compare current state against a git ref (default: HEAD~1)')
+    .option('--json', 'Output raw JSON diff')
+    .action(async (ref, options) => {
+    const baseRef = ref ?? 'HEAD~1';
+    const projectPath = resolve('.');
+    let tempDir;
+    try {
+        process.stderr.write(`\nComputing diff: HEAD vs ${baseRef}...\n\n`);
+        // Scan current state
+        const config = await loadConfig(projectPath);
+        const currentFiles = analyzeProject(projectPath, config);
+        const currentReport = buildReport(projectPath, currentFiles);
+        // Extract base state from git
+        tempDir = extractFilesAtRef(projectPath, baseRef);
+        const baseFiles = analyzeProject(tempDir, config);
+        // Remap base file paths to match current project paths
+        // (temp dir paths → project paths for accurate comparison)
+        const baseReport = buildReport(tempDir, baseFiles);
+        const remappedBase = {
+            ...baseReport,
+            files: baseReport.files.map(f => ({
+                ...f,
+                path: f.path.replace(tempDir, projectPath),
+            })),
+        };
+        const diff = computeDiff(remappedBase, currentReport, baseRef);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(diff, null, 2) + '\n');
+        }
+        else {
+            printDiff(diff);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`\n  Error: ${message}\n\n`);
+        process.exit(1);
+    }
+    finally {
+        if (tempDir)
+            cleanupTempDir(tempDir);
+    }
+});
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+import type { DriftConfig } from './types.js';
+/**
+ * Load drift.config.ts / .js / .json from the given project root.
+ * Returns undefined if no config file is found.
+ *
+ * Search order (first match wins):
+ *   1. drift.config.ts
+ *   2. drift.config.js
+ *   3. drift.config.json
+ */
+export declare function loadConfig(projectRoot: string): Promise<DriftConfig | undefined>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Load drift.config.ts / .js / .json from the given project root.
+ * Returns undefined if no config file is found.
+ *
+ * Search order (first match wins):
+ *   1. drift.config.ts
+ *   2. drift.config.js
+ *   3. drift.config.json
+ */
+export async function loadConfig(projectRoot) {
+    const candidates = [
+        join(projectRoot, 'drift.config.ts'),
+        join(projectRoot, 'drift.config.js'),
+        join(projectRoot, 'drift.config.json'),
+    ];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const ext = candidate.split('.').pop();
+            if (ext === 'json') {
+                const { readFileSync } = await import('node:fs');
+                return JSON.parse(readFileSync(candidate, 'utf-8'));
+            }
+            // .ts / .js — dynamic import via file URL
+            const fileUrl = pathToFileURL(resolve(candidate)).href;
+            const mod = await import(fileUrl);
+            const config = mod.default ?? mod;
+            return config;
+        }
+        catch {
+            // drift-ignore: catch-swallow — config is optional; load failure is non-fatal
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/diff.d.ts

@@ -0,0 +1,10 @@
+import type { DriftReport, DriftDiff } from './types.js';
+/**
+ * Compute the diff between two DriftReports.
+ *
+ * Issues are matched by (rule + line + column) as a unique key within a file.
+ * A "new" issue exists in `current` but not in `base`.
+ * A "resolved" issue exists in `base` but not in `current`.
+ */
+export declare function computeDiff(base: DriftReport, current: DriftReport, baseRef: string): DriftDiff;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.js

@@ -0,0 +1,58 @@
+/**
+ * Compute the diff between two DriftReports.
+ *
+ * Issues are matched by (rule + line + column) as a unique key within a file.
+ * A "new" issue exists in `current` but not in `base`.
+ * A "resolved" issue exists in `base` but not in `current`.
+ */
+export function computeDiff(base, current, baseRef) {
+    const fileDiffs = [];
+    // Build a map of base files by path for O(1) lookup
+    const baseByPath = new Map(base.files.map(f => [f.path, f]));
+    const currentByPath = new Map(current.files.map(f => [f.path, f]));
+    // All unique paths across both reports
+    const allPaths = new Set([
+        ...base.files.map(f => f.path),
+        ...current.files.map(f => f.path),
+    ]);
+    for (const filePath of allPaths) {
+        const baseFile = baseByPath.get(filePath);
+        const currentFile = currentByPath.get(filePath);
+        const scoreBefore = baseFile?.score ?? 0;
+        const scoreAfter = currentFile?.score ?? 0;
+        const scoreDelta = scoreAfter - scoreBefore;
+        const baseIssues = baseFile?.issues ?? [];
+        const currentIssues = currentFile?.issues ?? [];
+        // Issue identity key: rule + line + column
+        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)));
+        // Only include files that have actual changes
+        if (scoreDelta !== 0 || newIssues.length > 0 || resolvedIssues.length > 0) {
+            fileDiffs.push({
+                path: filePath,
+                scoreBefore,
+                scoreAfter,
+                scoreDelta,
+                newIssues,
+                resolvedIssues,
+            });
+        }
+    }
+    // Sort: most regressed first, then most improved last
+    fileDiffs.sort((a, b) => b.scoreDelta - a.scoreDelta);
+    return {
+        baseRef,
+        projectPath: current.targetPath,
+        scannedAt: new Date().toISOString(),
+        files: fileDiffs,
+        totalScoreBefore: base.totalScore,
+        totalScoreAfter: current.totalScore,
+        totalDelta: current.totalScore - base.totalScore,
+        newIssuesCount: fileDiffs.reduce((sum, f) => sum + f.newIssues.length, 0),
+        resolvedIssuesCount: fileDiffs.reduce((sum, f) => sum + f.resolvedIssues.length, 0),
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/git.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Extract all TypeScript files from the project at a given git ref into a
+ * temporary directory. Returns the temp directory path.
+ *
+ * Uses `git ls-tree` to list files and `git show <ref>:<path>` to read each
+ * file — no checkout, no stash, no repo state mutation.
+ *
+ * Throws if the directory is not a git repo or the ref is invalid.
+ */
+export declare function extractFilesAtRef(projectPath: string, ref: string): string;
+/**
+ * Clean up a temporary directory created by extractFilesAtRef.
+ */
+export declare function cleanupTempDir(tempDir: string): void;
+/**
+ * Get the short hash of a git ref for display purposes.
+ */
+export declare function resolveRefHash(projectPath: string, ref: string): string;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.js

@@ -0,0 +1,84 @@
+import { execSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+/**
+ * Extract all TypeScript files from the project at a given git ref into a
+ * temporary directory. Returns the temp directory path.
+ *
+ * Uses `git ls-tree` to list files and `git show <ref>:<path>` to read each
+ * file — no checkout, no stash, no repo state mutation.
+ *
+ * Throws if the directory is not a git repo or the ref is invalid.
+ */
+export function extractFilesAtRef(projectPath, ref) {
+    // Verify git repo
+    try {
+        execSync('git rev-parse --git-dir', { cwd: projectPath, stdio: 'pipe' });
+    }
+    catch {
+        throw new Error(`Not a git repository: ${projectPath}`);
+    }
+    // Verify ref exists
+    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)
+    let fileList;
+    try {
+        fileList = execSync(`git ls-tree -r --name-only ${ref}`, { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' });
+    }
+    catch {
+        throw new Error(`Failed to list files at ref '${ref}'`);
+    }
+    const tsFiles = fileList
+        .split('\n')
+        .map(f => f.trim())
+        .filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts'));
+    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');
+    }
+    return tempDir;
+}
+/**
+ * Clean up a temporary directory created by extractFilesAtRef.
+ */
+export function cleanupTempDir(tempDir) {
+    if (existsSync(tempDir)) {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Get the short hash of a git ref for display purposes.
+ */
+export function resolveRefHash(projectPath, ref) {
+    try {
+        return execSync(`git rev-parse --short ${ref}`, { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    }
+    catch {
+        return ref;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { analyzeProject, analyzeFile } from './analyzer.js';
 export { buildReport, formatMarkdown } from './reporter.js';
-export type { DriftReport, FileReport, DriftIssue } from './types.js';
+export { computeDiff } from './diff.js';
+export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,4 @@
 export { analyzeProject, analyzeFile } from './analyzer.js';
 export { buildReport, formatMarkdown } from './reporter.js';
+export { computeDiff } from './diff.js';
 //# sourceMappingURL=index.js.map

package/dist/printer.d.ts

@@ -1,5 +1,6 @@
-import type { DriftReport } from './types.js';
+import type { DriftReport, DriftDiff } from './types.js';
 export declare function printConsole(report: DriftReport, options?: {
     showFix?: boolean;
 }): void;
+export declare function printDiff(diff: DriftDiff): void;
 //# sourceMappingURL=printer.d.ts.map

package/dist/printer.js

@@ -33,6 +33,84 @@ function formatFixSuggestion(issue) {
             'Consolidate with existing function',
             'Or rename to clarify different behavior',
         ],
+        'high-complexity': [
+            'Extract each branch into a named function',
+            'Use early returns to reduce nesting and branching',
+            'Consider a strategy pattern or lookup table for switch-heavy logic',
+        ],
+        'deep-nesting': [
+            'Invert conditions and return early instead of nesting',
+            'Extract inner blocks into separate functions',
+            'Flatten promise chains with async/await',
+        ],
+        'too-many-params': [
+            'Group related params into an options object: foo({ a, b, c, d, e })',
+            'Consider if this function is doing too many things',
+        ],
+        'high-coupling': [
+            'Group related imports into a single module',
+            'Consider if this file has too many responsibilities',
+            'Extract a sub-module that encapsulates some of these dependencies',
+        ],
+        'promise-style-mix': [
+            'Pick one style and use it consistently: async/await is preferred',
+            'Convert .then()/.catch() chains to async/await',
+        ],
+        'magic-number': [
+            'Extract to a named constant: const MAX_RETRIES = 3',
+            'Use an enum for related numeric values',
+        ],
+        'comment-contradiction': [
+            'Remove the comment — the code already says what it does',
+            'Replace with a comment explaining WHY, not what: // retry because upstream is flaky',
+        ],
+        'unused-export': [
+            "Remove the export keyword if it's only used internally",
+            'Or delete the declaration entirely if it serves no purpose',
+        ],
+        'dead-file': [
+            'Delete the file if it is no longer needed',
+            'Or import it from an entry point if it should be active',
+        ],
+        'unused-dependency': [
+            'Remove it from package.json: npm uninstall <pkg>',
+            'Or verify it is used transitively and document why it is kept',
+        ],
+        'circular-dependency': [
+            'Introduce an abstraction (interface or shared module) that both files depend on',
+            'Move shared logic to a third file that neither of the cyclic modules imports',
+            'Use dependency injection to break the compile-time dependency',
+        ],
+        'layer-violation': [
+            'Move the import to a layer that is allowed to access this dependency',
+            'Introduce a port/interface in the domain layer to invert the dependency (Dependency Inversion Principle)',
+            'Or adjust the layer rules in drift.config.ts if this import is intentional',
+        ],
+        'cross-boundary-import': [
+            "Import from the module's public API barrel (index.ts) instead of internal paths",
+            'Or add the module to allowedExternalImports in drift.config.ts if this is intentional',
+            'Consider using dependency injection or an event bus to decouple the modules',
+        ],
+        'over-commented': [
+            'Remove comments that restate what the code already expresses clearly',
+            'Keep only comments that explain WHY, not WHAT — prefer self-documenting names',
+        ],
+        'hardcoded-config': [
+            'Move the value to an environment variable: process.env.YOUR_VAR',
+            'Or extract it to a config file / constants module imported at the top',
+        ],
+        'inconsistent-error-handling': [
+            'Pick one style (async/await + try/catch is preferred) and apply it consistently',
+            'Avoid mixing .then()/.catch() with await in the same file',
+        ],
+        'unnecessary-abstraction': [
+            'Inline the abstraction if it has only one implementation and is never reused',
+            'Or document why the extension point exists (e.g., future plugin system)',
+        ],
+        'naming-inconsistency': [
+            'Pick one naming convention (camelCase for variables/functions, PascalCase for types)',
+            'Rename snake_case identifiers to camelCase to match TypeScript conventions',
+        ],
     };
     return suggestions[issue.rule] ?? ['Review and fix manually'];
 }
@@ -104,4 +182,54 @@ export function printConsole(report, options) {
         console.log();
     }
 }
+export function printDiff(diff) {
+    const { totalDelta, totalScoreBefore, totalScoreAfter, newIssuesCount, resolvedIssuesCount } = diff;
+    const deltaSign = totalDelta > 0 ? '+' : '';
+    const deltaColor = totalDelta > 0 ? kleur.red : totalDelta < 0 ? kleur.green : kleur.white;
+    const baseGrade = scoreToGrade(totalScoreBefore);
+    const headGrade = scoreToGrade(totalScoreAfter);
+    console.log();
+    console.log(kleur.bold('  drift diff') + kleur.gray(`  — comparing HEAD vs ${diff.baseRef}`));
+    console.log('  ' + '─'.repeat(50));
+    console.log();
+    console.log(`  Score  ${kleur.bold(String(totalScoreBefore))} ${baseGrade.badge}  →  ` +
+        `${kleur.bold(String(totalScoreAfter))} ${headGrade.badge}  ` +
+        deltaColor(`(${deltaSign}${totalDelta})`));
+    console.log();
+    if (newIssuesCount > 0) {
+        console.log(`  ${kleur.red(`▲ ${newIssuesCount} new issue${newIssuesCount !== 1 ? 's' : ''} introduced`)}`);
+    }
+    if (resolvedIssuesCount > 0) {
+        console.log(`  ${kleur.green(`▼ ${resolvedIssuesCount} issue${resolvedIssuesCount !== 1 ? 's' : ''} resolved`)}`);
+    }
+    if (newIssuesCount === 0 && resolvedIssuesCount === 0) {
+        console.log(`  ${kleur.gray('No issue changes detected')}`);
+    }
+    if (diff.files.length === 0) {
+        console.log();
+        console.log(`  ${kleur.gray('No file-level changes detected')}`);
+        console.log();
+        return;
+    }
+    console.log();
+    console.log('  ' + '─'.repeat(50));
+    console.log();
+    for (const file of diff.files) {
+        const rel = file.path.replace(/\\/g, '/').split('/').pop() ?? file.path;
+        const fileDeltaSign = file.scoreDelta > 0 ? '+' : '';
+        const fileDeltaColor = file.scoreDelta > 0 ? kleur.red : kleur.green;
+        console.log(`  ${kleur.bold(rel)}` +
+            `  ${kleur.gray(`${file.scoreBefore} → ${file.scoreAfter}`)}` +
+            `  ${fileDeltaColor(`${fileDeltaSign}${file.scoreDelta}`)}`);
+        for (const issue of file.newIssues) {
+            console.log(`    ${kleur.red('+')} ${severityIcon(issue.severity)} ` +
+                `${kleur.yellow(issue.rule)}  ${kleur.gray(`L${issue.line}`)}  ${issue.message}`);
+        }
+        for (const issue of file.resolvedIssues) {
+            console.log(`    ${kleur.green('-')} ${severityIcon(issue.severity)} ` +
+                `${kleur.yellow(issue.rule)}  ${kleur.gray(`L${issue.line}`)}  ${issue.message}`);
+        }
+        console.log();
+    }
+}
 //# sourceMappingURL=printer.js.map

package/dist/types.d.ts

@@ -52,4 +52,47 @@ export interface AIIssue {
     fix_suggestion: string;
     effort: 'low' | 'medium' | 'high';
 }
+/**
+ * Layer definition for architectural boundary enforcement.
+ */
+export interface LayerDefinition {
+    name: string;
+    patterns: string[];
+    canImportFrom: string[];
+}
+/**
+ * Module boundary definition for cross-boundary enforcement.
+ */
+export interface ModuleBoundary {
+    name: string;
+    root: string;
+    allowedExternalImports?: string[];
+}
+/**
+ * Optional project-level configuration for drift.
+ * Place in drift.config.ts (or .js / .json) at the project root.
+ */
+export interface DriftConfig {
+    layers?: LayerDefinition[];
+    modules?: ModuleBoundary[];
+}
+export interface FileDiff {
+    path: string;
+    scoreBefore: number;
+    scoreAfter: number;
+    scoreDelta: number;
+    newIssues: DriftIssue[];
+    resolvedIssues: DriftIssue[];
+}
+export interface DriftDiff {
+    baseRef: string;
+    projectPath: string;
+    scannedAt: string;
+    files: FileDiff[];
+    totalScoreBefore: number;
+    totalScoreAfter: number;
+    totalDelta: number;
+    newIssuesCount: number;
+    resolvedIssuesCount: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Detect silent technical debt left by AI-generated code",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,14 @@
   ],
   "author": "eduardbar",
   "license": "MIT",
+  "homepage": "https://github.com/eduardbar/drift#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eduardbar/drift.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eduardbar/drift/issues"
+  },
   "dependencies": {
     "commander": "^14.0.3",
     "kleur": "^4.1.5",