@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/dist/refactors.d.ts

@@ -0,0 +1,15 @@
+import type { EditorContributions } from "@stateward/core";
+type CodeActions = NonNullable<EditorContributions["codeActions"]>;
+/** The title of the refactoring that wraps a catch-all for the errors its `try` can throw. */
+export declare const HANDLE_KNOWN_TITLE = "Handle the known errors here, rethrow the rest";
+/**
+ * On a `catch (e)` with no `instanceof` branches, whose `try` can throw at least one error class
+ * stateward can name and whose body does not already throw: wraps the body as
+ * `if (e instanceof A || e instanceof B) { <old body> } else { throw e; }`. Two insertions, so the
+ * old body stays as written. It keeps what the catch does for the known errors and stops hiding
+ * the others, which is why it is a refactoring and not a "safe" fix. Core offers it only when the
+ * result compiles (a class the file does not import gets no action).
+ */
+export declare const codeActions: CodeActions;
+export {};
+//# sourceMappingURL=refactors.d.ts.map

package/dist/refactors.js

@@ -0,0 +1,69 @@
+import ts from "@stateward/core/typescript";
+import { catchesOf } from "./inference/catches.js";
+import { catchName } from "./inference/format.js";
+import { analyse } from "./inference/solve.js";
+import { factSummaries } from "./inlay.js";
+/** The title of the refactoring that wraps a catch-all for the errors its `try` can throw. */
+export const HANDLE_KNOWN_TITLE = "Handle the known errors here, rethrow the rest";
+/**
+ * On a `catch (e)` with no `instanceof` branches, whose `try` can throw at least one error class
+ * stateward can name and whose body does not already throw: wraps the body as
+ * `if (e instanceof A || e instanceof B) { <old body> } else { throw e; }`. Two insertions, so the
+ * old body stays as written. It keeps what the catch does for the known errors and stops hiding
+ * the others, which is why it is a refactoring and not a "safe" fix. Core offers it only when the
+ * result compiles (a class the file does not import gets no action).
+ */
+export const codeActions = (input) => {
+    const summaries = factSummaries(input);
+    if (summaries === undefined)
+        return [];
+    const { sourceFile } = input;
+    const clauses = [];
+    const visit = (node) => {
+        if (ts.isCatchClause(node)) {
+            // The head: `catch (e) {`.
+            const head = [node.getStart(sourceFile), node.block.getStart(sourceFile) + 1];
+            if (head[0] <= input.end && input.start <= head[1])
+                clauses.push(node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    if (clauses.length === 0)
+        return [];
+    const analysis = analyse(summaries);
+    const catches = new Map(catchesOf(analysis, sourceFile.fileName).map((seen) => [seen.handler.at[0], seen]));
+    const actions = [];
+    for (const clause of clauses) {
+        const seen = catches.get(clause.getStart(sourceFile));
+        const variable = seen?.handler.variable;
+        if (seen === undefined ||
+            variable === null ||
+            variable === undefined ||
+            seen.handler.branches.length > 0 ||
+            seen.handler.restThrows ||
+            seen.handler.block[0] !== clause.block.getStart(sourceFile)) {
+            continue;
+        }
+        const names = [
+            ...new Set([...seen.thrown.classes.keys()].map((id) => catchName(id, analysis.classes))),
+        ].sort();
+        if (names.length === 0)
+            continue;
+        const tests = names.map((name) => `${variable} instanceof ${name}`).join(" || ");
+        const [open, close] = seen.handler.block;
+        const at = (offset, newText) => ({
+            location: { file: input.file, start: offset, end: offset },
+            newText,
+        });
+        actions.push({
+            title: HANDLE_KNOWN_TITLE,
+            edits: [
+                at(open + 1, `\nif (${tests}) {`),
+                at(close - 1, `\n} else {\nthrow ${variable};\n}\n`),
+            ],
+        });
+    }
+    return actions;
+};
+//# sourceMappingURL=refactors.js.map

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

@@ -0,0 +1,11 @@
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export declare const GROUP = "render";
+/** The reason `plan` gives when a root boundary makes the rule silent. */
+export declare const ROOT_BOUNDARY_SILENT = "your app's root has an error boundary";
+export declare const renderThrowWithoutBoundary: import("@stateward/core").ProjectRule<import("./react/boundaries.js").ReactSummary, {
+    skipContextGuards: import("@stateward/core").BooleanOption;
+    skipInputGuards: import("@stateward/core").BooleanOption;
+    rootBoundaryCounts: import("@stateward/core").BooleanOption;
+    boundaries: import("@stateward/core").RecordOption;
+}, "render">;
+//# sourceMappingURL=render-throw-without-boundary.d.ts.map

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

@@ -0,0 +1,223 @@
+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 { codeList, fitted, withExample } from "./text.js";
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export const GROUP = "render";
+const EXPLAIN = `# errors/render-throw-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.
+
+A boundary around the whole app (the one that wraps the tree at \`createRoot(…).render(…)\`) does not count: it catches the error, but the whole app is replaced by its fallback, which is rarely what you want for one page. The finding is then at the highest place below it that renders the component that throws. If an app-wide fallback is what you want, set \`rootBoundaryCounts\` to \`true\`: the rule then says nothing for an app with a boundary at its root, and \`stateward plan\` says so (\`silent: your app's root has an error boundary\`).
+
+Two kinds of throw are left out, since they name a programming mistake of the caller rather than a failure to show: the usual check in a context hook (\`if (!ctx) throw new Error("useAuth must be used within AuthProvider")\` on a value from \`useContext\`, or a comparison with a "missing" constant declared at the top of the file), and a check on what the caller passed when its type already rules the value out (\`props.title === undefined\` with \`title: string\`, a missing value from a context hook). A check on an optional prop or a parameter that can be \`undefined\` (\`title?: string\`, \`useLabel(label: string | undefined)\`) counts: any caller can leave it out, so it is a failure to show. A throw on a truthy value (\`if (error) throw error\`) or on a comparison (\`id === ""\`) still counts. Set \`skipContextGuards\` or \`skipInputGuards\` to \`false\` to count those too.
+
+### 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. \`async/handler-rejection-lost\` 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.
+- A throw that is not of a known error class (\`throw "no cart"\`), and a thrown promise (Suspense).
+
+## Turn it on or off
+
+In \`stateward.config.ts\`:
+
+\`\`\`ts
+rules: { "errors/render-throw-without-boundary": "off" } // or "error"
+groups: { "errors/react": "off" } // the whole group
+rules: {
+  "errors/render-throw-without-boundary": [
+    "warning",
+    { boundaries: { "react-error-boundary": ["ErrorBoundary"], "@sentry/react": ["ErrorBoundary"] } },
+  ],
+} // Sentry's boundary counts too
+rules: {
+  "errors/render-throw-without-boundary": ["warning", { rootBoundaryCounts: true }],
+} // a boundary around the whole app is enough
+\`\`\`
+`;
+/** 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((cut) => `\`<${cut(component)}>\` can throw ${codeList(names, cut)} while rendering, with no error boundary above it`);
+}
+/** A throw that only the boundary around the whole app catches (`rootBoundaryCounts` is off). */
+function rootHeadline(component, names) {
+    return fitted((cut) => `\`<${cut(component)}>\` can throw ${codeList(names, cut)} while rendering; only the app-wide boundary catches it`);
+}
+function rootHint(component) {
+    return withExample("the whole app is replaced; add a boundary around it, or set `rootBoundaryCounts` if that is what you want", ["<ErrorBoundary FallbackComponent={ErrorPage}>", `  <${component} />`, "</ErrorBoundary>"]);
+}
+/** The reason `plan` gives when a root boundary makes the rule silent. */
+export const ROOT_BOUNDARY_SILENT = "your app's root has an error boundary";
+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 && !model.own(id).guarded.has(cls));
+    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];
+}
+/** Whether an error boundary of the project wraps the entry render: the app-wide boundary. */
+function rootBoundaryOf(model, entry) {
+    const key = model.nearest(entry);
+    return key !== undefined && model.boundaries.has(key);
+}
+/**
+ * Where the walk starts below an entry with a root boundary: the renders in its component, or the
+ * entry itself when the component throws on its own (nothing nearer can be named then).
+ */
+function belowRoot(model, entry) {
+    const own = model.own(entry.to);
+    const throwsItself = [...own.classes].some(([cls, brought]) => brought.certain && !own.guarded.has(cls));
+    return throwsItself ? [entry] : model.edges(entry.to);
+}
+export const renderThrowWithoutBoundary = 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: {
+            skipContextGuards: option.boolean({
+                default: true,
+                description: 'Leave out the usual check in a context hook: `if (!ctx) throw new Error("useAuth must be used within AuthProvider")`.',
+            }),
+            skipInputGuards: option.boolean({
+                default: true,
+                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).",
+            }),
+            rootBoundaryCounts: option.boolean({
+                default: false,
+                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.",
+            }),
+            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, {
+        contextGuards: ctx.options.skipContextGuards,
+        inputGuards: ctx.options.skipInputGuards,
+    }),
+    silentReason(summaries, ctx) {
+        if (!ctx.options.rootBoundaryCounts)
+            return undefined;
+        const model = modelOf(summaries);
+        return model.entries.length > 0 && model.entries.every((entry) => rootBoundaryOf(model, entry))
+            ? ROOT_BOUNDARY_SILENT
+            : undefined;
+    },
+    check(summaries, ctx) {
+        const model = modelOf(summaries);
+        const classes = model.analysis.classes;
+        const walk = (roots, open = []) => highestUncovered({
+            roots,
+            edges: (id) => model.edges(id),
+            covered: (edge) => !open.includes(edge) && model.nearest(edge) !== undefined,
+            needs: (id) => model.needs(id),
+            key: (edge) => `${edge.file}:${String(edge.render.at[0])}`,
+        });
+        // An entry with a boundary around it yields nothing in the plain walk. Unless the root
+        // boundary counts, the walk starts again below it, and what it finds is for the root message.
+        const rooted = ctx.options.rootBoundaryCounts
+            ? []
+            : model.entries.filter((entry) => rootBoundaryOf(model, entry));
+        const reported = new Set();
+        const places = [
+            ...walk(model.entries).map((found) => ({ ...found, root: false })),
+            ...walk(rooted.flatMap((entry) => belowRoot(model, entry)), rooted).map((found) => ({
+                ...found,
+                root: true,
+            })),
+        ];
+        for (const { edge, needs, root } of places) {
+            const key = `${edge.file}:${String(edge.render.at[0])}`;
+            if (reported.has(key))
+                continue;
+            reported.add(key);
+            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;
+            const names = named.map((one) => one.name);
+            ctx.report({
+                message: root ? rootHeadline(component, names) : headline(component, names),
+                hint: root ? rootHint(edge.render.name) : 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-throw-without-boundary.js.map

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

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

@@ -0,0 +1,151 @@
+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/result-ignored.d.ts

@@ -0,0 +1,6 @@
+export declare const resultIgnored: import("@stateward/core").FileRule<{
+    allowVoid: import("@stateward/core").BooleanOption;
+    resultTypes: import("@stateward/core").StringsOption;
+    ignore: import("@stateward/core").StringsOption;
+}, "callers">;
+//# sourceMappingURL=result-ignored.d.ts.map

package/dist/result-ignored.js

@@ -0,0 +1,167 @@
+import ts from "@stateward/core/typescript";
+import { defineRule, matchesName, option } from "@stateward/core";
+import { example, resultShapeOf, shorten } from "./result-type.js";
+const EXPLAIN = `# errors/result-ignored
+
+The Result of a call is checked or passed on, not dropped as a statement, after void or after await.
+
+## Why
+
+A \`Result\` is how a function says "this can fail". Call \`saveUser(user)\` as a statement and the answer is thrown away: nobody sees the error, and the code goes on as if the user was saved. The failure shows up later, as missing data.
+
+## When to use it
+
+Use it if your functions return a \`Result\` instead of throwing: your own, neverthrow's, or a \`safeParse\` result. It is on as an error in every preset. To drop a result on purpose, list the function in \`ignore\`, or set \`allowVoid\` and write \`void save()\`.
+
+## What it catches
+
+A call whose value is a Result (or a \`Promise\` of one) that is dropped: written as a statement, after \`void\`, or after \`await\` on its own. A Result is recognised by its shape, so no library is needed:
+
+- a union told apart by \`ok: true\` and \`ok: false\` (\`{ ok: true; value: T } | { ok: false; error: E }\`);
+- a union told apart by \`success: true\` and \`success: false\` (zod's \`safeParse\`);
+- a type with \`isOk()\` and \`isErr()\` methods (neverthrow);
+- a type the \`resultTypes\` option names (\`["Result", "Either"]\`), whatever its shape.
+
+### Bad
+
+\`\`\`ts
+type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
+declare function saveUser(user: User): Promise<Result<void>>;
+
+await saveUser(user);
+\`\`\`
+
+### Good
+
+\`\`\`ts
+const saved = await saveUser(user);
+if (!saved.ok) return saved;
+\`\`\`
+
+### Fix
+
+Check the result, or return it to your caller; the message shows how with your names and your Result's shape. There is no quick fix.
+
+## What it does not catch
+
+- A result that is assigned, returned, passed on, used in a condition or spread.
+- A Result of another shape (an \`Either\` with \`_tag\`, a tuple \`[error, value]\`), unless \`resultTypes\` names it.
+- A result dropped in a callback that returns nothing (\`items.forEach((item) => save(item))\`), or after \`&&\` or \`?.\`.
+- A result stored and never looked at (\`const saved = saveUser(user);\` with \`saved\` unused).
+- Reading \`.value\` without checking \`.ok\`.
+
+## Turn it on or off
+
+In \`stateward.config.ts\`:
+
+\`\`\`ts
+rules: { "errors/result-ignored": "off" } // or "warning"
+groups: { "values/results": "off" } // the whole group
+rules: { "errors/result-ignored": ["error", { allowVoid: true }] } // \`void save()\` drops it on purpose
+rules: { "errors/result-ignored": ["error", { resultTypes: ["Either"] }] } // your own name for a Result
+\`\`\`
+`;
+/** The longest callee a headline shows before it is cut, and the longest call an example line shows. */
+const CALLEE_MAX = 30;
+const CALL_MAX = 60;
+const OPTIONS = {
+    allowVoid: option.boolean({
+        default: false,
+        description: "Take `void save()` as dropping the Result on purpose, and stay quiet.",
+    }),
+    resultTypes: option.strings({
+        default: [],
+        description: "Your names for a Result type whose shape stateward does not recognise (`Either`, `Outcome*`; globs allowed).",
+    }),
+    ignore: option.strings({
+        default: [],
+        description: "Functions whose Result may be dropped, by the name they are called with (`logEvent`, `*.track`; globs allowed).",
+    }),
+};
+function unwrap(expression) {
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isVoidExpression(expression) ||
+        ts.isAwaitExpression(expression)) {
+        return unwrap(expression.expression);
+    }
+    return expression;
+}
+/** The text of the callee, keeping its end when it is long: `…users.save`. */
+function calleeText(call, ctx) {
+    const text = call.expression.getText(ctx.sourceFile).replace(/\s+/g, "");
+    return text.length > CALLEE_MAX ? `…${text.slice(-(CALLEE_MAX - 1))}` : text;
+}
+/** `void x`, also inside parentheses or after `await`. */
+function isVoided(expression) {
+    if (ts.isVoidExpression(expression))
+        return true;
+    return ((ts.isParenthesizedExpression(expression) || ts.isAwaitExpression(expression)) &&
+        isVoided(expression.expression));
+}
+/** The line of the example that checks the result, in the Result's own shape. */
+function checkLine(shape) {
+    switch (shape) {
+        case "ok":
+            return "if (!saved.ok) return saved;";
+        case "success":
+            return "if (!saved.success) return saved;";
+        case "isErr":
+            return "if (saved.isErr()) return saved;";
+        case "named":
+            return "// handle its failure here, or return it";
+        default: {
+            const unreachable = shape;
+            return unreachable;
+        }
+    }
+}
+function checkStatement(statement, ctx) {
+    if (ctx.options.allowVoid && isVoided(statement.expression))
+        return;
+    const call = unwrap(statement.expression);
+    if (!ts.isCallExpression(call))
+        return;
+    const callee = call.expression.getText(ctx.sourceFile).replace(/\s+/g, "");
+    if (matchesName(callee, ctx.options.ignore))
+        return;
+    const shape = resultShapeOf(call, ctx.types, ctx.options.resultTypes);
+    if (shape === undefined)
+        return;
+    const promised = ctx.types.isPromiseLike(call);
+    const whole = shorten(call.getText(ctx.sourceFile), Number.MAX_SAFE_INTEGER);
+    // A long call keeps its callee and drops its arguments, so the example stays valid code.
+    const callText = whole.length > CALL_MAX
+        ? `${shorten(call.expression.getText(ctx.sourceFile), CALL_MAX)}(…)`
+        : whole;
+    ctx.report({
+        node: statement,
+        about: statement,
+        message: `the result of \`${calleeText(call, ctx)}(…)\` is dropped, so its error is never handled`,
+        hint: [
+            "check it, or pass it on:",
+            example([`const saved = ${promised ? "await " : ""}${callText};`, checkLine(shape)]),
+        ].join("\n"),
+    });
+}
+export const resultIgnored = defineRule({
+    kind: "file",
+    meta: {
+        description: "The Result of a call is checked or passed on, not dropped as a statement, after void or after await.",
+        defaultSeverity: "error",
+        tier: "core",
+        group: "callers",
+        // A trigger dropped where its failure goes unseen is said better there (one cause, one message).
+        yieldsTo: ["result-unchecked"],
+        options: OPTIONS,
+        explain: EXPLAIN,
+    },
+    check(ctx) {
+        const visit = (node) => {
+            if (ts.isExpressionStatement(node))
+                checkStatement(node, ctx);
+            ts.forEachChild(node, visit);
+        };
+        visit(ctx.sourceFile);
+    },
+});
+//# sourceMappingURL=result-ignored.js.map