up

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

@@ -0,0 +1,44 @@
+# Deno Analyzer Scope · SCANNER-ENG-0011 (2025-12-08)
+
+## Goals
+- Deliver offline-safe Deno analyzer (lockfile/import graph/runtime signals) that matches Ruby/PHP parity bar.
+- Provide deterministic SBOM/inventory outputs and capability signals consumable by Policy/Surface.
+
+## Inputs
+- `deno.json` / `deno.jsonc` (tasks, import map refs, npm bridging).
+- `deno.lock` v2/v3 (modules, npm section, integrity hashes).
+- Optional `import_map.json`; vendor/cache roots (`$DENO_DIR`, `vendor/`).
+- CLI flags via Surface.Env: `deno.disable_npm`, `deno.vendor`, `deno.lock_path`, `deno.import_map`.
+
+## Pipeline (deterministic, offline)
+1) **Normalize config**: parse `deno.json`/jsonc; resolve `importMap` path; default to repo root import map if present. Sort keys.
+2) **Lock resolver**: read `deno.lock`; emit components:
+   - `npm:` entries → PURL (`pkg:npm/<name>@<version>`) + integrity from `integrity`.
+   - `specifiers` → source→target map for transitive graph.
+   - `modules` (remote URLs) → canonical URL + content hash when present; mark `fetchSource: cache`.
+3) **Import map & vendor**:
+   - Apply `imports`/`scopes` to rewrite edges before graph emission.
+   - If `vendor/` exists, prefer vendored paths; emit `provenance: vendor`.
+4) **Graph builder**:
+   - Build module graph from `specifiers` + import map rewrites; emit edges `(from -> to, kind: import|dynamic|npm)`.
+   - Recognise `npm:` specifiers; map to npm package node.
+   - Stable ordering: sort by `from, to`.
+5) **Runtime/capability signals**:
+   - Detect permissions from `tasks` (`--allow-*` flags) and `deno.json` `unstable`/`no-check`.
+   - Capture `nodeModulesDir` toggle to flag npm bridge.
+6) **Outputs**:
+   - Inventory: npm components + remote module list (`digest`, `source`, `origin`).
+   - Graph: edges with provenance (`lockfile`, `import_map`, `vendor`).
+   - Signals: `deno.permissions[]`, `deno.node_compat`, `deno.unstable`.
+
+## Tests & fixtures
+- Add fixtures under `src/Scanner/__Tests/StellaOps.Scanner.Analyzers.Lang.Deno.Tests/Fixtures/`:
+  - lockfile v2 + import map,
+  - lockfile v3 with npm section,
+  - vendorized project (`vendor/` present).
+- Determinism assertions: sorted edges, stable hash of inventory, no network calls (enforce via stubbed fetcher).
+
+## Deliverables
+- Analyzer implementation + tests in `StellaOps.Scanner.Analyzers.Lang.Deno`.
+- Doc cross-link to `docs/modules/scanner/implementation_plan.md` and sprint log.
+- Offline posture: default `LIVE_FETCH=false` equivalent; rely solely on lock/import map/vendor.