@stateward/plugin-errors 1.0.1 → 1.1.0

package/dist/result-unchecked.js

@@ -3,79 +3,75 @@ import { defineRule } from "@stateward/core";
 import { example, resultShapeOf, shorten } from "./result-type.js";
 const EXPLAIN = `# errors/result-unchecked
 
-A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked.
+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.
 
-## Why
+\`\`\`ts example-bad
+type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
 
-Some calls do not throw when they fail: they resolve to data or an error. An RTK Query trigger without \`.unwrap()\` is the common one. Wrap \`await deletePlan(id)\` in a \`try\` and the \`catch\` never runs: a failed delete still shows "Deleted" and closes the dialog. Store the result and show its error, and the lines after still run: "Saved" appears after a save that failed.
+declare function saveSettings(values: string): Promise<Result<void>>;
+declare function toast(text: string): void;
 
-## When to use it
-
-Use it if you call RTK Query triggers, or functions that return a Result (\`{ ok: true; value } | { ok: false; error }\`, zod's \`safeParse\`, neverthrow), and await them in event handlers. It is a warning in every preset.
-
-## What it catches
+export async function submit(values: string): Promise<void> {
+  const result = await saveSettings(values);
+  if (!result.ok) toast("Could not save");
+  toast("Saved");
+}
+\`\`\`
 
-A call whose value is data or an error: a promise with an \`unwrap()\` method that resolves to a union with an \`error\` member (RTK Query's triggers; found by the type, not by a name), or a Result recognised as \`errors/result-ignored\` recognises it. Then:
+When it failed, stop there: \`return\` (or \`throw\`) in the check:
 
-- awaited as a statement inside a \`try\` whose \`catch\` nothing else can reach (no call before it, no other \`await\` or \`throw\` in the \`try\`): the \`catch\` never runs;
-- awaited as a statement inside a \`try\` after another call (an optimistic \`setFolders(…)\`, a \`parse(values)\`), with more lines after it: when it fails, those lines run (\`notify("Folder updated!")\`) and the \`catch\` (the rollback) does not;
-- a trigger awaited as a statement outside a \`try\`, with more lines after it (\`await sendReply(x); setText("")\`);
-- stored, then its data read before it is checked;
-- stored, its error read in an \`if\` that does not \`return\` or \`throw\` (\`"error" in result\`, \`result.error\`, or an \`error\` or \`isError\` taken out of it), with more lines after that \`if\`.
+\`\`\`ts example-good
+type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
 
-### Bad
+declare function saveSettings(values: string): Promise<Result<void>>;
+declare function toast(text: string): void;
 
-\`\`\`ts
-try {
-  await deletePlan(id);
-  toast.success("Deleted");
-} catch {
-  toast.error("Could not delete");
+export async function submit(values: string): Promise<void> {
+  const result = await saveSettings(values);
+  if (!result.ok) {
+    toast("Could not save");
+    return;
+  }
+  toast("Saved");
 }
-
-const result = await saveSettings(values);
-if ("error" in result) toast.error("Could not save");
-toast.success("Saved");
 \`\`\`
 
-### Good
+For an RTK Query trigger, add \`.unwrap()\` so a failure throws: \`await deletePlan(id).unwrap()\`. Where the result is dropped, a quick fix adds it.
 
-\`\`\`ts
-try {
-  await deletePlan(id).unwrap();
-  toast.success("Deleted");
-} catch {
-  toast.error("Could not delete");
-}
+## Why it matters
 
-const result = await saveSettings(values);
-if ("error" in result) {
-  toast.error("Could not save");
-  return;
-}
-toast.success("Saved");
-\`\`\`
+Some calls do not throw when they fail: they resolve to data or an error. An RTK Query trigger without \`.unwrap()\` is the common one. Wrap \`await deletePlan(id)\` in a \`try\` and the \`catch\` never runs: a failed delete still shows "Deleted" and closes the dialog. Store the result and show its error without stopping, and the lines after still run: "Saved" appears after a save that failed.
 
-### Fix
+## When it says “not checked”
 
-Add \`.unwrap()\` so a failure throws (a quick fix where the result is dropped), or check the result and \`return\` (or \`throw\`) when it failed. Code that says what it means is left alone: \`void trigger(…)\`, \`.unwrap()\`, a check (\`"error" in result\`, \`if (result.error) return\`, \`isOk(result)\`, \`const { data, isError } = await dispatch(…); if (isError) throw …\`) before the success path, an \`if\` with an \`else\` for the success path, and a component that reads the trigger's own \`isError\` or \`error\` from its hook (\`const [save, { isError }] = useSaveMutation()\`).
+An \`if\` that tests the result in a way stateward cannot read (\`if (result.error && isApiError(result.error))\`) is listed as a place not checked. Test it in one of the ways below, then narrow further inside.
 
 ## What it does not catch
 
-- A Result (\`ok\`, \`success\`, neverthrow) dropped as a statement: that is \`errors/result-ignored\`'s.
-- Lines after the call that only set back a pending state set before it (\`setSaving(true)\` … \`setSaving(false)\`): they run either way on purpose.
-- A \`try\` with another \`await\` or a \`throw\` in it: the \`catch\` may be there for that.
-- A result passed on, returned or stored elsewhere, or checked in a callback.
-- A promise that rejects on failure (react-query's \`mutateAsync\`, \`fetch\`): it has no \`unwrap()\` that resolves to data or an error.
-- An \`if\` that tests the result in a way stateward cannot read (\`if (result.error && isApiError(result.error))\`): it is listed as a place not checked.
+It looks at a call whose value is data or an error: a promise with an \`unwrap()\` method that resolves to a union with an \`error\` member (RTK Query's triggers, found by the type, not by a name), or a Result as \`errors/result-ignored\` recognises it. It reports such a call when:
 
-## Turn it on or off
+- it is awaited as a statement inside a \`try\` whose \`catch\` nothing else can reach (no call before it, no other \`await\` or \`throw\` in the \`try\`): the \`catch\` never runs;
+- it is awaited as a statement inside a \`try\` after another call (an optimistic \`setFolders(…)\`), with more lines after it: when it fails, those lines run and the \`catch\` (the rollback) does not;
+- a trigger is awaited as a statement outside a \`try\`, with more lines after it (\`await sendReply(x); setText("")\`);
+- it is stored, then its data is read before it is checked;
+- it is stored, and its error is read in an \`if\` that does not \`return\` or \`throw\` (\`"error" in result\`, \`result.error\`, \`!result.ok\`, or an \`error\` or \`isError\` taken out of it), with more lines after that \`if\`.
+
+It is silent on:
 
-In \`stateward.config.ts\`:
+- a Result dropped as a statement: that is \`errors/result-ignored\`;
+- lines after the call that only set back a pending state set before it (\`setSaving(true)\` … \`setSaving(false)\`): they run either way on purpose;
+- a \`try\` with another \`await\` or a \`throw\` in it: the \`catch\` may be there for that;
+- a result passed on, returned, stored elsewhere, or checked in a callback;
+- a promise that rejects on failure (react-query's \`mutateAsync\`, \`fetch\`): it has no \`unwrap()\` that resolves to data or an error.
+
+## Getting the best from it
+
+Code that says what it means is left alone: \`void trigger(…)\`, \`.unwrap()\`, a check (\`"error" in result\`, \`if (result.error) return\`, \`isOk(result)\`, \`const { data, isError } = await dispatch(…); if (isError) throw …\`) before the success path, an \`if\` with an \`else\` for the success path, and a component that reads the trigger's own \`isError\` or \`error\` from its hook (\`const [save, { isError }] = useSaveMutation()\`).
+
+## Turn it on or off
 
 \`\`\`ts
 rules: { "errors/result-unchecked": "off" } // or "error"
-groups: { "errors/callers": "off" } // the whole group
 \`\`\`
 `;
 /** The longest call an example line shows before its arguments become `…`. */
@@ -428,7 +424,7 @@ function checkTry(statement, ctx) {
                 continue;
             ctx.report({
                 node: inner,
-                message: `the lines after this run even when \`${calleeText(call, ctx)}(…)\` failed, and the \`catch\` does not`,
+                message: `code after the call runs even when \`${calleeText(call, ctx)}(…)\` failed, and the \`catch\` does not`,
                 hint: [
                     'add `.unwrap()` so a failure reaches the `catch` (quick fix), or check `"error" in result` and return:',
                     example([
@@ -445,9 +441,9 @@ function checkTry(statement, ctx) {
         ctx.report({
             // The statement, as `errors/result-ignored` reports it, so that rule can yield to this one.
             node: inner,
-            message: `\`${calleeText(call, ctx)}(…)\` does not throw when it fails, so this \`catch\` never runs`,
+            message: `\`catch\` never runs for \`${calleeText(call, ctx)}(…)\`: it does not throw when it fails`,
             hint: [
-                'the lines after it still run on failure; add `.unwrap()` (quick fix), or check `"error" in result` and return:',
+                'add `.unwrap()` (quick fix), or check `"error" in result` and return, so the code after it does not run on failure:',
                 example([`const result = await ${callText(call, ctx)};`, `if ("error" in result) return;`]),
             ].join("\n"),
             fixes: [unwrapFix(call, "Add `.unwrap()` so a failure reaches the `catch`", ctx)],
@@ -531,12 +527,12 @@ function checkDropped(statement, ctx) {
         return;
     ctx.report({
         node: statement,
-        message: `the lines after this run even when \`${calleeText(call, ctx)}(…)\` failed`,
+        message: `code after the call runs even when \`${calleeText(call, ctx)}(…)\` failed`,
         hint: [
             'add `.unwrap()` so a failure throws (quick fix), or check `"error" in result` and return:',
             example([`const result = await ${callText(call, ctx)};`, `if ("error" in result) return;`]),
         ].join("\n"),
-        fixes: [unwrapFix(call, "Add `.unwrap()` so a failure stops this function", ctx)],
+        fixes: [unwrapFix(call, "Add `.unwrap()` so a failure stops the function", ctx)],
     });
 }
 /** What a stored result is reached by: `const r = …` or `const { data, error } = …`. */
@@ -561,8 +557,8 @@ function trackedOf(declaration, call, kind, ctx) {
     return aliases.size === 0 ? undefined : { whole: undefined, aliases, callee, kind };
 }
 function goesOnHeadline(tracked, after) {
-    const what = after === "if" ? "this `if`" : "this";
-    return `the lines after ${what} run even when \`${tracked.callee}(…)\` failed`;
+    const what = after === "if" ? "the `if`" : "the call";
+    return `code after ${what} runs even when \`${tracked.callee}(…)\` failed`;
 }
 /**
  * The statements that run after a check that is the last of its list: those after the enclosing
@@ -644,8 +640,8 @@ function followStored(statement, before, rest, tracked, call, ctx) {
         case "undecided":
             ctx.unknown({
                 node: outcome.test,
-                message: `stateward cannot tell whether this \`if\` checks that \`${tracked.callee}(…)\` failed`,
-                hint: `test the result itself to make it checkable, as in \`${checkLine(tracked)}\``,
+                message: `not checked: whether the \`if\` tests that \`${tracked.callee}(…)\` failed: it does not test the result itself`,
+                hint: `test the result itself, as in \`${checkLine(tracked)}\`, so the check can be followed`,
             });
             return;
         case "goes-on": {
@@ -723,7 +719,8 @@ function checkDeclaration(statement, ctx) {
 export const resultUnchecked = defineRule({
     kind: "file",
     meta: {
-        description: "A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked.",
+        description: "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.",
+        summary: "a call that fails in its value (an RTK Query trigger, a Result) used as if it had worked",
         defaultSeverity: "warning",
         tier: "core",
         group: "callers",

package/dist/rules.meta.d.ts

@@ -2,7 +2,8 @@ export declare const RULES: {
     readonly "catch-hides-unexpected": {
         readonly kind: "file";
         readonly meta: {
-            readonly description: "A catch that handles some errors with instanceof also rethrows or handles all the others.";
+            readonly 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.";
+            readonly summary: "a `catch` that handles some error classes with `instanceof` and ignores the rest";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "catch";
@@ -15,48 +16,11 @@ export declare const RULES: {
             };
         };
     };
-    readonly "catch-without-intent": {
-        readonly kind: "file";
-        readonly meta: {
-            readonly description: "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.";
-            readonly defaultSeverity: "warning";
-            readonly tier: "addon";
-            readonly addon: "catch-intent";
-            readonly group: "catch";
-            readonly heuristic: true;
-            readonly options: {
-                readonly loggers: {
-                    readonly kind: "strings";
-                    readonly default: readonly ["console", "logger", "log"];
-                    readonly description: "Objects whose every method only logs (globs like *Logger): a catch that only calls them swallows the error.";
-                };
-                readonly logMethods: {
-                    readonly kind: "strings";
-                    readonly default: readonly ["error", "warn", "info", "debug"];
-                    readonly description: "Method names that only log, on any object (`Sentry.captureException` is not one).";
-                };
-                readonly logFunctions: {
-                    readonly kind: "strings";
-                    readonly default: readonly [];
-                    readonly description: "Plain functions of your own that only log, like logError (globs allowed).";
-                };
-                readonly edgeHelpers: {
-                    readonly kind: "strings";
-                    readonly default: readonly [];
-                    readonly description: "Your functions that report an error where it ends (to a service, to the user): a catch that calls one is handled, like reportAndShow (globs allowed). Sentry, Bugsnag and Datadog are known without it.";
-                };
-                readonly swallowHelpers: {
-                    readonly kind: "strings";
-                    readonly default: readonly [];
-                    readonly description: "Functions that mark an error as ignored on purpose, like ignoreError (globs allowed): a catch that calls one is not reported.";
-                };
-            };
-        };
-    };
     readonly "finally-can-throw": {
         readonly kind: "file";
         readonly meta: {
-            readonly description: "A finally block does not call something that throws, so the error that led to it is not lost.";
+            readonly description: "An error thrown in `finally` replaces the error that was already thrown, so the report names the cleanup instead of the original cause.";
+            readonly summary: "a `finally` that calls something that can throw and replace the original error";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "catch";
@@ -77,7 +41,8 @@ export declare const RULES: {
     readonly "catch-misses-error": {
         readonly kind: "project";
         readonly meta: {
-            readonly 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.";
+            readonly 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.";
+            readonly summary: "a `catch` that branches on error classes but misses one its `try` can throw";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "catch";
@@ -94,7 +59,8 @@ export declare const RULES: {
     readonly "throws-doc-mismatch": {
         readonly kind: "project";
         readonly meta: {
-            readonly description: "A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see.";
+            readonly description: "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.";
+            readonly summary: "a `@throws` tag that lists an error the function cannot throw, or misses one it can";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "callers";
@@ -120,11 +86,16 @@ export declare const RULES: {
     readonly "render-throw-without-boundary": {
         readonly kind: "project";
         readonly meta: {
-            readonly description: "A component that can throw a known error while rendering has an error boundary above it.";
+            readonly description: "An error thrown while rendering, with no error boundary above the component, unmounts the whole React tree and leaves a blank page.";
+            readonly summary: "a component that can throw a known error while rendering, with no error boundary above it";
             readonly defaultSeverity: "warning";
             readonly tier: "core";
             readonly group: "render";
             readonly needsJsDoc: true;
+            readonly needsTypes: {
+                readonly library: "React";
+                readonly modules: readonly ["react"];
+            };
             readonly options: {
                 readonly skipContextGuards: {
                     readonly kind: "boolean";
@@ -154,7 +125,8 @@ export declare const RULES: {
     readonly "must-handle-error": {
         readonly kind: "project";
         readonly meta: {
-            readonly description: "An error class marked @mustHandle is named in a catch or passed on with @throws by every call that can throw it.";
+            readonly 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.";
+            readonly summary: "a call that can throw an error marked `@mustHandle`, with no code that handles or passes it on";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "callers";
@@ -165,7 +137,8 @@ export declare const RULES: {
     readonly "narrow-try": {
         readonly kind: "project";
         readonly meta: {
-            readonly description: "Calls to your own code placed in a `try` after the call it is for: move them after the `try`.";
+            readonly 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.";
+            readonly summary: "calls to your own code inside a `try` after the call it is for, so their bugs look like its failure";
             readonly defaultSeverity: "warning";
             readonly tier: "addon";
             readonly addon: "narrow-try";
@@ -176,7 +149,8 @@ export declare const RULES: {
     readonly "result-ignored": {
         readonly kind: "file";
         readonly meta: {
-            readonly description: "The Result of a call is checked or passed on, not dropped as a statement, after void or after await.";
+            readonly description: "A `Result` dropped as a statement discards its error, so a failed call looks the same as a successful one.";
+            readonly summary: "a `Result` dropped as a statement, after `void` or after `await`";
             readonly defaultSeverity: "error";
             readonly tier: "core";
             readonly group: "callers";
@@ -203,7 +177,8 @@ export declare const RULES: {
     readonly "result-unchecked": {
         readonly kind: "file";
         readonly meta: {
-            readonly description: "A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked.";
+            readonly description: "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.";
+            readonly summary: "a call that fails in its value (an RTK Query trigger, a Result) used as if it had worked";
             readonly defaultSeverity: "warning";
             readonly tier: "core";
             readonly group: "callers";

package/dist/rules.meta.js

@@ -2,7 +2,8 @@ export const RULES = {
     "catch-hides-unexpected": {
         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: "catch",
@@ -15,48 +16,11 @@ export const RULES = {
             },
         },
     },
-    "catch-without-intent": {
-        kind: "file",
-        meta: {
-            description: "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.",
-            defaultSeverity: "warning",
-            tier: "addon",
-            addon: "catch-intent",
-            group: "catch",
-            heuristic: true,
-            options: {
-                loggers: {
-                    kind: "strings",
-                    default: ["console", "logger", "log"],
-                    description: "Objects whose every method only logs (globs like *Logger): a catch that only calls them swallows the error.",
-                },
-                logMethods: {
-                    kind: "strings",
-                    default: ["error", "warn", "info", "debug"],
-                    description: "Method names that only log, on any object (`Sentry.captureException` is not one).",
-                },
-                logFunctions: {
-                    kind: "strings",
-                    default: [],
-                    description: "Plain functions of your own that only log, like logError (globs allowed).",
-                },
-                edgeHelpers: {
-                    kind: "strings",
-                    default: [],
-                    description: "Your functions that report an error where it ends (to a service, to the user): a catch that calls one is handled, like reportAndShow (globs allowed). Sentry, Bugsnag and Datadog are known without it.",
-                },
-                swallowHelpers: {
-                    kind: "strings",
-                    default: [],
-                    description: "Functions that mark an error as ignored on purpose, like ignoreError (globs allowed): a catch that calls one is not reported.",
-                },
-            },
-        },
-    },
     "finally-can-throw": {
         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: "catch",
@@ -77,7 +41,8 @@ export const RULES = {
     "catch-misses-error": {
         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: "catch",
@@ -94,7 +59,8 @@ export const RULES = {
     "throws-doc-mismatch": {
         kind: "project",
         meta: {
-            description: "A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see.",
+            description: "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.",
+            summary: "a `@throws` tag that lists an error the function cannot throw, or misses one it can",
             defaultSeverity: "error",
             tier: "core",
             group: "callers",
@@ -120,11 +86,13 @@ export const RULES = {
     "render-throw-without-boundary": {
         kind: "project",
         meta: {
-            description: "A component that can throw a known error while rendering has an error boundary above it.",
+            description: "An error thrown while rendering, with no error boundary above the component, unmounts the whole React tree and leaves a blank page.",
+            summary: "a component that can throw a known error while rendering, with no error boundary above it",
             defaultSeverity: "warning",
             tier: "core",
             group: "render",
             needsJsDoc: true,
+            needsTypes: { library: "React", modules: ["react"] },
             options: {
                 skipContextGuards: {
                     kind: "boolean",
@@ -152,7 +120,8 @@ export const RULES = {
     "must-handle-error": {
         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: "callers",
@@ -163,7 +132,8 @@ export const RULES = {
     "narrow-try": {
         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",
@@ -174,7 +144,8 @@ export const RULES = {
     "result-ignored": {
         kind: "file",
         meta: {
-            description: "The Result of a call is checked or passed on, not dropped as a statement, after void or after await.",
+            description: "A `Result` dropped as a statement discards its error, so a failed call looks the same as a successful one.",
+            summary: "a `Result` dropped as a statement, after `void` or after `await`",
             defaultSeverity: "error",
             tier: "core",
             group: "callers",
@@ -201,7 +172,8 @@ export const RULES = {
     "result-unchecked": {
         kind: "file",
         meta: {
-            description: "A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked.",
+            description: "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.",
+            summary: "a call that fails in its value (an RTK Query trigger, a Result) used as if it had worked",
             defaultSeverity: "warning",
             tier: "core",
             group: "callers",

package/dist/throws-doc-mismatch.js

@@ -7,65 +7,55 @@ import { codeList, fitted } from "./text.js";
 export const GROUP = "callers";
 const EXPLAIN = `# errors/throws-doc-mismatch
 
-A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see.
+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.
 
-## Why
+\`\`\`ts example-bad
+export class NotFoundError extends Error {}
 
-\`@throws {T}\` tells callers which errors to expect, and stateward checks every caller's \`catch\` against it. A tag that has drifted from the code misleads both. If \`loadUser\` says \`@throws {NotFoundError}\` but also calls \`JSON.parse\`, a \`SyntaxError\` slips past a \`catch\` written for \`NotFoundError\`. A tag that lists an error the function can no longer throw sends callers to handle something that never comes.
-
-## When to use it
-
-Use it if you write \`@throws\` tags, typically on public functions and module boundaries. It is on as an error in every preset, and does nothing for functions without the tag, so it costs nothing until you start writing them.
-
-## What it catches
-
-It compares the tag with what the function can throw (its own \`throw new X(…)\`, the functions it calls, and the built-ins stateward knows), and reports:
-
-- a class in the tag that the function cannot throw, neither it nor a subclass;
-- a class the function can throw that the tag does not cover, by itself or by a class it extends.
-
-On a function that returns a promise, \`@throws\` means what the promise rejects with: what callers see when they \`await\` it or use \`.catch\`.
-
-### Bad
-
-\`\`\`ts
 /** @throws {NotFoundError} */
-export async function loadUser(id: string): Promise<User> {
-  const text = await readUser(id);
-  return JSON.parse(text); // SyntaxError, not listed
+export function loadUser(text: string): { name: string } {
+  if (text === "") throw new NotFoundError("no such user");
+  return JSON.parse(text) as { name: string };
 }
 \`\`\`
 
-### Good
+Update the tag to what the function can throw; the message gives the one to write:
+
+\`\`\`ts example-good
+export class NotFoundError extends Error {}
 
-\`\`\`ts
 /** @throws {NotFoundError | SyntaxError} */
-export async function loadUser(id: string): Promise<User> {
-  const text = await readUser(id);
-  return JSON.parse(text);
+export function loadUser(text: string): { name: string } {
+  if (text === "") throw new NotFoundError("no such user");
+  return JSON.parse(text) as { name: string };
 }
 \`\`\`
 
-### Fix
+The message links to the call that throws each missing class. There is no quick fix.
+
+## Why it matters
 
-Update the tag; the message gives the one to write and links to the call that throws each missing class. There is no quick fix.
+\`@throws {T}\` tells callers which errors to expect, and stateward checks every caller's \`catch\` against it. A tag that has drifted from the code misleads both: here a \`SyntaxError\` from \`JSON.parse\` slips past a \`catch\` written for \`NotFoundError\`. A tag that lists an error the function can no longer throw sends callers to handle something that never comes.
+
+## When it says “not checked”
+
+- A listed class that comes from a call stateward cannot see into (a package, a callback, a dynamic call): it names the call. Remove the class from the tag if the function cannot throw it, or declare the package's errors under \`facts\` in the config (\`facts: { "config-lib": { load: { throws: ["ConfigError"] } } }\`).
+- A name in the tag that is not a class in scope: import the class, or use a name in scope.
 
 ## What it does not catch
 
-- A function without \`@throws\`.
-- A tag without a type (\`@throws when the id is empty\`): it only says the function throws.
-- A listed class that comes from a call stateward cannot see into (a package, a callback, a dynamic call). It says so in an info finding, naming the call: remove the class from the tag if the function cannot throw it, or declare the package's errors under \`facts\` in the config.
-- A name in the tag that is not a class in scope: also an info finding. Import the class, or use a name in scope.
-- A class that a surrounding \`try\` may catch: only classes that surely escape are reported as missing.
-- Errors from the JavaScript engine itself, such as reading a property of \`undefined\`.
+It compares the tag with what the function can throw (its own \`throw new X(…)\`, the functions it calls, and the built-ins stateward knows) and reports a class in the tag that the function cannot throw (neither it nor a subclass), and a class it can throw that the tag does not cover. On a function that returns a promise, \`@throws\` means what the promise rejects with. It is silent on:
+
+- a function without \`@throws\`, or a tag without a type (\`@throws when the id is empty\`): that only says the function throws;
+- a class that a surrounding \`try\` may catch: only classes that surely escape are reported as missing;
+- errors from the JavaScript engine itself, such as reading a property of \`undefined\`.
 
 ## Turn it on or off
 
-In \`stateward.config.ts\`:
+It does nothing for functions without the tag, so it costs nothing until you start writing them.
 
 \`\`\`ts
 rules: { "errors/throws-doc-mismatch": "off" } // or "warning"
-groups: { "errors/inference": "off" } // the whole group
 rules: { "errors/throws-doc-mismatch": ["error", { severities: { extra: "warning" } }] } // a stale tag only warns
 \`\`\`
 `;
@@ -109,7 +99,7 @@ function check(entry, analysis, ctx) {
         const location = locationOf(entry.file, item.at);
         if (item.id === null) {
             ctx.unknown({
-                message: fitted((cut) => `stateward cannot find the class \`${cut(item.name)}\` this \`@throws\` names`),
+                message: fitted((cut) => `not checked: \`@throws\` names \`${cut(item.name)}\`: no class of that name is in scope`),
                 hint: "name an error class that is in scope in this file, or import it",
                 location,
             });
@@ -122,14 +112,14 @@ function check(entry, analysis, ctx) {
         const listed = className(id, classes);
         if (firstUnknown !== undefined) {
             ctx.unknown({
-                message: fitted((cut) => `stateward cannot tell whether \`${cut(name)}\` throws \`${cut(listed)}\` (via \`${cut(firstUnknown.text)}\`: ${firstUnknown.reason})`),
-                hint: `if \`${name}\` cannot throw it, remove \`${listed}\` from the tag; else add \`@throws\` where it comes from`,
+                message: fitted((cut) => `not checked: whether \`${cut(name)}\` throws \`${cut(listed)}\`: what \`${cut(firstUnknown.text)}\` throws is not known (${firstUnknown.reason})`),
+                hint: `remove \`${listed}\` from the tag if \`${name}\` cannot throw it; otherwise add \`@throws\` where it comes from`,
                 location,
             });
             continue;
         }
         ctx.report({
-            message: fitted((cut) => `\`@throws\` lists \`${cut(listed)}\`, which \`${cut(name)}\` cannot throw`),
+            message: fitted((cut) => `\`@throws\` of \`${cut(name)}\` lists \`${cut(listed)}\`, which it cannot throw`),
             hint: `remove \`${listed}\` from the tag, or throw it where it can happen`,
             location,
             findingKind: "extra",
@@ -160,7 +150,7 @@ function check(entry, analysis, ctx) {
     const names = missing.map((one) => className(one.id, classes)).sort();
     const tagNames = [...new Set(missing.map((one) => catchName(one.id, classes)))].sort();
     ctx.report({
-        message: fitted((cut) => `\`${cut(name)}\` can throw ${codeList(names, cut)}, which its \`@throws\` does not list`),
+        message: fitted((cut) => `\`@throws\` of \`${cut(name)}\` does not list ${codeList(names, cut)}`),
         hint: `add ${missing.length === 1 ? "it" : "them"} to the tag: \`@throws {${tagNames.join(" | ")}}\``,
         location: locationOf(entry.file, entry.fact.at),
         related: missing.flatMap((one) => (one.related === undefined ? [] : [one.related])).slice(0, 3),
@@ -170,7 +160,8 @@ function check(entry, analysis, ctx) {
 export const throwsDocMismatch = defineRule({
     kind: "project",
     meta: {
-        description: "A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see.",
+        description: "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.",
+        summary: "a `@throws` tag that lists an error the function cannot throw, or misses one it can",
         defaultSeverity: "error",
         tier: "core",
         group: GROUP,