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

package/dist/throw-in-hook.js

@@ -1,510 +0,0 @@
-import ts from "@stateward/core/typescript";
-import { defineRule, matchesName, option } from "@stateward/core";
-import { hasModifier, sameFileFunction, scanRunning, stripParentheses, throwsUncaught, } from "./syntax.js";
-import { HEADLINE_MAX, fitted, oneLine, withExample } from "./text.js";
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export const GROUP = "react";
-const EXPLAIN = `# errors/throw-in-hook
-
-A component or hook that throws while rendering takes down the screen up to the nearest error boundary.
-
-## Why
-
-When a component or hook throws while React renders it, React unmounts everything up to the nearest error boundary, or the whole app when there is none. The parent never gets a value back, so it cannot show the failure itself. A \`Cart\` that throws \`new Error("no cart")\` for a missing id blanks the page where it could have shown "cart not found".
-
-## When to use it
-
-Use it for app code that returns failures as state (\`RemoteData\`, \`Result\`). Many apps throw on purpose, to an error boundary or for Suspense, and libraries throw to flag a misuse, so it is off until you add its add-on (below), then a warning in every preset. For a throw that is meant, document it with \`@throws\`, accept the finding with \`// stateward-ignore errors/throw-in-hook: <why>\` above the line, or with \`stateward baseline\`.
-
-## What it catches
-
-In the body of a component (a capitalised function with JSX or hook calls) or a custom hook (\`use\` plus a capital letter):
-
-- a \`throw\` not caught by a \`try\` / \`catch\` in the same body;
-- a call to a function in the same file that has a \`throw\` outside its own \`try\` / \`catch\`.
-
-### Bad
-
-\`\`\`tsx
-function Cart({ id }: { id: string }) {
-  const cart = useCartData(id);
-  if (cart === undefined) throw new Error("no cart");
-  return <List items={cart.items} />;
-}
-\`\`\`
-
-### Good
-
-\`\`\`tsx
-function Cart({ id }: { id: string }) {
-  const cart = useCartData(id);
-  if (cart === undefined) return <NotFound />;
-  return <List items={cart.items} />;
-}
-\`\`\`
-
-### Fix
-
-Render the failure, or return it as state the caller can render. There is no quick fix.
-
-## What it does not catch
-
-It stays quiet for:
-
-- code in a nested function: event handlers, effects, \`useMemo\` and \`useCallback\` callbacks, promise callbacks;
-- a \`throw\` caught in the same body, and a thrown promise (Suspense);
-- 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. A missing Provider is a programming mistake, and the throw names it;
-- a check on what the caller passed: a \`throw\` when a prop or parameter is missing (\`if (!render && !children) throw …\`, \`props.title === undefined\`), or when a value from a context hook is missing (\`const editor = usePreferencesEditor(); if (!editor) throw …\`). A throw on a truthy value (\`if (error) throw error\`) or on a comparison (\`id === ""\`) is still reported;
-- a call to such a context hook in the same file (\`useSidebar()\` in \`<SidebarTrigger>\`);
-- functions from other files.
-
-Set \`skipContextGuards\` or \`skipInputGuards\` to \`false\` to report those checks of a context or of the caller's input too.
-
-Whether an error boundary is above it is checked by \`errors/render-throws-without-boundary\`.
-
-## Turn it on or off
-
-Turn it on in \`stateward.config.ts\`:
-
-\`\`\`ts
-addons: ["errors/hook-throws"]
-\`\`\`
-
-Then change or turn off the rule itself:
-
-\`\`\`ts
-rules: { "errors/throw-in-hook": "off" } // or "error"
-groups: { "errors/react": "off" } // the whole group
-rules: { "errors/throw-in-hook": ["warning", { ignore: ["use*Suspense"] }] } // hooks that throw on purpose
-\`\`\`
-`;
-const OPTIONS = {
-    skipContextGuards: option.boolean({
-        default: true,
-        description: 'Stay quiet on the usual check in a context hook: `if (!ctx) throw new Error("useAuth must be used within AuthProvider")`.',
-    }),
-    skipInputGuards: option.boolean({
-        default: true,
-        description: "Stay quiet on a throw when a prop, a parameter or a context hook's value is missing (a mistake of the caller).",
-    }),
-    ignore: option.strings({
-        default: [],
-        description: "Components and hooks (names or globs like use*Suspense) that may throw while rendering.",
-    }),
-};
-function nameOf(fn) {
-    if (ts.isFunctionDeclaration(fn))
-        return fn.name?.text;
-    const parent = fn.parent;
-    if ((ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) && ts.isVariableDeclaration(parent)) {
-        return ts.isIdentifier(parent.name) ? parent.name.text : undefined;
-    }
-    return undefined;
-}
-function isHookName(name) {
-    return /^use[A-Z]/.test(name);
-}
-/** Whether the render body has JSX or a call to a hook. */
-function rendersOrUsesHooks(body) {
-    let found = false;
-    scanRunning(body, (node) => {
-        if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
-            found = true;
-        }
-        else if (ts.isCallExpression(node)) {
-            const callee = stripParentheses(node.expression);
-            if (ts.isIdentifier(callee) && isHookName(callee.text))
-                found = true;
-        }
-    });
-    return found;
-}
-function renderOf(fn) {
-    const isFunction = ts.isFunctionDeclaration(fn) || ts.isArrowFunction(fn) || ts.isFunctionExpression(fn);
-    if (!isFunction || fn.body === undefined || hasModifier(fn, ts.SyntaxKind.AsyncKeyword)) {
-        return undefined;
-    }
-    if (fn.asteriskToken !== undefined)
-        return undefined;
-    const name = nameOf(fn);
-    if (name === undefined)
-        return undefined;
-    if (isHookName(name))
-        return { kind: "hook", name, label: name, fn, body: fn.body };
-    if (/^[A-Z]/.test(name) && rendersOrUsesHooks(fn.body)) {
-        return { kind: "component", name, label: `<${name}>`, fn, body: fn.body };
-    }
-    return undefined;
-}
-/** `throw promise` is how Suspense is asked to wait, not a failure. */
-function throwsPromise(statement, ctx) {
-    return /^(?:Promise|PromiseLike)</.test(ctx.types.typeTextOf(statement.expression));
-}
-/** `useContext(X)` or `React.useContext(X)`. */
-function isUseContextCall(expression) {
-    const node = stripParentheses(expression);
-    if (!ts.isCallExpression(node))
-        return false;
-    const callee = stripParentheses(node.expression);
-    const name = ts.isPropertyAccessExpression(callee) ? callee.name : callee;
-    return ts.isIdentifier(name) && name.text === "useContext";
-}
-/**
- * Whether an expression is the value a context gives: a `useContext(X)` call, or a local `const`
- * initialized with one. A property of it (`ctx.user`) is the app's state, not the Provider.
- */
-function isContextValue(expression, ctx) {
-    const node = stripParentheses(expression);
-    if (isUseContextCall(node))
-        return true;
-    if (!ts.isIdentifier(node))
-        return false;
-    const symbol = ctx.types.symbolAt(node);
-    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
-    if (declaration === undefined || !ts.isVariableDeclaration(declaration))
-        return false;
-    const list = declaration.parent;
-    return (ts.isVariableDeclarationList(list) &&
-        (list.flags & ts.NodeFlags.Const) !== 0 &&
-        declaration.initializer !== undefined &&
-        isUseContextCall(declaration.initializer));
-}
-function isNullish(expression) {
-    const node = stripParentheses(expression);
-    return (node.kind === ts.SyntaxKind.NullKeyword || (ts.isIdentifier(node) && node.text === "undefined"));
-}
-/**
- * Whether a condition holds when a context value is missing: `!ctx`, `ctx == null`,
- * `ctx === undefined` (either side), or an `||` of such checks.
- */
-function checksMissingContext(condition, ctx) {
-    const node = stripParentheses(condition);
-    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
-        return isContextValue(node.operand, ctx);
-    }
-    if (!ts.isBinaryExpression(node))
-        return false;
-    const operator = node.operatorToken.kind;
-    if (operator === ts.SyntaxKind.BarBarToken) {
-        return checksMissingContext(node.left, ctx) && checksMissingContext(node.right, ctx);
-    }
-    if (operator !== ts.SyntaxKind.EqualsEqualsToken &&
-        operator !== ts.SyntaxKind.EqualsEqualsEqualsToken) {
-        return false;
-    }
-    return ((isMissingMarker(node.right, ctx) && isContextValue(node.left, ctx)) ||
-        (isMissingMarker(node.left, ctx) && isContextValue(node.right, ctx)));
-}
-/**
- * What a context gives when its Provider is missing: `null`, `undefined`, or a sentinel, a
- * `const` declared at the top of the file (`const missing = {}` as the context's default).
- */
-function isMissingMarker(expression, ctx) {
-    if (isNullish(expression))
-        return true;
-    const node = stripParentheses(expression);
-    if (!ts.isIdentifier(node))
-        return false;
-    const symbol = ctx.types.symbolAt(node);
-    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
-    if (declaration === undefined || !ts.isVariableDeclaration(declaration))
-        return false;
-    const list = declaration.parent;
-    return (ts.isVariableDeclarationList(list) &&
-        (list.flags & ts.NodeFlags.Const) !== 0 &&
-        ts.isVariableStatement(list.parent) &&
-        ts.isSourceFile(list.parent.parent));
-}
-/** Whether a declaration is a parameter of `fn`, or a name bound by destructuring one. */
-function isParameterOf(declaration, fn) {
-    for (let node = declaration; node !== fn; node = node.parent) {
-        if (ts.isParameter(node))
-            return node.parent === fn;
-        if (!ts.isBindingElement(node) &&
-            !ts.isObjectBindingPattern(node) &&
-            !ts.isArrayBindingPattern(node)) {
-            return false;
-        }
-    }
-    return false;
-}
-/**
- * A hook that hands over a context: named `use…Context`, or one whose body is `useContext(X)`
- * (`const usePreferencesEditor = () => useContext(EditorContext)`).
- */
-function isContextHook(callee, ctx) {
-    const node = stripParentheses(callee);
-    if (!ts.isIdentifier(node))
-        return false;
-    if (/^use\w*Context$/.test(node.text))
-        return true;
-    const symbol = ctx.types.symbolAt(node);
-    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
-    if (declaration === undefined)
-        return false;
-    const fn = ts.isVariableDeclaration(declaration) && declaration.initializer !== undefined
-        ? stripParentheses(declaration.initializer)
-        : declaration;
-    if (!ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn) && !ts.isFunctionDeclaration(fn)) {
-        return false;
-    }
-    const body = fn.body;
-    if (body === undefined)
-        return false;
-    if (!ts.isBlock(body))
-        return isUseContextCall(body);
-    // A wrapper that reads a context, maybe guards it, and returns it (`usePreferencesEditor`).
-    let reads = false;
-    scanRunning(body, (node) => {
-        if (ts.isCallExpression(node) && isUseContextCall(node))
-            reads = true;
-    });
-    return reads;
-}
-/**
- * A name destructured from a parameter in the body: `const { children, render } = props;`.
- */
-function isDestructuredParameter(declaration, render, ctx) {
-    if (!ts.isBindingElement(declaration))
-        return false;
-    let pattern = declaration.parent;
-    while (ts.isBindingElement(pattern.parent))
-        pattern = pattern.parent.parent;
-    const variable = pattern.parent;
-    if (!ts.isVariableDeclaration(variable) || variable.initializer === undefined)
-        return false;
-    const source = stripParentheses(variable.initializer);
-    return ts.isIdentifier(source) && isParameterName(source, render, ctx);
-}
-/**
- * Whether an expression is an input the caller is responsible for: a parameter (or a prop
- * destructured from one, or `props.x`), or a context value read through a context hook.
- */
-function isCallerInput(expression, render, ctx) {
-    const node = stripParentheses(expression);
-    if (ts.isPropertyAccessExpression(node)) {
-        const owner = stripParentheses(node.expression);
-        // `props.title`; a property of a context value is the app's state (`ctx.user`), not a prop.
-        return ts.isIdentifier(owner) && isParameterName(owner, render, ctx);
-    }
-    if (!ts.isIdentifier(node))
-        return false;
-    const symbol = ctx.types.symbolAt(node);
-    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
-    if (declaration === undefined)
-        return false;
-    if (isParameterOf(declaration, render.fn) || isDestructuredParameter(declaration, render, ctx)) {
-        return true;
-    }
-    if (!ts.isVariableDeclaration(declaration) || declaration.initializer === undefined)
-        return false;
-    const list = declaration.parent;
-    if (!ts.isVariableDeclarationList(list) || (list.flags & ts.NodeFlags.Const) === 0)
-        return false;
-    const init = stripParentheses(declaration.initializer);
-    return ts.isCallExpression(init) && isContextHook(init.expression, ctx);
-}
-function isParameterName(node, render, ctx) {
-    const symbol = ctx.types.symbolAt(node);
-    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
-    return declaration !== undefined && isParameterOf(declaration, render.fn);
-}
-/**
- * Whether a condition holds only when an input is missing: `!x`, `x == null`, `x === undefined`
- * (either side), and `&&` / `||` of such checks, every one on a caller's input.
- */
-function checksMissingInput(condition, render, ctx) {
-    const node = stripParentheses(condition);
-    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
-        return isCallerInput(node.operand, render, ctx);
-    }
-    if (!ts.isBinaryExpression(node))
-        return false;
-    const operator = node.operatorToken.kind;
-    if (operator === ts.SyntaxKind.BarBarToken ||
-        operator === ts.SyntaxKind.AmpersandAmpersandToken) {
-        return (checksMissingInput(node.left, render, ctx) && checksMissingInput(node.right, render, ctx));
-    }
-    if (operator !== ts.SyntaxKind.EqualsEqualsToken &&
-        operator !== ts.SyntaxKind.EqualsEqualsEqualsToken) {
-        return false;
-    }
-    return ((isNullish(node.right) && isCallerInput(node.left, render, ctx)) ||
-        (isNullish(node.left) && isCallerInput(node.right, render, ctx)));
-}
-/** An invariant: `if (!render && !children) throw …`, a programming error of the caller. */
-function guardsInput(statement, render, ctx) {
-    for (const guard of enclosingIfs(statement, render.body)) {
-        if (checksMissingInput(guard.expression, render, ctx))
-            return true;
-    }
-    return false;
-}
-/** The `if` whose `then` branch holds `node`, nearest first, up to the render body. */
-function* enclosingIfs(node, body) {
-    let child = node;
-    for (let parent = node.parent; child !== body; child = parent, parent = parent.parent) {
-        if (ts.isIfStatement(parent) && parent.thenStatement === child)
-            yield parent;
-    }
-}
-/** The guard of a context hook: `if (!ctx) throw new Error("useX must be used within XProvider")`. */
-function guardsContext(statement, body, ctx) {
-    for (const guard of enclosingIfs(statement, body)) {
-        if (checksMissingContext(guard.expression, ctx))
-            return true;
-    }
-    return false;
-}
-/** A `throw` that unmounts the screen: not a Suspense promise, not the guard of a context hook. */
-function isRenderFailure(statement, body, ctx) {
-    return (!throwsPromise(statement, ctx) &&
-        !(ctx.options.skipContextGuards && guardsContext(statement, body, ctx)));
-}
-/**
- * Whether a function declared in this file throws a render failure outside its own `try` /
- * `catch`. A context hook's guard (`useSidebar` called by `<SidebarTrigger>`) is not one.
- */
-function calleeFails(declared, ctx) {
-    if (!throwsUncaught(declared))
-        return false;
-    const body = declared.body ?? declared;
-    let fails = false;
-    scanRunning(body, (node, guarded) => {
-        if (!guarded && ts.isThrowStatement(node) && isRenderFailure(node, body, ctx))
-            fails = true;
-    });
-    return fails;
-}
-function causeOf(node, render, ctx) {
-    if (ts.isThrowStatement(node)) {
-        return isRenderFailure(node, render.body, ctx) &&
-            !(ctx.options.skipInputGuards && guardsInput(node, render, ctx))
-            ? node
-            : undefined;
-    }
-    if (!ts.isCallExpression(node))
-        return undefined;
-    const declared = sameFileFunction(node.expression, ctx);
-    if (declared === undefined || hasModifier(declared, ts.SyntaxKind.AsyncKeyword))
-        return undefined;
-    return calleeFails(declared, ctx) ? node : undefined;
-}
-function checkRender(render, ctx) {
-    if (matchesName(render.name, ctx.options.ignore))
-        return;
-    let found;
-    scanRunning(render.body, (node, guarded) => {
-        if (found === undefined && !guarded)
-            found = causeOf(node, render, ctx);
-    });
-    if (found === undefined)
-        return;
-    const cause = found;
-    ctx.report({
-        node: found,
-        message: fitted(HEADLINE_MAX, (cut) => `\`${cut(render.label)}\` throws while rendering, unmounting the screen up to an error boundary`),
-        hint: hint(render, cause, ctx),
-    });
-}
-/** Text from the developer's code is used in an example up to this length; longer, a neutral name. */
-const OWN_TEXT_MAX = 50;
-function ownText(node, ctx, neutral) {
-    const text = node === undefined ? "" : oneLine(node.getText(ctx.sourceFile));
-    return text === "" || text.length > OWN_TEXT_MAX ? neutral : text;
-}
-/** For a component: render the failure, with the throw's own condition and error where it has them. */
-function componentHint(cause, render, ctx) {
-    const [guard] = ts.isThrowStatement(cause) ? enclosingIfs(cause, render.body) : [];
-    const thrown = ts.isThrowStatement(cause) &&
-        (ts.isIdentifier(stripParentheses(cause.expression)) ||
-            ts.isPropertyAccessExpression(stripParentheses(cause.expression)))
-        ? cause.expression
-        : undefined;
-    const condition = ownText(guard?.expression, ctx, "failed");
-    const error = ownText(thrown, ctx, "error");
-    return withExample("render the failure instead, so the screen stays:", [
-        `if (${condition}) return <ErrorMessage error={${error}} />;`,
-    ]);
-}
-/** What a hook returns: its declared type, else each `return` (more than one type is a union). */
-function returnsObjectOrUnion(fn, ctx) {
-    const returned = [];
-    if (fn.type !== undefined) {
-        returned.push(fn.type);
-    }
-    else if (fn.body !== undefined && !ts.isBlock(fn.body)) {
-        returned.push(fn.body);
-    }
-    else if (fn.body !== undefined) {
-        scanRunning(fn.body, (node) => {
-            if (ts.isReturnStatement(node))
-                returned.push(node.expression ?? node);
-        });
-    }
-    const texts = new Set(returned.map((node) => (ts.isReturnStatement(node) ? "undefined" : ctx.types.typeTextOf(node))));
-    if (texts.size > 1)
-        return true;
-    return returned.some((node) => !ts.isReturnStatement(node) &&
-        (isUnionText(ctx.types.typeTextOf(node)) || ctx.types.propertyKeysOf(node) !== "not-object"));
-}
-/** Whether a printed type is a union at its top level: `A | B`, not `{ a: A | B }` or `() => A | B`. */
-function isUnionText(text) {
-    let depth = 0;
-    let union = false;
-    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 (depth === 0 && char === "=" && text[i + 1] === ">")
-            return false;
-        else if (depth === 0 && char === "|")
-            union = true;
-    }
-    return union;
-}
-function hint(render, cause, ctx) {
-    switch (render.kind) {
-        case "component":
-            return componentHint(cause, render, ctx);
-        case "hook":
-            return returnsObjectOrUnion(render.fn, ctx)
-                ? withExample("return the failure as state so the caller can render it:", [
-                    'return { kind: "failed", error } as const;',
-                ])
-                : "return a value the caller can check instead of throwing";
-        default: {
-            const unreachable = render.kind;
-            return unreachable;
-        }
-    }
-}
-export const throwInHook = defineRule({
-    kind: "file",
-    meta: {
-        description: "A component or hook that throws while rendering takes down the screen up to the nearest error boundary.",
-        defaultSeverity: "warning",
-        tier: "addon",
-        addon: "hook-throws",
-        group: GROUP,
-        heuristic: true,
-        options: OPTIONS,
-        explain: EXPLAIN,
-    },
-    check(ctx) {
-        const visit = (node) => {
-            const render = renderOf(node);
-            if (render !== undefined)
-                checkRender(render, ctx);
-            ts.forEachChild(node, visit);
-        };
-        visit(ctx.sourceFile);
-    },
-});
-//# sourceMappingURL=throw-in-hook.js.map

package/dist/throws-matches-doc.d.ts

@@ -1,7 +0,0 @@
-/** The group the rule belongs to in the docs and in `stateward status`. */
-export declare const GROUP = "inference";
-export declare const throwsMatchesDoc: import("@stateward/core").ProjectRule<import("./index.js").ThrowsSummary, {
-    severities: import("@stateward/core").SeveritiesOption<"missing" | "extra">;
-    ignoreClasses: import("@stateward/core").StringsOption;
-}, "inference">;
-//# sourceMappingURL=throws-matches-doc.d.ts.map