@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/dist/inference/project.d.ts

@@ -0,0 +1,8 @@
+import type { FileContext } from "@stateward/core";
+import type { ThrowsSummary } from "./summary.js";
+/**
+ * `summarizeThrows` with the facts of the packages the file calls (packages.ts), computed once
+ * per file when its rules run one after the other.
+ */
+export declare function summarizeOnce(ctx: FileContext): ThrowsSummary;
+//# sourceMappingURL=project.d.ts.map

package/dist/inference/project.js

@@ -0,0 +1,22 @@
+import { packageResolver } from "./packages.js";
+import { summarizeThrows } from "./summarize.js";
+/**
+ * The last file's summary, by program: `catch-misses-error`, `throws-doc-mismatch` and the React
+ * rules all summarize the same facts, and the engine runs a file's rules one after the other.
+ * Only the last file is kept: kept for every file, the summaries stayed in memory for the whole
+ * run next to the engine's own copies.
+ */
+const last = new WeakMap();
+/**
+ * `summarizeThrows` with the facts of the packages the file calls (packages.ts), computed once
+ * per file when its rules run one after the other.
+ */
+export function summarizeOnce(ctx) {
+    const known = last.get(ctx.types);
+    if (known?.sourceFile === ctx.sourceFile)
+        return known.summary;
+    const summary = summarizeThrows(ctx, packageResolver(ctx));
+    last.set(ctx.types, { sourceFile: ctx.sourceFile, summary });
+    return summary;
+}
+//# sourceMappingURL=project.js.map

package/dist/inference/solve.d.ts

@@ -0,0 +1,128 @@
+import type { Json, Location } from "@stateward/core";
+import type { ClassFact, Effect, FunctionFact, Handler, PackageFacts } from "./summary.js";
+/** `zod 3.23.8`, or `zod` when its version is not known. */
+export declare function packageLabel(facts: Pick<PackageFacts, "name" | "version">): string;
+/** Something that cannot be followed, where it is and why: shown as `api.get: no declaration`. */
+export type Source = {
+    readonly file: string;
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly reason: string;
+    /** The package whose facts this unknown comes from, when it does. */
+    readonly package?: string;
+};
+/**
+ * A set of errors: known classes by id (true when the class surely reaches here, false when it
+ * may have been handled by a test this analysis does not read), and the unknown sources.
+ */
+export type Thrown = {
+    readonly classes: ReadonlyMap<string, boolean>;
+    /**
+     * Where a class known from a package's facts comes from, by id: `zod 3.23.8: declared`
+     *. Classes of the project have none.
+     */
+    readonly origins: ReadonlyMap<string, string>;
+    readonly unknowns: readonly Source[];
+    readonly more: boolean;
+};
+/** What calling a function throws, and what the promise it returns rejects with. */
+export type Result = {
+    readonly throws: Thrown;
+    readonly rejects: Thrown;
+};
+/** Where a class first comes into a set: the call that brings it, null for a `throw`. */
+export type Via = Location & {
+    readonly text: string;
+};
+/** The set while it is being computed, with where each class comes from. */
+export type Collected = {
+    readonly classes: Map<string, {
+        certain: boolean;
+        via: Via | null;
+        from: string | null;
+    }>;
+    readonly unknowns: Map<string, Source>;
+    more: boolean;
+};
+export type FunctionEntry = {
+    readonly file: string;
+    readonly fact: FunctionFact;
+};
+export type Analysis = {
+    readonly functions: ReadonlyMap<string, FunctionEntry>;
+    readonly classes: ReadonlyMap<string, ClassFact>;
+    readonly results: ReadonlyMap<string, Result>;
+    /** Every class's facts as one text: equal texts, equal `instanceof` answers. */
+    readonly classesKey: string;
+    /** The top-level code of each file. */
+    readonly modules: readonly {
+        file: string;
+        effects: readonly Effect[];
+    }[];
+    /** Functions computed by this solve (not reused from the last one): early cut-off at work. */
+    readonly computed: number;
+};
+/** A catch as the evaluation met it: what its `try` throws, and what no branch handles. */
+export type CatchSeen = {
+    readonly file: string;
+    readonly handler: Handler;
+    readonly thrown: Collected;
+    readonly unhandled: ReadonlyMap<string, {
+        certain: boolean;
+        via: Via | null;
+        from: string | null;
+    }>;
+};
+export declare function collected(): Collected;
+/** The set as a result: classes sorted by id, unknown sources sorted and capped. */
+export declare function toThrown(from: Collected): Thrown;
+export declare function sameResult(a: Result, b: Result): boolean;
+/**
+ * Whether `instanceof <handler>` is true for an error of class `cls`: "yes" when `handler` is the
+ * class or one it extends, "no" when the chain is known and does not reach it, "undecided" when
+ * the chain cannot be followed.
+ */
+export declare function relation(handler: string, cls: string, classes: ReadonlyMap<string, ClassFact>): "yes" | "no" | "undecided";
+/** What evaluating a function body needs. */
+type Context = {
+    readonly file: string;
+    readonly classes: ReadonlyMap<string, ClassFact>;
+    resultOf(id: string): Result | undefined;
+    /** Told about every catch the evaluation passes, for `catch-misses-error`. */
+    onCatch?: (seen: CatchSeen) => void;
+};
+/** Adds what `effects` throw to `into`; `caught` holds, by catch, what reaches its variable. */
+export declare function evaluate(effects: readonly Effect[], context: Context, caught: ReadonlyMap<number, Collected>, into: Collected): void;
+/** What the body of a function throws and rejects with, ignoring its `@throws`. */
+export declare function inferred(entry: FunctionEntry, analysis: Pick<Analysis, "classes" | "results">, onCatch?: (seen: CatchSeen) => void): {
+    throws: Collected;
+    rejects: Collected;
+};
+/** Solves what every function of the project throws. */
+export declare function analyse(summaries: ReadonlyMap<string, Json>): Analysis;
+/**
+ * Solves a closed set of functions on its own, without the project's memo: a package's functions
+ * read from its source. Calls outside the set are unknown.
+ */
+export declare function solveFunctions(functions: ReadonlyMap<string, FunctionEntry>, classes: ReadonlyMap<string, ClassFact>): ReadonlyMap<string, Result>;
+/**
+ * What a function's own evaluation gives the rules (its catches, what its body throws), kept per
+ * facts object while its callees' results and the classes are the same objects: a full pass
+ * after an edit evaluates only the functions whose facts or callees changed.
+ */
+type Evaluated = {
+    readonly callees: readonly (Result | undefined)[];
+    readonly classesKey: string;
+    readonly catches: readonly CatchSeen[];
+    readonly body: {
+        throws: Collected;
+        rejects: Collected;
+    };
+};
+/** The function's catches and inferred result, evaluated with the analysis's callee results. */
+export declare function evaluated(entry: FunctionEntry, analysis: Analysis): Evaluated;
+/** Every catch of the project, with what reaches it, for `catch-misses-error`. */
+export declare function everyCatch(analysis: Analysis): readonly CatchSeen[];
+export {};
+//# sourceMappingURL=solve.d.ts.map