@eduardbar/drift 1.0.0 → 1.2.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,41 @@ export interface ModuleBoundary {
 export interface DriftConfig {
     layers?: LayerDefinition[];
     modules?: ModuleBoundary[];
+    plugins?: string[];
+    architectureRules?: {
+        controllerNoDb?: boolean;
+        serviceNoHttp?: boolean;
+        maxFunctionLines?: number;
+    };
+    saas?: {
+        freeUserThreshold?: number;
+        maxRunsPerWorkspacePerMonth?: number;
+        maxReposPerWorkspace?: number;
+        retentionDays?: 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,157 @@
+# PRD - drift
+
+Version: 1.2.0  
+Estado: Activo  
+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 score por archivo y por repositorio.
+
+Con release `v1.2.0`, el producto entrega comandos operativos, analisis AST, reglas de arquitectura configurables, salida accionable, workflow CI para PR comments, y foundations SaaS (`drift cloud ingest|summary|dashboard`) con politica free-until-7500.
+
+## 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 mergear a produccion.
+
+## 3) Killer feature
+
+## AI Code Smell Detector
+
+Detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, review de PR, reglas de arquitectura y reportes).
+
+## 4) Estado de cumplimiento (actualizado)
+
+### Entregado
+
+- `drift review` en CLI para analizar diff contra base y producir markdown usable en PR.
+- `drift map` basico para generar `architecture.svg`.
+- Senial de IA en salida (`ai_likelihood` y `files_suspected`).
+- Reglas de arquitectura configurables via `drift.config.ts`.
+- Score y breakdown por dimensiones para lectura ejecutiva y tecnica.
+- Metricas de maintenance risk/hotspots.
+- Plugin system MVP (`drift-plugin-*`) con aislamiento de errores.
+- `drift fix` con modos preview/write.
+- Workflow CI para comentario automatico unico y actualizable de `drift review`.
+- `drift map` con marcado de cycle edges y layer violations en el SVG.
+- VSCode quick actions para fixes de bajo riesgo.
+- Confirmacion interactiva para `drift fix --write` (con `--yes` para CI/no-interactive).
+- `drift report` HTML (`drift-report.html`) sin flag extra.
+- Documentacion y tests del release.
+
+### Parcial
+
+- Consolidacion/hardening de API de plugins para ecosistema externo amplio.
+
+### Pendiente
+
+- Hardening del contrato de plugins para ecosistema externo amplio.
+- Evolucion del dashboard SaaS foundations a experiencia multi-tenant full (auth, permisos por rol y billing activo post-umbral).
+
+## 5) Criterios de aceptacion vigentes
+
+### 5.1 Entregables cerrados en v1.1.0
+
+- `drift review --base <ref>` devuelve score delta de PR, issues nuevos/resueltos y markdown.
+- `drift scan --ai` incluye `ai_likelihood` y ranking `files_suspected`.
+- `drift map <path>` genera `architecture.svg` utilizable sin edicion manual.
+- `drift report [path]` genera HTML self-contained (no requiere `--html`).
+- `drift fix --preview` muestra antes/despues y `drift fix --write` aplica reglas soportadas.
+
+### 5.1.b Entregables cerrados en v1.2 (scope tecnico)
+
+- Workflow CI publica/actualiza comentario unico en PR para `drift review`.
+- `drift map` marca visualmente ciclos y violaciones por capa.
+- Extension VSCode expone quick actions para `debug-leftover` y `catch-swallow`.
+- `drift fix --write` pide confirmacion interactiva por defecto y admite `--yes`.
+
+### 5.2 Objetivos aun abiertos (CI/editor/UX)
+
+- Hardening del contrato de plugins para compatibilidad de largo plazo (versionado/migraciones).
+
+## 6) Roadmap actualizado
+
+### v1.1 (completado - release 1.1.0)
+
+Prioridades cerradas:
+- CLI de review para PR, mapa basico, salida AI, reglas configurables, report HTML, fix preview/write, hotspots, plugin MVP.
+
+Done del bloque:
+- Features documentadas.
+- Tests de paths principales.
+- Salidas CLI/JSON/AI consistentes para uso local y CI.
+
+### v1.2 (completado - cierre de pendientes tecnicos)
+
+Prioridades cerradas:
+- Comentario automatico actualizable en PR desde workflow CI.
+- Mejora de `drift map` para destacar ciclos y violaciones.
+- UX de seguridad para `drift fix --write` con confirmacion interactiva.
+
+Done del bloque:
+- Flujo CI reproducible con comentario unico por PR.
+- Visualizaciones verificables en SVG sobre repos medianos.
+- Confirmacion interactiva implementada para write mode.
+
+### v2 (prioridad: experiencia de editor + extensibilidad)
+
+Prioridades:
+- Consolidacion de API de plugins y hardening de compatibilidad.
+- Reglas de plugin versionadas y validacion de contrato avanzada.
+
+Criterio de done:
+- Plugins con contrato estable y manejo de errores robusto.
+- Documentacion de versionado para autores de plugins.
+
+### v3 (fundations completadas en v1.2.0)
+
+Prioridades cerradas:
+- Base de datos local de snapshots para cloud MVP.
+- Ingestion de reportes en storage local SaaS-like.
+- Summary de uso/threshold y dashboard HTML inicial.
+- Guardrails de fase gratuita por workspace + politica free-until-7500.
+
+Siguiente incremento (v3.x):
+- Auth real multi-tenant, permisos por equipo y backend remoto persistente.
+- Activacion de billing cuando el umbral de 7.500 usuarios se cumpla.
+
+## 6.1) Estrategia de monetizacion (aprobada)
+
+- Fase gratuita: Drift SaaS gratis hasta alcanzar 7.500 usuarios registrados.
+- Trigger de monetizacion: al alcanzar 7.500 usuarios, activar planes pagos para nuevos usuarios y definir politica de migracion para cohortes gratuitas.
+- Objetivo: priorizar adopcion y proof-of-value temprano sin friccion comercial inicial.
+- Guardrails durante fase gratuita:
+  - Limites tecnicos por workspace (runs/mes, retencion de historial, repositorios activos).
+  - Instrumentacion de uso desde el dia 1 para evitar abuso y medir unit economics.
+  - Feature flags de pricing listas antes del trigger para evitar corte abrupto.
+
+## 7) Fuera de alcance actual
+
+- Soporte multi-lenguaje completo fuera de TypeScript/JS.
+- Autofix de reglas de alto riesgo sin confirmacion explicita.
+- 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 configurables por equipo.
+
+## 9) Dependencias y riesgos
+
+- Performance en repos grandes (AST + cross-file).
+- Calidad de senial en `ai_likelihood` (falsos positivos/negativos).
+- Variabilidad de entornos CI para publicar comentarios de PR.
+- Evolucion de API de plugins sin romper backward compatibility.
+
+## 10) Definition of Done por release
+
+Checklist minimo por release:
+
+- [ ] Scope del release cerrado y trazable a este PRD.
+- [ ] Comandos/flujo documentados con ejemplos reales.
+- [ ] Tests de regresion en paths principales y casos borde.
+- [ ] Salidas CLI/JSON/AI estables para automatizacion.
+- [ ] Criterios de aceptacion del bloque marcados como cumplidos o movidos a pendiente.
+- [ ] Riesgos y tradeoffs explicitados en notas de release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "1.0.0",
+  "version": "1.2.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/code-actions.ts

@@ -0,0 +1,53 @@
+import * as vscode from 'vscode'
+
+function buildRemoveLineEdit(document: vscode.TextDocument, line: number): vscode.WorkspaceEdit {
+  const edit = new vscode.WorkspaceEdit()
+  const targetLine = document.lineAt(line)
+  const start = targetLine.range.start
+  const end = line < document.lineCount - 1
+    ? document.lineAt(line + 1).range.start
+    : targetLine.range.end
+  edit.delete(document.uri, new vscode.Range(start, end))
+  return edit
+}
+
+function buildCatchTodoEdit(document: vscode.TextDocument, line: number): vscode.WorkspaceEdit {
+  const edit = new vscode.WorkspaceEdit()
+  const targetLine = document.lineAt(line)
+  const baseIndent = targetLine.text.match(/^\s*/)?.[0] ?? ''
+  const indent = `${baseIndent}  `
+  edit.insert(document.uri, new vscode.Position(line + 1, 0), `${indent}// TODO: handle error\n`)
+  return edit
+}
+
+export class DriftCodeActionProvider implements vscode.CodeActionProvider {
+  provideCodeActions(
+    document: vscode.TextDocument,
+    _range: vscode.Range,
+    context: vscode.CodeActionContext,
+  ): vscode.CodeAction[] {
+    const actions: vscode.CodeAction[] = []
+
+    for (const diagnostic of context.diagnostics) {
+      if (diagnostic.source !== 'drift') continue
+      const rule = String(diagnostic.code ?? '')
+      const line = diagnostic.range.start.line
+
+      if (rule === 'debug-leftover') {
+        const quickFix = new vscode.CodeAction('drift: remove debug leftover line', vscode.CodeActionKind.QuickFix)
+        quickFix.diagnostics = [diagnostic]
+        quickFix.edit = buildRemoveLineEdit(document, line)
+        actions.push(quickFix)
+      }
+
+      if (rule === 'catch-swallow') {
+        const quickFix = new vscode.CodeAction('drift: add TODO in empty catch', vscode.CodeActionKind.QuickFix)
+        quickFix.diagnostics = [diagnostic]
+        quickFix.edit = buildCatchTodoEdit(document, line)
+        actions.push(quickFix)
+      }
+    }
+
+    return actions
+  }
+}