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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stateward/plugin-errors",
-  "version": "1.0.1-rc.1",
+  "version": "1.1.0",
   "description": "stateward rules for errors: errors are handled where they can happen.",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,6 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@stateward/core": "1.0.1-rc.1"
+    "@stateward/core": "1.1.0"
   }
 }

package/dist/async-handler-unhandled.d.ts

@@ -1,7 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "async";
-export declare const asyncHandlerUnhandled: import("@stateward/core").FileRule<{
-    timers: import("@stateward/core").StringsOption;
-    ignoreProps: import("@stateward/core").StringsOption;
-}, "async">;
-//# sourceMappingURL=async-handler-unhandled.d.ts.map

package/dist/async-handler-unhandled.js

@@ -1,342 +0,0 @@
-import ts from "@stateward/core/typescript";
-import { defineRule, matchesName, option } from "@stateward/core";
-import { hasModifier, isBuiltinGlobal, scanRunning, sameFileFunction, stripParentheses, } from "./syntax.js";
-import { pathOf } from "./inference/packages.js";
-import { HEADLINE_MAX, fitted, oneLine, shorten, withExample } from "./text.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "async";
-const EXPLAIN = `# errors/async-handler-unhandled
-
-An async event handler, listener or timer callback catches its own failures, since nothing awaits it.
-
-## Why
-
-Nothing awaits an \`onClick\`, a listener or a timer callback. When an \`async\` one fails after an \`await\`, its promise rejects with no code waiting for it: the console shows an unhandled rejection, the user sees nothing, and whatever the handler was changing is left half done. A Save button whose \`await save()\` fails looks like it did nothing.
-
-## When to use it
-
-Use it in any app with async event handlers: React components, DOM listeners, timers. It is on as an error in every preset. Turn it off only if a global \`unhandledrejection\` handler is how you deal with these on purpose.
-
-## What it catches
-
-An \`async\` function written in place as:
-
-- a JSX prop named \`on\` plus a capital letter (\`onClick\`, \`onSubmit\`);
-- the listener of \`addEventListener\`;
-- the callback of \`setTimeout\`, \`setInterval\` or \`queueMicrotask\` (the \`timers\` option adds more);
-
-when it awaits outside a \`try\` with a \`catch\`, or returns a promise from \`fetch\`, \`Promise.all\` and similar, or an \`async\` function in the same file. An \`await\` in a \`catch\` or \`finally\` block is not protected by that \`try\`.
-
-### Bad
-
-\`\`\`tsx
-<button onClick={async () => {
-  await save();
-}}>Save</button>
-\`\`\`
-
-### Good
-
-\`\`\`tsx
-<button onClick={async () => {
-  try { await save(); } catch (e) { showError(e); }
-}}>Save</button>
-\`\`\`
-
-### Fix
-
-Wrap the body in \`try\` / \`catch\` and show, retry or record the failure. There is no quick fix: what to do with it is your call.
-
-## What it does not catch
-
-- A call that catches its own failure (\`await save().catch(showError)\`).
-- A promise that reports failure in its value instead of rejecting: its type has an \`unwrap()\` method and it resolves to data or an \`error\` (RTK Query's mutation and lazy-query triggers, \`await addTodo(todo)\`). \`await addTodo(todo).unwrap()\` rejects, and is reported.
-- A package function the config's \`facts\` say never fails: \`facts: { "my-client": { send: { rejects: [] } } }\`.
-- A handler passed by name (\`onClick={save}\`): only functions written in place are read.
-- A prop whose type returns a promise (\`onSave: () => Promise<void>\`): the component that declares it awaits it.
-- Other callbacks nobody awaits: \`.then\` callbacks, \`setImmediate\`, observers, \`useEffect\` callbacks.
-- A handler with no \`await\` and no promise the rule recognises.
-
-## Turn it on or off
-
-In \`stateward.config.ts\`:
-
-\`\`\`ts
-rules: { "errors/async-handler-unhandled": "off" } // or "warning"
-groups: { "errors/async": "off" } // the whole group
-rules: { "errors/async-handler-unhandled": ["error", { ignoreProps: ["onSubmit"] }] } // a prop your form library awaits
-\`\`\`
-`;
-const OPTIONS = {
-    timers: option.strings({
-        default: ["setTimeout", "setInterval", "queueMicrotask"],
-        description: "Functions whose first argument is a callback nobody awaits (add requestAnimationFrame, setImmediate…).",
-    }),
-    ignoreProps: option.strings({
-        default: [],
-        description: "JSX props whose async handler the component awaits itself, like a form library's onSubmit (globs allowed).",
-    }),
-};
-/** Objects the timers are also called on: `window.setTimeout`. */
-const TIMER_OWNERS = new Set(["window", "globalThis", "self"]);
-/** `Promise` methods that return a promise that can reject. */
-const REJECTING_PROMISES = new Set([
-    "all",
-    "allSettled",
-    "race",
-    "any",
-    "reject",
-]);
-function asyncFunction(expression) {
-    const node = stripParentheses(expression);
-    if (!ts.isArrowFunction(node) && !ts.isFunctionExpression(node))
-        return undefined;
-    if (!hasModifier(node, ts.SyntaxKind.AsyncKeyword))
-        return undefined;
-    return ts.isFunctionExpression(node) && node.asteriskToken !== undefined ? undefined : node;
-}
-function calleeName(call) {
-    const callee = stripParentheses(call.expression);
-    if (ts.isIdentifier(callee))
-        return callee.text;
-    if (!ts.isPropertyAccessExpression(callee))
-        return undefined;
-    if (callee.name.text === "addEventListener")
-        return callee.name.text;
-    const owner = stripParentheses(callee.expression);
-    return ts.isIdentifier(owner) && TIMER_OWNERS.has(owner.text) ? callee.name.text : undefined;
-}
-/** The members of a printed union at its top level: `(() => A) | undefined` is two. */
-function unionMembers(text) {
-    const members = [];
-    let depth = 0;
-    let start = 0;
-    for (let i = 0; i < text.length; i += 1) {
-        const char = text[i];
-        if (char === "(" || char === "[" || char === "{" || char === "<")
-            depth += 1;
-        else if (char === ")" ||
-            char === "]" ||
-            char === "}" ||
-            (char === ">" && text[i - 1] !== "=")) {
-            depth -= 1;
-        }
-        else if (char === "|" && depth === 0) {
-            members.push(text.slice(start, i).trim());
-            start = i + 1;
-        }
-    }
-    members.push(text.slice(start).trim());
-    return members;
-}
-/** `() => Promise<void>` or `(id: string) => PromiseLike<T>`, in parentheses or not. */
-const RETURNS_PROMISE = /^\(*\(.*\) => (?:Promise|PromiseLike)<.*>\)*$/;
-/**
- * Whether the prop an attribute sets is declared as a function that returns a promise
- * (`onSave: () => Promise<void>`, `onSave?(): Promise<void>`): the component asks for a promise
- * so that it can await it, so a failure is its to handle.
- */
-function awaitedByComponent(fn, ctx) {
-    const expected = ctx.types.contextualTypeTextOf(fn);
-    if (expected === undefined)
-        return false;
-    const present = unionMembers(expected).filter((member) => member !== "undefined" && member !== "null");
-    return present.length > 0 && present.every((member) => RETURNS_PROMISE.test(member));
-}
-/** The async function this node hands to something that never awaits it, if it does. */
-function handlerOf(node, ctx) {
-    if (ts.isJsxAttribute(node)) {
-        const name = node.name;
-        if (!ts.isIdentifier(name) || !/^on[A-Z]/.test(name.text))
-            return undefined;
-        if (matchesName(name.text, ctx.options.ignoreProps))
-            return undefined;
-        const value = node.initializer;
-        if (value === undefined || !ts.isJsxExpression(value) || value.expression === undefined) {
-            return undefined;
-        }
-        const fn = asyncFunction(value.expression);
-        return fn === undefined || awaitedByComponent(fn, ctx)
-            ? undefined
-            : { fn, name: name.text, role: "handler" };
-    }
-    if (!ts.isCallExpression(node))
-        return undefined;
-    const name = calleeName(node);
-    if (name === "addEventListener") {
-        const [, listener] = node.arguments;
-        const fn = listener === undefined ? undefined : asyncFunction(listener);
-        return fn === undefined ? undefined : { fn, name, role: "listener", call: node };
-    }
-    if (name !== undefined && ctx.options.timers.includes(name)) {
-        const [callback] = node.arguments;
-        const fn = callback === undefined ? undefined : asyncFunction(callback);
-        return fn === undefined ? undefined : { fn, name, role: "callback", call: node };
-    }
-    return undefined;
-}
-/** A call that returns a promise which can reject: `fetch`, `Promise.all`, a local async function. */
-function returnsPromise(expression, ctx) {
-    const call = stripParentheses(expression);
-    if (!ts.isCallExpression(call))
-        return false;
-    const callee = stripParentheses(call.expression);
-    if (ts.isIdentifier(callee) && callee.text === "fetch" && isBuiltinGlobal(callee, ctx)) {
-        return true;
-    }
-    if (ts.isPropertyAccessExpression(callee)) {
-        const owner = stripParentheses(callee.expression);
-        if (ts.isIdentifier(owner) &&
-            owner.text === "Promise" &&
-            REJECTING_PROMISES.has(callee.name.text) &&
-            isBuiltinGlobal(owner, ctx)) {
-            return true;
-        }
-    }
-    const declared = sameFileFunction(callee, ctx);
-    return declared !== undefined && hasModifier(declared, ts.SyntaxKind.AsyncKeyword);
-}
-/**
- * Whether the config's facts say the package function called here never fails: `rejects: []`
- * (and no `throws`). The function is named as the facts name it: its path in the package's
- * types (`Client.send`), or its own name (`send`).
- */
-function factsSayNeverRejects(call, ctx) {
-    const callee = stripParentheses(call.expression);
-    const name = ts.isPropertyAccessExpression(callee) ? callee.name : callee;
-    const symbol = ctx.types.symbolAt(name);
-    const declared = symbol && ctx.types.declarationOf(symbol);
-    if (declared === undefined || ctx.types.isOwnFile(declared.file))
-        return false;
-    const packageName = ctx.types.packageOf(declared.file);
-    const facts = packageName === undefined ? undefined : ctx.facts[packageName];
-    if (facts === undefined)
-        return false;
-    const names = pathOf(declared.node);
-    const entry = facts[names.join(".")] ?? facts[names.at(-1) ?? ""];
-    return entry?.rejects?.length === 0 && (entry.throws ?? []).length === 0;
-}
-/**
- * A promise that reports failure in its value, not by rejecting: its type has an `unwrap()`
- * method and resolves to data or an error (RTK Query's mutation and lazy-query triggers, item
- * 19), or the config's facts say the function never rejects.
- */
-function neverRejects(expression, ctx) {
-    const code = stripParentheses(expression);
-    if (ctx.types.settlesWithError(code))
-        return true;
-    return ts.isCallExpression(code) && factsSayNeverRejects(code, ctx);
-}
-/** `save().catch(showError)`: a call that handles its own failure. */
-function catchesOwnFailure(expression) {
-    const call = stripParentheses(expression);
-    if (!ts.isCallExpression(call) || call.arguments.length === 0)
-        return false;
-    const callee = stripParentheses(call.expression);
-    return ts.isPropertyAccessExpression(callee) && callee.name.text === "catch";
-}
-/** The first place the handler can fail with nothing to catch it, or undefined. */
-function unguardedFailure(fn, ctx) {
-    let found;
-    const look = (node, guarded) => {
-        if (found !== undefined || guarded)
-            return;
-        if (ts.isAwaitExpression(node) &&
-            !catchesOwnFailure(node.expression) &&
-            !neverRejects(node.expression, ctx)) {
-            found = {
-                node: node.getFirstToken(ctx.sourceFile) ?? node,
-                kind: "await",
-                code: node.expression,
-            };
-        }
-        else if (ts.isForOfStatement(node) && node.awaitModifier !== undefined) {
-            found = { node: node.awaitModifier, kind: "for-await", code: node.expression };
-        }
-        else if (ts.isReturnStatement(node) &&
-            node.expression !== undefined &&
-            returnsPromise(node.expression, ctx)) {
-            found = { node: node.expression, kind: "await", code: node.expression };
-        }
-    };
-    scanRunning(fn.body, look);
-    if (found === undefined && !ts.isBlock(fn.body) && returnsPromise(fn.body, ctx)) {
-        found = { node: fn.body, kind: "await", code: fn.body };
-    }
-    return found;
-}
-function headline(handler) {
-    return fitted(HEADLINE_MAX, (cut) => `a failure in this async \`${cut(handler.name)}\` ${handler.role} is an unhandled rejection`);
-}
-/** The developer's own code in an example is cut to this many characters. */
-const CODE_MAX = 50;
-function code(node, ctx) {
-    return shorten(oneLine(node.getText(ctx.sourceFile)), CODE_MAX);
-}
-/** The example's first and last line: the handler written where it was, with its own names. */
-function frame(handler, ctx) {
-    switch (handler.role) {
-        case "handler":
-            return { first: `${oneLine(handler.name)}={async () => {`, last: "}}" };
-        case "listener":
-        case "callback": {
-            const [before, after] = aroundFunction(handler.call, handler.fn, ctx);
-            return {
-                first: `${code(handler.call.expression, ctx)}(${before}async () => {`,
-                last: `}${after});`,
-            };
-        }
-        default: {
-            const unreachable = handler;
-            return unreachable;
-        }
-    }
-}
-/** The call's other arguments, before and after the function: `"click", ` and `, 100`. */
-function aroundFunction(call, fn, ctx) {
-    const index = call.arguments.findIndex((argument) => stripParentheses(argument) === fn);
-    const texts = call.arguments.map((argument) => code(argument, ctx));
-    const before = texts.slice(0, index).map((text) => `${text}, `);
-    const after = texts.slice(index + 1).map((text) => `, ${text}`);
-    return [before.join(""), after.join("")];
-}
-function hint(handler, failure, ctx) {
-    const { first, last } = frame(handler, ctx);
-    const failing = failure.kind === "await"
-        ? `await ${code(failure.code, ctx)};`
-        : `for await (const item of ${code(failure.code, ctx)}) { … }`;
-    return withExample(`nothing awaits the ${handler.role}, so catch inside it:`, [
-        first,
-        `  try { ${failing} } catch (e) { showError(e); }`,
-        last,
-    ]);
-}
-export const asyncHandlerUnhandled = defineRule({
-    kind: "file",
-    meta: {
-        description: "An async event handler, listener or timer callback catches its own failures, since nothing awaits it.",
-        defaultSeverity: "error",
-        tier: "core",
-        group: GROUP,
-        options: OPTIONS,
-        explain: EXPLAIN,
-    },
-    check(ctx) {
-        const visit = (node) => {
-            const handler = handlerOf(node, ctx);
-            if (handler !== undefined) {
-                const failure = unguardedFailure(handler.fn, ctx);
-                if (failure !== undefined) {
-                    ctx.report({
-                        node: failure.node,
-                        message: headline(handler),
-                        hint: hint(handler, failure, ctx),
-                    });
-                }
-            }
-            ts.forEachChild(node, visit);
-        };
-        visit(ctx.sourceFile);
-    },
-});
-//# sourceMappingURL=async-handler-unhandled.js.map

package/dist/catch-without-intent.d.ts

@@ -1,10 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "catch";
-export declare const catchWithoutIntent: import("@stateward/core").FileRule<{
-    loggers: import("@stateward/core").StringsOption;
-    logMethods: import("@stateward/core").StringsOption;
-    logFunctions: import("@stateward/core").StringsOption;
-    edgeHelpers: import("@stateward/core").StringsOption;
-    swallowHelpers: import("@stateward/core").StringsOption;
-}, "catch">;
-//# sourceMappingURL=catch-without-intent.d.ts.map