docutrack 0.1.0

package/src/analyzer/parsers/express.js

@@ -0,0 +1,110 @@
+'use strict'
+
+const path = require('path')
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']
+
+// Matches: (app|router|server|this).(method)('path' or "path" or `path`)
+const ROUTE_RE = /(?:app|router|server|this|fastify|koa)\s*\.\s*(get|post|put|patch|delete|options|head)\s*\(\s*[`'"](\/[^`'"]*)[`'"]/gi
+
+// Matches: .route('/path').get(h).post(h)...
+const ROUTE_CHAIN_PATH_RE = /\.route\s*\(\s*[`'"](\/[^`'"]*)[`'"]\s*\)/g
+const ROUTE_CHAIN_METHOD_RE = /\.\s*(get|post|put|patch|delete|options|head)\s*\(/gi
+
+function parse(filePath, content) {
+  const tag = inferTag(filePath)
+  const routes = []
+  const seen = new Set()
+
+  // Standard method routes
+  let m
+  const re = new RegExp(ROUTE_RE.source, 'gi')
+  while ((m = re.exec(content)) !== null) {
+    const method = m[1].toUpperCase()
+    const rawPath = m[2]
+    const opPath = toOpenApiPath(rawPath)
+    const key = `${method}:${opPath}`
+    if (!seen.has(key)) {
+      seen.add(key)
+      routes.push(makeRoute(method, opPath, tag))
+    }
+  }
+
+  // .route('/path').get().post() chains
+  const chainRe = new RegExp(ROUTE_CHAIN_PATH_RE.source, 'g')
+  while ((m = chainRe.exec(content)) !== null) {
+    const opPath = toOpenApiPath(m[1])
+    // Grab the segment after this .route(...) match and find chained methods
+    const segment = content.slice(m.index + m[0].length, m.index + m[0].length + 200)
+    const methodRe = new RegExp(ROUTE_CHAIN_METHOD_RE.source, 'g')
+    let mm
+    while ((mm = methodRe.exec(segment)) !== null) {
+      const method = mm[1].toUpperCase()
+      if (!HTTP_METHODS.includes(method.toLowerCase())) continue
+      const key = `${method}:${opPath}`
+      if (!seen.has(key)) {
+        seen.add(key)
+        routes.push(makeRoute(method, opPath, tag))
+      }
+    }
+  }
+
+  return routes
+}
+
+function makeRoute(method, opPath, tag) {
+  const params = extractPathParams(opPath)
+  const route = {
+    method,
+    path: opPath,
+    tag,
+    summary: '',
+    operationId: toOperationId(method, opPath),
+    parameters: params.map(p => ({
+      name: p,
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    })),
+    responses: { '200': { description: 'OK' } },
+  }
+  if (['POST', 'PUT', 'PATCH'].includes(method)) {
+    route.requestBody = {
+      content: { 'application/json': { schema: { type: 'object' } } },
+    }
+  }
+  return route
+}
+
+function toOpenApiPath(expressPath) {
+  return expressPath.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}')
+}
+
+function extractPathParams(openApiPath) {
+  const params = []
+  const re = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g
+  let m
+  while ((m = re.exec(openApiPath)) !== null) params.push(m[1])
+  return params
+}
+
+function inferTag(filePath) {
+  const base = path.basename(filePath, path.extname(filePath))
+  return base
+    .replace(/\.routes?$/, '').replace(/\.controller$/, '').replace(/\.handler$/, '')
+    .replace(/[-_]/g, ' ')
+    .split(' ')[0]
+    .toLowerCase()
+}
+
+function toOperationId(method, opPath) {
+  const parts = opPath
+    .replace(/\{([^}]+)\}/g, (_, name) => 'By' + name.charAt(0).toUpperCase() + name.slice(1))
+    .replace(/^\//, '').split('/')
+    .filter(Boolean)
+    .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+  return method.toLowerCase() + (parts || 'Root')
+}
+
+module.exports = { parse }

package/src/analyzer/parsers/fastapi.js

@@ -0,0 +1,89 @@
+'use strict'
+
+const path = require('path')
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']
+
+// @app.get('/path') or @router.post('/path') or @app_v2.delete('/path/{id}')
+const DECORATOR_RE = /@\w+\.(get|post|put|patch|delete|options|head)\s*\(\s*["'](\/[^"']+)["']/gi
+
+// async def function_name — to infer operation name
+const DEF_RE = /(?:async\s+)?def\s+(\w+)\s*\(/g
+
+function parse(filePath, content) {
+  const tag = inferTag(filePath)
+  const routes = []
+  const seen = new Set()
+
+  // Collect function names (for operationId inference)
+  const functions = []
+  let fm
+  const defRe = new RegExp(DEF_RE.source, 'g')
+  while ((fm = defRe.exec(content)) !== null) functions.push({ name: fm[1], index: fm.index })
+
+  let m
+  const re = new RegExp(DECORATOR_RE.source, 'gi')
+  while ((m = re.exec(content)) !== null) {
+    const method = m[1].toUpperCase()
+    const opPath = m[2] // FastAPI already uses {param} syntax
+
+    const key = `${method}:${opPath}`
+    if (seen.has(key)) continue
+    seen.add(key)
+
+    // Find the function that follows this decorator
+    const nearestFn = functions.find(f => f.index > m.index)
+    const operationId = nearestFn?.name || toOperationId(method, opPath)
+
+    const params = extractPathParams(opPath)
+    const route = {
+      method,
+      path: opPath,
+      tag,
+      summary: '',
+      operationId,
+      parameters: params.map(p => ({
+        name: p,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      })),
+      responses: { '200': { description: 'OK' } },
+    }
+
+    if (['POST', 'PUT', 'PATCH'].includes(method)) {
+      route.requestBody = {
+        content: { 'application/json': { schema: { type: 'object' } } },
+      }
+    }
+
+    routes.push(route)
+  }
+
+  return routes
+}
+
+function extractPathParams(p) {
+  const params = []
+  const re = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g
+  let m
+  while ((m = re.exec(p)) !== null) params.push(m[1])
+  return params
+}
+
+function inferTag(filePath) {
+  return path.basename(filePath, path.extname(filePath))
+    .replace(/[-_]/g, ' ').split(' ')[0].toLowerCase()
+}
+
+function toOperationId(method, opPath) {
+  const parts = opPath
+    .replace(/\{([^}]+)\}/g, (_, n) => 'By' + n.charAt(0).toUpperCase() + n.slice(1))
+    .replace(/^\//, '').split('/')
+    .filter(Boolean)
+    .map(p => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('')
+  return method.toLowerCase() + (parts || 'Root')
+}
+
+module.exports = { parse }

package/src/commands/analyze.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { analyze } = require('../analyzer/index')
+
+const OUT_PATH = path.join('docs', 'api', 'openapi.json')
+
+async function run(args) {
+  const projectRoot = process.cwd()
+
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const quiet = args.includes('--quiet') || args.includes('-q')
+
+  if (!quiet) console.log('\nDocuTrack — analyzing project routes...\n')
+
+  const spec = analyze(projectRoot)
+  const endpointCount = Object.values(spec.paths).reduce((n, p) => n + Object.keys(p).length, 0)
+
+  if (!quiet) {
+    console.log(`  Project      : ${spec.info.title}`)
+    console.log(`  Framework    : ${spec.info.description.match(/Framework detected: (.+)\./)?.[1] || 'unknown'}`)
+    console.log(`  Endpoints    : ${endpointCount}`)
+    console.log(`  Output       : ${OUT_PATH}\n`)
+  }
+
+  const outDir = path.dirname(OUT_PATH)
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true })
+  fs.writeFileSync(OUT_PATH, JSON.stringify(spec, null, 2))
+
+  if (!quiet) {
+    if (endpointCount === 0) {
+      console.log('  No routes detected. Make sure your routes are in one of:')
+      console.log('  routes/, src/routes/, api/, src/api/, controllers/, src/controllers/\n')
+    } else {
+      console.log(`  Done. Open "docutrack serve" and click API Explorer to browse.\n`)
+    }
+  }
+
+  return spec
+}
+
+module.exports = { run }

package/src/commands/badge.js

@@ -0,0 +1,79 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { read: readQueue } = require('../utils/queue')
+
+const OUT_PATH = path.join('docs', 'badge.svg')
+
+function coverageColor(pct) {
+  if (pct >= 80) return '#22c55e' // green
+  if (pct >= 60) return '#f59e0b' // amber
+  if (pct >= 40) return '#f97316' // orange
+  return '#ef4444'                // red
+}
+
+function makeSvg(pct) {
+  const label = 'docs'
+  const value = `${pct}%`
+  const labelW = 38
+  const valueW = value.length <= 3 ? 32 : value.length <= 4 ? 38 : 44
+  const totalW = labelW + valueW
+  const color = coverageColor(pct)
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalW}" height="20" role="img" aria-label="docs: ${pct}%">
+  <title>docs: ${pct}%</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${totalW}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelW}" height="20" fill="#555"/>
+    <rect x="${labelW}" width="${valueW}" height="20" fill="${color}"/>
+    <rect width="${totalW}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110">
+    <text x="${Math.round(labelW / 2 * 10)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(labelW - 10) * 10}" lengthAdjust="spacing">${label}</text>
+    <text x="${Math.round(labelW / 2 * 10)}" y="140" transform="scale(.1)" textLength="${(labelW - 10) * 10}" lengthAdjust="spacing">${label}</text>
+    <text x="${Math.round((labelW + valueW / 2) * 10)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(valueW - 10) * 10}" lengthAdjust="spacing">${value}</text>
+    <text x="${Math.round((labelW + valueW / 2) * 10)}" y="140" transform="scale(.1)" textLength="${(valueW - 10) * 10}" lengthAdjust="spacing">${value}</text>
+  </g>
+</svg>`
+}
+
+async function run() {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const queue = readQueue()
+  const pending = queue.pending?.length || 0
+
+  // Count doc files
+  const docsDir = 'docs'
+  let docCount = 0
+  function walkDocs(dir) {
+    if (!fs.existsSync(dir)) return
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) walkDocs(path.join(dir, e.name))
+      else if (e.name.endsWith('.md') && e.name !== '.gitkeep') docCount++
+    }
+  }
+  walkDocs(docsDir)
+
+  const total = docCount + pending
+  const pct = total > 0 ? Math.round((docCount / total) * 100) : 100
+
+  const svg = makeSvg(pct)
+  const outDir = path.dirname(OUT_PATH)
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true })
+  fs.writeFileSync(OUT_PATH, svg)
+
+  console.log(`\nBadge generated: ${OUT_PATH}  (coverage: ${pct}%)`)
+  console.log('\nAdd to your README:')
+  console.log(`  ![DocuTrack](./docs/badge.svg)\n`)
+}
+
+module.exports = { run }

package/src/commands/check.js

@@ -0,0 +1,187 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { findStale } = require('../utils/stale')
+const { analyzeDrift } = require('../utils/drift')
+const { analyzeComplexity } = require('../analyzer/complexity')
+const { read: readQueue } = require('../utils/queue')
+
+const RESET = '\x1b[0m'
+const RED = '\x1b[31m'
+const YELLOW = '\x1b[33m'
+const GREEN = '\x1b[32m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+
+function color(level, text) {
+  if (level === 'critical') return `${RED}${text}${RESET}`
+  if (level === 'warn') return `${YELLOW}${text}${RESET}`
+  return `${GREEN}${text}${RESET}`
+}
+
+async function run(args) {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const isJson = args.includes('--json')
+  const isCI = args.includes('--ci')
+  const root = process.cwd()
+
+  if (!isJson) console.log(`\n${BOLD}DocuTrack Health Check${RESET}\n${'─'.repeat(52)}`)
+
+  // ── 1. Queue status ────────────────────────────────────
+  const queue = readQueue(root)
+  const pendingCount = queue.pending.length
+
+  // ── 2. Stale docs ──────────────────────────────────────
+  const stale = findStale(root)
+
+  // ── 3. Drift analysis ─────────────────────────────────
+  let driftResults = []
+  try { driftResults = analyzeDrift(root) } catch { /* no docs yet */ }
+
+  // ── 4. Complexity ──────────────────────────────────────
+  let complexityReport = { files: [], summary: { total: 0, critical: 0, warnings: 0, healthy: 0 } }
+  try { complexityReport = analyzeComplexity(root) } catch { /* no src yet */ }
+
+  const criticalFiles = complexityReport.files.filter(f => f.warnings.some(w => w.level === 'critical'))
+  const warnFiles = complexityReport.files.filter(f =>
+    f.warnings.some(w => w.level === 'warn') && !f.warnings.some(w => w.level === 'critical')
+  )
+
+  // ── JSON output for CI ─────────────────────────────────
+  if (isJson) {
+    const report = {
+      pending: pendingCount,
+      stale: stale.length,
+      drift: driftResults.map(d => ({ module: d.module, severity: d.severity, undocumented: d.undocumented, orphaned: d.orphaned })),
+      complexity: { summary: complexityReport.summary, critical: criticalFiles.map(f => ({ file: f.file, score: f.score, warnings: f.warnings })) },
+      ok: pendingCount === 0 && stale.length === 0 && driftResults.filter(d => d.severity === 'high').length === 0 && criticalFiles.length === 0,
+    }
+    console.log(JSON.stringify(report, null, 2))
+    if (!report.ok && isCI) process.exit(1)
+    return
+  }
+
+  // ── Human-readable output ──────────────────────────────
+
+  // Pending
+  const pendingLabel = pendingCount === 0
+    ? `${GREEN}✓ 0 pending${RESET}`
+    : `${YELLOW}⚠ ${pendingCount} files need documentation${RESET}`
+  console.log(`  Queue       : ${pendingLabel}`)
+
+  // Stale
+  const staleLabel = stale.length === 0
+    ? `${GREEN}✓ 0 stale docs${RESET}`
+    : `${YELLOW}⚠ ${stale.length} stale${RESET}`
+  console.log(`  Stale docs  : ${staleLabel}`)
+
+  // Drift
+  const highDrift = driftResults.filter(d => d.severity === 'high').length
+  const driftLabel = driftResults.length === 0
+    ? `${GREEN}✓ no drift${RESET}`
+    : highDrift > 0
+      ? `${RED}✗ ${highDrift} high-drift module${highDrift !== 1 ? 's' : ''}${RESET}`
+      : `${YELLOW}⚠ ${driftResults.length} module${driftResults.length !== 1 ? 's' : ''} drifted${RESET}`
+  console.log(`  Doc drift   : ${driftLabel}`)
+
+  // Complexity
+  const complexityLabel = criticalFiles.length === 0
+    ? warnFiles.length === 0
+      ? `${GREEN}✓ ${complexityReport.summary.total} files healthy${RESET}`
+      : `${YELLOW}⚠ ${warnFiles.length} complex${RESET}`
+    : `${RED}✗ ${criticalFiles.length} critical${RESET}${criticalFiles.length > 0 && warnFiles.length > 0 ? ` + ${warnFiles.length} warnings` : ''}`
+  console.log(`  Complexity  : ${complexityLabel}`)
+
+  // ── Detail sections ────────────────────────────────────
+
+  if (stale.length > 0) {
+    console.log(`\n${BOLD}Stale Docs${RESET}`)
+    for (const s of stale.slice(0, 8)) {
+      const age = formatMs(s.staleSinceMs)
+      console.log(`  ${YELLOW}${s.doc}${RESET}  ${DIM}(${age} behind)${RESET}`)
+    }
+    if (stale.length > 8) console.log(`  ${DIM}…and ${stale.length - 8} more${RESET}`)
+  }
+
+  if (driftResults.length > 0) {
+    console.log(`\n${BOLD}Documentation Drift${RESET}`)
+    for (const d of driftResults.slice(0, 6)) {
+      console.log(`  ${color(d.severity, d.severity.toUpperCase())}  ${BOLD}${d.module}${RESET}  ${DIM}← ${d.sourceFile}${RESET}`)
+      if (d.undocumented.length > 0) {
+        console.log(`    ${RED}+undocumented${RESET}: ${d.undocumented.slice(0, 5).join(', ')}${d.undocumented.length > 5 ? ` …+${d.undocumented.length - 5}` : ''}`)
+      }
+      if (d.orphaned.length > 0) {
+        console.log(`    ${DIM}-orphaned${RESET}:    ${d.orphaned.slice(0, 5).join(', ')}${d.orphaned.length > 5 ? ` …+${d.orphaned.length - 5}` : ''}`)
+      }
+    }
+    if (driftResults.length > 6) console.log(`  ${DIM}…and ${driftResults.length - 6} more${RESET}`)
+  }
+
+  if (criticalFiles.length > 0 || warnFiles.length > 0) {
+    console.log(`\n${BOLD}Complexity${RESET}`)
+    const toShow = [...criticalFiles.slice(0, 4), ...warnFiles.slice(0, 3)]
+    for (const f of toShow) {
+      const rel = path.relative(root, f.file)
+      const level = f.warnings.some(w => w.level === 'critical') ? 'critical' : 'warn'
+      const msgs = f.warnings.map(w => w.message).join('  ·  ')
+      console.log(`  ${color(level, level === 'critical' ? '✗' : '⚠')}  ${rel}  ${DIM}(score ${f.score})${RESET}`)
+      console.log(`     ${DIM}${msgs}${RESET}`)
+    }
+    const shown = Math.min(4, criticalFiles.length) + Math.min(3, warnFiles.length)
+    const total = criticalFiles.length + warnFiles.length
+    if (total > shown) console.log(`  ${DIM}…and ${total - shown} more${RESET}`)
+  }
+
+  // ── Suggestions ────────────────────────────────────────
+  const suggestions = buildSuggestions({ pendingCount, stale, driftResults, criticalFiles })
+  if (suggestions.length > 0) {
+    console.log(`\n${BOLD}Suggested Actions${RESET}`)
+    for (const s of suggestions) console.log(`  → ${s}`)
+  }
+
+  // ── Overall verdict ────────────────────────────────────
+  const isHealthy = pendingCount === 0 && stale.length === 0 && highDrift === 0 && criticalFiles.length === 0
+  console.log(`\n${'─'.repeat(52)}`)
+  if (isHealthy) {
+    console.log(`  ${GREEN}${BOLD}✓ Project documentation is healthy.${RESET}\n`)
+  } else {
+    const issues = [
+      pendingCount > 0 && `${pendingCount} pending`,
+      stale.length > 0 && `${stale.length} stale`,
+      driftResults.length > 0 && `${driftResults.length} drifted`,
+      criticalFiles.length > 0 && `${criticalFiles.length} complex`,
+    ].filter(Boolean).join(', ')
+    console.log(`  ${YELLOW}${BOLD}⚠ Issues found: ${issues}${RESET}\n`)
+  }
+
+  if (isCI && !isHealthy) process.exit(1)
+}
+
+function buildSuggestions({ pendingCount, stale, driftResults, criticalFiles }) {
+  const s = []
+  if (pendingCount > 0) s.push('Run the documentalista subagent to clear the queue (or use /arch-review)')
+  if (stale.length > 0) s.push(`Update docs for ${stale.length} stale module${stale.length !== 1 ? 's' : ''}, then run "docutrack clear"`)
+  if (driftResults.filter(d => d.severity === 'high').length > 0) {
+    const mods = driftResults.filter(d => d.severity === 'high').map(d => d.module).slice(0, 3).join(', ')
+    s.push(`High drift: add missing exports to docs for ${mods}`)
+  }
+  if (criticalFiles.length > 0) {
+    const f = path.basename(criticalFiles[0].file)
+    s.push(`Consider splitting ${f} — it exceeds complexity thresholds`)
+  }
+  return s
+}
+
+function formatMs(ms) {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m`
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h`
+  return `${Math.round(ms / 86_400_000)}d`
+}
+
+module.exports = { run }

package/src/commands/clear.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const fs = require('fs')
+const { clear, pendingCount } = require('../utils/queue')
+
+async function run() {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const before = pendingCount()
+  clear()
+  console.log(`\nQueue cleared. Removed ${before} pending item(s).\n`)
+}
+
+module.exports = { run }