codemetrics-ai 0.3.0 → 0.5.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-scoring.d.ts

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

package/dist/error-handling-scoring.js

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

package/dist/error-handling.d.ts

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

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