From Zero to First PR with Go and WebAssembly

目的

• ✅ withastro/compiler にPRを出す

https://github.com/withastro/compiler

ターゲットゴール

• ✅ コンパイラが Go で書かれている理由、Wasm ビルドの所在、そして各サブパッケージの役割を理解する。
• ✅ 小さなパッケージを自分で書き、go fmt で整形し、実行・テストまで行えるようにする（Stack Overflow からのコピペに頼らない）。
• ✅ .wasm ファイルと、それを動かす JavaScript システムの仕組みを「ブラックボックス」ではなく理解する。
• ✅ 自分の環境でコンパイルし、テストをすべてグリーンで通す。

リポジトリ全体像を掴む

何をする？：README とフォルダツリーをざっと眺める

なぜ、必要？：Go で書かれている部分と TypeScript／JS で書かれているラッパー部分を見分け、
Codespaces 用 .devcontainer や Makefile のターゲットを把握する

具体的に何をする？：GitHub 上なら「Code → Files」を押してブラウザで階層を展開する

🟦 = Go ソース 🟨 = JS/TS ほか

compiler/
├── cmd/astro-wasm/        // 🟦 Goエントリポイント -> Wasm 生成
├── internal/              // 🟦 トークナイザ / スキャナ / プリンタ本体
│   ├── printer/           // 🟦 出力(JS/TS)生成ロジック
│   └── ...                // 🟦 その他ユーティリティ
├── internal_wasm/         // 🟦 Wasm ランタイム補助
├── lib/esbuild/           // 🟨 ビルド用 JS ラッパー
├── packages/compiler/     // 🟨 npm 配布物 (wasm 同梱)
├── .devcontainer/         // 開発コンテナ設定
├── Makefile               // `make wasm`, `make publish-node` など
└── README.md / CONTRIBUTING.md / …

ポイント
Go ソースは cmd/, internal/, internal_wasm/ に集約。packages/compiler/wasm/astro.wasm が最終生成物で、npm 経由で配布されます。
Makefile には “Wasm ビルド”・“Node 版公開” など最短経路のコマンドが定義されている。

3 段階パイプラインを理解する

Astro コンパイラは Tokenize → Scan → Print の 3 ステージ。CONTRIBUTING.md の最初の節に図が載っており、次のような責務分担になっている。

┌───────────┐     ┌──────────────┐     ┌────────────┐
│ Tokenizer │ ─▶  │ JS Scanner   │ ─▶  │ Printer    │
│ (token.go)│     │ js_scanner.go│     │ printer/*  │
└───────────┘     └──────────────┘     └────────────┘
   .astro原文            import 解析        TypeScript 出力

• Tokenizer – .astro ファイルを字句解析し、FrontmatterStart や TagEnd などおおまかなトークン列を生成。
• JS Scanner – そのトークン列をもとに、どこが JS なのかを把握し import 文などを抽出。
• Printer – 解析結果を TypeScript (TSX) に変換。Node／ブラウザ双方で実行可能なコードを吐き出します。

ポイント : 何かバグを直す時は Tokenizer → Scanner → Printer の順に下層から確認すると原因を切り分けやすい。

どうやって情報を読むか

1. README / CONTRIBUTING

• README の冒頭で Go+Wasm 採用理由と “使い方” サンプルをチェック。
• CONTRIBUTING の “Code Structure” にパイプライン図・テスト方法がまとまっています。

2. VS Code Dev Container

   • .devcontainer/devcontainer.json で Go 1.x と Node、pnpm が事前インストールされた環境が定義済み。
   • Codespaces で “Open in Codespaces” をクリックすればローカルセットアップ不要。

3. Makefile で最短ビルド

   make wasm        # .wasm を生成
   go test ./...    # すべての Go テストを実行
   

✅ コンパイラが Go で書かれている理由、Wasm ビルドの所在、そして各サブパッケージの役割を理解する。

Go を学習する

🏃‍♂️ A Tour of Go

ここで学べる内容は以下のとおり：

• 基本文法（if、for、switch など）
• スライス（可変長配列）
• インターフェース（Go 独特の型システム）
• テストの基本（*_test.go）

👉 A Tour of Go
👉 A Tour of Go List

📖 2. Effective Go の冒頭を読む

Effective Go は、Go コードを書く上での慣習やベストプラクティスをまとめた公式ドキュメントです。

以下の項目に目を通す：

• 命名規則
• エラーハンドリング（error の使い方）
• 並行処理（goroutine、channel の基礎）

ざっと流し読みし、Go らしさの感覚をつかむ。
👉 Effective Go

💻 3. ローカルに Go 1.22+ をインストールする

macOS の場合は Homebrew で：

brew install go

または公式インストーラー（Windows/Linux 含む）から入手：
👉 Go ダウンロードページ

⚙️ 4. 簡単なパッケージを初期化してテストする

学習用ディレクトリを作成し、初期化とテストを試す。

go mod init learn-astro
go test ./...

https://github.com/cblte/100-golang-exercises

Today I create this PR
https://github.com/withastro/compiler/pull/1101