codemetrics-ai 0.5.0 → 0.6.0-preview.1

package/README.md

@@ -1,6 +1,6 @@
 # codemetrics-ai
 
-Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.5.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).
 
@@ -20,6 +20,10 @@ 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. |
@@ -27,6 +31,7 @@ Default output paths are `.scorecard/javascript-typescript/metrics.csv` and `.sc
 | 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 | 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.
@@ -64,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.
@@ -176,3 +198,11 @@ 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

@@ -12,6 +12,8 @@ import { decompositionModule, decompositionEvidence } from "./decomposition-evid
 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);
@@ -69,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 = {
@@ -77,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-09-handler-contracts",
-            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>;