@eduardbar/drift 1.0.0 → 1.2.0

package/src/map.ts

@@ -0,0 +1,219 @@
+import { writeFileSync } from 'node:fs'
+import { resolve, relative } from 'node:path'
+import { Project } from 'ts-morph'
+import type { DriftConfig } from './types.js'
+import { detectLayerViolations } from './rules/phase3-arch.js'
+import { RULE_WEIGHTS } from './analyzer.js'
+
+interface LayerNode {
+  name: string
+  files: Set<string>
+}
+
+interface MapEdge {
+  key: string
+  from: string
+  to: string
+  count: number
+  kind: 'normal' | 'cycle' | 'violation'
+}
+
+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, config?: DriftConfig): 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>()
+  const layerAdjacency = new Map<string, Set<string>>()
+  const fileImportGraph = new Map<string, Set<string>>()
+
+  for (const file of project.getSourceFiles()) {
+    const filePath = file.getFilePath()
+    const rel = relative(targetPath, filePath).replace(/\\/g, '/')
+    const layerName = detectLayer(rel)
+    if (!layers.has(layerName)) layers.set(layerName, { name: layerName, files: new Set() })
+    layers.get(layerName)!.files.add(rel)
+    if (!fileImportGraph.has(filePath)) fileImportGraph.set(filePath, new Set())
+
+    for (const decl of file.getImportDeclarations()) {
+      const imported = decl.getModuleSpecifierSourceFile()
+      if (!imported) continue
+      fileImportGraph.get(filePath)!.add(imported.getFilePath())
+      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)
+      if (!layerAdjacency.has(layerName)) layerAdjacency.set(layerName, new Set())
+      layerAdjacency.get(layerName)!.add(importedLayer)
+    }
+  }
+
+  const cycleEdges = detectCycleEdges(layerAdjacency)
+  const violationEdges = new Set<string>()
+
+  if (config?.layers && config.layers.length > 0) {
+    const violations = detectLayerViolations(fileImportGraph, config.layers, targetPath, RULE_WEIGHTS)
+    for (const issues of violations.values()) {
+      for (const issue of issues) {
+        const match = issue.message.match(/Layer '([^']+)' must not import from layer '([^']+)'/)
+        if (!match) continue
+        const from = match[1]
+        const to = match[2]
+        violationEdges.add(`${from}->${to}`)
+        if (!layers.has(from)) layers.set(from, { name: from, files: new Set() })
+        if (!layers.has(to)) layers.set(to, { name: to, files: new Set() })
+      }
+    }
+  }
+
+  const edgeList: MapEdge[] = [...edges.entries()].map(([key, count]) => {
+    const [from, to] = key.split('->')
+    const kind = violationEdges.has(key)
+      ? 'violation'
+      : cycleEdges.has(key)
+        ? 'cycle'
+        : 'normal'
+    return { key, from, to, count, kind }
+  })
+
+  for (const key of violationEdges) {
+    if (edges.has(key)) continue
+    const [from, to] = key.split('->')
+    edgeList.push({ key, from, to, count: 1, kind: 'violation' })
+  }
+
+  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 = edgeList.map((edge) => {
+    const a = boxByName.get(edge.from)
+    const b = boxByName.get(edge.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
+    const stroke = edge.kind === 'violation'
+      ? '#ef4444'
+      : edge.kind === 'cycle'
+        ? '#f59e0b'
+        : '#64748b'
+    const widthPx = edge.kind === 'normal' ? 2 : 3
+    return `
+      <line x1="${startX}" y1="${startY}" x2="${endX}" y2="${endY}" stroke="${stroke}" stroke-width="${widthPx}" marker-end="url(#arrow)" data-edge="${esc(edge.key)}" data-kind="${edge.kind}" />
+      <text x="${(startX + endX) / 2}" y="${(startY + endY) / 2 - 4}" fill="#94a3b8" font-size="11" text-anchor="middle">${edge.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('')
+
+  const cycleCount = edgeList.filter((edge) => edge.kind === 'cycle').length
+  const violationCount = edgeList.filter((edge) => edge.kind === 'violation').length
+
+  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>
+  <text x="28" y="72" fill="#94a3b8" font-size="11" font-family="monospace">Cycle edges: ${cycleCount} | Layer violations: ${violationCount}</text>
+  <line x1="520" y1="66" x2="560" y2="66" stroke="#f59e0b" stroke-width="3" /><text x="567" y="69" fill="#94a3b8" font-size="11" font-family="monospace">cycle</text>
+  <line x1="630" y1="66" x2="670" y2="66" stroke="#ef4444" stroke-width="3" /><text x="677" y="69" fill="#94a3b8" font-size="11" font-family="monospace">violation</text>
+  ${lines}
+  ${nodes}
+</svg>`
+}
+
+function detectCycleEdges(adjacency: Map<string, Set<string>>): Set<string> {
+  const visited = new Set<string>()
+  const inStack = new Set<string>()
+  const stack: string[] = []
+  const cycleEdges = new Set<string>()
+
+  function dfs(node: string): void {
+    visited.add(node)
+    inStack.add(node)
+    stack.push(node)
+
+    for (const neighbor of adjacency.get(node) ?? []) {
+      if (!visited.has(neighbor)) {
+        dfs(neighbor)
+        continue
+      }
+
+      if (!inStack.has(neighbor)) continue
+
+      const startIndex = stack.indexOf(neighbor)
+      if (startIndex >= 0) {
+        for (let i = startIndex; i < stack.length - 1; i++) {
+          cycleEdges.add(`${stack[i]}->${stack[i + 1]}`)
+        }
+      }
+      cycleEdges.add(`${node}->${neighbor}`)
+    }
+
+    stack.pop()
+    inStack.delete(node)
+  }
+
+  for (const node of adjacency.keys()) {
+    if (!visited.has(node)) dfs(node)
+  }
+
+  return cycleEdges
+}
+
+export function generateArchitectureMap(targetPath: string, outputFile = 'architecture.svg', config?: DriftConfig): string {
+  const resolvedTarget = resolve(targetPath)
+  const svg = generateArchitectureSvg(resolvedTarget, config)
+  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']
 }

package/src/report.ts

@@ -644,6 +644,8 @@ export function generateHtmlReport(report: DriftReport): string {
   const projColor = scoreColor(report.totalScore)
   const projLabel = scoreLabel(report.totalScore)
   const projGrade = scoreGrade(report.totalScore)
+  const quality = report.quality
+  const risk = report.maintenanceRisk
 
   const filesWithIssues = report.files.filter(f => f.issues.length > 0).length
 
@@ -658,6 +660,17 @@ export function generateHtmlReport(report: DriftReport): string {
           <span class="rule-count">${count}</span>
         </button>`).join('')
 
+  const hotspotsHtml = risk.hotspots.length === 0
+    ? '<div class="empty-state" style="padding:0.8rem">No hotspots detected.</div>'
+    : risk.hotspots.slice(0, 5).map((hotspot) => `
+      <div class="issue-row" style="grid-template-columns: 62px 1fr;grid-template-rows:auto auto;">
+        <span class="issue-line">R${hotspot.risk}</span>
+        <div class="issue-rule-msg">
+          <span class="issue-rule">hotspot</span>
+          <span class="issue-msg">${escapeHtml(hotspot.file)} (${hotspot.reasons.join(', ')})</span>
+        </div>
+      </div>`).join('')
+
   // ── File sections ──────────────────────────────────────────────────────
   const fileSections = report.files
     .filter(f => f.issues.length > 0)
@@ -770,6 +783,21 @@ export function generateHtmlReport(report: DriftReport): string {
           </div>
         </div>
 
+        <div class="sidebar-block">
+          <div class="sidebar-label">Repo Quality</div>
+          <div style="font-size:1.1rem;font-weight:700;color:${scoreColor(100 - quality.overall)}">${quality.overall}/100</div>
+          <div style="font-size:0.72rem;color:var(--muted)">Architecture ${quality.dimensions.architecture} · Complexity ${quality.dimensions.complexity}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">AI patterns ${quality.dimensions['ai-patterns']} · Testing ${quality.dimensions.testing}</div>
+        </div>
+
+        <div class="sidebar-block">
+          <div class="sidebar-label">Maintenance Risk</div>
+          <div style="font-size:1.1rem;font-weight:700;color:${scoreColor(risk.score)}">${risk.score}/100 (${risk.level.toUpperCase()})</div>
+          <div style="font-size:0.72rem;color:var(--muted)">High complexity: ${risk.signals.highComplexityFiles}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">No tests: ${risk.signals.filesWithoutNearbyTests}</div>
+          <div style="font-size:0.72rem;color:var(--muted)">Frequent changes: ${risk.signals.frequentChangeFiles}</div>
+        </div>
+
         <!-- Severity filters -->
         <div class="sidebar-block">
           <div class="sidebar-label">Severity</div>
@@ -819,6 +847,13 @@ export function generateHtmlReport(report: DriftReport): string {
         <div class="main-header">
           <span id="issue-counter" style="color:var(--muted);font-size:0.75rem">Loading…</span>
         </div>
+        <section class="file-section" open>
+          <summary>
+            <span class="file-name">Risk hotspots</span>
+            <span class="file-score" style="color:${scoreColor(risk.score)}">${risk.score}/100</span>
+          </summary>
+          <div class="issues-list">${hotspotsHtml}</div>
+        </section>
         ${fileSections || noIssues}
       </main>