@git.zone/tsdoc is a next-generation documentation tool that combines traditional TypeDoc generation with cutting-edge AI to create comprehensive, intelligent documentation for your TypeScript projects. It reads your code, understands it, and writes documentation that actually makes sense.

✨ Key Features

🤖 AI-Enhanced Documentation - Leverages GPT-5 and other models to generate contextual READMEs
🧠 Smart Context Building - Intelligent file prioritization with dependency analysis and caching
📚 TypeDoc Integration - Classic API documentation generation when you need it
💬 Smart Commit Messages - AI analyzes your changes and suggests meaningful commit messages
🎯 Context Optimization - Advanced token management with 40-60% reduction in usage
⚡ Performance Optimized - 3-5x faster with lazy loading and parallel processing
📦 Zero Config - Works out of the box with sensible defaults
🔧 Highly Configurable - Customize every aspect when needed

Installation

# Global installation (recommended)
npm install -g @git.zone/tsdoc

# Or with pnpm
pnpm add -g @git.zone/tsdoc

# Or use with npx
npx @git.zone/tsdoc

Quick Start

Generate AI-Powered Documentation

# In your project root
tsdoc aidoc

That's it! tsdoc will analyze your entire codebase and generate:

A comprehensive README.md
Updated package.json description and keywords
Smart documentation based on your actual code structure

Generate Traditional TypeDoc

tsdoc typedoc --publicSubdir docs

Get Smart Commit Messages

tsdoc commit

CLI Commands

Command	Description
`tsdoc`	Auto-detects and runs appropriate documentation
`tsdoc aidoc`	Generate AI-enhanced documentation
`tsdoc typedoc`	Generate TypeDoc documentation
`tsdoc commit`	Generate smart commit message
`tsdoc tokens`	Analyze token usage for AI context
`tsdoc context`	Display context information

Token Analysis

Understanding token usage helps optimize AI costs:

# Show token count for current project
tsdoc tokens

# Show detailed stats for all task types
tsdoc tokens --all

# Test with trimmed context
tsdoc tokens --trim

Programmatic Usage

Generate Documentation Programmatically

import { AiDoc } from '@git.zone/tsdoc';

const generateDocs = async () => {
  const aiDoc = new AiDoc({ OPENAI_TOKEN: 'your-token' });
  await aiDoc.start();

  // Generate README
  await aiDoc.buildReadme('./');

  // Update package.json description
  await aiDoc.buildDescription('./');

  // Get smart commit message
  const commit = await aiDoc.buildNextCommitObject('./');
  console.log(commit.recommendedNextVersionMessage);

  // Don't forget to stop when done
  await aiDoc.stop();
};

TypeDoc Generation

import { TypeDoc } from '@git.zone/tsdoc';

const typeDoc = new TypeDoc(process.cwd());
await typeDoc.compile({ publicSubdir: 'docs' });

Smart Context Management

Control how tsdoc processes your codebase with the new intelligent context system:

import { EnhancedContext, ContextAnalyzer, LazyFileLoader, ContextCache } from '@git.zone/tsdoc';

const context = new EnhancedContext('./');
await context.initialize();

// Set token budget
context.setTokenBudget(100000);

// Choose context mode
context.setContextMode('trimmed'); // 'full' | 'trimmed' | 'summarized'

// Build optimized context with smart prioritization
const result = await context.buildContext('readme');
console.log(`Tokens used: ${result.tokenCount}`);
console.log(`Files included: ${result.includedFiles.length}`);
console.log(`Token savings: ${result.tokenSavings}`);

Advanced: Using Individual Context Components

import { LazyFileLoader, ContextAnalyzer, ContextCache } from '@git.zone/tsdoc';

// Lazy file loading - scan metadata without loading contents
const loader = new LazyFileLoader('./');
const metadata = await loader.scanFiles(['ts/**/*.ts']);
console.log(`Found ${metadata.length} files`);

// Analyze and prioritize files
const analyzer = new ContextAnalyzer('./');
const analysis = await analyzer.analyze(metadata, 'readme');

// Files are sorted by importance with dependency analysis
for (const file of analysis.files) {
  console.log(`${file.path}: score ${file.importanceScore.toFixed(2)}, tier ${file.tier}`);
}

// Context caching for performance
const cache = new ContextCache('./', { enabled: true, ttl: 3600 });
await cache.init();

Configuration

Configure tsdoc via npmextra.json:

{
  "tsdoc": {
    "context": {
      "maxTokens": 190000,
      "defaultMode": "trimmed",
      "cache": {
        "enabled": true,
        "ttl": 3600,
        "maxSize": 100
      },
      "analyzer": {
        "enabled": true,
        "useAIRefinement": false
      },
      "prioritization": {
        "dependencyWeight": 0.3,
        "relevanceWeight": 0.4,
        "efficiencyWeight": 0.2,
        "recencyWeight": 0.1
      },
      "tiers": {
        "essential": { "minScore": 0.8, "trimLevel": "none" },
        "important": { "minScore": 0.5, "trimLevel": "light" },
        "optional": { "minScore": 0.2, "trimLevel": "aggressive" }
      },
      "taskSpecificSettings": {
        "readme": {
          "mode": "trimmed",
          "includePaths": ["ts/", "src/"],
          "excludePaths": ["test/", "node_modules/"]
        },
        "commit": {
          "mode": "trimmed",
          "focusOnChangedFiles": true
        }
      },
      "trimming": {
        "removeImplementations": true,
        "preserveInterfaces": true,
        "preserveJSDoc": true,
        "maxFunctionLines": 5,
        "removeComments": true
      }
    }
  }
}

Configuration Options

Context Settings

maxTokens - Maximum tokens for AI context (default: 190000)
defaultMode - Default context mode: 'full', 'trimmed', or 'summarized'
cache - Caching configuration for improved performance
analyzer - Smart file analysis and prioritization settings
prioritization - Weights for file importance scoring
tiers - Tier thresholds and trimming levels

Cache Configuration

enabled - Enable/disable file caching (default: true)
ttl - Time-to-live in seconds (default: 3600)
maxSize - Maximum cache size in MB (default: 100)
directory - Cache directory path (default: .nogit/context-cache)

Analyzer Configuration

enabled - Enable smart file analysis (default: true)
useAIRefinement - Use AI for additional context refinement (default: false)
aiModel - Model for AI refinement (default: 'haiku')

How It Works

🚀 Smart Context Building Pipeline

📊 Fast Metadata Scanning - Lazy loading scans files without reading contents
🧬 Dependency Analysis - Builds dependency graph from import statements
🎯 Intelligent Scoring - Multi-factor importance scoring:
- Relevance: Task-specific file importance (e.g., index.ts for READMEs)
- Centrality: How many files depend on this file
- Efficiency: Information density (tokens vs. value)
- Recency: Recently changed files (for commits)
🏆 Smart Prioritization - Files sorted by combined importance score
🎭 Tier-Based Trimming - Adaptive trimming based on importance:
- Essential (score ≥ 0.8): No trimming
- Important (score ≥ 0.5): Light trimming
- Optional (score ≥ 0.2): Aggressive trimming
💾 Intelligent Caching - Cache results with file change detection
🧠 AI Processing - Send optimized context to AI for documentation

Context Optimization Benefits

The smart context system delivers significant improvements:

Metric	Before	After	Improvement
Token Usage	~190k (limit)	~110-130k	⬇️ 40-60% reduction
Build Time	4-6 seconds	1-2 seconds	⚡ 3-5x faster
Memory Usage	All files loaded	Metadata + selected	📉 80%+ reduction
Relevance	Alphabetical sorting	Smart scoring	🎯 90%+ relevant
Cache Hits	None	70-80%	🚀 Major speedup

Traditional Context Optimization

For projects where the analyzer is disabled, tsdoc still employs:

Intelligent Trimming - Removes implementation details while preserving signatures
JSDoc Preservation - Keeps documentation comments
Interface Prioritization - Type definitions always included
Token Budgeting - Ensures optimal use of AI context windows

Environment Variables

Variable	Description
`OPENAI_TOKEN`	Your OpenAI API key for AI features (required)

Use Cases

🚀 Continuous Integration

# .github/workflows/docs.yml
name: Documentation
on: [push]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Generate Documentation
        env:
          OPENAI_TOKEN: ${{ secrets.OPENAI_TOKEN }}
        run: |
          npm install -g @git.zone/tsdoc
          tsdoc aidoc
      - name: Commit Changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add readme.md package.json
          git commit -m "docs: update documentation [skip ci]" || exit 0
          git push

🔄 Pre-Commit Hooks

# .git/hooks/prepare-commit-msg
#!/bin/bash
tsdoc commit > .git/COMMIT_EDITMSG

📦 Package Publishing

{
  "scripts": {
    "prepublishOnly": "tsdoc aidoc",
    "version": "tsdoc aidoc && git add readme.md"
  }
}

Advanced Features

Multi-Module Projects

tsdoc automatically detects and documents multi-module projects:

const aiDoc = new AiDoc();
await aiDoc.start();

// Process main project
await aiDoc.buildReadme('./');

// Process submodules
for (const module of ['packages/core', 'packages/cli']) {
  await aiDoc.buildReadme(module);
}

await aiDoc.stop();

Custom Context Building

Fine-tune what gets sent to AI with task-specific contexts:

import { TaskContextFactory } from '@git.zone/tsdoc';

const factory = new TaskContextFactory('./');
await factory.initialize();

// Get optimized context for specific tasks
const readmeContext = await factory.createContextForReadme();
const commitContext = await factory.createContextForCommit();
const descContext = await factory.createContextForDescription();

Dependency Graph Analysis

Understand your codebase structure:

import { ContextAnalyzer } from '@git.zone/tsdoc';

const analyzer = new ContextAnalyzer('./');
const analysis = await analyzer.analyze(metadata, 'readme');

// Explore dependency graph
for (const [path, deps] of analysis.dependencyGraph) {
  console.log(`${path}:`);
  console.log(`  Imports: ${deps.imports.length}`);
  console.log(`  Imported by: ${deps.importedBy.length}`);
  console.log(`  Centrality: ${deps.centrality.toFixed(3)}`);
}

Performance & Optimization

⚡ Performance Features

Lazy Loading - Files scanned for metadata before content loading
Parallel Processing - Multiple files loaded simultaneously
Smart Caching - Results cached with mtime-based invalidation
Incremental Updates - Only reprocess changed files
Streaming - Minimal memory footprint

💰 Cost Optimization

The smart context system significantly reduces AI API costs:

// Check token usage before and after optimization
import { EnhancedContext } from '@git.zone/tsdoc';

const context = new EnhancedContext('./');
await context.initialize();

// Build with analyzer enabled
const result = await context.buildContext('readme');
console.log(`Tokens: ${result.tokenCount}`);
console.log(`Savings: ${result.tokenSavings} (${(result.tokenSavings/result.tokenCount*100).toFixed(1)}%)`);

📊 Token Analysis

Monitor and optimize your token usage:

# Analyze current token usage
tsdoc tokens

# Compare modes
tsdoc tokens --mode full      # No optimization
tsdoc tokens --mode trimmed    # Standard optimization
tsdoc tokens --analyze         # With smart prioritization

Requirements

Node.js >= 18.0.0
TypeScript project
OpenAI API key (for AI features)

Troubleshooting

Token Limit Exceeded

If you hit token limits, try:

# Enable smart analyzer (default)
tsdoc aidoc

# Use aggressive trimming
tsdoc aidoc --trim

# Check token usage details
tsdoc tokens --all --analyze

Or configure stricter limits:

{
  "tsdoc": {
    "context": {
      "maxTokens": 100000,
      "tiers": {
        "essential": { "minScore": 0.9, "trimLevel": "none" },
        "important": { "minScore": 0.7, "trimLevel": "aggressive" },
        "optional": { "minScore": 0.5, "trimLevel": "aggressive" }
      }
    }
  }
}

Missing API Key

Set your OpenAI key:

export OPENAI_TOKEN="your-key-here"
tsdoc aidoc

Slow Performance

Enable caching and adjust settings:

{
  "tsdoc": {
    "context": {
      "cache": {
        "enabled": true,
        "ttl": 7200,
        "maxSize": 200
      },
      "analyzer": {
        "enabled": true
      }
    }
  }
}

Cache Issues

Clear the cache if needed:

rm -rf .nogit/context-cache

Why tsdoc?

🎯 Actually Understands Your Code

Not just parsing, but real comprehension through AI. The smart context system ensures AI sees the most relevant parts of your codebase.

⏱️ Saves Hours

Generate complete, accurate documentation in seconds. The intelligent caching system makes subsequent runs even faster.

🔄 Always Up-to-Date

Regenerate documentation with every change. Smart dependency analysis ensures nothing important is missed.

🎨 Beautiful Output

Clean, professional documentation every time. AI understands your code's purpose and explains it clearly.

🛠️ Developer-Friendly

Built by developers, for developers. Sensible defaults, powerful configuration, and extensive programmatic API.

💰 Cost-Effective

Smart context optimization reduces AI API costs by 40-60% without sacrificing quality.

Architecture

Core Components

@git.zone/tsdoc
├── AiDoc              # Main AI documentation orchestrator
├── TypeDoc            # Traditional TypeDoc integration
├── Context System     # Smart context building
│   ├── EnhancedContext      # Main context builder
│   ├── LazyFileLoader       # Efficient file loading
│   ├── ContextCache         # Performance caching
│   ├── ContextAnalyzer      # Intelligent file analysis
│   ├── ContextTrimmer       # Adaptive code trimming
│   ├── ConfigManager        # Configuration management
│   └── TaskContextFactory   # Task-specific contexts
└── CLI                # Command-line interface

Data Flow

Project Files
    ↓
LazyFileLoader (metadata scan)
    ↓
ContextAnalyzer (scoring & prioritization)
    ↓
ContextCache (check cache)
    ↓
File Loading (parallel, on-demand)
    ↓
ContextTrimmer (tier-based)
    ↓
Token Budget (enforcement)
    ↓
AI Model (GPT-5)
    ↓
Generated Documentation

Contributing

We appreciate your interest! However, we are not accepting external contributions at this time. If you find bugs or have feature requests, please open an issue.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

@git.zone/tsdoc 🚀

What is tsdoc?