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

Scanner Language Analyzer Contracts (Identity / Evidence / Container Layout)

This document freezes the cross-analyzer contracts that are shared by the language analyzers (Java, .NET, Python, Node, Bun). These rules exist to prevent false matches, keep outputs deterministic, and protect against host-path leakage.

1) Identity Safety Contract (PURL vs Explicit Key)

1.1 Goals

• No fake versions: never encode version ranges, tags, local paths, or git URLs as a versioned PURL.
• No collisions: explicit-key identities must not collide with concrete PURLs and must be deterministic across OS path separators.
• Proof-first: emit concrete PURLs only when the analyzer has concrete, replayable evidence for the version.

1.2 When to emit a concrete PURL

Emit a concrete (versioned) PURL only when both are true:

1. The analyzer can determine a concrete version (ecosystem-specific) for the component.
2. The version is backed by replayable evidence (e.g., installed artifact metadata or lockfile-resolved entry).

Typical sources that qualify:

• Installed inventory (e.g., node_modules/**/package.json, Python *.dist-info/METADATA, .NET deps.json entries).
• Lockfile-resolved inventory (e.g., bun.lock entry with name@version and integrity/resolved URL).

1.3 When to emit an explicit-key component (required)

Emit an explicit-key component when the dependency is declared-only or otherwise non-concrete:

• Version ranges / operators (^, ~, >=, <, *, x, latest, etc.).
• Workspace/link/file dependencies (workspace:*, link:, file:, local path refs, editable installs).
• Git dependencies (git URL / commit / ref) when a concrete semantic version is not provable from local evidence.
• Unknown / missing version.

Rule: If the analyzer cannot prove a concrete version from local evidence, it must not emit a versioned PURL for that dependency.

1.4 Explicit-key format (canonical)

For declared-only / non-concrete identities, analyzers must emit:

• componentKey: explicit::<analyzerId>::<ecosystem>::<name>::sha256:<digest>
• purl: null
• version: null

Where <digest> is sha256 of the canonical UTF-8 string:

<ecosystem>\n<normalizedName>\n<normalizedSpec>\n<originLocator>

Canonicalization rules:

• <normalizedName> uses ecosystem naming rules (e.g., npm scoped names keep @scope/name).
• <normalizedSpec> is the original declared specifier (range/tag/url/path), trimmed; for unknown, use "".
• <originLocator> is project-relative with / separators (e.g., package.json#dependencies, requirements.txt, Directory.Packages.props#PackageVersion:Foo).
• No absolute paths, drive letters, or host roots appear in any input to the digest.

1.5 Required metadata for explicit-key components

Explicit-key components must include (at minimum) these metadata keys:

• declaredOnly=true
• declared.source=<file> (e.g., package.json, Directory.Packages.props)
• declared.locator=<originLocator> (same string used in digest)
• declared.versionSpec=<normalizedSpec> (original specifier or empty)
• declared.scope=<prod|dev|peer|optional|unknown> when applicable
• declared.sourceType=<range|tag|git|tarball|file|link|workspace|path|editable|unknown>

2) Evidence Locator Contract

2.1 General rules

• Evidence locators are external-facing and must be stable and parseable.
• Every locator is project-relative with / separators (never absolute).
• Evidence content/hashing must be bounded; when bounds are exceeded, emit deterministic skipped markers in metadata instead of silently omitting.

2.2 Locator formats (canonical)

File evidence

• locator: <relativePath> (e.g., packages/app/package.json)
• source: a stable discriminator (e.g., package.json, pom.xml, METADATA)

Lockfile entry evidence

• locator: <lockfileRelativePath>:<selector>
• Examples:
  • Node package-lock: package-lock.json:packages/app/node_modules/foo
  • Bun lock: bun.lock:packages[foo@1.2.3]
  • Maven/Gradle lock: gradle.lockfile:com.example:foo:1.2.3

Nested artifact evidence

• locator: <outer>!<inner>!<path>
• Example: demo-jni.jar!META-INF/native-image/demo/jni-config.json

Derived evidence

• locator: a stable synthetic name (e.g., phase22.ndjson)
• source: a stable synthetic source (e.g., node.observation)

2.3 Hashing rules (baseline)

• Hash only bounded inputs (default: 1 MiB per evidence value/file; analyzers may choose a tighter cap).
• Hash algorithm: sha256 over UTF-8 bytes for textual evidence, raw bytes for file evidence.
• If hashing is skipped due to bounds or errors, emit deterministic metadata markers (e.g., hashSkipped=true, hashSkipped.reason=sizeCap).

3) Container Layout Discovery Contract

3.1 Layer root candidates

Language analyzers that support container-root discovery must treat these as candidate roots under the analysis root:

• layers/* (direct children)
• .layers/* (direct children; must not be skipped)
• layer* (direct children of the analysis root, e.g., layer1/, layer2/)

Each candidate root is scanned independently for projects.

3.2 Bounds and traversal safety (required)

• Deterministic traversal (sorted directory enumeration).
• Depth caps per candidate root; hard cap on total discovered project roots.
• Must never recurse into node_modules/ (Node/Bun) or equivalent heavy dirs.
• Hidden directories may be skipped except .layers which is treated as a top-level candidate root.
• No symlink escape: if symlinks are followed, resolved targets must remain within the candidate root prefix and cycles must be prevented.

3.3 Overlay/whiteout semantics

• If an analyzer implements overlay semantics (notably Python container adapters), whiteouts and precedence rules must be explicit, deterministic, and fixture-tested.
• If an analyzer does not implement overlay semantics, it must still keep discovery bounded and must not silently drop projects; emit deterministic "skipped" markers when bounds prevent full traversal.

Compliance

Sprints docs/implplan/SPRINT_0403_0001_0001_scanner_java_detection_gaps.md through docs/implplan/SPRINT_0407_0001_0001_scanner_bun_detection_gaps.md (and the program sprint docs/implplan/SPRINT_0408_0001_0001_scanner_language_detection_gaps_program.md) carry the per-analyzer implementation and test evidence required to enforce this contract.