ロードマップ
XTL 1.0(仕様)および xl3 1.0(リファレンス実装)に到達するために何が必要かをまとめます。
現在のバージョンは 0.7.0(npm)で、**XTL 0.1(ドラフト)**を対象としています。0.x の期間中は依然として破壊的変更が発生し得ます。1.0 のリリースはカレンダー上の日付ではなく、以下に挙げる項目によってゲーティングされます。
詳細なバージョン計画は
docs/internal/blueprint-to-1.0.mdにまとめてあります — ギャップ分析、設計思想の境界(xl3 ≠ JXLS)、バージョンごとのステップ計画です。本書はエレベーターピッチであり、ブループリントは根拠そのものです。1.0 ゲートの唯一の正典は下記のテーブルです。 本書とブループリントが矛盾する場合はこのテーブルが優先され、ブループリントの方をそれに合わせて更新します。
xl3 における 1.0 の意味
1.0 の目標は オペレーターにとって信頼できる読みやすさ です。すなわち、ぐらつかない仕様、サプライズのないリファレンス実装、そしてコードを読まなくてもオペレーターがテンプレートをレビューできる程度に小さい表面積です。これは JXLS との機能比較における網羅性の話では ありません — xl3 は意図的に小さな表面でリリースしています(ADR-0043 + ADR-0048)。想定する利用層は 多数の顧客固有の請求書フォーマット(거래명세서、정산서、발주서)を扱う韓国のオペレーションチーム です。エンジンはこのニッチを越えて一般化できますが、ニッチがくさびとなります。
1.0 ゲートテーブル(唯一の正典)
各ゲートにはオーナー、ゲートをクローズさせる成果物、合否基準、ゲートが到達不能となった場合のフォールバック、そしてターゲットマイルストーンが定められています。下の各バージョンごとのステップ計画はゲートを ID で参照します。
| ID | ゲート | オーナー | 成果物 | 合格基準 | フォールバック | ターゲット |
|---|---|---|---|---|---|---|
| G1 | 適合性コーパス ≥ 140 | メンテナ | conformance/fixtures/ | ls conformance/fixtures/ | wc -l ≥ 140 | — | 0.7.1(現在 139 件; 0.7.0 の ADR が 141–187 を予約済み) |
| G2 | Stage 2 OOXML 正規化を仕様化 | メンテナ | ADR-0006 + src/ 配下のカノニカライザ | フィクスチャ 024-027, 093 と ADR-0006 の改訂で網羅 | — | 完了 |
| G3 | エラーコードカタログの凍結 | メンテナ | src/__tests__/error-codes.test.ts スナップショット | カタログのスナップショットが 30 日間変更なし | — | 0.9-rc(0.7.0 の新規 4 コードにより 2026-05-22 にクロックがリセット) |
| G4 | JXLS との境界を公開 | メンテナ | ADR-0048 | ファイルが存在し、PORTERS_GUIDE を参照していること | — | 完了 |
| G5 | 先送り実装の ADR を着地 | メンテナ | ADR-0038 実装 ✅(2026-05-18)+ ADR-0040 PE 実装 | ADR-0038 の対象範囲はリリース済み(フィクスチャ 132-135);ADR-0040 の CF/DV 範囲拡張は未完了 | — | 0.6(一部)/ 0.7.1 |
| G6 | 公開 API サーフェスの凍結 | メンテナ | src/__tests__/api-surface.test.ts スナップショット | スナップショットが 30 日間変更なし | — | 0.9-rc |
| G7 | @stable エクスポートに JSDoc 例 | メンテナ | TypeDoc 出力 | すべての @stable シンボルに @example ブロックが存在 | — | 0.8 |
| G8 | 性能の特性化 | メンテナ | scripts/BENCH.md | 1k/10k/100k 行 × 5/10/20 列のマトリクス + メモリ上限 + parse/eval/write の内訳を公開 | — | 0.7.1 |
| G9 | 性能リグレッションフィクスチャ | メンテナ | 適合性コーパス | 比率ベースのアサーションを含む大規模フィクスチャを 2 件以上 | — | 0.7.1 |
| G10 | クロスブラウザのスモーク | メンテナ | ci.yml | Safari + Firefox でのバンドル読み込み + 1 回の convert() を毎実行 | — | 0.7.1 |
| G11 | CI での Stage 2 実行 | メンテナ | ci.yml | すべての PR で npm run conformance:stage2 が走る | — | 0.7.1 |
| G12 | 未確定挙動の固定(ピボット/スパークライン/ListObject/改ページ) | メンテナ | 適合性フィクスチャ + 項目ごとの ADR | 各項目について:現状挙動を固定するフィクスチャ、または明示的に 1.x に先送りする ADR | ADR と共に 1.1 へ先送り | 0.7.1 / 0.8 |
| G13 | 第二言語実装による検証 | 外部(xl3-py) | conformance/reports/*.json | xl3-py が Stage 1 を 80% 以上、または Stage 2 を 80% 以上通過すること、もしくは他のすべてのゲートがクローズしてから 12 か月以内に別言語(Rust/Go/Java)で 50% のスケルトンが文書化されていること | GOVERNANCE を改訂する公開 ADR で単一実装 1.0 を受容 | 0.7.x–0.8.x |
| G14 | 外部コントリビューターによる ADR | 外部 | spec/decisions/NNNN-*.md | 著者がメンテナ以外で、Context/Decision セクションを行数比 60% 以上書いた ADR が 1 件以上 | 18 か月のタイムボックスを設け、その時点で外部執筆のクックブックレシピが 2 件以上、または外部執筆の適合性フィクスチャが 5 件以上 | 0.8 |
| G15 | 本番リファレンス事例 | 外部(メンテナ協力可) | IMPLEMENTATIONS.md の「Production users」行 | 名指しのユーザーが 1 件以上で、(a) 掲載許諾のある外部企業、または (b) メンテナ自身の雇用主が xl3 をスケジュール化された本番で稼働させ、公開事例研究を出している、のいずれかを満たす | — | 0.8 |
| G16 | メンテナ集合の拡大 | メンテナ | GOVERNANCE.md | ADR と実装 PR に対し承認/却下権を持つ人が 2 人以上 | GOVERNANCE への改訂で単一メンテナ 1.0 ガバナンスを明示的に受容 | 0.8 |
| G17 | 韓国語クックブック i18n の完了 | メンテナ | website/i18n/ko/.../guides/ | すべてのクックブックレシピに韓国語訳が存在 | — | 完了(0.6) |
| G18 | README に本番利用ケースを掲載 | メンテナ | README.md | 「アルファ」ステータスを具体的な本番リファレンス事例で置き換える(G15 と連動) | — | 1.0(G15 と同時) |
| G19 | 0.x → 1.0 移行ガイド | メンテナ | docs/migration-0.x-to-1.0.md | すべての挙動変更を記述、または追加のみであることを確認 | 追加のみと確認できれば CHANGELOG の注記に格下げ | 0.8 |
| G20 | SECURITY.md + 脅威モデル | メンテナ | SECURITY.md + 仕様改訂 | ZIP 爆弾 / 超巨大ワークブック / 数式実行に対するスタンスと制限 API を文書化 | — | 0.7.1 |
| G21 | ハードリミットを文書化(1.1 までストリーミングなし) | メンテナ | spec/evaluation.md | 行数 / メモリのハードリミット値と AbortSignal API を文書化 | — | 0.7.1 |
| G22 | API サーフェス — 内部モデル型を分離 | メンテナ | src/index.ts のエクスポート + STABILITY.md | convert/preview/analyze + 安定インターフェイスのみが @stable 指定、モデル/パーサ型は @experimental か xl3/internal に移動 | — | 完了(0.6) |
| G23 | RC ソーク | メンテナ | git タグ | RC を公開し、21 日以上のソーク(レビューフィードバックを受けて 7 日から延長)、クリティカル課題ゼロ | — | 0.9-rc |
| G24 | 「安定四半期」リリース後チェックリスト | メンテナ | リリースカレンダー | 上記の最終ゲートが ✅ となってから 90 日間の窓を設け、その間に仕様/API/エラーコードの破壊的変更が発生しない | 破壊的変更があればクロックを再スタート | 最終ゲート完了から 1.0 リリースまでの間 |
定義(テスト可能なかたちで)
- 外部コントリビューター(G14): PR オープン時点で
GOVERNANCE.mdのメンテナ集合に含まれず、かつマージ済み ADR コミットのCo-authored-by履歴にも含まれない人物。誤字修正の「ドライブバイ」編集は対象外。ADR フロントマターに著者として記載され、Context/Decision セクションを行数比 60% 以上執筆していること。 - 破壊的変更(G24、G23): (a) 公開 API サーフェスのスナップショット、(b) エラーコードカタログ(改名/削除/再利用)、(c) ADR の
accepted→rejectedへの変更や矛盾するステータス反転、のいずれかへの変更。パッチリリースおよび追加のみの ADR は四半期クロックをリセットしません。 - クリティカルバグ修正(G23 の RC 例外): (a)
convert()における暗黙のデータ損失、(b) ドキュメントとランタイム間のエラーコードカタログの不整合、または (c) 文字通りには実装できないacceptedADR の MUST 条項。メンテナは PR で (a)/(b)/(c) のいずれかを引用します。 - データ損失テスト(G24 のテスト可能形式): コーパスに専用の
data-loss/フィクスチャグループ(8 件以上)を持ち、暗黙の文字列化、numFmt の欠落、数式の書き換え、日付ラウンドトリップの経路を網羅し、すべてがリファレンス実装で合格すること。 - 四半期クロックの起点(G24 と G23 の関係): 90 日の四半期は最後のゲートが ✅ となった日からカウント開始します。RC の公開時点ではクロックは始まりません — RC を公開する前にクロックが始まっている必要があります。RC ソーク中に破壊的変更が発生した場合、ソーク(G23)も四半期(G24)もリセットされます。
バージョン別ステップ計画
ゲートベースであり、日付ベースではありません。カレンダー見積もりは削除しました — 各マイルストーンは、列挙されたゲートがクローズした時点でクローズします。
0.6.0 — 先送り実装、狭いスコープ
テーマ: もっともインパクトの大きい先送り実装ゲートをクリーンにクローズする。
クローズしたゲート: G5(@group/@subtotal 実装のみ — ADR-0040 PE の残りは 0.6.1 へ)、G17(韓国語クックブックの未翻訳 16/17 件)、G22(@group が新たな内部型を露出する前に API サーフェスを整理)。
以前の「0.6.0 ですべてを片付ける」計画はエンジニアリング実現性レビューに照らしてスコープが過大でした。ADR-0038 の実装単体でも、新しいディレクティブ、グループ境界のステートマシン、トランスフォームパスの分割、レンダラーの書き換え、グループスコープの集計評価という、パイプライン全体への組み込みを伴います。0.6.0 を分割することでマイルストーンを出荷可能なサイズに保ちます。
0.6.1 — 残りの先送り実装(計画中、未出荷)
クローズしたゲート: G5 の完成(ADR-0040 PE の CF/DV sqref 拡張)、G12 に向けたピボット/改ページ挙動のフィクスチャ。
0.7.0 出荷時点のステータス: このマイルストーンは仕様監査バッチ(0.7.0)によってスキップされました。G5/G12 の作業は 0.7.1 に統合されます。
0.7.0 — 仕様監査バッチ(2026-05-22 出荷)
テーマ: 字句解析、セル分類、ディレクティブ合成、集計引数、予約シートのセマンティクスを深く監査して浮かび上がった 17 件の構文上の矛盾ギャップを解消する。元のゲートテーブルには予定されていなかった追加作業で、本来 0.7.0 として予定されていた perf/CI/制限まわりの作業は 0.7.1 に移動します。
出荷した成果物:
- 新規 ADR 15 件(0051–0065)に加え、ADR-0021 改訂(group-order カタログエントリ)と ADR-0041 改訂(ヘッダーセルの複数行正規化)。
- 新規エラーコード 4 件 —
xl3/parser/unbalanced-literal、xl3/lists/invalid-use、xl3/eval/bad-aggregate-arg、xl3/expression/unknown-name。 - 文法の追加:
positive_integer、group_directive、subtotal_directive、aggregate_call、字句的曖昧性解消ノート。 src/directive-parser.tsにおける先頭ゼロ整数の厳格化。- 二段並列レビュー(claude-general + codex);タグ付けの前に CRITICAL/HIGH の所見はすべてクローズ済み。
ゲートへの影響:
- G1 — 現在 139 件のフィクスチャ。0.7.0 の ADR がフィクスチャ番号 141–187 を予約していますが、実装は保留中です。これらが 0.7.1 で着地した時点で G1 はクローズします。
- G3 — 30 日のエラーコードカタログクロックは、新規 4 コードにより 2026-05-22 にリセット されました。
- G6 — 公開 API サーフェスの変更はなく、G6 のクロックには影響しません。
0.7.1 — 性能 + 外部検証の開始(旧 0.7.0 を改名)
クローズするゲート: G5 の完成(ADR-0040 の CF/DV sqref 範囲)、G8(性能ベンチマーク)、G9(性能リグレッションフィクスチャ)、G10(クロスブラウザ)、G11(CI での Stage 2)、G20(SECURITY.md ドラフト + 脅威モデル)、G21(ハードリミット + AbortSignal ドキュメント)。
また 0.7.0 の ADR が予約していたフィクスチャ 141–187 を着地させることで、G1 ≥ 140 フィクスチャ のフロアもクローズします。
進行中: G12(未確定挙動の固定)、G13(xl3-py)。
ラベルの変更: G8 公開後、かつ xl3-py が Stage 1 の 50% 以上に到達した時点で alpha → beta。
0.8.0 — 社会的ゲート
クローズするゲート: G14(外部 ADR)、G15(本番事例)、G16(メンテナ拡大、または単一メンテナの明示的受容)、G19(移行ガイド)、G20 の完了。
このマイルストーンは長期になります。リクルート期間中に黙って待つのではなく、その間 0.8.x のパッチをこまめにリリースしていく計画です。
0.9.0-rc.x — 1.0 前のフリーズ
クローズするゲート: G3、G6、G7、G23(21 日以上の RC ソーク)。
G23 が始まると、G24 の四半期クロックがカウント開始します(上記の定義のとおり、G3/G6/G7 などがクローズしていく間にクロックは既に動いている必要があります)。
1.0.0 — 最終リリース
クローズするゲート: G24(最後のゲート完了から 90 日の四半期を消化済み)。
採用とアウトリーチ
社会的ゲート(G13/G14/G15/G16)はコードではなく人手を必要とします。プロジェクトには区別された二つの採用接面があります。
韓国オペレーション層(G15、将来のクックブックコントリビューター)
チャネル: 韓国のデベロッパーコミュニティ(Naver Café、Kakao 오픈톡、LinkedIn KR)、社内向けまたはベンダー向けのテンプレート作成者アンケート。マイナーリリースごとに、リリースの瞬間に紐づく韓国語ポストを公開します(0.6 = 請求書の小計パターン向け @group/@subtotal デモ、0.7 = 性能数値、0.8 = ケーススタディ)。
英語 OSS 層(G13、G14)
チャネル: HN、lobste.rs、r/excel、カンファレンス CFP(JSConf、xl3-py 向けには EuroPython)。メジャーな節目ごとに、特定の外部成果物を 1 つ出荷します。
- 0.7.0 リリース: 「Show HN: xl3 0.7 — 100k 行対応の Excel テンプレートエンジン」
- 0.8.0 リリース: ケーススタディ + xl3-py 適合性ダッシュボード
- 1.0.0 リリース: 仕様 + 複数実装による検証
1.0 のノンゴール
これらは意図的に先送りしています。それぞれ理由を説明する ADR があります。
- Y/M/D/EOMONTH/EDATE/DATEDIF を超える日付演算 — その他のファミリーは ADR-0019 改訂 により先送り。
- ロケール対応の文字列照合 — ADR-0020。
- マルチ結合、左結合、複数行マッチ — ADR-0014 のスコープ外セクション。
- XLOOKUP のワイルドカード / 近似 / 逆方向検索 — ADR-0013 のスコープ外セクション。
- 動的画像挿入 — ADR-0037。
- 実行時のセル変更 — ADR-0042。
- ADR-0043 ゲートにより却下された関数群 — 数学関数の拡張、型テスト(
ISBLANKは ADR-0047 で例外的に採用)、NOW / WEEKDAY 等、条件付き集計、TEXT() 書式トークンの拡張。ADR-0045 を参照。 - ストリーミング出力 / SXSSF 相当機能。 1.1+ に先送り。1.0 では代わりに、メモリ/行数のハードリミットを文書化(G21)します。
- テンプレートコンパイルキャッシュ API。 1.1+ に先送り。
- PDF / HTML 出力。 スコープ外。xl3 は xlsx 入力 - xlsx 出力に特化します。
093を超えるクロスライター Stage 2 フィクスチャ — ADR-0006 改訂。
これらは需要に応じて XTL 1.1、1.2、1.x の候補として残ります。
項目クローズへの貢献方法
| 項目 | 貢献の仕方 |
|---|---|
| G13 第二実装 ≥ 80% | xl3-py に貢献するか、新たな移植(Rust、Java、Go)を始める。PORTERS_GUIDE.md を参 照。 |
| G14 外部 ADR | 先送り項目(ピボットテーブル保持、改ページ、ADR-0045 で除外された関数)を一つ選び、spec/decisions/ に ADR を起草する。GOVERNANCE.md の「How changes enter the project」を参照。いくつかの「スターター ADR スタブ」が GitHub の good-first-ADR イシューとして用意されています。 |
| G15 本番事例 | xl3 を内部で利用し、うまくいったこと/いかなかったことを共有する。適切であれば IMPLEMENTATIONS.md に行を追加する。メンテナ自身の雇用主(Snack24h)も、公開ケーススタディを出せば対象となります。 |
| G17 韓国語クックブック 16+17 i18n | 新しめの 2 レシピを翻訳する(他は完了済み)。 |
| G8 ベンチマーク | 代表的なテンプレートで npm run bench を回し、結果を共有する。 |
| G10 クロスブラウザ | Safari + Firefox をバンドルスモークテストに追加する。 |
| 関数の再提案 | ADR-0045 で却下された関数が必要な場合は、Function re-proposal のイシューテンプレートを使ってください。 |
このロードマップの更新方法
本書は公開エレベーターピッチであり、ゲートテーブルが唯一の正典です。より深い docs/internal/blueprint-to-1.0.md が、ギャップ分析、設計思想の境界、バージョンごとの根拠を扱います。ゲートがチェックされるごとに、両方のドキュメントを更新します。新たなギャップが浮かべば、両方に追記します。
1.0 ゲートテーブルへの追加や削除は、他のすべてと同じく ADR / イシュープロセスを通して議論されます。