docsync

从代码自动生成文档并通过 git hook 检测文档偏差。免费自述文件生成 + 付费生活文档。

# DocSync — Living Documentation for Your Codebase

DocSync generates documentation from your code and keeps it in sync automatically. It uses tree-sitter for multi-language AST parsing, lefthook for git hook integration, and difftastic for semantic change detection.

## Commands

### Free Tier (No license required)

#### `docsync generate <file-or-directory>`
Generate a one-shot README or API doc for a single file or directory.

**How to execute:**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" generate <target>
```

**What it does:**
1. Parses the target file(s) with tree-sitter to extract symbols (functions, classes, exports, types, interfaces)
2. Applies the appropriate template from `<SKILL_DIR>/templates/`
3. Generates a markdown documentation file alongside the source

**Example usage scenarios:**
- "Generate docs for src/utils/auth.ts" → runs `docsync generate src/utils/auth.ts`
- "Document this whole directory" → runs `docsync generate src/api/`
- "Create a README for this project" → runs `docsync generate .`

### Pro Tier ($29/user/month — requires DOCSYNC_LICENSE_KEY)

#### `docsync drift [directory]`
Scan for documentation drift — find where code has changed but docs haven't been updated.

**How to execute:**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" drift [directory]
```

**What it does:**
1. Validates license key from config
2. Parses all source files with tree-sitter
3. Compares extracted symbols against existing documentation
4. Reports: new undocumented symbols, changed signatures with stale docs, deleted symbols still in docs
5. Outputs a drift report with severity levels (critical/warning/info)

#### `docsync hooks install`
Install git hooks that automatically check for doc drift on every commit.

**How to execute:**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" hooks install
```

**What it does:**
1. Validates Pro+ license
2. Copies lefthook config to project root
3. Installs lefthook pre-commit hook
4. On every commit: analyzes staged files, blocks commit if critical drift detected, offers auto-regen

#### `docsync hooks uninstall`
Remove DocSync git hooks.

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" hooks uninstall
```

#### `docsync auto-fix [directory]`
Auto-regenerate stale documentation for files with detected drift.

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" auto-fix [directory]
```

### Team Tier ($49/user/month — requires DOCSYNC_LICENSE_KEY with team tier)

#### `docsync onboarding [directory]`
Generate a comprehensive onboarding guide for new developers.

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" onboarding [directory]
```

#### `docsync architecture [directory]`
Generate architecture documentation showing module relationships and data flow.

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" architecture [directory]
```

## Supported Languages

DocSync uses tree-sitter grammars and supports:
- JavaScript / TypeScript (including JSX/TSX)
- Python
- Rust
- Go
- Java
- C / C++
- Ruby
- PHP
- C#
- Swift
- Kotlin

## Configuration

Users can configure DocSync in `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "docsync": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "outputDir": "docs",
          "templateOverrides": {},
          "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
          "languages": ["typescript", "python", "go"],
          "driftThreshold": "warning",
          "autoFix": false
        }
      }
    }
  }
}
```

## Important Notes

- **Free tier** works immediately with no configuration
- **Pro/Team tiers** require a license key from https://docsync.pages.dev
- All processing happens **locally** — no code is sent to external servers
- License validation is **offline** — no network calls needed
- Git hooks use **lefthook** which must be installed (see install metadata above)
- tree-sitter and difftastic are optional but recommended for best results; the skill falls back to regex-based parsing if unavailable

## Error Handling

- If tree-sitter is not installed, fall back to regex-based symbol extraction (less accurate but functional)
- If lefthook is not installed and user tries `hooks install`, prompt to install it
- If license key is invalid or expired, show clear message with link to https://docsync.pages.dev/renew
- If a language grammar is not available, skip that file with a warning

## When to Use DocSync

The user might say things like:
- "Generate docs for this file/project"
- "Are my docs up to date?"
- "Check for documentation drift"
- "Set up auto-docs on my commits"
- "Create an onboarding guide"
- "Document the architecture"
- "What's undocumented in this codebase?"

---

## 中文说明

# DocSync — 为你的代码库提供生活文档

DocSync 从你的代码生成文档，并自动保持其同步。它使用 tree-sitter 进行多语言 AST 解析，使用 lefthook 集成 git hook，并使用 difftastic 进行语义变更检测。

## 命令

### 免费版（无需许可证）

#### `docsync generate <file-or-directory>`
为单个文件或目录一次性生成 README 或 API 文档。

**如何执行：**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" generate <target>
```

**它做什么：**
1. 使用 tree-sitter 解析目标文件以提取符号（函数、类、导出、类型、接口）
2. 应用 `<SKILL_DIR>/templates/` 中的相应模板
3. 在源码旁生成一个 markdown 文档文件

**使用场景示例：**
- "Generate docs for src/utils/auth.ts" → 运行 `docsync generate src/utils/auth.ts`
- "Document this whole directory" → 运行 `docsync generate src/api/`
- "Create a README for this project" → 运行 `docsync generate .`

### 专业版（$29/用户/月 —— 需要 DOCSYNC_LICENSE_KEY）

#### `docsync drift [directory]`
扫描文档偏差 —— 找出代码已变更但文档尚未更新的地方。

**如何执行：**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" drift [directory]
```

**它做什么：**
1. 从配置中校验许可证密钥
2. 使用 tree-sitter 解析所有源文件
3. 将提取的符号与现有文档进行比较
4. 报告：新增的未记录符号、签名已变更但文档过时的符号、已删除但文档仍在的符号
5. 输出带严重级别（critical/warning/info）的偏差报告

#### `docsync hooks install`
安装 git hook，在每次提交时自动检查文档偏差。

**如何执行：**
```bash
bash "<SKILL_DIR>/scripts/docsync.sh" hooks install
```

**它做什么：**
1. 校验专业版及以上的许可证
2. 将 lefthook 配置复制到项目根目录
3. 安装 lefthook pre-commit hook
4. 每次提交时：分析暂存文件，若检测到严重偏差则阻止提交，并提供自动重新生成

#### `docsync hooks uninstall`
移除 DocSync 的 git hook。

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" hooks uninstall
```

#### `docsync auto-fix [directory]`
为检测到偏差的文件自动重新生成过时文档。

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" auto-fix [directory]
```

### 团队版（$49/用户/月 —— 需要团队版的 DOCSYNC_LICENSE_KEY）

#### `docsync onboarding [directory]`
为新开发者生成一份全面的入门指南。

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" onboarding [directory]
```

#### `docsync architecture [directory]`
生成展示模块关系和数据流的架构文档。

```bash
bash "<SKILL_DIR>/scripts/docsync.sh" architecture [directory]
```

## 支持的语言

DocSync 使用 tree-sitter 语法，支持：
- JavaScript / TypeScript（包括 JSX/TSX）
- Python
- Rust
- Go
- Java
- C / C++
- Ruby
- PHP
- C#
- Swift
- Kotlin

## 配置

用户可在 `~/.openclaw/openclaw.json` 中配置 DocSync：

```json
{
  "skills": {
    "entries": {
      "docsync": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "outputDir": "docs",
          "templateOverrides": {},
          "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
          "languages": ["typescript", "python", "go"],
          "driftThreshold": "warning",
          "autoFix": false
        }
      }
    }
  }
}
```

## 重要说明

- **免费版**无需任何配置即可立即使用
- **专业版/团队版**需要来自 https://docsync.pages.dev 的许可证密钥
- 所有处理都在**本地**进行 —— 不会有代码发送到外部服务器
- 许可证校验为**离线**进行 —— 无需任何网络调用
- Git hook 使用 **lefthook**，必须先安装它（参见上面的 install 元数据）
- tree-sitter 和 difftastic 为可选项，但推荐使用以获得最佳效果；若不可用，技能会回退到基于正则的解析

## 错误处理

- 若未安装 tree-sitter，回退到基于正则的符号提取（准确度较低但可用）
- 若未安装 lefthook 而用户尝试执行 `hooks install`，提示其先安装
- 若许可证密钥无效或已过期，显示清晰的提示信息并附上 https://docsync.pages.dev/renew 链接
- 若某语言的语法不可用，跳过该文件并给出警告

## 何时使用 DocSync

用户可能会这样说：
- "Generate docs for this file/project"
- "Are my docs up to date?"
- "Check for documentation drift"
- "Set up auto-docs on my commits"
- "Create an onboarding guide"
- "Document the architecture"
- "What's undocumented in this codebase?"