@stateward/plugin-errors 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,15 @@
 
 The `errors` pack of [stateward](https://github.com/khoing1111/ts-stateward#readme). It finds a `catch` that misses an error class or hides the unexpected ones, an error lost in `finally`, a `Result` nobody checks, and a component that can throw with no error boundary above it. In VS Code, hints name the errors a function can throw.
 
+## Contents
+
+- [Turn it on](#turn-it-on)
+- [Rules](#rules)
+
+<!-- generated:setup -->
+
+## Turn it on
+
 ```bash
 npm install --save-dev stateward @stateward/plugin-errors
 ```
@@ -13,9 +22,58 @@ import { errors } from "@stateward/plugin-errors";
 
 export default defineConfig({
   plugins: [errors()],
-  preset: "recommended",
+  preset: "recommended", // or "strict"
 });
 ```
 
-`npx stateward init` writes this for you. The rules, their options and how to fix what they find:
-[docs/packs/errors.md](https://github.com/khoing1111/ts-stateward/blob/main/docs/packs/errors.md).
+`npx stateward init` writes this for you. A preset turns on the core and coverage rules; without one
+no rule is on.
+
+One rule's severity (`error`, `warning`, `info` or `off`), and its options, go under `rules`:
+
+```ts
+rules: {
+  "errors/must-handle-error": "warning",
+  // a severity and options; this option is at its default, the rule's page lists them all
+  "errors/result-ignored": ["error", { allowVoid: false }],
+},
+```
+
+Add-on rules stay off until you list their add-on:
+
+```ts
+addons: ["errors/catch-intent", "errors/narrow-try"],
+```
+
+- `errors/catch-intent`: `catch-without-intent`
+- `errors/narrow-try`: `narrow-try`
+
+Every key of the config: [config.md](https://github.com/khoing1111/ts-stateward/blob/main/docs/user/config.md).
+
+<!-- /generated:setup -->
+
+<!-- generated:rules -->
+
+## Rules
+
+| Rule | What it finds | Kind | `recommended` | `strict` |
+| --- | --- | --- | --- | --- |
+| [must-handle-error](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/must-handle-error.md) | An error class marked @mustHandle is named in a catch or passed on with @throws by every call that can throw it. | Core | error | error |
+| [result-ignored](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/result-ignored.md) | The Result of a call is checked or passed on, not dropped as a statement, after void or after await. | Core | error | error |
+| [result-unchecked](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/result-unchecked.md) | A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked. (heuristic) | Core | warning | warning |
+| [throws-doc-mismatch](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/throws-doc-mismatch.md) | A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see. | Core | error | error |
+| [catch-hides-unexpected](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/catch-hides-unexpected.md) | A catch that handles some errors with instanceof also rethrows or handles all the others. | Core | error | error |
+| [catch-misses-error](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/catch-misses-error.md) | A catch that branches with instanceof handles every error class its try can throw, or rethrows the rest; so does an error boundary's fallback. | Core | error | error |
+| [finally-can-throw](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/finally-can-throw.md) | A finally block does not call something that throws, so the error that led to it is not lost. | Core | error | error |
+| [catch-without-intent](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/catch-without-intent.md) | Experimental: on real projects it is mostly wrong; it may change or be removed. A catch that handles every error says how: it narrows, reports, or falls back; one that only logs, or calls something stateward cannot judge, and carries on is reported. (heuristic) | Add-on `catch-intent` | warning | warning |
+| [narrow-try](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/narrow-try.md) | Calls to your own code placed in a `try` after the call it is for: move them after the `try`. | Add-on `narrow-try` | warning | warning |
+| [render-throw-without-boundary](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/render-throw-without-boundary.md) | A component that can throw a known error while rendering has an error boundary above it. | Core | warning | warning |
+
+Kind: **Core** rules are on in every preset. **Coverage** rules ask your types to say more; they
+are info under `recommended` and errors under `strict`. **Add-on** rules stay off until you list
+their add-on in `addons`; the table shows their severity once it is listed. A heuristic rule
+guesses, so it is never an error unless you set it.
+
+Each rule's page says why it matters, what it catches and misses, how to fix what it finds, and its options. The pack's page: [docs/packs/errors.md](https://github.com/khoing1111/ts-stateward/blob/main/docs/packs/errors.md). Every pack's rules: [the rules index](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/README.md).
+
+<!-- /generated:rules -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stateward/plugin-errors",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "stateward rules for errors: errors are handled where they can happen.",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,6 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@stateward/core": "1.0.0"
+    "@stateward/core": "1.0.1"
   }
 }

package/dist/async-handler-unhandled.d.ts

@@ -1,7 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "async";
-export declare const asyncHandlerUnhandled: import("@stateward/core").FileRule<{
-    timers: import("@stateward/core").StringsOption;
-    ignoreProps: import("@stateward/core").StringsOption;
-}, "async">;
-//# sourceMappingURL=async-handler-unhandled.d.ts.map

package/dist/async-handler-unhandled.js

@@ -1,342 +0,0 @@
-import ts from "@stateward/core/typescript";
-import { defineRule, matchesName, option } from "@stateward/core";
-import { hasModifier, isBuiltinGlobal, scanRunning, sameFileFunction, stripParentheses, } from "./syntax.js";
-import { pathOf } from "./inference/packages.js";
-import { HEADLINE_MAX, fitted, oneLine, shorten, withExample } from "./text.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "async";
-const EXPLAIN = `# errors/async-handler-unhandled
-
-An async event handler, listener or timer callback catches its own failures, since nothing awaits it.
-
-## Why
-
-Nothing awaits an \`onClick\`, a listener or a timer callback. When an \`async\` one fails after an \`await\`, its promise rejects with no code waiting for it: the console shows an unhandled rejection, the user sees nothing, and whatever the handler was changing is left half done. A Save button whose \`await save()\` fails looks like it did nothing.
-
-## When to use it
-
-Use it in any app with async event handlers: React components, DOM listeners, timers. It is on as an error in every preset. Turn it off only if a global \`unhandledrejection\` handler is how you deal with these on purpose.
-
-## What it catches
-
-An \`async\` function written in place as:
-
-- a JSX prop named \`on\` plus a capital letter (\`onClick\`, \`onSubmit\`);
-- the listener of \`addEventListener\`;
-- the callback of \`setTimeout\`, \`setInterval\` or \`queueMicrotask\` (the \`timers\` option adds more);
-
-when it awaits outside a \`try\` with a \`catch\`, or returns a promise from \`fetch\`, \`Promise.all\` and similar, or an \`async\` function in the same file. An \`await\` in a \`catch\` or \`finally\` block is not protected by that \`try\`.
-
-### Bad
-
-\`\`\`tsx
-<button onClick={async () => {
-  await save();
-}}>Save</button>
-\`\`\`
-
-### Good
-
-\`\`\`tsx
-<button onClick={async () => {
-  try { await save(); } catch (e) { showError(e); }
-}}>Save</button>
-\`\`\`
-
-### Fix
-
-Wrap the body in \`try\` / \`catch\` and show, retry or record the failure. There is no quick fix: what to do with it is your call.
-
-## What it does not catch
-
-- A call that catches its own failure (\`await save().catch(showError)\`).
-- A promise that reports failure in its value instead of rejecting: its type has an \`unwrap()\` method and it resolves to data or an \`error\` (RTK Query's mutation and lazy-query triggers, \`await addTodo(todo)\`). \`await addTodo(todo).unwrap()\` rejects, and is reported.
-- A package function the config's \`facts\` say never fails: \`facts: { "my-client": { send: { rejects: [] } } }\`.
-- A handler passed by name (\`onClick={save}\`): only functions written in place are read.
-- A prop whose type returns a promise (\`onSave: () => Promise<void>\`): the component that declares it awaits it.
-- Other callbacks nobody awaits: \`.then\` callbacks, \`setImmediate\`, observers, \`useEffect\` callbacks.
-- A handler with no \`await\` and no promise the rule recognises.
-
-## Turn it on or off
-
-In \`stateward.config.ts\`:
-
-\`\`\`ts
-rules: { "errors/async-handler-unhandled": "off" } // or "warning"
-groups: { "errors/async": "off" } // the whole group
-rules: { "errors/async-handler-unhandled": ["error", { ignoreProps: ["onSubmit"] }] } // a prop your form library awaits
-\`\`\`
-`;
-const OPTIONS = {
-    timers: option.strings({
-        default: ["setTimeout", "setInterval", "queueMicrotask"],
-        description: "Functions whose first argument is a callback nobody awaits (add requestAnimationFrame, setImmediate…).",
-    }),
-    ignoreProps: option.strings({
-        default: [],
-        description: "JSX props whose async handler the component awaits itself, like a form library's onSubmit (globs allowed).",
-    }),
-};
-/** Objects the timers are also called on: `window.setTimeout`. */
-const TIMER_OWNERS = new Set(["window", "globalThis", "self"]);
-/** `Promise` methods that return a promise that can reject. */
-const REJECTING_PROMISES = new Set([
-    "all",
-    "allSettled",
-    "race",
-    "any",
-    "reject",
-]);
-function asyncFunction(expression) {
-    const node = stripParentheses(expression);
-    if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node))
-        return undefined;
-    if (!hasModifier(node, ts.SyntaxKind.AsyncKeyword))
-        return undefined;
-    return ts.isFunctionExpression(node) && node.asteriskToken !== undefined ? undefined : node;
-}
-function calleeName(call) {
-    const callee = stripParentheses(call.expression);
-    if (ts.isIdentifier(callee))
-        return callee.text;
-    if (!ts.isPropertyAccessExpression(callee))
-        return undefined;
-    if (callee.name.text === "addEventListener")
-        return callee.name.text;
-    const owner = stripParentheses(callee.expression);
-    return ts.isIdentifier(owner) && TIMER_OWNERS.has(owner.text) ? callee.name.text : undefined;
-}
-/** The members of a printed union at its top level: `(() => A) | undefined` is two. */
-function unionMembers(text) {
-    const members = [];
-    let depth = 0;
-    let start = 0;
-    for (let i = 0; i < text.length; i += 1) {
-        const char = text[i];
-        if (char === "(" || char === "[" || char === "{" || char === "<")
-            depth += 1;
-        else if (char === ")" ||
-            char === "]" ||
-            char === "}" ||
-            (char === ">" && text[i - 1] !== "=")) {
-            depth -= 1;
-        }
-        else if (char === "|" && depth === 0) {
-            members.push(text.slice(start, i).trim());
-            start = i + 1;
-        }
-    }
-    members.push(text.slice(start).trim());
-    return members;
-}
-/** `() => Promise<void>` or `(id: string) => PromiseLike<T>`, in parentheses or not. */
-const RETURNS_PROMISE = /^\(*\(.*\) => (?:Promise|PromiseLike)<.*>\)*$/;
-/**
- * Whether the prop an attribute sets is declared as a function that returns a promise
- * (`onSave: () => Promise<void>`, `onSave?(): Promise<void>`): the component asks for a promise
- * so that it can await it, so a failure is its to handle.
- */
-function awaitedByComponent(fn, ctx) {
-    const expected = ctx.types.contextualTypeTextOf(fn);
-    if (expected === undefined)
-        return false;
-    const present = unionMembers(expected).filter((member) => member !== "undefined" && member !== "null");
-    return present.length > 0 && present.every((member) => RETURNS_PROMISE.test(member));
-}
-/** The async function this node hands to something that never awaits it, if it does. */
-function handlerOf(node, ctx) {
-    if (ts.isJsxAttribute(node)) {
-        const name = node.name;
-        if (!ts.isIdentifier(name) || !/^on[A-Z]/.test(name.text))
-            return undefined;
-        if (matchesName(name.text, ctx.options.ignoreProps))
-            return undefined;
-        const value = node.initializer;
-        if (value === undefined || !ts.isJsxExpression(value) || value.expression === undefined) {
-            return undefined;
-        }
-        const fn = asyncFunction(value.expression);
-        return fn === undefined || awaitedByComponent(fn, ctx)
-            ? undefined
-            : { fn, name: name.text, role: "handler" };
-    }
-    if (!ts.isCallExpression(node))
-        return undefined;
-    const name = calleeName(node);
-    if (name === "addEventListener") {
-        const [, listener] = node.arguments;
-        const fn = listener === undefined ? undefined : asyncFunction(listener);
-        return fn === undefined ? undefined : { fn, name, role: "listener", call: node };
-    }
-    if (name !== undefined && ctx.options.timers.includes(name)) {
-        const [callback] = node.arguments;
-        const fn = callback === undefined ? undefined : asyncFunction(callback);
-        return fn === undefined ? undefined : { fn, name, role: "callback", call: node };
-    }
-    return undefined;
-}
-/** A call that returns a promise which can reject: `fetch`, `Promise.all`, a local async function. */
-function returnsPromise(expression, ctx) {
-    const call = stripParentheses(expression);
-    if (!ts.isCallExpression(call))
-        return false;
-    const callee = stripParentheses(call.expression);
-    if (ts.isIdentifier(callee) && callee.text === "fetch" && isBuiltinGlobal(callee, ctx)) {
-        return true;
-    }
-    if (ts.isPropertyAccessExpression(callee)) {
-        const owner = stripParentheses(callee.expression);
-        if (ts.isIdentifier(owner) &&
-            owner.text === "Promise" &&
-            REJECTING_PROMISES.has(callee.name.text) &&
-            isBuiltinGlobal(owner, ctx)) {
-            return true;
-        }
-    }
-    const declared = sameFileFunction(callee, ctx);
-    return declared !== undefined && hasModifier(declared, ts.SyntaxKind.AsyncKeyword);
-}
-/**
- * Whether the config's facts say the package function called here never fails: `rejects: []`
- * (and no `throws`). The function is named as the facts name it: its path in the package's
- * types (`Client.send`), or its own name (`send`).
- */
-function factsSayNeverRejects(call, ctx) {
-    const callee = stripParentheses(call.expression);
-    const name = ts.isPropertyAccessExpression(callee) ? callee.name : callee;
-    const symbol = ctx.types.symbolAt(name);
-    const declared = symbol && ctx.types.declarationOf(symbol);
-    if (declared === undefined || ctx.types.isOwnFile(declared.file))
-        return false;
-    const packageName = ctx.types.packageOf(declared.file);
-    const facts = packageName === undefined ? undefined : ctx.facts[packageName];
-    if (facts === undefined)
-        return false;
-    const names = pathOf(declared.node);
-    const entry = facts[names.join(".")] ?? facts[names.at(-1) ?? ""];
-    return entry?.rejects?.length === 0 && (entry.throws ?? []).length === 0;
-}
-/**
- * A promise that reports failure in its value, not by rejecting: its type has an `unwrap()`
- * method and resolves to data or an error (RTK Query's mutation and lazy-query triggers, item
- * 19), or the config's facts say the function never rejects.
- */
-function neverRejects(expression, ctx) {
-    const code = stripParentheses(expression);
-    if (ctx.types.settlesWithError(code))
-        return true;
-    return ts.isCallExpression(code) && factsSayNeverRejects(code, ctx);
-}
-/** `save().catch(showError)`: a call that handles its own failure. */
-function catchesOwnFailure(expression) {
-    const call = stripParentheses(expression);
-    if (!ts.isCallExpression(call) || call.arguments.length === 0)
-        return false;
-    const callee = stripParentheses(call.expression);
-    return ts.isPropertyAccessExpression(callee) && callee.name.text === "catch";
-}
-/** The first place the handler can fail with nothing to catch it, or undefined. */
-function unguardedFailure(fn, ctx) {
-    let found;
-    const look = (node, guarded) => {
-        if (found !== undefined || guarded)
-            return;
-        if (ts.isAwaitExpression(node) &&
-            !catchesOwnFailure(node.expression) &&
-            !neverRejects(node.expression, ctx)) {
-            found = {
-                node: node.getFirstToken(ctx.sourceFile) ?? node,
-                kind: "await",
-                code: node.expression,
-            };
-        }
-        else if (ts.isForOfStatement(node) && node.awaitModifier !== undefined) {
-            found = { node: node.awaitModifier, kind: "for-await", code: node.expression };
-        }
-        else if (ts.isReturnStatement(node) &&
-            node.expression !== undefined &&
-            returnsPromise(node.expression, ctx)) {
-            found = { node: node.expression, kind: "await", code: node.expression };
-        }
-    };
-    scanRunning(fn.body, look);
-    if (found === undefined && !ts.isBlock(fn.body) && returnsPromise(fn.body, ctx)) {
-        found = { node: fn.body, kind: "await", code: fn.body };
-    }
-    return found;
-}
-function headline(handler) {
-    return fitted(HEADLINE_MAX, (cut) => `a failure in this async \`${cut(handler.name)}\` ${handler.role} is an unhandled rejection`);
-}
-/** The developer's own code in an example is cut to this many characters. */
-const CODE_MAX = 50;
-function code(node, ctx) {
-    return shorten(oneLine(node.getText(ctx.sourceFile)), CODE_MAX);
-}
-/** The example's first and last line: the handler written where it was, with its own names. */
-function frame(handler, ctx) {
-    switch (handler.role) {
-        case "handler":
-            return { first: `${oneLine(handler.name)}={async () => {`, last: "}}" };
-        case "listener":
-        case "callback": {
-            const [before, after] = aroundFunction(handler.call, handler.fn, ctx);
-            return {
-                first: `${code(handler.call.expression, ctx)}(${before}async () => {`,
-                last: `}${after});`,
-            };
-        }
-        default: {
-            const unreachable = handler;
-            return unreachable;
-        }
-    }
-}
-/** The call's other arguments, before and after the function: `"click", ` and `, 100`. */
-function aroundFunction(call, fn, ctx) {
-    const index = call.arguments.findIndex((argument) => stripParentheses(argument) === fn);
-    const texts = call.arguments.map((argument) => code(argument, ctx));
-    const before = texts.slice(0, index).map((text) => `${text}, `);
-    const after = texts.slice(index + 1).map((text) => `, ${text}`);
-    return [before.join(""), after.join("")];
-}
-function hint(handler, failure, ctx) {
-    const { first, last } = frame(handler, ctx);
-    const failing = failure.kind === "await"
-        ? `await ${code(failure.code, ctx)};`
-        : `for await (const item of ${code(failure.code, ctx)}) { … }`;
-    return withExample(`nothing awaits the ${handler.role}, so catch inside it:`, [
-        first,
-        `  try { ${failing} } catch (e) { showError(e); }`,
-        last,
-    ]);
-}
-export const asyncHandlerUnhandled = defineRule({
-    kind: "file",
-    meta: {
-        description: "An async event handler, listener or timer callback catches its own failures, since nothing awaits it.",
-        defaultSeverity: "error",
-        tier: "core",
-        group: GROUP,
-        options: OPTIONS,
-        explain: EXPLAIN,
-    },
-    check(ctx) {
-        const visit = (node) => {
-            const handler = handlerOf(node, ctx);
-            if (handler !== undefined) {
-                const failure = unguardedFailure(handler.fn, ctx);
-                if (failure !== undefined) {
-                    ctx.report({
-                        node: failure.node,
-                        message: headline(handler),
-                        hint: hint(handler, failure, ctx),
-                    });
-                }
-            }
-            ts.forEachChild(node, visit);
-        };
-        visit(ctx.sourceFile);
-    },
-});
-//# sourceMappingURL=async-handler-unhandled.js.map

package/dist/exhaustive-catch.d.ts

@@ -1,6 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "catch";
-export declare const exhaustiveCatch: import("@stateward/core").ProjectRule<import("./inference/summary.js").ThrowsSummary, {
-    ignoreClasses: import("@stateward/core").StringsOption;
-}, "catch">;
-//# sourceMappingURL=exhaustive-catch.d.ts.map

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