@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/graph/entities.js

@@ -0,0 +1,77 @@
+/** Entities gathered from the operations that name them, each with its lifecycle operations. */
+import { identityRank } from "./identity.js";
+/** Files every operation that names an entity and an action under that entity. */
+export function registerOperations(entities, operations) {
+    const identityRanks = new Map();
+    for (const op of operations) {
+        if (op.entity === null || op.action === null)
+            continue;
+        const entity = entityNamed(entities, op.entity);
+        /* Declared beats an item route, which beats a collection's guess: teardown deletes through the item route. */
+        if (op.identity !== null && identityRank(op.identitySource) > (identityRanks.get(entity.name) ?? -1)) {
+            entity.identity = op.identity;
+            identityRanks.set(entity.name, identityRank(op.identitySource));
+        }
+        adopt(entity, op);
+        assignAction(entity, op);
+    }
+}
+/** The entity called `name`, created empty the first time it is named. */
+export function entityNamed(entities, name) {
+    const existing = entities.get(name);
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        actions: [],
+        declaredSurface: [],
+        identity: null,
+        invite: null,
+        name,
+        readSurface: [],
+        tenantParams: [],
+        trackable: false,
+        unique: null,
+    };
+    entities.set(name, created);
+    return created;
+}
+/** Takes on what an operation says about its entity: tenancy, invites and unique sets. */
+function adopt(entity, op) {
+    if (op.tenantParam !== null && !entity.tenantParams.includes(op.tenantParam)) {
+        entity.tenantParams.push(op.tenantParam);
+    }
+    if (entity.invite === null && op.invite !== null)
+        entity.invite = op.invite;
+    if (op.unique !== null && (op.action === "create" || entity.unique === null))
+        entity.unique = op.unique;
+}
+function assignAction(entity, op) {
+    switch (op.action) {
+        case "create":
+            /* An invite POST looks like a collection create. Seeding it invents a grantee
+             * (usually a junk email) and the real invite check never runs. */
+            if (op.invite !== null)
+                break;
+            entity.create = op.operationId;
+            break;
+        case "list":
+            entity.list = op.operationId;
+            break;
+        case "read":
+            entity.reads ??= [];
+            if (!entity.reads.includes(op.operationId))
+                entity.reads.push(op.operationId);
+            entity.read ??= op.operationId;
+            break;
+        case "update":
+            entity.update = op.operationId;
+            break;
+        case "delete":
+            entity.delete = op.operationId;
+            break;
+        case "action":
+            entity.actions.push(op.operationId);
+            break;
+    }
+}
+//# sourceMappingURL=entities.js.map

package/dist/api/spec/graph/identity.d.ts

@@ -0,0 +1,19 @@
+/** Which property identifies an operation's records, and how sure the API tester is of it. */
+import type { JsonSchema } from "../types.ts";
+import type { OperationModel } from "./types.ts";
+type Identity = Pick<OperationModel, "identity" | "identitySource">;
+/**
+ * The identity `x-entity` declares, else the one the item route's parameter or the schema names.
+ * `pathParams` are the operation's path parameters in order; the last one names an item route
+ * when the path ends with it.
+ */
+/** An operation's path, and its path parameters in order. */
+export interface OperationRoute {
+    path: string;
+    pathParams: readonly string[];
+}
+export declare function operationIdentity(declared: string | undefined, itemSchema: JsonSchema | null, { path, pathParams }: OperationRoute): Identity;
+/** How much an operation's identity counts when an entity's operations disagree. */
+export declare function identityRank(source: OperationModel["identitySource"]): number;
+export {};
+//# sourceMappingURL=identity.d.ts.map

package/dist/api/spec/graph/identity.js

@@ -0,0 +1,14 @@
+/** Which property identifies an operation's records, and how sure the API tester is of it. */
+import { deriveIdentity } from "../collection/identity.js";
+export function operationIdentity(declared, itemSchema, { path, pathParams }) {
+    const lastParam = pathParams.at(-1);
+    const itemRoute = lastParam !== undefined && path.endsWith(`{${lastParam}}`);
+    const identity = declared ?? deriveIdentity(itemSchema, lastParam, itemRoute);
+    const identitySource = declared !== undefined ? "declared" : identity === null ? null : itemRoute ? "route" : "schema";
+    return { identity, identitySource };
+}
+/** How much an operation's identity counts when an entity's operations disagree. */
+export function identityRank(source) {
+    return source === "declared" ? 2 : source === "route" ? 1 : 0;
+}
+//# sourceMappingURL=identity.js.map

package/dist/api/spec/graph/naming.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One inferred name, two collections: `/projects/{id}/members` and `/orgs/{id}/members` both
+ * read as `member`, and fusing them would seed one through the other's routes. An entity is its
+ * collection's path template, so same-named collections under different parents are told apart
+ * by their parents: `project-member` and `org-member`. A tagged name is the author's and stays.
+ */
+import type { OperationModel } from "./types.ts";
+export declare function separateSameNamedCollections(operations: OperationModel[]): void;
+//# sourceMappingURL=naming.d.ts.map

package/dist/api/spec/graph/naming.js

@@ -0,0 +1,71 @@
+/**
+ * One inferred name, two collections: `/projects/{id}/members` and `/orgs/{id}/members` both
+ * read as `member`, and fusing them would seed one through the other's routes. An entity is its
+ * collection's path template, so same-named collections under different parents are told apart
+ * by their parents: `project-member` and `org-member`. A tagged name is the author's and stays.
+ */
+import { singularize } from "../extensions/entity.js";
+import { isParamSegment, segmentsOf, templateKey } from "./segments.js";
+export function separateSameNamedCollections(operations) {
+    const renamed = new Map();
+    for (const [name, byTemplate] of collectionTemplates(operations)) {
+        if (byTemplate.size < 2)
+            continue;
+        for (const [template, to] of distinctNames(name, byTemplate))
+            renamed.set(`${name}\u0000${template}`, to);
+    }
+    if (renamed.size === 0)
+        return;
+    for (const op of operations) {
+        const segments = heuristicTemplate(op);
+        if (segments === null)
+            continue;
+        const to = renamed.get(`${op.entity}\u0000${templateKey(segments)}`);
+        if (to !== undefined)
+            op.entity = to;
+    }
+}
+/** Each heuristic entity name, with the collection templates that carry it. */
+function collectionTemplates(operations) {
+    const templates = new Map();
+    for (const op of operations) {
+        const segments = heuristicTemplate(op);
+        if (segments === null)
+            continue;
+        const name = op.entity;
+        const byName = templates.get(name) ?? new Map();
+        byName.set(templateKey(segments), segments);
+        templates.set(name, byName);
+    }
+    return templates;
+}
+/** The collection an operation's heuristic entity name was read from, up to that segment. */
+function heuristicTemplate(op) {
+    if (op.entity === null || op.entitySource !== "heuristic")
+        return null;
+    const segments = segmentsOf(op.path);
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const segment = segments[i];
+        if (!isParamSegment(segment) && singularize(segment) === op.entity)
+            return segments.slice(0, i + 1);
+    }
+    return null;
+}
+/** Prefix ancestors until every collection of this name reads differently. */
+function distinctNames(name, byTemplate) {
+    for (let depth = 1;; depth++) {
+        const names = new Map();
+        for (const [template, segments] of byTemplate) {
+            const parents = segments
+                .slice(0, -1)
+                .filter((segment) => !isParamSegment(segment) && !/^v\d+$/i.test(segment))
+                .slice(-depth)
+                .map(singularize);
+            names.set(template, [...parents, name].join("-"));
+        }
+        const exhausted = [...byTemplate.values()].every((segments) => segments.slice(0, -1).filter((s) => !isParamSegment(s)).length <= depth);
+        if (new Set(names.values()).size === names.size || exhausted)
+            return names;
+    }
+}
+//# sourceMappingURL=naming.js.map

package/dist/api/spec/graph/operation.d.ts

@@ -0,0 +1,16 @@
+/** One operation read into the model: its tags, its contract, and what its query parameters mean. */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { Endpoint, OpenApiDocument } from "../types.ts";
+import type { QueryEnvelopeNames, QueryParamNames } from "../../config/types/query.ts";
+import type { OperationModel } from "./types.ts";
+/** What an operation is read against: its document, the gaps it records, and config's parameter and envelope names. */
+export interface ModelContext {
+    doc: OpenApiDocument;
+    gaps: GapCollector;
+    /** Config `query.params`, outranking `x-query.params`. */
+    queryParams?: QueryParamNames | undefined;
+    /** Config `query.envelope`, outranking `x-query.envelope`. */
+    queryEnvelope?: QueryEnvelopeNames | undefined;
+}
+export declare function modelOperation(endpoint: Endpoint, context: ModelContext): OperationModel;
+//# sourceMappingURL=operation.d.ts.map

package/dist/api/spec/graph/operation.js

@@ -0,0 +1,176 @@
+/** One operation read into the model: its tags, its contract, and what its query parameters mean. */
+import { ambiguousRows, deriveCollectionShape } from "../collection/shape.js";
+import { documentsEventStream, successSchema } from "../collection/responses.js";
+import { hasRequestBody, requestSchema } from "../collection/request.js";
+import { deriveQueryConventions } from "../conventions/derive.js";
+import { mergeEnvelopeNames } from "../conventions/envelope-names.js";
+import { mergeQueryParams } from "../conventions/query-params.js";
+import { pathParameterNames, readRootParams, readTenantParam, readTenantSource } from "../extensions/tenant.js";
+import { readAsync, readWait } from "../extensions/async.js";
+import { readCleanup, readInvalidate } from "../extensions/routes.js";
+import { readConsistency } from "../extensions/consistency.js";
+import { readCost, readFeatureGate, readFlag, readGenerated, readImmutable, readRateLimit, readSoftDelete, } from "../extensions/flags.js";
+import { readCreatedIdFrom, readEntity, readRecordPath } from "../extensions/entity.js";
+import { readEffects } from "../extensions/effects.js";
+import { readInvite } from "../extensions/invite.js";
+import { readPrivileged, requiredPrivileged } from "../extensions/privileged.js";
+import { readQueryCapability } from "../extensions/query-tag.js";
+import { ext, extObject } from "../extensions/tag.js";
+import { readUnique } from "../extensions/unique.js";
+import { MUTATING, unsendableReason } from "../methods.js";
+import { resolveSecurity } from "../security/requirements.js";
+import { validateTags } from "../tags/validate.js";
+import { operationIdentity } from "./identity.js";
+import { idempotencyHeader, readParamStyles, readRequiredCookies, readRequiredHeaders, readRequiredQuery, successResponseHeaders, } from "./parameters.js";
+import { isParamSegment, segmentsOf } from "./segments.js";
+import { readStatuses } from "./statuses.js";
+export function modelOperation(endpoint, context) {
+    const reading = readOperation(endpoint, context);
+    return { ...contractFacts(reading), ...behaviorFacts(reading), ...requestFacts(reading) };
+}
+function readOperation(endpoint, { doc, gaps, queryParams, queryEnvelope }) {
+    const { op, path, operationId } = endpoint;
+    const responseSchema = successSchema(op);
+    const recordPath = readRecordPath(endpoint);
+    const collection = deriveCollectionShape(responseSchema, recordPath);
+    reportAmbiguousRows(endpoint, { recordPath, schema: responseSchema }, gaps);
+    const bodySchema = requestSchema(op);
+    validateTags(op, operationId, gaps);
+    const entity = readEntity(endpoint, gaps);
+    const pathParams = pathParameterNames(path);
+    const itemSchema = collection?.itemSchema ?? responseSchema;
+    return {
+        bodySchema,
+        collection,
+        endpoint,
+        entity,
+        gaps,
+        identity: operationIdentity(entity?.identity, itemSchema, { path, pathParams }),
+        pathParams,
+        queryEnvelope,
+        queryParams,
+        recordPath,
+        security: readSecurity(endpoint, doc, gaps),
+        statuses: readStatuses(op.responses),
+    };
+}
+/* The operation's requirement, with a gap for each scheme whose scopes are not a list. */
+function readSecurity({ op, operationId }, doc, gaps) {
+    const security = resolveSecurity(op, doc);
+    for (const scheme of security.malformedScopes) {
+        gaps.record(operationId, "security", `security requirement "${scheme}" gives its scopes as something other than a list; the API tester reads it as no scopes`);
+    }
+    return security;
+}
+/** Only a listing has rows to name: a record that holds several arrays is just a record. */
+function reportAmbiguousRows(endpoint, { recordPath, schema }, gaps) {
+    const lastSegment = segmentsOf(endpoint.path).at(-1) ?? "";
+    const listing = endpoint.method.toUpperCase() === "GET" && !isParamSegment(lastSegment);
+    const ambiguous = recordPath === null && listing ? ambiguousRows(schema) : [];
+    if (ambiguous.length === 0)
+        return;
+    gaps.record(endpoint.operationId, "x-entity.recordPath", `the response holds several arrays of objects (${ambiguous.join(", ")}), so the API tester cannot tell which ` +
+        'are the rows; name them with x-entity.recordPath (e.g. "$.' +
+        `${ambiguous[0]}")`);
+}
+function contractFacts(reading) {
+    const { endpoint, gaps } = reading;
+    const { op } = endpoint;
+    return {
+        action: reading.entity?.action ?? null,
+        async: readAsync(op),
+        eventStream: documentsEventStream(op),
+        cleanup: readCleanup(op),
+        collection: reading.collection,
+        createdIdFrom: readCreatedIdFrom(endpoint),
+        recordPath: reading.recordPath,
+        cost: readCost(op),
+        featureGate: readFeatureGate(op),
+        unique: readUnique(op, endpoint.operationId, gaps),
+        destructive: readFlag(op, "x-destructive", true),
+        documentedStatuses: reading.statuses.exact,
+        statuses: reading.statuses,
+    };
+}
+function behaviorFacts(reading) {
+    const { endpoint, gaps } = reading;
+    const { op, operationId, path } = endpoint;
+    const effects = ext(op, "x-effects");
+    const method = endpoint.method.toUpperCase();
+    return {
+        consistency: readConsistency(op),
+        effects: readEffects(op, operationId, gaps),
+        noEffects: Array.isArray(effects) && effects.length === 0,
+        entity: reading.entity?.name ?? null,
+        entitySource: reading.entity?.source ?? null,
+        freshPrincipal: readFlag(op, "x-fresh-principal"),
+        generated: readGenerated(op, reading.bodySchema),
+        hasRequestBody: hasRequestBody(op),
+        ...reading.identity,
+        idempotent: readFlag(op, "x-idempotent"),
+        immutable: readImmutable(op),
+        invalidates: readInvalidate(op),
+        rateLimit: readRateLimit(op),
+        isMutation: MUTATING.has(method),
+        unsendable: unsendableReason(method),
+        method,
+        operationId,
+        path,
+        pathParams: reading.pathParams,
+        ...privilegedFacts(reading),
+    };
+}
+/* The request body properties marked x-privileged, and those of them the body requires. */
+function privilegedFacts(reading) {
+    const { bodySchema: body, endpoint, gaps } = reading;
+    const privileged = readPrivileged(endpoint.op, { body, gaps, operationId: endpoint.operationId });
+    return { privileged, privilegedRequired: requiredPrivileged(body, privileged) };
+}
+/** Whether a success response, by its code or the `2XX` range, declares an `ETag` header. */
+function declaresEtag(op) {
+    const responses = (op.responses ?? {});
+    return Object.entries(responses).some(([status, response]) => /^2(\d\d|XX)$/i.test(status) &&
+        Object.keys(response?.headers ?? {}).some((name) => name.toLowerCase() === "etag"));
+}
+function requestFacts(reading) {
+    const { endpoint, gaps, collection, queryParams, queryEnvelope } = reading;
+    const { op, operationId } = endpoint;
+    const parameters = op.parameters ?? [];
+    const declared = extObject(op, "x-query");
+    const queryParamNames = parameters.filter((p) => p.in === "query").map((p) => p.name);
+    const record = (message) => gaps.record(operationId, "x-query", message);
+    return {
+        query: collection === null ? null : readQueryCapability(endpoint, collection.itemSchema, { gaps, params: queryParams }),
+        /* A config name the operation does not declare is dropped before this, so an unmatched one is the tag's. */
+        conventions: deriveQueryConventions(parameters, collection, {
+            declared,
+            envelope: mergeEnvelopeNames({
+                config: queryEnvelope,
+                declared: collection?.envelopeKeys ?? [],
+                tag: declared?.envelope,
+            }),
+            onGuess: record,
+            onUnmatched: record,
+            params: mergeQueryParams({ config: queryParams, declared: queryParamNames, tag: declared?.params }),
+            responseHeaders: successResponseHeaders(op),
+        }),
+        queryParamNames,
+        requiredQuery: readRequiredQuery(parameters),
+        requiredHeaders: readRequiredHeaders(op),
+        requiredCookies: readRequiredCookies(parameters),
+        paramStyles: readParamStyles(parameters),
+        idempotencyHeader: idempotencyHeader(op),
+        etag: declaresEtag(op),
+        ifMatch: parameters.find((p) => p.in === "header" && p.name.toLowerCase() === "if-match")?.name ?? null,
+        rootParams: readRootParams(op),
+        route: `${endpoint.method.toUpperCase()} ${endpoint.path}`,
+        securitySchemes: [...new Set(reading.security.alternatives.flat().map((requirement) => requirement.scheme))],
+        security: reading.security,
+        softDelete: readSoftDelete(op),
+        invite: readInvite(op),
+        wait: readWait(op),
+        tenantParam: readTenantParam(endpoint, gaps),
+        tenantSource: readTenantSource(endpoint),
+    };
+}
+//# sourceMappingURL=operation.js.map

package/dist/api/spec/graph/paging.d.ts

@@ -0,0 +1,16 @@
+import type { OperationModel, SpecModel } from "./types.ts";
+/**
+ * The largest page a list operation documents, and the parameter that asks for it.
+ *
+ * `x-query`'s `maxLimit` first, then the page-size parameter's schema `maximum`, then a
+ * conventional 100 where the document states no bound. A request above the documented maximum is
+ * the caller breaking the contract, and a backend is right to refuse it. `param` is undefined when
+ * the operation has no page-size parameter at all — then no size can be asked for.
+ */
+export declare function documentedPage(model: SpecModel, op: OperationModel): {
+    param: string | undefined;
+    size: number;
+};
+/** The query that asks an operation for its largest documented page. */
+export declare function largestPageQuery(model: SpecModel, op: OperationModel): Record<string, number>;
+//# sourceMappingURL=paging.d.ts.map

package/dist/api/spec/graph/paging.js

@@ -0,0 +1,23 @@
+/**
+ * The largest page a list operation documents, and the parameter that asks for it.
+ *
+ * `x-query`'s `maxLimit` first, then the page-size parameter's schema `maximum`, then a
+ * conventional 100 where the document states no bound. A request above the documented maximum is
+ * the caller breaking the contract, and a backend is right to refuse it. `param` is undefined when
+ * the operation has no page-size parameter at all — then no size can be asked for.
+ */
+export function documentedPage(model, op) {
+    const param = op.conventions.limit;
+    if (op.query?.maxLimit !== undefined)
+        return { param, size: op.query.maxLimit };
+    const raw = model.rawOperations.get(op.operationId);
+    const declared = (raw?.parameters ?? []).find((candidate) => "name" in candidate && candidate.in === "query" && candidate.name === param);
+    const max = declared?.schema?.maximum;
+    return { param, size: typeof max === "number" && max >= 1 ? max : 100 };
+}
+/** The query that asks an operation for its largest documented page. */
+export function largestPageQuery(model, op) {
+    const { param, size } = documentedPage(model, op);
+    return param === undefined ? {} : { [param]: size };
+}
+//# sourceMappingURL=paging.js.map

package/dist/api/spec/graph/parameters.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What an operation's parameters promise a request: the values its required parameters declare, how
+ * each is written, and an idempotency key.
+ */
+import type { OperationObject, ParameterObject } from "../types.ts";
+/** Where a parameter goes. */
+export type ParamIn = ParameterObject["in"];
+/** How the document says to write a parameter: its OAS `style`, `explode` and `allowReserved`. */
+export interface ParamStyle {
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+/** Each parameter's non-default style, by location and name. */
+export type ParamStyles = Partial<Record<ParamIn, Record<string, ParamStyle>>>;
+/**
+ * Required query parameters and the value the document declares for each; an object or array is
+ * kept whole for its style to write. A parameter with no declared value is left to the caller,
+ * never invented.
+ */
+export declare function readRequiredQuery(parameters: readonly ParameterObject[]): Record<string, unknown>;
+/**
+ * Required header parameters and their declared values. Never the idempotency key, which the run
+ * mints per request, nor a header OAS ignores or a credential carries.
+ */
+export declare function readRequiredHeaders(op: OperationObject): Record<string, unknown>;
+/** Required cookie parameters and their declared values. */
+export declare function readRequiredCookies(parameters: readonly ParameterObject[]): Record<string, unknown>;
+/** Each parameter's style, explode and allowReserved where they differ from the OAS default. */
+export declare function readParamStyles(parameters: readonly ParameterObject[]): ParamStyles;
+/**
+ * The required query, header and cookie parameters a request cannot carry: the document declares no
+ * value for them, and the run supplies none itself (the idempotency key, a credential, a header OAS
+ * ignores). An operation with one cannot be sent whole, so its answer judges the request.
+ */
+export declare function unfilledRequired(op: OperationObject): string[];
+/** The header parameter `op` accepts as an idempotency key, when it declares one. */
+export declare function idempotencyHeader(op: OperationObject): string | null;
+/**
+ * Header names the operation's success response declares.
+ *
+ * Pagination facts do not always live in the body — `Link` is the obvious case — so a header the
+ * document publishes is part of the response contract and has to be read as such.
+ */
+export declare function successResponseHeaders(op: OperationObject): string[];
+//# sourceMappingURL=parameters.d.ts.map

package/dist/api/spec/graph/parameters.js

@@ -0,0 +1,119 @@
+/**
+ * What an operation's parameters promise a request: the values its required parameters declare, how
+ * each is written, and an idempotency key.
+ */
+import { CREDENTIAL_HEADERS } from "../../security/credential-names.js";
+/** The value a parameter's document gives it: an example first, then a const, enum, or default. */
+function declaredValue(param) {
+    const schema = param.schema ?? {};
+    const named = param["examples"];
+    const fromNamed = named !== null && typeof named === "object"
+        ? Object.values(named).find((entry) => entry?.value !== undefined)?.value
+        : undefined;
+    const listed = Array.isArray(schema["examples"]) ? schema["examples"][0] : undefined;
+    const enumerated = Array.isArray(schema["enum"]) ? schema["enum"][0] : undefined;
+    return [param["example"], fromNamed, listed, schema["example"], schema["const"], enumerated, schema["default"]].find((candidate) => candidate !== undefined && candidate !== null);
+}
+/* Required parameters in one location and the value the document declares for each, kept whole. */
+function readRequired(parameters, where) {
+    const out = {};
+    for (const param of parameters) {
+        if (param.in !== where || param.required !== true)
+            continue;
+        const value = declaredValue(param);
+        if (value !== undefined)
+            out[param.name] = value;
+    }
+    return out;
+}
+/**
+ * Required query parameters and the value the document declares for each; an object or array is
+ * kept whole for its style to write. A parameter with no declared value is left to the caller,
+ * never invented.
+ */
+export function readRequiredQuery(parameters) {
+    return readRequired(parameters, "query");
+}
+/* OAS 3.1 §4.8.12: a header parameter named Accept, Content-Type or Authorization is ignored. A
+ * credential header is the operation's security to send, never a parameter's example. */
+const IGNORED_HEADERS = /* @__PURE__ */ new Set(["accept", "content-type", ...CREDENTIAL_HEADERS]);
+/**
+ * Required header parameters and their declared values. Never the idempotency key, which the run
+ * mints per request, nor a header OAS ignores or a credential carries.
+ */
+export function readRequiredHeaders(op) {
+    const key = idempotencyHeader(op);
+    const all = readRequired(op.parameters ?? [], "header");
+    return Object.fromEntries(Object.entries(all).filter(([name]) => name !== key && !IGNORED_HEADERS.has(name.toLowerCase())));
+}
+/** Required cookie parameters and their declared values. */
+export function readRequiredCookies(parameters) {
+    return readRequired(parameters, "cookie");
+}
+/* What OAS writes a parameter as when it says nothing: form exploded in query and cookie, else simple. */
+const defaultStyle = (where) => (where === "query" || where === "cookie" ? "form" : "simple");
+/* The parts of `param`'s declared style that differ from its location's default, or null when none do. */
+function styleOf(param) {
+    const out = {};
+    const declared = typeof param["style"] === "string" ? param["style"] : undefined;
+    const style = declared ?? defaultStyle(param.in);
+    if (style !== defaultStyle(param.in))
+        out.style = style;
+    const explode = param["explode"];
+    if (typeof explode === "boolean" && explode !== (style === "form"))
+        out.explode = explode;
+    if (param["allowReserved"] === true)
+        out.allowReserved = true;
+    return Object.keys(out).length === 0 ? null : out;
+}
+/** Each parameter's style, explode and allowReserved where they differ from the OAS default. */
+export function readParamStyles(parameters) {
+    const out = {};
+    for (const param of parameters) {
+        const style = styleOf(param);
+        if (style !== null)
+            (out[param.in] ??= {})[param.name] = style;
+    }
+    return out;
+}
+/**
+ * The required query, header and cookie parameters a request cannot carry: the document declares no
+ * value for them, and the run supplies none itself (the idempotency key, a credential, a header OAS
+ * ignores). An operation with one cannot be sent whole, so its answer judges the request.
+ */
+export function unfilledRequired(op) {
+    const parameters = op.parameters ?? [];
+    const declared = {
+        cookie: readRequiredCookies(parameters),
+        header: readRequiredHeaders(op),
+        query: readRequiredQuery(parameters),
+    };
+    const key = idempotencyHeader(op);
+    const supplied = (name) => name === key || IGNORED_HEADERS.has(name.toLowerCase());
+    return parameters
+        .filter((param) => param.required === true && param.in !== "path")
+        .filter(({ in: where, name }) => !Object.hasOwn(declared[where], name) && !(where === "header" && supplied(name)))
+        .map(({ name }) => name);
+}
+/** The header parameter `op` accepts as an idempotency key, when it declares one. */
+export function idempotencyHeader(op) {
+    return ((op.parameters ?? []).find((p) => p.in === "header" && /^(x-)?idempotenc(y|e)([-_]?key)?$/i.test(p.name.replace(/\s/g, "")))?.name ?? null);
+}
+/**
+ * Header names the operation's success response declares.
+ *
+ * Pagination facts do not always live in the body — `Link` is the obvious case — so a header the
+ * document publishes is part of the response contract and has to be read as such.
+ */
+export function successResponseHeaders(op) {
+    const responses = (op.responses ?? {});
+    const names = new Set();
+    for (const [status, response] of Object.entries(responses)) {
+        if (!/^2\d\d$/.test(status))
+            continue;
+        for (const name of Object.keys(response?.headers ?? {}))
+            names.add(name);
+    }
+    return [...names];
+}
+//# sourceMappingURL=parameters.js.map

package/dist/api/spec/graph/resolver.d.ts

@@ -0,0 +1,25 @@
+import type { CacheBypass } from "../extensions/consistency.ts";
+import type { ParamStyles } from "./parameters.ts";
+import type { SpecModel } from "./types.ts";
+/** The documented operation a request instances, with the path parameters it carries. */
+export interface ResolvedOperation {
+    operationId: string;
+    template: string;
+    entity: string | null;
+    redirects: boolean;
+    requiredQuery: Record<string, unknown>;
+    requiredHeaders: Record<string, unknown>;
+    requiredCookies: Record<string, unknown>;
+    paramStyles: ParamStyles;
+    pathParams: Record<string, string>;
+    /** The `x-consistency` bypass the operation declares; null when it declares none. */
+    bypass: CacheBypass | null;
+}
+/**
+ * Maps a request (method + path below the base URL) to the documented operation it instances.
+ *
+ * Literal segments beat parameters where two templates match — `/tables/archived` is not
+ * `/tables/{id}` — so the most specific template wins.
+ */
+export declare function operationResolver(model: SpecModel): (method: string, relativePath: string) => ResolvedOperation | null;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/api/spec/graph/resolver.js

@@ -0,0 +1,38 @@
+import { pathTemplateParams } from "../routes.js";
+/**
+ * Maps a request (method + path below the base URL) to the documented operation it instances.
+ *
+ * Literal segments beat parameters where two templates match — `/tables/archived` is not
+ * `/tables/{id}` — so the most specific template wins.
+ */
+export function operationResolver(model) {
+    const candidates = [...model.operations].sort((a, b) => (a.path.match(/\{/g)?.length ?? 0) - (b.path.match(/\{/g)?.length ?? 0));
+    return (method, relativePath) => {
+        const verb = method.toUpperCase();
+        for (const op of candidates) {
+            if (op.method.toUpperCase() !== verb)
+                continue;
+            const pathParams = pathTemplateParams(op.path, relativePath);
+            if (pathParams !== null)
+                return resolvedTo(op, pathParams);
+        }
+        return null;
+    };
+}
+function resolvedTo(op, pathParams) {
+    /* A documented 3xx is the answer to grade, not a hop to follow. */
+    const redirects = op.statuses.exact.some((code) => code >= 300 && code < 400) || op.statuses.ranges.includes(3);
+    return {
+        bypass: op.consistency?.bypass ?? null,
+        entity: op.entity,
+        operationId: op.operationId,
+        pathParams,
+        paramStyles: op.paramStyles,
+        redirects,
+        requiredCookies: op.requiredCookies,
+        requiredHeaders: op.requiredHeaders,
+        requiredQuery: op.requiredQuery,
+        template: op.path,
+    };
+}
+//# sourceMappingURL=resolver.js.map