ViewDoctor

ViewDoctor

モジュールの所有情報を付けて、SwiftUI の差分をチェックします。

ViewDoctor は SwiftUI コードをスキャンする前に、Swift Package Manager、Tuist、Xcode プロジェクト、および一般的なソースレイアウトからモジュールをマッピングします。人間またはコーディングエージェントが差分を変更した後に実行してください。結果はローカルに保持され、ターミナルテキスト、簡潔なエージェント JSON、完全なバージョン付き JSON、または SARIF として確認できます。

Modules/Profile/Sources/ProfileView.swift:42:18: warning: VD001 [tuist:Modules/Profile/Profile]: DateFormatter is constructed inside a body property.
ViewDoctor: 1 finding(s) in 12 file(s), 4 module(s).

レビューループ

小さな生成差分を確認し、既知の SwiftUI のリスクを 3 つ探すだけなのに、リポジトリ全体を汎用モデルに送る必要はありません。ViewDoctor は、これらのチェックに安定したルール ID、正確な位置、モジュールの所有情報、そして上限のある出力を提供します。

edit -> scan changed files -> fix findings -> verify once

• ソースをローカルで読み取り、テレメトリーはありません。
• マニフェスト由来の識別子により、大規模なリポジトリでも検出結果を有効に活用できます。
• エージェント JSON では、冗長な人間向けのコンテキストを繰り返さずに、位置、モジュール、メッセージ、修正内容を保持します。完全な JSON では、インテグレーション向けに説明も保持します。
• 決定論的な順序と終了コードにより、CI でも同じコマンドを活用できます。

ViewDoctor は Swift コンパイラー、SwiftLint、Periphery、Instruments を補完します。ビルド、プロファイリング、アーキテクチャレビューの代わりにはなりません。

インストールと実行

ソースからビルドするには、Swift 6.2 以降が必要です。

git clone https://github.com/KamnevVladimir/ViewDoctor.git
cd ViewDoctor
swift build -c release
.build/release/viewdoctor scan /path/to/project

現在の git 差分のみを解析します。コーディングエージェントにはこのモードを推奨します。

viewdoctor scan . --git-diff --format agent
viewdoctor scan . --base origin/main --format agent

--git-diff は、追跡対象の変更と、新しい未追跡の Swift ファイルを含みます。そのため、新しく生成されたビューは、まだ Git に追加されていなくてもスキップされません。

インデックスのみを対象に、厳密なコミット前チェックを実行します。

viewdoctor scan . --staged --fail-on warning

検出されたモジュールと依存関係を確認します。

viewdoctor graph .

GitHub Code Scanning の出力を生成します。

viewdoctor scan . --base origin/main --format sarif > viewdoctor.sarif

README を開かずに、コマンドとインストール済みバージョンを確認します。

viewdoctor --help
viewdoctor --version

変更ファイル、コミット前チェック、CI

これらは別々のチェックポイントであり、同じ意味のエイリアスではありません。

ワークフロー	コマンド	対象
エージェントまたは人間によるチェックポイント	--git-diff	追跡対象の作業ツリー／インデックスの変更、および未追跡の Swift ファイル
プルリクエストのチェックポイント	--base origin/main	ベース以降の変更、および未追跡の Swift ファイル
コミット前フック	--staged	ステージ済みの Swift ファイルのみ
全体監査	Git オプションなし	検出されたすべての Swift ファイル

警告によってフックまたは CI ジョブを失敗させる必要がある場合は、--fail-on warning を使用してください。デフォルトは引き続き error なので、ViewDoctor を導入しても、すべての警告が暗黙のうちにブロッキングゲートになることはありません。

マルチモジュールアーキテクチャ

ViewDoctor は、検出したすべてのマニフェストから正規化されたグラフを構築します。

ビルドシステム	検出元	モジュールの所有情報
SwiftPM	Package.swift のターゲットと依存関係	Sources/<Target>
Tuist	Project.swift のターゲット、ソースの glob、プロジェクトパス	プロジェクト／ターゲットのソースルート
Xcode	.xcodeproj/project.pbxproj のネイティブターゲット	ターゲットのソースルート
フォルダレイアウト	Modules、Apps、Sources、Tests	決定論的なフォールバック

複数のプロバイダーが重複する場合は、最長一致するソースルートが優先されます。グラフモデルは、インテグレーションや将来の影響モジュールルール向けに、依存関係の逆方向の範囲を取得する操作を公開します。現在の 3 つのソースルールは、選択されたファイルのみをスキャンします。変更されていない依存先まで検証するかのように装うことはありません。

マニフェストの呼び出しは、範囲を限定した SwiftSyntax 式として解析されるため、あるターゲットの依存関係が次のターゲットに混入することはありません。Tuist の .project(target:path:) エッジは、マニフェストまたはプロジェクトのルートを基準に解決され、自己エッジは破棄されます。viewdoctor graph . は、Tuist マニフェストが ProjectDescriptionHelpers をインポートしている場合にも診断を出力します。ヘルパーが生成するターゲットは実行可能な Swift であり、静的パーサーでは展開できないためです。ViewDoctor は、この制限を報告し、不完全なグラフを完全なものとして提示することを避けます。

ルール

ルール	デフォルト	検出内容
VD001	warning	SwiftUI の body 内での、再利用可能またはコストの高いオブジェクトの構築
VD002	note	body 内で繰り返されるコレクション変換
VD003	warning	body 内での detached task の作成

ルールでは意図的に慎重な表現を使っています。検出結果はレビュー可能なリスクであり、 プロファイリングによってパフォーマンスの低下が証明されたという主張ではありません。

現在のリリースには3つのルールがあります。依存関係の方向の適用、循環の検出、実行時パフォーマンスの証明には、まだ対応していません。これらは明示されたロードマップ項目であり、暗黙の機能ではありません。

GitHub Action

Swift 6.2以降を搭載した macOS ランナー上で、CI で ViewDoctor を実行します。この Action は固定された Swift パッケージをビルドし、チェックアウト済みのリポジトリをスキャンして、SARIF の検出結果を GitHub Code Scanning にアップロードできます。

name: ViewDoctor

on:
  pull_request:

permissions:
  contents: read
  security-events: write

jobs:
  analyze:
    runs-on: macos-26
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: KamnevVladimir/ViewDoctor@v0
        with:
          diff-base: origin/main
          fail-on: warning

制限付きフォークのワークフローなど、ワークフローで security-events: write を許可できない場合は、upload-sarif: false を設定してください。不変の依存関係が必要な場合は、v0.1.7 などの完全なリリースタグを使用してください。v0 はメンテナンス対象のメジャーバージョンポインターです。

出力仕様

完全な JSON レポートには、schemaVersion、相対ソース位置、安定したルール ID、モジュール ID、説明、修正方法、モジュールグラフの概要が含まれます。--format agent は編集・修正ループ向けの、より小さな JSON 仕様です。検出結果と修正内容はそのまま保持し、繰り返されるモジュール一覧を件数に置き換えます。すべてのフィールドが必要なインテグレーションでは、完全な JSON または SARIF を使用してください。

任意の .viewdoctor.json：

{
  "excludedPaths": ["Generated", "Vendor"],
  "disabledRules": ["VD002"],
  "minimumSeverity": "warning",
  "maxFindings": 100
}

minimumSeverity は、どの検出結果を報告するかを制御します。--fail-on が制御するのはプロセスの終了コードのみです。そのため、共有レポートの設定を変えずに、CI のゲートをより厳しくできます。

終了コード：

• 0：スキャンが完了し、検出結果が --fail-on のしきい値を下回っています。
• 1：しきい値以上の検出結果が1つ以上あります。
• 2：引数またはスキャンの開始に失敗しました。

コーディングエージェントとの統合

このリポジトリには、Codex/OpenAI スキルとローカル MCP サーバーが plugin/ に含まれています。 MCP ツールはシェルを使わずに同じ CLI を呼び出し、ソースをローカルマシン上に保持して、コーディングエージェントにスキャン結果とモジュールグラフを提供します。信頼できる情報源は引き続き CLI であり、スキルと MCP サーバーは薄いアダプターです。

このリリースには macOS MCP Bundle も含まれています。 ViewDoctor-v0.1.7.mcpb を、MCPB に対応する任意のクライアントにインストールするか、公式 MCP Registry で io.github.KamnevVladimir/viewdoctor として見つけてください。このバンドルにはローカル CLI と stdio アダプターが含まれます。リポジトリのソースがホスト型サービスに送信されることはありません。

このリリースのワークフローの変更は、ルールの要望を増やしたことではなく、具体的な統合上の失敗を受けて行われました。根拠と範囲に関する判断は docs/PAIN_DRIVEN_UX.md に記載されています。

ロードマップ

• 既存の検出結果に対するベースライン。
• モジュール依存関係の循環と未宣言インポートに関するルール。
• ノイズの少ないテストケースを備えた、body の複雑さと識別性に関するルール。
• 署名済みリリースアーティファクトとパッケージマネージャーによるインストール。
• 増分キャッシュと依存関係コーン分析。

プライバシー

ViewDoctor はローカルの Swift ファイルとマニフェストファイルを読み取ります。分析中にネットワークリクエストを行わず、テレメトリーも収集しません。公開されている例とテストでは、合成ソースのみを使用しています。

本番用 SwiftUI アプリケーションを開発する中で KamnevApps が開発しました。MIT ライセンスです。