@eduardbar/drift 0.4.0 → 0.6.0

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/badge.ts

@@ -0,0 +1,60 @@
+import type {} from './types.js'
+
+const LEFT_WIDTH = 47
+const CHAR_WIDTH = 7
+const PADDING = 16
+
+function scoreColor(score: number): string {
+  if (score < 20) return '#4c1'
+  if (score < 45) return '#dfb317'
+  if (score < 70) return '#fe7d37'
+  return '#e05d44'
+}
+
+function scoreLabel(score: number): string {
+  if (score < 20) return 'LOW'
+  if (score < 45) return 'MODERATE'
+  if (score < 70) return 'HIGH'
+  return 'CRITICAL'
+}
+
+function rightWidth(text: string): number {
+  return text.length * CHAR_WIDTH + PADDING
+}
+
+export function generateBadge(score: number): string {
+  const valueText = `${score} ${scoreLabel(score)}`
+  const color = scoreColor(score)
+
+  const rWidth = rightWidth(valueText)
+  const totalWidth = LEFT_WIDTH + rWidth
+
+  const leftCenterX = LEFT_WIDTH / 2
+  const rightCenterX = LEFT_WIDTH + rWidth / 2
+
+  // shields.io pattern: font-size="110" + scale(.1) = effective 11px
+  // all X/Y coords are ×10
+  const leftTextWidth = (LEFT_WIDTH - 10) * 10
+  const rightTextWidth = (rWidth - PADDING) * 10
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${totalWidth}" height="20">
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r">
+    <rect width="${totalWidth}" height="20" rx="3" fill="#fff"/>
+  </clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${LEFT_WIDTH}" height="20" fill="#555"/>
+    <rect x="${LEFT_WIDTH}" width="${rWidth}" height="20" fill="${color}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110">
+    <text x="${leftCenterX * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${leftTextWidth}" lengthAdjust="spacing">drift</text>
+    <text x="${leftCenterX * 10}" y="140" transform="scale(.1)" textLength="${leftTextWidth}" lengthAdjust="spacing">drift</text>
+    <text x="${rightCenterX * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${rightTextWidth}" lengthAdjust="spacing">${valueText}</text>
+    <text x="${rightCenterX * 10}" y="140" transform="scale(.1)" textLength="${rightTextWidth}" lengthAdjust="spacing">${valueText}</text>
+  </g>
+</svg>`
+}

package/src/ci.ts

@@ -0,0 +1,87 @@
+import { writeFileSync } from 'node:fs'
+import { relative } from 'node:path'
+import type { DriftReport } from './types.js'
+
+function encodeMessage(msg: string): string {
+  return msg
+    .replace(/%/g, '%25')
+    .replace(/\r/g, '%0D')
+    .replace(/\n/g, '%0A')
+    .replace(/:/g, '%3A')
+    .replace(/,/g, '%2C')
+}
+
+function severityToAnnotation(s: string): 'error' | 'warning' | 'notice' {
+  if (s === 'error') return 'error'
+  if (s === 'warning') return 'warning'
+  return 'notice'
+}
+
+function scoreLabel(score: number): string {
+  if (score >= 80) return 'A'
+  if (score >= 60) return 'B'
+  if (score >= 40) return 'C'
+  if (score >= 20) return 'D'
+  return 'F'
+}
+
+export function emitCIAnnotations(report: DriftReport): void {
+  for (const file of report.files) {
+    for (const issue of file.issues) {
+      const level = severityToAnnotation(issue.severity)
+      const relPath = relative(process.cwd(), file.path).replace(/\\/g, '/')
+      const msg = encodeMessage(`[drift/${issue.rule}] ${issue.message}`)
+      const line = issue.line ?? 1
+      const col = issue.column ?? 1
+      process.stdout.write(`::${level} file=${relPath},line=${line},col=${col}::${msg}\n`)
+    }
+  }
+}
+
+export function printCISummary(report: DriftReport): void {
+  const summaryPath = process.env['GITHUB_STEP_SUMMARY']
+  if (!summaryPath) return
+
+  const score = report.totalScore
+  const grade = scoreLabel(score)
+
+  let errors = 0
+  let warnings = 0
+  let info = 0
+
+  for (const file of report.files) {
+    for (const issue of file.issues) {
+      if (issue.severity === 'error') errors++
+      else if (issue.severity === 'warning') warnings++
+      else info++
+    }
+  }
+
+  const sorted = [...report.files]
+    .sort((a, b) => b.issues.length - a.issues.length)
+    .slice(0, 10)
+
+  const rows = sorted
+    .map((f) => {
+      const relPath = relative(process.cwd(), f.path).replace(/\\/g, '/')
+      return `| ${relPath} | ${f.score} | ${f.issues.length} |`
+    })
+    .join('\n')
+
+  const md = [
+    '## drift scan results',
+    '',
+    `**Score:** ${score}/100 — Grade **${grade}**`,
+    '',
+    '### Top files by issue count',
+    '',
+    '| File | Score | Issues |',
+    '|------|-------|--------|',
+    rows,
+    '',
+    `**Total issues:** ${errors} errors, ${warnings} warnings, ${info} info`,
+    '',
+  ].join('\n')
+
+  writeFileSync(summaryPath, md, { flag: 'a' })
+}

package/src/cli.ts

@@ -8,13 +8,16 @@ import { printConsole, printDiff } from './printer.js'
 import { loadConfig } from './config.js'
 import { extractFilesAtRef, cleanupTempDir } from './git.js'
 import { computeDiff } from './diff.js'
+import { generateHtmlReport } from './report.js'
+import { generateBadge } from './badge.js'
+import { emitCIAnnotations, printCISummary } from './ci.js'
 
 const program = new Command()
 
 program
   .name('drift')
   .description('Detect silent technical debt left by AI-generated code')
-  .version('0.1.0')
+  .version('0.6.0')
 
 program
   .command('scan [path]', { isDefault: true })
@@ -109,4 +112,55 @@ program
     }
   })
 
+program
+  .command('report [path]')
+  .description('Generate a self-contained HTML report')
+  .option('-o, --output <file>', 'Output file path (default: drift-report.html)', 'drift-report.html')
+  .action(async (targetPath: string | undefined, options: { output: string }) => {
+    const resolvedPath = resolve(targetPath ?? '.')
+    process.stderr.write(`\nScanning ${resolvedPath}...\n`)
+    const config = await loadConfig(resolvedPath)
+    const files = analyzeProject(resolvedPath, config)
+    process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
+    const report = buildReport(resolvedPath, files)
+    const html = generateHtmlReport(report)
+    const outPath = resolve(options.output)
+    writeFileSync(outPath, html, 'utf8')
+    process.stderr.write(`  Report saved to ${outPath}\n\n`)
+  })
+
+program
+  .command('badge [path]')
+  .description('Generate a badge.svg with the current drift score')
+  .option('-o, --output <file>', 'Output file path (default: badge.svg)', 'badge.svg')
+  .action(async (targetPath: string | undefined, options: { output: string }) => {
+    const resolvedPath = resolve(targetPath ?? '.')
+    process.stderr.write(`\nScanning ${resolvedPath}...\n`)
+    const config = await loadConfig(resolvedPath)
+    const files = analyzeProject(resolvedPath, config)
+    const report = buildReport(resolvedPath, files)
+    const svg = generateBadge(report.totalScore)
+    const outPath = resolve(options.output)
+    writeFileSync(outPath, svg, 'utf8')
+    process.stderr.write(`  Badge saved to ${outPath}\n`)
+    process.stderr.write(`  Score: ${report.totalScore}/100\n\n`)
+  })
+
+program
+  .command('ci [path]')
+  .description('Emit GitHub Actions annotations and step summary')
+  .option('--min-score <n>', 'Exit with code 1 if overall score exceeds this threshold', '0')
+  .action(async (targetPath: string | undefined, options: { minScore: string }) => {
+    const resolvedPath = resolve(targetPath ?? '.')
+    const config = await loadConfig(resolvedPath)
+    const files = analyzeProject(resolvedPath, config)
+    const report = buildReport(resolvedPath, files)
+    emitCIAnnotations(report)
+    printCISummary(report)
+    const minScore = Number(options.minScore)
+    if (minScore > 0 && report.totalScore > minScore) {
+      process.exit(1)
+    }
+  })
+
 program.parse()

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