diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 92e0a05..6894d9b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -18,6 +18,8 @@ What user problem does this solve? Link the issue or showcase evidence when one List exact commands and results. Do not write only “tests pass.” +For CI-oriented validation and receipt handling, see the [CI and pull request integration guide](https://github.com/tt-a1i/archify/blob/main/docs/ci-integration.md). + ## Visual evidence For visible changes, attach before/after final-artifact screenshots and state whether visual review passed, failed, or was skipped. Write “Not applicable” for non-visual changes. diff --git a/docs/ci-integration.md b/docs/ci-integration.md new file mode 100644 index 0000000..b6a1557 --- /dev/null +++ b/docs/ci-integration.md @@ -0,0 +1,104 @@ +# CI and Pull Request Integration + +Archify exposes two useful automation boundaries: + +- `validate` checks a typed JSON source and a temporary rendered artifact without replacing a user file. +- `deliver` freezes the source, performs the same final checks, and atomically commits a verified HTML artifact with hashes. + +Both commands return a non-zero exit code on failure. Add `--json` when a CI job or pull-request bot needs structured evidence. + +## Run the repository test suite + +The renderer package is under `archify/`. The repository's baseline CI setup is: + +```bash +cd archify +npm ci +npm test +``` + +`npm test` checks generated validator freshness, release identity, golden files, and the repository-level test suite. Run it for renderer, schema, package, or generated-artifact changes. + +## Validate a diagram in GitHub Actions + +The following job stores the complete receipt even when validation fails. The command's exit status still fails the job, so a green workflow cannot hide an invalid source: + +```yaml +name: Validate Archify diagram + +on: + pull_request: + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Install renderer dependencies + run: npm ci + working-directory: archify + - name: Validate source + run: | + node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \ + --quality showcase --json > validation.json + working-directory: archify + - name: Upload validation receipt + if: always() + uses: actions/upload-artifact@v4 + with: + name: archify-validation-receipt + path: archify/validation.json +``` + +Use the diagram type that matches the input file. For a repository-evidence Architecture source, add `--repo-root` and ensure the checkout contains the pinned commit before validation. + +## Make a trusted artifact in CI + +Use `deliver` when CI must produce the exact HTML that a release, documentation site, or downstream job will consume: + +```bash +node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \ + workflow.html --quality showcase --json > delivery.json +``` + +The success receipt records the source and artifact SHA-256 values, byte counts, artifact checks, composition status, and optional repository-evidence details. Upload both `workflow.html` and `delivery.json` as artifacts when reviewers need reproducible evidence. + +Do not treat `deliver` as a visual-review claim. It proves deterministic rendering and artifact checks. A human or capable image reader must inspect the final artifact before reporting `visual_review: passed`. + +## Compare Architecture snapshots + +Architecture Delta can be used as a read-only pull-request artifact: + +```bash +node bin/archify.mjs compare architecture base.json head.json \ + architecture-delta.html --quality showcase --json +``` + +The command commits the HTML and a sidecar `architecture-delta.receipt.json` together. Keep both files from the same run; the receipt binds the compared source hashes and the generated artifact. + +## Consume receipts safely + +Treat the receipt as data, not as a success message: + +1. Check the process exit code. +2. Parse JSON only when the command was run with `--json`. +3. Require `ok: true` before publishing an artifact. +4. On failure, preserve `stage`, `diagnostics[]`, and `checker` details in the CI log or uploaded artifact. +5. Never replace a previous trusted output after a failed `deliver` run. + +For a successful `validate`, the important fields are `checks` and `composition`. For a successful `deliver`, also record `specification.sha256`, `artifact.sha256`, and the `validation` object. A `visual-check` receipt is additional browser evidence, not a replacement for deterministic validation. + +## Package freshness + +Documentation outside the packaged `archify/` tree, including root README files, `docs/`, `CONTRIBUTING.md`, and GitHub templates, does not require rebuilding `archify.zip`. Documentation inside `archify/`, including references, examples, and the published `SKILL.md`, is packaged and does require a rebuild. Run the script from the repository root: + +```bash +scripts/build-zip.sh /tmp/archify-fresh.zip +``` + +The CI `zip-freshness` job is the final authority. Do not commit an archive that differs from the current package contents. + +See [Contributing](../CONTRIBUTING.md) for the full pull-request checklist and [the delivery contract](../archify/references/delivery-contract.md) for atomic delivery and visual-review boundaries. diff --git a/docs/ci-integration.zh-CN.md b/docs/ci-integration.zh-CN.md new file mode 100644 index 0000000..5f772b1 --- /dev/null +++ b/docs/ci-integration.zh-CN.md @@ -0,0 +1,104 @@ +# CI 与 Pull Request 集成 + +Archify 暴露了两个适合自动化的边界： + +- `validate` 校验 Typed JSON 源文件和临时渲染成品，不会替换用户文件。 +- `deliver` 冻结源文件，执行同一套最终检查，并以原子方式提交带哈希的可信 HTML 成品。 + +两个命令失败时都会返回非零退出码。CI 任务或 Pull Request 机器人需要结构化证据时，请加上 `--json`。 + +## 运行仓库测试 + +Renderer 包位于 `archify/`。仓库基线 CI 流程如下： + +```bash +cd archify +npm ci +npm test +``` + +`npm test` 会检查生成 Validator（校验器）是否新鲜、Release Identity（发布身份）、Golden File（基准文件）以及仓库级测试。修改 Renderer、Schema、Package 或生成成品时都应运行它。 + +## 在 GitHub Actions 中校验图表 + +下面的 Job 即使校验失败也会保存完整回执。命令退出码仍会让 Job 失败，因此绿色工作流不会掩盖无效源文件： + +```yaml +name: Validate Archify diagram + +on: + pull_request: + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Install renderer dependencies + run: npm ci + working-directory: archify + - name: Validate source + run: | + node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json \ + --quality showcase --json > validation.json + working-directory: archify + - name: Upload validation receipt + if: always() + uses: actions/upload-artifact@v4 + with: + name: archify-validation-receipt + path: archify/validation.json +``` + +请把图表类型改成与输入文件匹配的值。如果是带仓库证据的 Architecture 源文件，还要增加 `--repo-root`，并确保检出目录包含固定版本的 commit。 + +## 在 CI 中生成可信成品 + +当 CI 要生成 Release、文档网站或下游任务真正消费的 HTML 时，使用 `deliver`： + +```bash +node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json \ + workflow.html --quality showcase --json > delivery.json +``` + +成功回执会记录源文件和成品的 SHA-256、字节数、成品检查、构图状态，以及可选的仓库证据详情。当审阅者需要可复现证据时，请把 `workflow.html` 和 `delivery.json` 一起作为 CI 产物上传。 + +不要把 `deliver` 当成视觉复核结论。它证明的是确定性渲染和成品检查；只有人工或具备能力的图像读取器检查最终成品后，才能报告 `visual_review: passed`。 + +## 比较 Architecture 快照 + +Architecture Delta 可以作为只读的 Pull Request 成品： + +```bash +node bin/archify.mjs compare architecture base.json head.json \ + architecture-delta.html --quality showcase --json +``` + +该命令会同时提交 HTML 和旁边的 `architecture-delta.receipt.json`。两者必须来自同一次运行；回执会绑定被比较源文件的哈希和生成成品。 + +## 安全消费回执 + +把回执当作数据，而不是成功提示： + +1. 先检查进程退出码。 +2. 只有使用 `--json` 时才解析 JSON。 +3. 发布成品前必须确认 `ok: true`。 +4. 失败时，把 `stage`、`diagnostics[]` 和 `checker` 详情保留在 CI 日志或上传的产物中。 +5. `deliver` 失败后，绝不要替换上一份可信输出。 + +成功的 `validate` 重点关注 `checks` 和 `composition`。成功的 `deliver` 还应记录 `specification.sha256`、`artifact.sha256` 和 `validation` 对象。`visual-check` 回执是额外的浏览器证据，不能替代确定性校验。 + +## Package 新鲜度 + +仓库根目录下的 README、`docs/`、`CONTRIBUTING.md` 和 GitHub 模板等不在已打包 `archify/` 目录中的文档，不需要重建 `archify.zip`。`archify/` 目录内的文档，包括 references、examples 和发布版 `SKILL.md`，属于 Package 内容，修改后必须重建。请从仓库根目录运行脚本： + +```bash +scripts/build-zip.sh /tmp/archify-fresh.zip +``` + +CI 的 `zip-freshness` Job 是最终依据。不要提交与当前 Package 内容不一致的压缩包。 + +完整 Pull Request 检查项请阅读[贡献指南](../CONTRIBUTING.md)；原子交付和视觉复核边界请阅读[交付契约](../archify/references/delivery-contract.md)。