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

package/dist/no-swallow.d.ts

@@ -0,0 +1,8 @@
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export declare const GROUP = "catch";
+export declare const noSwallow: import("@stateward/core").FileRule<{
+    loggers: import("@stateward/core").StringsOption;
+    logMethods: import("@stateward/core").StringsOption;
+    logFunctions: import("@stateward/core").StringsOption;
+}, "catch">;
+//# sourceMappingURL=no-swallow.d.ts.map

package/dist/no-swallow.js

@@ -0,0 +1,320 @@
+import ts from "@stateward/core/typescript";
+import { defineRule, matchesName, option } from "@stateward/core";
+import { withExample } from "./text.js";
+import { stripParentheses } from "./syntax.js";
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export const GROUP = "catch";
+const EXPLAIN = `# errors/no-swallow
+
+A catch that only logs, or does nothing, and then carries on treats a failure as if it had not happened.
+
+## Why
+
+In \`load\`, a failed \`fetchUser\` is logged and \`render(user)\` runs anyway, with a \`user\` that was never fetched. The page shows a blank profile instead of an error, and the only trace is a line in the console.
+
+## When to use it
+
+Use it for code that must never lose a failure: payments, sync, data import; or to review a module's catches once. In most apps many catches that only log are deliberate fallbacks (a setting read from storage, a best-effort cache write), so it is off until you add its add-on (below), then a warning in every preset. Make it an error once that code is clean.
+
+## What it catches
+
+A \`catch\` that is empty or only logs (\`console.*\`, a call on \`logger\` or \`log\`, or \`.error\`, \`.warn\`, \`.info\`, \`.debug\` on any object; the options below change these lists), when the function carries on after the \`try\`.
+
+### Bad
+
+\`\`\`ts
+async function load(id: string) {
+  let user;
+  try {
+    user = await fetchUser(id);
+  } catch (e) {
+    console.error(e);
+  }
+  return render(user);
+}
+\`\`\`
+
+### Good
+
+\`\`\`ts
+async function load(id: string) {
+  try {
+    return render(await fetchUser(id));
+  } catch (e) {
+    return err(e);
+  }
+}
+\`\`\`
+
+### Fix
+
+Rethrow the error, return a failure the caller can see, or show it to the user. The message shows \`throw e;\`, or \`return err(e);\` when the file imports \`err\` from \`@stateward/values\`. There is no quick fix.
+
+## What it does not catch
+
+It stays quiet when:
+
+- the \`catch\` does anything else (\`return\`, \`throw\`, a call that shows the error);
+- an empty \`catch\` holds a comment, which says it is on purpose;
+- the \`try\` returns its value and the code after it returns a default (\`try { return JSON.parse(stored); } catch (e) { console.warn(e); } return defaults;\`);
+- every variable the \`try\` assigns already had a value to fall back on (\`let flags = DEFAULTS; try { flags = JSON.parse(stored); } catch …\`; a parameter counts, a \`let\` with no value does not);
+- the \`try\` is the last thing the function, or a loop's body, does (a retry loop moves on to the next attempt).
+
+A function of your own that only logs is not recognised as logging until you list it in \`logFunctions\`.
+
+## Turn it on or off
+
+Turn it on in \`stateward.config.ts\`:
+
+\`\`\`ts
+addons: ["errors/swallow"]
+\`\`\`
+
+Then change or turn off the rule itself:
+
+\`\`\`ts
+rules: { "errors/no-swallow": "off" } // or "error"
+groups: { "errors/catch": "off" } // the whole group
+rules: { "errors/no-swallow": ["warning", { logFunctions: ["logError"] }] } // your own log helpers
+\`\`\`
+`;
+const OPTIONS = {
+    loggers: option.strings({
+        default: ["console", "logger", "log"],
+        description: "Objects whose every method only logs (globs like *Logger): a catch that only calls them swallows the error.",
+    }),
+    logMethods: option.strings({
+        default: ["error", "warn", "info", "debug"],
+        description: "Method names that only log, on any object (`Sentry.captureException` is not one).",
+    }),
+    logFunctions: option.strings({
+        default: [],
+        description: "Plain functions of your own that only log, like logError (globs allowed).",
+    }),
+};
+/** The name an expression ends in: `logger`, `this.logger`, `app.log`. */
+function lastName(expression) {
+    const node = stripParentheses(expression);
+    if (ts.isIdentifier(node))
+        return node.text;
+    return ts.isPropertyAccessExpression(node) ? node.name.text : undefined;
+}
+/**
+ * A call that only logs: any method of a logger (`console.x()`, `logger.x()`), a log method on any
+ * object (`app.warn()`), or one of the team's own log functions (`logError(e)`).
+ */
+function isLoggingCall(expression, logging) {
+    const call = stripParentheses(expression);
+    if (!ts.isCallExpression(call))
+        return false;
+    const callee = stripParentheses(call.expression);
+    if (ts.isIdentifier(callee))
+        return matchesName(callee.text, logging.logFunctions);
+    if (!ts.isPropertyAccessExpression(callee))
+        return false;
+    if (logging.logMethods.includes(callee.name.text))
+        return true;
+    const name = lastName(stripParentheses(callee.expression));
+    return name !== undefined && matchesName(name, logging.loggers);
+}
+/** What the catch does: nothing, or only log. Undefined when it does anything else. */
+function swallowKind(block, sourceFile, logging) {
+    const statements = block.statements.filter((statement) => !ts.isEmptyStatement(statement));
+    if (statements.length === 0) {
+        // A comment inside an empty catch says it is on purpose.
+        return hasComment(block, sourceFile) ? undefined : "ignores";
+    }
+    const onlyLogs = statements.every((statement) => ts.isExpressionStatement(statement) && isLoggingCall(statement.expression, logging));
+    return onlyLogs ? "logs" : undefined;
+}
+function hasComment(block, sourceFile) {
+    const inner = sourceFile.text.slice(block.getStart(sourceFile) + 1, block.getEnd() - 1);
+    return inner.trim() !== "";
+}
+/** Statements that run nothing: a bare `;` and declarations that only exist at compile time. */
+function runsNothing(statement) {
+    return (ts.isEmptyStatement(statement) ||
+        ts.isFunctionDeclaration(statement) ||
+        ts.isInterfaceDeclaration(statement) ||
+        ts.isTypeAliasDeclaration(statement));
+}
+/** `return;`, `break;` and `continue;` end the flow: nothing after them carries on. */
+function endsFlow(statement) {
+    if (ts.isReturnStatement(statement))
+        return statement.expression === undefined;
+    return ts.isBreakStatement(statement) || ts.isContinueStatement(statement);
+}
+/**
+ * Whether the function runs something after the `try` statement: a statement that follows it in
+ * its block or in a block around it, up to the function (or the file, for top-level code). The end
+ * of a loop's body runs nothing after it: the loop goes on to its next turn (a retry loop's next
+ * attempt).
+ */
+function continuesAfter(tryStatement) {
+    let node = tryStatement;
+    for (let parent = node.parent;; parent = node.parent) {
+        if (ts.isFunctionLike(parent))
+            return false;
+        if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isCaseOrDefaultClause(parent)) {
+            const statements = parent.statements;
+            const after = statements.slice(statements.findIndex((candidate) => candidate === node) + 1);
+            const next = after.find((statement) => !runsNothing(statement));
+            if (next !== undefined)
+                return !endsFlow(next);
+        }
+        if (ts.isSourceFile(parent))
+            return false;
+        if (ts.isIterationStatement(parent, false) && parent.statement === node)
+            return false;
+        node = parent;
+    }
+}
+/** Whether `node` has a `return` with a value that runs in this function (not in a nested one). */
+function returnsValue(node) {
+    if (ts.isReturnStatement(node))
+        return node.expression !== undefined;
+    if (ts.isFunctionLike(node) || ts.isClassLike(node))
+        return false;
+    return ts.forEachChild(node, (child) => (returnsValue(child) ? true : undefined)) === true;
+}
+/**
+ * A fallback: the `try` returns the value it produced, and the statement right after it returns
+ * another one (`try { return JSON.parse(stored); } catch (e) { console.warn(e); } return
+ * defaults;`). The caller gets a value either way; nothing runs on a result that was never made.
+ */
+function fallsBackToAValue(tryStatement) {
+    const list = tryStatement.parent;
+    if (!ts.isBlock(list) && !ts.isSourceFile(list) && !ts.isCaseOrDefaultClause(list))
+        return false;
+    const after = list.statements.slice(list.statements.indexOf(tryStatement) + 1);
+    const next = after.find((statement) => !runsNothing(statement));
+    return (next !== undefined &&
+        ts.isReturnStatement(next) &&
+        next.expression !== undefined &&
+        returnsValue(tryStatement.tryBlock));
+}
+/** The names the `try` block assigns with `=` (not in a nested function): `flags = parse(…)`. */
+function assignedNames(block) {
+    const names = [];
+    const visit = (node) => {
+        if (ts.isFunctionLike(node) || ts.isClassLike(node))
+            return;
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isIdentifier(stripParentheses(node.left))) {
+            const target = stripParentheses(node.left);
+            if (ts.isIdentifier(target))
+                names.push(target.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(block);
+    return names;
+}
+/**
+ * Whether `name` already holds a value before the `try`: a `let` or `var` declared with an
+ * initializer in a block around it (before it, up to the module), or a parameter of a function
+ * around it.
+ */
+function holdsAValueBefore(name, tryStatement) {
+    let node = tryStatement;
+    for (let parent = node.parent;; parent = node.parent) {
+        if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isCaseOrDefaultClause(parent)) {
+            const before = parent.statements.slice(0, parent.statements.findIndex((s) => s === node));
+            for (const statement of before) {
+                if (!ts.isVariableStatement(statement))
+                    continue;
+                for (const declaration of statement.declarationList.declarations) {
+                    if (ts.isIdentifier(declaration.name) && declaration.name.text === name) {
+                        return declaration.initializer !== undefined;
+                    }
+                }
+            }
+        }
+        // A parameter holds the caller's value; past it, a closure's or the module's variable.
+        if (ts.isFunctionLike(parent) &&
+            parent.parameters.some((parameter) => ts.isIdentifier(parameter.name) && parameter.name.text === name)) {
+            return true;
+        }
+        if (ts.isSourceFile(parent))
+            return false;
+        node = parent;
+    }
+}
+/**
+ * A fallback assigned before the `try`: every variable the `try` assigns already held a value
+ * (`let flags = DEFAULTS; try { flags = parse(…); } catch (e) { log(e); } return flags;`). The
+ * code after the `try` runs on that value when the `try` fails, which is what the author chose.
+ */
+function replacesAFallback(tryStatement) {
+    const names = assignedNames(tryStatement.tryBlock);
+    return names.length > 0 && names.every((name) => holdsAValueBefore(name, tryStatement));
+}
+function headline(kind) {
+    return `this catch ${kind} the error and carries on as if nothing failed`;
+}
+/** The local name of `err` when the file imports it from `@stateward/values`. */
+function importedErr(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            !ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== "@stateward/values" ||
+            statement.importClause?.phaseModifier === ts.SyntaxKind.TypeKeyword) {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings))
+            continue;
+        const element = bindings.elements.find((candidate) => !candidate.isTypeOnly && (candidate.propertyName ?? candidate.name).text === "err");
+        if (element !== undefined)
+            return element.name.text;
+    }
+    return undefined;
+}
+/** The example uses only what the file has: `err` when it imports it, else a plain rethrow. */
+function hint(variable, sourceFile) {
+    const err = importedErr(sourceFile);
+    return withExample("rethrow it, return a failure the caller can see, or show it to the user:", [
+        err === undefined ? `throw ${variable};` : `return ${err}(${variable});`,
+    ]);
+}
+function checkCatch(clause, ctx) {
+    const kind = swallowKind(clause.block, ctx.sourceFile, ctx.options);
+    if (kind === undefined ||
+        !continuesAfter(clause.parent) ||
+        fallsBackToAValue(clause.parent) ||
+        replacesAFallback(clause.parent)) {
+        return;
+    }
+    const declaration = clause.variableDeclaration;
+    const variable = declaration !== undefined && ts.isIdentifier(declaration.name)
+        ? declaration.name.text
+        : "error";
+    ctx.report({
+        node: clause.getFirstToken(ctx.sourceFile) ?? clause,
+        message: headline(kind),
+        hint: hint(variable, ctx.sourceFile),
+    });
+}
+export const noSwallow = defineRule({
+    kind: "file",
+    meta: {
+        description: "A catch that only logs, or does nothing, and then carries on treats a failure as if it had not happened.",
+        defaultSeverity: "warning",
+        tier: "addon",
+        addon: "swallow",
+        group: GROUP,
+        heuristic: true,
+        options: OPTIONS,
+        explain: EXPLAIN,
+    },
+    check(ctx) {
+        const visit = (node) => {
+            if (ts.isCatchClause(node))
+                checkCatch(node, ctx);
+            ts.forEachChild(node, visit);
+        };
+        visit(ctx.sourceFile);
+    },
+});
+//# sourceMappingURL=no-swallow.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,116 @@
+export declare function errors(): import("@stateward/core").PluginOf<"errors", {
+    readonly "catch-hides-unexpected": import("@stateward/core").LazyRule<{
+        readonly restUsesError: {
+            readonly kind: "boolean";
+            readonly default: false;
+            readonly description: "The branch for the other errors must use the error (rethrow it, wrap it, report it); a generic message alone does not count.";
+        };
+    }, "catch">;
+    readonly "catch-without-intent": import("@stateward/core").LazyRule<{
+        readonly loggers: {
+            readonly kind: "strings";
+            readonly default: readonly ["console", "logger", "log"];
+            readonly description: "Objects whose every method only logs (globs like *Logger): a catch that only calls them swallows the error.";
+        };
+        readonly logMethods: {
+            readonly kind: "strings";
+            readonly default: readonly ["error", "warn", "info", "debug"];
+            readonly description: "Method names that only log, on any object (`Sentry.captureException` is not one).";
+        };
+        readonly logFunctions: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Plain functions of your own that only log, like logError (globs allowed).";
+        };
+        readonly edgeHelpers: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Your functions that report an error where it ends (to a service, to the user): a catch that calls one is handled, like reportAndShow (globs allowed). Sentry, Bugsnag and Datadog are known without it.";
+        };
+        readonly swallowHelpers: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Functions that mark an error as ignored on purpose, like ignoreError (globs allowed): a catch that calls one is not reported.";
+        };
+    }, "catch">;
+    readonly "finally-can-throw": import("@stateward/core").LazyRule<{
+        readonly severities: {
+            readonly kind: "severities";
+            readonly default: {};
+            readonly kinds: {
+                readonly throw: "a `throw` written in the finally: it throws whenever it runs.";
+                readonly builtin: "a built-in such as `JSON.parse` or `new URL`: it throws only on input it cannot handle.";
+                readonly "own-function": "a function in the same file with a `throw` in it: it throws on some paths.";
+            };
+            readonly description: "A severity per kind of call, where you trust one kind less.";
+        };
+    }, "catch">;
+    readonly "catch-misses-error": import("@stateward/core").LazyRule<{
+        readonly ignoreClasses: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Error classes a catch never needs a branch for, as its instanceof test names them (SyntaxError, *AbortError).";
+        };
+    }, "catch">;
+    readonly "throws-doc-mismatch": import("@stateward/core").LazyRule<{
+        readonly severities: {
+            readonly kind: "severities";
+            readonly default: {};
+            readonly kinds: {
+                readonly missing: "the function can throw a class its `@throws` does not list.";
+                readonly extra: "the `@throws` lists a class the function cannot throw (stale, not dangerous).";
+            };
+            readonly description: "A severity per kind of mismatch.";
+        };
+        readonly ignoreClasses: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Error classes a `@throws` never needs to list (TypeError, *AbortError), as a catch names them.";
+        };
+    }, "callers">;
+    readonly "render-throw-without-boundary": import("@stateward/core").LazyRule<{
+        readonly skipContextGuards: {
+            readonly kind: "boolean";
+            readonly default: true;
+            readonly description: "Leave out the usual check in a context hook: `if (!ctx) throw new Error(\"useAuth must be used within AuthProvider\")`.";
+        };
+        readonly skipInputGuards: {
+            readonly kind: "boolean";
+            readonly default: true;
+            readonly description: "Leave out a throw when a prop or a parameter whose type rules it out, or a context hook's value, is missing (a mistake of the caller).";
+        };
+        readonly rootBoundaryCounts: {
+            readonly kind: "boolean";
+            readonly default: false;
+            readonly description: "Count the error boundary around the whole app as handling the error. Off by default: the whole app is then replaced by its fallback, so the rule asks for a boundary nearer the page.";
+        };
+        readonly boundaries: {
+            readonly kind: "record";
+            readonly default: {
+                readonly "react-error-boundary": readonly ["ErrorBoundary"];
+            };
+            readonly description: "Error boundary components from packages, by package: add Sentry's with `{ \"@sentry/react\": [\"ErrorBoundary\"] }` (keep react-error-boundary's to keep it).";
+        };
+    }, "render">;
+    readonly "must-handle-error": import("@stateward/core").LazyRule<Readonly<Record<string, import("@stateward/core").OptionSpec>>, "callers">;
+    readonly "narrow-try": import("@stateward/core").LazyRule<Readonly<Record<string, import("@stateward/core").OptionSpec>>, "catch">;
+    readonly "result-ignored": import("@stateward/core").LazyRule<{
+        readonly allowVoid: {
+            readonly kind: "boolean";
+            readonly default: false;
+            readonly description: "Take `void save()` as dropping the Result on purpose, and stay quiet.";
+        };
+        readonly resultTypes: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Your names for a Result type whose shape stateward does not recognise (`Either`, `Outcome*`; globs allowed).";
+        };
+        readonly ignore: {
+            readonly kind: "strings";
+            readonly default: readonly [];
+            readonly description: "Functions whose Result may be dropped, by the name they are called with (`logEvent`, `*.track`; globs allowed).";
+        };
+    }, "callers">;
+    readonly "result-unchecked": import("@stateward/core").LazyRule<Readonly<Record<string, import("@stateward/core").OptionSpec>>, "callers">;
+}>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -0,0 +1,39 @@
+import { definePlugin, lazyRule, moduleLoader } from "@stateward/core";
+import { codeActions } from "./refactors.js";
+import { hover } from "./hover.js";
+import { libraryFacts } from "./inference/deps.js";
+import { inlayHints } from "./inlay.js";
+import { RULES } from "./rules.meta.js";
+/** Each rule's module, imported the first time the rule is on. */
+const load = {
+    catchHidesUnexpected: moduleLoader(() => import("./catch-hides-unexpected.js")),
+    catchWithoutIntent: moduleLoader(() => import("./catch-without-intent.js")),
+    finallyCanThrow: moduleLoader(() => import("./finally-can-throw.js")),
+    catchMissesError: moduleLoader(() => import("./catch-misses-error.js")),
+    throwsDocMismatch: moduleLoader(() => import("./throws-doc-mismatch.js")),
+    renderThrowWithoutBoundary: moduleLoader(() => import("./render-throw-without-boundary.js")),
+    mustHandleError: moduleLoader(() => import("./must-handle-error.js")),
+    narrowTry: moduleLoader(() => import("./narrow-try.js")),
+    resultIgnored: moduleLoader(() => import("./result-ignored.js")),
+    resultUnchecked: moduleLoader(() => import("./result-unchecked.js")),
+};
+export function errors() {
+    return definePlugin({
+        name: "errors",
+        description: "Errors are handled where they can happen: nothing swallowed, nothing lost in finally, no Result dropped.",
+        rules: {
+            "catch-hides-unexpected": lazyRule(RULES["catch-hides-unexpected"], load.catchHidesUnexpected, (module) => module.catchHidesUnexpected),
+            "catch-without-intent": lazyRule(RULES["catch-without-intent"], load.catchWithoutIntent, (module) => module.catchWithoutIntent),
+            "finally-can-throw": lazyRule(RULES["finally-can-throw"], load.finallyCanThrow, (module) => module.finallyCanThrow),
+            "catch-misses-error": lazyRule(RULES["catch-misses-error"], load.catchMissesError, (module) => module.catchMissesError),
+            "throws-doc-mismatch": lazyRule(RULES["throws-doc-mismatch"], load.throwsDocMismatch, (module) => module.throwsDocMismatch),
+            "render-throw-without-boundary": lazyRule(RULES["render-throw-without-boundary"], load.renderThrowWithoutBoundary, (module) => module.renderThrowWithoutBoundary),
+            "must-handle-error": lazyRule(RULES["must-handle-error"], load.mustHandleError, (module) => module.mustHandleError),
+            "narrow-try": lazyRule(RULES["narrow-try"], load.narrowTry, (module) => module.narrowTry),
+            "result-ignored": lazyRule(RULES["result-ignored"], load.resultIgnored, (module) => module.resultIgnored),
+            "result-unchecked": lazyRule(RULES["result-unchecked"], load.resultUnchecked, (module) => module.resultUnchecked),
+        },
+        editor: { hover, inlayHints, codeActions, libraryFacts },
+    });
+}
+//# sourceMappingURL=plugin.js.map

package/dist/react/boundaries.d.ts

@@ -0,0 +1,83 @@
+import type { FileContext, Json, Location, StringListRecord } from "@stateward/core";
+import type { Analysis, Source } from "../inference/solve.js";
+import type { ThrowsSummary } from "../inference/summary.js";
+import { type GuardSkips } from "./render-guards.js";
+import type { BoundaryElement, TreeFunction, TreeRender, TreeSummary } from "./tree.js";
+/**
+ * Errors in React: what each component throws while React
+ * renders it or runs its effects, which error boundary is nearest above each render, and what
+ * each boundary can catch. Handlers, timers and async code are left out: a boundary never sees
+ * their errors.
+ */
+/** The summary of the pack's React rules: the throws facts and the render tree of one file. */
+export type ReactSummary = {
+    readonly throws: ThrowsSummary;
+    readonly tree: TreeSummary;
+};
+/** The rules whose summaries hold a render tree; the first that ran is read. */
+export declare const TREE_RULES: readonly ["errors/render-throw-without-boundary", "errors/catch-misses-error"];
+export declare function summarizeReact(ctx: FileContext, libraryBoundaries?: StringListRecord, skips?: GuardSkips): ReactSummary;
+/** A render with the file it is written in. */
+export type Site = {
+    readonly to: string;
+    readonly file: string;
+    readonly render: TreeRender;
+};
+/** One class a component throws: whether surely, and the call that brings it. */
+export type Brought = {
+    readonly certain: boolean;
+    /** `useUser` for `(via <UserPage> → useUser)`; null when the component throws it itself. */
+    readonly step: string | null;
+    readonly location: Location;
+    /** `` `useUser(…)` can throw `NotFoundError` `` once the class's name is known. */
+    readonly what: string;
+};
+export type Own = {
+    readonly classes: ReadonlyMap<string, Brought>;
+    /**
+     * The classes it throws only from guards (render-guards.ts): a missing context or input, a
+     * mistake of the caller. A boundary still catches them; they do not make a render failure.
+     */
+    readonly guarded: ReadonlySet<string>;
+    readonly unknowns: readonly Source[];
+    readonly more: boolean;
+};
+export type Model = {
+    readonly analysis: Analysis;
+    readonly functions: ReadonlyMap<string, {
+        file: string;
+        fn: TreeFunction;
+    }>;
+    readonly boundaries: ReadonlyMap<string, {
+        file: string;
+        element: BoundaryElement;
+    }>;
+    /** Boundaries by file, for the hover. */
+    readonly byFile: ReadonlyMap<string, readonly BoundaryElement[]>;
+    readonly entries: readonly Site[];
+    /** Every render (entries first), by file and offset. */
+    readonly sites: readonly Site[];
+    /** The renders written in a component, in order. */
+    edges(id: string): readonly Site[];
+    /** The boundary nearest above a render, by key; undefined when there is none in its component. */
+    nearest(site: Site): string | undefined;
+    own(id: string): Own;
+    /** The classes a component surely throws, with what it renders outside any boundary. */
+    needs(id: string): ReadonlySet<string>;
+    /** What a boundary catches: from the renders whose nearest boundary it is, down to nested ones. */
+    catches(key: string): Omit<Own, "guarded"> & {
+        readonly labels: ReadonlyMap<string, string>;
+    };
+};
+/** The throws part of each summary: the same facts `catch-misses-error` solves. */
+export declare function throwsOf(summaries: ReadonlyMap<string, Json>): ReadonlyMap<string, Json>;
+/** The pack's view of the app's render tree, built once per summaries map. */
+export declare function modelOf(summaries: ReadonlyMap<string, Json>): Model;
+/** The line every boundary hover ends with: what no boundary ever catches. */
+export declare const NOT_CAUGHT = "not caught here: errors in event handlers and async code";
+/**
+ * On a boundary's tag: `catches: NotFoundError (via <UserPage> → useUser) | others stateward
+ * cannot see (from …)`, then `NOT_CAUGHT`. Undefined when `offset` is on no boundary's tag.
+ */
+export declare function boundaryLines(model: Model, file: string, offset: number): string[] | undefined;
+//# sourceMappingURL=boundaries.d.ts.map