up

docs/modules/scanner/design/swiftpm-coverage-plan.md

@@ -0,0 +1,42 @@
+# 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.