@eduardbar/drift 0.2.3 → 0.4.0

package/src/cli.ts

@@ -3,8 +3,11 @@ 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 { printConsole } from './printer.js'
+import { buildReport, formatMarkdown, formatAIOutput } from './reporter.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()
 
@@ -18,21 +21,30 @@ 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(async (targetPath: string | undefined, options: { output?: string; json?: boolean; ai?: boolean; fix?: boolean; minScore: string }) => {
     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) {
+      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)
@@ -48,4 +60,53 @@ program
     }
   })
 
+program
+  .command('diff [ref]')
+  .description('Compare current state against a git ref (default: HEAD~1)')
+  .option('--json', 'Output raw JSON diff')
+  .action(async (ref: string | undefined, options: { json?: boolean }) => {
+    const baseRef = ref ?? 'HEAD~1'
+    const projectPath = resolve('.')
+
+    let tempDir: string | undefined
+
+    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()

package/src/config.ts

@@ -0,0 +1,45 @@
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+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 async function loadConfig(projectRoot: string): Promise<DriftConfig | undefined> {
+  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')) as DriftConfig
+      }
+
+      // .ts / .js — dynamic import via file URL
+      const fileUrl = pathToFileURL(resolve(candidate)).href
+      const mod = await import(fileUrl)
+      const config: DriftConfig = mod.default ?? mod
+
+      return config
+    } catch {
+      // drift-ignore: catch-swallow — config is optional; load failure is non-fatal
+    }
+  }
+
+  return undefined
+}

package/src/diff.ts

@@ -0,0 +1,74 @@
+import type { DriftReport, DriftDiff, FileDiff, DriftIssue } 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 function computeDiff(
+  base: DriftReport,
+  current: DriftReport,
+  baseRef: string,
+): DriftDiff {
+  const fileDiffs: FileDiff[] = []
+
+  // 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: DriftIssue) => `${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),
+  }
+}

package/src/git.ts

@@ -0,0 +1,98 @@
+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: string, ref: string): string {
+  // 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: string
+  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: string
+    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: string): void {
+  if (existsSync(tempDir)) {
+    rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Get the short hash of a git ref for display purposes.
+ */
+export function resolveRefHash(projectPath: string, ref: string): string {
+  try {
+    return execSync(
+      `git rev-parse --short ${ref}`,
+      { cwd: projectPath, encoding: 'utf-8', stdio: 'pipe' }
+    ).trim()
+  } catch {
+    return ref
+  }
+}

package/src/index.ts

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

package/src/printer.ts

@@ -1,9 +1,103 @@
 // drift-ignore-file
 import kleur from 'kleur'
-import type { DriftReport } from './types.js'
+import type { DriftIssue, DriftReport, DriftDiff } 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',
+    ],
+    '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',
+    ],
+  }
+  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 +166,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)}`))
       }
@@ -80,3 +185,70 @@ export function printConsole(report: DriftReport): void {
     console.log()
   }
 }
+
+export function printDiff(diff: DriftDiff): void {
+  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()
+  }
+}

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),
+    },
+  }
+}