Tianyi Cui
3a88912a22
A repo-wide Not Invented Here audit (ten parallel domain surveys covering every package group, scripts/, native/, vendor/ edges, python/, test infrastructure, and CI) asked of each hand-rolled surface whether a maintained external package or Node builtin deletes it with a net win. Policy: new implemented process note records that a dependency which genuinely deletes owned code is a preferred simplification (bar: net deletion, health, boundary fit, settled seams stay); root AGENTS.md carries the one-line rule and dsh-find-simplifications now surveys for hand-rolled-where-a-dependency-exists candidates. Findings, all bilingual from birth: - proposed/simplification: eventsource-parser for llm-deepseek SSE, node:timers/promises for three hand-rolled sleeps, turndown (or minimal 'entities') for tool-web HTML->markdown, gate-script consolidation onto mdast/parseArgs/globSync - proposed/testing: execa + parseArgs + loadEnvFile + vi.waitFor for hand-rolled test subprocess plumbing - proposed/process: pnpm/action-setup for symmetric CI caching - proposed/feature: evaluate landstrip before building a Windows sandbox launcher - rejected/simplification: ~30 swap verdicts recorded (vscode-jsonrpc, p-retry, Ajv, write-file-atomic, msw, hono, better-sqlite3, wireit, landstrip-for-linux, YAML consolidation, ...) so the survey is not re-litigated from scratch Also drops the stale prompt/ entry from the AGENTS.md layout map (workspace instructions live in packages/context/workspace-context).
4.6 KiB
4.6 KiB
Agent Note: 把门禁脚本统一到已有依赖与内置模块上
Status: proposed
English | 中文
问题
scripts/ 下的门禁大多已经在用正确的工具（15 个以上的门禁使用 node:fs 的 globSync，markdown 门禁使用 mdast/micromark），但少数几个掉队的脚本仍在手写同类门禁早已用既有依赖或内置模块完成的事情：
- 重复的围栏扫描器。
scripts/md-fences.ts（约 55 行，由doc-typecheck.ts消费）和scripts/verify-type-equiv.ts中的extractEquivBlocks（约 39 行）是同一个围栏代码块正则行扫描器的两份拷贝，而scripts/verify-mermaid.ts已经通过共享的scripts/markdown.ts辅助函数访问 mdastcode节点来提取代码围栏；markdown.ts自己的markdownProseLines也是先解析成 mdast，再用第二个正则手工跟踪围栏状态。这两个正则扫描器只识别第 0 列的反引号围栏，因此在波浪线围栏和缩进围栏上与基于 mdast 的门禁悄悄不一致。 - 手写的 argv 解析。
scripts/publint-all.ts中的parseOptions和scripts/verify-built-package-invariants.mjs中与之几乎相同的拷贝（约 26 行）手工推进 argv 下标，而同类脚本（verify-runtime-closure.ts、build-exe-for-python-sdk.ts、packages/sdk/scripts/src/args.ts）已经在使用node:util的内置parseArgs。 - **手写的目录遍历。**五处代码各自重写了
globSync已覆盖的嵌套readdirSync遍历：verify-runtime-closure.ts对 packages 与 vendor manifest（元数据清单）的扫描、dev-web.ts的discoverPluginDirs、verify-package-paths.ts的realPackageNames、verify-client-domain-graph.ts的listSources，以及publint-all.ts的addPath（合计约 55–65 行）。scripts/package-invariants.ts展示了一行式的globSync模板。
所有替换都不需要引入新依赖；每一处替换用的都是既有的 devDependency 或 Node 内置模块。
提案
- 在
scripts/markdown.ts中提取一个约 10–15 行的共享 mdast 围栏辅助函数（访问code节点，读取lang、meta、value、position.start.line）；把doc-typecheck.ts和verify-type-equiv.ts改写到它上面；删除md-fences.ts和重复的扫描器；去掉markdownProseLines中冗余的围栏正则。 - 用
parseArgs替换两份parseOptions拷贝。 - 用
globSync替换那五处掉队的目录遍历。保留check-workspace-constraints.ts和clean.ts中的遍历：它们需要 dirent 级别的细节来诊断结构异常的目录树，按模式匹配的 glob 报告不了这些信息。
曾考虑的替代方案
- **新的 glob/目录遍历依赖（
tinyglobby、fdir）。**不予采纳：内置模块已在全仓库范围内胜出；这几处只是掉队者，不是能力缺口。 - **用
p-map替换publint-all.ts中约 19 行的有序 worker 池。**刻意未纳入：为一次小删除引入一个新 devDependency，正处在依赖策略门槛的边缘，而且该池的需求（worker 数量有界、确定性顺序、环境变量覆盖）已记录在并行 pre-push 门禁决策记录中。仅当p-map赢得第二个消费方时再顺带纳入。 - **保留这两个围栏扫描器。**不予采纳：在第三个正确实现旁边放着两份逐渐漂移的解析器拷贝，正是共享的
markdown.ts辅助函数要防止的那种重复；「只认第 0 列反引号」的限制也是同类门禁之间的潜在不一致。
验收标准
md-fences.ts已删除；doc-typecheck与verify-type-equiv通过scripts/markdown.ts提取代码围栏；pnpm run doc-sync在当前代码树上通过且结果不变（如有差异，必须能追溯到正则扫描器处理有误的某种围栏形态）。- 两个 CLI 都改用
parseArgs解析；未知选项仍然大声失败。 - 五处遍历代码改用
globSync；它们供给的门禁保持原样通过。
风险
- 病态 markdown 上的行为差异：mdast 会承认正则扫描器忽略的波浪线围栏和缩进围栏，因此如果文档树中存在任何零散的此类围栏形态，
doc-typecheck的 opt-out 比例可能变化；应在改动前后分别运行doc-sync加以验证。 parseArgs对重复出现的选项保留最后一个值而不报错，还会把下一个以--开头的 token 当作值消费；这两种情况都是测试未固定的开发工具边缘用例。