"description":"A comprehensive TypeScript documentation tool that leverages AI to generate and enhance project documentation, including dynamic README creation, API docs via TypeDoc, and smart commit message generation.",
"type":"module",
@@ -13,36 +13,35 @@
"tsdoc":"cli.js"
},
"scripts":{
"test":"(tstest test/) && npm run testCli",
"test":"(tstest test/ --verbose --logfile --timeout 600) && npm run testCli",
An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.
# @git.zone/tsdoc 🚀
**AI-Powered Documentation for TypeScript Projects**
## Install
> Stop writing documentation. Let AI understand your code and do it for you.
To install @git.zone/tsdoc, you have two options. You can install it globally so that the CLI commands are available throughout your system, or you can use it with npx if you prefer to keep the installation local to your project.
## What is tsdoc?
### Global Installation
`@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.
To install the tool globally, run the following command in your terminal:
### ✨ 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
```
Installing globally ensures that the CLI commands (such as tsdoc, tsdoc typedoc, tsdoc aidoc, etc.) are available anywhere on your machine without the need to refer to the local node_modules folder.
## Quick Start
### Usage with npx
If you prefer not to install the tool globally, you can invoke it using npx directly from your project. This method works well if you intend to use the tool on a per-project basis:
### Generate AI-Powered Documentation
```bash
npx @git.zone/tsdoc <command>
# In your project root
tsdoc aidoc
```
In the commands below, you will see how to use the various functionalities that @git.zone/tsdoc provides for generating intricate and enhanced documentation for your TypeScript projects.
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
## Usage
The @git.zone/tsdoc module provides a very rich and interactive CLI interface together with a set of programmable classes that let you integrate documentation generation into your build processes or workflows. This section will walk you through every aspect of the module—from its basic CLI commands to its advanced internal API usage. All examples provided below use ESM syntax with TypeScript and are designed to be comprehensive. Every code snippet is written so you can easily copy, paste, and adapt to your project. The following guide is divided into several sections covering every major feature, tool integration, and customization options available in the module.
At its heart, @git.zone/tsdoc is a CLI tool that blends classic documentation generation (using libraries such as TypeDoc) with AI-enhanced techniques. The tool reads your project files, uses a context builder to optimize file content based on token usage and configurable trimming strategies, and then leverages an AI engine to generate enhanced documentation. This complete solution is designed to integrate smoothly into your project pipeline.
Key features include:
- **Auto-detection of documentation format**: The CLI attempts to determine the best documentation strategy for your project.
- **Support for TypeDoc generation**: Build TypeDoc-compatible documentation directly.
- **AI-Enhanced Documentation (AiDoc)**: Generate a README and project description using artificial intelligence that analyzes your project’s code and context.
- **Plugin Integration**: The module leverages a variety of plugins (smartfile, smartgit, smartcli, smartai, etc.) to streamline tasks such as file manipulation, CLI interaction, shell command execution, and logging.
- **Context Trimming and Optimization**: To manage token usage (especially for AI input), the module includes advanced context-building strategies that trim and summarize code files intelligently.
- **Robust Internal API**: While the primary user interface is through the CLI, the underlying classes (AiDoc, TypeDoc, Readme, etc.) can be used to build custom integrations or extend the tool’s functionality.
Below, you will find detailed explanations along with ESM/TypeScript code examples for all core use cases.
The most common way to interact with @git.zone/tsdoc is via its command-line interface (CLI). The CLI is designed to auto-detect your project’s context and trigger the appropriate commands based on your needs. Below is a guide on how to use the CLI commands.
#### Basic Invocation
When you run the command without any arguments, the tool attempts to determine the appropriate documentation generation mode:
```bash
tsdoc
```
This will scan the project directory and attempt to detect whether your project follows a TypeDoc convention or if it would benefit from an AI-enhanced documentation build. The auto-detection logic uses the project context (for example, the presence of a ts directory or specific configuration files) to decide the best course of action.
##### Example Scenario
Imagine you have a TypeScript project with the following structure:
├── package.json
├── ts/
│ └── index.ts
└── readme.hints.md
When you execute:
```bash
tsdoc
```
The tool will analyze the project directory, recognizing the ts/ folder, and it will route the command to the appropriate documentation generator, such as the TypeDoc generator if it detects valid structure.
#### TypeDoc Command
For projects that require a traditional documentation format, you can explicitly generate documentation using the TypeDoc integration:
### Generate Traditional TypeDoc
```bash
tsdoc typedoc --publicSubdir docs
```
This command instructs the module to generate HTML documentation using TypeDoc, placing the output into a public directory (or a custom subdirectory as specified).
**Inside a TypeScript file, this command can be mirrored by calling the TypeDoc class directly:**
// Specify the output subdirectory for documentation
awaittypeDocInstance.compile({
publicSubdir:'docs'
});
console.log('Documentation successfully generated using TypeDoc.');
}catch(error){
console.error('Error generating documentation with TypeDoc:',error);
}
};
compileDocumentation();
```
In this example, the script creates an instance of the TypeDoc class passing the current working directory. The compile method is then called with an options object, indicating that the public subdirectory should be named “docs.” The method spawns a shell command using the smart shell plugin to execute the TypeDoc binary.
#### AI-Enhanced Documentation Command
One of the standout features of this module is its AI-enhanced documentation capabilities. The `aidoc` command integrates with an OpenAI interface to produce a more contextual and detailed README and project description. This is particularly useful when your project codebase has evolved and requires documentation updates based on the current source code.
To run the AI-enhanced documentation generation:
### Get Smart Commit Messages
```bash
tsdoc aidoc
tsdoc commit
```
In an ESM/TypeScript project, you can use the AiDoc class to programmatically run the same functionality:
## CLI Commands
```typescript
import{AiDoc}from'@git.zone/tsdoc';
| Command | Description |
|---------|-------------|
| `tsdoc` | Auto-detects and runs appropriate documentation |
console.error('Failed to generate AI-enhanced documentation:',error);
}
};
buildEnhancedDocs();
```
In the above snippet, we import the AiDoc class and create an instance with an OpenAI token. The methods start(), buildReadme(), and buildDescription() streamline the process of generating enhanced documentation by leveraging the underlying AI engine. This code example should serve as a blueprint for those wishing to integrate AI-driven documentation updates as part of their CI/CD pipelines.
#### Testing Your Documentation Setup
Before you commit changes to your project documentation, it is often worthwhile to run tests to ensure that your documentation generation process is behaving as expected. The module includes a `test` command:
Understanding token usage helps optimize AI costs:
```bash
tsdoc test
# 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
```
This command verifies that all components (CLI commands, TypeDoc compilation, AI integration, etc.) are properly configured.
## Programmatic Usage
Here is an example test script written in TypeScript using a test bundle:
// Attempt buildReadme and buildDescription synchronously for test coverage
awaitaidoc.buildReadme(process.cwd());
awaitaidoc.buildDescription(process.cwd());
// If no errors are thrown, we assume the process works as expected
expect(true).toBe(true);
});
tap.start();
```
This test script demonstrates how to automate the validation process by using the provided AiDoc class. Using a testing framework like tap ensures that your documentation generation remains robust even as new features are added or as the project evolves.
Beyond using the CLI, @git.zone/tsdoc provides various classes and plugins that allow you to deeply integrate documentation generation within your project. The following sections document advanced usage scenarios where you programmatically interact with different components.
#### 1. Deep Dive into AiDoc Functionality
The AiDoc class is the core of the AI-enhanced documentation generation. It manages interactions with the OpenAI API, handles token validations, and integrates with project-specific configurations.
Consider the following advanced usage example:
### Generate Documentation Programmatically
```typescript
import{AiDoc}from'@git.zone/tsdoc';
import*aspathfrom'path';
constgenerateProjectDocs=async()=>{
// Create an instance of the AiDoc class with a configuration object
// that includes your OpenAI token. This token will be used to query the AI.
In this example, the AiDoc class handles multiple tasks:
- It starts by validating and printing the sanitized token.
- It generates and writes the README file based on dynamic analysis.
- It updates the project description stored in your configuration files.
- It even integrates with Git to produce a suggested commit message that factors in the current state of the project directory.
Internally, methods such as buildReadme() interact with the ProjectContext class to gather files and determine the relevant context. This context is trimmed and processed based on token budgets, thus ensuring that the AI interface only receives the information it can effectively process.
#### 2. Interacting with the TypeDoc Class Programmatically
The TypeDoc class does not merely wrap the standard TypeDoc tool. It adds a layer of automation by preparing the TypeScript environment, generating a temporary tsconfig file, and invoking TypeDoc with the proper configuration. You can use this functionality to conditionally generate documentation or integrate it into your build steps.
Below is another example demonstrating the integration:
### TypeDoc Generation
```typescript
import{TypeDoc}from'@git.zone/tsdoc';
import*aspathfrom'path';
constgenerateTypeDocDocs=async()=>{
// Assume you are in the root directory of your TypeScript project
constcwd=process.cwd();
// Create an instance of the TypeDoc class
consttypeDocInstance=newTypeDoc(cwd);
// Prepare additional options if necessary (e.g., setting a public subdirectory for docs)
constoptions={publicSubdir:'documentation'};
// Compile your TypeScript project documentation.
// The compile method handles creating the tsconfig file, running the shell command, and cleaning up afterward.
try{
console.log('Compiling TypeScript documentation using TypeDoc...');
This script clearly demonstrates how TypeDoc automation is structured inside the module. By invoking the compile() method, the class takes care of setting directory paths, preparing command arguments, and executing the underlying TypeDoc binary using the smart shell plugin.
### Context Management
#### 3. Customizing Context Building
One of the critical functionalities within @git.zone/tsdoc is its ability to build a smart context for documentation generation. The module not only collects file content from your project (like package.json, readme.hints.md, and other source files) but also intelligently trims and summarizes these contents to fit within token limits for AI processing.
Consider the following deep-dive example into the context building process:
- The EnhancedContext class is initialized with the project directory.
- Configuration is loaded via the ConfigManager, which reads parameters from npmextra.json.
- The context builder then gathers files (such as package.json, readme hints, TypeScript sources, etc.), trims unnecessary content, and builds a context string.
- Finally, it prints the overall token counts and savings, giving you valuable feedback on how the context was optimized for the AI input.
## Configuration
This detailed context-building mechanism is essential for managing large TypeScript projects. It ensures that the AI engine can process relevant code data without being overwhelmed by too many tokens.
Configure tsdoc via `npmextra.json`:
#### 4. Working with the Readme Class for Automatic README Generation
The Readme class in @git.zone/tsdoc takes the AI-enhanced documentation further by not only generating a project-level README but also iterating over submodules within your project. This ensures that every published module has its own complete, AI-generated README.
Here is an advanced example demonstrating how to trigger README generation for the main project and its submodules:
logger.log('info',`Generated README for ${subModule}:\n${readmeContent.substring(0,200)}...`);
}catch(error){
logger.log('error',`Failed to read README for ${subModule}: ${error}`);
```json
{
"tsdoc":{
"context":{
"maxTokens":150000,
"contextMode":"trimmed",
"includePatterns":["**/*.ts"],
"excludePatterns":["**/*.test.ts"],
"trimming":{
"removeImplementations":true,
"preserveJSDoc":true,
"removeComments":true
}
}
}
};
buildProjectReadme();
}
```
In this example, the script:
- Starts by building the AI-enhanced README for the entire project.
- Then iterates over a list of submodule directories and generates READMEs for each.
- Uses the logging utility to provide immediate feedback on the generation process.
- Optionally, reads back a snippet of the generated file to verify successful documentation generation.
## How It Works
This approach ensures that projects with multiple submodules or packages maintain a consistent and high-quality documentation standard across every component.
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
Under the hood, @git.zone/tsdoc leverages a number of smaller, focused plugins that extend its functionality. These plugins facilitate file system operations, shell command execution, environment variable management, and logging. The modular design makes it easy to extend or customize the tool according to your needs.
tsdoc employs sophisticated strategies to maximize the value of every token:
The relevant plugins include:
-smartai: Provides the API integration with OpenAI.
-smartcli: Handles CLI input parsing and command setup.
-smartdelay: Manages asynchronous delays and debouncing.
- smartfile: Offers an abstraction over file I/O operations.
- smartinteract: Eases interaction with the user (prompting for tokens, confirming actions).
- smartlog and smartlogDestinationLocal: Provide comprehensive logging mechanisms.
- smartpath, smartshell, and smarttime: Manage file paths, execute shell commands, and process time data respectively.
- **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
Below is a sample snippet illustrating how you might directly interact with a few of these plugins to, for example, run a custom shell command or log events:
## 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:
- Set up a smartshell instance by specifying the shell executor and the directories where executables are located.
- Execute a command (in this case, listing directory contents) and log the results using the provided logging plugin.
### Custom Context Building
Such examples demonstrate the flexibility provided by the module’s internal API. They also illustrate that even if you choose not to use the CLI, you can still leverage the @git.zone/tsdoc functionality programmatically in a highly integrated fashion.
A unique feature of this tool is its capacity to assist with creating smart commit messages based on code changes. The Commit class (found within the aidocs_classes directory) ties together output from smartgit and AiDoc to suggest commit messages that are both descriptive and formatted according to conventional commit guidelines.
Consider this example where you generate a commit message based on the diff from your git repository:
2. The tool uses the smartgit plugin to fetch uncommitted changes from the repository.
3. It then builds a context string incorporating file diffs and project metadata.
4. Finally, the OpenAI API is queried to produce a commit message formatted as JSON. This JSON object is parsed and can be used directly in your git workflow.
## Performance
This advanced integration assists teams in maintaining consistent commit message standards while reducing the manual burden of summarizing code changes.
- ⚡ **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
If you are curious about the intricate inner workings of @git.zone/tsdoc and wish to extend or debug its behavior, here is an in-depth explanation of some internal mechanisms.
- Node.js >= 18.0.0
- TypeScript project
- OpenAI API key (for AI features)
#### Context Trimming Strategy
## Troubleshooting
Managing token count is critical when interfacing with APIs that have strict limits. The module uses a multi-step process:
- It gathers various files (such as package.json, ts files, readme hints).
- It sorts the files and calculates the token count using the GPT tokenizer.
- It applies trimming strategies such as removing function implementations or comments in TypeScript files, based on a configurable set of parameters.
- Finally, it constructs a unified context string that includes file boundaries for clarity.
### Token Limit Exceeded
For example, the ContextTrimmer class carries out these transformations:
This process helps in reducing the number of tokens before sending the data to the AI API while preserving the essential context needed for documentation generation.
### Missing API Key
#### Dynamic Configuration Management
The module’s configuration is stored in the npmextra.json file and includes settings for context building, trimming strategies, and task-specific options. The ConfigManager class reads these settings and merges them with default values. This dynamic configuration system ensures that the behavior of the documentation tool can be easily adjusted without altering the source code.
- Allows updates to specific keys (such as token limits).
- Persists these changes back to the file system using the smartfile plugin.
## Why tsdoc?
#### Logging and Diagnostic Output
Throughout its execution, @git.zone/tsdoc logs important information such as token counts, file statistics, and shell command outputs. This logging is accomplished through a combination of the smartlog and smartlogDestinationLocal plugins. The following example illustrates how logging can help diagnose execution issues:
logger.log('debug','Token budget set for context building:',150000);
// Simulate a long-running process
setTimeout(()=>{
logger.log('info','Documentation generation process completed successfully.');
},2000);
};
logDiagnosticInfo();
```
Using comprehensive logging, the tool provides feedback not only during normal execution but also in error scenarios, allowing developers to troubleshoot and optimize their documentation generation workflow.
### Integrating @git.zone/tsdoc into a Continuous Integration Pipeline
For teams looking to integrate documentation generation into their CI processes, @git.zone/tsdoc can be harnessed by scripting the CLI commands or by embedding the class-based API directly into your build scripts. Here’s an example of a CI script written in TypeScript that runs as part of a GitHub Action or similar workflow:
logger.log('error','Documentation pipeline encountered an error:',error);
process.exit(1);
}
};
runDocumentationPipeline();
```
In a CI environment, you can invoke this script to ensure that documentation is generated or updated as part of your deployment process. The process includes building the README, updating project descriptions, and generating TypeDoc documentation if the project structure warrants it.
Below is a full-fledged example that combines many of the above functionalities into a single workflow. This script is intended to be run as part of your build process or as a standalone command, and it demonstrates how to initialize all parts of the module, generate documentation for the main project and its submodules, update configuration, and log key diagnostics.
The examples provided above demonstrate that @git.zone/tsdoc is not simply a CLI tool—it is a complete documentation framework designed to adapt to your workflow. Whether you are a developer looking to automate documentation updates in your CI pipeline or a team seeking an AI-powered enhancement for your project metadata, this module offers a wide range of interfaces and hooks for you to leverage.
Key takeaways:
- The CLI handles most routine tasks automatically while also exposing commands for specific documentation generation strategies.
- Programmatic usage allows deep integration with your project’s build and commit processes.
- The internal architecture—built on plugins, context optimization, and extensive logging—ensures that the tool can scale with project complexity.
- Advanced users can customize context trimming, file inclusion rules, and even modify AI queries to better suit their project’s needs.
Each code example provided here is written using modern ESM syntax and TypeScript to ensure compatibility with current development practices. Since the module is designed with extensibility in mind, developers are encouraged to explore the source code (especially the classes in the ts/ and ts/aidocs_classes directories) for further customization opportunities.
By integrating @git.zone/tsdoc into your workflow, you ensure that your project documentation remains accurate, comprehensive, and reflective of your latest code changes—whether you are generating a simple README or a complex API documentation set enhanced by AI insights.
Happy documenting!
- **🎯 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
@@ -739,4 +298,4 @@ 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.
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.
description:'A comprehensive TypeScript documentation tool that leverages AI to generate and enhance project documentation, including dynamic README creation, API docs via TypeDoc, and smart commit message generation.'
For the recommendedNextVersionDetails, please only add a detail entries to the array if it has an obvious value to the reader.
You are being given the files of the project. You should use them to create the commit message.
Also you are given a diff
Also you are given a diff.
Never mention CLAUDE code, or codex.
`,
messageHistory:[],
userMessage: contextString,
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
