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

package/dist/rethrow-unknown.js

@@ -1,260 +0,0 @@
-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/throw-in-hook.d.ts

@@ -1,8 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "react";
-export declare const throwInHook: import("@stateward/core").FileRule<{
-    skipContextGuards: import("@stateward/core").BooleanOption;
-    skipInputGuards: import("@stateward/core").BooleanOption;
-    ignore: import("@stateward/core").StringsOption;
-}, "react">;
-//# sourceMappingURL=throw-in-hook.d.ts.map