Deno 如何对 Markdown 中的代码块做类型检查：以 deno check --doc-only 测试夹具为例

Deno 如何对 Markdown 中的代码块做类型检查以 deno check --doc-only 测试夹具为例【免费下载链接】denoA modern runtime for JavaScript and TypeScript.项目地址: https://gitcode.com/GitHub_Trending/de/deno本文以 Deno 仓库中tests/specs/check/typecheck_doc_in_markdown/目录下的测试夹具为核心完整拆解deno check --doc-only针对 Markdown 文档的「代码块抽取」规则哪些围栏代码块会被抽取、抽取时如何确定扩展名、ignore属性如何跳过检查、类型错误如何导致检查失败并结合 CLI 源码说明该功能在当前版本中的实现状态与适用前提。测试夹具的定位markdown.md 并不是给人阅读的普通文档而是deno check命令的集成测试夹具spec test fixture。它被test.jsonc 中的测试配置引用用于验证文档代码块类型检查的整套行为。测试配置内容如下{ // Disabled during the TypeScript un-fork: check --doc/--doc-only is not // yet supported by the native tsc backend. Tracked in // https://github.com/denoland/deno/issues/35946. ignore: true, args: check --doc-only markdown.md, exitCode: 1, output: markdown.out }从中可以读出三个关键信息执行命令deno check --doc-only markdown.md。--doc-only表示「只检查文档Markdown、JSDoc中抽取出来的代码块不检查项目里常规的 TS/JS 模块」与之相对的--doc则是「常规检查 文档代码块检查」两种都做。期望退出码为 1这个夹具是故意写坏的——最后一块代码包含类型错误用来断言检查器确实会捕获并报错而不是误判通过。当前被标记为ignore: true由于 Deno 正在进行 TypeScript「un-fork」改用原生 tsc 作为检查后端原生 tsc 后端尚不支持--doc/--doc-only该测试暂时禁用。markdown.md 的五个代码块与五条抽取规则夹具全文 31 行包含 5 个围栏代码块每一个都对应一条明确的抽取规则规则 1无语言标注的围栏块被忽略This is a fenced block without attributes, its invalid and it should be ignored.没有语言属性如js、ts的代码块无法判断其语言类型抽取逻辑会直接跳过不会进入类型检查。这保证了普通说明性文本块如 CLI 输出、ASCII 图不会干扰检查。规则 2js块按.js扩展名抽取console.log(js);带js语言标注的块在抽取时会被赋予.js扩展名从源码结构看Deno 的文档检查会把每个代码块虚拟化为一个带扩展名的模块再交给 tsc扩展名决定语言语义——这是js与ts的关键区别。该块代码合法检查应通过。规则 3ts块按.ts扩展名抽取console.log(ts);ts标注的块被赋予.ts扩展名以 TypeScript 语义检查。同样合法检查通过。规则 4ignore属性强制跳过const value: Invalid ignored;这里代码本身是故意非法的Invalid是未定义类型但围栏属性中带有ignore。规则是带ignore属性的块无论内容如何都不参与类型检查。这条规则的价值在于文档作者经常需要在示例中展示「错误示范」或伪代码ignore提供了合法的逃逸方式避免文档示例被迫改成能编译通过的「正确版」而失真。规则 5类型错误必须使检查失败const a: string 42;这是整个夹具的「引爆点」string类型变量被赋值为数字字面量42是确定性的类型错误。它验证的是检查器真的在对抽取出的文档代码做类型检查——如果检查器静默放行了文档块这条断言就会失败。这正是测试配置中exitCode: 1的来源命令应当以失败结束并在输出中报告该错误输出快照文件名为markdown.out当前测试禁用期间该文件不在仓库目录中。源码层面--doc / --doc-only 在哪里被处理标志位定义在 libs/cli_parser/src/flags.rs 的CheckFlags结构体中含doc/doc_only布尔字段由 cli/tools/check.rs 的check()入口消费。当前仓库中该功能的状态可以在 native_check 中直接看到if check_flags.doc || check_flags.doc_only { // Doc snippet extraction was handled by Deno 2.xs forked tsc; the native // compiler does not type-check markdown/JSDoc snippets yet. log::warn!( {} --doc/--doc-only is not yet supported by the native type checker and will be ignored, colors::yellow(Warning) ); }这段代码透露了两层事实历史实现文档代码块的抽取与类型检查原先由 Deno 2.x 分支自带的 fork 版 tsc 完成该能力最早由「evaluate code snippets in JSDoc and markdown」的提交引入同时覆盖 JSDoc 注释块与 Markdown 围栏块两种来源。当前行为迁移到原生 tsc 后端之后--doc/--doc-only会被忽略并打印黄色警告而不是报错。也就是说在上述版本的 Deno 上运行deno check --doc-only markdown.md会得到警告而非类型错误——这与夹具期望的exitCode: 1不符所以测试被ignore而非删除等待原生后端补齐文档检查能力后重新启用。适用前提与版本限制重要如果你要在自己项目中实践「文档代码块类型检查」必须先确认版本前提能力前提条件deno check --doc/--doc-only实际生效需要构建中启用 fork 版 tsc 文档检查Deno 2.x 时代的默认行为当前仓库所处的 un-fork 迁移期间原生 tsc 后端不支持该标志仅打印警告ignore属性跳过代码块依赖文档抽取逻辑同上js/ts语言标注决定扩展名同上另外cli/tools/check.rs 中还有一条相关警告当前deno check --watch在文件变更后不会重新检查只运行一次涉及文档检查的 watch 工作流同样需要留意这一限制。如何在本仓库中验证在仓库根目录依次查看以下文件即可复现本文全部结论tests/specs/check/typecheck_doc_in_markdown/markdown.md——五条抽取规则的实体tests/specs/check/typecheck_doc_in_markdown/test.jsonc——spec 测试的执行命令、期望退出码与禁用原因cli/tools/check.rs——--doc/--doc-only在当前原生 tsc 后端下的处理路径libs/cli_parser/src/flags.rs——CheckFlags中标志位定义。这套「用故意写坏的测试夹具钉死行为边界」的做法本身也值得借鉴无语言块忽略、语言标注映射扩展名、ignore逃逸、类型错误必须失败——四条规则各自独立成块、互不干扰任何一条抽取逻辑回归都能在 spec 测试中被单独定位。【免费下载链接】denoA modern runtime for JavaScript and TypeScript.项目地址: https://gitcode.com/GitHub_Trending/de/deno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考