Tombi | 🐑 TOML ファイルを自動ソート

Tombi という TOML Language Server を開発している @yn7010 です。

https://zenn.dev/yassun7010/articles/6a60d705d0a55c

より多くの方に Tombi を知ってもらうため、いくつかに分けて Tombi の開発の小話を記事にしていきます。

今回は Tombi の目玉機能と考えている自動ソートについて話をしたいと思います。

自動ソートは不可能？

Tombi と同様の TOML Language Server である Taplo でも自動ソートの機能があるのですが、部分的なサポートにとどまり、複数の Issues が開かれたまま解決されていない状態です。

Issue が解決されないのは Taplo の開発が停滞していることもありますが、それだけではありません。
プログラミング言語においてコメントの扱いは難しいものです。

次のようなコードを [dependencies] のキーを昇順に自動ソートすることを考えてみましょう。

Cargo.toml

[dependencies]
regex = "1.11.1"
serde = "1.0.0"

# clap = "4.5.37"

futures = "0.3.31"
ahash = "0.8.11"

さて、このようなファイルを自動ソートする場合、# clap = ... の扱いはどうすれば良いのでしょう？

1. serde = ... に紐づいていると解釈？
2. ahash = ... に紐づいていると解釈？
3. どちらにも紐づいていないと解釈？

一見すると 3 に見えますが、だとすると並び替えた後、 # clap = ... のコメントはどこに置けば良いのでしょうか？

...コメントは記載できる箇所が多いため、これ以外にも、自動ソートをしようとすると「あれ？このコメントはどう解釈すれば？」と一意に定めることができない状況に遭遇します。
そのため、コメントを含んだコードの自動ソートは難しいのです。

では、コメントを入れることのできる TOML では自動ソートは不可能なのでしょうか？

自動ソート、できるよ

Taplo の自動ソート結果

# clap = ... をグループの区切りコメントと考え、それぞれのグループの中で自動ソートします。

Cargo.toml

[dependencies]
regex = "1.11.1"
serde = "1.0.0"

# clap = "4.5.37"

ahash = "0.8.11"
futures = "0.3.31"

Tombi の自動ソート結果

# clap = ... を ahash に紐づいたコメントと解釈して自動ソートします。

Cargo.toml

[dependencies]
# clap = "4.5.37"
ahash = "0.8.11"
futures = "0.3.31"
regex = "1.11.1"
serde = "1.0.0"

一意にコメントを定めることができないと言いましたが、もう少し踏み込むと コメント位置を一意に決定するには制約が足りない ということです。
そのため、追加でルールを定めると自動ソートできる様になります。

少し話を変えると、 Tombi は TOML の LSP という既存の市場に踏み込んだ新参者ですが、新規参入の特権である「それが仕様です」カードをどこかで使おうと考えていました 🙄
（ Tombi が尖った機能を多く載せているのは、このあたりの私の思考が影響しています）

例えば Python の black というフォーマッタは従来のフォーマッタとは異なり、最初から設定項目がありませんでした。
もし、途中で既存のすべての設定項目を削除したら、black のユーザは怒って離れていったでしょう。
最初から設定レスを主張していたから、ユーザに受け入れられたのです。

コメントの解釈方法が複数ある自動ソートは、途中からルールを追加すると怒るユーザが現れるかもしれませんが（少なくとも Taplo の GitHub Issue は少し荒れていました）、Tombi は、最初から「筋の通ったルール」を設けることで自動ソートを実現しています。

「筋の通ったルール」とは何か？となりますが、ここでは次のようなものです。

• フォーマット前後で、要素が欠損せず、意味が変化しない（等価性）
• 繰り返しフォーマットを繰り返しても、フォーマット後の形が維持される（冪等性）
• フォーマットされた前後の差分について、大きな違和感が発生しない

では、いよいよ本題の Tombi のコメントの扱いについて説明します。

Tombi のコメント解釈ルール

一般的なコメントの分類

Tombi のコメント解釈について説明する前に、プログラミング言語におけるコメントの話をしましょう。

コメントの種類は一般的に下記の3つに分類できます。

Leading Comment

# 要素の上にくっつくもの
# コメント行は連続していていい
key = "value"

Trailing Comment

key = "value" # 要素の後ろにくっつくもの

Dangling Comment

# 直前または直後に要素がないもの
# コメント行は連続していていい

# 空白行に挟まれているもの
# コメント行は連続していていい

key = "value"
# 要素の次の行にくっつくもの
# コメント行は連続していていい

このうち自動ソートを困難にするものは Dangling Comment です。

そのため、自動ソートを行うには、どのように Dangling Comment を扱うかが問題になります。

要素の次の行を Dangling Comment とするのではなく、 Tailing Comment のような上の要素に紐づくコメントにした方が良いのではないかと考える方がいるかもしれませんが、
次のケースを考えると Dangling Comment として扱い、 Leading Comment は Dangling Comment より優先度が高いと考えた方が良いことがわかります。

key1 = "value1"
# これは key1 の Dangling Comment？ いいえ、 key2 の Leading Comment
key2 = "value2"

Dangling Comment なんてなかった

今回 Tombi に設けた追加ルールは「自動ソートに邪魔な Dangling Comment」を「Leading Comment」として扱う、というものです。

Cargo.toml

[dependencies]
serde = "1.0.0"

# clap = "4.5.37"
# これは Dangling Comment ではなく、 ahash の Leading Comment とみなす。

# これが普通の Leading Comment
ahash = "0.8.11"

どこの Dangling Comment を Tombi が Leading Comment をみなすのかは、ドキュメント か、特定のコメント行をエディタで Hover すれば確認することができます。

この解釈は、保存したコメントが意図しない行にソートされる可能性がありますが

• 自動ソートによる大きな変更は最初の一度だけ
• 追加のコードを書いている分には、違和感が発生しにくい
• Tombi 側の仕様であると割り切れる

という考えで採用しました。

Dangling Comment を Dangling Comment のままにする箇所も残されており、その理由は「使っても違和感が少ない」ようにするためです。

初期のコメント解釈は Dangling Comment を一切許容しませんでしたが、利用してみると「ここは改行が欲しいんだよ！」という苛立ちが多く、廃案になりました。

今は 2世代目のコメント解釈システムですが、一部を Dangling Comment として残すことで、苛立ちが少なくなるようにチューニングされています。

Taplo: 設定ファイルによる自動ソートの問題

さて、 Taplo の自動ソートにはもう一つ問題があります。
Taplo の自動ソートは taplo.toml で次のように設定することで利用できます。

talpo.toml

[formatting]
reorder_keys = true

しかし、この方法の場合、すべてのテーブルのキーを自動ソートしようと試みますが、実際には自動ソートして欲しいものは TOML ファイルの全てではなく一部であることがあります。

Cargo.toml

# このセクションはキー名で並び替えして欲しくない
[package]
name = "my-crate"
version = "1.0.0"
authors = ["taro <[e-mail]>"]

# このセクションはキー名で並び替えして欲しい
[dependencies]
anyhow = "^1.0.0"
serde = "^1.0.0"

では設定項目を増やせばいいのでしょうか？

taplo.toml

[formatting]
reorder_keys = [{ enabled = true, file = "Cargo.toml", target = "dependencies" }]

それとも、コメントで設定を追加する形でしょうか？

Cargo.toml

# taplo: reorder-key = false
[package]
name = "my-crate"
version = "1.0.0"
authors = ["taro <[e-mail]>"]

# taplo: reorder-key = true
[dependencies]
anyhow = "^1.0.0"
serde = "^1.0.0"

しかし、どちらも美しくないですね...

Tombi のコンセプトの一つは「設定不要」であるので、ユーザが設定することなく、自動でどのテーブルをどのルールで自動ソートするかを決定する必要がありました。

Tombi: JSON Schema Store を利用した自動ソートで解決

あれこれ考えているうちに、 JSON Schema Store から情報を取得すればいいことに気がつきました。

具体的には、オブジェクト（TOML のテーブル）のスキーマに Tombi のための設定を追加します。

{
  "type": "object",
  "properties": {
    ...
  },
  ...
  "x-tombi-table-keys-order": "ascending"
}

スキーマの提供者がどこのテーブルを自動ソートするのかを JSON Schema Store に事前登録しておくことで、ユーザが指定することなく自動ソートのルールを細かく定義できます。

Tombi は Taplo よりも並び替えの選択肢が多く、 x-tombi-table-keys-order と x-tombi-array-values-order が利用でき、それぞれに "ascending" | "descending" | "schema" を指定できます。

JSON Schema の x- を使うことに最初は抵抗を感じたのですが、 Taplo がすでに別の機能のために利用していたので、しばらく経った後にこの方法に気がつきました。

Taplo は必要な道具をすでに持っていた！

おわりに

今回は Tombi の目玉機能と位置付けた「自動ソート」について説明しました。

私は TOML の自動ソートを完全に実装したツールを Tombi 以外に知りません。
しかし、Tombi はリリース後 Rust コミュニティに紹介 しても、さっぱり GitHub のスターがつかず、シェアを拡大するため、さらなる機能追加が求められたのでした。

最後に、Tombi ではスポンサーも募集しています。
支援していただける方がいれば、応援よろしくお願いします。

https://github.com/tombi-toml/tombi