没有门禁校验「package.json 的 files 条目在磁盘上真实存在」——npm 静默跳过缺失条目,#3647 因此长期无人察觉

发现于 #3647 的实施(PR #3662)。观察类记录,不在该单完成范围内。

事实

npm 对 package.json files 里不存在的条目是静默跳过的:不报错、不警告、退出码 0。于是「声明要打包 X、但 X 不存在」这种 manifest 与事实不符的状态,npm publish、npm pack、CI 全都发现不了。

#3647 就是这个机制的一个实例:@object-ui/plugin-tree 的 files 写着 "LICENSE",而 packages/plugin-tree/LICENSE 不存在,已发布的每一个 tarball 都缺这份 MIT 文本,而 CI 从未报过任何信号。它是靠人工逐包核对 files 才被翻出来的(#3622 的排查副产物),不是靠门禁。

实测仓库现有脚本(origin/main),没有任何一条覆盖这个面:

$ grep -rn "LICENSE" scripts/ .github/workflows/     # 只有 check-doc-links 的注释与测试夹具
$ grep -rln "\"files\"" scripts/                     # 只有 shadcn-sync 相关,与打包无关

scripts/check-doc-links.mjs 查的是 README 里链接的死活,查不到这一类:plugin-tree 的 README 连指向 ./LICENSE 的链接都没有,自然没有死链可报(见 #3664)。

为什么记为观察类

#3647 修掉的是当前唯一的实例,所以今天没有用户会撞上。这条记的是同类缺陷可以再次静默发生:任何人往 files 里加一个条目、或删掉一个被 files 点名的文件,都不会有任何东西拦住。

可能的处置(供分诊裁决,未实施)

一条很小的脚本即可闭合:遍历所有非 private 包,断言 files 里的每个条目在磁盘上能解析到(dist 这类构建产物需要按「构建后校验」或允许缺失来区分处理)。也可以顺带断言「每个已发布包都带 LICENSE」——但后者与 react-runtime / sdui-parser 的打包策略问题耦合,那是另一个决定。

具体形态与是否值得做,请分诊裁决。

认领(PM 派发)。

Session: session_01GTRjn8xBqp75dk7kFupVRt
分支:claude/issue-3663-files-exist-gate
文件面:scripts/__tests__/ 新测试文件(或新脚本 + 测试,以既有门禁形态先例定 — 纯静态断言倾向直接写成 vitest 测试,不必新开 workflow)+ 如需的头注。⛔ 不碰 check-doc-links.mjs(刚被 docs(scripts): 按真实机制改写两处 Lychee 门禁描述,并删掉 judgeHref 重复注释 (#3587) (#3648) #3656 改)、不碰在途 i18n 门禁:en 文案变更时其余九包必须同批跟改(或显式挂账)——#3582/#3625 族缺陷缺的那道不变量 #3650 的 en-drift 文件。
处置:对每个非 private 包断言 package.json files 条目在磁盘可解析(dist 类构建产物条目按 glob 语义豁免或以「目录将由构建产生」白名单处理 — 先测量 39 包 files 形态再定,取舍写 PR);落地基线应为绿(@object-ui/plugin-tree 的 package.json files 声明了 LICENSE,但 packages/plugin-tree/LICENSE 不存在——已发布包缺失它自己声明要带的许可证文本 #3647/PR fix(plugin-tree): 补上 package.json files 已声明、但仓库里不存在的 LICENSE (#3647) #3662 已清唯一存量 — 以你的全量扫描复核);逆向验证:临时在某包 files 塞不存在条目 → 红且点名。
⚠️ LICENSE 类 npm 恒包含的条目不豁免检查 — 门禁断言的是「声明与磁盘一致」,与 npm 是否兜底无关(fix(plugin-tree): 补上 package.json files 已声明、但仓库里不存在的 LICENSE (#3647) #3662 已证 npm 静默跳过正是潜伏机制)。

Generated by Claude Code

验收 ACCEPT → PR #3667(session_01GTRjn8xBqp75dk7kFupVRt)。

已核:单文件 334 行,159 条条目普查(40 包)、预测 A-E 全中(含反直觉方向 C 的显式钉法);反空绿三层(包数下限 + 具名钉 + git 命令失败抛错而非空集)。

裁决记录:

git 推导豁免判据记入方法库:三条同时成立才豁免(git-ignore + 未跟踪 + 有 build 脚本)— 白名单需要人维持正确,而「掩盖真实缺陷」与「教门禁认新构建目录」的编辑不可区分;推导后豁免的唯一途径是 .gitignore 声明,可评审。
开放问题裁决:A 先落地,B 紧随 — 采纳 dev 推荐。棘轮双向性(验证 C)保证 B 完成时套件转红逼删基线行,两径收敛同终态;门禁立刻防新增违规优于等 B 排期继续裸奔。@object-ui/cli 与 @object-ui/create-plugin 的 files 声明了 templates,但该目录从未在仓库里存在过——#3647 的同类残留声明 #3665 即 B 卡:删两个 package.json 的 templates 行 + create-plugin 死变量 + 清空 KNOWN_MISSING — ⚠️ 碰本 PR 的测试文件,串行等 3667 落 main 后派。
39 vs 40 的口径修正(vscode-extension private 无 files;+console/schema-catalog)与「不证明构建产物真会生成」的边界声明,诚实完整。

Generated by Claude Code

test(scripts): gate that package.json `files` entries exist on disk (o…

Navigation Menu

Repository navigation

没有门禁校验「package.json 的 files 条目在磁盘上真实存在」——npm 静默跳过缺失条目,#3647 因此长期无人察觉 #3663

事实

为什么记为观察类

可能的处置(供分诊裁决,未实施)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

没有门禁校验「package.json 的 files 条目在磁盘上真实存在」——npm 静默跳过缺失条目,#3647 因此长期无人察觉 #3663

Description

事实

为什么记为观察类

可能的处置(供分诊裁决,未实施)

Activity

yinlianghui commented on Aug 7, 2026

yinlianghui commented on Aug 7, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions