Rolldown 的 cannotCallNamespace 检查在构建期捕获模块命名空间对象的误调用【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown导读checks.cannotCallNamespace是 RolldownRollup 兼容 API 的 Rust 版 JavaScript/TypeScript 打包器提供的一项构建期静态检查当代码把通过import * as utils引入的模块命名空间对象module namespace object当作函数调用时Rolldown 会在打包阶段发出警告提前暴露这段必然在运行时抛错的代码。本文基于仓库文档 packages/rolldown/src/options/docs/checks-cannot-call-namespace.md 展开结合 event_kind.rs、import_analyzer.rs 等源码讲解该检查的触发条件、诊断输出格式与配置方法帮助你在项目中借助它消除一类隐蔽的运行时崩溃。问题背景命名空间对象不是函数ES 模块中import * as utils from ./utils.js引入的utils是一个模块命名空间对象Module Namespace Object。它是一个普通对象其属性对应被导入模块的全部导出named exports 与 default export。对象不是函数因此对它直接进行调用utils()或作为标签模板utils...使用时JavaScript 运行时会抛出TypeError: utils is not a function。这类错误的特点是静态语法完全合法TypeScript 类型检查器在某些宽松配置下也可能放行只有代码实际执行到该行时才会崩溃——import * as的写法在重构例如把默认导出改成命名导出后尤其容易残留这种误调用。Rolldown 的cannotCallNamespace检查正是为在构建期捕获这一隐患而设计其枚举定义位于 event_kind.rs原文注释明确指出A module namespace object is an object and not a function. Calling it as a function will cause a runtime error.触发警告的最小示例仓库文档提供了可直接复现的最小示例checks-cannot-call-namespace.md。包含两个模块main.jsimport * as utils from ./utils.js; // This will trigger the warning // because utils is a namespace object, not a function utils();utils.jsexport function greet() { return Hello; }使用 Rolldown 打包main.js时由于utils是通过import * as引入的命名空间对象utils()这一调用会触发cannotCallNamespace警告同时构建照常成功该事件默认是 warning 级别不会中断打包。检测原理AST 扫描器如何发现误调用该检查并非运行时防护而是 Rolldown 在**链接阶段之前的 AST 扫描ast_scanner**中完成的静态分析。核心实现在 crates/rolldown/src/ast_scanner/import_analyzer.rs 的check_import_assign方法中其判定逻辑可分三步确认标识符是导入符号通过symbol_flags.contains(SymbolFlags::Import)判断当前标识符引用指向一个 import 绑定确认是命名空间导入在named_imports中查找该SymbolRef并检查其导入类型是否为Specifier::Star即import * as形式确认它被当作可调用值使用检查 AST 访问路径中的父节点当父节点为CallExpression且该标识符恰好是callee或父节点为TaggedTemplateExpression且该标识符是tag时即判定为误调用。值得注意检测范围不仅限于普通函数调用还包括标签模板用法utils...——这两种语法在运行时同样要求被调用的值是一个函数。判定命中后扫描器通过 constructors.rs 中的BuildDiagnostic::cannot_call_namespace(...)构造函数创建诊断并显式调用.with_severity_warning()将其标记为 warning推入self.result.warnings。诊断输出警告信息里写了什么当警告被触发时Rolldown 会生成一条包含两个源码标注label的诊断实现见 crates/rolldown_error/src/build_diagnostic/events/cannot_call_namespace.rs主消息Cannot call a namespace (utils).对应message()方法调用处标注定位到utils()的调用 span提示This will cause an error at runtime because utils is a module namespace object and not a function. Consider changing utils to a default import instead.——直接给出修复建议改用默认导入import utils from ./utils.js前提是目标模块确实提供了默认导出声明处标注定位到import * as utils的导入声明 span提示utils is imported as a namespace here帮助开发者一眼找到误用根因。诊断事件结构体CannotCallNamespace携带了filename、source、span、name与declaration_span五个字段分别用于渲染文件路径、源码片段、调用位置、被调用的名称以及导入声明位置使 IDE 与终端日志都能同时高亮调用点与声明点两处代码。配置开关checks.cannotCallNamespace该检查可通过打包配置中的checks.cannotCallNamespace开关控制对应的 TypeScript 类型定义在 packages/rolldown/src/options/generated/checks-options.ts/** * Whether to emit warnings when a namespace is called as a function. * * A module namespace object is an object and not a function. Calling it as a function will cause a runtime error. * * default true * */ cannotCallNamespace?: boolean;即默认开启true。如果你希望关闭此检查例如项目中有意保留这类代码等待后续重构且不想被警告干扰可以这样配置// rolldown.config.js export default { input: src/main.js, checks: { cannotCallNamespace: false, }, };从源码结构看CannotCallNamespace在事件枚举中对应位标记1 32见 event_kind_switcher.rs与CannotCallNamespace 32的枚举序号一一对应事件种类切换器据此在运行时把诊断事件分发到对应的事件处理分支。与其他 checks 检查的配合cannotCallNamespace属于 Rolldownchecks检查族中的一员与其语义相近的还有checks.importIsUndefinedImportIsUndefined 20检测导入了目标模块并未导出的变量这类变量取值恒为undefined同样是重构残留代码的常见隐患checks.mixedExports检测一个模块同时使用 ESM 与 CommonJS 导出风格的混用问题。这三者分别覆盖了调用了不存在的行为调用对象读取了不存在的导出值为 undefined导出风格冲突三类导入/导出侧的常见错误。建议保持默认开启让构建期警告充当低成本的运行时崩溃防线若某个检查产生噪音再按上文的checks配置逐项关闭。小结checks.cannotCallNamespace用极低的静态分析成本拦截了命名空间对象被当作函数调用这类必然在运行时抛TypeError的代码。它依托 Rolldown AST 扫描器对CallExpression与TaggedTemplateExpression的调用点检测输出同时指向调用处与导入声明处的双标注诊断并直接给出改用默认导入的修复建议。开启它默认即开启就能在npm run build阶段提前发现这些运行时才会爆炸的问题。参考资料文档示例 checks-cannot-call-namespace.md供default true的 API 文档内嵌展示、事件枚举 event_kind.rs、诊断实现 cannot_call_namespace.rs、检测逻辑 import_analyzer.rs、配置类型 checks-options.ts。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Rolldown 的 cannotCallNamespace 检查：在构建期捕获模块命名空间对象的误调用
Rolldown 的 cannotCallNamespace 检查在构建期捕获模块命名空间对象的误调用【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown导读checks.cannotCallNamespace是 RolldownRollup 兼容 API 的 Rust 版 JavaScript/TypeScript 打包器提供的一项构建期静态检查当代码把通过import * as utils引入的模块命名空间对象module namespace object当作函数调用时Rolldown 会在打包阶段发出警告提前暴露这段必然在运行时抛错的代码。本文基于仓库文档 packages/rolldown/src/options/docs/checks-cannot-call-namespace.md 展开结合 event_kind.rs、import_analyzer.rs 等源码讲解该检查的触发条件、诊断输出格式与配置方法帮助你在项目中借助它消除一类隐蔽的运行时崩溃。问题背景命名空间对象不是函数ES 模块中import * as utils from ./utils.js引入的utils是一个模块命名空间对象Module Namespace Object。它是一个普通对象其属性对应被导入模块的全部导出named exports 与 default export。对象不是函数因此对它直接进行调用utils()或作为标签模板utils...使用时JavaScript 运行时会抛出TypeError: utils is not a function。这类错误的特点是静态语法完全合法TypeScript 类型检查器在某些宽松配置下也可能放行只有代码实际执行到该行时才会崩溃——import * as的写法在重构例如把默认导出改成命名导出后尤其容易残留这种误调用。Rolldown 的cannotCallNamespace检查正是为在构建期捕获这一隐患而设计其枚举定义位于 event_kind.rs原文注释明确指出A module namespace object is an object and not a function. Calling it as a function will cause a runtime error.触发警告的最小示例仓库文档提供了可直接复现的最小示例checks-cannot-call-namespace.md。包含两个模块main.jsimport * as utils from ./utils.js; // This will trigger the warning // because utils is a namespace object, not a function utils();utils.jsexport function greet() { return Hello; }使用 Rolldown 打包main.js时由于utils是通过import * as引入的命名空间对象utils()这一调用会触发cannotCallNamespace警告同时构建照常成功该事件默认是 warning 级别不会中断打包。检测原理AST 扫描器如何发现误调用该检查并非运行时防护而是 Rolldown 在**链接阶段之前的 AST 扫描ast_scanner**中完成的静态分析。核心实现在 crates/rolldown/src/ast_scanner/import_analyzer.rs 的check_import_assign方法中其判定逻辑可分三步确认标识符是导入符号通过symbol_flags.contains(SymbolFlags::Import)判断当前标识符引用指向一个 import 绑定确认是命名空间导入在named_imports中查找该SymbolRef并检查其导入类型是否为Specifier::Star即import * as形式确认它被当作可调用值使用检查 AST 访问路径中的父节点当父节点为CallExpression且该标识符恰好是callee或父节点为TaggedTemplateExpression且该标识符是tag时即判定为误调用。值得注意检测范围不仅限于普通函数调用还包括标签模板用法utils...——这两种语法在运行时同样要求被调用的值是一个函数。判定命中后扫描器通过 constructors.rs 中的BuildDiagnostic::cannot_call_namespace(...)构造函数创建诊断并显式调用.with_severity_warning()将其标记为 warning推入self.result.warnings。诊断输出警告信息里写了什么当警告被触发时Rolldown 会生成一条包含两个源码标注label的诊断实现见 crates/rolldown_error/src/build_diagnostic/events/cannot_call_namespace.rs主消息Cannot call a namespace (utils).对应message()方法调用处标注定位到utils()的调用 span提示This will cause an error at runtime because utils is a module namespace object and not a function. Consider changing utils to a default import instead.——直接给出修复建议改用默认导入import utils from ./utils.js前提是目标模块确实提供了默认导出声明处标注定位到import * as utils的导入声明 span提示utils is imported as a namespace here帮助开发者一眼找到误用根因。诊断事件结构体CannotCallNamespace携带了filename、source、span、name与declaration_span五个字段分别用于渲染文件路径、源码片段、调用位置、被调用的名称以及导入声明位置使 IDE 与终端日志都能同时高亮调用点与声明点两处代码。配置开关checks.cannotCallNamespace该检查可通过打包配置中的checks.cannotCallNamespace开关控制对应的 TypeScript 类型定义在 packages/rolldown/src/options/generated/checks-options.ts/** * Whether to emit warnings when a namespace is called as a function. * * A module namespace object is an object and not a function. Calling it as a function will cause a runtime error. * * default true * */ cannotCallNamespace?: boolean;即默认开启true。如果你希望关闭此检查例如项目中有意保留这类代码等待后续重构且不想被警告干扰可以这样配置// rolldown.config.js export default { input: src/main.js, checks: { cannotCallNamespace: false, }, };从源码结构看CannotCallNamespace在事件枚举中对应位标记1 32见 event_kind_switcher.rs与CannotCallNamespace 32的枚举序号一一对应事件种类切换器据此在运行时把诊断事件分发到对应的事件处理分支。与其他 checks 检查的配合cannotCallNamespace属于 Rolldownchecks检查族中的一员与其语义相近的还有checks.importIsUndefinedImportIsUndefined 20检测导入了目标模块并未导出的变量这类变量取值恒为undefined同样是重构残留代码的常见隐患checks.mixedExports检测一个模块同时使用 ESM 与 CommonJS 导出风格的混用问题。这三者分别覆盖了调用了不存在的行为调用对象读取了不存在的导出值为 undefined导出风格冲突三类导入/导出侧的常见错误。建议保持默认开启让构建期警告充当低成本的运行时崩溃防线若某个检查产生噪音再按上文的checks配置逐项关闭。小结checks.cannotCallNamespace用极低的静态分析成本拦截了命名空间对象被当作函数调用这类必然在运行时抛TypeError的代码。它依托 Rolldown AST 扫描器对CallExpression与TaggedTemplateExpression的调用点检测输出同时指向调用处与导入声明处的双标注诊断并直接给出改用默认导入的修复建议。开启它默认即开启就能在npm run build阶段提前发现这些运行时才会爆炸的问题。参考资料文档示例 checks-cannot-call-namespace.md供default true的 API 文档内嵌展示、事件枚举 event_kind.rs、诊断实现 cannot_call_namespace.rs、检测逻辑 import_analyzer.rs、配置类型 checks-options.ts。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考