git.zone/tsdoc
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

BREAKING CHANGE(aidoc): migrate agent orchestration to new runAgent API and filesystem tools; refactor model handling and update README and tests

Browse Source
This commit is contained in:
Jürgen Kunz
2026-03-11 18:58:48 +00:00
parent 883985dbc0
commit 6b2957b272
11 changed files with 834 additions and 3270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

492
readme.md
View File

@@ -1,4 +1,4 @@
# @git.zone/tsdoc 🚀
# @git.zone/tsdoc
AI-Powered Documentation for TypeScript Projects
@@ -6,402 +6,226 @@ AI-Powered Documentation for TypeScript Projects
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://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/](https://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
## Install
```bash
# Global installation (recommended)
# Global installation (recommended for CLI usage)
pnpm add -g @git.zone/tsdoc
# Or use with npx
npx @git.zone/tsdoc
# Or install locally as a dependency
pnpm add @git.zone/tsdoc
```
## Quick Start
## Usage
### Generate AI-Powered Documentation
`@git.zone/tsdoc` is a comprehensive TypeScript documentation tool that combines traditional TypeDoc API documentation generation with AI-powered documentation workflows. It uses OpenAI models via the Vercel AI SDK to generate READMEs, project descriptions, keywords, and semantic commit messages by intelligently exploring your project with agentic tool use.
### CLI Commands
| Command | Description |
|---------|-------------|
| `tsdoc` | Auto-detects project type and runs TypeDoc |
| `tsdoc aidoc` | Generates AI-powered README + description/keywords |
| `tsdoc readme` | Generates AI-powered README only |
| `tsdoc description` | Generates AI-powered description and keywords only |
| `tsdoc commit` | Generates a semantic commit message from uncommitted changes |
| `tsdoc typedoc` | Generates traditional TypeDoc API documentation |
### Generating AI-Powered Documentation
The `aidoc` command combines README generation and description/keyword generation in one step:
```bash
# 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
This will:
1. Analyze your codebase using an AI agent with filesystem access
2. Generate a comprehensive `readme.md`
3. Update `package.json` and `npmextra.json` with an AI-generated description and keywords
### Generate Traditional TypeDoc
You can also run these separately:
```bash
tsdoc typedoc --publicSubdir docs
# Generate only the README
tsdoc readme
# Generate only the description and keywords
tsdoc description
```
### Get Smart Commit Messages
### Generating Commit Messages
The `commit` command analyzes your uncommitted changes and produces a structured commit object:
```bash
tsdoc commit
```
## CLI Commands
Output is a JSON object following conventional commits:
| 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:
```bash
# 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
```json
{
"recommendedNextVersionLevel": "feat",
"recommendedNextVersionScope": "core",
"recommendedNextVersionMessage": "add new feature for better documentation",
"recommendedNextVersionDetails": [
"implemented X",
"refactored Y"
],
"recommendedNextVersion": "1.13.0",
"changelog": "# Changelog\n\n## 2026-03-11 - 1.13.0 - core\n..."
}
```
### Command Options
The commit command includes intelligent diff processing that:
- Excludes lock files, build artifacts, IDE directories, and caches from the diff
- Prioritizes source files over build artifacts
- Samples large diffs with head/tail extraction to stay within token budgets
- Automatically generates or updates the changelog
#### tsdoc aidoc
- `--tokens` / `--showTokens` - Show token count before generating
- `--tokensOnly` - Only show token count, don't generate
### Generating TypeDoc
#### tsdoc typedoc
- `--publicSubdir <dir>` - Output subdirectory within public folder
For traditional API documentation via TypeDoc:
#### 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`)
```bash
# Generate to default ./public directory
tsdoc typedoc
# Generate to a specific subdirectory
tsdoc typedoc --publicSubdir docs
```
### Monorepo Support
When generating READMEs, tsdoc automatically detects monorepo submodules via `@git.zone/tspublish` conventions. Each submodule directory with a `tspublish.json` gets its own generated README.
### Programmatic API
You can also use tsdoc programmatically:
```typescript
import { AiDoc } from '@git.zone/tsdoc';
const aidoc = new AiDoc();
await aidoc.start(); // Initializes the AI model (prompts for OpenAI token if needed)
// Generate a README
await aidoc.buildReadme('/path/to/project');
// Generate description and keywords
await aidoc.buildDescription('/path/to/project');
// Generate a commit message object
const commitObj = await aidoc.buildNextCommitObject('/path/to/project');
console.log(commitObj);
// Get project context information
const context = await aidoc.getProjectContext('/path/to/project');
// Get token count for a project
const tokenCount = await aidoc.getProjectContextTokenCount('/path/to/project');
// Estimate tokens in arbitrary text
const tokens = aidoc.countTokens('some text here');
await aidoc.stop();
```
## Configuration
Configure tsdoc via `npmextra.json`:
### OpenAI Token
An OpenAI API key is required for all AI features. It can be provided in three ways:
1. **Environment variable**: `OPENAI_TOKEN`
2. **Interactive prompt**: On first run, tsdoc will prompt for the token and persist it
3. **Constructor argument**: Pass `{ OPENAI_TOKEN: 'sk-...' }` to `new AiDoc()`
The token is persisted at `~/.npmextra/kv/@git.zone/tsdoc.json` for subsequent runs.
### npmextra.json
tsdoc uses `npmextra.json` for project metadata. The `tsdoc` key holds legal information that gets appended to generated READMEs:
```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
}
"tsdoc": {
"legal": "\n## License and Legal Information\n\n..."
},
"gitzone": {
"module": {
"githost": "gitlab.com",
"gitscope": "gitzone",
"gitrepo": "tsdoc",
"npmPackagename": "@git.zone/tsdoc",
"description": "...",
"keywords": ["..."]
}
}
}
```
### 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
1. **📊 Fast Metadata Scanning** - Lazy loading scans files without reading contents
2. **🧬 Dependency Analysis** - Builds dependency graph from import statements
3. **🎯 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)
4. **🏆 Smart Prioritization** - Files sorted by combined importance score
5. **🎭 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
6. **💾 Intelligent Caching** - Cache results with file change detection
7. **🧠 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
```yaml
# .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
```bash
# .git/hooks/prepare-commit-msg
#!/bin/bash
tsdoc commit > .git/COMMIT_EDITMSG
```
### 📦 Package Publishing
```json
{
"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:
```bash
# Check token usage details
tsdoc tokens --all --detailed
```
Or configure stricter limits in `npmextra.json`:
```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:
```bash
export OPENAI_TOKEN="your-key-here"
tsdoc aidoc
```
### Slow Performance
Enable caching and adjust settings in `npmextra.json`:
```json
{
"@git.zone/tsdoc": {
"context": {
"cache": {
"enabled": true,
"ttl": 7200,
"maxSize": 200
}
}
}
}
```
### Cache Issues
Clear the cache if needed:
```bash
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
├── AiDoc # Main orchestrator - manages AI model and delegates to task classes
├── TypeDoc # Traditional TypeDoc API documentation generation
├── ProjectContext # Gathers project files for context (package.json, ts/, test/)
├── DiffProcessor # Intelligent git diff processing with prioritization and sampling
├── Readme # AI-powered README generation using runAgent with filesystem tools
├── Commit # AI-powered commit message generation with diff analysis
├── Description # AI-powered description and keyword generation
└── CLI # Command-line interface built on @push.rocks/smartcli
```
### Data Flow
### AI Agent Architecture
```
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
```
tsdoc uses `@push.rocks/smartagent`'s `runAgent()` function with `@push.rocks/smartai`'s `getModel()` for all AI tasks. Each documentation task (readme, commit, description) runs an autonomous AI agent that:
1. Receives a system prompt defining its role and constraints
2. Gets access to scoped filesystem tools (read-only, limited to project directory)
3. Explores the project structure autonomously using tool calls
4. Produces the final output (README markdown, commit JSON, or description JSON)
### Diff Processing
The `DiffProcessor` class handles large git diffs intelligently:
- **Small files** (< 300 lines): Included in full
- **Medium files** (< 800 lines): Head/tail sampling with context
- **Large files**: Metadata only (filepath, lines added/removed)
- Files are prioritized by importance: source > test > config > docs > build artifacts
- Token budget is enforced dynamically based on OpenAI's context limits
## Requirements
- **Node.js** >= 18.0.0
- **TypeScript** project with `ts/` source directory
- **OpenAI API key** (for AI features)
## 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](./LICENSE) file.
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](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 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.
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.
### Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.