@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/dist/rules.meta.js

@@ -0,0 +1,212 @@
+export const RULES = {
+    "catch-hides-unexpected": {
+        kind: "file",
+        meta: {
+            description: "A catch that handles some errors with instanceof also rethrows or handles all the others.",
+            defaultSeverity: "error",
+            tier: "core",
+            group: "catch",
+            options: {
+                restUsesError: {
+                    kind: "boolean",
+                    default: false,
+                    description: "The branch for the other errors must use the error (rethrow it, wrap it, report it); a generic message alone does not count.",
+                },
+            },
+        },
+    },
+    "catch-without-intent": {
+        kind: "file",
+        meta: {
+            description: "Experimental: on real projects it is mostly wrong; it may change or be removed. A catch that handles every error says how: it narrows, reports, or falls back; one that only logs, or calls something stateward cannot judge, and carries on is reported.",
+            defaultSeverity: "warning",
+            tier: "addon",
+            addon: "catch-intent",
+            group: "catch",
+            heuristic: true,
+            options: {
+                loggers: {
+                    kind: "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: {
+                    kind: "strings",
+                    default: ["error", "warn", "info", "debug"],
+                    description: "Method names that only log, on any object (`Sentry.captureException` is not one).",
+                },
+                logFunctions: {
+                    kind: "strings",
+                    default: [],
+                    description: "Plain functions of your own that only log, like logError (globs allowed).",
+                },
+                edgeHelpers: {
+                    kind: "strings",
+                    default: [],
+                    description: "Your functions that report an error where it ends (to a service, to the user): a catch that calls one is handled, like reportAndShow (globs allowed). Sentry, Bugsnag and Datadog are known without it.",
+                },
+                swallowHelpers: {
+                    kind: "strings",
+                    default: [],
+                    description: "Functions that mark an error as ignored on purpose, like ignoreError (globs allowed): a catch that calls one is not reported.",
+                },
+            },
+        },
+    },
+    "finally-can-throw": {
+        kind: "file",
+        meta: {
+            description: "A finally block does not call something that throws, so the error that led to it is not lost.",
+            defaultSeverity: "error",
+            tier: "core",
+            group: "catch",
+            options: {
+                severities: {
+                    kind: "severities",
+                    default: {},
+                    kinds: {
+                        throw: "a `throw` written in the finally: it throws whenever it runs.",
+                        builtin: "a built-in such as `JSON.parse` or `new URL`: it throws only on input it cannot handle.",
+                        "own-function": "a function in the same file with a `throw` in it: it throws on some paths.",
+                    },
+                    description: "A severity per kind of call, where you trust one kind less.",
+                },
+            },
+        },
+    },
+    "catch-misses-error": {
+        kind: "project",
+        meta: {
+            description: "A catch that branches with instanceof handles every error class its try can throw, or rethrows the rest; so does an error boundary's fallback.",
+            defaultSeverity: "error",
+            tier: "core",
+            group: "catch",
+            needsJsDoc: true,
+            options: {
+                ignoreClasses: {
+                    kind: "strings",
+                    default: [],
+                    description: "Error classes a catch never needs a branch for, as its instanceof test names them (SyntaxError, *AbortError).",
+                },
+            },
+        },
+    },
+    "throws-doc-mismatch": {
+        kind: "project",
+        meta: {
+            description: "A function's @throws tag lists exactly the error classes it can throw, as far as stateward can see.",
+            defaultSeverity: "error",
+            tier: "core",
+            group: "callers",
+            needsJsDoc: true,
+            options: {
+                severities: {
+                    kind: "severities",
+                    default: {},
+                    kinds: {
+                        missing: "the function can throw a class its `@throws` does not list.",
+                        extra: "the `@throws` lists a class the function cannot throw (stale, not dangerous).",
+                    },
+                    description: "A severity per kind of mismatch.",
+                },
+                ignoreClasses: {
+                    kind: "strings",
+                    default: [],
+                    description: "Error classes a `@throws` never needs to list (TypeError, *AbortError), as a catch names them.",
+                },
+            },
+        },
+    },
+    "render-throw-without-boundary": {
+        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: "render",
+            needsJsDoc: true,
+            options: {
+                skipContextGuards: {
+                    kind: "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: {
+                    kind: "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: {
+                    kind: "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: {
+                    kind: "record",
+                    default: { "react-error-boundary": ["ErrorBoundary"] },
+                    description: 'Error boundary components from packages, by package: add Sentry\'s with `{ "@sentry/react": ["ErrorBoundary"] }` (keep react-error-boundary\'s to keep it).',
+                },
+            },
+        },
+    },
+    "must-handle-error": {
+        kind: "project",
+        meta: {
+            description: "An error class marked @mustHandle is named in a catch or passed on with @throws by every call that can throw it.",
+            defaultSeverity: "error",
+            tier: "core",
+            group: "callers",
+            needsJsDoc: true,
+            listUnknowns: true,
+        },
+    },
+    "narrow-try": {
+        kind: "project",
+        meta: {
+            description: "Calls to your own code placed in a `try` after the call it is for: move them after the `try`.",
+            defaultSeverity: "warning",
+            tier: "addon",
+            addon: "narrow-try",
+            group: "catch",
+            needsJsDoc: true,
+        },
+    },
+    "result-ignored": {
+        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",
+            yieldsTo: ["result-unchecked"],
+            options: {
+                allowVoid: {
+                    kind: "boolean",
+                    default: false,
+                    description: "Take `void save()` as dropping the Result on purpose, and stay quiet.",
+                },
+                resultTypes: {
+                    kind: "strings",
+                    default: [],
+                    description: "Your names for a Result type whose shape stateward does not recognise (`Either`, `Outcome*`; globs allowed).",
+                },
+                ignore: {
+                    kind: "strings",
+                    default: [],
+                    description: "Functions whose Result may be dropped, by the name they are called with (`logEvent`, `*.track`; globs allowed).",
+                },
+            },
+        },
+    },
+    "result-unchecked": {
+        kind: "file",
+        meta: {
+            description: "A call that reports failure in its value, not by throwing, is checked before the code goes on as if it worked.",
+            defaultSeverity: "warning",
+            tier: "core",
+            group: "callers",
+            heuristic: true,
+        },
+    },
+};
+//# sourceMappingURL=rules.meta.js.map

package/dist/syntax.d.ts

@@ -0,0 +1,41 @@
+import ts from "@stateward/core/typescript";
+import type { FileContext } from "@stateward/core";
+export declare function stripParentheses(expression: ts.Expression): ts.Expression;
+/** A function, method or accessor: code in it runs when it is called, not where it is written. */
+export declare function isFunctionBoundary(node: ts.Node): boolean;
+/**
+ * Visits `root` and what runs with it, in source order, without entering a nested function or
+ * class. `guarded` is true inside the `try` block of a `try` that has a `catch`: an error there is
+ * caught. The `catch` and `finally` blocks of that `try` are not guarded by it.
+ */
+export declare function scanRunning(root: ts.Node, visit: (node: ts.Node, guarded: boolean) => void): void;
+export declare function hasModifier(node: ts.Node, kind: ts.SyntaxKind): boolean;
+/** A function that is declared here with a body: a declaration, a method, or one bound to a name. */
+export type DeclaredFunction = ts.FunctionDeclaration | ts.MethodDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/**
+ * The function that `callee` (`save`, `this.save`, `service.save`) names, when it is declared in
+ * this file and has a body. Resolved by declaration, so a shadowing name or an import is not
+ * mistaken for it.
+ */
+export declare function sameFileFunction(callee: ts.Expression, ctx: FileContext): DeclaredFunction | undefined;
+/**
+ * Whether `name` is the language's own global (`JSON`, `URL`, `fetch`): it resolves to a
+ * declaration outside the project, so a local variable of the same name is not taken for it.
+ */
+export declare function isBuiltinGlobal(name: ts.Identifier, ctx: FileContext): boolean;
+/** Whether the function has a `throw` that no `try` / `catch` of its own catches. */
+export declare function throwsUncaught(fn: DeclaredFunction): boolean;
+/**
+ * Whether a `catch` tests what it caught before handling it: `e instanceof X`, `e.name === …`,
+ * `"status" in e`, or a type guard `isApiError(e)`, in an `if`, a `switch` or a `?:`. Such a catch
+ * says which errors it expects; `errors/catch-hides-unexpected` checks what it does with the rest.
+ */
+export declare function testsCaught(clause: ts.CatchClause): boolean;
+/**
+ * Whether `call`, in `clause`, hands the caught error to a callback the function around it was
+ * given (`reject(e)`, `next(e)`, `onError(e)`): the caller gets it, as with a rethrow.
+ */
+export declare function handsOnCaught(call: ts.CallExpression, clause: ts.CatchClause): boolean;
+/** Whether `test` holds for `root` or a node under it, without entering nested functions or classes. */
+export declare function someRunning(root: ts.Node, test: (node: ts.Node) => boolean): boolean;
+//# sourceMappingURL=syntax.d.ts.map

package/dist/syntax.js

@@ -0,0 +1,171 @@
+import ts from "@stateward/core/typescript";
+export function stripParentheses(expression) {
+    let node = expression;
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    return node;
+}
+/** A function, method or accessor: code in it runs when it is called, not where it is written. */
+export function isFunctionBoundary(node) {
+    return ts.isFunctionLike(node) || ts.isClassDeclaration(node) || ts.isClassExpression(node);
+}
+/**
+ * Visits `root` and what runs with it, in source order, without entering a nested function or
+ * class. `guarded` is true inside the `try` block of a `try` that has a `catch`: an error there is
+ * caught. The `catch` and `finally` blocks of that `try` are not guarded by it.
+ */
+export function scanRunning(root, visit) {
+    const walk = (node, guarded) => {
+        if (isFunctionBoundary(node))
+            return;
+        visit(node, guarded);
+        if (ts.isTryStatement(node)) {
+            walk(node.tryBlock, guarded || node.catchClause !== undefined);
+            if (node.catchClause !== undefined)
+                walk(node.catchClause, guarded);
+            if (node.finallyBlock !== undefined)
+                walk(node.finallyBlock, guarded);
+            return;
+        }
+        ts.forEachChild(node, (child) => {
+            walk(child, guarded);
+        });
+    };
+    walk(root, false);
+}
+export function hasModifier(node, kind) {
+    return ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((m) => m.kind === kind) === true;
+}
+function functionOfDeclaration(node) {
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+        return node.body === undefined ? undefined : node;
+    }
+    if (ts.isVariableDeclaration(node) ||
+        ts.isPropertyDeclaration(node) ||
+        ts.isPropertyAssignment(node)) {
+        const initializer = node.initializer === undefined ? undefined : stripParentheses(node.initializer);
+        if (initializer !== undefined &&
+            (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer))) {
+            return initializer;
+        }
+    }
+    return undefined;
+}
+/**
+ * The function that `callee` (`save`, `this.save`, `service.save`) names, when it is declared in
+ * this file and has a body. Resolved by declaration, so a shadowing name or an import is not
+ * mistaken for it.
+ */
+export function sameFileFunction(callee, ctx) {
+    const target = stripParentheses(callee);
+    const name = ts.isIdentifier(target)
+        ? target
+        : ts.isPropertyAccessExpression(target)
+            ? target.name
+            : undefined;
+    if (name === undefined || ts.isPrivateIdentifier(name))
+        return undefined;
+    const symbol = ctx.types.symbolAt(name);
+    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol);
+    if (declaration?.node.getSourceFile() !== ctx.sourceFile)
+        return undefined;
+    return functionOfDeclaration(declaration.node);
+}
+/**
+ * Whether `name` is the language's own global (`JSON`, `URL`, `fetch`): it resolves to a
+ * declaration outside the project, so a local variable of the same name is not taken for it.
+ */
+export function isBuiltinGlobal(name, ctx) {
+    const symbol = ctx.types.symbolAt(name);
+    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol);
+    return declaration !== undefined && !ctx.types.isOwnFile(declaration.file);
+}
+/** Whether the function has a `throw` that no `try` / `catch` of its own catches. */
+export function throwsUncaught(fn) {
+    let thrown = false;
+    scanRunning(fn.body ?? fn, (node, guarded) => {
+        if (ts.isThrowStatement(node) && !guarded)
+            thrown = true;
+    });
+    return thrown;
+}
+/**
+ * Whether a `catch` tests what it caught before handling it: `e instanceof X`, `e.name === …`,
+ * `"status" in e`, or a type guard `isApiError(e)`, in an `if`, a `switch` or a `?:`. Such a catch
+ * says which errors it expects; `errors/catch-hides-unexpected` checks what it does with the rest.
+ */
+export function testsCaught(clause) {
+    const declaration = clause.variableDeclaration;
+    if (declaration === undefined || !ts.isIdentifier(declaration.name))
+        return false;
+    const variable = declaration.name.text;
+    const isVariable = (node) => {
+        const inner = stripParentheses(node);
+        return ts.isIdentifier(inner) && inner.text === variable;
+    };
+    const tests = (condition) => {
+        if (ts.isBinaryExpression(condition)) {
+            const operator = condition.operatorToken.kind;
+            if (operator === ts.SyntaxKind.InstanceOfKeyword && isVariable(condition.left))
+                return true;
+            if (operator === ts.SyntaxKind.InKeyword && isVariable(condition.right))
+                return true;
+        }
+        if (ts.isPropertyAccessExpression(condition) && isVariable(condition.expression))
+            return true;
+        if (ts.isCallExpression(condition) && condition.arguments.some(isVariable))
+            return true;
+        return ts.forEachChild(condition, (child) => (tests(child) ? true : undefined)) === true;
+    };
+    let found = false;
+    const walk = (node) => {
+        if (found || isFunctionBoundary(node))
+            return;
+        if (ts.isIfStatement(node) && tests(node.expression))
+            found = true;
+        if (ts.isConditionalExpression(node) && tests(node.condition))
+            found = true;
+        if (ts.isSwitchStatement(node)) {
+            found ||=
+                tests(node.expression) ||
+                    node.caseBlock.clauses.some((one) => ts.isCaseClause(one) && tests(one.expression));
+        }
+        ts.forEachChild(node, walk);
+    };
+    walk(clause.block);
+    return found;
+}
+/** A parameter of a function around `node` with this name: `reject`, `next`, `onError`. */
+function isParameterOfEnclosing(name, node) {
+    for (let parent = node.parent; !ts.isSourceFile(parent); parent = parent.parent) {
+        if (ts.isFunctionLike(parent) &&
+            parent.parameters.some((parameter) => ts.isIdentifier(parameter.name) && parameter.name.text === name)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether `call`, in `clause`, hands the caught error to a callback the function around it was
+ * given (`reject(e)`, `next(e)`, `onError(e)`): the caller gets it, as with a rethrow.
+ */
+export function handsOnCaught(call, clause) {
+    const declaration = clause.variableDeclaration;
+    if (declaration === undefined || !ts.isIdentifier(declaration.name))
+        return false;
+    const variable = declaration.name.text;
+    const callee = stripParentheses(call.expression);
+    return (ts.isIdentifier(callee) &&
+        isParameterOfEnclosing(callee.text, clause) &&
+        call.arguments.some((argument) => {
+            const inner = stripParentheses(argument);
+            return ts.isIdentifier(inner) && inner.text === variable;
+        }));
+}
+/** Whether `test` holds for `root` or a node under it, without entering nested functions or classes. */
+export function someRunning(root, test) {
+    const walk = (node) => (node === root || !isFunctionBoundary(node)) &&
+        (test(node) || ts.forEachChild(node, (child) => (walk(child) ? true : undefined)) === true);
+    return walk(root);
+}
+//# sourceMappingURL=syntax.js.map

package/dist/text.d.ts

@@ -0,0 +1,22 @@
+/** A headline is at most this long. */
+export declare const HEADLINE_MAX = 100;
+/** The first line of a fix is at most this long. */
+export declare const HINT_MAX = 140;
+/** The text on one line: all whitespace becomes a single space. */
+export declare function oneLine(text: string): string;
+/** The text as it is, or its first `max - 1` characters and `…` when it is longer than `max`. */
+export declare function shorten(text: string, max: number): string;
+/**
+ * Builds a message whose inserted names are shown whole, on one line: a developer's name is never
+ * cut. A headline that is longer than the limit because of its names is allowed to be.
+ * `build` applies the given `cut` to every name it inserts.
+ */
+export declare function fitted(build: (cut: (text: string) => string) => string): string;
+/**
+ * `` `A` ``, `` `A` and `B` ``, `` `A`, `B` and `C` ``, or the first three and `and N more`. Each
+ * name is passed through `cut` and put in backticks.
+ */
+export declare function codeList(names: readonly string[], cut: (text: string) => string): string;
+/** A fix line followed by a code example, each example line indented by 4 spaces. */
+export declare function withExample(line: string, example: readonly string[]): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/text.js

@@ -0,0 +1,43 @@
+/** A headline is at most this long. */
+export const HEADLINE_MAX = 100;
+/** The first line of a fix is at most this long. */
+export const HINT_MAX = 140;
+/** The text on one line: all whitespace becomes a single space. */
+export function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** The text as it is, or its first `max - 1` characters and `…` when it is longer than `max`. */
+export function shorten(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Builds a message whose inserted names are shown whole, on one line: a developer's name is never
+ * cut. A headline that is longer than the limit because of its names is allowed to be.
+ * `build` applies the given `cut` to every name it inserts.
+ */
+export function fitted(build) {
+    return build(oneLine);
+}
+/** The names that a list shows, at most this many; the rest are counted. */
+const MAX_LISTED = 3;
+/**
+ * `` `A` ``, `` `A` and `B` ``, `` `A`, `B` and `C` ``, or the first three and `and N more`. Each
+ * name is passed through `cut` and put in backticks.
+ */
+export function codeList(names, cut) {
+    const shown = names.slice(0, MAX_LISTED).map((name) => `\`${cut(name)}\``);
+    const hidden = names.length - shown.length;
+    if (hidden > 0)
+        return `${shown.join(", ")} and ${String(hidden)} more`;
+    const last = shown.at(-1);
+    if (last === undefined || shown.length === 1)
+        return last ?? "";
+    return `${shown.slice(0, -1).join(", ")} and ${last}`;
+}
+/** A fix line followed by a code example, each example line indented by 4 spaces. */
+export function withExample(line, example) {
+    return [line, ...example.map((text) => `    ${text}`)].join("\n");
+}
+//# sourceMappingURL=text.js.map

package/dist/throw-in-hook.d.ts

@@ -0,0 +1,8 @@
+/** The group the rule belongs to in the docs and in `stateward status`. */
+export declare const GROUP = "react";
+export declare const throwInHook: import("@stateward/core").FileRule<{
+    skipContextGuards: import("@stateward/core").BooleanOption;
+    skipInputGuards: import("@stateward/core").BooleanOption;
+    ignore: import("@stateward/core").StringsOption;
+}, "react">;
+//# sourceMappingURL=throw-in-hook.d.ts.map