hakorune/docs/guides/source-extensions.md

Source Extensions Policy — .hako と .nyash の等価性（Phase 20.47）

Intent

• 拡張子が異なるだけで、言語は 1 つ（.hako / .nyash は等価）。
• using は言語中立な“テキスト・プレリュード統合”に一本化してからパーサへ渡す。

Execution Mapping (unified)

• .hako / .nyash → using のテキスト統合（merge_prelude_text）→ Nyash Parser → MIR → VM 実行。
• verify (MIR v1) → hv1 早期経路（NYASH_VERIFY_JSON + HAKO_VERIFY_V1_FORCE_HAKOVM=1）。

Resolver/Include/Normalize

• Using: 常にテキスト統合。AST プレリュード統合は任意（プロファイルによる）。
• 拡張子の扱い: .hako を優先、.nyash を次点（両方探索）。
• using.paths 既定: apps, lib, ., lang/src（nyash.toml/hakorune.toml）。
• Include: 言語としては非推奨（quick は ERROR）。必要時のみ preinclude スクリプトを使用。
• Normalize（inline/dev）: CRLF→LF、冗長 ; } の最小削除、先頭 local の互換補助 等。

Fail‑Fast Guards / Profiles

• Fail‑Fast: 既定OFF。HAKO_FAIL_FAST_ON_HAKO_IN_NYASH_VM=1 のときのみ Hako 風ソースを Nyash VM 経路で拒否（診断用）。
• Profiles:
  • dev/ci: using 有効。AST マージ 既定ON。相対パス using は許容。
  • prod: using は名前解決のみ（alias/modules）。相対パス using は ERROR。NYASH_USING_PROFILE=prod。
• Extern（Hako provider）: HAKO_V1_EXTERN_PROVIDER=1（開発時ガード）、HAKO_V1_EXTERN_PROVIDER_C_ABI=1（任意タグ）。

Why two extensions?

• 言語は 1 つ。拡張子が異なるだけ（歴史的理由）。解決は等価で、.hako を優先・.nyash を次点で探索する。

Migration Plan

• 本ドキュメントの時点で統一完了（Phase 20.47）。以降は代表拡張/ハードニングを Phase 21.x で進める。

Best Practices (now)

• パス using ではなく、nyash.toml/hakorune.toml の [modules]/[using.paths]/[aliases]/workspace を活用。
• ソース内 include は避ける（必要時は preinclude を使ってテキスト展開）。
• verify は JSON を env（NYASH_VERIFY_JSON）経由で渡し、末尾数値を rc として評価。

Quick Example (alias using)

using selfhost.vm.entry as MiniVmEntryBox
static box Main { method main(args) {
  // alias 解決の確認（静的メソッド呼び出し）
  local _s = MiniVmEntryBox.int_to_str(0)
  return 0
} }

実行（quick プロファイル、dev 想定）: bash tools/smokes/v2/run.sh --profile quick --filter 'phase2047/using_alias_selfhost_vm_entry_canary_vm.sh'

Nested Prelude Example

using selfhost.vm.hakorune-vm.json_v1_reader as JsonV1ReaderBox
static box Main { method main(args) {
  local seg = JsonV1ReaderBox.get_block0_instructions('{"schema_version":"1.0","functions":[{"name":"main","blocks":[{"id":0,"instructions":[]}]}]}')
  return seg == "" ? 0 : 1
} }

実行: bash tools/smokes/v2/run.sh --profile quick --filter 'phase2047/using_alias_nested_prelude_json_v1_reader_canary_vm.sh'

Notes (this pass)

• Stage‑B emit の安定化: inline コンパイラ無効化と失敗時 tail 出力で原因を可視化。
• hv1 inline の拡張: const/compare/branch/jump/phi/extern（最小）を実装。