リンター・フォーマッターの意義を再確認

[tarepan]

内容

リンター・フォーマッターの意義を再確認し、適用するルールの範囲を明確化することを提案します。

#1644 (comment) にてリンター・フォーマッタールールの導入を一旦立ち止まり「そもそもなぜリンター・フォーマッターを導入するのか」を整理する必要が指摘された。

Pros 良くなる点

• 開発速度が上昇
  • ルールの単純化による煩わしさの低減
  • ルールの自動適用によるレビュー速度の向上・コストの削減
  • 共通認識の形成による議論の効率化

Cons 悪くなる点

考えるのに時間がかかる

実現方法

• 意義の再定義
• 適用範囲の議論
• 既存 linter/formatter の見直し
• 新規 linter/formatter の導入と適用

VOICEVOXのバージョン

all

[tarepan]

第一段階として、VOICEVOX ENGINE にリンター・フォーマッターを導入した際のロジックを確認したいと考えます。
これにより「そもそも何で今リンター・フォーマッターが導入されているのか」という共通認識を持つことが出来ます。

レポジトリを軽く調査したところ、導入の理由付けは見つかりませんでした（導入 PR (#24) では意義の説明無し）。
@Hiroshiba
VOICEVOX ENGINE にリンター・フォーマッターを導入した際、どのような理由付け/ロジックで Go となったか等の記憶ありますでしょうか？

[Hiroshiba]

流石に覚えていない･･･というより、最初は「ないよりはあったほうが楽」という経験則とかな気がしました！

とりあえず最古のPRがどれかとかをまとめてみました！！参考になれば！！！
（AIにお願いしてみたのですが、検索ヒット数が膨大でうまく抽出するのは難しそうな気配を感じました･･･。）

# VOICEVOX プロジェクトにおけるリンター導入の経緯

## 主要リポジトリのリンター導入時期と変遷

### 1. voicevox（エディター）

**最初の導入**: 2021 年 8 月 2 日（PR #5）

- MT224244 氏による PR
- VSCode が TS ファイルのリンティングもできるよう ESLint の設定を変更
- これが最も古い ESLint 関連の PR

**主な改善・拡張**:

- 2022 年 11 月 4 日: template 内での ?? と ?. の利用を eslint で制限（PR #1010）
- 2023 年 2 月 24 日: eslint-plugin-import を追加してインポートの順番を制御（PR #1233）
- 2023 年 7 月 4 日: ESLint に vue3-recommended を追加（PR #1371）
- 2024 年 7 月 17 日: 型付き ESLint を有効化（PR #2172）
- 2025 年 2 月 24 日: ESLint を最新にして Flat Config に移行（PR #2560）
- 2025 年 3 月 6 日: ESLint のキャッシュを有効化（PR #2597）

### 2. voicevox_engine（音声合成エンジン）

**最初の導入**: 2021 年 12 月 4 日（PR #219）

- qwerty2501 氏による PR
- pre-push 時に pysen lint を実行するように設定
- レビュワー負荷軽減が目的

**主な改善・拡張**:

- 2023 年 2 月 2 日: pysen lint extras の利用をやめ、各 linter ライブラリに個別に依存（PR #608）
- 2025 年 3 月 22 日: pysen から ruff(+mypy)に移行（PR #1563）
- 2025 年 4 月以降: ruff の各種ルール（D100, D101, D102, D103, D105, D200, D202, D205, D300, D409, D410, D411 など）を適用するリファクタリングが多数実施

### 3. voicevox_core（コア）

**最初の導入**: 2022 年 12 月 4 日（PR #341）

- qryxip 氏による PR
- ShellCheck と actionlint を導入
- Issue #310（actionlint を実行したところ、GitHub Actions のワークフローファイルに問題が見つかった）を受けての対応

## 組織全体での取り組み

### リンターの種類と目的

1. **JavaScript/TypeScript (voicevox)**

   - ESLint: コードの品質管理、バグの早期発見
   - 型付き ESLint: 型情報を活用したより厳密なチェック

2. **Python (voicevox_engine)**

   - 当初: pysen (black, flake8, isort, mypy)
   - 現在: ruff + mypy
   - 目的: コードフォーマット統一、バグの早期発見、型チェック

3. **Rust (voicevox_core)**
   - ShellCheck、actionlint
   - 目的: シェルスクリプトと GitHub Actions ワークフローの品質管理

## 最近の動向

2025 年 3 月以降、voicevox_engine リポジトリでは pysen から ruff への移行が完了し、ruff の各種ルールを段階的に適用するリファクタリングが活発に行われています。これにより、コードの品質と一貫性が向上しています。

また、voicevox リポジトリでは ESLint の Flat Config 化やキャッシュの有効化など、開発体験を向上させる取り組みが進められています。

## まとめ

VOICEVOX プロジェクトでは、各リポジトリの特性に合わせて適切なリンターが導入され、継続的に改善されてきました。当初は基本的なリンティングから始まり、徐々に型チェックや特定のルールの追加など、より高度な機能が導入されています。また、2023 年以降は最新ツールへの移行など、より効率的な開発環境の構築が進められています。

与えたプロンプトメモ

あなたは GitHub のコード検索やプルリク／Issue 検索 API を扱えるアシスタントです。
VOICEVOX 組織（org:VOICEVOX）の全リポジトリから「リンター導入の経緯」を調べたいので、
以下の手順で効率的に情報を集約してください。

1. **対象リポジトリの絞り込み**  
   - まず VOICEVOX/voicevox_engine に限らず、org:VOICEVOX 全体のリポジトリ一覧を取得して下さい。
   - ただし archive ラベルがついている or 明らかに無関係なリポジトリはスキップして構いません。

2. **メタデータ中心の検索**  
   - 各リポジトリで、まず「設定ファイル追加」PR を特定します。検索クエリ例：  
     
is:pr org:VOICEVOX filename:.github/**/*linter* OR filename:.eslintrc* OR filename:.flake8*

     タイトル／内容に “linter” “eslint” “flake” “lint” を含むものを狙い、**PR番号・作成日・タイトル・作成者**だけを最初に取得。

3. **Issue／PR本文の要約抽出**  
   - 見つかった PR の中で最も古い（＝最初に導入した）ものをピックアップし、その PR 本文とリンクされている Issue（あれば）の本文から、「導入理由」や「目的説明」にあたる箇所だけを抜粋して要約。

4. **補足調査**  
   - 必要に応じて、PR 本文に “参考: #123” のようにリンクされている Issue も同じように本文を要約。
   - ついでにコミットメッセージに lint キーワードだけでヒットするものを検索し、PR より前に存在する関連コミットがあれば、そのコミットログも要約。

5. **出力**  
   - 最終的に「いつ」「誰が」「どの PR/Issue で」「どんな理由で」リンターを導入したのかを、
     - PR/Issue の番号と URL
     - 日付（YYYY-MM-DD 形式）
     - 本人たちのコメント（要約）
   でまとめた表形式、もしくは箇条書きで返してください。

[tarepan]

最初は「ないよりはあったほうが楽」という経験則とかな気がしました

👍️
情報ありがとうございます。

---

@tarepan @Hiroshiba の調査により、現時点の VOICEVOX ENGINE は

「リンター・フォーマッターがあると品質に良い影響がありそう」

という理由付け・判断基準がリンター・フォーマッターに適用されているとわかりました🎉

---

現在の判断基準は、個別ルールを適用するか否かの判断基準としては曖昧です。
このためリンター・フォーマッターの ENGINE における意義を 1 から整理する必要がありそうです。

いくつかの確認事項を揃えたのち、私から叩き台を提案し、皆さんの意見を伺いながら修正していく形が良いかなと感じました。
@Hiroshiba
この形での進行はどうでしょうか？

---

@Hiroshiba
#1644 (comment) にて

導入する以上他にどういうルールが有るのかは全部見ておく必要がありそう

との指摘がありました。
既に適用されているリンター・フォーマッターのルール（flake8・pyflake・isort・pycodestyle 等）については @Hiroshiba さんあるいは他のメンテナさんが一通り確認済みという理解で良いでしょうか？
それとも #24 での導入時に「品質に良い影響がありそう」という感じでガバっと有効化している（個別ルールはあまり見ていない）感じでしょうか？

[Hiroshiba]

このあたりの選定理由はたぶんruffのPRのコメントやり取りとかが詳しいかもしれません！

いま有効化されてるのは、たしかruffを導入してるmajor open-sourceなのをいくつか調べて、それらに導入されているものとかをとりあえずで提案した記憶があります！

ruffのときは僕は全ルール見て問題なさそうか判断してました！
といってもルールの詳しい部分とかは追いきれないので、１回実行してみて嫌な変更がないことと、１行ずつまとまってるページをざっと眺めて気になるのがなければという感じですが。

---

今までいろんなものの導入判断をしてきましたが、良いか悪いかはさておいてその気持ちを書き起こしてみるとこんな感じかもしれません：

• 自分が長くよく使っているもの・知っているものは導入判断が甘い
  • uvとか
• よく知らないものが提案されたとき、それがよくあることなのかを調べる
  • 大規模プロジェクトが率先して導入していて、かつしんどいという知見もなさそうなものは導入しても大丈夫なことが多い
    • ruffのルール選定で他のOSSの導入状況を網羅的に調べたのはこれが理由
  • 逆にあまり導入されていないものは最悪自分たちでメンテしないといけなかったりするので敬遠気味
• ライブラリ選定基準に従う（今回は関係なさそうだけど）
  • 基本的に長くメンテされそうなのを選ぶ
  • たぶんその心の１つは「しんどくならないか」（他にもありそう）
  • メンテナが責任持って導入する場合は例外的にOKなこともある
• AかBどっちが良いのかわからなくなったときは、それを判断できる共通方針を考える
  • 今ここ

今たぶん「しんどくならないか」の部分で引っかかって、このissue作成をお願いしたという感じになるかもしれません･･･！！

[Hiroshiba]

@qryxip @sevenc-nanashi
コアとエディタのメンテナのお二人も、よかったら静的解析を導入するかしないかの判断の線引きについて意見あったらお聞きしたいです！ 🙏

「コア・エディタだったらこう」とかでも大丈夫だと思います。
例えばeslintのルールは無限にある中で、それを導入するリクエストが来た時、受け入れるか受け入れないかの判断指標に使えるかなと･･･！

[sevenc-nanashi]

気持ちとして：

• 基本的にはrecommendedを使う
• 導入することでレビューで気づきにくいバグが出るなら増やす（no-floating-promisesとか）
• 導入することによるコードが増える、かつ「たしかにそうだけど基本的に大丈夫でしょ...」みたいなことはやらない（それこそS101とか）
• 不都合がそれほどつらくない場合（例えばWeb上でイベントハンドラにasync functionをそのまま渡す、Nodeだとやばいけどブラウザならあまり問題はない）はやらない

って感じですかね？

[Hiroshiba]

あ、もしよかったら静的解析を導入するかしないかの判断の線引きについて @qryxip さんもなにかコメントいただけると！
あとは @tarepan さん自身もコメント書いておくと良いのかもと思いました！

[qryxip]

コアの話だと、全体設定に関しては基本的にrustcとClippyのデフォルト設定のままにしてあります。というのもClippyのリントのラインナップおよびリントレベルはしょっちゅう変わるため、その「波」に乗っておけばよさそうという感じです。
例外として全体有効化しているのはrustc本体の方のリントであるrust_2018_idiomsくらいでしょうか。

ただしPythonのnoqaにあたる#[allow(…)]/#[expect(…)]は積極的に使っています。「9割方のケースで正しく機能するようなリントを全体指定して残りの1割のケースでは個別に抑制する」という考え方について、私は特に否定的な考えを持ち合わせていないためです。

例えばRustではなくBashのShellCheckだとSC2016というのがあって、Bashをよくわかっていない人を大いに助けると思うのですが、わかっている人にとっては邪魔なケースが存在します。このような場合では個別での抑制が最適だと思っています。

# 環境変数の値とかではなく、'$ORIGIN'という文字列を渡したい！

# shellcheck disable=SC2016
patchelf --set-rpath '$ORIGIN' ./path/to/lib.so

他の言語だと(リンターではないですが)MISRA-Cという、criticalなシステムをCで書くときのガイドラインがあるのですが、MISRA-Cは「逸脱 (deviation)」という行為を許容しており逸脱の際の作法まであったりします。

まあRustだと#[expect(…)]の方であれば抑制が不必要になった時点で逆に警告を発するようにできるし#[expect(lint_name, reason = "…")]という書き方までできる、というのも理由ではあります。あとClippyはRust初学者向けのリントを多く含むために、Rustをわかっている人にとっては少々煩雑というものあるかなと。

それでエンジンでどうすべきかですが、正直Pythonでもどんどんリントを入れていって、確固たる理由があれば「逸脱」を許すというのも選択肢の一つとしてはありなんじゃないかなとは思いました。"noqa"という名前をしているのが見た目的にどうなんだ感はちょっとありますが。

[Hiroshiba]

２人共ありがとうございます！！
ENGINEやVOICEVOX全体に適用できそうな観点を抽出させてもらうと、こんな雰囲気のことを感じました：

• ヒホ
  • 他OSSでの事例や実際の挙動を調べる
  • 導入してしんどくならなさそうであればOK
• 名無し。
  • recommendedをベースにし、バグ検出できるなら増やしていく
  • ルールを足すことでコードが増える＆そもそも問題にならないなら足さない
• qryxip
  • ルール多めに合わせ、理由があれば局所的に抑制する
  • （ヒホ補足：qryxipさんは特にRustにおいて、ルールや仕様のほぼ全部を網羅的に把握しています）

参考にしつつ、リンター・フォーマッターを導入する方針を提案するならこんな感じでしょうか！

1. recommendedなものは取り入れていく
2. よく知る
3. バグを防げるなら導入する
4. 理由があれば局所的に抑制していく
5. 問題ではなく、かつコードが増えるなどしてしんどくなりそうなら避ける

ruffはrecommendedがないけど、雰囲気として一文字ルール（Eとか）は推奨されているというか、よく取り入れられるものな気がしています。

[Hiroshiba]

ここまで書いていて思いましたが、どういうものを取り込んでいくかの方針は考えられたけど、そもそもこのissueの目的はリンター・フォーマッターの意義でした。。。
まあ意義の雰囲気まとめるとこういう感じ･･････？

• コミッター・メンテナーともに楽をするため
  • 一般論として、指摘のやり取り・判断のやり取りを減らせる
    • たぶん判断のやり取りはゼロにならない。理由があれば抑制しても良いので。
  • 導入してコードが増えるなどしんどくなる場合は逆効果
• バグを減らすため

追加・削減等あればコメントをお待ちしつつ、一旦 @tarepan さんにお返しします！！
（全然まとまってないので、まとめの叩き台とかご提案いただけると助かります！！！！ 🙇 🙇 🙇 🙇 ）