# StructureFacts
## 职责
StructureFacts 负责把 `CFG + GraphFacts + Dataflow` 上的图与数据流事实翻译成源码恢复候选。
这一层只产出候选、边界与约束，不直接做最终 HIR 语法决策。
## 入口与模块
- `src/structure/mod.rs`
- `analyze_structure`
- `src/structure/common.rs`
- `src/structure/analyze.rs`
- `src/structure/helpers.rs`
- `src/structure/phi_facts.rs`
- `src/structure/branches.rs`
- `src/structure/branch_values.rs`
- `src/structure/loops.rs`
- `src/structure/goto.rs`
- `src/structure/regions.rs`
- `src/structure/scope.rs`
- `src/structure/short_circuit/`
## 应消费的前层事实
StructureFacts 应消费：
- `LoweredProto`
- `Cfg`
- `GraphFacts`
- `DataflowFacts`
StructureFacts 不应回退去做：
- parser / transformer 协议解码
- HIR 级语法选择
- AST 级糖化
## 应优先复用的共享设施
### 共享 query / cache
`src/structure/helpers.rs` 是结构层的共享 query/cache 入口。
涉及下面这些内容时，应优先补在这里：
- region entry / exit edge
- region reducible 判定
- branch region block 收集
- forward region 扫描
- region predecessor 收集
### phi 翻译
`src/structure/phi_facts.rs` 是把 `phi / def / incoming` 翻译成结构候选的正式入口。
下面这类逻辑不应再散落到 `loops`、`branch_values`、`short_circuit` 各处：
- `phi_candidates_in_block + filter_map`
- incoming 分类
- merge arm def 提取
- generic phi fallback 分类
### 短路子模块
`src/structure/short_circuit/` 已按关注点拆开：
- `branch_exit.rs`
- `value_merge.rs`
- `shared.rs`
短路条件出口识别与值合流提取应继续在这里收口，而不是跑到 HIR 再解释一遍 DAG。
## 正式产物
StructureFacts 对外公开的核心类型在 `src/structure/common.rs`：
- `StructureFacts`
- `BranchCandidate`
- `BranchRegionFact`
- `BranchValueMergeCandidate`
- `LoopCandidate`
- `LoopSourceBindings`
- `LoopValueMerge`
- `LoopExitValueMergeCandidate`
- `ShortCircuitCandidate`
- `GotoRequirement`
- `RegionFact`
- `ScopeCandidate`
- `GenericPhiMaterialization`
## 维护规范
### 1. 结构证据应尽量前移
如果 HIR 需要顺着：
- `DefId -> block/instr`
- `phi_candidates`
- `phi.incoming`
- `entry_overrides / phi_overrides`
去重新分类某类结构证据，优先考虑把该证据补进 StructureFacts。
### 2. 候选与最终决策分开
StructureFacts 只回答：
- 这里像不像 branch / loop / short-circuit / goto / scope
- 这个 merge 两边分别是谁
- 哪些跳转必须保留
它不回答：
- HIR 应该选哪一种最终语法
- AST 应该输出哪种 sugar
例如 `loops.rs` 里的 `WhileLike` 识别，应该回答“header 这块是不是仍然属于 while 条件前缀”，
而不是要求 header 必须退化成一条裸 branch。像 `#values`、位运算、表访问这类
无副作用的条件前缀计算，应继续留在 StructureFacts 这一层判断成 while-like，
而不是把这些 shape 打回 HIR fallback 再让后层兜底。
### 3. 共享事实放 common，算法放子模块
- 跨多个结构 pass 共享的事实放 `common.rs`
- 算法与收集过程放 `branches/loops/...`
不要把“被多个模块引用的事实类型”继续挂在某个具体算法文件下面。
### 4. 结构层自己也应复用 CFG/Dataflow query
结构层不应再私养一份“小型 CFG API”或“小型 Dataflow API”。
如果需要：
- block reachability
- predecessor / successor 过滤
- phi use / def 元数据
应优先消费 `Cfg` 或 `DataflowFacts` 的正式 query。
## 向后提供的事实
StructureFacts 向 HIR 正式提供：
- branch / loop / short-circuit / goto / scope 候选
- branch value merge 与 loop value merge
- generic phi materialization
- 结构层已经确认好的 region / edge / merge facts
HIR 默认把这些视为“应优先消费”的结构证据。
## 维护检查清单
修改 StructureFacts 时，应至少检查：
1. 这个证据是不是已经在 CFG / GraphFacts / Dataflow 存在，只是没有共享 query。
2. 这个翻译逻辑是不是已经能放进 `phi_facts.rs` 或 `helpers.rs`。
3. 这个类型是不是属于共享事实，应放到 `common.rs`。
4. 这是不是最终语法决策；如果是，应放到 HIR。