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

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,57 @@ 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/narrow-try"],
+```
+
+- `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 | Why it matters | Kind | `recommended` | `strict` |
+| --- | --- | --- | --- | --- | --- |
+| [must-handle-error](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/must-handle-error.md) | a call that can throw an error marked `@mustHandle`, with no code that handles or passes it on | An error marked `@mustHandle` needs a decision at each call, such as a message to the user; a call that neither catches it nor passes it on lets it reach the top. | Core | error | error |
+| [result-ignored](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/result-ignored.md) | a `Result` dropped as a statement, after `void` or after `await` | A `Result` dropped as a statement discards its error, so a failed call looks the same as a successful one. | Core | error | error |
+| [result-unchecked](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/result-unchecked.md) | a call that fails in its value (an RTK Query trigger, a Result) used as if it had worked (guess) | A call that returns its failure instead of throwing never reaches the `catch`; without a check, the code after it runs as if the call worked. | Core | warning | warning |
+| [throws-doc-mismatch](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/throws-doc-mismatch.md) | a `@throws` tag that lists an error the function cannot throw, or misses one it can | Callers decide what to catch from `@throws`: a class it omits reaches them unhandled, and a class listed in excess asks them to handle a case that cannot happen. | 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 error classes with `instanceof` and ignores the rest | A `catch` that tests some error classes and has no last branch ignores every other error, bugs included; rethrowing the rest keeps them visible. | 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 on error classes but misses one its `try` can throw | An error class the `try` can throw and the `catch` does not test goes to the generic branch, or is ignored; a branch for it, or a rethrow, handles it explicitly. | Core | error | error |
+| [finally-can-throw](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/finally-can-throw.md) | a `finally` that calls something that can throw and replace the original error | An error thrown in `finally` replaces the error that was already thrown, so the report names the cleanup instead of the original cause. | Core | error | error |
+| [narrow-try](https://github.com/khoing1111/ts-stateward/blob/main/docs/rules/errors/narrow-try.md) | calls to your own code inside a `try` after the call it is for, so their bugs look like its failure | A bug in code inside a `try` meant for another call is caught and reported as that call's failure; moving the code after the `try` keeps the two apart. | 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, with no error boundary above it | An error thrown while rendering, with no error boundary above the component, unmounts the whole React tree and leaves a blank page. | Core | warning | warning |
+
+**Core** rules are on in every preset. **Coverage** rules point at code whose types do not say
+enough for stateward to check it; 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 rule marked (guess) judges from patterns in the code, not only from types, so
+it can be wrong and is never an error unless you make it one.
+
+Each rule's page shows an example with what stateward prints for it, the fix, why it matters, what it misses, 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/dist/catch-hides-unexpected.js

@@ -6,71 +6,66 @@ import { codeList, fitted, oneLine, withExample } from "./text.js";
 export const GROUP = "catch";
 const EXPLAIN = `# errors/catch-hides-unexpected
 
-A catch that handles some errors with instanceof also rethrows or handles all the others.
-
-## Why
-
-A \`catch\` that handles \`NotFoundError\` and \`AuthError\` with \`instanceof\`, and has no last branch, silently drops every other error: a bug, a network failure, a string someone threw. \`save(order)\` fails with a \`TypeError\`, neither branch matches, and the code carries on as if the order was saved.
-
-## When to use it
-
-Use it in any code that catches by class. It is on as an error in every preset; keep it on. It needs no knowledge of what the \`try\` throws, so it works even where \`errors/catch-misses-error\` cannot see.
-
-## What it catches
-
-A \`catch (e)\` with an \`if\` / \`else if\` chain or \`switch (true)\` that tests \`e instanceof X\`, and no branch for the other errors. It is fine when:
-
-- a last \`else\` or \`default\` does something: rethrows, wraps the error with \`{ cause: e }\`, or handles it;
-- any statement follows the chain in the \`catch\`, since it runs for every error.
-
-### Bad
-
-\`\`\`ts
-try {
-  await save(order);
-} catch (e) {
-  if (e instanceof NotFoundError) {
-    showMissing();
-  } else if (e instanceof AuthError) {
-    redirectToLogin();
+A \`catch\` that tests some error classes and has no last branch ignores every other error, bugs included; rethrowing the rest keeps them visible.
+
+\`\`\`ts example-bad
+class NotFoundError extends Error {}
+class AuthError extends Error {}
+
+declare function save(order: string): Promise<void>;
+
+export async function submit(order: string, show: (text: string) => void): Promise<void> {
+  try {
+    await save(order);
+  } catch (e) {
+    if (e instanceof NotFoundError) {
+      show("This order no longer exists.");
+    } else if (e instanceof AuthError) {
+      show("Please sign in again.");
+    }
   }
 }
 \`\`\`
 
-### Good
+End the chain with a branch for every other error, which rethrows it or handles it:
 
-\`\`\`ts
-try {
-  await save(order);
-} catch (e) {
-  if (e instanceof NotFoundError) {
-    showMissing();
-  } else if (e instanceof AuthError) {
-    redirectToLogin();
-  } else {
-    throw e;
+\`\`\`ts example-good
+class NotFoundError extends Error {}
+class AuthError extends Error {}
+
+declare function save(order: string): Promise<void>;
+
+export async function submit(order: string, show: (text: string) => void): Promise<void> {
+  try {
+    await save(order);
+  } catch (e) {
+    if (e instanceof NotFoundError) {
+      show("This order no longer exists.");
+    } else if (e instanceof AuthError) {
+      show("Please sign in again.");
+    } else {
+      throw e;
+    }
   }
 }
 \`\`\`
 
-### Fix
+A quick fix adds \`else { throw e; }\` to an \`if\` chain. For a \`switch (true)\`, add \`default: throw e;\` yourself; the message shows it. Wrapping the error with \`{ cause: e }\`, or any statement after the chain, counts too, since it runs for every error.
 
-A quick fix adds \`else { throw e; }\` to an \`if\` chain. For a \`switch (true)\`, add \`default: throw e;\` yourself; the message shows it.
+## Why it matters
+
+A \`catch\` that handles \`NotFoundError\` and \`AuthError\` and has no last branch ignores every other error: a bug, a network failure, a string someone threw. \`save(order)\` fails with a \`TypeError\`, neither branch matches, and the code carries on as if the order was saved. The rule needs no knowledge of what the \`try\` throws, so it works even where \`errors/catch-misses-error\` cannot see.
 
 ## What it does not catch
 
-- A chain that tests another value, or tests other than \`instanceof\`.
+- A chain that tests another value, or tests with something other than \`instanceof\`.
 - A \`catch\` with no parameter, or a destructured one.
-- A last \`else\` that does something but still ignores the error (\`else { showGenericError(); }\`): it counts as handling the rest, unless you set \`restUsesError\` (below). \`errors/catch-misses-error\` looks at what that \`else\` does with the error.
-- A \`catch\` with no \`instanceof\` chain that ignores the error: that is \`errors/catch-without-intent\`.
+- A last \`else\` that does something but still ignores the error (\`else { showGenericError(); }\`): it counts as handling the rest, unless you set \`restUsesError\`. \`errors/catch-misses-error\` looks at what that \`else\` does with the error.
 
 ## Turn it on or off
 
-In \`stateward.config.ts\`:
-
 \`\`\`ts
 rules: { "errors/catch-hides-unexpected": "off" } // or "warning"
-groups: { "errors/catch": "off" } // the whole group
 rules: { "errors/catch-hides-unexpected": ["error", { restUsesError: true }] } // the last branch must use the error
 \`\`\`
 `;
@@ -155,23 +150,16 @@ function mentions(nodes, variable) {
     return nodes.some(visit);
 }
 function ignoringHeadline(classes, variable) {
-    return fitted((cut) => `errors other than ${codeList(classes, cut)} are handled here without ever using \`${variable}\``);
+    return fitted((cut) => `\`catch\` handles errors other than ${codeList(classes, cut)} without looking at \`${variable}\``);
 }
 function headline(classes) {
-    return fitted((cut) => `errors other than ${codeList(classes, cut)} are silently swallowed here`);
+    return fitted((cut) => `\`catch\` ignores errors other than ${codeList(classes, cut)}`);
 }
 function hint(dispatch, variable) {
     if (dispatch.kind === "switch") {
-        return withExample("end the switch with a case for the rest:", [
-            "default:",
-            `  throw ${variable};`,
-        ]);
+        return withExample("end the switch with a case that rethrows the rest, so they reach the caller:", ["default:", `  throw ${variable};`]);
     }
-    return withExample("end the chain with a branch for the rest:", [
-        "} else {",
-        `  throw ${variable};`,
-        "}",
-    ]);
+    return withExample("end the chain with a branch that rethrows the rest, so they reach the caller:", ["} else {", `  throw ${variable};`, "}"]);
 }
 /** The whitespace at the start of the line that holds `position`. */
 function indentationAt(position, text) {
@@ -241,7 +229,8 @@ function checkCatch(clause, ctx) {
 export const catchHidesUnexpected = defineRule({
     kind: "file",
     meta: {
-        description: "A catch that handles some errors with instanceof also rethrows or handles all the others.",
+        description: "A `catch` that tests some error classes and has no last branch ignores every other error, bugs included; rethrowing the rest keeps them visible.",
+        summary: "a `catch` that handles some error classes with `instanceof` and ignores the rest",
         defaultSeverity: "error",
         tier: "core",
         group: GROUP,

package/dist/catch-misses-error.js

@@ -8,94 +8,83 @@ import { codeList, fitted, withExample } from "./text.js";
 export const GROUP = "catch";
 const EXPLAIN = `# errors/catch-misses-error
 
-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.
+An error class the \`try\` can throw and the \`catch\` does not test goes to the generic branch, or is ignored; a branch for it, or a rethrow, handles it explicitly.
 
-## Why
+\`\`\`ts example-bad
+class AuthError extends Error {}
+class RateLimitError extends Error {}
 
-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 (also on a function declared without a body, such as \`declare function\` or a \`.d.ts\` of your own), 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
+function send(text: string, remaining: number): void {
+  if (remaining === 0) throw new RateLimitError("slow down");
+  if (text === "") throw new AuthError("signed out");
+}
 
-\`\`\`ts
-// api.send can throw RateLimitError and AuthError.
-try {
-  await api.send(message);
-} catch (e) {
-  if (e instanceof AuthError) {
-    redirectToLogin();
-  } else {
-    showGenericError();
+export function post(text: string, remaining: number, show: (text: string) => void): void {
+  try {
+    send(text, remaining);
+  } catch (e) {
+    if (e instanceof AuthError) {
+      show("Please sign in again.");
+    } else {
+      show("Something went wrong.");
+    }
   }
 }
 \`\`\`
 
-### Good
+Add a branch for each class the message names, and rethrow what you do not handle:
 
-\`\`\`ts
-try {
-  await api.send(message);
-} catch (e) {
-  if (e instanceof AuthError) {
-    redirectToLogin();
-  } else if (e instanceof RateLimitError) {
-    retryLater();
-  } else {
-    throw e;
+\`\`\`ts example-good
+class AuthError extends Error {}
+class RateLimitError extends Error {}
+
+function send(text: string, remaining: number): void {
+  if (remaining === 0) throw new RateLimitError("slow down");
+  if (text === "") throw new AuthError("signed out");
+}
+
+export function post(text: string, remaining: number, show: (text: string) => void): void {
+  try {
+    send(text, remaining);
+  } catch (e) {
+    if (e instanceof AuthError) {
+      show("Please sign in again.");
+    } else if (e instanceof RateLimitError) {
+      show("Too many messages; try again in a minute.");
+    } else {
+      throw e;
+    }
   }
 }
 \`\`\`
 
-### Fix
+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.
+
+## Why it matters
 
-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.
+A \`catch\` that checks \`e instanceof AuthError\` says which errors it expects. When \`send\` can also throw \`RateLimitError\`, a rate limit falls into the generic branch: the user sees "Something went wrong", and the wait that would have worked never happens. The rule lists, at the \`catch\`, the classes it leaves out, so a new error class reaches every place that has to decide about it.
 
 ## 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/catch-hides-unexpected\` 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"\`).
+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; and one that uses the error (\`setError(e)\`, logging it, reading a property) handles the rest. An \`else\` that ignores the error, like \`show("Something went wrong.")\` above, does not. The rule is silent on:
 
-## Error boundary fallbacks
+- 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. The message notes each call it could not see into, with the reason, and \`errors/catch-hides-unexpected\` makes sure the rest is not dropped;
+- a class whose \`extends\` cannot be followed, or a branch whose test is not only \`instanceof\` (\`e instanceof A && e.code === 1\`, \`isAbort(e)\`, \`e.name === "AbortError"\`): 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.
 
-An error boundary's fallback is a catch too: what the components below the boundary throw while rendering and in their effects, down to the next boundary, is its \`try\` (the hover on the boundary lists it). A fallback that branches with \`if\` / \`else if\`, \`switch (true)\` or \`? :\` on \`error instanceof X\` is checked the same way: each class the boundary can catch has a branch, or a branch for the rest does more than return \`null\` or nothing. The fallback is react-error-boundary's \`FallbackComponent\`, \`fallbackRender\` or \`onError\`, or a boundary class's \`getDerivedStateFromError\`.
+## Getting the best from it
 
-\`\`\`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 <p>Something went wrong: {String(error)}</p>; // a branch for the rest
-}
-\`\`\`
+What the \`try\` can throw is worked out from \`throw new X(…)\` in the functions it calls, in any file; their \`@throws {X}\` tags (also on a function with no body, such as \`declare function\` or a \`.d.ts\` of your own); the built-ins above; and the packages it calls (\`stateward deps\` shows how well each package's errors are known). So throw classes, not strings, and document what a function throws with \`@throws\`. Declare a package's errors under \`facts\` in the config: \`facts: { "config-lib": { load: { throws: ["ConfigError"] } } }\`.
 
-A fallback that does not branch on \`instanceof\`, or whose tests are not only \`instanceof\`, is left alone; so is one passed as anything other than a function written in place or the name of a function of the project.
+An error boundary's fallback is checked the same way: what the components below the boundary throw while rendering and in their effects, down to the next boundary, is its \`try\` (the hover on the boundary lists it). A fallback (react-error-boundary's \`FallbackComponent\`, \`fallbackRender\` or \`onError\`, or a boundary class's \`getDerivedStateFromError\`) that branches with \`if\` / \`else if\`, \`switch (true)\` or \`? :\` on \`error instanceof X\` needs a branch for each class the boundary can catch, or a branch for the rest that does more than return \`null\` or nothing. A fallback that does not branch on \`instanceof\`, whose tests are not only \`instanceof\`, or that is passed as anything other than a function written in place or the name of one of your functions, is left alone.
 
 ## Turn it on or off
 
-In \`stateward.config.ts\`:
-
 \`\`\`ts
 rules: { "errors/catch-misses-error": "off" } // or "warning"
-groups: { "errors/catch": "off" } // the whole group
-facts: { "config-lib": { load: { throws: ["ConfigError"] } } } // declare a package's errors
 rules: { "errors/catch-misses-error": ["error", { ignoreClasses: ["SyntaxError"] }] } // never require a branch for these
 \`\`\`
 `;
@@ -103,8 +92,8 @@ rules: { "errors/catch-misses-error": ["error", { ignoreClasses: ["SyntaxError"]
 const MAX_UNKNOWN_NOTES = 2;
 function headline(names, via) {
     return fitted((cut) => {
-        const source = via === undefined ? "its `try` block" : `\`${cut(via)}\``;
-        return `this catch does not handle ${codeList(names, cut)}, which ${source} can throw`;
+        const source = via === undefined ? "thrown in its `try` block" : `from \`${cut(via)}\``;
+        return `\`catch\` does not handle ${codeList(names, cut)} ${source}`;
     });
 }
 /** The fix, in the shape of the catch: a `case`, an `else if`, or an `if` for a chain without `else`. */
@@ -166,7 +155,7 @@ function report(seen, classes, ignored, emit) {
     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`,
+            message: `\`${source.text}\` may also throw errors that are not known (${source.reason}); rethrow what you do not handle`,
         });
     }
     emit({
@@ -179,7 +168,8 @@ function report(seen, classes, ignored, emit) {
 export const catchMissesError = defineRule({
     kind: "project",
     meta: {
-        description: "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.",
+        description: "An error class the `try` can throw and the `catch` does not test goes to the generic branch, or is ignored; a branch for it, or a rethrow, handles it explicitly.",
+        summary: "a `catch` that branches on error classes but misses one its `try` can throw",
         defaultSeverity: "error",
         tier: "core",
         group: GROUP,

package/dist/finally-can-throw.js

@@ -6,70 +6,62 @@ import { fitted, oneLine, withExample } from "./text.js";
 export const GROUP = "catch";
 const EXPLAIN = `# errors/finally-can-throw
 
-A finally block does not call something that throws, so the error that led to it is not lost.
+An error thrown in \`finally\` replaces the error that was already thrown, so the report names the cleanup instead of the original cause.
 
-## Why
+\`\`\`ts example-bad
+declare function upload(file: string): Promise<void>;
+declare function restore(state: unknown): void;
 
-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);
+export async function send(file: string, saved: string): Promise<void> {
+  try {
+    await upload(file);
+  } finally {
+    restore(JSON.parse(saved));
+  }
 }
 \`\`\`
 
-### Good
+Give the cleanup its own \`try\` / \`catch\`, or move it out of the \`finally\`:
 
-\`\`\`ts
-try {
-  await upload(file);
-} finally {
+\`\`\`ts example-good
+declare function upload(file: string): Promise<void>;
+declare function restore(state: unknown): void;
+declare function report(error: unknown): void;
+
+export async function send(file: string, saved: string): Promise<void> {
   try {
-    restore(JSON.parse(saved));
-  } catch (e) {
-    report(e);
+    await upload(file);
+  } finally {
+    try {
+      restore(JSON.parse(saved));
+    } catch (e) {
+      report(e);
+    }
   }
 }
 \`\`\`
 
-### Fix
+There is no quick fix: what the cleanup should do when it fails is your call.
+
+## Why it matters
 
-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.
+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.
 
 ## 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.
+It looks, in a \`finally\` and outside a nested \`try\` that has a \`catch\`, for a \`throw\`; a call to a built-in that throws (\`JSON.parse\`, \`JSON.stringify\` on circular values, \`new URL\`, \`decodeURIComponent\`, \`decodeURI\`, \`structuredClone\`, \`atob\`); or a call to a function in the same file that throws outside its own \`try\` / \`catch\` (an \`async\` one when the call is awaited). It reports the first of these in each \`finally\`. It does not see:
+
+- functions from other files, and package calls;
+- other built-ins, such as \`fetch\` or \`BigInt\`;
+- a function that throws only inside its own \`try\` / \`catch\`;
+- a second throwing call in the same \`finally\`.
 
 ## Turn it on or off
 
-In \`stateward.config.ts\`:
+Turn it off only if your cleanup's own errors are meant to win:
 
 \`\`\`ts
 rules: { "errors/finally-can-throw": "off" } // or "warning"
-groups: { "errors/finally": "off" } // the whole group
 rules: { "errors/finally-can-throw": ["error", { severities: { builtin: "warning" } }] } // built-ins only warn
 \`\`\`
 `;
@@ -108,13 +100,13 @@ const KINDS = {
 };
 function causeOf(node, awaited, ctx) {
     if (ts.isThrowStatement(node))
-        return { node, subject: () => "this `throw` runs", kind: "throw" };
+        return { node, subject: () => "", 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 { node, subject: () => `\`new ${callee.text}(…)\` can throw`, kind: "builtin" };
         }
         return undefined;
     }
@@ -122,7 +114,7 @@ function causeOf(node, awaited, ctx) {
         return undefined;
     const builtin = builtinCall(node, ctx);
     if (builtin !== undefined) {
-        return { node, subject: () => `\`${builtin}(…)\` throws here`, kind: "builtin" };
+        return { node, subject: () => `\`${builtin}(…)\` can throw`, kind: "builtin" };
     }
     const declared = sameFileFunction(node.expression, ctx);
     if (declared === undefined || !throwsUncaught(declared))
@@ -131,16 +123,14 @@ function causeOf(node, awaited, ctx) {
     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" };
+    return { node, subject: (cut) => `\`${cut(callee)}(…)\` can throw`, kind: "own-function" };
 }
 function headline(cause) {
-    return fitted((cut) => `if ${cause.subject(cut)}, the error that led to this finally is lost`);
+    if (cause.kind === "throw")
+        return "a `throw` in `finally` replaces the original error";
+    return fitted((cut) => `a throw in \`finally\` replaces the original error: ${cause.subject(cut)}`);
 }
-const HINT = withExample("move it out of finally, or catch it inside:", [
-    "finally {",
-    "  try { cleanup(); } catch (e) { report(e); }",
-    "}",
-]);
+const HINT = withExample("catch it inside the `finally`, or move it out, so the original error is kept:", ["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;
@@ -158,7 +148,8 @@ function checkFinally(block, shown, ctx) {
 export const finallyCanThrow = defineRule({
     kind: "file",
     meta: {
-        description: "A finally block does not call something that throws, so the error that led to it is not lost.",
+        description: "An error thrown in `finally` replaces the error that was already thrown, so the report names the cleanup instead of the original cause.",
+        summary: "a `finally` that calls something that can throw and replace the original error",
         defaultSeverity: "error",
         tier: "core",
         group: GROUP,

package/dist/inference/format.d.ts

@@ -4,10 +4,10 @@ import type { ClassFact } from "./summary.js";
 export declare function className(id: string, classes: ReadonlyMap<string, ClassFact>): string;
 /** The name an `instanceof` test or a `@throws` tag uses for the class. */
 export declare function catchName(id: string, classes: ReadonlyMap<string, ClassFact>): string;
-/** `others stateward cannot see (from a: why; b: why; and 3 more)`. */
+/** `others not known (from a: why; b: why; and 3 more)`. */
 export declare function unknownText(sources: readonly Source[], more: boolean): string;
 /**
- * `ParseError | ZodError (zod 3.23.8: declared) | others stateward cannot see (from …)`, or "" for an empty set: a class
+ * `ParseError | ZodError (zod 3.23.8: declared) | others not known (from …)`, or "" for an empty set: a class
  * known from a package's facts names where they come from.
  */
 export declare function thrownText(thrown: Thrown, classes: ReadonlyMap<string, ClassFact>): string;
@@ -19,7 +19,7 @@ export declare function thrownText(thrown: Thrown, classes: ReadonlyMap<string,
 export declare function rejectsShown(result: Result): Thrown;
 /**
  * The hover's lines: `throws: …` for what a call throws, `rejects: …` for what its promise
- * rejects with, `throws nothing stateward can see` when both are empty.
+ * rejects with, `throws nothing known` when both are empty.
  */
 export declare function resultLines(result: Result, classes: ReadonlyMap<string, ClassFact>): string[];
 //# sourceMappingURL=format.d.ts.map