Swift Semantic Indexing Workflow
Choose between live file semantics and persisted project-wide index data without substituting syntax shape for type-checked meaning.
Workflow
- State the semantic question and required scope:
- one source snapshot at a byte position
- one file or module
- project-wide occurrences and relations
- documentation or generated interface
- Resolve the toolchain that produced or should interpret the source:
- use Swiftly for matching Swift.org toolchains and cross-platform SwiftPM builds
- use Xcode's
xcrun tools and sourcekitd for Apple SDK or Xcode build settings
- never load
sourcekitd from one toolchain while passing compiler or plugin paths from another
- Choose the surface using references/semantic-index-surfaces.md:
- raw SourceKit for precise live semantic requests
- SourceKitten for an accepted Swift or JSON convenience layer
- compiler index store plus IndexStoreDB for project-wide symbols, occurrences, and relations
- SourceKit-LSP when a standard editor-facing protocol already covers the request
- Reconstruct exact compiler arguments from the real build. Include target, SDK, module search paths, language mode, conditional flags, generated sources, bridging inputs, and plugins when applicable.
- Keep the source text and position representation paired. Record whether positions are UTF-8 byte offsets, line and column pairs, or LSP positions.
- Verify build and index freshness before interpreting missing results.
- Normalize output into typed domain records at the integration boundary instead of spreading SourceKit keys or loose JSON dictionaries through the application.
- Test absent symbols, overloads, extensions, generated code, conditional compilation, and stale-index behavior.
SourceKitten Policy
- Treat SourceKitten as a third-party wrapper and CLI around SourceKit, not as the source of semantic truth.
- Use it when its
structure, syntax, doc, index, complete, or raw-request JSON contract matches a concrete integration need.
- Check installation and toolchain resolution before use; do not assume SourceKitten is bundled with Swiftly or Xcode.
- Prefer a direct supported library or LSP contract when adding SourceKitten would only translate one unstable representation into another.
Output
Return semantic scope, selected toolchain, selected surface, compiler-argument source, position encoding, index freshness, query result, and uncertainty.
Guardrails
- Do not answer inferred-type or reference questions from SwiftSyntax alone.
- Do not treat a missing index result as proof that a symbol is unused before verifying every relevant target was indexed.
- Do not reuse byte offsets after source text changes.
- Do not pass machine-local SourceKit or SDK paths into shared package manifests.
- Do not let raw SourceKit dictionaries become a public application API.
1---2name: swift-semantic-indexing-workflow3description: Query Swift types, USRs, documentation, occurrences, references, and relationships with SourceKit, SourceKitten, index stores, and IndexStoreDB. Use for file-local semantics or project-wide symbol questions.4license: Apache-2.05---67# Swift Semantic Indexing Workflow89Choose between live file semantics and persisted project-wide index data without substituting syntax shape for type-checked meaning.1011## Workflow12131. State the semantic question and required scope:14 - one source snapshot at a byte position15 - one file or module16 - project-wide occurrences and relations17 - documentation or generated interface182. Resolve the toolchain that produced or should interpret the source:19 - use Swiftly for matching Swift.org toolchains and cross-platform SwiftPM builds20 - use Xcode's `xcrun` tools and `sourcekitd` for Apple SDK or Xcode build settings21 - never load `sourcekitd` from one toolchain while passing compiler or plugin paths from another223. Choose the surface using [references/semantic-index-surfaces.md](references/semantic-index-surfaces.md):23 - raw SourceKit for precise live semantic requests24 - SourceKitten for an accepted Swift or JSON convenience layer25 - compiler index store plus IndexStoreDB for project-wide symbols, occurrences, and relations26 - SourceKit-LSP when a standard editor-facing protocol already covers the request274. Reconstruct exact compiler arguments from the real build. Include target, SDK, module search paths, language mode, conditional flags, generated sources, bridging inputs, and plugins when applicable.285. Keep the source text and position representation paired. Record whether positions are UTF-8 byte offsets, line and column pairs, or LSP positions.296. Verify build and index freshness before interpreting missing results.307. Normalize output into typed domain records at the integration boundary instead of spreading SourceKit keys or loose JSON dictionaries through the application.318. Test absent symbols, overloads, extensions, generated code, conditional compilation, and stale-index behavior.3233## SourceKitten Policy3435- Treat SourceKitten as a third-party wrapper and CLI around SourceKit, not as the source of semantic truth.36- Use it when its `structure`, `syntax`, `doc`, `index`, `complete`, or raw-request JSON contract matches a concrete integration need.37- Check installation and toolchain resolution before use; do not assume SourceKitten is bundled with Swiftly or Xcode.38- Prefer a direct supported library or LSP contract when adding SourceKitten would only translate one unstable representation into another.3940## Output4142Return semantic scope, selected toolchain, selected surface, compiler-argument source, position encoding, index freshness, query result, and uncertainty.4344## Guardrails4546- Do not answer inferred-type or reference questions from SwiftSyntax alone.47- Do not treat a missing index result as proof that a symbol is unused before verifying every relevant target was indexed.48- Do not reuse byte offsets after source text changes.49- Do not pass machine-local SourceKit or SDK paths into shared package manifests.50- Do not let raw SourceKit dictionaries become a public application API.
gaelic-ghost