git.stella-ops.org/docs/modules/scanner/analyzers-node.md

# Node Analyzer (npm/Yarn/pnpm)

This document captures the Node language analyzer’s deterministic behavior guarantees and safety constraints (what it emits, what it refuses to emit, and how it stays bounded/offline).

## Component identity & precedence

### Installed vs declared-only
- The analyzer always emits **on-disk inventory** first (workspace member manifests + installed `node_modules`/PNPM/Yarn PnP cache packages).
- It then emits **declared-only** components for lockfile / manifest declarations that are **not backed by on-disk inventory**:
  - If a declared entry has a **concrete resolved version** from a lockfile, it emits a versioned `pkg:npm/...@<version>` PURL.
  - If the version is **non-concrete** (ranges/tags/git/file/workspace/link/path), it emits an **explicit-key** component (`purl=null`, `version=null`).

### Identity safety (PURL vs explicit-key)
- Concrete PURLs are emitted only when the analyzer can prove a **concrete version** from local evidence (installed `package.json` or a lockfile-resolved entry).
- Declared-only/non-concrete dependencies use `LanguageExplicitKey` (see `docs/modules/scanner/language-analyzers-contract.md`).

### Lock metadata lookup precedence
When attaching lock metadata to an installed package:
1) `package-lock.json` path match (`packages["<relativePath>"]`),
2) `(name, version)` match (Yarn/pnpm multi-version support),
3) fallback to name-only (last-wins) for legacy locks.

## Lockfile parsing guarantees (offline)

### `package-lock.json` (npm)
- Supports v3+ `packages{}` layout and legacy `dependencies{}` traversal.
- Correctly extracts nested names from `node_modules/.../node_modules/...` paths (including scoped packages).

### `yarn.lock` (Yarn v1 + Berry v2/v3)
- Supports both Yarn v1 (`resolved "https://..."`) and Berry fields (`resolution:`, `checksum:`).
- If `integrity` is absent but `checksum` is present, the analyzer records integrity-like evidence as `checksum:<value>`.
- Ignores the `__metadata` section.

### `pnpm-lock.yaml` (pnpm)
- Parses modern `packages:` and `snapshots:` sections.
- Does not drop entries that lack `integrity` (workspace/link/file/git); instead it emits:
  - `lockIntegrityMissing=true`
  - `lockIntegrityMissingReason=<workspace|link|file|git|directory|missing>`

## Workspaces
- Reads workspace members from the root `package.json` (`workspaces` array or `{ packages: [...] }` form).
- Supports glob patterns:
  - `*` (single segment)
  - `**` (multi-segment)
- Expansion is bounded and deterministic:
  - Skips `node_modules`
  - Caps traversal depth and total visited directories/members
  - Stable, sorted member output
- Dependency scopes (`production|development|peer|optional`) are derived from both the root and workspace manifests, with deterministic precedence.

## Import scanning (bounded)
- Import scanning runs only for the root package and workspace member packages (not `node_modules` packages).
- File types: `.js/.jsx/.mjs/.cjs/.ts/.tsx/.mts/.cts`.
- Parser behavior:
  - Attempts AST parsing as script/module; falls back to a bounded regex heuristic for TS when parsing fails.
- Hard caps per package:
  - `maxFiles=500`, `maxBytes=5MiB`, `maxFileBytes=512KiB`, `maxDepth=20`
  - Skips `node_modules` and `.pnpm` directories during traversal
- If capped, the analyzer marks the package metadata with:
  - `importScanSkipped=true`
  - `importScan.filesScanned=<n>`
  - `importScan.bytesScanned=<n>`

## Container layer layouts
- Candidate layer roots under the analysis root:
  - `layers/*`, `.layers/*`, `layer*`
- Each candidate root is scanned independently.
- The analyzer also discovers `package.json` roots nested under layer roots (bounded depth) and includes their nested `node_modules` roots when present.

## Determinism & evidence hashing
- On-disk `package.json` manifests are hashed (sha256) when ≤ 1 MiB and attached to the root evidence for deterministic provenance.
- Output ordering is stable (componentKey ordering, sorted metadata/evidence).

## Benchmark
- Scenario id: `node_detection_gaps_fixture` (config: `src/Bench/StellaOps.Bench/Scanner.Analyzers/config.json`)
- Fixture root: `samples/runtime/node-detection-gaps`
- Run:
  - `dotnet run --project src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/StellaOps.Bench.ScannerAnalyzers.csproj -- --repo-root . --config src/Bench/StellaOps.Bench/Scanner.Analyzers/config.json --json out/bench/scanner-analyzers/latest.json --prom out/bench/scanner-analyzers/latest.prom`
  - Prometheus output includes additional metrics under `scanner_analyzer_bench_metric{scenario=\"...\",name=\"node.importScan.*\"}`.