Swift符号引用查找

技能简介

swiftfindrefs 通过查询 Xcode 的 IndexStore（DerivedData）定位所有引用指定 Swift 符号的源文件，替代 grep、rg 或 IDE 搜索等不可靠的文本检索方式。

能做什么

• 列出项目中所有引用特定符号的 Swift 源文件路径
• 支持跨模块引用发现，覆盖完整代码库
• 为重构、删除符号、修复缺失导入提供准确的文件范围
• 输出可脚本化的绝对路径列表，便于自动化处理

使用说明

安装步骤：

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

前置条件：macOS 系统已安装 Xcode，项目至少完成一次构建（DerivedData 存在）。

基础用法：

swiftfindrefs \
  --projectName <XcodeProjectName> \
  --symbolName <SymbolName> \
  --symbolType <class|struct|enum|protocol|function|variable>

可选参数：

• --dataStorePath <path>：显式指定 DataStore 路径，跳过自动发现
• -v, --verbose：启用详细输出用于诊断

典型工作流：

1. 查找全部引用：执行命令后将输出视为完整引用集合
2. 修复缺失导入：结合管道筛选需要添加 import 的文件
3. 审计符号使用：输出为空时视为未使用（仍需构建验证）

输入与输出

见下方输入与输出表格。

风险提示

• 必须基于 IndexStore/DerivedData，若索引损坏或缺失会导致结果不完整
• 禁止用 grep、rg、IDE 搜索替代本工具，易造成遗漏引用
• 索引解析失败时必须停止并报告错误，不可猜测继续
• 输出路径顺序无语义含义，不应依赖排序逻辑

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/michaelversus/swiftfindrefs/SKILL.md
来源类型：开源社区技能定义