@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/load/defs.d.ts

@@ -0,0 +1,7 @@
+import type { OpenApiDocument } from "../types.ts";
+/** Where recursive schemas live after dereferencing: `$ref: "testing-defs#/$defs/<name>"`. */
+export declare const DEFS_ID = "testing-defs";
+export declare const DEFS_KEY = "x-testing-defs";
+/** The recursive schemas a dereferenced document refers to, by name. Empty when there are none. */
+export declare function documentDefs(doc: OpenApiDocument): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=defs.d.ts.map

package/dist/api/spec/load/defs.js

@@ -0,0 +1,9 @@
+/** Where recursive schemas live after dereferencing: `$ref: "testing-defs#/$defs/<name>"`. */
+export const DEFS_ID = "testing-defs";
+export const DEFS_KEY = "x-testing-defs";
+/** The recursive schemas a dereferenced document refers to, by name. Empty when there are none. */
+export function documentDefs(doc) {
+    const defs = doc[DEFS_KEY];
+    return defs !== null && typeof defs === "object" ? defs : {};
+}
+//# sourceMappingURL=defs.js.map

package/dist/api/spec/load/dereference.d.ts

@@ -0,0 +1,23 @@
+import type { OpenApiDocument } from "../types.ts";
+/**
+ * Resolves internal `$ref`s, producing a document with no references left in it except the ones
+ * that must stay: external refs, reported by the caller as a coverage gap, and refs that would
+ * otherwise recurse forever. A ref that points at nothing becomes a `DANGLING_KEY` node, also
+ * reported, which the model reads operation by operation.
+ *
+ * Every source node maps to exactly one output node, so the result is the same whatever order the
+ * document lists its keys in — `components` before `paths` or after. Sibling keys beside a `$ref`
+ * (OpenAPI 3.1) apply to that use site only and never leak onto the shared target. Data is left
+ * alone: a `$ref` inside an `example` is an example, not a reference.
+ *
+ * A schema that refers to itself, directly or through others, cannot be inlined: the result would
+ * be a cyclic object that no serializer can print and no generator can bound. Such a reference
+ * becomes `$ref: "testing-defs#/$defs/<name>"` and the schema is stored once under `x-testing-defs`, which
+ * the validator registers with AJV and the generator follows to a bounded depth.
+ */
+export declare function dereference(doc: OpenApiDocument): {
+    doc: OpenApiDocument;
+    externalRefs: string[];
+    danglingRefs: string[];
+};
+//# sourceMappingURL=dereference.d.ts.map

package/dist/api/spec/load/dereference.js

@@ -0,0 +1,55 @@
+import { EXTERNAL_KEY } from "./bundle.js";
+import { DEFS_KEY } from "./defs.js";
+import { resolvePointer } from "./pointer.js";
+import { walk } from "./walk.js";
+/**
+ * Resolves internal `$ref`s, producing a document with no references left in it except the ones
+ * that must stay: external refs, reported by the caller as a coverage gap, and refs that would
+ * otherwise recurse forever. A ref that points at nothing becomes a `DANGLING_KEY` node, also
+ * reported, which the model reads operation by operation.
+ *
+ * Every source node maps to exactly one output node, so the result is the same whatever order the
+ * document lists its keys in — `components` before `paths` or after. Sibling keys beside a `$ref`
+ * (OpenAPI 3.1) apply to that use site only and never leak onto the shared target. Data is left
+ * alone: a `$ref` inside an `example` is an example, not a reference.
+ *
+ * A schema that refers to itself, directly or through others, cannot be inlined: the result would
+ * be a cyclic object that no serializer can print and no generator can bound. Such a reference
+ * becomes `$ref: "testing-defs#/$defs/<name>"` and the schema is stored once under `x-testing-defs`, which
+ * the validator registers with AJV and the generator follows to a bounded depth.
+ */
+export function dereference(doc) {
+    const state = {
+        building: new Set(),
+        danglingRefs: new Set(),
+        defNames: new Map(),
+        doc,
+        externalRefs: new Set(),
+        memo: new Map(),
+    };
+    const out = walk(state, doc);
+    const defs = recursiveSchemas(state, out);
+    /* Every ref into the bundled files is inlined or stored in the definitions by now. */
+    delete out[EXTERNAL_KEY];
+    if (Object.keys(defs).length > 0)
+        out[DEFS_KEY] = defs;
+    return { danglingRefs: [...state.danglingRefs], doc: out, externalRefs: [...state.externalRefs] };
+}
+/**
+ * Each recursive schema, stored once by name. Its body is the completed output for the target
+ * node, whose own self-references are already `$ref`s into these definitions.
+ */
+function recursiveSchemas(state, out) {
+    const defs = {};
+    for (const [ref, name] of state.defNames) {
+        /* A name is only given to a target that was being built, which is always an object. */
+        const target = resolvePointer(state.doc, ref);
+        /* An Example Object is walked without a memo entry, so a cycle through one walks it again. */
+        const body = state.memo.get(target) ?? walk(state, target);
+        /* `$ref: "#"` names the document itself, which is about to carry these definitions: store a
+         * copy without them, or the definitions would contain themselves. */
+        defs[name] = body === out ? { ...out } : body;
+    }
+    return defs;
+}
+//# sourceMappingURL=dereference.js.map

package/dist/api/spec/load/parse.d.ts

@@ -0,0 +1,16 @@
+/** A specification's text read as an OpenAPI 3.x document, JSON or YAML. */
+import type { OpenApiDocument } from "../types.ts";
+/** Parses `text` read from `source`; every failure names the source and what went wrong. */
+export declare function parseDocument(text: string, source: string): Promise<OpenApiDocument>;
+/** Parses JSON or YAML text read from `source`, whatever it holds: a file another one refers to. */
+export declare function parseText(text: string, source: string): Promise<unknown>;
+/**
+ * Accepts an OpenAPI 3.0–3.2 document and nothing else; `assertVersion` refuses every other
+ * version as the caller's to convert.
+ *
+ * YAML parses almost any text — a `Not Found` page is a valid YAML string — so "it parsed" says
+ * nothing about whether this is a document the API tester can test. Accepting it produced a run that graded
+ * zero operations and reported success.
+ */
+export declare function assertOpenApi(parsed: unknown, source: string): OpenApiDocument;
+//# sourceMappingURL=parse.d.ts.map

package/dist/api/spec/load/parse.js

@@ -0,0 +1,76 @@
+/** A specification's text read as an OpenAPI 3.x document, JSON or YAML. */
+import { messageOf } from "../../errors/message.js";
+import { assertVersion } from "./version.js";
+import { isRaw } from "../../config/types/raw.js";
+/** Parses `text` read from `source`; every failure names the source and what went wrong. */
+export async function parseDocument(text, source) {
+    return assertOpenApi(await parseText(text, source), source);
+}
+/** Parses JSON or YAML text read from `source`, whatever it holds: a file another one refers to. */
+export async function parseText(text, source) {
+    /* A byte-order mark is not part of the document; JSON.parse rejects it outright. */
+    const body = text.replace(/^\uFEFF/, "");
+    if (body.trim() === "") {
+        throw new Error(`testing api: ${source} is empty`);
+    }
+    return looksLikeJson(body) ? parseJson(body, source) : parseYaml(body, source);
+}
+function parseJson(text, source) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`testing api: ${source} starts as JSON but does not parse: ${messageOf(error)}. ${diagnoseJson(text)}`, {
+            cause: error,
+        });
+    }
+}
+async function parseYaml(text, source) {
+    try {
+        const { parse } = await import("yaml");
+        return parse(text);
+    }
+    catch (error) {
+        throw new Error(`testing api: could not parse ${source} as JSON or YAML: ${messageOf(error)}`, { cause: error });
+    }
+}
+/**
+ * Accepts an OpenAPI 3.0–3.2 document and nothing else; `assertVersion` refuses every other
+ * version as the caller's to convert.
+ *
+ * YAML parses almost any text — a `Not Found` page is a valid YAML string — so "it parsed" says
+ * nothing about whether this is a document the API tester can test. Accepting it produced a run that graded
+ * zero operations and reported success.
+ */
+export function assertOpenApi(parsed, source) {
+    if (!isRaw(parsed)) {
+        const shown = typeof parsed === "string" ? JSON.stringify(parsed.slice(0, 60)) : String(parsed);
+        throw new Error(`testing api: ${source} is not an OpenAPI document — it parsed as ${shown}`);
+    }
+    const doc = parsed;
+    assertVersion(doc, source);
+    if (doc.paths === null || typeof doc.paths !== "object" || Array.isArray(doc.paths)) {
+        throw new Error(`testing api: ${source} has no "paths" object, so there is nothing to test`);
+    }
+    return doc;
+}
+function looksLikeJson(text) {
+    const first = text.trimStart()[0];
+    return first === "{" || first === "[";
+}
+/**
+ * Distinguishes a malformed document from a truncated one. A spec cut short by a proxy or a
+ * download limit is by far the most common cause, and reporting it as invalid syntax sends
+ * people looking for a bug in a file that is actually fine.
+ */
+function diagnoseJson(text) {
+    const opens = text.match(/[[{]/g).length;
+    const closes = (text.match(/[\]}]/g) ?? []).length;
+    if (opens > closes) {
+        return (`The document has ${opens - closes} more opening than closing brackets, so it is most ` +
+            `likely truncated — it ends after ${text.length} bytes. Check for a download or proxy ` +
+            "size limit.");
+    }
+    return "The document appears complete, so this is a syntax error rather than truncation.";
+}
+//# sourceMappingURL=parse.js.map

package/dist/api/spec/load/pointer.d.ts

@@ -0,0 +1,6 @@
+/** JSON pointers into a document, as an internal `$ref` names them. */
+/** The node `ref` points at (`#`, `#/`, or `#/a/b`), or `undefined` when nothing is there. */
+export declare function resolvePointer(doc: unknown, ref: string): unknown;
+/** A JSON pointer segment: `~1` and `~0` escapes, then percent-encoding (`%7Bid%7D`). */
+export declare function decodeSegment(seg: string): string;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/api/spec/load/pointer.js

@@ -0,0 +1,24 @@
+/** JSON pointers into a document, as an internal `$ref` names them. */
+/** The node `ref` points at (`#`, `#/`, or `#/a/b`), or `undefined` when nothing is there. */
+export function resolvePointer(doc, ref) {
+    if (ref === "#" || ref === "#/")
+        return doc;
+    let node = doc;
+    for (const seg of ref.slice(2).split("/").map(decodeSegment)) {
+        if (node === null || typeof node !== "object" || !Object.hasOwn(node, seg))
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/** A JSON pointer segment: `~1` and `~0` escapes, then percent-encoding (`%7Bid%7D`). */
+export function decodeSegment(seg) {
+    const unescaped = seg.replace(/~1/g, "/").replace(/~0/g, "~");
+    try {
+        return decodeURIComponent(unescaped);
+    }
+    catch {
+        return unescaped;
+    }
+}
+//# sourceMappingURL=pointer.js.map

package/dist/api/spec/load/source.d.ts

@@ -0,0 +1,27 @@
+import type { OpenApiDocument } from "../types.ts";
+/** Where a document is read from, and how a URL is fetched; the caller owns the network. */
+export interface SpecSourceOptions {
+    baseUrl?: string | undefined;
+    fetchText?: (url: string) => Promise<string>;
+    /** The folder a relative path is read from: the config's, for a document a config names. Default the working directory. */
+    dir?: string | undefined;
+}
+/**
+ * Loads a specification from wherever it lives, in JSON or YAML.
+ *
+ * Three forms are accepted, resolved in a fixed order so the outcome never depends on a guess
+ * about what the string "looks like":
+ *
+ *   1. an absolute `http(s)://` or `file://` URL — used as given
+ *   2. a path that exists on disk — read as a file, relative to `dir` (default the working directory)
+ *   3. anything else, when a base URL is known — resolved against it, so `/v1/openapi/spec`
+ *      and `openapi.json` both work next to `baseUrl`
+ *
+ * When none apply the error names every location that was tried, rather than reporting the last
+ * failure as though it were the only attempt.
+ *
+ * A file's relative `$ref`s to other files are read in beside it (`bundleLocalRefs`); a fetched
+ * document's are left unfetched, for the caller to report.
+ */
+export declare function loadSpec(source: string, options?: SpecSourceOptions): Promise<OpenApiDocument>;
+//# sourceMappingURL=source.d.ts.map

package/dist/api/spec/load/source.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bundleLocalRefs } from "./bundle.js";
+import { parseDocument } from "./parse.js";
+/**
+ * Loads a specification from wherever it lives, in JSON or YAML.
+ *
+ * Three forms are accepted, resolved in a fixed order so the outcome never depends on a guess
+ * about what the string "looks like":
+ *
+ *   1. an absolute `http(s)://` or `file://` URL — used as given
+ *   2. a path that exists on disk — read as a file, relative to `dir` (default the working directory)
+ *   3. anything else, when a base URL is known — resolved against it, so `/v1/openapi/spec`
+ *      and `openapi.json` both work next to `baseUrl`
+ *
+ * When none apply the error names every location that was tried, rather than reporting the last
+ * failure as though it were the only attempt.
+ *
+ * A file's relative `$ref`s to other files are read in beside it (`bundleLocalRefs`); a fetched
+ * document's are left unfetched, for the caller to report.
+ */
+export async function loadSpec(source, options = {}) {
+    const { path, text } = await readSpecSource(source, options);
+    const doc = await parseDocument(text, source);
+    return path === undefined ? doc : bundleLocalRefs(doc, path);
+}
+/* A URL with nothing to fetch it is a caller's mistake: the API tester's network policy lives in the runtime. */
+function fetcher(options) {
+    return (options.fetchText ??
+        ((url) => Promise.reject(new Error(`testing api: ${url} is a URL, and this caller reads only files`))));
+}
+async function readSpecSource(source, options) {
+    const { baseUrl } = options;
+    if (/^https?:\/\//.test(source))
+        return { text: await fetcher(options)(source) };
+    if (source.startsWith("file://"))
+        return readPath(fileURLToPath(source));
+    /* A real file wins over a route: a spec checked into the repository is the more specific
+     * intent, and silently fetching instead would hide a typo in the path. */
+    const asPath = resolve(options.dir ?? process.cwd(), source);
+    try {
+        return await readPath(asPath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (baseUrl !== undefined && baseUrl !== "") {
+        return { text: await fetcher(options)(new URL(source, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString()) };
+    }
+    throw new Error(`testing api: could not find a specification at "${source}". Tried:\n  ${asPath}` +
+        (baseUrl === undefined ? "\nPass --base-url (or set baseUrl in the config) to resolve it as a route." : ""));
+}
+async function readPath(path) {
+    return { path, text: await readFile(path, "utf8") };
+}
+//# sourceMappingURL=source.js.map

package/dist/api/spec/load/version.d.ts

@@ -0,0 +1,14 @@
+/** The OpenAPI versions the API tester reads, and the refusal of every other. */
+import type { RawOf } from "../../config/types/raw.ts";
+import type { OpenApiDocument } from "../types.ts";
+/**
+ * Accepts an OpenAPI 3.0, 3.1 or 3.2 document. Swagger 2, an OpenAPI below 3.0 and one newer than
+ * 3.2 are documents the caller must convert or choose otherwise, so each is a `UsageError` naming
+ * its version. A document with no version string is not an OpenAPI document at all.
+ */
+/** A parsed document's top-level fields before it is known to be OpenAPI: its own, and Swagger 2's marker. */
+export type RawDocument = RawOf<OpenApiDocument & {
+    swagger: unknown;
+}>;
+export declare function assertVersion(doc: RawDocument, source: string): void;
+//# sourceMappingURL=version.d.ts.map

package/dist/api/spec/load/version.js

@@ -0,0 +1,16 @@
+/** The OpenAPI versions the API tester reads, and the refusal of every other. */
+import { UsageError } from "../../errors/usage-error.js";
+const READS = "the API tester reads OpenAPI 3.0–3.2 only";
+export function assertVersion(doc, source) {
+    if (doc.swagger !== undefined) {
+        throw new UsageError(`testing api: ${source} is Swagger ${String(doc.swagger)}; ${READS} — convert it first`);
+    }
+    if (typeof doc.openapi !== "string") {
+        throw new Error(`testing api: ${source} has no "openapi" version field; ${READS}`);
+    }
+    const minor = /^3\.(\d+)/.exec(doc.openapi)?.[1];
+    if (minor === undefined || Number(minor) > 2) {
+        throw new UsageError(`testing api: ${source} is OpenAPI ${doc.openapi}; ${READS}`);
+    }
+}
+//# sourceMappingURL=version.js.map

package/dist/api/spec/load/walk.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The walk `dereference` runs: every source node maps to exactly one output node, internal refs
+ * are inlined, and a ref that would recurse becomes a ref into the definitions.
+ */
+import type { OpenApiDocument } from "../types.ts";
+/**
+ * Where a discriminated union of refs records the tag values of each branch, by branch index, so
+ * `normalizeSchema` can pin each branch's tag once the refs are inlined and their names are gone.
+ */
+export declare const DISCRIMINATOR_KEY = "x-testing-discriminator";
+/**
+ * What an internal ref that points at nothing reads as: an empty node naming the pointer. As a
+ * schema it is unconstrained (`normalizeSchema` drops the key); anywhere else the model leaves the
+ * operation that holds it untested.
+ */
+export declare const DANGLING_KEY = "x-testing-dangling";
+/** The tag property of a discriminated union, and the values that name each branch. */
+export interface Discriminated {
+    propertyName: string;
+    values: string[][];
+}
+/** One dereference in progress. */
+export interface Dereferencing {
+    doc: OpenApiDocument;
+    /** External refs met, reported by the caller as a coverage gap. */
+    externalRefs: Set<string>;
+    /** Internal refs that point at nothing, each read as a `DANGLING_KEY` node. */
+    danglingRefs: Set<string>;
+    /** source object → its resolved output, so a node is resolved once wherever it is reached */
+    memo: Map<object, unknown>;
+    /** source nodes whose output is still being built: reaching one again is a cycle, whether it
+     * was entered through a $ref or walked directly as part of `components` */
+    building: Set<object>;
+    /** Each recursive ref, by the definition name it is stored under. */
+    defNames: Map<string, string>;
+}
+/**
+ * `mode` says what the node is: ordinary document structure, or an Example Object, whose `value`
+ * is data. Data (an `example`, a schema's `examples` array) is copied, never walked.
+ */
+type Mode = "node" | "example";
+export declare function walk(ctx: Dereferencing, node: unknown, mode?: Mode): unknown;
+export {};
+//# sourceMappingURL=walk.d.ts.map

package/dist/api/spec/load/walk.js

@@ -0,0 +1,162 @@
+/**
+ * The walk `dereference` runs: every source node maps to exactly one output node, internal refs
+ * are inlined, and a ref that would recurse becomes a ref into the definitions.
+ */
+import { DEFS_ID } from "./defs.js";
+import { decodeSegment, resolvePointer } from "./pointer.js";
+/**
+ * Where a discriminated union of refs records the tag values of each branch, by branch index, so
+ * `normalizeSchema` can pin each branch's tag once the refs are inlined and their names are gone.
+ */
+export const DISCRIMINATOR_KEY = "x-testing-discriminator";
+/**
+ * What an internal ref that points at nothing reads as: an empty node naming the pointer. As a
+ * schema it is unconstrained (`normalizeSchema` drops the key); anywhere else the model leaves the
+ * operation that holds it untested.
+ */
+export const DANGLING_KEY = "x-testing-dangling";
+export function walk(ctx, node, mode = "node") {
+    if (node === null || typeof node !== "object")
+        return node;
+    const cached = mode === "node" ? ctx.memo.get(node) : undefined;
+    if (cached !== undefined)
+        return cached;
+    if (Array.isArray(node))
+        return walkArray(ctx, node);
+    const obj = node;
+    /* Not memoized by node: whether a ref recurses depends on the path that reached it. */
+    if (typeof obj.$ref === "string")
+        return walkRef(ctx, obj, obj.$ref);
+    return walkObject(ctx, obj, mode);
+}
+function walkArray(ctx, node) {
+    const out = [];
+    ctx.memo.set(node, out);
+    ctx.building.add(node);
+    for (const item of node)
+        out.push(walk(ctx, item));
+    ctx.building.delete(node);
+    return out;
+}
+function walkObject(ctx, obj, mode) {
+    const out = {};
+    if (mode === "node")
+        ctx.memo.set(obj, out);
+    ctx.building.add(obj);
+    for (const [key, value] of Object.entries(obj))
+        out[key] = walkEntry(ctx, key, value, mode);
+    const tags = mode === "node" ? discriminated(ctx, obj) : undefined;
+    if (tags !== undefined)
+        out[DISCRIMINATOR_KEY] = tags;
+    ctx.building.delete(obj);
+    return out;
+}
+function walkEntry(ctx, key, value, mode) {
+    if (key === "example" || (mode === "example" && key === "value"))
+        return value;
+    if (key === "examples" && Array.isArray(value))
+        return value;
+    if (key === "examples" && value !== null && typeof value === "object") {
+        /* A map of Example Objects: each may be a $ref, and each one's `value` is data. */
+        const examples = {};
+        for (const [name, example] of Object.entries(value))
+            examples[name] = walk(ctx, example, "example");
+        return examples;
+    }
+    return walk(ctx, value);
+}
+function walkRef(ctx, obj, ref) {
+    if (ref !== "#" && !ref.startsWith("#/")) {
+        ctx.externalRefs.add(ref);
+        return obj;
+    }
+    const target = resolvePointer(ctx.doc, ref);
+    if (target !== null && typeof target === "object" && ctx.building.has(target)) {
+        return { $ref: `${DEFS_ID}#/$defs/${defName(ctx, ref)}` };
+    }
+    if (target === undefined)
+        ctx.danglingRefs.add(ref);
+    const resolved = target === undefined ? { [DANGLING_KEY]: ref } : walk(ctx, target);
+    const siblings = Object.entries(obj).filter(([key]) => key !== "$ref");
+    if (siblings.length === 0)
+        return resolved;
+    const base = resolved !== null && typeof resolved === "object" && !Array.isArray(resolved) ? resolved : {};
+    const out = { ...base };
+    for (const [key, value] of siblings)
+        out[key] = walk(ctx, value);
+    return out;
+}
+function defName(ctx, ref) {
+    const existing = ctx.defNames.get(ref);
+    if (existing !== undefined)
+        return existing;
+    /* `split` always yields at least one segment. */
+    const base = (decodeSegment(ref.split("/").at(-1)) || "schema").replace(/[^\w.-]/g, "_");
+    const taken = new Set(ctx.defNames.values());
+    let name = base;
+    for (let n = 2; taken.has(name); n++)
+        name = `${base}_${n}`;
+    ctx.defNames.set(ref, name);
+    return name;
+}
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isSchema = (value) => isRecord(value);
+/** An OpenAPI Discriminator Object: the property naming a union's branch, and its value mapping. */
+const isDiscriminator = (value) => value !== null && typeof value === "object" && "propertyName" in value && typeof value.propertyName === "string";
+const COMPONENT = /^#\/components\/schemas\/([^/]+)$/;
+/**
+ * The tag values of each branch of a `oneOf` / `anyOf` of internal refs beside a `discriminator`:
+ * the `mapping` values that reach the branch's schema, or else its component name. A branch is
+ * matched by the source node both refs end at, however each is spelled. Nothing is recorded when
+ * any branch is not such a ref or has no value, since a union only partly pinned is not narrower.
+ */
+function discriminated(ctx, obj) {
+    const { discriminator } = obj;
+    const union = obj.oneOf ?? obj.anyOf;
+    if (!isDiscriminator(discriminator) || !Array.isArray(union))
+        return undefined;
+    const mapped = mappingTargets(ctx, discriminator.mapping);
+    const values = [];
+    for (const branch of union) {
+        const ref = isSchema(branch) && typeof branch.$ref === "string" ? branch.$ref : "";
+        const target = ref.startsWith("#/") ? finalTarget(ctx, ref) : undefined;
+        /* A mapped node is never undefined, so a branch that reaches nothing matches no value. */
+        const own = mapped.filter(([, node]) => node === target).map(([value]) => value);
+        const name = COMPONENT.exec(ref)?.[1];
+        const named = own.length > 0 ? own : name === undefined ? [] : [decodeSegment(name)];
+        if (named.length === 0)
+            return undefined;
+        values.push(named);
+    }
+    return { propertyName: discriminator.propertyName, values };
+}
+/** Each mapping value with the node it reaches: a pointer, or a schema name under `components`. */
+function mappingTargets(ctx, mapping) {
+    if (!isRecord(mapping))
+        return [];
+    const schemas = ctx.doc.components?.schemas ?? {};
+    const out = [];
+    for (const [value, ref] of Object.entries(mapping)) {
+        if (typeof ref !== "string")
+            continue;
+        const pointer = ref.startsWith("#") ? ref : Object.hasOwn(schemas, ref) ? `#/components/schemas/${ref}` : "";
+        const target = pointer === "" ? undefined : finalTarget(ctx, pointer);
+        if (target !== undefined)
+            out.push([value, target]);
+    }
+    return out;
+}
+/** The node a chain of internal refs ends at, or `undefined` when it ends nowhere or loops. */
+function finalTarget(ctx, ref) {
+    const seen = new Set();
+    let pointer = ref;
+    while (!seen.has(pointer)) {
+        seen.add(pointer);
+        const node = resolvePointer(ctx.doc, pointer);
+        if (!isSchema(node) || typeof node.$ref !== "string" || !node.$ref.startsWith("#"))
+            return node;
+        pointer = node.$ref;
+    }
+    return undefined;
+}
+//# sourceMappingURL=walk.js.map

package/dist/api/spec/methods.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The HTTP methods a document can declare, and every set the API tester reads them by. A list of methods
+ * written anywhere else drifts: one module once missed QUERY, another counted OPTIONS as a write.
+ */
+/** The operation fields of an OAS 3.2 Path Item, in the order the specification lists them. */
+export declare const PATH_ITEM_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace", "query"];
+/** A method as a path item names it. */
+export type HttpMethod = (typeof PATH_ITEM_METHODS)[number];
+/** RFC 9110 §9.2.1, with QUERY (the safe method with a body): asking changes nothing on the server. */
+export declare const SAFE_METHODS: readonly ["GET", "HEAD", "OPTIONS", "TRACE", "QUERY"];
+/** A method that cannot change server state. */
+export type SafeMethod = (typeof SAFE_METHODS)[number];
+export declare const SAFE: ReadonlySet<string>;
+/** RFC 9110 §9.2.2: sending one twice does what sending it once does. */
+export declare const IDEMPOTENT: ReadonlySet<string>;
+/** Every declarable method that is not safe: what may change state. */
+export declare const MUTATING: ReadonlySet<string>;
+/** The safe method that carries its question in a body. */
+export declare const BODY_READS: ReadonlySet<string>;
+/**
+ * Methods that read the target's representation. OPTIONS asks what the target supports and TRACE
+ * echoes the request, so neither shows a record's state.
+ */
+export declare const READS: ReadonlySet<string>;
+/** The reads with no body: one may be sent again as it was, since there is no body stream to replay. */
+export declare const BODILESS_READS: ReadonlySet<string>;
+/** Methods the API tester lists but never sends, with the reason. */
+export declare const UNSENDABLE: ReadonlyMap<string, string>;
+/** Why `method` is never sent, or `null` when it can be. */
+export declare function unsendableReason(method: string): string | null;
+//# sourceMappingURL=methods.d.ts.map

package/dist/api/spec/methods.js

@@ -0,0 +1,37 @@
+/**
+ * The HTTP methods a document can declare, and every set the API tester reads them by. A list of methods
+ * written anywhere else drifts: one module once missed QUERY, another counted OPTIONS as a write.
+ */
+/** The operation fields of an OAS 3.2 Path Item, in the order the specification lists them. */
+export const PATH_ITEM_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace", "query"];
+/** RFC 9110 §9.2.1, with QUERY (the safe method with a body): asking changes nothing on the server. */
+export const SAFE_METHODS = ["GET", "HEAD", "OPTIONS", "TRACE", "QUERY"];
+export const SAFE = /* @__PURE__ */ new Set(SAFE_METHODS);
+/** RFC 9110 §9.2.2: sending one twice does what sending it once does. */
+export const IDEMPOTENT = /* @__PURE__ */ new Set([...SAFE_METHODS, "PUT", "DELETE"]);
+/** Every declarable method that is not safe: what may change state. */
+export const MUTATING = /* @__PURE__ */ new Set(
+/* @__PURE__ */ PATH_ITEM_METHODS.map((method) => method.toUpperCase()).filter((method) => !SAFE.has(method)));
+/** The safe method that carries its question in a body. */
+export const BODY_READS = /* @__PURE__ */ new Set(["QUERY"]);
+/**
+ * Methods that read the target's representation. OPTIONS asks what the target supports and TRACE
+ * echoes the request, so neither shows a record's state.
+ */
+export const READS = /* @__PURE__ */ new Set(
+/* @__PURE__ */ SAFE_METHODS.filter((method) => method !== "OPTIONS" && method !== "TRACE"));
+/** The reads with no body: one may be sent again as it was, since there is no body stream to replay. */
+export const BODILESS_READS = /* @__PURE__ */ new Set(
+/* @__PURE__ */ [...READS].filter((method) => !BODY_READS.has(method)));
+/** Methods the API tester lists but never sends, with the reason. */
+export const UNSENDABLE = /* @__PURE__ */ new Map([
+    [
+        "TRACE",
+        "fetch refuses TRACE (a cross-site tracing guard), so the API tester lists the operation but never sends it",
+    ],
+]);
+/** Why `method` is never sent, or `null` when it can be. */
+export function unsendableReason(method) {
+    return UNSENDABLE.get(method.toUpperCase()) ?? null;
+}
+//# sourceMappingURL=methods.js.map

package/dist/api/spec/operation-name.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How the API tester names an operation, and how config names one back.
+ *
+ * An operation is named by its `operationId`, or, when the document gives it none, `METHOD /path`
+ * with the method uppercased. Config may write that method in any case, but the path must be one
+ * of the document's path templates exactly, and an operation with an `operationId` answers to that
+ * id alone. `ops`, `allow` and `overlay.operations` all resolve through here, so they cannot
+ * disagree about what a name means.
+ */
+/** The name of the operation at `method` and `path`. */
+export declare function operationName(method: string, path: string, operationId: string | undefined): string;
+/** Where an operation sits in a document: its path item and the method under it. */
+export interface OperationSlot {
+    item: Record<string, unknown>;
+    method: string;
+}
+/** Each operation of a document's `paths`, by name. */
+export declare function operationSlots(paths: Readonly<Record<string, unknown>>): Map<string, OperationSlot>;
+/** The operation name in `names` that `ref` refers to, or `undefined` when it refers to none. */
+export declare function resolveOperationName(ref: string, names: {
+    has(name: string): boolean;
+}): string | undefined;
+//# sourceMappingURL=operation-name.d.ts.map