@eduardbar/drift 0.4.0 → 0.5.0

package/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

package/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/dist/analyzer.js

@@ -28,6 +28,12 @@ const RULE_WEIGHTS = {
     // 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 },
 };
 function hasIgnoreComment(file, line) {
     const lines = file.getFullText().split('\n');
@@ -509,6 +515,268 @@ function detectCommentContradiction(file) {
     return issues;
 }
 // ---------------------------------------------------------------------------
+// Phase 5: AI authorship heuristics
+// ---------------------------------------------------------------------------
+function detectOverCommented(file) {
+    const issues = [];
+    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) {
+    const issues = [];
+    const CONFIG_PATTERNS = [
+        { 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) {
+    const issues = [];
+    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 = [];
+        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) {
+    const issues = [];
+    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) {
+    const issues = [];
+    const isCamelCase = (name) => /^[a-z][a-zA-Z0-9]*$/.test(name) && /[A-Z]/.test(name);
+    const isSnakeCase = (name) => /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/.test(name);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function checkFunction(fn) {
+        const vars = fn.getVariableDeclarations();
+        if (vars.length < 3)
+            return; // muy pocas vars para ser significativo
+        let camelCount = 0;
+        let snakeCount = 0;
+        const snakeExamples = [];
+        const camelExamples = [];
+        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
 // ---------------------------------------------------------------------------
 function calculateScore(issues) {
@@ -547,6 +815,12 @@ export function analyzeFile(file) {
         // Stubs now implemented
         ...detectMagicNumbers(file),
         ...detectCommentContradiction(file),
+        // Phase 5: AI authorship heuristics
+        ...detectOverCommented(file),
+        ...detectHardcodedConfig(file),
+        ...detectInconsistentErrorHandling(file),
+        ...detectUnnecessaryAbstraction(file),
+        ...detectNamingInconsistency(file),
     ];
     return {
         path: file.getFilePath(),

package/dist/printer.js

@@ -91,6 +91,26 @@ function formatFixSuggestion(issue) {
             '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'];
 }

package/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",

package/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 {

package/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']
 }