src/utils/ 里 1,373 行 .js 不受类型检查，而 .js/.ts 的分界线已经名存实亡（并带来一条未声明的 Node ≥22.18 依赖）

[SongshGeo]

src/utils/ 里 8 个 .js 文件、1,373 行，astro check 一行都没看。而「为什么是
.js 不是 .ts」这个理由，仓库自己已经不遵守了。

事实一：这 1,373 行不受类型检查

tsconfig.json extends astro/tsconfigs/strict，它继承的 base.json 里是
"allowJs": true，而没有 checkJs。所以：

src/utils/contentLayout.js            170   （23 个文件 import 它，全仓被 import 最多）
src/utils/i18nContract.js             387
src/utils/obsidian-links.js           275
src/utils/rehype-callouts.js          147
src/utils/render-markdown.js          137
src/utils/bundleAssets.js             106
src/utils/remark-obsidian-callouts.js  94
src/utils/remark-revive-directives.js  57

eslint.config.js 的注释已经把这件事写下来了，并且说 ESLint 是唯一看得见它们的
工具——但 ESLint 看不出类型。这里面正是它列举的「path resolution、remark AST
surgery、recursive deletes」。

事实二：.js / .ts 的分界线已经失效

原来的理由是「scripts/*.mjs 要不经构建直接 import 它们」，写在
contentLayout.js 和 i18nContract.js 的文件头。但 scripts/check-content.mjs
现在这么写：

import { normalizeRole, ROLES } from '../src/utils/roles.ts';
import { matchAuthorIds, readPeople } from '../src/utils/peopleIndex.ts';

它已经在直接 import .ts 了。所以「必须是 .js」不再成立，剩下的 8 个 .js 是
历史，不是规则。现在的状态最坏：既没有统一的规则可讲，又丢掉了类型。

事实三：这条隐式依赖没有被记录，且和声明的 Node 版本不一致

.mjs 直接 import .ts 依赖 Node 的 type stripping。它在 Node 22.6 需要
--experimental-strip-types，到 22.18 才默认开启。而仓库声明的是：

package.json   "engines": { "node": ">=22.0.0" }
.nvmrc         22

在 Node 22.0–22.17 上，npm run check:content 和 npm run i18n:manifest 会直接
报错——两个都在 CI 的必经路径上。CI 现在能过，是因为 .nvmrc 的 22 解析到了
新的 22.x。这不是一个可以靠运气维持的约束。

建议

1. 把 engines.node 收紧到 >=22.18.0，.nvmrc 写具体版本。这一步立刻做，
   和下面无关。
2. 把 8 个 .js 全部转成 .ts。scripts 已经证明它 import 得动。
3. 转完之后 astro check 自动覆盖它们；不想一次转完的话，中间状态可以先在
   tsconfig.json 打开 "checkJs": true + 逐文件加 // @ts-check，把当前的
   类型错误暴露出来再排期。

[SongshGeo]

第一部分（真正会炸的那个）已实现，第二部分未做。

已做：

• package.json 的 engines.node → >=22.18.0，.nvmrc → 22.18.0（钉死在下限，这样 CI 跑的就是下限本身，engines 不会变成一句空话）。
• 查过依赖：astro 要 >=22.12、vite >=22.12、vitest >=22.0，没有任何一个要 22.18 以上，所以 22.18 这个下限确实是 type stripping 一家定的。
• README 的 Commands 一节写明了下限和它的真实理由。

未做：8 个 .js 转 .ts。

现状：src/content-layer/ 3 个、src/markdown/ 5 个、src/i18n/contract.js 1 个，合计 ~1,300 行仍不过 astro check。这是个纯机械但会摊开很大 diff 的改动，和其余五个 issue 的结构性改动混在一起不好审，留作独立一轮。

eslint.config.js 里那段注释已更新成现在的目录，并指回本 issue。

[SongshGeo]

第二部分已完成（commit af52c18）。src/ 下已经没有 JavaScript。

八个文件全部转成 .ts：content-layer/ 2 个、markdown/ 5 个、i18n/contract.ts。scripts/*.mjs 和 test/e2e/*.mjs 保持不变——它们是 Node 直跑的 CLI 入口，eslint.config.js 里那段注释也改成了这么说。

scripts/*.mjs 现在 import 的是 .ts specifier，靠的正是 07db67f 钉下的 Node ≥22.18。四个脚本都对着 fixtures 实跑验证过，不只是 CI 里的那两个。

类型在写第一行之前就已经回本

1. obsidian-links 会把任意字符串当 locale 拼进 URL。

const fmLang = file?.data?.astro?.frontmatter?.lang;   // 作者在 frontmatter 里随便写的
const lang = fmLang || inferredFromPath || 'zh';
href = entryHref(lang, 'library', slug);              // ← 类型报错

一篇写了 lang: fr 的笔记会产出 /fr/library/…——一个站点根本不构建的 URL，而且不会有任何警告。现在按 LOCALES 收窄，落不到就退回基准语言（顺带干掉了这个文件里自己那份硬编码的 'zh'）。

2. remark-obsidian-callouts 先构造节点、再往可选字段里写。

const directiveNode: ContainerDirective = { …, data: { hName, hProperties } };
if (titleText) directiveNode.data.hProperties['data-title'] = titleText;
//                            ^^^^ ts(18048): possibly undefined

data 和 hProperties 在节点类型上都是可选的，所以这次写入从来没有被保证落到任何地方。改成一次性构造出来。

3. bundleAssets 现在有自己的 key 类型。 bundleAssets('library', …)——一个不使用 bundle 的集合——从「运行时静默返回空对象」变成编译错误。运行时保护保留，测试里写清了为什么。

用真类型，而不是近似

@types/mdast / @types/hast 本来就在（传递依赖），mdast-util-directive 也自带 ContainerDirective / TextDirective 并且会 augment mdast 的 node map——所以那几个 visitor 里的收窄是编译器做的，不是我断言的。

只剩两处 cast，都写了注释：remark-wiki-link 的节点类型（那个插件不发类型），以及 Astro 挂在 vfile 上的 frontmatter。

另外，把 bundleAssets 类型化之后，localizedPages.ts 里那个「因为被调用方没类型」而存在的 cast 直接删掉了。

验证

和 07db67f 同一把尺子：46 个页面、1051 个链接、全部可见文本与重构前基线逐字节一致。lint（0 error 0 warning）、251 个测试、check:content、i18n:manifest、astro check、以及浏览器 e2e（起了 preview 实跑，PASS）全绿。