现象
scripts/check-doc-links.mjs 的 SCAN_ROOTS 里,包级两行是精确文件名匹配:
{path: 'packages/*/README.md',rule: 'disk'},{path: 'apps/*/README.md',rule: 'disk'},于是包目录(及其子目录)下任何不叫 README.md 的 markdown 都在扫描面外。该脚本自己的注释把「包内非 README markdown 未被扫描」记为已知边界,但边界的代价一直没被测过。
排除 CHANGELOG.md(生成物)后,当前有 15 个这样的文件:
apps/console/docs/UI_IMPROVEMENT_PROPOSAL.md
apps/console/docs/deployment.md
apps/console/docs/error-tracking.md
packages/cli/MIGRATION.md
packages/components/README_SHADCN_SYNC.md
packages/components/TESTING.md
packages/components/docs/FilterBuilder.md
packages/components/src/renderers/complex/README-KANBAN.md
packages/components/src/renderers/complex/TIMELINE.md
packages/plugin-dashboard/SKILL.md
packages/plugin-gantt/ROADMAP.md
packages/vscode-extension/DESIGN.md
packages/vscode-extension/ICON.md
packages/vscode-extension/PUBLISHING.md
packages/vscode-extension/SUMMARY.md
实测入场价(按先例的口径先量后报)
这 15 个文件里共 4 条仓内相对 markdown 链接,其中 1 条死链:
packages/components/src/renderers/complex/TIMELINE.md:349
See the [prototype app](../../examples/prototype/src/App.tsx) …
→ 解析到 packages/components/src/examples/prototype/src/App.tsx,不存在;仓根 examples/prototype/ 也不存在。
所以 markdown 链接这一面很便宜(先例 #3603/#3622 的入场价是 9~11 条,这里是 1 条)。
真正大的那一面:反引号仓内路径
死链只是一半。#3881 实际被咬的是反引号包裹的仓内路径——README_SHADCN_SYNC.md 的 ## Files 声称 shadcn-sync.js 在 packages/components/ 目录下,而它一直在仓根 scripts/shadcn-sync.js。这类路径没有任何门禁看:scripts/check-skills-paths.mjs(#3735 的产物)只覆盖 skills/**,带 baseline;包内 markdown 一概不在其内。
两面的失效形状不同,建议分开定价:
SCAN_ROOTS 加一行把包内非 README markdown 纳入(链接面,入场价实测 1 条);- 反引号仓内路径的校验是否要从
skills/** 推广到包内 markdown(面更大,需另测)。
分级
按 finding 归档,不带 pm:queue,交分诊定级。今天没有 CI 会因它变红,读者付的成本是照着错误路径去找文件。归为观察类而非具体缺陷:那条死链本身是小事,值钱的是「这一整片文件从未被解析过」这个结构事实。
出处与去重
发现于 #3881 的实施过程(PR 见该卡)。#3881 的可选修法 3 曾建议「顺带考虑把包内 README* 纳入 check-doc-links 扫描面」,该 PR 刻意未取:它是独立的门禁扩面,有自己的入场价,按 #3536 → #3572 → #3603/#3622 → #4148 这条先例链,每次扩面都是一张独立卡。#3881 落地的是文档内容 + 成员集合钉,已把该文件的反引号路径在包内测试里局部钉住(packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts),不构成全仓覆盖。
检索过开放卡:#3536 / #3572 / #3603 / #3622 / #4148 / #3735 均已关闭,无在途卡覆盖本条。
现象
scripts/check-doc-links.mjs的SCAN_ROOTS里,包级两行是精确文件名匹配:于是包目录(及其子目录)下任何不叫
README.md的 markdown 都在扫描面外。该脚本自己的注释把「包内非 README markdown 未被扫描」记为已知边界,但边界的代价一直没被测过。排除
CHANGELOG.md(生成物)后,当前有 15 个这样的文件:实测入场价(按先例的口径先量后报)
这 15 个文件里共 4 条仓内相对 markdown 链接,其中 1 条死链:
packages/components/src/renderers/complex/TIMELINE.md:349See the [prototype app](../../examples/prototype/src/App.tsx) …→ 解析到
packages/components/src/examples/prototype/src/App.tsx,不存在;仓根examples/prototype/也不存在。所以 markdown 链接这一面很便宜(先例 #3603/#3622 的入场价是 9~11 条,这里是 1 条)。
真正大的那一面:反引号仓内路径
死链只是一半。#3881 实际被咬的是反引号包裹的仓内路径——
README_SHADCN_SYNC.md的## Files声称shadcn-sync.js在packages/components/目录下,而它一直在仓根scripts/shadcn-sync.js。这类路径没有任何门禁看:scripts/check-skills-paths.mjs(#3735 的产物)只覆盖skills/**,带 baseline;包内 markdown 一概不在其内。两面的失效形状不同,建议分开定价:
SCAN_ROOTS加一行把包内非 README markdown 纳入(链接面,入场价实测 1 条);skills/**推广到包内 markdown(面更大,需另测)。分级
按
finding归档,不带pm:queue,交分诊定级。今天没有 CI 会因它变红,读者付的成本是照着错误路径去找文件。归为观察类而非具体缺陷:那条死链本身是小事,值钱的是「这一整片文件从未被解析过」这个结构事实。出处与去重
发现于 #3881 的实施过程(PR 见该卡)。#3881 的可选修法 3 曾建议「顺带考虑把包内 README* 纳入 check-doc-links 扫描面」,该 PR 刻意未取:它是独立的门禁扩面,有自己的入场价,按 #3536 → #3572 → #3603/#3622 → #4148 这条先例链,每次扩面都是一张独立卡。#3881 落地的是文档内容 + 成员集合钉,已把该文件的反引号路径在包内测试里局部钉住(
packages/components/src/__tests__/readme-shadcn-sync-categories.test.ts),不构成全仓覆盖。检索过开放卡:#3536 / #3572 / #3603 / #3622 / #4148 / #3735 均已关闭,无在途卡覆盖本条。