@eduardbar/drift 0.6.0 → 0.8.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

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs'
+import * as crypto from 'node:crypto'
 import * as path from 'node:path'
 import {
   Project,
@@ -13,7 +14,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 },
@@ -45,6 +46,8 @@ const RULE_WEIGHTS: Record<string, { severity: DriftIssue['severity']; weight: n
   'inconsistent-error-handling':   { severity: 'warning', weight: 8  },
   'unnecessary-abstraction':       { severity: 'warning', weight: 7  },
   'naming-inconsistency':          { severity: 'warning', weight: 6  },
+  // Phase 8: semantic duplication
+  'semantic-duplication':          { severity: 'warning', weight: 12 },
 }
 
 type FunctionLike = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration
@@ -873,6 +876,123 @@ function calculateScore(issues: DriftIssue[]): number {
   return Math.min(100, raw)
 }
 
+// ---------------------------------------------------------------------------
+// Phase 8: Semantic duplication — AST fingerprinting helpers
+// ---------------------------------------------------------------------------
+
+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 normalizeFunctionBody(fn: FunctionLikeNode): string {
+  // Build a substitution map: localName → canonical token
+  const subst = new Map<string, string>()
+
+  // Map parameters first
+  for (const [i, param] of fn.getParameters().entries()) {
+    const name = param.getName()
+    if (name && name !== '_') subst.set(name, `P${i}`)
+  }
+
+  // Map locally declared variables (VariableDeclaration)
+  let varIdx = 0
+  fn.forEachDescendant(node => {
+    if (node.getKind() === SyntaxKind.VariableDeclaration) {
+      const nameNode = (node as import('ts-morph').VariableDeclaration).getNameNode()
+      // Support destructuring — getNameNode() may be a BindingPattern
+      if (nameNode.getKind() === SyntaxKind.Identifier) {
+        const name = nameNode.getText()
+        if (!subst.has(name)) subst.set(name, `V${varIdx++}`)
+      }
+    }
+  })
+
+  function serializeNode(node: Node): string {
+    const kind = node.getKindName()
+
+    switch (node.getKind()) {
+      case SyntaxKind.Identifier: {
+        const text = node.getText()
+        return subst.get(text) ?? text  // external refs (Math, console) kept as-is
+      }
+      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(serializeNode).join('|')
+    return `${kind}(${childStr})`
+  }
+
+  const body = fn.getBody()
+  if (!body) return ''
+  return serializeNode(body)
+}
+
+/** Return a SHA-256 fingerprint for a function body (normalized). */
+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
+
+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
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -1284,5 +1404,48 @@ export function analyzeProject(targetPath: string, config?: DriftConfig): FileRe
     }
   }
 
+  // ── Phase 8: semantic-duplication ────────────────────────────────────────
+  // Build a fingerprint → [{filePath, fnName, line, col}] map across all files
+  const fingerprintMap = new Map<string, Array<{ filePath: string; name: string; line: number; col: number }>>()
+
+  for (const sf of sourceFiles) {
+    const sfPath = sf.getFilePath()
+    for (const { fn, name, line, col } of collectFunctions(sf)) {
+      const fp = fingerprintFunction(fn)
+      if (!fingerprintMap.has(fp)) fingerprintMap.set(fp, [])
+      fingerprintMap.get(fp)!.push({ filePath: sfPath, name, line, col })
+    }
+  }
+
+  // For each fingerprint with 2+ functions: report each as a duplicate of the others
+  for (const [, entries] of fingerprintMap) {
+    if (entries.length < 2) continue
+
+    for (const entry of entries) {
+      const report = reportByPath.get(entry.filePath)
+      if (!report) continue
+
+      // Build the "duplicated in" list (all other locations)
+      const others = entries
+        .filter(e => e !== entry)
+        .map(e => {
+          const rel = path.relative(targetPath, e.filePath).replace(/\\/g, '/')
+          return `${rel}:${e.line} (${e.name})`
+        })
+        .join(', ')
+
+      const weight = RULE_WEIGHTS['semantic-duplication']?.weight ?? 12
+      report.issues.push({
+        rule: 'semantic-duplication',
+        severity: 'warning',
+        message: `Function '${entry.name}' is semantically identical to: ${others}`,
+        line: entry.line,
+        column: entry.col,
+        snippet: `function ${entry.name} — duplicated in ${entries.length - 1} other location${entries.length > 2 ? 's' : ''}`,
+      })
+      report.score = Math.min(100, report.score + weight)
+    }
+  }
+
   return reports
 }

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}`) +

package/src/types.ts

@@ -1,18 +1,18 @@
-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 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

package/src/utils.ts

@@ -1,35 +1,35 @@
-import kleur from 'kleur'
-import type { DriftIssue } from './types.js'
-
-export interface Grade {
-  badge: string
-  label: string
-}
-
-export function scoreToGrade(score: number): Grade {
-  if (score === 0) return { badge: kleur.green('CLEAN'), label: 'clean' }
-  if (score < 20) return { badge: kleur.green('LOW'), label: 'low' }
-  if (score < 45) return { badge: kleur.yellow('MODERATE'), label: 'moderate' }
-  if (score < 70) return { badge: kleur.red('HIGH'), label: 'high' }
-  return { badge: kleur.bold().red('CRITICAL'), label: 'critical' }
-}
-
-export function scoreToGradeText(score: number): Grade {
-  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' }
-}
-
-export function severityIcon(s: DriftIssue['severity']): string {
-  if (s === 'error') return '✖'
-  if (s === 'warning') return '▲'
-  return '◦'
-}
-
-export function scoreBar(score: number, width = 20): string {
-  const filled = Math.round((score / 100) * width)
-  const empty = width - filled
-  return '█'.repeat(filled) + '░'.repeat(empty)
-}
+import kleur from 'kleur'
+import type { DriftIssue } from './types.js'
+
+export interface Grade {
+  badge: string
+  label: string
+}
+
+export function scoreToGrade(score: number): Grade {
+  if (score === 0) return { badge: kleur.green('CLEAN'), label: 'clean' }
+  if (score < 20) return { badge: kleur.green('LOW'), label: 'low' }
+  if (score < 45) return { badge: kleur.yellow('MODERATE'), label: 'moderate' }
+  if (score < 70) return { badge: kleur.red('HIGH'), label: 'high' }
+  return { badge: kleur.bold().red('CRITICAL'), label: 'critical' }
+}
+
+export function scoreToGradeText(score: number): Grade {
+  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' }
+}
+
+export function severityIcon(s: DriftIssue['severity']): string {
+  if (s === 'error') return '✖'
+  if (s === 'warning') return '▲'
+  return '◦'
+}
+
+export function scoreBar(score: number, width = 20): string {
+  const filled = Math.round((score / 100) * width)
+  const empty = width - filled
+  return '█'.repeat(filled) + '░'.repeat(empty)
+}