For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Install

# 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:

# In your project root
tsdoc aidoc

This will:

Analyze your codebase using an AI agent with filesystem access
Generate a comprehensive readme.md
Update package.json and npmextra.json with an AI-generated description and keywords

You can also run these separately:

# 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:

tsdoc commit

Output is a JSON object following conventional commits:

{
  "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:

# 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:

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:

Environment variable: OPENAI_TOKEN
Interactive prompt: On first run, tsdoc will prompt for the token and persist it
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:

{
  "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:

Receives a system prompt defining its role and constraints
Gets access to scoped filesystem tools (read-only, limited to project directory)
Explores the project structure autonomously using tool calls
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 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.

readme.md

@git.zone/tsdoc

Issue Reporting and Security