skill-family-doc-render 0.4.1 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 变更日志
 
+## 0.4.5 - 2026-09-10
+
+### 变更
+
+- 与 `skill-family-docs` 和公开站点的 0.4.5 联合发布对齐版本。渲染器的公开 API、命令行参数与输入合同均没有变化；相同内容输入仍生成相同的站点字节。
+
+## 0.4.4 - 2026-09-10
+
+### 修复
+
+- 修复 `--check --assert-git` 组合调用提前返回的问题。组合命令现在依次检查渲染一致性与 Git 索引跟踪状态，全程不改目标目录、基线或索引。
+- Git 查询失败继续返回工具错误 2；渲染漂移或输出未跟踪返回状态错误 1。单独使用 `--assert-git` 成功后仍按既有合同执行渲染。
+- 帮助和错误文本把 Git 断言准确表述为“已被索引跟踪”，不再误写成“已提交”或“已发布”。
+
+### 变更
+
+- 将 Foundation 运行依赖精确升级到 0.19.3，继续复用原有路径收容、摘要、原子写和固定文件集发布接口。
+
 ## 0.4.1 - 2026-09-07
 
 ### 变更

package/README.md

@@ -16,51 +16,54 @@ publication APIs. A failure before commit removes staging and leaves the existin
 untouched. After commit, or when publication is indeterminate, staging or displaced data may
 remain for diagnosis; the renderer does not guess or roll back.
 
-> **Version boundary:** this source tree is version `0.4.1`. Verify that exact version in the
-> official npm registry before treating it as installable. Version 0.4.1 preserves the
+> **Version boundary:** this source tree is version `0.4.5`. Verify that exact version in the
+> official npm registry before treating it as installable. Version 0.4.5 preserves the
 > `markdown-v1`, `editorial`, and `--check-project` behavior introduced in 0.4.0 and aligns the
-> renderer, documentation plugin, and public site at 0.4.1 for the joint release.
+> renderer, documentation plugin, and public site at 0.4.5 for the joint release.
 
 ## Install
 
 After confirming availability, install this release with an exact version:
 
 ```sh
-npm install --save-exact skill-family-doc-render@0.4.1
+npm install --save-exact skill-family-doc-render@0.4.5
 ```
 
 Requires Node.js `>=22.22.2 <23` (aligned with the skill-family foundation packages).
 
-Version 0.4.1 has exact runtime dependencies on `marked@18.0.11`,
-`skill-family-contracts@0.18.0`, and `skill-family-harness-node@0.18.0`. `marked` supplies the
+Version 0.4.5 has exact runtime dependencies on `marked@18.0.11`,
+`skill-family-contracts@0.19.3`, and `skill-family-harness-node@0.19.3`. `marked` supplies the
 Markdown lexer; the renderer applies its own restricted-format validation before passing semantic
 content to the template. The workspace profile check separately uses
-`skill-family-engineering-kit@0.18.0`.
+`skill-family-engineering-kit@0.19.3`.
 The 0.2.0 baseline format and exit-code changes are breaking changes; existing 0.1.x users
 must re-render their baseline before using `--check`. See the changelog for the full migration
 notes.
 
 ## CLI
 
-Use the exact 0.4.1 CLI for rendering, checks, coverage maintenance, and the Git index assertion:
+Use the exact 0.4.5 CLI for rendering, checks, coverage maintenance, and the Git index assertion:
 
 ```sh
 # render all repos with a site field (writes to disk)
-npx skill-family-doc-render@0.4.1
+npx skill-family-doc-render@0.4.5
 
-# drift check only: compare in-memory render against committed site-baseline.json, write nothing
-npx skill-family-doc-render@0.4.1 --check
+# drift check only: compare in-memory render against the on-disk site-baseline.json, write nothing
+npx skill-family-doc-render@0.4.5 --check
 
 # render / check a single repo by name
-npx skill-family-doc-render@0.4.1 --repo <name>
+npx skill-family-doc-render@0.4.5 --repo <name>
 
-# additionally assert every rendered file is tracked in the git index
-npx skill-family-doc-render@0.4.1 --assert-git
+# assert every rendered file is tracked in the Git index, then render
+npx skill-family-doc-render@0.4.5 --assert-git
+
+# run both the drift and Git index tracking checks without writing
+npx skill-family-doc-render@0.4.5 --check --assert-git
 
 # inspect or refresh the reviewed product-input snapshot
-npx skill-family-doc-render@0.4.1 --status --repo <name>
-npx skill-family-doc-render@0.4.1 --refresh-coverage --repo <name>
-npx skill-family-doc-render@0.4.1 --check-project --repo <name>
+npx skill-family-doc-render@0.4.5 --status --repo <name>
+npx skill-family-doc-render@0.4.5 --refresh-coverage --repo <name>
+npx skill-family-doc-render@0.4.5 --check-project --repo <name>
 ```
 
 The current directory must be the workspace that owns `public-release.json`. From this package's
@@ -73,14 +76,20 @@ then internal links and resources. It writes nothing. A failure identifies the r
 `public-release.json`, the reason, and a copyable `skill-family-docs-render-site` recovery prompt.
 
 Exit codes: `0` success; `1` drift/status class — `--check` drift, leak-scan hit, `--assert-git`
-missing files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
+untracked rendered files, missing/corrupt render baseline, or missing/stale coverage snapshot; `2`
 configuration/tool class — missing/invalid `public-release.json` or `pages.json`, JSON parse
 failures, unreplaced `@TOKEN@` placeholders, invalid `--repo` usage, invalid coverage inputs, or
 Git failure (the message includes the JSON field path). `--check-project` uses the same classes:
 public-safety, coverage, render, link, or resource findings return `1`; invalid input,
 configuration, or tool errors return `2`.
-When several repos are
-rendered in one run, each repo is isolated: a failure in one does not stop the others, and the
+Combining `--check` with `--assert-git` first verifies the render against the on-disk baseline,
+then checks that every rendered page, asset, and `.nojekyll` entry is tracked in the Git index.
+The combined command writes neither the target tree, `site-baseline.json`, nor the Git index.
+`site-baseline.json` itself, source Markdown, configuration, and coverage locks are outside the
+Git assertion set. A staged file satisfies the assertion; the command does not claim that the
+file is committed or published. Without `--check`, a successful `--assert-git` preflight is
+followed by the normal rendering write. When several repos are rendered in one run, each repo is
+isolated: a failure in one does not stop the others, and the
 run ends with a summary of successes/failures plus a non-zero exit (2 if any failure was
 configuration-class, otherwise 1).
 
@@ -274,10 +283,10 @@ Foundation packages below, it uses exact `marked@18.0.11` for Markdown tokenizat
 Apache-2.0
 
 <!-- release-skill:capability:safe-first-command -->
-> **Start here:** run `npx skill-family-doc-render@0.4.1 --check-project --repo <name>` after
+> **Start here:** run `npx skill-family-doc-render@0.4.5 --check-project --repo <name>` after
 > confirming that exact release in the official registry. From a local checkout, use
 > `node bin/skill-family-doc-render.mjs --check-project --repo <name>`. The check is read-only:
-> it renders in memory, compares against the committed `site-baseline.json`, writes
+> it renders in memory, compares against the on-disk `site-baseline.json`, writes
 > nothing and touches no network or credentials. The CLI performs no Git writes; only an
 > explicit `--assert-git` performs a read-only query of the Git index.
 
@@ -298,6 +307,6 @@ Apache-2.0
 Display help and run a read-only project check:
 
 ```sh
-npx skill-family-doc-render@0.4.1 --help
-npx skill-family-doc-render@0.4.1 --check-project --repo <name>
+npx skill-family-doc-render@0.4.5 --help
+npx skill-family-doc-render@0.4.5 --check-project --repo <name>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-family-doc-render",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "Config-driven GitHub Pages knowledge-site renderer for skill-family projects (multi-repo capable).",
   "author": "广州市风荷科技有限公司",
   "license": "Apache-2.0",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "marked": "18.0.11",
-    "skill-family-contracts": "0.18.0",
-    "skill-family-harness-node": "0.18.0"
+    "skill-family-contracts": "0.19.3",
+    "skill-family-harness-node": "0.19.3"
   }
 }

package/scripts/render-public-site.mjs

@@ -20,7 +20,7 @@
 //
 // 错误分类（退出码语义）：
 //   exit 1 — 漂移类：--check 检出漂移、覆盖快照缺失或落后、泄漏扫描命中、
-//            --assert-git 缺失、渲染基线缺失 / 基线 JSON 损坏；
+//            --assert-git 检出未跟踪文件、渲染基线缺失 / 基线 JSON 损坏；
 //   exit 2 — 配置或工具类：配置 / JSON / 覆盖输入非法、Git 调用失败、
 //            @TOKEN@ 占位符残留、markdown-v1/SVG 输入非法、--repo 参数无效；
 //   其余意外异常（HarnessError 等）原样抛出，CLI 归为 exit 1。
@@ -514,6 +514,30 @@ async function markdownOutputs(root, repo, dirRel, pagesDoc, tokens) {
   return outputs;
 }
 
+function assertGitTracked(root, repo, targetRel, files) {
+  const expected = files.map((f) => `${targetRel}/${f}`);
+  let missing = 0;
+  for (const f of expected) {
+    try {
+      execFileSync('git', ['ls-files', '--error-unmatch', f], { cwd: root, stdio: 'pipe' });
+    } catch (cause) {
+      if (cause?.status === 1) {
+        console.error(`[assert-git] ${repo.name}: 未被 Git 索引跟踪（请先 git add）: ${f}`);
+        missing++;
+        continue;
+      }
+      const detail = String(cause?.stderr || cause?.message || '').trim();
+      throw configError(
+        repo.name,
+        `Git 索引查询失败: git ls-files --error-unmatch ${f}${detail ? `: ${detail}` : ''}`,
+        cause,
+      );
+    }
+  }
+  if (missing) throw new RenderError(`[assert-git] ${repo.name}: ${missing} 个渲染文件未被 Git 索引跟踪`, 1);
+  console.log(`[assert-git] ${repo.name}: 全部渲染文件均已被 Git 索引跟踪`);
+}
+
 // --- 渲染单仓 ---
 async function renderRepo(root, repo, release, leakLiterals, { check, assertGit, inputOnly = false }) {
   const site = repo.site;
@@ -641,7 +665,7 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit,
     const baselineRel = join(targetRel, 'site-baseline.json');
     if (!existsSync(resolve(root, baselineRel))) {
       throw new RenderError(
-        `[render-public-site --check] ${repo.name}: 未找到已提交基线 site-baseline.json（请先渲染并提交）`,
+        `[render-public-site --check] ${repo.name}: 未找到磁盘基线 site-baseline.json（请先运行渲染）`,
         1,
       );
     }
@@ -685,24 +709,12 @@ async function renderRepo(root, repo, release, leakLiterals, { check, assertGit,
       );
     }
     console.log(`[render-public-site --check] ${repo.name}: 一致，无漂移`);
+    if (assertGit) assertGitTracked(root, repo, targetRel, files);
     return;
   }
 
   // assert-git 必须在任何 target 变更前完成，避免门禁失败留下部分替换结果。
-  if (assertGit) {
-    const expected = files.map((f) => `${targetRel}/${f}`);
-    let missing = 0;
-    for (const f of expected) {
-      try {
-        execFileSync('git', ['ls-files', '--error-unmatch', f], { cwd: root, stdio: 'pipe' });
-      } catch {
-        console.error(`[assert-git] ${repo.name}: 未跟踪（需 git add 并提交）: ${f}`);
-        missing++;
-      }
-    }
-    if (missing) throw new RenderError(`[assert-git] ${repo.name}: ${missing} 个文件未进 Git 快照，站点无法进入发布`, 1);
-    console.log(`[assert-git] ${repo.name}: 全部站点文件已在 Git 快照中`);
-  }
+  if (assertGit) assertGitTracked(root, repo, targetRel, files);
 
   // --- 写盘事务化：在目标目录的 canonical parent 内创建 sibling staging，
   // 写入和发布均使用 Foundation 公共目录发布 API。 ---
@@ -786,9 +798,11 @@ const USAGE_TEXT = `skill-family-doc-render — config-driven GitHub Pages knowl
 
 Usage:
   skill-family-doc-render                render every repo with a site field (writes)
-  skill-family-doc-render --check        read-only drift check against site-baseline.json
+  skill-family-doc-render --check        read-only drift check against the on-disk site-baseline.json
   skill-family-doc-render --repo <name>  render / check a single repo by name
-  skill-family-doc-render --assert-git   also assert rendered files are git-tracked
+  skill-family-doc-render --assert-git   assert rendered files are tracked in the Git index, then render
+  skill-family-doc-render --check --assert-git
+                                        read-only drift and Git index tracking checks
   skill-family-doc-render --status --repo <name>
                                         read-only coverage status and Git changes
   skill-family-doc-render --refresh-coverage --repo <name>