Auto-DOC

Plugin your trusted LLM API and start documenting your code base

Overview

Auto-DOC is an automatic code documentation generator that scans your project's source files, analyzes their dependencies and code structure, and generates comprehensive documentation including a linking table, individual file documentation, and a beautiful HTML documentation site.

NEW: Interactive inspector mode with control flow tracing!

Features

• 🔍 Automatic Source Scanning: Scans your src folder for source files
• 🔗 Dependency Analysis: Detects import/export relationships between files
• 🧠 Code Structure Analysis: Extracts functions, classes, methods, parameters, variables, and class variables using Tree-sitter AST parsing
• 🎯 Goal Extraction: Automatically extracts function/method purposes from comments
• 📊 Enhanced Linking Table: Creates a JSON table with file dependencies and comprehensive code structure
• 🔎 Interactive Inspector: Browse your codebase structure with an emulated terminal
• 🌊 Control Flow Tracing: Visualize function call flows with customizable depth
• 📄 Enhanced Trace Documentation: Generate detailed HTML documentation with line-by-line control flow analysis
• 🎯 Line-by-Line Execution Tracking: See exactly what each line of code does and what it calls
• 📊 Node-Graph Flow Files: Separate .flow files store control flow data in a structured format
• 🗂️ Hierarchical Flow Organization: Flow files mirror your src directory structure for easy navigation
• ⬆️ Upstream Analysis: Discover callers and dependencies for methods
• 📝 Individual Documentation: Generates HTML documentation for each source file
• 🌐 Beautiful HTML Site: Creates a main.html with language distribution, entry points, and project overview
• 📈 Project Statistics: Shows classes, functions, most referenced files, and dependencies
• 🎯 Entry Point Detection: Automatically identifies application entry points
• 🔗 Hyperlinked Navigation: Every file reference links directly to its generated documentation
• 🌍 Multi-Language Support: Works with JavaScript, TypeScript, Python, Java, Go, Rust, C/C++
• 🔌 LLM Integration Ready: Designed to integrate with OpenAI and other LLM APIs
• 🌳 Tree-sitter Parsing: Uses Tree-sitter for accurate AST-based code parsing with regex fallback for enhanced details

Installation

npm install -g llm-autodoc

Or use directly with npx:

npx auto-doc

Usage

Basic Usage

Run Auto-DOC in your project directory:

autodoc

This will:

1. Scan the src folder for source files
2. Analyze code structure (functions, classes, methods)
3. Create an autodoc folder alongside src
4. Generate a linking-table.json file with dependency and structure information
5. Create individual HTML documentation files in autodoc/docs/
6. Generate a main.html summary page with project overview
7. Create a summary.txt file with a human-readable overview

Command Line Options

autodoc [options] [project-path]

Options:
  -h, --help              Show help message
  -p, --project <path>    Project path (default: current directory)
  -s, --src <folder>      Source folder name (default: 'src')
  -o, --output <folder>   Output folder name (default: 'autodoc')
  -k, --api-key <key>     Set API key (overrides OPENAI_API_KEY env var)
  -e, --api-endpoint <url>  Set API endpoint base URL
  --use-llm              Require LLM features and prompt for credentials if missing
  --configure-llm        Interactively set or update stored LLM credentials
  --clear-llm            Remove stored LLM credentials
  -inspect, --inspect     Open interactive inspector to browse linking table
  -serve, --serve         Start local HTTP server to serve documentation
  --port <number>         Server port (default: 3000, used with --serve)

Examples

Document a specific project:

autodoc /path/to/my/project

Use a different source folder:

autodoc --src lib

Custom source and output folders:

autodoc -s source -o documentation

Serve documentation on local server:

autodoc -serve              # Start server on default port 3000
autodoc -serve --port 8080  # Start server on custom port

Interactive Inspector Mode

The inspector provides an emulated terminal to explore your codebase interactively:

autodoc -inspect

Available Commands:

• ls [path] - List objects at current or specified path
• cd <path> - Navigate to a file or directory
  • Supports partial paths: cd file.js (no need for full path)
  • Supports going up: cd ../ (go up one level), cd .. (go to root)
  • Can navigate to directories: cd src (shows files in directory)
• pwd - Print current path
• info <name> - Show detailed information about a function/class/method
• trace <name> [depth] - Display control flow trace (default depth: 3)
• tracedoc <name> [depth] - Generate HTML documentation for control flow
• find <pattern> - Find functions/classes/methods matching pattern (supports :: syntax)
• help - Show help message
• exit/quit - Exit inspector

Universal :: Syntax:

Auto-DOC now supports a universal syntax for referencing code objects across files:

• file.js::function - Reference a function in a file
• file.ts::ClassName - Reference a class in a file
• file.py::ClassName::methodName - Reference a method in a class

Examples:

autodoc:/> info src/calculator.js::Calculator::add
autodoc:/> trace src/utils.js::processData
autodoc:/> find ::MyClass::  # Find all methods in MyClass

Example Inspector Session:

autodoc:/> ls
Files:
  src/index.js (3 functions, 1 classes, 5 methods)
  src/utils.js (10 functions, 0 classes, 0 methods)

autodoc:/> cd src/index.js
autodoc:src/index.js> ls
Functions:
  calculate(a, b, operation) - Calculator application

autodoc:src/index.js> info calculate
Function: calculate
Type: function
Parameters: a, b, operation
Goal: Calculator application
Calls: log, add, subtract, error

autodoc:src/index.js> trace calculate 2
Tracing control flow for: calculate (depth: 2)
→ calculate
  Goal: Calculator application
  Calls: log, add, subtract, error

autodoc:src/index.js> tracedoc calculate 3
✅ Trace documentation generated successfully!
Flow: /path/to/autodoc/flows/src/index_calculate.flow
Doc: /path/to/autodoc/flows/src/index_calculate.doc.html

The generated trace documentation includes:

• Code Context: Shows the function signature with surrounding lines
• Line-by-Line Execution: Detailed breakdown of what each line does
• Function Calls: Highlights which functions are called on each line
• Nested Call Hierarchy: Shows the full call stack up to the specified depth
• Flow Data: Separate .flow file containing node-graph structure
• Cross-File Tracing: Tracer can follow function calls across imported files
• Method Call Support: Handles this.method() and self.method() patterns

Trace Buttons in Documentation:

When viewing the HTML documentation in a browser, each method and function has a trace button:

• 🔍 Trace - Blue button shown when no trace exists yet. Tooltip indicates you can use tracedoc <name> in the inspector to generate the trace.
• 📊 View Trace - Green button shown when a trace already exists. Clicking it navigates to the detailed control flow trace documentation.

This makes it easy to explore control flow directly from the documentation without switching to the inspector.

Local Documentation Server

Auto-DOC includes a built-in HTTP server to serve your documentation locally:

autodoc -serve              # Start server on port 3000
autodoc -serve --port 8080  # Start server on custom port

The server:

• Serves all files from the autodoc directory
• Supports nested paths and directory structures
• Automatically serves main.html as the index page
• Includes MIME type detection for proper file serving
• Provides a convenient way to browse documentation in your browser

Access your documentation at http://localhost:3000 (or your specified port).

LLM Integration

Auto-DOC is designed to work with LLM APIs like OpenAI. Set your API credentials as environment variables:

export OPENAI_API_KEY=your-api-key-here
export OPENAI_API_ENDPOINT=https://api.openai.com/v1 # optional
autodoc

You can also supply these at runtime with CLI flags:

autodoc --api-key your-api-key --api-endpoint https://custom-endpoint/v1

🔒 No API? No problem. All scanning, analysis, and documentation generation runs locally. Supplying API credentials is only required if you enable LLM-backed features in future releases.

Auto-DOC's current feature set does not require an LLM. When you opt into LLM functionality using --use-llm, the CLI will prompt for any missing credentials and persist them to ~/.autodoc/config.json. You can update those values at any time with --configure-llm or remove them with --clear-llm.

Each run prints a token usage summary so you can track LLM costs. The values are also persisted inside the generated metadata described below.

Output Files

main.html

A beautiful, interactive documentation site featuring:

• Project Statistics: Total files, lines of code, classes, functions, and languages
• Language Distribution: Visual bar chart showing code breakdown
• Entry Points: Identified application entry points
• Most Referenced Files: Shows which files are imported most (each entry links to its doc page)
• Files with Most Dependencies: Identifies complex modules with clickable drill-down
• Documentation Index: Hierarchical file tree that mirrors your source layout for quick navigation
• Project Purpose: Auto-generated overview of the codebase

docs/*.html

Individual HTML documentation files for each source file containing:

• Language and file path information
• Hyperlinked import/export relationships to related documentation
• Detailed function signatures with parameters
• Function/method goals and purposes (extracted from comments)
• Class hierarchies with methods
• Export information
• Function call dependencies

flows/.doc.html & flows/.flow

Enhanced control flow trace documentation generated via the inspector with detailed line-by-line analysis:

• Visual Control Flow: Hierarchical view of function/method calls up to specified depth
• Code Context: Shows the actual code with line numbers around each function
• Line-by-Line Execution: Detailed breakdown showing what each line does and what it calls
• Goal Information: Purpose of each function in the call chain
• Depth Control: Configurable trace depth (default: 3 levels)
• Upstream Analysis: For methods, shows potential callers
• Separate Flow Files: .flow files contain node-graph data structure in JSON format
• Hierarchical Organization: Flow files replicate the src directory structure

The .flow files store the control flow data in a structured JSON format:

{
  "metadata": {
    "object": "calculate",
    "file": "src/index.js",
    "type": "function",
    "goal": "Calculator application",
    "depth": 3
  },
  "controlFlow": [
    {
      "name": "calculate",
      "type": "function",
      "goal": "Calculator application",
      "parameters": ["a", "b", "operation"],
      "codeSnippet": { /* line numbers and code */ },
      "bodyLines": [ /* line-by-line breakdown */ ],
      "calls": ["log", "add", "subtract"],
      "children": [ /* nested function calls */ ]
    }
  ]
}

The .doc.html files render the flow data with beautiful formatting and syntax highlighting.

linking-table.json

Enhanced JSON file containing the complete dependency graph and code structure:

{
  "generatedAt": "2025-10-11T23:10:00.000Z",
  "files": {
    "/path/to/file.js": {
      "path": "/path/to/file.js",
      "importingFrom": ["/path/to/dependency.js"],
      "importedBy": ["/path/to/consumer.js"],
      "structure": {
        "language": "JavaScript",
        "variables": [
          {
            "name": "globalVar",
            "type": "variable",
            "startIndex": 0,
            "endIndex": 9
          }
        ],
        "functions": [
          {
            "name": "calculate",
            "parameters": ["a", "b"],
            "type": "function",
            "async": false,
            "goal": "Performs calculation",
            "calls": ["add", "subtract", "log"]
          }
        ],
        "classes": [
          {
            "name": "Calculator",
            "extends": "BaseClass",
            "type": "class",
            "goal": "Main calculator class",
            "methods": [...]
          }
        ],
        "classVariables": [
          {
            "name": "instanceVar",
            "className": "Calculator",
            "type": "class-variable",
            "startIndex": 100,
            "endIndex": 111
          }
        ],
        "methods": [...],
        "exports": [...]
      }
    }
  }
}

The structure extracts five types of objects for comprehensive analysis:

1. Plain variables: Global and module-level variable declarations
2. Functions: Standalone functions and arrow functions with parameters, goals, and call information
3. Classes: Class declarations with inheritance information
4. Class variables: Field declarations within classes (instance and static variables)
5. Class methods: Methods and constructors within classes

All objects support universal identifiers for cross-file references:

• file.js::objectName - Reference to a function, class, or variable in a file
• file.js::ClassName::methodName - Reference to a method in a class
• file.js::ClassName::variableName - Reference to a class variable

meta.json

Run metadata and bookkeeping to help you understand each documentation pass:

• Token Usage: Prompt, completion, and total token counts aggregated across every LLM call
• Run Stats: Start time and duration, language distribution, file counts
• Folder Structures: Snapshot of the source tree and generated Auto-DOC output
• File Indexes: Lists of documented files and their corresponding docs

summary.txt

A human-readable text file summarizing the project structure and dependencies.

Supported Languages

• JavaScript (.js, .mjs)
• TypeScript (.ts, .tsx)
• Python (.py)
• Java (.java)
• Go (.go)
• Rust (.rs)
• C/C++ (.c, .cpp)

Project Structure

After running Auto-DOC, your project will look like:

my-project/
├── src/                  # Your source code
│   ├── index.js
│   ├── utils.js
│   └── ...
├── autodoc/              # Auto-generated documentation
│   ├── main.html         # Main documentation site
│   ├── linking-table.json # Enhanced with code structure
│   ├── summary.txt       # Text summary
│   ├── docs/             # Individual file documentation
│   │   ├── file1.html
│   │   ├── file2.html
│   │   └── ...
│   ├── flows/            # Control flow traces (mirrors src structure)
│   │   └── src/          # Follows src directory hierarchy
│   │       ├── index_calculate.flow      # Flow data (JSON)
│   │       ├── index_calculate.doc.html  # Rendered documentation
│   │       └── ...
└── ...

Advanced Features

Tree-sitter Based Parsing

Auto-DOC uses Tree-sitter, a powerful parser generator tool, for accurate Abstract Syntax Tree (AST) based code parsing. This approach provides several advantages over pure regex-based parsing:

• Accurate Structure: Correctly handles nested structures, complex syntax, and edge cases
• Language Support: Native support for JavaScript, TypeScript, Python, Java, Go, Rust, and C/C++
• Five Object Types: Extracts plain variables, functions, classes, class variables, and class methods
• Fallback Strategy: Uses regex for enhanced detail extraction (goals from comments, refined call analysis)

The hybrid approach combines Tree-sitter's structural accuracy with regex's flexibility for extracting metadata like comments and goals.

Goal/Purpose Extraction

Auto-DOC automatically extracts the purpose or goal of functions, methods, and classes from comments:

/**
 * Calculates the sum of two numbers
 */
function add(a, b) {
  return a + b;
}

The linking table will include: "goal": "Calculates the sum of two numbers"

Control Flow Analysis

Each function and method tracks its dependencies (calls):

function calculate(a, b, operation) {
  log('Calculating...');
  if (operation === 'add') {
    return add(a, b);
  }
  return subtract(a, b);
}

The linking table will include: "calls": ["log", "add", "subtract"]

Upstream Discovery

For methods, the inspector can identify potential upstream callers, helping you understand:

• Which functions/methods call this method within the same file
• Which external files import this file

This is particularly useful for understanding the impact of changes to a method.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC