tsdoc/readme.md

# @git.zone/tsdoc 🚀
**AI-Powered Documentation for TypeScript Projects**

> Stop writing documentation. Let AI understand your code and do it for you.

## What is tsdoc?

`@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
- **📚 TypeDoc Integration** - Classic API documentation generation when you need it
- **💬 Smart Commit Messages** - AI analyzes your changes and suggests meaningful commit messages
- **🎯 Context Optimization** - Intelligent token management for efficient AI processing
- **📦 Zero Config** - Works out of the box with sensible defaults
- **🔧 Highly Configurable** - Customize every aspect when needed

## Installation

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

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

## Quick Start

### Generate AI-Powered Documentation

```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

### Generate Traditional TypeDoc

```bash
tsdoc typedoc --publicSubdir docs
```

### Get Smart Commit Messages

```bash
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:

```bash
# 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

```typescript
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);
};
```

### TypeDoc Generation

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

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

### Context Management

Control how tsdoc processes your codebase:

```typescript
import { EnhancedContext } 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
const result = await context.buildContext('readme');
console.log(`Tokens used: ${result.tokenCount}`);
```

## Configuration

Configure tsdoc via `npmextra.json`:

```json
{
  "tsdoc": {
    "context": {
      "maxTokens": 150000,
      "contextMode": "trimmed",
      "includePatterns": ["**/*.ts"],
      "excludePatterns": ["**/*.test.ts"],
      "trimming": {
        "removeImplementations": true,
        "preserveJSDoc": true,
        "removeComments": true
      }
    }
  }
}
```

## How It Works

1. **🔍 Code Analysis** - Scans your TypeScript files, package.json, and existing documentation
2. **✂️ Smart Trimming** - Optimizes code context to fit within AI token limits
3. **🧠 AI Processing** - Sends optimized context to AI for analysis
4. **📝 Generation** - Creates documentation that understands your code's purpose and structure

### Context Optimization

tsdoc employs sophisticated strategies to maximize the value of every token:

- **Intelligent Trimming** - Removes implementation details while preserving signatures
- **Priority Sorting** - Most important files first
- **Smart Summarization** - Condenses large files while maintaining context
- **Token Budgeting** - Ensures optimal use of AI context windows

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_TOKEN` | Your OpenAI API key for AI features |

## Use Cases

### 🚀 Continuous Integration

```yaml
# .github/workflows/docs.yml
- name: Generate Documentation
  run: |
    npm install -g @git.zone/tsdoc
    tsdoc aidoc
```

### 🔄 Pre-Commit Hooks

```bash
# Generate commit message before each commit
tsdoc commit
```

### 📦 Package Publishing

```javascript
// Ensure docs are updated before publish
{
  "scripts": {
    "prepublishOnly": "tsdoc aidoc"
  }
}
```

## Advanced Features

### Multi-Module Projects

tsdoc automatically detects and documents multi-module projects:

```typescript
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);
}
```

### Custom Context Building

Fine-tune what gets sent to AI:

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

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

// Get optimized context for specific tasks
const readmeContext = await factory.getContext('readme');
const commitContext = await factory.getContext('commit');
```

## Performance

- ⚡ **Fast** - Parallel file processing and smart caching
- 💾 **Efficient** - Minimal memory footprint with streaming
- 🎯 **Accurate** - Context optimization ensures AI gets the most relevant code
- 💰 **Cost-Effective** - Token optimization reduces AI API costs

## 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
# Use trimmed mode
tsdoc aidoc --trim

# Check token usage
tsdoc tokens --all
```

### Missing API Key

Set your OpenAI key:
```bash
export OPENAI_TOKEN="your-key-here"
tsdoc aidoc
```

## Why tsdoc?

- **🎯 Actually Understands Your Code** - Not just parsing, but comprehension
- **⏱️ Saves Hours** - Generate complete documentation in seconds
- **🔄 Always Up-to-Date** - Regenerate documentation with every change
- **🎨 Beautiful Output** - Clean, professional documentation every time
- **🛠️ Developer-Friendly** - Built by developers, for developers

## 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](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.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

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.