レポート: moonbit/ の modernize #

結論 #

• パッケージの構成と依存関係に問題はなく、局所的な書き換えを先にしたことで困ることはなかった。
• 公開 API は、ほぼ呼び出し側が必要とするものだけになっている。internal/ パッケージに分ける必要もない。
• skill の Intent にある「view 型でコピーを避ける」は、tinymarkdown にまだ余地がある。
• テストのカバレッジは 386/411 行。残りは主に worker（テストなし）と compare のエラー経路。公開 API に、doc コメント中のテスト（mbt check のコードブロック）はない。

パッケージ構成と依存関係 #

• 依存関係に循環はなく、上位のパッケージが下位を import する向きだけになっている。
• 規模は skill の目安（パッケージ 1 万行、ファイル 2 千行、関数 200 行）よりずっと小さい。一番長い関数は tinymarkdown の scan で 84 行。
• el、tinymarkdown、posts は、まだどのパッケージからも使われていない。site がこれらを使うのは TODO.md の「ブログを MoonBit で作り直す」の残りのステップで、移植の途中だから。
• そのため site には、el のエスケープと同じ役割の write_escaped が別にある。エスケープ結果も違い、" を el は Go の html.EscapeString と同じ " に、site は " にする。site を el で書き直せば、この重複はなくなる。
• バックエンドの切り替えは、どちらも moon.pkg の supported_targets で揃っている（worker は wasm-gc のみ、compare/cmd は native のみ）。ファイル名の接尾辞や #cfg は使っていない。

公開 API #

• site の Response::html、el の各ヘルパー、tinymarkdown の scan、nest、cells などは、すべてパッケージ内に閉じている。
• worker の path_push と serve は、Wasm から export するために pub が必要。
• compare の body_diff を使っているのは、compare 自身とテストだけ。pub を外すこともできる。ただしその場合、ブラックボックステストからは compare 経由でしか確かめられなくなる。skill はブラックボックステストを勧めているので、pub のままにした。
• el の const.mbt にある要素名や属性名（div、href など）は、ほとんどがまだ使われていない。HTML を組み立てる DSL の語彙なので、そのまま残す。
• 呼び出し元の洗い出しには moon ide find-references を使った。このコマンドは --target を付けないと moon.mod の preferred_target（wasm-gc）で解析する。そのため、native でしかビルドしない compare/cmd からの参照が出てこない。たとえば default_paths は、そのままだとテストの 1 件しか見つからず、--target native を付けて初めて compare/cmd/main.mbt の参照が見つかった。

view 型とコピー #

skill の Intent は「view 型（StringView など）でコピーを避ける」としている。 modernize のコミットでは、[:] を削り、strip_prefix の結果を view のまま扱うところまでで止めた。tinymarkdown には、まだ to_owned() が 9 箇所ある。

• trim_space は StringView を受け取るが、String を返す。cells(line : String) と code_text(s : String) も String を受け取るので、呼び出し側が先に to_owned() している。
• split_inlines と link は、Text、Code、Link に入れる部分文字列を切り出すたびにコピーしている。

Block と Inline は String を持つので、木に入れる時点でのコピーは必要になる。 減らせるのは、途中のヘルパーが String を受け取っているために起きるコピーで、cells と code_text が StringView を受け取るようにすれば減る。 ただ、tinymarkdown の目的は Go 版と同じ挙動の移植で、性能の問題もまだない。そのため手を付けていない。

テストとドキュメント #

moon test --enable-coverage の結果は 386/411 行。主な残りは次のとおり。

• worker（0/18 行）: host の import を呼ぶので、moon test では確かめられない。make dev と make compare で確かめている。
• compare（53/59 行）: 改行も > もない末尾の断片、\r と \t の表示、MoonBit 側だけの取得失敗。
• tinymarkdown/inline.mbt（71/72 行）: 1 行。

公開 API に、doc コメント中のテスト（mbt check のコードブロック）はない。 テストはすべて、Go のテストケースを移したブラックボックステスト（*_test.mbt）になっている。 modernize で変えた公開 API（compare のラベル、Response と Report の可視性）は README に書かれておらず、README を直す必要はなかった。

適用したもの #

当てはまらなかったもの、見送ったもの #

• **正規表現（lexscan、=~）:** tinymarkdown のインライン解析は、トークナイザとして書き直せる。ただし Go 版と同じ挙動の移植が目的で、書き直しが大きいので見送った。
• **<?、カスケード ..、ラベル付きブロック、[| .. |]、extenum、ローカル型、phantom type、ビット列パターン、defer / errdefer、suberror、#non_exhaustive、FFI の注釈:** どれも使う場面がなかった。
• **fn Type::Type:** 構築用の関数は、名前空間付きの Response::html しかない。
• **#as_free_fn:** 最初のパスでメソッドにした関数は、どれもパッケージ内に閉じていて、移行させる呼び出し元がない。
• **ReadOnlyArray / FixedArray:** prefer_readonly_array / prefer_fixed_array の警告は出なかった。
• **trim_space のローカルメソッド化:** StringView のメソッドにすると、String の値から呼ぶときに変換が要るので見送った。
• **| と > の行の判定:** 束縛する値がないので、has_prefix の方が読みやすい。
• **個人ポリシー「主要な引数以外はラベル付きにする」との差:** 最初のパスでは、el(name, children) の children のような、役割の明らかな第 2 引数を位置引数のまま残した（escape_to(sb, s) はメソッド sb.write_escaped(s) になり、self の直後は位置引数でよいという精緻化の側に入った）。個人ポリシーはこれもラベル付きにする側なので、方針が分かれている。el は HTML を組み立てる DSL で、ノードごとに children= が入ると読みにくいため、そのままにしている。
• **mbt check の doc テスト:** 「テストとドキュメント」の節のとおり、まだない。

気づいたこと #

• catalog の多くは、警告ではなく「この問題にはこの機能がある」という当たりを付けるための知識だった。今回適用した 8 種類は、どれも警告が出ない。
• 文字列パターンは Char 単位で進み、s[i] や s[n:] は UTF-16 のコード単位で数える。リテラルで判定する形（今回の [.. "- ", .. rest]、[' ', .. inner, ' ']）は、書き換えても結果が同じになる。一方、位置で数える形は変わる。s[2:] を [_, _, .. rest] にすると、BMP 外の文字が先頭にあるときに結果がずれ、警告も出ない。たとえば "😀ab" では、s[2:] は "ab"、パターンの rest は "b" になる（moon 0.1.20261012 で確認）。
• 配列への複合代入 items[i] += ".." も、今の toolchain で書けた。

結論 #

• 11 種類の書き換えを 12 コミット（for-in の分解は、拾い漏れを後から足したので 2 コミット）と、doc コメントの修正 1 コミットにした。挙動は変えていない。各コミットの前に moon fmt と moon info を実行し、make check（wasm-gc と native の moon check、moon test 59 件、.mbti の差分確認）を通した。
• opt-in の警告で見つかったのは unnecessary_annotation の 90 件（すべて @el.）だけで、方針どおり書き換えなかった。今回の書き換えも、すべて skill の catalog と grep、.mbti から見つけたもの。
• 公開 API が変わったのは picoel（引数のラベル）と site（Site::new → Site::Site、Site を抽象型に）だけ。

Step 0: 全体の構造の確認 #

skill の Step 0 に従い、moonbit-refactoring の「Local refactoring」より前の観点で、新しいパッケージを先に見た。

• 依存関係は worker → site → picoel / el / tinymarkdown / tinyfrontmatter / posts / repodocs / assets の一方向で、循環はない。
• site は 4 ファイル、約 1,100 行。links.mbt は Go の net/url と path の一部の移植を含むが、使うのは site だけなので、パッケージを分けるほどではない。
• 公開 API のうち、Site のフィールド（by_slug などの索引）は外から読まれていなかった。これは書き換えの 1 つとして Site を抽象型にした（9034696）。Post と Doc のフィールドはテストが読むので pub struct のまま。

構造を変える必要はなかったので、そのまま局所的な書き換えに進んだ。

コミットの一覧 #

方針を決めたもの #

1 回目のパスの方針（@pkg. は残す、ラベルは同じ型の引数が並ぶ箇所にだけ付ける、el の DSL の children は位置引数のまま）をそのまま使った。

• **ラベル:** picoel の a(href, children) や table(header, rows) は、引数の型が違うので取り違えようがなく、位置引数のままにした。
• **method の名前:** Doc にはフィールド path（/docs/ より下の URL のパス）があるので、ページの URL を返すメソッドは path ではなく page_path にした。Post::source は、Doc のフィールド source と同じ意味（リポジトリ内のファイルのパス）になるように付けた。

見送ったもの #

• **post_list と doc_list の push のループ。** 内包表記にすると [h1, ..[for p in posts => { .. }]] と入れ子が深くなり、元のループより読みにくかった。一度書き換えてから戻した。
• **ogp のメソッド化。** 引数は呼び出し側で組み立てたレコード（{ ..meta, title, description }）で、メソッドにするとレコードリテラルにメソッドを続ける形になる。
• **render_blocks の bs.map(b => ..)。** 内包表記と同じ意味で、書き換えても読みやすさは変わらない。
• **テストの複数行の文字列を #| にすること。** Go のテストケースの文字列をそのまま移しているので、Go 版と見比べやすい今の形にした。
• **worker の put_string の添字のループ。** UTF-16 のコード単位を 1 つずつ host に渡すという意図が、添字のループで一番はっきり読める。

気づいたこと #

• **2 部形式の functional-for（for i = 0; cond; { .. }）で、本体の末尾まで continue なしで落ちると、状態を変えないまま次の周回に入る。** ほかの分岐に continue e が 1 つでもあれば警告は出ず、無限ループになる（どこでも更新しないときだけ unused_loop_variable の警告が出る）。split を書き換えたとき、本体の最後に continue next, lineno + 1 を置いたのはこのため（moon 0.1.20261012 で確認）。
• **UInt16 の値にも、Char のリテラルの範囲パターン（'0'..<='9'）がそのまま使える。** s[i] == '%' と同じく、リテラルの型が UInt16 として推論される。hex_value は to_char() を挟まずに書けた。
• **ラベル付きの引数を持つ関数は、ローカル変数に束縛して呼べない。** let prop = @picoel.meta_property の後に prop(.., content=..) と書くと、エラー 4117「Function with labelled arguments can only be applied directly」になる。ogp は @picoel.meta_property(..) を直接呼ぶ形にした。
• **内包表記の for も、for-in と同じくタプルのパターンを取れる。** [for (name, _) in @posts.files => name] と書けた。
• **for-in の分解は、1 つのコミットで拾い切れなかった。** 最初の grep は for c in xs { の次の行の let (..) = c だけを探していて、本体で c.0 を直接読む形を見落とした。[^a-zA-Z_.][a-z_]+\.[0-9]\b で探し直して見つけた。

適用したもの #

どのコミットも、make check と moon check --target all --deny-warn を通した（テストは 60 件）。

当てはまらなかったもの、見送ったもの #

• **使う場面がなかった:** defer / errdefer、<?、ラベル付きブロック、[| .. |]、ビット列パターン、or-pattern の with、extenum、ローカル型、phantom type、using、#as_free_fn、#non_exhaustive。
• **lexscan による tinymarkdown のインライン解析の書き直し:** 1 回目のパスと同じく、書き直しが大きいので見送った。
• **Post と Doc の一部のフィールドを priv にすること:** 外から読まれていないフィールドもあるが、読み取り専用のデータとして公開しておく方が自然なので見送った。
• **個人ポリシー「主要な引数以外はラベル付きにする」:** el / picoel の DSL の子要素は位置引数のまま、という 1 回目のパスの方針を変えていない。
• **表形式のテストケースの #| 化:** 1 行に 1 ケースを並べた方が入力を見比べやすいので、#| にしたのは文書まるごとのフィクスチャだけ。

気づいたこと #

• **=~ のコストは小さかった。** release の worker.wasm は 234,123 バイトから 234,164 バイトになり、41 バイトしか増えなかった。
• **Map パターンの値の位置には、値そのものを書く。** { "title": Some(t) } と書くと型エラー（4014）になり、{ "title": t, .. } と書く。
• **suberror の impl Show で、logger <+ message は parse error になる。** skill の Pitfalls にあるとおり、<+ の右辺はテンプレート文字列でなければならない。logger.write_string(message) と書いた。Show のメソッドにも警告 implicit_impl_as_method が出るので、pub extend .. with Show::{to_string, output} も足した。
• **カスケードの最後の呼び出しを .. にすると、警告 deprecated_syntax が出る。** 結果を黙って捨てることになるため。最後だけ . にする。
• **doc コメントの mbt check の例は、moon test のテストとして数えられる。** 期待値をわざと壊すと失敗することも確かめた。
• **moon fmt は、タプルの中の #| のブロックを括弧で包む。** 値は元の \n を使った文字列と同じで、最後の行の後に改行は付かない。一時的なテストで、元のリテラルと等しいことを確かめた。
• **作業の途中まで、検証用のスクリプトが警告を見落としていた。** make check の moon check は --deny-warn を付けていないので、警告があっても失敗しない。途中から、警告が出たら失敗するようにスクリプトを直した。直した後のスクリプトで、HEAD に警告がないことを確かめた。

handbook に戻したもの #

podhmo/moonbit-individual-handbook#64 に draft として出した。

2 回目のパスで得たものは、次の 3 つ。

• 更新節のない 2 部形式の functional-for で、continue を書き忘れた経路があると、警告なしで無限ループになるという Pitfall。
• UInt16 のコード単位にも、Char のリテラルの範囲パターンが使えること。
• 内包表記もタプルのパターンを取れること。c.0 / c.1 を読む形も、for-in の分解の候補になること。

このパスからは、初めて読む人にも読みやすく、コードの意味もはっきりする 2 つを、moonbit-modernize の Step 2 に足した。

• 文字列の形を確かめるだけのループを、正規表現 =~ に。
• 文書まるごとの \n 入りのリテラルを、#| に。

ほかは次の理由で入れていない。

• Map パターンとカスケード: 元の書き方より読みやすくならないか、初見で分かりにくい規則がある。
• suberror の impl Show、インラインテスト、mbt check: 設計やテスト方針の判断を含むので、カタログと個人ポリシーの側に置いたままにした。

結論 #

• Step 0 の構造の確認で公開 API を 2 コミット分減らし、そのあと 12 種類の書き換えを 1 コミットずつ適用した。挙動は変えていない。各コミットで moon fmt、wasm-gc と native の moon check --deny-warn、moon test、moon info を通し、最後に make check と、Node 上で実際の Wasm を動かす make test-echo（9 件）も通した。テストは 76 件から 77 件になった。
• 対象はほぼ pkg/http と pkg/http/wasm だった。tinymarkdown の入れ子のリスト（nest_items）など、ほかに加わったコードは、すでに functional-for や内包表記で書かれていた。
• opt-in の警告で見つかったのは unnecessary_annotation の 188 件（wasm-gc と native で重複して数えた件数）だけで、方針どおり書き換えなかった。
• 公開 API の変更は http（constructor の名前、value~ のラベル、BadRequest の payload、parse_multipart を非公開に）と http/wasm（decode_request と encode_head を非公開に）。pkg.generated.mbti の diff がそのまま API の変更点になっている。docs/sketch/ja/moonbit-workers-http.md の API の一覧も合わせて直した。
• release の Wasm（wasm-opt 後）は、ブログの app.wasm が 330,935 バイトから 331,067 バイトに、echo の echo.wasm が 92,613 バイトから 92,750 バイトになった（どちらも 140 バイト弱の増加）。

Step 0: 全体の構造の確認 #

今回は Step 0 を省かずに行い、構造の問題があればコミットとして直すことにした。

• **パッケージの大きさ:** どのパッケージも 1,000 行前後以下、関数も 200 行を大きく下回る。分ける必要はない。
• **依存関係:** pkg/ の下のパッケージは examples/ を参照しない。examples/blog/worker → site → pkg/* と、examples/echo → pkg/http/wasm → pkg/http の一方向で、循環はない。
• **公開 API:** moon ide の代わりに grep で pub の呼び出し元を数えた（native 専用の compare/cmd も含めるため）。
  • http/wasm の decode_request と encode_head は、パッケージの外からはテストしか呼んでいなかった。アプリが使うのは handle だけなので、非公開にし、テストを white-box テストにした（63a7e68）。
  • http の parse_multipart は Request::form からしか呼ばれていなかったので非公開にした（c79bfd0）。
  • media_type と parse_values も外からはテストしか呼ばないが、Go の mime.ParseMediaType と url.ParseQuery に当たる汎用の部品で、ハンドラが自分で Content-Type やクエリを読むときに使えるので公開のままにした。
• **experiments/:** 別のモジュールで、計測を再現するためのスパイクなので、skill の判断基準（古い形そのものが目的のコードは書き換えない）に従って書き換えの対象から外した。ただし moon.work でこのモジュールを今の API のまま import しているので、API を変えた結果、wasm-fetch の @http.Router::new() が通らなくなった。README の「今の API に合わせる必要のあるところだけ直す」に従い、constructor のコミットで @http.Router() に直した。

コミットの一覧 #

方針を決めたもの #

• **ラベル:** これまでのパスと同じく、同じ型の引数が並ぶ箇所にだけ付けた。Response::text(status, body) や Router::handle(pattern, handler) は型が違うので位置引数のまま。Response::typed(status, content_type, body) も、Body の値が Text(..) / Binary(..) と書かれるので、content_type との取り違えは型で分かる。
• **constructor の呼び出し:** skill のとおり @http.Router() と型名だけで書く。doc コメントとテスト名は Router::Router と書いた。Site の private なメソッド Site::new_router は「新しい router を作る」という意味の名前なので、そのままにした。

• **破壊的更新は Unit を返し、カスケード .. でつなぐ。** Response::header は self.headers に push してから同じ self を返していたので、新しい値を返すように読めた（let b = a.header(..) で a も変わる）。新しい値を返すにはヘッダの配列を毎回複製する必要があり、ハンドラの中で 1 回組み立てるだけの使い方には合わないので、-> Unit にした。-> Self のメソッドを .. でつなぐと、警告 invalid_cascade が出る。この書き換えは、パスの後のレビューで指摘を受けて足した。

見送ったもの #

• **decode_request の、ヘッダと env を分けるループ。** let mut in_env が 1 つだけで、functional-for にするとすべての経路の最後に continue in_env を書くことになる。最初の空行の位置で配列を分ける書き方も考えたが、空行が必ず 2 つあることを読み手が知っていないと追えない。
• **Router::handle のセグメントの組み立て。** 最後の空のセグメントは subtree を立てるだけで、配列には入らない。内包表記にすると、この特別扱いが別の場所に分かれる。
• **Route::match_path の末尾の if / else if の連鎖。** 3 つの条件が別々のものを見ているので、match にしても読みやすくならない。
• **Headers::get と Values::get の return するループ。** find_first(..).map(p => p.1) と書けるが、for-in の分解で名前の付いた今の形の方が読みやすい。
• **echo の form.files.map(f => { .. })。** 2 回目のパスの render_blocks と同じく、内包表記にしても読みやすさは変わらない。
• **Map([])。** let params : Map[String, String] = {} と書けるが、型の注釈が増えるだけ。

気づいたこと #

• **文字列の for-in は、サロゲートペアを 1 つの Char にまとめ、孤立したサロゲートはそのまま 1 つの Char として返す。** write が手で行っていた処理と同じ結果になる（孤立した U+D800 は ED A0 80 の 3 バイトになる）。white-box テストで、書き換えの前と後の両方で確かめた（moon 0.1.20261012）。
• **3 部形式の functional-for の条件に、本体の先頭の break を移せる。** parse_multipart は while true の先頭で -- を見て抜けていたので、for pos = ..; !body[pos:].has_prefix(b"--"); { .. } と書けた。本体の最後の continue next_pos を忘れると、2 回目のパスの Pitfall と同じく警告なしで無限ループになるので、名前のないパートを飛ばす continue の経路にテストを足した。
• **match の一方の腕がビューのとき、もう一方の腕の url[:] には unnecessary_view_op が出る。** 期待される型がビューになるので、url だけでよい。
• **experiments/ は、ルートの moon check にも make check にも入らない。** 最初はこれに気づかず、全体を検証した後に README を読んで wasm-fetch が壊れていることを見つけた。moon.work でこのモジュールを参照する別のモジュールがあるときは、公開 API を変えたら、その中でも moon check を実行する必要がある。その後、make check が experiments/ の各モジュールでも moon check を実行するようにした。
• **作業の途中まで、検証用のスクリプトが moon check の失敗を見落としていた。** 出力を tail に渡していたので、set -e があっても失敗が伝わらなかった。上の警告で気づき、pipefail を付けて直した。それより前のコミットは、出力に警告もエラーもなかったことを確かめてある。