@eduardbar/drift 1.2.0 → 1.4.0

package/src/map.ts

@@ -4,6 +4,8 @@ import { Project } from 'ts-morph'
 import type { DriftConfig } from './types.js'
 import { detectLayerViolations } from './rules/phase3-arch.js'
 import { RULE_WEIGHTS } from './analyzer.js'
+import { detectCycleEdges } from './map-cycles.js'
+import { renderArchitectureSvg } from './map-svg.js'
 
 interface LayerNode {
   name: string
@@ -24,11 +26,68 @@ function detectLayer(relPath: string): string {
   return first
 }
 
-function esc(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+function appendFileLayerContext(
+  filePath: string,
+  targetPath: string,
+  layers: Map<string, LayerNode>,
+  fileImportGraph: Map<string, Set<string>>,
+): { rel: string; layerName: string } {
+  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())
+  }
+
+  return { rel, layerName }
 }
 
-export function generateArchitectureSvg(targetPath: string, config?: DriftConfig): string {
+function registerImportEdge(
+  layerName: string,
+  importedLayer: string,
+  edges: Map<string, number>,
+  layerAdjacency: Map<string, Set<string>>,
+): void {
+  if (importedLayer === layerName) return
+
+  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)
+}
+
+function buildEdgeList(edges: Map<string, number>, cycleEdges: Set<string>, violationEdges: Set<string>): MapEdge[] {
+  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' })
+  }
+
+  return edgeList
+}
+
+
+function createArchitectureProject(targetPath: string): Project {
   const project = new Project({
     skipAddingFilesFromTsConfig: true,
     compilerOptions: { allowJs: true, jsx: 1 },
@@ -45,6 +104,18 @@ export function generateArchitectureSvg(targetPath: string, config?: DriftConfig
     `!${targetPath}/**/*.d.ts`,
   ])
 
+  return project
+}
+
+function collectArchitectureGraph(
+  project: Project,
+  targetPath: string,
+): {
+  layers: Map<string, LayerNode>
+  edges: Map<string, number>
+  layerAdjacency: Map<string, Set<string>>
+  fileImportGraph: Map<string, Set<string>>
+} {
   const layers = new Map<string, LayerNode>()
   const edges = new Map<string, number>()
   const layerAdjacency = new Map<string, Set<string>>()
@@ -52,11 +123,7 @@ export function generateArchitectureSvg(targetPath: string, config?: DriftConfig
 
   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())
+    const { layerName } = appendFileLayerContext(filePath, targetPath, layers, fileImportGraph)
 
     for (const decl of file.getImportDeclarations()) {
       const imported = decl.getModuleSpecifierSourceFile()
@@ -64,150 +131,52 @@ export function generateArchitectureSvg(targetPath: string, config?: DriftConfig
       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)
+      registerImportEdge(layerName, importedLayer, edges, layerAdjacency)
     }
   }
 
-  const cycleEdges = detectCycleEdges(layerAdjacency)
-  const violationEdges = new Set<string>()
+  return { layers, edges, layerAdjacency, fileImportGraph }
+}
 
-  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() })
-      }
+function collectViolationEdges(
+  config: DriftConfig | undefined,
+  fileImportGraph: Map<string, Set<string>>,
+  targetPath: string,
+  layers: Map<string, LayerNode>,
+): Set<string> {
+  const violationEdges = new Set<string>()
+  if (!config?.layers?.length) return violationEdges
+
+  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>`
+  return violationEdges
 }
 
-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)
-  }
+export function generateArchitectureSvg(targetPath: string, config?: DriftConfig): string {
+  const project = createArchitectureProject(targetPath)
+  const { layers, edges, layerAdjacency, fileImportGraph } = collectArchitectureGraph(project, targetPath)
 
-  return cycleEdges
+  const cycleEdges = detectCycleEdges(layerAdjacency)
+  const violationEdges = collectViolationEdges(config, fileImportGraph, targetPath, layers)
+
+  const edgeList = buildEdgeList(edges, cycleEdges, violationEdges)
+  return renderArchitectureSvg({
+    layers,
+    edgeList,
+    cycleCount: edgeList.filter((edge) => edge.kind === 'cycle').length,
+    violationCount: edgeList.filter((edge) => edge.kind === 'violation').length,
+  })
 }
 
 export function generateArchitectureMap(targetPath: string, outputFile = 'architecture.svg', config?: DriftConfig): string {

package/src/metrics.ts

@@ -30,6 +30,20 @@ const AI_RULES = new Set([
   'ai-code-smell',
 ])
 
+const ISSUE_WEIGHT_PER_FILE = 20
+const DIMENSION_COUNT = 4
+const MAX_COMPLEXITY_RISK = 40
+const COMPLEXITY_RISK_PER_ISSUE = 10
+const MISSING_TESTS_RISK = 25
+const FREQUENT_CHANGE_THRESHOLD = 8
+const FREQUENT_CHANGE_RISK = 20
+const HIGH_DRIFT_THRESHOLD = 50
+const HIGH_DRIFT_RISK = 15
+const HOTSPOT_LIMIT = 10
+const LEVEL_CRITICAL_THRESHOLD = 75
+const LEVEL_HIGH_THRESHOLD = 55
+const LEVEL_MEDIUM_THRESHOLD = 30
+
 function clamp(value: number, min: number, max: number): number {
   return Math.max(min, Math.min(max, value))
 }
@@ -38,20 +52,23 @@ function listFilesRecursively(root: string): string[] {
   if (!existsSync(root)) return []
   const out: string[] = []
   const stack = [root]
+
+  const shouldSkipDirectory = (name: string): boolean =>
+    name === 'node_modules' || name === 'dist' || name === '.git' || name === '.next' || name === 'build'
+
   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 {
+      if (!stat.isDirectory()) {
         out.push(full)
+        continue
       }
+
+      if (shouldSkipDirectory(entry)) continue
+      stack.push(full)
     }
   }
   return out
@@ -88,7 +105,55 @@ function getCommitTouchCount(targetPath: string, filePath: string): number {
 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)
+  return clamp(100 - Math.round((count / totalFiles) * ISSUE_WEIGHT_PER_FILE), 0, 100)
+}
+
+function riskLevelFromScore(score: number): MaintenanceRiskMetrics['level'] {
+  if (score >= LEVEL_CRITICAL_THRESHOLD) return 'critical'
+  if (score >= LEVEL_HIGH_THRESHOLD) return 'high'
+  if (score >= LEVEL_MEDIUM_THRESHOLD) return 'medium'
+  return 'low'
+}
+
+function evaluateHotspot(targetPath: string, file: FileReport): RiskHotspot {
+  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(targetPath, file.path)
+  const hasTests = hasNearbyTest(targetPath, file.path)
+  const reasons: string[] = []
+  let risk = 0
+
+  if (complexityIssues > 0) {
+    risk += Math.min(MAX_COMPLEXITY_RISK, complexityIssues * COMPLEXITY_RISK_PER_ISSUE)
+    reasons.push('high complexity signals')
+  }
+  if (!hasTests) {
+    risk += MISSING_TESTS_RISK
+    reasons.push('no nearby tests')
+  }
+  if (changeFrequency >= FREQUENT_CHANGE_THRESHOLD) {
+    risk += FREQUENT_CHANGE_RISK
+    reasons.push('frequently changed file')
+  }
+  if (file.score >= HIGH_DRIFT_THRESHOLD) {
+    risk += HIGH_DRIFT_RISK
+    reasons.push('high drift score')
+  }
+
+  return {
+    file: file.path,
+    driftScore: file.score,
+    complexityIssues,
+    hasNearbyTests: hasTests,
+    changeFrequency,
+    risk: clamp(risk, 0, 100),
+    reasons,
+  }
 }
 
 export function computeRepoQuality(targetPath: string, files: FileReport[]): RepoQualityScore {
@@ -119,73 +184,27 @@ export function computeRepoQuality(targetPath: string, files: FileReport[]): Rep
     dimensions.complexity +
     dimensions['ai-patterns'] +
     dimensions.testing
-  ) / 4)
+  ) / DIMENSION_COUNT)
 
   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,
-      }
-    })
+  const hotspots: RiskHotspot[] = report.files
+    .map((file) => evaluateHotspot(report.targetPath, file))
     .filter((hotspot) => hotspot.risk > 0)
     .sort((a, b) => b.risk - a.risk)
-    .slice(0, 10)
+    .slice(0, HOTSPOT_LIMIT)
 
   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 frequentChangeFiles = hotspots.filter((hotspot) => hotspot.changeFrequency >= FREQUENT_CHANGE_THRESHOLD).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'
+  const level = riskLevelFromScore(score)
 
   return {
     score,

package/src/output-metadata.ts

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json') as { version: string }
+
+const TOOL_VERSION = version
+
+export const OUTPUT_SCHEMA = {
+  report: 'schemas/drift-report.v1.json',
+  trust: 'schemas/drift-trust.v1.json',
+  ai: 'schemas/drift-ai-output.v1.json',
+} as const
+
+type OutputMetadata = {
+  $schema: string
+  toolVersion: string
+}
+
+type JsonOutputWithMetadata<T extends object> = T & OutputMetadata
+
+export function withOutputMetadata<T extends object>(
+  payload: T,
+  schema: string,
+): JsonOutputWithMetadata<T> {
+  return {
+    ...payload,
+    $schema: schema,
+    toolVersion: TOOL_VERSION,
+  }
+}

package/src/plugins-capabilities.ts

@@ -0,0 +1,36 @@
+import type { DriftPlugin } from './types.js'
+import type { PluginValidationContext } from './plugins-rules.js'
+import { pushError } from './plugins-messages.js'
+
+export function validateCapabilities(
+  capabilitiesCandidate: unknown,
+  context: PluginValidationContext,
+): DriftPlugin['capabilities'] | undefined {
+  const { pluginId, pluginName, errors } = context
+  if (capabilitiesCandidate === undefined) return undefined
+  if (!capabilitiesCandidate || typeof capabilitiesCandidate !== 'object' || Array.isArray(capabilitiesCandidate)) {
+    pushError(
+      errors,
+      pluginId,
+      `Plugin '${pluginName}' has invalid capabilities metadata. Expected an object map like { "fixes": true } when provided.`,
+      { pluginName, code: 'plugin-capabilities-invalid' },
+    )
+    return undefined
+  }
+
+  const entries = Object.entries(capabilitiesCandidate as Record<string, unknown>)
+  for (const [capabilityKey, capabilityValue] of entries) {
+    const capabilityType = typeof capabilityValue
+    if (capabilityType !== 'string' && capabilityType !== 'number' && capabilityType !== 'boolean') {
+      pushError(
+        errors,
+        pluginId,
+        `Plugin '${pluginName}' capability '${capabilityKey}' has invalid value type '${capabilityType}'. Allowed: string | number | boolean.`,
+        { pluginName, code: 'plugin-capabilities-value-invalid' },
+      )
+    }
+  }
+
+  if (errors.length > 0) return undefined
+  return capabilitiesCandidate as DriftPlugin['capabilities']
+}

package/src/plugins-messages.ts

@@ -0,0 +1,35 @@
+import type { PluginLoadError, PluginLoadWarning } from './types.js'
+
+type PluginMessageOptions = { pluginName?: string; ruleId?: string; code?: string }
+
+function pushLoadMessage(
+  pluginId: string,
+  message: string,
+  options?: PluginMessageOptions,
+): PluginLoadError | PluginLoadWarning {
+  return {
+    pluginId,
+    pluginName: options?.pluginName,
+    ruleId: options?.ruleId,
+    code: options?.code,
+    message,
+  }
+}
+
+export function pushError(
+  errors: PluginLoadError[],
+  pluginId: string,
+  message: string,
+  options?: PluginMessageOptions,
+): void {
+  errors.push(pushLoadMessage(pluginId, message, options))
+}
+
+export function pushWarning(
+  warnings: PluginLoadWarning[],
+  pluginId: string,
+  message: string,
+  options?: PluginMessageOptions,
+): void {
+  warnings.push(pushLoadMessage(pluginId, message, options))
+}