@eduardbar/drift 1.0.0 → 1.1.0

package/src/fix.ts

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { analyzeProject, analyzeFile } from './analyzer.js'
-import type { DriftIssue, DriftConfig } from './types.js'
+import type { DriftIssue, DriftConfig, FileReport } from './types.js'
 import { Project } from 'ts-morph'
 
 export interface FixResult {
@@ -10,6 +10,8 @@ export interface FixResult {
   line: number
   description: string
   applied: boolean
+  before?: string
+  after?: string
 }
 
 const FIXABLE_RULES = new Set(['debug-leftover', 'catch-swallow'])
@@ -73,15 +75,84 @@ function applyFixToLines(
   return null
 }
 
+function collectFixableIssues(
+  fileReports: FileReport[],
+  options?: { rule?: string }
+): Map<string, DriftIssue[]> {
+  const fixableByFile = new Map<string, DriftIssue[]>()
+
+  for (const report of fileReports) {
+    const fixableIssues = report.issues.filter(issue => {
+      if (!isFixable(issue)) return false
+      if (options?.rule && issue.rule !== options.rule) return false
+      return true
+    })
+
+    if (fixableIssues.length > 0) {
+      fixableByFile.set(report.path, fixableIssues)
+    }
+  }
+
+  return fixableByFile
+}
+
+function processFile(
+  filePath: string,
+  issues: DriftIssue[],
+  dryRun: boolean
+): FixResult[] {
+  const content = readFileSync(filePath, 'utf8')
+  let lines = content.split('\n')
+  const results: FixResult[] = []
+
+  const sortedIssues = [...issues].sort((a, b) => b.line - a.line)
+
+  for (const issue of sortedIssues) {
+    const before = lines[issue.line - 1]?.trim() ?? ''
+    const fixResult = applyFixToLines(lines, issue)
+
+    if (fixResult) {
+      const after = fixResult.newLines[issue.line - 1]?.trim() ?? ''
+      results.push({
+        file: filePath,
+        rule: issue.rule,
+        line: issue.line,
+        description: fixResult.description,
+        applied: true,
+        before,
+        after,
+      })
+      lines = fixResult.newLines
+    } else {
+      results.push({
+        file: filePath,
+        rule: issue.rule,
+        line: issue.line,
+        description: 'no fix available',
+        applied: false,
+      })
+    }
+  }
+
+  if (!dryRun) {
+    writeFileSync(filePath, lines.join('\n'), 'utf8')
+  }
+
+  return results
+}
+
 export async function applyFixes(
   targetPath: string,
   config?: DriftConfig,
-  options?: { rule?: string; dryRun?: boolean }
+  options?: { rule?: string; dryRun?: boolean; write?: boolean; preview?: boolean }
 ): Promise<FixResult[]> {
   const resolvedPath = resolve(targetPath)
-  const dryRun = options?.dryRun ?? false
+  const dryRun = options?.write
+    ? false
+    : options?.preview || options?.dryRun
+      ? true
+      : false
 
-  // Determine if target is a file or directory
   let fileReports
   const stat = statSync(resolvedPath)
 
@@ -96,58 +167,11 @@ export async function applyFixes(
     fileReports = analyzeProject(resolvedPath, config)
   }
 
-  // Collect fixable issues, optionally filtered by rule
-  const fixableByFile = new Map<string, DriftIssue[]>()
-
-  for (const report of fileReports) {
-    const fixableIssues = report.issues.filter(issue => {
-      if (!isFixable(issue)) return false
-      if (options?.rule && issue.rule !== options.rule) return false
-      return true
-    })
-
-    if (fixableIssues.length > 0) {
-      fixableByFile.set(report.path, fixableIssues)
-    }
-  }
-
+  const fixableByFile = collectFixableIssues(fileReports, options)
   const results: FixResult[] = []
 
   for (const [filePath, issues] of fixableByFile) {
-    const content = readFileSync(filePath, 'utf8')
-    let lines = content.split('\n')
-
-    // Sort issues by line descending to avoid line number drift after fixes
-    const sortedIssues = [...issues].sort((a, b) => b.line - a.line)
-
-    // Track line offset caused by deletions (debug-leftover removes lines)
-    // We process top-to-bottom after sorting descending, so no offset needed per issue
-    for (const issue of sortedIssues) {
-      const fixResult = applyFixToLines(lines, issue)
-
-      if (fixResult) {
-        results.push({
-          file: filePath,
-          rule: issue.rule,
-          line: issue.line,
-          description: fixResult.description,
-          applied: true,
-        })
-        lines = fixResult.newLines
-      } else {
-        results.push({
-          file: filePath,
-          rule: issue.rule,
-          line: issue.line,
-          description: 'no fix available',
-          applied: false,
-        })
-      }
-    }
-
-    if (!dryRun) {
-      writeFileSync(filePath, lines.join('\n'), 'utf8')
-    }
+    results.push(...processFile(filePath, issues, dryRun))
   }
 
   return results

package/src/git/trend.ts

@@ -1,5 +1,6 @@
-import type { SourceFile } from 'ts-morph'
-import type { FileReport, DriftConfig, TrendDataPoint, DriftTrendReport, BlameAttribution } from '../types.js'
+// drift-ignore-file
+
+import type { FileReport, DriftConfig, TrendDataPoint, DriftTrendReport } from '../types.js'
 import { assertGitRepo, analyzeHistoricalCommits } from './helpers.js'
 import { buildReport } from '../reporter.js'
 

package/src/git.ts

@@ -13,22 +13,23 @@ import { randomUUID } from 'node:crypto'
  *
  * 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
+function verifyGitRepo(projectPath: string): void {
   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: string, ref: string): void {
   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: string, ref: string): string[] {
   let fileList: string
   try {
     fileList = execSync(
@@ -39,36 +40,44 @@ export function extractFilesAtRef(projectPath: string, ref: string): string {
     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: string, ref: string, filePath: string, tempDir: string): void {
+  let content: string
+  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: string, ref: string): string {
+  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: 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')
+    extractFile(projectPath, ref, filePath, tempDir)
   }
 
   return tempDir

package/src/index.ts

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

package/src/map.ts

@@ -0,0 +1,117 @@
+import { writeFileSync } from 'node:fs'
+import { resolve, relative } from 'node:path'
+import { Project } from 'ts-morph'
+
+interface LayerNode {
+  name: string
+  files: Set<string>
+}
+
+function detectLayer(relPath: string): string {
+  const normalized = relPath.replace(/\\/g, '/').replace(/^\.\//, '')
+  const first = normalized.split('/')[0] || 'root'
+  return first
+}
+
+function esc(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+export function generateArchitectureSvg(targetPath: string): string {
+  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<string, LayerNode>()
+  const edges = new Map<string, number>()
+
+  for (const file of project.getSourceFiles()) {
+    const rel = relative(targetPath, file.getFilePath()).replace(/\\/g, '/')
+    const layerName = detectLayer(rel)
+    if (!layers.has(layerName)) layers.set(layerName, { name: layerName, files: new Set() })
+    layers.get(layerName)!.files.add(rel)
+
+    for (const decl of file.getImportDeclarations()) {
+      const imported = decl.getModuleSpecifierSourceFile()
+      if (!imported) continue
+      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)
+    }
+  }
+
+  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 = [...edges.entries()].map(([key, count]) => {
+    const [from, to] = key.split('->')
+    const a = boxByName.get(from)
+    const b = boxByName.get(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
+    return `
+      <line x1="${startX}" y1="${startY}" x2="${endX}" y2="${endY}" stroke="#64748b" stroke-width="2" marker-end="url(#arrow)" />
+      <text x="${(startX + endX) / 2}" y="${(startY + endY) / 2 - 4}" fill="#94a3b8" font-size="11" text-anchor="middle">${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('')
+
+  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>
+  ${lines}
+  ${nodes}
+</svg>`
+}
+
+export function generateArchitectureMap(targetPath: string, outputFile = 'architecture.svg'): string {
+  const resolvedTarget = resolve(targetPath)
+  const svg = generateArchitectureSvg(resolvedTarget)
+  const outPath = resolve(outputFile)
+  writeFileSync(outPath, svg, 'utf8')
+  return outPath
+}

package/src/metrics.ts

@@ -0,0 +1,200 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { join, relative } from 'node:path'
+import type { DriftIssue, DriftReport, FileReport, MaintenanceRiskMetrics, RepoQualityScore, RiskHotspot } from './types.js'
+
+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: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value))
+}
+
+function listFilesRecursively(root: string): string[] {
+  if (!existsSync(root)) return []
+  const out: string[] = []
+  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: string, filePath: string): boolean {
+  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: string, filePath: string): number {
+  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: number, issues: DriftIssue[], rules: Set<string>): number {
+  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: string, files: FileReport[]): RepoQualityScore {
+  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: DriftReport): MaintenanceRiskMetrics {
+  const allFiles = report.files
+  const hotspots: RiskHotspot[] = 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: string[] = []
+      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,
+    },
+  }
+}

package/src/plugins.ts

@@ -0,0 +1,76 @@
+import { existsSync } from 'node:fs'
+import { isAbsolute, resolve } from 'node:path'
+import { createRequire } from 'node:module'
+import type { DriftPlugin, PluginLoadError, LoadedPlugin } from './types.js'
+
+const require = createRequire(import.meta.url)
+
+function isPluginShape(value: unknown): value is DriftPlugin {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<DriftPlugin>
+  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: unknown): DriftPlugin | undefined {
+  if (isPluginShape(mod)) return mod
+  if (mod && typeof mod === 'object' && 'default' in mod) {
+    const maybeDefault = (mod as { default?: unknown }).default
+    if (isPluginShape(maybeDefault)) return maybeDefault
+  }
+  return undefined
+}
+
+function resolvePluginSpecifier(projectRoot: string, pluginId: string): string {
+  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: string, pluginIds: string[] | undefined): {
+  plugins: LoadedPlugin[]
+  errors: PluginLoadError[]
+} {
+  if (!pluginIds || pluginIds.length === 0) {
+    return { plugins: [], errors: [] }
+  }
+
+  const loaded: LoadedPlugin[] = []
+  const errors: PluginLoadError[] = []
+
+  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 }
+}