CI でワークブックの回帰を検出
CLI を使い、ワークブックの変更をコードレビューで可視化するパターンです。手で Excel 編集されたワークブックはバイナリとして不透明ですが、Formulon にかけるとレビュアーが読める差分になります。
揮発性数式に注意
NOW / TODAY / RAND / RANDBETWEEN を含むワークブックは値スナップショットに向きません。隔離、明文化、またはスナップショット対象外にしてください。
用語: 期待値ファイル
期待出力としてコミットされているファイルです。テストは現在出力と比較し、ずれていれば失敗します。レビュアーが意図的変更（期待値更新）か回帰（コード / ワークブックの修正）か判断します。
パイプラインの形
数式・値のスナップショットを取る基本コマンド（formulon dump --formulas、formulon recalc && formulon dump --values）は CI 回帰検査 で説明しているものと同じです。具体的な呼び出し方や、揮発性数式でスナップショットを避けるべき場面についてはそちらを参照してください。このページでは、それらを PR パイプラインに組み込む方法と、ドリフトのレビュー方針を扱います。
push する前のローカルチェックとしては、make parity-test が手早い補完手段になります。利用可能なチャネル（cli、npm（WASM）、python）で共有の検証用ワークブックを評価し、チャネル間の不一致を報告します。これも CI ジョブ単体では捉えられない種類のドリフトです。詳しくは CI 回帰検査 を参照してください。
GitHub Actions 例
name: workbook regression
on: [pull_request]
jobs:
workbook:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Install formulon CLI
run: |
curl -L -o formulon.tar.gz "https://github.com/libraz/formulon/releases/download/v0.9.5/formulon-0.9.5-linux-x64.tar.gz"
tar -xzf formulon.tar.gz --strip-components=1
chmod +x formulon
sudo mv formulon /usr/local/bin/
- name: Snapshot formulas
run: |
formulon dump --formulas model.xlsx > testdata/model.formulas.txt
- name: Snapshot values
run: |
formulon recalc model.xlsx -o /tmp/model.xlsx --quiet
formulon dump --values /tmp/model.xlsx > testdata/model.values.txt
- name: Fail on diff
run: |
git diff --exit-code testdata/同じワークブック + プロファイル + Formulon バージョンに対して結果は決定論的なので、失敗するのはワークブックかエンジンが変わったときだけです。どちらもレビュー価値があります。
レビュー方針
差分は次のいずれかに分類してください。
- 想定済みの数式編集
- 想定済みの入力変更
- Formulon の互換性差分
- Excel の挙動変化
- バグ
この分類を PR 本文（またはコミット末尾の注記）に書き残すと、将来同じ差分を見た人が「なぜ受け入れたのか」を追跡できます。期待値ファイルが「ただのバイナリ差分」になるのを防ぎます。
CI では Formulon バージョンを固定する
dump 出力フォーマットと値の意味はパッチリリース間で安定していますが、Formulon バージョン（または CLI バイナリ URL）を明示的に固定してください。無関係なリリースアップグレードがワークブック回帰として顕在化するのを避けられます。
次に読むもの
- CLI ワークフロー ─ このシナリオの裏で動くコマンド
- CI 回帰検査 ─ より広いパターン
- 互換性モデル ─ プロファイルを固定する理由