@eduardbar/drift 0.3.0 → 0.4.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something is broken or behaving unexpectedly
+title: "fix: "
+labels: bug
+assignees: ""
+---
+
+## What happened
+
+<!-- A clear description of the bug. -->
+
+## Steps to reproduce
+
+1. Run `npx @eduardbar/drift scan ...`
+2. ...
+
+## Expected behavior
+
+<!-- What should have happened. -->
+
+## Actual behavior
+
+<!-- What actually happened. Include the full terminal output if relevant. -->
+
+## Environment
+
+- drift version: <!-- run `npx @eduardbar/drift --version` -->
+- Node.js version: <!-- run `node --version` -->
+- OS: <!-- e.g. Windows 11, macOS 14, Ubuntu 22.04 -->
+- Shell: <!-- e.g. PowerShell, bash, zsh -->
+
+## Minimal reproduction
+
+```typescript
+// Paste the smallest possible file that triggers the bug
+```
+
+## Additional context
+
+<!-- Screenshots, links, anything else that helps. -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,39 @@
+---
+name: Feature request
+about: Propose a new detection rule or CLI feature
+title: "feat: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+<!-- What specific AI-generated pattern or technical debt is NOT currently detected?
+     Or what workflow friction does this feature address? -->
+
+## Proposed solution
+
+<!-- Describe the rule or feature. If it's a new detection rule, include:
+     - Rule name (kebab-case)
+     - Severity: error | warning | info
+     - Suggested weight (1–20)
+     - What it detects and why it matters -->
+
+## Example
+
+```typescript
+// Code that SHOULD trigger the new rule
+function example() {
+  // ...
+}
+```
+
+## Why drift and not ESLint
+
+<!-- drift is NOT an ESLint replacement. It targets patterns ESLint can't catch:
+     architectural violations, AI-specific habits, historical debt trends.
+     Explain why this belongs in drift. -->
+
+## Additional context
+
+<!-- Links, references, real-world examples that motivated this request. -->

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,46 @@
+# Pull Request
+
+## Type
+
+- [ ] Bug fix
+- [ ] New detection rule
+- [ ] New CLI feature
+- [ ] Refactor / performance
+- [ ] Docs
+- [ ] Other
+
+## Summary
+
+<!-- What does this PR do and why? 1–3 sentences max. -->
+
+## Changes
+
+- 
+- 
+
+## New rule checklist (skip if not applicable)
+
+- [ ] Entry added to `RULE_WEIGHTS` in `src/analyzer.ts`
+- [ ] Detection logic implemented using ts-morph AST
+- [ ] `fix_suggestion` added for the rule in `src/printer.ts`
+- [ ] Rule documented in `README.md` (What it detects table)
+- [ ] Rule documented in `AGENTS.md` (Rules table)
+
+## Testing
+
+```bash
+# Command you ran to verify this works
+npx @eduardbar/drift scan ./src
+```
+
+<!-- Paste the relevant part of the output. -->
+
+## Breaking changes
+
+<!-- Does this change the score of existing scans, remove a flag, or change output format?
+     If yes, describe the impact. -->
+
+## Commit convention
+
+This PR follows [Conventional Commits](https://www.conventionalcommits.org/).
+All commits are in the format `type(scope): description`.

package/AGENTS.md

@@ -0,0 +1,229 @@
+# AGENTS.md — drift
+
+## Qué es drift
+
+`@eduardbar/drift` es un CLI TypeScript que escanea proyectos TypeScript con análisis AST (ts-morph) y asigna un score de 0 a 100 a cada archivo según la cantidad de deuda técnica AI-generada que contiene.
+
+- **0** = código limpio
+- **100** = reescribí esto antes de que alguien lo vea
+
+Publicado en npm como `@eduardbar/drift`. MIT.
+
+---
+
+## Stack técnico
+
+| Dep | Rol |
+|-----|-----|
+| `ts-morph ^27` | Motor AST — traversal de nodos TypeScript |
+| `commander ^14` | CLI flags y subcomandos |
+| `kleur ^4` | Colores en consola (sin dependencias) |
+| `typescript ^5.9` | Dev — compilación |
+| `@types/node ^25` | Dev — tipos Node.js |
+
+**Runtime:** Node.js 18+, ES Modules (`"type": "module"`).
+
+---
+
+## Estructura del proyecto
+
+```
+drift/
+├── bin/
+│   └── drift.js          ← wrapper cross-platform (Windows npx fix)
+├── src/
+│   ├── types.ts          ← interfaces: DriftIssue, FileReport, DriftReport, AIOutput
+│   ├── analyzer.ts       ← motor AST + 10 reglas de detección + drift-ignore
+│   ├── reporter.ts       ← buildReport(), formatMarkdown(), formatAIOutput()
+│   ├── printer.ts        ← salida consola con colores y score bar ASCII
+│   ├── utils.ts          ← scoreToGrade, severityIcon, scoreBar
+│   ├── index.ts          ← re-exports públicos (librería)
+│   └── cli.ts            ← entry point Commander.js
+├── assets/
+│   ├── og.svg / og.png           ← imagen OG original
+│   ├── og-v030-linkedin.svg/png  ← imagen post LinkedIn v0.3.0
+│   └── og-v030-x.svg/png         ← imagen hilo X v0.3.0
+├── dist/                 ← output tsc (no editar a mano)
+├── .github/workflows/publish.yml
+├── package.json
+├── tsconfig.json
+└── AGENTS.md             ← este archivo
+```
+
+---
+
+## Comandos de desarrollo
+
+```bash
+npm run build       # tsc — compila src/ → dist/
+npm run dev         # tsc --watch
+npm start           # node dist/cli.js (desarrollo local)
+```
+
+**Pre-publicación:** `prepublishOnly` corre `build` automáticamente.
+
+---
+
+## CLI — flags disponibles
+
+| Flag | Tipo | Descripción |
+|------|------|-------------|
+| `scan <path>` | positional | Ruta a escanear (requerido) |
+| `--output <file>` / `-o` | string | Escribe reporte Markdown a archivo |
+| `--json` | boolean | Imprime `DriftReport` crudo como JSON |
+| `--ai` | boolean | JSON optimizado para LLMs (`AIOutput`) |
+| `--fix` | boolean | Muestra sugerencias de fix en consola |
+| `--min-score <n>` | number | Exit code 1 si score supera umbral (CI) |
+
+**Uso básico:**
+```bash
+npx @eduardbar/drift scan .
+npx @eduardbar/drift scan ./src --min-score 60
+npx @eduardbar/drift scan ./src --ai | pbcopy   # pegar en Claude/GPT
+npx @eduardbar/drift scan ./src --fix           # ver sugerencias inline
+npx @eduardbar/drift scan ./src -o report.md    # exportar Markdown
+```
+
+---
+
+## Reglas del analyzer
+
+| Regla | Severidad | Peso | Qué detecta |
+|-------|-----------|------|-------------|
+| `large-file` | error | 20 | Archivos > 300 líneas |
+| `large-function` | error | 15 | Funciones > 50 líneas |
+| `duplicate-function-name` | error | 18 | Nombres de función duplicados (case-insensitive) |
+| `debug-leftover` | warning | 10 | `console.log/warn/error` + `TODO/FIXME/HACK/XXX/TEMP` |
+| `catch-swallow` | warning | 10 | Bloques `catch {}` vacíos |
+| `dead-code` | warning | 8 | Imports nombrados sin usar |
+| `any-abuse` | warning | 8 | Uso explícito de `any` como tipo |
+| `comment-contradiction` | warning | 12 | (reservado — definido en RULE_WEIGHTS) |
+| `no-return-type` | info | 5 | Funciones sin tipo de retorno explícito |
+| `magic-number` | info | 3 | (reservado — definido en RULE_WEIGHTS) |
+
+**Score = suma de pesos capped a 100. Score del proyecto = promedio de archivos.**
+
+---
+
+## drift-ignore
+
+**Por línea** (`// drift-ignore`):
+- Suprime el issue en la línea actual o en la línea inmediatamente superior al problema.
+- Funciona para cualquier regla.
+
+**Por archivo** (`// drift-ignore-file`):
+- Se coloca en las primeras 10 líneas del archivo.
+- `analyzeFile()` devuelve reporte vacío (score 0, cero issues) para ese archivo.
+- Usar en archivos con `console.log` intencional (ej: `printer.ts`).
+
+---
+
+## Formato `--ai` (`AIOutput`)
+
+```typescript
+interface AIOutput {
+  summary: {
+    score: number
+    grade: string          // "CLEAN" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
+    total_issues: number
+    files_affected: number
+    files_clean: number
+  }
+  priority_order: Array<{
+    rank: number
+    file: string
+    line: number
+    rule: string
+    severity: "error" | "warning" | "info"
+    message: string
+    snippet: string
+    fix_suggestion: string
+    effort: "low" | "medium" | "high"
+  }>
+  context_for_ai: {
+    project_type: "typescript"
+    scan_path: string
+    rules_detected: string[]
+    recommended_action: string
+  }
+}
+```
+
+Los issues se ordenan: error > warning > info, luego low effort primero (quick wins).
+
+---
+
+## Formato `--fix` en consola
+
+```
+       ┌──────────────────────────────────────────────────────┐
+       │  - console.log(userData)
+       │  + Remove this console.log statement
+       │  + Or replace with a proper logging library
+       └──────────────────────────────────────────────────────┘
+```
+
+Las sugerencias por regla están hardcodeadas en `src/printer.ts`.
+
+---
+
+## CI/CD — GitHub Actions
+
+Workflow en `.github/workflows/publish.yml`:
+- **Trigger único:** `release: published` (evita doble publish)
+- **Fallback manual:** `workflow_dispatch` con input `tag`
+- **Guard:** verifica `npm view @eduardbar/drift@$VERSION` antes de publicar
+
+**Integración CI en proyectos externos:**
+```yaml
+- name: Check drift score
+  run: npx @eduardbar/drift scan ./src --min-score 60
+```
+
+---
+
+## Compatibilidad Windows
+
+`bin/drift.js` es el wrapper cross-platform:
+```javascript
+#!/usr/bin/env node
+import('../dist/cli.js')
+```
+
+`package.json` apunta `bin.drift` a `bin/drift.js`, **no** a `dist/cli.js`.
+Sin esto, Windows no ejecuta el shebang correctamente con ES modules.
+
+---
+
+## Versiones
+
+| Versión | Cambios principales |
+|---------|---------------------|
+| **0.3.0** | `--ai` (LLM-optimized JSON output) + `--fix` (inline suggestions) |
+| **0.2.3** | Fix: bin wrapper para compatibilidad Windows npx |
+| **0.2.2** | Refactor: `formatMarkdown` dividido en helpers + fix CI doble publish |
+| **0.2.1** | `drift-ignore` por línea y por archivo + fix console output propio |
+| **0.2.0** | Score bar ASCII + header hierarchy + DRY utils + file count en CLI |
+| **0.1.x** | Bootstrap: tipos, analyzer (10 reglas), reporter, printer, CLI, CI/CD |
+
+---
+
+## Convenciones de código
+
+- Todo en TypeScript — sin `any` explícito (drift se corre sobre sí mismo)
+- ES Modules — `import/export`, sin CommonJS
+- Conventional Commits obligatorios (ver AGENTS.md global)
+- `// drift-ignore-file` en `printer.ts` — sus `console.log` son output intencional
+- `scoreToGrade`, `severityIcon`, `scoreBar` viven en `utils.ts` — no duplicar
+- Nuevas reglas: agregar entrada en `RULE_WEIGHTS` en `analyzer.ts` + lógica de detección AST
+
+---
+
+## Agregar una nueva regla — checklist
+
+1. Agregar `"rule-name": <peso>` a `RULE_WEIGHTS` en `src/analyzer.ts`
+2. Implementar la lógica de detección AST usando ts-morph en `analyzeFile()`
+3. Agregar `fix_suggestion` para la regla en `src/printer.ts` (objeto de sugerencias por regla)
+4. Actualizar `README.md` — tabla de reglas
+5. Actualizar este `AGENTS.md` — tabla de reglas
+6. Commit: `feat(analyzer): add <rule-name> rule`

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to drift are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.4.0] — 2026-02-23
+
+### Added
+- **Phase 2: cross-file dead code detection** — three new rules that require project-level import graph analysis (ESLint cannot do this by design — issue wontfix #371):
+  - `unused-export` (warning, weight 8): named exports that are never imported anywhere in the project.
+  - `dead-file` (warning, weight 10): source files that are never imported by any other file.
+  - `unused-dependency` (warning, weight 6): packages listed in `dependencies` in `package.json` that are never imported in source code.
+- `analyzeProject()` now builds a cross-file import graph before per-file analysis, enabling project-level rules without additional dependencies.
+- Fix suggestions for all three new rules in `src/printer.ts`.
+- **Phase 3: structural architecture analysis**:
+  - `circular-dependency` (error, weight 14): detects circular import chains using DFS cycle detection. Reports the full cycle path as `A → B → C → A`.
+  - `layer-violation` (error, weight 16): flags imports that violate declared architectural layers. Requires `drift.config.ts`.
+  - `cross-boundary-import` (warning, weight 10): flags imports across module boundaries outside allowed paths. Requires `drift.config.ts`.
+- `loadConfig()` — new async config loader in `src/config.ts`. Discovers `drift.config.ts / .js / .json` at project root. All rules except `layer-violation` and `cross-boundary-import` work without any config.
+- `DriftConfig`, `LayerDefinition`, `ModuleBoundary` types exported from the package.
+- Fix suggestions for all Phase 3 rules in `src/printer.ts`.
+- **Phase 4: `drift diff` — historical comparison**:
+  - `drift diff [ref]` command: compare current project state against any git ref (commit, branch, tag). Default ref: `HEAD~1`.
+  - Uses `git show <ref>:<file>` for non-destructive extraction — no checkout, no stash, no repo state changes.
+  - Detects new issues introduced and issues resolved per file.
+  - Shows score delta per file and overall (`+N` red = regression, `-N` green = improvement).
+  - `--json` flag outputs raw `DriftDiff` JSON for CI consumption.
+  - New types `DriftDiff` and `FileDiff` exported from the package.
+  - New `computeDiff()` function exported for programmatic use.
+
+---
+
+## [0.3.0]
+
+### Added
+- `--ai` flag: outputs LLM-optimized JSON (`AIOutput`) designed to be pasted directly into Claude, GPT, or any other model as context. Issues are ranked by severity and effort — quick wins first. Each issue includes `fix_suggestion` and `effort` level. The output includes `recommended_action` generated from the scan.
+- `--fix` flag: shows inline fix suggestions in the console for each detected issue, rendered as a visual diff block.
+
+### Changed
+- `formatAIOutput()` added to `reporter.ts` — produces the `AIOutput` structure with `summary`, `priority_order`, and `context_for_ai`.
+
+---
+
+## [0.2.3]
+
+### Fixed
+- `npx @eduardbar/drift` now works correctly on Windows. The issue was that Node.js on Windows does not execute the shebang (`#!/usr/bin/env node`) in ES module `.js` files reliably. Added `bin/drift.js` as a thin wrapper with a dynamic `import()` that works cross-platform.
+
+---
+
+## [0.2.2]
+
+### Fixed
+- CI workflow was triggering a double publish on the same release. Removed the duplicate `push: tags` trigger — now uses only `release: published`. Added a guard step that checks `npm view @eduardbar/drift@$VERSION` before publishing to skip if already published.
+
+### Refactored
+- `formatMarkdown()` in `reporter.ts` split into smaller helper functions for readability.
+
+---
+
+## [0.2.1]
+
+### Added
+- `drift-ignore` comment support: add `// drift-ignore` on a line (or the line above it) to suppress that specific issue.
+- `drift-ignore-file` comment support: add `// drift-ignore-file` in the first 10 lines of a file to exclude the entire file from analysis. Used in `printer.ts` itself — its `console.log` calls are intentional CLI output, not debug leftovers.
+
+### Fixed
+- drift was reporting issues in its own `printer.ts` when run on itself. Fixed by adding `// drift-ignore-file` to that file.
+
+---
+
+## [0.2.0]
+
+### Added
+- ASCII score bar in console output (`█████████████░░░░░░░ 67/100`).
+- Executive summary header with total file count, error/warning/info counts, and top issues.
+- File count shown after scan completes.
+- `scoreToGrade`, `severityIcon`, and `scoreBar` extracted to `src/utils.ts` — shared between printer and reporter.
+
+### Changed
+- Console output restructured with cleaner visual hierarchy.
+
+---
+
+## [0.1.0]
+
+### Added
+- Initial release.
+- AST analysis engine using ts-morph.
+- 8 detection rules: `large-file`, `large-function`, `debug-leftover`, `dead-code`, `duplicate-function-name`, `any-abuse`, `catch-swallow`, `no-return-type`.
+- Score 0–100 per file and per project (average).
+- Console printer with color output using kleur.
+- Markdown reporter (`--output`).
+- Raw JSON output (`--json`).
+- CI integration via `--min-score` (exit code 1 if score exceeds threshold).
+- CLI entry point with Commander.js.
+- GitHub Actions workflow for automated npm publish on release.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our Commitment
+
+drift is a technical project. We keep discussion focused on code, architecture, and technical debt patterns.
+
+Everyone who participates — through issues, PRs, discussions, or comments — is expected to:
+
+- Be direct and specific. Vague complaints don't help anyone.
+- Criticize ideas, not people.
+- Provide actionable feedback when rejecting a PR or issue.
+- Assume good intent by default.
+
+## What we don't tolerate
+
+- Personal attacks, insults, or harassment of any kind.
+- Dismissing contributions without explanation.
+- Spam, self-promotion unrelated to drift, or off-topic debates.
+
+## Scope
+
+This applies in all project spaces: GitHub Issues, Pull Requests, Discussions, and any other channel where drift is represented.
+
+## Enforcement
+
+Violations can be reported to [ing.eduardbarrera@gmail.com](mailto:ing.eduardbarrera@gmail.com). All reports will be reviewed and responded to. Maintainers have final say on enforcement decisions.
+
+## Note
+
+This project does not adopt any third-party code of conduct document verbatim. These are our own rules, written to be simple and enforceable.

package/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to drift
+
+Thanks for taking the time. drift exists because ESLint solves correctness and SonarQube solves enterprise complexity — but nobody solved the middle: code that compiles, passes linting, and quietly accumulates into a codebase no one can maintain six months later.
+
+Every rule in drift was added because real developers kept finding the same pattern in AI-generated code and had no automated way to catch it. That's the contribution model: you see something repeatedly, you open an issue, we add a rule.
+
+**The gap drift fills:**
+
+| Tool | What it catches | What it misses |
+|------|-----------------|----------------|
+| ESLint | Correctness, style, per-file patterns | Cross-file dead code, architecture violations, complexity trends |
+| SonarQube | Enterprise security, deep complexity | Lightweight, fast, free for small teams |
+| knip | Unused exports and files | Structural health, AI-specific patterns, score |
+| **drift** | Structural debt, AI patterns, cross-file analysis, score | Style, correctness (intentionally) |
+
+## How to contribute
+
+### Report a bug
+
+Open an issue using the **Bug Report** template. Include:
+- The command you ran
+- What you expected vs what happened
+- Your Node.js version and OS
+
+### Suggest a new rule
+
+This is the most valuable contribution. If you keep seeing a specific AI-generated pattern that drift doesn't catch yet, open an issue using the **Rule Request** template with:
+- A short description of the pattern
+- A real code snippet that triggers it (anonymized is fine)
+- Why it's harmful or a sign of AI-generated debt
+
+### Submit a PR
+
+```bash
+# 1. Fork and clone
+git clone https://github.com/eduardbar/drift
+cd drift
+
+# 2. Install dependencies
+npm install
+
+# 3. Build
+npm run build
+
+# 4. Create a branch
+git checkout -b feat/rule-name
+# or
+git checkout -b fix/issue-description
+```
+
+#### Adding a new rule
+
+1. Add the rule weight in `RULE_WEIGHTS` in `src/analyzer.ts`:
+   ```typescript
+   const RULE_WEIGHTS: Record<string, number> = {
+     'your-rule-name': 10, // weight between 1 and 20
+   }
+   ```
+
+2. Implement the detection logic in `analyzeFile()` using ts-morph AST traversal.
+
+3. Add a fix suggestion in `src/printer.ts`:
+   ```typescript
+   const FIX_SUGGESTIONS: Record<string, string[]> = {
+     'your-rule-name': [
+       'First suggestion',
+       'Alternative suggestion',
+     ],
+   }
+   ```
+
+4. Update the rules table in `README.md`.
+
+5. Run drift on itself to make sure nothing breaks:
+   ```bash
+   node dist/cli.js scan ./src
+   ```
+
+6. Open a PR with a clear description of what the rule detects and why it matters.
+
+#### Commit convention
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(analyzer): add high-complexity rule for cyclomatic detection
+fix(printer): align snippet indentation for long file paths
+docs(readme): add rule description for deep-nesting
+```
+
+Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `chore`, `ci`, `test`
+
+### What makes a good rule
+
+A good drift rule:
+- Detects a **specific, reproducible** pattern — not a matter of style preference
+- Has a **measurable signal** that AI tools leave this more than humans do
+- Is **false-positive resistant** — it should almost never fire on intentional code
+- Can be **ignored with `// drift-ignore`** when the pattern is intentional
+
+### What drift is NOT
+
+drift is not a linter for style or correctness. That's ESLint's job and it does it well. drift does not replace ESLint — it runs alongside it.
+
+drift detects patterns that are:
+- Syntactically correct and pass linting
+- But accumulate into a codebase no one can maintain
+- Specifically amplified by AI code generation tools
+
+If your proposed rule overlaps with an existing ESLint rule (e.g. `no-unused-vars`, `complexity`, `no-empty`), it does not belong in drift — unless drift can do something ESLint fundamentally cannot (e.g. cross-file analysis, architectural context, project-wide scoring).
+
+The test: *"Could ESLint catch this with a single-file rule?"* If yes, it's probably not a drift rule.
+
+## Development setup
+
+```bash
+npm install       # install dependencies
+npm run build     # compile TypeScript → dist/
+npm run dev       # watch mode
+node dist/cli.js scan ./src  # run on the project itself
+```
+
+## Questions?
+
+Open a [Discussion](https://github.com/eduardbar/drift/discussions) — not an issue. Issues are for bugs and rule requests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eduard Barrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.