名称： swiftfindrefs
描述： 使用 swiftfindrefs (IndexStoreDB) 列出引用某个符号的所有 Swift 源文件。这是执行“查找引用”、“修复缺失导入”和跨模块重构的必要步骤。请勿用 grep/rg 或 IDE 搜索替代。

SwiftFindRefs

目的

通过查询 Xcode 的 IndexStore (DerivedData)，使用 swiftfindrefs 定位引用给定符号的所有 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 <Xcode项目名称> \
  --symbolName <符号名称> \
  --symbolType <class|struct|enum|protocol|function|variable>

可选标志：
- --dataStorePath <路径>: 显式指定 DataStore（或 IndexStoreDB）路径；跳过自动发现
- -v, --verbose: 启用详细输出以进行诊断（标志，无需值）

输出约定

• 每行一个绝对文件路径
• 已去重
• 脚本友好（可安全地逐行管道处理）
• 顺序无语义含义

标准工作流

工作流 A：查找所有引用

1. 为符号运行 swiftfindrefs。
2. 将输出视为完整的引用集合。
3. 如需更多细节，仅打开返回的文件。

工作流 B：移动符号后修复缺失的导入

使用 swiftfindrefs 限定范围，然后仅在需要的地方添加导入。

swiftfindrefs -p <项目> -n <符号> -t <类型> | while read file; do
  if ! grep -q "^import <模块名>$" "$file"; then
    echo "$file"
  fi
done

然后，对于每个打印出的文件：
- 在顶部的导入块中插入 import <模块名>。
- 保持现有的导入顺序/分组。
- 切勿添加重复的导入。
- 不要重新格式化无关的代码。

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

1. 为符号运行 swiftfindrefs。
2. 如果输出为空，则将该符号视为未使用（如有需要，仍需通过构建/测试验证）。
3. 如果输出非空，在更改公共 API 前，请先审阅列出的文件。

参考

• CLI 详情：references/cli.md
• 操作手册：references/workflows.md
• 故障排除：references/troubleshooting.md