@eduardbar/drift 0.9.0 → 1.0.0

package/src/rules/phase0-basic.ts

@@ -0,0 +1,187 @@
+import { SourceFile, SyntaxKind } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment, getSnippet, getFunctionLikeLines, type FunctionLike } from './shared.js'
+
+export function detectLargeFile(file: SourceFile): DriftIssue[] {
+  const lineCount = file.getEndLineNumber()
+  if (lineCount > 300) {
+    return [
+      {
+        rule: 'large-file',
+        severity: 'error',
+        message: `File has ${lineCount} lines (threshold: 300). Large files are the #1 sign of AI-generated structural drift.`,
+        line: 1,
+        column: 1,
+        snippet: `// ${lineCount} lines total`,
+      },
+    ]
+  }
+  return []
+}
+
+export function detectLargeFunctions(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 lines = getFunctionLikeLines(fn)
+    const startLine = fn.getStartLineNumber()
+    if (lines > 50) {
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'large-function',
+        severity: 'error',
+        message: `Function spans ${lines} lines (threshold: 50). AI tends to dump logic into single functions.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+export function detectDebugLeftovers(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const expr = call.getExpression().getText()
+    const line = call.getStartLineNumber()
+    if (/^console\.(log|warn|error|debug|info)\b/.test(expr)) {
+      if (hasIgnoreComment(file, line)) continue
+      issues.push({
+        rule: 'debug-leftover',
+        severity: 'warning',
+        message: `console.${expr.split('.')[1]} left in production code.`,
+        line,
+        column: call.getStartLinePos(),
+        snippet: getSnippet(call, file),
+      })
+    }
+  }
+
+  const lines = file.getFullText().split('\n')
+  lines.forEach((lineContent, i) => {
+    if (/\/\/\s*(TODO|FIXME|HACK|XXX|TEMP)\b/i.test(lineContent)) {
+      if (hasIgnoreComment(file, i + 1)) return
+      issues.push({
+        rule: 'debug-leftover',
+        severity: 'warning',
+        message: `Unresolved marker found: ${lineContent.trim().slice(0, 60)}`,
+        line: i + 1,
+        column: 1,
+        snippet: lineContent.trim().slice(0, 120),
+      })
+    }
+  })
+
+  return issues
+}
+
+export function detectDeadCode(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const imp of file.getImportDeclarations()) {
+    for (const named of imp.getNamedImports()) {
+      const name = named.getName()
+      const refs = file.getDescendantsOfKind(SyntaxKind.Identifier).filter(
+        (id) => id.getText() === name && id !== named.getNameNode()
+      )
+      if (refs.length === 0) {
+        issues.push({
+          rule: 'dead-code',
+          severity: 'warning',
+          message: `Unused import '${name}'. AI often imports more than it uses.`,
+          line: imp.getStartLineNumber(),
+          column: imp.getStartLinePos(),
+          snippet: getSnippet(imp, file),
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+export function detectDuplicateFunctionNames(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const seen = new Map<string, number>()
+
+  const fns = file.getFunctions()
+  for (const fn of fns) {
+    const name = fn.getName()
+    if (!name) continue
+    const normalized = name.toLowerCase().replace(/[_-]/g, '')
+    if (seen.has(normalized)) {
+      issues.push({
+        rule: 'duplicate-function-name',
+        severity: 'error',
+        message: `Function '${name}' looks like a duplicate of a previously defined function. AI often generates near-identical helpers.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    } else {
+      seen.set(normalized, fn.getStartLineNumber())
+    }
+  }
+  return issues
+}
+
+export function detectAnyAbuse(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const node of file.getDescendantsOfKind(SyntaxKind.AnyKeyword)) {
+    issues.push({
+      rule: 'any-abuse',
+      severity: 'warning',
+      message: `Explicit 'any' type detected. AI defaults to 'any' when it can't infer types properly.`,
+      line: node.getStartLineNumber(),
+      column: node.getStartLinePos(),
+      snippet: getSnippet(node, file),
+    })
+  }
+  return issues
+}
+
+export function detectCatchSwallow(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const tryCatch of file.getDescendantsOfKind(SyntaxKind.TryStatement)) {
+    const catchClause = tryCatch.getCatchClause()
+    if (!catchClause) continue
+    const block = catchClause.getBlock()
+    const stmts = block.getStatements()
+    if (stmts.length === 0) {
+      issues.push({
+        rule: 'catch-swallow',
+        severity: 'warning',
+        message: `Empty catch block silently swallows errors. Classic AI pattern to make code "not throw".`,
+        line: catchClause.getStartLineNumber(),
+        column: catchClause.getStartLinePos(),
+        snippet: getSnippet(catchClause, file),
+      })
+    }
+  }
+  return issues
+}
+
+export function detectMissingReturnTypes(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const fn of file.getFunctions()) {
+    if (!fn.getReturnTypeNode()) {
+      issues.push({
+        rule: 'no-return-type',
+        severity: 'info',
+        message: `Function '${fn.getName() ?? 'anonymous'}' has no explicit return type.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}

package/src/rules/phase1-complexity.ts

@@ -0,0 +1,302 @@
+import { SourceFile, SyntaxKind, Node } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment, getSnippet, type FunctionLike } from './shared.js'
+
+/**
+ * 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
+}
+
+export 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
+}
+
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
+}

package/src/rules/phase2-crossfile.ts

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { SourceFile } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+
+/**
+ * Detect files that are never imported by any other file in the project.
+ * Entry-point files (index, main, cli, app, bin/) are excluded.
+ */
+export function detectDeadFiles(
+  sourceFiles: SourceFile[],
+  allImportedPaths: Set<string>,
+  ruleWeights: Record<string, { severity: DriftIssue['severity']; weight: number }>,
+): Map<string, DriftIssue> {
+  const issues = new Map<string, DriftIssue>()
+
+  for (const sf of sourceFiles) {
+    const sfPath = sf.getFilePath()
+    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)) {
+      issues.set(sfPath, {
+        rule: 'dead-file',
+        severity: ruleWeights['dead-file'].severity,
+        message: 'File is never imported — may be dead code',
+        line: 1,
+        column: 1,
+        snippet: basename,
+      })
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Detect named exports that are never imported by any other file.
+ * Barrel files (index.*) are excluded since their entire surface is the public API.
+ */
+export function detectUnusedExports(
+  sourceFiles: SourceFile[],
+  allImportedNames: Map<string, Set<string>>,
+  ruleWeights: Record<string, { severity: DriftIssue['severity']; weight: number }>,
+): Map<string, DriftIssue[]> {
+  const result = new Map<string, DriftIssue[]>()
+
+  for (const sf of sourceFiles) {
+    const sfPath = sf.getFilePath()
+    const basename = path.basename(sfPath)
+    const isBarrel = /^index\.(ts|tsx|js|jsx)$/.test(basename)
+    const importedNamesForFile = allImportedNames.get(sfPath)
+    const hasNamespaceImport = importedNamesForFile?.has('*') ?? false
+
+    if (isBarrel || hasNamespaceImport) continue
+
+    const issues: DriftIssue[] = []
+
+    for (const exportDecl of sf.getExportDeclarations()) {
+      for (const namedExport of exportDecl.getNamedExports()) {
+        const name = namedExport.getName()
+        if (!importedNamesForFile?.has(name)) {
+          issues.push({
+            rule: 'unused-export',
+            severity: ruleWeights['unused-export'].severity,
+            message: `'${name}' is exported but never imported`,
+            line: namedExport.getStartLineNumber(),
+            column: 1,
+            snippet: namedExport.getText().slice(0, 80),
+          })
+        }
+      }
+    }
+
+    // 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
+
+        issues.push({
+          rule: 'unused-export',
+          severity: ruleWeights['unused-export'].severity,
+          message: `'${exportName}' is exported but never imported`,
+          line: decl.getStartLineNumber(),
+          column: 1,
+          snippet: decl.getText().split('\n')[0].slice(0, 80),
+        })
+        break // one issue per export name is enough
+      }
+    }
+
+    if (issues.length > 0) {
+      result.set(sfPath, issues)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Detect packages in package.json that are never imported in any source file.
+ * @type-only packages (@types/*) are excluded.
+ */
+export function detectUnusedDependencies(
+  targetPath: string,
+  allLiteralImports: Set<string>,
+  ruleWeights: Record<string, { severity: DriftIssue['severity']; weight: number }>,
+): DriftIssue[] {
+  const pkgPath = path.join(targetPath, 'package.json') // drift-ignore
+  if (!fs.existsSync(pkgPath)) return []
+
+  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
+    const isUsed = [...allLiteralImports].some(
+      imp => imp === depName || imp.startsWith(depName + '/')
+    )
+    if (!isUsed) unusedDeps.push(depName)
+  }
+
+  return unusedDeps.map(dep => ({
+    rule: 'unused-dependency',
+    severity: ruleWeights['unused-dependency'].severity,
+    message: `'${dep}' is in package.json but never imported`,
+    line: 1,
+    column: 1,
+    snippet: `"${dep}"`,
+  }))
+}