unluac 1.2.1

# 调试实现 Code Map

> 本文只回答“调试能力在哪里实现、扩展时该改哪”。命令怎么用见 `docs/debug.md`。

## 总体流向

```text
CLI 参数
   -> DecompileOptions / DebugFilters
   -> output_plan 决定要不要 dump / timing / pass-dump
   -> 各层 debug.rs 负责把本层状态渲染成文本
   -> stderr 输出调试信息，stdout 保持正常结果
```

## 核心文件

| 位置 | 职责 |
| --- | --- |
| `src/decompile/options.rs` | 调试相关选项进入 `DecompileOptions` 的入口 |
| `src/decompile/output_plan.rs` | 把 CLI 请求整理成 stage dump、pass dump、timing 等执行计划 |
| `src/decompile/debug.rs` | stage dump 收集与统一调度 |
| `src/debug.rs` | `DebugFilters`、`ProtoDepth` 等跨层共享类型 |
| `src/debug/focus.rs` | `--proto` / `--proto-depth` 的共享聚焦算法 |
| `src/debug/colorize.rs` | ANSI 着色与终端输出辅助 |
| `src/timing.rs` | `--timing` 所需的阶段打点与汇总 |
| `src/hir/simplify.rs` | `--dump-pass` 的 before/after 快照调度 |

## 各层 dump 入口

| 层 | 文件 | 主要函数 |
| --- | --- | --- |
| parser | `src/parser/debug.rs` | `dump_parser` |
| transformer | `src/transformer/debug.rs` | `dump_lir` |
| cfg / graph-facts / 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` / `dump_proto_snapshot` |
| ast / readability | `src/ast/debug.rs` | `dump_ast` / `dump_readability` / `dump_ast_snapshot` |
| naming | `src/naming/debug.rs` | `dump_naming` |
| generate | `src/generate/debug.rs` | `dump_generate` |

## 共享语义

- `DebugFilters { proto, proto_depth }` 是所有分层 dump 的统一过滤接口。
- `compute_focus_plan` 把 proto 树映射成 “可见 / elided / 跳过” 三态，避免每层各写一套聚焦逻辑。
- AST / Readability 的 proto id 与 parser / HIR 对齐，保证同一个 `--proto N` 可以跨层比对。
- generate 层不做 proto 裁剪，因为裁剪后的 Lua 文本会变成非法语法。

## `--dump-pass` 代码路径

1. CLI 把 pass 名和过滤条件写入 `DecompileOptions`。
2. `src/decompile/output_plan.rs` 组装 `PassDumpConfig`。
3. `src/hir/simplify.rs` 在 pass 前后抓取快照，并只在实际变更时输出。
4. HIR 快照由 `src/hir/debug.rs` 渲染；AST readability 快照由 `src/ast/debug.rs` 渲染。

## 扩展调试设施时看这里

1. 新增 stage dump：先在对应层实现渲染函数，再接到 `src/decompile/debug.rs` 的统一调度。
2. 新增带 proto 概念的层：不要自写过滤规则，直接接入 `src/debug/focus.rs`。
3. 新增 pass-dump 能力：优先复用现有快照格式，不要另起一套输出协议。
4. 新增调试参数：入口放 `src/decompile/options.rs`，计划编排放 `src/decompile/output_plan.rs`。
5. 若只是调某层业务逻辑，不要把业务事实塞进 debug 层；debug 层只负责观测，不负责修复。

## 相关文档

- 使用手册：`docs/debug.md`
- 测试体系：`docs/design/11.test.md`
- 总体设计入口：`docs/design.md`