test(docs-drift): 磁贴散文规则语言无关化,zh 页引用同样对账 (#725)

[yinlianghui]

Fixes #725

纯守卫单:test/docs-drift.test.ts 的 TILE_REFERENCE 语言无关化,让 zh 页正文里的磁贴引用与英文页一样被解析并对账到真实 widget。仅改一个测试文件 + 一个 changeset,src/** 与 content/docs/** 零改动。

一、stale-premise 复核:前提成立,规模数字按实测修正

在 fresh origin/main(6014b2cf,平台 17.0.0-rc.3)上逐条复核:

• test/docs-drift.test.ts:386 的正则原文与 issue 引用一字不差(名字之后必须紧跟英文 tiles? 并以词边界收尾,分隔符是「一个或多个空白」)。
• :351-355 的 Locale note 仍原样记载着这个不对称(「keys on the English word "tile", so it only ever fires on the English page」),本 PR 已改写。
• zh 页现有磁贴散文引用全部真实:实测 Quiet 90+ Days(两页各 :154)与 SLA Compliance(各 :155),对着 stack 里 54 个 widget title 逐一比对,都命中。今天没有活的缺陷,休眠覆盖缺口的定性成立。

⚠️ 一处需要向 PM 说明的收窄:issue 正文列的 7 个名(Win / Loss by Rep、Why We Lose、Quiet 90+ Days、SLA Violations、SLA Compliance、Interactions on Deals、Open Deals)是 #685 人工核对过的全部加粗磁贴名,不是这条规则的引用面。这条规则只读「加粗名 + 紧跟的磁贴名词」这个构造,7 个里只有 2 个是这种写法;另外 5 个在英文页也同样不被该规则读到(它们后面没有 tile 这个词,只是并列的加粗名)。所以「zh 页 7 个引用无人检查」应读作「zh 页的散文引用一条都没被读到,而今天恰好只有 2 条」。规则只在英文页开火这个核心事实成立。

二、修法取舍:选了映射表,并写明代价

选 TILE_WORDS 映射表而不是在正则里内联 (?:tiles?|磁贴|磁貼),理由是这份词表在本文件里被用了三处而不是一处:

1. 构造 TILE_REFERENCE;
2. vacuity guard 的报错文案(原文硬写着 **Name** tile,现在从词表生成);
3. 新增的逐词自检断言(见第三节)。

内联分支的话,后两处各要再抄一份词表,词表与正则漂移就是下一个休眠缺口 —— 这正是本单要消除的形状。

代价如实写明:正则从字面量变成 new RegExp(String.raw ...),失去字面量在作者期的语法校验;表项因此被约束为「纯词、不含正则标点」,这条约束已写进表上方的注释,因为它靠肉眼维持。

两个正则细节按实测定稿(裁定 1 提醒的「中文无词边界」确有其事):

• 分隔符从「一个或多个空白」放宽为「零个或多个空白」。 实测两页现有的 2 条引用都带一个 ASCII 空格,但中文排版并不要求这个空格。若保留「一个或多个」,**Quiet 90+ Days**磁贴(无空格,下一个译者很可能就这么写)照样不被检查 —— 同一个洞换个拼法。
• 尾部从词边界断言改为「ASCII 词字符的负向前瞻」。 JS 的词边界对两侧同时定义:「磁贴」后面跟中文句号时,两侧都是非词字符,断言不成立。照搬原尾部的话,新加的两个中文分支会是死的 —— 拼写被拒的分支让测试保持绿而规则已死,是这类守卫最常见的失效形状。负向前瞻对英文接受的字符串与原词边界完全一致(前一个字符必为字母时两者等价)。

没有做的一件事:没有把 DOC_PAGES 改成「文件 → 词」的按页映射。那会连带改掉三条规则共用的迭代面,而它唯一多买到的能力是「英文页写了磁贴算拼错」—— 不是任何读者会踩的缺陷类;文件头 Locale note 的既有口径也是「提取器语言无关」。

三、两阶段红→绿验证(注入只在工作树,未进提交历史)

红:在两个 zh 页各注入一条假引用,两种拼法各取其一

• zh-Hans :156(带空格):- ✅ 每周五用 **Slipping Deals** 磁贴来规划下周的交易评审通话。
Slipping Deals 正是 content/docs/analytics/dashboards.mdx describes tiles that no dashboard ships (near-total drift, plus a fabricated usage stat) #610 里以散文形态出现过的那个假磁贴,原句就是「每周五使用 … 磁贴来规划下周的交易评审通话」。
• zh-Hant :156(不带空格,专为验证放宽后的分隔符):- ✅ 每週五用 **Cases Approaching SLA**磁貼來規劃下週的交易評審通話。

 FAIL  test/docs-drift.test.ts > the dashboards docs page lists tiles that exist > every "**Name** tile" / "**Name** 磁贴" reference names a real tile
AssertionError: tile references that do not resolve:
  content/docs/analytics/dashboards.zh-Hans.mdx: prose points at a "Slipping Deals" tile, which no dashboard ships
  content/docs/analytics/dashboards.zh-Hant.mdx: prose points at a "Cases Approaching SLA" tile, which no dashboard ships
Name a tile that exists, or drop the advice — a workflow built on a tile nobody can open is worse than no advice.

 Test Files  1 failed (1)
      Tests  1 failed | 33 passed (34)

两条都点名了假名字,带空格与不带空格各中一条。

绿:移除注入(git restore 两个 mdx)后跑同一条命令

 Test Files  1 passed (1)
      Tests  34 passed (34)

git status 干净,提交里没有这两行。

反向验证:方向先预测再跑,预测与实测一致

预测:把正则换回改前那一行、注入仍在时,引用规则应当绿(它看不见 zh 页散文 —— 这正是休眠缺口本身),而新增的逐词自检应当红。实测:

 FAIL  test/docs-drift.test.ts > ... > the tile reference extraction reads every locale the page ships (#725)
AssertionError: TILE_REFERENCE no longer reads:
  每周都处理一次 **Open Deals**tiles。
  每周都处理一次 **Open Deals**tile。
  每周都处理一次 **Open Deals** 磁贴。
  每周都处理一次 **Open Deals**磁贴。
  每周都处理一次 **Open Deals** 磁貼。
  每周都处理一次 **Open Deals**磁貼。

 Test Files  1 failed (1)
      Tests  1 failed | 33 passed (34)

那两条 Slipping Deals / Cases Approaching SLA 假引用在这一轮一条都没被报出来 —— 旧正则确实读不到 zh 页散文。休眠缺口因此以可执行形式被钉住,而不是靠注释声明。

这一轮还顺手改进了断言形状:自检最初是逐条 expect,首个探针失败即中断,只报了一条(不带空格的英文);改为收集后一次性断言,才有上面这份完整清单 —— 也与本文件既有的 bad 数组风格一致。

四、命中计数对比与 vacuity guard

页	改前	改后
content/docs/analytics/dashboards.mdx	2	2
content/docs/analytics/dashboards.zh-Hans.mdx	0	2
content/docs/analytics/dashboards.zh-Hant.mdx	0	2
合计(vacuity guard 读的并集)	2	6

vacuity guard 的判据一个字没动(仍是并集大于 0,只把报错文案里硬写的 **Name** tile 换成从词表生成),因此不会变脆:某个 locale 页将来合法地不在散文里点磁贴名,它依然绿。

但并集也正是它盖不住的地方:把中文词从表里删掉,并集靠英文那 2 条仍然大于 0,缺口会静默重开。新增的逐词自检就是补这一刀 —— 它不读任何文档内容,只对四个词各造带空格/不带空格两个探针,所以既不脆也不空。上一节反向验证里报出来的 6 条,就是它的输出。

五、英文页零变化

改前改后英文页命中集逐一比对:都是 Quiet 90+ Days(:154)与 SLA Compliance(:155),名字、条数、来源行全同。尾部负向前瞻与原词边界对英文接受的字符串等价;分隔符放宽在英文页没有新增命中(全页不存在加粗名紧贴 tile 的写法,已实测)。

六、验证

六道门全部在 flock -w 7200 /tmp/os-heavy-verify.lock 内串行执行,NODE_OPTIONS=--max-old-space-size=4096:

门	退出码	关键行
pnpm validate	0	✓ Validation passed;5 条 author-time 警告为 main 既有(approval 审批人可能解析为空 ×4、crm_campaign_member 字段组)
pnpm typecheck	0	tsc --noEmit,无输出
pnpm lint	0	13 warning(s), 14 suggestion(s),与 main 同
pnpm hygiene	0	✓ source hygiene clean;扫描面 245 个代码文件 + 420 个文本文件(含 content 与 .changeset)
pnpm build	0	Artifact: dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66);Tests 1598 passed、1 skipped(1599),main 为 1597 passed,本 PR 净 +1

单跑本文件:Test Files 1 passed (1) / Tests 34 passed (34)。

控制字节:pnpm hygiene 之外另做自扫(grep -naP,覆盖除 tab、LF、CR 之外的全部 C0 控制字符,即只盯 NUL 的扫描会漏掉的那一类),改动的两个文件零命中。

⚠️ 本 PR 正文按 #4890 的教训只描述区间、不粘贴区间;正则里的反斜杠转义序列也一律用中文描述而非原样粘贴。转义被编辑/接口层实体化成真控制字节,恰恰最容易发生在「正在写关于字符的代码」的那一刻,而本单从头到尾都在写正则。

未起 dev server。

七、范围与边界

• 只动 test/docs-drift.test.ts 与 .changeset/tile-prose-guard-every-locale.md(patch 级)。src/**、content/docs/** 零改动,content/docs/releases/ 未触碰,@objectstack/* 版本未动(17.0.0-rc.3)。
• 规则的消费半径已核:TILE_REFERENCE 只在本文件内定义与使用,全仓 grep 无第二处消费者;DOC_PAGES 三份之外没有别的页进入这条规则,不存在别的包的 fixture 需要同步扫。
• 越界发现:无。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 9:09am