@eduardbar/drift 0.9.1 → 1.1.0

package/src/rules/phase5-ai.ts

@@ -0,0 +1,292 @@
+// drift-ignore-file
+import { SourceFile, SyntaxKind } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+
+export 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
+}
+
+export 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
+}
+
+export 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
+}
+
+export 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
+}
+
+export 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
+}

package/src/rules/phase8-semantic.ts

@@ -0,0 +1,136 @@
+// drift-ignore-file
+
+import * as crypto from 'node:crypto'
+import {
+  SourceFile,
+  SyntaxKind,
+  Node,
+  FunctionDeclaration,
+  ArrowFunction,
+  FunctionExpression,
+  MethodDeclaration,
+} from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+
+export type FunctionLikeNode = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
+
+/** Normalize a function body to a canonical string (Type-2 clone detection).
+ *  Variable names, parameter names, and numeric/string literals are replaced
+ *  with canonical tokens so that two functions with identical logic but
+ *  different identifiers produce the same fingerprint.
+ */
+function buildSubstitutionMap(fn: FunctionLikeNode): Map<string, string> {
+  const subst = new Map<string, string>()
+
+  for (const [i, param] of fn.getParameters().entries()) {
+    const name = param.getName()
+    if (name && name !== '_') subst.set(name, `P${i}`)
+  }
+
+  let varIdx = 0
+  fn.forEachDescendant(node => {
+    if (node.getKind() === SyntaxKind.VariableDeclaration) {
+      const nameNode = (node as import('ts-morph').VariableDeclaration).getNameNode()
+      if (nameNode.getKind() === SyntaxKind.Identifier) {
+        const name = nameNode.getText()
+        if (!subst.has(name)) subst.set(name, `V${varIdx++}`)
+      }
+    }
+  })
+
+  return subst
+}
+
+function serializeNode(node: Node, subst: Map<string, string>): string {
+  const kind = node.getKindName()
+
+  switch (node.getKind()) {
+    case SyntaxKind.Identifier: {
+      const text = node.getText()
+      return subst.get(text) ?? text
+    }
+    case SyntaxKind.NumericLiteral:
+      return 'NL'
+    case SyntaxKind.StringLiteral:
+    case SyntaxKind.NoSubstitutionTemplateLiteral:
+      return 'SL'
+    case SyntaxKind.TrueKeyword:
+      return 'TRUE'
+    case SyntaxKind.FalseKeyword:
+      return 'FALSE'
+    case SyntaxKind.NullKeyword:
+      return 'NULL'
+  }
+
+  const children = node.getChildren()
+  if (children.length === 0) return kind
+
+  const childStr = children.map(c => serializeNode(c, subst)).join('|')
+  return `${kind}(${childStr})`
+}
+
+export function normalizeFunctionBody(fn: FunctionLikeNode): string {
+  const subst = buildSubstitutionMap(fn)
+
+  const body = fn.getBody()
+  if (!body) return ''
+  return serializeNode(body, subst)
+}
+
+/** Return a SHA-256 fingerprint for a function body (normalized). */
+export function fingerprintFunction(fn: FunctionLikeNode): string {
+  const normalized = normalizeFunctionBody(fn)
+  return crypto.createHash('sha256').update(normalized).digest('hex')
+}
+
+/** Return all function-like nodes from a SourceFile that are worth comparing:
+ *  - At least MIN_LINES lines in their body
+ *  - Not test helpers (describe/it/test/beforeEach/afterEach)
+ */
+const MIN_LINES = 8
+
+export function collectFunctions(sf: SourceFile): Array<{ fn: FunctionLikeNode; name: string; line: number; col: number }> {
+  const results: Array<{ fn: FunctionLikeNode; name: string; line: number; col: number }> = []
+
+  const kinds = [
+    SyntaxKind.FunctionDeclaration,
+    SyntaxKind.FunctionExpression,
+    SyntaxKind.ArrowFunction,
+    SyntaxKind.MethodDeclaration,
+  ] as const
+
+  for (const kind of kinds) {
+    for (const node of sf.getDescendantsOfKind(kind)) {
+      const body = (node as FunctionLikeNode).getBody()
+      if (!body) continue
+
+      const start = body.getStartLineNumber()
+      const end = body.getEndLineNumber()
+      if (end - start + 1 < MIN_LINES) continue
+
+      // Skip test-framework helpers
+      const name = node.getKind() === SyntaxKind.FunctionDeclaration
+        ? (node as FunctionDeclaration).getName() ?? '<anonymous>'
+        : node.getKind() === SyntaxKind.MethodDeclaration
+          ? (node as MethodDeclaration).getName()
+          : '<anonymous>'
+
+      if (['describe', 'it', 'test', 'beforeEach', 'afterEach', 'beforeAll', 'afterAll'].includes(name)) continue
+
+      const pos = node.getStart()
+      const lineInfo = sf.getLineAndColumnAtPos(pos)
+
+      results.push({ fn: node as FunctionLikeNode, name, line: lineInfo.line, col: lineInfo.column })
+    }
+  }
+
+  return results
+}
+
+export function calculateScore(issues: DriftIssue[], ruleWeights: Record<string, { severity: DriftIssue['severity']; weight: number }>): number {
+  let raw = 0
+  for (const issue of issues) {
+    raw += ruleWeights[issue.rule]?.weight ?? 5
+  }
+  return Math.min(100, raw)
+}

package/src/rules/promise.ts

@@ -0,0 +1,29 @@
+import { SourceFile, SyntaxKind } from 'ts-morph'
+import type { DriftIssue } from '../types.js'
+
+export function detectPromiseStyleMix(file: SourceFile): DriftIssue[] {
+  const text = file.getFullText()
+
+  const hasThen = file.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression).some((node) => {
+    const name = node.getName()
+    return name === 'then' || name === 'catch'
+  })
+
+  const hasAsync =
+    file.getDescendantsOfKind(SyntaxKind.AsyncKeyword).length > 0 ||
+    /\bawait\b/.test(text)
+
+  if (hasThen && hasAsync) {
+    return [
+      {
+        rule: 'promise-style-mix',
+        severity: 'warning',
+        message: `File mixes async/await with .then()/.catch(). AI generates both styles without picking one.`,
+        line: 1,
+        column: 1,
+        snippet: `// mixed promise styles detected`,
+      },
+    ]
+  }
+  return []
+}

package/src/rules/shared.ts

@@ -0,0 +1,39 @@
+import {
+  SourceFile,
+  Node,
+  FunctionDeclaration,
+  ArrowFunction,
+  FunctionExpression,
+  MethodDeclaration,
+} from 'ts-morph'
+
+export type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
+
+export function hasIgnoreComment(file: SourceFile, line: number): boolean {
+  const lines = file.getFullText().split('\n')
+  const currentLine = lines[line - 1] ?? ''
+  const prevLine = lines[line - 2] ?? ''
+
+  if (/\/\/\s*drift-ignore\b/.test(currentLine)) return true
+  if (/\/\/\s*drift-ignore\b/.test(prevLine)) return true
+  return false
+}
+
+export function isFileIgnored(file: SourceFile): boolean {
+  const firstLines = file.getFullText().split('\n').slice(0, 10).join('\n') // drift-ignore
+  return /\/\/\s*drift-ignore-file\b/.test(firstLines)
+}
+
+export 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) // drift-ignore
+}
+
+export function getFunctionLikeLines(node: FunctionLike): number {
+  return node.getEndLineNumber() - node.getStartLineNumber()
+}

package/src/snapshot.ts

@@ -0,0 +1,175 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import kleur from 'kleur'
+import type { DriftReport } from './types.js'
+import { scoreToGradeText } from './utils.js'
+
+export interface SnapshotEntry {
+  timestamp: string
+  label: string
+  score: number
+  grade: string
+  totalIssues: number
+  files: number
+  byRule: Record<string, number>
+}
+
+export interface SnapshotHistory {
+  project: string
+  snapshots: SnapshotEntry[]
+}
+
+const HISTORY_FILE = 'drift-history.json'
+
+const HEADER_PAD = {
+  INDEX: 4,
+  DATE: 26,
+  LABEL: 20,
+  SCORE: 8,
+  GRADE: 12,
+  ISSUES: 8,
+  DELTA: 6,
+}
+
+const GRADE_THRESHOLDS = {
+  LOW: 20,
+  MODERATE: 45,
+  HIGH: 70,
+}
+
+export function loadHistory(targetPath: string): SnapshotHistory {
+  const filePath = path.join(targetPath, HISTORY_FILE)
+  if (fs.existsSync(filePath)) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8')) as SnapshotHistory
+  }
+  return { project: targetPath, snapshots: [] }
+}
+
+export function saveSnapshot(
+  targetPath: string,
+  report: DriftReport,
+  label?: string,
+): SnapshotEntry {
+  const history = loadHistory(targetPath)
+
+  const entry: SnapshotEntry = {
+    timestamp: new Date().toISOString(),
+    label: label ?? '',
+    score: report.totalScore,
+    grade: scoreToGradeText(report.totalScore).label.toUpperCase(),
+    totalIssues: report.totalIssues,
+    files: report.totalFiles,
+    byRule: { ...report.summary.byRule },
+  }
+
+  history.snapshots.push(entry)
+
+  const filePath = path.join(targetPath, HISTORY_FILE)
+  fs.writeFileSync(filePath, JSON.stringify(history, null, 2), 'utf8')
+
+  return entry
+}
+
+function formatDelta(current: SnapshotEntry, prev: SnapshotEntry | null): string {
+  if (!prev) return '—'
+  const delta = current.score - prev.score
+  if (delta > 0) return kleur.red(`+${delta}`)
+  if (delta < 0) return kleur.green(String(delta))
+  return kleur.gray('0')
+}
+
+export function printHistory(history: SnapshotHistory): void {
+  const { snapshots } = history
+
+  if (snapshots.length === 0) {
+    process.stdout.write('\n  No snapshots recorded yet.\n\n')
+    return
+  }
+
+  process.stdout.write('\n')
+  process.stdout.write(
+    kleur.bold(
+      `  ${'#'.padEnd(HEADER_PAD.INDEX)} ${'Date'.padEnd(HEADER_PAD.DATE)} ${'Label'.padEnd(HEADER_PAD.LABEL)} ${'Score'.padEnd(HEADER_PAD.SCORE)} ${'Grade'.padEnd(HEADER_PAD.GRADE)} ${'Issues'.padEnd(HEADER_PAD.ISSUES)} ${'Delta'}\n`,
+    ),
+  )
+  process.stdout.write(
+    `  ${'─'.repeat(HEADER_PAD.INDEX)} ${'─'.repeat(HEADER_PAD.DATE)} ${'─'.repeat(HEADER_PAD.LABEL)} ${'─'.repeat(HEADER_PAD.SCORE)} ${'─'.repeat(HEADER_PAD.GRADE)} ${'─'.repeat(HEADER_PAD.ISSUES)} ${'─'.repeat(HEADER_PAD.DELTA)}\n`,
+  )
+
+  for (let i = 0; i < snapshots.length; i++) {
+    const s = snapshots[i]
+    const date = new Date(s.timestamp).toLocaleString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+    })
+
+    const deltaStr = formatDelta(s, i > 0 ? snapshots[i - 1] : null)
+    const gradeColored = colorGrade(s.grade, s.score)
+
+    process.stdout.write(
+      `  ${String(i + 1).padEnd(HEADER_PAD.INDEX)} ${date.padEnd(HEADER_PAD.DATE)} ${(s.label || '—').padEnd(HEADER_PAD.LABEL)} ${String(s.score).padEnd(HEADER_PAD.SCORE)} ${gradeColored.padEnd(HEADER_PAD.GRADE)} ${String(s.totalIssues).padEnd(HEADER_PAD.ISSUES)} ${deltaStr}\n`,
+    )
+  }
+
+  process.stdout.write('\n')
+}
+
+export function printSnapshotDiff(
+  history: SnapshotHistory,
+  currentScore: number,
+): void {
+  const { snapshots } = history
+
+  if (snapshots.length === 0) {
+    process.stdout.write('\n  No previous snapshot to compare against.\n\n')
+    return
+  }
+
+  const last = snapshots[snapshots.length - 1]
+  const delta = currentScore - last.score
+
+  const lastDate = new Date(last.timestamp).toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+  const lastLabel = last.label ? ` (${last.label})` : ''
+
+  process.stdout.write('\n')
+  process.stdout.write(
+    `  Last snapshot: ${kleur.bold(lastDate)}${lastLabel} — score ${kleur.bold(String(last.score))}\n`,
+  )
+  process.stdout.write(
+    `  Current score: ${kleur.bold(String(currentScore))}\n`,
+  )
+  process.stdout.write('\n')
+
+  if (delta > 0) {
+    process.stdout.write(
+      `  Delta: ${kleur.bold().red(`+${delta}`)} — technical debt increased\n`,
+    )
+  } else if (delta < 0) {
+    process.stdout.write(
+      `  Delta: ${kleur.bold().green(String(delta))} — technical debt decreased\n`,
+    )
+  } else {
+    process.stdout.write(
+      `  Delta: ${kleur.gray('0')} — no change since last snapshot\n`,
+    )
+  }
+
+  process.stdout.write('\n')
+}
+
+function colorGrade(grade: string, score: number): string {
+  if (score === 0) return kleur.green(grade)
+  if (score < GRADE_THRESHOLDS.LOW) return kleur.green(grade)
+  if (score < GRADE_THRESHOLDS.MODERATE) return kleur.yellow(grade)
+  if (score < GRADE_THRESHOLDS.HIGH) return kleur.red(grade)
+  return kleur.bold().red(grade)
+}