refactor(shader): split parser/compiler/analyzer + structured diagnostics (RFC #3017)

[zhuxudong]

设计文档：RFC #3017（完整诊断规则目录、判据、实施步骤见该 issue）

背景与目标

dev/2.0 的 shader 诊断与运行时编译耦合在一包，靠 #if _VERBOSE 门控：release 产物零诊断、错误无行列定位、同一错误多次上报、外部无法消费。

本 PR 把 shader 体系拆为三包并引入结构化诊断：

• 解耦：诊断与 codegen 物理分离，依赖结构上不可能 drift；
• 结构化：可定位、release 可见、每错一遍、IDE / CI / LLM 可直接消费。

架构

flowchart LR
    SRC["ShaderLab 源码"] --> P["📦 shader-parser<br/>中性 typed-AST + 语义线索<br/>（唯一来源）"]
    P --> C["⚙️ shader-compiler<br/>codegen → GLSL ES"]
    P --> A["🔍 shader-analyzer<br/>ShaderValidator 校验 + 收集线索"]
    C --> OUT["IShaderProgramSource"]
    A --> DIAG["Diagnostic[]"]
    classDef base fill:#fff9c4,stroke:#f57f17
    classDef comp fill:#d4edda,stroke:#28a745
    classDef ana fill:#e3f2fd,stroke:#1976d2
    class P base
    class C,OUT comp
    class A,DIAG ana

Loading

shader-compiler 与 shader-analyzer 互不依赖，是 parser 之上两个平等消费者。类型/控制流校验抽成独立的 ShaderValidator pass（走 typed-AST），类型语义收口到 TypeSystem；与解析序耦合的校验（重载 / 声明序 / const 求值）+ 管线 IO + RenderState 仍在 parser 内联打标。整体对齐 Naga「中性源 + 独立 Validator + 多 backend」的分离方向（建模型 / 校验 / 发射）；模型是带注解的 typed-AST，非完全 lower 的 IR。

核心机制：校验独立于 codegen

	dev/2.0	本 PR
判定	散落 reportError + #if _VERBOSE	类型/控制流校验由 ShaderValidator 走 typed-AST 现算；解析序耦合项 parser 内联打标（error-as-clue）
analyzer	—	ShaderValidator 走 typed-AST 做类型/控制流校验 + 收集 parser 线索 → Diagnostic[]
codegen	与诊断耦合	纯生成、零诊断；走同一棵 typed-AST

对外 API

入口	形态	场景
analyzer.analyze(src)	返回结构化 Diagnostic[]	编辑器 / CI / LLM
WebGLEngine.create({ shaderCompiler, shaderAnalyzer })	注入即诊断 → Logger	dev / 运行时校验
formatDiagnostic(d)	渲染带行号源码 + caret 的文本块	运行时 Logger 与编辑器/CI 同款输出

interface Diagnostic {
  severity: DiagnosticSeverity;   // error | warning（枚举）
  code: DiagnosticType;           // 语义码（glslang 风格，非数字码）
  message: string;                // 'token' : 说明
  range: { start; end };          // 行 / 列 / offset
  relatedSource?: string;         // 出错 pass 源码，供上下文呈现
}

诊断能力

43 个 DiagnosticType，逐条对 Naga valid/ 源码核过粒度（过度拆分已合并、ShaderLab/GLSL 专属项标注依据）；完整目录 + 正/误示例见 RFC #3017 §3。按实体分类：

类	覆盖
结构	入口绑定、入口指向、RenderState 合法性
类型 / 表达式	swizzle、struct 成员、构造函数、下标、除零、移位、运算操作数类型
符号 / 作用域	使用前声明、重定义、函数解析、实参匹配
函数 / 控制流	void/return、if 条件、break/continue、禁递归
管线 IO	入口签名、IO 可共享类型、struct 角色、整型 varying flat、vertex 输出位置
常量 / 资源	数组大小常量、const 初始化、采样目标

优势

• 物理解耦：依赖结构强制 single source of truth；release 可见诊断；取消 verbose 变体（8 → 4 产物）。
• 平台无关：类型/控制流诊断建立在 parser 的中性 typed 线索上，与具体后端无关；平台分叉构造（如 array-of-array）归 backend 生成时报。
• 零运行时成本：不注入 analyzer 即纯编译；shader codegen 输出保持不变。
• 可消费：结构化 Diagnostic —— 编辑器画波浪线、CI 出 file:line:col [Code] msg、LLM 拿去自动修复。

测试

• 每条诊断规则配 ABTest：正确版（应通过、零该类型诊断）+ 错误版（精确命中 DiagnosticType + 位置）。
• codegen 回归保护：基于 dev/2.0，IShaderProgramSource 字节对等（precompile 守护）。
• 覆盖率门：每个 DiagnosticType 必有触发用例，缺测即 fail。
• 本地与 CI：npm run build（b:module + b:types，tsc 全量类型检查）后 npm run test。