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

fix(npmextra): update to new format

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-13 11:42:39 +00:00
parent f8d0895aab
commit 3b1c84d7e8
18 changed files with 1951 additions and 1801 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
readme.md
View File

@@ -1,15 +1,18 @@
# @git.zone/tsdoc 🚀
**AI-Powered Documentation for TypeScript Projects**
> Stop writing documentation. Let AI understand your code and do it for you.
AI-Powered Documentation for TypeScript Projects
## Issue Reporting and Security
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 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.
`@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 GPT-5 and other models to generate contextual READMEs
- **🤖 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
@@ -22,9 +25,6 @@
```bash
# Global installation (recommended)
npm install -g @git.zone/tsdoc
# Or with pnpm
pnpm add -g @git.zone/tsdoc
# Or use with npx
@@ -66,7 +66,6 @@ tsdoc commit
| `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
@@ -79,91 +78,25 @@ tsdoc tokens
# Show detailed stats for all task types
tsdoc tokens --all
# Test with trimmed context
tsdoc tokens --trim
# Show detailed breakdown with file listing
tsdoc tokens --detailed --listFiles
```
## Programmatic Usage
### Command Options
### Generate Documentation Programmatically
#### tsdoc aidoc
- `--tokens` / `--showTokens` - Show token count before generating
- `--tokensOnly` - Only show token count, don't generate
```typescript
import { AiDoc } from '@git.zone/tsdoc';
#### tsdoc typedoc
- `--publicSubdir <dir>` - Output subdirectory within public folder
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
```typescript
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:
```typescript
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
```typescript
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();
```
#### 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
@@ -171,7 +104,8 @@ Configure tsdoc via `npmextra.json`:
```json
{
"tsdoc": {
"@git.zone/tsdoc": {
"legal": "## License and Legal Information\n\n...",
"context": {
"maxTokens": 190000,
"defaultMode": "trimmed",
@@ -181,7 +115,6 @@ Configure tsdoc via `npmextra.json`:
"maxSize": 100
},
"analyzer": {
"enabled": true,
"useAIRefinement": false
},
"prioritization": {
@@ -234,11 +167,6 @@ Configure tsdoc via `npmextra.json`:
- **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
@@ -270,21 +198,14 @@ The smart context system delivers significant improvements:
| **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) |
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
@@ -336,103 +257,6 @@ tsdoc commit > .git/COMMIT_EDITMSG
}
```
## 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);
}
await aiDoc.stop();
```
### Custom Context Building
Fine-tune what gets sent to AI with task-specific contexts:
```typescript
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:
```typescript
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:
```typescript
// 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:
```bash
# 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
@@ -446,21 +270,15 @@ tsdoc tokens --analyze # With smart prioritization
If you hit token limits, try:
```bash
# Enable smart analyzer (default)
tsdoc aidoc
# Use aggressive trimming
tsdoc aidoc --trim
# Check token usage details
tsdoc tokens --all --analyze
tsdoc tokens --all --detailed
```
Or configure stricter limits:
Or configure stricter limits in `npmextra.json`:
```json
{
"tsdoc": {
"@git.zone/tsdoc": {
"context": {
"maxTokens": 100000,
"tiers": {
@@ -484,19 +302,16 @@ tsdoc aidoc
### Slow Performance
Enable caching and adjust settings:
Enable caching and adjust settings in `npmextra.json`:
```json
{
"tsdoc": {
"@git.zone/tsdoc": {
"context": {
"cache": {
"enabled": true,
"ttl": 7200,
"maxSize": 200
},
"analyzer": {
"enabled": true
}
}
}
@@ -525,9 +340,6 @@ Regenerate documentation with every change. Smart dependency analysis ensures no
### 🎨 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.
@@ -545,6 +357,7 @@ Smart context optimization reduces AI API costs by 40-60% without sacrificing qu
│ ├── 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
@@ -567,30 +380,28 @@ ContextTrimmer (tier-based)
↓
Token Budget (enforcement)
↓
AI Model (GPT-5)
AI Model
↓
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](license) file within this repository.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./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 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.
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.
### 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 if you require further information, please contact us via email at hello@task.vc.
For any legal inquiries or 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.