diff --git a/docs/development/current/main/design/control-tree.md b/docs/development/current/main/design/control-tree.md new file mode 100644 index 00000000..f3c7107a --- /dev/null +++ b/docs/development/current/main/design/control-tree.md @@ -0,0 +1,58 @@ +# ControlTree / StepTree(構造SSOT) + +Status: **SSOT(design / vocabulary)** +Scope: **AST の“構造”だけ**を表現し、JoinIR/MIR の値・PHI・ブロックを一切持たない。 + +目的: +- ループ/if の **ネスト構造**を SSOT として持ち、pattern/policy の増殖先を「構造」側へ寄せる。 +- LoopSkeleton(loop_canonicalizer の骨格)を壊さずに、“次の一般化”の受け皿を追加する。 + +## 基本方針(禁止事項) + +StepTree は「制御構造の形」だけを表す。 + +禁止(混ぜない): +- `ValueId` / `BlockId` / `PHI` / `JoinInst` / `MirInstruction` など、値やCFGの概念 +- backend 依存の最適化・型情報 +- “動くための lowering” ロジック(生成・変換) + +許可(持ってよいもの): +- AST の最小要約(条件の形 / 文の種類 / span など) +- Capability / Feature(例: has_loop, has_if, has_return などの分類) + +## 用語 + +### ControlTree +StepTree(後述)を含む、構造SSOTの総称。将来 “BlockTree / BoundaryTree” 等を追加しても、値は持たない。 + +### StepTree +AST を「構造ノード」に落とした木(または木+Block列)で、次のノード種別を持つ: + +- `Block`: 文の列(順序を保持) +- `If`: `cond` と then/else の `Block` +- `Loop`: `cond` と body の `Block` +- `Stmt`: 構造化していない文(Local/Assign/Return/Break/Continue/Expr などを tag 化) + +## Capability(段階投入のSSOT) + +StepTree は capability を“宣言”し、未対応は **Fail-Fast(dev-only / strict)** で止める。 + +想定する段階(例): +1. **if-only**(ネストifまで): Phase 110 P1 +2. loop-in-if / if-in-loop: Phase 111+(予定) +3. nested loop: capability guard のまま(別Phaseで解禁) + +## 位置づけ(LoopSkeleton との関係) + +- **LoopSkeleton**(`loop_canonicalizer`): loop 1個の骨格を正規化して、JoinIR に渡せる形へ整える。 +- **StepTree**(control_tree): 関数/ブロック全体の“構造”をSSOT化し、ネスト対応の入口を提供する。 + +両者は競合しない: +- LoopSkeleton は “loop単体の正規化” が責務 +- StepTree は “構造の観測と分類” が責務(値やCFGを持たない) + +## デバッグ出力(dev-only) + +- 既定では出さない(既定挙動不変)。 +- `NYASH_JOINIR_DEV=1` のときのみ StepTree をダンプする(prefix は `[trace:dev] control_tree/step_tree`)。 + diff --git a/docs/development/current/main/design/joinir-design-map.md b/docs/development/current/main/design/joinir-design-map.md index 2dcff02f..a631ea1a 100644 --- a/docs/development/current/main/design/joinir-design-map.md +++ b/docs/development/current/main/design/joinir-design-map.md @@ -37,6 +37,7 @@ Related: 改善の方向(将来): - policy Reject の "hint" を `error_tags` に集約して、修正方針を 1 行で出せるようにする(Phase 109 候補) +- 構造SSOT(LoopSkeleton + StepTree)へ寄せて、policy/step箱の増殖先を “構造” に集約する(Phase 110) ## Error Tags with Hints (Phase 109)