ViewDoctor

ViewDoctor

检查 SwiftUI 差异，并附带模块归属信息。

ViewDoctor 会在扫描 SwiftUI 代码前，从 Swift Package Manager、Tuist、Xcode 项目和常见源码布局中映射模块。人类或编码 Agent 修改差异后运行它；结果保留在本地，可通过终端文本、精简 Agent 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 风险，就把整个仓库发送给通用模型。ViewDoctor 为这些检查提供稳定的规则 ID、精确位置、模块归属和有界输出：

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

• 它在本地读取源码，不收集遥测数据。
• 根据清单生成的标识符，让检查结果在大型仓库中依然实用。
• Agent 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 差异——这是面向编码 Agent 的推荐模式：

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

这些是不同的检查点，并非别名：

工作流	命令	包含内容
Agent 或人工检查点	--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	确定性回退方案

当多个提供方的路径重叠时，匹配的源码根目录中路径最长者优先。图模型提供反向依赖锥操作，供集成和未来的受影响模块规则使用。当前的三个源码规则仍只扫描选定文件；它们不会声称验证未更改的依赖模块。

清单调用会解析为受限的 SwiftSyntax 表达式，因此一个目标的依赖项不会串入下一个目标。Tuist .project(target:path:) 边会相对于清单或项目根目录解析，并丢弃自环。viewdoctor graph . 还会在 Tuist 清单导入 ProjectDescriptionHelpers 时输出诊断信息：由 helper 生成的目标是可执行 Swift 代码，静态解析器无法展开。ViewDoctor 会报告这一限制，而不会把不完整的图呈现为完整图。

规则

规则	默认级别	检测内容
VD001	warning	在 SwiftUI body 中构造可复用或开销较大的对象
VD002	note	在 body 中重复执行集合转换
VD003	warning	在 body 中创建分离任务

规则特意采用审慎措辞：发现项表示值得审查的风险，而非声称性能分析已证实发生性能回退。

当前版本包含三条规则。目前尚未强制执行依赖方向、检测循环或证明运行时性能。这些是明确列入路线图的事项，并非暗示现有功能。

GitHub Action

在运行 Swift 6.2 或更高版本的 macOS Runner 上，在 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 权限（例如受限的 Fork 工作流），请将 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：至少有一项发现达到该阈值；
• 2：参数错误或扫描启动失败。

编码 Agent 集成

仓库在 plugin/ 中包含 Codex/OpenAI 技能和本地 MCP 服务。MCP 工具无需通过 Shell 即可调用同一 CLI，在本机保留源代码，并向编码 Agent 提供扫描结果和模块图。CLI 仍是事实来源；技能和 MCP 服务只是轻量适配器。

此版本还包含 macOS MCP Bundle。将 ViewDoctor-v0.1.7.mcpb 安装到任何支持 MCPB 的客户端，或在官方 MCP Registry 中搜索 io.github.KamnevVladimir/viewdoctor。该 Bundle 包含本地 CLI 和 stdio 适配器；仓库源代码不会发送到托管服务。

此版本中的工作流改进源于具体的集成故障，而非扩充规则愿望清单。相关证据和范围决策记录在 docs/PAIN_DRIVEN_UX.md 中。

路线图

• 为现有发现项提供基线；
• 模块依赖循环和未声明导入规则；
• 配备低噪声测试样例的 body 复杂度和身份规则；
• 已签名的发布制品和包管理器安装方式；
• 增量缓存和依赖锥分析。

隐私

ViewDoctor 会读取本地 Swift 和清单文件。分析期间不会发起网络请求，也不会收集遥测数据。公开示例和测试只使用合成源代码。

由 KamnevApps 在开发生产级 SwiftUI 应用期间构建。采用 MIT 许可证。