解决VS Code中JSDoc无法识别Protocol Buffers生成JS代码的语义检查报错问题

• VS Code开启js/ts.implicitProjectConfig.checkJs后的语义检查，底层依赖TypeScript的静态类型推导逻辑，仅能识别代码中顶层静态声明的模块导出，无法解析Protobuf生成代码中运行时动态挂载的导出属性
• 官方Protobuf JS编译器默认生成CommonJS风格代码时，不会附带静态识别需要的JSDoc类型注解，导出逻辑为运行时通过闭包赋值挂载fooPackage、Foo等成员到module.exports上，静态扫描阶段无法推导到这些动态属性，因此会报成员不存在的错误
• 常规手写的bar.js可被正常识别，是因为其导出为模块顶层的静态声明，完全匹配TypeScript静态推导的规则；而手写的JSDoc typedef导入逻辑，因为缺少对应模块的类型声明依据，自然会触发导出成员不存在的报错
• 该问题不属于ESLint规则冲突，也不属于项目配置错误，本质是Protobuf默认生成代码的结构，和TypeScript静态类型检查的推导逻辑不兼容

• 为Protobuf生成文件补充同路径的TypeScript类型声明
  • 与foo_pb.js同目录下新建foo_pb.d.ts文件，手动声明模块的导出结构，明确标注导出的fooPackage命名空间、命名空间下的Foo枚举成员及对应枚举值
  • 声明文件仅参与静态类型校验，不会被Node.js运行时加载，无运行时侵入性
• 调整Protobuf编译参数生成带类型的代码
  • 编译时添加--js_out=import_style=typescript参数重新生成对应PB文件，生成的代码会自动包含符合静态识别要求的导出结构与配套类型信息，可被checkJs能力、ESLint google规则集直接识别，无需额外手写声明
• 针对生成路径做校验规则覆盖
  • 在项目jsconfig.json中，对存放Protobuf生成代码的目录配置路径级覆盖，关闭对应路径下的checkJs能力，跳过对生成代码的静态类型校验，从根源屏蔽报错
  • 注意该方案仅能消除报错，无法为生成代码提供类型提示，适合临时过渡场景
• 修正JSDoc导入的写法
  • 不单独使用typedef拆分导入Protobuf的成员，在完成类型声明补全的前提下，直接通过标准CommonJS语法导入模块，配合/** @type {typeof import('./foo_pb.js')} */格式的JSDoc标注引用成员，避免因导入语法不匹配触发的类型识别错误

内容的提问来源于stack exchange，提问作者Vaclav Honzik