安定性とバージョニング

big-code-analysis is on the 2.x line (currently 2.2.0). The full stability contract lives in STABILITY.md at the root of the repository — that file is the source of truth and is updated alongside the changelog at every release.

ライブラリ利用者向けの要点は次のとおりです。

  • パッチ・マイナーバンプをまたぐ形状の安定性。 STABILITY.md § "What is stable in shape" に列挙されたすべての公開型と関数シグネチャは、2.x 系列を通じて維持されます。追加的変更（新しい項目、新しい LANG バリアント、新しい MetricsError バリアント、新しい言語フィーチャ）はマイナーバンプで許可されます。破壊的な形状変更は次のメジャーバンプまで保留され、チェンジログ の 3.0.0 セクションに (breaking) として記載されます。
  • No value stability guarantee within 2.x. A grammar pin bump or a bug fix in a metric definition can shift any metric value on any file in any direction, even across a patch bump. Each such drift is flagged in the changelog. Pin to an exact version (big-code-analysis = "= 2.2.0") if you need bit-for-bit reproducibility across runs.
  • MSRV は 1.94 です。MSRV の引き上げはマイナーバンプ相当のイベントとして扱われ、チェンジログに(breaking) として明記されます — STABILITY.md § MSRV policy を参照してください。
  • Escape hatches. The Node wrapper exposes its tree_sitter::Node through Node::as_tree_sitter(), and the tree_sitter crate is re-exported as big_code_analysis::tree_sitter. Node also carries the accessors the metric walk itself uses (kind, kind_id, child, children, child_by_field_name, utf8_text, the position accessors). Their signatures are shape-stable, but the values they return — node kinds and kind_id numbers — belong to the pinned grammar and move when it does, so anything reached through those seams follows the pinned tree-sitter version rather than our own SemVer. See STABILITY.md § Escape hatches before depending on them.
  • big-code-analysis-ast is not a stability surface. Since #1376 the parse and classification layer lives in that separate published crate, which this one pins exactly and releases in lockstep. It will appear in your cargo tree. Nothing in it carries a promise of its own: depend on big-code-analysis and use what it re-exports.

3.0 に向けて

かつて 2.0 向けに準備されていた破壊的変更は 2.0.0 で出荷済みです。開かれた公開列挙型への #[non_exhaustive] マーカー、シリアライズキーの正規化、整数メトリクスの u64 への移行、言語ディスパッチと文法のデフォルト変更、Python と REST の表面変更、そして 1.0 以降に蓄積したドリフトを織り込んだメトリクス値の一括再ベースライン化です。パス位置引数によるコールバックディスパッチ（action / Callback トレイト）、フリー関数の metrics / metrics_with_options / get_function_spaces / metrics_from_tree / get_ops、およびジェネリックな Parser<T> / ParserTrait の配管も同時に削除されました。現在は analyze と Ast が唯一の解析の継ぎ目であり、Parser と言語ごとのパーサー / タグ型は pub(crate) に降格されています。

積み残しが一つ、次のメジャーに先送りされています。メトリクスごとの Stats 構造体はまだ #[non_exhaustive] ではないため、フィールドの追加は厳密な SemVer の意味では形状の破壊になります。実際には、フィールド追加はマイナーバンプでの追加的変更として扱われ、チェンジログに明記されます。構造体への #[non_exhaustive] の付与は 3.0 ロードマップ に載っており、この例外扱いを廃止できるようにする予定です。

3.0 の予定はありません。2.0 で追加された #[non_exhaustive] マーカーにより、将来の追加（新しい列挙型バリアント、新しいフィールド）のほとんどは非破壊的になるため、依存すべき表面は 2.x です。