@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/conventions/infer.d.ts

@@ -0,0 +1,22 @@
+/** Grammars read off what a parameter's examples and description demonstrate. */
+import type { ParameterObject } from "../types.ts";
+import type { FilterGrammar, SelectGrammar, SortGrammar } from "./types.ts";
+/**
+ * Infers the filter grammar from the parameter's declared examples, which is where APIs
+ * describing a grammar almost always demonstrate it. Defaults to one-parameter-per-field
+ * equality — the assumption that holds for the widest range of APIs, and the one whose checks
+ * degrade most gracefully when wrong.
+ */
+export declare function inferGrammar(filter: ParameterObject | undefined): FilterGrammar;
+/**
+ * Infers the sort grammar from what the document demonstrates.
+ *
+ * Descriptions and examples are where an API shows its hand — `sort=-created_at` is unambiguous,
+ * and so is `field:desc`. Defaults to the dotted form, which is the most common and, being an
+ * unrecognized token rather than a wrong direction, fails loudly rather than silently sorting
+ * backwards when wrong.
+ */
+export declare function inferSortGrammar(order: ParameterObject | undefined): SortGrammar;
+/** Infers how a sparse fieldset is written. `fields[type]=` is JSON:API's and unmistakable. */
+export declare function inferSelectGrammar(select: ParameterObject | undefined): SelectGrammar;
+//# sourceMappingURL=infer.d.ts.map

package/dist/api/spec/conventions/infer.js

@@ -0,0 +1,59 @@
+/** Grammars read off what a parameter's examples and description demonstrate. */
+import { demonstrated } from "./roles.js";
+/**
+ * Infers the filter grammar from the parameter's declared examples, which is where APIs
+ * describing a grammar almost always demonstrate it. Defaults to one-parameter-per-field
+ * equality — the assumption that holds for the widest range of APIs, and the one whose checks
+ * degrade most gracefully when wrong.
+ */
+export function inferGrammar(filter) {
+    if (filter === undefined)
+        return "equality";
+    const text = demonstrated(filter);
+    /* Named outright in the description is the strongest signal — documents that describe a
+     * grammar almost always name it before demonstrating it. */
+    if (/postgrest/i.test(text))
+        return "postgrest";
+    if (/\b[\w.]+\.(eq|neq|gt|gte|lt|lte|like|ilike|in|nin|is|contains)\b/.test(text))
+        return "postgrest";
+    /* `field.op.value` written as a schema rather than an instance. */
+    if (/\bfield\.op\.value\b/i.test(text))
+        return "postgrest";
+    if (/\b[\w.]+=(eq|neq|gt|gte|lt|lte|like|in):/.test(text))
+        return "colon";
+    return "equality";
+}
+/**
+ * Infers the sort grammar from what the document demonstrates.
+ *
+ * Descriptions and examples are where an API shows its hand — `sort=-created_at` is unambiguous,
+ * and so is `field:desc`. Defaults to the dotted form, which is the most common and, being an
+ * unrecognized token rather than a wrong direction, fails loudly rather than silently sorting
+ * backwards when wrong.
+ */
+export function inferSortGrammar(order) {
+    if (order === undefined)
+        return "dotted";
+    const text = demonstrated(order);
+    if (/\b[\w.]+\.(asc|desc)\b/i.test(text))
+        return "dotted";
+    if (/\b[\w.]+:(asc|desc)\b/i.test(text))
+        return "colon";
+    if (/\b[\w.]+\s+(asc|desc)\b/i.test(text))
+        return "spaced";
+    /* A leading minus is the JSON:API convention; the "-" must precede a field name, not merely
+     * appear in prose, so the match is anchored to a token boundary. */
+    if (/(^|[\s,="'])-[a-z_][\w.]*/i.test(text))
+        return "prefixed";
+    return "dotted";
+}
+/** Infers how a sparse fieldset is written. `fields[type]=` is JSON:API's and unmistakable. */
+export function inferSelectGrammar(select) {
+    if (select === undefined)
+        return "csv";
+    if (/\[[^\]]+\]$/.test(select.name))
+        return "bracketed";
+    const description = typeof select.description === "string" ? select.description : "";
+    return /fields\[[^\]]+\]/.test(description) ? "bracketed" : "csv";
+}
+//# sourceMappingURL=infer.js.map

package/dist/api/spec/conventions/query-params.d.ts

@@ -0,0 +1,27 @@
+/** The query parameter names `x-query.params` or config `query.params` give each role. */
+import type { QueryParamNames, QueryParamRole } from "../../config/types/query.ts";
+import type { NamedRoles, Role } from "./roles.ts";
+/** The role each public name stands for; the public vocabulary says `sort`, the conventions `order`. */
+export declare const ROLE_OF: Readonly<Record<QueryParamRole, Role>>;
+/** The role names a `params` object may hold, for the message that lists them. */
+export declare const QUERY_PARAM_ROLES: QueryParamRole[];
+export declare function isQueryParamRole(key: string): key is QueryParamRole;
+/** The public name of a role, as a message to the author says it. */
+export declare function publicRole(role: Role): QueryParamRole;
+/**
+ * The known roles of a raw `params` object that name a parameter. `x-query`'s validation records a
+ * gap for everything else; this keeps what can be used.
+ */
+export declare function readQueryParams(raw: unknown): QueryParamNames | undefined;
+export declare function toNamedRoles(params: QueryParamNames): NamedRoles;
+/**
+ * The names an operation uses: its `x-query.params`, with config's laid over them. A config name the
+ * operation does not declare is not applied to it; config is run-wide, and the operation it was
+ * written for declares it.
+ */
+export declare function mergeQueryParams(sources: {
+    tag: unknown;
+    config?: QueryParamNames | undefined;
+    declared: readonly string[];
+}): QueryParamNames;
+//# sourceMappingURL=query-params.d.ts.map

package/dist/api/spec/conventions/query-params.js

@@ -0,0 +1,44 @@
+/** The query parameter names `x-query.params` or config `query.params` give each role. */
+/** The role each public name stands for; the public vocabulary says `sort`, the conventions `order`. */
+export const ROLE_OF = {
+    filter: "filter",
+    sort: "order",
+    select: "select",
+    search: "search",
+    searchMode: "searchMode",
+    limit: "limit",
+    page: "page",
+    offset: "offset",
+    cursor: "cursor",
+};
+/** The role names a `params` object may hold, for the message that lists them. */
+export const QUERY_PARAM_ROLES = /* @__PURE__ */ Object.keys(ROLE_OF);
+export function isQueryParamRole(key) {
+    return Object.hasOwn(ROLE_OF, key);
+}
+/** The public name of a role, as a message to the author says it. */
+export function publicRole(role) {
+    return role === "order" ? "sort" : role;
+}
+/**
+ * The known roles of a raw `params` object that name a parameter. `x-query`'s validation records a
+ * gap for everything else; this keeps what can be used.
+ */
+export function readQueryParams(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    return Object.fromEntries(Object.entries(raw).filter(([role, name]) => isQueryParamRole(role) && typeof name === "string" && name !== ""));
+}
+export function toNamedRoles(params) {
+    return Object.fromEntries(Object.entries(params).map(([role, name]) => [ROLE_OF[role], name]));
+}
+/**
+ * The names an operation uses: its `x-query.params`, with config's laid over them. A config name the
+ * operation does not declare is not applied to it; config is run-wide, and the operation it was
+ * written for declares it.
+ */
+export function mergeQueryParams(sources) {
+    const applied = Object.entries(sources.config ?? {}).filter(([, name]) => sources.declared.includes(name));
+    return { ...readQueryParams(sources.tag), ...Object.fromEntries(applied) };
+}
+//# sourceMappingURL=query-params.js.map

package/dist/api/spec/conventions/roles.d.ts

@@ -0,0 +1,28 @@
+/** Which query parameter plays which role, by the aliases real APIs use and the schema they declare. */
+import type { ParameterObject, JsonSchema } from "../types.ts";
+export type Role = "filter" | "order" | "select" | "search" | "searchMode" | "limit" | "page" | "offset" | "cursor";
+export declare function schemaOf(parameter: ParameterObject): JsonSchema;
+/** What the document shows of a parameter's values: its examples, then its description. */
+export declare function demonstrated(parameter: ParameterObject): string;
+/** Whether `role`'s alias list finds a parameter called `name`. */
+export declare function isAliasOf(name: string, role: Role): boolean;
+/** A parameter name per role, as `x-query.params` or config names them. */
+export type NamedRoles = Partial<Record<Role, string>>;
+export interface ResolvedRoles {
+    /** The parameter playing each role the operation has. */
+    roles: Partial<Record<Role, string>>;
+    /** Names given for a role that the operation declares no parameter by. */
+    unmatched: Array<{
+        role: Role;
+        name: string;
+    }>;
+}
+/**
+ * The parameter playing each role: the one a name points at when the operation declares it, else
+ * the first alias of the role among the parameters no name has claimed. A name the author gave is
+ * trusted as given; the guards the aliases need are for parameters nobody named.
+ */
+export declare function resolveRoles(query: readonly ParameterObject[], named: NamedRoles): ResolvedRoles;
+/** The first query parameter called `name`. */
+export declare function parameterNamed(query: readonly ParameterObject[], name: string | undefined): ParameterObject | undefined;
+//# sourceMappingURL=roles.d.ts.map

package/dist/api/spec/conventions/roles.js

@@ -0,0 +1,153 @@
+/** Which query parameter plays which role, by the aliases real APIs use and the schema they declare. */
+import { scalarKinds } from "../schema.js";
+/*
+ * Aliases seen across real APIs. Order matters only for readability; a parameter is matched
+ * case-insensitively and with separators normalized, so `perPage`, `per_page` and `PerPage` are
+ * one entry.
+ */
+const ALIASES = {
+    cursor: ["cursor", "after", "starting_after", "next", "page_token", "continuation"],
+    filter: ["filter", "where", "query", "conditions"],
+    limit: ["limit", "per_page", "page_size", "pagesize", "count", "max_results", "top", "size"],
+    offset: ["offset", "skip", "start", "from"],
+    order: ["order", "order_by", "sort", "sort_by", "ordering"],
+    searchMode: ["search_mode", "searchmode", "search_type", "mode"],
+    page: ["page", "page_number", "pagenum", "p"],
+    search: ["q", "search", "query_text", "term", "keyword", "text", "search_term", "searchterm"],
+    select: ["select", "fields", "field", "include_fields", "projection", "only"],
+};
+function normalize(name) {
+    return (name
+        /* A bracketed suffix is a *value* carried in the parameter name — `fields[articles]`,
+         * `filter[status]` — not part of the role's name. Matching the whole string against the
+         * alias list would fail to recognize the role at all, and the check that needed it would
+         * report itself inapplicable against an API that plainly supports it. */
+        .replace(/\[[^\]]*\]$/, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/[-\s]/g, "_"));
+}
+export function schemaOf(parameter) {
+    return parameter.schema ?? {};
+}
+/** What the document shows of a parameter's values: its examples, then its description. */
+export function demonstrated(parameter) {
+    const schema = schemaOf(parameter);
+    return [
+        ...(Array.isArray(schema.examples) ? schema.examples : []),
+        ...(schema.example === undefined ? [] : [schema.example]),
+        ...(typeof parameter.description === "string" ? [parameter.description] : []),
+    ]
+        .filter((value) => typeof value === "string")
+        .join(" ");
+}
+/* `key:value`, `key1:value2`, `key: value` — the spelling a document uses to say it takes pairs. */
+const KEY_VALUE = /\bkey\w*\s*:\s*value\w*/i;
+/**
+ * Whether a parameter's own declaration says it takes structured input rather than free text: a
+ * scalar that is not a string, a `pattern` with a `:` in it, or examples or a description that spell
+ * out `key:value`. Keycloak names its attribute query `q` and describes it as
+ * `'key1:value2 key2:value2'`; a search probe sent there tests a grammar nobody wrote, and an empty
+ * answer to it reads as a backend whose search is broken. Kept this narrow on purpose: a colon in
+ * an example (`role:admin`) or the word "attribute" alone can belong to free text.
+ */
+function takesStructuredInput(parameter) {
+    const schema = schemaOf(parameter);
+    const kinds = scalarKinds(schema);
+    if (kinds !== undefined && !kinds.includes("string"))
+        return true;
+    if (typeof schema.pattern === "string" && schema.pattern.includes(":"))
+        return true;
+    return KEY_VALUE.test(demonstrated(parameter));
+}
+/** Whether `role`'s alias list finds a parameter called `name`. */
+export function isAliasOf(name, role) {
+    return ALIASES[role].includes(normalize(name));
+}
+/**
+ * The name of the first query parameter whose name is an alias of `role`. A search alias that
+ * takes structured input is passed over: free text is the one thing a search check sends.
+ */
+function aliasName(query, role) {
+    return query.find((p) => isAliasOf(p.name, role) && (role !== "search" || !takesStructuredInput(p)))?.name;
+}
+/* The roles matched by alias alone, in the order they claim parameters. */
+const ALIASED = ["filter", "order", "select", "search", "searchMode", "cursor"];
+/**
+ * The parameter playing each role: the one a name points at when the operation declares it, else
+ * the first alias of the role among the parameters no name has claimed. A name the author gave is
+ * trusted as given; the guards the aliases need are for parameters nobody named.
+ */
+export function resolveRoles(query, named) {
+    const roles = {};
+    const unmatched = [];
+    for (const [role, name] of Object.entries(named)) {
+        if (query.some((p) => p.name === name))
+            roles[role] = name;
+        else
+            unmatched.push({ name, role });
+    }
+    const claimed = new Set(Object.values(roles));
+    const free = query.filter((p) => !claimed.has(p.name));
+    for (const role of ALIASED) {
+        /* A bare `mode` is too common to steal unless a search role is already present. */
+        if (roles[role] !== undefined || (role === "searchMode" && roles.search === undefined))
+            continue;
+        const name = aliasName(free, role);
+        if (name !== undefined)
+            roles[role] = name;
+    }
+    return { roles: { ...roles, ...resolvePagingRoles(free, roles) }, unmatched };
+}
+/** The first query parameter called `name`. */
+export function parameterNamed(query, name) {
+    return query.find((p) => p.name === name);
+}
+/**
+ * `limit` and `page` are both bare integers, and several APIs spell one of them with a word that
+ * belongs to the other's alias list — `count` most notoriously. The declared schema settles it:
+ * a page size is the one with an upper bound, a page number the one that starts at 1.
+ */
+function resolvePagingRoles(candidates, named) {
+    const roles = {};
+    for (const role of ["limit", "page", "offset"]) {
+        const name = named[role];
+        if (name !== undefined)
+            roles[role] = name;
+    }
+    for (const parameter of candidates) {
+        /* A page size or number is a number, however its nullability is spelled. */
+        const kinds = scalarKinds(schemaOf(parameter));
+        if (kinds === undefined || !kinds.every((kind) => kind === "integer" || kind === "number"))
+            continue;
+        const role = namedRole(parameter, roles) ?? shapedRole(schemaOf(parameter), roles);
+        if (role !== undefined)
+            roles[role] = parameter.name;
+    }
+    return roles;
+}
+/** The free role this parameter's name claims. */
+function namedRole(parameter, roles) {
+    const name = normalize(parameter.name);
+    const schema = schemaOf(parameter);
+    const hasMaximum = typeof schema.maximum === "number";
+    /* `count` is a page size only when it reads like one; otherwise it is a total. */
+    const sized = name !== "count" || hasMaximum || schema.default !== undefined;
+    if (roles.limit === undefined && ALIASES.limit.includes(name) && sized)
+        return "limit";
+    if (roles.page === undefined && ALIASES.page.includes(name) && !hasMaximum)
+        return "page";
+    if (roles.offset === undefined && ALIASES.offset.includes(name))
+        return "offset";
+    return undefined;
+}
+/** Unnamed but unmistakable: a bounded integer with a default is a page size, one starting at 1 a page. */
+function shapedRole(schema, roles) {
+    const hasMaximum = typeof schema.maximum === "number";
+    if (roles.limit === undefined && hasMaximum && schema.default !== undefined)
+        return "limit";
+    if (roles.page === undefined && schema.minimum === 1 && !hasMaximum)
+        return "page";
+    return undefined;
+}
+//# sourceMappingURL=roles.js.map

package/dist/api/spec/conventions/select.d.ts

@@ -0,0 +1,9 @@
+import type { QueryConventions } from "./types.ts";
+/**
+ * Renders a sparse fieldset, returning the parameter name alongside the value.
+ *
+ * JSON:API puts the resource type in the parameter name rather than the value, so the two cannot
+ * be chosen independently — which is why this returns a pair rather than a string.
+ */
+export declare function selectTerm(conventions: QueryConventions, fields: readonly string[], resource: string): Record<string, string> | null;
+//# sourceMappingURL=select.d.ts.map

package/dist/api/spec/conventions/select.js

@@ -0,0 +1,19 @@
+/**
+ * Renders a sparse fieldset, returning the parameter name alongside the value.
+ *
+ * JSON:API puts the resource type in the parameter name rather than the value, so the two cannot
+ * be chosen independently — which is why this returns a pair rather than a string.
+ */
+export function selectTerm(conventions, fields, resource) {
+    const parameter = conventions.select;
+    if (parameter === undefined)
+        return null;
+    const value = fields.join(",");
+    if (conventions.selectGrammar === "csv")
+        return { [parameter]: value };
+    /* Already bracketed in the document — `fields[articles]` — so the name is used verbatim.
+     * Otherwise the resource name is inserted, which is what the grammar requires. */
+    const name = /\[[^\]]+\]$/.test(parameter) ? parameter : `${parameter}[${resource}]`;
+    return { [name]: value };
+}
+//# sourceMappingURL=select.js.map

package/dist/api/spec/conventions/sort.d.ts

@@ -0,0 +1,14 @@
+/** Sort keys, written in whichever grammar the endpoint speaks. */
+import { type SortGrammarSpec, type SortKey, type SortValue } from "../render/sort.ts";
+import type { QueryConventions } from "./types.ts";
+/** How this endpoint's sort keys are spelled: its declared template, or its named grammar's preset. */
+export declare function sortSpec(conventions: QueryConventions): SortGrammarSpec;
+/** Renders a sort term in whichever grammar the endpoint speaks. */
+export declare function sortTerm(conventions: QueryConventions, key: SortKey): string;
+/** `null` when the grammar cannot write a nulls token. */
+export declare function sortTermWithNulls(conventions: QueryConventions, key: SortKey & {
+    nulls: "first" | "last";
+}): string | null;
+/** Several sort keys as one order value (a list, for a repeated grammar); `null` when it sorts by one key only. */
+export declare function sortKeys(conventions: QueryConventions, keys: readonly (readonly [string, "asc" | "desc"])[]): SortValue | null;
+//# sourceMappingURL=sort.d.ts.map

package/dist/api/spec/conventions/sort.js

@@ -0,0 +1,25 @@
+/** Sort keys, written in whichever grammar the endpoint speaks. */
+import { renderSortKey, renderSortKeys, SORT_PRESETS, } from "../render/sort.js";
+/** How this endpoint's sort keys are spelled: its declared template, or its named grammar's preset. */
+export function sortSpec(conventions) {
+    if (conventions.sortGrammar === "template") {
+        if (conventions.sortSpec === undefined)
+            throw new Error("a template sort grammar without its template");
+        return conventions.sortSpec;
+    }
+    return SORT_PRESETS[conventions.sortGrammar];
+}
+/** Renders a sort term in whichever grammar the endpoint speaks. */
+export function sortTerm(conventions, key) {
+    return renderSortKey(sortSpec(conventions), key);
+}
+/** `null` when the grammar cannot write a nulls token. */
+export function sortTermWithNulls(conventions, key) {
+    const spec = sortSpec(conventions);
+    return spec.nulls === undefined ? null : renderSortKey(spec, key);
+}
+/** Several sort keys as one order value (a list, for a repeated grammar); `null` when it sorts by one key only. */
+export function sortKeys(conventions, keys) {
+    return renderSortKeys(sortSpec(conventions), keys);
+}
+//# sourceMappingURL=sort.js.map

package/dist/api/spec/conventions/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * What a list endpoint's query parameters and response envelope *mean*, derived from the
+ * document rather than assumed.
+ *
+ * Checks used to match on literal names — `"filter"`, `"page"`, `envelope.hasMore` — which made
+ * roughly half of them fire only against APIs that happened to share the fixture's spelling.
+ * Everywhere else they were skipped, and skipped silently, so a quiet run on an unfamiliar API
+ * read exactly like a clean one.
+ *
+ * Names are matched against the aliases real APIs actually use, and the shape of the declared
+ * schema breaks ties. Anything still ambiguous is left `undefined` — the check then reports that
+ * it did not apply, and `x-query` can state the answer outright.
+ */
+import type { FilterGrammarSpec } from "../render/filter-types.ts";
+import type { SortGrammarSpec } from "../render/sort.ts";
+/** How filter values are spelled. Determines what the API tester can express, not merely what it sends. */
+export type FilterGrammar = 
+/** `field.op.value`, with `and(...)`/`or(...)` — PostgREST and friends. */
+"postgrest"
+/** `field=op:value`, e.g. `?price=gt:10`. */
+ | "colon"
+/** One parameter per field, equality only — `?status=active`. */
+ | "equality"
+/** Declared as a template; `QueryConventions.filterGrammar` says how terms are spelled. */
+ | "template"
+/** A filter expression the API tester could not recognize and nobody declared: no term can be written. */
+ | "unrecognized";
+/**
+ * How a sort direction is spelled.
+ *
+ * The role of the parameter and the *grammar* of its value are separate problems, and generalizing
+ * only the first is a half-measure: an API that names the parameter `sort` but expects `-name`
+ * receives `name.asc`, ignores or rejects it, and reads as a backend with broken sorting rather
+ * than one speaking a dialect the API tester cannot write.
+ */
+export type SortGrammar = 
+/** `field.asc` / `field.desc`, comma-separated — PostgREST. */
+"dotted"
+/** `-field` for descending, bare for ascending — JSON:API. */
+ | "prefixed"
+/** `field:asc` / `field:desc`. */
+ | "colon"
+/** `field asc` / `field desc`, as SQL writes it. */
+ | "spaced"
+/** Declared as a template; `QueryConventions.sortSpec` says how keys are spelled. */
+ | "template";
+/** How a sparse fieldset is spelled. */
+export type SelectGrammar = 
+/** `id,name` — comma-separated field names. */
+"csv"
+/** `fields[type]=id,name` — JSON:API's per-type bracket form. */
+ | "bracketed";
+export interface QueryConventions {
+    /** Parameter carrying a filter expression, when the endpoint has one. */
+    filter?: string;
+    /** Parameter selecting sort order. */
+    order?: string;
+    /** Parameter selecting a sparse fieldset. */
+    select?: string;
+    /** Free-text search parameter. */
+    search?: string;
+    /** Optional search-mode parameter (`keyword` / `semantic` / …). */
+    searchMode?: string;
+    /** Page-size parameter. */
+    limit?: string;
+    /** 1-based page number. */
+    page?: string;
+    /** Zero-based row offset, where the API pages by offset rather than page number. */
+    offset?: string;
+    /** Opaque forward cursor. */
+    cursor?: string;
+    grammar: FilterGrammar;
+    /** How terms are spelled under a declared template; the named grammars are presets. */
+    filterGrammar?: FilterGrammarSpec;
+    /**
+     * The filter grammar was declared (on `x-query` or in config), not inferred. Only then is a
+     * deliberately malformed request the API tester writes malformed on purpose rather than by a wrong guess.
+     */
+    grammarDeclared?: true;
+    /** How sort directions are written for the `order` parameter. */
+    sortGrammar: SortGrammar;
+    /** How sort keys are spelled under a declared template; the named grammars are presets. */
+    sortSpec?: SortGrammarSpec;
+    /** The sort grammar was declared, not inferred. */
+    sortDeclared?: true;
+    /** How a sparse fieldset is written for the `select` parameter. */
+    selectGrammar: SelectGrammar;
+    /**
+     * Response header carrying RFC 8288 pagination links, when the document declares one.
+     *
+     * Its presence changes how "are there more pages" is answered: under Link pagination the
+     * *absence* of `rel="next"` means no, so a response with no header at all is a definite
+     * "false" rather than an unknown. Without knowing the API publishes such a header, the two
+     * are indistinguishable and the check that asks has to stand down.
+     */
+    linkHeader?: string;
+    /** Where each is spelled in the response envelope, when the schema declares one. */
+    envelope: {
+        total?: string;
+        hasMore?: string;
+        nextCursor?: string;
+        page?: string;
+        limit?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/spec/conventions/types.js

@@ -0,0 +1,15 @@
+/**
+ * What a list endpoint's query parameters and response envelope *mean*, derived from the
+ * document rather than assumed.
+ *
+ * Checks used to match on literal names — `"filter"`, `"page"`, `envelope.hasMore` — which made
+ * roughly half of them fire only against APIs that happened to share the fixture's spelling.
+ * Everywhere else they were skipped, and skipped silently, so a quiet run on an unfamiliar API
+ * read exactly like a clean one.
+ *
+ * Names are matched against the aliases real APIs actually use, and the shape of the declared
+ * schema breaks ties. Anything still ambiguous is left `undefined` — the check then reports that
+ * it did not apply, and `x-query` can state the answer outright.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,4 @@
+/** The operations a document declares, each with its method, path and the parameters it inherits. */
+import type { Endpoint, OpenApiDocument } from "./types.ts";
+export declare function listEndpoints(doc: OpenApiDocument): Endpoint[];
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/api/spec/endpoints.js

@@ -0,0 +1,42 @@
+/** The operations a document declares, each with its method, path and the parameters it inherits. */
+import { PATH_ITEM_METHODS } from "./methods.js";
+import { operationName } from "./operation-name.js";
+export function listEndpoints(doc) {
+    const out = [];
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        if (item === null || typeof item !== "object")
+            continue;
+        for (const method of PATH_ITEM_METHODS) {
+            const op = item[method];
+            if (op === null || typeof op !== "object")
+                continue;
+            const operation = withPathParameters(op, item.parameters);
+            out.push({
+                method,
+                op: operation,
+                operationId: operationName(method, path, operation.operationId),
+                path,
+            });
+        }
+    }
+    return out;
+}
+function key(p) {
+    return `${String(p.in)}:${String(p.name)}`;
+}
+/**
+ * An operation with its path item's `parameters` folded in.
+ *
+ * A path item may declare parameters once for every operation under it, and an operation may
+ * override one by name and location. Reading only the operation's own list lost every shared
+ * path parameter, and with it the declared schema of each identifier.
+ */
+function withPathParameters(op, shared) {
+    if (!Array.isArray(shared) || shared.length === 0)
+        return op;
+    const own = op.parameters ?? [];
+    const overridden = new Set(own.map(key));
+    const inherited = shared.filter((parameter) => parameter !== null && typeof parameter === "object" && !overridden.has(key(parameter)));
+    return inherited.length === 0 ? op : { ...op, parameters: [...inherited, ...own] };
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/api/spec/extensions/async.d.ts

@@ -0,0 +1,24 @@
+/** `x-async` and `x-wait`: operations whose outcome arrives later, and how long to poll for it. */
+import type { OperationObject } from "../types.ts";
+export interface AsyncSpec {
+    poll: string;
+    idFrom?: string;
+    until?: string;
+    successWhen?: string;
+    timeoutMs: number;
+    pollIntervalMs: number;
+}
+export declare function readAsync(op: OperationObject): AsyncSpec | null;
+export interface WaitSpec {
+    operationId: string;
+    until?: string;
+    timeoutMs: number;
+    pollIntervalMs: number;
+}
+/**
+ * `x-wait: { operationId, until?, timeoutMs? }` — after this write, poll `operationId` until
+ * `until` (JSON path / pointer) is non-empty, or `hooks.awaitSideEffect` returns true.
+ * Default timeout 30s. Timeout is a finding, not a coverage gap.
+ */
+export declare function readWait(op: OperationObject): WaitSpec | null;
+//# sourceMappingURL=async.d.ts.map

package/dist/api/spec/extensions/async.js

@@ -0,0 +1,38 @@
+/** `x-async` and `x-wait`: operations whose outcome arrives later, and how long to poll for it. */
+import { extObject } from "./tag.js";
+export function readAsync(op) {
+    const tag = extObject(op, "x-async");
+    if (tag === undefined || typeof tag.poll !== "string")
+        return null;
+    const spec = {
+        poll: tag.poll,
+        pollIntervalMs: typeof tag.pollIntervalMs === "number" ? tag.pollIntervalMs : 2000,
+        timeoutMs: typeof tag.timeoutMs === "number" ? tag.timeoutMs : 120_000,
+    };
+    if (typeof tag.idFrom === "string")
+        spec.idFrom = tag.idFrom;
+    if (typeof tag.until === "string")
+        spec.until = tag.until;
+    if (typeof tag.successWhen === "string")
+        spec.successWhen = tag.successWhen;
+    return spec;
+}
+/**
+ * `x-wait: { operationId, until?, timeoutMs? }` — after this write, poll `operationId` until
+ * `until` (JSON path / pointer) is non-empty, or `hooks.awaitSideEffect` returns true.
+ * Default timeout 30s. Timeout is a finding, not a coverage gap.
+ */
+export function readWait(op) {
+    const tag = extObject(op, "x-wait");
+    if (tag === undefined || typeof tag.operationId !== "string" || tag.operationId === "")
+        return null;
+    const spec = {
+        operationId: tag.operationId,
+        pollIntervalMs: typeof tag.pollIntervalMs === "number" && tag.pollIntervalMs > 0 ? tag.pollIntervalMs : 1000,
+        timeoutMs: typeof tag.timeoutMs === "number" && tag.timeoutMs > 0 ? tag.timeoutMs : 30_000,
+    };
+    if (typeof tag.until === "string" && tag.until !== "")
+        spec.until = tag.until;
+    return spec;
+}
+//# sourceMappingURL=async.js.map