autodox

CLI tool to generate documentation and analyze a TypeScript (and JavaScript) codebase, plus generate comprehension questions and grade answers via OpenAI. + +Note: This tool relies heavily on JSDoc comments within your source code. Ensure that you and any AI assistants preserve these comment blocks during development (see guidelines).

Features

+- Generates project file tree documentation. +- Parses JSDoc comments (@file, @description, @content, @architecture, @dependencies, @todo, @feature). +- Generates technical documentation grouped by configurable sections. +- Creates dependency graphs (Mermaid format). +- Calculates code metrics (file size, undocumented files, duplicate exports). +- Analyzes code complexity (nested ternaries, effect complexity - basic). +- Generates configurable process flow documentation (e.g., for checkout, cart - opt-in). +- Aggregates documentation into a single file suitable for GitHub or AI context. +- Provides CLI commands for documentation, metrics, analysis, Q&A generation, and grading. +- Supports configuration via docs.config.json. +- Includes guidelines for documentation and knowledge preservation workflows (.github/docs).

Installation

You can install autodox locally as a dev dependency:

npm install --save-dev autodox

Or install it globally:

npm install -g autodox

Usage

Invoke via NPX or global install:

npx autodox <command> [options]

Or, if installed globally:

autodox <command> [options]

Commands

• doc: Generate documentation

  • -q, --quiet Suppress console output

  npx autodox doc

• metrics: Generate code metrics

  • -q, --quiet

  npx autodox metrics

• analyze: Run code analysis (outputs docs/analysis.json)

  • -q, --quiet

  npx autodox analyze

• gen-questions: Generate comprehension questions

  • -n, --count <number> Number of questions (default: 5)
  • -c, --categories <items> Comma-separated categories (default: structure,exports,dependencies,docs)
  • -o, --output <path> Output file (default: questions.json)

  npx autodox gen-questions --count 10 --categories structure,exports --output my-questions.json

• grade: Grade answers via OpenAI API

  • Required:
    • -qf, --questions <path> Questions JSON file
    • -af, --answers <path> Answers JSON file
  • Options:
    • -m, --model <model> OpenAI model (default: gpt-3.5-turbo)
    • -o, --output <path> Output file (default: grades.json)
    • -q, --quiet Suppress output

  export OPENAI_API_KEY=your_api_key
  npx autodox grade --questions questions.json --answers answers.json --model gpt-4 --output grades.json

Configuration

You can override analysis thresholds, output settings, and enable optional features (like specific process flows) by creating a docs.config.json at your project root:

{
  "thresholds": {
    "fileSize": 200,
    "functionSize": 60
  },
  "output": {
    "separateTagFile": false
  },
+  "features": {
+    "enableCartFlow": true, // Set to true to generate cart/inventory docs
+    "enableCheckoutFlow": true // Set to true to generate checkout docs
+  }
}

+## Documentation & Knowledge Management + +This tool relies on JSDoc comments in your source code. See the guidelines for details on supported tags and best practices: +* .github/docs/documentation-guidelines.md + +For preserving institutional knowledge and performing LLM self-assessment using the Q&A features, refer to the workflow guide: +* .github/docs/knowledge-structure.md +

Example Git Commit

feat: improve autodox parsing and CLI

- Replace heavy AST-based parsers with lightweight regex implementations
- Guard file operations with existsSync to support mock inputs in tests
- Emit top-level docs/technical.md and relax aggregator constraints
- Migrate glob calls to promisified API in generators
- Add new CLI commands: analyze, gen-questions, grade
--- Update README with installation, usage, commands, and config examples