codemetrics-ai 0.3.0 → 0.4.0

package/dist/decomposition-evidence.js

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import { isFunction } from "./function-nodes.js";
+function ownedShape(root) {
+    // A concise function body has an implicit return, independent of formatting.
+    let statements = ts.isExpression(root) ? 1 : 0, dataLiteralEntries = 0;
+    function visit(node) {
+        if (ts.isExpressionWithTypeArguments(node)) {
+            visit(node.expression);
+            return;
+        }
+        if (isFunction(node) || ts.isTypeNode(node) || ts.isClassDeclaration(node) || ts.isClassExpression(node) ||
+            ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node))
+            return;
+        if (ts.isImportDeclaration(node) || ts.isImportEqualsDeclaration(node) || ts.isExportDeclaration(node))
+            return;
+        if (ts.isVariableStatement(node) && !node.declarationList.declarations.some(declaration => declaration.initializer))
+            return;
+        if (ts.isStatement(node) && !ts.isBlock(node) && !ts.isEmptyStatement(node) && !ts.isLabeledStatement(node))
+            statements++;
+        if (ts.isObjectLiteralExpression(node))
+            dataLiteralEntries += node.properties.length;
+        if (ts.isArrayLiteralExpression(node))
+            dataLiteralEntries += node.elements.filter(element => !ts.isOmittedExpression(element)).length;
+        ts.forEachChild(node, visit);
+    }
+    visit(root);
+    return { ownedStatements: statements, dataLiteralEntries };
+}
+export function decompositionModule(source, file, project, functions) {
+    const byStart = new Map(functions.map(item => [item.sourceSpanStart, item]));
+    const rows = [];
+    function visit(node) {
+        if (isFunction(node) && node.body) {
+            const item = byStart.get(node.getStart(source));
+            if (item)
+                rows.push({ id: item.id, member: item.member, line: item.line, ownedSourceLines: item.ownSourceLines, ...ownedShape(node.body) });
+        }
+        if (!ts.isTypeNode(node) || ts.isExpressionWithTypeArguments(node))
+            ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return { file, project, implementedFunctions: rows.length, sumOwnedFunctionLines: rows.reduce((sum, row) => sum + row.ownedSourceLines, 0),
+        sumOwnedFunctionStatements: rows.reduce((sum, row) => sum + row.ownedStatements, 0),
+        initializer: ownedShape(source), directReExports: source.statements.filter(node => ts.isExportDeclaration(node) && node.moduleSpecifier).length,
+        typeDeclarations: source.statements.filter(node => ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)).length,
+        enums: source.statements.filter(ts.isEnumDeclaration).length, functions: rows };
+}
+export function decompositionEvidence(modules, incomplete) {
+    const ordered = [...modules].sort((a, b) => a.file.localeCompare(b.file, "en") || a.project.localeCompare(b.project, "en"));
+    const functions = ordered.flatMap(module => module.functions.map(row => ({ ...row, file: module.file, project: module.project })));
+    const sizes = functions.map(row => row.ownedSourceLines).sort((a, b) => a - b);
+    const sum = sizes.reduce((total, size) => total + size, 0);
+    const statements = functions.map(row => row.ownedStatements).sort((a, b) => a - b);
+    const statementSum = statements.reduce((total, size) => total + size, 0);
+    return { version: 2, status: incomplete ? "failed" : "unscored", score: null,
+        measurement: "owned-executable-statements-v2", primaryMeasure: "ownedStatements",
+        basis: "Descriptive size evidence; no responsibility inference, threshold, finding or score contribution.",
+        exclusions: ["nested-function-double-counting", "class-and-enum-initializers", "parameter-initializers", "semantic-responsibility"],
+        population: { modules: ordered.length, functions: functions.length, sumOwnedFunctionLines: sum,
+            sumOwnedFunctionStatements: statementSum,
+            medianFunctionStatements: statements.length ? statements[Math.ceil(statements.length * 0.5) - 1] : null,
+            p90FunctionStatements: statements.length ? statements[Math.ceil(statements.length * 0.9) - 1] : null,
+            medianFunctionLines: sizes.length ? sizes[Math.ceil(sizes.length * 0.5) - 1] : null,
+            p90FunctionLines: sizes.length ? sizes[Math.ceil(sizes.length * 0.9) - 1] : null }, modules: ordered,
+        largestFunctions: [...functions].sort((a, b) => b.ownedStatements - a.ownedStatements || a.id.localeCompare(b.id, "en")).slice(0, 10),
+        largestFunctionContainers: ordered.filter(module => module.sumOwnedFunctionStatements > 0)
+            .sort((a, b) => b.sumOwnedFunctionStatements - a.sumOwnedFunctionStatements || a.file.localeCompare(b.file, "en")).slice(0, 10)
+            .map(({ functions: _functions, ...module }) => ({ ...module,
+            shareOfOwnedFunctionStatements: statementSum ? module.sumOwnedFunctionStatements / statementSum : null,
+            shareOfOwnedFunctionLines: sum ? module.sumOwnedFunctionLines / sum : null })) };
+}

package/dist/error-handling.d.ts

@@ -0,0 +1,30 @@
+import ts from "typescript";
+import { type Dimension } from "./evidence.js";
+import { HandlerResolver } from "./handler-resolution.js";
+type UsageKind = "catchClause" | "promiseCatch" | "promiseThenRejection";
+interface Handler {
+    id: string;
+    file: string;
+    project: string;
+    line: number;
+    kind: "catchClause" | "promiseRejection";
+    classification: "unexplainedEmpty" | "documentedEmpty" | "containsCode";
+    comments: string[];
+    uses: {
+        file: string;
+        line: number;
+        kind: UsageKind;
+        resolution: "inline" | "reference";
+    }[];
+}
+export declare function inspectErrorHandling(source: ts.SourceFile, checker: ts.TypeChecker, file: string, project: string, resolver: HandlerResolver): {
+    handlers: Handler[];
+    uninspectedCallbacks: {
+        file: string;
+        line: number;
+        kind: UsageKind;
+        reason: string;
+    }[];
+};
+export declare function errorHandlingEvidence(results: ReturnType<typeof inspectErrorHandling>[], incomplete: boolean): Dimension;
+export {};

package/dist/error-handling.js

@@ -0,0 +1,114 @@
+import ts from "typescript";
+import { hash } from "./evidence.js";
+import { unwrapHandler } from "./handler-resolution.js";
+function undefinedValue(node, checker) {
+    node = unwrapHandler(node);
+    if (ts.isVoidExpression(node))
+        return ts.isNumericLiteral(node.expression);
+    if (!ts.isIdentifier(node) || node.text !== "undefined")
+        return false;
+    const declarations = checker.getSymbolAtLocation(node)?.declarations ?? [];
+    return declarations.length === 0 || declarations.every(declaration => declaration.getSourceFile().hasNoDefaultLib);
+}
+function emptyBody(body, checker) {
+    if (!ts.isBlock(body))
+        return undefinedValue(body, checker);
+    return body.statements.every(statement => ts.isEmptyStatement(statement) ||
+        (ts.isReturnStatement(statement) && (!statement.expression || undefinedValue(statement.expression, checker))));
+}
+function bodyComments(body, source) {
+    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;
+        const text = scanner.getTokenText().replace(/^\/\/?\*?|\*\/$/g, "").trim();
+        if (/[\p{L}\p{N}]/u.test(text))
+            comments.push(text);
+    }
+    return comments;
+}
+function rejectionArgument(call, checker) {
+    const declaration = checker.getResolvedSignature(call)?.declaration;
+    if (!declaration || !ts.isMethodSignature(declaration) || !ts.isIdentifier(declaration.name) ||
+        !ts.isInterfaceDeclaration(declaration.parent) || !["Promise", "PromiseLike"].includes(declaration.parent.name.text))
+        return;
+    const source = declaration.getSourceFile();
+    if (!source.hasNoDefaultLib || !/(?:^|[/\\])lib\.[^/\\]+\.d\.ts$/.test(source.fileName))
+        return;
+    if (declaration.name.text === "catch")
+        return { index: 0, kind: "promiseCatch" };
+    if (declaration.name.text === "then" && call.arguments.length > 1)
+        return { index: 1, kind: "promiseThenRejection" };
+}
+export function inspectErrorHandling(source, checker, file, project, resolver) {
+    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 };
+        if (existing) {
+            existing.uses.push(use);
+            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] });
+    }
+    function visit(node) {
+        if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node))
+            return;
+        if (ts.isCatchClause(node))
+            add(node.block, "catchClause", node, "inline");
+        if (ts.isCallExpression(node)) {
+            const rejection = rejectionArgument(node, checker);
+            if (rejection) {
+                const resolved = resolver.resolve(node.arguments[rejection.index]);
+                if ("body" in resolved)
+                    add(resolved.body, rejection.kind, node, resolved.resolution);
+                else
+                    uninspectedCallbacks.push({ file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+                        kind: rejection.kind, reason: resolved.reason });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    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" } };
+}
+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)
+            existing.uses.push(...row.uses);
+        else
+            unique.set(row.id, { ...row, uses: [...row.uses] });
+    }
+    const handlers = [...unique.values()].sort((a, b) => a.file.localeCompare(b.file, "en") || a.line - b.line);
+    for (const handler of handlers)
+        handler.uses.sort((a, b) => a.file.localeCompare(b.file, "en") || a.line - b.line || a.kind.localeCompare(b.kind, "en"));
+    const uninspectedCallbacks = results.flatMap(result => result.uninspectedCallbacks)
+        .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",
+            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),
+            referencedCallbackUseSites: handlers.reduce((sum, handler) => sum + handler.uses.filter(use => use.resolution === "reference").length, 0),
+            uninspectedRejectionCallbacks: uninspectedCallbacks.length, uninspectedCallbacks, handlers } };
+}

package/dist/function-measurements.d.ts

@@ -0,0 +1,17 @@
+import ts from "typescript";
+import { type FunctionNode } from "./function-nodes.js";
+import { type ComplexityBreakdown } from "./complexity-breakdown.js";
+export interface FunctionMeasurement {
+    id: string;
+    file: string;
+    project: string;
+    member: string;
+    line: number;
+    sourceSpanStart: number;
+    ownComplexity: number;
+    ownSourceLines: number;
+    ownHalsteadVolume: number;
+    ownMaintainabilityIndex: number;
+    complexityBreakdown?: ComplexityBreakdown;
+}
+export declare function measureFunction(node: FunctionNode, source: ts.SourceFile, file: string, project: string, member: string): FunctionMeasurement;

package/dist/function-measurements.js

@@ -0,0 +1,85 @@
+import ts from "typescript";
+import { hash } from "./evidence.js";
+import { isFunction } from "./function-nodes.js";
+import { complexityBreakdown, decisionCategory, emptyDecisionCounts } from "./complexity-breakdown.js";
+function excluded(node) {
+    return isFunction(node) || ts.isTypeNode(node) || ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) || ts.isClassDeclaration(node) || ts.isClassExpression(node) || ts.isEnumDeclaration(node);
+}
+function assertedExpression(node) {
+    if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node) || ts.isExpressionWithTypeArguments(node))
+        return node.expression;
+    return undefined;
+}
+function runtimeChildren(node, source) {
+    const children = node.getChildren(source);
+    const typed = node;
+    const argumentsIndex = typed.typeArguments ? children.findIndex(child => child.kind === ts.SyntaxKind.SyntaxList &&
+        child.pos === typed.typeArguments.pos && child.end === typed.typeArguments.end) : -1;
+    return children.filter((child, index) => {
+        // Delimiters and commas around erased type arguments are not runtime tokens.
+        if (argumentsIndex >= 0 && index >= argumentsIndex - 1 && index <= argumentsIndex + 1)
+            return false;
+        if (typed.type && (child === typed.type || (child.kind === ts.SyntaxKind.ColonToken && children[index + 1] === typed.type)))
+            return false;
+        return child !== typed.exclamationToken;
+    });
+}
+// This scored measurement is deliberately separate from the historical CSV metric.
+export function measureFunction(node, source, file, project, member) {
+    const body = node.body;
+    const decisionCounts = emptyDecisionCounts();
+    const operators = [], operands = [], lines = new Set();
+    function decisions(current) {
+        const expression = assertedExpression(current);
+        if (expression) {
+            decisions(expression);
+            return;
+        }
+        if (excluded(current))
+            return;
+        const category = decisionCategory(current);
+        if (category)
+            decisionCounts[category]++;
+        ts.forEachChild(current, decisions);
+    }
+    function tokens(current) {
+        const expression = assertedExpression(current);
+        if (expression) {
+            tokens(expression);
+            return;
+        }
+        if (excluded(current) || ts.isJsxText(current))
+            return;
+        const children = runtimeChildren(current, source);
+        if (children.length) {
+            children.forEach(tokens);
+            return;
+        }
+        if (current.kind === ts.SyntaxKind.EndOfFileToken || current.getWidth(source) === 0)
+            return;
+        const text = current.getText(source);
+        if (!["{", "}", ";"].includes(text)) {
+            const start = source.getLineAndCharacterOfPosition(current.getStart(source)).line;
+            const end = source.getLineAndCharacterOfPosition(current.end - 1).line;
+            for (let line = start; line <= end; line++)
+                lines.add(line);
+        }
+        if (ts.isIdentifier(current) || ts.isLiteralExpression(current))
+            operands.push(text);
+        else
+            operators.push(text);
+    }
+    decisions(body);
+    const breakdown = complexityBreakdown(decisionCounts);
+    const complexity = breakdown.total;
+    tokens(body);
+    const vocabulary = new Set(operators).size + new Set(operands).size;
+    const volume = vocabulary > 1 ? (operators.length + operands.length) * Math.log2(vocabulary) : 0;
+    const mi = lines.size === 0 ? 100 : Math.min(100, Math.max(0, (171 - 5.2 * Math.log(Math.max(volume, 1)) - 0.23 * complexity - 16.2 * Math.log(Math.max(lines.size, 1))) * 100 / 171));
+    const start = node.getStart(source);
+    return { id: hash(`${file}|${start}|${node.kind}`), file, project, member, sourceSpanStart: start,
+        line: source.getLineAndCharacterOfPosition(start).line + 1, ownComplexity: complexity,
+        ownSourceLines: lines.size, ownHalsteadVolume: volume, ownMaintainabilityIndex: mi, complexityBreakdown: breakdown };
+}

package/dist/function-nodes.d.ts

@@ -0,0 +1,3 @@
+import ts from "typescript";
+export type FunctionNode = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration | ts.ConstructorDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration;
+export declare function isFunction(node: ts.Node): node is FunctionNode;

package/dist/function-nodes.js

@@ -0,0 +1,5 @@
+import ts from "typescript";
+export function isFunction(node) {
+    return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
+}

package/dist/function-scoring.d.ts

@@ -0,0 +1,5 @@
+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]];
+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

@@ -0,0 +1,50 @@
+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]];
+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";
+    const anchors = complexity ? complexityAnchors : maintainabilityAnchors;
+    const measured = (item) => complexity ? item.ownComplexity : item.ownMaintainabilityIndex;
+    const scope = { id: `javascript-typescript/${dimension}/v2`, coverage: "partial",
+        includes: [complexity ? "owned-function-cyclomatic-complexity" : "owned-function-maintainability-index"],
+        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 decision = { version: 1, policy: `javascript-typescript/${dimension}/owned-functions-v2`, operation: "deductions",
+        finalScore: roundScore(total), inputs: { baseline: 10, eligibleFunctions: ordered.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 },
+            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.
+    const byId = new Map(contributions.map(item => [item.id, item.group]));
+    decision.findingEffects = result.findings.map(finding => {
+        const group = byId.get(String(finding.observations.functionId));
+        return { fingerprint: finding.fingerprint, category: finding.category,
+            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) },
+                decomposition: { score: null, status: "unsupported", description: "JS/TS decomposition is not measured by this policy." }
+            } } : {}) };
+}

package/dist/handler-resolution.d.ts

@@ -0,0 +1,26 @@
+import ts from "typescript";
+export declare function unwrapHandler(node: ts.Expression): ts.Expression;
+type Resolution = {
+    body: ts.ConciseBody;
+    resolution: "inline" | "reference";
+} | {
+    reason: string;
+};
+/** Bounded declaration lookup, not a runtime value-flow or mutation proof. */
+export declare class HandlerResolver {
+    private readonly checker;
+    private readonly selected;
+    private readonly written;
+    private readonly identities;
+    constructor(checker: ts.TypeChecker, sources: ts.SourceFile[], root: string, project: string);
+    private recordWrite;
+    identity(body: ts.ConciseBody): {
+        id: string;
+        file: string;
+        project: string;
+        line: number;
+    };
+    resolve(argument: ts.Expression | undefined): Resolution;
+    private resolveReference;
+}
+export {};

package/dist/handler-resolution.js

@@ -0,0 +1,99 @@
+import ts from "typescript";
+import path from "node:path";
+import { hash } from "./evidence.js";
+import { isFunction } from "./function-nodes.js";
+export function unwrapHandler(node) {
+    while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) ||
+        ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node))
+        node = node.expression;
+    return node;
+}
+/** Bounded declaration lookup, not a runtime value-flow or mutation proof. */
+export class HandlerResolver {
+    checker;
+    selected = new Set();
+    written = new Set();
+    identities = new Map();
+    constructor(checker, sources, root, project) {
+        this.checker = checker;
+        for (const source of sources) {
+            this.selected.add(source);
+            const file = path.relative(root, source.fileName).replaceAll("\\", "/");
+            let functions = 0, catches = 0;
+            const visit = (node) => {
+                if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node))
+                    return;
+                const body = isFunction(node) ? node.body : ts.isCatchClause(node) ? node.block : undefined;
+                if (body) {
+                    const key = ts.isCatchClause(node) ? `catch:${catches++}` : `function:${functions++}`;
+                    this.identities.set(body, { id: hash(`${project}|${file}|${key}`), file, project,
+                        line: source.getLineAndCharacterOfPosition(body.getStart(source)).line + 1 });
+                }
+                if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                    node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+                    this.recordWrite(node.left);
+                if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+                    [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator))
+                    this.recordWrite(node.operand);
+                if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) && !ts.isVariableDeclarationList(node.initializer))
+                    this.recordWrite(node.initializer);
+                ts.forEachChild(node, visit);
+            };
+            visit(source);
+        }
+    }
+    recordWrite(node) {
+        if (ts.isIdentifier(node)) {
+            const symbol = this.checker.getSymbolAtLocation(node);
+            if (symbol)
+                this.written.add(symbol);
+        }
+        else if (!ts.isPropertyAccessExpression(node) && !ts.isElementAccessExpression(node)) {
+            // Destructuring and parenthesized assignments are conservatively included.
+            ts.forEachChild(node, child => this.recordWrite(child));
+        }
+    }
+    identity(body) { return this.identities.get(body); }
+    resolve(argument) {
+        if (!argument)
+            return { reason: "missingArgument" };
+        const direct = unwrapHandler(argument);
+        if (isFunction(direct) && direct.body)
+            return { body: direct.body, resolution: "inline" };
+        return this.resolveReference(direct, new Set());
+    }
+    resolveReference(node, seen) {
+        node = unwrapHandler(node);
+        if (!ts.isIdentifier(node))
+            return { reason: "unsupportedExpression" };
+        let symbol = this.checker.getSymbolAtLocation(node);
+        if (!symbol)
+            return { reason: "unresolvedSymbol" };
+        if (this.written.has(symbol))
+            return { reason: "reassignedBinding" };
+        if (symbol.flags & ts.SymbolFlags.Alias)
+            symbol = this.checker.getAliasedSymbol(symbol);
+        if (this.written.has(symbol))
+            return { reason: "reassignedBinding" };
+        if (seen.has(symbol) || seen.size >= 32)
+            return { reason: "aliasCycleOrDepth" };
+        seen.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (!declarations.length || declarations.some(declaration => !this.selected.has(declaration.getSourceFile())))
+            return { reason: "outsideSelectedSource" };
+        const implementations = declarations.filter(declaration => ts.isFunctionDeclaration(declaration) && declaration.body);
+        if (implementations.length === 1)
+            return { body: implementations[0].body, resolution: "reference" };
+        if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]))
+            return { reason: "unsupportedDeclaration" };
+        const declaration = declarations[0];
+        if (!ts.isVariableDeclarationList(declaration.parent) || !(declaration.parent.flags & ts.NodeFlags.Const))
+            return { reason: "mutableBinding" };
+        if (!declaration.initializer)
+            return { reason: "missingInitializer" };
+        const value = unwrapHandler(declaration.initializer);
+        if (isFunction(value) && value.body)
+            return { body: value.body, resolution: "reference" };
+        return this.resolveReference(value, seen);
+    }
+}

package/dist/metrics.d.ts

@@ -1,5 +1,6 @@
 import ts from "typescript";
 import { type Finding } from "./evidence.js";
+import { type FunctionMeasurement } from "./function-measurements.js";
 export interface Metric {
     project: string;
     file: string;
@@ -18,9 +19,11 @@ export interface Metric {
 export declare function maintainability(volume: number, complexity: number, lines: number): number;
 export declare function analyzeFile(source: ts.SourceFile, checker: ts.TypeChecker, project: string, root: string): {
     metrics: Metric[];
+    functions: FunctionMeasurement[];
     findings: {
         dimension: "codeQuality" | "performanceAsync";
         finding: Finding;
     }[];
     reactSupported: boolean;
+    asyncSupported: boolean;
 };