up

docs/modules/scanner/design/dart-swift-analyzer-scope.md

@@ -0,0 +1,46 @@
+# Dart & Swift Analyzer Scope Note (2025-12-09)
+
+## Goals
+- Define the initial analyzer scope for Dart (pub) and Swift (SwiftPM) with deterministic, offline-friendly behavior.
+- Provide fixture/backlog list to unblock readiness tracking and align with Signals/Zastava expectations.
+
+## Dart (pub)
+- Inputs: `pubspec.yaml`, `pubspec.lock`, `.dart_tool/package_config.json`, and downloaded packages under `.dart_tool/pub`.
+- Outputs:
+  - Inventory of `pkg:pub/<name>@<version>` with resolved source (hosted/path/git) and sha256 when present in lockfile.
+  - Dependency edges from `pubspec.lock`; dev dependencies emitted only when `include_dev=true`.
+  - Analyzer metadata: sdk constraint, null-safety flag, source type per package.
+- Determinism:
+  - Sort packages and edges lexicographically.
+  - Normalize paths to POSIX; no network calls; rely only on lockfile/package_config on disk.
+- Out of scope (v1):
+  - Flutter build graph, transitive runtime surface, and hosted index downloads.
+  - Git/path overrides beyond what is listed in lock/package_config.
+- Fixtures/backlog:
+  - Hosted app with `pubspec.lock` and `.dart_tool/package_config.json` (dev deps included).
+  - Path dependency sample (relative and absolute).
+  - Git dependency sample with locked commit.
+  - Missing lockfile case (expect finding + no inventory).
+
+## Swift (SwiftPM)
+- Inputs: `Package.swift`, `Package.resolved` (v1/v2), `.build/` manifest cache when present.
+- Outputs:
+  - Inventory of `pkg:swiftpm/<name>@<version>` with checksum from `Package.resolved` when available.
+  - Dependency edges from `Package.resolved` target graph; emit platforms/arch only when declared.
+  - Analyzer metadata: Swift tools version, resolution format, mirrors when specified.
+- Determinism:
+  - Do not execute `swift package`; parse manifests/resolved files only.
+  - Stable ordering by package then target; normalize paths to POSIX.
+- Out of scope (v1):
+  - Xcodeproj resolution, binary target downloads, and build artifacts hashing.
+  - Conditional target resolution beyond what `Package.resolved` records.
+- Fixtures/backlog:
+  - Single-package app with `Package.resolved` v2 (checksum present).
+  - Nested target graph with products/targets/flexible platforms.
+  - Binary target entry (no download; expect metadata-only inventory).
+  - Missing `Package.resolved` case (emit finding, no inventory).
+
+## Alignment & Next Steps
+- Signals/Zastava: confirm package ID naming (`pkg:pub`, `pkg:swiftpm`) and dependency edge semantics for reachability ingestion.
+- Add goldens/fixtures under `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.DartSwift.Tests/Fixtures/**`.
+- Update readiness checkpoints once fixtures and parsers land; current scope note unblocks backlog creation only.