@stateward/plugin-errors 0.0.0-stage → 1.0.1-rc.1

package/dist/finally-may-throw.js

@@ -0,0 +1,184 @@
+import ts from "@stateward/core/typescript";
+import { defineRule, option } from "@stateward/core";
+import { hasModifier, isBuiltinGlobal, sameFileFunction, scanRunning, stripParentheses, throwsUncaught, } from "./syntax.js";
+import { HEADLINE_MAX, fitted, oneLine, withExample } from "./text.js";
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export const GROUP = "finally";
+const EXPLAIN = `# errors/finally-may-throw
+
+A finally block does not call something that throws, so the error that led to it is not lost.
+
+## Why
+
+When code in a \`finally\` throws, its error replaces the one that sent the code there. An upload that fails with a network error then reports a \`SyntaxError\` from parsing the saved state: the real cause, with its message and stack, is gone, and the rest of the cleanup does not run.
+
+## When to use it
+
+Use it in any code that cleans up in \`finally\`. It is on as an error in every preset; keep it on. Turn it off only if your cleanup's own errors are meant to win.
+
+## What it catches
+
+In a \`finally\` block, outside a nested \`try\` that has a \`catch\`:
+
+- a call to a built-in that throws: \`JSON.parse\`, \`JSON.stringify\` (on circular values), \`new URL\`, \`decodeURIComponent\`, \`decodeURI\`, \`structuredClone\`, \`atob\`;
+- a \`throw\`;
+- a call to a function in the same file that has a \`throw\` outside its own \`try\` / \`catch\` (an \`async\` one when the call is awaited).
+
+One finding per \`finally\`, on the first of these.
+
+### Bad
+
+\`\`\`ts
+try {
+  await upload(file);
+} finally {
+  const state = JSON.parse(saved);
+  restore(state);
+}
+\`\`\`
+
+### Good
+
+\`\`\`ts
+try {
+  await upload(file);
+} finally {
+  try {
+    restore(JSON.parse(saved));
+  } catch (e) {
+    report(e);
+  }
+}
+\`\`\`
+
+### Fix
+
+Move the call out of the \`finally\`, or wrap it in its own \`try\` / \`catch\`. There is no quick fix: what the cleanup should do when it fails is your call.
+
+## What it does not catch
+
+- Functions from other files, and package calls: only the built-ins above and functions in the same file are read.
+- Other built-ins, such as \`fetch\` or \`BigInt\`.
+- A function that throws only inside its own \`try\` / \`catch\`.
+- Anything inside a nested \`try\` that has a \`catch\`.
+- A second throwing call in the same \`finally\`: only the first is reported.
+
+## Turn it on or off
+
+In \`stateward.config.ts\`:
+
+\`\`\`ts
+rules: { "errors/finally-may-throw": "off" } // or "warning"
+groups: { "errors/finally": "off" } // the whole group
+rules: { "errors/finally-may-throw": ["error", { severities: { builtin: "warning" } }] } // built-ins only warn
+\`\`\`
+`;
+/** Built-in functions that throw on input they cannot handle, as `Owner.name` or `name`. */
+const THROWING_CALLS = new Set([
+    "JSON.parse",
+    "JSON.stringify",
+    "decodeURIComponent",
+    "decodeURI",
+    "structuredClone",
+    "atob",
+]);
+/** Built-in constructors that throw. */
+const THROWING_CONSTRUCTORS = new Set(["URL"]);
+/** `JSON.parse` or `atob`, when the callee is one of the globals in the table. */
+function builtinCall(call, ctx) {
+    const callee = stripParentheses(call.expression);
+    if (ts.isIdentifier(callee)) {
+        return THROWING_CALLS.has(callee.text) && isBuiltinGlobal(callee, ctx)
+            ? callee.text
+            : undefined;
+    }
+    if (!ts.isPropertyAccessExpression(callee))
+        return undefined;
+    const owner = stripParentheses(callee.expression);
+    if (!ts.isIdentifier(owner))
+        return undefined;
+    const name = `${owner.text}.${callee.name.text}`;
+    return THROWING_CALLS.has(name) && isBuiltinGlobal(owner, ctx) ? name : undefined;
+}
+/** The kinds of finding: they differ in how sure the rule is that the call throws. */
+const KINDS = {
+    throw: "a `throw` written in the finally: it throws whenever it runs.",
+    builtin: "a built-in such as `JSON.parse` or `new URL`: it throws only on input it cannot handle.",
+    "own-function": "a function in the same file with a `throw` in it: it throws on some paths.",
+};
+function causeOf(node, awaited, ctx) {
+    if (ts.isThrowStatement(node))
+        return { node, subject: () => "this `throw` runs", kind: "throw" };
+    if (ts.isNewExpression(node)) {
+        const callee = stripParentheses(node.expression);
+        if (ts.isIdentifier(callee) &&
+            THROWING_CONSTRUCTORS.has(callee.text) &&
+            isBuiltinGlobal(callee, ctx)) {
+            return { node, subject: () => `\`new ${callee.text}(…)\` throws here`, kind: "builtin" };
+        }
+        return undefined;
+    }
+    if (!ts.isCallExpression(node))
+        return undefined;
+    const builtin = builtinCall(node, ctx);
+    if (builtin !== undefined) {
+        return { node, subject: () => `\`${builtin}(…)\` throws here`, kind: "builtin" };
+    }
+    const declared = sameFileFunction(node.expression, ctx);
+    if (declared === undefined || !throwsUncaught(declared))
+        return undefined;
+    // An async function turns its throw into a rejected promise, which only an `await` rethrows.
+    if (hasModifier(declared, ts.SyntaxKind.AsyncKeyword) && !awaited)
+        return undefined;
+    const callee = oneLine(stripParentheses(node.expression).getText(ctx.sourceFile));
+    return { node, subject: (cut) => `\`${cut(callee)}(…)\` throws here`, kind: "own-function" };
+}
+function headline(cause) {
+    return fitted(HEADLINE_MAX, (cut) => `if ${cause.subject(cut)}, the error that led to this finally is lost`);
+}
+const HINT = withExample("move it out of finally, or catch it inside:", [
+    "finally {",
+    "  try { cleanup(); } catch (e) { report(e); }",
+    "}",
+]);
+/** `shown` holds what is already reported: a `finally` inside a `finally` is looked at twice. */
+function checkFinally(block, shown, ctx) {
+    let found;
+    scanRunning(block, (node, guarded) => {
+        if (found !== undefined || guarded)
+            return;
+        const awaited = ts.isAwaitExpression(node.parent);
+        found = causeOf(node, awaited, ctx);
+    });
+    if (found === undefined || shown.has(found.node))
+        return;
+    shown.add(found.node);
+    ctx.report({ node: found.node, message: headline(found), hint: HINT, findingKind: found.kind });
+}
+export const finallyMayThrow = defineRule({
+    kind: "file",
+    meta: {
+        description: "A finally block does not call something that throws, so the error that led to it is not lost.",
+        defaultSeverity: "error",
+        tier: "core",
+        group: GROUP,
+        options: {
+            severities: option.severities({
+                kinds: KINDS,
+                description: "A severity per kind of call, where you trust one kind less.",
+            }),
+        },
+        explain: EXPLAIN,
+    },
+    check(ctx) {
+        const shown = new Set();
+        const visit = (node) => {
+            if (ts.isTryStatement(node) && node.finallyBlock !== undefined) {
+                checkFinally(node.finallyBlock, shown, ctx);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(ctx.sourceFile);
+    },
+});
+//# sourceMappingURL=finally-may-throw.js.map

package/dist/hover.d.ts

@@ -0,0 +1,11 @@
+import type { EditorContributions } from "@stateward/core";
+type Hover = NonNullable<EditorContributions["hover"]>;
+/**
+ * `throws: ParseError | unknown (via api.get: no declaration)` on a function's name and on a
+ * call of it, from the last full check's solve (no recomputation: the solve is kept per
+ * summaries map). Nothing when the pack's inference rules did not run, or for a function that is
+ * not the project's own. On an error boundary's tag, what it catches (`boundaryLines`).
+ */
+export declare const hover: Hover;
+export {};
+//# sourceMappingURL=hover.d.ts.map

package/dist/hover.js

@@ -0,0 +1,62 @@
+import ts from "@stateward/core/typescript";
+import { FACT_RULES } from "./inference/deps.js";
+import { resultLines } from "./inference/format.js";
+import { analyse } from "./inference/solve.js";
+import { TREE_RULES, boundaryLines, modelOf, throwsOf } from "./react/boundaries.js";
+/** The identifier that covers `offset`, if any. */
+function identifierAt(root, offset) {
+    if (offset < root.getStart() || offset >= root.getEnd())
+        return undefined;
+    if (ts.isIdentifier(root))
+        return root;
+    return ts.forEachChild(root, (child) => identifierAt(child, offset));
+}
+/** The name of a function's declaration, or the name a call or `new` calls. */
+function isFunctionName(identifier) {
+    const parent = identifier.parent;
+    if (ts.isFunctionDeclaration(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isVariableDeclaration(parent) ||
+        ts.isPropertyAssignment(parent) ||
+        ts.isPropertyDeclaration(parent)) {
+        return parent.name === identifier;
+    }
+    const callee = ts.isPropertyAccessExpression(parent) && parent.name === identifier ? parent : identifier;
+    const owner = callee.parent;
+    return (ts.isCallExpression(owner) || ts.isNewExpression(owner)) && owner.expression === callee;
+}
+/**
+ * `throws: ParseError | unknown (via api.get: no declaration)` on a function's name and on a
+ * call of it, from the last full check's solve (no recomputation: the solve is kept per
+ * summaries map). Nothing when the pack's inference rules did not run, or for a function that is
+ * not the project's own. On an error boundary's tag, what it catches (`boundaryLines`).
+ */
+export const hover = (input) => {
+    let trees;
+    for (const ruleId of TREE_RULES)
+        trees ??= input.projectSummaries(ruleId);
+    if (trees !== undefined) {
+        const lines = boundaryLines(modelOf(trees), input.sourceFile.fileName, input.offset);
+        if (lines !== undefined)
+            return lines.join("\n\n");
+    }
+    let summaries;
+    for (const ruleId of FACT_RULES)
+        summaries ??= input.projectSummaries(ruleId);
+    summaries ??= trees === undefined ? undefined : throwsOf(trees);
+    if (summaries === undefined)
+        return undefined;
+    const identifier = identifierAt(input.sourceFile, input.offset);
+    if (identifier === undefined || !isFunctionName(identifier))
+        return undefined;
+    const symbol = input.types.symbolAt(identifier);
+    if (symbol === undefined)
+        return undefined;
+    const analysis = analyse(summaries);
+    const result = analysis.results.get(symbol.id);
+    if (result === undefined)
+        return undefined;
+    // A blank line between them: Markdown joins single-newline lines into one paragraph.
+    return resultLines(result, analysis.classes).join("\n\n");
+};
+//# sourceMappingURL=hover.js.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { errors } from "./plugin.js";
+export type { ThrowsSummary } from "./inference/summary.js";
+export type { ReactSummary } from "./react/boundaries.js";
+export type { TreeSummary } from "./react/tree.js";
+export type { MustHandleSummary } from "./must-handle-error.js";
+export type { NarrowTrySummary } from "./narrow-try.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { errors } from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/inference/builtins.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the language's own functions throw. Anything of the
+ * platform (TypeScript's lib files, global declarations) that is not listed here is taken not to
+ * throw: errors of the engine itself (reading a property of `undefined`, a stack overflow) are not
+ * modelled, as Java does not declare its unchecked exceptions.
+ */
+/** The error classes of the platform; their ids are `builtin:<Name>`. */
+export declare const BUILTIN_ERRORS: ReadonlySet<string>;
+export declare function builtinId(name: string): string;
+/** A `DOMException` with one `name` (`AbortError`): caught by `instanceof DOMException`. */
+export declare function domExceptionId(name: string): string;
+export declare function isBuiltin(id: string): boolean;
+/**
+ * The class a built-in error class extends: `Error` for every other one, `DOMException` for a
+ * named `DOMException`; null for `Error`.
+ */
+export declare function builtinParent(id: string): string | null;
+/** How a class is shown: `TypeError`, `AbortError (DOMException)`. */
+export declare function builtinName(id: string): string;
+/** The class an `instanceof` test names to catch it: `DOMException` for `AbortError (DOMException)`. */
+export declare function builtinCatchName(id: string): string;
+/** Methods of the platform's interfaces, as `<interface>.<method>`, that throw synchronously. */
+export declare const THROWING_MEMBERS: ReadonlyMap<string, readonly string[]>;
+/** Global functions that throw synchronously. */
+export declare const THROWING_GLOBALS: ReadonlyMap<string, readonly string[]>;
+/** Global constructors that throw. */
+export declare const THROWING_CONSTRUCTORS: ReadonlyMap<string, readonly string[]>;
+/** `Array(n)` and `new Array(n)` with one argument: a length that is not a valid one. */
+export declare const ARRAY_LENGTH: string[];
+/** What `fetch` rejects with: a network failure, and an abort when a signal is passed. */
+export declare const FETCH_REJECTS: string[];
+export declare const FETCH_ABORT: string;
+/** What `Promise.any` rejects with when every promise rejects. */
+export declare const ANY_REJECTS: string;
+/**
+ * Methods and functions of the platform that call a callback before they return, as
+ * `<interface>.<method>` (or the global's name), with the index of the argument that is the
+ * callback: what it throws, the call throws. `replace`'s second argument and `JSON.stringify`'s
+ * replacer may also be a string or a list; only a function there is a callback.
+ */
+export declare const SYNC_CALLBACKS: ReadonlyMap<string, number>;
+/** Calls whose result holds what the callback returned (promises, for `Promise.all`). */
+export declare const MAPPING_METHODS: ReadonlySet<string>;
+/**
+ * Functions and constructors of the platform, by name, that run their callback later (a timer, an
+ * event, an observer) or never (`removeEventListener`): what the callback throws never reaches
+ * the caller, so it is left out on purpose. Its own catches are still checked.
+ */
+export declare const DEFERRED_CALLERS: ReadonlySet<string>;
+/** Whether a call into package `name`, written `callText`, is one of React's non-throwing hooks. */
+export declare function isNonThrowingReactHook(name: string, callText: string): boolean;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/inference/builtins.js

@@ -0,0 +1,179 @@
+/**
+ * What the language's own functions throw. Anything of the
+ * platform (TypeScript's lib files, global declarations) that is not listed here is taken not to
+ * throw: errors of the engine itself (reading a property of `undefined`, a stack overflow) are not
+ * modelled, as Java does not declare its unchecked exceptions.
+ */
+/** The error classes of the platform; their ids are `builtin:<Name>`. */
+export const BUILTIN_ERRORS = new Set([
+    "Error",
+    "TypeError",
+    "RangeError",
+    "SyntaxError",
+    "URIError",
+    "ReferenceError",
+    "EvalError",
+    "AggregateError",
+    "DOMException",
+]);
+const BUILTIN = "builtin:";
+const DOM_EXCEPTION = `${BUILTIN}DOMException`;
+export function builtinId(name) {
+    return `${BUILTIN}${name}`;
+}
+/** A `DOMException` with one `name` (`AbortError`): caught by `instanceof DOMException`. */
+export function domExceptionId(name) {
+    return `${DOM_EXCEPTION}:${name}`;
+}
+export function isBuiltin(id) {
+    return id.startsWith(BUILTIN);
+}
+/**
+ * The class a built-in error class extends: `Error` for every other one, `DOMException` for a
+ * named `DOMException`; null for `Error`.
+ */
+export function builtinParent(id) {
+    if (id === builtinId("Error"))
+        return null;
+    if (id.startsWith(`${DOM_EXCEPTION}:`))
+        return DOM_EXCEPTION;
+    return builtinId("Error");
+}
+/** How a class is shown: `TypeError`, `AbortError (DOMException)`. */
+export function builtinName(id) {
+    if (id.startsWith(`${DOM_EXCEPTION}:`)) {
+        return `${id.slice(DOM_EXCEPTION.length + 1)} (DOMException)`;
+    }
+    return id.slice(BUILTIN.length);
+}
+/** The class an `instanceof` test names to catch it: `DOMException` for `AbortError (DOMException)`. */
+export function builtinCatchName(id) {
+    return id.startsWith(`${DOM_EXCEPTION}:`) ? "DOMException" : id.slice(BUILTIN.length);
+}
+const SYNTAX = builtinId("SyntaxError");
+const TYPE = builtinId("TypeError");
+const RANGE = builtinId("RangeError");
+const URI = builtinId("URIError");
+/** Methods of the platform's interfaces, as `<interface>.<method>`, that throw synchronously. */
+export const THROWING_MEMBERS = new Map([
+    ["JSON.parse", [SYNTAX]],
+    // A circular value, or a BigInt.
+    ["JSON.stringify", [TYPE]],
+    // A digit count outside 0 to 100.
+    ["Number.toFixed", [RANGE]],
+]);
+/** Global functions that throw synchronously. */
+export const THROWING_GLOBALS = new Map([
+    ["decodeURIComponent", [URI]],
+    ["decodeURI", [URI]],
+    ["structuredClone", [domExceptionId("DataCloneError")]],
+    ["atob", [domExceptionId("InvalidCharacterError")]],
+    // A fraction (RangeError), text that is not a number (SyntaxError), a symbol (TypeError).
+    ["BigInt", [RANGE, SYNTAX, TYPE]],
+]);
+/** Global constructors that throw. */
+export const THROWING_CONSTRUCTORS = new Map([
+    ["URL", [TYPE]],
+]);
+/** `Array(n)` and `new Array(n)` with one argument: a length that is not a valid one. */
+export const ARRAY_LENGTH = [RANGE];
+/** What `fetch` rejects with: a network failure, and an abort when a signal is passed. */
+export const FETCH_REJECTS = [TYPE];
+export const FETCH_ABORT = domExceptionId("AbortError");
+/** What `Promise.any` rejects with when every promise rejects. */
+export const ANY_REJECTS = builtinId("AggregateError");
+/**
+ * Methods and functions of the platform that call a callback before they return, as
+ * `<interface>.<method>` (or the global's name), with the index of the argument that is the
+ * callback: what it throws, the call throws. `replace`'s second argument and `JSON.stringify`'s
+ * replacer may also be a string or a list; only a function there is a callback.
+ */
+export const SYNC_CALLBACKS = new Map([
+    ...["Array", "ReadonlyArray"].flatMap((owner) => [
+        "map",
+        "forEach",
+        "filter",
+        "reduce",
+        "reduceRight",
+        "some",
+        "every",
+        "find",
+        "findIndex",
+        "findLast",
+        "findLastIndex",
+        "flatMap",
+        "toSorted",
+    ].map((method) => [`${owner}.${method}`, 0])),
+    ["Array.sort", 0],
+    ...["Map", "ReadonlyMap", "Set", "ReadonlySet"].map((owner) => [
+        `${owner}.forEach`,
+        0,
+    ]),
+    ["ArrayConstructor.from", 1],
+    ["String.replace", 1],
+    ["String.replaceAll", 1],
+    ["JSON.parse", 1],
+    ["JSON.stringify", 1],
+    ["ObjectConstructor.groupBy", 1],
+    ["MapConstructor.groupBy", 1],
+]);
+/** Calls whose result holds what the callback returned (promises, for `Promise.all`). */
+export const MAPPING_METHODS = new Set([
+    "Array.map",
+    "ReadonlyArray.map",
+    "Array.flatMap",
+    "ReadonlyArray.flatMap",
+    "ArrayConstructor.from",
+]);
+/**
+ * Functions and constructors of the platform, by name, that run their callback later (a timer, an
+ * event, an observer) or never (`removeEventListener`): what the callback throws never reaches
+ * the caller, so it is left out on purpose. Its own catches are still checked.
+ */
+export const DEFERRED_CALLERS = new Set([
+    "setTimeout",
+    "setInterval",
+    "queueMicrotask",
+    "requestAnimationFrame",
+    "requestIdleCallback",
+    "addEventListener",
+    "removeEventListener",
+    "MutationObserver",
+    "ResizeObserver",
+    "IntersectionObserver",
+    "PerformanceObserver",
+]);
+/**
+ * React's built-in hooks do not throw in correct use (misuse, like a hook called conditionally, is
+ * a bug the rules-of-hooks lint finds, not part of their contract), so a call to one adds nothing.
+ * Without this, every component would carry "unknown (package react)". `use()` is left out: it
+ * rethrows a rejected promise.
+ */
+const NON_THROWING_REACT_HOOKS = new Set([
+    "useState",
+    "useReducer",
+    "useEffect",
+    "useLayoutEffect",
+    "useInsertionEffect",
+    "useMemo",
+    "useCallback",
+    "useRef",
+    "useContext",
+    "useId",
+    "useTransition",
+    "useDeferredValue",
+    "useImperativeHandle",
+    "useDebugValue",
+    "useSyncExternalStore",
+    "useOptimistic",
+    "useActionState",
+    "useFormStatus",
+]);
+/** Whether a call into package `name`, written `callText`, is one of React's non-throwing hooks. */
+export function isNonThrowingReactHook(name, callText) {
+    if (name !== "react" && name !== "react-dom")
+        return false;
+    const callee = /([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*\(?/.exec(callText.split(".").pop() ?? "")?.[1];
+    return callee !== undefined && NON_THROWING_REACT_HOOKS.has(callee);
+}
+//# sourceMappingURL=builtins.js.map

package/dist/inference/catches.d.ts

@@ -0,0 +1,9 @@
+import type { Analysis, CatchSeen } from "./solve.js";
+/**
+ * Every catch of `file` (of the whole project when `file` is undefined) with what its `try` can
+ * throw, whether it branches on `instanceof` or not: the editor's catch-variable hint and
+ * the refactoring "Handle the known errors" read these. `catch-misses-error` reads only the catches that branch
+ * (`everyCatch`). In source order, one per `catch` keyword.
+ */
+export declare function catchesOf(analysis: Analysis, file?: string): readonly CatchSeen[];
+//# sourceMappingURL=catches.d.ts.map

package/dist/inference/catches.js

@@ -0,0 +1,33 @@
+import { collected, evaluate, inferred } from "./solve.js";
+/**
+ * Every catch of `file` (of the whole project when `file` is undefined) with what its `try` can
+ * throw, whether it branches on `instanceof` or not: the editor's catch-variable hint and
+ * the refactoring "Handle the known errors" read these. `catch-misses-error` reads only the catches that branch
+ * (`everyCatch`). In source order, one per `catch` keyword.
+ */
+export function catchesOf(analysis, file) {
+    const found = new Map();
+    const add = (one) => {
+        const key = `${one.file}\u0000${String(one.handler.at[0]).padStart(10, "0")}`;
+        if (!found.has(key))
+            found.set(key, one);
+    };
+    for (const entry of analysis.functions.values()) {
+        if (file === undefined || entry.file === file)
+            inferred(entry, analysis, add);
+    }
+    for (const module of analysis.modules) {
+        if (file !== undefined && module.file !== file)
+            continue;
+        evaluate(module.effects, {
+            file: module.file,
+            classes: analysis.classes,
+            resultOf: (id) => analysis.results.get(id),
+            onCatch: add,
+        }, new Map(), collected());
+    }
+    return [...found.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([, one]) => one);
+}
+//# sourceMappingURL=catches.js.map

package/dist/inference/deps.d.ts

@@ -0,0 +1,12 @@
+import type { EditorContributions, Json, LibraryUse } from "@stateward/core";
+type LibraryFacts = NonNullable<EditorContributions["libraryFacts"]>;
+/** The rules whose summaries hold the throws facts; the first that ran is read. */
+export declare const FACT_RULES: readonly ["errors/throws-doc-mismatch"];
+/**
+ * Every package function the project calls, with where its throws facts come from and why what
+ * is unknown is unknown (`stateward deps`), from the last full check.
+ */
+export declare function packagesCalled(summaries: ReadonlyMap<string, Json>): readonly LibraryUse[];
+export declare const libraryFacts: LibraryFacts;
+export {};
+//# sourceMappingURL=deps.d.ts.map

package/dist/inference/deps.js

@@ -0,0 +1,79 @@
+import { TREE_RULES, throwsOf } from "../react/boundaries.js";
+import { readSummary } from "./summary.js";
+/** The rules whose summaries hold the throws facts; the first that ran is read. */
+export const FACT_RULES = ["errors/throws-doc-mismatch"];
+function collect(effects, into) {
+    for (const effect of effects) {
+        if (effect.k === "package")
+            into.push(effect.facts);
+        else if (effect.k === "try") {
+            collect(effect.body, into);
+            collect(effect.fin, into);
+            const handler = effect.handler;
+            if (handler !== null) {
+                collect(handler.pre, into);
+                for (const branch of handler.branches)
+                    collect(branch.body, into);
+                collect(handler.otherwise ?? [], into);
+                collect(handler.after, into);
+            }
+        }
+    }
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Every package function the project calls, with where its throws facts come from and why what
+ * is unknown is unknown (`stateward deps`), from the last full check.
+ */
+export function packagesCalled(summaries) {
+    const found = [];
+    for (const value of summaries.values()) {
+        const summary = readSummary(value);
+        if (summary === undefined)
+            continue;
+        for (const fact of summary.functions) {
+            collect(fact.body, found);
+            collect(fact.returns, found);
+        }
+        collect(summary.module, found);
+    }
+    const byPackage = new Map();
+    for (const facts of found) {
+        const key = `${facts.name}\u0000${facts.version}`;
+        const entry = byPackage.get(key) ?? {
+            version: facts.version,
+            functions: new Map(),
+        };
+        byPackage.set(key, entry);
+        const fn = entry.functions.get(facts.fn) ?? {
+            source: facts.source,
+            unknown: new Set(),
+        };
+        entry.functions.set(facts.fn, fn);
+        for (const reason of [...facts.throws.unknown, ...facts.rejects.unknown])
+            fn.unknown.add(reason);
+    }
+    return [...byPackage]
+        .sort(([a], [b]) => compare(a, b))
+        .map(([key, entry]) => ({
+        package: key.slice(0, key.indexOf("\u0000")),
+        version: entry.version,
+        functions: [...entry.functions]
+            .sort(([a], [b]) => compare(a, b))
+            .map(([name, fn]) => ({ name, source: fn.source, unknown: [...fn.unknown].sort() })),
+    }));
+}
+export const libraryFacts = (input) => {
+    let summaries;
+    for (const ruleId of FACT_RULES)
+        summaries ??= input.projectSummaries(ruleId);
+    for (const ruleId of TREE_RULES) {
+        const trees = summaries === undefined ? input.projectSummaries(ruleId) : undefined;
+        if (trees !== undefined)
+            summaries = throwsOf(trees);
+    }
+    return summaries === undefined ? [] : packagesCalled(summaries);
+};
+//# sourceMappingURL=deps.js.map

package/dist/inference/format.d.ts

@@ -0,0 +1,25 @@
+import type { Result, Source, Thrown } from "./solve.js";
+import type { ClassFact } from "./summary.js";
+/** How a class is shown: its name, `AbortError (DOMException)` for a named DOMException. */
+export declare function className(id: string, classes: ReadonlyMap<string, ClassFact>): string;
+/** The name an `instanceof` test or a `@throws` tag uses for the class. */
+export declare function catchName(id: string, classes: ReadonlyMap<string, ClassFact>): string;
+/** `others stateward cannot see (from a: why; b: why; and 3 more)`. */
+export declare function unknownText(sources: readonly Source[], more: boolean): string;
+/**
+ * `ParseError | ZodError (zod 3.23.8: declared) | others stateward cannot see (from …)`, or "" for an empty set: a class
+ * known from a package's facts names where they come from.
+ */
+export declare function thrownText(thrown: Thrown, classes: ReadonlyMap<string, ClassFact>): string;
+/**
+ * What a call's promise rejects with, without the unknown parts already listed as thrown: an
+ * unknown call is both thrown and returned when stateward cannot tell whether it gives a promise,
+ * and is shown once, where it is thrown.
+ */
+export declare function rejectsShown(result: Result): Thrown;
+/**
+ * The hover's lines: `throws: …` for what a call throws, `rejects: …` for what its promise
+ * rejects with, `throws nothing stateward can see` when both are empty.
+ */
+export declare function resultLines(result: Result, classes: ReadonlyMap<string, ClassFact>): string[];
+//# sourceMappingURL=format.d.ts.map