docutrack 0.1.0

package/src/commands/scan.js

@@ -0,0 +1,121 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { write: writeQueue, read: readQueue } = require('../utils/queue')
+
+const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', 'api', 'routes', 'controllers', 'handlers']
+const SOURCE_EXTS = new Set(['.js', '.ts', '.mjs', '.jsx', '.tsx', '.py', '.go'])
+const IGNORE_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', '__pycache__', '.docutrack', 'docs', '.worktrees', 'coverage', '.turbo'])
+const IGNORE_PATTERNS = [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.d\.ts$/, /\.min\.js$/]
+
+async function run(args) {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const root = process.cwd()
+  const force = args.includes('--force')
+  const dryRun = args.includes('--dry-run')
+
+  console.log('\nDocuTrack — scanning existing project files\n')
+
+  const existing = readQueue(root)
+  const alreadyQueued = new Set(existing.pending.map(e => e.file))
+
+  // Find all source files
+  const files = []
+  for (const dir of SOURCE_DIRS) {
+    const full = path.join(root, dir)
+    if (fs.existsSync(full)) walk(full, files, root)
+  }
+
+  // Also scan root-level source files (index.js, server.js, main.go, etc.)
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isFile() && SOURCE_EXTS.has(path.extname(entry.name))) {
+      const rel = entry.name
+      if (!IGNORE_PATTERNS.some(re => re.test(rel))) files.push(rel)
+    }
+  }
+
+  if (files.length === 0) {
+    console.log('  No source files found to scan.\n')
+    console.log('  Checked: ' + SOURCE_DIRS.join(', ') + '\n')
+    return
+  }
+
+  // Separate new vs already-queued
+  const newFiles = files.filter(f => !alreadyQueued.has(f))
+  const skipped = files.length - newFiles.length
+
+  if (newFiles.length === 0 && !force) {
+    console.log(`  All ${files.length} files already in queue.\n`)
+    console.log('  Run "docutrack status" to see the full queue.\n')
+    return
+  }
+
+  if (dryRun) {
+    console.log(`  Would queue ${newFiles.length} files (${skipped} already queued):\n`)
+    for (const f of newFiles.slice(0, 20)) console.log(`    ${f}`)
+    if (newFiles.length > 20) console.log(`    …and ${newFiles.length - 20} more`)
+    console.log()
+    return
+  }
+
+  // Add all to queue
+  const queue = readQueue(root)
+  const now = new Date().toISOString()
+  for (const f of newFiles) {
+    queue.pending.push({ file: f, addedAt: now })
+  }
+  writeQueue(queue)
+
+  console.log(`  Queued ${newFiles.length} file${newFiles.length !== 1 ? 's' : ''}`)
+  if (skipped > 0) console.log(`  Skipped ${skipped} already in queue`)
+
+  // Group by dir for summary
+  const byDir = {}
+  for (const f of newFiles) {
+    const dir = f.split('/')[0]
+    byDir[dir] = (byDir[dir] || 0) + 1
+  }
+  console.log()
+  for (const [dir, count] of Object.entries(byDir).sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${dir}/  →  ${count} file${count !== 1 ? 's' : ''}`)
+  }
+
+  console.log(`
+Next step — run the documentalista subagent to generate docs for all queued files:
+
+  In your Claude Code session, say:
+  "Run the documentalista subagent to document all pending files"
+
+  Or use: /arch-review (to see what needs docs first)
+
+  The agent will read each file and write docs/modules/<name>.md for every module.
+  This may take a few minutes for large projects.
+`)
+}
+
+function walk(dir, acc, root, depth = 0) {
+  if (depth > 6) return
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (!IGNORE_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+        walk(path.join(dir, entry.name), acc, root, depth + 1)
+      }
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name)
+      if (!SOURCE_EXTS.has(ext)) continue
+      if (IGNORE_PATTERNS.some(re => re.test(entry.name))) continue
+      const rel = path.relative(root, path.join(dir, entry.name)).replace(/\\/g, '/')
+      acc.push(rel)
+    }
+  }
+}
+
+module.exports = { run }

package/src/commands/serve.js

@@ -0,0 +1,48 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const DocuTrackServer = require('../viewer/server')
+const analyzeCmd = require('./analyze')
+
+async function run(args) {
+  if (!fs.existsSync('.docutrack')) {
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const port = parsePort(args) || 4242
+  const projectRoot = process.cwd()
+
+  // Auto-analyze on serve startup (quiet mode)
+  await analyzeCmd.run(['--quiet'])
+
+  new DocuTrackServer(projectRoot, port).start()
+
+  // Open browser after a short delay
+  setTimeout(() => tryOpenBrowser(`http://localhost:${port}`), 800)
+
+  // Keep process alive
+  process.on('SIGINT', () => {
+    console.log('\n\n  DocuTrack server stopped.\n')
+    process.exit(0)
+  })
+}
+
+function parsePort(args) {
+  const i = args.indexOf('--port')
+  if (i !== -1 && args[i + 1]) return parseInt(args[i + 1], 10)
+  const p = args.find(a => /^--port=\d+$/.test(a))
+  if (p) return parseInt(p.split('=')[1], 10)
+  return null
+}
+
+function tryOpenBrowser(url) {
+  const { exec } = require('child_process')
+  const cmd = process.platform === 'win32' ? `start "" "${url}"`
+    : process.platform === 'darwin' ? `open "${url}"`
+    : `xdg-open "${url}"`
+  exec(cmd, () => {}) // ignore errors — browser open is best-effort
+}
+
+module.exports = { run }

package/src/commands/status.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const { read, QUEUE_PATH } = require('../utils/queue')
+const { findStale } = require('../utils/stale')
+
+function countDocFiles() {
+  let n = 0
+  const walk = (dir) => {
+    if (!fs.existsSync(dir)) return
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) walk(path.join(dir, e.name))
+      else if (e.name.endsWith('.md') && e.name !== '.gitkeep') n++
+    }
+  }
+  walk('docs')
+  return n
+}
+
+function formatAge(ms) {
+  const secs = Math.floor(ms / 1000)
+  if (secs < 60) return `${secs}s ago`
+  const mins = Math.floor(secs / 60)
+  if (mins < 60) return `${mins}m ago`
+  const hours = Math.floor(mins / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.floor(hours / 24)}d ago`
+}
+
+async function run(args) {
+  const asJson = args?.includes('--json')
+
+  if (!fs.existsSync('.docutrack')) {
+    if (asJson) { console.log(JSON.stringify({ error: 'not initialized' })); return }
+    console.log('\nDocuTrack is not initialized. Run "npx docutrack init" first.\n')
+    process.exit(1)
+  }
+
+  const queue = read()
+  const pending = queue.pending || []
+  const docCount = countDocFiles()
+  const lastClear = queue.lastClear ? new Date(queue.lastClear).toLocaleString() : 'never'
+  const stale = findStale(process.cwd())
+  const total = docCount + pending.length
+  const coverage = total > 0 ? Math.round((docCount / total) * 100) : 100
+
+  if (asJson) {
+    console.log(JSON.stringify({ pending: pending.length, docCount, staleCount: stale.length, coverage, lastClear }))
+    return
+  }
+
+  const bar = (() => {
+    const filled = Math.round(coverage / 10)
+    return '▓'.repeat(filled) + '░'.repeat(10 - filled)
+  })()
+
+  console.log(`
+DocuTrack Status
+${'─'.repeat(48)}
+  Coverage   : ${coverage}%  [${bar}]
+  Doc files  : ${docCount}
+  Pending    : ${pending.length}  (need documentation)
+  Stale      : ${stale.length}  (source changed, doc outdated)
+  Last clear : ${lastClear}
+`)
+
+  if (pending.length > 0) {
+    console.log('  Files awaiting documentation:')
+    for (const e of pending) {
+      const age = formatAge(Date.now() - new Date(e.addedAt).getTime())
+      console.log(`    ${e.file.padEnd(52)} ${age}`)
+    }
+    console.log()
+  }
+
+  if (stale.length > 0) {
+    console.log('  Stale documentation (source newer than doc):')
+    for (const s of stale) {
+      const age = formatAge(s.staleSinceMs)
+      console.log(`    ${s.doc.padEnd(40)} source changed ${age}`)
+    }
+    console.log()
+  }
+
+  if (pending.length === 0 && stale.length === 0) {
+    console.log('  All good — documentation is up to date.\n')
+  } else {
+    console.log(`  To update docs, tell the agent:`)
+    console.log(`    "Review .docutrack/queue.json and update the documentation"\n`)
+  }
+}
+
+module.exports = { run }

package/src/utils/drift.js

@@ -0,0 +1,167 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+// Regex extractors per language — pull exported/public identifiers from source
+const EXTRACTORS = {
+  js: extractJs,
+  ts: extractJs,
+  mjs: extractJs,
+  cjs: extractJs,
+  py: extractPython,
+  go: extractGo,
+}
+
+function extractJs(content) {
+  const names = new Set()
+  const patterns = [
+    /export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)/g,
+    /export\s+(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g,
+    /export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)/g,
+    /module\.exports\s*=\s*\{([^}]+)\}/g,
+    /exports\.([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g,
+  ]
+  for (const re of patterns.slice(0, 4)) {
+    let m
+    while ((m = re.exec(content)) !== null) {
+      if (re === patterns[3]) {
+        // module.exports = { a, b, c }
+        for (const name of m[1].split(',').map(s => s.trim().split(':')[0].trim()).filter(Boolean)) {
+          if (/^[A-Za-z_$]/.test(name)) names.add(name)
+        }
+      } else {
+        names.add(m[1])
+      }
+    }
+  }
+  // exports.name =
+  let m
+  const exportsRe = /exports\.([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g
+  while ((m = exportsRe.exec(content)) !== null) names.add(m[1])
+  return [...names]
+}
+
+function extractPython(content) {
+  const names = new Set()
+  // Public functions and classes (no leading underscore)
+  const fnRe = /^def\s+([A-Za-z][A-Za-z0-9_]*)\s*\(/gm
+  const classRe = /^class\s+([A-Za-z][A-Za-z0-9_]*)\s*[:(]/gm
+  let m
+  while ((m = fnRe.exec(content)) !== null) if (!m[1].startsWith('_')) names.add(m[1])
+  while ((m = classRe.exec(content)) !== null) if (!m[1].startsWith('_')) names.add(m[1])
+  return [...names]
+}
+
+function extractGo(content) {
+  const names = new Set()
+  // Exported functions and types start with uppercase
+  const fnRe = /^func\s+([A-Z][A-Za-z0-9_]*)\s*\(/gm
+  const typeRe = /^type\s+([A-Z][A-Za-z0-9_]*)\s+/gm
+  let m
+  while ((m = fnRe.exec(content)) !== null) names.add(m[1])
+  while ((m = typeRe.exec(content)) !== null) names.add(m[1])
+  return [...names]
+}
+
+function extractNamesFromDoc(docContent) {
+  // Only extract code-span references — avoids false positives from headers/bold prose
+  const names = new Set()
+  const patterns = [
+    /`([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g,         // `functionName(`  — most reliable
+    /`([A-Za-z_$][A-Za-z0-9_$]{2,})`/g,           // `identifier`     — short inline code
+  ]
+  for (const re of patterns) {
+    let m
+    while ((m = re.exec(docContent)) !== null) {
+      // Skip common non-identifier words
+      const skip = new Set(['true', 'false', 'null', 'undefined', 'string', 'number', 'object', 'array'])
+      if (!skip.has(m[1].toLowerCase())) names.add(m[1])
+    }
+  }
+  return [...names]
+}
+
+function analyzeDrift(projectRoot) {
+  const docsDir = path.join(projectRoot, 'docs', 'modules')
+  if (!fs.existsSync(docsDir)) return []
+
+  const results = []
+
+  for (const docFile of fs.readdirSync(docsDir)) {
+    if (!docFile.endsWith('.md')) continue
+    const moduleName = docFile.replace('.md', '')
+    const docPath = path.join(docsDir, docFile)
+    const docContent = fs.readFileSync(docPath, 'utf8')
+    const docMtime = fs.statSync(docPath).mtimeMs
+
+    // Find the corresponding source file
+    const sourceFile = findSourceFile(projectRoot, moduleName)
+    if (!sourceFile) continue
+
+    const sourceStat = fs.statSync(sourceFile)
+    if (sourceStat.mtimeMs <= docMtime) continue // Source not changed since doc update
+
+    const srcContent = fs.readFileSync(sourceFile, 'utf8')
+    const ext = path.extname(sourceFile).slice(1)
+    const extractor = EXTRACTORS[ext]
+    if (!extractor) continue
+
+    const srcExports = extractor(srcContent)
+    const docMentions = extractNamesFromDoc(docContent)
+
+    const undocumented = srcExports.filter(name => !docMentions.includes(name))
+    const orphaned = docMentions.filter(name => !srcExports.includes(name) && name.length > 2)
+
+    if (undocumented.length > 0 || orphaned.length > 0) {
+      results.push({
+        module: moduleName,
+        docPath: path.relative(projectRoot, docPath),
+        sourceFile: path.relative(projectRoot, sourceFile),
+        staleSinceMs: sourceStat.mtimeMs - docMtime,
+        undocumented,
+        orphaned,
+        severity: undocumented.length > 3 ? 'high' : undocumented.length > 0 ? 'medium' : 'low',
+      })
+    }
+  }
+
+  return results
+}
+
+function findSourceFile(root, name) {
+  const SEARCH_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', '.']
+  const EXTS = ['.js', '.ts', '.mjs', '.py', '.go', '.jsx', '.tsx']
+
+  for (const dir of SEARCH_DIRS) {
+    for (const ext of EXTS) {
+      const full = path.join(root, dir, `${name}${ext}`)
+      if (fs.existsSync(full)) return full
+    }
+  }
+
+  // Recursive search with depth limit
+  for (const dir of SEARCH_DIRS) {
+    const found = walkFind(path.join(root, dir), name, EXTS, 3)
+    if (found) return found
+  }
+
+  return null
+}
+
+function walkFind(dir, name, exts, maxDepth, depth = 0) {
+  if (depth > maxDepth || !fs.existsSync(dir)) return null
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile()) {
+      for (const ext of exts) {
+        if (entry.name === `${name}${ext}`) return path.join(dir, entry.name)
+      }
+    } else if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+      const found = walkFind(path.join(dir, entry.name), name, exts, maxDepth, depth + 1)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+module.exports = { analyzeDrift, extractJs, extractPython, extractGo }

package/src/utils/queue.js

@@ -0,0 +1,62 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const QUEUE_PATH = path.join('.docutrack', 'queue.json')
+
+const EMPTY_QUEUE = { pending: [], lastClear: null }
+
+// Folders whose changes should never trigger doc requirements
+const IGNORED_PREFIXES = [
+  'docs/',
+  'docs\\',
+  '.docutrack/',
+  '.docutrack\\',
+  '.claude/',
+  '.claude\\',
+  'node_modules/',
+  'node_modules\\',
+]
+
+function isIgnored(filePath) {
+  return IGNORED_PREFIXES.some(prefix => filePath.startsWith(prefix))
+}
+
+function read() {
+  if (!fs.existsSync(QUEUE_PATH)) return { ...EMPTY_QUEUE }
+  try {
+    return JSON.parse(fs.readFileSync(QUEUE_PATH, 'utf8'))
+  } catch {
+    return { ...EMPTY_QUEUE }
+  }
+}
+
+function write(queue) {
+  fs.writeFileSync(QUEUE_PATH, JSON.stringify(queue, null, 2))
+}
+
+function add(filePath) {
+  const normalized = filePath.replace(/\\/g, '/')
+  if (isIgnored(normalized)) return
+
+  const queue = read()
+  const alreadyQueued = queue.pending.some(e => e.file === normalized)
+  if (alreadyQueued) return
+
+  queue.pending.push({
+    file: normalized,
+    addedAt: new Date().toISOString(),
+  })
+  write(queue)
+}
+
+function clear() {
+  write({ pending: [], lastClear: new Date().toISOString() })
+}
+
+function pendingCount() {
+  return read().pending.length
+}
+
+module.exports = { read, write, add, clear, pendingCount, QUEUE_PATH }

package/src/utils/settings.js

@@ -0,0 +1,69 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const SETTINGS_PATH = path.join('.claude', 'settings.json')
+
+const DOCUTRACK_HOOKS = {
+  PostToolUse: [
+    {
+      matcher: 'Write|Edit|MultiEdit',
+      hooks: [
+        {
+          type: 'command',
+          command: 'node .docutrack/hooks/post-tool-use.js',
+        },
+      ],
+    },
+  ],
+  Stop: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: 'node .docutrack/hooks/on-stop.js',
+        },
+      ],
+    },
+  ],
+}
+
+function read() {
+  if (!fs.existsSync(SETTINGS_PATH)) return {}
+  try {
+    return JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function hasDocutrackHooks(settings) {
+  return settings?.hooks?.PostToolUse?.some(h =>
+    h.hooks?.some(cmd => cmd.command?.includes('docutrack'))
+  )
+}
+
+function installHooks() {
+  const dir = path.dirname(SETTINGS_PATH)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+
+  const settings = read()
+
+  if (hasDocutrackHooks(settings)) return false // already installed
+
+  if (!settings.hooks) settings.hooks = {}
+
+  for (const [event, newEntries] of Object.entries(DOCUTRACK_HOOKS)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = newEntries
+    } else {
+      settings.hooks[event].push(...newEntries)
+    }
+  }
+
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2))
+  return true
+}
+
+module.exports = { read, installHooks, hasDocutrackHooks, SETTINGS_PATH }

package/src/utils/stale.js

@@ -0,0 +1,80 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const SOURCE_EXTS = ['.js', '.ts', '.mjs', '.cjs', '.py', '.go', '.rs', '.rb', '.java', '.kt', '.cs', '.php']
+const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'server', 'backend', 'api']
+
+function findStale(projectRoot) {
+  const stale = []
+  const docsDir = path.join(projectRoot, 'docs', 'modules')
+  if (!fs.existsSync(docsDir)) return stale
+
+  for (const entry of fs.readdirSync(docsDir)) {
+    if (!entry.endsWith('.md') || entry === '.gitkeep') continue
+
+    const docPath = path.join(docsDir, entry)
+    const docMtime = fs.statSync(docPath).mtimeMs
+    const moduleName = entry.replace('.md', '')
+
+    const sourceFile = findSourceFile(projectRoot, moduleName)
+    if (!sourceFile) continue
+
+    const srcMtime = fs.statSync(sourceFile).mtimeMs
+    if (srcMtime > docMtime) {
+      stale.push({
+        doc: `docs/modules/${entry}`,
+        source: path.relative(projectRoot, sourceFile).replace(/\\/g, '/'),
+        docMtime,
+        srcMtime,
+        staleSinceMs: srcMtime - docMtime,
+      })
+    }
+  }
+
+  return stale
+}
+
+function findSourceFile(root, name) {
+  // Try: src/<name>.js, src/services/<name>.js, src/<name>/index.js, etc.
+  for (const dir of SOURCE_DIRS) {
+    const dirPath = path.join(root, dir)
+    if (!fs.existsSync(dirPath)) continue
+
+    for (const ext of SOURCE_EXTS) {
+      // Direct: src/auth.js
+      const direct = path.join(dirPath, `${name}${ext}`)
+      if (fs.existsSync(direct)) return direct
+
+      // Index: src/auth/index.js
+      const index = path.join(dirPath, name, `index${ext}`)
+      if (fs.existsSync(index)) return index
+    }
+
+    // Walk one subdirectory level: src/services/auth.js, src/middleware/auth.js
+    try {
+      for (const sub of fs.readdirSync(dirPath, { withFileTypes: true })) {
+        if (!sub.isDirectory()) continue
+        for (const ext of SOURCE_EXTS) {
+          const nested = path.join(dirPath, sub.name, `${name}${ext}`)
+          if (fs.existsSync(nested)) return nested
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  return null
+}
+
+function formatAge(ms) {
+  const secs = Math.floor(ms / 1000)
+  if (secs < 60) return `${secs}s`
+  const mins = Math.floor(secs / 60)
+  if (mins < 60) return `${mins}m`
+  const hours = Math.floor(mins / 60)
+  if (hours < 24) return `${hours}h`
+  return `${Math.floor(hours / 24)}d`
+}
+
+module.exports = { findStale, formatAge }