@stateward/plugin-errors 1.0.0 → 1.0.1

package/dist/exhaustive-fallback.js

@@ -1,157 +0,0 @@
-import { defineRule, matchesName, option } from "@stateward/core";
-import { catchName, className } from "./inference/format.js";
-import { relation } from "./inference/solve.js";
-import { modelOf, summarizeReact } from "./react/boundaries.js";
-import { HEADLINE_MAX, codeList, fitted, withExample } from "./text.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "react";
-const EXPLAIN = `# errors/exhaustive-fallback
-
-An error boundary's fallback that branches on the error with instanceof handles every error class the boundary can catch, or has a branch for the rest.
-
-## Why
-
-A fallback that checks \`error instanceof NotFoundError\` says which errors it expects. When a page under the same boundary can also throw \`ParseError\`, and the fallback ends with \`return null\`, the user gets an empty screen with no message and no way back. This rule lists the classes the boundary can catch that no branch names.
-
-## When to use it
-
-Use it with error boundaries whose fallback shows something different per error class. It is a core rule, a warning in every preset; a fallback that does not branch on \`instanceof\` is left alone.
-
-## What it catches
-
-A fallback that branches with \`if\` / \`else if\`, \`switch (true)\` or \`? :\` on \`error instanceof X\`, has no branch for any other error, and belongs to a boundary that can catch a class no branch names. The fallback is react-error-boundary's \`FallbackComponent\`, \`fallbackRender\` or \`onError\`, or a boundary class's \`getDerivedStateFromError\`. What the boundary can catch is what the components below it throw while rendering and in their effects, down to the next boundary (the hover on the boundary lists it).
-
-A branch for the rest is a final \`else\` or \`default\`, or code after the chain, that does more than return \`null\` or nothing.
-
-### Bad
-
-\`\`\`tsx
-// SettingsPage, under this boundary, can throw ParseError.
-function UserErrorPage({ error }: FallbackProps) {
-  if (error instanceof NotFoundError) return <p>This user does not exist.</p>;
-  return null;
-}
-\`\`\`
-
-### Good
-
-\`\`\`tsx
-function UserErrorPage({ error }: FallbackProps) {
-  if (error instanceof NotFoundError) return <p>This user does not exist.</p>;
-  return <p>Something went wrong: {String(error)}</p>;
-}
-\`\`\`
-
-### Fix
-
-Add a branch for each class the message lists, or end the chain with a fallback for any other error. There is no quick fix.
-
-## What it does not catch
-
-- A fallback that does not branch on \`instanceof\`, or whose tests are not only \`instanceof\` (\`error instanceof A && error.status === 404\`): it does not guess what such a branch handles.
-- Errors stateward cannot see (from a package it cannot read, a callback, a dynamic call): only known classes are checked.
-- Errors from event handlers and async code: a boundary never receives them.
-- A fallback passed as anything other than a function written in place or the name of a function of the project.
-
-## Turn it on or off
-
-In \`stateward.config.ts\`:
-
-\`\`\`ts
-rules: { "errors/exhaustive-fallback": "off" } // or "error"
-groups: { "errors/react": "off" } // the whole group
-rules: { "errors/exhaustive-fallback": ["warning", { ignoreClasses: ["ChunkLoadError"] }] } // never require a branch for these
-\`\`\`
-`;
-/** What the fallback does with any other error, in the example: what it returns or does. */
-function restLine(kind, variable) {
-    switch (kind) {
-        case "FallbackComponent":
-        case "fallbackRender":
-            return `return <p>Something went wrong: {String(${variable})}</p>;`;
-        case "onError":
-            return `console.error(${variable});`;
-        case "getDerivedStateFromError":
-            return `return { error: ${variable} };`;
-        default: {
-            const unreachable = kind;
-            return unreachable;
-        }
-    }
-}
-function hint(fallback, chain, handler, count) {
-    const line = `add a branch for ${count === 1 ? "it" : "each"}, or end with one for any other error:`;
-    const rest = restLine(fallback.kind, chain.variable);
-    return chain.dispatch === "switch"
-        ? withExample(line, [
-            `case ${chain.variable} instanceof ${handler}:`,
-            "  …",
-            "default:",
-            `  ${rest}`,
-        ])
-        : withExample(line, [`if (${chain.variable} instanceof ${handler}) {`, "  …", "}", rest]);
-}
-export const exhaustiveFallback = defineRule({
-    kind: "project",
-    meta: {
-        description: "An error boundary's fallback that branches on the error with instanceof handles every error class the boundary can catch, or has a branch for the rest.",
-        defaultSeverity: "warning",
-        tier: "core",
-        group: GROUP,
-        needsJsDoc: true,
-        options: {
-            ignoreClasses: option.strings({
-                default: [],
-                description: "Error classes a fallback never needs a branch for, as its instanceof test names them (globs allowed).",
-            }),
-        },
-        explain: EXPLAIN,
-    },
-    summarize: (ctx) => summarizeReact(ctx),
-    check(summaries, ctx) {
-        const model = modelOf(summaries);
-        const classes = model.analysis.classes;
-        for (const [key, { file, element }] of model.boundaries) {
-            for (const fallback of element.fallbacks) {
-                const chain = fallback.chain;
-                if (chain === null || chain.generic || !chain.exact)
-                    continue;
-                const handled = [];
-                let readable = true;
-                for (const branch of chain.branches) {
-                    if (branch === null)
-                        readable = false;
-                    else
-                        handled.push(...branch);
-                }
-                if (!readable)
-                    continue;
-                const caught = model.catches(key);
-                const missing = [...caught.classes]
-                    .filter(([id, brought]) => brought.certain &&
-                    !matchesName(catchName(id, classes), ctx.options.ignoreClasses) &&
-                    handled.every((one) => relation(one, id, classes) === "no"))
-                    .map(([id, brought]) => ({ id, brought, name: className(id, classes) }))
-                    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-                const [first] = missing;
-                if (first === undefined)
-                    continue;
-                const related = missing.slice(0, 3).map(({ brought, name }) => ({
-                    location: brought.location,
-                    message: `${brought.what} \`${name}\``,
-                }));
-                related.push({
-                    location: { file: chain.file, start: chain.at[0], end: chain.at[1] },
-                    message: `\`${fallback.name}\` branches on the error here`,
-                });
-                ctx.report({
-                    message: fitted(HEADLINE_MAX, (cut) => `\`${cut(fallback.name)}\` does not handle ${codeList(missing.map((one) => one.name), cut)}, which this boundary can catch`),
-                    hint: hint(fallback, chain, catchName(first.id, classes), missing.length),
-                    location: { file, start: fallback.at[0], end: fallback.at[1] },
-                    related,
-                });
-            }
-        }
-    },
-});
-//# sourceMappingURL=exhaustive-fallback.js.map

package/dist/finally-may-throw.d.ts

@@ -1,6 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "finally";
-export declare const finallyMayThrow: import("@stateward/core").FileRule<{
-    severities: import("@stateward/core").SeveritiesOption<"throw" | "builtin" | "own-function">;
-}, "finally">;
-//# sourceMappingURL=finally-may-throw.d.ts.map

package/dist/finally-may-throw.js

@@ -1,184 +0,0 @@
-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/no-swallow.d.ts

@@ -1,8 +0,0 @@
-/** 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

@@ -1,320 +0,0 @@
-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/render-throws-without-boundary.d.ts

@@ -1,6 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "react";
-export declare const renderThrowsWithoutBoundary: import("@stateward/core").ProjectRule<import("./react/boundaries.js").ReactSummary, {
-    boundaries: import("@stateward/core").RecordOption;
-}, "react">;
-//# sourceMappingURL=render-throws-without-boundary.d.ts.map