@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,32 @@
+/** Path parameters nothing in the document can produce, and the entity each parameter identifies. */
+import type { EntityModel, OperationModel } from "./types.ts";
+/**
+ * A path parameter is a root when nothing in the document can produce it: no entity whose name
+ * matches has a create operation. Roots must be supplied by config before a run starts —
+ * discovering them late is what turns one missing fixture into a cascade of failures.
+ */
+export declare function collectRoots(operations: readonly OperationModel[], entities: ReadonlyMap<string, EntityModel>): string[];
+/**
+ * The entity `{param}` identifies: whatever the document tags the collection before it as — its
+ * create, else its item read. Names can carry a parent (`organization-webhook`, when another
+ * `webhooks` collection exists), so the segment alone does not name it. Falls back to the
+ * segment's singular when no route sits on that collection.
+ */
+export declare function owningEntityOf(operations: readonly Pick<OperationModel, "entity" | "method" | "path">[], path: string, param: string): string | null;
+/** The collection segment immediately preceding `{param}` in the path. */
+export declare function owningEntityName(path: string, param: string): string | null;
+/** `{project_id}` → `project`, `{tableId}` → `table`. */
+export declare function impliedEntityName(param: string): string | null;
+/** What a prefix root is read from: the operations, and the entities whose list and create they are. */
+export type Scoping = {
+    operations: readonly OperationModel[];
+    entities: ReadonlyMap<string, EntityModel>;
+};
+/**
+ * The path parameters `op` hangs below: tagged `x-root`, or followed by another parameter, or by the
+ * collection its entity lists or creates in. An id a route ends on, or acts on (`/invites/{token}/accept`), is none.
+ */
+export declare function scopingParams(op: OperationModel, model: Scoping): string[];
+/** The prefix roots a document's routes hang below, each with the operations it scopes. */
+export declare function prefixRoots(model: Scoping): Map<string, string[]>;
+//# sourceMappingURL=roots.d.ts.map

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

@@ -0,0 +1,89 @@
+/** Path parameters nothing in the document can produce, and the entity each parameter identifies. */
+import { singularize } from "../extensions/entity.js";
+import { isParamSegment, pathShape, segmentsOf } from "./segments.js";
+/**
+ * A path parameter is a root when nothing in the document can produce it: no entity whose name
+ * matches has a create operation. Roots must be supplied by config before a run starts —
+ * discovering them late is what turns one missing fixture into a cascade of failures.
+ */
+export function collectRoots(operations, entities) {
+    const roots = new Set();
+    for (const op of operations) {
+        for (const param of op.rootParams)
+            roots.add(param);
+    }
+    for (const op of operations) {
+        for (const param of op.pathParams) {
+            /* Resolve the entity from the segment the parameter qualifies, not from its name:
+             * `/table-templates/{template_id}` identifies a `table-template`, and matching on
+             * the name alone would invent a phantom `template` root. */
+            const implied = owningEntityOf(operations, op.path, param) ?? impliedEntityName(param);
+            if (implied === null)
+                continue;
+            const entity = entities.get(implied);
+            if (entity === undefined || (entity.create === undefined && entity.invite === null))
+                roots.add(param);
+        }
+    }
+    return [...roots].sort();
+}
+/**
+ * The entity `{param}` identifies: whatever the document tags the collection before it as — its
+ * create, else its item read. Names can carry a parent (`organization-webhook`, when another
+ * `webhooks` collection exists), so the segment alone does not name it. Falls back to the
+ * segment's singular when no route sits on that collection.
+ */
+export function owningEntityOf(operations, path, param) {
+    const segments = segmentsOf(path);
+    const index = segments.indexOf(`{${param}}`);
+    if (index <= 0)
+        return null;
+    const collection = pathShape(segments.slice(0, index).join("/"));
+    const item = pathShape(segments.slice(0, index + 1).join("/"));
+    const tagged = (method, at) => operations.find((op) => op.entity !== null && op.method === method && pathShape(op.path) === at)?.entity;
+    return tagged("POST", collection) ?? tagged("GET", item) ?? owningEntityName(path, param);
+}
+/** The collection segment immediately preceding `{param}` in the path. */
+export function owningEntityName(path, param) {
+    const segments = segmentsOf(path);
+    const index = segments.indexOf(`{${param}}`);
+    if (index <= 0)
+        return null;
+    const previous = segments[index - 1];
+    if (isParamSegment(previous))
+        return null;
+    return singularize(previous);
+}
+/** `{project_id}` → `project`, `{tableId}` → `table`. */
+export function impliedEntityName(param) {
+    const stripped = param
+        .replace(/[_.]?(id|slug|uuid|key)$/i, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase();
+    return stripped.length === 0 ? null : stripped.replace(/_/g, "-");
+}
+/**
+ * The path parameters `op` hangs below: tagged `x-root`, or followed by another parameter, or by the
+ * collection its entity lists or creates in. An id a route ends on, or acts on (`/invites/{token}/accept`), is none.
+ */
+export function scopingParams(op, model) {
+    const segments = segmentsOf(op.path);
+    const entity = op.entity === null ? undefined : model.entities.get(op.entity);
+    const collects = entity !== undefined && (entity.list === op.operationId || entity.create === op.operationId);
+    return op.pathParams.filter((param) => {
+        if (op.rootParams.includes(param))
+            return true;
+        const after = segments.slice(segments.indexOf(`{${param}}`) + 1);
+        return after.some((segment) => segment.startsWith("{")) || (collects && after.length > 0);
+    });
+}
+/** The prefix roots a document's routes hang below, each with the operations it scopes. */
+export function prefixRoots(model) {
+    const scoped = new Map();
+    for (const op of model.operations) {
+        for (const root of scopingParams(op, model))
+            scoped.set(root, [...(scoped.get(root) ?? []), op.operationId]);
+    }
+    return scoped;
+}
+//# sourceMappingURL=roots.js.map

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

@@ -0,0 +1,10 @@
+/** A path read segment by segment, with its parameters told apart from its literals. */
+/** Whether `segment` is a whole `{param}`. */
+export declare function isParamSegment(segment: string): boolean;
+/** The non-empty segments of `path`. */
+export declare function segmentsOf(path: string): string[];
+/** Segments with every parameter written `{}`, so templates that differ only in names compare equal. */
+export declare function templateKey(segments: readonly string[]): string;
+/** `path` as a template key. */
+export declare function pathShape(path: string): string;
+//# sourceMappingURL=segments.d.ts.map

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

@@ -0,0 +1,19 @@
+/** A path read segment by segment, with its parameters told apart from its literals. */
+const PARAM_SEGMENT = /^\{[^}]+\}$/;
+/** Whether `segment` is a whole `{param}`. */
+export function isParamSegment(segment) {
+    return PARAM_SEGMENT.test(segment);
+}
+/** The non-empty segments of `path`. */
+export function segmentsOf(path) {
+    return path.split("/").filter(Boolean);
+}
+/** Segments with every parameter written `{}`, so templates that differ only in names compare equal. */
+export function templateKey(segments) {
+    return segments.map((s) => (isParamSegment(s) ? "{}" : s)).join("/");
+}
+/** `path` as a template key. */
+export function pathShape(path) {
+    return templateKey(segmentsOf(path));
+}
+//# sourceMappingURL=segments.js.map

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

@@ -0,0 +1,7 @@
+import type { DocumentedStatuses } from "./types.ts";
+export declare function readStatuses(responses: Record<string, unknown> | undefined): DocumentedStatuses;
+/** Whether `status` is covered: named exactly, by its range, or by `default`. */
+export declare function documentsStatus(statuses: DocumentedStatuses, status: number): boolean;
+/** The success statuses as the document spells them, for messages. */
+export declare function describeSuccess(statuses: DocumentedStatuses): string[];
+//# sourceMappingURL=statuses.d.ts.map

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

@@ -0,0 +1,26 @@
+export function readStatuses(responses) {
+    const exact = [];
+    const ranges = [];
+    let hasDefault = false;
+    for (const key of Object.keys(responses ?? {})) {
+        if (/^[1-5]\d\d$/.test(key))
+            exact.push(Number(key));
+        else if (/^[1-5]xx$/i.test(key))
+            ranges.push(Number(key[0]));
+        else if (key === "default")
+            hasDefault = true;
+    }
+    return { default: hasDefault, exact: exact.sort((a, b) => a - b), ranges: ranges.sort((a, b) => a - b) };
+}
+/** Whether `status` is covered: named exactly, by its range, or by `default`. */
+export function documentsStatus(statuses, status) {
+    return statuses.exact.includes(status) || statuses.ranges.includes(Math.floor(status / 100)) || statuses.default;
+}
+/** The success statuses as the document spells them, for messages. */
+export function describeSuccess(statuses) {
+    return [
+        ...statuses.exact.filter((code) => code < 300).map(String),
+        ...statuses.ranges.filter((c) => c === 2).map(() => "2XX"),
+    ];
+}
+//# sourceMappingURL=statuses.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * Each entity's read surface — the routes through which an instance is observable — and whether
+ * an instance can be tracked across them at all.
+ *
+ * The central move: `x-invalidate` is read as a graph edge, not a cache hint. Inverting it gives
+ * each entity the set of projections through which it is observable: the criss-cross matrix.
+ */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { EntityModel, OperationModel } from "./types.ts";
+/** The document's operations, in order and by route. */
+export interface DocumentOperations {
+    operations: readonly OperationModel[];
+    byRoute: ReadonlyMap<string, OperationModel>;
+}
+/** Invert x-invalidate: a mutator's declared read routes belong to its entity's surface. */
+export declare function invertInvalidate(entities: Map<string, EntityModel>, { byRoute, operations }: DocumentOperations, gaps: GapCollector): void;
+/** Sibling fallback for entities whose mutators declared nothing. */
+export declare function fallBackToSiblings(entities: ReadonlyMap<string, EntityModel>, operations: readonly OperationModel[], gaps: GapCollector): void;
+/** An entity is trackable when it has an identity; one with mutators and none is a gap. */
+export declare function markTrackable(entities: ReadonlyMap<string, EntityModel>, gaps: GapCollector): void;
+//# sourceMappingURL=surface.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * Each entity's read surface — the routes through which an instance is observable — and whether
+ * an instance can be tracked across them at all.
+ *
+ * The central move: `x-invalidate` is read as a graph edge, not a cache hint. Inverting it gives
+ * each entity the set of projections through which it is observable: the criss-cross matrix.
+ */
+import { parseRouteRef } from "../routes.js";
+import { entityNamed } from "./entities.js";
+/** Invert x-invalidate: a mutator's declared read routes belong to its entity's surface. */
+export function invertInvalidate(entities, { byRoute, operations }, gaps) {
+    for (const op of operations) {
+        if (op.entity === null || op.invalidates.length === 0)
+            continue;
+        const entity = entityNamed(entities, op.entity);
+        for (const ref of op.invalidates) {
+            if (parseRouteRef(ref)?.method !== "GET")
+                continue;
+            if (!entity.readSurface.includes(ref)) {
+                entity.readSurface.push(ref);
+                entity.declaredSurface.push(ref);
+            }
+            if (!byRoute.has(ref)) {
+                gaps.record(op.operationId, "x-invalidate", `names "${ref}", which is not an operation in this document`);
+            }
+        }
+    }
+}
+/** Sibling fallback for entities whose mutators declared nothing. */
+export function fallBackToSiblings(entities, operations, gaps) {
+    for (const entity of entities.values()) {
+        if (entity.readSurface.length > 0)
+            continue;
+        for (const opId of [entity.list, entity.read]) {
+            if (opId === undefined)
+                continue;
+            const op = operations.find((o) => o.operationId === opId);
+            if (op !== undefined)
+                entity.readSurface.push(op.route);
+        }
+        const mutator = entity.create ?? entity.update ?? entity.delete;
+        if (entity.readSurface.length > 0 && mutator) {
+            gaps.record(mutator, "x-invalidate", `entity "${entity.name}" has mutators but no declared read surface; ` +
+                `falling back to sibling routes ${entity.readSurface.join(", ")}`);
+        }
+    }
+}
+/** An entity is trackable when it has an identity; one with mutators and none is a gap. */
+export function markTrackable(entities, gaps) {
+    for (const entity of entities.values()) {
+        entity.trackable = entity.identity !== null;
+        const mutator = entity.create ?? entity.update;
+        if (!entity.trackable && mutator !== undefined) {
+            gaps.record(mutator, "x-entity.identity", `entity "${entity.name}" has no discoverable identity property, so instances cannot ` +
+                "be tracked across projections; lifecycle and criss-cross coverage disabled");
+        }
+    }
+}
+//# sourceMappingURL=surface.js.map

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

@@ -0,0 +1,162 @@
+/** The entity graph's shapes: each operation as the API tester reads it, each entity, and the model they form. */
+import type { SecurityScheme } from "../security/schemes.ts";
+import type { ResolvedSecurity } from "../security/requirements.ts";
+import type { CollectionShape } from "../collection/shape.ts";
+import type { QueryConventions } from "../conventions/types.ts";
+import type { AsyncSpec, WaitSpec } from "../extensions/async.ts";
+import type { ConsistencySpec } from "../extensions/consistency.ts";
+import type { EffectSpec } from "../extensions/effects.ts";
+import type { EntityAction } from "../extensions/entity.ts";
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { InviteSpec } from "../extensions/invite.ts";
+import type { QueryCapability } from "../extensions/query-tag.ts";
+import type { RateLimitTag } from "../extensions/flags.ts";
+import type { OperationObject } from "../types.ts";
+import type { ParamStyles } from "./parameters.ts";
+export interface OperationModel {
+    operationId: string;
+    method: string;
+    path: string;
+    route: string;
+    entity: string | null;
+    action: EntityAction | null;
+    entitySource: "tag" | "heuristic" | null;
+    invalidates: string[];
+    /** `x-consistency`: the read's staleness bound and cache bypass; null when undeclared. */
+    consistency: ConsistencySpec | null;
+    effects: EffectSpec[];
+    /** The operation declares it has no effects (`x-effects: []`): its contract is the whole promise. */
+    noEffects: boolean;
+    async: AsyncSpec | null;
+    /** Documented success response lists `text/event-stream`. Media type is the stream signal. */
+    eventStream: boolean;
+    tenantParam: string | null;
+    /** Whether tenancy was declared via `x-tenant` or merely guessed from the path. */
+    tenantSource: "tag" | "heuristic" | null;
+    pathParams: string[];
+    /**
+     * Request body properties marked `x-privileged: true`, nested ones by dotted path: only the
+     * highest-rank principal may set them.
+     */
+    privileged: string[];
+    /** The `privileged` paths the body requires: a create only the highest rank can send. */
+    privilegedRequired: string[];
+    rootParams: string[];
+    queryParamNames: string[];
+    /**
+     * Required query parameters and the value the document declares for each, an object or array
+     * kept whole. A request the document calls incomplete without one is sent with it; a parameter
+     * with no declared value is left to the caller, never invented.
+     */
+    requiredQuery: Record<string, unknown>;
+    /** Required header parameters and their declared values: never the idempotency key or a credential. */
+    requiredHeaders: Record<string, unknown>;
+    /** Required cookie parameters and their declared values. */
+    requiredCookies: Record<string, unknown>;
+    /** Each parameter's OAS style, explode and allowReserved, where they differ from the default. */
+    paramStyles: ParamStyles;
+    /**
+     * Header parameter this operation accepts as an idempotency key, when it declares one.
+     *
+     * Read straight from the document rather than from a new meta tag: an API that promises replay
+     * safety publishes the header, and the promise is what makes the property testable.
+     */
+    idempotencyHeader: string | null;
+    /** A success response declares an `ETag` header: the record's version a precondition can name. */
+    etag: boolean;
+    /** The `If-Match` header parameter the operation declares, under its declared spelling. */
+    ifMatch: string | null;
+    /** What this endpoint's query parameters and envelope mean, derived from the document. */
+    conventions: QueryConventions;
+    /** Exact status codes the document names. Ranges and `default` live in `statuses`. */
+    documentedStatuses: number[];
+    statuses: DocumentedStatuses;
+    securitySchemes: string[];
+    /** The credentials this operation needs: any one alternative, every scheme in it. */
+    security: ResolvedSecurity;
+    collection: CollectionShape | null;
+    /** `x-entity.createdIdFrom`: where a create's answer puts the made record's id. */
+    createdIdFrom: string | null;
+    /** `x-entity.recordPath`: where this operation's answer keeps the record, or a list's rows. */
+    recordPath: string | null;
+    identity: string | null;
+    /** Where `identity` came from: an `x-entity` tag, the item route's parameter, or the schema alone. */
+    identitySource: "declared" | "route" | "schema" | null;
+    query: QueryCapability | null;
+    immutable: string[];
+    generated: string[];
+    softDelete: string | null;
+    invite: InviteSpec | null;
+    wait: WaitSpec | null;
+    cost: "low" | "medium" | "high";
+    /** Declared so a matching 403 is coverage, not a seed defect. */
+    featureGate: string | null;
+    /**
+     * Declared unique column sets. `null` means the tag is absent or malformed (checks do not
+     * run). `[]` is explicit none. Non-empty lists are the sets `create.unique-conflict-rejected`
+     * and `update.unique-conflict-rejected` probe.
+     */
+    unique: string[][] | null;
+    destructive: boolean;
+    idempotent: boolean;
+    freshPrincipal: boolean;
+    cleanup: string | null;
+    rateLimit: RateLimitTag | null;
+    hasRequestBody: boolean;
+    isMutation: boolean;
+    /**
+     * Why the API tester never sends this operation, or `null` when it can: a TRACE, which fetch refuses. The
+     * operation is listed, and a check that reaches it sends nothing.
+     */
+    unsendable: string | null;
+}
+export interface EntityModel {
+    name: string;
+    identity: string | null;
+    create?: string;
+    list?: string;
+    read?: string;
+    /** Every read on this entity. `read` stays the first. */
+    reads?: string[];
+    update?: string;
+    delete?: string;
+    actions: string[];
+    invite: InviteSpec | null;
+    /** Read routes through which an instance is observable — the criss-cross matrix. */
+    readSurface: string[];
+    /** Read routes contributed by `x-invalidate` rather than by sibling inference. */
+    declaredSurface: string[];
+    tenantParams: string[];
+    trackable: boolean;
+    /** Effective unique sets for this entity (from create, else any tagged operation). */
+    unique: string[][] | null;
+}
+export interface SpecModel {
+    operations: OperationModel[];
+    byOperationId: Map<string, OperationModel>;
+    byRoute: Map<string, OperationModel>;
+    /** The untouched operation objects, keyed by id — schemas are read from here. */
+    rawOperations: Map<string, OperationObject>;
+    /** Recursive schemas the dereferenced document refers to as `testing-defs#/$defs/<name>`. */
+    defs: Record<string, Record<string, unknown>>;
+    entities: Map<string, EntityModel>;
+    roots: string[];
+    gaps: GapCollector;
+    securitySchemes: string[];
+    /** Every declared security scheme, read: where its credential goes, or why the API tester cannot send it. */
+    schemes: ReadonlyMap<string, SecurityScheme>;
+    hasAuthOperations: boolean;
+}
+/**
+ * The responses an operation documents: exact codes, `NXX` ranges, and `default`.
+ *
+ * Parsing the keys as integers read `2XX` as status 2 and dropped `default` entirely, so a
+ * document written in ranges declared nothing a real status could match.
+ */
+export interface DocumentedStatuses {
+    exact: number[];
+    /** Status classes documented as a range: 2 for `2XX`. */
+    ranges: number[];
+    default: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,3 @@
+/** The entity graph's shapes: each operation as the API tester reads it, each entity, and the model they form. */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * What a document declares that the API tester never exercises: webhooks the API sends, callbacks it makes,
+ * links to follow-up calls, and OAS 3.2 `additionalOperations`. Each becomes a gap `doctor` names,
+ * so a silent skip never reads as coverage.
+ */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { OpenApiDocument } from "../types.ts";
+import type { OperationModel } from "./types.ts";
+/**
+ * An operation the API tester lists but never sends (TRACE) is a gap under its method, and joins no entity: no
+ * lifecycle may pick it as a read or a write it would then fail to send.
+ */
+export declare function recordUnsendable(operations: readonly OperationModel[], gaps: GapCollector): void;
+/** Marks `op` never sent, for `reason`, and takes it out of every lifecycle. */
+export declare function leaveUntested(op: OperationModel, reason: string): void;
+/** Records a gap for every webhook, callback, response link and additional operation the document declares. */
+export declare function recordUnmodeled(doc: OpenApiDocument, gaps: GapCollector): void;
+//# sourceMappingURL=unmodeled.d.ts.map

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

@@ -0,0 +1,65 @@
+/**
+ * What a document declares that the API tester never exercises: webhooks the API sends, callbacks it makes,
+ * links to follow-up calls, and OAS 3.2 `additionalOperations`. Each becomes a gap `doctor` names,
+ * so a silent skip never reads as coverage.
+ */
+import { listEndpoints } from "../endpoints.js";
+/* The keys of a map the document declares; anything that is not a map declares none. */
+function keysOf(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? Object.keys(value) : [];
+}
+/* One member of an untyped object, or undefined when there is no object to read. */
+function member(value, key) {
+    return value !== null && typeof value === "object" ? value[key] : undefined;
+}
+function recordCallsOut(doc, gaps) {
+    for (const { op, operationId } of listEndpoints(doc)) {
+        for (const name of keysOf(member(op, "callbacks"))) {
+            gaps.record(operationId, "callbacks", `declares callback "${name}", a call the API makes back to a URL the request names`);
+        }
+        const responses = member(op, "responses");
+        for (const status of keysOf(responses)) {
+            for (const name of keysOf(member(member(responses, status), "links"))) {
+                gaps.record(operationId, "links", `response ${status} links "${name}" to a follow-up call the API tester does not make`);
+            }
+        }
+    }
+}
+/* OAS 3.2 methods outside the fixed Path Item fields, keyed as they are sent. */
+function recordAdditionalOperations(doc, gaps) {
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        const additional = member(item, "additionalOperations");
+        for (const method of keysOf(additional)) {
+            const id = member(member(additional, method), "operationId");
+            gaps.record(typeof id === "string" ? id : `${method} ${path}`, "additionalOperations", `declares method ${method} under additionalOperations, which the API tester does not send`);
+        }
+    }
+}
+/**
+ * An operation the API tester lists but never sends (TRACE) is a gap under its method, and joins no entity: no
+ * lifecycle may pick it as a read or a write it would then fail to send.
+ */
+export function recordUnsendable(operations, gaps) {
+    for (const op of operations) {
+        if (op.unsendable === null)
+            continue;
+        gaps.record(op.operationId, op.method, op.unsendable);
+        leaveUntested(op, op.unsendable);
+    }
+}
+/** Marks `op` never sent, for `reason`, and takes it out of every lifecycle. */
+export function leaveUntested(op, reason) {
+    op.unsendable = reason;
+    op.entity = null;
+    op.entitySource = null;
+    op.action = null;
+}
+/** Records a gap for every webhook, callback, response link and additional operation the document declares. */
+export function recordUnmodeled(doc, gaps) {
+    for (const name of keysOf(member(doc, "webhooks"))) {
+        gaps.record(`webhook ${name}`, "webhooks", "is a call the API sends to a subscriber's URL; the API tester receives no inbound call");
+    }
+    recordCallsOut(doc, gaps);
+    recordAdditionalOperations(doc, gaps);
+}
+//# sourceMappingURL=unmodeled.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Local-file `$ref`s, read into the one document so `dereference` meets only internal refs. Each
+ * file is stored once under `x-testing-external`, keyed by its path in the document's folder, and every
+ * ref to it, its own `#/` refs included, becomes a pointer there.
+ */
+import type { OpenApiDocument } from "../types.ts";
+/** Where the files a document refers to are stored, by their path in its folder. */
+export declare const EXTERNAL_KEY = "x-testing-external";
+/**
+ * Reads every file `doc`, read from `sourcePath`, refers to by relative path, recursively. A URL
+ * ref, an anchor and a ref in a fetched document stay as they are, reported as unresolved. A ref by
+ * absolute path, one resolving outside the document's folder, or one naming a missing file is
+ * the caller's to fix.
+ */
+export declare function bundleLocalRefs(doc: OpenApiDocument, sourcePath: string): Promise<OpenApiDocument>;
+//# sourceMappingURL=bundle.d.ts.map

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

@@ -0,0 +1,112 @@
+/**
+ * Local-file `$ref`s, read into the one document so `dereference` meets only internal refs. Each
+ * file is stored once under `x-testing-external`, keyed by its path in the document's folder, and every
+ * ref to it, its own `#/` refs included, becomes a pointer there.
+ */
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { UsageError } from "../../errors/usage-error.js";
+import { parseText } from "./parse.js";
+/** Where the files a document refers to are stored, by their path in its folder. */
+export const EXTERNAL_KEY = "x-testing-external";
+/**
+ * Reads every file `doc`, read from `sourcePath`, refers to by relative path, recursively. A URL
+ * ref, an anchor and a ref in a fetched document stay as they are, reported as unresolved. A ref by
+ * absolute path, one resolving outside the document's folder, or one naming a missing file is
+ * the caller's to fix.
+ */
+export async function bundleLocalRefs(doc, sourcePath) {
+    const root = await realpath(sourcePath);
+    const ctx = { files: {}, folder: dirname(root), keys: new Map(), root };
+    await rewriteRefs(ctx, doc, root);
+    if (ctx.keys.size > 0)
+        doc[EXTERNAL_KEY] = ctx.files;
+    return doc;
+}
+async function rewriteRefs(ctx, node, file) {
+    const found = { holders: [], seen: new Set() };
+    collect(found, node, "node");
+    for (const holder of found.holders)
+        holder.$ref = await rewrite(ctx, holder.$ref, file);
+}
+/* Mirrors `walk`: an `example`, a schema's `examples` array and an Example Object's `value` are data. */
+function collect(ctx, node, mode) {
+    if (node === null || typeof node !== "object" || ctx.seen.has(node))
+        return;
+    ctx.seen.add(node);
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collect(ctx, item, "node");
+        return;
+    }
+    const obj = node;
+    if (typeof obj.$ref === "string")
+        ctx.holders.push(obj);
+    for (const [key, value] of Object.entries(obj))
+        collectEntry(ctx, key, value, mode);
+}
+function collectEntry(ctx, key, value, mode) {
+    if (key === "example" || (mode === "example" && key === "value"))
+        return;
+    if (key !== "examples")
+        return collect(ctx, value, "node");
+    /* A map of Example Objects: each may be a $ref, and each one's `value` is data. */
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        for (const example of Object.values(value))
+            collect(ctx, example, "example");
+    }
+}
+/** `ref`, met in `file`, as a pointer into the bundled document; read its file when first named. */
+async function rewrite(ctx, ref, file) {
+    const hash = ref.indexOf("#");
+    const path = hash === -1 ? ref : ref.slice(0, hash);
+    const fragment = hash === -1 ? "" : ref.slice(hash + 1);
+    if (fragment !== "" && !fragment.startsWith("/"))
+        return ref;
+    if (path === "")
+        return pointer(ctx, file, fragment);
+    if (isAbsolute(path) || /^file:/i.test(path)) {
+        throw new UsageError(`testing api: ${file} refers to ${ref}, an absolute path; the API tester reads only paths relative to the document`);
+    }
+    if (/^[a-z][a-z\d+.-]*:/i.test(path))
+        return ref;
+    const target = await realOf(resolve(dirname(file), decoded(path)), ref, file);
+    const inFolder = relative(ctx.folder, target);
+    if (inFolder.split(sep)[0] === ".." || isAbsolute(inFolder)) {
+        throw new UsageError(`testing api: ${file} refers to ${ref}, which resolves outside ${ctx.folder}; the API tester reads only files in the document's folder`);
+    }
+    if (target !== ctx.root && !ctx.keys.has(target)) {
+        ctx.keys.set(target, inFolder.split(sep).join("/"));
+        const parsed = await parseText(await readFile(target, "utf8"), target);
+        ctx.files[inFolder.split(sep).join("/")] = parsed;
+        await rewriteRefs(ctx, parsed, target);
+    }
+    return pointer(ctx, target, fragment);
+}
+/** The pointer to `fragment` inside `file`: the document itself, or its entry under `EXTERNAL_KEY`. */
+function pointer(ctx, file, fragment) {
+    if (file === ctx.root)
+        return `#${fragment}`;
+    const key = ctx.keys.get(file).replace(/~/g, "~0").replace(/\//g, "~1").replace(/%/g, "%25");
+    return `#/${EXTERNAL_KEY}/${key}${fragment}`;
+}
+async function realOf(target, ref, file) {
+    try {
+        return await realpath(target);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        throw new UsageError(`testing api: ${file} refers to ${ref}, but ${target} does not exist`);
+    }
+}
+/* A ref is a URI reference: `my%20file.yaml` names "my file.yaml". A malformed escape is literal. */
+function decoded(path) {
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
+//# sourceMappingURL=bundle.js.map