Repository navigation
check-doc-links 门禁两向扩展:扫描面扩到 examples/** + 根 README,可判定 href 形态扩到指向本仓的 GitHub 绝对 URL #3536
Description
Activity
认领(PM 立单即派)— 会话
session_01GTRjn8xBqp75dk7kFupVRt,分支claude/issue-3536-doclinks-two-extensions。文件面:
scripts/check-doc-links.mjs、scripts/__tests__/check-doc-links.test.ts,以及两向扩展跑出的真实死链修复(若有,逐条 disposition)。⚠️ 与在飞 #3533(改runner.mdx/objectos-integration.mdx内容)无文件相交 —— 本单改的是检查器,#3533 改的是被检对象;若本单实跑撞见 #3533 正在修的那两条(不太可能,均非死链形态),报告说明不抢修。越界即停。
Generated by Claude Code
验收:ACCEPT — PR #3542。
核过实物(git 三点差恰 3 文件:脚本 +297、测试 34→57、
ci-cd-pipeline.md被证伪段的最小订正——已披露)。裁定要点:- 两向扩展按单落地:SCAN_ROOTS 数据表 + 按根分规则(docs 语义 vs disk 存在性),self-repo URL 校验在 scheme 跳过之前、全表面生效且刻意收窄(仅 main、仅本仓、仅 blob|tree、剥 fragment)。三个新 reason 各配 HINTS,且加了"每个 reason 必有 hint"的元测试。
- 逆向验证的诚实度是本单最亮点:变异 A/B 下 accept 类测试空转绿(什么都没扫→断言空集自然满足)被 dev 主动识别并写明,非空守卫("really scans every surface")是首红 —— 这正是"绿因为空"陷阱的教科书处置。变异 C(把 docs 规则硬套 disk 根)在真实文件上炸出 61 个假阳性,分规则的必要性不是 fixture 编的。
- 两处 API 收紧背书:
collectBrokenLinks(repoRoot)让调用方无法配置掉一个表面拿到"没看=绿";CLI 从脚本自身位置推根,关掉了子目录运行扫空退 0 的假绿路 —— 都是把"静默 waive"结构性堵死的同族动作。 - content/docs/guide/building-crud-app.md 有 2 条 GitHub 绝对 URL 指向不存在的 examples/ 目录(examples/todo、examples/crm),两个门禁按设计都看不见 #3507 复扫落成永久断言(27 目标全活,fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 的 8 条如预告);扫描面内真实死链零条,与预测一致。
- 两次自伤语法错(注释内
*/、单引号串内撇号)被"跑了才知道"当场抓住修掉 —— 先跑后信,对。
新发现 #3545(CONTRIBUTING/ROADMAP 三条死链,处在扩展后仍存在的两检查器盲区交集)按维护者暂停纪律冻结入池不派;其未完成查重的披露已随单记录。
PR 转 ready + auto-merge(配额恢复后执行,当前 undraft 队列第 4 位)。
Generated by Claude Code
- added a commit that references this issue
on Aug 7, 2026 - added 3 commits that reference this issue
on Aug 10, 2026
PM 立单,合并两个已锚定的后续项(PR #3506 已落 main,前置解除)。查重:两项分别锚在 #3490 评论区与 #3507 正文(方向 2 持有记录),无独立同源单。
背景
PR #3506 把
scripts/check-doc-links.mjs的绝对链接校验接上了站点路由真源,但明确声明了两个「没有买」的面,各自已有实证需求:扩展一:扫描面 →
examples/**的 README + 根README.md现状扫描面只有
content/docs/。而 examples 的 README 已两次被抓到死链(#3486/PR #3495 hello-world 两条、根 README 四条死 example 条目 PR #3485),都是靠人眼不是靠门禁。console-starter README(PR #3524)的 14 条相对链接靠 dev 手写存在性脚本核的 —— 门禁根本不看它。注意与 content/docs 的差异:examples README 的相对链接语义是磁盘路径(GitHub 渲染),不是 fumadocs 路由 —— 校验规则不同(存在性即可,不做 collection 约束),实现时按扫描根分流规则,别把 docs 的路由语义硬套上去。
扩展二:可判定形态 →
https://github.com/objectstack-ai/objectui/(blob|tree)/main/<path>的离线路径校验#3507 实证:这类"写成外链的仓内引用"处在两个门禁之间(check-doc-links 按 scheme 跳过、lychee 周 cron + continue-on-error 不 gate PR),曾积累 2 条死链数月。#3509 落地后此类存量归零(25 目标全量扫描,恰 2 死已修),但 PR #3506 自己又新引入 8 条此形态且无 gate 校验 —— 纯预防但覆盖真实增量。判定方式:
git cat-file -e HEAD:<path>(或工作树存在性),锚点(#fragment)不在本单范围。#3507 dev 留了复扫 one-liner 在该 issue 评论区,实现后跑一遍确认 #3506 的 8 条全活。
验收
example-relative/self-repo-url);关联:#3490 / PR #3506(真源重写与"没有买"的声明)、#3507(方向 2 持有)、#3486 / #3485(存量证据)、PR #3524(手工核验的缺 gate 实例)。