Skip to content

Commit 421bab7

Browse files
committed
fix(docs): 测试数处处一致——替换规则收拢到共用模块
双 README 里测试数以五种形状重复出现(1 个 shields.io 徽章 + 4 种开发命令注释, root 双语再多一条)。v0.8.11 发版后徽章跳到 1437,四条注释却留在 1431。 根因不是「忘了改」,而是两条写入路径各存了一份替换规则、形状集合还不一样: - scripts/release-prep.mjs(Release Prep 工作流,自动,每次发版都跑) - dsh-mneme/scripts/sync-test-badge.mjs(npm run badge:sync,手动) 前者只 replace 徽章 URL,注释压根不在它的替换范围内——自动路径反倒成了漂移来源, 下次发版还会再错一遍。A/B 实测:拿「徽章 1437 / 注释 1431」的漂移态跑修复前的 release-prep,它静默放过、README 仍不一致;修复后同一场景两处都刷成 1437。 改动: - 新增 dsh-mneme/scripts/test-count-sync.mjs,把形状集合(徽章 + 4 种注释)连同 applyTestCount / readTestCounts 收在一处,两条路径共用; - release-prep.mjs 与 sync-test-badge.mjs 改为调用它(后者逻辑不变,只是不再自带 一份正则); - 修正双 README 里四行落后于徽章的注释(1431 → 1437); - 新增 test/test-count-sync.test.js 四条:直接断言双 README 的徽章与注释同数 (跑在真实文件上,就是这次漂移的回归锁)、覆盖全部五种形状、幂等、以及不碰 历史版本表里的「N 测试全绿」。 变异检验:把 root README 注释改回 1431 → 一致性用例变红,并精确报出 badge=1437 / comment-cjk=1431;把徽章正则改坏 → 一致性用例与形状用例同时变红。 两条都如实变红,用例不是空转。 测试 1441 项:1440 通过 / 0 失败 / 1 跳过(原 1437 + 新增 4)。
1 parent 8519f57 commit 421bab7

6 files changed

Lines changed: 124 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ dsh web
183183

184184
```bash
185185
cd dsh-mneme && npm install
186-
npm test # 1431 个测试
186+
npm test # 1437 个测试
187187
npm run stress # 三轴线压测
188188
npm run sync # src → lib 同步
189189
```
@@ -366,7 +366,7 @@ The plugin ships a zero-dependency stdio MCP server (standalone npm package **`m
366366

367367
```bash
368368
cd dsh-mneme && npm install
369-
npm test # 1431 tests
369+
npm test # 1437 tests
370370
npm run stress # three-axis stress test
371371
npm run sync # src → lib sync
372372
```

‎dsh-mneme/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -584,7 +584,7 @@ src/
584584
├── api.js # HTTP 路由(Web 面板数据通道,含 /conflicts 冲突队列)
585585
└── index.js # 插件接线
586586
lib/ # src 的同步分发产物(npm run sync;发布前由 root prepack 的 check-sync.js 校验一致性;唯一手写例外 lib/client.js——Web 面板 bundle,sync 不覆盖)
587-
test/ # 1431 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
587+
test/ # 1437 个 node:test 测试(审计与三轴线压测不变量;src↔lib 一致性由 scripts/check-sync.js 发布闸门校验)
588588
scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js / benchmark-embed.js / benchmark-rerank.js 基准 · sync-test-badge.mjs 测试徽章 · build-runtime-manifest.mjs 运行时清单
589589
```
590590
@@ -593,7 +593,7 @@ scripts/ # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
593593
```bash
594594
cd dsh-mneme
595595
npm install # 安装 peer 依赖(以 devDependencies 形式,用于本地测试)
596-
npm test # 运行 1431 个测试
596+
npm test # 运行 1437 个测试
597597
npm run stress # 三轴线压测:长会话检索 / 冲突仲裁 / 多 Agent 并发(离线 mock LLM)
598598
npm run sync # 把 src/ 同步到 lib/(发布时由 prepack 钩子自动执行)
599599
```

‎dsh-mneme/scripts/sync-test-badge.mjs‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
// 1. 跑一遍全量测试(npm test),取套件总数(`ℹ tests N` 汇总行);
77
// 2. 把双 README 的 tests 徽章(img.shields.io/badge/tests-N%20passed)与
88
// 开发命令注释(# N 个测试 / # 运行 N 个测试 / # N 个 node:test 测试 /
9-
// # N tests)刷成该数字;
9+
// # N tests)刷成该数字——形状集合收在 scripts/test-count-sync.mjs,与发版
10+
// 自动路径 scripts/release-prep.mjs 共用(两条路径各存一份曾导致 v0.8.11
11+
// 徽章与注释不同数);
1012
// 3. 有变化就写回文件(由调用方决定是否 commit/push),无变化静默退出。
1113
//
1214
// 测试失败(fail>0 或进程非零退出)时以非零退出且不改任何文件——徽章永远
@@ -16,6 +18,7 @@ import { execSync } from "node:child_process";
1618
import { readFileSync, writeFileSync } from "node:fs";
1719
import { dirname, join } from "node:path";
1820
import { fileURLToPath } from "node:url";
21+
import { applyTestCount } from "./test-count-sync.mjs";
1922

2023
const scriptDir = dirname(fileURLToPath(import.meta.url));
2124
const repoRoot = join(scriptDir, "..", "..");
@@ -46,18 +49,17 @@ if (!count) {
4649
process.exit(1);
4750
}
4851

49-
// 3) 刷双 README(徽章 + 两行开发命令注释)
52+
// 3) 刷双 README(徽章 + 四种开发命令注释形状)
53+
// 形状集合与 release-prep.mjs(发版自动路径)共用,收在 scripts/test-count-sync.mjs —
54+
// 两条路径各自维护一份规则正是 v0.8.11 注释漂移的根因。
5055
const targets = [
5156
join(repoRoot, "README.md"),
5257
join(repoRoot, "dsh-mneme", "README.md")
5358
];
5459
let changed = 0;
5560
for (const file of targets) {
56-
let text = readFileSync(file, "utf8");
57-
const next = text
58-
.replace(/tests-\d+%20passed-/g, `tests-${count}%20passed-`)
59-
.replace(/(#\s*(?:运行\s*)?)\d+( 个(?:\s*node:test)?\s*测试)/g, `$1${count}$2`)
60-
.replace(/(#\s*)\d+( tests)/g, `$1${count}$2`);
61+
const text = readFileSync(file, "utf8");
62+
const next = applyTestCount(text, count);
6163
if (next !== text) {
6264
writeFileSync(file, next);
6365
changed += 1;
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// 测试数在双 README 里以多种形状重复出现:shields.io 徽章 URL,以及四种 `# N …测试`
2+
// 注释(`# N 个测试` / `# 运行 N 个测试` / `# N 个 node:test 测试` / `# N tests`)。
3+
// 所有出现处必须永远报同一个数。
4+
//
5+
// 这些规则原先在两条写入路径里各存一份,且形状集合不同:
6+
// - scripts/release-prep.mjs(Release Prep 工作流,自动,每次发版跑)
7+
// - dsh-mneme/scripts/sync-test-badge.mjs(npm run badge:sync,手动)
8+
// release-prep 当时只 replace 徽章 URL,于是 v0.8.11 发版时徽章自动跳到 1437,
9+
// 四条注释留在 1431 —— 自动路径反而成了漂移的来源。规则收在这里共用,
10+
// 由 test/test-count-sync.test.js 锁住形状集合与「双 README 同数」这条不变量。
11+
//
12+
// 徽章正则刻意不带尾随 `-`:`tests-N%20passed` 既能命中 `…passed-3E63DD`(root)
13+
// 也能命中 `…passed-success`(包 README),将来出现无后缀写法也不会静默漏改。
14+
15+
const BADGE = /tests-\d+%20passed/g;
16+
const COMMENT_CJK = /(#\s*(?:运行\s*)?)\d+( 个(?:\s*node:test)?\s*测试)/g;
17+
const COMMENT_EN = /(#\s*)\d+( tests)/g;
18+
19+
/** 把一段文本里所有测试数出现处刷成 count(含徽章与四种注释形状)。 */
20+
export function applyTestCount(text, count) {
21+
return text
22+
.replace(BADGE, `tests-${count}%20passed`)
23+
.replace(COMMENT_CJK, `$1${count}$2`)
24+
.replace(COMMENT_EN, `$1${count}$2`);
25+
}
26+
27+
/**
28+
* 只读地抽出文本里所有测试数字面量及其形状,供「处处一致」断言使用。
29+
* 历史版本表里的「745 测试全绿」不带 `#` 前缀,刻意不在两种口径内——那是各版本
30+
* 当时的真实记录,不该被后续发版改写。
31+
*/
32+
export function readTestCounts(text) {
33+
const found = [];
34+
for (const m of text.matchAll(/tests-(\d+)%20passed/g)) {
35+
found.push({ shape: "badge", value: Number(m[1]) });
36+
}
37+
for (const m of text.matchAll(/#\s*(?:运行\s*)?(\d+)\s*个(?:\s*node:test)?\s*测试/g)) {
38+
found.push({ shape: "comment-cjk", value: Number(m[1]) });
39+
}
40+
for (const m of text.matchAll(/#\s*(\d+)\s+tests/g)) {
41+
found.push({ shape: "comment-en", value: Number(m[1]) });
42+
}
43+
return found;
44+
}
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import test from "node:test";
2+
import assert from "node:assert/strict";
3+
import { readFileSync } from "node:fs";
4+
import { dirname, join } from "node:path";
5+
import { fileURLToPath } from "node:url";
6+
import { applyTestCount, readTestCounts } from "../scripts/test-count-sync.mjs";
7+
8+
const HERE = dirname(fileURLToPath(import.meta.url));
9+
const PKG_ROOT = join(HERE, "..");
10+
const REPO_ROOT = join(PKG_ROOT, "..");
11+
const READMES = [join(REPO_ROOT, "README.md"), join(PKG_ROOT, "README.md")];
12+
13+
// 双 README 是发布门面,同一个数字在里面重复出现三到五次(一个 shields.io 徽章 +
14+
// 每条开发命令注释一处,root 是双语所以中英各一条)。它们必须永远同数——否则
15+
// 「这个项目有多少测试」取决于读者恰好看了哪一行。
16+
//
17+
// v0.8.11 实际漂移过:徽章 1437、四条注释留在 1431。本用例就是那次漂移的回归锁,
18+
// 跑在真实 README 上(不是 fixture),所以它能在发版前拦住同类漂移。
19+
test("双 README 的测试数处处一致(徽章与所有注释同数)", () => {
20+
for (const f of READMES) {
21+
const counts = readTestCounts(readFileSync(f, "utf8"));
22+
const shapes = new Set(counts.map((c) => c.shape));
23+
assert.ok(counts.length >= 2, `${f} 抽到的测试数出现处太少:${JSON.stringify(counts)}`);
24+
assert.ok(shapes.has("badge"), `${f} 没抽到徽章:${JSON.stringify(counts)}`);
25+
const values = [...new Set(counts.map((c) => c.value))];
26+
assert.equal(values.length, 1, `${f} 测试数不一致:${JSON.stringify(counts)}`);
27+
}
28+
});
29+
30+
// v0.8.11 的真实漂移样本(徽章已 1437、注释仍 1431)。锁住「徽章 + 四种注释形状」
31+
// 全覆盖:少任何一种,就会有一处静默落后——release-prep.mjs 原先只覆盖徽章 URL,
32+
// 自动发版路径因此反倒成了漂移来源。
33+
test("applyTestCount 覆盖徽章与全部四种注释形状(真实漂移样本)", () => {
34+
const drifted = [
35+
'<img src="https://img.shields.io/badge/tests-1431%20passed-3E63DD?style=flat-square" alt="tests">',
36+
"[![tests](https://img.shields.io/badge/tests-1431%20passed-success)](https://github.com/slow-stack/mneme)",
37+
"npm test # 1431 个测试",
38+
"npm test # 运行 1431 个测试",
39+
"test/ # 1431 个 node:test 测试(审计与三轴线压测不变量)",
40+
"npm test # 1431 tests"
41+
].join("\n");
42+
const fixed = applyTestCount(drifted, 1437);
43+
assert.ok(!/\b1431\b/.test(fixed), "仍有 1431 未被替换:\n" + fixed);
44+
const counts = readTestCounts(fixed);
45+
assert.equal(counts.length, 6, "六处出现都该被认出来:" + JSON.stringify(counts));
46+
assert.deepEqual([...new Set(counts.map((c) => c.value))], [1437]);
47+
});
48+
49+
test("applyTestCount 幂等:同一个数重复施加不再产生变化", () => {
50+
const once = applyTestCount("tests-9%20passed-3E63DD\n# 9 个测试\n# 9 tests", 12);
51+
assert.equal(applyTestCount(once, 12), once);
52+
});
53+
54+
// 历史版本表里的「745 测试全绿」「790 通过」是各版本当时的真实记录(sync-test-badge
55+
// 的注释也写明了刻意不改它们)。替换规则只认徽章 URL 与 `#` 前缀注释两种形状,
56+
// 这条用例锁住那个边界,免得将来放宽正则把历史改写掉。
57+
test("applyTestCount 不碰历史版本表里的「N 测试全绿」", () => {
58+
const history = "| **v0.8.0** | 745 测试全绿 |\n| **v0.7.9** | 790 通过 |\n| v0.2.7 | 263 |";
59+
assert.equal(applyTestCount(history, 1437), history);
60+
});

‎scripts/release-prep.mjs‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"use strict";
66

77
import fs from "node:fs";
8+
import { applyTestCount } from "../dsh-mneme/scripts/test-count-sync.mjs";
89

910
const version = (process.argv[2] || "").replace(/^v/, "");
1011
const testCount = process.argv[3];
@@ -31,14 +32,17 @@ for (const f of [PKG, LOCK]) {
3132
console.log(`✓ ${f} → ${version}`);
3233
}
3334

34-
// ── 2. 测试徽章同步(两个 README)──
35+
// ── 2. 测试数同步(两个 README:徽章 + 4 种 `# N …测试` 注释形状)──
36+
// 规则收在 dsh-mneme/scripts/test-count-sync.mjs,与手动路径 sync-test-badge.mjs
37+
// 共用。原先两条路径各存一份、形状集合还不同——本脚本只 replace 徽章 URL,于是
38+
// v0.8.11 发版时徽章跳到 1437 而四条注释留在 1431,自动路径反倒成了漂移来源。
3539
if (testCount && /^\d+$/.test(testCount)) {
3640
for (const f of READMES) {
3741
const t = fs.readFileSync(f, "utf8");
38-
const n = t.replace(/tests-\d+%20passed/g, `tests-${testCount}%20passed`);
42+
const n = applyTestCount(t, testCount);
3943
if (n !== t) {
4044
fs.writeFileSync(f, n);
41-
console.log(`✓ ${f} 测试徽章 → ${testCount}`);
45+
console.log(`✓ ${f} 测试数 → ${testCount}`);
4246
}
4347
}
4448
}

0 commit comments

Comments
 (0)