codemetrics-ai 0.3.0 → 0.5.0

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-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/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;
 };

package/dist/metrics.js

@@ -1,10 +1,10 @@
 import path from "node:path";
 import ts from "typescript";
 import { hash } from "./evidence.js";
-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);
-}
+import { isFunction } from "./function-nodes.js";
+import { inspectReactCall } from "./react-probe.js";
+import { inspectAsyncNode, isAsyncFunction, isPromiseConstruction } from "./async-probe.js";
+import { measureFunction } from "./function-measurements.js";
 function nameOf(node, source) {
     if (node.name)
         return node.name.getText(source);
@@ -28,19 +28,24 @@ export function maintainability(volume, complexity, lines) {
 export function analyzeFile(source, checker, project, root) {
     const file = path.relative(root, source.fileName).replaceAll("\\", "/");
     const metrics = [];
+    const functions = [];
     const findings = [];
     const importCount = new Set(source.statements.filter(ts.isImportDeclaration).map(node => node.moduleSpecifier.getText(source))).size;
     const identities = new Map();
-    function emit(category, dimension, node, member, message, observations, confidence = "high") {
+    let asyncSupported = false;
+    function emit(category, dimension, node, member, message, observations, confidence = "high", severity = "warning") {
         const ruleId = `javascript-typescript/${dimension}/${category}`;
         const identity = `${ruleId}|${file}|${project}|${member}`;
         const occurrence = identities.get(identity) ?? 0;
         identities.set(identity, occurrence + 1);
         findings.push({ dimension, finding: { category, ruleId, fingerprint: hash(`${identity}|${occurrence}`),
-                severity: "warning", confidence, file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+                severity, confidence, file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
                 project, member, message, observations } });
     }
     function visit(node, parentName = "") {
+        asyncSupported ||= isAsyncFunction(node) || ts.isAwaitExpression(node) || isPromiseConstruction(node, checker);
+        for (const finding of inspectAsyncNode(node, checker))
+            emit(finding.category, "performanceAsync", node, parentName || "<module>", finding.message, { ...finding.observations, sourceSpanStart: node.getStart(source), sourceSpanLength: node.getWidth(source) }, finding.confidence, finding.severity);
         if (isFunction(node) && node.body) {
             const name = nameOf(node, source);
             const member = parentName ? `${parentName}/${name}` : name;
@@ -57,41 +62,9 @@ export function analyzeFile(source, checker, project, root) {
                 if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child))
                     hasJsx = true;
                 if (ts.isCallExpression(child)) {
-                    const symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(child.expression) ? child.expression.name : child.expression);
-                    const declarations = symbol?.declarations ?? [];
-                    const reactHook = declarations.some(declaration => {
-                        let cursor = declaration;
-                        while (cursor && !ts.isImportDeclaration(cursor))
-                            cursor = cursor.parent;
-                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
-                    });
-                    const hookName = declarations.find(ts.isImportSpecifier);
-                    const calledName = hookName ? (hookName.propertyName ?? hookName.name).text : ts.isPropertyAccessExpression(child.expression) ? child.expression.name.text : "";
-                    const namespaceSymbol = ts.isPropertyAccessExpression(child.expression) ? checker.getSymbolAtLocation(child.expression.expression) : undefined;
-                    const reactNamespace = namespaceSymbol?.declarations?.some(declaration => {
-                        let cursor = declaration;
-                        while (cursor && !ts.isImportDeclaration(cursor))
-                            cursor = cursor.parent;
-                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
-                    });
-                    if ((reactHook || reactNamespace) && /^use[A-Z]/.test(calledName)) {
-                        let ancestor = child.parent;
-                        while (ancestor && ancestor !== node.body) {
-                            if (ts.isIfStatement(ancestor) || ts.isConditionalExpression(ancestor) || ts.isForStatement(ancestor) || ts.isForOfStatement(ancestor) || ts.isForInStatement(ancestor) || ts.isWhileStatement(ancestor) || ts.isDoStatement(ancestor) ||
-                                ts.isBinaryExpression(ancestor) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(ancestor.operatorToken.kind)) {
-                                emit("conditionalHook", "performanceAsync", child, member, `${calledName} is called within a conditional or loop.`, { hook: calledName });
-                                break;
-                            }
-                            ancestor = ancestor.parent;
-                        }
-                        if (["useEffect", "useLayoutEffect"].includes(calledName)) {
-                            const callback = child.arguments[0];
-                            if (callback && isFunction(callback) && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword))
-                                emit("asyncEffectCallback", "performanceAsync", child, member, "An effect callback is async and returns a Promise instead of cleanup or undefined.", { hook: calledName });
-                            if (child.arguments.length < 2)
-                                emit("effectWithoutDependencies", "performanceAsync", child, member, "Effect runs after every render; verify that this is intentional.", { hook: calledName }, "low");
-                        }
-                    }
+                    for (const finding of inspectReactCall(child, node.body, checker))
+                        emit(finding.category, "performanceAsync", child, member, finding.message, { ...finding.observations, sourceSpanStart: child.getStart(source), classification: finding.confidence === "low" ? "reviewLead" : "actionableSignal",
+                            scoreDisposition: finding.confidence === "low" ? "excludedReviewLead" : "scored" }, finding.confidence, finding.confidence === "low" ? "info" : "warning");
                 }
             });
             if (!ts.isBlock(node.body))
@@ -138,16 +111,21 @@ export function analyzeFile(source, checker, project, root) {
                 complexity, sourceLines: Math.max(1, sourceLineSet.size), executableLines, halsteadVolume: volume,
                 maintainabilityIndex: maintainability(volume, complexity, Math.max(1, sourceLineSet.size)), coupling: importCount, inheritance };
             metrics.push(metric);
-            if (complexity > 10)
-                emit("highFunctionComplexity", "codeQuality", node, member, `${member} has cyclomatic complexity ${complexity} (threshold: 10).`, { measured: complexity, threshold: 10, metric: "cyclomaticComplexity", kind });
+            const measurement = measureFunction(node, source, file, project, member);
+            functions.push(measurement);
+            if (measurement.ownComplexity > 10)
+                emit("highFunctionComplexity", "codeQuality", node, member, `${member} has cyclomatic complexity ${measurement.ownComplexity} (threshold: 10).`, { measured: measurement.ownComplexity, threshold: 10, metric: "ownedCyclomaticComplexity", kind, functionId: measurement.id,
+                    complexityBreakdown: measurement.complexityBreakdown });
             ts.forEachChild(node, child => visit(child, member));
             return;
         }
-        if (!ts.isTypeNode(node))
+        // An instantiation expression (factory<T>) is classified as a TypeNode by
+        // TypeScript, but its expression can contain real functions and operations.
+        if (!ts.isTypeNode(node) || ts.isExpressionWithTypeArguments(node))
             ts.forEachChild(node, child => visit(child, parentName));
     }
     visit(source);
     const reactSupported = source.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly &&
         ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react");
-    return { metrics, findings, reactSupported };
+    return { metrics, functions, findings, reactSupported, asyncSupported };
 }

package/dist/module-forwarding.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import type { ModuleReference } from "./module-references.js";
+export type DependencyRole = "implementation" | "reExport";
+export declare function dependencyRoles(source: ts.SourceFile, checker: ts.TypeChecker, references: ModuleReference[]): Map<ts.Node, DependencyRole[]>;