@lovrozagar/oat 0.1.0

package/dist/runtime/teardown.js

@@ -0,0 +1,129 @@
+/**
+ * Teardown of everything a run created.
+ *
+ * A tester that leaves its fixtures behind is a tester nobody runs twice against anything real.
+ * Records are unwound newest-first so children go before the parents they depend on, and every
+ * failure is collected rather than thrown — a teardown that aborts halfway is worse than one that
+ * reports exactly what it could not remove.
+ */
+import { parseRouteRef } from "../spec/load.js";
+import { fillPath } from "./world.js";
+/**
+ * Registry of what a run brought into existence. Entities are recorded in creation order so the
+ * unwind can reverse it.
+ */
+export class Ledger {
+    items = [];
+    record(entity, id, scope) {
+        if (id === "" || id === "undefined")
+            return;
+        this.items.push({ entity, id, scope: { ...scope } });
+    }
+    get size() {
+        return this.items.length;
+    }
+    entries() {
+        return this.items;
+    }
+    async unwind(model, client, headers, onItem) {
+        const report = { failed: [], removed: 0, unsupported: [] };
+        const unsupported = new Set();
+        /* Newest first: a child created inside a parent must be removed before the parent, and
+         * creation order already encodes that dependency. */
+        const queue = [...this.items].reverse();
+        let done = 0;
+        for (const item of queue) {
+            onItem?.(done, queue.length, item);
+            const deleteOp = deleteOperationFor(item.entity, model);
+            if (deleteOp === null) {
+                unsupported.add(item.entity);
+                done += 1;
+                continue;
+            }
+            const param = deleteOp.pathParams.at(-1);
+            const scope = param === undefined ? item.scope : { ...item.scope, [param]: item.id };
+            let path;
+            try {
+                path = fillPath(deleteOp.path, scope);
+            }
+            catch (error) {
+                report.failed.push({
+                    entity: item.entity,
+                    id: item.id,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+                done += 1;
+                continue;
+            }
+            try {
+                const exchange = await client.request("DELETE", path, { headers: headers() });
+                /* 404 means it is already gone — the goal is absence, not a successful call. */
+                if (exchange.status < 300 || exchange.status === 404 || exchange.status === 410) {
+                    report.removed += 1;
+                }
+                else {
+                    report.failed.push({
+                        entity: item.entity,
+                        id: item.id,
+                        reason: `DELETE ${path} returned ${exchange.status}`,
+                    });
+                }
+            }
+            catch (error) {
+                report.failed.push({
+                    entity: item.entity,
+                    id: item.id,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+            done += 1;
+            onItem?.(done, queue.length, item);
+        }
+        report.unsupported = [...unsupported];
+        return report;
+    }
+}
+/**
+ * The operation that removes an instance: the entity's own delete, or an explicit `x-cleanup`
+ * route for entities whose removal lives somewhere the graph does not connect.
+ */
+function deleteOperationFor(entityName, model) {
+    const entity = model.entities.get(entityName);
+    if (entity?.delete !== undefined) {
+        const op = model.byOperationId.get(entity.delete);
+        if (op !== undefined)
+            return op;
+    }
+    for (const op of model.operations) {
+        if (op.entity !== entityName || op.cleanup === null)
+            continue;
+        const parsed = parseRouteRef(op.cleanup);
+        if (parsed === null)
+            continue;
+        const target = model.byRoute.get(`${parsed.method} ${parsed.path}`);
+        if (target !== undefined)
+            return target;
+    }
+    return null;
+}
+export function renderTeardown(report, created) {
+    if (created === 0)
+        return [];
+    const lines = [];
+    if (report.failed.length === 0 && report.unsupported.length === 0) {
+        lines.push(`  cleaned up ${report.removed}/${created} created record(s)`);
+        return lines;
+    }
+    lines.push(`  cleanup: removed ${report.removed}/${created} created record(s)`);
+    if (report.unsupported.length > 0) {
+        lines.push(`    ${report.unsupported.join(", ")} — no delete operation in the document, so records ` +
+            "created for these entities remain. Declare x-cleanup to make them removable.");
+    }
+    for (const failure of report.failed.slice(0, 5)) {
+        lines.push(`    ${failure.entity} ${failure.id}: ${failure.reason}`);
+    }
+    if (report.failed.length > 5)
+        lines.push(`    … and ${report.failed.length - 5} more`);
+    return lines;
+}
+//# sourceMappingURL=teardown.js.map

package/dist/runtime/teardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.js","sourceRoot":"","sources":["../../src/runtime/teardown.ts"],"names":[],"mappings":"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"}

package/dist/runtime/validate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Response-schema validation — the floor beneath the behavioural checks.
+ *
+ * Schemas are compiled per operation+status and reused. `additionalProperties: false` is honoured
+ * as written: a document that declares a closed object and a backend that returns extra fields
+ * genuinely disagree, and which one is wrong is a decision for the reader, not for oat.
+ */
+import type { OperationObject } from "../spec/types.ts";
+/** Minimal surface oat uses — avoids depending on AJV's CJS/ESM type shape. */
+export interface ValidateFunction {
+    (data: unknown): boolean;
+    errors?: Array<{
+        instancePath?: string;
+        message?: string;
+    }> | null;
+}
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+export declare class SchemaValidator {
+    private readonly ajv;
+    private readonly cache;
+    constructor();
+    /** Compiles the schema documented for this operation and status, if there is one. */
+    private compile;
+    validate(operationId: string, op: OperationObject, status: number, body: unknown): ValidationResult;
+    /** True when the document actually documents this status for this operation. */
+    documents(op: OperationObject, status: number): boolean;
+}
+//# sourceMappingURL=validate.d.ts.map

package/dist/runtime/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/runtime/validate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,kBAAkB,CAAA;AAErE,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAChC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACxB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAA;CAClE;AAQD,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,EAAE,CAAA;CAChB;AAWD,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;;IAanE,qFAAqF;IACrF,OAAO,CAAC,OAAO;IAqBf,QAAQ,CACP,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,GACX,gBAAgB;IAWnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;CAGvD"}

package/dist/runtime/validate.js

@@ -0,0 +1,111 @@
+/**
+ * Response-schema validation — the floor beneath the behavioural checks.
+ *
+ * Schemas are compiled per operation+status and reused. `additionalProperties: false` is honoured
+ * as written: a document that declares a closed object and a backend that returns extra fields
+ * genuinely disagree, and which one is wrong is a decision for the reader, not for oat.
+ */
+import ajvModule from "ajv/dist/2020.js";
+import formatsModule from "ajv-formats";
+const OK = { errors: [], ok: true };
+/* Both packages ship CJS with an interop default, so the callable lives on `.default` under
+ * NodeNext resolution — but only at runtime, hence the cast. */
+const Ajv2020 = (ajvModule.default ?? ajvModule);
+const addFormats = (formatsModule.default ?? formatsModule);
+export class SchemaValidator {
+    ajv;
+    cache = new Map();
+    constructor() {
+        this.ajv = new Ajv2020({
+            allErrors: true,
+            /* Specs in the wild carry annotations AJV does not know; refusing to compile over a
+             * vocabulary quibble would make oat useless on real documents. */
+            strict: false,
+            validateFormats: true,
+        });
+        addFormats(this.ajv);
+    }
+    /** Compiles the schema documented for this operation and status, if there is one. */
+    compile(op, key, status) {
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const schema = schemaFor(op, status);
+        if (schema === null) {
+            this.cache.set(key, null);
+            return null;
+        }
+        try {
+            const validate = this.ajv.compile(sanitise(schema));
+            this.cache.set(key, validate);
+            return validate;
+        }
+        catch {
+            /* An uncompilable schema is a spec defect, surfaced by the caller as a gap rather than
+             * crashing the run. */
+            this.cache.set(key, null);
+            return null;
+        }
+    }
+    validate(operationId, op, status, body) {
+        const validate = this.compile(op, `${operationId}:${status}`, status);
+        if (validate === null)
+            return OK;
+        if (validate(body) === true)
+            return OK;
+        const errors = (validate.errors ?? []).map((error) => {
+            const at = error.instancePath === undefined || error.instancePath === "" ? "(root)" : error.instancePath;
+            return `${at} ${error.message ?? "is invalid"}`;
+        });
+        return { errors: [...new Set(errors)].slice(0, 12), ok: false };
+    }
+    /** True when the document actually documents this status for this operation. */
+    documents(op, status) {
+        return schemaFor(op, status) !== null;
+    }
+}
+function schemaFor(op, status) {
+    const responses = op.responses ?? {};
+    const candidates = [String(status), `${Math.floor(status / 100)}XX`, "default"];
+    for (const code of candidates) {
+        const content = responses[code]?.content;
+        if (content === undefined)
+            continue;
+        for (const [mediaType, media] of Object.entries(content)) {
+            if (mediaType.includes("json") && media.schema !== undefined)
+                return media.schema;
+        }
+    }
+    return null;
+}
+/**
+ * Strips constructs that break AJV but carry no validation meaning here: OpenAPI's `nullable`
+ * without a sibling `type` (invalid JSON Schema, emitted by several generators), and `example`
+ * keys that collide with the `examples` keyword in draft 2020-12.
+ */
+function sanitise(schema) {
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node === null || typeof node !== "object")
+            return node;
+        const out = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "nullable")
+                continue;
+            if (key === "example")
+                continue;
+            if (key === "discriminator")
+                continue;
+            out[key] = walk(value);
+        }
+        /* `nullable: true` with a concrete type widens the type rather than being dropped. */
+        const original = node;
+        if (original.nullable === true && typeof original.type === "string") {
+            out.type = [original.type, "null"];
+        }
+        return out;
+    };
+    return walk(schema);
+}
+//# sourceMappingURL=validate.js.map

package/dist/runtime/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/runtime/validate.ts"],"names":[],"mappings":"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"}

package/dist/runtime/world.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Seeds the world once per run: resolves path parameters top-down, then creates a discriminating
+ * cohort per entity.
+ *
+ * Prior art resolved fixtures per test case, which meant one unseedable resource produced dozens
+ * of unrelated failures. Here a resolution failure is recorded once and everything downstream is
+ * reported as BLOCKED against that single cause.
+ */
+import type { OperationModel, SpecModel } from "../spec/graph.ts";
+import type { Client } from "./client.ts";
+import { type CohortMember } from "./fixture.ts";
+export type Record_ = Record<string, unknown>;
+export interface Scope {
+    values: Record<string, string>;
+    /** Records created while resolving ancestors, newest last — unwound in reverse at teardown. */
+    created: Array<{
+        entity: string;
+        path: string;
+        id: string;
+    }>;
+}
+export declare class SeedError extends Error {
+    readonly cause_: string;
+    /** Status the failing request returned, when the failure was an HTTP response. */
+    readonly status?: number | undefined;
+    constructor(cause_: string, message: string, 
+    /** Status the failing request returned, when the failure was an HTTP response. */
+    status?: number | undefined);
+}
+export declare function fillPath(template: string, values: Record<string, string>): string;
+export interface WorldOptions {
+    roots: Record<string, string>;
+    seed: number;
+    cohortSize?: number;
+    authHeaders: () => Record<string, string>;
+}
+/**
+ * Resolves every path parameter an operation needs. Roots come from config; everything else is
+ * created through the owning entity's create operation, depth-first.
+ */
+export declare function resolveScope(op: OperationModel, model: SpecModel, client: Client, options: WorldOptions, scope?: Scope): Promise<Scope>;
+export declare function requestSchemaOf(op: OperationModel, model: SpecModel): Record<string, unknown> | null;
+export interface SeededCohort {
+    members: CohortMember[];
+    records: Record_[];
+}
+/** Creates the cohort and returns the server's view of each instance. */
+export declare function seedCohort(createOp: OperationModel, model: SpecModel, client: Client, options: WorldOptions, scope: Scope): Promise<SeededCohort>;
+//# sourceMappingURL=world.d.ts.map

package/dist/runtime/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../src/runtime/world.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,cAAc,CAAA;AAE7D,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE7C,MAAM,WAAW,KAAK;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,+FAA+F;IAC/F,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5D;AAED,qBAAa,SAAU,SAAQ,KAAK;IAElC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEvB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAHf,MAAM,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM;IACf,kFAAkF;IACzE,MAAM,CAAC,EAAE,MAAM,YAAA;CAIzB;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAMjF;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACzC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,KAAK,GAAE,KAAmC,GACxC,OAAO,CAAC,KAAK,CAAC,CAuChB;AAyBD,wBAAgB,eAAe,CAC9B,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,SAAS,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQhC;AAED,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,OAAO,EAAE,OAAO,EAAE,CAAA;CAClB;AAED,yEAAyE;AACzE,wBAAsB,UAAU,CAC/B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,KAAK,GACV,OAAO,CAAC,YAAY,CAAC,CA4BvB"}

package/dist/runtime/world.js

@@ -0,0 +1,119 @@
+/**
+ * Seeds the world once per run: resolves path parameters top-down, then creates a discriminating
+ * cohort per entity.
+ *
+ * Prior art resolved fixtures per test case, which meant one unseedable resource produced dozens
+ * of unrelated failures. Here a resolution failure is recorded once and everything downstream is
+ * reported as BLOCKED against that single cause.
+ */
+import { owningEntityName } from "../spec/graph.js";
+import { buildCohort } from "./fixture.js";
+export class SeedError extends Error {
+    cause_;
+    status;
+    constructor(cause_, message, 
+    /** Status the failing request returned, when the failure was an HTTP response. */
+    status) {
+        super(message);
+        this.cause_ = cause_;
+        this.status = status;
+    }
+}
+export function fillPath(template, values) {
+    return template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = values[name];
+        if (value === undefined)
+            throw new SeedError(name, `no value for path parameter {${name}}`);
+        return encodeURIComponent(value);
+    });
+}
+/**
+ * Resolves every path parameter an operation needs. Roots come from config; everything else is
+ * created through the owning entity's create operation, depth-first.
+ */
+export async function resolveScope(op, model, client, options, scope = { created: [], values: {} }) {
+    for (const param of op.pathParams) {
+        if (scope.values[param] !== undefined)
+            continue;
+        const fromRoot = options.roots[param];
+        if (fromRoot !== undefined) {
+            scope.values[param] = fromRoot;
+            continue;
+        }
+        const owner = owningEntityName(op.path, param);
+        if (owner === null) {
+            throw new SeedError(param, `path parameter {${param}} names no entity oat can create`);
+        }
+        const entity = model.entities.get(owner);
+        if (entity?.create === undefined) {
+            throw new SeedError(param, `{${param}} identifies a "${owner}", which has no create operation — supply it as a root`);
+        }
+        const createOp = model.byOperationId.get(entity.create);
+        if (createOp === undefined)
+            throw new SeedError(param, `missing operation ${entity.create}`);
+        await resolveScope(createOp, model, client, options, scope);
+        const created = await createOne(createOp, model, client, options, scope);
+        const identity = entity.identity ?? "id";
+        const id = created[identity];
+        if (typeof id !== "string" && typeof id !== "number") {
+            throw new SeedError(param, `create for "${owner}" returned no usable "${identity}"`);
+        }
+        scope.values[param] = String(id);
+        scope.created.push({
+            entity: owner,
+            id: String(id),
+            path: fillPath(createOp.path, scope.values),
+        });
+    }
+    return scope;
+}
+async function createOne(createOp, model, client, options, scope) {
+    const schema = requestSchemaOf(createOp, model);
+    const [member] = buildCohort(schema ?? {}, options.seed, ["baseline"]);
+    const exchange = await client.request("POST", fillPath(createOp.path, scope.values), {
+        body: member?.body ?? {},
+        headers: options.authHeaders(),
+    });
+    if (exchange.status >= 300) {
+        throw new SeedError(createOp.operationId, `${createOp.operationId} returned ${exchange.status}: ${JSON.stringify(exchange.responseBody).slice(0, 300)}`, exchange.status);
+    }
+    return (exchange.responseBody ?? {});
+}
+export function requestSchemaOf(op, model) {
+    const raw = model.rawOperations.get(op.operationId);
+    const content = raw?.requestBody?.content;
+    if (content === undefined)
+        return null;
+    for (const [mediaType, media] of Object.entries(content)) {
+        if (mediaType.includes("json") && media.schema !== undefined)
+            return media.schema;
+    }
+    return null;
+}
+/** Creates the cohort and returns the server's view of each instance. */
+export async function seedCohort(createOp, model, client, options, scope) {
+    const schema = requestSchemaOf(createOp, model);
+    if (schema === null) {
+        throw new SeedError(createOp.operationId, `${createOp.operationId} declares no JSON request body`);
+    }
+    const members = buildCohort(schema, options.seed).slice(0, options.cohortSize ?? 7);
+    const records = [];
+    const path = fillPath(createOp.path, scope.values);
+    for (const member of members) {
+        const exchange = await client.request("POST", path, {
+            body: member.body,
+            headers: options.authHeaders(),
+        });
+        if (exchange.status >= 300) {
+            /* Partial cohorts are still useful — a single rejected variant should not cost the
+             * entity all of its coverage. Only a completely empty cohort is fatal. */
+            if (records.length > 0)
+                break;
+            throw new SeedError(createOp.operationId, `seeding "${member.variant}" returned ${exchange.status}: ` +
+                JSON.stringify(exchange.responseBody).slice(0, 300), exchange.status);
+        }
+        records.push((exchange.responseBody ?? {}));
+    }
+    return { members, records };
+}
+//# sourceMappingURL=world.js.map

package/dist/runtime/world.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.js","sourceRoot":"","sources":["../../src/runtime/world.ts"],"names":[],"mappings":"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"}

package/dist/spec/collection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Derives collection shape from the response schema rather than guessing at wrapper key names.
+ *
+ * Hardcoding `["data","items","results","records"]` — as prior art does — returns null on any
+ * API whose envelopes are named after the resource (`{ tables: [...] }`), which silently
+ * disables every list-based assertion. The schema already states the answer; read it.
+ */
+import type { OperationObject, SchemaObject } from "./types.ts";
+export interface CollectionShape {
+    /** Property holding the array, or null when the response *is* the array. */
+    key: string | null;
+    itemSchema: SchemaObject | null;
+    /** Sibling properties of the collection — `count`, `hasMore`, `nextCursor`, `page`. */
+    envelopeKeys: string[];
+    pagination: {
+        countKey?: string;
+        hasMoreKey?: string;
+        cursorKey?: string;
+        pageKey?: string;
+        limitKey?: string;
+    };
+}
+export declare function successSchema(op: OperationObject): SchemaObject | null;
+export declare function requestSchema(op: OperationObject): SchemaObject | null;
+export declare function deriveCollectionShape(schema: SchemaObject | null): CollectionShape | null;
+/**
+ * Finds the property that identifies an instance. Prefers a required identity-like property,
+ * then any identity-like property, then the trailing path parameter's implied name.
+ */
+export declare function deriveIdentity(itemSchema: SchemaObject | null, pathParamHint?: string): string | null;
+//# sourceMappingURL=collection.d.ts.map

package/dist/spec/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/spec/collection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE/D,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,UAAU,EAAE,YAAY,GAAG,IAAI,CAAA;IAC/B,uFAAuF;IACvF,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,UAAU,EAAE;QACX,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACD;AAQD,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAWtE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,YAAY,GAAG,IAAI,CAOtE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,eAAe,GAAG,IAAI,CA+CzF;AAQD;;;GAGG;AACH,wBAAgB,cAAc,CAC7B,UAAU,EAAE,YAAY,GAAG,IAAI,EAC/B,aAAa,CAAC,EAAE,MAAM,GACpB,MAAM,GAAG,IAAI,CAsBf"}

package/dist/spec/collection.js

@@ -0,0 +1,121 @@
+/**
+ * Derives collection shape from the response schema rather than guessing at wrapper key names.
+ *
+ * Hardcoding `["data","items","results","records"]` — as prior art does — returns null on any
+ * API whose envelopes are named after the resource (`{ tables: [...] }`), which silently
+ * disables every list-based assertion. The schema already states the answer; read it.
+ */
+const COUNT_KEYS = ["count", "total", "totalCount", "total_count", "totalItems"];
+const HAS_MORE_KEYS = ["hasMore", "has_more", "hasNextPage", "more"];
+const CURSOR_KEYS = ["nextCursor", "next_cursor", "cursor", "next", "endCursor"];
+const PAGE_KEYS = ["page", "pageNumber", "page_number", "offset"];
+const LIMIT_KEYS = ["limit", "perPage", "per_page", "pageSize", "page_size"];
+export function successSchema(op) {
+    const responses = op.responses ?? {};
+    for (const code of ["200", "201", "202", "2XX", "default"]) {
+        const content = responses[code]?.content;
+        if (content === undefined)
+            continue;
+        for (const [mediaType, media] of Object.entries(content)) {
+            if (!mediaType.includes("json"))
+                continue;
+            if (media.schema !== undefined)
+                return media.schema;
+        }
+    }
+    return null;
+}
+export function requestSchema(op) {
+    const content = op.requestBody?.content;
+    if (content === undefined)
+        return null;
+    for (const [mediaType, media] of Object.entries(content)) {
+        if (mediaType.includes("json") && media.schema !== undefined)
+            return media.schema;
+    }
+    return null;
+}
+export function deriveCollectionShape(schema) {
+    if (schema === null)
+        return null;
+    if (schema.type === "array") {
+        return {
+            envelopeKeys: [],
+            itemSchema: asSchema(schema.items),
+            key: null,
+            pagination: {},
+        };
+    }
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return null;
+    const entries = Object.entries(props);
+    const arrayProps = entries.filter(([, value]) => value?.type === "array");
+    if (arrayProps.length === 0)
+        return null;
+    /* With several array properties, the collection is the one whose items are objects and
+     * whose name is not an obvious sidecar (`errors`, `warnings`, `meta`). Ties break toward
+     * the property with the richest item schema — the real payload. */
+    const candidates = arrayProps
+        .filter(([name]) => !/^(errors?|warnings?|messages?|meta|links)$/i.test(name))
+        .map(([name, value]) => ({ item: asSchema(value.items), name }))
+        .filter((c) => c.item !== null);
+    const chosen = candidates.find((c) => c.item?.type === "object" || c.item?.properties !== undefined) ??
+        candidates[0];
+    if (chosen === undefined)
+        return null;
+    const siblingNames = entries.map(([name]) => name).filter((name) => name !== chosen.name);
+    const pagination = {};
+    const pick = (keys) => siblingNames.find((n) => keys.includes(n));
+    const countKey = pick(COUNT_KEYS);
+    const hasMoreKey = pick(HAS_MORE_KEYS);
+    const cursorKey = pick(CURSOR_KEYS);
+    const pageKey = pick(PAGE_KEYS);
+    const limitKey = pick(LIMIT_KEYS);
+    if (countKey !== undefined)
+        pagination.countKey = countKey;
+    if (hasMoreKey !== undefined)
+        pagination.hasMoreKey = hasMoreKey;
+    if (cursorKey !== undefined)
+        pagination.cursorKey = cursorKey;
+    if (pageKey !== undefined)
+        pagination.pageKey = pageKey;
+    if (limitKey !== undefined)
+        pagination.limitKey = limitKey;
+    return { envelopeKeys: siblingNames, itemSchema: chosen.item, key: chosen.name, pagination };
+}
+function asSchema(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+const IDENTITY_CANDIDATES = ["id", "uuid", "slug", "key", "name"];
+/**
+ * Finds the property that identifies an instance. Prefers a required identity-like property,
+ * then any identity-like property, then the trailing path parameter's implied name.
+ */
+export function deriveIdentity(itemSchema, pathParamHint) {
+    if (itemSchema !== null) {
+        const props = itemSchema.properties;
+        if (props !== null && typeof props === "object") {
+            const names = Object.keys(props);
+            const required = Array.isArray(itemSchema.required)
+                ? itemSchema.required
+                : [];
+            for (const candidate of IDENTITY_CANDIDATES) {
+                if (required.includes(candidate))
+                    return candidate;
+            }
+            for (const candidate of IDENTITY_CANDIDATES) {
+                if (names.includes(candidate))
+                    return candidate;
+            }
+        }
+    }
+    if (pathParamHint !== undefined) {
+        /* `{table_id}` on `/tables/{table_id}` implies the item's own key is `id`. */
+        const stripped = pathParamHint.replace(/^.*[_.]/, "");
+        if (IDENTITY_CANDIDATES.includes(stripped))
+            return stripped;
+    }
+    return null;
+}
+//# sourceMappingURL=collection.js.map

package/dist/spec/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../../src/spec/collection.ts"],"names":[],"mappings":"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"}