言語: package（ディレクトリ単位のモジュール束）と可視性制御

[ryuichi1208]

目的

複数ファイルをまとめた package（ディレクトリ単位のモジュール束） を言語の一級構造として導入し、pub / private などの可視性で API 境界を制御できるようにする。

背景

現在の rw には「package 機能」に該当する 3 つのレイヤのうち 2 つしか issue が無い:

レイヤ	既存 issue
(a) モジュール = 1 ファイル単位の名前空間 + import	#11
(b) package = 複数モジュールをまとめた配布/可視性単位	本 issue
(c) パッケージマネージャ = 依存解決・lockfile	#57

(b) は #11 (import foo) の自然な延長で、Rust の mod/pub、Go のディレクトリ単位 package、Python の __init__.py、Java の package 宣言に相当する。stdlib (#33〜#43) を整理する際にも (b) の境界が無いと「どの関数を公開するか」「どの名前を re-export するか」を統一的に決められない。

スコープ

• package 宣言: ディレクトリ単位で 1 package とする規約（mypkg/foo.rw, mypkg/bar.rw で同一 package）。または明示的な package mypkg ヘッダ構文（要検討）
• 可視性キーワード: `pub` (or `export`) を関数 / 型 / 定数に付与。デフォルトは package-private
• package 内クロス参照: 同一 package 内のシンボルは可視性に関わらず参照可（Go と同じ規約）
• package 間参照: `import mypkg` で package 全体、`from mypkg import foo` で個別シンボル
• エントリポイント規約: `main` 関数を持つファイルがある package を "binary package"、それ以外を "library package" として扱う方針の明文化
• re-export 構文: package の入口ファイル（`mod.rw` or 同名ファイル等）から下位モジュールの公開 API を再エクスポートできるか（要検討）
• driver / irgen 側の対応: 複数ファイル + 可視性のシンボルテーブルを通せるようにする
• 診断: 可視性違反、未公開シンボル参照、循環 package 参照のわかりやすいエラー

非ゴール

• レジストリ・lockfile・依存解決 → tooling: パッケージマネージャ / プロジェクト manifest #57
• import 構文そのものとモジュール解決ロジック → 言語: import とモジュールシステム #11
• stdlib の物理ディレクトリ構成 → 別 issue で議論

設計検討メモ

• package 宣言方式の選択肢:
  1. 暗黙（Go 方式）: ディレクトリ = package。ファイルヘッダの宣言不要。シンプル
  2. 明示（Rust 方式）: `mod foo;` または `package foo` をヘッダに書く。リネーム耐性が高い
  3. ハイブリッド: ディレクトリ名を package 名のデフォルトにし、package 宣言で上書き可
• 可視性キーワード:
  • Python 慣習の "アンダースコア prefix で private" は弱い規約なので、コンパイラで強制したい
  • 候補: `pub fn` (Rust 風)、 `export def` (TS 風)、 大文字始まりで公開 (Go 風)
• テスト用 friend 可視性（例: `pub(crate)` 相当）が必要か → 当面は不要、必要になったら追加

関連

• 前提: 言語: import とモジュールシステム #11 (import / モジュールシステム)
• 連携: tooling: パッケージマネージャ / プロジェクト manifest #57 (パッケージマネージャ / manifest)
• 影響: stdlib: ファイル I/O (open / read / write / close) #33〜stdlib: filesystem path / dir 操作 #43 (stdlib) — package 境界が決まると stdlib 構造を確定できる

受け入れ基準（最低限）

• 2 つの `.rw` ファイルを 1 package としてまとめ、片方の関数からもう片方の関数を呼べる
• 同 package 内では `pub` の有無に関わらず参照できる
• 別 package から `pub` の付いた関数だけ `import` 経由で参照できる
• 未公開関数を別 package から参照すると分かりやすい診断エラーになる
• examples/ または tests/ にケースを追加