メモ: どこに何を置くか #

このリポジトリで、コードやテストをどこに置くと後で分かりやすいか、なぜそうするかのメモ。言語には依らないので、新しい言語の実装 foo/ を足すときの目安にもなる。例には moonbit/ を使う（go/ も pkg/、examples/、Makefile は同じ形で、experiments/ はまだない）。

守るべき規則ではない。数か月後の自分が見て、どこに何があるか分かれば十分。作業の途中は散らかっていてかまわない（moonbit/ も、ブログを移植している間はモジュールの直下にパッケージが並んでいた）。落ち着いたところで、ここに書いた形に寄せる。

新しい言語を足すときの目安 #

foo/
  README.md      何がどこにあるか、どう動かすか
  Makefile       言語の道具の外にあるものをつなぐ糊（build、test、check）
  pkg/           ライブラリ。保守対象
  examples/      アプリ（ブログなど）。保守対象
  experiments/   実験。保守対象のモジュールの外に置き、そちらから参照する

言語の道具がモジュールやパッケージを持つなら、foo/ を 1 つのモジュールにし、pkg/ と examples/ をその中のパッケージにすると分かりやすい。実験は別のモジュールにしておく。
テストのための部品（スタブのアプリ、フィクスチャ）は、テストされる側の隣にあると探しやすい（後述）。
Makefile のターゲットの意味が言語ごとにそろっていると、どの実装でも同じつもりで make check を実行できる（後述の表）。
その言語の道具に合わないところは、合わせなくてよい。気づいたことがあれば、この文書に書き足す。

置き場所は「誰が、どれくらい長く使うか」で決める #

コードを 3 種類に分けて考えると、置き場所が決めやすい。

種類	置き場所（`moonbit/`）	保守	テスト	公開 API
ライブラリ	`pkg/`（`el`、`picoel`、`tinymarkdown`、`tinyfrontmatter`、`http`、`http/wasm`）	する	常に走らせる	ほかから使われるので、必要なものだけに絞る
アプリ	`examples/blog/`（`site`、`worker`、`compare` など）	する	常に走らせる	ほかから使われないので、ほとんど要らない
実験	`experiments/`（`adapter-abi`、`wasm-fetch`、`http-bench`）	しない	走らせない。ビルドできることだけを確かめる	要らない

ライブラリとアプリは保守対象で、変更のたびにテストを走らせる。
実験は突発的な探索で、計測の数字を再現できるように残しているだけ。古い形のままであることに意味があるので、整えたり書き直したりしない。ただし、ビルドできなくなったら直す。
迷ったら「これが壊れたとき、誰が困るか」を考える。誰も困らないなら実験、ほかのコードが困るならライブラリ、使う人が困るならアプリ。

依存は一方向にする #

依存は、実験 → アプリ → ライブラリの向きにだけ張っておくと、どこを直すと何が壊れうるかが追いやすい。

pkg/ の下は examples/ を参照しない。
実験は、保守対象のモジュールの外に別のモジュールとして置き、実験の側から参照する。moonbit/ では、実験ごとに moon.mod を置き、moon.work でブログのモジュール（../..）をメンバーにしている。保守対象のモジュールは実験の存在を知らない。
このため、保守対象のモジュールで moon check を実行しても、実験は見えない。公開 API を変えると、気づかないうちに実験が壊れることがある。実際、Router::new を Router::Router にしたときに wasm-fetch が壊れ、全体の検証の後まで気づかなかった。そこで make check が、実験の各モジュールでも moon check を実行する。
実験を保守対象と同じワークスペースに入れる（ルートに moon.work を置く）と、moon check だけで実験も見える。ただし、ふだんの moon test やリリースのビルドにも実験が混ざる。依存の向きを優先して、そうしていない。

テストのための部品は、テスト対象の隣に置く #

名前は形ではなく役割で付け、置き場所も役割で決めておくと、後から見たときに何のためのものか分かる。

pkg/http/wasm/integration/ は、http/wasm の integration test。echo.mbt は受け取った要求をそのまま返すスタブのアプリで、test.mjs がそれを Node で adapter.mjs 越しに動かす。JS と Wasm の線形メモリの間の受け渡しを確かめているのは、このテストだけ。ブログの Worker も同じ経路を通る。
最初は examples/echo という「使用例」として置いていた。ただ、日常的に使うツールでも、一度きりの例でもなく、実態はテストの部品だった。そこで、テスト対象の pkg/http/wasm の下に移した。
スタブは本番のビルドに入れない。最適化（wasm-opt）も要らない。make test は moon の出力をそのまま読む。

公開するものは、呼ばれているものだけにする #

パッケージの外からテストしか呼ばない関数は、API ではない。非公開にして、テストは white-box テスト（_wbtest.mbt）にする。http/wasm の decode_request と encode_head がこれに当たった。アプリが使うのは handle だけ。
汎用の部品として外から使われうるものは、今は呼ばれていなくても残す。http の media_type と parse_values は、Go の mime.ParseMediaType と url.ParseQuery に当たる。
一覧は pkg.generated.mbti で見る。make check は moon info の差分で止まるので、公開 API の変更は diff に出る。

言語の道具と、それを補う糊 #

パッケージとモジュールの扱いは、言語の道具（moon、go）に任せる。一部だけ動かすときは、moon test -p podhmo/html-sandbox/pkg/http のように言語の道具を直接使う。
make は、言語の道具の外にあるものをつなぐ一時的な糊。moonbit/ では、Static Assets に置く記事と文書のコピーと目録（content）と、テスト用の埋め込みの生成（embed）、wasm-opt、Node でのテスト、wrangler が当たる。
make のターゲットは保守対象の全体を扱う。

ターゲット	内容
`make build`	配備するものだけ（ブログの Worker）をビルドし、wasm-opt をかけ、Static Assets に置く記事と文書をコピーする
`make test`	保守対象のテストをすべて走らせる（`moon test` と、Node での integration test）
`make check`	コミットの前の簡易チェック。`make test` に加えて、fmt、check（wasm-gc と native）、実験のビルド、`.mbti` の差分

make で何かを補う必要が出たら、まず構成を疑う。たとえば一時期、make test が実験の各モジュールでも moon test を実行していたので、ブログのテストが 3 回走った。実験は moon.work でブログを含むので、実験の中の moon test はブログのテストも走らせる。実験はテストせず、ビルドだけを確かめる、という区別がないまま糊で補おうとした結果だった。

名前は、持っているものに合わせる #

モジュールがブログ以外のライブラリも持つようになったので、モジュール名を podhmo/blog から podhmo/html-sandbox に変えた。パッケージのパスも podhmo/blog/examples/blog/site のような重なりがなくなり、podhmo/html-sandbox/examples/blog/site になった。

見直すきっかけ #

次のことが起きたら、置き場所か依存の向きを見直す頃合い。

make が同じ処理を何度も実行している、あるいは言語の道具でできることを make が代わりにしている。
検証を通っているのに、何かが壊れている。
「例」や「ツール」と呼んでいるものが、実際にはテストからしか使われていない。
パッケージの外からテストしか呼ばない pub がある。