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

package/dist/no-swallow.js

@@ -1,320 +0,0 @@
-import ts from "@stateward/core/typescript";
-import { defineRule, matchesName, option } from "@stateward/core";
-import { withExample } from "./text.js";
-import { stripParentheses } from "./syntax.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "catch";
-const EXPLAIN = `# errors/no-swallow
-
-A catch that only logs, or does nothing, and then carries on treats a failure as if it had not happened.
-
-## Why
-
-In \`load\`, a failed \`fetchUser\` is logged and \`render(user)\` runs anyway, with a \`user\` that was never fetched. The page shows a blank profile instead of an error, and the only trace is a line in the console.
-
-## When to use it
-
-Use it for code that must never lose a failure: payments, sync, data import; or to review a module's catches once. In most apps many catches that only log are deliberate fallbacks (a setting read from storage, a best-effort cache write), so it is off until you add its add-on (below), then a warning in every preset. Make it an error once that code is clean.
-
-## What it catches
-
-A \`catch\` that is empty or only logs (\`console.*\`, a call on \`logger\` or \`log\`, or \`.error\`, \`.warn\`, \`.info\`, \`.debug\` on any object; the options below change these lists), when the function carries on after the \`try\`.
-
-### Bad
-
-\`\`\`ts
-async function load(id: string) {
-  let user;
-  try {
-    user = await fetchUser(id);
-  } catch (e) {
-    console.error(e);
-  }
-  return render(user);
-}
-\`\`\`
-
-### Good
-
-\`\`\`ts
-async function load(id: string) {
-  try {
-    return render(await fetchUser(id));
-  } catch (e) {
-    return err(e);
-  }
-}
-\`\`\`
-
-### Fix
-
-Rethrow the error, return a failure the caller can see, or show it to the user. The message shows \`throw e;\`, or \`return err(e);\` when the file imports \`err\` from \`@stateward/values\`. There is no quick fix.
-
-## What it does not catch
-
-It stays quiet when:
-
-- the \`catch\` does anything else (\`return\`, \`throw\`, a call that shows the error);
-- an empty \`catch\` holds a comment, which says it is on purpose;
-- the \`try\` returns its value and the code after it returns a default (\`try { return JSON.parse(stored); } catch (e) { console.warn(e); } return defaults;\`);
-- every variable the \`try\` assigns already had a value to fall back on (\`let flags = DEFAULTS; try { flags = JSON.parse(stored); } catch …\`; a parameter counts, a \`let\` with no value does not);
-- the \`try\` is the last thing the function, or a loop's body, does (a retry loop moves on to the next attempt).
-
-A function of your own that only logs is not recognised as logging until you list it in \`logFunctions\`.
-
-## Turn it on or off
-
-Turn it on in \`stateward.config.ts\`:
-
-\`\`\`ts
-addons: ["errors/swallow"]
-\`\`\`
-
-Then change or turn off the rule itself:
-
-\`\`\`ts
-rules: { "errors/no-swallow": "off" } // or "error"
-groups: { "errors/catch": "off" } // the whole group
-rules: { "errors/no-swallow": ["warning", { logFunctions: ["logError"] }] } // your own log helpers
-\`\`\`
-`;
-const OPTIONS = {
-    loggers: option.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: option.strings({
-        default: ["error", "warn", "info", "debug"],
-        description: "Method names that only log, on any object (`Sentry.captureException` is not one).",
-    }),
-    logFunctions: option.strings({
-        default: [],
-        description: "Plain functions of your own that only log, like logError (globs allowed).",
-    }),
-};
-/** The name an expression ends in: `logger`, `this.logger`, `app.log`. */
-function lastName(expression) {
-    const node = stripParentheses(expression);
-    if (ts.isIdentifier(node))
-        return node.text;
-    return ts.isPropertyAccessExpression(node) ? node.name.text : undefined;
-}
-/**
- * A call that only logs: any method of a logger (`console.x()`, `logger.x()`), a log method on any
- * object (`app.warn()`), or one of the team's own log functions (`logError(e)`).
- */
-function isLoggingCall(expression, logging) {
-    const call = stripParentheses(expression);
-    if (!ts.isCallExpression(call))
-        return false;
-    const callee = stripParentheses(call.expression);
-    if (ts.isIdentifier(callee))
-        return matchesName(callee.text, logging.logFunctions);
-    if (!ts.isPropertyAccessExpression(callee))
-        return false;
-    if (logging.logMethods.includes(callee.name.text))
-        return true;
-    const name = lastName(stripParentheses(callee.expression));
-    return name !== undefined && matchesName(name, logging.loggers);
-}
-/** What the catch does: nothing, or only log. Undefined when it does anything else. */
-function swallowKind(block, sourceFile, logging) {
-    const statements = block.statements.filter((statement) => !ts.isEmptyStatement(statement));
-    if (statements.length === 0) {
-        // A comment inside an empty catch says it is on purpose.
-        return hasComment(block, sourceFile) ? undefined : "ignores";
-    }
-    const onlyLogs = statements.every((statement) => ts.isExpressionStatement(statement) && isLoggingCall(statement.expression, logging));
-    return onlyLogs ? "logs" : undefined;
-}
-function hasComment(block, sourceFile) {
-    const inner = sourceFile.text.slice(block.getStart(sourceFile) + 1, block.getEnd() - 1);
-    return inner.trim() !== "";
-}
-/** Statements that run nothing: a bare `;` and declarations that only exist at compile time. */
-function runsNothing(statement) {
-    return (ts.isEmptyStatement(statement) ||
-        ts.isFunctionDeclaration(statement) ||
-        ts.isInterfaceDeclaration(statement) ||
-        ts.isTypeAliasDeclaration(statement));
-}
-/** `return;`, `break;` and `continue;` end the flow: nothing after them carries on. */
-function endsFlow(statement) {
-    if (ts.isReturnStatement(statement))
-        return statement.expression === undefined;
-    return ts.isBreakStatement(statement) || ts.isContinueStatement(statement);
-}
-/**
- * Whether the function runs something after the `try` statement: a statement that follows it in
- * its block or in a block around it, up to the function (or the file, for top-level code). The end
- * of a loop's body runs nothing after it: the loop goes on to its next turn (a retry loop's next
- * attempt).
- */
-function continuesAfter(tryStatement) {
-    let node = tryStatement;
-    for (let parent = node.parent;; parent = node.parent) {
-        if (ts.isFunctionLike(parent))
-            return false;
-        if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isCaseOrDefaultClause(parent)) {
-            const statements = parent.statements;
-            const after = statements.slice(statements.findIndex((candidate) => candidate === node) + 1);
-            const next = after.find((statement) => !runsNothing(statement));
-            if (next !== undefined)
-                return !endsFlow(next);
-        }
-        if (ts.isSourceFile(parent))
-            return false;
-        if (ts.isIterationStatement(parent, false) && parent.statement === node)
-            return false;
-        node = parent;
-    }
-}
-/** Whether `node` has a `return` with a value that runs in this function (not in a nested one). */
-function returnsValue(node) {
-    if (ts.isReturnStatement(node))
-        return node.expression !== undefined;
-    if (ts.isFunctionLike(node) || ts.isClassLike(node))
-        return false;
-    return ts.forEachChild(node, (child) => (returnsValue(child) ? true : undefined)) === true;
-}
-/**
- * A fallback: the `try` returns the value it produced, and the statement right after it returns
- * another one (`try { return JSON.parse(stored); } catch (e) { console.warn(e); } return
- * defaults;`). The caller gets a value either way; nothing runs on a result that was never made.
- */
-function fallsBackToAValue(tryStatement) {
-    const list = tryStatement.parent;
-    if (!ts.isBlock(list) && !ts.isSourceFile(list) && !ts.isCaseOrDefaultClause(list))
-        return false;
-    const after = list.statements.slice(list.statements.indexOf(tryStatement) + 1);
-    const next = after.find((statement) => !runsNothing(statement));
-    return (next !== undefined &&
-        ts.isReturnStatement(next) &&
-        next.expression !== undefined &&
-        returnsValue(tryStatement.tryBlock));
-}
-/** The names the `try` block assigns with `=` (not in a nested function): `flags = parse(…)`. */
-function assignedNames(block) {
-    const names = [];
-    const visit = (node) => {
-        if (ts.isFunctionLike(node) || ts.isClassLike(node))
-            return;
-        if (ts.isBinaryExpression(node) &&
-            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
-            ts.isIdentifier(stripParentheses(node.left))) {
-            const target = stripParentheses(node.left);
-            if (ts.isIdentifier(target))
-                names.push(target.text);
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(block);
-    return names;
-}
-/**
- * Whether `name` already holds a value before the `try`: a `let` or `var` declared with an
- * initializer in a block around it (before it, up to the module), or a parameter of a function
- * around it.
- */
-function holdsAValueBefore(name, tryStatement) {
-    let node = tryStatement;
-    for (let parent = node.parent;; parent = node.parent) {
-        if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isCaseOrDefaultClause(parent)) {
-            const before = parent.statements.slice(0, parent.statements.findIndex((s) => s === node));
-            for (const statement of before) {
-                if (!ts.isVariableStatement(statement))
-                    continue;
-                for (const declaration of statement.declarationList.declarations) {
-                    if (ts.isIdentifier(declaration.name) && declaration.name.text === name) {
-                        return declaration.initializer !== undefined;
-                    }
-                }
-            }
-        }
-        // A parameter holds the caller's value; past it, a closure's or the module's variable.
-        if (ts.isFunctionLike(parent) &&
-            parent.parameters.some((parameter) => ts.isIdentifier(parameter.name) && parameter.name.text === name)) {
-            return true;
-        }
-        if (ts.isSourceFile(parent))
-            return false;
-        node = parent;
-    }
-}
-/**
- * A fallback assigned before the `try`: every variable the `try` assigns already held a value
- * (`let flags = DEFAULTS; try { flags = parse(…); } catch (e) { log(e); } return flags;`). The
- * code after the `try` runs on that value when the `try` fails, which is what the author chose.
- */
-function replacesAFallback(tryStatement) {
-    const names = assignedNames(tryStatement.tryBlock);
-    return names.length > 0 && names.every((name) => holdsAValueBefore(name, tryStatement));
-}
-function headline(kind) {
-    return `this catch ${kind} the error and carries on as if nothing failed`;
-}
-/** The local name of `err` when the file imports it from `@stateward/values`. */
-function importedErr(sourceFile) {
-    for (const statement of sourceFile.statements) {
-        if (!ts.isImportDeclaration(statement) ||
-            !ts.isStringLiteral(statement.moduleSpecifier) ||
-            statement.moduleSpecifier.text !== "@stateward/values" ||
-            statement.importClause?.phaseModifier === ts.SyntaxKind.TypeKeyword) {
-            continue;
-        }
-        const bindings = statement.importClause?.namedBindings;
-        if (bindings === undefined || !ts.isNamedImports(bindings))
-            continue;
-        const element = bindings.elements.find((candidate) => !candidate.isTypeOnly && (candidate.propertyName ?? candidate.name).text === "err");
-        if (element !== undefined)
-            return element.name.text;
-    }
-    return undefined;
-}
-/** The example uses only what the file has: `err` when it imports it, else a plain rethrow. */
-function hint(variable, sourceFile) {
-    const err = importedErr(sourceFile);
-    return withExample("rethrow it, return a failure the caller can see, or show it to the user:", [
-        err === undefined ? `throw ${variable};` : `return ${err}(${variable});`,
-    ]);
-}
-function checkCatch(clause, ctx) {
-    const kind = swallowKind(clause.block, ctx.sourceFile, ctx.options);
-    if (kind === undefined ||
-        !continuesAfter(clause.parent) ||
-        fallsBackToAValue(clause.parent) ||
-        replacesAFallback(clause.parent)) {
-        return;
-    }
-    const declaration = clause.variableDeclaration;
-    const variable = declaration !== undefined && ts.isIdentifier(declaration.name)
-        ? declaration.name.text
-        : "error";
-    ctx.report({
-        node: clause.getFirstToken(ctx.sourceFile) ?? clause,
-        message: headline(kind),
-        hint: hint(variable, ctx.sourceFile),
-    });
-}
-export const noSwallow = defineRule({
-    kind: "file",
-    meta: {
-        description: "A catch that only logs, or does nothing, and then carries on treats a failure as if it had not happened.",
-        defaultSeverity: "warning",
-        tier: "addon",
-        addon: "swallow",
-        group: GROUP,
-        heuristic: true,
-        options: OPTIONS,
-        explain: EXPLAIN,
-    },
-    check(ctx) {
-        const visit = (node) => {
-            if (ts.isCatchClause(node))
-                checkCatch(node, ctx);
-            ts.forEachChild(node, visit);
-        };
-        visit(ctx.sourceFile);
-    },
-});
-//# sourceMappingURL=no-swallow.js.map

package/dist/render-throws-without-boundary.d.ts

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

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