codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/failure-contracts.d.ts

@@ -0,0 +1,19 @@
+import ts from "typescript";
+export declare function standardConsole(call: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/** Source-backed contracts, not name-based exemptions or a runtime data-flow proof. */
+export declare class FailureContracts {
+    private readonly checker;
+    private readonly selected;
+    private readonly references;
+    private readonly writes;
+    private readonly local;
+    constructor(checker: ts.TypeChecker, sources: readonly ts.SourceFile[], selected: readonly ts.SourceFile[], root: string);
+    forwardsCaughtError(call: ts.CallExpression): boolean;
+    explicitResult(expression: ts.Expression | undefined, depth?: number): boolean;
+    reports(call: ts.CallExpression): boolean;
+    private reachesConsole;
+    guardedUndefinedResult(body: ts.ConciseBody): boolean;
+    private commonJsFile;
+    private guardedCallResult;
+    private truthyGuard;
+}

package/dist/failure-contracts.js

@@ -0,0 +1,261 @@
+import ts from "typescript";
+import path from "node:path";
+import { exclusion } from "./discovery.js";
+import { unwrapHandler } from "./handler-resolution.js";
+export function standardConsole(call, checker) {
+    const member = call.expression;
+    if (!ts.isPropertyAccessExpression(member) || !["error", "warn", "info", "log", "debug", "trace"].includes(member.name.text) ||
+        !ts.isIdentifier(member.expression) || member.expression.text !== "console" || !call.arguments.length || call.questionDotToken || member.questionDotToken)
+        return false;
+    const declarations = checker.getSymbolAtLocation(member.expression)?.declarations ?? [];
+    return declarations.length > 0 && declarations.every(declaration => declaration.getSourceFile().isDeclarationFile &&
+        /(?:lib\.dom\.d\.ts|[/\\]@types[/\\]node[/\\](?:web-globals[/\\])?(?:console|globals)\.d\.ts)$/.test(declaration.getSourceFile().fileName));
+}
+const descendants = (node, match) => match(node) || (ts.forEachChild(node, child => descendants(child, match)) ?? false);
+function enclosingFunction(node) {
+    for (let at = node.parent; at; at = at.parent)
+        if (ts.isFunctionLike(at))
+            return at;
+}
+function documentation(node) {
+    return (ts.getLeadingCommentRanges(node.getSourceFile().text, node.getFullStart()) ?? [])
+        .map(range => node.getSourceFile().text.slice(range.pos, range.end)).join("\n");
+}
+/** Source-backed contracts, not name-based exemptions or a runtime data-flow proof. */
+export class FailureContracts {
+    checker;
+    selected;
+    references = new Map();
+    writes = new Set();
+    local = new Set();
+    constructor(checker, sources, selected, root) {
+        this.checker = checker;
+        this.selected = selected;
+        for (const source of sources) {
+            const relative = path.relative(root, source.fileName).replaceAll("\\", "/");
+            if (source.isDeclarationFile || relative.startsWith("../") || exclusion(relative))
+                continue;
+            this.local.add(source);
+            const visit = (node) => {
+                if (ts.isIdentifier(node)) {
+                    const symbol = ts.isShorthandPropertyAssignment(node.parent)
+                        ? checker.getShorthandAssignmentValueSymbol(node.parent) : checker.getSymbolAtLocation(node);
+                    if (symbol) {
+                        const refs = this.references.get(symbol) ?? [];
+                        refs.push(node);
+                        this.references.set(symbol, refs);
+                    }
+                }
+                if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment) {
+                    const record = (target) => {
+                        if (ts.isIdentifier(target) || ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) {
+                            const symbol = checker.getSymbolAtLocation(target);
+                            if (symbol)
+                                this.writes.add(symbol);
+                        }
+                        else
+                            ts.forEachChild(target, record);
+                    };
+                    record(node.left);
+                }
+                if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+                    [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)) {
+                    const symbol = checker.getSymbolAtLocation(node.operand);
+                    if (symbol)
+                        this.writes.add(symbol);
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(source);
+        }
+    }
+    forwardsCaughtError(call) {
+        if (call.questionDotToken || !ts.isIdentifier(call.expression) || !call.arguments.length)
+            return false;
+        const target = this.checker.getSymbolAtLocation(call.expression), error = unwrapHandler(call.arguments[0]);
+        const declaration = target?.declarations?.[0];
+        if (!target || this.writes.has(target) || !declaration || !ts.isParameter(declaration) || declaration.initializer ||
+            declaration.getSourceFile() !== call.getSourceFile() || call.pos < declaration.parent.pos || call.end > declaration.parent.end)
+            return false;
+        const caughtSymbol = (symbol) => {
+            const binding = symbol?.declarations?.[0];
+            return !!symbol && !!binding && ts.isVariableDeclaration(binding) && ts.isCatchClause(binding.parent) &&
+                !this.writes.has(symbol) && call.pos >= binding.parent.block.pos && call.end <= binding.parent.block.end;
+        };
+        // Only plain payload expressions, never an unrelated call taking the error.
+        const payload = (node) => {
+            if (ts.isIdentifier(node) && caughtSymbol(this.checker.getSymbolAtLocation(node)))
+                return true;
+            if (ts.isPropertyAccessExpression(node))
+                return payload(node.expression);
+            if (ts.isObjectLiteralExpression(node))
+                return node.properties.some(property => ts.isPropertyAssignment(property) ? payload(property.initializer) : ts.isShorthandPropertyAssignment(property) &&
+                    caughtSymbol(this.checker.getShorthandAssignmentValueSymbol(property)));
+            return false;
+        };
+        return payload(error);
+    }
+    explicitResult(expression, depth = 0) {
+        if (!expression || depth > 4)
+            return false;
+        expression = unwrapHandler(expression);
+        if (ts.isObjectLiteralExpression(expression) || ts.isArrayLiteralExpression(expression) || ts.isNewExpression(expression))
+            return true;
+        if (!ts.isIdentifier(expression))
+            return false;
+        const symbol = this.checker.getSymbolAtLocation(expression), declarations = symbol?.declarations ?? [];
+        if (!symbol || this.writes.has(symbol) || declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]))
+            return false;
+        const declaration = declarations[0];
+        if (!ts.isVariableDeclarationList(declaration.parent) || !(declaration.parent.flags & ts.NodeFlags.Const) || !declaration.initializer)
+            return false;
+        const value = unwrapHandler(declaration.initializer);
+        return ts.isLiteralExpression(value) || [ts.SyntaxKind.NullKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(value.kind) || this.explicitResult(value, depth + 1);
+    }
+    reports(call) {
+        return this.reachesConsole(call, new Set(), 0);
+    }
+    reachesConsole(call, seen, depth, payloadPositions = new Set(call.arguments.map((_, index) => index))) {
+        if (call.questionDotToken || (ts.isPropertyAccessExpression(call.expression) && call.expression.questionDotToken))
+            return false;
+        if (standardConsole(call, this.checker))
+            return true;
+        const symbol = this.checker.getSymbolAtLocation(call.expression);
+        if (symbol && this.writes.has(symbol))
+            return false;
+        if (ts.isPropertyAccessExpression(call.expression) && ts.isIdentifier(call.expression.expression)) {
+            const receiver = this.checker.getSymbolAtLocation(call.expression.expression);
+            if (receiver && this.writes.has(receiver))
+                return false;
+        }
+        const declaration = this.checker.getResolvedSignature(call)?.declaration;
+        if (!declaration || depth >= 3 || seen.has(declaration) || !this.local.has(declaration.getSourceFile()) ||
+            !(ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration) || ts.isFunctionExpression(declaration) || ts.isArrowFunction(declaration)) || !declaration.body)
+            return false;
+        seen = new Set(seen).add(declaration);
+        const parameters = new Set(declaration.parameters.filter((parameter, index) => payloadPositions.has(index) || parameter.dotDotDotToken && [...payloadPositions].some(position => position >= index))
+            .map(parameter => this.checker.getSymbolAtLocation(parameter.name)).filter(symbol => symbol && !this.writes.has(symbol)));
+        const declaredLogger = /\b(?:log|write)\b[^\n]*\b(?:message|exception|error|warn)\b/i.test(documentation(declaration));
+        // Ordinary wrappers require an unconditional forwarding call. A documented
+        // logger may have runtime level filters; prove its payload reaches a console sink.
+        const candidates = [];
+        const visit = (node) => {
+            if (node !== declaration.body && ts.isFunctionLike(node))
+                return;
+            if (ts.isCallExpression(node))
+                candidates.push(node);
+            ts.forEachChild(node, visit);
+        };
+        if (declaredLogger)
+            visit(declaration.body);
+        else if (ts.isBlock(declaration.body)) {
+            for (const statement of declaration.body.statements) {
+                if (ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression))
+                    candidates.push(statement.expression);
+                else if (ts.isReturnStatement(statement) && statement.expression && ts.isCallExpression(statement.expression)) {
+                    candidates.push(statement.expression);
+                    break;
+                }
+                else if (!ts.isVariableStatement(statement) && !ts.isEmptyStatement(statement))
+                    break;
+            }
+        }
+        else if (ts.isCallExpression(declaration.body))
+            candidates.push(declaration.body);
+        return candidates.some(candidate => {
+            const forwarded = new Set(candidate.arguments.flatMap((arg, index) => descendants(arg, node => ts.isIdentifier(node) && parameters.has(this.checker.getSymbolAtLocation(node))) ? [index] : []));
+            return forwarded.size > 0 && this.reachesConsole(candidate, seen, depth + 1, forwarded);
+        });
+    }
+    guardedUndefinedResult(body) {
+        const fn = enclosingFunction(body);
+        if (!fn || !ts.isFunctionDeclaration(fn) || !fn.name || ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Export)
+            return false;
+        const symbol = this.checker.getSymbolAtLocation(fn.name);
+        if (!symbol || this.writes.has(symbol))
+            return false;
+        const module = this.checker.getSymbolAtLocation(fn.getSourceFile());
+        if (!module && !this.commonJsFile(fn.getSourceFile()) && !enclosingFunction(fn))
+            return false;
+        if (module && this.checker.getExportsOfModule(module).some(exported => (exported.flags & ts.SymbolFlags.Alias ? this.checker.getAliasedSymbol(exported) : exported) === symbol))
+            return false;
+        const uses = (this.references.get(symbol) ?? []).filter(node => node !== fn.name);
+        return uses.length > 0 && uses.every(node => this.selected.includes(node.getSourceFile()) &&
+            ts.isCallExpression(node.parent) && node.parent.expression === node && this.guardedCallResult(node.parent));
+    }
+    commonJsFile(source) {
+        const exportRoot = (node) => {
+            if (!ts.isPropertyAccessExpression(node))
+                return;
+            if (ts.isIdentifier(node.expression)) {
+                const base = node.expression;
+                return base.text === "exports" || base.text === "module" && node.name.text === "exports" ? base : undefined;
+            }
+            return exportRoot(node.expression);
+        };
+        const inferredExport = (node) => {
+            // Depending on the assignments present, the JS binder uses either the
+            // assignment or its root identifier as the inferred module declaration.
+            while (ts.isPropertyAccessExpression(node.parent) && node.parent.expression === node)
+                node = node.parent;
+            if (ts.isBinaryExpression(node.parent) && node.parent.left === node)
+                node = node.parent;
+            return ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && !!exportRoot(node.left);
+        };
+        return source.statements.some(statement => {
+            if (!ts.isExpressionStatement(statement) || !ts.isBinaryExpression(statement.expression) ||
+                statement.expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+                return false;
+            const base = exportRoot(statement.expression.left);
+            if (!base)
+                return false;
+            const declarations = this.checker.getSymbolAtLocation(base)?.declarations ?? [];
+            // TypeScript binds bare CommonJS `module` to its export assignment when
+            // Node declarations are absent; that inferred declaration is not shadowing.
+            return declarations.every(declaration => inferredExport(declaration) ||
+                declaration.getSourceFile().isDeclarationFile && /[/\\]@types[/\\]node[/\\]/.test(declaration.getSourceFile().fileName));
+        });
+    }
+    guardedCallResult(call) {
+        const parent = call.parent;
+        let identifier, statement;
+        if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+            identifier = parent.name;
+            statement = parent.parent.parent;
+        }
+        else if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(parent.left)) {
+            identifier = parent.left;
+            statement = parent.parent;
+        }
+        else
+            return false;
+        if (!ts.isBlock(statement.parent))
+            return false;
+        const next = statement.parent.statements[statement.parent.statements.indexOf(statement) + 1];
+        const symbol = this.checker.getSymbolAtLocation(identifier);
+        if (!symbol || !next || !ts.isIfStatement(next) || !this.truthyGuard(next.expression, symbol))
+            return false;
+        return (this.references.get(symbol) ?? []).every(node => {
+            if (ts.isVariableDeclaration(node.parent) && node.parent.name === node)
+                return true;
+            if (ts.isBinaryExpression(node.parent) && node.parent.left === node && node.parent.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+                return ts.isCallExpression(node.parent.right) && this.checker.getSymbolAtLocation(node.parent.right.expression) === this.checker.getSymbolAtLocation(call.expression) &&
+                    node.parent.parent.parent === statement.parent;
+            if (ts.isPrefixUnaryExpression(node.parent) || ts.isPostfixUnaryExpression(node.parent))
+                return false;
+            for (let at = node; at.parent && !ts.isFunctionLike(at.parent); at = at.parent) {
+                const parent = at.parent;
+                if (ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken && this.truthyGuard(parent.left, symbol))
+                    return true;
+                if (ts.isIfStatement(parent) && (parent.expression === at || parent.thenStatement === at) && this.truthyGuard(parent.expression, symbol))
+                    return true;
+            }
+            return false;
+        });
+    }
+    truthyGuard(expression, symbol) {
+        expression = unwrapHandler(expression);
+        return ts.isIdentifier(expression) ? this.checker.getSymbolAtLocation(expression) === symbol :
+            ts.isBinaryExpression(expression) && expression.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken && this.truthyGuard(expression.left, symbol);
+    }
+}

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/handler-disposition.d.ts

@@ -0,0 +1,9 @@
+import ts from "typescript";
+import type { FailureContracts } from "./failure-contracts.js";
+export type DispositionKind = "propagated" | "failureResult" | "reported" | "fallback" | "documented" | "unexplainedSwallowing" | "unknown";
+export interface HandlerDisposition {
+    classification: DispositionKind;
+    reason: string;
+    comments?: string[];
+}
+export declare function classifyDisposition(body: ts.ConciseBody, checker: ts.TypeChecker, empty: boolean, comments: string[], use: ts.Node, contracts: FailureContracts): HandlerDisposition;

package/dist/handler-disposition.js

@@ -0,0 +1,156 @@
+import ts from "typescript";
+import { unwrapHandler } from "./handler-resolution.js";
+const result = (classification, reason) => ({ classification, reason });
+// These are declarations of intent, not a judgment about whether the rationale is good.
+const intentional = /\b(?:ignor(?:e|ed|ing)|swallow(?:ed|ing)?|discard(?:ed|ing)?|optional|best[- ]effort|does nothing|no[- ]op|intention(?:al|ally))\b/i;
+function leadingComments(node) {
+    const source = node.getSourceFile();
+    return (ts.getLeadingCommentRanges(source.text, node.getFullStart()) ?? [])
+        .map(range => source.text.slice(range.pos, range.end)).filter(text => intentional.test(text));
+}
+function declaredIntent(body, checker) {
+    const owner = body.parent;
+    if (ts.isCatchClause(owner))
+        return [...leadingComments(owner), ...leadingComments(owner.parent)];
+    if (ts.isFunctionDeclaration(owner)) {
+        const declarations = owner.name ? checker.getSymbolAtLocation(owner.name)?.declarations ?? [owner] : [owner];
+        return declarations.flatMap(leadingComments);
+    }
+    if ((ts.isArrowFunction(owner) || ts.isFunctionExpression(owner)) && ts.isVariableDeclaration(owner.parent)) {
+        const list = owner.parent.parent;
+        // A comment on a multi-binding declaration cannot identify one handler's intent.
+        if (ts.isVariableDeclarationList(list) && list.declarations.length === 1)
+            return leadingComments(list.parent);
+    }
+    return leadingComments(owner);
+}
+function explicitValue(expression) {
+    if (!expression)
+        return false;
+    const node = unwrapHandler(expression);
+    // No names, calls, spreads or property reads: their value/side effects need more flow analysis.
+    if (ts.isLiteralExpression(node) || [ts.SyntaxKind.NullKeyword, ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(node.kind))
+        return true;
+    if (ts.isPrefixUnaryExpression(node))
+        return ts.isNumericLiteral(node.operand);
+    if (ts.isArrayLiteralExpression(node))
+        return node.elements.every(element => explicitValue(element));
+    return ts.isObjectLiteralExpression(node) && node.properties.every(property => ts.isPropertyAssignment(property) &&
+        !ts.isComputedPropertyName(property.name) && explicitValue(property.initializer));
+}
+function statementOutcome(statement, checker, contracts) {
+    if (ts.isThrowStatement(statement))
+        return result("propagated", "Unconditional throw on the failure path.");
+    if (ts.isReturnStatement(statement))
+        return explicitValue(statement.expression) || contracts.explicitResult(statement.expression)
+            ? result("failureResult", "Returns an explicit value/container on the failure path; suitability and caller correctness are not judged.")
+            : result("unknown", "Return value or caller contract requires additional analysis.");
+    if (ts.isBlock(statement))
+        return blockOutcome(statement.statements, checker, contracts);
+    if (ts.isIfStatement(statement)) {
+        const yes = statementOutcome(statement.thenStatement, checker, contracts);
+        const no = statement.elseStatement && statementOutcome(statement.elseStatement, checker, contracts);
+        if (yes && no && ![yes.classification, no.classification].includes("unknown"))
+            return result(yes.classification === no.classification ? yes.classification : "failureResult", "Both branches have an explicit failure disposition.");
+        return result("unknown", "Conditional failure path is not fully resolved.");
+    }
+    if (ts.isExpressionStatement(statement) && ts.isCallExpression(statement.expression)) {
+        if (contracts.forwardsCaughtError(statement.expression))
+            return result("propagated", "Passes the caught error to a caller-supplied callback; consumer correctness is outside scope.");
+        if (contracts.reports(statement.expression))
+            return result("reported", "Standard console output or a resolved source-backed logging wrapper; runtime filtering is outside scope.");
+    }
+    if (ts.isExpressionStatement(statement) || ts.isVariableStatement(statement) || ts.isEmptyStatement(statement) ||
+        ts.isFunctionDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement))
+        return;
+    return result("unknown", "Control flow is outside the bounded handler classifier.");
+}
+function blockOutcome(statements, checker, contracts) {
+    for (const statement of statements) {
+        const outcome = statementOutcome(statement, checker, contracts);
+        if (outcome)
+            return outcome;
+    }
+}
+function containsReturn(node) {
+    if (ts.isReturnStatement(node))
+        return true;
+    if (ts.isFunctionLike(node))
+        return false;
+    return ts.forEachChild(node, containsReturn) ?? false;
+}
+function guardedFallback(statement, next, checker, contracts) {
+    if (!next || !ts.isIfStatement(next) || statement.tryBlock.statements.length !== 1)
+        return false;
+    const assignment = statement.tryBlock.statements[0];
+    if (!ts.isExpressionStatement(assignment) || !ts.isBinaryExpression(assignment.expression) ||
+        assignment.expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken || !ts.isIdentifier(assignment.expression.left))
+        return false;
+    const symbol = checker.getSymbolAtLocation(assignment.expression.left);
+    const declarations = symbol?.declarations ?? [];
+    if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]) || declarations[0].initializer)
+        return false;
+    const refersToBinding = (node) => (ts.isIdentifier(node) && checker.getSymbolAtLocation(node) === symbol) ||
+        (ts.forEachChild(node, refersToBinding) ?? false);
+    if (refersToBinding(assignment.expression.right))
+        return false;
+    // Require the uninitialized binding immediately before the try: no earlier assigned state.
+    const parent = statement.parent;
+    if (!ts.isBlock(parent) && !ts.isSourceFile(parent))
+        return false;
+    const previous = parent.statements[parent.statements.indexOf(statement) - 1];
+    if (!previous || !ts.isVariableStatement(previous) || previous.declarationList.declarations.length !== 1 ||
+        !(previous.declarationList.flags & ts.NodeFlags.Let) || previous.declarationList.declarations[0] !== declarations[0])
+        return false;
+    const condition = unwrapHandler(next.expression);
+    if (!ts.isBinaryExpression(condition) || condition.operatorToken.kind !== ts.SyntaxKind.EqualsEqualsEqualsToken)
+        return false;
+    const left = unwrapHandler(condition.left), right = unwrapHandler(condition.right);
+    if (!ts.isIdentifier(left) || checker.getSymbolAtLocation(left) !== symbol || !ts.isIdentifier(right) || right.text !== "undefined")
+        return false;
+    const undefinedDeclarations = checker.getSymbolAtLocation(right)?.declarations ?? [];
+    if (undefinedDeclarations.some(declaration => !declaration.getSourceFile().hasNoDefaultLib))
+        return false;
+    const outcome = statementOutcome(next.thenStatement, checker, contracts);
+    return !!outcome && ["failureResult", "propagated", "reported"].includes(outcome.classification);
+}
+export function classifyDisposition(body, checker, empty, comments, use, contracts) {
+    const owner = body.parent;
+    // Finally may replace a throw/return, even when the catch itself is explicit.
+    if (ts.isCatchClause(owner)) {
+        for (let ancestor = owner.parent; ancestor && !ts.isFunctionLike(ancestor); ancestor = ancestor.parent)
+            if (ts.isTryStatement(ancestor) && ancestor.finallyBlock)
+                return result("unknown", "Finally may change the failure disposition.");
+    }
+    const intent = [...(empty ? comments : comments.filter(comment => intentional.test(comment))), ...declaredIntent(body, checker)];
+    if (intent.length)
+        return { ...result("documented", "Attached developer intent is honored without judging the business decision."), comments: intent };
+    if (!empty) {
+        const outcome = ts.isBlock(body) ? blockOutcome(body.statements, checker, contracts) : explicitValue(body) || contracts.explicitResult(body) ? result("failureResult", "Explicit value/container from rejection handler.") : undefined;
+        return outcome ?? result("unknown", "Code presence alone does not establish a failure disposition.");
+    }
+    if (!ts.isCatchClause(owner)) {
+        if (!ts.isExpressionStatement(use.parent))
+            return result("unknown", "The rejection handler's result is used by an enclosing expression or caller; its failure contract needs context.");
+        return result("unexplainedSwallowing", "Empty rejection handler resolves without a value or declared intent; its result is discarded.");
+    }
+    const statement = owner.parent, parent = statement.parent;
+    if (!ts.isBlock(parent) && !ts.isSourceFile(parent))
+        return result("unknown", "Enclosing control flow requires context.");
+    const following = parent.statements.slice(parent.statements.indexOf(statement) + 1);
+    if (guardedFallback(statement, following[0], checker, contracts))
+        return result("fallback", "Failed assignment is followed by an explicit undefined guard and failure outcome.");
+    if (following.length) {
+        const outcome = blockOutcome(following, checker, contracts);
+        if (outcome && outcome.classification !== "unknown")
+            return result("fallback", outcome.reason);
+        return result("unknown", "Continuation after the empty catch needs a failure-contract review.");
+    }
+    if (containsReturn(statement.tryBlock) && contracts.guardedUndefinedResult(body))
+        return result("fallback", "Every selected-source call tests the optional result before using it; no escaping function reference was found.");
+    if (containsReturn(statement.tryBlock))
+        return result("unknown", "Success returns a value; the implicit/undefined failure result may be a caller contract.");
+    if (!ts.isSourceFile(parent) && !ts.isFunctionLike(parent.parent))
+        return result("unknown", "Outer continuation or control flow requires context.");
+    return result("unexplainedSwallowing", "Terminal empty catch discards failure without an explicit result or attached intent.");
+}

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).