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

package/dist/react/render-guards.js

@@ -0,0 +1,271 @@
+import ts from "@stateward/core/typescript";
+import { scanRunning, stripParentheses } from "../syntax.js";
+/** Both left out: the default. */
+export const ALL_GUARDS = { contextGuards: true, inputGuards: true };
+/** `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);
+}
+/**
+ * Who answers for an input: `parameter` for a parameter (or a prop destructured from one, or
+ * `props.x`), `context` for a value read through a context hook; undefined for anything else.
+ */
+function callerInput(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) ? "parameter" : undefined;
+    }
+    if (!ts.isIdentifier(node))
+        return undefined;
+    const symbol = ctx.types.symbolAt(node);
+    const declaration = symbol === undefined ? undefined : ctx.types.declarationOf(symbol)?.node;
+    if (declaration === undefined)
+        return undefined;
+    if (isParameterOf(declaration, render.fn) || isDestructuredParameter(declaration, render, ctx)) {
+        return "parameter";
+    }
+    if (!ts.isVariableDeclaration(declaration) || declaration.initializer === undefined) {
+        return undefined;
+    }
+    const list = declaration.parent;
+    if (!ts.isVariableDeclarationList(list) || (list.flags & ts.NodeFlags.Const) === 0) {
+        return undefined;
+    }
+    const init = stripParentheses(declaration.initializer);
+    return ts.isCallExpression(init) && isContextHook(init.expression, ctx) ? "context" : undefined;
+}
+const EITHER = { undefined: true, null: true };
+/**
+ * Whether a check for a missing input names a caller's mistake. A parameter's check does only
+ * when its type rules the value out: a prop typed `title?: string` can be left out by any caller,
+ * so its check is a render failure. A context hook's value is missing only
+ * when a Provider is, which is the caller's mistake.
+ */
+function isCallerMistake(expression, missing, render, ctx) {
+    const input = callerInput(expression, render, ctx);
+    if (input !== "parameter")
+        return input === "context";
+    const node = stripParentheses(expression);
+    return (!(missing.undefined && ctx.types.canBeUndefined(node)) &&
+        !(missing.null && ctx.types.canBeNull(node)));
+}
+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);
+}
+/** What a comparison with `undefined` or `null` tests for; undefined for any other operand. */
+function missingTested(operand, loose) {
+    const node = stripParentheses(operand);
+    if (node.kind === ts.SyntaxKind.NullKeyword)
+        return loose ? EITHER : { undefined: false, null: true };
+    if (ts.isIdentifier(node) && node.text === "undefined") {
+        return loose ? EITHER : { undefined: true, null: false };
+    }
+    return undefined;
+}
+/**
+ * Whether a condition holds only when an input is missing through a caller's mistake: `!x`,
+ * `x == null`, `x === undefined` (either side), and `&&` / `||` of such checks.
+ */
+function checksMissingInput(condition, render, ctx) {
+    const node = stripParentheses(condition);
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+        return isCallerMistake(node.operand, EITHER, 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;
+    }
+    const loose = operator === ts.SyntaxKind.EqualsEqualsToken;
+    const right = missingTested(node.right, loose);
+    const left = missingTested(node.left, loose);
+    return ((right !== undefined && isCallerMistake(node.left, right, render, ctx)) ||
+        (left !== undefined && isCallerMistake(node.right, left, 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;
+}
+/**
+ * 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 function guardThrows(fn, ctx, skips) {
+    const body = fn.body;
+    if (body === undefined || (!skips.contextGuards && !skips.inputGuards))
+        return [];
+    const render = { fn, body };
+    const found = [];
+    scanRunning(body, (node) => {
+        if (!ts.isThrowStatement(node))
+            return;
+        const guard = (skips.contextGuards && guardsContext(node, body, ctx)) ||
+            (skips.inputGuards && guardsInput(node, render, ctx));
+        if (guard)
+            found.push(stripParentheses(node.expression).getStart(ctx.sourceFile));
+    });
+    return found;
+}
+//# sourceMappingURL=render-guards.js.map

package/dist/react/tree.d.ts

@@ -0,0 +1,98 @@
+import type { FileContext, Json, StringListRecord } from "@stateward/core";
+import { type GuardSkips } from "./render-guards.js";
+/**
+ * What one file renders, for the boundary rules and hover:
+ * its components and hooks, the components each renders and the error boundaries around each
+ * render, the app's entry points, and every boundary element with its fallbacks. Plain JSON, so
+ * the engine caches it with the file.
+ */
+/** A start and end offset in the summarized file. */
+export type Span = readonly [number, number];
+/**
+ * What is around a render inside the component that writes it, innermost first: a boundary
+ * element (by key), or an own component whose `children` it is passed as (by id), which may put
+ * them under a boundary of its own.
+ */
+export type Around = {
+    readonly boundary: string;
+} | {
+    readonly via: string;
+};
+export type TreeRender = {
+    /** The id of the own component or class the tag names. */
+    readonly target: string;
+    /** The tag as written. */
+    readonly name: string;
+    readonly at: Span;
+    readonly around: readonly Around[];
+    /**
+     * The element goes where stateward cannot follow it (passed to a function, stored in an
+     * object): which boundary is above it is not known, so nothing is reported for it.
+     */
+    readonly unknown: boolean;
+};
+/** The parts of a boundary that receive the error it catches. */
+export type FallbackKind = "FallbackComponent" | "fallbackRender" | "onError" | "getDerivedStateFromError";
+export declare const FALLBACK_KINDS: readonly FallbackKind[];
+/** How a fallback branches on the error with `instanceof`. */
+export type Chain = {
+    /** The file of the fallback's code (a `FallbackComponent` may live in another file). */
+    readonly file: string;
+    /** The first `if`, `switch` or `?:` of the chain. */
+    readonly at: Span;
+    /** How the error is written in the tests: `error`, `props.error`. */
+    readonly variable: string;
+    readonly dispatch: "if" | "switch";
+    /** The classes each branch names (ids); a branch with a class that resolves to nothing is `null`. */
+    readonly branches: readonly (readonly string[] | null)[];
+    /** Every test is only `instanceof` tests joined by `||`. */
+    readonly exact: boolean;
+    /** A final `else`, `default`, or code after the chain that does more than return nothing. */
+    readonly generic: boolean;
+};
+export type Fallback = {
+    readonly kind: FallbackKind;
+    /** The prop on the element, or the element's tag for a class's `getDerivedStateFromError`. */
+    readonly at: Span;
+    /** How messages name it: `UserError`, `fallbackRender`, `AppBoundary.getDerivedStateFromError`. */
+    readonly name: string;
+    readonly chain: Chain | null;
+};
+export type BoundaryElement = {
+    /** `<file>:<offset of the element>`. */
+    readonly key: string;
+    readonly name: string;
+    /** The tag name. */
+    readonly at: Span;
+    readonly fallbacks: readonly Fallback[];
+};
+/** An effect callback, by the offset its function starts at (how the throws facts name it). */
+export type TreeFunction = {
+    readonly id: string;
+    readonly name: string;
+    readonly at: Span;
+    readonly kind: "component" | "hook" | "class";
+    readonly renders: readonly TreeRender[];
+    /** Own hooks it calls, by id. */
+    readonly hooks: readonly string[];
+    /** The offsets of the `useEffect` / `useLayoutEffect` callbacks written in it. */
+    readonly effects: readonly number[];
+    /** A class's render and lifecycle methods, by id. */
+    readonly methods: readonly string[];
+    /** The boundaries around every place it renders `children`, innermost first; null for none. */
+    readonly children: readonly string[] | null;
+    /** Where the guard throws in its body start (render-guards.ts): not counted as render failures. */
+    readonly guards: readonly number[];
+};
+export type TreeSummary = {
+    readonly functions: readonly TreeFunction[];
+    /** What `createRoot(…).render(…)` and `hydrateRoot(…)` render. */
+    readonly entries: readonly TreeRender[];
+    readonly boundaries: readonly BoundaryElement[];
+};
+/** The error boundaries from packages that are known without a config: package to components. */
+export declare const LIBRARY_BOUNDARIES: StringListRecord;
+export declare function summarizeTree(ctx: FileContext, libraryBoundaries?: StringListRecord, skips?: GuardSkips): TreeSummary;
+/** The tree as `summarizeTree` wrote it, or undefined for anything else (an old cache file). */
+export declare function readTree(value: Json | undefined): TreeSummary | undefined;
+//# sourceMappingURL=tree.d.ts.map