docutrack 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# DocuTrack
+
+**Plugin de Claude Code que documenta automáticamente lo que construyes.**
+
+DocuTrack engancha los lifecycle hooks de Claude Code para registrar cada archivo modificado y generar documentación técnica en tiempo real — sin interrumpir tu flujo de trabajo.
+
+---
+
+## Instalación
+
+```bash
+npx docutrack init
+```
+
+Detecta tu stack automáticamente (Next.js, FastAPI, Express, Go, monorepo) y configura todo en segundos.
+
+---
+
+## ¿Qué hace?
+
+- **Hook PostToolUse** — cada vez que Claude edita un archivo, lo encola automáticamente
+- **Hook Stop** — al terminar la sesión, el subagente `documentalista` genera los docs de todo lo pendiente
+- **Visor web** — interfaz tipo Notion en `localhost:4242` con sidebar, renderizado Markdown, API Explorer interactivo y Health Check
+- **Generación con IA** — escanea proyectos existentes y genera toda la documentación con un clic desde el visor
+- **Sin dependencias** — llama a la API de Anthropic directo via `https` nativo de Node.js
+
+---
+
+## Uso rápido
+
+```bash
+# Inicializar en tu proyecto
+npx docutrack init
+
+# Abrir el visor de documentación
+docutrack serve
+
+# Escanear un proyecto existente y generar docs
+# → Usar el botón "Regenerar docs" en el visor
+
+# Ver estado de cobertura
+docutrack status
+
+# Health check completo (drift, complejidad, stale)
+docutrack check
+```
+
+---
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `docutrack init` | Inicializa DocuTrack en el proyecto actual |
+| `docutrack serve` | Abre el visor web en el puerto 4242 |
+| `docutrack scan` | Encola todos los archivos fuente existentes |
+| `docutrack status` | Muestra cobertura, pendientes y docs desactualizados |
+| `docutrack check` | Health check: drift, complejidad, stale |
+| `docutrack analyze` | Detecta rutas y genera `docs/api/openapi.json` |
+| `docutrack onboard` | Genera `docs/ONBOARDING.md` |
+| `docutrack export` | Exporta a Mintlify o Docusaurus |
+| `docutrack badge` | Genera badge SVG de cobertura |
+
+---
+
+## Templates soportados
+
+Detección automática o manual con `--template`:
+
+- `nextjs` — Next.js App Router
+- `fastapi` — Python FastAPI
+- `express` — Node.js Express / Fastify
+- `monorepo` — Turborepo / pnpm workspaces
+- `go` — Go modules
+
+---
+
+## Estructura generada
+
+```
+docs/
+├── modules/        ← un .md por módulo/componente
+├── api/            ← docs de rutas API + openapi.json
+└── decisions/      ← Architecture Decision Records (ADRs)
+ARCHITECTURE.md     ← vista general del proyecto (auto-generada con IA)
+```
+
+---
+
+## Visor web
+
+```bash
+docutrack serve
+# → http://localhost:4242
+```
+
+Incluye:
+- Sidebar con todos los módulos, decisiones y rutas API
+- **API Explorer** interactivo estilo Swagger
+- **Health Check**: drift de código vs docs, mapa de complejidad
+- **Generación desde la UI**: escanea y documenta sin abrir la terminal
+- Toggle de idioma Español / English
+
+---
+
+## Requisitos
+
+- Node.js 18+
+- Claude Code CLI
+- `ANTHROPIC_API_KEY` en el entorno o en `.env.local` (solo para generación con IA)
+
+---
+
+## Licencia
+
+MIT — [mnovoaq](https://github.com/mnovoaq)

package/bin/docutrack.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const [, , command, ...args] = process.argv
+
+const commands = {
+  init: () => require('../src/commands/init'),
+  serve: () => require('../src/commands/serve'),
+  analyze: () => require('../src/commands/analyze'),
+  status: () => require('../src/commands/status'),
+  clear: () => require('../src/commands/clear'),
+  badge: () => require('../src/commands/badge'),
+  export: () => require('../src/commands/export'),
+  check: () => require('../src/commands/check'),
+  onboard: () => require('../src/commands/onboard'),
+  scan: () => require('../src/commands/scan'),
+}
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(`
+docutrack — Claude Code documentation plugin
+
+Usage:
+  npx docutrack init                      Initialize DocuTrack in the current project
+  docutrack init --template <name>        Init with a specific stack template
+  docutrack serve                         Start the documentation web viewer (port 4242)
+  docutrack analyze                       Scan routes and generate docs/api/openapi.json
+  docutrack status                        Show coverage, pending files, and stale docs
+  docutrack status --json                 Machine-readable output for CI
+  docutrack badge                         Generate docs/badge.svg for your README
+  docutrack clear                         Clear the documentation queue
+  docutrack export --format mintlify      Export docs to Mintlify format
+  docutrack export --format docusaurus    Export docs to Docusaurus format
+  docutrack export --format <f> --out <dir>   Export to a custom output directory
+  docutrack check                             Full health: drift, complexity, stale docs
+  docutrack check --json                      Machine-readable health report for CI
+  docutrack onboard                           Generate docs/ONBOARDING.md
+  docutrack onboard --force                   Regenerate ONBOARDING.md
+  docutrack scan                              Queue ALL existing source files for initial documentation
+  docutrack scan --dry-run                    Preview what would be queued
+
+Templates (auto-detected from project files):
+  nextjs, fastapi, express, monorepo, go
+
+Options:
+  --help, -h              Show this help message
+  --version, -v           Show version
+`)
+  process.exit(0)
+}
+
+if (command === '--version' || command === '-v') {
+  console.log(require('../package.json').version)
+  process.exit(0)
+}
+
+const handler = commands[command]
+if (!handler) {
+  console.error(`Unknown command: ${command}\nRun "docutrack --help" for usage.`)
+  process.exit(1)
+}
+
+handler().run(args).catch(err => {
+  console.error(`\nError: ${err.message}`)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "docutrack",
+  "version": "0.1.0",
+  "description": "Claude Code plugin that forces AI agents to document what they build — automatically.",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "documentation",
+    "ai-agents",
+    "architecture",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./bin/docutrack.js",
+  "bin": {
+    "docutrack": "bin/docutrack.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mnovoaq/docutrack.git"
+  },
+  "homepage": "https://github.com/mnovoaq/docutrack#readme",
+  "bugs": {
+    "url": "https://github.com/mnovoaq/docutrack/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js"
+  }
+}

package/src/analyzer/complexity.js

@@ -0,0 +1,145 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const THRESHOLDS = {
+  lines: { warn: 200, critical: 400 },
+  exports: { warn: 10, critical: 20 },
+  complexity: { warn: 15, critical: 30 },
+  maxNesting: { warn: 4, critical: 6 },
+}
+
+function analyzeFile(filePath) {
+  let content
+  try { content = fs.readFileSync(filePath, 'utf8') } catch { return null }
+
+  const ext = path.extname(filePath).slice(1)
+  const lines = content.split('\n').filter(l => l.trim()).length // non-blank lines
+
+  const metrics = {
+    file: filePath,
+    lines,
+    exports: countExports(content, ext),
+    complexity: countCyclomaticApprox(content),
+    maxNesting: countMaxNesting(content, ext),
+    warnings: [],
+  }
+
+  // Flag violations
+  if (metrics.lines >= THRESHOLDS.lines.critical) metrics.warnings.push({ level: 'critical', message: `${metrics.lines} lines — consider splitting this module` })
+  else if (metrics.lines >= THRESHOLDS.lines.warn) metrics.warnings.push({ level: 'warn', message: `${metrics.lines} lines — getting large` })
+
+  if (metrics.exports >= THRESHOLDS.exports.critical) metrics.warnings.push({ level: 'critical', message: `${metrics.exports} exports — wide public API` })
+  else if (metrics.exports >= THRESHOLDS.exports.warn) metrics.warnings.push({ level: 'warn', message: `${metrics.exports} exports` })
+
+  if (metrics.complexity >= THRESHOLDS.complexity.critical) metrics.warnings.push({ level: 'critical', message: `complexity ${metrics.complexity} — high branching` })
+  else if (metrics.complexity >= THRESHOLDS.complexity.warn) metrics.warnings.push({ level: 'warn', message: `complexity ${metrics.complexity}` })
+
+  if (metrics.maxNesting >= THRESHOLDS.maxNesting.critical) metrics.warnings.push({ level: 'critical', message: `nesting depth ${metrics.maxNesting} — deeply nested code` })
+  else if (metrics.maxNesting >= THRESHOLDS.maxNesting.warn) metrics.warnings.push({ level: 'warn', message: `nesting depth ${metrics.maxNesting}` })
+
+  metrics.score = computeScore(metrics)
+  return metrics
+}
+
+function countExports(content, ext) {
+  if (ext === 'py') {
+    return (content.match(/^(?:def|class)\s+[A-Z][A-Za-z0-9_]*/gm) || []).length
+  }
+  if (ext === 'go') {
+    return (content.match(/^(?:func|type|var|const)\s+[A-Z]/gm) || []).length
+  }
+  // JS/TS
+  const patterns = [
+    /export\s+(?:async\s+)?function\s+/g,
+    /export\s+(?:const|let|var)\s+/g,
+    /export\s+class\s+/g,
+    /exports\.[A-Za-z_$]/g,
+  ]
+  const moduleExports = content.match(/module\.exports\s*=\s*\{([^}]+)\}/)?.[1]
+  const fromModule = moduleExports
+    ? moduleExports.split(',').filter(s => /[A-Za-z_$]/.test(s.trim())).length
+    : 0
+  return patterns.reduce((acc, re) => acc + (content.match(re) || []).length, 0) + fromModule
+}
+
+function countCyclomaticApprox(content) {
+  // Count decision points: if, else if, for, while, case, catch, ternary, &&, ||
+  const DECISION_RE = /\b(if|else\s+if|for|while|case|catch)\b|\?(?!:)|&&|\|\|/g
+  return (content.match(DECISION_RE) || []).length
+}
+
+function countMaxNesting(content, ext) {
+  if (ext === 'py') return countPythonNesting(content)
+  // Brace-based languages
+  let depth = 0
+  let max = 0
+  for (const ch of content) {
+    if (ch === '{') { depth++; if (depth > max) max = depth }
+    else if (ch === '}') depth = Math.max(0, depth - 1)
+  }
+  return max
+}
+
+function countPythonNesting(content) {
+  let max = 0
+  for (const line of content.split('\n')) {
+    const indent = line.match(/^(\s*)/)?.[1].length || 0
+    const depth = Math.floor(indent / 4)
+    if (depth > max) max = depth
+  }
+  return max
+}
+
+function computeScore(m) {
+  // 0–100, lower = worse
+  let score = 100
+  score -= Math.max(0, m.lines - THRESHOLDS.lines.warn) * 0.1
+  score -= Math.max(0, m.exports - THRESHOLDS.exports.warn) * 2
+  score -= Math.max(0, m.complexity - THRESHOLDS.complexity.warn) * 1.5
+  score -= Math.max(0, m.maxNesting - THRESHOLDS.maxNesting.warn) * 5
+  return Math.round(Math.max(0, Math.min(100, score)))
+}
+
+function analyzeComplexity(projectRoot) {
+  const results = []
+  const SCAN_DIRS = ['src', 'lib', 'app', 'pkg', 'internal']
+  const EXTS = new Set(['.js', '.ts', '.mjs', '.py', '.go', '.jsx', '.tsx'])
+  const IGNORE = new Set(['node_modules', '.git', 'dist', 'build', '__pycache__', '.docutrack', 'docs'])
+
+  for (const dir of SCAN_DIRS) {
+    const full = path.join(projectRoot, dir)
+    if (!fs.existsSync(full)) continue
+    walk(full, results, EXTS, IGNORE)
+  }
+
+  // Sort by score ascending (worst first)
+  results.sort((a, b) => a.score - b.score)
+
+  return {
+    files: results,
+    summary: {
+      total: results.length,
+      critical: results.filter(f => f.warnings.some(w => w.level === 'critical')).length,
+      warnings: results.filter(f => f.warnings.some(w => w.level === 'warn') && !f.warnings.some(w => w.level === 'critical')).length,
+      healthy: results.filter(f => f.warnings.length === 0).length,
+    },
+    thresholds: THRESHOLDS,
+  }
+}
+
+function walk(dir, acc, exts, ignore, depth = 0) {
+  if (depth > 8) return
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (ignore.has(entry.name)) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) walk(full, acc, exts, ignore, depth + 1)
+    else if (entry.isFile() && exts.has(path.extname(entry.name))) {
+      const m = analyzeFile(full)
+      if (m) acc.push(m)
+    }
+  }
+}
+
+module.exports = { analyzeComplexity, analyzeFile, THRESHOLDS }

package/src/analyzer/detect.js

@@ -0,0 +1,124 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const JS_EXTS = ['.js', '.ts', '.mjs', '.cjs']
+const PY_EXTS = ['.py']
+const GO_EXTS = ['.go']
+
+const JS_ROUTE_DIRS = [
+  'routes', 'src/routes',
+  'api', 'src/api',
+  'controllers', 'src/controllers',
+  'handlers', 'src/handlers',
+  'routers', 'src/routers',
+]
+
+const PY_ROUTE_DIRS = ['routers', 'app/routers', 'api', 'app/api', 'routes', 'app/routes']
+const GO_ROUTE_DIRS = ['internal/handlers', 'handlers', 'api', 'cmd']
+
+function detectFramework(root) {
+  // Python project?
+  const isPython = fs.existsSync(path.join(root, 'requirements.txt'))
+    || fs.existsSync(path.join(root, 'pyproject.toml'))
+    || fs.existsSync(path.join(root, 'setup.py'))
+  if (isPython) {
+    const isFastAPI = checkFileContent(root, ['requirements.txt', 'pyproject.toml', 'Pipfile'], 'fastapi')
+    const framework = isFastAPI ? 'fastapi' : 'python'
+    return { framework, name: path.basename(root), version: '0.0.0', routeFiles: findFiles(root, PY_ROUTE_DIRS, PY_EXTS), lang: 'python' }
+  }
+
+  // Go project?
+  if (fs.existsSync(path.join(root, 'go.mod'))) {
+    const modContent = fs.readFileSync(path.join(root, 'go.mod'), 'utf8')
+    const modMatch = modContent.match(/^module\s+(\S+)/m)
+    return { framework: 'go', name: modMatch?.[1]?.split('/').pop() || path.basename(root), version: '0.0.0', routeFiles: findFiles(root, GO_ROUTE_DIRS, GO_EXTS), lang: 'go' }
+  }
+
+  // Node.js project
+  let pkg = {}
+  try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')) } catch { /* ok */ }
+
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }
+  const name = pkg.name || path.basename(root)
+  const version = pkg.version || '0.0.0'
+
+  // Next.js — detect API routes in app/ or pages/api/
+  if (deps.next) {
+    return { framework: 'nextjs', name, version, routeFiles: findNextJsRoutes(root), lang: 'js' }
+  }
+
+  let framework = 'generic'
+  if (deps.express || deps['@types/express']) framework = 'express'
+  else if (deps.fastify) framework = 'fastify'
+  else if (deps.koa || deps['koa-router']) framework = 'koa'
+  else if (deps.hapi || deps['@hapi/hapi']) framework = 'hapi'
+
+  const routeFiles = findFiles(root, JS_ROUTE_DIRS, JS_EXTS)
+  if (routeFiles.length === 0) {
+    // Shallow scan src/
+    const srcDir = path.join(root, 'src')
+    if (fs.existsSync(srcDir)) walkFiles(srcDir, routeFiles, JS_EXTS, 2)
+  }
+
+  return { framework, name, version, routeFiles, lang: 'js' }
+}
+
+function findNextJsRoutes(root) {
+  const files = []
+  // App router: app/**/route.{js,ts}
+  const appDir = path.join(root, 'app')
+  if (fs.existsSync(appDir)) {
+    walkFilesWhere(appDir, files, JS_EXTS, f => path.basename(f, path.extname(f)) === 'route')
+  }
+  // Pages router: pages/api/**/*.{js,ts}
+  const pagesApi = path.join(root, 'pages', 'api')
+  if (fs.existsSync(pagesApi)) walkFiles(pagesApi, files, JS_EXTS, 10)
+
+  return files
+}
+
+function findFiles(root, dirs, exts) {
+  const found = []
+  for (const dir of dirs) {
+    const full = path.join(root, dir)
+    if (fs.existsSync(full)) walkFiles(full, found, exts)
+  }
+  return found
+}
+
+function walkFiles(dir, acc, exts, maxDepth = 10, depth = 0) {
+  if (depth > maxDepth) return
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+      walkFiles(full, acc, exts, maxDepth, depth + 1)
+    } else if (entry.isFile() && exts.includes(path.extname(entry.name))) {
+      acc.push(full)
+    }
+  }
+}
+
+function walkFilesWhere(dir, acc, exts, predicate, maxDepth = 10, depth = 0) {
+  if (depth > maxDepth) return
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory() && !entry.name.startsWith('.')) {
+      walkFilesWhere(full, acc, exts, predicate, maxDepth, depth + 1)
+    } else if (entry.isFile() && exts.includes(path.extname(entry.name)) && predicate(full)) {
+      acc.push(full)
+    }
+  }
+}
+
+function checkFileContent(root, files, keyword) {
+  for (const f of files) {
+    const full = path.join(root, f)
+    if (!fs.existsSync(full)) continue
+    if (fs.readFileSync(full, 'utf8').toLowerCase().includes(keyword)) return true
+  }
+  return false
+}
+
+module.exports = { detectFramework }

package/src/analyzer/index.js

@@ -0,0 +1,121 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { detectFramework } = require('./detect')
+const expressParser = require('./parsers/express')
+const fastapiParser = require('./parsers/fastapi')
+
+function getParser(framework) {
+  if (framework === 'fastapi' || framework === 'python') return fastapiParser
+  // Express, Fastify, Koa, Next.js, Go, generic — all use JS-style regex for now
+  return expressParser
+}
+
+function analyze(projectRoot) {
+  const { framework, name, version, routeFiles, lang } = detectFramework(projectRoot)
+  const parser = getParser(framework)
+  const allRoutes = []
+
+  for (const file of routeFiles) {
+    let content
+    try { content = fs.readFileSync(file, 'utf8') } catch { continue }
+
+    const routes = parser.parse(file, content)
+
+    // For Next.js App Router route files, extract HTTP exports
+    if (framework === 'nextjs') {
+      const nextRoutes = parseNextJsRoute(file, content, projectRoot)
+      allRoutes.push(...nextRoutes)
+    } else {
+      allRoutes.push(...routes)
+    }
+  }
+
+  return buildSpec(name, version, allRoutes, framework)
+}
+
+function parseNextJsRoute(filePath, content, root) {
+  const routes = []
+  const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
+
+  // Detect exported HTTP methods: export async function GET(...) or export { GET }
+  const exportRe = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s*\(/g
+  const exportConst = /export\s+const\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s*=/g
+
+  const foundMethods = new Set()
+  let m
+  while ((m = exportRe.exec(content)) !== null) foundMethods.add(m[1])
+  while ((m = exportConst.exec(content)) !== null) foundMethods.add(m[1])
+
+  if (foundMethods.size === 0) return routes
+
+  // Derive the API path from the file path
+  const rel = path.relative(root, filePath).replace(/\\/g, '/')
+  let apiPath = '/'
+
+  if (rel.startsWith('app/')) {
+    apiPath = '/' + rel
+      .replace(/^app\//, '')
+      .replace(/\/route\.[jt]s$/, '')
+      .replace(/\(([^)]+)\)\//g, '') // remove route groups like (auth)/
+      || '/'
+    // Convert Next.js [param] to OpenAPI {param}
+    apiPath = '/' + apiPath.replace(/\[([^\]]+)\]/g, '{$1}').replace(/^\/+/, '')
+  } else if (rel.startsWith('pages/api/')) {
+    apiPath = '/' + rel.replace(/^pages\//, '').replace(/\.[jt]sx?$/, '')
+      .replace(/\[([^\]]+)\]/g, '{$1}')
+  }
+
+  const tag = apiPath.split('/').filter(Boolean)[1] || 'api'
+
+  for (const method of foundMethods) {
+    const params = (apiPath.match(/\{([^}]+)\}/g) || []).map(p => ({
+      name: p.slice(1, -1), in: 'path', required: true, schema: { type: 'string' },
+    }))
+    const route = {
+      method,
+      path: apiPath,
+      tag,
+      summary: '',
+      operationId: method.toLowerCase() + apiPath.replace(/[^a-zA-Z0-9]/g, '_').replace(/_+/g, '_'),
+      parameters: params,
+      responses: { '200': { description: 'OK' } },
+    }
+    if (['POST', 'PUT', 'PATCH'].includes(method)) {
+      route.requestBody = { content: { 'application/json': { schema: { type: 'object' } } } }
+    }
+    routes.push(route)
+  }
+
+  return routes
+}
+
+function buildSpec(name, version, routes, framework) {
+  const paths = {}
+
+  for (const route of routes) {
+    if (!paths[route.path]) paths[route.path] = {}
+    const method = route.method.toLowerCase()
+    if (paths[route.path][method]) continue
+
+    const operation = { operationId: route.operationId, summary: route.summary, tags: [route.tag] }
+    if (route.parameters?.length) operation.parameters = route.parameters
+    if (route.requestBody) operation.requestBody = route.requestBody
+    operation.responses = route.responses
+
+    paths[route.path][method] = operation
+  }
+
+  return {
+    openapi: '3.0.3',
+    info: {
+      title: name,
+      version,
+      description: `API documentation auto-generated by DocuTrack. Framework: ${framework}.`,
+    },
+    paths,
+  }
+}
+
+module.exports = { analyze }