hakorune/CURRENT_TASK.md

Current Task — Phase Freeze (Macro Complete)

Updated: 2025‑09‑19 (night)

Status

マクロ基盤は完成・既定ONで安定（AST JSON v0、PyVMサンドボックス、strict/timeout、dump/golden、JSONL trace、プロファイル）。ここで機能を一旦凍結し、自己ホスト/実アプリ開発に注力して磨き込むフェーズに入る。

Delivered (Macro Platform)

• Built‑in macros (Rust): derive(Equals/ToString) minimal, public‑only + hygiene.
• User macros (Nyash/PyVM): Proxy → child process (NYASH_VM_USE_PY=1, plugins disabled, timeout). Strict=1 by default (fail on error/timeout; strict=0 → identity fallback).
• Dump/Trace: --dump-expanded-ast-json, NYASH_MACRO_TRACE_JSONL=….
• Runner routes:
  • Child mode (PoC): --macro-expand-child <file> (stdin JSON → stdout JSON).
  • PyVM runner (recommended): dynamic runner includes macro and calls MacroBoxSpec.expand(json) once per pass.
• Templates & Tests:
  • Templates: echo_macro (identity), upper_string_macro ("UPPER:" prefix → uppercase suffix).
  • Array/Map examples: array_prepend_zero_macro (prepend 0 to any Array), map_insert_tag_macro (insert {"__macro":"on"} into any Map).
  • Goldens (user macros): identity, upper_string, array_prepend_zero, array_empty, array_nested, array_mixed, map_insert_tag, map_multi, map_esc。
  • Negative smokes: user macro timeout (strict fail), invalid JSON strict fail, invalid JSON non‑strict → identity fallback。
• Capabilities (実効化): マクロNyashのAST静的走査で IO/NET をゲート（strict=fail / 非厳格は未登録=identity）。
• MacroCtx (MVP): gensym/report/getEnv の最小スキャフォールドを提供。
• Self‑host 前展開（PyVM限定）: NYASH_USE_NY_COMPILER=1 + NYASH_MACRO_SELFHOST_PRE_EXPAND=1|auto → AST前展開→MIR→PyVM 実行。
• CI: min‑gate に macro‑golden ジョブと selfhost‑preexpand‑smoke を追加。
• Docs: user‑macros.md / ast‑json‑v0.md / capabilities.md (io/net/env).

Delivered (LoopForm – MVP‑1 Safe)

• LoopNormalize macro (Nyash runner) scaffolded and active.
• Canonicalize Loop node key order (condition → body).
• Safe body reorder: move Assignment nodes to tail only when original order already has non‑assign → assign; otherwise keep order (no semantic change).
• JsonBuilder utility added for AST JSON v0 fragments (string‑based minimal helpers).
• Golden comparison made key‑order insensitive (JSON normalized via python) for macro tests.
• LLVM pre‑expand run verified on loop_simple (PyVM → MIR → LLVM).

Focus — Freeze & Polish

1. 実アプリの作成と運用（マクロ前展開/PyVM/LLVMラインの動作確認）
2. バグ修正・ドキュメント整備・スモーク/ゴールデン/CI強化（仕様不変）
3. 自己ホスト前展開の観測強化（ログ/スモーク）と安定運用
4. ランタイムcapabilities（io/net/env）のPyVM側実効化は必要になった時点で最小修正

Next Milestones

• DONE: Self‑host 前展開 既定化（auto）
  • 変更多: NYASH_MACRO_SELFHOST_PRE_EXPAND 未設定時に、マクロ有効かつ NYASH_VM_USE_PY=1 で自動ON（安全策付き）。
  • 追加: --macro-preexpand-auto フラグ。
• DONE: 環境変数の整理（CLI中心の導線）
  • 追加: --macro-top-level-allow, --macro-profile {dev|ci-fast|strict}（非破壊の簡易マッピング）。
• DONE: Top‑level allow 既定値を OFF に変更 + AST検出へ統一（ファイル名ヒューリスティック撤廃）。
• DONE: MacroCtx 契約 PoC — ランナーが expand(json, ctx) を優先、失敗時に expand(json) へフォールバック。

Next (short)

• LoopForm MVP‑2: while → carrier normalization (no break/continue, up to 2 vars)
  • Extract updated vars (e.g., i, sum) and normalize body so updates are tail; emit carrier‑like structure with existing AST forms (Local/If/Loop/Assignment) while preserving semantics.
  • Add goldens (two‑vars) + selfhost‑preexpand smokes; verify PyVM/LLVM parity.
• LoopForm MVP‑3: break/continue minimal handling (single‑level)
• for/foreach pre‑desugaring → LoopForm normalization (limited)
• LLVM IR hygiene for LoopForm cases — PHI at block head, no empty PHIs (smoke)
• Docs: enrich docs/guides/loopform.md with carrier examples and JSON builder snippets.
• If/Match normalization pass: canonical If join with single PHI group and Match→If‑chain (scrutinee once, guard fused), expression results via join var.
• ScopeBox (compile-time meta): design + docs; no-op macro scaffold; MIR hint names (no-op) and plan for zero-cost stripping.
• ControlFlowBuilder/PatternBuilder docs and scaffolding: author APIs for If/Match normalization and pattern conditions; migrate macros to use them.

Action Items (next 48h)

• Enable sugar by default (array/map literals)
• Golden normalizer (key‑order insensitive) for macro tests
• Loop simple/two‑vars goldens with normalization
• LoopForm MVP‑2: two‑vars carrier safe normalization + tests/smokes
• LLVM PHI hygiene smoke on LoopForm cases
• ScopeBox docs + macro scaffold (no-op) + MIR hint type sketch
• ControlFlowBuilder/PatternBuilder docs（本commitで追加）→ スキャフォールド実装 → If/Matchマクロ置換の最初の1本

Phase‑16 Outlook

• MacroCtx (gensym/report/getEnv) and capabilities mapped to nyash.toml.
• Attribute‑style (@derive/@lint) macros consolidated via MacroBox.
• span/source map for better diagnostics.

Final Goal (Replacement Strategy)

• Ultimately replace both the Rust front (beyond minimal bootstrap/backends) and PyVM with Nyash implementations—fully self‑hosted pipeline.
• Steps: front macros → resolver helpers → MIR lowering helpers → Nyash VM → phase out PyVM → reduce Rust to boot/backends only.

Quick Reference

• Profiles: --profile {lite|dev|ci|strict}（dev相当が既定運用）
• Register macros: NYASH_MACRO_PATHS=apps/macros/examples/echo_macro.nyash
• Strict/Timeout: NYASH_MACRO_STRICT=1（既定）, NYASH_NY_COMPILER_TIMEOUT_MS=2000
• Dump expanded AST: nyash --dump-expanded-ast-json <file.nyash>
• Self‑host 前展開: 既定auto（PyVM限定）
• Docs: docs/guides/user-macros.md, docs/guides/macro-profiles.md, docs/reference/ir/ast-json-v0.md, docs/reference/macro/capabilities.md