@stateward/plugin-errors 0.0.0-stage → 1.0.0

package/dist/inference/format.js

@@ -0,0 +1,72 @@
+import { builtinCatchName, builtinName, isBuiltin } from "./builtins.js";
+/** At most this many unknown sources are listed; the rest are counted. */
+const MAX_LISTED_SOURCES = 5;
+const PACKAGE_CLASS = /^package:.+#(?<name>[^#]+)$/;
+/** A class's name from its id when no facts are known about it (`package:zod#ZodError`). */
+function nameOfId(id) {
+    return PACKAGE_CLASS.exec(id)?.groups?.name ?? id;
+}
+/** How a class is shown: its name, `AbortError (DOMException)` for a named DOMException. */
+export function className(id, classes) {
+    return isBuiltin(id) ? builtinName(id) : (classes.get(id)?.name ?? nameOfId(id));
+}
+/** The name an `instanceof` test or a `@throws` tag uses for the class. */
+export function catchName(id, classes) {
+    return isBuiltin(id) ? builtinCatchName(id) : (classes.get(id)?.name ?? nameOfId(id));
+}
+function sourceKey(source) {
+    return `${source.file}:${String(source.start)}:${source.reason}`;
+}
+/** `api.get: no declaration`. */
+function sourceText(source) {
+    return `${source.text}: ${source.reason}`;
+}
+/** `others stateward cannot see (from a: why; b: why; and 3 more)`. */
+export function unknownText(sources, more) {
+    const listed = sources.slice(0, MAX_LISTED_SOURCES).map(sourceText);
+    const rest = sources.length - listed.length;
+    const tail = rest > 0 || more ? [`and ${String(rest)}${more ? "+" : ""} more`] : [];
+    return `others stateward cannot see (from ${[...listed, ...tail].join("; ")})`;
+}
+/**
+ * `ParseError | ZodError (zod 3.23.8: declared) | others stateward cannot see (from …)`, or "" for an empty set: a class
+ * known from a package's facts names where they come from.
+ */
+export function thrownText(thrown, classes) {
+    const shown = (id) => {
+        const origin = thrown.origins.get(id);
+        const name = className(id, classes);
+        return origin === undefined ? name : `${name} (${origin})`;
+    };
+    const names = [...new Set([...thrown.classes.keys()].map(shown))].sort();
+    const parts = thrown.unknowns.length > 0 || thrown.more
+        ? [...names, unknownText(thrown.unknowns, thrown.more)]
+        : names;
+    return parts.join(" | ");
+}
+/**
+ * What a call's promise rejects with, without the unknown parts already listed as thrown: an
+ * unknown call is both thrown and returned when stateward cannot tell whether it gives a promise,
+ * and is shown once, where it is thrown.
+ */
+export function rejectsShown(result) {
+    const shown = new Set(result.throws.unknowns.map(sourceKey));
+    return {
+        ...result.rejects,
+        unknowns: result.rejects.unknowns.filter((s) => !shown.has(sourceKey(s))),
+    };
+}
+/**
+ * The hover's lines: `throws: …` for what a call throws, `rejects: …` for what its promise
+ * rejects with, `throws nothing stateward can see` when both are empty.
+ */
+export function resultLines(result, classes) {
+    const throws = thrownText(result.throws, classes);
+    const rejects = thrownText(rejectsShown(result), classes);
+    const lines = [
+        ...(throws === "" ? [] : [`throws: ${throws}`]),
+        ...(rejects === "" ? [] : [`rejects: ${rejects}`]),
+    ];
+    return lines.length === 0 ? ["throws nothing stateward can see"] : lines;
+}
+//# sourceMappingURL=format.js.map

package/dist/inference/packages.d.ts

@@ -0,0 +1,40 @@
+import ts from "@stateward/core/typescript";
+import type { FileContext } from "@stateward/core";
+import type { PackageResolver } from "./summarize.js";
+/**
+ * Library facts for the Errors pack: what a call into a
+ * package throws, from the first source that answers:
+ *
+ * 1. the project's config (`facts`);
+ * 2. curated fact files shipped with stateward (`curatedFacts` answers nothing yet);
+ * 3. `@throws {X}` on the called declaration in the package's `.d.ts`;
+ * 4. inferred from the package's JavaScript, with the summarizer of the project's own code, from
+ *    the called function to what it calls in the package (bounded), cached globally;
+ * 5. unknown, with one of the reasons below.
+ */
+/** Why a package's function is not (fully) known: fixed strings, shown as they are. */
+export declare const UNKNOWN_REASONS: readonly ["no readable source", "not found in its source", "native addon", "minified", "eval", "dynamic require", "too large to follow", "untyped @throws", "calls a callback", "calls code it cannot see", "dynamic call", "throws a value of unknown class", "awaits a promise it cannot follow"];
+export type UnknownReason = (typeof UNKNOWN_REASONS)[number];
+/**
+ * At most this many functions are read per package function asked for.
+ * The bounds count, never time: a verdict by time would differ between machines.
+ */
+export declare const MAX_FUNCTIONS = 200;
+/** The declaration's path in the package's types: `["Client", "get"]`. */
+export declare function pathOf(node: ts.Node): string[];
+/**
+ * Curated fact files shipped with stateward: none ship yet, so nothing answers between the config
+ * and the declarations. Reading `facts/<package>@<major>.json` here would add the `curated`
+ * source, and the resolver would ask it after the config.
+ */
+export declare function curatedFacts(): undefined;
+/** What this process computed and read back, for tests: inference runs and global-cache hits. */
+export declare function packageFactsStats(): {
+    inferences: number;
+    cacheHits: number;
+};
+/** Forgets what this process knows about packages (tests: the next run reads the global cache). */
+export declare function forgetPackageFacts(): void;
+/** Finds the facts of the calls into packages of the file `ctx` summarizes. */
+export declare function packageResolver(ctx: Pick<FileContext, "file" | "facts">): PackageResolver;
+//# sourceMappingURL=packages.d.ts.map