Files
git.stella-ops.org/docs/modules/scanner/design/deno-analyzer-plan.md
StellaOps Bot bc0762e97d up
2025-12-09 00:20:52 +02:00

2.5 KiB

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.