@eduardbar/drift 1.0.0 → 1.2.0

package/src/reporter.ts

@@ -1,5 +1,6 @@
 import type { FileReport, DriftReport, DriftIssue, AIOutput, AIIssue } from './types.js'
 import { scoreToGradeText, severityIcon } from './utils.js'
+import { computeRepoQuality, computeMaintenanceRisk } from './metrics.js'
 
 const FIX_SUGGESTIONS: Record<string, string> = {
   'large-file': 'Consider splitting this file into smaller modules with single responsibility',
@@ -25,6 +26,17 @@ const RULE_EFFORT: Record<string, 'low' | 'medium' | 'high'> = {
 
 const SEVERITY_ORDER: Record<string, number> = { error: 0, warning: 1, info: 2 }
 const EFFORT_ORDER: Record<string, number> = { low: 0, medium: 1, high: 2 }
+const AI_SIGNAL_RULES = new Set([
+  'over-commented',
+  'hardcoded-config',
+  'inconsistent-error-handling',
+  'unnecessary-abstraction',
+  'naming-inconsistency',
+  'comment-contradiction',
+  'promise-style-mix',
+  'any-abuse',
+  'ai-code-smell',
+])
 
 export function buildReport(targetPath: string, files: FileReport[]): DriftReport {
   const allIssues = files.flatMap((f) => f.issues)
@@ -39,10 +51,12 @@ export function buildReport(targetPath: string, files: FileReport[]): DriftRepor
       ? Math.round(files.reduce((sum, f) => sum + f.score, 0) / files.length)
       : 0
 
-  return {
+  const sortedFiles = files.filter((f) => f.issues.length > 0).sort((a, b) => b.score - a.score)
+
+  const baseReport: DriftReport = {
     scannedAt: new Date().toISOString(),
     targetPath,
-    files: files.filter((f) => f.issues.length > 0).sort((a, b) => b.score - a.score),
+    files: sortedFiles,
     totalIssues: allIssues.length,
     totalScore,
     totalFiles: files.length,
@@ -52,7 +66,31 @@ export function buildReport(targetPath: string, files: FileReport[]): DriftRepor
       infos: allIssues.filter((i) => i.severity === 'info').length,
       byRule,
     },
+    quality: {
+      overall: 100,
+      dimensions: {
+        architecture: 100,
+        complexity: 100,
+        'ai-patterns': 100,
+        testing: 100,
+      },
+    },
+    maintenanceRisk: {
+      score: 0,
+      level: 'low',
+      hotspots: [],
+      signals: {
+        highComplexityFiles: 0,
+        filesWithoutNearbyTests: 0,
+        frequentChangeFiles: 0,
+      },
+    },
   }
+
+  baseReport.quality = computeRepoQuality(targetPath, files)
+  baseReport.maintenanceRisk = computeMaintenanceRisk(baseReport)
+
+  return baseReport
 }
 
 function formatHeader(report: DriftReport, grade: { badge: string }): string[] {
@@ -163,12 +201,62 @@ function buildRecommendedAction(priorityOrder: AIIssue[]): string {
   return 'Start with the highest priority issue and work through them in order.'
 }
 
+function fileAILikelihood(fileIssues: DriftIssue[]): { score: number; triggers: string[] } {
+  if (fileIssues.length === 0) return { score: 0, triggers: [] }
+  const triggerCounts = new Map<string, number>()
+  for (const issue of fileIssues) {
+    if (!AI_SIGNAL_RULES.has(issue.rule)) continue
+    triggerCounts.set(issue.rule, (triggerCounts.get(issue.rule) ?? 0) + 1)
+  }
+  const triggerTotal = [...triggerCounts.values()].reduce((sum, count) => sum + count, 0)
+  const smellBoost = fileIssues.some((issue) => issue.rule === 'ai-code-smell') ? 20 : 0
+  const ratioScore = Math.round((triggerTotal / Math.max(fileIssues.length, 1)) * 100)
+  const score = Math.max(0, Math.min(100, ratioScore + smellBoost))
+  const triggers = [...triggerCounts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 4)
+    .map(([rule]) => rule)
+  return { score, triggers }
+}
+
+function computeAILikelihood(report: DriftReport): {
+  overall: number
+  files: Array<{ path: string; ai_likelihood: number; triggers: string[] }>
+  smellScore: number
+} {
+  const suspected = report.files
+    .map((file) => {
+      const likelihood = fileAILikelihood(file.issues)
+      return {
+        path: file.path,
+        ai_likelihood: likelihood.score,
+        triggers: likelihood.triggers,
+      }
+    })
+    .filter((entry) => entry.ai_likelihood >= 35)
+    .sort((a, b) => b.ai_likelihood - a.ai_likelihood)
+
+  const overall = suspected.length === 0
+    ? 0
+    : Math.round(suspected.reduce((sum, entry) => sum + entry.ai_likelihood, 0) / suspected.length)
+
+  const smellCount = report.files.flatMap((file) => file.issues).filter((issue) => issue.rule === 'ai-code-smell').length
+  const smellScore = Math.min(100, smellCount * 15)
+
+  return {
+    overall,
+    files: suspected.slice(0, 10),
+    smellScore,
+  }
+}
+
 export function formatAIOutput(report: DriftReport): AIOutput {
   const allIssues = collectAllIssues(report)
   const sortedIssues = sortIssues(allIssues)
   const priorityOrder = sortedIssues.map((item, i) => buildAIIssue(item, i + 1))
   const rulesDetected = [...new Set(allIssues.map((i) => i.issue.rule))]
   const grade = scoreToGradeText(report.totalScore)
+  const aiLikelihood = computeAILikelihood(report)
 
   return {
     summary: {
@@ -177,8 +265,13 @@ export function formatAIOutput(report: DriftReport): AIOutput {
       total_issues: report.totalIssues,
       files_affected: report.files.length,
       files_clean: report.totalFiles - report.files.length,
+      ai_likelihood: aiLikelihood.overall,
+      ai_code_smell_score: aiLikelihood.smellScore,
     },
+    files_suspected: aiLikelihood.files,
     priority_order: priorityOrder,
+    maintenance_risk: report.maintenanceRisk,
+    quality: report.quality,
     context_for_ai: {
       project_type: 'typescript',
       scan_path: report.targetPath,

package/src/review.ts

@@ -0,0 +1,98 @@
+import { resolve } from 'node:path'
+import { analyzeProject } from './analyzer.js'
+import { loadConfig } from './config.js'
+import { buildReport } from './reporter.js'
+import { cleanupTempDir, extractFilesAtRef } from './git.js'
+import { computeDiff } from './diff.js'
+import type { DriftDiff } from './types.js'
+
+export interface DriftReview {
+  baseRef: string
+  scannedAt: string
+  totalDelta: number
+  newIssues: number
+  resolvedIssues: number
+  status: 'clean' | 'improved' | 'regressed'
+  summary: string
+  markdown: string
+  diff: DriftDiff
+}
+
+export function formatReviewMarkdown(review: DriftReview): string {
+  const trendIcon = review.status === 'regressed' ? '⚠️' : review.status === 'improved' ? '✅' : 'ℹ️'
+  const topFiles = review.diff.files
+    .slice(0, 8)
+    .map((file) => {
+      const sign = file.scoreDelta > 0 ? '+' : ''
+      return `- \`${file.path}\`: ${file.scoreBefore} -> ${file.scoreAfter} (${sign}${file.scoreDelta}), +${file.newIssues.length} new / -${file.resolvedIssues.length} resolved`
+    })
+    .join('\n')
+
+  return [
+    '## drift review',
+    '',
+    `${trendIcon} ${review.summary}`,
+    '',
+    `- Base ref: \`${review.baseRef}\``,
+    `- Score delta: **${review.totalDelta >= 0 ? '+' : ''}${review.totalDelta}**`,
+    `- New issues: **${review.newIssues}**`,
+    `- Resolved issues: **${review.resolvedIssues}**`,
+    '',
+    '### File breakdown',
+    topFiles || '- No file-level deltas detected',
+  ].join('\n')
+}
+
+function getStatus(totalDelta: number, newIssues: number): 'clean' | 'improved' | 'regressed' {
+  if (totalDelta > 0 || newIssues > 0) return 'regressed'
+  if (totalDelta < 0) return 'improved'
+  return 'clean'
+}
+
+export async function generateReview(projectPath: string, baseRef: string): Promise<DriftReview> {
+  const resolvedPath = resolve(projectPath)
+  const config = await loadConfig(resolvedPath)
+
+  const currentFiles = analyzeProject(resolvedPath, config)
+  const currentReport = buildReport(resolvedPath, currentFiles)
+
+  let tempDir: string | undefined
+  try {
+    tempDir = extractFilesAtRef(resolvedPath, baseRef)
+    const baseFiles = analyzeProject(tempDir, config)
+    const baseReport = buildReport(tempDir, baseFiles)
+
+    const remappedBase = {
+      ...baseReport,
+      files: baseReport.files.map((file) => ({
+        ...file,
+        path: file.path.replace(tempDir!, resolvedPath),
+      })),
+    }
+
+    const diff = computeDiff(remappedBase, currentReport, baseRef)
+    const status = getStatus(diff.totalDelta, diff.newIssuesCount)
+    const summary = status === 'regressed'
+      ? `Drift regressed: +${diff.totalDelta} score and ${diff.newIssuesCount} new issue(s).`
+      : status === 'improved'
+        ? `Drift improved: ${diff.totalDelta} score delta and ${diff.resolvedIssuesCount} issue(s) resolved.`
+        : 'No drift changes detected against base ref.'
+
+    const review: DriftReview = {
+      baseRef,
+      scannedAt: new Date().toISOString(),
+      totalDelta: diff.totalDelta,
+      newIssues: diff.newIssuesCount,
+      resolvedIssues: diff.resolvedIssuesCount,
+      status,
+      summary,
+      markdown: '',
+      diff,
+    }
+
+    review.markdown = formatReviewMarkdown(review)
+    return review
+  } finally {
+    if (tempDir) cleanupTempDir(tempDir)
+  }
+}

package/src/rules/comments.ts

@@ -0,0 +1,56 @@
+import { SourceFile } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment } from './shared.js'
+
+const TRIVIAL_COMMENT_PATTERNS = [
+  { comment: /\/\/\s*return\b/i, code: /^\s*return\b/ },
+  { comment: /\/\/\s*(increment|increase|add\s+1|plus\s+1)\b/i, code: /\+\+|(\+= ?1)\b/ },
+  { comment: /\/\/\s*(decrement|decrease|subtract\s+1|minus\s+1)\b/i, code: /--|(-= ?1)\b/ },
+  { comment: /\/\/\s*log\b/i, code: /console\.(log|warn|error)/ },
+  { comment: /\/\/\s*(set|assign)\b/i, code: /^\s*\w[\w.[\]]*\s*=(?!=)/ },
+  { comment: /\/\/\s*call\b/i, code: /^\s*\w[\w.]*\(/ },
+  { comment: /\/\/\s*(declare|define|create|initialize)\b/i, code: /^\s*(const|let|var)\b/ },
+  { comment: /\/\/\s*check\s+if\b/i, code: /^\s*if\s*\(/ },
+  { comment: /\/\/\s*(loop|iterate|for each|foreach)\b/i, code: /^\s*(for|while)\b/ },
+  { comment: /\/\/\s*import\b/i, code: /^\s*import\b/ },
+]
+
+const SNIPPET_TRUNCATE = 60
+
+function checkLineForContradiction(
+  commentLine: string,
+  nextLine: string,
+  lineNumber: number,
+  file: SourceFile,
+): DriftIssue | null {
+  for (const { comment, code } of TRIVIAL_COMMENT_PATTERNS) {
+    if (comment.test(commentLine) && code.test(nextLine)) {
+      if (hasIgnoreComment(file, lineNumber)) return null
+      return {
+        rule: 'comment-contradiction',
+        severity: 'warning',
+        message: `Comment restates what the code already says. AI documents the obvious instead of the why.`,
+        line: lineNumber,
+        column: 1,
+        snippet: `${commentLine.slice(0, SNIPPET_TRUNCATE)}\n${nextLine.trim().slice(0, SNIPPET_TRUNCATE)}`,
+      }
+    }
+  }
+  return null
+}
+
+export function detectCommentContradiction(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+  const lines = file.getFullText().split('\n')
+
+  for (let i = 0; i < lines.length - 1; i++) {
+    const commentLine = lines[i].trim()
+    const nextLine = lines[i + 1]
+    const issue = checkLineForContradiction(commentLine, nextLine, i + 1, file)
+    if (issue) {
+      issues.push(issue)
+    }
+  }
+
+  return issues
+}

package/src/rules/complexity.ts

@@ -0,0 +1,57 @@
+import { SourceFile, SyntaxKind } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment, getSnippet, type FunctionLike } from './shared.js'
+
+const COMPLEXITY_THRESHOLD = 10
+
+const INCREMENT_KINDS = [
+  SyntaxKind.IfStatement,
+  SyntaxKind.ForStatement,
+  SyntaxKind.ForInStatement,
+  SyntaxKind.ForOfStatement,
+  SyntaxKind.WhileStatement,
+  SyntaxKind.DoStatement,
+  SyntaxKind.CaseClause,
+  SyntaxKind.CatchClause,
+  SyntaxKind.ConditionalExpression,
+  SyntaxKind.AmpersandAmpersandToken,
+  SyntaxKind.BarBarToken,
+  SyntaxKind.QuestionQuestionToken,
+]
+
+function getCyclomaticComplexity(fn: FunctionLike): number {
+  let complexity = 1
+
+  for (const kind of INCREMENT_KINDS) {
+    complexity += fn.getDescendantsOfKind(kind).length
+  }
+
+  return complexity
+}
+
+export function detectHighComplexity(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 complexity = getCyclomaticComplexity(fn)
+    if (complexity > COMPLEXITY_THRESHOLD) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'high-complexity',
+        severity: 'error',
+        message: `Cyclomatic complexity is ${complexity} (threshold: ${COMPLEXITY_THRESHOLD}). AI generates correct code, not simple code.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}

package/src/rules/coupling.ts

@@ -0,0 +1,23 @@
+import { SourceFile } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+
+const COUPLING_THRESHOLD = 10
+
+export function detectHighCoupling(file: SourceFile): DriftIssue[] {
+  const imports = file.getImportDeclarations()
+  const sources = new Set(imports.map((i) => i.getModuleSpecifierValue()))
+
+  if (sources.size > COUPLING_THRESHOLD) {
+    return [
+      {
+        rule: 'high-coupling',
+        severity: 'warning',
+        message: `File imports from ${sources.size} distinct modules (threshold: ${COUPLING_THRESHOLD}). High coupling makes refactoring dangerous.`,
+        line: 1,
+        column: 1,
+        snippet: `// ${sources.size} import sources`,
+      },
+    ]
+  }
+  return []
+}

package/src/rules/magic.ts

@@ -0,0 +1,38 @@
+import { SourceFile, SyntaxKind } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment, getSnippet } from './shared.js'
+
+const ALLOWED_NUMBERS = new Set([0, 1, -1, 2, 100])
+
+export function detectMagicNumbers(file: SourceFile): DriftIssue[] {
+  const issues: DriftIssue[] = []
+
+  for (const node of file.getDescendantsOfKind(SyntaxKind.NumericLiteral)) {
+    const value = Number(node.getLiteralValue())
+    if (ALLOWED_NUMBERS.has(value)) continue
+
+    const parent = node.getParent()
+    if (!parent) continue
+
+    const parentKind = parent.getKind()
+    if (
+      parentKind === SyntaxKind.VariableDeclaration ||
+      parentKind === SyntaxKind.PropertyAssignment ||
+      parentKind === SyntaxKind.EnumMember ||
+      parentKind === SyntaxKind.Parameter
+    ) continue
+
+    const line = node.getStartLineNumber()
+    if (hasIgnoreComment(file, line)) continue
+
+    issues.push({
+      rule: 'magic-number',
+      severity: 'info',
+      message: `Magic number ${value} used directly in logic. Extract to a named constant.`,
+      line,
+      column: node.getStartLinePos(),
+      snippet: getSnippet(node, file),
+    })
+  }
+  return issues
+}

package/src/rules/nesting.ts

@@ -0,0 +1,88 @@
+import { SourceFile, SyntaxKind, Node } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+import { hasIgnoreComment, getSnippet, type FunctionLike } from './shared.js'
+
+const NESTING_THRESHOLD = 3
+const PARAMS_THRESHOLD = 4
+
+const NESTING_KINDS = new Set([
+  SyntaxKind.IfStatement,
+  SyntaxKind.ForStatement,
+  SyntaxKind.ForInStatement,
+  SyntaxKind.ForOfStatement,
+  SyntaxKind.WhileStatement,
+  SyntaxKind.DoStatement,
+  SyntaxKind.TryStatement,
+  SyntaxKind.SwitchStatement,
+])
+
+function getMaxNestingDepth(fn: FunctionLike): number {
+  let maxDepth = 0
+
+  function walk(node: Node, depth: number): void {
+    if (NESTING_KINDS.has(node.getKind())) {
+      depth++
+      if (depth > maxDepth) maxDepth = depth
+    }
+    for (const child of node.getChildren()) {
+      walk(child, depth)
+    }
+  }
+
+  walk(fn, 0)
+  return maxDepth
+}
+
+export function detectDeepNesting(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 depth = getMaxNestingDepth(fn)
+    if (depth > NESTING_THRESHOLD) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'deep-nesting',
+        severity: 'warning',
+        message: `Maximum nesting depth is ${depth} (threshold: ${NESTING_THRESHOLD}). Deep nesting is the #1 readability killer.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}
+
+export function detectTooManyParams(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 paramCount = fn.getParameters().length
+    if (paramCount > PARAMS_THRESHOLD) {
+      const startLine = fn.getStartLineNumber()
+      if (hasIgnoreComment(file, startLine)) continue
+      issues.push({
+        rule: 'too-many-params',
+        severity: 'warning',
+        message: `Function has ${paramCount} parameters (threshold: ${PARAMS_THRESHOLD}). AI avoids refactoring into options objects.`,
+        line: startLine,
+        column: fn.getStartLinePos(),
+        snippet: getSnippet(fn, file),
+      })
+    }
+  }
+  return issues
+}

package/src/rules/phase0-basic.ts

@@ -2,14 +2,19 @@ import { SourceFile, SyntaxKind } from 'ts-morph'
 import type { DriftIssue } from '../types.js'
 import { hasIgnoreComment, getSnippet, getFunctionLikeLines, type FunctionLike } from './shared.js'
 
+const LARGE_FILE_THRESHOLD = 300
+const LARGE_FUNCTION_THRESHOLD = 50
+const SNIPPET_TRUNCATE_SHORT = 60
+const SNIPPET_TRUNCATE_LONG = 120
+
 export function detectLargeFile(file: SourceFile): DriftIssue[] {
   const lineCount = file.getEndLineNumber()
-  if (lineCount > 300) {
+  if (lineCount > LARGE_FILE_THRESHOLD) {
     return [
       {
         rule: 'large-file',
         severity: 'error',
-        message: `File has ${lineCount} lines (threshold: 300). Large files are the #1 sign of AI-generated structural drift.`,
+        message: `File has ${lineCount} lines (threshold: ${LARGE_FILE_THRESHOLD}). Large files are the #1 sign of AI-generated structural drift.`,
         line: 1,
         column: 1,
         snippet: `// ${lineCount} lines total`,
@@ -31,12 +36,12 @@ export function detectLargeFunctions(file: SourceFile): DriftIssue[] {
   for (const fn of fns) {
     const lines = getFunctionLikeLines(fn)
     const startLine = fn.getStartLineNumber()
-    if (lines > 50) {
+    if (lines > LARGE_FUNCTION_THRESHOLD) {
       if (hasIgnoreComment(file, startLine)) continue
       issues.push({
         rule: 'large-function',
         severity: 'error',
-        message: `Function spans ${lines} lines (threshold: 50). AI tends to dump logic into single functions.`,
+        message: `Function spans ${lines} lines (threshold: ${LARGE_FUNCTION_THRESHOLD}). AI tends to dump logic into single functions.`,
         line: startLine,
         column: fn.getStartLinePos(),
         snippet: getSnippet(fn, file),
@@ -72,10 +77,10 @@ export function detectDebugLeftovers(file: SourceFile): DriftIssue[] {
       issues.push({
         rule: 'debug-leftover',
         severity: 'warning',
-        message: `Unresolved marker found: ${lineContent.trim().slice(0, 60)}`,
+        message: `Unresolved marker found: ${lineContent.trim().slice(0, SNIPPET_TRUNCATE_SHORT)}`,
         line: i + 1,
         column: 1,
-        snippet: lineContent.trim().slice(0, 120),
+        snippet: lineContent.trim().slice(0, SNIPPET_TRUNCATE_LONG),
       })
     }
   })
@@ -156,11 +161,13 @@ export function detectCatchSwallow(file: SourceFile): DriftIssue[] {
     const block = catchClause.getBlock()
     const stmts = block.getStatements()
     if (stmts.length === 0) {
+      const line = catchClause.getStartLineNumber()
+      if (hasIgnoreComment(file, line)) continue
       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(),
+        line,
         column: catchClause.getStartLinePos(),
         snippet: getSnippet(catchClause, file),
       })