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

package/dist/render-throws-without-boundary.js

@@ -1,151 +0,0 @@
-import { defineRule, highestUncovered, option, shortestPath } from "@stateward/core";
-import { className } from "./inference/format.js";
-import { modelOf, summarizeReact } from "./react/boundaries.js";
-import { LIBRARY_BOUNDARIES } from "./react/tree.js";
-import { HEADLINE_MAX, codeList, fitted, withExample } from "./text.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "react";
-const EXPLAIN = `# errors/render-throws-without-boundary
-
-A component that can throw a known error while rendering has an error boundary above it.
-
-## Why
-
-When a component throws while React renders it, or in one of its effects, React unmounts everything up to the nearest error boundary. With no boundary above, the whole app goes blank. A \`<UserPage>\` whose \`useUser\` throws \`NotFoundError\` for a wrong id takes the menu, the header and every other route down with it, where a boundary could have shown "this user does not exist".
-
-## When to use it
-
-Use it in React apps whose code throws its own error classes. It is a core rule, a warning in every preset: whether a page should handle an error itself or let a boundary do it is your call. If every throw in render is a bug you want to see crash in development, turn it off.
-
-## What it catches
-
-A place that renders a component which can throw a known error while rendering, with no error boundary above it on the way from your entry point (\`createRoot(…).render(…)\` or \`hydrateRoot\`). The component counts what its body and its hooks throw, what its \`useEffect\` and \`useLayoutEffect\` callbacks throw, and what the components it renders outside a boundary throw. A boundary is react-error-boundary's \`<ErrorBoundary>\` (the \`boundaries\` option adds other packages' boundaries), or a class of yours with \`getDerivedStateFromError\` or \`componentDidCatch\`.
-
-It is reported once, at the highest place where the boundary is missing, with the path down to the call that throws. With a boundary around the whole app, it says nothing.
-
-### Bad
-
-\`\`\`tsx
-// useUser throws NotFoundError for an id it does not know.
-createRoot(root).render(<App />); // App renders <UserPage /> for /users/:id
-\`\`\`
-
-### Good
-
-\`\`\`tsx
-createRoot(root).render(
-  <ErrorBoundary FallbackComponent={ErrorPage}>
-    <App />
-  </ErrorBoundary>,
-);
-\`\`\`
-
-### Fix
-
-Put an error boundary above the place the message names, or nearer to the component that throws (around one route). There is no quick fix: where the boundary goes, and what it shows, is your call.
-
-## What it does not catch
-
-- Errors in event handlers, timers and async code: a boundary never catches them, so they are not counted. \`errors/async-handler-unhandled\` checks async handlers.
-- Errors stateward cannot see (a package it cannot read, a callback, a dynamic call): it is about known error classes, so these never make a finding. The hover on a boundary lists them.
-- An app with no \`createRoot(…).render(…)\` or \`hydrateRoot\` it can find: nothing is checked.
-- Routes in \`createBrowserRouter([...])\` route objects: React Router catches their errors itself (\`errorElement\`). \`memo\`, \`forwardRef\` and \`lazy\` components, and boundaries from other packages you have not listed in \`boundaries\`, are not followed.
-- An element passed to a function or stored in an object or array (\`showToast(<UserPage />)\`): where it renders cannot be followed, so it never makes a finding. An element held in a local \`const\` or \`let\` is checked where the variable is rendered.
-- A class that a \`try\` in the component may catch (with a test other than \`instanceof\`): it is not counted.
-
-## Turn it on or off
-
-In \`stateward.config.ts\`:
-
-\`\`\`ts
-rules: { "errors/render-throws-without-boundary": "off" } // or "error"
-groups: { "errors/react": "off" } // the whole group
-rules: {
-  "errors/render-throws-without-boundary": [
-    "warning",
-    { boundaries: { "react-error-boundary": ["ErrorBoundary"], "@sentry/react": ["ErrorBoundary"] } },
-  ],
-} // Sentry's boundary counts too
-\`\`\`
-`;
-/** At most this many notes; a longer path keeps its first steps and its last. */
-const MAX_NOTES = 5;
-function headline(component, names) {
-    return fitted(HEADLINE_MAX, (cut) => `\`<${cut(component)}>\` can throw ${codeList(names, cut)} while rendering, with no error boundary above it`);
-}
-function hint(component) {
-    return withExample("wrap it in an error boundary, here or nearer to what throws; for example with react-error-boundary:", ["<ErrorBoundary FallbackComponent={ErrorPage}>", `  <${component} />`, "</ErrorBoundary>"]);
-}
-/** The renders down from the site to the component that throws `cls`, then the call that throws it. */
-function pathNotes(model, site, cls) {
-    const classes = model.analysis.classes;
-    const path = shortestPath(site.to, (id) => model.edges(id), (edge) => model.nearest(edge) === undefined && model.needs(edge.to).has(cls), (id) => model.own(id).classes.get(cls)?.certain === true);
-    if (path === undefined)
-        return [];
-    const notes = path.map((edge) => ({
-        location: { file: edge.file, start: edge.render.at[0], end: edge.render.at[1] },
-        message: `\`<${edge.render.name}>\` is rendered here`,
-    }));
-    const thrower = path.at(-1)?.to ?? site.to;
-    const brought = model.own(thrower).classes.get(cls);
-    if (brought !== undefined) {
-        notes.push({
-            location: brought.location,
-            message: `${brought.what} \`${className(cls, classes)}\``,
-        });
-    }
-    if (notes.length <= MAX_NOTES)
-        return notes;
-    const skipped = notes.length - (MAX_NOTES - 1);
-    const last = notes.at(-1);
-    const head = notes.slice(0, MAX_NOTES - 2);
-    const first = notes[MAX_NOTES - 2];
-    return first === undefined || last === undefined
-        ? head
-        : [...head, { location: first.location, message: `… ${String(skipped)} more steps …` }, last];
-}
-export const renderThrowsWithoutBoundary = defineRule({
-    kind: "project",
-    meta: {
-        description: "A component that can throw a known error while rendering has an error boundary above it.",
-        defaultSeverity: "warning",
-        tier: "core",
-        group: GROUP,
-        needsJsDoc: true,
-        options: {
-            boundaries: option.record({
-                default: LIBRARY_BOUNDARIES,
-                description: 'Error boundary components from packages, by package: add Sentry\'s with `{ "@sentry/react": ["ErrorBoundary"] }` (keep react-error-boundary\'s to keep it).',
-            }),
-        },
-        explain: EXPLAIN,
-    },
-    summarize: (ctx) => summarizeReact(ctx, ctx.options.boundaries),
-    check(summaries, ctx) {
-        const model = modelOf(summaries);
-        const classes = model.analysis.classes;
-        const found = highestUncovered({
-            roots: model.entries,
-            edges: (id) => model.edges(id),
-            covered: (edge) => model.nearest(edge) !== undefined,
-            needs: (id) => model.needs(id),
-            key: (edge) => `${edge.file}:${String(edge.render.at[0])}`,
-        });
-        for (const { edge, needs } of found) {
-            const named = needs
-                .map((id) => ({ id, name: className(id, classes) }))
-                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-            const [first] = named;
-            if (first === undefined)
-                continue;
-            const component = model.functions.get(edge.to)?.fn.name ?? edge.render.name;
-            ctx.report({
-                message: headline(component, named.map((one) => one.name)),
-                hint: hint(edge.render.name),
-                location: { file: edge.file, start: edge.render.at[0], end: edge.render.at[1] },
-                related: pathNotes(model, edge, first.id),
-            });
-        }
-    },
-});
-//# sourceMappingURL=render-throws-without-boundary.js.map

package/dist/rethrow-unknown.d.ts

@@ -1,6 +0,0 @@
-/** 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

@@ -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