@eduardbar/drift 0.9.1 → 1.1.0

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

package/src/printer.ts

@@ -113,6 +113,26 @@ function formatFixSuggestion(issue: DriftIssue): string[] {
       'Pick one naming convention (camelCase for variables/functions, PascalCase for types)',
       'Rename snake_case identifiers to camelCase to match TypeScript conventions',
     ],
+    'controller-no-db': [
+      'Move DB access to a service/repository and inject it into the controller',
+      'Keep controllers focused on transport and orchestration only',
+    ],
+    'service-no-http': [
+      'Move HTTP concerns to adapters/clients and keep services framework-agnostic',
+      'Inject interfaces for outbound calls instead of calling fetch/express directly',
+    ],
+    'max-function-lines': [
+      'Split the function into smaller units with clear responsibilities',
+      'Extract branch-heavy chunks into dedicated helpers',
+    ],
+    'ai-code-smell': [
+      'Address the listed AI-smell signals in this file before adding more code',
+      'Prioritize consistency: naming, error handling, and abstraction level',
+    ],
+    'plugin-error': [
+      'Fix or remove the failing plugin in drift.config.*',
+      'Validate plugin contract: export { name, rules[] } and detector functions',
+    ],
   }
   return suggestions[issue.rule] ?? ['Review and fix manually']
 }