@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/dist/rethrow-unknown.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 rethrowUnknown: import("@stateward/core").FileRule<{
+    restUsesError: import("@stateward/core").BooleanOption;
+}, "catch">;
+//# sourceMappingURL=rethrow-unknown.d.ts.map

package/dist/rethrow-unknown.js

@@ -0,0 +1,260 @@
+import ts from "@stateward/core/typescript";
+import { defineRule, option } from "@stateward/core";
+import { stripParentheses } from "./syntax.js";
+import { HEADLINE_MAX, 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/rethrow-unknown
+
+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/exhaustive-catch\` 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/exhaustive-catch\` looks at what that \`else\` does with the error.
+- A \`catch\` with no \`instanceof\` chain that ignores the error: that is \`errors/no-swallow\`.
+
+## Turn it on or off
+
+In \`stateward.config.ts\`:
+
+\`\`\`ts
+rules: { "errors/rethrow-unknown": "off" } // or "warning"
+groups: { "errors/catch": "off" } // the whole group
+rules: { "errors/rethrow-unknown": ["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(HEADLINE_MAX, (cut) => `errors other than ${codeList(classes, cut)} are handled here without ever using \`${variable}\``);
+}
+function headline(classes) {
+    return fitted(HEADLINE_MAX, (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 rethrowUnknown = 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=rethrow-unknown.js.map

package/dist/rules.meta.d.ts

@@ -0,0 +1,214 @@
+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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "catch";
+            readonly options: {
+                readonly restUsesError: {
+                    readonly kind: "boolean";
+                    readonly default: false;
+                    readonly description: "The branch for the other errors must use the error (rethrow it, wrap it, report it); a generic message alone does not count.";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "catch";
+            readonly options: {
+                readonly severities: {
+                    readonly kind: "severities";
+                    readonly default: {};
+                    readonly kinds: {
+                        readonly throw: "a `throw` written in the finally: it throws whenever it runs.";
+                        readonly builtin: "a built-in such as `JSON.parse` or `new URL`: it throws only on input it cannot handle.";
+                        readonly "own-function": "a function in the same file with a `throw` in it: it throws on some paths.";
+                    };
+                    readonly description: "A severity per kind of call, where you trust one kind less.";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "catch";
+            readonly needsJsDoc: true;
+            readonly options: {
+                readonly ignoreClasses: {
+                    readonly kind: "strings";
+                    readonly default: readonly [];
+                    readonly description: "Error classes a catch never needs a branch for, as its instanceof test names them (SyntaxError, *AbortError).";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "callers";
+            readonly needsJsDoc: true;
+            readonly options: {
+                readonly severities: {
+                    readonly kind: "severities";
+                    readonly default: {};
+                    readonly kinds: {
+                        readonly missing: "the function can throw a class its `@throws` does not list.";
+                        readonly extra: "the `@throws` lists a class the function cannot throw (stale, not dangerous).";
+                    };
+                    readonly description: "A severity per kind of mismatch.";
+                };
+                readonly ignoreClasses: {
+                    readonly kind: "strings";
+                    readonly default: readonly [];
+                    readonly description: "Error classes a `@throws` never needs to list (TypeError, *AbortError), as a catch names them.";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "warning";
+            readonly tier: "core";
+            readonly group: "render";
+            readonly needsJsDoc: true;
+            readonly options: {
+                readonly skipContextGuards: {
+                    readonly kind: "boolean";
+                    readonly default: true;
+                    readonly description: "Leave out the usual check in a context hook: `if (!ctx) throw new Error(\"useAuth must be used within AuthProvider\")`.";
+                };
+                readonly skipInputGuards: {
+                    readonly kind: "boolean";
+                    readonly default: true;
+                    readonly description: "Leave out a throw when a prop or a parameter whose type rules it out, or a context hook's value, is missing (a mistake of the caller).";
+                };
+                readonly rootBoundaryCounts: {
+                    readonly kind: "boolean";
+                    readonly default: false;
+                    readonly description: "Count the error boundary around the whole app as handling the error. Off by default: the whole app is then replaced by its fallback, so the rule asks for a boundary nearer the page.";
+                };
+                readonly boundaries: {
+                    readonly kind: "record";
+                    readonly default: {
+                        readonly "react-error-boundary": readonly ["ErrorBoundary"];
+                    };
+                    readonly description: "Error boundary components from packages, by package: add Sentry's with `{ \"@sentry/react\": [\"ErrorBoundary\"] }` (keep react-error-boundary's to keep it).";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "callers";
+            readonly needsJsDoc: true;
+            readonly listUnknowns: true;
+        };
+    };
+    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 defaultSeverity: "warning";
+            readonly tier: "addon";
+            readonly addon: "narrow-try";
+            readonly group: "catch";
+            readonly needsJsDoc: true;
+        };
+    };
+    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 defaultSeverity: "error";
+            readonly tier: "core";
+            readonly group: "callers";
+            readonly yieldsTo: readonly ["result-unchecked"];
+            readonly options: {
+                readonly allowVoid: {
+                    readonly kind: "boolean";
+                    readonly default: false;
+                    readonly description: "Take `void save()` as dropping the Result on purpose, and stay quiet.";
+                };
+                readonly resultTypes: {
+                    readonly kind: "strings";
+                    readonly default: readonly [];
+                    readonly description: "Your names for a Result type whose shape stateward does not recognise (`Either`, `Outcome*`; globs allowed).";
+                };
+                readonly ignore: {
+                    readonly kind: "strings";
+                    readonly default: readonly [];
+                    readonly description: "Functions whose Result may be dropped, by the name they are called with (`logEvent`, `*.track`; globs allowed).";
+                };
+            };
+        };
+    };
+    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 defaultSeverity: "warning";
+            readonly tier: "core";
+            readonly group: "callers";
+            readonly heuristic: true;
+        };
+    };
+};
+//# sourceMappingURL=rules.meta.d.ts.map