feat(parsers): replace Swift regex parser with swift-symbolgraph-extract

[grdsdev]

Summary

Replaces the handrolled swift-parser.ts (a ~170-line regex scanner with brace-depth tracking) with swift package dump-symbol-graph — the Swift compiler's own tool for public API surface extraction — and a thin TypeScript normalizer.

Why

The regex parser had known blind spots: multi-line declarations, #if conditional compilation, attributes spanning lines, and could not model access control semantics (@_spi, @usableFromInline, re-exports). Root cause: regex cannot reliably parse Swift. swift package dump-symbol-graph uses the Swift compiler and gets it right by construction.

Approach

swift package dump-symbol-graph              # builds + extracts all library targets
  --minimum-access-level public              # filter at source — only public/open symbols
  --skip-synthesized-members                 # suppress _Concurrency actor conformance noise
  → <triple>/symbolgraph/*.symbols.json

jq -s '[.[] | .symbols[]]' *.symbols.json   # merge into flat array
  → merged-raw.json

normalize-symbolgraph <merged-raw.json> <root>   # thin TS normalizer (new)
  → ParseResult JSON
  → check-api-symbols  (unchanged)

Changes

Added

• src/normalize-symbolgraph.ts — core normalizer: SymbolGraphSymbol[] → ParseResult
• src/normalize-symbolgraph-cli.ts — CLI entry point (npm run normalize-symbolgraph)
• test/normalize-symbolgraph.test.ts — 103 tests (kind mapping, name construction, file path, fixture smoke tests)
• test/fixtures/symbolgraph-sample.json — real dump-symbol-graph output (17 symbols, public/open only)

Removed

• src/swift-parser.ts, src/parse-swift.ts — regex parser
• test/swift-parser.test.ts — regex parser tests

Modified

• .github/workflows/validate-sdk-compliance.yml — Swift-conditional steps: macos-latest runner, swift package dump-symbol-graph, jq merge, normalizer dispatch; existing parse steps guarded for only javascript; actions/cache SHA-pinned; Dart steps from feat(parsers): add Dart public API parser via package:analyzer (alternative to #35) #41 integrated
• package.json — normalize-symbolgraph replaces parse-swift

Key decisions

• --minimum-access-level public: filters at source, so the normalizer needs no access-level check of its own
• --skip-synthesized-members: prevents _Concurrency protocol conformance methods (e.g. withSerialExecutor) from generating false-positive "new symbol" CI failures when a PR adds a new public actor
• || true on extraction: dump-symbol-graph also tries test targets, which can fail to load on CI runners; library targets land before the test-target attempt, so || true + a file-count guard lets the step continue correctly
• macos-latest runner: Swift is pre-installed; avoids swift-actions/setup-swift overhead on ubuntu

Test plan

• 103 tests pass (npm test — 11 files)
• TypeScript strict check clean (npm run typecheck)
• Fixture is real dump-symbol-graph --minimum-access-level public output (not hand-authored)
• E2E verified: full CI run on supabase-swift passed (both validate and check jobs)

[spydon]

Can't we use the swift package dump-symbol-graph instead of going as low-level as we do in this PR?

swift package dump-symbol-graph \
  --minimum-access-level public \
  --skip-synthesized-members \
  --output-directory ./symbolgraph

[grdsdev]

Good call — replaced the manual swift build + module-discovery loop + swift-symbolgraph-extract invocation with a single swift package dump-symbol-graph --minimum-access-level public --skip-synthesized-members call (commit 82af3bf). Drops ~30 lines and removes the need to resolve TRIPLE/SDK/-I flags manually.

🤖 Addressed by Claude Code

[spydon]

The symbol graph should be regenerated with swift package dump-symbol-graph --minimum-access-level public --skip-synthesized-members I think?
If you do that the the access-filter assertions can be dropped.

[grdsdev]

Done in commit a88c801 — fixture regenerated with swift package dump-symbol-graph --minimum-access-level public --skip-synthesized-members (only public/open symbols, InternalClass absent from output), and the access-filter test block + the excludes InternalClass smoke assertion removed (5 tests dropped, 103 remain).

🤖 Addressed by Claude Code