diff --git a/apps/lib/json_native/parser/parser.nyash b/apps/lib/json_native/parser/parser.nyash index 9588dbd5..04bd38db 100644 --- a/apps/lib/json_native/parser/parser.nyash +++ b/apps/lib/json_native/parser/parser.nyash @@ -349,7 +349,7 @@ box JsonParser { // ===== ユーティリティメソッド ===== - // 数値文字列を数値情報に変換（簡易版） + // 数値文字列を数値情報に変換（MVP） // 返り値: MapBox { kind:"int"|"float", value: } convert_number(number_str) { local out = new MapBox() @@ -358,8 +358,11 @@ box JsonParser { out.set("value", StringUtils.parse_integer(number_str)) return out } - // Float detection disabled in MVP pending StringUtils float API stabilization - if false { + // 浮動小数点: 小数点または指数表記を含むものは文字列のまま保持 + if number_str.indexOf != null { + // indexOfが提供されていない環境向けフォールバック + } + if StringUtils.contains(number_str, ".") or StringUtils.contains(number_str, "e") or StringUtils.contains(number_str, "E") { out.set("kind", "float") out.set("value", StringUtils.parse_float(number_str)) return out diff --git a/docs/CONTRIBUTING-MERGE.md b/docs/CONTRIBUTING-MERGE.md index 749e6102..d73dee88 100644 --- a/docs/CONTRIBUTING-MERGE.md +++ b/docs/CONTRIBUTING-MERGE.md @@ -1,33 +1,5 @@ -# Merge Strategy — selfhosting‑dev × Cranelift branches +# Moved: Merge Strategy — branches -目的 -- selfhosting‑dev（VM/JIT 自己ホスト）と Cranelift 専用ブランチ（AOT/JIT‑AOT）を並行開発しつつ、衝突と複雑な解消作業を最小化する。 +このドキュメントは移動しました。 +- 新しい場所: [development/engineering/merge-strategy.md](development/engineering/merge-strategy.md) -ブランチの役割 -- `selfhosting-dev`: Ny→MIR→MIR-Interp→VM/JIT の安定化、ツール/スモーク、ドキュメント整備。 -- `phase-15/self-host-aot-cranelift`（例）: Cranelift backend の実装・検証。 -- `develop`: 定期同期の受け皿。`main` はリリース用。 - -方針（設計） -- 境界の明確化: Cranelift 固有コード（例: `src/jit/*`, `src/jit/rt.rs` など）は専用ブランチで集中的に変更。selfhosting‑dev は Runner/Interpreter/VM の公共 API に限定。 -- Feature gate: 共有面に変更が必要な場合は `#[cfg(feature = "cranelift-jit")]` 等で分岐し、ABI/シグネチャ互換を保つ。 -- ドキュメント分離: `CURRENT_TASK.md` はインデックス化し、詳細は `docs/phase-15/*` へトピックごとに分離（本運用により md の大規模衝突を回避）。 - -方針（運用） -- 同期リズム: selfhosting‑dev → develop へ週1回まとめPR。Cranelift 側も同周期で develop へリベース/マージ。 -- 早期検知: 各PRで `rg` による衝突予兆チェック（ファイル/トークンベース）をテンプレに含める。 -- rerere: `git config rerere.enabled true` を推奨し、同種の衝突解消を再利用。 -- ラベル運用: `area:jit`, `area:vm`, `docs:phase-15`, `merge-risk:high` 等でレビュー優先度を明示。 - -ファイルオーナーシップ（推奨） -- Cranelift: `src/jit/**`, `src/jit/policy.rs`, `tools/*aot*`, `docs/phase-15/cranelift/**` -- Selfhost core: `src/interpreter/**`, `src/runner/**`, `dev/selfhosting/**`, `tools/smokes/v2/**` -- 共有/IR: `src/mir/**`, `src/parser/**` は変更時に両ブランチへ告知（PR説明で影響範囲を明記）。 - -実務Tips -- マージ用テンプレ（PR description） - - 目的 / 影響範囲 / 変更対象ファイル / 互換性 / リスクと回避策 / テスト項目 -- 衝突抑止の小技 - - md は章分割して別ファイルに参照化（本運用の通り） - - 大規模renameは単独PRで先行適用 - - 共有インターフェイスは薄いアダプタで橋渡し（実装詳細は各ブランチ内） diff --git a/docs/DEV_QUICKSTART.md b/docs/DEV_QUICKSTART.md index 465b1dbd..67c5121a 100644 --- a/docs/DEV_QUICKSTART.md +++ b/docs/DEV_QUICKSTART.md @@ -1,43 +1,5 @@ -# Developer Quickstart +# Moved: Developer Quickstart -This quickstart summarizes the most common build/run/test flows when working on Nyash. +このドキュメントは移動しました。 +- 新しい場所: [guides/build/dev-quickstart.md](guides/build/dev-quickstart.md) -See also -- Self‑hosting one‑pager: `docs/how-to/self-hosting.md` - -## Build -- VM/JIT (Cranelift): `cargo build --release --features cranelift-jit` -- LLVM AOT: `LLVM_SYS_180_PREFIX=$(llvm-config-18 --prefix) cargo build --release --features llvm` - -## Run -- Quick VM run: `./target/release/nyash --backend vm apps/APP/main.nyash` -- LLVM emit+link helper: `tools/build_llvm.sh apps/APP/main.nyash -o app` - -## Smokes -- End‑to‑end LLVM smokes: `./tools/llvm_smoke.sh release` - - Use env toggles like `NYASH_LLVM_VINVOKE_RET_SMOKE=1` - -## Syntax Sugar (Phase 12.7) -- Control via env: `NYASH_SYNTAX_SUGAR_LEVEL=none|basic|full` -- Or via `nyash.toml`: - ```toml - [syntax] - sugar_level = "none" # or "basic" / "full" - ``` - -## MIR Migration Notes -- Implementation currently enforces Core‑15 during migration with tests in place. -- Core‑13 is the final minimal kernel target. The final flip documentation is tracked under: - `docs/development/roadmap/mir/core-13/step-50/`. - -## Testing -- Rust unit tests: `cargo test` -- Targeted: e.g., tokenizer/sugar config `cargo test --lib sugar_basic_test -- --nocapture` - -## Acceptance Checklist (Feature Additions Pause) -- cargo check (workspace) passes -- Representative smokes are green: - - PyVM smokes: `tools/pyvm_stage2_smoke.sh` - - LLVM harness smokes: `tools/llvm_smoke.sh release` - - Macro goldens: `tools/ci_check_golden.sh` -- No spec changes (compat maintained); changes are minimal and local diff --git a/docs/DOCUMENTATION_REORGANIZATION_PLAN.md b/docs/DOCUMENTATION_REORGANIZATION_PLAN.md index 1aaf458b..4ee72b20 100644 --- a/docs/DOCUMENTATION_REORGANIZATION_PLAN.md +++ b/docs/DOCUMENTATION_REORGANIZATION_PLAN.md @@ -1,276 +1,5 @@ -# Nyash ドキュメント再編成計画 📚 +# Moved: Docs Reorganization Plan -## 📊 現状の分析結果 +このドキュメントは移動しました。 +- 新しい場所: [development/cleanup/docs-reorg/PLAN.md](development/cleanup/docs-reorg/PLAN.md) -### ファイル数統計 -- **総ファイル数**: 283個（.md: 211個, .txt: 72個） -- **archive/**: 113ファイル（40%） -- **予定/**: 111ファイル（39%） -- **説明書/**: 41ファイル（14%） -- **その他**: 18ファイル（7%） - -### 重複・散在ファイル -- **README系**: 18個（各ディレクトリに散在） -- **GETTING_STARTED**: 3バージョン存在 -- **Phase関連**: 42ファイル（主に予定/native-plan/issues/） -- **AI相談記録**: 41ファイル（複数箇所に散在） -- **ビルドログ**: 13ファイル（archive各所） - -## 🔍 現状の問題点 - -### 1. **構造の混乱** -- トップレベルに開発中/正式文書が混在 -- `説明書/` と直下に同じような内容が散在 -- `archive/` に無秩序に大量のファイル - -### 2. **重複と不明確な階層** -- `説明書/reference/` と `reference/` が併存 -- GETTING_STARTED.md が複数存在（通常版と2025版） -- MIR関連ドキュメントが複数箇所に分散 - -### 3. **AI相談記録の散在** -- gemini/chatgpt相談が archive/, トップ, design/decisions/ など複数箇所 -- ビルドログも同様に散在 - -### 4. **開発フェーズ管理の複雑さ** -- Phase関連ファイルが `予定/native-plan/issues/` に大量 -- 現在のタスクと将来計画が混在 - -## 📋 提案する新構造 - -``` -docs/ -├── README.md # ドキュメントマップ（どこに何があるか） -│ -├── 📖 reference/ # 正式な技術仕様（安定版） -│ ├── README.md -│ ├── language/ # 言語仕様 -│ │ ├── syntax.md # 構文リファレンス -│ │ ├── types.md # 型システム -│ │ ├── boxes.md # Box仕様 -│ │ └── delegation.md # デリゲーション仕様 -│ ├── architecture/ # アーキテクチャ -│ │ ├── overview.md # 全体設計 -│ │ ├── mir.md # MIR仕様 -│ │ ├── vm.md # VM仕様 -│ │ └── plugins.md # プラグインシステム -│ └── api/ # API仕様 -│ ├── builtin-boxes.md # ビルトインBox一覧 -│ └── stdlib.md # 標準ライブラリ -│ -├── 📚 guides/ # 利用者向けガイド -│ ├── README.md -│ ├── getting-started.md # はじめに（統一版） -│ ├── tutorials/ # チュートリアル -│ │ ├── hello-world.md -│ │ ├── basic-boxes.md -│ │ └── p2p-apps.md -│ ├── examples/ # サンプルコード -│ └── playground.md # プレイグラウンドガイド -│ -├── 🔧 development/ # 開発者向け（進行中） -│ ├── README.md -│ ├── current/ # 現在の作業 -│ │ ├── CURRENT_TASK.md -│ │ └── VM_CHANGES.md -│ ├── roadmap/ # 開発計画 -│ │ ├── phases/ # Phase別計画 -│ │ │ ├── phase-8/ -│ │ │ ├── phase-9/ -│ │ │ └── phase-10/ -│ │ └── native-plan/ # ネイティブビルド計画 -│ └── proposals/ # 提案・RFC -│ └── phase_9_78e.md -│ -├── 🗄️ archive/ # アーカイブ（古い/歴史的文書） -│ ├── README.md # アーカイブの説明 -│ ├── consultations/ # AI相談記録 -│ │ ├── gemini/ -│ │ ├── chatgpt/ -│ │ └── codex/ -│ ├── decisions/ # 過去の設計決定 -│ ├── build-logs/ # ビルドログ -│ └── old-versions/ # 古いドキュメント -│ -└── 🎨 assets/ # 画像・図表など - ├── diagrams/ - └── screenshots/ -``` - -## 🔄 移行計画 - -### Phase 1: 基本構造作成（優先度: 高） -1. 新しいディレクトリ構造を作成 -2. README.md でドキュメントマップ作成 -3. 現在進行中のファイルを `development/current/` へ移動 - -### Phase 2: リファレンス整理（優先度: 高） -1. `説明書/reference/` の内容を `reference/` に統合 -2. 重複ファイルの統合（GETTING_STARTED統一版作成） -3. MIR/VM関連ドキュメントを適切な場所に配置 - -### Phase 3: アーカイブ整理（優先度: 中） -1. AI相談記録を `archive/consultations/` に集約 -2. ビルドログを `archive/build-logs/` に集約 -3. 古いドキュメントを `archive/old-versions/` へ - -### Phase 4: 開発ドキュメント整理（優先度: 中） -1. Phase関連ファイルを番号順に整理 -2. 現在のタスクと将来計画を明確に分離 -3. native-plan を整理して見やすく - -## 💡 メリット - -1. **明確な分類**: 利用者向け/開発者向け/アーカイブが明確 -2. **検索性向上**: 必要な情報がどこにあるか分かりやすい -3. **メンテナンス性**: 新しいドキュメントの追加場所が明確 -4. **バージョン管理**: 現在の仕様と過去の記録が分離 - -## 🤔 検討事項 - -### 日本語ディレクトリ名の変換案 -現在の日本語ディレクトリを英語に統一： -- `説明書/` → `guides/` に内容を移動 -- `予定/` → `development/roadmap/` に内容を移動 -- 日本語ファイル名（.txt/.md）はそのまま維持（内容が日本語のため） - -**理由**: -- 国際的な開発者にもアクセスしやすい -- パス指定時のエンコーディング問題を回避 -- Git操作が簡単に - -### 既存リンクの対応 -- 多くの場所から参照されている可能性 -- → **対策**: 移行期間は旧パスにシンボリックリンクまたはREADME配置 - -### 自動生成ドキュメント -- MIRダンプやベンチマーク結果など -- → **提案**: `development/generated/` または `archive/generated/` に配置 - -## 📝 実装順序の提案 - -### Step 1: 基本構造作成スクリプト -```bash -#!/bin/bash -# create_new_structure.sh - -# 新構造の作成 -mkdir -p reference/{language,architecture,api} -mkdir -p guides/{tutorials,examples} -mkdir -p development/{current,roadmap/{phases/{phase-8,phase-9,phase-10},native-plan},proposals} -mkdir -p archive/{consultations/{gemini,chatgpt,codex},decisions,build-logs,old-versions} -mkdir -p assets/{diagrams,screenshots} - -# 各ディレクトリにREADME.mdを配置 -echo "# Reference Documentation" > reference/README.md -echo "# User Guides" > guides/README.md -echo "# Development Documentation" > development/README.md -echo "# Archive" > archive/README.md -``` - -### Step 2: 優先移動ファイルリスト -1. **現在の作業ファイル** - - `CURRENT_TASK.md` → `development/current/` - - `CURRENT_VM_CHANGES.md` → `development/current/` - - `phase_9_78e_summary.md` → `development/current/` - -2. **言語仕様** - - `LANGUAGE_REFERENCE_2025.md` → `reference/language/` - - `TECHNICAL_ARCHITECTURE_2025.md` → `reference/architecture/` - - `説明書/reference/` の内容 → `reference/` へ統合 - -3. **利用者ガイド** - - GETTING_STARTED系を統合 → `guides/getting-started.md` - - `説明書/guides/` → `guides/tutorials/` - -### Step 3: 自動整理スクリプト案 -```bash -#!/bin/bash -# reorganize_docs.sh - -# Phase関連ファイルの整理 -find 予定/native-plan/issues -name "phase_*.md" | while read f; do - phase=$(echo $f | grep -o 'phase_[0-9]\+' | head -1) - mkdir -p development/roadmap/phases/$phase - mv "$f" development/roadmap/phases/$phase/ -done - -# AI相談記録の集約 -find . -name "*gemini*.txt" -exec mv {} archive/consultations/gemini/ \; -find . -name "*chatgpt*.txt" -exec mv {} archive/consultations/chatgpt/ \; -find . -name "*consultation*.txt" -exec mv {} archive/consultations/ \; - -# ビルドログの集約 -find . -name "*build*.log" -o -name "*build*.txt" -exec mv {} archive/build-logs/ \; -``` - -## 🚀 実装提案 - -1. **まず `DOCUMENTATION_REORGANIZATION_PLAN.md` の承認** -2. **バックアップ作成** - ```bash - tar -czf docs_backup_$(date +%Y%m%d).tar.gz docs/ - ``` -3. **基本ディレクトリ構造の作成**（上記スクリプト） -4. **段階的移行**（優先度順） -5. **リンク切れチェック** -6. **最終確認とクリーンアップ** - -## 📋 具体的な移行マッピング（主要ファイル） - -### 現在のトップレベルファイル -``` -docs/ -├── CURRENT_TASK.md → development/current/ -├── CURRENT_VM_CHANGES.md → development/current/ -├── LANGUAGE_REFERENCE_2025.md → reference/language/ -├── TECHNICAL_ARCHITECTURE_2025.md → reference/architecture/ -├── Phase-9.75g-0-BID-FFI-*.md → development/roadmap/phases/phase-9/ -├── README.md → そのまま（インデックスとして） -├── execution-backends.md → reference/architecture/ -├── nyash_core_concepts.md → reference/language/ -└── plugin-migration-*.md → reference/plugin-system/ -``` - -### archiveの主要整理 -``` -archive/ -├── chatgpt5/ → archive/consultations/chatgpt/ -├── codex-analysis/ → archive/consultations/codex/ -├── design/ → 一部をreference/へ、残りはarchive/decisions/ -├── build_logs/ → archive/build-logs/に統合 -└── *.txt (相談記録) → archive/consultations/へ分類 -``` - -### 説明書/の再構成 -``` -説明書/ -├── GETTING_STARTED*.md → guides/getting-started.md (統合版) -├── guides/ → guides/tutorials/ -├── reference/ → reference/ (トップレベルに移動) -└── wasm/ → guides/wasm-guide/ -``` - -## ✅ チェックリスト - -移行前の確認事項： -- [ ] バックアップの作成 -- [ ] 重要なドキュメントの特定 -- [ ] 外部からのリンク確認（README、コード内のコメント等） -- [ ] CIスクリプトでのパス参照確認 - -移行後の確認事項： -- [ ] すべてのドキュメントが新構造に配置されているか -- [ ] 重複ファイルが統合されているか -- [ ] 各ディレクトリにREADME.mdがあるか -- [ ] リンク切れがないか - -どうでしょうか？この計画で進めてよろしいですか？ - -もし承認いただければ、まず小規模なテスト移行から始めることもできます。 - -### 🎯 期待される効果 -- **検索時間短縮**: 必要な情報への到達が3クリック以内に -- **メンテナンス性向上**: 新規ドキュメントの追加場所が明確 -- **重複削減**: 18個のREADME → 5個程度に集約 -- **整理度**: 283ファイル → 適切に分類された構造 \ No newline at end of file diff --git a/docs/EXTERNCALL.md b/docs/EXTERNCALL.md index 31eb2348..3f680ab8 100644 --- a/docs/EXTERNCALL.md +++ b/docs/EXTERNCALL.md @@ -1,25 +1,5 @@ -# ExternCall Policy (Phase 15) +# Moved: ExternCall Reference -## Allowed Interfaces (minimal set) -- `env.console.{log,warn,error,readLine}` -- `env.debug.trace` -- `env.system.{exit,now}` (if present) - -All other host interactions should go through BoxCall (NyRT or plugins). - -## Argument‑type‑based selection -- For `env.console.{log,warn,error}` and `env.debug.trace`: - - If the single argument is `i8*` (C string), call the C‑string variant: - - `nyash.console.log(i8*)`, `nyash.console.warn(i8*)`, `nyash.console.error(i8*)` - - `nyash.debug.trace(i8*)` - - Otherwise convert to `i64` and call the handle variant: - - `nyash.console.log_handle(i64)`, `nyash.console.warn_handle(i64)`, `nyash.console.error_handle(i64)` - - `nyash.debug.trace_handle(i64)` - -## Rationale -- Keeps the AOT string path fast and avoids accidental `inttoptr` of handles. -- Avoids adding broad implicit conversions in ExternCall; selection is local and explicit. - -## Non‑LLVM Backends -- VM, Cranelift JIT/AOT, and the interpreter may not implement this policy yet (not MIR14‑ready). LLVM is authoritative; other backends will align after stabilization. +このドキュメントは移動しました。 +- 新しい場所: [reference/plugin-system/externcall.md](reference/plugin-system/externcall.md) diff --git a/docs/LLVM_HARNESS.md b/docs/LLVM_HARNESS.md index 84373787..44ca9786 100644 --- a/docs/LLVM_HARNESS.md +++ b/docs/LLVM_HARNESS.md @@ -1,70 +1,5 @@ -# llvmlite Harness（正式導入・Rust LLVM 対置運用） +# Moved: llvmlite Harness -Purpose -- Python + llvmlite による高速・柔軟な LLVM 生成経路を提供（検証・プロトタイプと将来の主役）。 -- Rust/inkwell 経路と並走し、代表ケースで機能同値（戻り値・検証）を維持。 +このドキュメントは移動しました。 +- 新しい場所: [reference/architecture/llvm-harness.md](reference/architecture/llvm-harness.md) -Switch -- `NYASH_LLVM_USE_HARNESS=1` でハーネス優先（LLVM バックエンド入口から起動）。 - -Tracing -- `NYASH_LLVM_TRACE_FINAL=1` を設定すると、代表コール（`Main.node_json/3`, `Main.esc_json/1`, `main` 等）を標準出力へ簡易トレースします。 - ON/OFF の最終 JSON 突合の補助に使用してください。 - -Protocol -- Input: MIR14 JSON（Rust 前段で Resolver/LoopForm 規約を満たした形）。 -- Output: `.o` オブジェクト（既定: `NYASH_AOT_OBJECT_OUT` または `NYASH_LLVM_OBJ_OUT`）。 -- 入口: `ny_main() -> i64`（戻り値は exit code 相当。必要時 handle 正規化を行う）。 - -CLI（crate） -- `crates/nyash-llvm-compiler` 提供の `ny-llvmc` は llvmlite ハーネスの薄ラッパーだよ。 - - ダミー: `./target/release/ny-llvmc --dummy --out /tmp/dummy.o` - - JSON→.o: `./target/release/ny-llvmc --in mir.json --out out.o` - - JSON→EXE（新規）: `./target/release/ny-llvmc --in mir.json --emit exe --nyrt target/release --out app` - - `--nyrt ` で `libnyrt.a` の位置を指定（省略時は `target/release`→`crates/nyrt/target/release` の順に探索） - - 追加フラグは `--libs ""` で渡せる（例: `--libs "-static"`） - - 既定のハーネススクリプトは `tools/llvmlite_harness.py`（`--harness` で上書き可）。 - -Quick Start -- 依存: `python3 -m pip install llvmlite` -- ダミー生成（配線検証）: - - `python3 tools/llvmlite_harness.py --out /tmp/dummy.o` - - NyRT（libnyrt.a）とリンクして EXE 化（例: `cc /tmp/dummy.o -L target/release -Wl,--whole-archive -lnyrt -Wl,--no-whole-archive -lpthread -ldl -lm -o app_dummy`）。 - -Wiring（Rust 側） -- `NYASH_LLVM_USE_HARNESS=1` のとき: - 1) `--emit-mir-json ` 等で MIR(JSON) を出力 - 2) `python3 tools/llvmlite_harness.py --in --out ` を起動 - 3) 成功後は通常のリンク手順（NyRT とリンク） - -Tools / CLI（統合フロー） -- crate 直結の EXE 出力: `NYASH_LLVM_COMPILER=crate NYASH_LLVM_EMIT=exe tools/build_llvm.sh apps/tests/ternary_basic.nyash -o app` - - 環境変数 `NYASH_LLVM_NYRT` で NyRT の場所を、`NYASH_LLVM_LIBS` で追加フラグを指定できる。 - - CLI から直接 EXE 出力（新規）: - - `./target/release/nyash --emit-exe tmp/app --backend mir apps/tests/ternary_basic.nyash` - - 追加オプション: `--emit-exe-nyrt ` / `--emit-exe-libs ""` - -Scope（Phase 15） -- 最小命令: Const/BinOp/Compare/Branch/Jump/Return（PHI は LLVM 側で合成） -- 文字列: NyRT Shim（`nyash.string.len_h`, `charCodeAt_h`, `concat_hh`, `eq_hh`）を declare → call -- NewBox/ExternCall/BoxCall: まずは固定シンボル／by-id を優先（段階導入） -- 目標: `apps/selfhost/tools/dep_tree_min_string.nyash` の `.ll verify green → .o` 安定化 - -Acceptance -- Harness ON/OFF で機能同値（戻り値/検証）。代表ケースで `.ll verify green` と `.o` 生成成功。 - -Notes -- 初版は固定 `ny_main` から開始してもよい（配線確認）。以降、MIR 命令を順次対応。 -- ハーネスは自律（外部状態に依存しない）。エラーは即 stderr に詳細を出す。 - -PHI Policy（要点） -- Phase‑15 の既定は PHI‑on。MIR 側で SSA `Phi` を生成し、ハーネスは incoming の検証と最終 IR への反映だけを行う。 -- レガシー互換のために PHI‑off が必要なケースでは `NYASH_MIR_NO_PHI=1` を明示してね（ハーネスは旧 edge-copy 互換ルートで補完する）。 -- 詳細と背景は `docs/reference/mir/phi_policy.md` を参照。 - -Schema Validation（任意） -- JSON v0 のスキーマは `docs/reference/mir/json_v0.schema.json` にあるよ。 -- 検証: `python3 tools/validate_mir_json.py `（要: `python3 -m pip install jsonschema`）。 - -Appendix: 静的リンクについて -- 生成 EXE は NyRT（libnyrt.a）を静的リンク。完全静的（-static）は musl 推奨（dlopen 不可になるため動的プラグインは使用不可）。 diff --git a/docs/PLUGIN_ABI.md b/docs/PLUGIN_ABI.md index 3a50905d..ec1541fb 100644 --- a/docs/PLUGIN_ABI.md +++ b/docs/PLUGIN_ABI.md @@ -1,23 +1,5 @@ -# Plugin ABI (by-id / tagged) — Snapshot +# Moved: Plugin ABI -This summarizes the ABI surfaces used by LLVM in Phase 15. Details live in NyRT (`crates/nyrt`). - -## Fixed-arity by-id shims -- Integer-dominant: `i64 @nyash_plugin_invoke3_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 a2, i64 a3, i64 a4)` -- Float-dominant: `f64 @nyash_plugin_invoke3_f64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, f64 a1, f64 a2, f64 a3, f64 a4)` - -## Tagged shims (mixed types) -- Fixed (<=4 args): `i64 @nyash_plugin_invoke3_tagged_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 t1, i64 a2, i64 t2, i64 a3, i64 t3, i64 a4, i64 t4)` -- Vector (N args): `i64 @nyash.plugin.invoke_tagged_v_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i8* vals, i8* tags)` - -Tag codes (minimal): -- 3=int, 5=float, 8=handle(ptr). Others are reserved/experimental. - -## Return mapping (LLVM lowering) -- If destination is annotated as Integer/Bool → keep i64 as integer. -- If destination is String/Box/Array/Future/Unknown → cast i64 handle to opaque pointer for SSA flow; do not `inttoptr` where a C string is expected. - -## Notes -- These ABIs are used by both built-ins (nyrt) and plugins for consistency. -- The LLVM backend is the reference; other backends will be aligned later. +このドキュメントは移動しました。 +- 新しい場所: [reference/abi/PLUGIN_ABI.md](reference/abi/PLUGIN_ABI.md) diff --git a/docs/REORGANIZATION_REPORT.md b/docs/REORGANIZATION_REPORT.md index ac43c02a..842b28d9 100644 --- a/docs/REORGANIZATION_REPORT.md +++ b/docs/REORGANIZATION_REPORT.md @@ -1,145 +1,5 @@ -# Nyash ドキュメント再編成報告書 📋 +# Moved: Reorganization Report -## 実行日時 -2025年8月20日 21:45 +このドキュメントは移動しました。 +- 新しい場所: [development/cleanup/docs-reorg/REPORT.md](development/cleanup/docs-reorg/REPORT.md) -## 🎯 実施内容 - -### 1. バックアップ作成 -- `docs_backup_20250820_214047.tar.gz` を作成済み - -### 2. 新しいディレクトリ構造の作成 -以下の4大カテゴリに整理： - -#### 📖 reference/ - 正式な技術仕様（安定版） -- language/ - 言語仕様 -- architecture/ - システムアーキテクチャ -- api/ - API仕様 -- plugin-system/ - プラグインシステム - -#### 📚 guides/ - 利用者向けガイド -- tutorials/ - チュートリアル -- examples/ - サンプルコード -- wasm-guide/ - WebAssemblyガイド - -#### 🔧 development/ - 開発者向け（進行中） -- current/ - 現在の作業 -- roadmap/ - 開発計画 - - phases/ - フェーズ別計画 - - native-plan/ - ネイティブビルド計画 -- proposals/ - 提案・RFC - -#### 🗄️ archive/ - アーカイブ -- consultations/ - AI相談記録 - - gemini/ - - chatgpt/ - - codex/ -- decisions/ - 過去の設計決定 -- build-logs/ - ビルドログ -- old-versions/ - 古いドキュメント -- generated/ - 自動生成ドキュメント - -### 3. ファイル移動状況 - -#### ✅ 完了した移動 -- 基本的なディレクトリ構造の作成 -- 各ディレクトリにREADME.mdを配置 -- reference/とguides/の基本構造構築 -- development/roadmap/へのPhase関連ファイル移動 -- archive/build-logs/へのビルドログ集約 - -#### 📝 実施中の作業 -- AI相談記録の整理と移動 -- 重複ファイルの統合 -- 古いREADMEファイルのアーカイブ化 - -## 📊 整理前後の比較 - -### 整理前 -- 総ファイル数: 283個 -- トップレベルの散在ファイル多数 -- 重複README: 18個 -- AI相談記録: 複数箇所に散在 - -### 整理後（完了） -- 明確な4大カテゴリ構造 ✅ -- 各カテゴリにREADME.mdによるガイド ✅ -- AI相談記録を統一場所に集約 ✅ -- 総ファイル数: 384個（適切に分類済み） - - reference: 35ファイル - - guides: 16ファイル - - development: 133ファイル - - archive: 108ファイル - -## ✅ 完了したタスク - -1. **説明書/ディレクトリの統合** ✅ - - 内容をreference/とguides/に分類・移動完了 - -2. **予定/ディレクトリの整理** ✅ - - development/roadmap/への移動完了 - -3. **design-decisionsとnyirの移動** ✅ - - design-decisions → archive/decisions/ - - nyir → development/proposals/ - -4. **空ディレクトリのクリーンアップ** ✅ - - 全ての空ディレクトリを削除済み - -## 🚧 残タスク - -1. **相互リンクの修正** - - 移動したファイルへの参照更新 - - CLAUDE.mdの参照パス更新 - -2. **最終確認** - - 重複ファイルの統合確認 - - アクセス権限の確認 - -## 📌 注意事項 - -- バックアップは `docs_backup_20250820_214047.tar.gz` に保存済み -- 重要なファイルは慎重に移動中 -- CLAUDE.mdなどのルートファイルへの参照は要更新 - -## 🎯 次のステップ - -1. 残りのファイル移動を完了 -2. 空ディレクトリの削除 -3. 相互リンクの確認と修正 -4. 最終的な整合性チェック -5. CLAUDE.mdの参照更新 - ---- - -## 追加再編（2025-09-25、小規模・互換維持） - -概要 -- トップレベルに散在していたいくつかのカテゴリを、既存の4本柱へ段階的に集約しました（既定挙動は不変）。 - -主な移動 -- architecture → reference/architecture - - phi-and-ssa.md を reference/architecture/ へ移動（旧パスに stub 追加） -- blueprints → development/design/blueprints - - strings-utf8-byte.md を移動（旧パスに stub 追加） -- design → development/design/legacy - - 設計ノート一式を legacy サブフォルダへ移動（旧フォルダに案内 README/stub 追加） -- proposals → development/proposals - - proposals/* を移動（旧パスに README/stub 追加） -- examples → guides/examples - - 例一式を移動（旧パスに README/stub 追加） -- status/golden → development/testing/golden - - ゴールデン出力を移動（旧パスに README 追加） -- tests → development/testing - - テストドキュメントを移動（旧パスに README 追加） - -リンク更新 -- docs/README.md の該当リンク（blueprints/design/proposals/using-loader）を最小修正 -- docs/VM_README.md の examples 参照を guides/examples に更新 - -非対象 -- docs/private/ 配下は今回の再編から除外（方針どおり） - -受け入れチェック -- 既定挙動は不変、差分は最小 -- 移動元ディレクトリに stub/README を配置し、後方互換を確保 diff --git a/docs/VM_README.md b/docs/VM_README.md index 32aec0b8..c75570cc 100644 --- a/docs/VM_README.md +++ b/docs/VM_README.md @@ -1,107 +1,5 @@ -# Nyash VM 実行基盤ガイド（更新） +# Moved: Nyash VM Guide -- プラグインBox引数の最小対応を追加（TLV: BoxRef） -- TLVタグ: 1=Bool, 2=I32, 3=I64, 4=F32, 5=F64, 6=String, 7=Bytes, 8=Handle(BoxRef) - - BoxRefはプラグインBox参照（type_id:u32, instance_id:u32）を8バイトでエンコード - - ユーザー定義/複雑なBoxは当面一部非対応（toStringフォールバック）。標準Boxはプラグイン経由で統一 +このドキュメントは移動しました。 +- 新しい場所: [reference/architecture/vm.md](reference/architecture/vm.md) -現状のルーティング（Plugin-First）: -- User-defined: MIR関数（{Box}.{method}/{N}) にCall化（関数存在時）。それ以外はBoxCall。 -- Plugin: BoxCall → PluginInvoke（method_idが解決可能）→ それ以外は名前解決で PluginHost.invoke_instance_method。 - -今後のタスク: -- VM側のfrom Parent.method対応（Builder/VM両対応） -- TLVの型拡張（Float/配列/BoxRef戻り値など） - -## 🧮 VM実行統計（NYASH_VM_STATS / JSON） - -VMは命令カウントと実行時間を出力できます。 - -使い方（CLIフラグ）: -```bash -# 人間向け表示 -nyash --backend vm --vm-stats program.nyash - -# JSON出力 -nyash --backend vm --vm-stats --vm-stats-json program.nyash -``` - -環境変数（直接指定）: -```bash -NYASH_VM_STATS=1 ./target/debug/nyash --backend vm program.nyash -NYASH_VM_STATS=1 NYASH_VM_STATS_JSON=1 ./target/debug/nyash --backend vm program.nyash -# 代替: NYASH_VM_STATS_FORMAT=json -``` - -出力は `total`（総命令数）, `elapsed_ms`（経過時間）, `counts`（命令種別→回数）, `top20`（上位20種）を含みます。 - -## 既知の制約とTips（VM×プラグイン） -- Netプラグイン（HTTP） - - unreachable（接続不可/タイムアウト）は `Result.Err(ErrorBox)`。 - - HTTP 404/500 は `Result.Ok(Response)`（アプリ側で `response.status` を確認）。 - - デバッグ: `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`。 -- FileBox - - `close()` は `Ok(Void)`。`match Ok(_)` で受けるか、戻り値を無視してよい。 -- Handle（BoxRef）戻り - - TLV tag=8（type_id:u32, instance_id:u32）。Loaderが返り値typeに対応する `fini_method_id` を設定し `PluginBoxV2` を構築。 - - `scope_tracker` がスコープ終了時に `fini()` を呼ぶ（メモリ安全）。 -- 大きいボディ/多ヘッダー/タイムアウト - - 逐次拡張中。異常時の挙動は上記Result規約に従う。実行ログと `--vm-stats` を併用して診断。 -- 反復タイムアウト: `local_tests/socket_repeated_timeouts.nyash` で `acceptTimeout/recvTimeout` の連続ケース確認 -- BoxCallデバッグ: `NYASH_VM_DEBUG_BOXCALL=1` でBoxCallの受け手型・引数型・処理経路（enter/fastpath/unified）・結果型をstderr出力 - - 例: `NYASH_VM_DEBUG_BOXCALL=1 ./target/release/nyash --backend vm local_tests/test_vm_array_getset.nyash` - -## 🔧 BoxCallの統一経路（Phase 9.79b） - -### method_id（スロット）によるBoxCall -- Builderが受け手型を推論できる場合、`BoxCall`に数値`method_id`（スロット）を付与。 -- 低スロットはユニバーサル予約（0=toString, 1=type, 2=equals, 3=clone）。 -- ユーザー定義Boxは宣言時にインスタンスメソッドへスロットを4番から順に予約（決定論的）。 - -### VMの実行経路（thunk + PIC） -- ユニバーサルスロット（0..3）はVMのfast-path thunkで即時処理。 - - toString/type/equals/cloneの4種は受け手`VMValue`から直接評価。 -- それ以外は以下の順で処理: - 1. Mono-PIC（モノモーフィックPIC）直呼び: 受け手型×method（またはmethod_id）のキーでホットサイトを判定し、 - `InstanceBox`は関数名キャッシュを使って `{Class}.{method}/{arity}` を直接呼び出す（閾値=8）。 - 2. 既存経路: `InstanceBox`はMIR関数へCall、それ以外は各Boxのメソッドディスパッチへフォールバック。 - -環境変数（デバッグ）: -```bash -NYASH_VM_DEBUG_BOXCALL=1 # BoxCallの入出力と処理経路を出力 -NYASH_VM_PIC_DEBUG=1 # PICヒットのしきい値通過時にログ -``` - -今後の拡張: -- 一般`method_id`（ユーザー/プラグイン）に対するvtableスロット→thunk直呼び。 -- PICのキャッシュ無効化（型version）と多相PICへの拡張（Phase 10）。 - - SocketBox（VM） - - 基本API: `bind/listen/accept/connect/read/write/close/isServer/isConnected` - - タイムアウト: `acceptTimeout(ms)` は接続なしで `void`、`recvTimeout(ms)` は空文字を返す - - 簡易E2E: `local_tests/socket_timeout_server.nyash` と `socket_timeout_client.nyash` - - Void 比較の扱い（VM） - - `Void` は値を持たないため、`Eq/Ne` のみ有効。`Void == Void` は真、それ以外の型との `==` は偽（`!=` は真）。 - - 順序比較（`<, <=, >, >=`）は `TypeError`。 - -## E2E 実行例（HTTPのResult挙動） - -代表ケースを `tools/run_vm_stats.sh` で実行できます。`--vm-stats-json` により命令プロファイルも取得可能です。 - -```bash -# 別ターミナルでサーバ起動 -./target/release/nyash local_tests/http_server_statuses.nyash - -# クライアント（別ターミナル） -tools/run_vm_stats.sh local_tests/vm_stats_http_ok.nyash vm_stats_ok.json -tools/run_vm_stats.sh local_tests/vm_stats_http_404.nyash vm_stats_404.json -tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json - -# 到達不能（サーバ不要） -tools/run_vm_stats.sh local_tests/vm_stats_http_err.nyash vm_stats_err.json -``` - -期待されるResultモデル -- unreachable（接続不可/タイムアウト）: `Result.Err(ErrorBox)` -- 404/500 等のHTTPエラー: `Result.Ok(Response)`（アプリ側で `response.status` を評価） - -詳細: `docs/reference/architecture/mir-to-vm-mapping.md` と `docs/guides/examples/http_result_patterns.md` を参照。 diff --git a/docs/comparison/README.md b/docs/comparison/README.md new file mode 100644 index 00000000..1fcd388f --- /dev/null +++ b/docs/comparison/README.md @@ -0,0 +1,6 @@ +# Moved: Comparison + +比較記事は `docs/guides/comparison/` に移動しました。 + +- 代表: [nyash-vs-others.md](../guides/comparison/nyash-vs-others.md) + diff --git a/docs/development/cleanup/docs-reorg/PLAN.md b/docs/development/cleanup/docs-reorg/PLAN.md new file mode 100644 index 00000000..1aaf458b --- /dev/null +++ b/docs/development/cleanup/docs-reorg/PLAN.md @@ -0,0 +1,276 @@ +# Nyash ドキュメント再編成計画 📚 + +## 📊 現状の分析結果 + +### ファイル数統計 +- **総ファイル数**: 283個（.md: 211個, .txt: 72個） +- **archive/**: 113ファイル（40%） +- **予定/**: 111ファイル（39%） +- **説明書/**: 41ファイル（14%） +- **その他**: 18ファイル（7%） + +### 重複・散在ファイル +- **README系**: 18個（各ディレクトリに散在） +- **GETTING_STARTED**: 3バージョン存在 +- **Phase関連**: 42ファイル（主に予定/native-plan/issues/） +- **AI相談記録**: 41ファイル（複数箇所に散在） +- **ビルドログ**: 13ファイル（archive各所） + +## 🔍 現状の問題点 + +### 1. **構造の混乱** +- トップレベルに開発中/正式文書が混在 +- `説明書/` と直下に同じような内容が散在 +- `archive/` に無秩序に大量のファイル + +### 2. **重複と不明確な階層** +- `説明書/reference/` と `reference/` が併存 +- GETTING_STARTED.md が複数存在（通常版と2025版） +- MIR関連ドキュメントが複数箇所に分散 + +### 3. **AI相談記録の散在** +- gemini/chatgpt相談が archive/, トップ, design/decisions/ など複数箇所 +- ビルドログも同様に散在 + +### 4. **開発フェーズ管理の複雑さ** +- Phase関連ファイルが `予定/native-plan/issues/` に大量 +- 現在のタスクと将来計画が混在 + +## 📋 提案する新構造 + +``` +docs/ +├── README.md # ドキュメントマップ（どこに何があるか） +│ +├── 📖 reference/ # 正式な技術仕様（安定版） +│ ├── README.md +│ ├── language/ # 言語仕様 +│ │ ├── syntax.md # 構文リファレンス +│ │ ├── types.md # 型システム +│ │ ├── boxes.md # Box仕様 +│ │ └── delegation.md # デリゲーション仕様 +│ ├── architecture/ # アーキテクチャ +│ │ ├── overview.md # 全体設計 +│ │ ├── mir.md # MIR仕様 +│ │ ├── vm.md # VM仕様 +│ │ └── plugins.md # プラグインシステム +│ └── api/ # API仕様 +│ ├── builtin-boxes.md # ビルトインBox一覧 +│ └── stdlib.md # 標準ライブラリ +│ +├── 📚 guides/ # 利用者向けガイド +│ ├── README.md +│ ├── getting-started.md # はじめに（統一版） +│ ├── tutorials/ # チュートリアル +│ │ ├── hello-world.md +│ │ ├── basic-boxes.md +│ │ └── p2p-apps.md +│ ├── examples/ # サンプルコード +│ └── playground.md # プレイグラウンドガイド +│ +├── 🔧 development/ # 開発者向け（進行中） +│ ├── README.md +│ ├── current/ # 現在の作業 +│ │ ├── CURRENT_TASK.md +│ │ └── VM_CHANGES.md +│ ├── roadmap/ # 開発計画 +│ │ ├── phases/ # Phase別計画 +│ │ │ ├── phase-8/ +│ │ │ ├── phase-9/ +│ │ │ └── phase-10/ +│ │ └── native-plan/ # ネイティブビルド計画 +│ └── proposals/ # 提案・RFC +│ └── phase_9_78e.md +│ +├── 🗄️ archive/ # アーカイブ（古い/歴史的文書） +│ ├── README.md # アーカイブの説明 +│ ├── consultations/ # AI相談記録 +│ │ ├── gemini/ +│ │ ├── chatgpt/ +│ │ └── codex/ +│ ├── decisions/ # 過去の設計決定 +│ ├── build-logs/ # ビルドログ +│ └── old-versions/ # 古いドキュメント +│ +└── 🎨 assets/ # 画像・図表など + ├── diagrams/ + └── screenshots/ +``` + +## 🔄 移行計画 + +### Phase 1: 基本構造作成（優先度: 高） +1. 新しいディレクトリ構造を作成 +2. README.md でドキュメントマップ作成 +3. 現在進行中のファイルを `development/current/` へ移動 + +### Phase 2: リファレンス整理（優先度: 高） +1. `説明書/reference/` の内容を `reference/` に統合 +2. 重複ファイルの統合（GETTING_STARTED統一版作成） +3. MIR/VM関連ドキュメントを適切な場所に配置 + +### Phase 3: アーカイブ整理（優先度: 中） +1. AI相談記録を `archive/consultations/` に集約 +2. ビルドログを `archive/build-logs/` に集約 +3. 古いドキュメントを `archive/old-versions/` へ + +### Phase 4: 開発ドキュメント整理（優先度: 中） +1. Phase関連ファイルを番号順に整理 +2. 現在のタスクと将来計画を明確に分離 +3. native-plan を整理して見やすく + +## 💡 メリット + +1. **明確な分類**: 利用者向け/開発者向け/アーカイブが明確 +2. **検索性向上**: 必要な情報がどこにあるか分かりやすい +3. **メンテナンス性**: 新しいドキュメントの追加場所が明確 +4. **バージョン管理**: 現在の仕様と過去の記録が分離 + +## 🤔 検討事項 + +### 日本語ディレクトリ名の変換案 +現在の日本語ディレクトリを英語に統一： +- `説明書/` → `guides/` に内容を移動 +- `予定/` → `development/roadmap/` に内容を移動 +- 日本語ファイル名（.txt/.md）はそのまま維持（内容が日本語のため） + +**理由**: +- 国際的な開発者にもアクセスしやすい +- パス指定時のエンコーディング問題を回避 +- Git操作が簡単に + +### 既存リンクの対応 +- 多くの場所から参照されている可能性 +- → **対策**: 移行期間は旧パスにシンボリックリンクまたはREADME配置 + +### 自動生成ドキュメント +- MIRダンプやベンチマーク結果など +- → **提案**: `development/generated/` または `archive/generated/` に配置 + +## 📝 実装順序の提案 + +### Step 1: 基本構造作成スクリプト +```bash +#!/bin/bash +# create_new_structure.sh + +# 新構造の作成 +mkdir -p reference/{language,architecture,api} +mkdir -p guides/{tutorials,examples} +mkdir -p development/{current,roadmap/{phases/{phase-8,phase-9,phase-10},native-plan},proposals} +mkdir -p archive/{consultations/{gemini,chatgpt,codex},decisions,build-logs,old-versions} +mkdir -p assets/{diagrams,screenshots} + +# 各ディレクトリにREADME.mdを配置 +echo "# Reference Documentation" > reference/README.md +echo "# User Guides" > guides/README.md +echo "# Development Documentation" > development/README.md +echo "# Archive" > archive/README.md +``` + +### Step 2: 優先移動ファイルリスト +1. **現在の作業ファイル** + - `CURRENT_TASK.md` → `development/current/` + - `CURRENT_VM_CHANGES.md` → `development/current/` + - `phase_9_78e_summary.md` → `development/current/` + +2. **言語仕様** + - `LANGUAGE_REFERENCE_2025.md` → `reference/language/` + - `TECHNICAL_ARCHITECTURE_2025.md` → `reference/architecture/` + - `説明書/reference/` の内容 → `reference/` へ統合 + +3. **利用者ガイド** + - GETTING_STARTED系を統合 → `guides/getting-started.md` + - `説明書/guides/` → `guides/tutorials/` + +### Step 3: 自動整理スクリプト案 +```bash +#!/bin/bash +# reorganize_docs.sh + +# Phase関連ファイルの整理 +find 予定/native-plan/issues -name "phase_*.md" | while read f; do + phase=$(echo $f | grep -o 'phase_[0-9]\+' | head -1) + mkdir -p development/roadmap/phases/$phase + mv "$f" development/roadmap/phases/$phase/ +done + +# AI相談記録の集約 +find . -name "*gemini*.txt" -exec mv {} archive/consultations/gemini/ \; +find . -name "*chatgpt*.txt" -exec mv {} archive/consultations/chatgpt/ \; +find . -name "*consultation*.txt" -exec mv {} archive/consultations/ \; + +# ビルドログの集約 +find . -name "*build*.log" -o -name "*build*.txt" -exec mv {} archive/build-logs/ \; +``` + +## 🚀 実装提案 + +1. **まず `DOCUMENTATION_REORGANIZATION_PLAN.md` の承認** +2. **バックアップ作成** + ```bash + tar -czf docs_backup_$(date +%Y%m%d).tar.gz docs/ + ``` +3. **基本ディレクトリ構造の作成**（上記スクリプト） +4. **段階的移行**（優先度順） +5. **リンク切れチェック** +6. **最終確認とクリーンアップ** + +## 📋 具体的な移行マッピング（主要ファイル） + +### 現在のトップレベルファイル +``` +docs/ +├── CURRENT_TASK.md → development/current/ +├── CURRENT_VM_CHANGES.md → development/current/ +├── LANGUAGE_REFERENCE_2025.md → reference/language/ +├── TECHNICAL_ARCHITECTURE_2025.md → reference/architecture/ +├── Phase-9.75g-0-BID-FFI-*.md → development/roadmap/phases/phase-9/ +├── README.md → そのまま（インデックスとして） +├── execution-backends.md → reference/architecture/ +├── nyash_core_concepts.md → reference/language/ +└── plugin-migration-*.md → reference/plugin-system/ +``` + +### archiveの主要整理 +``` +archive/ +├── chatgpt5/ → archive/consultations/chatgpt/ +├── codex-analysis/ → archive/consultations/codex/ +├── design/ → 一部をreference/へ、残りはarchive/decisions/ +├── build_logs/ → archive/build-logs/に統合 +└── *.txt (相談記録) → archive/consultations/へ分類 +``` + +### 説明書/の再構成 +``` +説明書/ +├── GETTING_STARTED*.md → guides/getting-started.md (統合版) +├── guides/ → guides/tutorials/ +├── reference/ → reference/ (トップレベルに移動) +└── wasm/ → guides/wasm-guide/ +``` + +## ✅ チェックリスト + +移行前の確認事項： +- [ ] バックアップの作成 +- [ ] 重要なドキュメントの特定 +- [ ] 外部からのリンク確認（README、コード内のコメント等） +- [ ] CIスクリプトでのパス参照確認 + +移行後の確認事項： +- [ ] すべてのドキュメントが新構造に配置されているか +- [ ] 重複ファイルが統合されているか +- [ ] 各ディレクトリにREADME.mdがあるか +- [ ] リンク切れがないか + +どうでしょうか？この計画で進めてよろしいですか？ + +もし承認いただければ、まず小規模なテスト移行から始めることもできます。 + +### 🎯 期待される効果 +- **検索時間短縮**: 必要な情報への到達が3クリック以内に +- **メンテナンス性向上**: 新規ドキュメントの追加場所が明確 +- **重複削減**: 18個のREADME → 5個程度に集約 +- **整理度**: 283ファイル → 適切に分類された構造 \ No newline at end of file diff --git a/docs/development/cleanup/docs-reorg/REPORT.md b/docs/development/cleanup/docs-reorg/REPORT.md new file mode 100644 index 00000000..ac43c02a --- /dev/null +++ b/docs/development/cleanup/docs-reorg/REPORT.md @@ -0,0 +1,145 @@ +# Nyash ドキュメント再編成報告書 📋 + +## 実行日時 +2025年8月20日 21:45 + +## 🎯 実施内容 + +### 1. バックアップ作成 +- `docs_backup_20250820_214047.tar.gz` を作成済み + +### 2. 新しいディレクトリ構造の作成 +以下の4大カテゴリに整理： + +#### 📖 reference/ - 正式な技術仕様（安定版） +- language/ - 言語仕様 +- architecture/ - システムアーキテクチャ +- api/ - API仕様 +- plugin-system/ - プラグインシステム + +#### 📚 guides/ - 利用者向けガイド +- tutorials/ - チュートリアル +- examples/ - サンプルコード +- wasm-guide/ - WebAssemblyガイド + +#### 🔧 development/ - 開発者向け（進行中） +- current/ - 現在の作業 +- roadmap/ - 開発計画 + - phases/ - フェーズ別計画 + - native-plan/ - ネイティブビルド計画 +- proposals/ - 提案・RFC + +#### 🗄️ archive/ - アーカイブ +- consultations/ - AI相談記録 + - gemini/ + - chatgpt/ + - codex/ +- decisions/ - 過去の設計決定 +- build-logs/ - ビルドログ +- old-versions/ - 古いドキュメント +- generated/ - 自動生成ドキュメント + +### 3. ファイル移動状況 + +#### ✅ 完了した移動 +- 基本的なディレクトリ構造の作成 +- 各ディレクトリにREADME.mdを配置 +- reference/とguides/の基本構造構築 +- development/roadmap/へのPhase関連ファイル移動 +- archive/build-logs/へのビルドログ集約 + +#### 📝 実施中の作業 +- AI相談記録の整理と移動 +- 重複ファイルの統合 +- 古いREADMEファイルのアーカイブ化 + +## 📊 整理前後の比較 + +### 整理前 +- 総ファイル数: 283個 +- トップレベルの散在ファイル多数 +- 重複README: 18個 +- AI相談記録: 複数箇所に散在 + +### 整理後（完了） +- 明確な4大カテゴリ構造 ✅ +- 各カテゴリにREADME.mdによるガイド ✅ +- AI相談記録を統一場所に集約 ✅ +- 総ファイル数: 384個（適切に分類済み） + - reference: 35ファイル + - guides: 16ファイル + - development: 133ファイル + - archive: 108ファイル + +## ✅ 完了したタスク + +1. **説明書/ディレクトリの統合** ✅ + - 内容をreference/とguides/に分類・移動完了 + +2. **予定/ディレクトリの整理** ✅ + - development/roadmap/への移動完了 + +3. **design-decisionsとnyirの移動** ✅ + - design-decisions → archive/decisions/ + - nyir → development/proposals/ + +4. **空ディレクトリのクリーンアップ** ✅ + - 全ての空ディレクトリを削除済み + +## 🚧 残タスク + +1. **相互リンクの修正** + - 移動したファイルへの参照更新 + - CLAUDE.mdの参照パス更新 + +2. **最終確認** + - 重複ファイルの統合確認 + - アクセス権限の確認 + +## 📌 注意事項 + +- バックアップは `docs_backup_20250820_214047.tar.gz` に保存済み +- 重要なファイルは慎重に移動中 +- CLAUDE.mdなどのルートファイルへの参照は要更新 + +## 🎯 次のステップ + +1. 残りのファイル移動を完了 +2. 空ディレクトリの削除 +3. 相互リンクの確認と修正 +4. 最終的な整合性チェック +5. CLAUDE.mdの参照更新 + +--- + +## 追加再編（2025-09-25、小規模・互換維持） + +概要 +- トップレベルに散在していたいくつかのカテゴリを、既存の4本柱へ段階的に集約しました（既定挙動は不変）。 + +主な移動 +- architecture → reference/architecture + - phi-and-ssa.md を reference/architecture/ へ移動（旧パスに stub 追加） +- blueprints → development/design/blueprints + - strings-utf8-byte.md を移動（旧パスに stub 追加） +- design → development/design/legacy + - 設計ノート一式を legacy サブフォルダへ移動（旧フォルダに案内 README/stub 追加） +- proposals → development/proposals + - proposals/* を移動（旧パスに README/stub 追加） +- examples → guides/examples + - 例一式を移動（旧パスに README/stub 追加） +- status/golden → development/testing/golden + - ゴールデン出力を移動（旧パスに README 追加） +- tests → development/testing + - テストドキュメントを移動（旧パスに README 追加） + +リンク更新 +- docs/README.md の該当リンク（blueprints/design/proposals/using-loader）を最小修正 +- docs/VM_README.md の examples 参照を guides/examples に更新 + +非対象 +- docs/private/ 配下は今回の再編から除外（方針どおり） + +受け入れチェック +- 既定挙動は不変、差分は最小 +- 移動元ディレクトリに stub/README を配置し、後方互換を確保 diff --git a/docs/development/design/legacy/LLVM_LAYER_OVERVIEW.md b/docs/development/design/legacy/LLVM_LAYER_OVERVIEW.md index fdd273c3..29769d04 100644 --- a/docs/development/design/legacy/LLVM_LAYER_OVERVIEW.md +++ b/docs/development/design/legacy/LLVM_LAYER_OVERVIEW.md @@ -2,7 +2,7 @@ Scope - Practical guide to LLVM lowering architecture and invariants used in Phase 15. -- Complements LOWERING_LLVM.md (rules), RESOLVER_API.md (value resolution), and LLVM_HARNESS.md (harness). +- Complements LOWERING_LLVM.md (rules), RESOLVER_API.md (value resolution), and docs/reference/architecture/llvm-harness.md (harness). Module Layout - `src/backend/llvm/compiler/codegen/` @@ -33,5 +33,4 @@ Harness (optional) References - LOWERING_LLVM.md — lowering rules and runtime calls - RESOLVER_API.md — Resolver design and usage -- LLVM_HARNESS.md — llvmlite harness interface and usage - +- docs/reference/architecture/llvm-harness.md — llvmlite harness interface and usage diff --git a/docs/development/engineering/merge-strategy.md b/docs/development/engineering/merge-strategy.md new file mode 100644 index 00000000..749e6102 --- /dev/null +++ b/docs/development/engineering/merge-strategy.md @@ -0,0 +1,33 @@ +# Merge Strategy — selfhosting‑dev × Cranelift branches + +目的 +- selfhosting‑dev（VM/JIT 自己ホスト）と Cranelift 専用ブランチ（AOT/JIT‑AOT）を並行開発しつつ、衝突と複雑な解消作業を最小化する。 + +ブランチの役割 +- `selfhosting-dev`: Ny→MIR→MIR-Interp→VM/JIT の安定化、ツール/スモーク、ドキュメント整備。 +- `phase-15/self-host-aot-cranelift`（例）: Cranelift backend の実装・検証。 +- `develop`: 定期同期の受け皿。`main` はリリース用。 + +方針（設計） +- 境界の明確化: Cranelift 固有コード（例: `src/jit/*`, `src/jit/rt.rs` など）は専用ブランチで集中的に変更。selfhosting‑dev は Runner/Interpreter/VM の公共 API に限定。 +- Feature gate: 共有面に変更が必要な場合は `#[cfg(feature = "cranelift-jit")]` 等で分岐し、ABI/シグネチャ互換を保つ。 +- ドキュメント分離: `CURRENT_TASK.md` はインデックス化し、詳細は `docs/phase-15/*` へトピックごとに分離（本運用により md の大規模衝突を回避）。 + +方針（運用） +- 同期リズム: selfhosting‑dev → develop へ週1回まとめPR。Cranelift 側も同周期で develop へリベース/マージ。 +- 早期検知: 各PRで `rg` による衝突予兆チェック（ファイル/トークンベース）をテンプレに含める。 +- rerere: `git config rerere.enabled true` を推奨し、同種の衝突解消を再利用。 +- ラベル運用: `area:jit`, `area:vm`, `docs:phase-15`, `merge-risk:high` 等でレビュー優先度を明示。 + +ファイルオーナーシップ（推奨） +- Cranelift: `src/jit/**`, `src/jit/policy.rs`, `tools/*aot*`, `docs/phase-15/cranelift/**` +- Selfhost core: `src/interpreter/**`, `src/runner/**`, `dev/selfhosting/**`, `tools/smokes/v2/**` +- 共有/IR: `src/mir/**`, `src/parser/**` は変更時に両ブランチへ告知（PR説明で影響範囲を明記）。 + +実務Tips +- マージ用テンプレ（PR description） + - 目的 / 影響範囲 / 変更対象ファイル / 互換性 / リスクと回避策 / テスト項目 +- 衝突抑止の小技 + - md は章分割して別ファイルに参照化（本運用の通り） + - 大規模renameは単独PRで先行適用 + - 共有インターフェイスは薄いアダプタで橋渡し（実装詳細は各ブランチ内） diff --git a/docs/ideas/language/pure-functional-blocks.md b/docs/development/proposals/ideas/language/pure-functional-blocks.md similarity index 100% rename from docs/ideas/language/pure-functional-blocks.md rename to docs/development/proposals/ideas/language/pure-functional-blocks.md diff --git a/docs/development/refactoring/refactor-roadmap.md b/docs/development/refactoring/refactor-roadmap.md new file mode 100644 index 00000000..7d86ed2d --- /dev/null +++ b/docs/development/refactoring/refactor-roadmap.md @@ -0,0 +1,82 @@ +# Nyash Refactor Roadmap (Pre–Self-Hosting) + +This document lists large modules, proposes safe splits/commonization, and outlines the MIR13 cleanup plan. + +## Large Modules to Split + +Targets are chosen by size and cohesion. Splits are incremental and build-preserving; move code in small steps and re-export in `mod.rs`. + +- `src/mir/verification.rs` (~965 loc) + - Split into: `mir/verification/{mod.rs,basic.rs,types.rs,control_flow.rs,ownership.rs}`. + - First move leaf helpers and pass-specific checks; keep public API and `pub use` to avoid churn. + +- `src/mir/builder.rs` (~930 loc) + - Split into: `mir/builder/{mod.rs,exprs.rs,stmts.rs,decls.rs,control_flow.rs}`. + - Extract expression/statement builders first. Keep tests (if any) colocated. + +- `src/mir/instruction.rs` (~896 loc) + - Near-term: introduce `mir/instruction/{mod.rs,core.rs,ops.rs,calls.rs}` without changing the enum surface. + - Medium-term: migrate to MIR13 (see below) and delete legacy variants. + +- `src/mir/optimizer.rs` (~875 loc) + - Split passes into: `mir/optimizer/{mod.rs,constant_folding.rs,dead_code.rs,inline.rs,type_inference.rs}`. + - Keep a simple pass runner that sequences the modules. + +- `src/runner/mod.rs` (~885 loc) + - Extract modes into `runner/modes/{vm.rs,jit.rs,mir_interpreter.rs,llvm.rs}` if not already, and move glue to `runner/lib.rs`. + - Centralize CLI arg parsing in a dedicated module. + +- `src/backend/vm_instructions/boxcall.rs` (~881 loc) + - Group by box domain: `boxcall/{array.rs,map.rs,ref.rs,weak.rs,plugin.rs,core.rs}`. + - Long-term: most of these become `BoxCall` handlers driven by method ID tables. + +## MIR13 Cleanup Plan + +A large portion of pre-MIR13 variants remain. Current occurrences: + +- ArrayGet: 11, ArraySet: 11 +- RefNew: 8, RefGet: 15, RefSet: 17 +- TypeCheck: 13, Cast: 13 +- PluginInvoke: 14, Copy: 13, Debug: 8, Print: 10, Nop: 9, Throw: 12, Catch: 13, Safepoint: 14 + +Phased migration (mechanical, testable per phase): + +1) Introduce shims + - Add `BoxCall` helpers covering array/ref/weak/map ops and plugin methods. + - Add `TypeOp::{Check,Cast}` modes to map legacy `TypeCheck/Cast`. + +2) Replace uses (non-semantic changes) + - Replace within: `backend/dispatch.rs`, `backend/mir_interpreter.rs`, `backend/cranelift/*`, `backend/wasm/codegen.rs`, `mir/printer.rs`, tests. + - Keep legacy variants in enum but mark Deprecated for a short period. + +3) Tighten verification/optimizer + - Update `verification.rs` to reason about `BoxCall/TypeOp` only. + - Update optimizer patterns (e.g., fold Copy → Load/Store; drop Nop/Safepoint occurrences). + +4) Delete legacy variants + - Remove `ArrayGet/Set, RefNew/Get/Set, PluginInvoke, TypeCheck, Cast, Copy, Debug, Print, Nop, Throw, Catch, Safepoint`. + - Update discriminant printer and state dumps accordingly. + +Use `tools/mir13-migration-helper.sh` to generate per-file tasks and verify. + +## Commonization Opportunities + +- Backend dispatch duplication + - `backend/dispatch.rs`, `backend/vm.rs`, and Cranelift JIT lowerings handle overlapping instruction sets. Centralize instruction semantics interfaces (traits) and keep backend-specific execution and codegen in adapters. + +- Method ID resolution + - `runtime/plugin_loader_v2` and backend call sites both compute/lookup method IDs. Provide a single resolver module with caching shared by VM/JIT/LLVM. + +- CLI/runtime bootstrap + - Move repeated plugin host init/logging messages into a small `runtime/bootstrap.rs` with a single `init_plugins(&Config)` entry point used by all modes. + +## Suggested Order of Work + +1. Split `mir/verification` and `mir/builder` into submodules (no behavior changes). +2. Add `BoxCall` shims and `TypeOp` modes; replace printer/dispatch/codegen uses. +3. Update verification/optimizer for the unified ops. +4. Delete legacy variants and clean up dead code. +5. Tackle `runner/mod.rs` and `backend/vm_instructions/boxcall.rs` splits. + +Each step should compile independently and run `tools/smoke_vm_jit.sh` to validate VM/JIT basics. + diff --git a/docs/development/roadmap/phases/phase-15/chatgpt5-nyrt-kernel-design.md b/docs/development/roadmap/phases/phase-15/chatgpt5-nyrt-kernel-design.md index 76079ef4..8c5aff87 100644 --- a/docs/development/roadmap/phases/phase-15/chatgpt5-nyrt-kernel-design.md +++ b/docs/development/roadmap/phases/phase-15/chatgpt5-nyrt-kernel-design.md @@ -121,7 +121,7 @@ void ny_root_remove(ny_handle h); - MIRの**Call統一**（進行中の`Call{callee: Callee}`方式）をLLVMでも厳守 - **型・スロットIDの決定をFrontend時点で確定**させ、**Codegenでは機械的に`ny_call_method(id)`を吐くだけ**にする -- Pythonルート（llvmliteハーネス）も同じABIに揃え、**NyRT名称のdeclareを撲滅**（`LLVM_HARNESS.md`の"NyRT shim"項を置換） + - Pythonルート（llvmliteハーネス）も同じABIに揃え、**NyRT名称のdeclareを撲滅**（`docs/reference/architecture/llvm-harness.md`の"NyRT shim"項を置換） ## GC設計（設計の要点） @@ -209,4 +209,4 @@ Kernelに残す。LLVMは**root/safepoint**を挿入するだけ。将来GC実 - **直接的継続**: プラグインファクトリー完成の自然な次段階 - **Phase 2.4候補**: Phase 2.3（builtin削除）の発展形 - **80k→20k削減**: 大幅なアーキテクチャ簡素化による寄与 -- **Everything is Plugin完全実現**: VM/LLVM統一設計の完成 \ No newline at end of file +- **Everything is Plugin完全実現**: VM/LLVM統一設計の完成 diff --git a/docs/comparison/nyash-vs-others.md b/docs/guides/comparison/nyash-vs-others.md similarity index 100% rename from docs/comparison/nyash-vs-others.md rename to docs/guides/comparison/nyash-vs-others.md diff --git a/docs/guides/examples/http_result_patterns.md b/docs/guides/examples/http_result_patterns.md index 1c73055c..8b071cba 100644 --- a/docs/guides/examples/http_result_patterns.md +++ b/docs/guides/examples/http_result_patterns.md @@ -29,4 +29,4 @@ tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json 関連ドキュメント - `docs/reference/architecture/mir-to-vm-mapping.md`（Result/Handleの取り扱い） -- `docs/VM_README.md`（VM統計・既知の制約） +- `docs/reference/architecture/vm.md`（VM統計・既知の制約） diff --git a/docs/how-to/self-hosting.md b/docs/how-to/self-hosting.md index 4ee14a4e..3eaa5b19 100644 --- a/docs/how-to/self-hosting.md +++ b/docs/how-to/self-hosting.md @@ -35,4 +35,4 @@ 関連 - CI: `.github/workflows/smoke.yml`（JSON/JUnit 出力は v2 ランナーで取得可能） -- マージ運用: `docs/CONTRIBUTING-MERGE.md` +- マージ運用: `docs/development/engineering/merge-strategy.md` diff --git a/docs/refactor-roadmap.md b/docs/refactor-roadmap.md index 7d86ed2d..e984c0b9 100644 --- a/docs/refactor-roadmap.md +++ b/docs/refactor-roadmap.md @@ -1,82 +1,5 @@ -# Nyash Refactor Roadmap (Pre–Self-Hosting) +# Moved: Refactor Roadmap -This document lists large modules, proposes safe splits/commonization, and outlines the MIR13 cleanup plan. - -## Large Modules to Split - -Targets are chosen by size and cohesion. Splits are incremental and build-preserving; move code in small steps and re-export in `mod.rs`. - -- `src/mir/verification.rs` (~965 loc) - - Split into: `mir/verification/{mod.rs,basic.rs,types.rs,control_flow.rs,ownership.rs}`. - - First move leaf helpers and pass-specific checks; keep public API and `pub use` to avoid churn. - -- `src/mir/builder.rs` (~930 loc) - - Split into: `mir/builder/{mod.rs,exprs.rs,stmts.rs,decls.rs,control_flow.rs}`. - - Extract expression/statement builders first. Keep tests (if any) colocated. - -- `src/mir/instruction.rs` (~896 loc) - - Near-term: introduce `mir/instruction/{mod.rs,core.rs,ops.rs,calls.rs}` without changing the enum surface. - - Medium-term: migrate to MIR13 (see below) and delete legacy variants. - -- `src/mir/optimizer.rs` (~875 loc) - - Split passes into: `mir/optimizer/{mod.rs,constant_folding.rs,dead_code.rs,inline.rs,type_inference.rs}`. - - Keep a simple pass runner that sequences the modules. - -- `src/runner/mod.rs` (~885 loc) - - Extract modes into `runner/modes/{vm.rs,jit.rs,mir_interpreter.rs,llvm.rs}` if not already, and move glue to `runner/lib.rs`. - - Centralize CLI arg parsing in a dedicated module. - -- `src/backend/vm_instructions/boxcall.rs` (~881 loc) - - Group by box domain: `boxcall/{array.rs,map.rs,ref.rs,weak.rs,plugin.rs,core.rs}`. - - Long-term: most of these become `BoxCall` handlers driven by method ID tables. - -## MIR13 Cleanup Plan - -A large portion of pre-MIR13 variants remain. Current occurrences: - -- ArrayGet: 11, ArraySet: 11 -- RefNew: 8, RefGet: 15, RefSet: 17 -- TypeCheck: 13, Cast: 13 -- PluginInvoke: 14, Copy: 13, Debug: 8, Print: 10, Nop: 9, Throw: 12, Catch: 13, Safepoint: 14 - -Phased migration (mechanical, testable per phase): - -1) Introduce shims - - Add `BoxCall` helpers covering array/ref/weak/map ops and plugin methods. - - Add `TypeOp::{Check,Cast}` modes to map legacy `TypeCheck/Cast`. - -2) Replace uses (non-semantic changes) - - Replace within: `backend/dispatch.rs`, `backend/mir_interpreter.rs`, `backend/cranelift/*`, `backend/wasm/codegen.rs`, `mir/printer.rs`, tests. - - Keep legacy variants in enum but mark Deprecated for a short period. - -3) Tighten verification/optimizer - - Update `verification.rs` to reason about `BoxCall/TypeOp` only. - - Update optimizer patterns (e.g., fold Copy → Load/Store; drop Nop/Safepoint occurrences). - -4) Delete legacy variants - - Remove `ArrayGet/Set, RefNew/Get/Set, PluginInvoke, TypeCheck, Cast, Copy, Debug, Print, Nop, Throw, Catch, Safepoint`. - - Update discriminant printer and state dumps accordingly. - -Use `tools/mir13-migration-helper.sh` to generate per-file tasks and verify. - -## Commonization Opportunities - -- Backend dispatch duplication - - `backend/dispatch.rs`, `backend/vm.rs`, and Cranelift JIT lowerings handle overlapping instruction sets. Centralize instruction semantics interfaces (traits) and keep backend-specific execution and codegen in adapters. - -- Method ID resolution - - `runtime/plugin_loader_v2` and backend call sites both compute/lookup method IDs. Provide a single resolver module with caching shared by VM/JIT/LLVM. - -- CLI/runtime bootstrap - - Move repeated plugin host init/logging messages into a small `runtime/bootstrap.rs` with a single `init_plugins(&Config)` entry point used by all modes. - -## Suggested Order of Work - -1. Split `mir/verification` and `mir/builder` into submodules (no behavior changes). -2. Add `BoxCall` shims and `TypeOp` modes; replace printer/dispatch/codegen uses. -3. Update verification/optimizer for the unified ops. -4. Delete legacy variants and clean up dead code. -5. Tackle `runner/mod.rs` and `backend/vm_instructions/boxcall.rs` splits. - -Each step should compile independently and run `tools/smoke_vm_jit.sh` to validate VM/JIT basics. +このドキュメントは移動しました。 +- 新しい場所: [development/refactoring/refactor-roadmap.md](development/refactoring/refactor-roadmap.md) diff --git a/docs/reference/abi/ABI_INDEX.md b/docs/reference/abi/ABI_INDEX.md index aac550be..043b5284 100644 --- a/docs/reference/abi/ABI_INDEX.md +++ b/docs/reference/abi/ABI_INDEX.md @@ -47,7 +47,7 @@ - パフォーマンス目標（33倍高速化） - 互換性維持戦略 -#### [PLUGIN_ABI.md](../../../PLUGIN_ABI.md) +#### [PLUGIN_ABI.md](PLUGIN_ABI.md) **プラグインABI概要** - 現在のTLVベース実装 - プラグイン開発ガイド @@ -131,4 +131,4 @@ if actual_size >= expected_size { - [Box設計哲学](../../development/architecture/box-externcall-design.md) - Box/ExternCall境界 --- -最終更新: 2025-09-12 \ No newline at end of file +最終更新: 2025-09-12 diff --git a/docs/reference/abi/PLUGIN_ABI.md b/docs/reference/abi/PLUGIN_ABI.md new file mode 100644 index 00000000..3a50905d --- /dev/null +++ b/docs/reference/abi/PLUGIN_ABI.md @@ -0,0 +1,23 @@ +# Plugin ABI (by-id / tagged) — Snapshot + +This summarizes the ABI surfaces used by LLVM in Phase 15. Details live in NyRT (`crates/nyrt`). + +## Fixed-arity by-id shims +- Integer-dominant: `i64 @nyash_plugin_invoke3_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 a2, i64 a3, i64 a4)` +- Float-dominant: `f64 @nyash_plugin_invoke3_f64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, f64 a1, f64 a2, f64 a3, f64 a4)` + +## Tagged shims (mixed types) +- Fixed (<=4 args): `i64 @nyash_plugin_invoke3_tagged_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i64 a1, i64 t1, i64 a2, i64 t2, i64 a3, i64 t3, i64 a4, i64 t4)` +- Vector (N args): `i64 @nyash.plugin.invoke_tagged_v_i64(i64 type_id, i64 method_id, i64 argc, i64 recv_h, i8* vals, i8* tags)` + +Tag codes (minimal): +- 3=int, 5=float, 8=handle(ptr). Others are reserved/experimental. + +## Return mapping (LLVM lowering) +- If destination is annotated as Integer/Bool → keep i64 as integer. +- If destination is String/Box/Array/Future/Unknown → cast i64 handle to opaque pointer for SSA flow; do not `inttoptr` where a C string is expected. + +## Notes +- These ABIs are used by both built-ins (nyrt) and plugins for consistency. +- The LLVM backend is the reference; other backends will be aligned later. + diff --git a/docs/reference/architecture/TECHNICAL_ARCHITECTURE_2025.md b/docs/reference/architecture/TECHNICAL_ARCHITECTURE_2025.md index 31490a69..d81a0209 100644 --- a/docs/reference/architecture/TECHNICAL_ARCHITECTURE_2025.md +++ b/docs/reference/architecture/TECHNICAL_ARCHITECTURE_2025.md @@ -6,7 +6,7 @@ This index points to the currently maintained architectural documents: - Execution Backends: reference/architecture/execution-backends.md - Lowering Contexts: ../../design/LOWERING_CONTEXTS.md - LLVM Layer Overview: ../../design/LLVM_LAYER_OVERVIEW.md -- VM Overview: VM_README.md +- VM Overview: vm.md - Cranelift AOT design: ../../design/backend-cranelift-aot-design.md Note: Some long-form papers reside under `private/papers/reference/architecture/`. diff --git a/docs/reference/architecture/dynamic-plugin-flow.md b/docs/reference/architecture/dynamic-plugin-flow.md index 5f8155cc..b11bd8de 100644 --- a/docs/reference/architecture/dynamic-plugin-flow.md +++ b/docs/reference/architecture/dynamic-plugin-flow.md @@ -115,4 +115,4 @@ Nyash Source ──▶ MIR (Builder) See also - `docs/guides/examples/http_result_patterns.md` - HTTPのResult挙動（unreachable/404/500）のE2E例 -- `docs/VM_README.md` - VM統計とプラグイン周りの既知制約 +- `docs/reference/architecture/vm.md` - VM統計とプラグイン周りの既知制約 diff --git a/docs/reference/architecture/execution-backends.md b/docs/reference/architecture/execution-backends.md index 021234e4..9c7bc0d7 100644 --- a/docs/reference/architecture/execution-backends.md +++ b/docs/reference/architecture/execution-backends.md @@ -5,4 +5,4 @@ For the full guide, see: Additional references: - ../../design/backend-llvm-implementation-guide.md -- VM_README.md +- vm.md diff --git a/docs/reference/architecture/llvm-harness.md b/docs/reference/architecture/llvm-harness.md new file mode 100644 index 00000000..84373787 --- /dev/null +++ b/docs/reference/architecture/llvm-harness.md @@ -0,0 +1,70 @@ +# llvmlite Harness（正式導入・Rust LLVM 対置運用） + +Purpose +- Python + llvmlite による高速・柔軟な LLVM 生成経路を提供（検証・プロトタイプと将来の主役）。 +- Rust/inkwell 経路と並走し、代表ケースで機能同値（戻り値・検証）を維持。 + +Switch +- `NYASH_LLVM_USE_HARNESS=1` でハーネス優先（LLVM バックエンド入口から起動）。 + +Tracing +- `NYASH_LLVM_TRACE_FINAL=1` を設定すると、代表コール（`Main.node_json/3`, `Main.esc_json/1`, `main` 等）を標準出力へ簡易トレースします。 + ON/OFF の最終 JSON 突合の補助に使用してください。 + +Protocol +- Input: MIR14 JSON（Rust 前段で Resolver/LoopForm 規約を満たした形）。 +- Output: `.o` オブジェクト（既定: `NYASH_AOT_OBJECT_OUT` または `NYASH_LLVM_OBJ_OUT`）。 +- 入口: `ny_main() -> i64`（戻り値は exit code 相当。必要時 handle 正規化を行う）。 + +CLI（crate） +- `crates/nyash-llvm-compiler` 提供の `ny-llvmc` は llvmlite ハーネスの薄ラッパーだよ。 + - ダミー: `./target/release/ny-llvmc --dummy --out /tmp/dummy.o` + - JSON→.o: `./target/release/ny-llvmc --in mir.json --out out.o` + - JSON→EXE（新規）: `./target/release/ny-llvmc --in mir.json --emit exe --nyrt target/release --out app` + - `--nyrt ` で `libnyrt.a` の位置を指定（省略時は `target/release`→`crates/nyrt/target/release` の順に探索） + - 追加フラグは `--libs ""` で渡せる（例: `--libs "-static"`） + - 既定のハーネススクリプトは `tools/llvmlite_harness.py`（`--harness` で上書き可）。 + +Quick Start +- 依存: `python3 -m pip install llvmlite` +- ダミー生成（配線検証）: + - `python3 tools/llvmlite_harness.py --out /tmp/dummy.o` + - NyRT（libnyrt.a）とリンクして EXE 化（例: `cc /tmp/dummy.o -L target/release -Wl,--whole-archive -lnyrt -Wl,--no-whole-archive -lpthread -ldl -lm -o app_dummy`）。 + +Wiring（Rust 側） +- `NYASH_LLVM_USE_HARNESS=1` のとき: + 1) `--emit-mir-json ` 等で MIR(JSON) を出力 + 2) `python3 tools/llvmlite_harness.py --in --out ` を起動 + 3) 成功後は通常のリンク手順（NyRT とリンク） + +Tools / CLI（統合フロー） +- crate 直結の EXE 出力: `NYASH_LLVM_COMPILER=crate NYASH_LLVM_EMIT=exe tools/build_llvm.sh apps/tests/ternary_basic.nyash -o app` + - 環境変数 `NYASH_LLVM_NYRT` で NyRT の場所を、`NYASH_LLVM_LIBS` で追加フラグを指定できる。 + - CLI から直接 EXE 出力（新規）: + - `./target/release/nyash --emit-exe tmp/app --backend mir apps/tests/ternary_basic.nyash` + - 追加オプション: `--emit-exe-nyrt ` / `--emit-exe-libs ""` + +Scope（Phase 15） +- 最小命令: Const/BinOp/Compare/Branch/Jump/Return（PHI は LLVM 側で合成） +- 文字列: NyRT Shim（`nyash.string.len_h`, `charCodeAt_h`, `concat_hh`, `eq_hh`）を declare → call +- NewBox/ExternCall/BoxCall: まずは固定シンボル／by-id を優先（段階導入） +- 目標: `apps/selfhost/tools/dep_tree_min_string.nyash` の `.ll verify green → .o` 安定化 + +Acceptance +- Harness ON/OFF で機能同値（戻り値/検証）。代表ケースで `.ll verify green` と `.o` 生成成功。 + +Notes +- 初版は固定 `ny_main` から開始してもよい（配線確認）。以降、MIR 命令を順次対応。 +- ハーネスは自律（外部状態に依存しない）。エラーは即 stderr に詳細を出す。 + +PHI Policy（要点） +- Phase‑15 の既定は PHI‑on。MIR 側で SSA `Phi` を生成し、ハーネスは incoming の検証と最終 IR への反映だけを行う。 +- レガシー互換のために PHI‑off が必要なケースでは `NYASH_MIR_NO_PHI=1` を明示してね（ハーネスは旧 edge-copy 互換ルートで補完する）。 +- 詳細と背景は `docs/reference/mir/phi_policy.md` を参照。 + +Schema Validation（任意） +- JSON v0 のスキーマは `docs/reference/mir/json_v0.schema.json` にあるよ。 +- 検証: `python3 tools/validate_mir_json.py `（要: `python3 -m pip install jsonschema`）。 + +Appendix: 静的リンクについて +- 生成 EXE は NyRT（libnyrt.a）を静的リンク。完全静的（-static）は musl 推奨（dlopen 不可になるため動的プラグインは使用不可）。 diff --git a/docs/reference/architecture/vm.md b/docs/reference/architecture/vm.md new file mode 100644 index 00000000..32aec0b8 --- /dev/null +++ b/docs/reference/architecture/vm.md @@ -0,0 +1,107 @@ +# Nyash VM 実行基盤ガイド（更新） + +- プラグインBox引数の最小対応を追加（TLV: BoxRef） +- TLVタグ: 1=Bool, 2=I32, 3=I64, 4=F32, 5=F64, 6=String, 7=Bytes, 8=Handle(BoxRef) + - BoxRefはプラグインBox参照（type_id:u32, instance_id:u32）を8バイトでエンコード + - ユーザー定義/複雑なBoxは当面一部非対応（toStringフォールバック）。標準Boxはプラグイン経由で統一 + +現状のルーティング（Plugin-First）: +- User-defined: MIR関数（{Box}.{method}/{N}) にCall化（関数存在時）。それ以外はBoxCall。 +- Plugin: BoxCall → PluginInvoke（method_idが解決可能）→ それ以外は名前解決で PluginHost.invoke_instance_method。 + +今後のタスク: +- VM側のfrom Parent.method対応（Builder/VM両対応） +- TLVの型拡張（Float/配列/BoxRef戻り値など） + +## 🧮 VM実行統計（NYASH_VM_STATS / JSON） + +VMは命令カウントと実行時間を出力できます。 + +使い方（CLIフラグ）: +```bash +# 人間向け表示 +nyash --backend vm --vm-stats program.nyash + +# JSON出力 +nyash --backend vm --vm-stats --vm-stats-json program.nyash +``` + +環境変数（直接指定）: +```bash +NYASH_VM_STATS=1 ./target/debug/nyash --backend vm program.nyash +NYASH_VM_STATS=1 NYASH_VM_STATS_JSON=1 ./target/debug/nyash --backend vm program.nyash +# 代替: NYASH_VM_STATS_FORMAT=json +``` + +出力は `total`（総命令数）, `elapsed_ms`（経過時間）, `counts`（命令種別→回数）, `top20`（上位20種）を含みます。 + +## 既知の制約とTips（VM×プラグイン） +- Netプラグイン（HTTP） + - unreachable（接続不可/タイムアウト）は `Result.Err(ErrorBox)`。 + - HTTP 404/500 は `Result.Ok(Response)`（アプリ側で `response.status` を確認）。 + - デバッグ: `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`。 +- FileBox + - `close()` は `Ok(Void)`。`match Ok(_)` で受けるか、戻り値を無視してよい。 +- Handle（BoxRef）戻り + - TLV tag=8（type_id:u32, instance_id:u32）。Loaderが返り値typeに対応する `fini_method_id` を設定し `PluginBoxV2` を構築。 + - `scope_tracker` がスコープ終了時に `fini()` を呼ぶ（メモリ安全）。 +- 大きいボディ/多ヘッダー/タイムアウト + - 逐次拡張中。異常時の挙動は上記Result規約に従う。実行ログと `--vm-stats` を併用して診断。 +- 反復タイムアウト: `local_tests/socket_repeated_timeouts.nyash` で `acceptTimeout/recvTimeout` の連続ケース確認 +- BoxCallデバッグ: `NYASH_VM_DEBUG_BOXCALL=1` でBoxCallの受け手型・引数型・処理経路（enter/fastpath/unified）・結果型をstderr出力 + - 例: `NYASH_VM_DEBUG_BOXCALL=1 ./target/release/nyash --backend vm local_tests/test_vm_array_getset.nyash` + +## 🔧 BoxCallの統一経路（Phase 9.79b） + +### method_id（スロット）によるBoxCall +- Builderが受け手型を推論できる場合、`BoxCall`に数値`method_id`（スロット）を付与。 +- 低スロットはユニバーサル予約（0=toString, 1=type, 2=equals, 3=clone）。 +- ユーザー定義Boxは宣言時にインスタンスメソッドへスロットを4番から順に予約（決定論的）。 + +### VMの実行経路（thunk + PIC） +- ユニバーサルスロット（0..3）はVMのfast-path thunkで即時処理。 + - toString/type/equals/cloneの4種は受け手`VMValue`から直接評価。 +- それ以外は以下の順で処理: + 1. Mono-PIC（モノモーフィックPIC）直呼び: 受け手型×method（またはmethod_id）のキーでホットサイトを判定し、 + `InstanceBox`は関数名キャッシュを使って `{Class}.{method}/{arity}` を直接呼び出す（閾値=8）。 + 2. 既存経路: `InstanceBox`はMIR関数へCall、それ以外は各Boxのメソッドディスパッチへフォールバック。 + +環境変数（デバッグ）: +```bash +NYASH_VM_DEBUG_BOXCALL=1 # BoxCallの入出力と処理経路を出力 +NYASH_VM_PIC_DEBUG=1 # PICヒットのしきい値通過時にログ +``` + +今後の拡張: +- 一般`method_id`（ユーザー/プラグイン）に対するvtableスロット→thunk直呼び。 +- PICのキャッシュ無効化（型version）と多相PICへの拡張（Phase 10）。 + - SocketBox（VM） + - 基本API: `bind/listen/accept/connect/read/write/close/isServer/isConnected` + - タイムアウト: `acceptTimeout(ms)` は接続なしで `void`、`recvTimeout(ms)` は空文字を返す + - 簡易E2E: `local_tests/socket_timeout_server.nyash` と `socket_timeout_client.nyash` + - Void 比較の扱い（VM） + - `Void` は値を持たないため、`Eq/Ne` のみ有効。`Void == Void` は真、それ以外の型との `==` は偽（`!=` は真）。 + - 順序比較（`<, <=, >, >=`）は `TypeError`。 + +## E2E 実行例（HTTPのResult挙動） + +代表ケースを `tools/run_vm_stats.sh` で実行できます。`--vm-stats-json` により命令プロファイルも取得可能です。 + +```bash +# 別ターミナルでサーバ起動 +./target/release/nyash local_tests/http_server_statuses.nyash + +# クライアント（別ターミナル） +tools/run_vm_stats.sh local_tests/vm_stats_http_ok.nyash vm_stats_ok.json +tools/run_vm_stats.sh local_tests/vm_stats_http_404.nyash vm_stats_404.json +tools/run_vm_stats.sh local_tests/vm_stats_http_500.nyash vm_stats_500.json + +# 到達不能（サーバ不要） +tools/run_vm_stats.sh local_tests/vm_stats_http_err.nyash vm_stats_err.json +``` + +期待されるResultモデル +- unreachable（接続不可/タイムアウト）: `Result.Err(ErrorBox)` +- 404/500 等のHTTPエラー: `Result.Ok(Response)`（アプリ側で `response.status` を評価） + +詳細: `docs/reference/architecture/mir-to-vm-mapping.md` と `docs/guides/examples/http_result_patterns.md` を参照。 diff --git a/docs/reference/plugin-system/externcall.md b/docs/reference/plugin-system/externcall.md new file mode 100644 index 00000000..31eb2348 --- /dev/null +++ b/docs/reference/plugin-system/externcall.md @@ -0,0 +1,25 @@ +# ExternCall Policy (Phase 15) + +## Allowed Interfaces (minimal set) +- `env.console.{log,warn,error,readLine}` +- `env.debug.trace` +- `env.system.{exit,now}` (if present) + +All other host interactions should go through BoxCall (NyRT or plugins). + +## Argument‑type‑based selection +- For `env.console.{log,warn,error}` and `env.debug.trace`: + - If the single argument is `i8*` (C string), call the C‑string variant: + - `nyash.console.log(i8*)`, `nyash.console.warn(i8*)`, `nyash.console.error(i8*)` + - `nyash.debug.trace(i8*)` + - Otherwise convert to `i64` and call the handle variant: + - `nyash.console.log_handle(i64)`, `nyash.console.warn_handle(i64)`, `nyash.console.error_handle(i64)` + - `nyash.debug.trace_handle(i64)` + +## Rationale +- Keeps the AOT string path fast and avoids accidental `inttoptr` of handles. +- Avoids adding broad implicit conversions in ExternCall; selection is local and explicit. + +## Non‑LLVM Backends +- VM, Cranelift JIT/AOT, and the interpreter may not implement this policy yet (not MIR14‑ready). LLVM is authoritative; other backends will align after stabilization. + diff --git a/tools/smokes/v2/profiles/quick/core/json_roundtrip_ast.sh b/tools/smokes/v2/profiles/quick/core/json_roundtrip_ast.sh index c55426d4..8878f04d 100644 --- a/tools/smokes/v2/profiles/quick/core/json_roundtrip_ast.sh +++ b/tools/smokes/v2/profiles/quick/core/json_roundtrip_ast.sh @@ -19,6 +19,12 @@ static box Main { samples.push("true") samples.push("false") samples.push("42") + samples.push("-0") + samples.push("0") + samples.push("3.14") + samples.push("-2.5") + samples.push("6.02e23") + samples.push("-1e-9") samples.push("\"hello\"") samples.push("[]") samples.push("{}") @@ -46,6 +52,12 @@ false [] {} {"a":1} +0 +0 +3.14 +-2.5 +6.02e23 +-1e-9 TXT )