@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/report/console/catalog.js

@@ -0,0 +1,73 @@
+import { describeFilterGrammar } from "../../spec/render/filter-describe.js";
+import { mergeQueryCapabilities } from "../../spec/query/merge.js";
+import { filterIsGuess, sendableCapabilities } from "../../spec/query/sendable.js";
+import { describeSortGrammar } from "../../spec/render/sort-parse.js";
+import { catalogCheckPreview } from "./catalog-checks.js";
+import { listOperation, sortedEntities } from "./describe.js";
+/** The capabilities a list was given by name in config rather than declared inline. */
+function harvested(caps) {
+    return [
+        caps.filterableFrom === undefined ? "" : "filterableFrom",
+        caps.sortableFrom === undefined ? "" : "sortableFrom",
+        caps.searchableFrom === undefined ? "" : "searchableFrom",
+        caps.selectableFrom === undefined ? "" : "selectableFrom",
+    ].filter(Boolean);
+}
+/** The capabilities that are there only when declared, in the order the catalog lists them. */
+function declaredLimits(caps) {
+    return {
+        ...(caps.operators === undefined ? {} : { operators: caps.operators }),
+        ...(caps.operatorsByType === undefined ? {} : { operatorsByType: caps.operatorsByType }),
+        ...(caps.identityFilter === undefined ? {} : { identityFilter: caps.identityFilter }),
+        ...(caps.emptyIn === undefined ? {} : { emptyIn: caps.emptyIn }),
+        ...(caps.maxInValues === undefined ? {} : { maxInValues: caps.maxInValues }),
+        ...(caps.maxFilterConditions === undefined ? {} : { maxFilterConditions: caps.maxFilterConditions }),
+        ...(caps.searchModes === undefined ? {} : { searchModes: caps.searchModes }),
+        ...(caps.searchEmpty === undefined ? {} : { searchEmpty: caps.searchEmpty }),
+        ...(caps.sort === undefined ? {} : { sort: caps.sort }),
+        ...(caps.select === undefined ? {} : { select: caps.select }),
+    };
+}
+/** One entity's catalog row: from its list operation and capabilities, with its name and hook as given. */
+function catalogRow(listOp, caps, { entity, hook }) {
+    const { filterGrammar, sortSpec } = listOp.conventions;
+    return {
+        aliases: caps.aliases,
+        checks: catalogCheckPreview(caps, listOp, caps.source),
+        ...(filterGrammar === undefined ? {} : { grammar: describeFilterGrammar(filterGrammar) }),
+        ...(sortSpec === undefined ? {} : { sortGrammar: describeSortGrammar(sortSpec) }),
+        entity,
+        filterable: caps.filterable,
+        harvest: harvested(caps),
+        hook,
+        searchable: caps.searchable,
+        selectable: caps.selectable,
+        sortable: caps.sortable,
+        source: caps.source,
+        ...declaredLimits(caps),
+    };
+}
+/** Per listable entity, the query capabilities document and config together give its list. */
+export function entityQueryCatalogs(model, config) {
+    const unknownEntities = Object.keys(config?.entities ?? {}).filter((name) => !model.entities.has(name));
+    const hook = config?.hooks?.resolveQueryCapabilities !== undefined;
+    const catalogs = [];
+    for (const entity of sortedEntities(model)) {
+        if (entity.list === undefined)
+            continue;
+        const listOp = listOperation(model, entity.list);
+        const entityQuery = config?.entities?.[entity.name]?.query;
+        const sources = {
+            tag: listOp.query,
+            ...(config?.query === undefined ? {} : { global: config.query }),
+            ...(entityQuery === undefined ? {} : { entity: entityQuery }),
+        };
+        const merged = mergeQueryCapabilities({ ...sources, itemSchema: listOp.collection?.itemSchema ?? null });
+        /* What the run sends: only what a declared parameter can carry. A configured hook is asked at run
+         * time, and whatever it answers is no guess. */
+        const caps = sendableCapabilities(merged, listOp, filterIsGuess(sources, { ...merged, hook })).capabilities;
+        catalogs.push(catalogRow(listOp, caps, { entity: entity.name, hook }));
+    }
+    return { catalogs, unknownEntities };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/api/report/console/describe.d.ts

@@ -0,0 +1,27 @@
+import type { EntityModel, OperationModel, SpecModel } from "../../spec/graph/types.ts";
+/** A declared grammar, described, for one entity's list. */
+export interface DeclaredGrammar {
+    entity: string;
+    filter?: string;
+    sort?: string;
+}
+/** `value` of `total` as a bar `width` cells wide; an empty total draws an empty rule. */
+export declare function bar(value: number, total: number, width?: number): string;
+/** The lifecycle an entity has, as `CLRUD` with a dot for each missing operation. */
+export declare function lifecycleGlyphs(entity: EntityModel): string;
+/** How an invite is accepted: by following its link, or by posting its token. */
+export declare function inviteAcceptMode(spec: NonNullable<EntityModel["invite"]>): string;
+/** An entity that declares an invite. */
+export type InvitingEntity = EntityModel & {
+    invite: NonNullable<EntityModel["invite"]>;
+};
+export declare function hasInvite(entity: EntityModel): entity is InvitingEntity;
+/** The entities sorted by name, less those the auth flow owns: what `plan` and `doctor` print, in order. */
+export declare function sortedEntities(model: SpecModel, authCreates?: ReadonlySet<string>): EntityModel[];
+/** The model's entities in document order, less those the auth flow owns, as a run leaves them out. */
+export declare function modeledEntities(model: SpecModel, authCreates: ReadonlySet<string>): EntityModel[];
+/** The operation that lists an entity. Its id is an operation's own, so the model holds it. */
+export declare function listOperation(model: SpecModel, list: string): OperationModel;
+/** The grammars a document or config declared, per entity, as `plan` and `doctor` print them. */
+export declare function declaredGrammars(model: SpecModel): DeclaredGrammar[];
+//# sourceMappingURL=describe.d.ts.map

package/dist/api/report/console/describe.js

@@ -0,0 +1,58 @@
+import { authOwnedReason } from "../../runtime/scope/entities.js";
+import { describeFilterGrammar } from "../../spec/render/filter-describe.js";
+import { describeSortGrammar } from "../../spec/render/sort-parse.js";
+/** `value` of `total` as a bar `width` cells wide; an empty total draws an empty rule. */
+export function bar(value, total, width = 24) {
+    if (total === 0)
+        return "─".repeat(width);
+    const filled = Math.round((value / total) * width);
+    return "█".repeat(filled) + "░".repeat(width - filled);
+}
+/** The lifecycle an entity has, as `CLRUD` with a dot for each missing operation. */
+export function lifecycleGlyphs(entity) {
+    const slots = [
+        ["C", entity.create],
+        ["L", entity.list],
+        ["R", entity.read],
+        ["U", entity.update],
+        ["D", entity.delete],
+    ];
+    return slots.map(([letter, opId]) => (opId === undefined ? "·" : letter)).join("");
+}
+/** How an invite is accepted: by following its link, or by posting its token. */
+export function inviteAcceptMode(spec) {
+    if (spec.acceptFrom === "link")
+        return "GET-link (x-invite.acceptFrom: link)";
+    return `JSON token → ${spec.accept}`;
+}
+export function hasInvite(entity) {
+    return entity.invite !== null;
+}
+/** The entities sorted by name, less those the auth flow owns: what `plan` and `doctor` print, in order. */
+export function sortedEntities(model, authCreates = new Set()) {
+    return modeledEntities(model, authCreates).sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The model's entities in document order, less those the auth flow owns, as a run leaves them out. */
+export function modeledEntities(model, authCreates) {
+    return [...model.entities.values()].filter((entity) => authOwnedReason(entity, model, authCreates) === null);
+}
+/** The operation that lists an entity. Its id is an operation's own, so the model holds it. */
+export function listOperation(model, list) {
+    return model.byOperationId.get(list);
+}
+/** The grammars a document or config declared, per entity, as `plan` and `doctor` print them. */
+export function declaredGrammars(model) {
+    return sortedEntities(model).flatMap((entity) => {
+        if (entity.list === undefined)
+            return [];
+        const { conventions } = listOperation(model, entity.list);
+        const filter = conventions.filterGrammar === undefined ? undefined : describeFilterGrammar(conventions.filterGrammar);
+        const sort = conventions.sortSpec === undefined ? undefined : describeSortGrammar(conventions.sortSpec);
+        if (filter === undefined && sort === undefined)
+            return [];
+        return [
+            { entity: entity.name, ...(filter === undefined ? {} : { filter }), ...(sort === undefined ? {} : { sort }) },
+        ];
+    });
+}
+//# sourceMappingURL=describe.js.map

package/dist/api/report/console/doctor-facts.d.ts

@@ -0,0 +1,61 @@
+import type { Hooks } from "../../config/types/hooks.ts";
+import type { Gap } from "../../spec/extensions/gaps.ts";
+import type { EntityModel, SpecModel } from "../../spec/graph/types.ts";
+import { type BypassGroup } from "./bypass.ts";
+import { type CatalogConfig, type QueryCatalog } from "./catalog.ts";
+import { type InvitingEntity } from "./describe.ts";
+import { type Roots } from "./roots.ts";
+import { type SecurityCredentials, type SecurityFacts } from "./security.ts";
+export interface DoctorConfig extends CatalogConfig {
+    /** Operations config `allow` took out of the document. */
+    allowRemoved?: string[];
+    /** Operations the config's security recipes send: neither their gaps nor the entities they own are reported. */
+    authCreates?: ReadonlySet<string>;
+    /** The config's recipes and principals: with them, an operation no principal can send blocks. */
+    credentials?: SecurityCredentials;
+    hooks?: Pick<Hooks, "resolveQueryCapabilities" | "resolvePathValue">;
+    /** The config's `cache.bypass`; default true. */
+    cacheBypass?: boolean;
+}
+/** What `doctor` found in a document, before it is printed as text or JSON. */
+export interface DoctorFacts {
+    entities: EntityModel[];
+    /** Entities a run seeds and checks, by the answer the run itself gives (`untestableEntityReason`). */
+    testable: EntityModel[];
+    /** Every other entity, and why a run cannot test it. */
+    untestable: Array<{
+        entity: string;
+        reason: string;
+    }>;
+    /** Entities with an identity and a read. */
+    trackable: EntityModel[];
+    /** Testable entities with a list: the ones query checks can run on. */
+    listable: EntityModel[];
+    /** The document's gaps, less those on an operation a recipe sends: a sign-in call is no entity to tag. */
+    gaps: Gap[];
+    gapsByTag: Map<string, Gap[]>;
+    /**
+     * Untestable entities, plus one when a root has to be supplied, plus each operation the config's
+     * principals cannot send. Non-zero exits 1.
+     */
+    blocking: number;
+    featureGates: Array<{
+        operationId: string;
+        featureGate: string | null;
+    }>;
+    uniqueConstraints: Array<{
+        entity: string;
+        unique: EntityModel["unique"];
+    }>;
+    inviting: InvitingEntity[];
+    catalogs: QueryCatalog[];
+    unknownEntities: string[];
+    security: SecurityFacts;
+    /** The document's roots: those the config supplies, and those a run would still lack. */
+    roots: Roots;
+    /** The cache bypass each read is sent with. */
+    bypass: BypassGroup[];
+}
+/** Everything `doctor` reports on, gathered once for both its text and its JSON. */
+export declare function doctorFacts(model: SpecModel, config?: DoctorConfig): DoctorFacts;
+//# sourceMappingURL=doctor-facts.d.ts.map

package/dist/api/report/console/doctor-facts.js

@@ -0,0 +1,50 @@
+import { untestableEntityReason } from "../../runtime/scope/entities.js";
+import { bypassGroups } from "./bypass.js";
+import { entityQueryCatalogs } from "./catalog.js";
+import { hasInvite, sortedEntities } from "./describe.js";
+import { rootsOf } from "./roots.js";
+import { securityFacts } from "./security.js";
+function gapsByTag(gaps) {
+    const byTag = new Map();
+    for (const gap of gaps) {
+        const list = byTag.get(gap.tag) ?? [];
+        list.push(gap);
+        byTag.set(gap.tag, list);
+    }
+    return byTag;
+}
+/** Everything `doctor` reports on, gathered once for both its text and its JSON. */
+export function doctorFacts(model, config) {
+    const authCreates = config?.authCreates ?? new Set();
+    const entities = sortedEntities(model, authCreates);
+    const gaps = model.gaps.gaps.filter((gap) => !authCreates.has(gap.operationId));
+    const untestable = entities.flatMap((entity) => {
+        const reason = untestableEntityReason(entity, model, authCreates);
+        return reason === null ? [] : [{ entity: entity.name, reason }];
+    });
+    const testable = entities.filter((entity) => !untestable.some((row) => row.entity === entity.name));
+    const security = securityFacts(model, config?.credentials);
+    const roots = rootsOf(model, config ?? {});
+    return {
+        bypass: bypassGroups(model, config?.cacheBypass ?? true),
+        blocking: untestable.length + (roots.required.length > 0 ? 1 : 0) + security.blocking,
+        entities,
+        featureGates: model.operations
+            .filter((op) => op.featureGate !== null)
+            .map((op) => ({ operationId: op.operationId, featureGate: op.featureGate })),
+        gaps,
+        gapsByTag: gapsByTag(gaps),
+        inviting: entities.filter(hasInvite),
+        listable: testable.filter((e) => e.list !== undefined),
+        testable,
+        trackable: entities.filter((e) => e.trackable && e.readSurface.length > 0),
+        uniqueConstraints: entities
+            .filter((entity) => entity.unique !== null)
+            .map((entity) => ({ entity: entity.name, unique: entity.unique })),
+        roots,
+        security,
+        untestable,
+        ...entityQueryCatalogs(model, config),
+    };
+}
+//# sourceMappingURL=doctor-facts.js.map

package/dist/api/report/console/doctor-notes.d.ts

@@ -0,0 +1,12 @@
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { DoctorFacts } from "./doctor-facts.ts";
+/** Per listable entity, what its list can be queried by and which query checks that lets run. */
+export declare function catalogLines(facts: DoctorFacts): string[];
+/** Where each operation's answer keeps its record and the id of what it made, as declared. */
+export declare function envelopeLines(model: SpecModel): string[];
+/**
+ * A document that secures its operations but offers no way to obtain a credential: the config's
+ * recipes must say how. One that declares no security leaves the anonymous probes nothing to judge.
+ */
+export declare function authLines(model: SpecModel): string[];
+//# sourceMappingURL=doctor-notes.d.ts.map

package/dist/api/report/console/doctor-notes.js

@@ -0,0 +1,77 @@
+import { block } from "./doctor-text.js";
+/** The declared limits of a catalog row, as `key=value` pairs. */
+function catalogExtras(row) {
+    const pairs = [
+        ["identityFilter", row.identityFilter],
+        ["emptyIn", row.emptyIn],
+        ["maxInValues", row.maxInValues],
+        ["maxFilterConditions", row.maxFilterConditions],
+        ["searchEmpty", row.searchEmpty],
+        ["searchModes", row.searchModes?.join(",")],
+        ["sort.nulls", row.sort?.nulls?.join(",")],
+        ["sort.maxKeys", row.sort?.maxKeys],
+        ["defaultOrder", row.sort?.defaultOrder],
+        ["stableTiebreak", row.sort?.stableTiebreak],
+        ["select.unknown", row.select?.unknown],
+        ["select.nested", row.select?.nested],
+    ];
+    return pairs.filter(([, value]) => value !== undefined).map(([key, value]) => `${key}=${String(value)}`);
+}
+function catalogRowLines(row) {
+    const ops = row.operators === undefined ? "implicit eq/neq/gt/gte/lt/lte/like" : row.operators.join(",");
+    const extras = catalogExtras(row);
+    return [
+        `    ${row.entity}  source=${row.source}${row.hook ? " +hook" : ""}${row.harvest.length > 0 ? ` harvest=${row.harvest.join(",")}` : ""}`,
+        ...(row.grammar === undefined ? [] : [`      grammar     ${row.grammar}`]),
+        ...(row.sortGrammar === undefined ? [] : [`      sort        ${row.sortGrammar}`]),
+        `      filterable  ${row.filterable.map((field) => field.field).join(", ") || "—"}  ops ${ops}`,
+        `      sortable    ${row.sortable.map((field) => field.field).join(", ") || "—"}`,
+        `      searchable  ${row.searchable.join(", ") || "—"}`,
+        `      selectable  ${row.selectable.join(", ") || "—"}`,
+        ...(extras.length === 0 ? [] : [`      ${extras.join("  ")}`]),
+        row.checks.length > 0
+            ? `      will apply  ${row.checks.join(", ")}`
+            : "      will apply  (none of the declared-or-skip catalog checks)",
+    ];
+}
+/** Per listable entity, what its list can be queried by and which query checks that lets run. */
+export function catalogLines(facts) {
+    return block("  query catalog (declared or skip — missing capability does not apply)", facts.catalogs.flatMap(catalogRowLines));
+}
+/** Where each operation's answer keeps its record and the id of what it made, as declared. */
+export function envelopeLines(model) {
+    const located = model.operations
+        .filter((op) => op.recordPath !== null || op.createdIdFrom !== null)
+        .sort((a, b) => a.operationId.localeCompare(b.operationId));
+    return block("  record envelopes (x-entity.recordPath / createdIdFrom)", located.map((op) => {
+        const parts = [
+            op.recordPath === null ? null : `record ${op.recordPath}`,
+            op.createdIdFrom === null ? null : `created id ${op.createdIdFrom}`,
+        ].filter((part) => part !== null);
+        return `    ${op.operationId.padEnd(28)} ${parts.join("  ")}`;
+    }));
+}
+/**
+ * A document that secures its operations but offers no way to obtain a credential: the config's
+ * recipes must say how. One that declares no security leaves the anonymous probes nothing to judge.
+ */
+export function authLines(model) {
+    if (model.securitySchemes.length === 0) {
+        return [
+            "  auth",
+            "    the document declares no security scheme; if the API needs a credential, declare it with overlay.securitySchemes and overlay.security (testing api init writes the stub)",
+            "",
+        ];
+    }
+    if (model.hasAuthOperations)
+        return [];
+    return [
+        "  auth",
+        `    document declares ${model.securitySchemes.map((s) => `"${s}"`).join(", ")} but contains no`,
+        "    operation for obtaining a credential. No generic client can bootstrap from",
+        "    this spec. Add a security.<scheme> recipe (login, static, mint, hook or oauth2)",
+        "    to the config for each scheme the document declares.",
+        "",
+    ];
+}
+//# sourceMappingURL=doctor-notes.js.map

package/dist/api/report/console/doctor-text.d.ts

@@ -0,0 +1,12 @@
+import type { SpecModel } from "../../spec/graph/types.ts";
+import type { DoctorConfig, DoctorFacts } from "./doctor-facts.ts";
+/** A titled block of rows, each already indented, and a blank line; nothing when there are no rows. */
+export declare function block(title: string, rows: string[]): string[];
+/** What `allow` removed, and how many entities a run can test and list. */
+export declare function summaryLines(facts: DoctorFacts, config?: DoctorConfig): string[];
+export declare function tagLines(model: SpecModel, facts: DoctorFacts): string[];
+/** Entities a run cannot test or list, and the roots it needs supplied. */
+export declare function entityLines(facts: DoctorFacts): string[];
+/** Feature gates, unique constraints, invites, and config entities the document does not have. */
+export declare function declarationLines(facts: DoctorFacts): string[];
+//# sourceMappingURL=doctor-text.d.ts.map

package/dist/api/report/console/doctor-text.js

@@ -0,0 +1,68 @@
+import { formatUniqueSets } from "../../spec/extensions/unique.js";
+import { bypassRows } from "./bypass.js";
+import { bar, inviteAcceptMode } from "./describe.js";
+import { declaredTags, TAG_SHARPENS, TAG_UNLOCKS } from "./tags.js";
+/** A titled block of rows, each already indented, and a blank line; nothing when there are no rows. */
+export function block(title, rows) {
+    return rows.length === 0 ? [] : [title, ...rows, ""];
+}
+/** What `allow` removed, and how many entities a run can test and list. */
+export function summaryLines(facts, config) {
+    const { entities, testable, listable } = facts;
+    const lines = [""];
+    if (config?.allowRemoved !== undefined) {
+        const removed = config.allowRemoved;
+        lines.push(`  allow      ${removed.length} operation${removed.length === 1 ? "" : "s"} removed` +
+            (removed.length === 0 ? "" : `: ${removed.join(", ")}`));
+    }
+    lines.push(`  testable   ${bar(testable.length, entities.length)}  ${testable.length}/${entities.length} ` +
+        "entities a run can seed and check");
+    lines.push(`  listable   ${bar(listable.length, entities.length)}  ${listable.length}/${entities.length} ` +
+        (listable.length === 0
+            ? "entities have a list — query checks will not run"
+            : "entities have a list, so query checks can run"));
+    lines.push("");
+    return lines;
+}
+/*
+ * What the missing tags cost, in checks. A gap list tells an author what the API tester could not read;
+ * this tells them what they get for fixing it, which is the only form of the message anyone
+ * acts on.
+ */
+export function tagLines(model, facts) {
+    const declared = declaredTags(model);
+    const locked = Object.entries(TAG_UNLOCKS).filter(([tag]) => !declared.has(tag));
+    const lockedChecks = locked.reduce((sum, [, checks]) => sum + checks.length, 0);
+    const applies = {
+        "x-query": facts.listable.length > 0,
+        "x-tenant": model.operations.some((op) => op.tenantSource !== null),
+    };
+    const vague = Object.entries(TAG_SHARPENS).filter(([tag]) => !declared.has(tag) && applies[tag]);
+    return [
+        ...block(`  ${lockedChecks} check(s) cannot run against this document`, locked.map(([tag, checks]) => `    ${tag.padEnd(16)} would enable ${checks.join(", ")}`)),
+        ...block("  running, but on inferred information", vague.map(([tag, effect]) => `    ${tag.padEnd(16)} ${effect}`)),
+    ];
+}
+/** Entities a run cannot test or list, and the roots it needs supplied. */
+export function entityLines(facts) {
+    const itemOnly = facts.testable.filter((e) => e.list === undefined);
+    return [
+        ...block("  not testable", facts.untestable.map(({ entity, reason }) => `    ${entity.padEnd(20)} ${reason}`)),
+        /* A testable entity with no list is read by its item route, its root read, or as the caller. */
+        ...block("  no list — query, pagination and count checks will not run", itemOnly.map((entity) => `    ${entity.name.padEnd(20)} ${entity.read ?? entity.readSurface[0]}`)),
+        ...block("  roots required in config (no create operation in this document)", facts.roots.required.map((root) => `    ${root}`)),
+        ...block("  roots the config supplies", facts.roots.supplied.map(({ root, by }) => `    ${root.padEnd(20)} ${by}`)),
+        ...block("  ids no operation creates — their operations run once a flow or hooks.resolvePathValue yields one", facts.roots.unmade.map((root) => `    ${root}`)),
+    ];
+}
+/** Feature gates, unique constraints, invites, and config entities the document does not have. */
+export function declarationLines(facts) {
+    return [
+        ...block("  feature gates — a matching 403 is a coverage gap, not a fail", facts.featureGates.map((gate) => `    ${gate.operationId.padEnd(28)} x-feature-gate: ${gate.featureGate}`)),
+        ...block("  unique constraints — a 409 on a duplicate of these columns is a pass", facts.uniqueConstraints.map((row) => `    ${row.entity.padEnd(28)} x-unique: ${formatUniqueSets(row.unique)}`)),
+        ...block("  invite — accept mode", facts.inviting.map((entity) => `    ${entity.name.padEnd(28)} ${inviteAcceptMode(entity.invite)}`)),
+        ...block("  cache bypass the API tester sends on reads", bypassRows(facts.bypass)),
+        ...block("  config.entities names that do not match the document (ignored)", facts.unknownEntities.map((name) => `    ${name}`)),
+    ];
+}
+//# sourceMappingURL=doctor-text.js.map

package/dist/api/report/console/doctor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `doctor` is the adoption surface: it reports what the API tester cannot test against this spec and names
+ * the meta tag that would close each gap. A backend team's path to full coverage is to run it
+ * and work the list down.
+ */
+import type { SpecModel } from "../../spec/graph/types.ts";
+import { type DoctorConfig } from "./doctor-facts.ts";
+/** How `doctor` reports: the refs the API tester could not follow, JSON or text, and the config beside it. */
+export interface DoctorOptions {
+    /** Refs to other files, which the API tester did not follow. */
+    externalRefs?: string[];
+    /** Internal refs that point at nothing. */
+    danglingRefs?: string[];
+    asJson?: boolean;
+    config?: DoctorConfig | undefined;
+    /** Variables the config names that are not set: a note, never a block. Given only with a config. */
+    unsetEnv?: string[] | undefined;
+}
+/** The note for variables a config names that are not set, or nothing when every one is. */
+export declare function unsetEnvLines(unsetEnv: readonly string[] | undefined): string[];
+/** `testing api doctor`: what the API tester can and cannot test in the document, as text or JSON, and how much of it blocks a run. */
+export declare function doctor(model: SpecModel, options?: DoctorOptions): {
+    text: string;
+    blocking: number;
+};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/api/report/console/doctor.js

@@ -0,0 +1,78 @@
+/**
+ * `doctor` is the adoption surface: it reports what the API tester cannot test against this spec and names
+ * the meta tag that would close each gap. A backend team's path to full coverage is to run it
+ * and work the list down.
+ */
+import { doctorFacts } from "./doctor-facts.js";
+import { authLines, catalogLines, envelopeLines } from "./doctor-notes.js";
+import { declarationLines, entityLines, summaryLines, tagLines } from "./doctor-text.js";
+import { danglingRefLines, externalRefLines, gapLines } from "./gaps.js";
+import { rootsJson } from "./roots.js";
+import { securityJson } from "./security.js";
+import { securityLines } from "./security-text.js";
+/** The note for variables a config names that are not set, or nothing when every one is. */
+export function unsetEnvLines(unsetEnv) {
+    if (unsetEnv === undefined || unsetEnv.length === 0)
+        return [];
+    return [`  ${"env".padEnd(11)}${unsetEnv.join(", ")} not set — a run stops until they are`, ""];
+}
+function doctorJson({ config, danglingRefs, externalRefs, facts, unsetEnv }) {
+    return `${JSON.stringify({
+        blocking: facts.blocking,
+        cacheBypass: facts.bypass,
+        entities: facts.entities.length,
+        externalRefs,
+        danglingRefs,
+        featureGates: facts.featureGates,
+        invites: facts.inviting.map((entity) => ({
+            accept: entity.invite.accept,
+            acceptFrom: entity.invite.acceptFrom === "link" ? "link" : "token",
+            entity: entity.name,
+            tokenFrom: entity.invite.tokenFrom,
+        })),
+        uniqueConstraints: facts.uniqueConstraints,
+        gaps: facts.gaps,
+        listableEntities: facts.listable.length,
+        queryCatalog: facts.catalogs,
+        ...(config?.allowRemoved === undefined ? {} : { allowRemoved: config.allowRemoved }),
+        ...rootsJson(facts.roots),
+        security: securityJson(facts.security),
+        testableEntities: facts.testable.length,
+        trackableEntities: facts.trackable.length,
+        untestableEntities: facts.untestable,
+        unknownEntities: facts.unknownEntities,
+        ...(unsetEnv === undefined ? {} : { unsetEnv }),
+    }, null, 2)}\n`;
+}
+/* Said only where the document declares or names a scheme: `authLines` already speaks for one that declares none. */
+function securityBlock(facts) {
+    const { security } = facts;
+    return security.schemes.length === 0 && security.undeclared.length === 0 ? [] : securityLines(security);
+}
+function doctorText({ config, danglingRefs, externalRefs, facts, model, unsetEnv }) {
+    const lines = [
+        ...summaryLines(facts, config),
+        ...tagLines(model, facts),
+        ...entityLines(facts),
+        ...declarationLines(facts),
+        ...catalogLines(facts),
+        ...envelopeLines(model),
+        ...authLines(model),
+        ...securityBlock(facts),
+        ...unsetEnvLines(unsetEnv),
+        ...externalRefLines(externalRefs),
+        ...danglingRefLines(danglingRefs),
+        ...gapLines(facts),
+    ];
+    if (facts.blocking === 0 && facts.gapsByTag.size === 0)
+        lines.push("  no gaps — full coverage available\n");
+    return lines.join("\n");
+}
+/** `testing api doctor`: what the API tester can and cannot test in the document, as text or JSON, and how much of it blocks a run. */
+export function doctor(model, options = {}) {
+    const { asJson = false, config, danglingRefs = [], externalRefs = [], unsetEnv } = options;
+    const facts = doctorFacts(model, config);
+    const diagnosis = { config, danglingRefs, externalRefs, facts, model, unsetEnv };
+    return { blocking: facts.blocking, text: asJson ? doctorJson(diagnosis) : doctorText(diagnosis) };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/api/report/console/gaps.d.ts

@@ -0,0 +1,9 @@
+/** The `doctor` sections for what the API tester could not read or test: unfollowed and dangling refs, and the gaps by tag. */
+import type { DoctorFacts } from "./doctor-facts.ts";
+/** The external refs the document named, which the API tester did not fetch. */
+export declare function externalRefLines(externalRefs: string[]): string[];
+/** The internal refs that point at nothing, each once; the `$ref` gaps say what each costs. */
+export declare function danglingRefLines(danglingRefs: string[]): string[];
+/** The gaps, most frequent tag first, each tag with what would close it. */
+export declare function gapLines(facts: DoctorFacts): string[];
+//# sourceMappingURL=gaps.d.ts.map

package/dist/api/report/console/gaps.js

@@ -0,0 +1,23 @@
+/** The `doctor` sections for what the API tester could not read or test: unfollowed and dangling refs, and the gaps by tag. */
+import { block } from "./doctor-text.js";
+import { TAG_REMEDY } from "./tags.js";
+/** Gaps listed per tag before the rest are counted. */
+const GAPS_SHOWN = 4;
+/** The external refs the document named, which the API tester did not fetch. */
+export function externalRefLines(externalRefs) {
+    return block("  unresolved external $refs (not fetched — a test tool should not follow arbitrary URLs)", externalRefs.map((ref) => `    ${ref}`));
+}
+/** The internal refs that point at nothing, each once; the `$ref` gaps say what each costs. */
+export function danglingRefLines(danglingRefs) {
+    return block("  dangling $refs (nothing in the document is at these pointers; see the $ref gaps)", danglingRefs.map((ref) => `    ${ref}`));
+}
+/** The gaps, most frequent tag first, each tag with what would close it. */
+export function gapLines(facts) {
+    const sorted = [...facts.gapsByTag.entries()].sort((a, b) => b[1].length - a[1].length);
+    return block("  gaps by tag", sorted.flatMap(([tag, gapList]) => [
+        `    ${tag} (${gapList.length}) — ${TAG_REMEDY[tag] ?? "see the README"}`,
+        ...gapList.slice(0, GAPS_SHOWN).map((gap) => `      ${gap.operationId}: ${gap.detail}`),
+        ...(gapList.length > GAPS_SHOWN ? [`      … and ${gapList.length - GAPS_SHOWN} more`] : []),
+    ]));
+}
+//# sourceMappingURL=gaps.js.map

package/dist/api/report/console/plan.d.ts

@@ -0,0 +1,19 @@
+import type { Hooks } from "../../config/types/hooks.ts";
+import { type ScopePlan } from "../../runtime/scope/types.ts";
+import type { SpecModel } from "../../spec/graph/types.ts";
+import { type SecurityCredentials } from "./security.ts";
+/** What `plan` shows beside the model: the targeted scope, and the operations the config's recipes send. */
+export interface PlanView {
+    scope?: ScopePlan | undefined;
+    /** An entity the auth flow owns through one of these is left out, as a run leaves it out. */
+    authCreates?: ReadonlySet<string>;
+    /** The config's recipes and principals: with them, each operation names the principal that sends it. */
+    credentials?: SecurityCredentials | undefined;
+    /** Variables the config names that are not set; listed in the JSON, given only with a config. */
+    unsetEnv?: string[] | undefined;
+    /** The config's hooks: `resolvePathValue` supplies every root. */
+    hooks?: Pick<Hooks, "resolvePathValue"> | undefined;
+}
+/** `testing api plan`: the test model derived from the document, as text or JSON; the targeted scope when there is one. */
+export declare function plan(model: SpecModel, asJson: boolean, view?: PlanView): string;
+//# sourceMappingURL=plan.d.ts.map