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 としてだけ組み込む。
具体的には:
bundle.mjsのbuildScriptBlock()内で、.ts/.tsxファイルに対してのみesbuild.transform()を呼ぶ- マーカーコメント(
// === @file: ... ===)は transform の前後で退避・復元 する(esbuild がコメントを削るため) - 型剥がし後のコードは既存の
stripImports/ トポロジカルソート / 連結パイプラインに流す esbuild.build()は 使わない(バンドラを置換しない)- 型チェックは
tsc --noEmitを別コマンドで実行する(バンドルに含めない) .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' オプションの対象外。よって: