SwiftFindRefs

用途

使用 swiftfindrefs 查询 Xcode 的 IndexStore（位于 DerivedData 中），定位所有引用指定符号的 Swift 源文件。该工具旨在避免因依赖文本搜索或启发式方法而导致的不完整重构。

规则

• 编辑任何文件前，必须先运行 swiftfindrefs。
• 仅编辑 swiftfindrefs 返回的文件。
• 不得用 grep、rg、IDE 内置搜索或文件系统启发式方法替代引用发现流程。
• 不得手动扩展文件集合。
• 若 IndexStore / DerivedData 解析失败，应立即中止并报告错误；禁止凭猜测继续操作。

前提条件

• 已安装 Xcode 的 macOS 系统
• 项目至少已构建一次（即 DerivedData 目录已存在）
• swiftfindrefs 已加入系统 PATH

安装

brew tap michaelversus/SwiftFindRefs https://github.com/michaelversus/SwiftFindRefs.git
brew install swiftfindrefs

标准命令格式

建议在可能的情况下显式提供 --projectName 和 --symbolType 参数。

swiftfindrefs 
  --projectName  
  --symbolName  
  --symbolType 

可选参数：

• --dataStorePath ：显式指定 DataStore（或 IndexStoreDB）路径；跳过自动发现逻辑
• -v, --verbose：启用详细输出，用于诊断（布尔标志，无需提供值）

输出约定

• 每行一个绝对路径
• 结果去重
• 脚本友好（可安全逐行管道传递）
• 输出顺序无语义含义

标准工作流

工作流 A：查找全部引用

1. 对目标符号执行 swiftfindrefs。
2. 将输出视为该符号的完整引用集合。
3. 如需进一步分析，仅打开上述输出中列出的文件。

工作流 B：移动符号后修复缺失的 import 声明

使用 swiftfindrefs 限定作用域，仅在必要位置添加 import 声明。

swiftfindrefs -p  -n  -t  | while read file; do
  if ! grep -q "^import $" "$file"; then
    echo "$file"
  fi
done

对每个输出的文件执行以下操作：

• 在文件顶部的 import 区块中插入 import 。
• 保持现有 import 的顺序与分组方式不变。
• 禁止重复添加同一模块的 import。
• 不得格式化与当前修改无关的代码。

工作流 C：删除或重命名符号前审计其使用情况

1. 对目标符号执行 swiftfindrefs。
2. 若输出为空，则视该符号为未使用（必要时仍需通过构建/测试进一步验证）。
3. 若输出非空，则在修改公开 API 前，须人工审查所列文件。

参考资料

• CLI 详细说明：references/cli.md
• 操作手册：references/workflows.md
• 故障排查指南：references/troubleshooting.md