# CIDI 管线

本仓库把「代码质量」与「文档/架构集成」放在同一条交付链上，简称 **CIDI**：

- **CI**：Node 单元测试矩阵 + 打包产物校验；
- **DI**：Docsify Wiki、ADR、链接审计与 LikeC4 模型链路的端到端集成。

两条线都通过后，才允许打 tag 发布到 npm 与 GitHub Release。

---

## 1. 流水线全景

```text
push / pull_request
        │
        ├── test (Node 22.x, 24.x) ── npm test（36 项单测）
        │
        ├── docs-pipeline ────────── npm run pipeline（7 个阶段）
        │
        └── package ──────────────── npm pack + 产物内容校验
                                         │
                                    upload-artifact
                                         │
tag v* / workflow_dispatch               ▼
        └── release ── test → docs-pipeline → npm publish → CHANGELOG → GitHub Release
```

| 阶段 | 触发 | 执行内容 | 失败即阻断 |
|---|---|---|---|
| `test` | push / PR / 手动 | `npm ci` + `npm test`，Node 22.x 与 24.x 双矩阵 | 是 |
| `docs-pipeline` | push / PR / 手动 | `npm run pipeline`，跑通 Wiki → ADR → 审计 → LikeC4 校验/构建 | 是 |
| `package` | 前两项通过 | `npm pack`，校验 tarball 必含 `lib/index.js`、`lib/client.js`、`cordis.patch.yml`、`README.md`，且不含 `test/` | 是 |
| `release` | tag `v*` 或手动 | 重跑测试与文档管线 → `npm publish` → 从 `CHANGELOG.md` 提取 Release Notes → 创建 GitHub Release 并上传 tarball | 是 |

工作流文件：

- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml)
- [`.github/workflows/release.yml`](../.github/workflows/release.yml)

---

## 2. 本地复现

```bash
# 一次性安装（使用 lockfile，保证与 CI 一致）
npm ci

# 单测
npm test

# 文档集成管线（会在系统临时目录创建 fixture，不污染仓库）
npm run pipeline

# 打包内容预览
npm run pack:check
```

`npm run ci` 等价于 `npm test && npm run pipeline`，提交前跑这一条即可。

### 文档管线的 7 个阶段

1. **路径识别**：`resolveDocsPaths` 自动发现 `docs/` 与 `docs/architecture/`；
2. **Wiki 侧边栏生成**：`generateSidebar` 按目录树生成 `_sidebar.md`；
3. **ADR 脚手架**：`createAdr` 自动递增编号并写入 ADR 目录；
4. **侧边栏再同步**：确认新 ADR 被重新纳入导航；
5. **文档健康审计**：`auditDocs` 检查死链、断图与孤立文档，要求 100 分；
6. **LikeC4 模型校验**：`validateC4` 走真实子进程调用协议；
7. **LikeC4 静态构建**：`buildC4Site` 产出 `index.html`。

> 第 6/7 步在 CI 中使用的是仓库内的**确定性 LikeC4 CLI 替身**，用于验证插件的
> 命令拼装、工作目录、退出码解析与产物回执；真实项目仍使用项目本地安装的
> `likec4` 可执行文件。这样 CI 不需要下载 LikeC4 的完整浏览器工具链，也不会
> 因上游版本波动而假红。

---

## 3. 测试 fixture

所有单测都通过 [`test-fixtures/docs-project.mjs`](../test-fixtures/docs-project.mjs)
在系统临时目录创建项目，不再依赖 `E:/Project/FordProject` 等本机路径：

```text
<tmp>/docs/
├── index.html
├── README.md
├── _sidebar.md
├── adr/ADR-001..003
├── architecture/
│   ├── README.md + 01/02 章节
│   ├── dist/index.html
│   └── c4/{00-specs.c4, model/, views/}
├── domain/README.md
└── quality/README.md
```

fixture 同时提供 `installFakeLikeC4()`，在 `node_modules/.bin` 下生成跨平台的
`likec4` / `likec4.cmd` 替身，覆盖 `--version`、`validate`、`build` 三种调用。

---

## 4. 发布约定

1. 修改 `package.json` 的 `version`；
2. 在 `CHANGELOG.md` 顶部新增 `## v<version> — <日期>` 条目（中英双语，`---` 分隔）；
3. 提交并打 tag：`git tag v<version> && git push origin v<version>`；
4. `Release` 工作流自动测试、发布、提取 Release Notes 并上传 tarball。

### 仓库需要配置

| 配置 | 位置 | 用途 |
|---|---|---|
| `NPM_TOKEN` | Settings → Secrets and variables → Actions | `npm publish` 认证；需 npm Automation token |
| 分支保护 | Settings → Branches → `main` | 要求 `test`、`docs-pipeline`、`package` 三项检查通过 |

> 当前目录尚未初始化 Git 仓库；把本目录推到 GitHub 后，上述工作流即自动生效。
> 若仓库默认分支不是 `main`，请同步修改两个 workflow 的 `branches` 配置。

---

## 5. 设计取舍

- **不引入 lint/format 工具**：当前代码量小，`node --test` 已覆盖全部模块导入；
  语法错误会在测试加载阶段直接失败。后续规模变大再引入 ESLint/Prettier，避免
  现在为空配置付维护成本。
- **不把 LikeC4 作为 devDependency**：它自带 Playwright/Vite 等重依赖，而插件
  的职责是调度**项目本地**的 LikeC4。用 CLI 替身验证边界，真实渲染交给使用方。
- **打包校验放在 CI 而非 `prepublishOnly`**：让 PR 阶段就能发现漏包/多包，
  而不是等到发布时才失败。