@eduardbar/drift 0.5.0 → 0.7.0

package/packages/eslint-plugin-drift/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "eslint-plugin-drift",
+  "version": "0.1.0",
+  "description": "ESLint plugin that exposes drift's technical debt rules for ESLint 9 flat config",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "drift",
+    "technical-debt",
+    "ai",
+    "typescript"
+  ],
+  "author": "eduardbar",
+  "license": "MIT",
+  "homepage": "https://github.com/eduardbar/drift#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eduardbar/drift.git"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "dependencies": {
+    "@eduardbar/drift": "^0.7.0",
+    "ts-morph": "^27.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  }
+}

package/packages/eslint-plugin-drift/src/index.ts

@@ -0,0 +1,170 @@
+import { analyzeFile } from '@eduardbar/drift'
+import type { FileReport } from '@eduardbar/drift'
+import { Project } from 'ts-morph'
+import type { Rule } from 'eslint'
+
+// Tipos auxiliares
+type RuleType = 'problem' | 'suggestion' | 'layout'
+
+// Mapeo rule → descripción legible
+const RULE_DOCS: Record<string, { type: RuleType; description: string }> = {
+  'large-file':                   { type: 'problem',    description: 'Files over 300 lines — AI dumps everything into one place' },
+  'large-function':               { type: 'problem',    description: 'Functions over 50 lines — AI avoids splitting logic' },
+  'duplicate-function-name':      { type: 'problem',    description: 'Near-identical function names — AI regenerates instead of reusing' },
+  'high-complexity':              { type: 'problem',    description: 'Cyclomatic complexity > 10 — AI generates correct code, not simple code' },
+  'circular-dependency':          { type: 'problem',    description: 'Circular import chains between modules' },
+  'layer-violation':              { type: 'problem',    description: 'Import from a prohibited architectural layer (requires drift.config.ts)' },
+  'debug-leftover':               { type: 'suggestion', description: 'console.log, TODO, FIXME comments left in production code' },
+  'dead-code':                    { type: 'suggestion', description: 'Unused imports — AI imports more than it uses' },
+  'any-abuse':                    { type: 'suggestion', description: 'Explicit any type — AI defaults to any when it cannot infer' },
+  'catch-swallow':                { type: 'suggestion', description: 'Empty catch blocks — AI makes code not throw' },
+  'comment-contradiction':        { type: 'suggestion', description: 'Comments that restate what the code already says' },
+  'deep-nesting':                 { type: 'suggestion', description: 'Nesting depth > 3 — unreadable control flow' },
+  'too-many-params':              { type: 'suggestion', description: 'Functions with more than 4 parameters' },
+  'high-coupling':                { type: 'suggestion', description: 'Files importing from more than 10 modules' },
+  'promise-style-mix':            { type: 'suggestion', description: 'async/await and .then() mixed in the same file' },
+  'unused-export':                { type: 'suggestion', description: 'Named exports never imported anywhere in the project' },
+  'dead-file':                    { type: 'suggestion', description: 'Files never imported by any other file' },
+  'unused-dependency':            { type: 'suggestion', description: 'Packages in package.json never imported in source code' },
+  'cross-boundary-import':        { type: 'suggestion', description: 'Module imports from another module outside allowed boundaries' },
+  'hardcoded-config':             { type: 'suggestion', description: 'Hardcoded URLs, IPs, or connection strings — AI skips env vars' },
+  'inconsistent-error-handling':  { type: 'suggestion', description: 'Mixed try/catch and .catch() patterns in the same file' },
+  'unnecessary-abstraction':      { type: 'suggestion', description: 'Single-method interfaces or abstract classes never reused' },
+  'naming-inconsistency':         { type: 'suggestion', description: 'Mixed camelCase and snake_case in the same scope' },
+  'no-return-type':               { type: 'suggestion', description: 'Missing explicit return types on functions' },
+  'magic-number':                 { type: 'suggestion', description: 'Numeric literals used directly in logic' },
+  'over-commented':               { type: 'suggestion', description: 'Functions where comments exceed 40% of lines' },
+}
+
+// ts-morph Project singleton — reutilizado para todos los archivos en un lint run
+const project = new Project({
+  skipAddingFilesFromTsConfig: true,
+  compilerOptions: { allowJs: true },
+})
+
+// Cache de FileReport por filename para no llamar analyzeFile 26 veces por archivo
+const cache = new Map<string, FileReport>()
+
+function getFileReport(filename: string): FileReport {
+  if (cache.has(filename)) return cache.get(filename)!
+
+  // Obtener o agregar el SourceFile al Project
+  let sourceFile = project.getSourceFile(filename)
+  if (!sourceFile) {
+    sourceFile = project.addSourceFileAtPath(filename)
+  }
+
+  const report = analyzeFile(sourceFile)
+  cache.set(filename, report)
+
+  // Evitar memory leak en watch mode — mantener máximo 100 entradas
+  if (cache.size > 100) {
+    const firstKey = cache.keys().next().value
+    if (firstKey !== undefined) cache.delete(firstKey)
+  }
+
+  return report
+}
+
+// Crea una regla ESLint para una regla drift específica
+function createRule(ruleName: string): Rule.RuleModule {
+  const doc = RULE_DOCS[ruleName] ?? { type: 'suggestion' as RuleType, description: ruleName }
+
+  return {
+    meta: {
+      type: doc.type,
+      docs: {
+        description: doc.description,
+        url: `https://github.com/eduardbar/drift#${ruleName}`,
+      },
+      schema: [],
+      messages: {
+        issue: '{{ message }}',
+      },
+    },
+    create(context) {
+      return {
+        'Program:exit'() {
+          const filename = context.filename
+          if (!filename.endsWith('.ts') && !filename.endsWith('.tsx')) return
+          if (filename.includes('node_modules')) return
+
+          try {
+            const fileReport = getFileReport(filename)
+            for (const issue of fileReport.issues) {
+              if (issue.rule !== ruleName) continue
+              const col = issue.column > 0 ? issue.column - 1 : 0
+              context.report({
+                loc: {
+                  start: { line: issue.line, column: col },
+                  end:   { line: issue.line, column: col + 1 },
+                },
+                messageId: 'issue',
+                data: { message: issue.message },
+              })
+            }
+          } catch {
+            // Archivo no parseable por ts-morph — silenciar
+          }
+        },
+      }
+    },
+  }
+}
+
+// Objeto con todas las reglas
+const rules: Record<string, Rule.RuleModule> = Object.fromEntries(
+  Object.keys(RULE_DOCS).map(name => [name, createRule(name)])
+)
+
+// Plugin object
+const plugin = {
+  meta: {
+    name: 'eslint-plugin-drift',
+    version: '0.1.0',
+  },
+  rules,
+  configs: {} as Record<string, unknown>,
+}
+
+// Config recommended — todas las reglas en su severidad canónica de drift
+Object.assign(plugin.configs, {
+  recommended: [
+    {
+      plugins: { drift: plugin },
+      rules: {
+        // errors
+        'drift/large-file':              'error',
+        'drift/large-function':          'error',
+        'drift/duplicate-function-name': 'error',
+        'drift/high-complexity':         'error',
+        'drift/circular-dependency':     'error',
+        'drift/layer-violation':         'error',
+        // warnings
+        'drift/debug-leftover':              'warn',
+        'drift/dead-code':                   'warn',
+        'drift/any-abuse':                   'warn',
+        'drift/catch-swallow':               'warn',
+        'drift/comment-contradiction':       'warn',
+        'drift/deep-nesting':                'warn',
+        'drift/too-many-params':             'warn',
+        'drift/high-coupling':               'warn',
+        'drift/promise-style-mix':           'warn',
+        'drift/unused-export':               'warn',
+        'drift/dead-file':                   'warn',
+        'drift/unused-dependency':           'warn',
+        'drift/cross-boundary-import':       'warn',
+        'drift/hardcoded-config':            'warn',
+        'drift/inconsistent-error-handling': 'warn',
+        'drift/unnecessary-abstraction':     'warn',
+        'drift/naming-inconsistency':        'warn',
+        // info → ESLint no tiene "info", mapeamos a "warn"
+        'drift/no-return-type':   'warn',
+        'drift/magic-number':     'warn',
+        'drift/over-commented':   'warn',
+      },
+    },
+  ],
+})
+
+export default plugin

package/packages/eslint-plugin-drift/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/src/analyzer.ts

@@ -13,7 +13,7 @@ import {
 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 }> = {
+export const RULE_WEIGHTS: Record<string, { severity: DriftIssue['severity']; weight: number }> = {
   'large-file':               { severity: 'error',   weight: 20 },
   'large-function':           { severity: 'error',   weight: 15 },
   'debug-leftover':           { severity: 'warning', weight: 10 },

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

@@ -1,4 +1,4 @@
-export { analyzeProject, analyzeFile } from './analyzer.js'
+export { analyzeProject, analyzeFile, RULE_WEIGHTS } from './analyzer.js'
 export { buildReport, formatMarkdown } from './reporter.js'
 export { computeDiff } from './diff.js'
-export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff } from './types.js'
+export type { DriftReport, FileReport, DriftIssue, DriftDiff, FileDiff, DriftConfig } from './types.js'

package/src/printer.ts

@@ -118,66 +118,66 @@ function formatFixSuggestion(issue: DriftIssue): string[] {
 }
 
 export function printConsole(report: DriftReport, options?: { showFix?: boolean }): void {
-  const sep = kleur.gray('  ' + '─'.repeat(50))
-
-  console.log()
-  console.log(kleur.bold().white('  drift') + kleur.gray('  —  vibe coding debt detector'))
-  console.log(sep)
-  console.log()
-
-  const grade = scoreToGrade(report.totalScore)
-  const scoreColor = report.totalScore === 0
-    ? kleur.green
-    : report.totalScore < 45
-    ? kleur.yellow
-    : kleur.red
-
-  const bar = scoreBar(report.totalScore)
-  console.log(
-    `  Score   ${kleur.gray(bar)}  ${scoreColor().bold(String(report.totalScore))}/100  ${grade.badge}`
-  )
-
-  const cleanFiles = report.totalFiles - report.files.length
-  console.log(
-    kleur.gray(
-      `  ${report.files.length} file(s) with issues  ·  ${report.summary.errors} errors  ·  ${report.summary.warnings} warnings  ·  ${report.summary.infos} info  ·  ${cleanFiles} files clean`
-    )
-  )
-  console.log()
-
-  // Top issues in header
-  const topRules = Object.entries(report.summary.byRule).sort((a, b) => b[1] - a[1]).slice(0, 3)
-  if (topRules.length > 0) {
-    const parts = topRules.map(([rule, count]) => `${kleur.cyan(rule)} ${kleur.gray(`×${count}`)}`)
-    console.log(`  Top issues:  ${parts.join(kleur.gray('  ·  '))}`)
-    console.log()
-  }
-
-  console.log(sep)
-  console.log()
-
-  if (report.files.length === 0) {
-    console.log(kleur.green('  No drift detected. Clean codebase.'))
-    console.log()
-    return
-  }
-
-  for (const file of report.files) {
-    const rel = file.path.replace(report.targetPath, '').replace(/^[\\/]/, '')
-    console.log(
-      kleur.bold().white(`  ${rel}`) +
-        kleur.gray(` (score ${file.score}/100)`)
-    )
-
-    for (const issue of file.issues) {
-      const icon = severityIcon(issue.severity)
-      const colorFn = (s: string) =>
-        issue.severity === 'error'
-          ? kleur.red(s)
-          : issue.severity === 'warning'
-          ? kleur.yellow(s)
-          : kleur.cyan(s)
-
+  const sep = kleur.gray('  ' + '─'.repeat(50))
+
+  console.log()
+  console.log(kleur.bold().white('  drift') + kleur.gray('  —  vibe coding debt detector'))
+  console.log(sep)
+  console.log()
+
+  const grade = scoreToGrade(report.totalScore)
+  const scoreColor = report.totalScore === 0
+    ? kleur.green
+    : report.totalScore < 45
+    ? kleur.yellow
+    : kleur.red
+
+  const bar = scoreBar(report.totalScore)
+  console.log(
+    `  Score   ${kleur.gray(bar)}  ${scoreColor().bold(String(report.totalScore))}/100  ${grade.badge}`
+  )
+
+  const cleanFiles = report.totalFiles - report.files.length
+  console.log(
+    kleur.gray(
+      `  ${report.files.length} file(s) with issues  ·  ${report.summary.errors} errors  ·  ${report.summary.warnings} warnings  ·  ${report.summary.infos} info  ·  ${cleanFiles} files clean`
+    )
+  )
+  console.log()
+
+  // Top issues in header
+  const topRules = Object.entries(report.summary.byRule).sort((a, b) => b[1] - a[1]).slice(0, 3)
+  if (topRules.length > 0) {
+    const parts = topRules.map(([rule, count]) => `${kleur.cyan(rule)} ${kleur.gray(`×${count}`)}`)
+    console.log(`  Top issues:  ${parts.join(kleur.gray('  ·  '))}`)
+    console.log()
+  }
+
+  console.log(sep)
+  console.log()
+
+  if (report.files.length === 0) {
+    console.log(kleur.green('  No drift detected. Clean codebase.'))
+    console.log()
+    return
+  }
+
+  for (const file of report.files) {
+    const rel = file.path.replace(report.targetPath, '').replace(/^[\\/]/, '')
+    console.log(
+      kleur.bold().white(`  ${rel}`) +
+        kleur.gray(` (score ${file.score}/100)`)
+    )
+
+    for (const issue of file.issues) {
+      const icon = severityIcon(issue.severity)
+      const colorFn = (s: string) =>
+        issue.severity === 'error'
+          ? kleur.red(s)
+          : issue.severity === 'warning'
+          ? kleur.yellow(s)
+          : kleur.cyan(s)
+
       console.log(
         `    ${colorFn(icon)} ` +
           kleur.gray(`L${issue.line}`) +