Prodivix

主题

Code 诊断 ​

Code 诊断用于描述用户在 Prodivix 中编写、挂载、引用和执行的代码片段问题，包括 TypeScript、JavaScript、CSS、SCSS、GLSL、WGSL、表达式片段，以及这些代码依赖的作者态共享符号环境。

Code 诊断使用 COD-xxxx 命名空间。它不是 MFE 自身应用崩溃码，也不是目标项目最终构建码，而是作者态代码环境给用户的稳定产品错误码。

什么时候会出现 Code 诊断 ​

常见场景包括：

  1. 代码片段语法错误、语言模式不支持或片段形状不符合宿主要求。
  2. 变量、import、route param、graph output 或外部库导出无法解析。
  3. TypeScript 类型、泛型、函数参数或宿主字段类型不兼容。
  4. Blueprint 事件、Mounted CSS、NodeGraph 端口或 Animation track 的宿主契约不满足。
  5. 用户代码在预览、worker、sandbox 或表达式求值中抛错、超时或被权限拒绝。
  6. TypeScript、CSS、SCSS、shader 或 source map 转译编译链路失败。
  7. 上游语言服务返回了错误，但证据不足，暂时无法映射到更具体的 COD 码。

这些问题应该落到 Code Editor inline diagnostic、Inspector 字段、NodeGraph 端口、Animation track、Preview 错误提示或 Issues 面板中。只要能定位到代码片段，优先保留 sourceSpan。

与其他错误码的区别 ​

问题类型使用命名空间
PIR graph、ValueRef、materializePIR-xxxx
Inspector 写入、拖拽、选择、画布命令EDT-xxxx
NodeGraph 结构、端口连线、执行计划NGR-xxxx
Animation timeline、track、keyframeANI-xxxx
外部库加载、扫描、注册ELIB-xxxx
目标项目代码生成和导出GEN-xxxx
用户体验质量问题UX-xxxx
用户代码和作者态代码环境COD-xxxx

例如 CSS parser 报错使用 COD-1001；同一段 CSS 如果可以解析但导致文本对比度不足，则另行产生 UX-1001。外部库本体加载失败使用 ELIB-xxxx；外部库已经可运行但缺少类型信息时使用 COD-2014。

上游错误码如何呈现 ​

TypeScript、ESLint、CSS parser、Sass/PostCSS、GLSL 或 WGSL compiler 的错误码不作为 MFE 主错误码展示。用户界面应该展示稳定的 MFE 主码，例如 COD-2003 类型不兼容，并在详情中展示上游来源和原始码，例如 TypeScript TS2322。

推荐结构：

ts
type UpstreamDiagnostic = {
  source: 'typescript' | 'eslint' | 'css' | 'scss' | 'glsl' | 'wgsl';
  code?: string | number;
  severity?: 'info' | 'warning' | 'error';
  message: string;
  sourceSpan?: SourceSpan;
  docsUrl?: string;
};

示例：

json
{
  "code": "COD-2003",
  "domain": "code",
  "severity": "warning",
  "message": "返回值类型不满足宿主字段的类型约束。",
  "sourceSpan": {
    "artifactId": "code_artifact_01",
    "startLine": 4,
    "startColumn": 10,
    "endLine": 4,
    "endColumn": 24
  },
  "targetRef": {
    "kind": "inspector-field",
    "fieldPath": "props.value"
  },
  "meta": {
    "upstream": [
      {
        "source": "typescript",
        "code": "TS2322",
        "severity": "error",
        "message": "Type 'string' is not assignable to type 'number'."
      }
    ]
  }
}

展示层建议：

  1. 列表主标题使用 COD-xxxx 和 MFE 诊断名称。
  2. 详情区展示上游来源、原始码、原始 message 和文档链接。
  3. 筛选和聚合优先按 COD-xxxx，再允许用户按上游来源过滤。
  4. 不要把多个上游错误直接暴露成多个产品主码，除非它们对应不同的 MFE 作者态语义。

常见映射 ​

上游来源上游示例MFE 主码
TypeScript parserTS1005COD-1001 代码解析失败
TypeScript typecheckTS2322、TS2345COD-2003 类型不兼容
TypeScript moduleTS2307COD-2002 import 无法解析
TypeScript genericTS2344COD-2015 泛型或类型参数不满足
ESLintno-undefCOD-2001 符号无法解析
自定义 lintreadonly context ruleCOD-3015 修改只读上下文
CSS parserdeclaration parse errorCOD-1001 代码解析失败
Mounted CSS ruleselector escapes scopeCOD-3011 selector 超出作用域
Sass/PostCSSmixin/import/variableCOD-5012 CSS/SCSS 预处理失败
GLSL/WGSL compilerentry、binding、type logCOD-5002 Shader 编译失败
Language workerinit or bridge failureCOD-5010 语言服务 worker 失败
Source mapbad generated mappingCOD-5011 Source map 映射失败

映射不是按字符串硬编码一一对应，而是按 MFE 作者态语义归类。同一个上游码在不同宿主下可能映射到不同 COD 码。

Code 诊断分段 ​

段位阶段说明
COD-10xxparse源码解析、语言模式、片段形状
COD-20xxsymbol符号解析、类型、import、共享环境 revision
COD-30xxbinding代码片段与 Blueprint/NodeGraph/Animation 契约
COD-40xxruntime用户代码运行时、sandbox、worker、执行权限
COD-50xxcompile转译、编译、shader compile、语言服务产物
COD-90xxenvironment代码环境未知异常

完整码表见 Code 错误码。

核心诊断列表 ​

当前核心 Code 诊断共 40 个：

Code名称
COD-1001代码解析失败
COD-1002不支持的语言模式
COD-1003代码片段为空或形状非法
COD-1004表达式片段不是单一表达式
COD-1005代码片段包含当前模式禁止的顶层语句
COD-1006源码编码或文本范围非法
COD-2001符号无法解析
COD-2002import 无法解析
COD-2003类型不兼容
COD-2004共享符号环境过期
COD-2010重命名符号存在冲突
COD-2011循环 import 或循环符号依赖
COD-2012符号解析结果不唯一
COD-2013引用了当前作用域不可见的符号
COD-2014外部库导出类型缺失或不可用
COD-2015泛型或类型参数无法满足约束
COD-2016类型推断超过复杂度上限
COD-3001代码片段绑定目标不存在
COD-3002代码片段返回值不满足宿主契约
COD-3003代码访问了当前上下文不可用的能力
COD-3010事件 handler 参数签名不匹配
COD-3011Mounted CSS selector 超出节点作用域
COD-3012代码片段 owner 类型不支持当前宿主
COD-3013生命周期 hook 与宿主阶段不匹配
COD-3014异步返回值不被宿主接受
COD-3015代码片段修改了只读上下文
COD-4001用户代码运行时抛错
COD-4010用户代码执行超时
COD-4011sandbox 权限拒绝
COD-4012用户代码产生非确定性副作用
COD-4013用户代码递归或循环超过限制
COD-4014用户代码返回不可序列化结果
COD-5001转译失败
COD-5002Shader 编译失败
COD-5010语言服务 worker 初始化失败
COD-5011Source map 生成或映射失败
COD-5012CSS/SCSS 预处理失败
COD-5013目标运行模式不支持当前语言特性
COD-9001代码环境未知异常
COD-9002代码诊断证据不足

常用入口 ​

基于 MIT 许可证发布

Copyright © 2024-present Prodivix Team