# roll-doc-audit —— 文档/产品一致性审计

`roll-doc-audit` 核对用户可见文档表面与真实实现: README、指南、网站页面、CLI help、
测试和源码。需要文档盘点时,它也会产出草稿文档:文档索引、为缺文档目录补的模块
README,以及 Phase 3b 阶段的跨目录主题文档(数据流、状态机、外部集成等)。它不会
在没有源码证据时编造行为。

```
$roll-doc-audit              # 完整运行(全部 phase)
$roll-doc-audit --dry-run    # 仅 Phase 1–2;打印 Phase 3 / 3b 计划,不写任何文件
$roll-doc-audit --force      # 即便目标文件已存在也重新生成草稿
```

## 四 Phase 全流程

roll-doc-audit 依序运行四个 phase,外加深度读取的 Phase 3b——当项目存在值得记录的
跨目录结构时触发。

| Phase | 名称 | 做什么 |
|-------|------|--------|
| 1 | Scan & Index | 遍历目录树,分类每个 `*.md` 与约定文件,(覆盖)写出 `docs/INDEX.md`,含覆盖率摘要与缺口报告。 |
| 2 | Gap Analysis | 找出有 ≥ 3 个源文件(或被 ≥ 5 个文件引用)却无 `README.md` 的模块目录,以及特殊缺口(领域模型图、约定文档)。 |
| 3 | Fill | 对每个目录级缺口,读取至多 20 个源文件并生成草稿 `README.md` / 上下文图 / 约定文档。已存在的文件除非 `--force` 否则跳过。 |
| 3b | Deep Read | 构建完整项目符号表(全量读取,不截断),侦测 Phase 3 单独无法发现的六类跨目录主题。 |
| 4 | Report | 打印各 phase 摘要:索引文档数、缺口数、生成草稿数、Phase 3b 符号表计数与主题文档。 |

Phase 3b 是"逐目录"文档与"贯穿整个代码库逻辑"文档之间的分水岭。Phase 3 孤立地
读取每个缺口目录(且每个目录至多 20 个文件);Phase 3b 全量读取每个源文件并跨文件
推理。

## Phase 3b —— 六类主题

Phase 3b 在**满足任一条件**时运行:Phase 2 发现了缺口,**或**项目展现出 Phase 3
无法捕捉的代码特征(跨 ≥ 3 个目录的 import 链、被共享的状态枚举、外部端点调用,
或 CI 配置)。纯文档项目若无源码缺口则完全跳过 Phase 3b。

构建符号表(`exports`、`imports`、`enums`、`external_urls`、`configs`)后,
Phase 3b 侦测六类主题。每类在其侦测规则无命中时跳过,目标文件已存在时也跳过
(除非 `--force`)。

| # | 主题 | 触发条件 | 输出 |
|---|------|----------|------|
| 1 | 数据流 / 调用链 | 从入口文件(`bin/`、`main.*`、`index.*`)出发的 import 链跨越 ≥ 3 个不同源目录 | `docs/data-flows.md` |
| 2 | 状态机 | 名为 `*State` / `*Status` 的枚举被 ≥ 2 个源文件引用 | `docs/state-machines.md` |
| 3 | 外部集成 | `fetch` / `axios` / `http.*` 调用或 `*_URL` / `*_HOST` 常量(排除注释与测试夹具) | `docs/integrations.md` |
| 4 | 部署管线 | 存在 CI 配置文件(`.github/workflows/*.yml`、`.gitlab-ci.yml`、`circle.yml`、`Jenkinsfile`)加部署 URL 模式 | `docs/deployment.md` |
| 5 | Agent 入口 | 根目录无 `AGENTS.md` 且源码根有 ≥ 3 个子目录 | `AGENTS.md` |
| 6 | 高引用目录 | 某目录被 ≥ 5 个其他源文件引用,即使自身 < 3 个源文件 | `<dir>/README.md` |

每篇主题文档都为每条论断标注 `file:line`,均来自真实符号表记录——roll-doc-audit 绝不
伪造行号。

## dry-run / force 行为

**`--dry-run`** 运行 Phase 1–2,随后打印 Phase 3 填充计划与 Phase 3b 计划
(符号表摘要计数,加上*将要*生成的主题文档,每条标 `(plan)`)。不写任何磁盘文件。
用它在完整运行前先预览。

**`--force`** 即便目标文件已存在也重新生成草稿。它只影响草稿生成(Phase 3 与
Phase 3b 的输出文件);无论带不带 flag,符号表每次运行都从头重建。`--force` 不改变
`docs/INDEX.md` 的行为(始终重建),也绝不覆盖草稿目标之外的人工内容。

**默认(无 flag)** 是幂等的:无新缺口时重新运行是 no-op——不写文件,不改已有
草稿。

## 典型输出文件清单

对一个含代码的项目完整运行,可能产出:

```
docs/INDEX.md            # Phase 1 —— 始终(覆盖)写出
src/<module>/README.md   # Phase 3 —— 每个模块缺口一个
docs/CONVENTIONS.md      # Phase 3 —— 当无约定文档时
.roll/domain/context-map.md  # Phase 3 —— 当无领域条目时
docs/data-flows.md       # Phase 3b —— 跨目录调用链
docs/state-machines.md   # Phase 3b —— 共享状态枚举
docs/integrations.md     # Phase 3b —— 外部端点
docs/deployment.md       # Phase 3b —— CI 管线
AGENTS.md                # Phase 3b —— 仅当不存在时
<dir>/README.md          # Phase 3b —— 高引用目录
```

只有 `docs/INDEX.md` 会被覆盖——它是派生产物。其余每个文件都是草稿,以下面这行
开头:

```
> **Draft** —— auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
```

审阅每篇草稿,按需修改,提交你想保留的那些。