decisiondecided

html-build を TypeScript 対応に拡張する

自作の分割ソース→バンドルツール html-build の TypeScript 対応方針を、esbuild を transformer として限定採用する形で確定する。バンドラ本体は置換しない。

状況

  • 実験ツール群(マニュアル生成器等)は scripts/html-build/ の自作ツールで開発している
  • 現行は「ESM ソース + @file / @import / @export マーカーコメント + 独自バンドラ」
  • 本家サイト(React + Vite)と同じコアロジックを共有する際、型の恩恵が欲しい
  • 開発中の IR(ルールブック中間表現)は判別共用体で、JSDoc では表現が冗長になる
  • 実装済みモジュール数は 8 個。まだ小さく、移行コストは今が最小

決定

html-build のバンドラ本体は維持し、esbuild を「TypeScript → JavaScript 型剥がし」の transformer としてだけ組み込む。

具体的には:

  1. bundle.mjs の buildScriptBlock() 内で、.ts / .tsx ファイルに対してのみ esbuild.transform() を呼ぶ
  2. マーカーコメント(// === @file: ... ===)は transform の前後で退避・復元 する(esbuild がコメントを削るため)
  3. 型剥がし後のコードは既存の stripImports / トポロジカルソート / 連結パイプラインに流す
  4. esbuild.build() は 使わない(バンドラを置換しない)
  5. 型チェックは tsc --noEmit を別コマンドで実行する(バンドルに含めない)
  6. .js と .ts は同一プロジェクト内で混在可能とする

理由

なぜバンドラを置換しないか

現行の html-build は「自作の軽量バンドラ」であることに価値がある:

  • @file マーカー駆動 — split ツールが 1 ファイルから複数ソースを復元できる
  • @import / @export の双方向照合 — audit-imports が「directive と実コードの 1:1」を強制できる
  • マーカーコメントがバンドル後も残る — split が復元できる前提そのもの

esbuild の build() に置き換えると:

  • マーカーコメントが消える → split 不能 → verify 不能 → audit 不能
  • コメント保持オプションが legalComments しかなく、// === 形式は保持対象外
  • 全部書き直しになる

なぜ transform としてだけ使うか

esbuild.transform() は:

  • 単一ファイルを入力として、型を剥がした ESM を返すだけ
  • コメントを(デフォルトで)削るが、事前に退避すれば問題ない
  • バンドルや tree shaking はしない — 既存パイプラインの責務を侵さない
  • 実行速度が非常に速い(Rust 実装)
  • .ts / .tsx / .js を同じ API で扱える

コメント退避の必然性

esbuild は //! または /*! で始まる「legal comments」以外のコメントを削る。既存のマーカーは // === 形式であり、legalComments: 'inline' オプションの対象外。よって: