feat(analyzer): add Phase 5 AI authorship heuristics (5 rules)

- over-commented (info, weight 4): comment density >= 40% in functions
- hardcoded-config (warning, weight 10): hardcoded URLs, IPs, connection strings
- inconsistent-error-handling (warning, weight 8): mixed try/catch and .catch() patterns
- unnecessary-abstraction (warning, weight 7): single-method interfaces with no reuse
- naming-inconsistency (warning, weight 6): mixed camelCase and snake_case in same scope

Includes fix suggestions in printer.ts, updated README rules table,
CHANGELOG Unreleased section, and version bump to 0.5.0

Author: eduardbar

CHANGELOG.md

@@ -9,6 +9,15 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Added
+
+- **Phase 5: AI authorship heuristics** — 5 new rules that detect patterns AI code generators produce
+  - `over-commented` (info, weight 4): functions where comment density ≥ 40% — AI over-documents the obvious
+  - `hardcoded-config` (warning, weight 10): hardcoded URLs, IPs, or connection strings instead of env vars
+  - `inconsistent-error-handling` (warning, weight 8): mixed `try/catch` and `.catch()` patterns in the same file
+  - `unnecessary-abstraction` (warning, weight 7): single-method interfaces or abstract classes never reused
+  - `naming-inconsistency` (warning, weight 6): mixed camelCase and snake_case identifiers in the same scope
+
 ---
 
 ## [0.4.0] — 2026-02-23

README.md

@@ -151,6 +151,11 @@ npx @eduardbar/drift scan ./src --fix
 | `magic-number` | info | Numeric literals used directly in logic — extract to named constants |
 | `layer-violation` | error | Layer imports a layer it's not allowed to (requires `drift.config.ts`) |
 | `cross-boundary-import` | warning | Module imports from another module outside allowed boundaries (requires `drift.config.ts`) |
+| `over-commented` | info | Functions where comments exceed 40% of lines — AI over-documents the obvious |
+| `hardcoded-config` | warning | Hardcoded URLs, IPs, or connection strings — AI skips environment variables |
+| `inconsistent-error-handling` | warning | Mixed `try/catch` and `.catch()` in the same file — AI combines styles randomly |
+| `unnecessary-abstraction` | warning | Single-method interfaces or abstract classes with no reuse — AI over-engineers |
+| `naming-inconsistency` | warning | Mixed camelCase and snake_case in the same scope — AI forgets project conventions |
 
 ---
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Detect silent technical debt left by AI-generated code",
   "type": "module",
   "main": "dist/index.js",

src/analyzer.ts

@@ -39,6 +39,12 @@ const RULE_WEIGHTS: Record<string, { severity: DriftIssue['severity']; weight: n
   // 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 },
+  // Phase 5: AI authorship heuristics
+  'over-commented':                { severity: 'info',    weight: 4  },
+  'hardcoded-config':              { severity: 'warning', weight: 10 },
+  'inconsistent-error-handling':   { severity: 'warning', weight: 8  },
+  'unnecessary-abstraction':       { severity: 'warning', weight: 7  },
+  'naming-inconsistency':          { severity: 'warning', weight: 6  },
 }
 
 type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
@@ -562,6 +568,299 @@ function detectCommentContradiction(file: SourceFile): DriftIssue[] {
   return issues
 }
 
+// ---------------------------------------------------------------------------
+// Phase 5: AI authorship heuristics
+// ---------------------------------------------------------------------------
+
+function detectOverCommented(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const fn of file.getFunctions()) {
+    const body = fn.getBody()
+    if (!body) continue
+
+    const bodyText = body.getText()
+    const lines = bodyText.split('\n')
+    const totalLines = lines.length
+
+    if (totalLines < 6) continue
+
+    let commentLines = 0
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*') || trimmed.startsWith('*/')) {
+        commentLines++
+      }
+    }
+
+    const ratio = commentLines / totalLines
+    if (ratio >= 0.4) {
+      issues.push({
+        rule: 'over-commented',
+        severity: 'info',
+        message: `Function has ${Math.round(ratio * 100)}% comment density (${commentLines}/${totalLines} lines). AI documents the obvious instead of the why.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: fn.getName() ? `function ${fn.getName()}` : '(anonymous function)',
+      })
+    }
+  }
+
+  for (const cls of file.getClasses()) {
+    for (const method of cls.getMethods()) {
+      const body = method.getBody()
+      if (!body) continue
+
+      const bodyText = body.getText()
+      const lines = bodyText.split('\n')
+      const totalLines = lines.length
+
+      if (totalLines < 6) continue
+
+      let commentLines = 0
+      for (const line of lines) {
+        const trimmed = line.trim()
+        if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*') || trimmed.startsWith('*/')) {
+          commentLines++
+        }
+      }
+
+      const ratio = commentLines / totalLines
+      if (ratio >= 0.4) {
+        issues.push({
+          rule: 'over-commented',
+          severity: 'info',
+          message: `Method '${method.getName()}' has ${Math.round(ratio * 100)}% comment density (${commentLines}/${totalLines} lines). AI documents the obvious instead of the why.`,
+          line: method.getStartLineNumber(),
+          column: method.getStartLinePos(),
+          snippet: `${cls.getName()}.${method.getName()}`,
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+function detectHardcodedConfig(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  const CONFIG_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+    { pattern: /^https?:\/\//i,                          label: 'HTTP/HTTPS URL' },
+    { pattern: /^wss?:\/\//i,                            label: 'WebSocket URL' },
+    { pattern: /^mongodb(\+srv)?:\/\//i,                 label: 'MongoDB connection string' },
+    { pattern: /^postgres(?:ql)?:\/\//i,                 label: 'PostgreSQL connection string' },
+    { pattern: /^mysql:\/\//i,                           label: 'MySQL connection string' },
+    { pattern: /^redis:\/\//i,                           label: 'Redis connection string' },
+    { pattern: /^amqps?:\/\//i,                          label: 'AMQP connection string' },
+    { pattern: /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/,  label: 'IP address' },
+    { pattern: /^:[0-9]{2,5}$/,                          label: 'Port number in string' },
+    { pattern: /^\/[a-z]/i,                              label: 'Absolute file path' },
+    { pattern: /localhost(:[0-9]+)?/i,                   label: 'localhost reference' },
+  ]
+
+  const filePath = file.getFilePath().replace(/\\/g, '/')
+  if (filePath.includes('.test.') || filePath.includes('.spec.') || filePath.includes('__tests__')) {
+    return issues
+  }
+
+  for (const node of file.getDescendantsOfKind(SyntaxKind.StringLiteral)) {
+    const value = node.getLiteralValue()
+    if (!value || value.length < 4) continue
+
+    const parent = node.getParent()
+    if (!parent) continue
+    const parentKind = parent.getKindName()
+    if (
+      parentKind === 'ImportDeclaration' ||
+      parentKind === 'ExportDeclaration' ||
+      (parentKind === 'CallExpression' && parent.getText().startsWith('import('))
+    ) continue
+
+    for (const { pattern, label } of CONFIG_PATTERNS) {
+      if (pattern.test(value)) {
+        issues.push({
+          rule: 'hardcoded-config',
+          severity: 'warning',
+          message: `Hardcoded ${label} detected. AI skips environment variables — extract to process.env or a config module.`,
+          line: node.getStartLineNumber(),
+          column: node.getStartLinePos(),
+          snippet: value.length > 60 ? value.slice(0, 60) + '...' : value,
+        })
+        break
+      }
+    }
+  }
+
+  return issues
+}
+
+function detectInconsistentErrorHandling(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  let hasTryCatch = false
+  let hasDotCatch = false
+  let hasThenErrorHandler = false
+  let firstLine = 0
+
+  // Detectar try/catch
+  const tryCatches = file.getDescendantsOfKind(SyntaxKind.TryStatement)
+  if (tryCatches.length > 0) {
+    hasTryCatch = true
+    firstLine = firstLine || tryCatches[0].getStartLineNumber()
+  }
+
+  // Detectar .catch(handler) en call expressions
+  for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const expr = call.getExpression()
+    if (expr.getKindName() === 'PropertyAccessExpression') {
+      const propAccess = expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression)
+      const propName = propAccess.getName()
+      if (propName === 'catch') {
+        // Verificar que tiene al menos un argumento (handler real, no .catch() vacío)
+        if (call.getArguments().length > 0) {
+          hasDotCatch = true
+          if (!firstLine) firstLine = call.getStartLineNumber()
+        }
+      }
+      // Detectar .then(onFulfilled, onRejected) — segundo argumento = error handler
+      if (propName === 'then' && call.getArguments().length >= 2) {
+        hasThenErrorHandler = true
+        if (!firstLine) firstLine = call.getStartLineNumber()
+      }
+    }
+  }
+
+  const stylesUsed = [hasTryCatch, hasDotCatch, hasThenErrorHandler].filter(Boolean).length
+
+  if (stylesUsed >= 2) {
+    const styles: string[] = []
+    if (hasTryCatch) styles.push('try/catch')
+    if (hasDotCatch) styles.push('.catch()')
+    if (hasThenErrorHandler) styles.push('.then(_, handler)')
+
+    issues.push({
+      rule: 'inconsistent-error-handling',
+      severity: 'warning',
+      message: `Mixed error handling styles: ${styles.join(', ')}. AI uses whatever pattern it saw last — pick one and stick to it.`,
+      line: firstLine || 1,
+      column: 1,
+      snippet: styles.join(' + '),
+    })
+  }
+
+  return issues
+}
+
+function detectUnnecessaryAbstraction(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const fileText = file.getFullText()
+
+  // Interfaces con un solo método
+  for (const iface of file.getInterfaces()) {
+    const methods = iface.getMethods()
+    const properties = iface.getProperties()
+
+    // Solo reportar si tiene exactamente 1 método y 0 propiedades (abstracción pura de comportamiento)
+    if (methods.length !== 1 || properties.length !== 0) continue
+
+    const ifaceName = iface.getName()
+
+    // Contar cuántas veces aparece el nombre en el archivo (excluyendo la declaración misma)
+    const usageCount = (fileText.match(new RegExp(`\\b${ifaceName}\\b`, 'g')) ?? []).length
+    // La declaración misma cuenta como 1 uso, implementaciones cuentan como 1 cada una
+    // Si usageCount <= 2 (declaración + 1 uso), es candidata a innecesaria
+    if (usageCount <= 2) {
+      issues.push({
+        rule: 'unnecessary-abstraction',
+        severity: 'warning',
+        message: `Interface '${ifaceName}' has 1 method and is used only once. AI creates abstractions preemptively — YAGNI.`,
+        line: iface.getStartLineNumber(),
+        column: iface.getStartLinePos(),
+        snippet: `interface ${ifaceName} { ${methods[0].getName()}(...) }`,
+      })
+    }
+  }
+
+  // Clases abstractas con un solo método abstracto y sin implementaciones en el archivo
+  for (const cls of file.getClasses()) {
+    if (!cls.isAbstract()) continue
+
+    const abstractMethods = cls.getMethods().filter(m => m.isAbstract())
+    const concreteMethods = cls.getMethods().filter(m => !m.isAbstract())
+
+    if (abstractMethods.length !== 1 || concreteMethods.length !== 0) continue
+
+    const clsName = cls.getName() ?? ''
+    const usageCount = (fileText.match(new RegExp(`\\b${clsName}\\b`, 'g')) ?? []).length
+
+    if (usageCount <= 2) {
+      issues.push({
+        rule: 'unnecessary-abstraction',
+        severity: 'warning',
+        message: `Abstract class '${clsName}' has 1 abstract method and is extended nowhere in this file. AI over-engineers single-use code.`,
+        line: cls.getStartLineNumber(),
+        column: cls.getStartLinePos(),
+        snippet: `abstract class ${clsName}`,
+      })
+    }
+  }
+
+  return issues
+}
+
+function detectNamingInconsistency(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  const isCamelCase = (name: string) => /^[a-z][a-zA-Z0-9]*$/.test(name) && /[A-Z]/.test(name)
+  const isSnakeCase = (name: string) => /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/.test(name)
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function checkFunction(fn: any): void {
+    const vars = fn.getVariableDeclarations()
+    if (vars.length < 3) return  // muy pocas vars para ser significativo
+
+    let camelCount = 0
+    let snakeCount = 0
+    const snakeExamples: string[] = []
+    const camelExamples: string[] = []
+
+    for (const v of vars) {
+      const name = v.getName()
+      if (isCamelCase(name)) {
+        camelCount++
+        if (camelExamples.length < 2) camelExamples.push(name)
+      } else if (isSnakeCase(name)) {
+        snakeCount++
+        if (snakeExamples.length < 2) snakeExamples.push(name)
+      }
+    }
+
+    if (camelCount >= 1 && snakeCount >= 1) {
+      issues.push({
+        rule: 'naming-inconsistency',
+        severity: 'warning',
+        message: `Mixed naming conventions: camelCase (${camelExamples.join(', ')}) and snake_case (${snakeExamples.join(', ')}) in the same scope. AI mixes conventions from different training examples.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: `camelCase: ${camelExamples[0]} / snake_case: ${snakeExamples[0]}`,
+      })
+    }
+  }
+
+  for (const fn of file.getFunctions()) {
+    checkFunction(fn)
+  }
+
+  for (const cls of file.getClasses()) {
+    for (const method of cls.getMethods()) {
+      checkFunction(method)
+    }
+  }
+
+  return issues
+}
+
 // ---------------------------------------------------------------------------
 // Score
 // ---------------------------------------------------------------------------
@@ -605,6 +904,12 @@ export function analyzeFile(file: SourceFile): FileReport {
     // Stubs now implemented
     ...detectMagicNumbers(file),
     ...detectCommentContradiction(file),
+    // Phase 5: AI authorship heuristics
+    ...detectOverCommented(file),
+    ...detectHardcodedConfig(file),
+    ...detectInconsistentErrorHandling(file),
+    ...detectUnnecessaryAbstraction(file),
+    ...detectNamingInconsistency(file),
   ]
 
   return {

src/printer.ts

@@ -93,6 +93,26 @@ function formatFixSuggestion(issue: DriftIssue): string[] {
       'Or add the module to allowedExternalImports in drift.config.ts if this is intentional',
       'Consider using dependency injection or an event bus to decouple the modules',
     ],
+    'over-commented': [
+      'Remove comments that restate what the code already expresses clearly',
+      'Keep only comments that explain WHY, not WHAT — prefer self-documenting names',
+    ],
+    'hardcoded-config': [
+      'Move the value to an environment variable: process.env.YOUR_VAR',
+      'Or extract it to a config file / constants module imported at the top',
+    ],
+    'inconsistent-error-handling': [
+      'Pick one style (async/await + try/catch is preferred) and apply it consistently',
+      'Avoid mixing .then()/.catch() with await in the same file',
+    ],
+    'unnecessary-abstraction': [
+      'Inline the abstraction if it has only one implementation and is never reused',
+      'Or document why the extension point exists (e.g., future plugin system)',
+    ],
+    'naming-inconsistency': [
+      'Pick one naming convention (camelCase for variables/functions, PascalCase for types)',
+      'Rename snake_case identifiers to camelCase to match TypeScript conventions',
+    ],
   }
   return suggestions[issue.rule] ?? ['Review and fix manually']
 }