@stateward/plugin-errors 1.0.1-rc.1 → 1.1.0

package/dist/exhaustive-catch.js

@@ -1,190 +0,0 @@
-import { defineRule, matchesName, option } from "@stateward/core";
-import { catchName, className } from "./inference/format.js";
-import { analyse, everyCatch } from "./inference/solve.js";
-import { summarizeOnce } from "./inference/project.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 = "catch";
-const EXPLAIN = `# errors/exhaustive-catch
-
-A catch that branches with instanceof handles every error class its try can throw, or rethrows the rest.
-
-## Why
-
-A \`catch\` that checks \`e instanceof AuthError\` says which errors it expects. When \`api.send\` can also throw \`RateLimitError\`, a rate limit falls into the generic branch: the user sees a generic error page, and the retry that would have worked never happens. This rule lists, at the \`catch\`, the classes it leaves out.
-
-## When to use it
-
-Use it in code that throws its own error classes and catches them by class. It is on as an error in every preset; where a \`catch\` does not branch on \`instanceof\`, it says nothing. It works best when your functions throw classes and document them with \`@throws {T}\`.
-
-## What it catches
-
-A \`catch\` that branches with \`if\` / \`else if\` or \`switch (true)\` on \`instanceof\`, when its \`try\` can throw an error class that no branch names and nothing passes on.
-
-What the \`try\` can throw is worked out from \`throw new X(…)\` in the functions it calls, in any file, their \`@throws\` tags, the built-ins stateward knows (\`JSON.parse\`, \`new URL\`, \`fetch\`, …), and the packages it calls. \`stateward deps\` shows how well each package's errors are known.
-
-What counts as handled:
-
-- \`e instanceof X\` handles \`X\` and every class that extends it (\`e instanceof Error\` handles them all);
-- a last \`else\` or \`default\`, or a statement after the chain, that throws (\`throw e\`, or a new error with \`{ cause: e }\`) passes the rest on;
-- a last \`else\` or \`default\`, or code after the chain, that uses the error (\`setError(e)\`, logging it, reading a property) handles the rest. An \`else\` that ignores the error (\`showGenericError()\`) does not.
-
-### Bad
-
-\`\`\`ts
-// api.send can throw RateLimitError and AuthError.
-try {
-  await api.send(message);
-} catch (e) {
-  if (e instanceof AuthError) {
-    redirectToLogin();
-  } else {
-    showGenericError();
-  }
-}
-\`\`\`
-
-### Good
-
-\`\`\`ts
-try {
-  await api.send(message);
-} catch (e) {
-  if (e instanceof AuthError) {
-    redirectToLogin();
-  } else if (e instanceof RateLimitError) {
-    retryLater();
-  } else {
-    throw e;
-  }
-}
-\`\`\`
-
-### Fix
-
-Add a branch for each missing class, or rethrow what you do not handle. The message shows the branch in the shape of your \`catch\`, and links to the call that throws each class. There is no quick fix.
-
-## What it does not catch
-
-- A \`catch\` with no \`instanceof\` branches: it treats every error alike on purpose.
-- Errors stateward cannot see: from a package it cannot read, a callback, or a dynamic call. Only the classes it can see are checked, and the message notes each call it could not see into, with the reason. \`errors/rethrow-unknown\` makes sure the rest is not dropped. To fill a gap, declare a package's errors under \`facts\` in the config.
-- A class whose \`extends\` cannot be followed, or a branch with a test that is not only \`instanceof\` (\`e instanceof A && e.code === 1\`, \`isAbort(e)\`): it does not guess what that branch handles.
-- Errors from the JavaScript engine itself, such as reading a property of \`undefined\`.
-- Built-ins other than \`JSON.parse\`, \`JSON.stringify\`, \`new URL\`, \`decodeURIComponent\`, \`decodeURI\`, \`structuredClone\`, \`atob\`, \`fetch\`, \`toFixed\`, \`Array(n)\` and \`BigInt\`: they are taken not to throw.
-- Promises kept in a \`let\`, a parameter or a property; getters, setters and generators; tests other than \`instanceof\` (\`e.name === "AbortError"\`).
-
-## Turn it on or off
-
-In \`stateward.config.ts\`:
-
-\`\`\`ts
-rules: { "errors/exhaustive-catch": "off" } // or "warning"
-groups: { "errors/catch": "off" } // the whole group
-facts: { "config-lib": { load: { throws: ["ConfigError"] } } } // declare a package's errors
-rules: { "errors/exhaustive-catch": ["error", { ignoreClasses: ["SyntaxError"] }] } // never require a branch for these
-\`\`\`
-`;
-/** At most this many package calls with unknown errors are noted on a finding. */
-const MAX_UNKNOWN_NOTES = 2;
-function headline(names, via) {
-    return fitted(HEADLINE_MAX, (cut) => {
-        const source = via === undefined ? "its `try` block" : `\`${cut(via)}\``;
-        return `this catch does not handle ${codeList(names, cut)}, which ${source} can throw`;
-    });
-}
-/** The fix, in the shape of the catch: a `case`, an `else if`, or an `if` for a chain without `else`. */
-function hint(count, variable, handler, shape) {
-    const branch = count === 1 ? "it" : "each";
-    switch (shape) {
-        case "switch":
-            return withExample(`add a branch for ${branch}, or rethrow what you do not handle:`, [
-                `case ${variable} instanceof ${handler}:`,
-                "  …",
-                "default:",
-                `  throw ${variable};`,
-            ]);
-        case "else":
-            return withExample(`add a branch for ${branch}, or rethrow what you do not handle:`, [
-                `} else if (${variable} instanceof ${handler}) {`,
-                "  …",
-                "} else {",
-                `  throw ${variable};`,
-            ]);
-        case "if":
-            return withExample(`add a branch for ${branch}, or rethrow what you do not handle after the chain:`, [`if (${variable} instanceof ${handler}) {`, "  …", "}", `throw ${variable};`]);
-        default: {
-            const unreachable = shape;
-            return unreachable;
-        }
-    }
-}
-function report(seen, classes, ignored, emit) {
-    const { handler } = seen;
-    if (handler.restThrows || handler.restUsed || handler.variable === null)
-        return;
-    const missing = [];
-    for (const [id, info] of seen.unhandled) {
-        if (info.certain && !matchesName(catchName(id, classes), ignored)) {
-            missing.push({ id, via: info.via });
-        }
-    }
-    const [first] = missing;
-    if (first === undefined)
-        return;
-    const vias = new Set(missing.map((one) => one.via?.text));
-    const via = vias.size === 1 ? first.via?.text : undefined;
-    const related = [];
-    const shown = new Set();
-    for (const { id, via: from } of missing) {
-        if (from === null || shown.has(`${String(from.start)}:${from.text}`) || related.length >= 3) {
-            continue;
-        }
-        shown.add(`${String(from.start)}:${from.text}`);
-        related.push({
-            location: { file: from.file, start: from.start, end: from.end },
-            message: `\`${from.text}\` can throw \`${className(id, classes)}\``,
-        });
-    }
-    // A package call whose errors are not all known: the catch passes them on (they reach the
-    // rethrow, or nothing is reported for them), and the note says which call and why.
-    const unknowns = [...seen.thrown.unknowns.values()].filter((one) => one.package !== undefined);
-    for (const source of unknowns.slice(0, MAX_UNKNOWN_NOTES)) {
-        related.push({
-            location: { file: source.file, start: source.start, end: source.end },
-            message: `\`${source.text}\` may also throw errors stateward cannot list (${source.reason}); rethrow what you do not handle`,
-        });
-    }
-    emit({
-        message: headline(missing.map((one) => className(one.id, classes)), via),
-        hint: hint(missing.length, handler.variable, catchName(first.id, classes), handler.dispatch === "switch" ? "switch" : handler.otherwise === null ? "if" : "else"),
-        location: { file: seen.file, start: handler.at[0], end: handler.at[1] },
-        related,
-    });
-}
-export const exhaustiveCatch = defineRule({
-    kind: "project",
-    meta: {
-        description: "A catch that branches with instanceof handles every error class its try can throw, or rethrows the rest.",
-        defaultSeverity: "error",
-        tier: "core",
-        group: GROUP,
-        needsJsDoc: true,
-        options: {
-            ignoreClasses: option.strings({
-                default: [],
-                description: "Error classes a catch never needs a branch for, as its instanceof test names them (SyntaxError, *AbortError).",
-            }),
-        },
-        explain: EXPLAIN,
-    },
-    summarize: (ctx) => summarizeOnce(ctx),
-    check(summaries, ctx) {
-        const analysis = analyse(summaries);
-        for (const seen of everyCatch(analysis)) {
-            report(seen, analysis.classes, ctx.options.ignoreClasses, (problem) => {
-                ctx.report(problem);
-            });
-        }
-    },
-});
-//# sourceMappingURL=exhaustive-catch.js.map

package/dist/exhaustive-fallback.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 exhaustiveFallback: import("@stateward/core").ProjectRule<import("./react/boundaries.js").ReactSummary, {
-    ignoreClasses: import("@stateward/core").StringsOption;
-}, "react">;
-//# sourceMappingURL=exhaustive-fallback.d.ts.map

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