@eduardbar/drift 1.0.0 → 1.1.0

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SourceFile } from 'ts-morph';
 export interface DriftIssue {
     rule: string;
     severity: 'error' | 'warning' | 'info';
@@ -24,6 +25,36 @@ export interface DriftReport {
         infos: number;
         byRule: Record<string, number>;
     };
+    quality: RepoQualityScore;
+    maintenanceRisk: MaintenanceRiskMetrics;
+}
+export interface RepoQualityScore {
+    overall: number;
+    dimensions: {
+        architecture: number;
+        complexity: number;
+        'ai-patterns': number;
+        testing: number;
+    };
+}
+export interface RiskHotspot {
+    file: string;
+    driftScore: number;
+    complexityIssues: number;
+    hasNearbyTests: boolean;
+    changeFrequency: number;
+    risk: number;
+    reasons: string[];
+}
+export interface MaintenanceRiskMetrics {
+    score: number;
+    level: 'low' | 'medium' | 'high' | 'critical';
+    hotspots: RiskHotspot[];
+    signals: {
+        highComplexityFiles: number;
+        filesWithoutNearbyTests: number;
+        frequentChangeFiles: number;
+    };
 }
 export interface AIOutput {
     summary: {
@@ -32,8 +63,17 @@ export interface AIOutput {
         total_issues: number;
         files_affected: number;
         files_clean: number;
+        ai_likelihood: number;
+        ai_code_smell_score: number;
     };
+    files_suspected: Array<{
+        path: string;
+        ai_likelihood: number;
+        triggers: string[];
+    }>;
     priority_order: AIIssue[];
+    maintenance_risk: MaintenanceRiskMetrics;
+    quality: RepoQualityScore;
     context_for_ai: {
         project_type: string;
         scan_path: string;
@@ -75,6 +115,35 @@ export interface ModuleBoundary {
 export interface DriftConfig {
     layers?: LayerDefinition[];
     modules?: ModuleBoundary[];
+    plugins?: string[];
+    architectureRules?: {
+        controllerNoDb?: boolean;
+        serviceNoHttp?: boolean;
+        maxFunctionLines?: number;
+    };
+}
+export interface PluginRuleContext {
+    projectRoot: string;
+    filePath: string;
+    config?: DriftConfig;
+}
+export interface DriftPluginRule {
+    name: string;
+    severity?: DriftIssue['severity'];
+    weight?: number;
+    detect: (file: SourceFile, context: PluginRuleContext) => DriftIssue[];
+}
+export interface DriftPlugin {
+    name: string;
+    rules: DriftPluginRule[];
+}
+export interface LoadedPlugin {
+    id: string;
+    plugin: DriftPlugin;
+}
+export interface PluginLoadError {
+    pluginId: string;
+    message: string;
 }
 export interface FileDiff {
     path: string;

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { DriftIssue } from './types.js';
-export interface Grade {
+interface Grade {
     badge: string;
     label: string;
 }
@@ -7,4 +7,5 @@ export declare function scoreToGrade(score: number): Grade;
 export declare function scoreToGradeText(score: number): Grade;
 export declare function severityIcon(s: DriftIssue['severity']): string;
 export declare function scoreBar(score: number, width?: number): string;
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -1,3 +1,4 @@
+// drift-ignore-file
 import kleur from 'kleur';
 export function scoreToGrade(score) {
     if (score === 0)

package/docs/AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS - Guia Operativa para drift
+
+## 1) Proposito
+
+Esta guia define como colaborar en `drift` para mantener calidad tecnica, consistencia de arquitectura y foco en producto.
+
+`drift` existe para detectar deuda tecnica asociada a codigo IA en proyectos TypeScript y convertir esa senial en acciones concretas.
+
+## 2) Stack y estructura principal
+
+### Stack real
+
+- Runtime: Node.js 18+
+- Lenguaje: TypeScript (`type: module`)
+- Analisis AST: `ts-morph`
+- CLI: `commander`
+- Output en consola: `kleur`
+- Testing: `vitest`
+
+### Estructura clave
+
+- `src/analyzer.ts`: motor principal de reglas y score
+- `src/rules/*`: reglas por fases y helpers de deteccion
+- `src/reporter.ts`: armado de reporte y salidas para markdown/AI
+- `src/printer.ts`: salida CLI y sugerencias de fix
+- `src/cli.ts`: entrypoint y subcomandos
+- `src/fix.ts`, `src/report.ts`, `src/ci.ts`, `src/diff.ts`: comandos operativos
+- `packages/eslint-plugin-drift`: plugin ESLint
+- `packages/vscode-drift`: extension VSCode
+
+## 3) Comandos de desarrollo
+
+Usar los comandos del repo (fuente: `package.json`):
+
+```bash
+npm run build
+npm run dev
+npm start
+npm test
+npm run test:watch
+npm run test:coverage
+```
+
+Comandos de uso de producto (referencia):
+
+```bash
+npx @eduardbar/drift scan ./src
+npx @eduardbar/drift scan ./src --ai
+npx @eduardbar/drift scan ./src --min-score 60
+```
+
+## 4) Reglas de contribucion
+
+- Mantener cambios pequenos, enfocados y trazables.
+- No editar `dist/` manualmente.
+- No introducir `any` sin justificacion tecnica fuerte.
+- Reusar utilidades existentes (`utils.ts`) antes de duplicar logica.
+- Si agregas una regla nueva, actualizar:
+  - peso en `RULE_WEIGHTS`
+  - deteccion AST
+  - sugerencia de fix
+  - documentacion (README/AGENTS/PRD segun aplique)
+
+## 5) Convencion de commits
+
+Se usa Conventional Commits.
+
+Formato:
+
+```text
+type(scope): descripcion corta
+```
+
+Tipos recomendados:
+
+- `feat`: nueva capacidad de producto
+- `fix`: correccion de bug
+- `refactor`: cambio interno sin impacto funcional
+- `test`: mejoras o nuevos tests
+- `docs`: documentacion
+- `chore`: mantenimiento
+
+Ejemplos:
+
+- `feat(review): add PR score and markdown output`
+- `fix(analyzer): prevent false positive in dead-file rule`
+- `docs(prd): define v1.2 architecture roadmap`
+
+## 6) Flujo para proponer e implementar features del PRD
+
+### Paso 1 - Definir alcance MVP
+
+- Explicar objetivo de negocio y usuario.
+- Delimitar que entra y que queda fuera.
+- Agregar criterios de aceptacion verificables.
+
+### Paso 2 - Disenar impacto tecnico
+
+- Identificar comandos, modulos y reglas afectados.
+- Definir formato de salida (CLI/JSON/AI).
+- Evaluar costo de performance en repos grandes.
+
+### Paso 3 - Implementar por incrementos
+
+- Primero contrato de tipos y salida.
+- Luego deteccion/reglas/comandos.
+- Finalmente UX de consola y documentacion.
+
+### Paso 4 - Validar
+
+- Tests unitarios de logica nueva.
+- Tests de integracion de CLI cuando aplique.
+- Verificacion manual de casos reales.
+
+## 7) Criterios minimos de calidad y testing
+
+Antes de merge, cada cambio debe cumplir:
+
+- Tests pasando (`npm test`).
+- Cobertura razonable en paths nuevos (`npm run test:coverage` cuando aplique).
+- Sin regresiones en salida JSON/AI (contratos estables).
+- Errores y mensajes de CLI claros y accionables.
+- Performance aceptable para el alcance del cambio.
+
+## 8) Seguridad y manejo de informacion
+
+- Nunca commitear secretos (`.env`, tokens, credenciales, llaves).
+- No incluir datos sensibles en fixtures ni snapshots.
+- Si una feature requiere integracion externa, usar variables de entorno y documentar setup sin exponer valores.
+- Mantener principio de minimo privilegio en scripts y flujos CI.
+
+## 9) Criterios de aceptacion para features nuevas
+
+Una feature se considera lista cuando:
+
+- Resuelve un objetivo explicitado en `docs/PRD.md`.
+- Tiene MVP funcional y criterios de aceptacion cumplidos.
+- Incluye tests y documentacion operativa.
+- Es compatible con flujo CLI existente y CI.
+
+## 10) Practicas recomendadas para agentes/colaboradores
+
+- Priorizar cambios que mejoren senial sobre ruido.
+- Favorecer reportes accionables por sobre analisis abstracto.
+- Evitar humo en roadmap: cada entrega debe mapear a comando, salida y test.
+- Dejar decisiones registradas en la documentacion del repo.

package/docs/PRD.md

@@ -0,0 +1,208 @@
+# PRD - drift
+
+Version: 1.1-draft  
+Estado: Draft  
+Producto: `@eduardbar/drift`
+
+## 1) Contexto
+
+`drift` es un CLI de analisis estatico para TypeScript que detecta deuda tecnica asociada a codigo generado por IA y calcula un score de calidad por archivo y por repositorio.
+
+Hoy el producto ya cubre escaneo AST, score, reportes y comandos operativos (`scan`, `fix`, `report`, `ci`, `diff`, `badge`, `snapshot`, `trend`, `blame`).
+
+Este PRD define la evolucion para convertir a drift en una plataforma de calidad de codigo AI-first, con foco en revision de PRs, reglas de arquitectura y accionabilidad.
+
+## 2) Vision de Producto
+
+Ser la herramienta de referencia para equipos que usan IA para programar y necesitan detectar, priorizar y corregir deuda tecnica antes de que llegue a produccion.
+
+## 3) Killer Feature
+
+## AI Code Smell Detector
+
+El diferencial principal de drift es detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, comentarios de PR, reglas de arquitectura y reportes).
+
+## 4) Objetivos de Negocio y Producto
+
+- Reducir riesgo de mantenimiento en repos con alto volumen de codigo IA.
+- Dar feedback accionable en el punto de trabajo (CLI, PR y editor).
+- Estandarizar calidad arquitectonica con reglas configurables por equipo.
+- Escalar desde CLI local a experiencia organizacional (dashboard SaaS).
+
+## 5) Alcance MVP por Feature (sin humo)
+
+Cada feature incluye objetivo, alcance MVP y criterios de aceptacion.
+
+### 5.1 Detector de codigo generado por IA
+
+- Objetivo: estimar `ai_likelihood` por archivo y listar `files_suspected`.
+- Alcance MVP:
+  - Exponer `ai_likelihood` (0-100) dentro de salida JSON/AI.
+  - Agregar lista ordenada de archivos sospechados con score y reglas disparadas.
+  - No hacer afirmaciones absolutas; reportar como probabilidad.
+- Criterios de aceptacion:
+  - `drift scan <path> --ai` incluye `ai_likelihood` por archivo.
+  - Reporte global incluye `files_suspected` y top N archivos.
+  - Tests cubren serializacion y orden de prioridad.
+
+### 5.2 PR reviewer automatico (`drift review` + comentario en PR)
+
+- Objetivo: revisar cambios de PR y publicar feedback tecnico automatico.
+- Alcance MVP:
+  - Nuevo comando `drift review` para analizar diff contra base branch.
+  - Salida markdown apta para comentario de PR.
+  - Integracion base via GitHub CLI (`gh`) en CI.
+- Criterios de aceptacion:
+  - `drift review --base main` devuelve score de PR y top issues.
+  - En workflow CI se publica un comentario unico actualizable.
+  - Si score supera umbral configurable, CI falla.
+
+### 5.3 Reglas de arquitectura configurables
+
+- Objetivo: habilitar reglas de arquitectura de negocio definidas por el equipo.
+- Alcance MVP:
+  - Soporte en `drift.config.ts` para:
+    - `controller-no-db`
+    - `service-no-http`
+    - `max-function-lines`
+  - Mensajes de error claros con ubicacion y recomendacion.
+- Criterios de aceptacion:
+  - Config valida y tipada.
+  - Reglas activas afectan score y aparecen en reporte.
+  - Fixtures de test para casos validos e invalidos.
+
+### 5.4 Score de calidad por repo con breakdown
+
+- Objetivo: mostrar salud del repo en forma ejecutiva y tecnica.
+- Alcance MVP:
+  - Score global del repo.
+  - Breakdown por severidad, regla y carpeta.
+  - Tendencia minima (ultimos snapshots locales).
+- Criterios de aceptacion:
+  - `drift scan` muestra score repo + breakdown resumido.
+  - `--json` expone estructura consumible por CI/dashboard.
+
+### 5.5 Mapa de arquitectura automatico (`drift map` -> `architecture.svg`)
+
+- Objetivo: visualizar dependencias y violaciones de capas.
+- Alcance MVP:
+  - Nuevo comando `drift map`.
+  - Genera `architecture.svg` desde imports y modulos detectados.
+  - Marca ciclos y violaciones de capas.
+- Criterios de aceptacion:
+  - `drift map ./src` crea `architecture.svg` sin edicion manual.
+  - El SVG es legible en repos medianos (ej. <= 300 archivos TS).
+
+### 5.6 VSCode extension con feedback en tiempo real
+
+- Objetivo: bajar el tiempo entre error y correccion.
+- Alcance MVP:
+  - Diagnosticos por archivo al guardar.
+  - Score visible por archivo.
+  - Quick actions para sugerencias simples.
+- Criterios de aceptacion:
+  - La extension muestra issues drift en panel Problems.
+  - La latencia por archivo en save se mantiene en nivel usable.
+
+### 5.7 Fix automatico (`drift fix`) con ejemplo antes/despues
+
+- Objetivo: convertir hallazgos en cambios concretos de bajo riesgo.
+- Alcance MVP:
+  - `drift fix` aplica fixes seguros en reglas seleccionadas.
+  - Modo preview con diff antes/despues.
+  - Modo write con confirmacion.
+- Criterios de aceptacion:
+  - `drift fix --preview` imprime diff legible.
+  - `drift fix --write` modifica solo reglas soportadas.
+  - Tests de no-regresion para no romper sintaxis TS.
+
+Ejemplo (antes/despues):
+
+```ts
+// Antes
+console.log(userData)
+
+// Despues (sugerencia simple)
+// Removed debug leftover; use structured logger if needed.
+```
+
+### 5.8 Reporte tecnico (`drift report` -> `drift-report.html`)
+
+- Objetivo: entregar reporte compartible para devs, tech leads y QA.
+- Alcance MVP:
+  - Salida HTML `drift-report.html` con score, breakdown y top issues.
+  - Secciones por archivo con snippets y sugerencias.
+- Criterios de aceptacion:
+  - `drift report ./src --html` genera archivo navegable.
+  - El reporte puede adjuntarse en CI artifacts.
+
+### 5.9 Metricas de riesgo de mantenimiento (hotspots)
+
+- Objetivo: priorizar deuda por impacto real.
+- Alcance MVP:
+  - Hotspots combinando score + frecuencia de cambios + criticidad.
+  - Ranking de archivos para plan de refactor.
+- Criterios de aceptacion:
+  - `drift trend` o salida dedicada muestra top hotspots.
+  - Metodo de ranking documentado y testeado.
+
+### 5.10 Plugin system (`drift-plugin-*`)
+
+- Objetivo: extender drift sin tocar el core.
+- Alcance MVP:
+  - Carga de plugins por convension `drift-plugin-*`.
+  - API minima para registrar reglas y metadata.
+  - Aislamiento de errores de plugins para no romper scan completo.
+- Criterios de aceptacion:
+  - Plugin de ejemplo funcional en repo de ejemplo.
+  - Si un plugin falla, drift sigue ejecutando y reporta el error.
+
+## 6) Roadmap Realista
+
+### v1.1
+
+- `drift review` para PR comments.
+- Score de PR y score de repo con breakdown minimo.
+
+### v1.2
+
+- Reglas de arquitectura configurables.
+- `drift map` y generacion de `architecture.svg`.
+
+### v2
+
+- VSCode extension con feedback en tiempo real.
+- `drift fix` con preview/write y fixes seguros.
+
+### v3
+
+- SaaS dashboard para historico, equipos y gobierno de calidad.
+
+## 7) Fuera de Alcance (por ahora)
+
+- Soporte multi-lenguaje completo fuera de TypeScript/JS.
+- Autofix de reglas de alto riesgo sin confirmacion.
+- Integraciones propietarias cerradas sin API estable.
+
+## 8) KPIs de Exito
+
+- Reduccion de score promedio en repos activos.
+- % de PRs con feedback drift resuelto antes de merge.
+- Tiempo medio desde deteccion hasta fix aplicado.
+- Adopcion de reglas de arquitectura por equipo.
+
+## 9) Dependencias y Riesgos
+
+- Performance en repos grandes (AST + analisis cross-file).
+- Calidad de senial en `ai_likelihood` (riesgo de falsos positivos).
+- Compatibilidad de integraciones CI/PR entre plataformas.
+- Diseno de API de plugins sin romper backward compatibility.
+
+## 10) Definicion de Done (global)
+
+Una feature del roadmap se considera terminada cuando:
+
+- Tiene comando/flujo usable y documentado.
+- Tiene tests automatizados de casos base y borde.
+- Tiene salida estable en CLI/JSON para CI.
+- Tiene criterios de aceptacion de esta PRD cumplidos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Detect silent technical debt left by AI-generated code",
   "type": "module",
   "main": "dist/index.js",

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

@@ -103,7 +103,7 @@ function createRule(ruleName: string): Rule.RuleModule {
                 data: { message: issue.message },
               })
             }
-          } catch {
+          } catch { // drift-ignore
             // Archivo no parseable por ts-morph — silenciar
           }
         },

package/packages/vscode-drift/package.json

@@ -113,7 +113,7 @@
     "typescript": "^5.3.0"
   },
   "dependencies": {
-    "@eduardbar/drift": "*",
+    "@eduardbar/drift": "1.0.0",
     "ts-morph": "^23.0.0"
   }
 }

package/packages/vscode-drift/src/analyzer.ts

@@ -1,3 +1,5 @@
+// drift-ignore-file
+
 import { Project } from 'ts-morph'
 import type { FileReport } from '@eduardbar/drift'
 

package/packages/vscode-drift/src/extension.ts

@@ -1,3 +1,5 @@
+// drift-ignore-file
+
 import * as vscode from 'vscode'
 import { analyzeFilePath } from './analyzer'
 import { DriftDiagnosticsProvider } from './diagnostics'
@@ -7,84 +9,106 @@ import type { FileReport } from '@eduardbar/drift'
 
 const SUPPORTED_LANGUAGES = ['typescript', 'typescriptreact', 'javascript', 'javascriptreact']
 
+async function analyzeAndUpdate(
+  document: vscode.TextDocument,
+  diagnostics: DriftDiagnosticsProvider,
+  treeProvider: DriftTreeProvider,
+  reportCache: Map<string, FileReport>,
+  statusBar: DriftStatusBarItem
+): Promise<void> {
+  const config = vscode.workspace.getConfiguration('drift')
+  if (!config.get<boolean>('enable', true)) return
+
+  if (!SUPPORTED_LANGUAGES.includes(document.languageId)) return
+  if (document.uri.scheme !== 'file') return
+
+  const filePath = document.uri.fsPath
+
+  const report = await analyzeFilePath(filePath)
+  if (!report) return
+
+  diagnostics.update(report)
+  treeProvider.updateFile(report)
+  reportCache.set(filePath, report)
+  statusBar.update(Array.from(reportCache.values()))
+}
+
+async function scanWorkspace(
+  diagnostics: DriftDiagnosticsProvider,
+  treeProvider: DriftTreeProvider,
+  reportCache: Map<string, FileReport>,
+  statusBar: DriftStatusBarItem
+): Promise<void> {
+  const files = await vscode.workspace.findFiles(
+    '**/*.{ts,tsx,js,jsx}',
+    '**/node_modules/**'
+  )
+
+  vscode.window.withProgress(
+    {
+      location: vscode.ProgressLocation.Notification,
+      title: 'drift: Scanning workspace...',
+      cancellable: false,
+    },
+    async (progress) => {
+      const total = files.length
+      let done = 0
+
+      for (const file of files) {
+        const report = await analyzeFilePath(file.fsPath)
+        if (report) {
+          diagnostics.update(report)
+          treeProvider.updateFile(report)
+          reportCache.set(file.fsPath, report)
+        }
+        done++
+        progress.report({ increment: (done / total) * 100 })
+      }
+
+      statusBar.update(Array.from(reportCache.values()))
+      vscode.window.showInformationMessage(`drift: ${total} files scanned.`)
+    }
+  )
+}
+
+function clearDiagnostics(
+  diagnostics: DriftDiagnosticsProvider,
+  treeProvider: DriftTreeProvider,
+  reportCache: Map<string, FileReport>,
+  statusBar: DriftStatusBarItem
+): void {
+  diagnostics.clear()
+  treeProvider.clearAll()
+  reportCache.clear()
+  statusBar.update([])
+}
+
 export function activate(context: vscode.ExtensionContext): void {
   const diagnostics = new DriftDiagnosticsProvider()
   const treeProvider = new DriftTreeProvider()
   const statusBar = new DriftStatusBarItem()
 
-  // Registrar TreeView
   const treeView = vscode.window.createTreeView('driftIssues', {
     treeDataProvider: treeProvider,
     showCollapseAll: true,
   })
 
-  // Cache de reports para la status bar
   const reportCache = new Map<string, FileReport>()
 
-  async function analyzeAndUpdate(document: vscode.TextDocument): Promise<void> {
-    const config = vscode.workspace.getConfiguration('drift')
-    if (!config.get<boolean>('enable', true)) return
-
-    if (!SUPPORTED_LANGUAGES.includes(document.languageId)) return
-    if (document.uri.scheme !== 'file') return
-
-    const filePath = document.uri.fsPath
-
-    const report = await analyzeFilePath(filePath)
-    if (!report) return
-
-    diagnostics.update(report)
-    treeProvider.updateFile(report)
-    reportCache.set(filePath, report)
-    statusBar.update(Array.from(reportCache.values()))
-  }
-
-  // Trigger: al guardar
-  const onSave = vscode.workspace.onDidSaveTextDocument(analyzeAndUpdate)
-
-  // Comando: scan workspace
-  const scanCmd = vscode.commands.registerCommand('drift.scanWorkspace', async () => {
-    const files = await vscode.workspace.findFiles(
-      '**/*.{ts,tsx,js,jsx}',
-      '**/node_modules/**'
-    )
-
-    vscode.window.withProgress(
-      {
-        location: vscode.ProgressLocation.Notification,
-        title: 'drift: Scanning workspace...',
-        cancellable: false,
-      },
-      async (progress) => {
-        const total = files.length
-        let done = 0
-
-        for (const file of files) {
-          const report = await analyzeFilePath(file.fsPath)
-          if (report) {
-            diagnostics.update(report)
-            treeProvider.updateFile(report)
-            reportCache.set(file.fsPath, report)
-          }
-          done++
-          progress.report({ increment: (done / total) * 100 })
-        }
+  const onSave = vscode.workspace.onDidSaveTextDocument(
+    (doc) => analyzeAndUpdate(doc, diagnostics, treeProvider, reportCache, statusBar)
+  )
 
-        statusBar.update(Array.from(reportCache.values()))
-        vscode.window.showInformationMessage(`drift: ${total} files scanned.`)
-      }
-    )
-  })
+  const scanCmd = vscode.commands.registerCommand(
+    'drift.scanWorkspace',
+    () => scanWorkspace(diagnostics, treeProvider, reportCache, statusBar)
+  )
 
-  // Comando: clear
-  const clearCmd = vscode.commands.registerCommand('drift.clearDiagnostics', () => {
-    diagnostics.clear()
-    treeProvider.clearAll()
-    reportCache.clear()
-    statusBar.update([])
-  })
+  const clearCmd = vscode.commands.registerCommand(
+    'drift.clearDiagnostics',
+    () => clearDiagnostics(diagnostics, treeProvider, reportCache, statusBar)
+  )
 
-  // Comando: go to issue (desde TreeView click)
   const goToCmd = vscode.commands.registerCommand(
     'drift.goToIssue',
     async (filePath: string, line: number) => {