codemetrics-ai 0.4.0 → 0.5.0

package/README.md

@@ -1,10 +1,14 @@
 # codemetrics-ai
 
-Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.4.0 implements source metrics and React hook/effect checks and emits schema-v3 evidence, including executed scoring decisions. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
+Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.5.0 implements source metrics and React hook/effect checks and emits schema-v3 evidence, including executed scoring decisions. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
 
 Each scored dimension includes `scoringDecision`: policy inputs, executed steps, rounding and finding attribution. These are aggregate policy decisions, not independent finding deductions. See [the decision contract](../../shared/scorecard-schema/scoring-decisions.md).
 
-The 0.4.0 ruleset `javascript-typescript-2026-10-04-local-handlers` replaces the published 0.3.0 maximum-CC/median-MI ladders with owned-function population scores and extends React-only checks with bounded promise-usage analysis. It also corrects erased TypeScript syntax in owned-body measurements, scores async usage by affected eligible owners, and adds unscored module dependency, decomposition, and error-handler evidence. Generate new baselines when upgrading from 0.3.0. See the [0.4.0 release and migration notes](https://github.com/sean-m-cooper/CodeMetrics.AI/blob/master/docs/releases/javascript-typescript-0.4.0.md).
+Version 0.5.0 uses `javascript-typescript-2026-10-09-handler-contracts` and adds
+contextual Error Handling scoring. Adopting it requires a fresh baseline. See the
+[0.5.0 release notes](../../docs/releases/javascript-typescript-0.5.0.md).
+
+The earlier 0.4.0 ruleset `javascript-typescript-2026-10-04-local-handlers` replaces the published 0.3.0 maximum-CC/median-MI ladders with owned-function population scores and extends React-only checks with bounded promise-usage analysis. It also corrects erased TypeScript syntax in owned-body measurements, scores async usage by affected eligible owners, and adds unscored module dependency, decomposition, and error-handler evidence. Generate new baselines when upgrading from 0.3.0. See the [0.4.0 release and migration notes](https://github.com/sean-m-cooper/CodeMetrics.AI/blob/master/docs/releases/javascript-typescript-0.4.0.md).
 
 ```sh
 npx codemetrics-ai --project package.json
@@ -22,7 +26,7 @@ Default output paths are `.scorecard/javascript-typescript/metrics.csv` and `.sc
 | maintainability | 40% mean weakest ceil(N/5) function scores + 60% mean remaining |
 | performanceAsync (Async/Blocking Usage) | React hook/effect checks, standard Promise async executors, and informational async Array.forEach callbacks |
 | architecture | Module dependencies, explicit type-only separation, internal cycle groups and fan-in/out rankings; score remains unmeasured |
-| errorHandling | Catch clauses and inline/referenced standard Promise rejection handlers; unique bodies, linked uses, and documented intent; no score |
+| errorHandling | Contextual failure dispositions for distinct catch/Promise handler bodies; scores unexplained swallowing only with a fully assessed population |
 | Other dimensions | Explicitly skipped |
 
 React checks run only when a source file imports React. Aliased named imports and namespace imports are recognized; local functions shadowing imports are excluded. Missing dependency arrays are advisory because running after every render can be intentional. The implementation does not claim exhaustive Rules of Hooks, dependency-array correctness, or general concurrency analysis. Source syntax errors make the run incomplete and source dimensions unscored. Semantic type errors are outside this AST-focused version's completeness check.
@@ -44,7 +48,9 @@ This is bounded source analysis, not promise-flow verification. Referenced execu
 
 `codeQuality.componentDetails.decomposition` version 2 uses owned executable statements as its primary measure. It ranks functions/modules by statements and reports statement totals, median/p90, and module concentration. Lines and initializer/literal/declaration/re-export observations remain context. Nested bodies are counted separately. Size is not responsibility: data tables, barrels, and orchestration roles receive no inferred defect or deduction. Code Quality remains a method-complexity score.
 
-`errorHandling.handlerEvidence` distinguishes unexplained empty syntax, documented empty bodies, and bodies containing code. Body comments acknowledge developer intent without judging the business rationale. Empty bodies produce informational review leads only; fallback behavior outside the handler may explain them. Referenced Promise callbacks resolve through function declarations, const aliases, and imports within selected source. Shared implementations count once, with call sites attached. Reassigned, mutable, unsupported, and out-of-scope references retain reasoned inspection gaps. No handlers means an unavailable percentage, not a perfect score. See the [evidence contract](../../shared/scorecard-schema/javascript-typescript-context-evidence.md).
+`errorHandling.handlerEvidence` preserves empty/documented/nonempty syntax measurements and links each distinct implementation to its uses. Referenced Promise callbacks resolve through function declarations, const aliases, and imports within selected source. The new `dispositionEvidence` separates explicit outcomes, recognized fallback, documented intent, unexplained swallowing, and unknown paths. Nonempty code alone does not establish handling. Attached intent is honored without judging the business rationale.
+
+When every observed body is assessed and no callback uses are unresolved, Error Handling scores `10 - 10 * unexplainedSwallowing / assessedHandlers`, capped at 9 if any issue exists, rounded half up to one decimal. Shared bodies count once. Unknown dispositions, unresolved callbacks, and absent populations yield no score. Scores describe bounded handling signals, not proven recovery or bugs. See the [policy and recognition limits](../../shared/scorecard-schema/javascript-typescript-error-handling-policy.md).
 
 ## Module architecture evidence
 
@@ -120,7 +126,7 @@ evidence. Overall dependencies and cycle findings remain intact, including mixed
 files and cycles crossing the views. Architecture is still unscored. See the
 [dependency view contract](../../shared/scorecard-schema/javascript-typescript-module-graph.md#implementation-reference-and-public-re-export-views).
 
-`metrics.ts` owns source traversal, raw member metrics and finding identities. `function-measurements.ts` collects the separate owned-body measurements; `function-scoring.ts` applies the two population policies with exact interpolation/rounding from `score-arithmetic.ts`. `react-probe.ts` checks calls owned by each function for React hook/effect observations. `async-probe.ts` checks each visited node once for bounded standard-library promise patterns, including module-level operations. Neither probe traverses nested bodies or calculates metrics. `async-population.ts` assigns distinct eligible owners; `async-scoring.ts` applies the population ladder. `decomposition-evidence.ts` records function size and module distribution without deductions. `handler-resolution.ts` performs bounded declaration lookup; `error-handling.ts` records distinct handler bodies, use sites, and body comments without a score. Regression fixtures preserve raw metrics, source locations and existing finding fingerprints; advisory severity/disposition changes are intentional.
+`metrics.ts` owns source traversal, raw member metrics and finding identities. `function-measurements.ts` collects the separate owned-body measurements; `function-scoring.ts` applies the two population policies with exact interpolation/rounding from `score-arithmetic.ts`. `react-probe.ts` checks calls owned by each function for React hook/effect observations. `async-probe.ts` checks each visited node once for bounded standard-library promise patterns, including module-level operations. Neither probe traverses nested bodies or calculates metrics. `async-population.ts` assigns distinct eligible owners; `async-scoring.ts` applies the population ladder. `decomposition-evidence.ts` records function size and module distribution without deductions. `handler-resolution.ts` performs bounded declaration lookup; `handler-disposition.ts` classifies bounded failure paths; `failure-contracts.ts` resolves local logging, callback, and guarded-result contracts; `error-handling.ts` aggregates bodies, uses, context, and findings; `error-handling-scoring.ts` applies the population formula. Regression fixtures preserve raw metrics and source identities; the handler policy and ruleset change is intentional.
 
 ```sh
 npm ci
@@ -160,3 +166,13 @@ records results and limitations. Executable statements are the accepted primary
 and weights remain experimental; Code Quality continues to score method complexity
 only. The [statement calibration report](../../shared/scorecard-schema/calibration-runs/javascript-typescript-statements-2026-10-04.md)
 records the updated preview and counting contract.
+
+The [completed context calibration](../../shared/scorecard-schema/javascript-typescript-context-policy-decision.md)
+retained decomposition and error handling as unscored evidence at that stage. Across 4,062 functions,
+the large-statement candidates overlapped existing CC/MI review groups; source review
+also found explicit fallback and declared-intent counterexamples to body-only handler
+deductions. The released workflow was verified on all six selections and a compatible
+Uptime Kuma rerun. Numerical experiments remain outside the analyzer and are not
+consumer scoring policies. The subsequent [contextual handler policy](../../shared/scorecard-schema/javascript-typescript-error-handling-policy.md)
+enables the agreed population formula only where bounded classification establishes
+an assessable population. Decomposition remains unscored.

package/dist/analyzer.js

@@ -11,6 +11,7 @@ import { asyncPopulation } from "./async-population.js";
 import { decompositionModule, decompositionEvidence } from "./decomposition-evidence.js";
 import { HandlerResolver } from "./handler-resolution.js";
 import { inspectErrorHandling, errorHandlingEvidence } from "./error-handling.js";
+import { FailureContracts } from "./failure-contracts.js";
 export function analyze(options, version) {
     const identity = invocationIds(options.runId, options.auditId);
     const discovery = discover(options.project, options.tsconfig);
@@ -30,6 +31,7 @@ export function analyze(options, version) {
         const handlerSources = pkg.files.map(filename => program.getSourceFile(filename))
             .filter((source) => !!source && !program.getSyntacticDiagnostics(source).length);
         const handlerResolver = new HandlerResolver(checker, handlerSources, discovery.repositoryRoot, pkg.name);
+        const failureContracts = new FailureContracts(checker, program.getSourceFiles(), handlerSources, discovery.repositoryRoot);
         const collectModules = moduleGraph.forPackage(pkg, program);
         for (const filename of pkg.files) {
             const source = program.getSourceFile(filename);
@@ -48,7 +50,7 @@ export function analyze(options, version) {
             const file = path.relative(discovery.repositoryRoot, filename).replaceAll("\\", "/");
             asyncOwners.push(...asyncPopulation(source, checker, file, pkg.name, result.functions, result.findings.filter(item => item.dimension === "performanceAsync").map(item => item.finding)));
             decompositionModules.push(decompositionModule(source, file, pkg.name, result.functions));
-            errorHandling.push(inspectErrorHandling(source, checker, file, pkg.name, handlerResolver));
+            errorHandling.push(inspectErrorHandling(source, checker, file, pkg.name, handlerResolver, failureContracts));
             metrics.push(...result.metrics);
             collected.push(...result.findings);
             functions.push(...result.functions);
@@ -75,7 +77,7 @@ export function analyze(options, version) {
         filters: { totalUnits: discovery.packages.reduce((sum, pkg) => sum + pkg.files.length, 0) + discovery.skipped.length,
             analyzedUnits: analyzedFiles, skipped: discovery.skipped },
         population: { types: new Set(metrics.map(metric => `${metric.project}|${metric.file}|${metric.type}`)).size, members: metrics.length },
-        dimensions, analysis: { ...identity, status: diagnostics.length ? "incomplete" : "complete", ruleset: "javascript-typescript-2026-10-04-local-handlers",
+        dimensions, analysis: { ...identity, status: diagnostics.length ? "incomplete" : "complete", ruleset: "javascript-typescript-2026-10-09-handler-contracts",
             calibration: "uncalibrated", configurationFingerprint: hash(JSON.stringify(canonicalConfiguration(discovery.packages.map(pkg => ({ name: pkg.name,
                 options: pkg.options, selection: pkg.selection })), discovery.repositoryRoot))), diagnostics, suppressions: [] }
     };

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

@@ -1,6 +1,8 @@
 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;
@@ -10,6 +12,7 @@ interface Handler {
     kind: "catchClause" | "promiseRejection";
     classification: "unexplainedEmpty" | "documentedEmpty" | "containsCode";
     comments: string[];
+    disposition: HandlerDisposition;
     uses: {
         file: string;
         line: number;
@@ -17,7 +20,7 @@ interface Handler {
         resolution: "inline" | "reference";
     }[];
 }
-export declare function inspectErrorHandling(source: ts.SourceFile, checker: ts.TypeChecker, file: string, project: string, resolver: HandlerResolver): {
+export declare function inspectErrorHandling(source: ts.SourceFile, checker: ts.TypeChecker, file: string, project: string, resolver: HandlerResolver, contracts: FailureContracts): {
     handlers: Handler[];
     uninspectedCallbacks: {
         file: string;

package/dist/error-handling.js

@@ -1,6 +1,8 @@
 import ts from "typescript";
-import { hash } from "./evidence.js";
+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))
@@ -17,11 +19,22 @@ function emptyBody(body, checker) {
         (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);
@@ -41,20 +54,24 @@ function rejectionArgument(call, checker) {
     if (declaration.name.text === "then" && call.arguments.length > 1)
         return { index: 1, kind: "promiseThenRejection" };
 }
-export function inspectErrorHandling(source, checker, file, project, resolver) {
+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 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] });
+        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))
@@ -77,19 +94,25 @@ export function inspectErrorHandling(source, checker, file, project, resolver) {
     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" } };
+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)
+        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] });
     }
@@ -100,12 +123,22 @@ export function errorHandlingEvidence(results, incomplete) {
         .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",
+    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),

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemetrics-ai",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Deterministic code metrics and scorecard evidence for JavaScript, TypeScript, and React projects",
   "license": "MIT",
   "type": "module",