@eduardbar/drift 0.3.0 → 0.5.0

package/src/cli.ts

@@ -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()
 
@@ -21,11 +24,12 @@ 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: string | undefined, options: { output?: string; json?: boolean; ai?: boolean; fix?: 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)
 
@@ -56,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,6 +1,6 @@
 // drift-ignore-file
 import kleur from 'kleur'
-import type { DriftIssue, DriftReport } from './types.js'
+import type { DriftIssue, DriftReport, DriftDiff } from './types.js'
 import { scoreToGrade, severityIcon, scoreBar } from './utils.js'
 
 function formatFixSuggestion(issue: DriftIssue): string[] {
@@ -35,6 +35,84 @@ function formatFixSuggestion(issue: DriftIssue): string[] {
       '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']
 }
@@ -127,3 +205,70 @@ export function printConsole(report: DriftReport, options?: { showFix?: boolean
     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/types.ts

@@ -56,3 +56,59 @@ export interface AIIssue {
   fix_suggestion: string
   effort: 'low' | 'medium' | 'high'
 }
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * 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[]
+}
+
+// ---------------------------------------------------------------------------
+// Diff
+// ---------------------------------------------------------------------------
+
+export interface FileDiff {
+  path: string            // path relativo al project root
+  scoreBefore: number
+  scoreAfter: number
+  scoreDelta: number      // positivo = empeoró (más deuda), negativo = mejoró
+  newIssues: DriftIssue[]
+  resolvedIssues: DriftIssue[]
+}
+
+export interface DriftDiff {
+  baseRef: string         // git ref del baseline (e.g. "HEAD~1", "main")
+  projectPath: string     // path absoluto del proyecto
+  scannedAt: string       // ISO timestamp
+  files: FileDiff[]       // solo archivos con cambios (delta != 0 o issues diff != 0)
+  totalScoreBefore: number
+  totalScoreAfter: number
+  totalDelta: number      // positivo = más deuda, negativo = menos deuda
+  newIssuesCount: number
+  resolvedIssuesCount: number
+}