refactor(shader-lab): unify #define dispatch into Lexer (drop Preprocessor regex path)

[zhuxudong]

背景

#2974（"AST-first #define"）合入后，shader-lab 中 #define 的处理被分到了两处：

1. Preprocessor._parseMacroDefines（正则）：扫描源码，提取宏名字 + params + referenceName，填到 macroDefineList
2. Lexer._defineHasValue（peek）：在每个 #define 指令处决定走 AST 路径还是 legacy opaque 路径

两处看的是同一段源码，但用的是不同的分析机制：

	处 1（正则）	处 2（Lexer peek）
分析机制	RegExp	字符状态机
是否懂 /* */ 和 // 注释	不懂	懂
是否懂 \ 续行	不懂	懂
是否懂"# 必须在行首"（GLSL ES §3.4）	部分懂（^\s*#define）	不强校验

不一致的真实风险

两套独立分析机制对同一段源码的理解不完全一致，已经带来了潜在 bug：

例子 1：注释里的 #define 假阳性注册

/*
 * 文档:
 * #define MAX_LIGHTS 4
 */

• 正则匹配并把 MAX_LIGHTS 写进 macroDefineList
• Lexer 跳过整个注释，从未看到 #define
• 后果：用户代码 int x = MAX_LIGHTS; 被 tokenize 成 MACRO_CALL，但展开时找不到值定义

例子 2：续行 \ 的 #define

#define LONG \
    a * b + c

• 正则 .*? 不跨行，value 抓不到
• Lexer 正确识别续行
• 后果：macroDefineList 里的 referenceName 提取失败

例子 3：注释 peek 盲点

#define HP /* comment */ highp

• Lexer 的 _defineHasValue peek 见到 / 不是 alpha → 直接返回 true → 进 AST 路径 → parse 失败
• feat(shader-lab): make #define values first-class AST nodes #2974 已经在 Lexer 一侧加了回归测试（commit 5b7f8ae37），但正则那一侧没改——典型的"两处不一致只修了一处"

例子 4：type-alias 误进 AST（详见 https://github.com/galacean/engine/pull/2974#issuecomment-4325529482）

• _expressionLeaderKeywords 白名单包含全部构造器类型 keyword
• #define FxaaTex sampler2D 被错误送进 AST → parse 失败
• FXAA portability 宏全部命中

这些 bug 都可以单独打补丁解决，但根本原因是两套分析机制必然 drift——每加一个新分流策略、每升级一次 GLSL 版本，两边都要同步审视。

建议方案

把 #define 处理完全收到 Lexer，删掉 Preprocessor 的 #define 正则。 Preprocessor 只保留 #include 处理。

实现思路

Lexer 内部做"两遍扫描"：

第 1 遍（轻量 forward-scan）：

• 快速跑一遍源码，只为找所有 #define <name> 的名字
• 不发 token，不分类，不解析 value
• 复用 Lexer 既有的注释/续行/字符串跳过机制 → 自动避开例子 1/2 的 bug
• 产出：macroDefineList 的名字索引

第 2 遍（正式 lex）：

• 知道所有宏名字后开始正式 tokenize
• 在每个 #define 指令处做 AST/legacy 分类
• 走到使用点 FOO，按 macroDefineList 决定 tokenize 成 MACRO_CALL 还是 ID

收益

1. 单一 source-of-truth：Lexer 全权处理 macro，没有任何 drift 可能
2. 注释、续行、字符串字面量等所有 source-level 细节天然一致——因为只有一套扫描机制
3. 现有的几个 bug 自动消失：
   • 例子 1：注释里假阳性 → Lexer 本来就跳注释
   • 例子 2：续行 → Lexer 本来就懂
   • 例子 3：peek 盲点 → 不需要 peek 了，第 1 遍就分类完了
   • 例子 4：type-alias 误进 AST → 第 1 遍可以做精确分类（peek 整条 replacement list）
4. Preprocessor scope 收敛：从"manage macros + manage includes"降到只 manage includes，单一职责

代价

1. 2x 扫描成本：PBR 这种 ~5000 行 shader 实测多 ~1ms（量级可接受，且只在源码编译阶段，runtime 不影响）
2. Lexer 内部状态机更复杂：要支持 "scan-only mode"（第 1 遍只找名字不发 token）
3. 改动量较大：~200-300 行 + 全面回归测试

迁移路径

1. 当前：先按 feat(shader-lab): make #define values first-class AST nodes #2974 那边 review 给的最小补丁（type-alias peek 加 6 行）打补丁，不阻塞 PR 合入
2. 下个迭代：单独立项做本 issue 的 refactor
3. 完工后：Preprocessor.ts 只剩 #include 处理，回到 PR 之前的简洁度

不能解决的（已知 scope）

C 只解决"分流不一致"这一类问题。以下不在 scope：

• Nit: 表达式宏 value 在 parse 时 semantic-analyze 引发假警告（Parser semantic action 时机问题）
• Nit: hasAstValue = .some(...) 在 #ifdef 分支 AST/legacy 混合时语义错（MacroCallSymbol 查询逻辑问题）
• 不支持 __LINE__ / __FILE__ / __VERSION__ 预定义宏（独立 feature）

这些需要独立 fix。

关联

• PR feat(shader-lab): make #define values first-class AST nodes #2974 (feat: shader-lab 宏 AST 化)
• 评论中已描述 type-alias 这个具体 bug 的 minimal fix：feat(shader-lab): make #define values first-class AST nodes #2974 (comment)

[GuoLei1990]

已实现，commit 3668d8c5a（在 PR #2974 内）。

实施要点

按 Issue 提的方案 — #define 完全收到 Lexer，删掉 Preprocessor 的正则路径。但没用 Issue 提的"双 pass"，而是单 pass 流式注册：

• _scanDirectives 看到 #define 时记下 directive 起始 offset
• AST 路径在 _emitMacroDefineEnd 时调 _registerMacroDefine
• Legacy 路径在 _scanDirectives 内 _scanUtilBreakLine 后调同一个 _registerMacroDefine
• 两条路径都从 _source 切出 directive 文本，用同一个 regex 解析（_defineDirectiveReg），同一个 push helper（MacroDefineInfo + 去重）

为什么单 pass 而不是双 pass：GLSL 实际行为是 #define 必须在使用前（C99 §6.10.3 规定，dev/2.0 baseline 实测也不支持 forward reference）。所以流式扫到 #define 立即注册，之后的 use 就能正确识别 MACRO_CALL —— 不需要 pre-scan 一遍找名字。

收益（同 session 4 rounds × 50 samples，release build）

维度	改动前	改动后
Preprocessor.ts	227 行	92 行（−135）
Lexer.ts	781 行	820 行（+39）
合计	1008 行	912 行（−96）
PBR 编译 (med-of-med)	40.60ms	38.50ms（−5.2%）
waterfull (med-of-med)	7.30ms	7.05ms（−3.4%）
macro-pre (med-of-med)	1.10ms	1.00ms（−9.1%）

性能略快是因为 baseline 的 _macroRegex 是全文 regex 扫描；现在每条 directive 只在自己几十字节的 slice 上跑一次小 regex，总成本更低。

Issue 列的 4 个例子全部解决

例子	dev/2.0 baseline	之前 PR HEAD	现在
例 1：/* #define MAX_LIGHTS 4 */ 假阳性	❌（实测 fail）	❌（同上）	✅
例 2：#define LONG \\\n a*b 续行	❌	❌	✅
例 3：#define HP /* c */ highp peek 盲点	❌	✅（commit 5b7f8ae patch）	✅（统一架构后免疫）
例 4：#define FxaaTex sampler2D type-alias	❌	✅（commit 992956f patch）	✅（同上）

例 1、2 之前从未被覆盖（dev/2.0 baseline 也是 fail 的，但因为生产 shader 没用过这两种模式没暴露），现在实测通过。

测试覆盖

新增两个 regression：

• tests/src/shader-lab/shaders/define-in-comment-repro.shader
• tests/src/shader-lab/shaders/define-line-continuation-repro.shader

29 + 2 = 31/31 shader-lab 测试通过。

反思

Issue 给的"双 pass"方案我也实现并实测过 — drift 消除是对的，但比 baseline 慢 ~1ms（多一遍全文扫描）。改成"流式单 pass"消除 drift 同时还略快。

第一性原理上：drift 的 root cause 不是"扫描遍数不够"，而是"两个独立分析者解读同一段源码"。把分析者从 2 个砍到 1 个就行 — 不一定要 2 遍扫描。

你提到的不在 scope 内的几项

• Nit: 表达式宏 value 在 parse 时 semantic-analyze 引发假警告（Parser semantic action 时机问题）
• Nit: hasAstValue = .some(...) 在 #ifdef 分支 AST/legacy 混合时语义错
• 不支持 __LINE__ / __FILE__ / __VERSION__ 预定义宏

这些确认仍然存在，是独立的 follow-up。本 PR 不动。

可以 close 这个 Issue 了吗？还是等 PR 合并后由 close 关键字自动关？

[GuoLei1990]

追加：之前列为 follow-up 的 hasAstValue = .some(...) 这条 本 PR 已修（commit e31c24544）。

修复内容

把 macroDefineList 改成分支感知的：

• BranchConstraint / BranchSignature 类型在 common/BaseToken.ts
• Lexer 维护 _branchStack，跨 #ifdef/#ifndef/#else/#endif
• 每个 token 的 branch 字段携带签名快照
• 每条 MacroDefineInfo.branch 记录注册位置的签名
• Lexer.sameBranch / Lexer.isVisibleFrom 静态 helper
• MacroCallSymbol.semanticAnalyze 用调用点签名过滤 defList，再从过滤后的 entry 算 hasAstValue / isFunctionLikeMacro / referenceSymbolNames
• MacroDefine.semanticAnalyze 的 upgrade 也按签名匹配，AST valueExpression 落到对的分支 entry

解决的具体问题

#ifdef USE_AST_FORM
  #define LIGHT_INPUT v.v_normal      // AST 形态
#else
  #define LIGHT_INPUT u_globalLightDir // legacy 形态
#endif

之前：hasAstValue = .some(valueAst != null) = true（AST entry 触发），call site 类型推导跳过 → 停留 TypeAny → 影响 builtin 重载、varying flatten 等下游决策 → release 模式生成错的 GLSL。

现在：调用点签名过滤后只剩当前激活分支的 entry，hasAstValue 和 referenceSymbolNames 都是分支精确的。

关键澄清：原生 GLSL 编译器对这种写法是接受的（preprocessor 文本替换是按激活分支展开的，每个分支单独看都是合法 GLSL）。所以这是 ShaderLab 的 bug 而不是用户 bug —— 输入合法的话 runtime 必须正确处理。

测试

新增 3 个 regression：

• define-mixed-form-repro.shader（AST/legacy 跨分支）
• define-branch-scoped-ast.shader（同 AST 形态、不同 member）
• define-nested-ifdef.shader（嵌套 #ifdef 组合签名）

176/176 shader-lab 测试全过（含 PrecompileBenchmark）。

已知 limitation

#if expr（一般表达式）未建模，分支栈不变，等价于注册和调用都在外层签名 → 互相可见 → 退化为 every 启发式（多形态时 fallback legacy 推导）。保守正确：永远不会错误排除可见 entry，只可能让某些场景退化为 pre-fix 行为。

剩余 follow-up

Issue 列的另外两项仍然不在本 PR scope：

• 表达式宏 value 在 parse 时 semantic-analyze 引发假警告
• 不支持 __LINE__ / __FILE__ / __VERSION__