docs-drift mapper 把 30 个嵌套包全部塌成父目录：只特判了 `plugins`，导致真实漏报（`automation/flows.mdx` 就是其中一个）

[os-zhuang]

scripts/docs-audit/affected-docs.mjs 从变更文件推导包根时只特判了 packages/plugins/*：

let m = f.match(/^(packages\/plugins\/[^/]+)\//) || f.match(/^(packages\/[^/]+)\//);

但这个仓库有 7 个「容器目录」—— 自身没有 package.json、下面才是真包：

容器目录	嵌套包数
packages/plugins/	18 ← 唯一被特判的
packages/services/	16
packages/connectors/	4
packages/apps/	3
packages/qa/	3
packages/triggers/	3
packages/adapters/	1

于是除 plugins 外的 30 个包，改动都会被归到父目录。

症状就在 #4161 的 drift 评论里

那条评论说 "This PR changes 2 package(s): packages/services, @objectstack/spec" —— 该 PR 改的是 packages/services/service-automation，本该报成 @objectstack/service-automation。报出目录名，就是这个 bug 的直接证据。

两个后果，漏报是严重的那个

packages/services/ 没有 package.json，所以：

const pj = join(repoRoot, dir, 'package.json');   // packages/services/package.json — 不存在
if (existsSync(pj)) { name = ... }                 // → name 保持 null

1. npm 名那条匹配臂整个失效。 匹配逻辑是：

if (name && text.includes(name)) hits.push(name);
else if (text.includes(dir)) hits.push(dir);

name 为 null，就只剩路径 token packages/services 可匹配。任何只提 @objectstack/service-automation、不提该路径的文档都会被漏掉。

实测这个漏报确实存在 —— 3 篇：

content/docs/automation/flows.mdx
content/docs/releases/implementation-status.mdx
content/docs/releases/v9.mdx

第一篇是和 wait 节点改动最相关的那一篇。#4161 里它们之所以出现在清单上，纯粹是因为该 PR 同时改了 packages/spec、被 @objectstack/spec 捞到了。一个只改 service-automation 的 PR 会一篇都不报。

这个方向正是工具自己声明要避免的：README 和 #4091 的 changeset 都写着 "over-inclusion is preferred over misses"。

2. 顺带的噪声。 路径 token packages/services 会匹配任何提到该目录下任意路径的文档，所以一个 service-automation 的改动会连带捞出 audit / settings / storage 等服务的文档。这个方向无害（过度包含是设计选择），但归因是错的 —— _(via packages/services)_ 没告诉读者是哪个包。

修法

不要硬编码那 7 个目录名。 那本身就是 #3786 排查的「手抄清单 + 保持同步」形状 —— 新增一个容器目录时它会再次静默失效。应当从文件系统推导：取变更文件路径上最深的、含 package.json 的祖先目录。这样 plugins 的特判也一并消失，而不是再加 6 条。

顺带一提，#4091 给这个脚本加的 --self-test 覆盖不到这条路径 —— 它只钉了 isTestFile 匹配器。守卫自身的守卫有个自己的洞。修的时候应把包根推导也纳入自检，至少含：直接子包（packages/spec）、每类嵌套包（packages/services/x、packages/plugins/y）、以及一个「容器目录本身绝不该成为包根」的断言。

未包含

@objectstack/spec 在 #4161 上匹配 108 篇文档 —— 那是设计如此的过度包含（spec 几乎在每篇文档里都被提到），不是 bug，本 issue 不涉及。

相关

• fix(tooling): docs-drift stops flagging docs for tests-only changes #4091 —— 给这个 mapper 排除测试文件 + 加 --self-test；本 bug 与那次改动无关，是更早就存在的
• 排查「手抄 spec 清单 + "keep in sync" 注释」模式:一天内确认三例,全部曾静默漂移 #3786 —— 「手抄清单没有闸门」模式；本 issue 的修法要求不引入第 8 条手抄

[os-zhuang]

另一条臂：packages/*/scripts/** 改动同样标出全部文档

和本 issue 主体是不同的臂（那条是包根推导错误，这条是「什么算实现改动」），但同一个文件、同一个修复者，记在一起省得分头分析。

证据

#4183 的 diff 是：

packages/spec/scripts/check-generated.ts   （新增）
packages/spec/package.json                 （+1 行脚本注册）
AGENTS.md
.changeset/…

src/ 零改动。drift 评论标出 106 篇手写文档。

理由和 #4091 排除测试文件完全同构：packages/*/scripts/ 是构建与校验工具，不是文档所描述的运行时行为。build-docs.ts 之类的生成器改动确实会改变产物，但那些产物是 content/docs/references/** —— 本工具的扫描范围本来就把它们排除在外（只看手写文档）。

但 package.json 不能一起排除

这点要写清楚，否则修的人容易顺手扩大：package.json 的 exports / main / types / 依赖变更确实是实现相关的，把整个文件排除会造成漏报。只有 scripts 字段的改动是安全的，而区分这一点需要 diff 内容而非路径 —— 成本明显高于收益。

所以这条臂的可做范围只有 packages/*/scripts/** 这一个路径前缀。

落地前需要先验证的一件事

scripts/ 是否在任何包里被实际发布（package.json 的 files 字段）。若某个包把 scripts/ 一起发出去，那它就是运行时代码，这条排除对该包不成立。#4091 当时对测试文件做过等价的核查，这里也该做，别直接照搬。

与主体那条的关系

两条都应进同一次修复的 --self-test：主体那条要断言「容器目录本身绝不该成为包根」，这条要断言「packages/x/scripts/y.ts 不算实现改动，而 packages/x/package.json 算」。

---

Generated by Claude Code