git.stella-ops.org/docs/modules/scanner/design/swiftpm-coverage-plan.md

SwiftPM Coverage Plan · SCANNER-ENG-0013 (2025-12-08)

Goals

• Plan Swift Package Manager coverage for Scanner: inventory, dependency graph, xcframework/binary target awareness, runtime hints.
• Keep processing offline and deterministic; no swift package execution.

Inputs

• Package.swift (manifest) and Package.resolved (v2/v3 lockfile).
• .build/checkouts/** (optional for checksum verification only).
• Binary targets: binaryTarget entries, xcframeworks under .xcframework/.
• Platform hints: platforms, cLanguageStandard, cxxLanguageStandard.

Pipeline (deterministic, offline)

1. Resolve lockfile:
   • Parse Package.resolved; emit packages with identity, version, repo URL, checksum.
   • PURL: pkg:swift/<identity>@<version>; include vcs metadata (git URL, revision).
   • Sort packages by identity.
2. Manifest signals:
   • Parse Package.swift (static parse via tree-sitter Swift or manifest JSON dump if available) to extract:
     • products/targets (name, type library/test/executable).
     • binary targets (path/url, checksum).
     • platform minimum versions.
3. Graph builder:
   • Edges from targets → dependencies; packages → transitive dependencies from lockfile pins.
   • Mark binary targets with provenance: binary-target and attach checksum if supplied.
4. Runtime hints:
   • Collect unsafeFlags, linker settings, swiftSettings/cSettings/cxxSettings indicators (e.g., -enable-library-evolution).
   • Emit xcframework presence for Apple platform binaries.
5. Outputs:
   • Inventory: Swift packages (PURL + checksum/vcs), binary targets (type=binary, checksum/path).
   • Graph: package dependency edges; target-to-target edges (optional).
   • Signals: platform minimums, binary target flags, unsafe flags presence.

Tests & fixtures

• Fixtures under src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Native.Tests/Fixtures/SwiftPM/:
  • Simple library/executable, binary target with checksum, mixed platform constraints.
  • Determinism: stable ordering, normalized checksums, no filesystem time dependency.

Deliverables

• Implementation to land under StellaOps.Scanner.Analyzers.Native (SwiftPM module).
• Documentation cross-link to sprint log and docs/modules/scanner/implementation_plan.md.
• Offline posture: never invoke swift build; rely solely on Package.resolved/manifest; error clearly when lockfile missing.