@stateward/plugin-errors 1.0.1 → 1.1.0

package/dist/inference/format.js

@@ -21,15 +21,15 @@ function sourceKey(source) {
 function sourceText(source) {
     return `${source.text}: ${source.reason}`;
 }
-/** `others stateward cannot see (from a: why; b: why; and 3 more)`. */
+/** `others not known (from a: why; b: why; and 3 more)`. */
 export function unknownText(sources, more) {
     const listed = sources.slice(0, MAX_LISTED_SOURCES).map(sourceText);
     const rest = sources.length - listed.length;
     const tail = rest > 0 || more ? [`and ${String(rest)}${more ? "+" : ""} more`] : [];
-    return `others stateward cannot see (from ${[...listed, ...tail].join("; ")})`;
+    return `others not known (from ${[...listed, ...tail].join("; ")})`;
 }
 /**
- * `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 function thrownText(thrown, classes) {
@@ -58,7 +58,7 @@ export function rejectsShown(result) {
 }
 /**
  * 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 function resultLines(result, classes) {
     const throws = thrownText(result.throws, classes);
@@ -67,6 +67,6 @@ export function resultLines(result, classes) {
         ...(throws === "" ? [] : [`throws: ${throws}`]),
         ...(rejects === "" ? [] : [`rejects: ${rejects}`]),
     ];
-    return lines.length === 0 ? ["throws nothing stateward can see"] : lines;
+    return lines.length === 0 ? ["throws nothing known"] : lines;
 }
 //# sourceMappingURL=format.js.map

package/dist/inference/solve.js

@@ -304,7 +304,7 @@ function declared(entry) {
             addSource(made, {
                 ...locationOf(entry.file, item.at),
                 text: item.name,
-                reason: "`@throws` names no class stateward can find",
+                reason: "`@throws` names a class that is not found",
             });
         }
     }

package/dist/inference/summarize.d.ts

@@ -9,7 +9,7 @@ export declare const REASON: {
     readonly dynamic: "dynamic call";
     readonly thrownValue: "a thrown value of unknown class";
     readonly madeError: "an error made by a call";
-    readonly promise: "a promise stateward cannot follow";
+    readonly promise: "a promise that is not followed";
     readonly heldPromise: "promise held in a variable";
 };
 /** Why a callback handed to a call of the platform that is not in the tables adds `unknown`. */

package/dist/inference/summarize.js

@@ -10,7 +10,7 @@ export const REASON = {
     dynamic: "dynamic call",
     thrownValue: "a thrown value of unknown class",
     madeError: "an error made by a call",
-    promise: "a promise stateward cannot follow",
+    promise: "a promise that is not followed",
     heldPromise: "promise held in a variable",
 };
 /** Why a callback handed to a call of the platform that is not in the tables adds `unknown`. */
@@ -345,7 +345,7 @@ export function summarizeThrows(ctx, packages) {
             ...doc.entries.map((entry) => entry.id === null
                 ? {
                     k: "unknown",
-                    reason: "`@throws` names no class stateward can find",
+                    reason: "`@throws` names a class that is not found",
                     text: entry.name,
                     at: span,
                 }

package/dist/must-handle-error.js

@@ -12,85 +12,76 @@ import { fitted, oneLine, shorten, withExample } from "./text.js";
 export const GROUP = "callers";
 const EXPLAIN = `# errors/must-handle-error
 
-An error class marked \`@mustHandle\` is named in a \`catch\` or passed on with \`@throws\` by every call that can throw it.
+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.
 
-## Why
-
-Some errors need a decision from the code that meets them. A declined card is not a crash: the user should be told and offered another card. If \`checkout\` lets \`PaymentDeclinedError\` fall into a generic \`catch\` that shows "Something went wrong", the user never learns why, and tries the same card again. TypeScript cannot say which errors a call can throw, so nothing reminds the author of \`checkout\` that this one needs handling.
-
-Write the decision once, on the class:
-
-\`\`\`ts
+\`\`\`ts example-bad
 /** @mustHandle Tell the user the card was declined and let them pick another card. */
 export class PaymentDeclinedError extends Error {}
-\`\`\`
-
-and stateward checks every call that can throw it, in any file, and shows your sentence where it is missed.
-
-## When to use it
 
-For the few errors that callers must act on: a declined payment, an expired session, a conflict the user must resolve. It is a core rule, an error in every preset, and reports nothing until you mark a class: you choose, error by error, what is checked. For new code, returning the failure as a value (a \`Result\` or a union) makes TypeScript itself check it; \`@mustHandle\` is for errors that are already thrown.
-
-## What it catches
-
-A call that can throw or reject with a marked class (or a class that extends it), when nothing between the call and the function's callers handles it on purpose:
+function pay(amount: number): string {
+  if (amount > 100) throw new PaymentDeclinedError("insufficient funds");
+  return "receipt-1";
+}
 
-- **handled on purpose:** a \`catch\` around the call has a branch \`e instanceof PaymentDeclinedError\` (or a marked class it extends) that does not rethrow it; a guard \`if (!(e instanceof PaymentDeclinedError)) throw e;\` followed by the handling, a \`?:\` or \`&&\` that tests \`e instanceof PaymentDeclinedError\`, and a \`switch (true)\` case count the same;
-- **handed to a helper that handles it:** the \`catch\` passes its error to a function of yours whose first statement is \`if (error instanceof PaymentDeclinedError) …\` (or a marked class it extends) and does not rethrow it there, like \`showPaymentError(e)\`; only that function is read, not the ones it calls;
-- **handled where it is called:** a helper declared inside a function and called only inside a handling \`try\` is judged at those calls, not in its own body;
-- **passed on on purpose:** the function's JSDoc has \`@throws {PaymentDeclinedError}\` (or a marked class it extends); then its own callers must handle it, and are checked the same way. An \`await\`ed promise counts as a call.
+export function reorder(amount: number): string {
+  return pay(amount);
+}
+\`\`\`
 
-Everything else is reported at the call: no \`try\`, a \`catch\` that treats every error alike (no branch, or only \`instanceof Error\`), a \`catch\` that rethrows everything (\`report(e); throw e;\`) in a function without \`@throws\`. The message gives your sentence from \`@mustHandle\` and links to the tag.
+Name the class in a \`catch\` and do what its sentence says:
 
-### Bad
+\`\`\`ts example-good
+/** @mustHandle Tell the user the card was declined and let them pick another card. */
+export class PaymentDeclinedError extends Error {}
 
-\`\`\`ts
-export async function reorder(order: Order, card: Card): Promise<Receipt> {
-  return await pay(order, card); // pay can throw PaymentDeclinedError
+function pay(amount: number): string {
+  if (amount > 100) throw new PaymentDeclinedError("insufficient funds");
+  return "receipt-1";
 }
-\`\`\`
 
-### Good
-
-\`\`\`ts
-export async function reorder(order: Order, card: Card): Promise<ReorderResult> {
+export function reorder(amount: number): { kind: "paid"; receipt: string } | { kind: "declined" } {
   try {
-    return { kind: "paid", receipt: await pay(order, card) };
+    return { kind: "paid", receipt: pay(amount) };
   } catch (e) {
-    if (e instanceof PaymentDeclinedError) return { kind: "declined", reason: e.reason };
+    if (e instanceof PaymentDeclinedError) return { kind: "declined" };
     throw e;
   }
 }
 \`\`\`
 
-or pass it on, so the caller of \`reorder\` decides:
+Or pass it on with \`/** @throws {PaymentDeclinedError} */\` on \`reorder\`, so its callers decide (and are checked the same way); the quick fix "Pass it on" adds that tag, creating the JSDoc when there is none. What to do in a \`catch\` branch is your call, so no fix writes one. Or change the throwing function to return the failure as a value.
 
-\`\`\`ts
-/** @throws {PaymentDeclinedError} */
-export async function reorder(order: Order, card: Card): Promise<Receipt> {
-  return await pay(order, card);
-}
-\`\`\`
+## Why it matters
 
-### Fix
+Some errors need a decision from the code that meets them. A declined card is not a crash: the user should be told and offered another card. If \`reorder\` lets \`PaymentDeclinedError\` fall into a generic \`catch\` that shows "Something went wrong", the user never learns why, and tries the same card again. TypeScript cannot say which errors a call can throw, so nothing reminds the author of \`reorder\` that this one needs handling. With \`@mustHandle\`, you write the decision once, on the class; stateward checks every call that can throw it, in any file, and shows your sentence where it is missed.
 
-Name the class in the \`catch\` and do what the sentence says, pass it on with \`@throws\`, or change the throwing function to return the failure as a value. The quick fix "Pass it on" adds \`@throws\` to the function's JSDoc (and creates the JSDoc when there is none); what to do in a \`catch\` branch is your call, so there is no fix that writes one.
+## When it says “not checked”
+
+Where it cannot follow the error, it says so, and \`stateward check\` lists these places (not only counts them), since you asked for this error: a callback whose caller it cannot see (an event handler, a function passed to another), a \`catch\` that tests a class whose \`extends\` it cannot follow, a test inside the called function it cannot read. A \`@mustHandle\` on a type alias or an interface (plain-object errors such as \`{ kind: "declined" }\`) is not checked yet, and is reported the same way.
 
 ## What it does not catch
 
-- Where stateward cannot follow the error, it says so, and these places are listed by \`stateward check\` (not only counted), since you asked for this error: a callback whose caller it cannot see (an event handler, a function passed to another), a \`catch\` that tests a class whose \`extends\` it cannot follow, a test inside the called function it cannot read.
-- \`promise.catch(handler)\`: the handler is taken to handle every rejection.
-- A \`@mustHandle\` on a type alias or an interface (plain-object errors such as \`{ kind: "declined" }\`): not checked yet, and reported as a place not checked. That is the next step.
-- Errors from packages: only classes of your project can be marked.
-- A \`throw new PaymentDeclinedError()\` itself: the function that throws it is where it starts; its callers are checked.
+A call that can throw or reject with a marked class (or one that extends it) is fine when it is:
 
-## Turn it on or off
+- **handled on purpose**: a \`catch\` around it has a branch \`e instanceof PaymentDeclinedError\` (or a marked class it extends) that does not rethrow it. A guard \`if (!(e instanceof PaymentDeclinedError)) throw e;\` followed by the handling, a \`?:\` or \`&&\` that tests it, and a \`switch (true)\` case count the same;
+- **handed to a helper that handles it**: the \`catch\` passes its error to a function of yours whose first statement is \`if (error instanceof PaymentDeclinedError) …\` and does not rethrow it there (only that function is read, not the ones it calls);
+- **handled where it is called**: a helper declared inside a function and called only inside a handling \`try\` is judged at those calls;
+- **passed on on purpose**: the function's JSDoc has \`@throws {PaymentDeclinedError}\`. An awaited promise counts as a call.
+
+Everything else is reported at the call: no \`try\`, a \`catch\` that treats every error alike (no branch, or only \`instanceof Error\`), or one that rethrows everything (\`report(e); throw e;\`) in a function without \`@throws\`. The rule is silent on:
+
+- \`promise.catch(handler)\`: the handler is taken to handle every rejection;
+- errors from packages: only classes of your project can be marked;
+- the \`throw new PaymentDeclinedError()\` itself: that is where it starts; its callers are checked.
 
-In \`stateward.config.ts\`:
+## Getting the best from it
+
+Mark only the few errors that callers must act on: a declined payment, an expired session, a conflict the user must resolve. The rule reports nothing until you mark a class, so you choose, error by error, what is checked. Write the sentence for the person who meets the error: it is what the finding shows. For new code, returning the failure as a value (a \`Result\` or a union) lets TypeScript itself check it; \`@mustHandle\` is for errors that are already thrown.
+
+## Turn it on or off
 
 \`\`\`ts
 rules: { "errors/must-handle-error": "off" } // or "warning"
-groups: { "errors/catch": "off" } // the whole group
 \`\`\`
 `;
 const TAG = "mustHandle";
@@ -530,13 +521,13 @@ function hintLine(met, name, model) {
         const passOn = fn === undefined ? undefined : `\`@throws {${cut(tag)}}\``;
         if (by?.fate === "generic") {
             return passOn === undefined || fn === undefined
-                ? `name \`${cut(name)}\` in this \`catch\`, which treats every error alike:`
-                : `name it in this \`catch\`, which treats every error alike, or rethrow it and add ${passOn} to \`${cut(fn)}\`:`;
+                ? `name \`${cut(name)}\` in the \`catch\`, which treats every error alike:`
+                : `name it in the \`catch\`, which treats every error alike, or rethrow it and add ${passOn} to \`${cut(fn)}\`:`;
         }
         if (by?.fate === "rethrown") {
             return passOn === undefined || fn === undefined
-                ? "this `catch` passes it on and nothing above it handles it: handle it in the `catch`:"
-                : `this \`catch\` passes it on: add ${passOn} to \`${cut(fn)}\`, or handle it in the \`catch\`:`;
+                ? "handle it in the `catch`: the `catch` passes it on, and nothing above handles it:"
+                : `add ${passOn} to \`${cut(fn)}\`, or handle it in the \`catch\`: the \`catch\` passes it on:`;
         }
         return passOn === undefined || fn === undefined
             ? "name it in a `catch` around the call, or return it as a failure instead of throwing:"
@@ -644,8 +635,8 @@ function report(met, model, out) {
                 related.push({
                     location: locationOf(met.file, outcome.by.handler.at),
                     message: outcome.by.fate === "generic"
-                        ? `this \`catch\` does not name \`${name}\`: it handles every error alike`
-                        : `this \`catch\` rethrows \`${name}\``,
+                        ? `\`catch\` does not name \`${name}\`: it handles every error alike`
+                        : `\`catch\` rethrows \`${name}\``,
                 });
             }
             related.push(tagNote(met, where, model));
@@ -661,22 +652,22 @@ function report(met, model, out) {
         }
         case "callback":
             out.unknown({
-                message: fitted((cut) => `\`${cut(call)}\` can throw \`${cut(name)}\` out of a callback stateward cannot follow`),
-                hint: fitted((cut) => `name \`${cut(tag)}\` in a \`catch\` here, or make sure the code that calls this callback does: it must be handled`),
+                message: fitted((cut) => `not checked: whether \`${cut(name)}\` from \`${cut(call)}\` is handled: it leaves a callback whose caller is not known`),
+                hint: fitted((cut) => `name \`${cut(tag)}\` in a \`catch\` around the call, or in the code that calls the callback: it must be handled`),
                 location,
             });
             return;
         case "undecided":
             out.unknown({
-                message: fitted((cut) => `stateward cannot tell whether the \`catch\` around \`${cut(call)}\` handles \`${cut(name)}\``),
-                hint: fitted((cut) => `name it with \`instanceof ${cut(tag)}\`: stateward cannot follow what a class this \`catch\` tests extends`),
+                message: fitted((cut) => `not checked: whether the \`catch\` around \`${cut(call)}\` handles \`${cut(name)}\`: the class it tests is not known`),
+                hint: fitted((cut) => `name it with \`instanceof ${cut(tag)}\`, so the \`catch\` can be checked`),
                 location,
             });
             return;
         case "maybe":
             out.unknown({
-                message: fitted((cut) => `stateward cannot tell whether \`${cut(call)}\` can still throw \`${cut(name)}\`, which must be handled`),
-                hint: fitted((cut) => `name it in a \`catch\`, or pass it on with \`@throws {${cut(tag)}}\`: a test inside \`${cut(met.leaf.text)}\` may handle it`),
+                message: fitted((cut) => `not checked: whether \`${cut(call)}\` can still throw \`${cut(name)}\`: a test inside \`${cut(met.leaf.text)}\` may handle it`),
+                hint: fitted((cut) => `name it in a \`catch\`, or pass it on with \`@throws {${cut(tag)}}\`, so the call can be checked: it must be handled`),
                 location,
             });
             return;
@@ -714,7 +705,8 @@ function modelOf(summaries) {
 export const mustHandleError = defineRule({
     kind: "project",
     meta: {
-        description: "An error class marked @mustHandle is named in a catch or passed on with @throws by every call that can throw it.",
+        description: "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.",
+        summary: "a call that can throw an error marked `@mustHandle`, with no code that handles or passes it on",
         defaultSeverity: "error",
         tier: "core",
         group: GROUP,
@@ -730,8 +722,8 @@ export const mustHandleError = defineRule({
         const { model, untracked } = modelOf(summaries);
         for (const location of untracked) {
             ctx.unknown({
-                message: "stateward does not check `@mustHandle` on a type yet, only on an error class",
-                hint: "to have every call checked, throw an error class marked `@mustHandle`; plain-object errors come later",
+                message: "not checked: the calls that meet `@mustHandle` on a type: only an error class is followed",
+                hint: "throw an error class marked `@mustHandle`, so every call is checked; plain-object errors come later",
                 location,
             });
         }

package/dist/narrow-try.d.ts

@@ -19,10 +19,15 @@ type Line = {
      * `JSON.parse(text)`): a value that may not have the shape its type says.
      */
     readonly data: readonly string[];
-    /** What its `await`s wait for, outside nested functions. */
+    /** What its `await`s wait for, outside nested functions: each call up to its arguments. */
     readonly awaits: readonly Span[];
     /** The first thing it awaits, as written (`promise`), or null. */
     readonly awaited: string | null;
+    /**
+     * The bodies of the functions it only defines (`const save = async () => {…}`, a function
+     * declaration): nothing in them runs at this line, so what they can throw is not its.
+     */
+    readonly defines: readonly Span[];
     /** The names it declares in the block. */
     readonly declares: readonly string[];
     /** Every name it mentions. */

package/dist/narrow-try.js

@@ -11,97 +11,80 @@ import { fitted, oneLine, shorten } from "./text.js";
 export const GROUP = "catch";
 const EXPLAIN = `# errors/narrow-try
 
-Lines after the call a \`try\` is for, which call your own code, belong after the \`try\`.
+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.
 
-## Why
+\`\`\`ts example-bad
+class RequestError extends Error {}
+declare function showError(error: unknown): void;
 
-\`\`\`ts
-try {
-  const plan = await getPlan(id);
-  openEditor(plan);
-} catch (e) {
-  showError("Could not load the plan");
+async function savePlan(plan: string): Promise<void> {
+  const response = await fetch("/api/plans", { method: "POST", body: plan });
+  if (!response.ok) throw new RequestError(String(response.status));
 }
-\`\`\`
-
-The \`catch\` is for a failed \`getPlan\`. When \`openEditor\` has a bug (it reads \`plan.details.title\` and a plan comes back without \`details\`), the \`TypeError\` is handled like a failed request: the user sees "Could not load the plan", the console shows nothing useful, and the bug is never reported.
-
-## When to use it
-
-Use it to review how wide your \`try\` blocks are. It is an add-on, off until you list it: in some code styles most \`try\` blocks hold the whole success path on purpose, and then it is noise. It needs to know which call in the \`try\` can fail as expected, so it works best where your functions throw classes or document \`@throws\`, and with packages stateward knows (\`stateward deps\`).
 
-## What it catches
+export async function submit(plan: string, close: () => void): Promise<void> {
+  try {
+    await savePlan(plan);
+    close();
+  } catch (e) {
+    showError(e);
+    return;
+  }
+}
+\`\`\`
 
-A \`try\` whose last statements come after the last call that can fail as expected, and can themselves fail only as bugs. A call can fail as expected when stateward knows an error class it throws (\`throw new RequestError(…)\` in your code, \`@throws\`, a built-in like \`JSON.parse\` or \`new URL\`), when it is awaited and calls a package whose errors are not all known, or when it is awaited and its rejection is not known to be nothing. The message names that call, the request the \`try\` is for. A call of a package that is not awaited (\`toast.success(…)\`) is not one, and with no such call the rule reports nothing.
+Keep only the call the \`try\` is for inside it, and move the rest after it:
 
-Of the lines after it, the first that calls your own code is reported: a function of the project given data the \`try\` got (\`openEditor(plan)\`), or a callback the function was given (\`onClose()\`). Data is what an \`await\` gives, and what is read from it (unless declared \`unknown\`, which TypeScript makes you test first); what \`JSON.parse\` or \`await response.json()\` gives is not, since a value of the wrong shape is the same failure as bad JSON, which the \`catch\` is for (a callback given it, \`onEvent(event)\`, is still reported).
+\`\`\`ts example-good
+class RequestError extends Error {}
+declare function showError(error: unknown): void;
 
-### Bad
+async function savePlan(plan: string): Promise<void> {
+  const response = await fetch("/api/plans", { method: "POST", body: plan });
+  if (!response.ok) throw new RequestError(String(response.status));
+}
 
-\`\`\`ts
-try {
-  await savePlan(plan);
-  closeEditor();
-  onSaved();
-} catch (e) {
-  showError(e);
-  return;
+export async function submit(plan: string, close: () => void): Promise<void> {
+  try {
+    await savePlan(plan);
+  } catch (e) {
+    showError(e);
+    return;
+  }
+  close();
 }
 \`\`\`
 
-### Good
+The quick fix moves the lines after the \`try\`. It is offered only when the move keeps what runs the same for every outcome but a bug: the \`catch\` ends with \`return\` or \`throw\`, there is no \`finally\`, and the moved lines use nothing declared in the \`try\`. Where they use the result, declare it before the \`try\` (\`let plan: Plan;\`), assign it inside, and return from the \`catch\`.
 
-\`\`\`ts
-try {
-  await savePlan(plan);
-} catch (e) {
-  showError(e);
-  return;
-}
-closeEditor();
-onSaved();
-\`\`\`
+## Why it matters
 
-### Fix
+The \`catch\` is for a failed save. When \`close\` has a bug (it reads a property of \`undefined\`, say), the \`TypeError\` is handled like a failed request: the user sees "Could not save", the console shows nothing useful, and the bug is never reported. With only the request inside the \`try\`, a bug in the code after it surfaces as the bug it is.
 
-The quick fix moves the lines after the \`try\`. It is offered only when the move keeps what runs the same for every outcome but the bug: the \`catch\` ends with \`return\` or \`throw\`, there is no \`finally\`, and the moved lines use nothing declared in the \`try\`. Where they use the result (\`plan\` above), declare it before the \`try\`, assign it inside, and return from the \`catch\`:
+## What it does not catch
 
-\`\`\`ts
-let plan: Plan;
-try {
-  plan = await getPlan(id);
-} catch (e) {
-  showError("Could not load the plan");
-  return;
-}
-openEditor(plan);
-\`\`\`
+It needs a call that can fail as expected: one that throws a known error class (\`throw new RequestError(…)\` in your code, \`@throws\`, a built-in like \`JSON.parse\` or \`new URL\`), an awaited call into a package whose errors are not all known, or an awaited call whose rejection is not known to be nothing. The message names it. A package call that is not awaited (\`toast.success(…)\`) is not one; with no such call the rule says nothing. After it, it reports the first line that calls your own code: a function of the project given data the \`try\` got (\`openEditor(plan)\`), or a callback the function was given (\`close()\`). It is silent on:
 
-## What it does not catch
+- lines that only read, test or default what the \`try\` got (\`setTitle(plan.title)\`, \`if ("items" in data)\`, \`data.items ?? []\`), \`break\` and \`continue\`, store dispatches (\`dispatch(addNotification(…))\`), and a promise's own \`resolve(…)\`: these are mostly inside the \`try\` on purpose;
+- lines that only use built-ins (\`seen.set(id, host)\`) or cannot fail (\`return true;\`);
+- a \`catch\` that tests the error (\`instanceof\`, \`e.name === …\`, a type guard), rethrows it, or hands it to \`reject(e)\` or another callback it was given: it already lets bugs through;
+- what \`JSON.parse\` or \`await response.json()\` gives: a value of the wrong shape is the same failure as bad JSON, which the \`catch\` is for (a callback given it, \`onEvent(event)\`, is still reported). A value declared \`unknown\` is not data either, since TypeScript makes you test it first;
+- code in a callback written inside the \`try\`: when what it throws is not known, the rule assumes the worst and reports nothing.
 
-- Lines that only read, test or default what the \`try\` got (\`setTitle(plan.title)\`, \`if ("items" in data)\`, \`data.items ?? []\`), \`break\` and \`continue\`, store dispatches (\`dispatch(addNotification(…))\`), and a promise's own \`resolve(…)\`: most of those are written inside the \`try\` on purpose, and reporting them was noise.
-- A \`catch\` that tests the error (\`instanceof\`, \`e.name === …\`, a type guard) or rethrows it: it already lets bugs through.
-- A \`try\` where nothing is known to fail as expected: every call in it unknown and not awaited.
-- Lines after the expected call that only use built-ins (\`seen.set(id, host)\`, \`url.searchParams.get("t")\`), or cannot fail (\`return true;\`).
-- A \`catch\` that hands the error to \`reject(e)\` or another callback it was given: the bug reaches the caller.
-- Code in a callback written inside the \`try\` counts as the callback's call: when stateward cannot tell what it throws, it assumes the worst and stays quiet.
+A limit: an awaited result of your own function (\`result.success\` after \`await convert(…)\`) counts as data too; the rule does not tell a typed result from a response.
 
-A limit: an awaited result of your own function (\`result.success\` after \`await convert(…)\`) counts as data too; the rule cannot tell a typed result from a response.
+ESLint, typescript-eslint, eslint-plugin-unicorn and Biome have no rule about how wide a \`try\` is: their catch rules are about empty catches, catches that only rethrow, and the catch variable.
 
-ESLint, typescript-eslint, eslint-plugin-unicorn and Biome have no rule about the width of a \`try\`: their catch rules are about empty catches (\`no-empty\`, \`noEmptyBlockStatements\`), catches that only rethrow (\`no-useless-catch\`, \`noUselessCatch\`) and the catch variable (\`prefer-optional-catch-binding\`, \`catch-error-name\`, \`use-unknown-in-catch-callback-variable\`).
+## Getting the best from it
+
+It works best where your functions throw classes or document \`@throws\`, and with packages stateward knows (\`stateward deps\`): it then knows which call in the \`try\` can fail as expected.
 
 ## Turn it on or off
 
-Turn it on in \`stateward.config.ts\`:
+It is an add-on: in some code styles most \`try\` blocks hold the whole success path on purpose, and then it is noise. Use it to review how wide your \`try\` blocks are:
 
 \`\`\`ts
 addons: ["errors/narrow-try"]
-\`\`\`
-
-Then change it, or turn it off in one folder:
-
-\`\`\`ts
-rules: { "errors/narrow-try": "off" } // or "error"
 overrides: [{ files: ["src/scripts/**"], rules: { "errors/narrow-try": "off" } }] // one folder
 \`\`\`
 `;
@@ -281,6 +264,63 @@ function endsWithExit(block) {
     const last = block.statements.at(-1);
     return last !== undefined && (ts.isReturnStatement(last) || ts.isThrowStatement(last));
 }
+/** The calls whose rejection reaches `Promise.all([…])` and its kin. */
+const COMBINED = new Set(["all", "race", "any"]);
+/**
+ * Where what an `await` waits for is written: a call up to its arguments (`api.save` in
+ * `await api.save({ ttl: ttl.trim() })`, not `ttl.trim`, user trial 1.0.2), the promise a
+ * `.then`/`.catch`/`.finally` chain starts from, and each call listed in `Promise.all([…])`;
+ * nothing for `Promise.allSettled(…)`, which never rejects; any other value whole. A call inside the arguments runs before the request and is not it.
+ */
+function awaitedSpans(expression, sourceFile) {
+    let node = expression;
+    while (ts.isParenthesizedExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node)) {
+        node = node.expression;
+    }
+    if (!ts.isCallExpression(node))
+        return [[node.getStart(sourceFile), node.getEnd()]];
+    const callee = node.expression;
+    const own = [node.getStart(sourceFile), callee.getEnd()];
+    if (!ts.isPropertyAccessExpression(callee))
+        return [own];
+    const method = callee.name.text;
+    if (method === "then" || method === "catch" || method === "finally") {
+        return [own, ...awaitedSpans(callee.expression, sourceFile)];
+    }
+    const [list] = node.arguments;
+    // `Promise.allSettled(…)` never rejects: an `await` of it waits for nothing that can fail.
+    if (ts.isIdentifier(callee.expression) &&
+        callee.expression.text === "Promise" &&
+        method === "allSettled") {
+        return [];
+    }
+    if (ts.isIdentifier(callee.expression) &&
+        callee.expression.text === "Promise" &&
+        COMBINED.has(method) &&
+        list !== undefined &&
+        ts.isArrayLiteralExpression(list)) {
+        return [own, ...list.elements.flatMap((element) => awaitedSpans(element, sourceFile))];
+    }
+    return [own];
+}
+/** The functions `statement` defines without running them, as spans (`Line.defines`). */
+function definedFunctions(statement, sourceFile) {
+    if (ts.isFunctionDeclaration(statement))
+        return [[statement.getStart(sourceFile), statement.getEnd()]];
+    if (!ts.isVariableStatement(statement))
+        return [];
+    return statement.declarationList.declarations.flatMap((declaration) => {
+        let value = declaration.initializer;
+        while (value !== undefined && ts.isParenthesizedExpression(value))
+            value = value.expression;
+        return value !== undefined && (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+            ? [[value.getStart(sourceFile), value.getEnd()]]
+            : [];
+    });
+}
 function shapeOf(node, sourceFile) {
     const clause = node.catchClause;
     if (clause === undefined)
@@ -294,7 +334,10 @@ function shapeOf(node, sourceFile) {
         let awaited = null;
         running(statement, (inner) => {
             if (ts.isAwaitExpression(inner)) {
-                awaits.push([inner.expression.getStart(sourceFile), inner.expression.getEnd()]);
+                const spans = awaitedSpans(inner.expression, sourceFile);
+                if (spans.length === 0)
+                    return;
+                awaits.push(...spans);
                 awaited ??= shorten(oneLine(inner.expression.getText(sourceFile)), LINE_MAX);
             }
         });
@@ -306,6 +349,7 @@ function shapeOf(node, sourceFile) {
             data: dataOf(statement, data),
             awaits,
             awaited,
+            defines: definedFunctions(statement, sourceFile),
             declares: declaredBy(statement),
             uses: namesIn(statement),
         });
@@ -344,10 +388,12 @@ function readLine(value) {
     const f = fieldsOf(value);
     const at = spanOf(f?.at);
     const awaits = each(f?.awaits, spanOf);
+    const defines = each(f?.defines, spanOf);
     const declares = readStrings(f?.declares);
     const uses = readStrings(f?.uses);
-    if (f === undefined || at === undefined || awaits === undefined)
+    if (f === undefined || at === undefined || awaits === undefined || defines === undefined) {
         return undefined;
+    }
     const data = readStrings(f.data);
     if (declares === undefined || uses === undefined || data === undefined)
         return undefined;
@@ -357,7 +403,18 @@ function readLine(value) {
         isString(f.raw) &&
         awaited !== undefined &&
         typeof canReport === "boolean"
-        ? { at, text: f.text, raw: f.raw, reportable: canReport, data, awaits, awaited, declares, uses }
+        ? {
+            at,
+            text: f.text,
+            raw: f.raw,
+            reportable: canReport,
+            data,
+            awaits,
+            awaited,
+            defines,
+            declares,
+            uses,
+        }
         : undefined;
 }
 function readShape(value) {
@@ -457,7 +514,9 @@ function spotsOf(analysis, file, effects, out) {
 const within = (inner, outer) => inner[0] >= outer[0] && inner[1] <= outer[1];
 /** The spots of `line` that are its own: not inside a `try` that is itself inside the line. */
 function spotsIn(line, spots) {
-    return spots.filter((spot) => within(spot.at, line.at) && (spot.parent === undefined || !within(spot.parent, line.at)));
+    return spots.filter((spot) => within(spot.at, line.at) &&
+        (spot.parent === undefined || !within(spot.parent, line.at)) &&
+        !line.defines.some((body) => within(spot.at, body)));
 }
 /**
  * What can fail as expected in `line`: a spot with a known error, or one stateward cannot follow
@@ -507,7 +566,7 @@ function moveFix(shape, kept, moved, file) {
     const raw = moved.map((line) => line.raw).join("");
     const dedented = raw.split(`\n${shape.inner}`).join(`\n${shape.indent}`);
     const fix = {
-        title: moved.length === 1 ? "Move this line after the `try`" : "Move these lines after the `try`",
+        title: moved.length === 1 ? "Move the line after the `try`" : "Move the lines after the `try`",
         edits: [
             { location: { file, start: lastKept.at[1], end: lastMoved.at[1] }, newText: "" },
             { location: { file, start: shape.at[1], end: shape.at[1] }, newText: dedented },
@@ -535,14 +594,14 @@ function nameOf(spot, line) {
     return `throw ${open < 0 ? thrown : `${thrown.slice(0, open)}(…)`}`;
 }
 function headline(line, expected) {
-    return fitted((cut) => `\`${asCode(cut(line))}\` is inside the \`try\` meant for \`${cut(expected)}\``);
+    return fitted((cut) => `the \`try\` for \`${cut(expected)}\` also catches errors from \`${asCode(cut(line))}\``);
 }
 function hint(expected, fixable, count) {
-    const lines = count === 1 ? "it" : "these lines";
-    const start = `a bug here would be handled like a failed \`${expected}\`; move ${lines} after the \`try\``;
+    const [lines, them] = count === 1 ? ["the line", "it"] : ["the lines", "them"];
+    const why = `so a bug in ${them} is not handled like a failed \`${expected}\``;
     if (fixable)
-        return `${start} (quick fix)`;
-    return `${start} and return from the \`catch\` (declare what ${count === 1 ? "it uses" : "they use"} before the \`try\`)`;
+        return `move ${lines} after the \`try\`, ${why} (quick fix)`;
+    return `move ${lines} after the \`try\` and return from the \`catch\` (declare what ${count === 1 ? "it uses" : "they use"} before the \`try\`), ${why}`;
 }
 /** A promise's own `resolve` and `reject` (excalidraw): they never throw. */
 const SETTLES = new Set(["resolve(…)", "reject(…)"]);
@@ -586,7 +645,8 @@ function checkTry(shape, spots, file, report) {
 export const narrowTry = defineRule({
     kind: "project",
     meta: {
-        description: "Calls to your own code placed in a `try` after the call it is for: move them after the `try`.",
+        description: "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.",
+        summary: "calls to your own code inside a `try` after the call it is for, so their bugs look like its failure",
         defaultSeverity: "warning",
         tier: "addon",
         addon: "narrow-try",