[Codex] Consolidate Pytra automation TODO fixes

[yasufumi-nakata]

概要

統合状況

大元向け PR はこの PR に一本化しました。この PR は #6 と #7 の範囲を包含し、その後の Go selfhost fixture/sample parity、Top100 coverage、automation 更新まで含む統合版です。旧 PR #6 / #7 はレビュー導線を一本化するため close 済みです。

この PR は Pytra の継続拡張ブランチです。自動化 TODO / Top100 coverage / devcontainer gate の整理に加えて、Go emitter を Go で selfhost したバイナリが fixture と sample を実際に再変換・実行し、Python 正本と parity 一致するところまで進めました。

今回の更新で P7-GO-SELFHOST-RT-S1 から S5 までを完了扱いにしています。Go selfhost は fixture 161/161 PASS、sample 18/18 PASS です。

主な変更

• Go selfhost build entry を Go emitter CLI に寄せ、selfhost binary が emit/go を含む実 emitter として動く経路を整備しました。
• src/toolchain/emit/go/cli.py を selfhost 用の最小 CLI として強化し、manifest 入力、単体 EAST3 JSON 入力、runtime copy、Go target 制限を扱えるようにしました。
• Go emitter の型推論と lowering を拡張しました。
  • isinstance narrowing、None 判定、union / container narrowing を selfhost 実行でも崩れない形に調整。
  • Path, deque, zip, sum, min, max, time.perf_counter, math.* などの戻り型・builtin lowering を補強。
  • typed list/set/dict literal、tuple call result、dataclass field order、method receiver typing、true division を Go の型制約に合う形へ修正。
• Go runtime の container bridge を補強し、py_to_list_typed などが selfhost 生成コードから typed wrapper へ戻れるようにしました。
• Go 1.19 でも通るよう、Go runtime の map clear を clear() builtin ではなく delete loop に戻しました。
• _png_append / _gif_append 型の bytearray-mutating helper を Go では戻り値で受けるようにし、PNG/GIF artifact-size parity を解消しました。
• Linker/type-id、selfhost parity runner、Go emitter helper 検出、Top100 generator の回帰テストを追加・更新しました。
• Top100 coverage generator と生成物を更新し、Go selfhost fixture/sample PASS と次段の stdlib sweep を matrix に反映しました。
• Pytra automation は毎時・日本語・隔離環境検証ルール付きで ACTIVE に戻しています。

根本原因

Go selfhost runtime は、Python emitter 実行時には曖昧なままでも通っていた JsonVal / any / container の型境界を、生成 Go の compile/run 時に厳密に踏み抜いていました。特に list[unknown] へ広がる comprehension、constructor 戻り値が any になる runtime import、tuple-return call の Go 表現、Path / str、deque()、sum(zip(...))、true division、min/max が複合して fixture parity を止めていました。

sample 側では compile/run blocker を解消した後、PNG/GIF の artifact-size mismatch が残っていました。原因は Go slice が値渡しであるにもかかわらず、Python の dst.extend(src) 型 helper を副作用だけの関数として Go に落としていた点でした。helper を []byte 戻り値として扱い、呼び出し側で dst = helper(dst, src) と受けることで Python 正本と同じ byte 列になりました。

検証

• python3 -m py_compile src/toolchain/emit/go/emitter.py tools/gen/gen_top100_language_coverage.py tools/unittest/toolchain2/test_linker_spec_conform2.py tools/run/run_selfhost_parity.py
• python3 -m unittest tools.unittest.toolchain2.test_go_selfhost_ifexp_typing tools.unittest.toolchain2.test_go_emitter_cli_selfhost
• python3 -m unittest tools.unittest.toolchain2.test_linker_spec_conform2.Toolchain2LinkerSpecConform2Tests.test_go_emitter_returns_mutated_bytearray_helpers
• python3 -m unittest tools.unittest.selfhost.test_run_selfhost_parity.RunSelfhostParityBuildTest.test_build_selfhost_binary_go_uses_go_emitter_cli_entry
• python3 -m unittest tools.unittest.tooling.test_gen_top100_language_coverage
• Go selfhost binary rebuild via tools.run.run_selfhost_parity._build_selfhost_binary("go")
• python3 tools/run/run_selfhost_parity.py --selfhost-lang go --cmd-timeout-sec 300 => fixture 161/161 PASS
• python3 tools/run/run_selfhost_parity.py --selfhost-lang go --case-root sample --all-samples --cmd-timeout-sec 300 => sample 18/18 PASS
• python3 tools/gen/gen_top100_language_coverage.py && python3 tools/gen/gen_top100_language_coverage.py --check
• git diff --check

残件

• Go selfhost は次に stdlib sweep を追加して、fixture/sample に続く runtime coverage を固定します。
• C++ sample sweep は別系統で 7/18 PASS のままです。artifact CRC、object 型漏れ、min / max / enumerate fallback が残っています。
• Dart / Zig CLI は Top100 matrix 上では隔離環境への追加が次アクションです。

[yasufumi-nakata]

補足説明です。PR 本文にも概要は書いていますが、差分が 65 files / +7796 / -682 と大きめなので、レビュー時に「どこで何を直したのか」を追いやすいよう、やや細かめに分解して書きます。

この PR の位置づけ

この PR は、個別に出していた #6 / #7 相当の変更を一本化した統合 PR です。単一の小修正ではなく、Pytra の多言語 backend 作業を進めるための足場整備、host emitter の再接続、Top100 coverage の可視化、Go selfhost parity の実測更新をまとめています。

最終的な主眼は、Go emitter を Python 実装から生成するだけでなく、Go で selfhost した emitter binary が実際に fixture と sample を再変換し、その出力が Python 正本と一致する状態まで持っていくことです。今回の到達点として、Go selfhost は fixture 161/161 PASS、sample 18/18 PASS になりました。

大きく何をしたか

1. devcontainer / Docker で隔離された多言語検証環境を追加しました。
2. pytra-cli.py の target 正規化と build / emit の dispatch を整理しました。
3. runtime EAST キャッシュ再生成を専用 tool に分離しました。
4. Dart / Zig / PowerShell / Lua / Ruby / C++ まわりの host emitter や runtime bridge を補強しました。
5. Go emitter と Go runtime を大きく拡張し、selfhost fixture / sample parity を通しました。
6. Top100 language coverage の生成器と日本語・英語の進捗 docs を追加しました。
7. 上記を守るための unit / parity / generator tests を追加・更新しました。

1. devcontainer と隔離検証環境

.devcontainer/ 配下を新規追加しています。目的は、Pytra の backend 作業が C/C++、JVM、Mono、PHP、Lua、Node.js、Go、Rust、.NET、PowerShell、Ruby など複数 runtime に依存しているため、ホスト環境の偶然の PATH やローカルインストール状態に依存しない検証面を作ることです。

追加した主なものは以下です。

• .devcontainer/Dockerfile
• .devcontainer/devcontainer.json
• .devcontainer/scripts/verify-toolchain.sh
• .devcontainer/README.md

Dockerfile では Python 3.12 系をベースに、Pytra の backend / runtime parity で必要になる主要 toolchain をまとめて入れています。verify-toolchain.sh は、コンテナ作成後に python3, pytest, gcc, g++, clang, cmake, ninja, java, javac, mono, mcs, php, lua, node, npm, tsc, go, rustc, cargo, dotnet, pwsh, ruby などを一括確認します。

Swift は Linux devcontainer では重いので optional 扱いにしており、標準 devcontainer には入れていません。Dart / Zig も今回の matrix 上では「host 生成は進んだが native CLI は未導入」という blocker として明示しています。

2. CLI / build pipeline の整理

src/pytra-cli.py では、build / emit の target handling を少し整理しました。特に ps1 / powershell と js / ts のように、ユーザー向け target 名と内部 lowering / build profile 名がずれるケースを明示的に扱うようにしています。

具体的には、以下のような方向です。

• _EMIT_TARGETS と _BUILD_TARGETS を分け、emit 可能な target と build 可能な target を明確化しました。
• _build_profile_target() で js -> ts、powershell -> ps1 のような lowering / linker 側 target を正規化します。
• _emit_dispatch_target() で ps1 -> powershell のような emitter dispatch 側の target を正規化します。
• unsupported target の error message に available target 一覧を出すようにしました。
• subprocess emitter 経路にも正規化済み target を渡すようにしました。

この変更により、CLI 上の表記ゆれで build が落ちる問題を減らし、PowerShell 系や JS/TS 系の扱いを tests で固定しやすくしています。

3. runtime EAST 再生成 tool の分離

tools/gen/regenerate_runtime_east.py を追加しました。以前は runtime EAST の再生成が check_east3_golden.py --check-runtime-east --update に寄っていましたが、fresh checkout や devcontainer 初期化時に「runtime EAST を作る」作業だけを明示的に行えるように分離しています。

あわせて、以下の docs / metadata も更新しています。

• .gitignore の runtime EAST 再生成コマンド説明
• docs/ja/spec/spec-setup.md
• docs/ja/spec/spec-tools.md
• docs/ja/spec/spec-tools-daily.md
• tools/README.md

これで、clone 直後の bootstrap 手順として PYTHONPATH=src python3 tools/gen/regenerate_runtime_east.py を案内できます。

4. host emitter / 多言語 runtime 側の補強

Go selfhost が主役ではありますが、周辺の host emitter と runtime も直しています。

Dart / Zig では、C++ emitter を Dart / Zig host として生成する流れで詰まっていた tuple unpack / multi assign 系の処理を補強しました。src/toolchain/emit/dart/cli.py、src/toolchain/emit/dart/emitter.py、src/toolchain/emit/zig/cli.py、src/toolchain/emit/zig/emitter.py などが対象です。これに対応する regression として test_tuple_unpack_emitter_hosts.py、Dart / Zig smoke tests も更新しています。

PowerShell では、CLI runtime copy と runtime mapping / native helper を補強しました。src/runtime/powershell/mapping.json、src/runtime/powershell/std/json_native.ps1、src/runtime/powershell/std/pathlib_native.ps1、src/toolchain/emit/powershell/cli.py、src/toolchain/emit/powershell/emitter.py が主な対象です。dataclass field default の regression として tools/unittest/emit/powershell/test_dataclass_field_defaults.py も追加しています。

Lua / Ruby / C++ でも、mapping や runtime bridge、plain builtin fallback、emitter helper detection の調整を入れています。C++ については full sample sweep はまだ 7/18 PASS ですが、代表的な fixture / sample / stdlib parity を通すために plain builtin call を runtime helper 経路へ戻す修正を入れています。

5. Go selfhost の主な修正

今回一番大きい差分は src/toolchain/emit/go/emitter.py です。Go selfhost では Python 実行時に曖昧なまま通っていた型境界が、生成後の Go compile / run で厳密に問題化していました。特に JsonVal / any / container / tuple return / runtime call の境界が詰まりどころでした。

Go emitter 側では、主に以下を補強しています。

• isinstance による narrowing
• None 判定の lowering
• union / container 型の narrowing
• typed list / set / dict literal
• tuple-return call の Go 表現
• dataclass field order
• method receiver typing
• true division の扱い
• Path / str 周辺の型推論
• deque() の戻り型
• zip, sum, min, max の builtin lowering
• time.perf_counter と math.* 関数の戻り型
• runtime helper call が any に広がりすぎるケースの抑制

src/toolchain/emit/go/cli.py も selfhost 用に強化しています。manifest directory を受ける pytra-cli 互換の -emit ... -o ... --target go 経路、単体 EAST3 JSON 入力、runtime/go copy、非 Go target の reject を扱えるようにしました。これにより、selfhost binary が単なる smoke ではなく、実際に Go emitter CLI として fixture / sample を処理できるようになっています。

Go runtime 側では src/runtime/go/built_in/py_runtime.go を補強しました。特に Go 1.19 互換性のため、map / set clear は Go 1.21 以降の clear() builtin ではなく delete loop に戻しています。devcontainer の Go version に左右されずに通るようにするためです。

さらに、PNG/GIF sample parity の最後の blocker だった bytearray-mutating helper を直しています。Python では dst.extend(src) のような副作用で bytearray が伸びますが、Go slice は値渡しなので、単に helper 内で append しても呼び出し元の slice に反映されないことがあります。そのため _png_append / _gif_append のような helper は Go 側では更新後の []byte を返し、呼び出し側で dst = helper(dst, src) と受ける形にしました。

この変更により、sample の PNG/GIF artifact-size mismatch が解消し、Go selfhost sample parity が 18/18 PASS になっています。

6. Top100 language coverage の追加

tools/gen/gen_top100_language_coverage.py を追加し、Top100 programming languages に対する Pytra 側の coverage / blocker / next action を機械生成できるようにしました。

生成物として以下を追加・更新しています。

• docs/ja/progress/top100-language-coverage.md
• docs/ja/progress/top100-language-coverage.json
• docs/en/progress/top100-language-coverage.md
• docs/ja/plans/p2-top100-language-coverage.md
• docs/en/plans/p2-top100-language-coverage.md
• docs/ja/progress/index.md
• docs/en/progress/index.md

coverage 表では、単に target が存在するかではなく、backend / syntax / defer / blocked などの分類、現状、blocker、次アクションを分けています。今回の更新で Go row は fixture 161/161 and sample 18/18 PASS に更新し、次アクションは sample artifact 修正ではなく stdlib selfhost sweep 拡張へ進めています。

7. TODO / progress docs の同期

docs 側では、日本語 TODO を中心に、今回の実測結果に合わせて状態を更新しています。

主な更新は以下です。

• docs/ja/todo/go.md: P7-GO-SELFHOST-RT-S4 / S5 を完了扱いに更新
• docs/en/todo/go.md: Go selfhost fixture / sample parity の英語側更新
• docs/ja/todo/infra.md: devcontainer / Top100 coverage / automation 前提の整理
• docs/ja/todo/dart.md: Dart host emitter 進捗の反映
• docs/ja/todo/powershell.md: PowerShell build lane の進捗反映
• docs/ja/todo/lua.md, docs/ja/todo/ruby.md: runtime / host 周辺の進捗反映

PR 本文にも書いた通り、残件は「終わったこと」と「まだ blocker として残っていること」を混ぜないように分けています。Go sample の PNG/GIF mismatch は完了側へ移し、C++ sample 7/18 の残 blocker、Dart / Zig native CLI 未導入、Go stdlib selfhost sweep 未拡張は残件として残しています。

8. 追加・更新した tests

今回の変更は emitter / runtime / CLI / docs generator にまたがるので、regression test もいくつか追加しています。

代表的な追加・更新は以下です。

• tools/unittest/toolchain2/test_common_cli_runner.py
• tools/unittest/toolchain2/test_go_emitter_cli_selfhost.py
• tools/unittest/toolchain2/test_go_selfhost_ifexp_typing.py
• tools/unittest/toolchain2/test_linker_spec_conform2.py
• tools/unittest/selfhost/test_run_selfhost_parity.py
• tools/unittest/toolchain2/test_tuple_unpack_emitter_hosts.py
• tools/unittest/toolchain2/test_dart_emitter_smoke.py
• tools/unittest/toolchain2/test_zig_emitter_smoke.py
• tools/unittest/toolchain2/test_powershell_cli_runtime_copy.py
• tools/unittest/emit/powershell/test_dataclass_field_defaults.py
• tools/unittest/tooling/test_gen_top100_language_coverage.py
• tools/unittest/tooling/test_pytra_cli2.py

特に test_go_emitter_cli_selfhost.py では、Go emitter CLI が pytra-cli 互換の引数を受けること、非 Go target を reject すること、単体 EAST3 JSON から app_main.go を書く経路を固定しています。test_linker_spec_conform2.py では、bytearray-mutating helper が Go では戻り値を返し、呼び出し側で受けることを小さい fixture で固定しています。

9. 実施した検証

PR 作成時点では、以下のような検証を通しています。

• python3 -m py_compile src/toolchain/emit/go/emitter.py tools/gen/gen_top100_language_coverage.py tools/unittest/toolchain2/test_linker_spec_conform2.py tools/run/run_selfhost_parity.py
• python3 -m unittest tools.unittest.toolchain2.test_go_selfhost_ifexp_typing tools.unittest.toolchain2.test_go_emitter_cli_selfhost
• python3 -m unittest tools.unittest.toolchain2.test_linker_spec_conform2.Toolchain2LinkerSpecConform2Tests.test_go_emitter_returns_mutated_bytearray_helpers
• python3 -m unittest tools.unittest.selfhost.test_run_selfhost_parity.RunSelfhostParityBuildTest.test_build_selfhost_binary_go_uses_go_emitter_cli_entry
• python3 -m unittest tools.unittest.tooling.test_gen_top100_language_coverage
• Go selfhost binary rebuild via tools.run.run_selfhost_parity._build_selfhost_binary("go")
• python3 tools/run/run_selfhost_parity.py --selfhost-lang go --cmd-timeout-sec 300 で fixture 161/161 PASS
• python3 tools/run/run_selfhost_parity.py --selfhost-lang go --case-root sample --all-samples --cmd-timeout-sec 300 で sample 18/18 PASS
• python3 tools/gen/gen_top100_language_coverage.py && python3 tools/gen/gen_top100_language_coverage.py --check
• git diff --check

レビュー時に見ていただきたい順番

差分が大きいので、レビュー時は以下の順が追いやすいと思います。

1. src/toolchain/emit/go/cli.py と tools/unittest/toolchain2/test_go_emitter_cli_selfhost.py で、selfhost binary の入口がどう変わったかを見る。
2. src/toolchain/emit/go/emitter.py と src/toolchain/emit/go/types.py で、Go lowering / typing の拡張を見る。
3. src/runtime/go/built_in/py_runtime.go と test_go_emitter_returns_mutated_bytearray_helpers で、Go runtime / bytearray helper の parity 修正を見る。
4. tools/run/run_selfhost_parity.py と tools/unittest/selfhost/test_run_selfhost_parity.py で、selfhost parity runner の期待値を見る。
5. tools/gen/gen_top100_language_coverage.py と生成済み docs で、coverage matrix が実測結果と残 blocker をどう表現しているかを見る。
6. .devcontainer/ と docs/ja/spec/spec-setup.md で、検証環境と bootstrap 手順を見る。

残していること

この PR で全部を完了扱いにはしていません。次に残しているのは主に以下です。

• Go selfhost は fixture / sample まで通ったので、次は stdlib sweep を追加して coverage を広げること。
• C++ sample full sweep は 7/18 PASS のままで、artifact CRC、object 型漏れ、min / max / enumerate fallback が残っていること。
• Dart / Zig は host 生成が進んだ一方で、native CLI が devcontainer に未導入なので compile / parity は次段であること。
• Top100 coverage は今回 generator と初期 matrix を入れた段階なので、今後は各 row を実測で更新し続ける必要があること。

以上です。PR 本文の概要よりもかなり細かく書くと、この PR は「Go selfhost parity を fixture/sample まで到達させるための emitter/runtime 修正」と「その作業を継続できる devcontainer・coverage・TODO・test の足場整備」をまとめたもの、という位置づけです。