# Debugging
## 职责
Debugging 文档描述各层 dump 与 timing 的维护入口。
调试系统的作用是：
- 让每一层都能独立观察自己的正式事实
- 让跨层排错有稳定锚点
- 让性能排查能直接定位到 stage / pass
## 共享设施
### 公共契约 (`src/debug.rs`)
定义所有层共享的调试类型：`DebugDetail`、`DebugColorMode`、`DebugFilters`、`format_display_set()`。
各层 debug.rs 只依赖这些契约类型，不反向依赖 `decompile` 模块。
### 着色引擎 (`src/debug/colorize.rs`)
独立子模块，负责将多行调试文本按 token 类别着色输出。
对外仅通过 `crate::debug::colorize_debug_text` 暴露，不污染主契约文件。
### Pipeline 调试调度 (`src/decompile/debug.rs`)
通过 `define_stage_dump!` 宏统一生成所有 `dump_*` 公共包装函数。
启用 `decompile-debug` 时调用底层模块的 dump 函数并包装为 `StageDebugOutput`；
禁用时统一返回 `DebugUnavailable`，让 wasm 产物不带渲染逻辑。
新增阶段时只需增加一行宏调用。
## 各层 dump 入口
### parser
- `src/parser/debug.rs`
- `dump_parser`
- dialect 专属 dump 在 `src/parser/dialect/*/debug.rs`
### transformer
- `src/transformer/debug.rs`
- `dump_lir`
### cfg / graph / dataflow
- `src/cfg/debug.rs`
- `dump_cfg`
- `dump_graph_facts`
- `dump_dataflow`
### structure
- `src/structure/debug.rs`
- `dump_structure`
### hir
- `src/hir/debug.rs`
- `dump_hir`
### ast / readability
- `src/ast/debug.rs`
- `dump_ast`
- `dump_readability`
### naming
- `src/naming/debug.rs`
- `dump_naming`
### generate
- `src/generate/debug.rs`
- `dump_generate`
## 维护规范
### 1. 每层 dump 只展示该层正式事实
例如：
- parser dump 只展示 raw
- transformer dump 只展示 low-IR 与 lowering map
- structure dump 只展示 structure facts
不要在某一层 dump 里重新计算下一层解释。
### 2. 跨层对照靠正式映射
跨层排错时，应优先使用：
- `Origin`
- `LoweringMap`
- `InstrRef / BlockRef / DefId / PhiId`
- function / proto 稳定索引
不要靠人工猜测“这大概是上一层哪一条”。
### 3. dump 优先稳定、紧凑、可过滤
新增 dump 字段时，优先考虑：
- 是否真能帮助定位问题
- 是否有稳定 id 可锚定
- 是否应放到 verbose 而不是默认输出
### 4. timing 只统计正式阶段
统一 timing 是维护入口的一部分。
它应覆盖：
- 总流水线
- 正式 stage
- 已显式建模的子阶段 / pass
不要制造假的子阶段名称来凑层级。
## 推荐排错顺序
1. 先看最早持有该事实的层的 dump。
2. 再看层间映射是否一致。
3. 最后才看消费者层是如何使用该事实的。
## 维护检查清单
修改某层时，应至少检查：
1. 对应 dump 是否仍能直接观察该层正式产物。
2. 新增共享事实是否需要出现在该层 dump 中。
3. 新增显式 pass / stage 是否需要接入 timing。
4. 是否已有稳定 id 与过滤器可定位新逻辑。