@eduardbar/drift 0.1.0

package/dist/reporter.js

@@ -0,0 +1,92 @@
+export function buildReport(targetPath, files) {
+    const allIssues = files.flatMap((f) => f.issues);
+    const byRule = {};
+    for (const issue of allIssues) {
+        byRule[issue.rule] = (byRule[issue.rule] ?? 0) + 1;
+    }
+    const totalScore = files.length > 0
+        ? Math.round(files.reduce((sum, f) => sum + f.score, 0) / files.length)
+        : 0;
+    return {
+        scannedAt: new Date().toISOString(),
+        targetPath,
+        files: files.filter((f) => f.issues.length > 0).sort((a, b) => b.score - a.score),
+        totalIssues: allIssues.length,
+        totalScore,
+        summary: {
+            errors: allIssues.filter((i) => i.severity === 'error').length,
+            warnings: allIssues.filter((i) => i.severity === 'warning').length,
+            infos: allIssues.filter((i) => i.severity === 'info').length,
+            byRule,
+        },
+    };
+}
+export function formatMarkdown(report) {
+    const grade = scoreToGrade(report.totalScore);
+    const lines = [];
+    lines.push(`# drift report`);
+    lines.push(``);
+    lines.push(`> Generated: ${new Date(report.scannedAt).toLocaleString()}`);
+    lines.push(`> Path: \`${report.targetPath}\``);
+    lines.push(``);
+    lines.push(`## Overall drift score: ${report.totalScore}/100 ${grade.badge}`);
+    lines.push(``);
+    lines.push(`| | Count |`);
+    lines.push(`|---|---|`);
+    lines.push(`| Errors | ${report.summary.errors} |`);
+    lines.push(`| Warnings | ${report.summary.warnings} |`);
+    lines.push(`| Info | ${report.summary.infos} |`);
+    lines.push(`| Files with issues | ${report.files.length} |`);
+    lines.push(`| Total issues | ${report.totalIssues} |`);
+    lines.push(``);
+    if (Object.keys(report.summary.byRule).length > 0) {
+        lines.push(`## Issues by rule`);
+        lines.push(``);
+        const sorted = Object.entries(report.summary.byRule).sort((a, b) => b[1] - a[1]);
+        for (const [rule, count] of sorted) {
+            lines.push(`- \`${rule}\`: ${count}`);
+        }
+        lines.push(``);
+    }
+    if (report.files.length === 0) {
+        lines.push(`## No drift detected`);
+        lines.push(``);
+        lines.push(`No issues found. Clean codebase.`);
+    }
+    else {
+        lines.push(`## Files (sorted by drift score)`);
+        lines.push(``);
+        for (const file of report.files) {
+            lines.push(`### \`${file.path}\` — score ${file.score}/100`);
+            lines.push(``);
+            for (const issue of file.issues) {
+                const icon = severityIcon(issue.severity);
+                lines.push(`**${icon} [${issue.rule}]** Line ${issue.line}: ${issue.message}`);
+                lines.push(`\`\`\``);
+                lines.push(issue.snippet);
+                lines.push(`\`\`\``);
+                lines.push(``);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function scoreToGrade(score) {
+    if (score === 0)
+        return { badge: '✦ CLEAN', label: 'clean' };
+    if (score < 20)
+        return { badge: '◎ LOW', label: 'low' };
+    if (score < 45)
+        return { badge: '◈ MODERATE', label: 'moderate' };
+    if (score < 70)
+        return { badge: '◉ HIGH', label: 'high' };
+    return { badge: '⬡ CRITICAL', label: 'critical' };
+}
+function severityIcon(s) {
+    if (s === 'error')
+        return '✖';
+    if (s === 'warning')
+        return '▲';
+    return '◦';
+}
+//# sourceMappingURL=reporter.js.map

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export interface DriftIssue {
+    rule: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    line: number;
+    column: number;
+    snippet: string;
+}
+export interface FileReport {
+    path: string;
+    issues: DriftIssue[];
+    score: number;
+}
+export interface DriftReport {
+    scannedAt: string;
+    targetPath: string;
+    files: FileReport[];
+    totalIssues: number;
+    totalScore: number;
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        byRule: Record<string, number>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@eduardbar/drift",
+  "version": "0.1.0",
+  "description": "Detect silent technical debt left by AI-generated code",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "drift": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["vibe-coding", "technical-debt", "ai", "cli", "typescript", "static-analysis"],
+  "author": "eduardbar",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.3",
+    "kleur": "^4.1.5",
+    "ts-morph": "^27.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/analyzer.ts

@@ -0,0 +1,270 @@
+import {
+  Project,
+  SourceFile,
+  SyntaxKind,
+  Node,
+  FunctionDeclaration,
+  ArrowFunction,
+  FunctionExpression,
+  MethodDeclaration,
+} from 'ts-morph'
+import type { DriftIssue, FileReport } from './types.js'
+
+// Rules and their drift score weight
+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 },
+  'dead-code':                { severity: 'warning', weight: 8  },
+  'duplicate-function-name':  { severity: 'error',   weight: 18 },
+  'comment-contradiction':    { severity: 'warning', weight: 12 },
+  'no-return-type':           { severity: 'info',    weight: 5  },
+  'catch-swallow':            { severity: 'warning', weight: 10 },
+  'magic-number':             { severity: 'info',    weight: 3  },
+  'any-abuse':                { severity: 'warning', weight: 8  },
+}
+
+type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
+
+function getSnippet(node: Node, file: SourceFile): string {
+  const startLine = node.getStartLineNumber()
+  const lines = file.getFullText().split('\n')
+  return lines
+    .slice(Math.max(0, startLine - 1), startLine + 1)
+    .join('\n')
+    .trim()
+    .slice(0, 120)
+}
+
+function getFunctionLikeLines(node: FunctionLike): number {
+  return node.getEndLineNumber() - node.getStartLineNumber()
+}
+
+function detectLargeFile(file: SourceFile): DriftIssue[] {
+  const lineCount = file.getEndLineNumber()
+  if (lineCount > 300) {
+    return [
+      {
+        rule: 'large-file',
+        severity: 'error',
+        message: `File has ${lineCount} lines (threshold: 300). Large files are the #1 sign of AI-generated structural drift.`,
+        line: 1,
+        column: 1,
+        snippet: `// ${lineCount} lines total`,
+      },
+    ]
+  }
+  return []
+}
+
+function detectLargeFunctions(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const fns: FunctionLike[] = [
+    ...file.getFunctions(),
+    ...file.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+    ...file.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+    ...file.getClasses().flatMap((c) => c.getMethods()),
+  ]
+
+  for (const fn of fns) {
+    const lines = getFunctionLikeLines(fn)
+    if (lines > 50) {
+      issues.push({
+        rule: 'large-function',
+        severity: 'error',
+        message: `Function spans ${lines} lines (threshold: 50). AI tends to dump logic into single functions.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+function detectDebugLeftovers(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const expr = call.getExpression().getText()
+    if (/^console\.(log|warn|error|debug|info)\b/.test(expr)) {
+      issues.push({
+        rule: 'debug-leftover',
+        severity: 'warning',
+        message: `console.${expr.split('.')[1]} left in production code.`,
+        line: call.getStartLineNumber(),
+        column: call.getStartLinePos(),
+        snippet: getSnippet(call, file),
+      })
+    }
+  }
+
+  const lines = file.getFullText().split('\n')
+  lines.forEach((line, i) => {
+    if (/\/\/\s*(TODO|FIXME|HACK|XXX|TEMP)\b/i.test(line)) {
+      issues.push({
+        rule: 'debug-leftover',
+        severity: 'warning',
+        message: `Unresolved marker found: ${line.trim().slice(0, 60)}`,
+        line: i + 1,
+        column: 1,
+        snippet: line.trim().slice(0, 120),
+      })
+    }
+  })
+
+  return issues
+}
+
+function detectDeadCode(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const imp of file.getImportDeclarations()) {
+    for (const named of imp.getNamedImports()) {
+      const name = named.getName()
+      const refs = file.getDescendantsOfKind(SyntaxKind.Identifier).filter(
+        (id) => id.getText() === name && id !== named.getNameNode()
+      )
+      if (refs.length === 0) {
+        issues.push({
+          rule: 'dead-code',
+          severity: 'warning',
+          message: `Unused import '${name}'. AI often imports more than it uses.`,
+          line: imp.getStartLineNumber(),
+          column: imp.getStartLinePos(),
+          snippet: getSnippet(imp, file),
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+function detectDuplicateFunctionNames(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const seen = new Map<string, number>()
+
+  const fns = file.getFunctions()
+  for (const fn of fns) {
+    const name = fn.getName()
+    if (!name) continue
+    const normalized = name.toLowerCase().replace(/[_-]/g, '')
+    if (seen.has(normalized)) {
+      issues.push({
+        rule: 'duplicate-function-name',
+        severity: 'error',
+        message: `Function '${name}' looks like a duplicate of a previously defined function. AI often generates near-identical helpers.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    } else {
+      seen.set(normalized, fn.getStartLineNumber())
+    }
+  }
+  return issues
+}
+
+function detectAnyAbuse(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const node of file.getDescendantsOfKind(SyntaxKind.AnyKeyword)) {
+    issues.push({
+      rule: 'any-abuse',
+      severity: 'warning',
+      message: `Explicit 'any' type detected. AI defaults to 'any' when it can't infer types properly.`,
+      line: node.getStartLineNumber(),
+      column: node.getStartLinePos(),
+      snippet: getSnippet(node, file),
+    })
+  }
+  return issues
+}
+
+function detectCatchSwallow(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const tryCatch of file.getDescendantsOfKind(SyntaxKind.TryStatement)) {
+    const catchClause = tryCatch.getCatchClause()
+    if (!catchClause) continue
+    const block = catchClause.getBlock()
+    const stmts = block.getStatements()
+    if (stmts.length === 0) {
+      issues.push({
+        rule: 'catch-swallow',
+        severity: 'warning',
+        message: `Empty catch block silently swallows errors. Classic AI pattern to make code "not throw".`,
+        line: catchClause.getStartLineNumber(),
+        column: catchClause.getStartLinePos(),
+        snippet: getSnippet(catchClause, file),
+      })
+    }
+  }
+  return issues
+}
+
+function detectMissingReturnTypes(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  for (const fn of file.getFunctions()) {
+    if (!fn.getReturnTypeNode()) {
+      issues.push({
+        rule: 'no-return-type',
+        severity: 'info',
+        message: `Function '${fn.getName() ?? 'anonymous'}' has no explicit return type.`,
+        line: fn.getStartLineNumber(),
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+function calculateScore(issues: DriftIssue[]): number {
+  let raw = 0
+  for (const issue of issues) {
+    raw += RULE_WEIGHTS[issue.rule]?.weight ?? 5
+  }
+  return Math.min(100, raw)
+}
+
+export function analyzeFile(file: SourceFile): FileReport {
+  const issues: DriftIssue[] = [
+    ...detectLargeFile(file),
+    ...detectLargeFunctions(file),
+    ...detectDebugLeftovers(file),
+    ...detectDeadCode(file),
+    ...detectDuplicateFunctionNames(file),
+    ...detectAnyAbuse(file),
+    ...detectCatchSwallow(file),
+    ...detectMissingReturnTypes(file),
+  ]
+
+  return {
+    path: file.getFilePath(),
+    issues,
+    score: calculateScore(issues),
+  }
+}
+
+export function analyzeProject(targetPath: string): FileReport[] {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: { allowJs: true },
+  })
+
+  project.addSourceFilesAtPaths([
+    `${targetPath}/**/*.ts`,
+    `${targetPath}/**/*.tsx`,
+    `${targetPath}/**/*.js`,
+    `${targetPath}/**/*.jsx`,
+    `!${targetPath}/**/node_modules/**`,
+    `!${targetPath}/**/dist/**`,
+    `!${targetPath}/**/.next/**`,
+    `!${targetPath}/**/build/**`,
+    `!${targetPath}/**/*.d.ts`,
+    `!${targetPath}/**/*.test.*`,
+    `!${targetPath}/**/*.spec.*`,
+  ])
+
+  return project.getSourceFiles().map(analyzeFile)
+}

package/src/cli.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { analyzeProject } from './analyzer.js'
+import { buildReport, formatMarkdown } from './reporter.js'
+import { printConsole } from './printer.js'
+
+const program = new Command()
+
+program
+  .name('drift')
+  .description('Detect silent technical debt left by AI-generated code')
+  .version('0.1.0')
+
+program
+  .command('scan [path]', { isDefault: true })
+  .description('Scan a directory for vibe coding drift')
+  .option('-o, --output <file>', 'Write report to a Markdown file')
+  .option('--json', 'Output raw JSON report')
+  .option('--min-score <n>', 'Exit with code 1 if overall score exceeds this threshold', '0')
+  .action((targetPath: string | undefined, options: { output?: string; json?: boolean; minScore: string }) => {
+    const resolvedPath = resolve(targetPath ?? '.')
+
+    console.error(`\nScanning ${resolvedPath}...`)
+
+    const files = analyzeProject(resolvedPath)
+    const report = buildReport(resolvedPath, files)
+
+    if (options.json) {
+      process.stdout.write(JSON.stringify(report, null, 2))
+      return
+    }
+
+    printConsole(report)
+
+    if (options.output) {
+      const md = formatMarkdown(report)
+      const outPath = resolve(options.output)
+      writeFileSync(outPath, md, 'utf8')
+      console.error(`Report saved to ${outPath}`)
+    }
+
+    const minScore = Number(options.minScore)
+    if (minScore > 0 && report.totalScore > minScore) {
+      process.exit(1)
+    }
+  })
+
+program.parse()

package/src/index.ts

@@ -0,0 +1,3 @@
+export { analyzeProject, analyzeFile } from './analyzer.js'
+export { buildReport, formatMarkdown } from './reporter.js'
+export type { DriftReport, FileReport, DriftIssue } from './types.js'

package/src/printer.ts

@@ -0,0 +1,86 @@
+import kleur from 'kleur'
+import type { DriftReport, DriftIssue } from './types.js'
+
+export function printConsole(report: DriftReport): void {
+  console.log()
+  console.log(kleur.bold().white('  drift') + kleur.gray(' — vibe coding debt detector'))
+  console.log()
+
+  const grade = scoreToGrade(report.totalScore)
+  const scoreColor = report.totalScore === 0
+    ? kleur.green
+    : report.totalScore < 45
+    ? kleur.yellow
+    : kleur.red
+
+  console.log(
+    `  Score  ${scoreColor().bold(String(report.totalScore).padStart(3))}${kleur.gray('/100')}  ${grade.badge}`
+  )
+  console.log(
+    kleur.gray(
+      `  ${report.files.length} file(s) with issues  ·  ${report.summary.errors} errors  ·  ${report.summary.warnings} warnings  ·  ${report.summary.infos} info`
+    )
+  )
+  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}`) +
+          `  ` +
+          colorFn(issue.rule) +
+          `  ` +
+          kleur.white(issue.message)
+      )
+      if (issue.snippet) {
+        console.log(kleur.gray(`       ${issue.snippet.split('\n')[0].slice(0, 100)}`))
+      }
+    }
+    console.log()
+  }
+
+  // Top drifting rules summary
+  const sorted = Object.entries(report.summary.byRule).sort((a, b) => b[1] - a[1]).slice(0, 3)
+  if (sorted.length > 0) {
+    console.log(kleur.gray('  Top rules:'))
+    for (const [rule, count] of sorted) {
+      console.log(kleur.gray(`    · ${rule}: ${count}`))
+    }
+    console.log()
+  }
+}
+
+function scoreToGrade(score: number): { badge: string } {
+  if (score === 0) return { badge: kleur.green('CLEAN') }
+  if (score < 20) return { badge: kleur.green('LOW') }
+  if (score < 45) return { badge: kleur.yellow('MODERATE') }
+  if (score < 70) return { badge: kleur.red('HIGH') }
+  return { badge: kleur.bold().red('CRITICAL') }
+}
+
+function severityIcon(s: DriftIssue['severity']): string {
+  if (s === 'error') return '✖'
+  if (s === 'warning') return '▲'
+  return '◦'
+}

package/src/reporter.ts

@@ -0,0 +1,97 @@
+import type { FileReport, DriftReport, DriftIssue } from './types.js'
+
+export function buildReport(targetPath: string, files: FileReport[]): DriftReport {
+  const allIssues = files.flatMap((f) => f.issues)
+  const byRule: Record<string, number> = {}
+
+  for (const issue of allIssues) {
+    byRule[issue.rule] = (byRule[issue.rule] ?? 0) + 1
+  }
+
+  const totalScore =
+    files.length > 0
+      ? Math.round(files.reduce((sum, f) => sum + f.score, 0) / files.length)
+      : 0
+
+  return {
+    scannedAt: new Date().toISOString(),
+    targetPath,
+    files: files.filter((f) => f.issues.length > 0).sort((a, b) => b.score - a.score),
+    totalIssues: allIssues.length,
+    totalScore,
+    summary: {
+      errors: allIssues.filter((i) => i.severity === 'error').length,
+      warnings: allIssues.filter((i) => i.severity === 'warning').length,
+      infos: allIssues.filter((i) => i.severity === 'info').length,
+      byRule,
+    },
+  }
+}
+
+export function formatMarkdown(report: DriftReport): string {
+  const grade = scoreToGrade(report.totalScore)
+  const lines: string[] = []
+
+  lines.push(`# drift report`)
+  lines.push(``)
+  lines.push(`> Generated: ${new Date(report.scannedAt).toLocaleString()}`)
+  lines.push(`> Path: \`${report.targetPath}\``)
+  lines.push(``)
+  lines.push(`## Overall drift score: ${report.totalScore}/100 ${grade.badge}`)
+  lines.push(``)
+  lines.push(`| | Count |`)
+  lines.push(`|---|---|`)
+  lines.push(`| Errors | ${report.summary.errors} |`)
+  lines.push(`| Warnings | ${report.summary.warnings} |`)
+  lines.push(`| Info | ${report.summary.infos} |`)
+  lines.push(`| Files with issues | ${report.files.length} |`)
+  lines.push(`| Total issues | ${report.totalIssues} |`)
+  lines.push(``)
+
+  if (Object.keys(report.summary.byRule).length > 0) {
+    lines.push(`## Issues by rule`)
+    lines.push(``)
+    const sorted = Object.entries(report.summary.byRule).sort((a, b) => b[1] - a[1])
+    for (const [rule, count] of sorted) {
+      lines.push(`- \`${rule}\`: ${count}`)
+    }
+    lines.push(``)
+  }
+
+  if (report.files.length === 0) {
+    lines.push(`## No drift detected`)
+    lines.push(``)
+    lines.push(`No issues found. Clean codebase.`)
+  } else {
+    lines.push(`## Files (sorted by drift score)`)
+    lines.push(``)
+    for (const file of report.files) {
+      lines.push(`### \`${file.path}\` — score ${file.score}/100`)
+      lines.push(``)
+      for (const issue of file.issues) {
+        const icon = severityIcon(issue.severity)
+        lines.push(`**${icon} [${issue.rule}]** Line ${issue.line}: ${issue.message}`)
+        lines.push(`\`\`\``)
+        lines.push(issue.snippet)
+        lines.push(`\`\`\``)
+        lines.push(``)
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function scoreToGrade(score: number): { badge: string; label: string } {
+  if (score === 0) return { badge: '✦ CLEAN', label: 'clean' }
+  if (score < 20) return { badge: '◎ LOW', label: 'low' }
+  if (score < 45) return { badge: '◈ MODERATE', label: 'moderate' }
+  if (score < 70) return { badge: '◉ HIGH', label: 'high' }
+  return { badge: '⬡ CRITICAL', label: 'critical' }
+}
+
+function severityIcon(s: DriftIssue['severity']): string {
+  if (s === 'error') return '✖'
+  if (s === 'warning') return '▲'
+  return '◦'
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export interface DriftIssue {
+  rule: string
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  line: number
+  column: number
+  snippet: string
+}
+
+export interface FileReport {
+  path: string
+  issues: DriftIssue[]
+  score: number // 0–100, higher = more drift
+}
+
+export interface DriftReport {
+  scannedAt: string
+  targetPath: string
+  files: FileReport[]
+  totalIssues: number
+  totalScore: number
+  summary: {
+    errors: number
+    warnings: number
+    infos: number
+    byRule: Record<string, number>
+  }
+}