up

docs/modules/scanner/design/dart-analyzer-plan.md

@@ -0,0 +1,41 @@
+# Dart Analyzer Scope · SCANNER-ENG-0012 (2025-12-08)
+
+## Goals
+- Define Dart analyzer for pubspec/pub cache parity with other language analyzers.
+- Keep offline-first (no `pub get`), deterministic inventories/graphs, and policy-ready signals.
+
+## Inputs
+- `pubspec.yaml` + `pubspec.lock` (dependencies, sources, sdk constraints).
+- `.dart_tool/package_config.json` (resolved packages, language version, root URIs).
+- AOT artifacts: `*.aot`, `*.snapshot`, `build/` outputs (record presence only).
+- Optional Flutter plugins: `ios/`/`android/` platform manifests (metadata only).
+
+## Pipeline (deterministic, offline)
+1) **Normalize pubspec/pubspec.lock**:
+   - Parse lock entries; map sources: `hosted`, `sdk:flutter`, `git`, `path`.
+   - Emit PURLs (`pkg:pub/<name>@<version>`) with `source` metadata (`hosted.url`, `git.sha`, `path`).
+   - Enforce sorted components by name.
+2) **Package config**:
+   - Read `.dart_tool/package_config.json`; map package `rootUri`/`packageUri` to build module graph roots.
+   - Capture `languageVersion` and `generated` timestamp (drop or normalize to `0001-01-01Z` for determinism).
+3) **Graph builder**:
+   - Build dependency edges from `pubspec.lock` -> `package_config` packages; include `sdk:flutter` nodes when present.
+   - Record `sourceType` (hosted/git/path/sdk) for provenance.
+4) **Signals**:
+   - `dart.sdk` requirement from `environment.sdk`; `flutter` channel/version when present.
+   - AOT snapshot presence flags (`aot=true`, `snapshot=true`); no binary parsing.
+5) **Outputs**:
+   - Inventory: list of PURLs + source metadata + checksum if provided in lock (hosted `sha256`).
+   - Graph: edges `(package -> dependency)` sorted.
+   - Signals: `dart.sdkConstraint`, `flutter.sdk`, `flutter.plugins` (names only), `buildArtifacts` flags.
+
+## Tests & fixtures
+- Fixtures under `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.Dart.Tests/Fixtures/`:
+  - Hosted-only lockfile, git dependency, path dependency, Flutter project with plugins.
+  - Determinism tests: stable ordering, normalized timestamps, no network.
+  - Signal tests: sdk constraint extraction, AOT/snapshot flagging.
+
+## Deliverables
+- Design captured here; wire into implementation plan + sprint log.
+- Analyzer to live under `StellaOps.Scanner.Analyzers.Lang.Dart` with tests mirroring fixtures.
+- Offline posture: never invoke `dart pub`; rely solely on provided lock/config; error clearly when missing lock.