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

package/dist/react/boundaries.js

@@ -0,0 +1,371 @@
+import { propagate } from "@stateward/core";
+import { summarizeOnce } from "../inference/project.js";
+import { analyse, evaluated } from "../inference/solve.js";
+import { className, unknownText } from "../inference/format.js";
+import { fieldsOf } from "../inference/summary.js";
+import { ALL_GUARDS } from "./render-guards.js";
+import { LIBRARY_BOUNDARIES, readTree, summarizeTree } from "./tree.js";
+/** The rules whose summaries hold a render tree; the first that ran is read. */
+export const TREE_RULES = [
+    "errors/render-throw-without-boundary",
+    "errors/catch-misses-error",
+];
+/**
+ * The last file's trees by program, then by the boundaries the rule's config adds (as JSON): the
+ * pack's two React rules summarize the same file one after the other. Only the last file is
+ * kept, as in `summarizeOnce`.
+ */
+const last = new WeakMap();
+export function summarizeReact(ctx, libraryBoundaries = LIBRARY_BOUNDARIES, skips = ALL_GUARDS) {
+    let known = last.get(ctx.types);
+    if (known?.sourceFile !== ctx.sourceFile) {
+        known = { sourceFile: ctx.sourceFile, trees: new Map() };
+        last.set(ctx.types, known);
+    }
+    const key = JSON.stringify([libraryBoundaries, skips.contextGuards, skips.inputGuards]);
+    let tree = known.trees.get(key);
+    if (tree === undefined) {
+        tree = summarizeTree(ctx, libraryBoundaries, skips);
+        known.trees.set(key, tree);
+    }
+    return { throws: summarizeOnce(ctx), tree };
+}
+/** What `nearest` answers for a render stateward cannot follow to where it is placed. */
+const UNFOLLOWED = "?";
+const models = new WeakMap();
+const throwsMaps = new WeakMap();
+/** The throws part of each summary: the same facts `catch-misses-error` solves. */
+export function throwsOf(summaries) {
+    let known = throwsMaps.get(summaries);
+    if (known === undefined) {
+        const made = new Map();
+        for (const [file, value] of summaries) {
+            const throws = fieldsOf(value)?.throws;
+            if (throws !== undefined)
+                made.set(file, throws);
+        }
+        known = made;
+        throwsMaps.set(summaries, known);
+    }
+    return known;
+}
+function compareSites(a, b) {
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    return a.render.at[0] - b.render.at[0];
+}
+function stepOf(text) {
+    return text.endsWith("(…)") ? text.slice(0, -"(…)".length) : text;
+}
+/** The pack's view of the app's render tree, built once per summaries map. */
+export function modelOf(summaries) {
+    const known = models.get(summaries);
+    if (known !== undefined)
+        return known;
+    const analysis = analyse(throwsOf(summaries));
+    const functions = new Map();
+    const boundaries = new Map();
+    const byFile = new Map();
+    const entries = [];
+    const sites = [];
+    for (const file of [...summaries.keys()].sort()) {
+        const value = summaries.get(file);
+        const tree = value === undefined ? undefined : readTree(fieldsOf(value)?.tree);
+        if (tree === undefined)
+            continue;
+        for (const fn of tree.functions)
+            functions.set(fn.id, { file, fn });
+        for (const element of tree.boundaries)
+            boundaries.set(element.key, { file, element });
+        byFile.set(file, tree.boundaries);
+        for (const render of tree.entries)
+            entries.push({ to: render.target, file, render });
+    }
+    for (const { file, fn } of functions.values()) {
+        for (const render of fn.renders)
+            sites.push({ to: render.target, file, render });
+    }
+    sites.sort(compareSites);
+    const edgesOf = new Map();
+    for (const { file, fn } of functions.values()) {
+        edgesOf.set(fn.id, fn.renders
+            .filter((render) => functions.has(render.target))
+            .map((render) => ({ to: render.target, file, render })));
+    }
+    const edges = (id) => edgesOf.get(id) ?? [];
+    const nearest = (site) => {
+        // Not a key of any boundary: nothing is reported for it, and no boundary counts it.
+        if (site.render.unknown)
+            return UNFOLLOWED;
+        for (const one of site.render.around) {
+            if ("boundary" in one)
+                return one.boundary;
+            const inner = functions.get(one.via)?.fn.children?.[0];
+            if (inner !== undefined)
+                return inner;
+        }
+        return undefined;
+    };
+    const effectsOf = (id) => {
+        const found = [];
+        const seen = new Set();
+        const visit = (one) => {
+            if (seen.has(one))
+                return;
+            seen.add(one);
+            const entry = functions.get(one);
+            if (entry === undefined)
+                return;
+            for (const start of entry.fn.effects)
+                found.push({ file: entry.file, start });
+            for (const hook of entry.fn.hooks)
+                visit(hook);
+        };
+        visit(id);
+        return found;
+    };
+    /**
+     * Whether every way function `fnId` throws `cls` is a guard: a `throw` its tree summary lists
+     * as one, or a call of a function that throws it only from guards. A `@throws` tag, a package
+     * or a built-in that throws it is not.
+     */
+    const guardOnly = (fnId, cls, seen) => {
+        const fact = analysis.functions.get(fnId)?.fact;
+        if (fact === undefined || seen.has(fnId))
+            return false;
+        seen.add(fnId);
+        if (fact.doc?.entries.some((entry) => entry.id === cls) === true)
+            return false;
+        const guards = functions.get(fnId)?.fn.guards ?? [];
+        let found = false;
+        const walk = (effects) => {
+            for (const effect of effects) {
+                switch (effect.k) {
+                    case "class":
+                        if (effect.id !== cls)
+                            break;
+                        if (effect.text !== null || !guards.includes(effect.at[0]))
+                            return false;
+                        found = true;
+                        break;
+                    case "call":
+                        if (analysis.results.get(effect.id)?.throws.classes.has(cls) !== true)
+                            break;
+                        if (!guardOnly(effect.id, cls, seen))
+                            return false;
+                        found = true;
+                        break;
+                    case "package":
+                        if (effect.facts[effect.part].classes.includes(cls))
+                            return false;
+                        break;
+                    case "maybe":
+                        if (!walk(effect.body))
+                            return false;
+                        break;
+                    case "try": {
+                        const handler = effect.handler;
+                        const parts = [
+                            effect.body,
+                            effect.fin,
+                            ...(handler === null
+                                ? []
+                                : [
+                                    handler.pre,
+                                    ...handler.branches.map((branch) => branch.body),
+                                    handler.otherwise ?? [],
+                                    handler.after,
+                                ]),
+                        ];
+                        if (!parts.every(walk))
+                            return false;
+                        break;
+                    }
+                    case "unknown":
+                    case "rethrow":
+                        break;
+                    default: {
+                        const unreachable = effect;
+                        return unreachable;
+                    }
+                }
+            }
+            return true;
+        };
+        return walk(fact.body) && found;
+    };
+    const owns = new Map();
+    const own = (id) => {
+        const cached = owns.get(id);
+        if (cached !== undefined)
+            return cached;
+        const entry = functions.get(id);
+        const classes = new Map();
+        const unknowns = new Map();
+        let more = false;
+        const guarded = new Set();
+        const add = (key, inEffect, file, name) => {
+            const fact = analysis.functions.get(key);
+            if (fact === undefined)
+                return;
+            const thrown = evaluated(fact, analysis).body.throws;
+            // A class an effect throws is a render failure, whatever the body's guards throw.
+            if (inEffect)
+                for (const cls of thrown.classes.keys())
+                    guarded.delete(cls);
+            for (const [cls, info] of thrown.classes) {
+                if (classes.get(cls)?.certain === true)
+                    continue;
+                const location = info.via === null
+                    ? { file, start: fact.fact.at[0], end: fact.fact.at[1] }
+                    : { file: info.via.file, start: info.via.start, end: info.via.end };
+                const step = info.via === null ? (inEffect ? "an effect" : null) : stepOf(info.via.text);
+                classes.set(cls, {
+                    certain: info.certain,
+                    step,
+                    location,
+                    what: info.via === null
+                        ? inEffect
+                            ? "this effect throws"
+                            : `\`${name}\` throws`
+                        : `\`${info.via.text}\` can throw`,
+                });
+            }
+            for (const [k, source] of thrown.unknowns)
+                unknowns.set(k, source);
+            more ||= thrown.more;
+        };
+        if (entry !== undefined) {
+            const ids = entry.fn.kind === "class" ? entry.fn.methods : [entry.fn.id];
+            for (const one of ids)
+                add(one, false, entry.file, entry.fn.name);
+            if (entry.fn.kind !== "class") {
+                for (const cls of classes.keys())
+                    if (guardOnly(id, cls, new Set()))
+                        guarded.add(cls);
+            }
+            for (const effect of effectsOf(id)) {
+                add(`${effect.file}#@${String(effect.start)}`, true, effect.file, entry.fn.name);
+            }
+        }
+        const made = {
+            classes,
+            guarded,
+            unknowns: [...unknowns.values()].sort((a, b) => a.file !== b.file ? (a.file < b.file ? -1 : 1) : a.start - b.start),
+            more,
+        };
+        owns.set(id, made);
+        return made;
+    };
+    const ids = [...functions.keys()].sort();
+    const { results } = propagate({
+        nodes: ids,
+        successors: (id) => edges(id)
+            .filter((site) => nearest(site) === undefined)
+            .map((site) => site.to),
+        input: (id) => id,
+        sameInput: (a, b) => a === b,
+        compute: (id, resultOf) => {
+            const found = new Set();
+            const mine = own(id);
+            for (const [cls, brought] of mine.classes) {
+                if (brought.certain && !mine.guarded.has(cls))
+                    found.add(cls);
+            }
+            for (const site of edges(id)) {
+                if (nearest(site) !== undefined)
+                    continue;
+                for (const cls of resultOf(site.to) ?? [])
+                    found.add(cls);
+            }
+            return found;
+        },
+        initial: new Set(),
+        same: (a, b) => a.size === b.size && [...a].every((cls) => b.has(cls)),
+    });
+    const needs = (id) => results.get(id) ?? new Set();
+    const caught = new Map();
+    const catches = (key) => {
+        const cached = caught.get(key);
+        if (cached !== undefined)
+            return cached;
+        const classes = new Map();
+        const labels = new Map();
+        const unknowns = new Map();
+        let more = false;
+        const seen = new Set();
+        const visit = (id) => {
+            if (seen.has(id))
+                return;
+            seen.add(id);
+            const entry = functions.get(id);
+            if (entry === undefined)
+                return;
+            const mine = own(id);
+            for (const [cls, brought] of mine.classes) {
+                const before = classes.get(cls);
+                if (before !== undefined && (before.certain || !brought.certain))
+                    continue;
+                classes.set(cls, brought);
+                const name = `<${entry.fn.name}>`;
+                labels.set(cls, brought.step === null ? name : `${name} → ${brought.step}`);
+            }
+            for (const source of mine.unknowns) {
+                unknowns.set(`${source.file}:${String(source.start)}:${source.reason}`, source);
+            }
+            more ||= mine.more;
+            for (const site of edges(id))
+                if (nearest(site) === undefined)
+                    visit(site.to);
+        };
+        for (const site of [...entries, ...sites]) {
+            if (nearest(site) === key)
+                visit(site.to);
+        }
+        const made = { classes, labels, unknowns: [...unknowns.values()], more };
+        caught.set(key, made);
+        return made;
+    };
+    const model = {
+        analysis,
+        functions,
+        boundaries,
+        byFile,
+        entries,
+        sites: [...entries, ...sites],
+        edges,
+        nearest,
+        own,
+        needs,
+        catches,
+    };
+    models.set(summaries, model);
+    return model;
+}
+/** The line every boundary hover ends with: what no boundary ever catches. */
+export const NOT_CAUGHT = "not caught here: errors in event handlers and async code";
+/**
+ * On a boundary's tag: `catches: NotFoundError (via <UserPage> → useUser) | others stateward
+ * cannot see (from …)`, then `NOT_CAUGHT`. Undefined when `offset` is on no boundary's tag.
+ */
+export function boundaryLines(model, file, offset) {
+    const element = model.byFile.get(file)?.find((one) => offset >= one.at[0] && offset < one.at[1]);
+    if (element === undefined)
+        return undefined;
+    const caught = model.catches(element.key);
+    const names = [...caught.classes.keys()]
+        .map((id) => {
+        const label = caught.labels.get(id);
+        const name = className(id, model.analysis.classes);
+        return label === undefined ? name : `${name} (via ${label})`;
+    })
+        .sort();
+    const parts = caught.unknowns.length > 0 || caught.more
+        ? [...names, unknownText(caught.unknowns, caught.more)]
+        : names;
+    return [
+        parts.length === 0 ? "catches nothing stateward can see" : `catches: ${parts.join(" | ")}`,
+        NOT_CAUGHT,
+    ];
+}
+//# sourceMappingURL=boundaries.js.map

package/dist/react/fallbacks.d.ts

@@ -0,0 +1,12 @@
+import type { Location, RelatedLocation } from "@stateward/core";
+import type { Model } from "./boundaries.js";
+type Problem = {
+    message: string;
+    hint: string;
+    location: Location;
+    related: readonly RelatedLocation[];
+};
+/** Reports each fallback that leaves out a class its boundary can catch. */
+export declare function checkFallbacks(model: Model, ignored: readonly string[], report: (problem: Problem) => void): void;
+export {};
+//# sourceMappingURL=fallbacks.d.ts.map

package/dist/react/fallbacks.js

@@ -0,0 +1,83 @@
+import { matchesName } from "@stateward/core";
+import { catchName, className } from "../inference/format.js";
+import { relation } from "../inference/solve.js";
+import { codeList, fitted, withExample } from "../text.js";
+/**
+ * Error boundary fallbacks, checked as catches (`errors/catch-misses-error`; they were
+ * `errors/exhaustive-fallback` in earlier releases): a fallback that branches on the error with
+ * `instanceof` handles every class its boundary can catch, or has a branch for the rest.
+ */
+/** What the fallback does with any other error, in the example: what it returns or does. */
+function restLine(kind, variable) {
+    switch (kind) {
+        case "FallbackComponent":
+        case "fallbackRender":
+            return `return <p>Something went wrong: {String(${variable})}</p>;`;
+        case "onError":
+            return `console.error(${variable});`;
+        case "getDerivedStateFromError":
+            return `return { error: ${variable} };`;
+        default: {
+            const unreachable = kind;
+            return unreachable;
+        }
+    }
+}
+function hint(fallback, chain, handler, count) {
+    const line = `add a branch for ${count === 1 ? "it" : "each"}, or end with one for any other error:`;
+    const rest = restLine(fallback.kind, chain.variable);
+    return chain.dispatch === "switch"
+        ? withExample(line, [
+            `case ${chain.variable} instanceof ${handler}:`,
+            "  …",
+            "default:",
+            `  ${rest}`,
+        ])
+        : withExample(line, [`if (${chain.variable} instanceof ${handler}) {`, "  …", "}", rest]);
+}
+/** Reports each fallback that leaves out a class its boundary can catch. */
+export function checkFallbacks(model, ignored, report) {
+    const classes = model.analysis.classes;
+    for (const [key, { file, element }] of model.boundaries) {
+        for (const fallback of element.fallbacks) {
+            const chain = fallback.chain;
+            if (chain === null || chain.generic || !chain.exact)
+                continue;
+            const handled = [];
+            let readable = true;
+            for (const branch of chain.branches) {
+                if (branch === null)
+                    readable = false;
+                else
+                    handled.push(...branch);
+            }
+            if (!readable)
+                continue;
+            const caught = model.catches(key);
+            const missing = [...caught.classes]
+                .filter(([id, brought]) => brought.certain &&
+                !matchesName(catchName(id, classes), ignored) &&
+                handled.every((one) => relation(one, id, classes) === "no"))
+                .map(([id, brought]) => ({ id, brought, name: className(id, classes) }))
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            const [first] = missing;
+            if (first === undefined)
+                continue;
+            const related = missing.slice(0, 3).map(({ brought, name }) => ({
+                location: brought.location,
+                message: `${brought.what} \`${name}\``,
+            }));
+            related.push({
+                location: { file: chain.file, start: chain.at[0], end: chain.at[1] },
+                message: `\`${fallback.name}\` branches on the error here`,
+            });
+            report({
+                message: fitted((cut) => `\`${cut(fallback.name)}\` does not handle ${codeList(missing.map((one) => one.name), cut)}, which this boundary can catch`),
+                hint: hint(fallback, chain, catchName(first.id, classes), missing.length),
+                location: { file, start: fallback.at[0], end: fallback.at[1] },
+                related,
+            });
+        }
+    }
+}
+//# sourceMappingURL=fallbacks.js.map

package/dist/react/render-guards.d.ts

@@ -0,0 +1,24 @@
+import ts from "@stateward/core/typescript";
+import type { FileContext } from "@stateward/core";
+/**
+ * The throws while rendering that `errors/render-throw-without-boundary` leaves out (they were
+ * `errors/throw-in-hook`'s skips in earlier releases): the usual check in a context hook
+ * (`if (!ctx) throw new Error("useAuth must be used within AuthProvider")`), and a check on what
+ * the caller passed (`if (!render && !children) throw …`). Both name a programming mistake of the
+ * caller; an error boundary is not what handles them.
+ */
+type RenderFunction = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+/** Which guards to leave out. */
+export type GuardSkips = {
+    readonly contextGuards: boolean;
+    readonly inputGuards: boolean;
+};
+/** Both left out: the default. */
+export declare const ALL_GUARDS: GuardSkips;
+/**
+ * The start of the thrown expression of every guard `throw` in the render function's own body
+ * (not in a nested function), as the throws summary records it (`new Error(…)`).
+ */
+export declare function guardThrows(fn: RenderFunction, ctx: FileContext, skips: GuardSkips): number[];
+export {};
+//# sourceMappingURL=render-guards.d.ts.map