@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the stateward authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @stateward/plugin-errors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```bash
+npm install --save-dev stateward @stateward/plugin-errors
+```
+
+```ts
+// stateward.config.ts
+import { defineConfig } from "stateward";
+import { errors } from "@stateward/plugin-errors";
+
+export default defineConfig({
+  plugins: [errors()],
+  preset: "recommended",
+});
+```
+
+`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).

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

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

package/dist/async-handler-unhandled.js

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

package/dist/catch-hides-unexpected.d.ts

@@ -0,0 +1,6 @@
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export declare const GROUP = "catch";
+export declare const catchHidesUnexpected: import("@stateward/core").FileRule<{
+    restUsesError: import("@stateward/core").BooleanOption;
+}, "catch">;
+//# sourceMappingURL=catch-hides-unexpected.d.ts.map

package/dist/catch-hides-unexpected.js

@@ -0,0 +1,260 @@
+import ts from "@stateward/core/typescript";
+import { defineRule, option } from "@stateward/core";
+import { stripParentheses } from "./syntax.js";
+import { codeList, fitted, oneLine, withExample } from "./text.js";
+/** The group the rule belongs to in the docs and in `stateward status`. */
+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();
+  }
+}
+\`\`\`
+
+### Good
+
+\`\`\`ts
+try {
+  await save(order);
+} catch (e) {
+  if (e instanceof NotFoundError) {
+    showMissing();
+  } else if (e instanceof AuthError) {
+    redirectToLogin();
+  } 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.
+
+## What it does not catch
+
+- A chain that tests another value, or tests 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\`.
+
+## 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
+\`\`\`
+`;
+/** The statements of a branch or block, without empty statements; a comment is not a statement. */
+const OPTIONS = {
+    restUsesError: option.boolean({
+        default: false,
+        description: "The branch for the other errors must use the error (rethrow it, wrap it, report it); a generic message alone does not count.",
+    }),
+};
+function realStatements(node) {
+    if (node === undefined)
+        return [];
+    const statements = ts.isBlock(node) ? node.statements : [node];
+    return statements.filter((statement) => !ts.isEmptyStatement(statement));
+}
+/** The classes of the `instanceof` tests on `variable` in a condition, in source order. */
+function instanceOfClasses(condition, variable, sourceFile) {
+    const node = stripParentheses(condition);
+    if (!ts.isBinaryExpression(node))
+        return [];
+    const operator = node.operatorToken.kind;
+    if (operator === ts.SyntaxKind.InstanceOfKeyword) {
+        const subject = stripParentheses(node.left);
+        return ts.isIdentifier(subject) && subject.text === variable
+            ? [oneLine(stripParentheses(node.right).getText(sourceFile))]
+            : [];
+    }
+    if (operator === ts.SyntaxKind.BarBarToken ||
+        operator === ts.SyntaxKind.AmpersandAmpersandToken) {
+        return [
+            ...instanceOfClasses(node.left, variable, sourceFile),
+            ...instanceOfClasses(node.right, variable, sourceFile),
+        ];
+    }
+    return [];
+}
+/** An `if` / `else if` chain, from its first `if` to its last link. */
+function linksOf(start) {
+    const links = [start];
+    for (let last = start; last.elseStatement !== undefined && ts.isIfStatement(last.elseStatement);) {
+        last = last.elseStatement;
+        links.push(last);
+    }
+    return links;
+}
+function dispatchOf(statement, variable, sourceFile) {
+    if (ts.isIfStatement(statement)) {
+        const links = linksOf(statement);
+        const classes = links.flatMap((link) => instanceOfClasses(link.expression, variable, sourceFile));
+        const end = links[links.length - 1];
+        if (classes.length === 0 || end === undefined)
+            return undefined;
+        return {
+            start: statement,
+            classes,
+            rest: realStatements(end.elseStatement),
+            openChainEnd: end.elseStatement === undefined ? end : undefined,
+            kind: "if",
+        };
+    }
+    if (ts.isSwitchStatement(statement)) {
+        if (stripParentheses(statement.expression).kind !== ts.SyntaxKind.TrueKeyword)
+            return undefined;
+        const classes = statement.caseBlock.clauses.flatMap((clause) => ts.isCaseClause(clause) ? instanceOfClasses(clause.expression, variable, sourceFile) : []);
+        if (classes.length === 0)
+            return undefined;
+        const fallback = statement.caseBlock.clauses.find((clause) => ts.isDefaultClause(clause));
+        return {
+            start: statement,
+            classes,
+            rest: (fallback?.statements ?? []).filter((inner) => !ts.isEmptyStatement(inner)),
+            openChainEnd: undefined,
+            kind: "switch",
+        };
+    }
+    return undefined;
+}
+/** Whether any of `nodes` names `variable` (a nested function's own `e` counts too: rare, and safe). */
+function mentions(nodes, variable) {
+    const visit = (node) => (ts.isIdentifier(node) && node.text === variable) || ts.forEachChild(node, visit) === true;
+    return nodes.some(visit);
+}
+function ignoringHeadline(classes, variable) {
+    return fitted((cut) => `errors other than ${codeList(classes, cut)} are handled here without ever using \`${variable}\``);
+}
+function headline(classes) {
+    return fitted((cut) => `errors other than ${codeList(classes, cut)} are silently swallowed here`);
+}
+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 chain with a branch for the rest:", [
+        "} else {",
+        `  throw ${variable};`,
+        "}",
+    ]);
+}
+/** The whitespace at the start of the line that holds `position`. */
+function indentationAt(position, text) {
+    const lineStart = text.lastIndexOf("\n", position - 1) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart, position))?.[0] ?? "";
+}
+/** `else { throw e; }` after the last branch, at the indentation of the chain. */
+function rethrowFix(start, end, variable, sourceFile) {
+    const indent = indentationAt(start.getStart(sourceFile), sourceFile.text);
+    const step = indent.includes("\t") ? "\t" : "  ";
+    const at = end.thenStatement.getEnd();
+    return {
+        title: `Rethrow the other errors with \`else { throw ${variable}; }\``,
+        edits: [
+            {
+                location: { file: sourceFile.fileName, start: at, end: at },
+                newText: ` else {\n${indent}${step}throw ${variable};\n${indent}}`,
+            },
+        ],
+    };
+}
+function checkCatch(clause, ctx) {
+    const declaration = clause.variableDeclaration;
+    if (declaration === undefined || !ts.isIdentifier(declaration.name))
+        return;
+    const variable = declaration.name.text;
+    const statements = clause.block.statements;
+    let last;
+    const classes = [];
+    for (const [index, statement] of statements.entries()) {
+        const dispatch = dispatchOf(statement, variable, ctx.sourceFile);
+        if (dispatch === undefined)
+            continue;
+        last = { dispatch, index };
+        for (const name of dispatch.classes)
+            if (!classes.includes(name))
+                classes.push(name);
+    }
+    if (last === undefined)
+        return;
+    const { dispatch, index } = last;
+    // A branch for the rest, or any statement that runs for every error after the chain.
+    const after = statements.slice(index + 1).filter((statement) => !ts.isEmptyStatement(statement));
+    const rest = [...dispatch.rest, ...after];
+    if (rest.length > 0) {
+        if (!ctx.options.restUsesError || mentions(rest, variable))
+            return;
+        ctx.report({
+            node: dispatch.start.getFirstToken(ctx.sourceFile) ?? dispatch.start,
+            message: ignoringHeadline(classes, variable),
+            hint: withExample("rethrow the rest, or pass the error on where you handle it:", [
+                `throw ${variable};`,
+            ]),
+        });
+        return;
+    }
+    const fixes = dispatch.openChainEnd === undefined
+        ? []
+        : [rethrowFix(dispatch.start, dispatch.openChainEnd, variable, ctx.sourceFile)];
+    ctx.report({
+        node: dispatch.start.getFirstToken(ctx.sourceFile) ?? dispatch.start,
+        message: headline(classes),
+        hint: hint(dispatch, variable),
+        fixes,
+    });
+}
+export const catchHidesUnexpected = defineRule({
+    kind: "file",
+    meta: {
+        description: "A catch that handles some errors with instanceof also rethrows or handles all the others.",
+        defaultSeverity: "error",
+        tier: "core",
+        group: GROUP,
+        options: OPTIONS,
+        explain: EXPLAIN,
+    },
+    check(ctx) {
+        const visit = (node) => {
+            if (ts.isCatchClause(node))
+                checkCatch(node, ctx);
+            ts.forEachChild(node, visit);
+        };
+        visit(ctx.sourceFile);
+    },
+});
+//# sourceMappingURL=catch-hides-unexpected.js.map

package/dist/catch-misses-error.d.ts

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