@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,18 @@
+/** `x-consistency`: how stale a read may be, and the request header that skips its cache. */
+import type { OperationObject } from "../types.ts";
+/** A request header that makes the read skip every cache: `x-fresh: 1`. Its name is lowercase. */
+export interface CacheBypass {
+    name: string;
+    value: string;
+}
+export interface ConsistencySpec {
+    /** How long after a write this read may still answer the old value; null when undeclared. */
+    stalenessMs: number | null;
+    bypass: CacheBypass | null;
+}
+/** `"<n>s"` in milliseconds; null for anything else. */
+export declare function readStaleness(value: unknown): number | null;
+/** `"<header>: <value>"`, split at the first colon; null without a name or a value. */
+export declare function readBypass(value: unknown): CacheBypass | null;
+export declare function readConsistency(op: OperationObject): ConsistencySpec | null;
+//# sourceMappingURL=consistency.d.ts.map

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

@@ -0,0 +1,27 @@
+/** `x-consistency`: how stale a read may be, and the request header that skips its cache. */
+import { extObject } from "./tag.js";
+const STALENESS = /^(\d+)s$/;
+/** `"<n>s"` in milliseconds; null for anything else. */
+export function readStaleness(value) {
+    const match = typeof value === "string" ? STALENESS.exec(value) : null;
+    return match === null ? null : Number(match[1]) * 1000;
+}
+/** `"<header>: <value>"`, split at the first colon; null without a name or a value. */
+export function readBypass(value) {
+    if (typeof value !== "string")
+        return null;
+    const colon = value.indexOf(":");
+    if (colon === -1)
+        return null;
+    const name = value.slice(0, colon).trim().toLowerCase();
+    const header = value.slice(colon + 1).trim();
+    return name === "" || header === "" ? null : { name, value: header };
+}
+export function readConsistency(op) {
+    const tag = extObject(op, "x-consistency");
+    if (tag === undefined)
+        return null;
+    const spec = { bypass: readBypass(tag.bypass), stalenessMs: readStaleness(tag.staleness) };
+    return spec.bypass === null && spec.stalenessMs === null ? null : spec;
+}
+//# sourceMappingURL=consistency.js.map

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

@@ -0,0 +1,13 @@
+/** `x-effects`: the records an operation adds, changes or removes, and how many. */
+import type { OperationObject } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+export interface EffectSpec {
+    entity: string;
+    op: "create" | "append" | "update" | "delete" | "replace";
+    /** Exact cardinality delta. Default `1` when both `count` and `min` are omitted. */
+    count?: number;
+    /** At-least cardinality (`delta >= min` and `added.length >= min`). Mutually exclusive with `count`. */
+    min?: number;
+}
+export declare function readEffects(op: OperationObject, operationId?: string, gaps?: GapCollector): EffectSpec[];
+//# sourceMappingURL=effects.d.ts.map

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

@@ -0,0 +1,36 @@
+/** `x-effects`: the records an operation adds, changes or removes, and how many. */
+import { isObject } from "../tags/checks.js";
+import { ext } from "./tag.js";
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const OPS = ["create", "append", "update", "delete", "replace"];
+const isOp = (value) => OPS.includes(value);
+/* One item as an effect, or none: what is wrong with it goes to `report`. */
+function effectOf(item, report) {
+    if (!isObject(item))
+        return undefined;
+    const rec = item;
+    if (typeof rec.entity !== "string" || typeof rec.op !== "string")
+        return undefined;
+    if (!isOp(rec.op)) {
+        report(`item for "${rec.entity}" has op "${rec.op}"; use ${OPS.slice(0, -1).join(", ")} or ${OPS.at(-1)}`);
+        return undefined;
+    }
+    const effect = { entity: rec.entity, op: rec.op };
+    if (finite(rec.count))
+        effect.count = rec.count;
+    if (finite(rec.min))
+        effect.min = rec.min;
+    if (effect.count !== undefined && effect.min !== undefined) {
+        report(`item for "${effect.entity}" sets both count and min; use exactly one`);
+        return undefined;
+    }
+    return effect;
+}
+export function readEffects(op, operationId, gaps) {
+    const raw = ext(op, "x-effects");
+    if (!Array.isArray(raw))
+        return [];
+    const report = (detail) => gaps?.record(operationId ?? "", "x-effects", detail);
+    return raw.flatMap((item) => effectOf(item, report) ?? []);
+}
+//# sourceMappingURL=effects.js.map

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

@@ -0,0 +1,28 @@
+/** `x-entity`: which entity an operation acts on and how, declared or read off its path. */
+import type { Endpoint } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+export declare const ENTITY_ACTIONS: readonly ["create", "list", "read", "update", "delete", "action"];
+export type EntityAction = (typeof ENTITY_ACTIONS)[number];
+/** The fields `x-entity` documents. */
+export interface EntityTag {
+    name: string;
+    action: EntityAction;
+    identity: string;
+    /** Where the answer keeps the record, or a list's rows. */
+    recordPath: string;
+    /** Where a create's answer puts the made record's id. */
+    createdIdFrom: string;
+}
+export interface EntityRef {
+    name: string;
+    action: EntityAction;
+    identity?: string;
+    source: "tag" | "heuristic";
+}
+export declare function singularize(word: string): string;
+export declare function readEntity(endpoint: Endpoint, gaps?: GapCollector): EntityRef | null;
+/** `x-entity.recordPath`: the JSON path where this operation's answer keeps the record (or a list's rows). */
+export declare function readRecordPath(endpoint: Endpoint): string | null;
+/** `x-entity.createdIdFrom`: the JSON path where a create's answer puts the made record's id. */
+export declare function readCreatedIdFrom(endpoint: Endpoint): string | null;
+//# sourceMappingURL=entity.d.ts.map

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

@@ -0,0 +1,103 @@
+/** `x-entity`: which entity an operation acts on and how, declared or read off its path. */
+import { extObject } from "./tag.js";
+export const ENTITY_ACTIONS = ["create", "list", "read", "update", "delete", "action"];
+const isEntityAction = (value) => ENTITY_ACTIONS.some((action) => action === value);
+const IRREGULAR_PLURALS = {
+    addresses: "address",
+    batches: "batch",
+    campuses: "campus",
+    categories: "category",
+    children: "child",
+    companies: "company",
+    entities: "entity",
+    inboxes: "inbox",
+    indices: "index",
+    people: "person",
+    properties: "property",
+    queries: "query",
+    statuses: "status",
+};
+/**
+ * Word endings that are not plural markers. Without these, `status` becomes `statu` and
+ * `analysis` becomes `analysi` — the kind of mangling that turns a readable report into one
+ * nobody trusts.
+ */
+const NON_PLURAL_ENDINGS = /(?:us|ss|is|os|as|ics|ews|ess|ous|sis)$/;
+export function singularize(word) {
+    const lower = word.toLowerCase();
+    const irregular = IRREGULAR_PLURALS[lower];
+    if (irregular !== undefined)
+        return irregular;
+    if (/(ches|shes|sses|xes|zes)$/.test(lower))
+        return lower.slice(0, -2);
+    if (/[^aeiou]ies$/.test(lower))
+        return `${lower.slice(0, -3)}y`;
+    if (NON_PLURAL_ENDINGS.test(lower))
+        return lower;
+    if (lower.endsWith("s"))
+        return lower.slice(0, -1);
+    return lower;
+}
+const PARAM_SEGMENT = /^\{[^}]+\}$/;
+export function readEntity(endpoint, gaps) {
+    const tag = extObject(endpoint.op, "x-entity");
+    if (typeof tag?.name === "string" && tag.name !== "" && isEntityAction(tag.action)) {
+        const ref = { action: tag.action, name: tag.name, source: "tag" };
+        if (typeof tag.identity === "string")
+            ref.identity = tag.identity;
+        return ref;
+    }
+    const inferred = inferEntity(endpoint);
+    if (inferred === null) {
+        gaps?.record(endpoint.operationId, "x-entity", `path "${endpoint.path}" does not follow /<plural>/{id}; entity could not be inferred, ` +
+            "so this operation gets no lifecycle coverage");
+        return null;
+    }
+    return inferred;
+}
+/** `x-entity.recordPath`: the JSON path where this operation's answer keeps the record (or a list's rows). */
+export function readRecordPath(endpoint) {
+    const path = extObject(endpoint.op, "x-entity")?.recordPath;
+    return typeof path === "string" && path !== "" ? path : null;
+}
+/** `x-entity.createdIdFrom`: the JSON path where a create's answer puts the made record's id. */
+export function readCreatedIdFrom(endpoint) {
+    const from = extObject(endpoint.op, "x-entity")?.createdIdFrom;
+    return typeof from === "string" && from !== "" ? from : null;
+}
+/** The CRUD action a method takes at collection or item scope; `null` for a method that has none. */
+function crudAction(method, itemScoped) {
+    if (method === "GET")
+        return itemScoped ? "read" : "list";
+    if (method === "POST")
+        return itemScoped ? "action" : "create";
+    if (method === "PUT" || method === "PATCH")
+        return "update";
+    if (method === "DELETE")
+        return "delete";
+    return null;
+}
+/**
+ * Heuristic: the last non-parameter segment names the collection; whether a parameter follows
+ * it decides collection-scope vs item-scope; the method then decides the action.
+ */
+function inferEntity(endpoint) {
+    const segments = endpoint.path.split("/").filter(Boolean);
+    const nounIndex = segments.findLastIndex((seg) => !PARAM_SEGMENT.test(seg));
+    if (nounIndex === -1)
+        return null;
+    /* Found by its index, so it is there. */
+    const noun = segments[nounIndex];
+    /* A version prefix is never an entity. */
+    if (/^v\d+$/i.test(noun))
+        return null;
+    /* Every segment after the noun is a parameter, so any segment there makes it item-scoped. */
+    const itemScoped = nounIndex < segments.length - 1;
+    const name = singularize(noun);
+    const method = endpoint.method.toUpperCase();
+    if (method !== "GET" && !itemScoped && method !== "POST")
+        return { action: "action", name, source: "heuristic" };
+    const action = crudAction(method, itemScoped);
+    return action === null ? null : { action, name, source: "heuristic" };
+}
+//# sourceMappingURL=entity.js.map

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

@@ -0,0 +1,30 @@
+/** Single-valued operation tags: soft delete, immutable and generated fields, cost, gates, flags, rate limits. */
+import type { OperationObject } from "../types.ts";
+export declare function readSoftDelete(op: OperationObject): string | null;
+export declare function readImmutable(op: OperationObject): string[];
+export declare function readGenerated(op: OperationObject, bodySchema: unknown): string[];
+export declare function readCost(op: OperationObject): "low" | "medium" | "high";
+/**
+ * `x-feature-gate: <string>` — the plan key this operation is sold behind.
+ *
+ * A matching 403 is the document talking, not a fixture failure. Anything other than a string
+ * (or a missing tag) is `null`, same defensive read as `readCost` / `readRateLimit`.
+ */
+export declare function readFeatureGate(op: OperationObject): string | null;
+/**
+ * A boolean tag. A malformed value is reported by `validateTags`; here it reads as `whenMalformed`
+ * — `x-destructive` passes `true`, so a typo never makes a destructive operation look safe.
+ */
+export declare function readFlag(op: OperationObject, key: string, whenMalformed?: boolean): boolean;
+export interface RateLimitTag {
+    category: string;
+    /** `null` when the tag names a category without a rate — still useful for grouping. */
+    rps: number | null;
+}
+/**
+ * `x-rate-limit: { category: string, rps?: number }` — read defensively, like every other tag,
+ * because the shape is the emitting app's policy to own, not the API tester's to assume. A category alone
+ * (no `rps`) still groups operations sharing one budget; a config-level rate can complete it.
+ */
+export declare function readRateLimit(op: OperationObject): RateLimitTag | null;
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1,59 @@
+/** Single-valued operation tags: soft delete, immutable and generated fields, cost, gates, flags, rate limits. */
+import { ext, extObject, strArray } from "./tag.js";
+export function readSoftDelete(op) {
+    const value = ext(op, "x-soft-delete");
+    return typeof value === "string" ? value : null;
+}
+export function readImmutable(op) {
+    return strArray(ext(op, "x-immutable"));
+}
+export function readGenerated(op, bodySchema) {
+    const declared = strArray(ext(op, "x-generated"));
+    if (declared.length > 0)
+        return declared;
+    /* `readOnly: true` carries the same meaning and is standard OpenAPI. */
+    if (bodySchema === null || typeof bodySchema !== "object")
+        return [];
+    const props = bodySchema.properties;
+    if (props === null || typeof props !== "object")
+        return [];
+    return Object.entries(props)
+        .filter(([, v]) => v !== null && typeof v === "object" && v.readOnly === true)
+        .map(([k]) => k);
+}
+export function readCost(op) {
+    const value = ext(op, "x-cost");
+    return value === "high" || value === "medium" ? value : "low";
+}
+/**
+ * `x-feature-gate: <string>` — the plan key this operation is sold behind.
+ *
+ * A matching 403 is the document talking, not a fixture failure. Anything other than a string
+ * (or a missing tag) is `null`, same defensive read as `readCost` / `readRateLimit`.
+ */
+export function readFeatureGate(op) {
+    const value = ext(op, "x-feature-gate");
+    return typeof value === "string" && value !== "" ? value : null;
+}
+/**
+ * A boolean tag. A malformed value is reported by `validateTags`; here it reads as `whenMalformed`
+ * — `x-destructive` passes `true`, so a typo never makes a destructive operation look safe.
+ */
+export function readFlag(op, key, whenMalformed = false) {
+    const value = ext(op, key);
+    if (value === undefined || typeof value === "boolean")
+        return value === true;
+    return whenMalformed;
+}
+/**
+ * `x-rate-limit: { category: string, rps?: number }` — read defensively, like every other tag,
+ * because the shape is the emitting app's policy to own, not the API tester's to assume. A category alone
+ * (no `rps`) still groups operations sharing one budget; a config-level rate can complete it.
+ */
+export function readRateLimit(op) {
+    const tag = extObject(op, "x-rate-limit");
+    if (typeof tag?.category !== "string" || tag.category === "")
+        return null;
+    return { category: tag.category, rps: typeof tag.rps === "number" && tag.rps > 0 ? tag.rps : null };
+}
+//# sourceMappingURL=flags.js.map

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

@@ -0,0 +1,11 @@
+/** A tag the API tester could not resolve, named so the report can say which tag would close the gap. */
+export interface Gap {
+    operationId: string;
+    tag: string;
+    detail: string;
+}
+export declare class GapCollector {
+    readonly gaps: Gap[];
+    record(operationId: string, tag: string, detail: string): void;
+}
+//# sourceMappingURL=gaps.d.ts.map

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

@@ -0,0 +1,8 @@
+/** A tag the API tester could not resolve, named so the report can say which tag would close the gap. */
+export class GapCollector {
+    gaps = [];
+    record(operationId, tag, detail) {
+        this.gaps.push({ detail, operationId, tag });
+    }
+}
+//# sourceMappingURL=gaps.js.map

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

@@ -0,0 +1,33 @@
+/** `x-invite`: the invite, accept and revoke operations of a grant, and where each reads its pieces. */
+import type { OperationObject } from "../types.ts";
+export interface InviteSpec {
+    invite: string;
+    accept: string;
+    revoke: string;
+    granteeField: string;
+    tokenPointer: string;
+    grantPointer: string;
+    /** Where the accept token comes from. Default `response` keeps `tokenPointer`. */
+    tokenFrom: "response" | "outOfBand";
+    /** `resolveOutOfBand` kind when `tokenFrom` is `outOfBand`. Default `${entity}-invite`. */
+    tokenKind?: string;
+    /**
+     * How the invitee consumes the token. Default `token` stuffs it into the documented accept
+     * JSON / path. `link` GETs the out-of-band value as an absolute URL (the mailed consume hop).
+     */
+    acceptFrom?: "token" | "link";
+    /**
+     * JSON path of a credential in a 2xx accept body. When it is a non-empty string, the invitee
+     * uses it for the grant read. Missing means the invitee keeps the credential it already had.
+     * Default `$.access_token`.
+     */
+    credentialFrom: string;
+    /**
+     * operationId of the read the accepted invite opens, filled from the inviter's scope. Default:
+     * the invite entity's own item read. Name it when the grant opens a parent (an organization)
+     * rather than the record the invite creates.
+     */
+    grants?: string;
+}
+export declare function readInvite(op: OperationObject): InviteSpec | null;
+//# sourceMappingURL=invite.d.ts.map

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

@@ -0,0 +1,30 @@
+/** `x-invite`: the invite, accept and revoke operations of a grant, and where each reads its pieces. */
+import { extObject } from "./tag.js";
+const stringOr = (value, fallback) => (typeof value === "string" ? value : fallback);
+const nonEmpty = (value) => typeof value === "string" && value !== "";
+export function readInvite(op) {
+    const tag = extObject(op, "x-invite");
+    if (tag === undefined)
+        return null;
+    const { invite, accept, revoke } = tag;
+    if (typeof invite !== "string" || typeof accept !== "string" || typeof revoke !== "string")
+        return null;
+    const spec = {
+        accept,
+        credentialFrom: nonEmpty(tag.credentialFrom) ? tag.credentialFrom : "$.access_token",
+        grantPointer: stringOr(tag.grantPointer, "$.grant_id"),
+        granteeField: stringOr(tag.granteeField, "key"),
+        invite,
+        revoke,
+        tokenFrom: tag.tokenFrom === "outOfBand" ? "outOfBand" : "response",
+        tokenPointer: stringOr(tag.tokenPointer, "$.token"),
+    };
+    if (nonEmpty(tag.tokenKind))
+        spec.tokenKind = tag.tokenKind;
+    if (nonEmpty(tag.grants))
+        spec.grants = tag.grants;
+    if (tag.acceptFrom === "link")
+        spec.acceptFrom = "link";
+    return spec;
+}
+//# sourceMappingURL=invite.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * `x-privileged: true` on a request body property: only the highest-rank principal may set it, as a
+ * plan or a verified flag. A write by anyone else that includes it must be refused or leave it
+ * unchanged. The marker goes on a schema property, by overlay when the document lacks it, and is a
+ * boolean; anywhere else, or of any other type, it is a gap and the API tester ignores it.
+ */
+import type { OperationObject, JsonSchema } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+/** The marker's name. */
+export declare const PRIVILEGED = "x-privileged";
+/** Where the marker is read from: the operation's request body, and where its gaps go. */
+export interface PrivilegedSource {
+    body: JsonSchema | null;
+    operationId: string;
+    gaps: GapCollector;
+}
+/** The request body properties marked privileged, nested ones by dotted path, in schema order. */
+export declare function readPrivileged(op: OperationObject, source: PrivilegedSource): string[];
+/**
+ * The marked properties (`readPrivileged`'s paths) the body requires: each segment of the path is
+ * required where it sits, by the object or one of its allOf members. Only the highest rank can send
+ * a create whose body requires one.
+ */
+export declare function requiredPrivileged(body: JsonSchema | null, marked: readonly string[]): string[];
+/** The schema of the property at a dotted path, a marked one say, allOf members included; undefined when none. */
+export declare function propertySchema(body: JsonSchema | null, path: string): JsonSchema | undefined;
+//# sourceMappingURL=privileged.d.ts.map

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

@@ -0,0 +1,84 @@
+/**
+ * `x-privileged: true` on a request body property: only the highest-rank principal may set it, as a
+ * plan or a verified flag. A write by anyone else that includes it must be refused or leave it
+ * unchanged. The marker goes on a schema property, by overlay when the document lacks it, and is a
+ * boolean; anywhere else, or of any other type, it is a gap and the API tester ignores it.
+ */
+/** The marker's name. */
+export const PRIVILEGED = "x-privileged";
+const TAG = PRIVILEGED;
+/** The request body properties marked privileged, nested ones by dotted path, in schema order. */
+export function readPrivileged(op, source) {
+    const { body, gaps, operationId } = source;
+    const misplaced = (where) => gaps.record(operationId, TAG, `${TAG} belongs on a request body property, not on ${where}; the API tester cannot use it`);
+    if (op[TAG] !== undefined)
+        misplaced("the operation");
+    if (body === null)
+        return [];
+    if (body[TAG] !== undefined)
+        misplaced("the body itself");
+    const marked = [];
+    walk(body, { gaps, marked, operationId, prefix: "", seen: new Set() });
+    return marked;
+}
+/**
+ * The marked properties (`readPrivileged`'s paths) the body requires: each segment of the path is
+ * required where it sits, by the object or one of its allOf members. Only the highest rank can send
+ * a create whose body requires one.
+ */
+export function requiredPrivileged(body, marked) {
+    return marked.filter((path) => {
+        let at = body ?? undefined;
+        for (const name of path.split(".")) {
+            if (at === undefined || !requiredAt(at).includes(name))
+                return false;
+            at = propertyAt(at, name);
+        }
+        return true;
+    });
+}
+/** The schema of the property at a dotted path, a marked one say, allOf members included; undefined when none. */
+export function propertySchema(body, path) {
+    let at = body ?? undefined;
+    for (const name of path.split("."))
+        at = at === undefined ? undefined : propertyAt(at, name);
+    return at;
+}
+/* The names an object schema requires, its allOf members' included. */
+function requiredAt(schema) {
+    return [schema, ...schemas(schema.allOf)].flatMap((part) => (Array.isArray(part.required) ? part.required : []));
+}
+/* The schema of property `name`, declared by the object or one of its allOf members. */
+function propertyAt(schema, name) {
+    return [schema, ...schemas(schema.allOf)].map((part) => schemaMap(part.properties)[name]).find(isSchema);
+}
+/* Each property of `schema` and of its allOf members, then each nested object's. */
+function walk(schema, at) {
+    if (at.seen.has(schema))
+        return;
+    at.seen.add(schema);
+    for (const member of schemas(schema.allOf))
+        walk(member, at);
+    for (const [name, property] of Object.entries(schemaMap(schema.properties))) {
+        const path = `${at.prefix}${name}`;
+        const marker = property[TAG];
+        if (marker === true)
+            at.marked.push(path);
+        else if (marker !== undefined && marker !== false) {
+            at.gaps.record(at.operationId, TAG, `${TAG} on property "${path}" must be true or false; the API tester cannot use it`);
+        }
+        walk(property, { ...at, prefix: `${path}.` });
+    }
+}
+function isSchema(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function schemas(value) {
+    return Array.isArray(value) ? value.filter(isSchema) : [];
+}
+function schemaMap(value) {
+    if (!isSchema(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => isSchema(entry[1])));
+}
+//# sourceMappingURL=privileged.js.map

package/dist/api/spec/extensions/query-tag.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `x-query`: which fields a list endpoint filters, sorts, searches and selects by. A declared tag
+ * is read as it stands; without one, an endpoint that takes a query parameter gets every scalar
+ * property guessed and a recorded gap saying so.
+ */
+import type { FilterableField, QueryCapabilities, QueryParamNames, SortableField } from "../../config/types/query.ts";
+import type { Endpoint, JsonSchema } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+export interface QueryCapability {
+    filterable: string[];
+    sortable: string[];
+    searchable: string[];
+    selectable: string[];
+    maxLimit?: number;
+    defaultOrder?: string;
+    stableTiebreak?: string;
+    source: "tag" | "heuristic";
+    /** Structured `x-query` extras. Absent on a heuristic guess. */
+    catalog?: QueryCapabilities;
+    /** True when the tag included a `filterable` key, even if the list is empty. */
+    filterableDeclared?: boolean;
+    sortableDeclared?: boolean;
+    searchableDeclared?: boolean;
+    selectableDeclared?: boolean;
+    /** Structured rows when the tag used objects; otherwise one `{ field }` per name. */
+    filterFields?: FilterableField[];
+    sortableFields?: SortableField[];
+}
+/** Where a capability is read from beside the operation: the gaps it records, and config's names. */
+export interface CapabilityContext {
+    gaps?: GapCollector | undefined;
+    /** Config `query.params`, outranking `x-query.params`. */
+    params?: QueryParamNames | undefined;
+}
+export declare function readQueryCapability(endpoint: Endpoint, itemSchema: JsonSchema | null, context?: CapabilityContext): QueryCapability | null;
+//# sourceMappingURL=query-tag.d.ts.map

package/dist/api/spec/extensions/query-tag.js

@@ -0,0 +1,92 @@
+/**
+ * `x-query`: which fields a list endpoint filters, sorts, searches and selects by. A declared tag
+ * is read as it stands; without one, an endpoint that takes a query parameter gets every scalar
+ * property guessed and a recorded gap saying so.
+ */
+import { deriveQueryConventions } from "../conventions/derive.js";
+import { mergeQueryParams } from "../conventions/query-params.js";
+import { parseQueryCatalog } from "../query/parse-catalog.js";
+import { extObject } from "./tag.js";
+import { scalarKinds } from "../schema.js";
+function scalarProperties(schema) {
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return [];
+    const out = [];
+    for (const [name, raw] of Object.entries(props)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        if (scalarKinds(raw) !== undefined)
+            out.push(name);
+    }
+    return out;
+}
+function declared(tag) {
+    const catalog = parseQueryCatalog(tag);
+    const fields = catalog.filterable ?? [];
+    const sortFields = catalog.sortable ?? [];
+    const cap = {
+        catalog,
+        filterFields: fields,
+        filterable: fields.map((field) => field.field),
+        filterableDeclared: tag.filterable !== undefined,
+        /* The catalog keeps a searchable or selectable list whenever the tag holds one. */
+        searchable: catalog.searchable ?? [],
+        searchableDeclared: tag.searchable !== undefined,
+        selectable: catalog.selectable ?? [],
+        selectableDeclared: tag.selectable !== undefined,
+        sortable: sortFields.map((field) => field.field),
+        sortableDeclared: tag.sortable !== undefined,
+        sortableFields: sortFields,
+        source: "tag",
+    };
+    if (typeof tag.maxLimit === "number")
+        cap.maxLimit = tag.maxLimit;
+    if (typeof tag.defaultOrder === "string")
+        cap.defaultOrder = tag.defaultOrder;
+    if (typeof tag.stableTiebreak === "string")
+        cap.stableTiebreak = tag.stableTiebreak;
+    return cap;
+}
+function guessed(endpoint, itemSchema, { gaps, params: config }) {
+    const params = (endpoint.op.parameters ?? []).filter((p) => p.in === "query");
+    const tag = extObject(endpoint.op, "x-query");
+    const named = mergeQueryParams({ config, declared: params.map((p) => p.name), tag: tag?.params });
+    /* Same roles the checks already use — named, or by the aliases `sort`/`fields`/`q`/`per_page`,
+     * not only the fixture spellings `filter`/`order`/`select`/`limit`. Pagination-only params do
+     * not count: a `page`/`limit` list is not a query grammar. */
+    const conventions = deriveQueryConventions(params, null, { params: named });
+    const roles = [conventions.filter, conventions.order, conventions.select, conventions.search].filter((name) => name !== undefined);
+    if (roles.length === 0)
+        return null;
+    const scalars = itemSchema === null ? [] : scalarProperties(itemSchema);
+    gaps?.record(endpoint.operationId, "x-query", `endpoint accepts ${roles.join("/")} ` +
+        `but does not declare which fields support them. Assuming all ${scalars.length} scalar ` +
+        "properties, which will produce false failures on unindexed fields");
+    const cap = {
+        filterable: scalars,
+        searchable: scalars.filter((f) => /name|title|slug|label|description|email/i.test(f)),
+        selectable: scalars,
+        /* A parameter of the list's own path holds one value across the listing: ordering by it shows nothing. */
+        sortable: scalars.filter((field) => !endpoint.path.includes(`{${field}}`)),
+        source: "heuristic",
+    };
+    if (conventions.limit !== undefined) {
+        const max = params.find((p) => p.name === conventions.limit)?.schema?.maximum;
+        if (typeof max === "number")
+            cap.maxLimit = max;
+    }
+    return cap;
+}
+/* Keys that say how to send a query and read its answer, not what it can be asked. */
+const NAMING_KEYS = /* @__PURE__ */ new Set(["params", "envelope"]);
+/* A tag that only names parameters and envelope fields is still a guess. `{}` declares nothing at all. */
+function declaresCapabilities(tag) {
+    const keys = tag === undefined ? [] : Object.keys(tag);
+    return tag !== undefined && (keys.length === 0 || keys.some((key) => !NAMING_KEYS.has(key)));
+}
+export function readQueryCapability(endpoint, itemSchema, context = {}) {
+    const tag = extObject(endpoint.op, "x-query");
+    return declaresCapabilities(tag) ? declared(tag) : guessed(endpoint, itemSchema, context);
+}
+//# sourceMappingURL=query-tag.js.map

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

@@ -0,0 +1,5 @@
+/** `x-invalidate` and `x-cleanup`: tags that name other routes, read as `METHOD /path`. */
+import type { OperationObject } from "../types.ts";
+export declare function readInvalidate(op: OperationObject): string[];
+export declare function readCleanup(op: OperationObject): string | null;
+//# sourceMappingURL=routes.d.ts.map