For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What is tsdoc?

@git.zone/tsdoc is a next-generation documentation CLI 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 AI 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)
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

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

# Show detailed breakdown with file listing
tsdoc tokens --detailed --listFiles

Command Options

tsdoc aidoc

--tokens / --showTokens - Show token count before generating
--tokensOnly - Only show token count, don't generate

tsdoc typedoc

--publicSubdir <dir> - Output subdirectory within public folder

tsdoc tokens

--task <type> - Specify task type: readme, commit, or description
--all - Show stats for all task types
--detailed - Show detailed token usage and costs
--listFiles - List all files included in context
--model <name> - Show usage for specific model (gpt4, gpt35)

Configuration

Configure tsdoc via npmextra.json:

{
  "@git.zone/tsdoc": {
    "legal": "## License and Legal Information\n\n...",
    "context": {
      "maxTokens": 190000,
      "defaultMode": "trimmed",
      "cache": {
        "enabled": true,
        "ttl": 3600,
        "maxSize": 100
      },
      "analyzer": {
        "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)

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

Environment Variables

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

The token can also be provided interactively on first run - it will be persisted in ~/.npmextra/kv/@git.zone/tsdoc.json.

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"
  }
}

Requirements

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

Troubleshooting

Token Limit Exceeded

If you hit token limits, try:

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

Or configure stricter limits in npmextra.json:

{
  "@git.zone/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 in npmextra.json:

{
  "@git.zone/tsdoc": {
    "context": {
      "cache": {
        "enabled": true,
        "ttl": 7200,
        "maxSize": 200
      }
    }
  }
}

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.

💰 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
│   ├── DiffProcessor        # Git diff optimization
│   ├── 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
    ↓
Generated Documentation

License and Legal Information

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

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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@git.zone/tsdoc 🚀

Issue Reporting and Security