ai-codebase-doc-drift-detector/README.md

AI Codebase Doc Drift Detector

Auto-detect and document code drift before AI context loss.

Problem

As AI generates more code, the gap between what the code does and what the docs say grows. No automated documentation maintenance keeps pace with AI-generated changes. This tool bridges that gap.

What It Does

• Scans your TypeScript/JavaScript codebase for exported functions, classes, and interfaces
• Generates API.md and ARCHITECTURE.md automatically
• Detects drift — finds symbols in code that aren't documented (or documented symbols that no longer exist)
• Updates docs on demand to match current code

Install

npm install -g ai-codebase-doc-drift-detector
# or use npx
npx ai-codebase-doc-drift-detector init

Usage

# Initialize config in your project
ai-doc-drift init

# Generate initial docs
ai-doc-drift scan

# Check for drift between code and docs
ai-doc-drift check

# Regenerate docs from current code
ai-doc-drift update

Config (ai-doc-drift.json)

{
  "docsDir": "./docs",
  "include": ["./src"],
  "exclude": ["./node_modules", "./dist", "./docs", "./.git"],
  "extensions": [".ts", ".js", ".tsx", ".jsx"],
  "projectName": "My Project"
}

How It Works

1. Parses your source files with lightweight regex (no heavy AST dependencies)
2. Extracts exports, classes, methods, interfaces
3. Generates markdown documentation
4. Compares code against existing docs to detect drift

Exit Codes

Code	Meaning
0	Success / no drift
1	Error (no docs found, no config, etc.)
2	Drift detected

License

MIT