@eduardbar/drift 0.2.3 → 0.4.0

package/src/analyzer.ts

@@ -1,3 +1,5 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
 import {
   Project,
   SourceFile,
@@ -8,7 +10,7 @@ import {
   FunctionExpression,
   MethodDeclaration,
 } from 'ts-morph'
-import type { DriftIssue, FileReport } from './types.js'
+import type { DriftIssue, FileReport, DriftConfig, LayerDefinition, ModuleBoundary } from './types.js'
 
 // Rules and their drift score weight
 const RULE_WEIGHTS: Record<string, { severity: DriftIssue['severity']; weight: number }> = {
@@ -22,6 +24,21 @@ const RULE_WEIGHTS: Record<string, { severity: DriftIssue['severity']; weight: n
   'catch-swallow':            { severity: 'warning', weight: 10 },
   'magic-number':             { severity: 'info',    weight: 3  },
   'any-abuse':                { severity: 'warning', weight: 8  },
+  // Phase 1: complexity detection
+  'high-complexity':          { severity: 'error',   weight: 15 },
+  'deep-nesting':             { severity: 'warning', weight: 12 },
+  'too-many-params':          { severity: 'warning', weight: 8  },
+  'high-coupling':            { severity: 'warning', weight: 10 },
+  'promise-style-mix':        { severity: 'warning', weight: 7  },
+  // Phase 2: cross-file dead code
+  'unused-export':            { severity: 'warning', weight: 8  },
+  'dead-file':                { severity: 'warning', weight: 10 },
+  'unused-dependency':        { severity: 'warning', weight: 6  },
+  // Phase 3: architectural boundaries
+  'circular-dependency':      { severity: 'error',   weight: 14 },
+  // Phase 3b/c: layer and module boundary enforcement (require drift.config.ts)
+  'layer-violation':          { severity: 'error',   weight: 16 },
+  'cross-boundary-import':    { severity: 'warning', weight: 10 },
 }
 
 type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
@@ -55,6 +72,10 @@ function getFunctionLikeLines(node: FunctionLike): number {
   return node.getEndLineNumber() - node.getStartLineNumber()
 }
 
+// ---------------------------------------------------------------------------
+// Existing rules
+// ---------------------------------------------------------------------------
+
 function detectLargeFile(file: SourceFile): DriftIssue[] {
   const lineCount = file.getEndLineNumber()
   if (lineCount > 300) {
@@ -239,6 +260,312 @@ function detectMissingReturnTypes(file: SourceFile): DriftIssue[] {
   return issues
 }
 
+// ---------------------------------------------------------------------------
+// Phase 1: complexity detection rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Cyclomatic complexity: count decision points in a function.
+ * Each if/else if/ternary/?:/for/while/do/case/catch/&&/|| adds 1.
+ * Threshold: > 10 is considered high complexity.
+ */
+function getCyclomaticComplexity(fn: FunctionLike): number {
+  let complexity = 1 // base path
+
+  const incrementKinds = [
+    SyntaxKind.IfStatement,
+    SyntaxKind.ForStatement,
+    SyntaxKind.ForInStatement,
+    SyntaxKind.ForOfStatement,
+    SyntaxKind.WhileStatement,
+    SyntaxKind.DoStatement,
+    SyntaxKind.CaseClause,
+    SyntaxKind.CatchClause,
+    SyntaxKind.ConditionalExpression,  // ternary
+    SyntaxKind.AmpersandAmpersandToken,
+    SyntaxKind.BarBarToken,
+    SyntaxKind.QuestionQuestionToken,  // ??
+  ]
+
+  for (const kind of incrementKinds) {
+    complexity += fn.getDescendantsOfKind(kind).length
+  }
+
+  return complexity
+}
+
+function detectHighComplexity(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const fns: FunctionLike[] = [
+    ...file.getFunctions(),
+    ...file.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+    ...file.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ...file.getClasses().flatMap((c) => c.getMethods()),
+  ]
+
+  for (const fn of fns) {
+    const complexity = getCyclomaticComplexity(fn)
+    if (complexity > 10) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'high-complexity',
+        severity: 'error',
+        message: `Cyclomatic complexity is ${complexity} (threshold: 10). AI generates correct code, not simple code.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+/**
+ * Deep nesting: count the maximum nesting depth of control flow inside a function.
+ * Counts: if, for, while, do, try, switch.
+ * Threshold: > 3 levels.
+ */
+function getMaxNestingDepth(fn: FunctionLike): number {
+  const nestingKinds = new Set([
+    SyntaxKind.IfStatement,
+    SyntaxKind.ForStatement,
+    SyntaxKind.ForInStatement,
+    SyntaxKind.ForOfStatement,
+    SyntaxKind.WhileStatement,
+    SyntaxKind.DoStatement,
+    SyntaxKind.TryStatement,
+    SyntaxKind.SwitchStatement,
+  ])
+
+  let maxDepth = 0
+
+  function walk(node: Node, depth: number): void {
+    if (nestingKinds.has(node.getKind())) {
+      depth++
+      if (depth > maxDepth) maxDepth = depth
+    }
+    for (const child of node.getChildren()) {
+      walk(child, depth)
+    }
+  }
+
+  walk(fn, 0)
+  return maxDepth
+}
+
+function detectDeepNesting(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const fns: FunctionLike[] = [
+    ...file.getFunctions(),
+    ...file.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+    ...file.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ...file.getClasses().flatMap((c) => c.getMethods()),
+  ]
+
+  for (const fn of fns) {
+    const depth = getMaxNestingDepth(fn)
+    if (depth > 3) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'deep-nesting',
+        severity: 'warning',
+        message: `Maximum nesting depth is ${depth} (threshold: 3). Deep nesting is the #1 readability killer.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+/**
+ * Too many parameters: functions with more than 4 parameters.
+ * AI avoids refactoring parameters into objects/options bags.
+ */
+function detectTooManyParams(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const fns: FunctionLike[] = [
+    ...file.getFunctions(),
+    ...file.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+    ...file.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ...file.getClasses().flatMap((c) => c.getMethods()),
+  ]
+
+  for (const fn of fns) {
+    const paramCount = fn.getParameters().length
+    if (paramCount > 4) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'too-many-params',
+        severity: 'warning',
+        message: `Function has ${paramCount} parameters (threshold: 4). AI avoids refactoring into options objects.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+/**
+ * High coupling: files with more than 10 distinct import sources.
+ * AI imports broadly without considering module cohesion.
+ */
+function detectHighCoupling(file: SourceFile): DriftIssue[] {
+  const imports = file.getImportDeclarations()
+  const sources = new Set(imports.map((i) => i.getModuleSpecifierValue()))
+
+  if (sources.size > 10) {
+    return [
+      {
+        rule: 'high-coupling',
+        severity: 'warning',
+        message: `File imports from ${sources.size} distinct modules (threshold: 10). High coupling makes refactoring dangerous.`,
+        line: 1,
+        column: 1,
+        snippet: `// ${sources.size} import sources`,
+      },
+    ]
+  }
+  return []
+}
+
+/**
+ * Promise style mix: async/await and .then()/.catch() used in the same file.
+ * AI generates both styles without consistency.
+ */
+function detectPromiseStyleMix(file: SourceFile): DriftIssue[] {
+  const text = file.getFullText()
+
+  // detect .then( or .catch( calls (property access on a promise)
+  const hasThen = file.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression).some((node) => {
+    const name = node.getName()
+    return name === 'then' || name === 'catch'
+  })
+
+  // detect async keyword usage
+  const hasAsync =
+    file.getDescendantsOfKind(SyntaxKind.AsyncKeyword).length > 0 ||
+    /\bawait\b/.test(text)
+
+  if (hasThen && hasAsync) {
+    return [
+      {
+        rule: 'promise-style-mix',
+        severity: 'warning',
+        message: `File mixes async/await with .then()/.catch(). AI generates both styles without picking one.`,
+        line: 1,
+        column: 1,
+        snippet: `// mixed promise styles detected`,
+      },
+    ]
+  }
+  return []
+}
+
+/**
+ * Magic numbers: numeric literals used directly in logic outside of named constants.
+ * Excludes 0, 1, -1 (universally understood) and array indices in obvious patterns.
+ */
+function detectMagicNumbers(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const ALLOWED = new Set([0, 1, -1, 2, 100])
+
+  for (const node of file.getDescendantsOfKind(SyntaxKind.NumericLiteral)) {
+    const value = Number(node.getLiteralValue())
+    if (ALLOWED.has(value)) continue
+
+    // Skip: variable/const initializers at top level (those ARE the named constants)
+    const parent = node.getParent()
+    if (!parent) continue
+    const parentKind = parent.getKind()
+    if (
+      parentKind === SyntaxKind.VariableDeclaration ||
+      parentKind === SyntaxKind.PropertyAssignment ||
+      parentKind === SyntaxKind.EnumMember ||
+      parentKind === SyntaxKind.Parameter
+    ) continue
+
+    const line = node.getStartLineNumber()
+    if (hasIgnoreComment(file, line)) continue
+
+    issues.push({
+      rule: 'magic-number',
+      severity: 'info',
+      message: `Magic number ${value} used directly in logic. Extract to a named constant.`,
+      line,
+      column: node.getStartLinePos(),
+      snippet: getSnippet(node, file),
+    })
+  }
+  return issues
+}
+
+/**
+ * Comment contradiction: comments that restate exactly what the code does.
+ * Classic AI pattern — documents the obvious instead of the why.
+ * Detects: "// increment counter" above counter++, "// return x" above return x, etc.
+ */
+function detectCommentContradiction(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const lines = file.getFullText().split('\n')
+
+  // Patterns: comment that is a near-literal restatement of the next line
+  const trivialCommentPatterns = [
+    // "// return ..." above a return statement
+    { comment: /\/\/\s*return\b/i,         code: /^\s*return\b/ },
+    // "// increment ..." or "// increase ..." above x++ or x += 1
+    { comment: /\/\/\s*(increment|increase|add\s+1|plus\s+1)\b/i, code: /\+\+|(\+= ?1)\b/ },
+    // "// decrement ..." above x-- or x -= 1
+    { comment: /\/\/\s*(decrement|decrease|subtract\s+1|minus\s+1)\b/i, code: /--|(-= ?1)\b/ },
+    // "// log ..." above console.log
+    { comment: /\/\/\s*log\b/i,            code: /console\.(log|warn|error)/ },
+    // "// set ... to ..." or "// assign ..." above assignment
+    { comment: /\/\/\s*(set|assign)\b/i,   code: /^\s*\w[\w.[\]]*\s*=(?!=)/ },
+    // "// call ..." above a function call
+    { comment: /\/\/\s*call\b/i,           code: /^\s*\w[\w.]*\(/ },
+    // "// declare ..." or "// define ..." or "// create ..." above const/let/var
+    { comment: /\/\/\s*(declare|define|create|initialize)\b/i, code: /^\s*(const|let|var)\b/ },
+    // "// check if ..." above an if statement
+    { comment: /\/\/\s*check\s+if\b/i,     code: /^\s*if\s*\(/ },
+    // "// loop ..." or "// iterate ..." above for/while
+    { comment: /\/\/\s*(loop|iterate|for each|foreach)\b/i, code: /^\s*(for|while)\b/ },
+    // "// import ..." above an import
+    { comment: /\/\/\s*import\b/i,         code: /^\s*import\b/ },
+  ]
+
+  for (let i = 0; i < lines.length - 1; i++) {
+    const commentLine = lines[i].trim()
+    const nextLine = lines[i + 1]
+
+    for (const { comment, code } of trivialCommentPatterns) {
+      if (comment.test(commentLine) && code.test(nextLine)) {
+        if (hasIgnoreComment(file, i + 1)) continue
+        issues.push({
+          rule: 'comment-contradiction',
+          severity: 'warning',
+          message: `Comment restates what the code already says. AI documents the obvious instead of the why.`,
+          line: i + 1,
+          column: 1,
+          snippet: `${commentLine.slice(0, 60)}\n${nextLine.trim().slice(0, 60)}`,
+        })
+        break // one issue per comment line max
+      }
+    }
+  }
+
+  return issues
+}
+
+// ---------------------------------------------------------------------------
+// Score
+// ---------------------------------------------------------------------------
+
 function calculateScore(issues: DriftIssue[]): number {
   let raw = 0
   for (const issue of issues) {
@@ -247,6 +574,10 @@ function calculateScore(issues: DriftIssue[]): number {
   return Math.min(100, raw)
 }
 
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
 export function analyzeFile(file: SourceFile): FileReport {
   if (isFileIgnored(file)) {
     return {
@@ -265,6 +596,15 @@ export function analyzeFile(file: SourceFile): FileReport {
     ...detectAnyAbuse(file),
     ...detectCatchSwallow(file),
     ...detectMissingReturnTypes(file),
+    // Phase 1: complexity
+    ...detectHighComplexity(file),
+    ...detectDeepNesting(file),
+    ...detectTooManyParams(file),
+    ...detectHighCoupling(file),
+    ...detectPromiseStyleMix(file),
+    // Stubs now implemented
+    ...detectMagicNumbers(file),
+    ...detectCommentContradiction(file),
   ]
 
   return {
@@ -274,7 +614,7 @@ export function analyzeFile(file: SourceFile): FileReport {
   }
 }
 
-export function analyzeProject(targetPath: string): FileReport[] {
+export function analyzeProject(targetPath: string, config?: DriftConfig): FileReport[] {
   const project = new Project({
     skipAddingFilesFromTsConfig: true,
     compilerOptions: { allowJs: true },
@@ -294,5 +634,350 @@ export function analyzeProject(targetPath: string): FileReport[] {
     `!${targetPath}/**/*.spec.*`,
   ])
 
-  return project.getSourceFiles().map(analyzeFile)
+  const sourceFiles = project.getSourceFiles()
+
+  // Phase 1: per-file analysis
+  const reports: FileReport[] = sourceFiles.map(analyzeFile)
+  const reportByPath = new Map<string, FileReport>()
+  for (const r of reports) reportByPath.set(r.path, r)
+
+  // Phase 2: cross-file analysis — build import graph first
+  const allImportedPaths = new Set<string>()   // absolute paths of files that are imported
+  const allImportedNames = new Map<string, Set<string>>() // file path → set of imported names
+  const allLiteralImports = new Set<string>()  // raw module specifiers (for unused-dependency)
+  const importGraph = new Map<string, Set<string>>() // Phase 3: filePath → Set of imported filePaths
+
+  for (const sf of sourceFiles) {
+    const sfPath = sf.getFilePath()
+    for (const decl of sf.getImportDeclarations()) {
+      const moduleSpecifier = decl.getModuleSpecifierValue()
+      allLiteralImports.add(moduleSpecifier)
+
+      // Resolve to absolute path for dead-file / unused-export
+      const resolved = decl.getModuleSpecifierSourceFile()
+      if (resolved) {
+        const resolvedPath = resolved.getFilePath()
+        allImportedPaths.add(resolvedPath)
+
+        // Phase 3: populate directed import graph
+        if (!importGraph.has(sfPath)) importGraph.set(sfPath, new Set())
+        importGraph.get(sfPath)!.add(resolvedPath)
+
+        // Collect named imports { A, B } and default imports
+        const named = decl.getNamedImports().map(n => n.getName())
+        const def = decl.getDefaultImport()?.getText()
+        const ns = decl.getNamespaceImport()?.getText()
+
+        if (!allImportedNames.has(resolvedPath)) {
+          allImportedNames.set(resolvedPath, new Set())
+        }
+        const nameSet = allImportedNames.get(resolvedPath)!
+        for (const n of named) nameSet.add(n)
+        if (def) nameSet.add('default')
+        if (ns) nameSet.add('*') // namespace import — counts all exports as used
+      }
+    }
+
+    // Also register re-exports: export { X, Y } from './module'
+    // These count as "using" X and Y from the source module
+    for (const exportDecl of sf.getExportDeclarations()) {
+      const reExportedModule = exportDecl.getModuleSpecifierSourceFile()
+      if (!reExportedModule) continue
+
+      const reExportedPath = reExportedModule.getFilePath()
+      allImportedPaths.add(reExportedPath)
+
+      if (!allImportedNames.has(reExportedPath)) {
+        allImportedNames.set(reExportedPath, new Set())
+      }
+      const nameSet = allImportedNames.get(reExportedPath)!
+
+      const namedExports = exportDecl.getNamedExports()
+      if (namedExports.length === 0) {
+        // export * from './module' — namespace re-export, all names used
+        nameSet.add('*')
+      } else {
+        for (const ne of namedExports) nameSet.add(ne.getName())
+      }
+    }
+  }
+
+  // Detect unused-export and dead-file per source file
+  for (const sf of sourceFiles) {
+    const sfPath = sf.getFilePath()
+    const report = reportByPath.get(sfPath)
+    if (!report) continue
+
+    // dead-file: file is never imported by anyone
+    // Exclude entry-point candidates: index.ts, main.ts, cli.ts, app.ts, bin files
+    const basename = path.basename(sfPath)
+    const isBinFile = sfPath.replace(/\\/g, '/').includes('/bin/')
+    const isEntryPoint = /^(index|main|cli|app)\.(ts|tsx|js|jsx)$/.test(basename) || isBinFile
+    if (!isEntryPoint && !allImportedPaths.has(sfPath)) {
+      const issue: DriftIssue = {
+        rule: 'dead-file',
+        severity: RULE_WEIGHTS['dead-file'].severity,
+        message: 'File is never imported — may be dead code',
+        line: 1,
+        column: 1,
+        snippet: basename,
+      }
+      report.issues.push(issue)
+      report.score = calculateScore(report.issues)
+    }
+
+    // unused-export: named exports not imported anywhere
+    // Skip barrel files (index.ts) — their entire surface is the public API
+    const isBarrel = /^index\.(ts|tsx|js|jsx)$/.test(basename)
+    const importedNamesForFile = allImportedNames.get(sfPath)
+    const hasNamespaceImport = importedNamesForFile?.has('*') ?? false
+    if (!isBarrel && !hasNamespaceImport) {
+      for (const exportDecl of sf.getExportDeclarations()) {
+        for (const namedExport of exportDecl.getNamedExports()) {
+          const name = namedExport.getName()
+          if (!importedNamesForFile?.has(name)) {
+            const line = namedExport.getStartLineNumber()
+            const issue: DriftIssue = {
+              rule: 'unused-export',
+              severity: RULE_WEIGHTS['unused-export'].severity,
+              message: `'${name}' is exported but never imported`,
+              line,
+              column: 1,
+              snippet: namedExport.getText().slice(0, 80),
+            }
+            report.issues.push(issue)
+            report.score = calculateScore(report.issues)
+          }
+        }
+      }
+
+      // Also check inline export declarations (export function foo, export const bar)
+      for (const exportSymbol of sf.getExportedDeclarations()) {
+        const [exportName, declarations] = [exportSymbol[0], exportSymbol[1]]
+        if (exportName === 'default') continue
+        if (importedNamesForFile?.has(exportName)) continue
+
+        for (const decl of declarations) {
+          // Skip if this is a re-export from another file
+          if (decl.getSourceFile().getFilePath() !== sfPath) continue
+
+          const line = decl.getStartLineNumber()
+          const issue: DriftIssue = {
+            rule: 'unused-export',
+            severity: RULE_WEIGHTS['unused-export'].severity,
+            message: `'${exportName}' is exported but never imported`,
+            line,
+            column: 1,
+            snippet: decl.getText().split('\n')[0].slice(0, 80),
+          }
+          report.issues.push(issue)
+          report.score = calculateScore(report.issues)
+          break // one issue per export name is enough
+        }
+      }
+    }
+  }
+
+  // Detect unused-dependency: packages in package.json never imported
+  const pkgPath = path.join(targetPath, 'package.json')
+  if (fs.existsSync(pkgPath)) {
+    let pkg: Record<string, unknown>
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    } catch {
+      pkg = {}
+    }
+
+    const deps = {
+      ...((pkg.dependencies as Record<string, string>) ?? {}),
+    }
+
+    const unusedDeps: string[] = []
+    for (const depName of Object.keys(deps)) {
+      // Skip type-only packages (@types/*)
+      if (depName.startsWith('@types/')) continue
+
+      // A dependency is "used" if any import specifier starts with the package name
+      // (handles sub-paths like 'lodash/merge', 'date-fns/format', etc.)
+      const isUsed = [...allLiteralImports].some(
+        imp => imp === depName || imp.startsWith(depName + '/')
+      )
+      if (!isUsed) unusedDeps.push(depName)
+    }
+
+    if (unusedDeps.length > 0) {
+      const pkgIssues: DriftIssue[] = unusedDeps.map(dep => ({
+        rule: 'unused-dependency',
+        severity: RULE_WEIGHTS['unused-dependency'].severity,
+        message: `'${dep}' is in package.json but never imported`,
+        line: 1,
+        column: 1,
+        snippet: `"${dep}"`,
+      }))
+
+      reports.push({
+        path: pkgPath,
+        issues: pkgIssues,
+        score: calculateScore(pkgIssues),
+      })
+    }
+  }
+
+  // Phase 3: circular-dependency — DFS cycle detection
+  function findCycles(graph: Map<string, Set<string>>): Array<string[]> {
+    const visited = new Set<string>()
+    const inStack = new Set<string>()
+    const cycles: Array<string[]> = []
+
+    function dfs(node: string, stack: string[]): void {
+      visited.add(node)
+      inStack.add(node)
+      stack.push(node)
+
+      for (const neighbor of graph.get(node) ?? []) {
+        if (!visited.has(neighbor)) {
+          dfs(neighbor, stack)
+        } else if (inStack.has(neighbor)) {
+          // Found a cycle — extract the cycle portion from the stack
+          const cycleStart = stack.indexOf(neighbor)
+          cycles.push(stack.slice(cycleStart))
+        }
+      }
+
+      stack.pop()
+      inStack.delete(node)
+    }
+
+    for (const node of graph.keys()) {
+      if (!visited.has(node)) {
+        dfs(node, [])
+      }
+    }
+
+    return cycles
+  }
+
+  const cycles = findCycles(importGraph)
+
+  // De-duplicate: each unique cycle (regardless of starting node) reported once per file
+  const reportedCycleKeys = new Set<string>()
+
+  for (const cycle of cycles) {
+    const cycleKey = [...cycle].sort().join('|')
+    if (reportedCycleKeys.has(cycleKey)) continue
+    reportedCycleKeys.add(cycleKey)
+
+    // Report on the first file in the cycle
+    const firstFile = cycle[0]
+    const report = reportByPath.get(firstFile)
+    if (!report) continue
+
+    const cycleDisplay = cycle
+      .map(p => path.basename(p))
+      .concat(path.basename(cycle[0])) // close the loop visually: A → B → C → A
+      .join(' → ')
+
+    const issue: DriftIssue = {
+      rule: 'circular-dependency',
+      severity: RULE_WEIGHTS['circular-dependency'].severity,
+      message: `Circular dependency detected: ${cycleDisplay}`,
+      line: 1,
+      column: 1,
+      snippet: cycleDisplay,
+    }
+    report.issues.push(issue)
+    report.score = calculateScore(report.issues)
+  }
+
+  // ── Phase 3b: layer-violation ──────────────────────────────────────────
+  if (config?.layers && config.layers.length > 0) {
+    const { layers } = config
+
+    function getLayer(filePath: string): LayerDefinition | undefined {
+      const rel = filePath.replace(/\\/g, '/')
+      return layers.find(layer =>
+        layer.patterns.some(pattern => {
+          const regexStr = pattern
+            .replace(/\\/g, '/')
+            .replace(/[.+^${}()|[\]]/g, '\\$&')
+            .replace(/\*\*/g, '###DOUBLESTAR###')
+            .replace(/\*/g, '[^/]*')
+            .replace(/###DOUBLESTAR###/g, '.*')
+          return new RegExp(`^${regexStr}`).test(rel)
+        })
+      )
+    }
+
+    for (const [filePath, imports] of importGraph.entries()) {
+      const fileLayer = getLayer(filePath)
+      if (!fileLayer) continue
+
+      for (const importedPath of imports) {
+        const importedLayer = getLayer(importedPath)
+        if (!importedLayer) continue
+        if (importedLayer.name === fileLayer.name) continue
+
+        if (!fileLayer.canImportFrom.includes(importedLayer.name)) {
+          const report = reportByPath.get(filePath)
+          if (report) {
+            const weight = RULE_WEIGHTS['layer-violation']?.weight ?? 5
+            report.issues.push({
+              rule: 'layer-violation',
+              severity: 'error',
+              message: `Layer '${fileLayer.name}' must not import from layer '${importedLayer.name}'`,
+              line: 1,
+              column: 1,
+              snippet: `import from '${path.relative(targetPath, importedPath).replace(/\\/g, '/')}'`,
+            })
+            report.score = Math.min(100, report.score + weight)
+          }
+        }
+      }
+    }
+  }
+
+  // ── Phase 3c: cross-boundary-import ────────────────────────────────────
+  if (config?.modules && config.modules.length > 0) {
+    const { modules } = config
+
+    function getModule(filePath: string): ModuleBoundary | undefined {
+      const rel = filePath.replace(/\\/g, '/')
+      return modules.find(m => rel.startsWith(m.root.replace(/\\/g, '/')))
+    }
+
+    for (const [filePath, imports] of importGraph.entries()) {
+      const fileModule = getModule(filePath)
+      if (!fileModule) continue
+
+      for (const importedPath of imports) {
+        const importedModule = getModule(importedPath)
+        if (!importedModule) continue
+        if (importedModule.name === fileModule.name) continue
+
+        const allowedImports = fileModule.allowedExternalImports ?? []
+        const relImported = importedPath.replace(/\\/g, '/')
+        const isAllowed = allowedImports.some(allowed =>
+          relImported.startsWith(allowed.replace(/\\/g, '/'))
+        )
+
+        if (!isAllowed) {
+          const report = reportByPath.get(filePath)
+          if (report) {
+            const weight = RULE_WEIGHTS['cross-boundary-import']?.weight ?? 5
+            report.issues.push({
+              rule: 'cross-boundary-import',
+              severity: 'warning',
+              message: `Module '${fileModule.name}' must not import from module '${importedModule.name}'`,
+              line: 1,
+              column: 1,
+              snippet: `import from '${path.relative(targetPath, importedPath).replace(/\\/g, '/')}'`,
+            })
+            report.score = Math.min(100, report.score + weight)
+          }
+        }
+      }
+    }
+  }
+
+  return reports
 }