@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,19 @@
+/** `x-invalidate` and `x-cleanup`: tags that name other routes, read as `METHOD /path`. */
+import { parseRouteRef } from "../routes.js";
+import { ext } from "./tag.js";
+/** `METHOD /path` as the route parser reads it, upper-cased and normalized; anything else trimmed as it is. */
+function normalizeRouteRef(ref) {
+    const route = parseRouteRef(ref);
+    return route === null ? ref.trim() : `${route.method} ${route.path}`;
+}
+export function readInvalidate(op) {
+    const raw = ext(op, "x-invalidate");
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((r) => typeof r === "string").map(normalizeRouteRef);
+}
+export function readCleanup(op) {
+    const value = ext(op, "x-cleanup");
+    return typeof value === "string" ? normalizeRouteRef(value) : null;
+}
+//# sourceMappingURL=routes.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Reads the `x-*` meta tags documented in the README.
+ *
+ * Every reader follows the same contract: explicit tag → heuristic → `null` plus a recorded
+ * gap. The API tester never silently guesses; an unresolved tag becomes a COVERAGE_GAP in the report
+ * naming the tag that would close it.
+ */
+import type { RawOf } from "../../config/types/raw.ts";
+import type { OperationObject } from "../types.ts";
+/** The operation's `key` extension as it stands; `undefined` when absent. */
+export declare function ext(op: OperationObject, key: string): unknown;
+/** The operation's `key` extension when it is an object with the fields of `T`, each unread; else `undefined`. */
+export declare function extObject<T>(op: OperationObject, key: string): RawOf<T> | undefined;
+/** The strings of a list; anything else is none. */
+export declare function strArray(value: unknown): string[];
+//# sourceMappingURL=tag.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * Reads the `x-*` meta tags documented in the README.
+ *
+ * Every reader follows the same contract: explicit tag → heuristic → `null` plus a recorded
+ * gap. The API tester never silently guesses; an unresolved tag becomes a COVERAGE_GAP in the report
+ * naming the tag that would close it.
+ */
+import { isObject } from "../tags/checks.js";
+/** The operation's `key` extension as it stands; `undefined` when absent. */
+export function ext(op, key) {
+    return op[key];
+}
+/** The operation's `key` extension when it is an object with the fields of `T`, each unread; else `undefined`. */
+export function extObject(op, key) {
+    const value = ext(op, key);
+    return isObject(value) ? value : undefined;
+}
+/** The strings of a list; anything else is none. */
+export function strArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+//# sourceMappingURL=tag.js.map

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

@@ -0,0 +1,9 @@
+/** `x-tenant` and `x-root`: the path parameters that scope an operation or must be given to it. */
+import type { Endpoint, OperationObject } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+export declare function pathParameterNames(path: string): string[];
+export declare function readTenantSource(endpoint: Endpoint): "tag" | "heuristic" | null;
+export declare function readTenantParam(endpoint: Endpoint, gaps?: GapCollector): string | null;
+/** Path parameters declared as roots — resources the API tester cannot create and must be given. */
+export declare function readRootParams(op: OperationObject): string[];
+//# sourceMappingURL=tenant.d.ts.map

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

@@ -0,0 +1,35 @@
+/** `x-tenant` and `x-root`: the path parameters that scope an operation or must be given to it. */
+import { ext } from "./tag.js";
+const TENANT_PARAM = /^(org(anization)?|tenant|workspace|account|project|app)_?(id|slug)?$/i;
+export function pathParameterNames(path) {
+    /* The pattern captures one or more characters, so every name is non-empty. */
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+export function readTenantSource(endpoint) {
+    const tag = ext(endpoint.op, "x-tenant");
+    /* `false` is a shared catalog that happens to sit under a project path. */
+    if (tag === false)
+        return null;
+    if (typeof tag === "string")
+        return "tag";
+    const guess = pathParameterNames(endpoint.path).find((name) => TENANT_PARAM.test(name));
+    return guess === undefined ? null : "heuristic";
+}
+export function readTenantParam(endpoint, gaps) {
+    const tag = ext(endpoint.op, "x-tenant");
+    if (tag === false)
+        return null;
+    if (typeof tag === "string")
+        return tag;
+    const guess = pathParameterNames(endpoint.path).find((name) => TENANT_PARAM.test(name));
+    if (guess === undefined)
+        return null;
+    gaps?.record(endpoint.operationId, "x-tenant", `assuming "${guess}" scopes this operation to a tenant, inferred from its name`);
+    return guess;
+}
+/** Path parameters declared as roots — resources the API tester cannot create and must be given. */
+export function readRootParams(op) {
+    const params = (op.parameters ?? []);
+    return params.filter((p) => p.in === "path" && p["x-root"] === true).map((p) => p.name);
+}
+//# sourceMappingURL=tenant.js.map

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

@@ -0,0 +1,20 @@
+/** `x-unique`: the column sets an entity keeps unique, for the unique-conflict checks. */
+import type { OperationObject } from "../types.ts";
+import type { GapCollector } from "./gaps.ts";
+/**
+ * `x-unique` — column sets that must stay unique.
+ *
+ * Accepted shapes:
+ * - a list of column sets (`[["email"], ["workspace_id", "slug"]]`)
+ * - `{ columns: [...] }` objects
+ * - a single `string[]` meaning one set
+ *
+ * Each set is a non-empty list of column names; empty sets are dropped. Malformed / non-array
+ * → `null` and a recorded gap (the check does not run). `[]` after filtering is explicit none
+ * (check does not run). Missing tag → `null`, no gap — unique checks do not run.
+ *
+ * Uniqueness is never inferred from 409s, unique-looking names, or JSON Schema `uniqueItems`.
+ */
+export declare function readUnique(op: OperationObject, operationId?: string, gaps?: GapCollector): string[][] | null;
+export declare function formatUniqueSets(sets: string[][] | null): string;
+//# sourceMappingURL=unique.d.ts.map

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

@@ -0,0 +1,63 @@
+/** `x-unique`: the column sets an entity keeps unique, for the unique-conflict checks. */
+import { isObject } from "../tags/checks.js";
+import { ext } from "./tag.js";
+const MALFORMED = "x-unique is not a list of column sets; unique-conflict checks will not run";
+const columns = (cols) => cols.filter((col) => col !== "");
+const allStrings = (items) => items.every((item) => typeof item === "string");
+/** `null` means the item is malformed, not an empty set. */
+function parseUniqueSet(item) {
+    if (Array.isArray(item))
+        return allStrings(item) ? columns(item) : null;
+    if (!isObject(item))
+        return null;
+    const set = item;
+    return Array.isArray(set.columns) && allStrings(set.columns) ? columns(set.columns) : null;
+}
+/**
+ * `x-unique` — column sets that must stay unique.
+ *
+ * Accepted shapes:
+ * - a list of column sets (`[["email"], ["workspace_id", "slug"]]`)
+ * - `{ columns: [...] }` objects
+ * - a single `string[]` meaning one set
+ *
+ * Each set is a non-empty list of column names; empty sets are dropped. Malformed / non-array
+ * → `null` and a recorded gap (the check does not run). `[]` after filtering is explicit none
+ * (check does not run). Missing tag → `null`, no gap — unique checks do not run.
+ *
+ * Uniqueness is never inferred from 409s, unique-looking names, or JSON Schema `uniqueItems`.
+ */
+export function readUnique(op, operationId, gaps) {
+    const raw = ext(op, "x-unique");
+    if (raw === undefined)
+        return null;
+    if (!Array.isArray(raw)) {
+        gaps?.record(operationId ?? "", "x-unique", MALFORMED);
+        return null;
+    }
+    if (raw.length === 0)
+        return [];
+    if (allStrings(raw)) {
+        const cols = columns(raw);
+        return cols.length === 0 ? [] : [cols];
+    }
+    const sets = [];
+    for (const item of raw) {
+        const parsed = parseUniqueSet(item);
+        if (parsed === null) {
+            gaps?.record(operationId ?? "", "x-unique", MALFORMED);
+            return null;
+        }
+        if (parsed.length > 0)
+            sets.push(parsed);
+    }
+    return sets;
+}
+export function formatUniqueSets(sets) {
+    if (sets === null)
+        return "—";
+    if (sets.length === 0)
+        return "(none)";
+    return sets.map((set) => `[${set.join(", ")}]`).join("; ");
+}
+//# sourceMappingURL=unique.js.map

package/dist/api/spec/grammar-overrides.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Filter and sort grammars declared in config, laid over what the document declared or the API tester inferred.
+ *
+ * The run's `query.grammar` / `query.sortGrammar` apply to every operation, and an entity's
+ * `entities.<name>.query.*` to that entity's operations, outranking the run's. A grammar config
+ * names but the API tester cannot read stops the run: config is the operator's own statement, and carrying on
+ * with another grammar would test something they did not ask for.
+ */
+import type { SpecModel } from "./graph/types.ts";
+import type { DeclaredFilterGrammar, DeclaredSortGrammar } from "../config/types/query.ts";
+export type { DeclaredFilterGrammar, DeclaredSortGrammar } from "../config/types/query.ts";
+interface DeclaredGrammars {
+    grammar?: DeclaredFilterGrammar;
+    sortGrammar?: DeclaredSortGrammar;
+}
+export interface GrammarConfig {
+    query?: DeclaredGrammars;
+    entities?: Record<string, {
+        query?: DeclaredGrammars;
+    } | undefined>;
+}
+export declare function applyGrammarOverrides(model: SpecModel, config: GrammarConfig): void;
+//# sourceMappingURL=grammar-overrides.d.ts.map

package/dist/api/spec/grammar-overrides.js

@@ -0,0 +1,70 @@
+/**
+ * Filter and sort grammars declared in config, laid over what the document declared or the API tester inferred.
+ *
+ * The run's `query.grammar` / `query.sortGrammar` apply to every operation, and an entity's
+ * `entities.<name>.query.*` to that entity's operations, outranking the run's. A grammar config
+ * names but the API tester cannot read stops the run: config is the operator's own statement, and carrying on
+ * with another grammar would test something they did not ask for.
+ */
+import { UsageError } from "../errors/usage-error.js";
+import { parseFilterGrammar } from "./render/filter-parse.js";
+import { parseSortGrammar } from "./render/sort-parse.js";
+import { SORT_PRESETS } from "./render/sort.js";
+function resolveFilter(declared, where) {
+    if (declared === "postgrest" || declared === "colon" || declared === "equality")
+        return { grammar: declared };
+    if (typeof declared !== "object" || declared === null) {
+        throw new UsageError(`${where} must be "postgrest", "colon", "equality" or a template object`);
+    }
+    const parsed = parseFilterGrammar(declared);
+    if (!parsed.ok)
+        throw new UsageError(`${where}: ${parsed.error}`);
+    return { filterGrammar: parsed.spec, grammar: "template" };
+}
+function resolveSort(declared, where) {
+    if (typeof declared === "string" && Object.hasOwn(SORT_PRESETS, declared)) {
+        return { sortGrammar: declared };
+    }
+    if (typeof declared !== "object" || declared === null) {
+        throw new UsageError(`${where} must be "dotted", "prefixed", "colon", "spaced" or a template object`);
+    }
+    const parsed = parseSortGrammar(declared);
+    if (!parsed.ok)
+        throw new UsageError(`${where}: ${parsed.error}`);
+    return { sortGrammar: "template", sortSpec: parsed.spec };
+}
+function resolve(declared, where) {
+    return {
+        ...(declared?.grammar === undefined ? {} : { filter: resolveFilter(declared.grammar, `${where}.grammar`) }),
+        ...(declared?.sortGrammar === undefined ? {} : { sort: resolveSort(declared.sortGrammar, `${where}.sortGrammar`) }),
+    };
+}
+export function applyGrammarOverrides(model, config) {
+    const global = resolve(config.query, "query");
+    const byEntity = new Map();
+    for (const [name, entity] of Object.entries(config.entities ?? {})) {
+        byEntity.set(name, resolve(entity?.query, `entities.${name}.query`));
+    }
+    for (const op of model.operations) {
+        const own = op.entity === null ? undefined : byEntity.get(op.entity);
+        const filter = own?.filter ?? global.filter;
+        const sort = own?.sort ?? global.sort;
+        if (filter !== undefined) {
+            op.conventions.grammar = filter.grammar;
+            op.conventions.grammarDeclared = true;
+            if (filter.filterGrammar === undefined)
+                delete op.conventions.filterGrammar;
+            else
+                op.conventions.filterGrammar = filter.filterGrammar;
+        }
+        if (sort !== undefined) {
+            op.conventions.sortGrammar = sort.sortGrammar;
+            op.conventions.sortDeclared = true;
+            if (sort.sortSpec === undefined)
+                delete op.conventions.sortSpec;
+            else
+                op.conventions.sortSpec = sort.sortSpec;
+        }
+    }
+}
+//# sourceMappingURL=grammar-overrides.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * Builds the entity graph — the model every scenario is planned against.
+ *
+ * The central move: `x-invalidate` is read as a graph edge, not a cache hint. Inverting it
+ * gives each entity its *read surface*, the set of projections through which an instance is
+ * observable. That set is the criss-cross matrix.
+ */
+import type { OpenApiDocument } from "../types.ts";
+import type { QueryEnvelopeNames, QueryParamNames } from "../../config/types/query.ts";
+import type { SpecModel } from "./types.ts";
+export interface BuildOptions {
+    /** Config `query.params`: the parameter each role is sent in, outranking `x-query.params`. */
+    queryParams?: QueryParamNames | undefined;
+    /** Config `query.envelope`: the field each paging fact is read from, outranking `x-query.envelope`. */
+    queryEnvelope?: QueryEnvelopeNames | undefined;
+}
+export declare function buildModel(doc: OpenApiDocument, options?: BuildOptions): SpecModel;
+//# sourceMappingURL=build.d.ts.map

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

@@ -0,0 +1,89 @@
+/**
+ * Builds the entity graph — the model every scenario is planned against.
+ *
+ * The central move: `x-invalidate` is read as a graph edge, not a cache hint. Inverting it
+ * gives each entity its *read surface*, the set of projections through which an instance is
+ * observable. That set is the criss-cross matrix.
+ */
+import { listEndpoints } from "../endpoints.js";
+import { GapCollector } from "../extensions/gaps.js";
+import { documentDefs } from "../load/defs.js";
+import { readSchemes } from "../security/schemes.js";
+import { recordDangling } from "./dangling.js";
+import { demoteNonEntities } from "./demote.js";
+import { registerOperations } from "./entities.js";
+import { separateSameNamedCollections } from "./naming.js";
+import { modelOperation } from "./operation.js";
+import { collectRoots } from "./roots.js";
+import { fallBackToSiblings, invertInvalidate, markTrackable } from "./surface.js";
+import { recordUnmodeled, recordUnsendable } from "./unmodeled.js";
+import { parseRouteRef } from "../routes.js";
+export function buildModel(doc, options = {}) {
+    const gaps = new GapCollector();
+    const endpoints = listEndpoints(doc);
+    const operations = endpoints.map((e) => modelOperation(e, { doc, gaps, queryEnvelope: options.queryEnvelope, queryParams: options.queryParams }));
+    recordUnsendable(operations, gaps);
+    const defs = documentDefs(doc);
+    recordDangling(endpoints, operations, { defs, gaps });
+    const views = demoteNonEntities(operations, gaps);
+    separateSameNamedCollections(operations);
+    /* Named once the entities have their final names: a split `member` is `org-member` here. */
+    for (const op of views) {
+        gaps.record(op.operationId, "x-entity", `returns a collection but exposes no item route, so the API tester treats "${op.entity}" as its ` +
+            "own entity. If it is a filtered view of another entity, name that entity explicitly");
+    }
+    const byOperationId = indexByOperationId(operations, gaps);
+    const byRoute = new Map(operations.map((o) => [o.route, o]));
+    const entities = buildEntities(operations, byRoute, gaps);
+    reportMissingCleanup(operations, byRoute, gaps);
+    recordUnmodeled(doc, gaps);
+    return {
+        byOperationId,
+        byRoute,
+        entities,
+        gaps,
+        hasAuthOperations: operations.some((o) => /auth|login|token|session/i.test(o.path)),
+        operations,
+        /* First wins, like `byOperationId`. */
+        rawOperations: new Map(endpoints.toReversed().map((e) => [e.operationId, e.op])),
+        defs,
+        roots: collectRoots(operations, entities),
+        securitySchemes: Object.keys(doc.components?.securitySchemes ?? {}),
+        schemes: readSchemes(doc),
+    };
+}
+/* An `x-cleanup` naming a route the document lacks removes nothing: teardown would leave its records. */
+function reportMissingCleanup(operations, byRoute, gaps) {
+    for (const op of operations) {
+        const route = op.cleanup === null ? null : parseRouteRef(op.cleanup);
+        if (route === null || byRoute.has(`${route.method} ${route.path}`))
+            continue;
+        gaps.record(op.operationId, "x-cleanup", `names "${op.cleanup}", which is not an operation in this document`);
+    }
+}
+/*
+ * Two operations sharing an id would silently become one. The first keeps the id; the other is
+ * reported, since findings, scope and `--ops` all name operations by it.
+ */
+function indexByOperationId(operations, gaps) {
+    const byOperationId = new Map();
+    for (const op of operations) {
+        const first = byOperationId.get(op.operationId);
+        if (first === undefined) {
+            byOperationId.set(op.operationId, op);
+            continue;
+        }
+        gaps.record(op.operationId, "operationId", `is declared by both ${first.route} and ${op.route}; operation ids must be unique, so ` +
+            `${op.route} is reachable only by its route`);
+    }
+    return byOperationId;
+}
+function buildEntities(operations, byRoute, gaps) {
+    const entities = new Map();
+    registerOperations(entities, operations);
+    invertInvalidate(entities, { byRoute, operations }, gaps);
+    fallBackToSiblings(entities, operations, gaps);
+    markTrackable(entities, gaps);
+    return entities;
+}
+//# sourceMappingURL=build.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * Internal `$ref`s that point at nothing, operation by operation. `dereference` reads each as a
+ * `DANGLING_KEY` node. In a schema that node is unconstrained, so validation of what it covers is
+ * vacuous and the operation carries a gap saying so. Anywhere else (a parameter, a body, a response,
+ * a header, an example, a link, a callback) the operation cannot be read safely: a missing required
+ * path parameter would make every request wrong, so the operation is left untested.
+ */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { Endpoint } from "../types.ts";
+import type { OperationModel } from "./types.ts";
+/**
+ * Records a `$ref` gap for each dangling pointer each operation reaches, and leaves an operation
+ * untested when one sits outside a schema. `operations` are `endpoints` modeled, in order.
+ */
+export declare function recordDangling(endpoints: readonly Endpoint[], operations: readonly OperationModel[], { defs, gaps }: {
+    defs: Readonly<Record<string, unknown>>;
+    gaps: GapCollector;
+}): void;
+//# sourceMappingURL=dangling.d.ts.map

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

@@ -0,0 +1,94 @@
+/**
+ * Internal `$ref`s that point at nothing, operation by operation. `dereference` reads each as a
+ * `DANGLING_KEY` node. In a schema that node is unconstrained, so validation of what it covers is
+ * vacuous and the operation carries a gap saying so. Anywhere else (a parameter, a body, a response,
+ * a header, an example, a link, a callback) the operation cannot be read safely: a missing required
+ * path parameter would make every request wrong, so the operation is left untested.
+ */
+import { DEFS_ID } from "../load/defs.js";
+import { DANGLING_KEY } from "../load/walk.js";
+import { PATH_ITEM_METHODS } from "../methods.js";
+import { leaveUntested } from "./unmodeled.js";
+const DEF_PREFIX = `${DEFS_ID}#/$defs/`;
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/* A node of document structure: a dangling one is recorded, any other is read by `visit`. */
+function at(found, node, visit) {
+    if (!isRecord(node))
+        return;
+    const pointer = node[DANGLING_KEY];
+    if (typeof pointer === "string")
+        found.structure.add(pointer);
+    else
+        visit(found, node);
+}
+/* Every entry of a map or list of structure nodes. */
+function each(found, nodes, visit) {
+    if (nodes !== null && typeof nodes === "object")
+        for (const node of Object.values(nodes))
+            at(found, node, visit);
+}
+const leaf = () => undefined;
+/* A schema and everything under it, recursive definitions included. */
+function schema(found, node) {
+    if (node === null || typeof node !== "object" || found.seen.has(node))
+        return;
+    found.seen.add(node);
+    const record = node;
+    const pointer = record[DANGLING_KEY];
+    if (typeof pointer === "string")
+        found.schema.add(pointer);
+    const ref = record["$ref"];
+    if (typeof ref === "string" && ref.startsWith(DEF_PREFIX))
+        schema(found, found.defs[ref.slice(DEF_PREFIX.length)]);
+    for (const value of Object.values(node))
+        schema(found, value);
+}
+const media = (found, node) => {
+    schema(found, node["schema"]);
+    schema(found, node["itemSchema"]);
+    each(found, node["examples"], leaf);
+    each(found, node["encoding"], (inner, encoding) => each(inner, encoding["headers"], parameter));
+};
+/* A Parameter Object, or a Header Object, which has the same shape without a name. */
+const parameter = (found, node) => {
+    schema(found, node["schema"]);
+    each(found, node["content"], media);
+    each(found, node["examples"], leaf);
+};
+const response = (found, node) => {
+    each(found, node["headers"], parameter);
+    each(found, node["content"], media);
+    each(found, node["links"], leaf);
+};
+const pathItem = (found, node) => {
+    each(found, node["parameters"], parameter);
+    for (const method of PATH_ITEM_METHODS)
+        at(found, node[method], operation);
+};
+const operation = (found, node) => {
+    each(found, node["parameters"], parameter);
+    at(found, node["requestBody"], (inner, body) => each(inner, body["content"], media));
+    each(found, node["responses"], response);
+    each(found, node["callbacks"], (inner, callback) => each(inner, callback, pathItem));
+};
+/**
+ * Records a `$ref` gap for each dangling pointer each operation reaches, and leaves an operation
+ * untested when one sits outside a schema. `operations` are `endpoints` modeled, in order.
+ */
+export function recordDangling(endpoints, operations, { defs, gaps }) {
+    endpoints.forEach((endpoint, index) => {
+        const found = { defs, schema: new Set(), seen: new Set(), structure: new Set() };
+        operation(found, endpoint.op);
+        const op = operations[index];
+        for (const pointer of found.schema) {
+            gaps.record(op.operationId, "$ref", `$ref ${pointer} points at nothing; the API tester reads that schema as unconstrained`);
+        }
+        for (const pointer of found.structure) {
+            gaps.record(op.operationId, "$ref", `$ref ${pointer} points at nothing; the API tester leaves this operation untested`);
+        }
+        const [first] = found.structure;
+        if (first !== undefined && op.unsendable === null)
+            leaveUntested(op, `$ref ${first} points at nothing`);
+    });
+}
+//# sourceMappingURL=dangling.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * The naming heuristic cannot tell a collection from a verb: `POST /tables/{id}/duplicate` and
+ * `POST /tables` are the same shape. The document itself settles it — a noun names an entity
+ * only if the API exposes an *item route* for it (`.../<noun>/{param}`), or if a GET on the
+ * collection returns a collection-shaped body.
+ *
+ * Everything else is an action on the nearest enclosing entity. Without this pass a spec with
+ * 5 entities models as 24, and every spurious one drags a full lifecycle plan behind it.
+ */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { OperationModel } from "./types.ts";
+/** Demotes operations that belong to no entity. Returns the collection-shaped views kept as their own entity. */
+export declare function demoteNonEntities(operations: OperationModel[], gaps: GapCollector): OperationModel[];
+//# sourceMappingURL=demote.d.ts.map

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

@@ -0,0 +1,94 @@
+/**
+ * The naming heuristic cannot tell a collection from a verb: `POST /tables/{id}/duplicate` and
+ * `POST /tables` are the same shape. The document itself settles it — a noun names an entity
+ * only if the API exposes an *item route* for it (`.../<noun>/{param}`), or if a GET on the
+ * collection returns a collection-shaped body.
+ *
+ * Everything else is an action on the nearest enclosing entity. Without this pass a spec with
+ * 5 entities models as 24, and every spurious one drags a full lifecycle plan behind it.
+ */
+import { singularize } from "../extensions/entity.js";
+import { isParamSegment, segmentsOf } from "./segments.js";
+/**
+ * Whether the final segment reads as a verb rather than a noun — `/pet/findByStatus`,
+ * `/reports/exportAll`, `/users/searchByEmail`.
+ *
+ * Such a segment names an operation, not a collection, even though it returns a collection. Left
+ * alone it becomes an entity called "findbystatus", which is both untestable and noise in the
+ * report.
+ */
+const VERB_PREFIX = /^(find|search|query|list|get|fetch|count|export|import|download|upload|bulk|batch|lookup|resolve|mine|me|all|current|latest|recent|active|archived|default|summary|stats?|statistics|history|preview)([A-Z_-]|$)/;
+/** Demotes operations that belong to no entity. Returns the collection-shaped views kept as their own entity. */
+export function demoteNonEntities(operations, gaps) {
+    const views = [];
+    const nouns = nounsWithItemRoute(operations);
+    const kept = keptCollections(operations, nouns);
+    for (const op of operations) {
+        if (op.entity === null || op.entitySource === "tag" || nouns.has(op.entity))
+            continue;
+        if (op.action === "create" && kept.has(`${op.entity}\u0000${op.path}`))
+            continue;
+        if (isView(op)) {
+            /* A collection-shaped GET with no item route is usually a named view of another
+             * entity (`/table-templates/mine`). The API tester cannot know which, so it says so. */
+            views.push(op);
+            continue;
+        }
+        demote(op, nouns, gaps);
+    }
+    return views;
+}
+/** Nouns the API exposes an item route for: `<noun>/{param}`. */
+function nounsWithItemRoute(operations) {
+    const nouns = new Set();
+    for (const op of operations) {
+        const segments = segmentsOf(op.path);
+        for (let i = 1; i < segments.length; i++) {
+            const seg = segments[i];
+            const prev = segments[i - 1];
+            if (isParamSegment(seg) && !isParamSegment(prev))
+                nouns.add(singularize(prev));
+        }
+    }
+    return nouns;
+}
+/**
+ * A noun kept for its collection GET keeps the create posted to the same collection: the
+ * decision is per noun, so an entity is never left listable but not creatable.
+ */
+function keptCollections(operations, nouns) {
+    return new Set(operations
+        .filter((op) => op.entity !== null && op.entitySource !== "tag" && !nouns.has(op.entity) && isView(op))
+        .map((op) => `${op.entity}\u0000${op.path}`));
+}
+function isView(op) {
+    return op.method === "GET" && op.collection !== null && !isVerbPhrase(op.path);
+}
+/** Makes `op` an action on its nearest enclosing entity, or on none. */
+function demote(op, nouns, gaps) {
+    const parent = enclosingEntity(op.path, nouns);
+    if (parent === null) {
+        gaps.record(op.operationId, "x-entity", `"${op.path}" names no collection with an item route and sits under none, so it belongs ` +
+            "to no entity and gets no lifecycle coverage. Name its entity with x-entity");
+    }
+    op.entity = parent;
+    op.action = parent === null ? null : "action";
+}
+/* Asked only of a heuristic entity outside `nounsWithItemRoute`, which was read off a trailing literal segment. */
+function isVerbPhrase(path) {
+    return VERB_PREFIX.test(segmentsOf(path).at(-1));
+}
+/** Nearest ancestor segment in the path that names a real entity. */
+function enclosingEntity(path, entities) {
+    const segments = segmentsOf(path);
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const seg = segments[i];
+        if (isParamSegment(seg))
+            continue;
+        const name = singularize(seg);
+        if (entities.has(name))
+            return name;
+    }
+    return null;
+}
+//# sourceMappingURL=demote.js.map

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

@@ -0,0 +1,7 @@
+/** Entities gathered from the operations that name them, each with its lifecycle operations. */
+import type { EntityModel, OperationModel } from "./types.ts";
+/** Files every operation that names an entity and an action under that entity. */
+export declare function registerOperations(entities: Map<string, EntityModel>, operations: readonly OperationModel[]): void;
+/** The entity called `name`, created empty the first time it is named. */
+export declare function entityNamed(entities: Map<string, EntityModel>, name: string): EntityModel;
+//# sourceMappingURL=entities.d.ts.map