codemetrics-ai 0.5.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/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");

package/dist/function-scoring.d.ts

@@ -1,5 +1,6 @@
 import { type Dimension, type Finding } from "./evidence.js";
 import type { FunctionMeasurement } from "./function-measurements.js";
-export declare const complexityAnchors: readonly [readonly [3, 10], readonly [5, 8], readonly [10, 6], readonly [20, 4], readonly [40, 0]];
+import { complexityAnchors } from "#source-facts/population.mjs";
+export { complexityAnchors };
 export declare const maintainabilityAnchors: readonly [readonly [40, 0], readonly [52, 2], readonly [58, 4], readonly [65, 6], readonly [70, 8], readonly [75, 10]];
 export declare function scoreFunctions(functions: FunctionMeasurement[], dimension: "codeQuality" | "maintainability", findings?: Finding[]): Dimension;

package/dist/function-scoring.js

@@ -1,6 +1,7 @@
 import { scored } from "./evidence.js";
-import { add, decimal, fraction, interpolate, multiply, numeric, roundScore, subtract } from "./score-arithmetic.js";
-export const complexityAnchors = [[3, 10], [5, 8], [10, 6], [20, 4], [40, 0]];
+import { aggregatePopulation, complexityPopulation, complexityAnchors } from "#source-facts/population.mjs";
+import { functionSourceFacts } from "./source-facts.js";
+export { complexityAnchors };
 export const maintainabilityAnchors = [[40, 0], [52, 2], [58, 4], [65, 6], [70, 8], [75, 10]];
 export function scoreFunctions(functions, dimension, findings = []) {
     const complexity = dimension === "codeQuality";
@@ -11,29 +12,17 @@ export function scoreFunctions(functions, dimension, findings = []) {
         excludes: ["module-and-field-initializers", "parameter-initializers", "runtime-behavior", complexity ? "decomposition" : "change-cost"] };
     if (!functions.length)
         return { status: "skipped", basis: "No implemented functions; function score is unmeasured.", findings, scope };
-    const ordered = functions.map(item => ({ item, score: interpolate(measured(item), anchors) }))
-        .sort((a, b) => (complexity ? measured(b.item) - measured(a.item) : measured(a.item) - measured(b.item)) ||
-        (a.item.id < b.item.id ? -1 : a.item.id > b.item.id ? 1 : 0));
-    const weakCount = complexity ? 1 : Math.ceil(ordered.length / 5);
-    const restCount = ordered.length - weakCount;
-    const weakWeight = restCount ? fraction(2n, 5n * BigInt(weakCount)) : fraction(1n, BigInt(weakCount));
-    const restWeight = restCount ? fraction(3n, 5n * BigInt(restCount)) : decimal(0);
-    const losses = { weakest: decimal(0), remainder: decimal(0) };
-    const contributions = ordered.map(({ item, score }, index) => {
-        const group = index < weakCount ? "weakest" : "remainder";
-        const weight = index < weakCount ? weakWeight : restWeight;
-        const weightedLoss = multiply(subtract(decimal(10), score), weight);
-        losses[group] = add(losses[group], weightedLoss);
-        return { ...item, group, individualScore: numeric(score), weightNumerator: Number(weight.numerator),
-            weightDenominator: Number(weight.denominator), weightedScoreLoss: numeric(weightedLoss) };
-    });
-    const total = subtract(decimal(10), add(losses.weakest, losses.remainder));
+    const population = complexity ? complexityPopulation(functionSourceFacts(functions))
+        : aggregatePopulation(functions.map(item => ({ id: item.id, value: measured(item) })), anchors, false, Math.ceil(functions.length / 5));
+    const { weakCount, restCount, losses } = population;
+    const byFunctionId = new Map(functions.map(item => [item.id, item]));
+    const contributions = population.contributions.map(({ id, ...contribution }) => ({ ...byFunctionId.get(id), ...contribution }));
     const decision = { version: 1, policy: `javascript-typescript/${dimension}/owned-functions-v2`, operation: "deductions",
-        finalScore: roundScore(total), inputs: { baseline: 10, eligibleFunctions: ordered.length, weakCount, restCount,
+        finalScore: population.score, inputs: { baseline: 10, eligibleFunctions: functions.length, weakCount, restCount,
             anchors, aggregation: complexity ? "worst-40-remainder-60" : "weakest-quintile-40-remainder-60",
-            rounding: "decimal-rational-half-up-one-decimal", unroundedScore: numeric(total) },
-        steps: (restCount ? ["weakest", "remainder"] : ["weakest"]).map(group => ({ id: group, kind: "component", score: numeric(losses[group]),
-            disposition: "applied", inputs: { weightedScoreLoss: numeric(losses[group]), functionCount: group === "weakest" ? weakCount : restCount },
+            rounding: "decimal-rational-half-up-one-decimal", unroundedScore: population.unroundedScore },
+        steps: (restCount ? ["weakest", "remainder"] : ["weakest"]).map(group => ({ id: group, kind: "component", score: losses[group],
+            disposition: "applied", inputs: { weightedScoreLoss: losses[group], functionCount: group === "weakest" ? weakCount : restCount },
             findingCategories: complexity ? ["highFunctionComplexity"] : [] })), findingEffects: [] };
     const result = scored(decision, `${complexity ? "Method complexity: one worst function" : "Maintainability: weakest ceil(N/5) functions"} receives 40%; remaining functions receive 60%. Single-function scopes use their own score. JS/TS remains uncalibrated across ecosystems.`, findings, { ...decision.inputs, measurement: "owned-function-body-v2-type-erasure", functionContributions: contributions, topOffenders: contributions.slice(0, 5) });
     // Findings identify population inputs, never additional independent penalties.
@@ -44,7 +33,7 @@ export function scoreFunctions(functions, dimension, findings = []) {
             effect: group ? "policyInput" : "noAdditionalReduction", stepIds: group ? [group] : [] };
     });
     return { ...result, scope, ...(complexity ? { displayName: "Method Complexity", componentDetails: {
-                methodComplexity: { score: result.score, eligibleFunctions: ordered.length, topOffenders: contributions.slice(0, 5) },
+                methodComplexity: { score: result.score, eligibleFunctions: functions.length, topOffenders: contributions.slice(0, 5) },
                 decomposition: { score: null, status: "unsupported", description: "JS/TS decomposition is not measured by this policy." }
             } } : {}) };
 }

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { defaultEvidencePath, defaultMetricsPath, dimensionKeys, ecosystemId, metricsCsvHeader, type DimensionKey, } from "./scorecard-contract.js";
 export { analyze } from "./analyzer.js";
+export { enrichDependencies } from "./dependency-evidence.js";
+export type { RegistryReader } from "./dependency-metadata.js";
 export { compare, gate, sarif, validateEvidence, readEvidence } from "./evidence-tools.js";
 export type { Evidence, Finding, Dimension } from "./evidence.js";
 export { readCompatibleEvidence, inspectEvidence, type LegacyEvidence } from "./evidence-reader.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { defaultEvidencePath, defaultMetricsPath, dimensionKeys, ecosystemId, metricsCsvHeader, } from "./scorecard-contract.js";
 export { analyze } from "./analyzer.js";
+export { enrichDependencies } from "./dependency-evidence.js";
 export { compare, gate, sarif, validateEvidence, readEvidence } from "./evidence-tools.js";
 export { readCompatibleEvidence, inspectEvidence } from "./evidence-reader.js";

package/dist/python/ASYNC_ADAPTERS.md

@@ -0,0 +1,38 @@
+# Python callback adapter context
+
+`async_adapters.py` implements `python/async-callback-adapters-review-v1` as an experimental report embedded at `dimensions.performanceAsync.adapterReview` in development adapter 0.14.0, ruleset `python-2026-10-24-async-adapters-review-v1`. It supplements the [async context report](ASYNC_CONTEXT.md) without changing its original observations. The archive ships this guide and the producer; the companion skill reports the evidence without runtime claims. Historical 0.13.0 reports retain their contract without invented adapter observations. **Async/Blocking Usage and Error Handling remain unscored.** Method Complexity remains Python's only scored dimension.
+
+```powershell
+py -3.12 analyzers/python/async_adapters.py E:/repos/example --output E:/temp/adapters.json
+py -3.12 analyzers/python/async_adapters_corpus.py --repos E:/repos --output TestResults/python-adapters-new
+```
+
+The same source-selection flags and optional run/audit UUIDs as the original async reviewer are supported. Output must be a new `.json` file with an existing parent; the corpus directory must be new. Target code is parsed, never imported or executed.
+
+## Partial construction
+
+Import-matched `functools.partial` calls record the construction extent, first positional callback expression, and bound positional/keyword expression shapes and extents. Literal argument values are not copied. `*args` and `**kwargs` are explicit syntax, not known argument counts. With a missing or starred first positional argument, callback layout is unresolved; the tool does not interpret `func=` as a callback. Callback references use the existing conservative local-definition/import-spelling rules. Calls, lambdas, receiver methods, and nested partial results are not resolved to callback implementations.
+
+These are construction observations, not proof that a partial was created, callable, executed, or offloaded successfully. Eager callback/argument calls retain their original owner. Callback and lambda bodies are never traversed to assign behavior to the async caller.
+
+An inline partial passed to a recognized helper or used as a callee links to its original owned construction call ID. A stored partial supports a direct-suite, single-name assignment in the same async owner, ending before use, with exactly one binding and a first positional callback. Reassignment, parameters, aliases, conditional/annotated/chained assignments, deletion, reflective operations, cross-scope writes, and comprehension shadowing withhold that link. Stored links in deferred generator bodies are withheld. Inline constructions in deferred bodies remain separately labeled syntax.
+
+For example, Starlette's `func = functools.partial(func, *args, **kwargs)` is a visible construction, but the parameter and assignment make `func` ambiguous. The subsequent helper callback remains unresolved. We do not infer the incoming callable's identity.
+
+Supported stored `sync_to_async` wrappers also expose partial callback context evaluated at construction. Repeated callback references link to the same construction. Construction, callback references, and invocation expressions must never be added together as distinct offloaded operations.
+
+## Decorator links
+
+A bare-name callee or helper callback can link to a unique direct lexical `def` with exactly one import-matched `asgiref.sync.sync_to_async` decorator. Supported syntax is `@sync_to_async`, `@sync_to_async()`, or a factory with one literal boolean `thread_sensitive` keyword. Import aliases are supported. The decorator is resolved in the definition's enclosing scope, not the caller's scope.
+
+The definition must end before the reference, have a selected source-fact owner, and have no competing binding. Stacked or unknown decorators, unsupported arguments, starred arguments, async definitions, conditional definitions, late definitions, receiver methods, and ambiguous/mutated imports are unresolved. Class namespaces are not lexical closures for methods. A positive link records a synchronous source definition and decorator syntax; it does not reclassify that owner's body as async or validate passing a decorated callable to a thread helper. Decorator headers are not added to the original async call population.
+
+## Accounting and validation
+
+Every original async call keeps its ID and direct/deferred execution context. Construction and reference counts are separate, as are production, test, support, and generated populations. Sync-only and empty populations are unavailable, with null measurements. Zero matches are not a clean async verdict. Existing unresolved import counts are unchanged.
+
+The report carries source selection, source-facts producer/policy, original async-row hash, configuration fingerprint, and matching run/audit IDs. It regenerates the input report before collection and verifies source hashes and exact owner/call measurements while collecting. Stale, inconsistent, changed, over-budget, or failed inputs produce exit 2, diagnostics, empty rows, and a null summary. These checks are not report authentication, filesystem locking, control-flow proof, or runtime identity analysis.
+
+No score, finding, deduction, gate, automatic concurrency recommendation, or judgment of developer intent is emitted.
+
+The package validator checks internal consistency against validated async/context reports: invocation and source metadata, original-row hash, ordered owners/calls, extents, construction links and repeated references, selected local definitions, decorator options, and recomputed context/population summaries. It is not independent AST remeasurement or report authentication. Incomplete required evidence makes the combined scorecard unusable; observations cannot restore a score. See the [installed-package study](../../shared/scorecard-schema/calibration-runs/python-async-adapters-package-2026-10-24.md).