codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/README.md

@@ -1,10 +1,14 @@
 # codemetrics-ai
 
-Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.4.0 implements source metrics and React hook/effect checks and emits schema-v3 evidence, including executed scoring decisions. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
+Deterministic source analysis for JavaScript, TypeScript, JSX and TSX, with Python support in preview 0.6.0-preview.1. The package implements source metrics and React hook/effect checks and emits schema-v3 evidence, including executed scoring decisions. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
 
 Each scored dimension includes `scoringDecision`: policy inputs, executed steps, rounding and finding attribution. These are aggregate policy decisions, not independent finding deductions. See [the decision contract](../../shared/scorecard-schema/scoring-decisions.md).
 
-The 0.4.0 ruleset `javascript-typescript-2026-10-04-local-handlers` replaces the published 0.3.0 maximum-CC/median-MI ladders with owned-function population scores and extends React-only checks with bounded promise-usage analysis. It also corrects erased TypeScript syntax in owned-body measurements, scores async usage by affected eligible owners, and adds unscored module dependency, decomposition, and error-handler evidence. Generate new baselines when upgrading from 0.3.0. See the [0.4.0 release and migration notes](https://github.com/sean-m-cooper/CodeMetrics.AI/blob/master/docs/releases/javascript-typescript-0.4.0.md).
+Version 0.5.0 uses `javascript-typescript-2026-10-09-handler-contracts` and adds
+contextual Error Handling scoring. Adopting it requires a fresh baseline. See the
+[0.5.0 release notes](../../docs/releases/javascript-typescript-0.5.0.md).
+
+The earlier 0.4.0 ruleset `javascript-typescript-2026-10-04-local-handlers` replaces the published 0.3.0 maximum-CC/median-MI ladders with owned-function population scores and extends React-only checks with bounded promise-usage analysis. It also corrects erased TypeScript syntax in owned-body measurements, scores async usage by affected eligible owners, and adds unscored module dependency, decomposition, and error-handler evidence. Generate new baselines when upgrading from 0.3.0. See the [0.4.0 release and migration notes](https://github.com/sean-m-cooper/CodeMetrics.AI/blob/master/docs/releases/javascript-typescript-0.4.0.md).
 
 ```sh
 npx codemetrics-ai --project package.json
@@ -16,13 +20,18 @@ Default output paths are `.scorecard/javascript-typescript/metrics.csv` and `.sc
 
 ## Implemented scope
 
+Preview 0.6.0-preview.1 adds unscored npm/pnpm dependency inventory and optional
+registry observations under ruleset `javascript-typescript-2026-10-09-dependency-evidence`.
+It requires fresh baselines. Stable 0.5.0 does not include this extension. Install the preview explicitly; the npm `latest` tag stays on the stable release.
+
 | Dimension | Implementation |
 |---|---|
 | codeQuality (Method Complexity) | 40% one worst function score + 60% mean remaining; owned CC findings above 10. Decomposition has descriptive size/distribution evidence and no score. |
 | maintainability | 40% mean weakest ceil(N/5) function scores + 60% mean remaining |
 | performanceAsync (Async/Blocking Usage) | React hook/effect checks, standard Promise async executors, and informational async Array.forEach callbacks |
 | architecture | Module dependencies, explicit type-only separation, internal cycle groups and fan-in/out rankings; score remains unmeasured |
-| errorHandling | Catch clauses and inline/referenced standard Promise rejection handlers; unique bodies, linked uses, and documented intent; no score |
+| errorHandling | Contextual failure dispositions for distinct catch/Promise handler bodies; scores unexplained swallowing only with a fully assessed population |
+| dependencyManagement (preview) | npm lockfile v2/v3 and pnpm v9 inventory, workspace uses, optional public-registry deprecation/update/advisory observations; no score |
 | Other dimensions | Explicitly skipped |
 
 React checks run only when a source file imports React. Aliased named imports and namespace imports are recognized; local functions shadowing imports are excluded. Missing dependency arrays are advisory because running after every render can be intentional. The implementation does not claim exhaustive Rules of Hooks, dependency-array correctness, or general concurrency analysis. Source syntax errors make the run incomplete and source dimensions unscored. Semantic type errors are outside this AST-focused version's completeness check.
@@ -44,7 +53,9 @@ This is bounded source analysis, not promise-flow verification. Referenced execu
 
 `codeQuality.componentDetails.decomposition` version 2 uses owned executable statements as its primary measure. It ranks functions/modules by statements and reports statement totals, median/p90, and module concentration. Lines and initializer/literal/declaration/re-export observations remain context. Nested bodies are counted separately. Size is not responsibility: data tables, barrels, and orchestration roles receive no inferred defect or deduction. Code Quality remains a method-complexity score.
 
-`errorHandling.handlerEvidence` distinguishes unexplained empty syntax, documented empty bodies, and bodies containing code. Body comments acknowledge developer intent without judging the business rationale. Empty bodies produce informational review leads only; fallback behavior outside the handler may explain them. Referenced Promise callbacks resolve through function declarations, const aliases, and imports within selected source. Shared implementations count once, with call sites attached. Reassigned, mutable, unsupported, and out-of-scope references retain reasoned inspection gaps. No handlers means an unavailable percentage, not a perfect score. See the [evidence contract](../../shared/scorecard-schema/javascript-typescript-context-evidence.md).
+`errorHandling.handlerEvidence` preserves empty/documented/nonempty syntax measurements and links each distinct implementation to its uses. Referenced Promise callbacks resolve through function declarations, const aliases, and imports within selected source. The new `dispositionEvidence` separates explicit outcomes, recognized fallback, documented intent, unexplained swallowing, and unknown paths. Nonempty code alone does not establish handling. Attached intent is honored without judging the business rationale.
+
+When every observed body is assessed and no callback uses are unresolved, Error Handling scores `10 - 10 * unexplainedSwallowing / assessedHandlers`, capped at 9 if any issue exists, rounded half up to one decimal. Shared bodies count once. Unknown dispositions, unresolved callbacks, and absent populations yield no score. Scores describe bounded handling signals, not proven recovery or bugs. See the [policy and recognition limits](../../shared/scorecard-schema/javascript-typescript-error-handling-policy.md).
 
 ## Module architecture evidence
 
@@ -58,6 +69,23 @@ Cycles are strongly connected groups of resolved internal value/mixed dependenci
 
 Architecture retains `status: skipped` and no score until calibration. Other measured dimensions remain usable when this diagnostic graph has resolution gaps. Source parse failures retain partial graph evidence with `status: failed` and the existing incomplete-analysis exit. Schema v3 is unchanged; the new scope/ruleset requires fresh baselines. See the [graph contract](../../shared/scorecard-schema/javascript-typescript-module-graph.md).
 
+## Dependency observations (development)
+
+Inventory supports npm lockfiles v2/v3 and pnpm v9, including pnpm 12 environment/project documents, catalogs, workspace links, aliases, and peer snapshots. The project graph is selected; environment tooling is explicitly excluded. Peer variants retain locations without multiplying package/version counts. Older pnpm formats and file/git/custom resolutions remain gaps. Integrity-only records do not establish public-registry provenance.
+
+Inventory is local by default. `--dependency-metadata` explicitly enables bounded
+public npm registry metadata and bulk advisory queries. It never installs target
+dependencies or runs their scripts. Unsupported package managers, stale locks,
+private/unknown sources, and failed queries are exposed as coverage gaps.
+Optional peers and locked range differences remain contextual notices. Duplicate
+installations retain their locations without creating independent penalties.
+
+Deprecation, `wanted` updates within direct declared ranges, `latest` releases,
+and advisories are separate observations. Exact pins and newer major versions do
+not establish neglect; advisory presence does not establish runtime reachability.
+The dimension remains unscored. See the [dependency policy](../../shared/scorecard-schema/javascript-typescript-dependency-policy.md)
+for counting, limits, availability, and calibration boundaries.
+
 ## Discovery
 
 The CLI discovers files from each package's tsconfig when present, otherwise scans source extensions. Positive npm workspace globs (including object-form `workspaces.packages`) are supported. Each child package owns its files and exclusions; the root cannot re-include a child's excluded files. External tsconfig references are not recursively analyzed as separate packages: include them in the workspace manifest. Explicit missing manifests/configs and unsupported negative workspace patterns are errors.
@@ -120,7 +148,7 @@ evidence. Overall dependencies and cycle findings remain intact, including mixed
 files and cycles crossing the views. Architecture is still unscored. See the
 [dependency view contract](../../shared/scorecard-schema/javascript-typescript-module-graph.md#implementation-reference-and-public-re-export-views).
 
-`metrics.ts` owns source traversal, raw member metrics and finding identities. `function-measurements.ts` collects the separate owned-body measurements; `function-scoring.ts` applies the two population policies with exact interpolation/rounding from `score-arithmetic.ts`. `react-probe.ts` checks calls owned by each function for React hook/effect observations. `async-probe.ts` checks each visited node once for bounded standard-library promise patterns, including module-level operations. Neither probe traverses nested bodies or calculates metrics. `async-population.ts` assigns distinct eligible owners; `async-scoring.ts` applies the population ladder. `decomposition-evidence.ts` records function size and module distribution without deductions. `handler-resolution.ts` performs bounded declaration lookup; `error-handling.ts` records distinct handler bodies, use sites, and body comments without a score. Regression fixtures preserve raw metrics, source locations and existing finding fingerprints; advisory severity/disposition changes are intentional.
+`metrics.ts` owns source traversal, raw member metrics and finding identities. `function-measurements.ts` collects the separate owned-body measurements; `function-scoring.ts` applies the two population policies with exact interpolation/rounding from `score-arithmetic.ts`. `react-probe.ts` checks calls owned by each function for React hook/effect observations. `async-probe.ts` checks each visited node once for bounded standard-library promise patterns, including module-level operations. Neither probe traverses nested bodies or calculates metrics. `async-population.ts` assigns distinct eligible owners; `async-scoring.ts` applies the population ladder. `decomposition-evidence.ts` records function size and module distribution without deductions. `handler-resolution.ts` performs bounded declaration lookup; `handler-disposition.ts` classifies bounded failure paths; `failure-contracts.ts` resolves local logging, callback, and guarded-result contracts; `error-handling.ts` aggregates bodies, uses, context, and findings; `error-handling-scoring.ts` applies the population formula. Regression fixtures preserve raw metrics and source identities; the handler policy and ruleset change is intentional.
 
 ```sh
 npm ci
@@ -160,3 +188,21 @@ records results and limitations. Executable statements are the accepted primary
 and weights remain experimental; Code Quality continues to score method complexity
 only. The [statement calibration report](../../shared/scorecard-schema/calibration-runs/javascript-typescript-statements-2026-10-04.md)
 records the updated preview and counting contract.
+
+The [completed context calibration](../../shared/scorecard-schema/javascript-typescript-context-policy-decision.md)
+retained decomposition and error handling as unscored evidence at that stage. Across 4,062 functions,
+the large-statement candidates overlapped existing CC/MI review groups; source review
+also found explicit fallback and declared-intent counterexamples to body-only handler
+deductions. The released workflow was verified on all six selections and a compatible
+Uptime Kuma rerun. Numerical experiments remain outside the analyzer and are not
+consumer scoring policies. The subsequent [contextual handler policy](../../shared/scorecard-schema/javascript-typescript-error-handling-policy.md)
+enables the agreed population formula only where bounded classification establishes
+an assessable population. Decomposition remains unscored.
+
+## Experimental Python command in development builds
+
+Local development archives bundle `codemetrics-python` and its Python 3.12 AST adapter, version `0.15.0`. It parses source without importing the target and produces evidence v3 with a production Method Complexity score, owned statements, block nesting, duplication, optional coverage/CRAP review evidence, and unscored exception-handler observations at `dimensions.errorHandling.review`, plus bounded lexical context and conservative patterns at `dimensions.errorHandling.contextReview`, with owned raise/cause syntax at `dimensions.errorHandling.transferReview` and owned calls/returns plus unresolved-suite inventory at `dimensions.errorHandling.operationReview`, and async-owned call evidence at `dimensions.performanceAsync.review`. `--coverage-json` imports observations; `--collection-manifest` checks their source binding. Adapter 0.15.0 also scores Async/Blocking Usage from production-owner contributions at `performanceAsync.asyncScoring`, with bounded paths at `performanceAsync.helperReview`. The other seven Python dimensions remain unavailable; decomposition, duplication, coverage/CRAP, and handler observations remain unscored. Install `codemetrics-ai@0.6.0-preview.1` explicitly to use these commands; stable npm 0.5.0 does not include them. For example: `npm exec --yes --package=codemetrics-ai@0.6.0-preview.1 -- codemetrics-python --project ./pyproject.toml --scorecard-output ./python-evidence.json`. The installed package includes its Python guide at `dist/python/README.md` and scoring policy at `dist/python/ASYNC_SCORING.md`. Ordinary analysis/import needs only Node.js 20+ and Python 3.12. The separate `codemetrics-python-collect` command explicitly executes tests and requires a caller-supplied environment containing coverage.py and the project's test dependencies.
+
+Python adapter 0.13.0 also embeds unscored async call context at `dimensions.performanceAsync.contextReview`, including unresolved reason/shape inventories and bounded local callback/stored-wrapper links. The package ships `dist/python/ASYNC_CONTEXT.md`; historical 0.12.0 reports remain valid without this extension.
+
+Python adapter 0.14.0 additionally embeds unscored partial construction/reference context and narrow `sync_to_async` decorator links at `dimensions.performanceAsync.adapterReview`. The package ships `dist/python/ASYNC_ADAPTERS.md`; historical 0.13.0 evidence remains valid without this report. This adapter report itself remains unscored; 0.15.0 adds the separate async scoring contract. Error Handling remains unscored.

package/dist/analyzer.d.ts

@@ -5,6 +5,7 @@ export declare function analyze(options: {
     tsconfig?: string;
     runId?: string;
     auditId?: string;
+    dependencyMetadata?: boolean;
 }, version: string): {
     evidence: Evidence;
     metrics: Metric[];

package/dist/analyzer.js

@@ -11,6 +11,9 @@ import { asyncPopulation } from "./async-population.js";
 import { decompositionModule, decompositionEvidence } from "./decomposition-evidence.js";
 import { HandlerResolver } from "./handler-resolution.js";
 import { inspectErrorHandling, errorHandlingEvidence } from "./error-handling.js";
+import { FailureContracts } from "./failure-contracts.js";
+import { dependencyInventory } from "./dependency-inventory.js";
+import { dependencyEvidence } from "./dependency-evidence.js";
 export function analyze(options, version) {
     const identity = invocationIds(options.runId, options.auditId);
     const discovery = discover(options.project, options.tsconfig);
@@ -30,6 +33,7 @@ export function analyze(options, version) {
         const handlerSources = pkg.files.map(filename => program.getSourceFile(filename))
             .filter((source) => !!source && !program.getSyntacticDiagnostics(source).length);
         const handlerResolver = new HandlerResolver(checker, handlerSources, discovery.repositoryRoot, pkg.name);
+        const failureContracts = new FailureContracts(checker, program.getSourceFiles(), handlerSources, discovery.repositoryRoot);
         const collectModules = moduleGraph.forPackage(pkg, program);
         for (const filename of pkg.files) {
             const source = program.getSourceFile(filename);
@@ -48,7 +52,7 @@ export function analyze(options, version) {
             const file = path.relative(discovery.repositoryRoot, filename).replaceAll("\\", "/");
             asyncOwners.push(...asyncPopulation(source, checker, file, pkg.name, result.functions, result.findings.filter(item => item.dimension === "performanceAsync").map(item => item.finding)));
             decompositionModules.push(decompositionModule(source, file, pkg.name, result.functions));
-            errorHandling.push(inspectErrorHandling(source, checker, file, pkg.name, handlerResolver));
+            errorHandling.push(inspectErrorHandling(source, checker, file, pkg.name, handlerResolver, failureContracts));
             metrics.push(...result.metrics);
             collected.push(...result.findings);
             functions.push(...result.functions);
@@ -67,6 +71,8 @@ export function analyze(options, version) {
             dimensions[key] = { status: "failed", basis: "Incomplete source analysis; partial findings are unscored.", findings: dimensions[key].findings, scope: dimensions[key].scope };
     dimensions.architecture = moduleGraph.finish(diagnostics.length > 0);
     dimensions.errorHandling = errorHandlingEvidence(errorHandling, diagnostics.length > 0);
+    const dependencies = dependencyInventory(discovery.packages, discovery.repositoryRoot);
+    dimensions.dependencyManagement = dependencyEvidence(dependencies.inventory, undefined, options.dependencyMetadata ? "public-registry" : "offline");
     dimensions.codeQuality.componentDetails = { ...(dimensions.codeQuality.componentDetails ?? {}),
         decomposition: decompositionEvidence(decompositionModules, diagnostics.length > 0) };
     const evidence = {
@@ -75,11 +81,11 @@ export function analyze(options, version) {
         filters: { totalUnits: discovery.packages.reduce((sum, pkg) => sum + pkg.files.length, 0) + discovery.skipped.length,
             analyzedUnits: analyzedFiles, skipped: discovery.skipped },
         population: { types: new Set(metrics.map(metric => `${metric.project}|${metric.file}|${metric.type}`)).size, members: metrics.length },
-        dimensions, analysis: { ...identity, status: diagnostics.length ? "incomplete" : "complete", ruleset: "javascript-typescript-2026-10-04-local-handlers",
-            calibration: "uncalibrated", configurationFingerprint: hash(JSON.stringify(canonicalConfiguration(discovery.packages.map(pkg => ({ name: pkg.name,
-                options: pkg.options, selection: pkg.selection })), discovery.repositoryRoot))), diagnostics, suppressions: [] }
+        dimensions, analysis: { ...identity, status: diagnostics.length ? "incomplete" : "complete", ruleset: "javascript-typescript-2026-10-09-dependency-evidence",
+            calibration: "uncalibrated", configurationFingerprint: hash(JSON.stringify(canonicalConfiguration({ packages: discovery.packages.map(pkg => ({ name: pkg.name,
+                    options: pkg.options, selection: pkg.selection })), dependencyMetadata: options.dependencyMetadata ? "public-registry" : "offline" }, discovery.repositoryRoot))), diagnostics, suppressions: [] }
     };
-    return { evidence, metrics, csv: toCsv(metrics), inputs: discovery.packages.flatMap(pkg => [pkg.entryPoint, ...pkg.files]) };
+    return { evidence, metrics, csv: toCsv(metrics), inputs: [...dependencies.inputs, ...discovery.packages.flatMap(pkg => [pkg.entryPoint, ...pkg.files])] };
 }
 function canonicalConfiguration(value, root) {
     if (typeof value === "string")

package/dist/cli.js

@@ -5,18 +5,20 @@ import { analyze } from "./analyzer.js";
 import { defaultEvidencePath, defaultMetricsPath } from "./scorecard-contract.js";
 import { compare, gate, readEvidence, sarif, validateEvidence } from "./evidence-tools.js";
 import { distinctOutputs, write } from "./io.js";
+import { enrichDependencies } from "./dependency-evidence.js";
 try {
     const { values } = parseArgs({ options: {
             project: { type: "string" }, tsconfig: { type: "string" }, "run-id": { type: "string" }, "audit-id": { type: "string" }, output: { type: "string", default: defaultMetricsPath },
             "scorecard-output": { type: "string", default: defaultEvidencePath }, baseline: { type: "string" },
             "comparison-output": { type: "string" }, sarif: { type: "string" }, "fail-on-new": { type: "string" },
-            "max-score-drop": { type: "string" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" }
+            "max-score-drop": { type: "string" }, "dependency-metadata": { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" }
         } });
     const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
     if (values.help)
         console.log([
             "codemetrics-ai — JavaScript, TypeScript and React source analysis",
             "--project <package.json> --tsconfig <tsconfig.json>",
+            "--dependency-metadata (opt in to bounded public npm registry observations; inventory is always local)",
             "--run-id <uuid> --audit-id <uuid> (generated when omitted)",
             "--output <metrics.csv> --scorecard-output <evidence.json>",
             "--baseline <evidence.json> --comparison-output <comparison.json>",
@@ -30,9 +32,11 @@ try {
         if ((values["fail-on-new"] || values["max-score-drop"] || values["comparison-output"]) && !values.baseline)
             throw new Error("Comparison and quality gates require --baseline.");
         distinctOutputs([values.project ?? "package.json", values.tsconfig, values.baseline], [values.output, values["scorecard-output"], values["comparison-output"], values.sarif]);
-        const result = analyze({ ...values, runId: values["run-id"], auditId: values["audit-id"] }, version);
-        validateEvidence(result.evidence);
+        const result = analyze({ ...values, runId: values["run-id"], auditId: values["audit-id"], dependencyMetadata: values["dependency-metadata"] }, version);
         distinctOutputs(result.inputs, [values.output, values["scorecard-output"], values["comparison-output"], values.sarif]);
+        if (values["dependency-metadata"])
+            await enrichDependencies(result.evidence);
+        validateEvidence(result.evidence);
         const comparison = values.baseline ? compare(result.evidence, readEvidence(values.baseline)) : undefined;
         const failed = comparison ? gate(comparison, values["fail-on-new"], values["max-score-drop"] === undefined ? undefined : Number(values["max-score-drop"])) : false;
         write(values.output, result.csv);

package/dist/dependency-evidence.d.ts

@@ -0,0 +1,5 @@
+import { type Dimension, type Evidence } from "./evidence.js";
+import type { DependencyInventory } from "./dependency-inventory.js";
+import { type DependencyMetadata, type RegistryReader } from "./dependency-metadata.js";
+export declare function dependencyEvidence(inventory: DependencyInventory, metadata?: DependencyMetadata, metadataMode?: "offline" | "public-registry"): Dimension;
+export declare function enrichDependencies(evidence: Evidence, reader?: RegistryReader): Promise<void>;

package/dist/dependency-evidence.js

@@ -0,0 +1,30 @@
+import { hash } from "./evidence.js";
+import { dependencyMetadata, noMetadata } from "./dependency-metadata.js";
+export function dependencyEvidence(inventory, metadata = noMetadata(), metadataMode = metadata.status === "notRequested" ? "offline" : "public-registry") {
+    const findings = [];
+    const add = (id, name, category, message, observations) => findings.push({
+        category, ruleId: `javascript-typescript/dependencyManagement/${category}`, fingerprint: hash(`${id}|${category}`),
+        severity: "info", confidence: "high", package: name, message, observations: { ...observations, scoreDisposition: "excludedUnscored" }
+    });
+    for (const row of metadata.observations) {
+        if (row.deprecated)
+            add(row.packageId, row.name, "deprecatedPackage", `${row.name} ${row.version} is deprecated: ${row.deprecated}`, { packageId: row.packageId, version: row.version });
+        if (row.upgrades?.some(upgrade => upgrade.newerWithinRange))
+            add(row.packageId, row.name, "updateWithinDeclaredRange", `${row.name} has an update within a declared version range; compatibility and intent require review.`, { packageId: row.packageId, upgrades: row.upgrades });
+        for (const advisory of row.vulnerabilities.advisories ?? [])
+            add(`${row.packageId}|${advisory.id}`, row.name, "reportedVulnerability", `${row.name} ${row.version}: ${advisory.title}`, { packageId: row.packageId, advisory, reachability: "notAssessed" });
+    }
+    return { status: "skipped", basis: "Dependency inventory and registry observations only; numerical scoring is not calibrated. Missing evidence is not a code defect.",
+        scope: { id: "javascript-typescript/dependencyManagement/lock-observations-v1", coverage: "partial",
+            includes: ["npm-lockfile-v2-v3", "pnpm-lockfile-v9", "selected-workspace-reachability", "public-registry-metadata-if-requested"],
+            excludes: ["dependency-scoring", "runtime-reachability", "upgrade-safety", "private-registry-authentication", "yarn-bun-lockfiles", "pnpm-file-git-custom-resolutions", "pnpm-environment-tooling-document", "implicit-registry-provenance"] },
+        findings, dependencyInventory: inventory, dependencyMetadata: metadata, metadataMode };
+}
+export async function enrichDependencies(evidence, reader) {
+    if (evidence.dimensions.dependencyManagement.metadataMode !== "public-registry")
+        throw new Error("Analyze with dependencyMetadata: true before requesting registry observations");
+    const inventory = evidence.dimensions.dependencyManagement.dependencyInventory;
+    if (!inventory)
+        throw new Error("Dependency inventory is required before metadata acquisition");
+    evidence.dimensions.dependencyManagement = dependencyEvidence(inventory, await dependencyMetadata(inventory, reader));
+}

package/dist/dependency-inventory.d.ts

@@ -0,0 +1,67 @@
+import type { PackageInput } from "./discovery.js";
+import { declarations, type DependencyKind } from "./dependency-spec.js";
+export { declarations, registrySpec, type DependencyKind } from "./dependency-spec.js";
+export interface DependencyUse {
+    project: string;
+    manifest: string;
+    from: string;
+    requested: string;
+    range: string;
+    resolvedRange?: string;
+    kind: DependencyKind;
+    direct: boolean;
+    optional: boolean;
+}
+export interface DependencyPackage {
+    id: string;
+    name: string;
+    version: string;
+    source: "publicRegistry" | "otherSource" | "workspace";
+    locations: string[];
+    uses: DependencyUse[];
+}
+export interface DependencyGap {
+    manifest: string;
+    reason: string;
+    dependency?: string;
+    from?: string;
+    range?: string;
+}
+export interface DependencyInventory {
+    version: 1;
+    status: "complete" | "gaps";
+    countingUnit: "packageNameVersionSource";
+    packages: DependencyPackage[];
+    gaps: DependencyGap[];
+    notices: {
+        manifest: string;
+        from: string;
+        dependency: string;
+        reason: string;
+        range: string;
+        version?: string;
+    }[];
+    manifests: {
+        file: string;
+        lockfile?: string;
+        manager?: string;
+        declarations: ReturnType<typeof declarations>;
+        overrides?: unknown;
+    }[];
+    lockfiles: {
+        file: string;
+        version: number;
+        sha256: string;
+        projectDocument?: number;
+        environmentDocument?: "excluded";
+    }[];
+    configurationInputs?: {
+        file: string;
+        sha256: string;
+    }[];
+}
+/** Reads only selected manifests and reachable lockfile entries; never installs or executes packages. */
+export declare function dependencyInventory(selected: Pick<PackageInput, "entryPoint" | "root" | "name">[], root: string): {
+    inventory: DependencyInventory;
+    inputs: string[];
+};

package/dist/dependency-inventory.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import { hash } from "./evidence.js";
+import { pnpmInventory } from "./dependency-pnpm.js";
+import { declarations, registrySpec } from "./dependency-spec.js";
+export { declarations, registrySpec } from "./dependency-spec.js";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const slash = (value) => value.replaceAll("\\", "/");
+const within = (root, file) => { const r = path.relative(root, file); return !path.isAbsolute(r) && r !== ".." && !r.startsWith(".." + path.sep); };
+function read(file) {
+    if (fs.statSync(file).size > 20 * 1024 * 1024)
+        throw new Error("Dependency input exceeds 20 MiB");
+    const text = fs.readFileSync(file, "utf8"), data = JSON.parse(text);
+    if (!object(data))
+        throw new Error("Dependency input must be an object");
+    return { data, sha256: hash(text) };
+}
+function locate(start, root, inputs) {
+    const directories = [];
+    for (let dir = start; within(root, dir); dir = path.dirname(dir)) {
+        directories.push(dir);
+        if (dir === root)
+            break;
+    }
+    let manager;
+    for (const dir of directories) {
+        const manifest = path.join(dir, "package.json");
+        if (fs.existsSync(manifest))
+            inputs.add(manifest);
+        const declared = fs.existsSync(manifest) ? read(manifest).data.packageManager : undefined;
+        if (!manager && typeof declared === "string")
+            manager = declared;
+    }
+    if (manager && !/^(npm|pnpm)@/.test(manager))
+        return { manager };
+    for (const dir of directories) {
+        const candidates = manager?.startsWith("pnpm@") ? ["pnpm-lock.yaml"] : manager?.startsWith("npm@") ? ["npm-shrinkwrap.json", "package-lock.json"] : ["pnpm-lock.yaml", "npm-shrinkwrap.json", "package-lock.json"];
+        if (!manager && fs.existsSync(path.join(dir, "pnpm-lock.yaml")) && ["npm-shrinkwrap.json", "package-lock.json", "yarn.lock", "bun.lock"].some(name => fs.existsSync(path.join(dir, name))))
+            return { manager: "ambiguous lockfiles without packageManager" };
+        for (const name of candidates) {
+            const file = path.join(dir, name);
+            if (fs.existsSync(file))
+                return { file, manager: name === "pnpm-lock.yaml" ? "pnpm" : "npm" };
+        }
+        const unsupported = ["yarn.lock", "bun.lock", "bun.lockb"].find(name => fs.existsSync(path.join(dir, name)));
+        if (unsupported) {
+            inputs.add(path.join(dir, unsupported));
+            return { manager: unsupported };
+        }
+    }
+    return { manager };
+}
+function validLocation(location) {
+    return !location.includes("\\") && !path.posix.isAbsolute(location) && !location.split("/").includes("..") && !location.includes(":");
+}
+function resolve(packages, from, name) {
+    if (!/^(?:@[^/]+\/)?[^/]+$/.test(name) || name.includes("\\") || name.includes(".."))
+        return;
+    for (let dir = from;; dir = path.posix.dirname(dir)) {
+        const at = path.posix.join(dir, "node_modules", name);
+        if (object(packages[at]))
+            return at;
+        if (!dir || dir === ".")
+            return;
+    }
+}
+function packageSource(entry) {
+    if (typeof entry.resolved !== "string")
+        return "otherSource";
+    try {
+        const url = new URL(entry.resolved);
+        return url.protocol === "https:" && url.hostname === "registry.npmjs.org" && !url.username && !url.password ? "publicRegistry" : "otherSource";
+    }
+    catch {
+        return "otherSource";
+    }
+}
+/** Reads only selected manifests and reachable lockfile entries; never installs or executes packages. */
+export function dependencyInventory(selected, root) {
+    const inventory = { version: 1, status: "complete", countingUnit: "packageNameVersionSource", packages: [], gaps: [], notices: [], manifests: [], lockfiles: [] };
+    const inputs = new Set(selected.map(pkg => pkg.entryPoint)), rows = new Map();
+    const locks = new Map();
+    const relative = (file) => slash(path.relative(root, file));
+    for (const pkg of selected) {
+        const manifest = relative(pkg.entryPoint);
+        const gap = (reason, dependency, from, range) => inventory.gaps.push({ manifest, reason, ...(dependency ? { dependency } : {}), ...(from !== undefined ? { from } : {}), ...(range ? { range } : {}) });
+        try {
+            const data = read(pkg.entryPoint).data, declared = declarations(data), located = locate(pkg.root, root, inputs);
+            inventory.manifests.push({ file: manifest, declarations: declared, ...(data.overrides ? { overrides: data.overrides } : {}), ...(located.file ? { lockfile: relative(located.file) } : {}), ...(located.manager ? { manager: located.manager } : {}) });
+            if (!located.file) {
+                gap(located.manager && !/^(npm|pnpm)@/.test(located.manager) ? `Unsupported package manager/lockfile: ${located.manager}` : `No ${located.manager?.split("@")[0] ?? "npm or pnpm"} lockfile found`);
+                continue;
+            }
+            inputs.add(located.file);
+            if (!within(root, fs.realpathSync(located.file))) {
+                gap("Lockfile is outside repository");
+                continue;
+            }
+            if (located.manager === "pnpm") {
+                pnpmInventory(pkg, root, located.file, inventory, inputs, rows);
+                continue;
+            }
+            if (!locks.has(located.file))
+                locks.set(located.file, read(located.file));
+            const lock = locks.get(located.file), packages = lock.data.packages;
+            if (![2, 3].includes(Number(lock.data.lockfileVersion)) || !object(packages)) {
+                gap("Only npm lockfile versions 2 and 3 with a packages map are supported");
+                continue;
+            }
+            if (!inventory.lockfiles.some(row => row.file === relative(located.file)))
+                inventory.lockfiles.push({ file: relative(located.file), version: Number(lock.data.lockfileVersion), sha256: lock.sha256 });
+            if (Object.keys(packages).some(location => !validLocation(location))) {
+                gap("Unsafe or malformed lockfile location");
+                continue;
+            }
+            const start = slash(path.relative(path.dirname(located.file), pkg.root)), locked = packages[start];
+            if (!object(locked)) {
+                gap("Selected manifest has no lockfile package entry");
+                continue;
+            }
+            if (JSON.stringify(declared) !== JSON.stringify(declarations(locked))) {
+                gap("Manifest and lockfile declarations differ; resolved inventory is withheld");
+                continue;
+            }
+            const visited = new Set();
+            const queue = declared.map(edge => ({ from: start, ...edge, mayBeAbsent: edge.optional, role: edge.kind, direct: true }));
+            for (let index = 0; index < queue.length; index++) {
+                if (index >= 100000) {
+                    gap("Dependency traversal limit exceeded");
+                    break;
+                }
+                const edge = queue[index], position = resolve(packages, edge.from, edge.requested);
+                if (!position) {
+                    if (edge.mayBeAbsent)
+                        inventory.notices.push({ manifest, from: edge.from, dependency: edge.requested, range: edge.range, reason: "Optional dependency/peer is absent from the lockfile; no missing-package deduction" });
+                    else
+                        gap(`Unresolved ${edge.kind} dependency in lockfile`, edge.requested, edge.from, edge.range);
+                    continue;
+                }
+                let location = position, entry = packages[location];
+                const linked = entry.link === true;
+                if (linked) {
+                    if (typeof entry.resolved !== "string" || !validLocation(entry.resolved) || !object(packages[entry.resolved])) {
+                        gap("Unresolved workspace/link target", edge.requested);
+                        continue;
+                    }
+                    location = entry.resolved;
+                    entry = packages[location];
+                    const target = path.resolve(path.dirname(located.file), location, "package.json");
+                    if (!within(root, target) || !fs.existsSync(target) || !within(root, fs.realpathSync(target))) {
+                        gap("Workspace manifest unavailable or outside repository", edge.requested);
+                        continue;
+                    }
+                    inputs.add(target);
+                    if (JSON.stringify(declarations(read(target).data)) !== JSON.stringify(declarations(entry))) {
+                        gap("Workspace manifest and lockfile differ", edge.requested);
+                        continue;
+                    }
+                }
+                const spec = registrySpec(edge.requested, edge.range);
+                const name = typeof entry.name === "string" ? entry.name : spec?.name ?? edge.requested;
+                if (typeof entry.version !== "string" || !semver.valid(entry.version)) {
+                    gap("Missing/non-semver resolved version", edge.requested);
+                    continue;
+                }
+                if (spec && semver.validRange(spec.range) && !semver.satisfies(entry.version, spec.range))
+                    inventory.notices.push({ manifest, from: edge.from, dependency: edge.requested, range: edge.range, version: entry.version,
+                        reason: "Locked version differs from requested range; overrides or peer-resolution policy may explain this. Installation validity is not assessed" });
+                if (spec && spec.name !== name)
+                    inventory.notices.push({ manifest, from: edge.from, dependency: edge.requested, range: edge.range, version: entry.version,
+                        reason: `Locked identity is ${name}; an alias/override may replace the requested package. Installation policy is not assessed` });
+                const source = linked ? "workspace" : packageSource(entry), id = hash(`${name}|${entry.version}|${source}`);
+                const row = rows.get(id) ?? { id, name, version: entry.version, source, locations: [], uses: [] };
+                rows.set(id, row);
+                const install = `${relative(located.file)}#${position}`;
+                if (!row.locations.includes(install))
+                    row.locations.push(install);
+                const use = { project: pkg.name, manifest, from: edge.from, requested: edge.requested, range: edge.range, kind: edge.role, direct: edge.direct, optional: edge.optional };
+                if (!row.uses.some(existing => JSON.stringify(existing) === JSON.stringify(use)))
+                    row.uses.push(use);
+                const key = `${location}|${edge.role}|${edge.optional}`;
+                if (visited.has(key))
+                    continue;
+                visited.add(key);
+                for (const child of declarations(entry, false))
+                    queue.push({ from: location, ...child, mayBeAbsent: child.optional, optional: edge.optional || child.optional, role: edge.role, direct: false });
+            }
+        }
+        catch (error) {
+            gap(error instanceof Error ? error.message : "Dependency inventory unavailable");
+        }
+    }
+    inventory.packages = [...rows.values()].sort((a, b) => a.name.localeCompare(b.name, "en") || a.version.localeCompare(b.version, "en") || a.source.localeCompare(b.source, "en"));
+    for (const row of inventory.packages) {
+        row.locations.sort();
+        row.uses.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b), "en"));
+    }
+    inventory.gaps = [...new Map(inventory.gaps.map(gap => [JSON.stringify(gap), gap])).values()];
+    inventory.notices = [...new Map(inventory.notices.map(notice => [JSON.stringify(notice), notice])).values()];
+    inventory.status = inventory.gaps.length ? "gaps" : "complete";
+    return { inventory, inputs: [...inputs] };
+}

package/dist/dependency-metadata.d.ts

@@ -0,0 +1,65 @@
+import { type DependencyInventory } from "./dependency-inventory.js";
+export interface MetadataResult {
+    status: "available" | "unavailable";
+    data?: unknown;
+    sha256?: string;
+    reason?: string;
+}
+export interface RegistryReader {
+    package(name: string): Promise<MetadataResult>;
+    advisories(packages: Record<string, string[]>): Promise<MetadataResult>;
+}
+export interface PackageObservation {
+    packageId: string;
+    name: string;
+    version: string;
+    metadata: {
+        status: "available" | "unavailable";
+        reason?: string;
+        sha256?: string;
+    };
+    deprecated?: string | null;
+    latest?: string | null;
+    upgrades?: {
+        manifest: string;
+        range: string;
+        wanted: string | null;
+        newerWithinRange: boolean;
+        latestOutsideRange: boolean | null;
+        reason?: string;
+    }[];
+    nodeEngine?: string | null;
+    vulnerabilities: {
+        status: "available" | "unavailable";
+        reason?: string;
+        advisories?: {
+            id: string;
+            title: string;
+            url: string;
+            severity: string;
+            range: string;
+        }[];
+    };
+}
+export interface DependencyMetadata {
+    version: 1;
+    status: "notRequested" | "available" | "partial" | "unavailable";
+    source: "https://registry.npmjs.org";
+    checkedAtUtc?: string;
+    scope: "public-registry-lockfile-packages";
+    observations: PackageObservation[];
+    availablePackages: number;
+    unavailablePackages: number;
+    advisoryResponseSha256?: string;
+}
+export declare const noMetadata: () => DependencyMetadata;
+/** Explicit opt-in, bounded public-registry reads. No credentials, redirects, installs or target scripts. */
+export declare function publicRegistryReader(options?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+    fetch?: typeof fetch;
+}): RegistryReader;
+export declare function dependencyMetadata(inventory: DependencyInventory, reader?: RegistryReader, options?: {
+    maxPackages?: number;
+    deadlineMs?: number;
+}): Promise<DependencyMetadata>;