swiftlint

SwiftLint

SwiftLint は、設定可能なルールセットに照らしてソースファイルをリントし、Swift のスタイルと規約を適用します。このスキルでは、セットアップ、設定、ルールの選択、抑制、CI との統合、導入戦略について説明します。

SwiftLint はスタイルを適用するツールであり、スタイルガイドではありません。Swift の命名規則と設計規約の基盤については、swift-api-design-guidelines を参照してください。アーキテクチャパターンについては、swift-architecture を参照してください。

目次

• 推奨されるセットアップ
• 設定
• ルール選択の戦略
• 抑制
• ベースライン
• 自動修正
• CI との統合
• 統合の判断ツリー
• 複数の設定
• よくある間違い
• レビュー用チェックリスト
• 参考資料

---

推奨されるセットアップ

デフォルト：SimplyDanny/SwiftLintPlugins 経由のビルドツールプラグインです。

プラグインパッケージを Package.swift に追加するか、Xcode のパッケージ依存関係から追加します。

// Package.swift
dependencies: [
  .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<reviewed-version>")
]

SwiftPM ターゲットでは、プラグインを適用します。

.target(
    name: "MyApp",
    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
)

Package.swift がない Xcode プロジェクトの場合は、プロジェクト設定でパッケージ依存関係を追加し、ターゲットの Build Phases またはパッケージのプラグイン信頼確認ダイアログでプラグインを有効にします。

ビルドツールプラグインは、ビルドのたびに SwiftLint を自動実行します。実行スクリプトは不要です。

初回ビルド：Xcode にプラグインの信頼を求められます。SwiftLintPlugins パッケージで「Trust & Enable All」を選択してください。

代替手段（実行スクリプト、コマンドプラグイン、Homebrew CLI）については、references/plugins-run-scripts-and-integrations.md を参照してください。

設定

プロジェクトのルートに .swiftlint.yml を作成します。SwiftLint は、呼び出し元またはプラグインの作業ディレクトリからメイン設定を読み込みます。また、設定が自動検出される場合は、各ファイルに対して最も近い場所にあるネストされた .swiftlint.yml をマージできます。--config を渡すと自動検出が上書きされ、ネストされた設定の検索が無効になります。

# .swiftlint.yml — conservative starter config
disabled_rules:
  - trailing_whitespace
  - todo

opt_in_rules:
  - empty_count
  - closure_spacing
  - force_unwrapping
  - sorted_imports
  - vertical_whitespace_opening_braces
  - private_swiftui_state
  - unhandled_throwing_task
  - accessibility_label_for_image

included:
  - Sources
  - Tests

excluded:
  - .build
  - DerivedData
  - "**/.build"
  - "**/Generated"

line_length:
  warning: 140
  error: 200

type_body_length:
  warning: 300
  error: 500

file_length:
  warning: 500
  error: 1000

主な設定オプション：

キー	目的
disabled_rules	デフォルトで有効なルールを無効にします
opt_in_rules	デフォルトでは有効でないルールを有効にします
only_rules	リストにあるルールのみを使用します（disabled_rules／opt_in_rules とは併用できません）
analyzer_rules	コンパイラログが必要なルールです（swiftlint analyze で実行します）
baseline	既知の違反を抑制するために使用する、既存のベースラインファイルへのパスです
write_baseline	SwiftLint が新しいベースラインファイルを書き込む場所のパスです
included	リント対象のパスです（デフォルト：現在のディレクトリ）
excluded	対象から除外するパスです
strict	すべての警告をエラーに引き上げます
lenient	すべてのエラーを警告に引き下げます
allow_zero_lintable_files	Swift ファイルが見つからない場合のエラーを抑制します
reporter	出力形式です：xcode（デフォルト）、json、checkstyle、sarif、csv、emoji など

重大度の調整、環境変数の展開、ネストされた設定やリモート設定など、設定の詳細については、references/adoption-and-configuration.md を参照してください。

ルール選択の方針

SwiftLint には、次の 3 種類のルールがあります。

1. デフォルトルール — 広く受け入れられている規約をカバーし、自動的に有効になります
2. オプトインルール — デフォルトでは無効で、opt_in_rules を使って選択的に有効にします
3. アナライザールール — コンパイラーログが必要で、analyzer_rules を使って有効にします

カテゴリ別の全ルール一覧は https://realm.github.io/SwiftLint/rule-directory.html をご覧ください。

新しいプロジェクトで推奨される方法：

1. デフォルトルールから始めます。swiftlint rules を実行して、有効になっているルールを確認します。
2. チームで定めた規約と矛盾するルールを無効にします。
3. オプトインルールを 1 つずつ追加します。追加を確定する前に、違反内容を確認します。
4. ゼロから始める特別な理由がない限り、only_rules は使用しないでください。

既存のコードベースで推奨される方法：

1. デフォルトのルールセットから始めます。
2. ベースラインを作成して、既存の違反をすべて抑制します（ベースラインを参照）。
3. CI で使用するものと同じ、厳格なベースライン対応コマンドを実行し、新たな違反をすべて修正します。
4. 別のルールを有効にする前、または次のクリーンアップ作業に着手する前に、違反がなくなるまで再実行します。
5. ベースラインの増加を認めず、既存の違反を段階的に減らします。

ルールディレクトリを書き写したり、暗記したりする必要はありません。必要に応じて、公式のルールディレクトリでルール識別子や設定オプションを確認してください。

抑制

ルールが誤検知を引き起こす場合や、違反が意図的なもので、確認済みの場合は、該当する行で SwiftLint を抑制します。

// swiftlint:disable:next force_cast
let view = object as! UIView

let legacy = try! JSONDecoder().decode(T.self, from: data) // swiftlint:disable:this force_try

// swiftlint:disable:previous large_tuple

領域内で無効にします：

// swiftlint:disable cyclomatic_complexity
func complexRouter(...) { ... }
// swiftlint:enable cyclomatic_complexity

すべてのルールを無効にします（使用は控えてください）：

// swiftlint:disable all
// ... generated or legacy code ...
// swiftlint:enable all

方針：

• all よりも、対象を絞った単一ルールの抑制を優先します。
• 領域の終わりでは、必ず再度有効にしてください。
• 生成コードでは、インライン抑制よりも .swiftlint.yml の excluded パスを使用してください。
• テストターゲットで許容度を変える場合は、子設定を使用してください（複数の設定を参照）。

抑制構文の詳細については、references/rules-suppressions-and-baselines.md を参照してください。

ベースライン

ベースラインを使うと、既存のコードベースで、レガシーな違反をすべて先に修正しなくても SwiftLint を導入できます。

ベースラインを作成します：

swiftlint --write-baseline .swiftlint.baseline

これにより、現在のすべての違反が記録されます。以降の実行では、このベースラインと比較し、新たな違反のみが報告されます。

ベースラインを使用します：

swiftlint --baseline .swiftlint.baseline

CI では --baseline を渡すと、新たな違反があった場合にのみビルドが失敗します。レガシーな違反を修正してベースラインを再生成し、時間をかけて違反を減らします。

ベースラインのワークフローと導入方針については、references/rules-suppressions-and-baselines.md を参照してください。

自動修正

SwiftLint では、一部の違反を自動修正できます：

swiftlint --fix
# or the legacy alias:
swiftlint --autocorrect

警告：

• --fix をコンパイル前のビルドフェーズで実行しないでください。 自動修正はソースファイルを変更します。毎回のビルドで自動実行すると、予測できない編集とビルドのループが発生し、実際の問題が見えなくなるおそれがあります。
• --fix は手動で実行するか、専用の CI ステップで実行し、その後差分を確認してください。
• すべてのルールが自動修正に対応しているわけではありません。swiftlint rules を確認してください。「Correctable」列に、自動修正できるルールが表示されます。
• --fix を実行する前に、必ずコミットするか、変更をスタッシュしてください。

CI との統合

CI は主な適用手段です。CI チェックにより、違反数を増やすコードがマージされるのを防げます。

推奨される CI パターン：

# GitHub Actions example
- name: Lint
  run: |
    brew install swiftlint
    swiftlint --strict --reporter sarif > swiftlint.sarif

主な CI オプション：

フラグ	効果
--strict	警告（エラーだけではありません）がある場合、ゼロ以外の終了コードを返します
--reporter sarif	GitHub Advanced Security に対応した出力
--reporter json	機械可読な出力
--reporter checkstyle	Jenkins／SonarQube に対応
--baseline .swiftlint.baseline	新しい違反のみを失敗対象にします

SARIF を GitHub のコードスキャンにアップロードするには、lint ステップの後に github/codeql-action/upload-sarif を追加します。

設定、ベースライン、またはルールを変更した後は、ローカルまたは検証ジョブで、CI と同じ lint コマンドを実行してください。ゼロ以外の終了コードが返された場合は、新たな違反を確認して修正し、成功するまで同じコマンドを再実行します。失敗を隠すためだけにベースラインを再生成しないでください。

CI の設定例とレポーターの詳細については、references/plugins-run-scripts-and-integrations.md を参照してください。

統合方法の判断フロー

プロジェクトの構成に基づいて、SwiftLint の実行方法を選択します。

シナリオ	推奨される統合方法
Package.swift を含む SwiftPM パッケージまたは Xcode プロジェクト	SwiftLintPlugins によるビルドツールプラグイン
CLI フラグ（--fix、--baseline）が必要な SwiftPM プロジェクト	コマンドプラグイン：swift package plugin swiftlint
SwiftPM を使わない Xcode プロジェクトで、チームが Homebrew を使用	ビルドフェーズの実行スクリプト
CI/CD パイプライン	Homebrew または Docker でインストールし、swiftlint を直接実行
コミット前フック	Homebrew でインストールし、.pre-commit-config.yaml または git フックスクリプトを使用

ビルドツールプラグインは、PATH の設定が不要で、パッケージ解決を通じて SwiftLint のバージョンを固定し、ビルド時に自動実行されるため、ローカル開発で推奨されます。

各統合方法の詳細な設定手順については、references/plugins-run-scripts-and-integrations.md を参照してください。

複数の設定

SwiftLint は階層化された設定ファイルに対応しています。サブディレクトリにある .swiftlint.yml は、親の設定を継承して上書きします。

よく使われるパターン：

• テスト用の緩和設定：Tests/ に .swiftlint.yml を配置し、force_unwrapping を無効にして file_length の上限を引き上げます
• 厳格なモジュール設定：共有モジュールのディレクトリに、より厳格な .swiftlint.yml を配置します
• リモート設定：parent_config に HTTPS URL を指定して、共有チーム設定を取得します（キャッシュに対応しています）

# Tests/.swiftlint.yml — child config
disabled_rules:
  - force_unwrapping
  - force_try

file_length:
  warning: 800

CLI で複数の設定を渡すこともできます。

swiftlint --config .swiftlint.yml --config .swiftlint-extra.yml

重複するキーについては、後の設定が前の設定を上書きします。

ネストされた設定の解決、リモート設定、CLI での複数設定の詳細については、references/adoption-and-configuration.md を参照してください。

よくある間違い

1. ビルドフェーズで--fixを実行する。 ビルドのたびに自動修正すると、予測不能なソースコードの変更が発生します。--fixは手動で実行してください。

2. 影響を理解せずにonly_rulesを使う。 これを使うと、一覧にあるものを除くすべてのルールが無効になります。ほとんどのチームでは、代わりにdisabled_rulesとopt_in_rulesを使うのがおすすめです。

3. // swiftlint:disable allで抑制し、再有効化を忘れる。 これにより、ファイルの残りの部分のすべてのLintが、気づかないうちに無効になります。

4. SwiftLintのバージョンを固定しない。 バージョンが異なると、デフォルトのルールも異なります。ビルドツールプラグイン（SPMでバージョンを固定）を使うか、BrewfileまたはCI設定でバージョンを固定してください。

5. 除外範囲が広すぎる。 Tests/全体を除外すると、テストコードにLintが実行されなくなります。代わりに、ルールを緩和した子設定を使ってください。

6. ツールチェーンの不一致を無視する。 SwiftLintは、プロジェクトのコンパイルに使用するSwiftツールチェーンと同じものを使ってビルドするか、それと互換性がある必要があります。不一致があると、パースエラーが発生します。複数のツールチェーンについては、references/plugins-run-scripts-and-integrations.mdを参照してください。

7. 大規模なコードベースで、一度に多くのオプトインルールを採用する。 これにより、違反が膨大な数になります。ルールは段階的に追加し、ベースラインを活用してください。

8. includedパスを設定しない。 includedを設定しない場合、SwiftLintは作業ディレクトリを再帰的にスキャンするため、ベンダーコードや生成コードが対象になることがあります。

レビューチェックリスト

• プロジェクトのルートに、included／excludedパスを明示した.swiftlint.ymlがある
• SwiftLintのバージョンが固定されている（SPMプラグインの解決、Brewfile、またはCI設定を使用）
• Lint対象とする各ターゲットで、ビルドツールプラグインが有効になっている
• CIでswiftlint --strictが実行されている（または段階的な導入では--baselineを使用している）
• ベースラインが意図せず増加しておらず、次のルールまたはクリーンアップの一括適用前にCIが成功している
• ビルドフェーズで--fix／--autocorrectを使っていない
• インライン抑制はallではなく、特定のルールを対象にしている
• インライン抑制には、その理由を説明するコメントが含まれている
• テストターゲットに適切な設定がある（完全に除外するのではなく、子設定でルールを緩和している）
• 自動修正による変更を、別のコミットでレビューしている
• 新しいオプトインルールを、チームの合意を得て一度に1つずつ追加している

参考資料

• references/adoption-and-configuration.md — インストール方法、.swiftlint.ymlの詳細、重大度の調整、環境変数、ネストされた設定／リモート設定、段階的な導入戦略
• references/plugins-run-scripts-and-integrations.md — ビルドツールプラグイン、コマンドプラグイン、実行スクリプト、CIのレシピ、複数ツールチェーンのガイダンス、VS Code、Fastlane、Docker、pre-commit
• references/rules-suppressions-and-baselines.md — デフォルトルールとオプトインルール、アナライザールール、抑制構文、ベースラインのワークフロー、誤検知への対処
• references/rule-reference.md — ローカルで参照できる、同梱ルールの網羅的な一覧。最新の詳細はswiftlint rulesまたは公式ルール一覧で確認してください
• references/custom-rules-and-analyze.md — 正規表現によるカスタムルール、Swiftのカスタムルール（概要）、swiftlint analyze、コンパイラログのワークフロー
• SwiftLint documentation — 公式ドキュメント
• SwiftLint rule directory — カテゴリ別の全ルール一覧
• SimplyDanny/SwiftLintPlugins — 推奨プラグインパッケージ