@eduardbar/drift 0.2.3 → 0.3.0

package/README.md

@@ -72,6 +72,8 @@ npx @eduardbar/drift scan .
 npx @eduardbar/drift scan ./src
 npx @eduardbar/drift scan ./src --output report.md
 npx @eduardbar/drift scan ./src --json
+npx @eduardbar/drift scan ./src --ai
+npx @eduardbar/drift scan ./src --fix
 npx @eduardbar/drift scan ./src --min-score 50
 
 # Install globally if you want the short 'drift' command
@@ -85,8 +87,29 @@ drift scan .
 |------|-------------|
 | `--output <file>` | Write Markdown report to a file |
 | `--json` | Output raw JSON instead of console output |
+| `--ai` | Output AI-optimized JSON for LLM consumption (Claude, GPT, etc.) |
+| `--fix` | Show fix suggestions for each detected issue |
 | `--min-score <n>` | Exit with code 1 if overall score exceeds threshold |
 
+### AI Integration
+
+Use `--ai` to get structured output that LLMs can consume:
+
+```bash
+npx @eduardbar/drift scan ./src --ai
+```
+
+Output includes:
+- Priority-ordered issues (by severity and effort)
+- Fix suggestions for each issue
+- Recommended action for quick wins
+
+Use `--fix` to see concrete fix suggestions in terminal:
+
+```bash
+npx @eduardbar/drift scan ./src --fix
+```
+
 ---
 
 ## 🔍 What it detects

package/dist/cli.js

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { analyzeProject } from './analyzer.js';
-import { buildReport, formatMarkdown } from './reporter.js';
+import { buildReport, formatMarkdown, formatAIOutput } from './reporter.js';
 import { printConsole } from './printer.js';
 const program = new Command();
 program
@@ -15,6 +15,8 @@ program
     .description('Scan a directory for vibe coding drift')
     .option('-o, --output <file>', 'Write report to a Markdown file')
     .option('--json', 'Output raw JSON report')
+    .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) => {
     const resolvedPath = resolve(targetPath ?? '.');
@@ -22,11 +24,16 @@ program
     const files = analyzeProject(resolvedPath);
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`);
     const report = buildReport(resolvedPath, files);
+    if (options.ai) {
+        const aiOutput = formatAIOutput(report);
+        process.stdout.write(JSON.stringify(aiOutput, null, 2));
+        return;
+    }
     if (options.json) {
         process.stdout.write(JSON.stringify(report, null, 2));
         return;
     }
-    printConsole(report);
+    printConsole(report, { showFix: options.fix });
     if (options.output) {
         const md = formatMarkdown(report);
         const outPath = resolve(options.output);

package/dist/printer.d.ts

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

package/dist/printer.js

@@ -1,7 +1,42 @@
 // drift-ignore-file
 import kleur from 'kleur';
 import { scoreToGrade, severityIcon, scoreBar } from './utils.js';
-export function printConsole(report) {
+function formatFixSuggestion(issue) {
+    const suggestions = {
+        'debug-leftover': [
+            'Remove this console.log statement',
+            'Or replace with a proper logging library',
+        ],
+        'any-abuse': [
+            "Replace 'any' with 'unknown' for type safety",
+            'Or define a proper interface/type for this data',
+        ],
+        'dead-code': [
+            'Remove this unused import',
+        ],
+        'catch-swallow': [
+            'Add error handling: console.error(error) or logger.error(error)',
+            'Or re-throw if this should bubble up: throw error',
+        ],
+        'large-function': [
+            'Extract logic into smaller functions',
+            'Each function should do one thing',
+        ],
+        'large-file': [
+            'Split into multiple files by responsibility',
+            'Consider using a directory with index.ts',
+        ],
+        'no-return-type': [
+            'Add explicit return type: function foo(): ReturnType',
+        ],
+        'duplicate-function-name': [
+            'Consolidate with existing function',
+            'Or rename to clarify different behavior',
+        ],
+    };
+    return suggestions[issue.rule] ?? ['Review and fix manually'];
+}
+export function printConsole(report, options) {
     const sep = kleur.gray('  ' + '─'.repeat(50));
     console.log();
     console.log(kleur.bold().white('  drift') + kleur.gray('  —  vibe coding debt detector'));
@@ -49,7 +84,19 @@ export function printConsole(report) {
                 colorFn(issue.rule) +
                 `  ` +
                 kleur.white(issue.message));
-            if (issue.snippet) {
+            if (options?.showFix) {
+                const fixes = formatFixSuggestion(issue);
+                console.log(kleur.gray('       ┌──────────────────────────────────────────────────────┐'));
+                if (issue.snippet) {
+                    const line = issue.snippet.split('\n')[0].slice(0, 48);
+                    console.log(kleur.gray('       │  ') + kleur.red('- ' + line));
+                }
+                for (const fix of fixes) {
+                    console.log(kleur.gray('       │  ') + kleur.green('+ ' + fix));
+                }
+                console.log(kleur.gray('       └──────────────────────────────────────────────────────┘'));
+            }
+            else if (issue.snippet) {
                 const snippetIndent = '    ' + ' '.repeat(icon.length + 1);
                 console.log(kleur.gray(`${snippetIndent}${issue.snippet.split('\n')[0].slice(0, 120)}`));
             }

package/dist/reporter.d.ts

@@ -1,4 +1,5 @@
-import type { FileReport, DriftReport } from './types.js';
+import type { FileReport, DriftReport, AIOutput } from './types.js';
 export declare function buildReport(targetPath: string, files: FileReport[]): DriftReport;
 export declare function formatMarkdown(report: DriftReport): string;
+export declare function formatAIOutput(report: DriftReport): AIOutput;
 //# sourceMappingURL=reporter.d.ts.map

package/dist/reporter.js

@@ -1,4 +1,26 @@
 import { scoreToGradeText, severityIcon } from './utils.js';
+const FIX_SUGGESTIONS = {
+    'large-file': 'Consider splitting this file into smaller modules with single responsibility',
+    'large-function': 'Extract logic into smaller functions with descriptive names',
+    'debug-leftover': 'Remove this console.log or replace with proper logging library',
+    'dead-code': 'Remove unused import to keep code clean',
+    'duplicate-function-name': 'Consolidate with existing function or rename to clarify different behavior',
+    'any-abuse': "Replace 'any' with proper type definition",
+    'catch-swallow': 'Add error handling or logging in catch block',
+    'no-return-type': 'Add explicit return type for better type safety',
+};
+const RULE_EFFORT = {
+    'debug-leftover': 'low',
+    'dead-code': 'low',
+    'no-return-type': 'low',
+    'any-abuse': 'medium',
+    'catch-swallow': 'medium',
+    'large-file': 'high',
+    'large-function': 'high',
+    'duplicate-function-name': 'high',
+};
+const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+const EFFORT_ORDER = { low: 0, medium: 1, high: 2 };
 export function buildReport(targetPath, files) {
     const allIssues = files.flatMap((f) => f.issues);
     const byRule = {};
@@ -83,4 +105,68 @@ export function formatMarkdown(report) {
     }
     return lines.join('\n');
 }
+function collectAllIssues(report) {
+    const all = [];
+    for (const file of report.files) {
+        for (const issue of file.issues) {
+            all.push({ file: file.path, issue });
+        }
+    }
+    return all;
+}
+function sortIssues(issues) {
+    return issues.sort((a, b) => {
+        const sevDiff = SEVERITY_ORDER[a.issue.severity] - SEVERITY_ORDER[b.issue.severity];
+        if (sevDiff !== 0)
+            return sevDiff;
+        const effortA = RULE_EFFORT[a.issue.rule] ?? 'medium';
+        const effortB = RULE_EFFORT[b.issue.rule] ?? 'medium';
+        return EFFORT_ORDER[effortA] - EFFORT_ORDER[effortB];
+    });
+}
+function buildAIIssue(item, rank) {
+    return {
+        rank,
+        file: item.file,
+        line: item.issue.line,
+        rule: item.issue.rule,
+        severity: item.issue.severity,
+        message: item.issue.message,
+        snippet: item.issue.snippet,
+        fix_suggestion: FIX_SUGGESTIONS[item.issue.rule] ?? 'Review and fix this issue',
+        effort: RULE_EFFORT[item.issue.rule] ?? 'medium',
+    };
+}
+function buildRecommendedAction(priorityOrder) {
+    if (priorityOrder.length === 0)
+        return 'No issues detected. Codebase looks clean.';
+    const lowEffortCount = priorityOrder.filter((i) => i.effort === 'low').length;
+    if (lowEffortCount > 0) {
+        return `Focus on fixing ${lowEffortCount} low-effort issue(s) first - they're quick wins.`;
+    }
+    return 'Start with the highest priority issue and work through them in order.';
+}
+export function formatAIOutput(report) {
+    const allIssues = collectAllIssues(report);
+    const sortedIssues = sortIssues(allIssues);
+    const priorityOrder = sortedIssues.map((item, i) => buildAIIssue(item, i + 1));
+    const rulesDetected = [...new Set(allIssues.map((i) => i.issue.rule))];
+    const grade = scoreToGradeText(report.totalScore);
+    return {
+        summary: {
+            score: report.totalScore,
+            grade: grade.label.toUpperCase(),
+            total_issues: report.totalIssues,
+            files_affected: report.files.length,
+            files_clean: report.totalFiles - report.files.length,
+        },
+        priority_order: priorityOrder,
+        context_for_ai: {
+            project_type: 'typescript',
+            scan_path: report.targetPath,
+            rules_detected: rulesDetected,
+            recommended_action: buildRecommendedAction(priorityOrder),
+        },
+    };
+}
 //# sourceMappingURL=reporter.js.map

package/dist/types.d.ts

@@ -25,4 +25,31 @@ export interface DriftReport {
         byRule: Record<string, number>;
     };
 }
+export interface AIOutput {
+    summary: {
+        score: number;
+        grade: string;
+        total_issues: number;
+        files_affected: number;
+        files_clean: number;
+    };
+    priority_order: AIIssue[];
+    context_for_ai: {
+        project_type: string;
+        scan_path: string;
+        rules_detected: string[];
+        recommended_action: string;
+    };
+}
+export interface AIIssue {
+    rank: number;
+    file: string;
+    line: number;
+    rule: string;
+    severity: string;
+    message: string;
+    snippet: string;
+    fix_suggestion: string;
+    effort: 'low' | 'medium' | 'high';
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Detect silent technical debt left by AI-generated code",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -3,7 +3,7 @@ import { Command } from 'commander'
 import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { analyzeProject } from './analyzer.js'
-import { buildReport, formatMarkdown } from './reporter.js'
+import { buildReport, formatMarkdown, formatAIOutput } from './reporter.js'
 import { printConsole } from './printer.js'
 
 const program = new Command()
@@ -18,8 +18,10 @@ program
   .description('Scan a directory for vibe coding drift')
   .option('-o, --output <file>', 'Write report to a Markdown file')
   .option('--json', 'Output raw JSON report')
+  .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: string | undefined, options: { output?: string; json?: boolean; minScore: string }) => {
+  .action((targetPath: string | undefined, options: { output?: string; json?: boolean; ai?: boolean; fix?: boolean; minScore: string }) => {
     const resolvedPath = resolve(targetPath ?? '.')
 
     process.stderr.write(`\nScanning ${resolvedPath}...\n`)
@@ -27,12 +29,18 @@ program
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
     const report = buildReport(resolvedPath, files)
 
+    if (options.ai) {
+      const aiOutput = formatAIOutput(report)
+      process.stdout.write(JSON.stringify(aiOutput, null, 2))
+      return
+    }
+
     if (options.json) {
       process.stdout.write(JSON.stringify(report, null, 2))
       return
     }
 
-    printConsole(report)
+    printConsole(report, { showFix: options.fix })
 
     if (options.output) {
       const md = formatMarkdown(report)

package/src/printer.ts

@@ -1,9 +1,45 @@
 // drift-ignore-file
 import kleur from 'kleur'
-import type { DriftReport } from './types.js'
+import type { DriftIssue, DriftReport } from './types.js'
 import { scoreToGrade, severityIcon, scoreBar } from './utils.js'
 
-export function printConsole(report: DriftReport): void {
+function formatFixSuggestion(issue: DriftIssue): string[] {
+  const suggestions: Record<string, string[]> = {
+    'debug-leftover': [
+      'Remove this console.log statement',
+      'Or replace with a proper logging library',
+    ],
+    'any-abuse': [
+      "Replace 'any' with 'unknown' for type safety",
+      'Or define a proper interface/type for this data',
+    ],
+    'dead-code': [
+      'Remove this unused import',
+    ],
+    'catch-swallow': [
+      'Add error handling: console.error(error) or logger.error(error)',
+      'Or re-throw if this should bubble up: throw error',
+    ],
+    'large-function': [
+      'Extract logic into smaller functions',
+      'Each function should do one thing',
+    ],
+    'large-file': [
+      'Split into multiple files by responsibility',
+      'Consider using a directory with index.ts',
+    ],
+    'no-return-type': [
+      'Add explicit return type: function foo(): ReturnType',
+    ],
+    'duplicate-function-name': [
+      'Consolidate with existing function',
+      'Or rename to clarify different behavior',
+    ],
+  }
+  return suggestions[issue.rule] ?? ['Review and fix manually']
+}
+
+export function printConsole(report: DriftReport, options?: { showFix?: boolean }): void {
   const sep = kleur.gray('  ' + '─'.repeat(50))
 
   console.log()
@@ -72,7 +108,18 @@ export function printConsole(report: DriftReport): void {
           `  ` +
           kleur.white(issue.message)
       )
-      if (issue.snippet) {
+      if (options?.showFix) {
+        const fixes = formatFixSuggestion(issue)
+        console.log(kleur.gray('       ┌──────────────────────────────────────────────────────┐'))
+        if (issue.snippet) {
+          const line = issue.snippet.split('\n')[0].slice(0, 48)
+          console.log(kleur.gray('       │  ') + kleur.red('- ' + line))
+        }
+        for (const fix of fixes) {
+          console.log(kleur.gray('       │  ') + kleur.green('+ ' + fix))
+        }
+        console.log(kleur.gray('       └──────────────────────────────────────────────────────┘'))
+      } else if (issue.snippet) {
         const snippetIndent = '    ' + ' '.repeat(icon.length + 1)
         console.log(kleur.gray(`${snippetIndent}${issue.snippet.split('\n')[0].slice(0, 120)}`))
       }

package/src/reporter.ts

@@ -1,6 +1,31 @@
-import type { FileReport, DriftReport, DriftIssue } from './types.js'
+import type { FileReport, DriftReport, DriftIssue, AIOutput, AIIssue } from './types.js'
 import { scoreToGradeText, severityIcon } from './utils.js'
 
+const FIX_SUGGESTIONS: Record<string, string> = {
+  'large-file': 'Consider splitting this file into smaller modules with single responsibility',
+  'large-function': 'Extract logic into smaller functions with descriptive names',
+  'debug-leftover': 'Remove this console.log or replace with proper logging library',
+  'dead-code': 'Remove unused import to keep code clean',
+  'duplicate-function-name': 'Consolidate with existing function or rename to clarify different behavior',
+  'any-abuse': "Replace 'any' with proper type definition",
+  'catch-swallow': 'Add error handling or logging in catch block',
+  'no-return-type': 'Add explicit return type for better type safety',
+}
+
+const RULE_EFFORT: Record<string, 'low' | 'medium' | 'high'> = {
+  'debug-leftover': 'low',
+  'dead-code': 'low',
+  'no-return-type': 'low',
+  'any-abuse': 'medium',
+  'catch-swallow': 'medium',
+  'large-file': 'high',
+  'large-function': 'high',
+  'duplicate-function-name': 'high',
+}
+
+const SEVERITY_ORDER: Record<string, number> = { error: 0, warning: 1, info: 2 }
+const EFFORT_ORDER: Record<string, number> = { low: 0, medium: 1, high: 2 }
+
 export function buildReport(targetPath: string, files: FileReport[]): DriftReport {
   const allIssues = files.flatMap((f) => f.issues)
   const byRule: Record<string, number> = {}
@@ -94,3 +119,71 @@ export function formatMarkdown(report: DriftReport): string {
 
   return lines.join('\n')
 }
+
+function collectAllIssues(report: DriftReport): Array<{ file: string; issue: DriftIssue }> {
+  const all: Array<{ file: string; issue: DriftIssue }> = []
+  for (const file of report.files) {
+    for (const issue of file.issues) {
+      all.push({ file: file.path, issue })
+    }
+  }
+  return all
+}
+
+function sortIssues(issues: Array<{ file: string; issue: DriftIssue }>): Array<{ file: string; issue: DriftIssue }> {
+  return issues.sort((a, b) => {
+    const sevDiff = SEVERITY_ORDER[a.issue.severity] - SEVERITY_ORDER[b.issue.severity]
+    if (sevDiff !== 0) return sevDiff
+    const effortA = RULE_EFFORT[a.issue.rule] ?? 'medium'
+    const effortB = RULE_EFFORT[b.issue.rule] ?? 'medium'
+    return EFFORT_ORDER[effortA] - EFFORT_ORDER[effortB]
+  })
+}
+
+function buildAIIssue(item: { file: string; issue: DriftIssue }, rank: number): AIIssue {
+  return {
+    rank,
+    file: item.file,
+    line: item.issue.line,
+    rule: item.issue.rule,
+    severity: item.issue.severity,
+    message: item.issue.message,
+    snippet: item.issue.snippet,
+    fix_suggestion: FIX_SUGGESTIONS[item.issue.rule] ?? 'Review and fix this issue',
+    effort: RULE_EFFORT[item.issue.rule] ?? 'medium',
+  }
+}
+
+function buildRecommendedAction(priorityOrder: AIIssue[]): string {
+  if (priorityOrder.length === 0) return 'No issues detected. Codebase looks clean.'
+  const lowEffortCount = priorityOrder.filter((i) => i.effort === 'low').length
+  if (lowEffortCount > 0) {
+    return `Focus on fixing ${lowEffortCount} low-effort issue(s) first - they're quick wins.`
+  }
+  return 'Start with the highest priority issue and work through them in order.'
+}
+
+export function formatAIOutput(report: DriftReport): AIOutput {
+  const allIssues = collectAllIssues(report)
+  const sortedIssues = sortIssues(allIssues)
+  const priorityOrder = sortedIssues.map((item, i) => buildAIIssue(item, i + 1))
+  const rulesDetected = [...new Set(allIssues.map((i) => i.issue.rule))]
+  const grade = scoreToGradeText(report.totalScore)
+
+  return {
+    summary: {
+      score: report.totalScore,
+      grade: grade.label.toUpperCase(),
+      total_issues: report.totalIssues,
+      files_affected: report.files.length,
+      files_clean: report.totalFiles - report.files.length,
+    },
+    priority_order: priorityOrder,
+    context_for_ai: {
+      project_type: 'typescript',
+      scan_path: report.targetPath,
+      rules_detected: rulesDetected,
+      recommended_action: buildRecommendedAction(priorityOrder),
+    },
+  }
+}

package/src/types.ts

@@ -27,3 +27,32 @@ export interface DriftReport {
     byRule: Record<string, number>
   }
 }
+
+export interface AIOutput {
+  summary: {
+    score: number
+    grade: string
+    total_issues: number
+    files_affected: number
+    files_clean: number
+  }
+  priority_order: AIIssue[]
+  context_for_ai: {
+    project_type: string
+    scan_path: string
+    rules_detected: string[]
+    recommended_action: string
+  }
+}
+
+export interface AIIssue {
+  rank: number
+  file: string
+  line: number
+  rule: string
+  severity: string
+  message: string
+  snippet: string
+  fix_suggestion: string
+  effort: 'low' | 'medium' | 'high'
+}