# @git.zone/tsdoc 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. ## Install ```bash # 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 ``` ## Usage `@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 ``` 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 You can also run these separately: ```bash # Generate only the README tsdoc readme # Generate only the description and keywords tsdoc description ``` ### Generating Commit Messages The `commit` command analyzes your uncommitted changes and produces a structured commit object: ```bash tsdoc commit ``` Output is a JSON object following conventional commits: ```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..." } ``` 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 ### Generating TypeDoc For traditional API documentation via TypeDoc: ```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 ### 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 { "tsdoc": { "legal": "\n## License and Legal Information\n\n..." }, "gitzone": { "module": { "githost": "gitlab.com", "gitscope": "gitzone", "gitrepo": "tsdoc", "npmPackagename": "@git.zone/tsdoc", "description": "...", "keywords": ["..."] } } } ``` ## Architecture ### Core Components ``` @git.zone/tsdoc ├── 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 ``` ### AI Agent Architecture 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 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.