codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/dependency-metadata.js

@@ -0,0 +1,125 @@
+import semver from "semver";
+import { hash } from "./evidence.js";
+import { registrySpec } from "./dependency-inventory.js";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+export const noMetadata = () => ({ version: 1, status: "notRequested", source: "https://registry.npmjs.org", scope: "public-registry-lockfile-packages", observations: [], availablePackages: 0, unavailablePackages: 0 });
+const unavailable = (reason) => ({ status: "unavailable", reason });
+/** Explicit opt-in, bounded public-registry reads. No credentials, redirects, installs or target scripts. */
+export function publicRegistryReader(options = {}) {
+    const request = async (route, body) => {
+        try {
+            const response = await (options.fetch ?? fetch)(`https://registry.npmjs.org/${route}`, {
+                method: body ? "POST" : "GET", redirect: "error", signal: AbortSignal.timeout(options.timeoutMs ?? 10000),
+                headers: { accept: body ? "application/json" : "application/vnd.npm.install-v1+json", ...(body ? { "content-type": "application/json" } : {}) },
+                ...(body ? { body: JSON.stringify(body) } : {})
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                return unavailable(`Registry HTTP ${response.status}`);
+            }
+            const limit = options.maxBytes ?? 5 * 1024 * 1024;
+            if (Number(response.headers.get("content-length")) > limit) {
+                await response.body?.cancel();
+                return unavailable("Registry response exceeds size limit");
+            }
+            if (!response.body)
+                return unavailable("Empty registry response");
+            const reader = response.body.getReader(), chunks = [];
+            let size = 0;
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > limit) {
+                    await reader.cancel();
+                    return unavailable("Registry response exceeds size limit");
+                }
+                chunks.push(value);
+            }
+            const text = Buffer.concat(chunks).toString("utf8"), data = JSON.parse(text);
+            return { status: "available", data, sha256: hash(text) };
+        }
+        catch {
+            return unavailable("Registry request failed, timed out, or returned invalid JSON");
+        }
+    };
+    return { package: name => request(encodeURIComponent(name)), advisories: packages => request("-/npm/v1/security/advisories/bulk", packages) };
+}
+function packageDetails(pkg, result) {
+    const data = result.data;
+    if (result.status !== "available" || !object(data) || data.name !== pkg.name || !object(data.versions) || !object(data.versions[pkg.version]))
+        return { metadata: { status: "unavailable", reason: result.reason ?? "Installed package/version metadata is missing or malformed" } };
+    const installed = data.versions[pkg.version];
+    if (installed.version !== pkg.version || (installed.deprecated !== undefined && typeof installed.deprecated !== "string") ||
+        installed.engines !== undefined && (!object(installed.engines) || installed.engines.node !== undefined && typeof installed.engines.node !== "string"))
+        return { metadata: { status: "unavailable", reason: "Installed-version metadata is malformed" } };
+    const latest = object(data["dist-tags"]) && typeof data["dist-tags"].latest === "string" && semver.valid(data["dist-tags"].latest) && object(data.versions[data["dist-tags"].latest]) ? data["dist-tags"].latest : null;
+    const versions = Object.keys(data.versions).filter(version => semver.valid(version));
+    const upgrades = pkg.uses.filter(use => use.direct).map(use => {
+        const spec = registrySpec(use.requested, use.resolvedRange ?? use.range), range = spec?.name === pkg.name ? spec.range : undefined;
+        const wanted = range && semver.validRange(range) ? semver.maxSatisfying(versions, range) : null;
+        return { manifest: use.manifest, range: use.range, wanted, newerWithinRange: !!wanted && semver.gt(wanted, pkg.version),
+            latestOutsideRange: latest && range && semver.validRange(range) ? !semver.satisfies(latest, range) : null,
+            ...(!range ? { reason: "Original range is unsupported or names a different package replaced by an alias/override" } : {}) };
+    });
+    return { metadata: { status: "available", sha256: result.sha256 }, deprecated: typeof installed.deprecated === "string" ? installed.deprecated : null, latest, upgrades,
+        nodeEngine: object(installed.engines) && typeof installed.engines.node === "string" ? installed.engines.node : null };
+}
+function advisoryDetails(pkg, result) {
+    if (result.status !== "available" || !object(result.data) || "error" in result.data)
+        return { status: "unavailable", reason: result.reason ?? "Malformed advisory response" };
+    const entries = Object.hasOwn(result.data, pkg.name) ? result.data[pkg.name] : [];
+    if (!Array.isArray(entries))
+        return { status: "unavailable", reason: "Malformed package advisory list" };
+    const advisories = new Map();
+    for (const row of entries) {
+        if (!object(row) || row.name !== pkg.name || !["string", "number"].includes(typeof row.id) || typeof row.title !== "string" ||
+            typeof row.url !== "string" || typeof row.vulnerable_versions !== "string" || !semver.validRange(row.vulnerable_versions) ||
+            typeof row.severity !== "string" || !["low", "moderate", "high", "critical", "info"].includes(row.severity))
+            return { status: "unavailable", reason: "Malformed advisory fields" };
+        if (!/^https:\/\//.test(row.url))
+            return { status: "unavailable", reason: "Invalid advisory URL" };
+        if (semver.satisfies(pkg.version, row.vulnerable_versions, { includePrerelease: true })) {
+            const id = String(row.id);
+            advisories.set(id, { id, title: row.title, url: row.url, severity: row.severity, range: row.vulnerable_versions });
+        }
+    }
+    return { status: "available", advisories: [...advisories.values()].sort((a, b) => a.id.localeCompare(b.id, "en")) };
+}
+export async function dependencyMetadata(inventory, reader = publicRegistryReader(), options = {}) {
+    const maximum = options.maxPackages ?? 100, deadline = Date.now() + (options.deadlineMs ?? 60000);
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 1000)
+        throw new Error("Metadata package limit must be an integer from 1 to 1000");
+    const direct = new Set(inventory.packages.filter(pkg => pkg.uses.some(use => use.direct)).map(pkg => pkg.name));
+    const names = [...new Set(inventory.packages.filter(pkg => pkg.source === "publicRegistry").map(pkg => pkg.name))]
+        .sort((a, b) => Number(direct.has(b)) - Number(direct.has(a)) || a.localeCompare(b, "en")).slice(0, maximum);
+    const payload = Object.create(null);
+    for (const name of names)
+        payload[name] = [...new Set(inventory.packages.filter(pkg => pkg.source === "publicRegistry" && pkg.name === name).map(pkg => pkg.version))];
+    const results = new Map();
+    let cursor = 0;
+    const safe = async (work) => { try {
+        return await work();
+    }
+    catch {
+        return unavailable("Registry reader failed");
+    } };
+    await Promise.all(Array.from({ length: Math.min(4, names.length) }, async () => {
+        while (cursor < names.length) {
+            const name = names[cursor++];
+            results.set(name, Date.now() >= deadline ? unavailable("Metadata time budget exhausted") : await safe(() => reader.package(name)));
+        }
+    }));
+    const audit = names.length && Date.now() < deadline ? await safe(() => reader.advisories(payload)) : unavailable("No eligible packages or metadata time budget exhausted");
+    const observations = inventory.packages.map(pkg => {
+        const eligible = pkg.source === "publicRegistry";
+        const metadata = eligible ? (results.get(pkg.name) ?? unavailable("Metadata package limit exceeded")) : unavailable("Workspace, private/other source, or registry provenance unavailable");
+        return { packageId: pkg.id, name: pkg.name, version: pkg.version, ...packageDetails(pkg, metadata),
+            vulnerabilities: eligible && Object.hasOwn(payload, pkg.name) ? advisoryDetails(pkg, audit) : { status: "unavailable", reason: metadata.reason } };
+    });
+    const available = observations.filter(row => row.metadata.status === "available" && row.vulnerabilities.status === "available").length;
+    const anyAvailable = observations.some(row => row.metadata.status === "available" || row.vulnerabilities.status === "available");
+    return { version: 1, status: observations.length && available === observations.length ? "available" : anyAvailable ? "partial" : "unavailable", source: "https://registry.npmjs.org", scope: "public-registry-lockfile-packages",
+        checkedAtUtc: new Date().toISOString(), observations, availablePackages: available, unavailablePackages: observations.length - available, ...(audit.sha256 ? { advisoryResponseSha256: audit.sha256 } : {}) };
+}

package/dist/dependency-pnpm.d.ts

@@ -0,0 +1,4 @@
+import type { PackageInput } from "./discovery.js";
+import type { DependencyInventory, DependencyPackage } from "./dependency-inventory.js";
+/** pnpm v9 adapter, including pnpm 12 environment + project YAML documents. No target code executes. */
+export declare function pnpmInventory(pkg: Pick<PackageInput, "entryPoint" | "root" | "name">, root: string, file: string, inventory: DependencyInventory, inputs: Set<string>, rows: Map<string, DependencyPackage>): void;

package/dist/dependency-pnpm.js

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import { parseAllDocuments } from "yaml";
+import { hash } from "./evidence.js";
+import { declarations, registrySpec } from "./dependency-spec.js";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const own = (value, key) => object(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+const slash = (value) => value.replaceAll("\\", "/");
+const within = (root, file) => { const r = path.relative(root, file); return !path.isAbsolute(r) && r !== ".." && !r.startsWith(".." + path.sep); };
+const fields = { production: "dependencies", development: "devDependencies", optional: "optionalDependencies" };
+function input(file, root, inputs) {
+    inputs.add(file);
+    if (!within(root, fs.realpathSync(file)))
+        throw new Error("pnpm input is outside repository");
+    if (fs.statSync(file).size > 20 * 1024 * 1024)
+        throw new Error("pnpm input exceeds 20 MiB");
+    return fs.readFileSync(file, "utf8");
+}
+function yamlDocuments(text) {
+    try {
+        const docs = parseAllDocuments(text, { uniqueKeys: true, strict: true });
+        if (!docs.length || docs.length > 2 || docs.some(doc => doc.errors.length || doc.warnings.length))
+            throw new Error();
+        const values = docs.map(doc => doc.toJS({ maxAliasCount: 0 }));
+        if (!values.every(object))
+            throw new Error();
+        return values;
+    }
+    catch {
+        throw new Error("Malformed or unsupported pnpm YAML (duplicate keys, tags, aliases, or document layout)");
+    }
+}
+function projectLock(text) {
+    const docs = yamlDocuments(text);
+    if (docs.some(doc => doc.lockfileVersion !== "9.0" && doc.lockfileVersion !== 9))
+        throw new Error("Only pnpm lockfile version 9 is supported");
+    if (docs.length === 2) {
+        const env = docs[0], importers = env.importers;
+        if (!object(importers) || Object.keys(importers).length !== 1 || !object(importers["."]))
+            throw new Error("Unsupported pnpm environment lock document");
+        const importer = importers["."];
+        if (!("configDependencies" in importer || "packageManagerDependencies" in importer) || Object.values(fields).some(field => importer[field] !== undefined))
+            throw new Error("Ambiguous pnpm project lock documents");
+    }
+    const lock = docs.at(-1);
+    if (!object(lock.importers))
+        throw new Error("pnpm project lockfile has no importers map");
+    if (Object.values(lock.importers).some(importer => object(importer) && ("configDependencies" in importer || "packageManagerDependencies" in importer)))
+        throw new Error("pnpm environment document has no following project document");
+    if (lock.packages !== undefined && !object(lock.packages) || lock.snapshots !== undefined && !object(lock.snapshots))
+        throw new Error("Malformed pnpm package or snapshot map");
+    if (Object.keys(lock.importers).some(key => key !== "." && (!key || key.includes("\\") || key.includes(":") || path.posix.isAbsolute(key) || key.split("/").includes(".."))))
+        throw new Error("Unsafe pnpm importer location");
+    return { lock, document: docs.length };
+}
+function catalogRange(declaration, config, lock) {
+    if (!declaration.range.startsWith("catalog:"))
+        return;
+    const catalog = declaration.range.slice(8) || "default";
+    const configured = catalog === "default" ? config.catalog : own(config.catalogs, catalog);
+    const range = own(configured, declaration.requested), record = own(own(lock.catalogs, catalog), declaration.requested);
+    const overridden = record === undefined && typeof range === "string" && own(lock.overrides, declaration.requested) === range && [range, declaration.range].includes(own(config.overrides, declaration.requested));
+    if (typeof range !== "string" || !overridden && (!object(record) || record.specifier !== range))
+        throw new Error(`Catalog unavailable or stale for ${declaration.requested}`);
+    return range;
+}
+function importerRecord(importer, edge) {
+    const candidates = edge.kind === "peer" ? Object.values(fields).map(field => own(importer[field], edge.requested)) : [own(importer[fields[edge.kind]], edge.requested)];
+    return candidates.find(object);
+}
+function overrideRange(name, config, rootManifest, lock) {
+    const current = own(config.overrides, name) ?? own(own(rootManifest.pnpm, "overrides"), name);
+    if (typeof current !== "string")
+        return;
+    const resolved = catalogRange({ requested: name, range: current, kind: "production", optional: false }, config, lock) ?? current;
+    return own(lock.overrides, name) === resolved ? resolved : undefined;
+}
+function importerEdges(location, manifest, lock, config, rootManifest, includeDevelopment) {
+    const importer = own(lock.importers, location);
+    if (!object(importer))
+        throw new Error(`Selected/workspace manifest has no pnpm importer: ${location}`);
+    const all = declarations(manifest);
+    for (const [kind, field] of Object.entries(fields)) {
+        if (importer[field] !== undefined && !object(importer[field]))
+            throw new Error("Malformed pnpm importer dependencies");
+        for (const [name, record] of Object.entries(object(importer[field]) ? importer[field] : {})) {
+            if (!object(record) || typeof record.specifier !== "string" || typeof record.version !== "string")
+                throw new Error("Malformed pnpm importer resolution");
+            if (!all.some(edge => edge.requested === name && (edge.kind === kind || edge.kind === "peer")))
+                throw new Error(`Manifest and pnpm importer declarations differ: ${location}`);
+        }
+    }
+    const edges = [];
+    for (const edge of all) {
+        const record = importerRecord(importer, edge), resolvedRange = catalogRange(edge, config, lock);
+        if (edge.kind !== "peer" && (!record || record.specifier !== edge.range && record.specifier !== overrideRange(edge.requested, config, rootManifest, lock)))
+            throw new Error(`Manifest and pnpm importer declarations differ: ${location}`);
+        if (!includeDevelopment && edge.kind === "development")
+            continue;
+        edges.push({ ...edge, from: location, ref: typeof record?.version === "string" ? record.version : undefined, ...(resolvedRange ? { resolvedRange } : {}), role: edge.kind, direct: true, mayBeAbsent: edge.optional, importer: true });
+    }
+    return edges;
+}
+function identity(requested, ref) {
+    // Snapshot suffixes encode peer contexts (and patches); preserve the complete key as a location.
+    const key = semver.valid(ref.split("(")[0]) ? `${requested}@${ref}` : ref;
+    const base = key.split("(")[0], match = /^((?:@[^/\s]+\/)?[^@/:\s]+)@([^()]+)$/.exec(base);
+    if (!match || !semver.valid(match[2]) || key.includes("\\") || key.includes("://"))
+        return;
+    return { key, base, name: match[1], version: match[2] };
+}
+function sourceOf(record) {
+    const tarball = own(record.resolution, "tarball");
+    if (typeof tarball !== "string")
+        return "otherSource";
+    try {
+        const url = new URL(tarball);
+        return url.protocol === "https:" && url.hostname === "registry.npmjs.org" && !url.username && !url.password ? "publicRegistry" : "otherSource";
+    }
+    catch {
+        return "otherSource";
+    }
+}
+function children(from, snapshot, record, parent) {
+    const peers = declarations({ peerDependencies: record.peerDependencies, peerDependenciesMeta: record.peerDependenciesMeta });
+    const rows = [];
+    for (const field of ["dependencies", "optionalDependencies"]) {
+        const dependencies = snapshot[field];
+        if (dependencies === undefined)
+            continue;
+        if (!object(dependencies))
+            throw new Error("Malformed pnpm snapshot dependencies");
+        for (const [requested, ref] of Object.entries(dependencies)) {
+            if (typeof ref !== "string")
+                throw new Error("Malformed pnpm snapshot reference");
+            if (field === "dependencies" && own(snapshot.optionalDependencies, requested) !== undefined)
+                continue;
+            const peer = peers.find(edge => edge.requested === requested), optional = field === "optionalDependencies" || peer?.optional === true;
+            rows.push({ from, requested, range: peer?.range ?? ref, ref, kind: peer ? "peer" : optional ? "optional" : "production", role: parent.role, direct: false, optional: parent.optional || optional, mayBeAbsent: optional, importer: false });
+        }
+    }
+    for (const peer of peers)
+        if (!rows.some(edge => edge.requested === peer.requested))
+            rows.push({ ...peer, from, role: parent.role, direct: false, optional: parent.optional || peer.optional, mayBeAbsent: peer.optional, importer: false });
+    return rows;
+}
+/** pnpm v9 adapter, including pnpm 12 environment + project YAML documents. No target code executes. */
+export function pnpmInventory(pkg, root, file, inventory, inputs, rows) {
+    const relative = (target) => slash(path.relative(root, target)), manifest = relative(pkg.entryPoint), directory = path.dirname(file);
+    const text = input(file, root, inputs), { lock, document } = projectLock(text);
+    if (!inventory.lockfiles.some(row => row.file === relative(file)))
+        inventory.lockfiles.push({ file: relative(file), version: 9, sha256: hash(text), projectDocument: document, ...(document === 2 ? { environmentDocument: "excluded" } : {}) });
+    const configFile = path.join(directory, "pnpm-workspace.yaml");
+    let config = {};
+    if (fs.existsSync(configFile)) {
+        const text = input(configFile, root, inputs), docs = yamlDocuments(text);
+        if (docs.length !== 1)
+            throw new Error("pnpm workspace configuration must be one YAML document");
+        config = docs[0];
+        inventory.configurationInputs ??= [];
+        if (!inventory.configurationInputs.some(row => row.file === relative(configFile)))
+            inventory.configurationInputs.push({ file: relative(configFile), sha256: hash(text) });
+    }
+    const rootFile = path.join(directory, "package.json"), rootManifest = fs.existsSync(rootFile) ? JSON.parse(input(rootFile, root, inputs)) : {};
+    const selectedManifest = JSON.parse(input(pkg.entryPoint, root, inputs));
+    const manifestRow = inventory.manifests.find(row => row.file === manifest);
+    manifestRow.overrides = { manifest: own(rootManifest.pnpm, "overrides") ?? {}, workspace: config.overrides ?? {}, lockfile: lock.overrides ?? {} };
+    const start = slash(path.relative(directory, pkg.root)) || ".";
+    const queue = importerEdges(start, selectedManifest, lock, config, rootManifest, true), visited = new Set();
+    const gap = (reason, edge) => inventory.gaps.push({ manifest, reason, dependency: edge.requested, from: edge.from, range: edge.range });
+    for (let index = 0; index < queue.length; index++) {
+        const edge = queue[index];
+        if (index >= 100000) {
+            gap("Dependency traversal limit exceeded", edge);
+            break;
+        }
+        if (!edge.ref) {
+            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 pnpm dependency/peer in lockfile", edge);
+            continue;
+        }
+        try {
+            let name, version, source, location, next;
+            if (edge.ref.startsWith("link:")) {
+                if (!edge.importer || edge.ref.includes("\\") || path.posix.isAbsolute(edge.ref.slice(5)) || edge.ref.slice(5).includes(":"))
+                    throw new Error("Unsupported pnpm link reference");
+                const target = path.resolve(directory, edge.from, edge.ref.slice(5), "package.json");
+                if (!within(root, target) || !fs.existsSync(target))
+                    throw new Error("pnpm workspace manifest unavailable or outside repository");
+                const data = JSON.parse(input(target, root, inputs));
+                if (!object(data) || typeof data.name !== "string" || typeof data.version !== "string" || !semver.valid(data.version))
+                    throw new Error("Missing pnpm workspace name/version");
+                name = data.name;
+                version = data.version;
+                source = "workspace";
+                location = slash(path.relative(directory, path.dirname(target))) || ".";
+                const linked = importerEdges(location, data, lock, config, rootManifest, false);
+                next = () => linked.map(child => ({ ...child, direct: false, role: edge.role, optional: edge.optional || child.optional }));
+            }
+            else {
+                const id = identity(edge.requested, edge.ref);
+                if (!id)
+                    throw new Error("Unsupported pnpm package reference (file/git/custom source or non-semver identity)");
+                const record = own(lock.packages, id.base), snapshot = own(lock.snapshots, id.key);
+                if (!object(record) || !object(snapshot))
+                    throw new Error("Missing pnpm package record or exact peer-context snapshot");
+                name = id.name;
+                version = id.version;
+                source = sourceOf(record);
+                location = id.key;
+                next = () => children(location, snapshot, record, edge);
+            }
+            const spec = registrySpec(edge.requested, edge.resolvedRange ?? edge.range);
+            if (spec && (spec.name !== name || semver.validRange(spec.range) && !semver.satisfies(version, spec.range)))
+                inventory.notices.push({ manifest, from: edge.from, dependency: edge.requested, range: edge.range, version, reason: "Locked identity/version differs from requested range; alias/override or peer policy may explain this. Installation validity is not assessed" });
+            const id = hash(`${name}|${version}|${source}`), row = rows.get(id) ?? { id, name, version, source, locations: [], uses: [] };
+            rows.set(id, row);
+            const install = `${relative(file)}#${source === "workspace" ? "importers" : "snapshots"}/${location}`;
+            if (!row.locations.includes(install))
+                row.locations.push(install);
+            const use = { project: pkg.name, manifest, from: edge.from, requested: edge.requested, range: edge.range, ...(edge.resolvedRange ? { resolvedRange: edge.resolvedRange } : {}), 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 = `${install}|${edge.role}|${edge.optional}`;
+            if (visited.has(key))
+                continue;
+            visited.add(key);
+            queue.push(...next());
+        }
+        catch (error) {
+            gap(error instanceof Error ? error.message : "pnpm dependency inventory unavailable", edge);
+        }
+    }
+}

package/dist/dependency-spec.d.ts

@@ -0,0 +1,13 @@
+export type DependencyKind = "production" | "development" | "optional" | "peer";
+type Json = Record<string, unknown>;
+export declare function declarations(manifest: Json, includeDevelopment?: boolean): {
+    requested: string;
+    range: string;
+    kind: DependencyKind;
+    optional: boolean;
+}[];
+export declare function registrySpec(name: string, range: string): {
+    name: string;
+    range: string;
+} | undefined;
+export {};

package/dist/dependency-spec.js

@@ -0,0 +1,30 @@
+import semver from "semver";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const kinds = { dependencies: "production", devDependencies: "development", optionalDependencies: "optional", peerDependencies: "peer" };
+export function declarations(manifest, includeDevelopment = true) {
+    const rows = [];
+    for (const [field, kind] of Object.entries(kinds)) {
+        if (!includeDevelopment && kind === "development")
+            continue;
+        if (manifest[field] === undefined)
+            continue;
+        if (!object(manifest[field]))
+            throw new Error(`Invalid ${field}`);
+        for (const [requested, range] of Object.entries(manifest[field])) {
+            if (typeof range !== "string")
+                throw new Error(`Invalid dependency range for ${requested}`);
+            if (kind === "production" && object(manifest.optionalDependencies) && requested in manifest.optionalDependencies)
+                continue;
+            const peer = object(manifest.peerDependenciesMeta) ? manifest.peerDependenciesMeta[requested] : undefined;
+            rows.push({ requested, range, kind, optional: kind === "optional" || kind === "peer" && object(peer) && peer.optional === true });
+        }
+    }
+    return rows.sort((a, b) => a.requested.localeCompare(b.requested, "en") || a.kind.localeCompare(b.kind, "en"));
+}
+export function registrySpec(name, range) {
+    if (range.startsWith("npm:")) {
+        const match = /^npm:((?:@[^/]+\/)?[^@/]+)(?:@(.+))?$/.exec(range);
+        return match ? { name: match[1], range: match[2] ?? "*" } : undefined;
+    }
+    return semver.validRange(range) ? { name, range } : undefined;
+}

package/dist/error-handling-scoring.d.ts

@@ -0,0 +1 @@
+export declare function errorHandlingDecision(total: number, unexplained: number, unknown: number, unresolvedUses: number): import("./scoring-decision.js").ScoringDecision | undefined;

package/dist/error-handling-scoring.js

@@ -0,0 +1,15 @@
+import { firstMatch } from "./scoring-decision.js";
+import { fraction, roundScore } from "./score-arithmetic.js";
+export function errorHandlingDecision(total, unexplained, unknown, unresolvedUses) {
+    if (![total, unexplained, unknown, unresolvedUses].every(value => Number.isSafeInteger(value) && value >= 0) || unexplained + unknown > total)
+        throw new Error("Invalid handler population.");
+    if (!total || unknown || unresolvedUses)
+        return undefined;
+    const populationScore = roundScore(fraction(10n * BigInt(total - unexplained), BigInt(total)));
+    const cap = unexplained ? 9 : 10;
+    return firstMatch("javascript-typescript/errorHandling/failure-disposition-v2", { countingUnit: "distinctHandlerBody", totalHandlers: total, assessedHandlers: total, unexplainedSwallowing: unexplained,
+        unknownHandlers: unknown, unresolvedCallbackUses: unresolvedUses, populationScore, cap,
+        formula: "min(10 - 10 * unexplainedSwallowing / assessedHandlers, unexplainedSwallowing > 0 ? 9 : 10)", rounding: "half-up-one-decimal" }, [{ id: "issueCap", condition: "unexplainedSwallowing > 0 and populationScore > 9", matched: unexplained > 0 && populationScore > 9,
+            score: 9, categories: ["unexplainedSwallowing"] },
+        { id: "population", condition: "otherwise", matched: true, score: populationScore, categories: ["unexplainedSwallowing"] }]);
+}

package/dist/error-handling.d.ts

@@ -1,6 +1,8 @@
 import ts from "typescript";
 import { type Dimension } from "./evidence.js";
 import { HandlerResolver } from "./handler-resolution.js";
+import { type HandlerDisposition } from "./handler-disposition.js";
+import type { FailureContracts } from "./failure-contracts.js";
 type UsageKind = "catchClause" | "promiseCatch" | "promiseThenRejection";
 interface Handler {
     id: string;
@@ -10,6 +12,7 @@ interface Handler {
     kind: "catchClause" | "promiseRejection";
     classification: "unexplainedEmpty" | "documentedEmpty" | "containsCode";
     comments: string[];
+    disposition: HandlerDisposition;
     uses: {
         file: string;
         line: number;
@@ -17,7 +20,7 @@ interface Handler {
         resolution: "inline" | "reference";
     }[];
 }
-export declare function inspectErrorHandling(source: ts.SourceFile, checker: ts.TypeChecker, file: string, project: string, resolver: HandlerResolver): {
+export declare function inspectErrorHandling(source: ts.SourceFile, checker: ts.TypeChecker, file: string, project: string, resolver: HandlerResolver, contracts: FailureContracts): {
     handlers: Handler[];
     uninspectedCallbacks: {
         file: string;

package/dist/error-handling.js

@@ -1,6 +1,8 @@
 import ts from "typescript";
-import { hash } from "./evidence.js";
+import { hash, scored } from "./evidence.js";
 import { unwrapHandler } from "./handler-resolution.js";
+import { classifyDisposition } from "./handler-disposition.js";
+import { errorHandlingDecision } from "./error-handling-scoring.js";
 function undefinedValue(node, checker) {
     node = unwrapHandler(node);
     if (ts.isVoidExpression(node))
@@ -17,11 +19,22 @@ function emptyBody(body, checker) {
         (ts.isReturnStatement(statement) && (!statement.expression || undefinedValue(statement.expression, checker))));
 }
 function bodyComments(body, source) {
+    const nested = [];
+    function visit(node) {
+        if (node !== body && (ts.isFunctionLike(node) || ts.isLiteralExpression(node) || ts.isTemplateExpression(node))) {
+            nested.push({ start: ts.isFunctionLike(node) ? node.pos : node.getStart(source), end: node.end });
+            return;
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(body);
     const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, source.languageVariant, source.text.slice(body.pos, body.end));
     const comments = [];
     for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
         if (token !== ts.SyntaxKind.SingleLineCommentTrivia && token !== ts.SyntaxKind.MultiLineCommentTrivia)
             continue;
+        if (nested.some(range => body.pos + scanner.getTokenPos() >= range.start && body.pos + scanner.getTokenPos() < range.end))
+            continue;
         const text = scanner.getTokenText().replace(/^\/\/?\*?|\*\/$/g, "").trim();
         if (/[\p{L}\p{N}]/u.test(text))
             comments.push(text);
@@ -41,20 +54,24 @@ function rejectionArgument(call, checker) {
     if (declaration.name.text === "then" && call.arguments.length > 1)
         return { index: 1, kind: "promiseThenRejection" };
 }
-export function inspectErrorHandling(source, checker, file, project, resolver) {
+export function inspectErrorHandling(source, checker, file, project, resolver, contracts) {
     const handlers = new Map();
     const uninspectedCallbacks = [];
     function add(body, kind, at, resolution) {
         const identity = resolver.identity(body);
         const existing = handlers.get(identity.id);
         const use = { file, line: source.getLineAndCharacterOfPosition(at.getStart(source)).line + 1, kind, resolution };
+        const empty = emptyBody(body, checker), comments = bodyComments(body, body.getSourceFile());
+        const disposition = classifyDisposition(body, checker, empty, comments, at, contracts);
         if (existing) {
             existing.uses.push(use);
+            if (existing.disposition.classification !== disposition.classification)
+                existing.disposition = { classification: "unknown", reason: "Uses of the shared handler have different failure contexts." };
             return;
         }
-        const empty = emptyBody(body, checker), comments = empty ? bodyComments(body, body.getSourceFile()) : [];
         const classification = !empty ? "containsCode" : comments.length ? "documentedEmpty" : "unexplainedEmpty";
-        handlers.set(identity.id, { ...identity, kind: kind === "catchClause" ? "catchClause" : "promiseRejection", classification, comments, uses: [use] });
+        handlers.set(identity.id, { ...identity, kind: kind === "catchClause" ? "catchClause" : "promiseRejection", classification, comments,
+            disposition, uses: [use] });
     }
     function visit(node) {
         if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node))
@@ -77,19 +94,25 @@ export function inspectErrorHandling(source, checker, file, project, resolver) {
     visit(source);
     return { handlers: [...handlers.values()], uninspectedCallbacks };
 }
-function handlerFinding(handler) {
-    return { category: "unexplainedEmptyHandler", ruleId: "javascript-typescript/errorHandling/unexplainedEmptyHandler",
-        fingerprint: hash(`${handler.id}|unexplainedEmptyHandler`), file: handler.file, project: handler.project, line: handler.line,
-        severity: "info", confidence: "high",
-        message: "Handler contains only empty syntax or an undefined return, without a body comment. Review whether discarding the failure is intentional.",
-        observations: { handlerId: handler.id, kind: handler.kind, uses: handler.uses, classification: "reviewLead", scoreDisposition: "excludedUncalibrated" } };
+function handlerFinding(handler, scoreAvailable) {
+    const actionable = handler.disposition.classification === "unexplainedSwallowing";
+    const category = actionable ? "unexplainedSwallowing" : "unknownHandlerDisposition";
+    return { category, ruleId: `javascript-typescript/errorHandling/${category}`,
+        fingerprint: hash(`${handler.id}|${category}`), file: handler.file, project: handler.project, line: handler.line,
+        severity: actionable && scoreAvailable ? "warning" : "info", confidence: actionable ? "high" : "low",
+        message: handler.disposition.reason,
+        observations: { handlerId: handler.id, kind: handler.kind, uses: handler.uses, classification: handler.disposition.classification,
+            scoreDisposition: !actionable ? "excludedUnknown" : scoreAvailable ? "policyInput" : "excludedUnavailablePopulation" } };
 }
 export function errorHandlingEvidence(results, incomplete) {
     const unique = new Map();
     for (const row of results.flatMap(result => result.handlers)) {
         const existing = unique.get(row.id);
-        if (existing)
+        if (existing) {
             existing.uses.push(...row.uses);
+            if (existing.disposition.classification !== row.disposition.classification)
+                existing.disposition = { classification: "unknown", reason: "Selected project contexts disagree about the shared handler disposition." };
+        }
         else
             unique.set(row.id, { ...row, uses: [...row.uses] });
     }
@@ -100,12 +123,22 @@ export function errorHandlingEvidence(results, incomplete) {
         .sort((a, b) => a.file.localeCompare(b.file, "en") || a.line - b.line);
     const count = (classification) => handlers.filter(handler => handler.classification === classification).length;
     const unexplained = count("unexplainedEmpty");
-    return { status: incomplete ? "failed" : "skipped", basis: incomplete ? "Incomplete source; handler observations are diagnostic only." :
-            "Handler syntax and documented intent are observed; error-handling scoring is not calibrated. Code presence is not proof of recovery.",
-        scope: { id: "javascript-typescript/errorHandling/handler-evidence-v2", coverage: "partial",
-            includes: ["catch-clauses", "inline-standard-promise-rejection-handlers", "body-comments", "selected-source-referenced-handlers"],
-            excludes: ["error-handling-score", "general-exception-flow", "arbitrary-callback-value-flow", "correctness-of-recovery", "semantic-rationale-judgment"] },
-        findings: handlers.filter(handler => handler.classification === "unexplainedEmpty").map(handlerFinding), handlerEvidence: { version: 2, countingUnit: "distinctHandlerBody",
+    const dispositions = Object.fromEntries(["propagated", "failureResult", "reported", "fallback", "documented", "unexplainedSwallowing", "unknown"]
+        .map(kind => [kind, handlers.filter(handler => handler.disposition.classification === kind).length]));
+    const decision = incomplete ? undefined : errorHandlingDecision(handlers.length, dispositions.unexplainedSwallowing, dispositions.unknown, uninspectedCallbacks.length);
+    const findings = handlers.filter(handler => ["unexplainedSwallowing", "unknown"].includes(handler.disposition.classification))
+        .map(handler => handlerFinding(handler, !!decision));
+    const scope = { id: "javascript-typescript/errorHandling/failure-disposition-v2", coverage: "partial",
+        includes: ["catch-clauses", "inline-standard-promise-rejection-handlers", "attached-intent", "selected-source-referenced-handlers", "bounded-failure-continuations"],
+        excludes: ["general-exception-flow", "arbitrary-callback-value-flow", "correctness-of-recovery", "semantic-rationale-judgment"] };
+    const dispositionEvidence = { version: 1, countingUnit: "distinctHandlerBody", totalHandlers: handlers.length,
+        assessedHandlers: handlers.length - dispositions.unknown, unknownHandlers: dispositions.unknown, counts: dispositions,
+        assessedPercent: handlers.length ? 100 * (handlers.length - dispositions.unknown) / handlers.length : null,
+        unresolvedCallbackUses: uninspectedCallbacks.length, populationComplete: !incomplete && !dispositions.unknown && !uninspectedCallbacks.length };
+    const dimension = decision ? scored(decision, "Partial Error Handling: unexplained swallowing among distinct assessed handler bodies. Documented intent is honored; failure outcomes are signals, not proof of correct recovery.", findings, dispositionEvidence) : { status: incomplete ? "failed" : "skipped", findings,
+        basis: incomplete ? "Incomplete source; handler observations are diagnostic only." : !handlers.length ? "No assessed handler population; error handling is unavailable." :
+            "Unknown handler dispositions or unresolved callback uses prevent a reliable population score." };
+    return { ...dimension, scope, dispositionEvidence, handlerEvidence: { version: 2, countingUnit: "distinctHandlerBody",
             totalHandlers: handlers.length, unexplainedEmptyHandlers: unexplained, documentedEmptyHandlers: count("documentedEmpty"),
             handlersContainingCode: count("containsCode"), unexplainedEmptyPercent: handlers.length ? 100 * unexplained / handlers.length : null,
             handlerUseSites: handlers.reduce((sum, handler) => sum + handler.uses.length, 0),

package/dist/evidence-reader.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
 import { validateEvidence } from "./evidence-tools.js";
+import { supportsPythonComparison } from "./python-evidence.js";
 const ajv = new Ajv2020({ allErrors: true, strict: false });
 addFormats(ajv);
 let legacyValidator;
@@ -46,7 +47,8 @@ export function inspectEvidence(file, expected = {}) {
     const legacy = evidence.schemaVersion === 2;
     const failed = Object.values(evidence.dimensions).some(dimension => dimension.status === "failed");
     const incomplete = !legacy && evidence.analysis.status !== "complete";
-    return { evidence, compatibility: { mode: legacy ? "legacy" : "native", comparisonAvailable: !legacy && !failed && !incomplete,
+    const experimental = !legacy && evidence.tool.ecosystem === "python" && !supportsPythonComparison(evidence);
+    return { evidence, compatibility: { mode: legacy ? "legacy" : "native", comparisonAvailable: !legacy && !failed && !incomplete && !experimental,
             analysisStatus: legacy ? "unknown" : evidence.analysis.status,
             scopeAvailable: !legacy && Object.values(evidence.dimensions).every(dimension => dimension.scope !== undefined) },
         usable: !failed && !incomplete };

package/dist/evidence-tools.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
 import { dimensionKeys } from "./scorecard-contract.js";
+import { validatePythonEvidence, supportsPythonComparison } from "./python-evidence.js";
 const ajv = new Ajv2020({ allErrors: true, strict: false });
 addFormats(ajv);
 let validator;
@@ -14,6 +15,7 @@ export function validateEvidence(value) {
     if (!validator(value))
         throw new Error("Invalid evidence: " + ajv.errorsText(validator.errors));
     const evidence = value;
+    validatePythonEvidence(evidence);
     if (evidence.filters.analyzedUnits > evidence.filters.totalUnits)
         throw new Error("Analyzed units exceed total units.");
     const ids = findings(evidence).map(finding => finding.fingerprint);
@@ -54,6 +56,8 @@ function entryPoint(evidence) {
 }
 export function compare(current, baseline, allowIncompatible = false) {
     const reasons = [];
+    if ([current, baseline].some(item => item.tool.ecosystem === "python" && !supportsPythonComparison(item)))
+        reasons.push("Python comparisons require supported Method Complexity scores; historical previews and empty populations cannot gate");
     for (const key of ["ecosystem", "version", "name"])
         if (current.tool[key] !== baseline.tool[key])
             reasons.push("tool." + key + " differs");