@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/dist/api-embeds.js

@@ -0,0 +1,84 @@
+import { code, heading, link, paragraph, parsePlainMarkdown, text } from './content.js';
+export function apiEmbedComponent(node, file) {
+    const fail = (message) => { throw new Error(`${file}: <${node.name}> ${message}`); };
+    if (node.type !== 'mdxJsxFlowElement' || node.children?.length)
+        fail('must be a standalone empty element');
+    const allowed = node.name === 'ApiExample' ? ['operation', 'kind', 'mediaType', 'status', 'example'] : ['operation', 'api', 'kind', 'mediaType', 'status', 'schema'];
+    const request = { component: node.name };
+    for (const attribute of node.attributes ?? []) {
+        if (attribute.type !== 'mdxJsxAttribute' || !allowed.includes(attribute.name) || Object.hasOwn(request, attribute.name))
+            fail(`has unknown or duplicate attribute ${attribute.name ?? '(spread)'}`);
+        if (typeof attribute.value !== 'string' || !attribute.value.trim())
+            fail(`${attribute.name} must be nonempty literal text`);
+        request[attribute.name] = attribute.value;
+    }
+    const standalone = node.name === 'ApiSchema' && !!request.api;
+    if (standalone) {
+        if (!request.schema || request.operation || request.kind || request.mediaType || request.status)
+            fail('api and schema select a standalone schema or field; do not combine them with operation, kind, mediaType, or status');
+    }
+    else {
+        for (const key of ['operation', 'kind', 'mediaType', ...(node.name === 'ApiExample' ? ['example'] : [])])
+            if (!request[key])
+                fail(`needs ${key}`);
+        if (!['request', 'response'].includes(request.kind))
+            fail('kind must be request or response');
+        if (request.kind === 'response' && !request.status)
+            fail('needs status for a response');
+        if (request.kind === 'request' && request.status)
+            fail('status applies only to a response');
+    }
+    if (request.schema && (!/^(?:\.\.?\/[^#]+)?#\//.test(request.schema) || request.schema.includes('://')))
+        fail('schema must be a local OpenAPI $ref');
+    return { type: 'apiEmbed', request: request, sourceFile: file };
+}
+function exampleBlocks(example) {
+    const context = `${example.location}${example.status ? ` ${example.status}` : ''}; ${example.mediaType}`;
+    const blocks = [heading(3, example.title), paragraph(text(`OpenAPI ${context}. Example key: ${example.key}. ${example.provenance}.`))];
+    if (example.description)
+        blocks.push(...parsePlainMarkdown(example.description));
+    if (example.externalValue)
+        blocks.push(paragraph(text('External example: '), link(example.externalValue, example.externalValue)));
+    else
+        blocks.push(code(typeof example.value === 'string' && example.mediaType?.startsWith('text/') ? example.value : JSON.stringify(example.value, null, 2), example.mediaType?.startsWith('text/') && typeof example.value === 'string' ? 'text' : 'json'));
+    return blocks;
+}
+export async function resolveApiEmbedTree(tree, reader, sourceFor, sourceForApi, documentKey, uses) {
+    const walk = async (node) => {
+        if (node.type !== 'apiEmbed') {
+            if (!node.children)
+                return [node];
+            const children = [];
+            for (const child of node.children)
+                children.push(...await walk(child));
+            return [{ ...node, children }];
+        }
+        const request = node.request;
+        let binding;
+        try {
+            binding = request.api ? sourceForApi(request.api) : sourceFor(request.operation);
+        }
+        catch (error) {
+            throw new Error(`${node.sourceFile}: <${request.component}> ${error.message}`);
+        }
+        let blocks;
+        if (request.component === 'ApiExample') {
+            const generated = await reader.operation(binding.file, binding.sourceOperationId, request.operation);
+            const selected = generated.examples.filter(example => example.location === request.kind && example.status === (request.status ?? null) && example.mediaType === request.mediaType && example.key === request.example);
+            if (selected.length !== 1)
+                throw new Error(`${node.sourceFile}: <ApiExample> cannot find ${request.operation} ${request.kind}${request.status ? ` ${request.status}` : ''} ${request.mediaType} example ${request.example}`);
+            blocks = exampleBlocks(selected[0]);
+        }
+        else {
+            try {
+                blocks = request.api ? await reader.schemaReference(binding.file, request.schema, `${documentKey}-${uses.filter(use => use.documentKey === documentKey).length}`) : await reader.operationSchema(binding.file, binding.sourceOperationId, request, `${documentKey}-${uses.filter(use => use.documentKey === documentKey).length}`);
+            }
+            catch (error) {
+                throw new Error(`${node.sourceFile}: <ApiSchema> ${error.message}`);
+            }
+        }
+        uses.push({ ...request, sourceFile: node.sourceFile, documentKey });
+        return blocks;
+    };
+    return (await walk(tree))[0];
+}

package/dist/api-identity.d.ts

@@ -0,0 +1,6 @@
+export declare function generatedOperationIdentity(apiId: string, sourceOperationId: string, pathPrefix?: string): {
+    id: string;
+    reference: string;
+    slug: string;
+    filename: string;
+};

package/dist/api-identity.js

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto';
+export function generatedOperationIdentity(apiId, sourceOperationId, pathPrefix = `/reference/${apiId}`) {
+    const stem = sourceOperationId.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'operation';
+    const suffix = createHash('sha256').update(sourceOperationId).digest('hex').slice(0, 8);
+    const identity = /^[A-Za-z0-9._-]+$/.test(sourceOperationId) ? sourceOperationId : `${stem}-${suffix}`;
+    return { id: `${apiId}.${identity}`, reference: `reference.${apiId}.${identity}`, slug: `${pathPrefix}/${stem}-${suffix}`, filename: `${stem}-${suffix}.mdx` };
+}

package/dist/api-materialize.d.ts

@@ -0,0 +1,12 @@
+export type MaterializeOptions = {
+    all?: boolean;
+    operations?: string[];
+    routes?: string[];
+    output?: string;
+};
+export declare function materializeApiPages(configFile: string, apiId: string, options: MaterializeOptions): Promise<{
+    api: string;
+    selected: number;
+    written: string[];
+    skipped: string[];
+}>;

package/dist/api-materialize.js

@@ -0,0 +1,120 @@
+import { mkdir, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { apiCandidates } from './api-selection.js';
+import { loadConfig } from './config.js';
+import { defaultLanguage } from './frontmatter.js';
+async function canonical(file) {
+    const resolved = path.resolve(file);
+    try {
+        return await realpath(resolved);
+    }
+    catch {
+        const parent = path.dirname(resolved);
+        return parent === resolved ? resolved : path.join(await canonical(parent), path.basename(resolved));
+    }
+}
+async function pageFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true }).catch(error => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const nested = await Promise.all(entries.map(async (entry) => entry.isDirectory() ? pageFiles(path.join(directory, entry.name)) : entry.isFile() && /\.mdx?$/.test(entry.name) ? [path.join(directory, entry.name)] : []));
+    return nested.flat();
+}
+function pageIdentity(source, file) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (!match)
+        return {};
+    const data = YAML.parse(match[1]);
+    if (!data || typeof data !== 'object')
+        throw new Error(`${file}: invalid page frontmatter`);
+    return { id: data.id, operation: Array.isArray(data.operations) && data.operations.length === 1 ? data.operations[0] : undefined, channel: data.channel, version: data.version, language: data.language, publications: data.publications };
+}
+function select(candidates, options) {
+    const ids = options.operations ?? [];
+    const routes = options.routes ?? [];
+    if (!!options.all === !!(ids.length || routes.length))
+        throw new Error('Choose --all or at least one --operation/--route selector');
+    const known = new Map(candidates.map(item => [item.operationId, item]));
+    const chosen = new Set();
+    if (options.all)
+        return candidates;
+    for (const id of ids) {
+        const item = known.get(id);
+        if (!item)
+            throw new Error(`Unknown source operationId ${id}`);
+        chosen.add(item);
+    }
+    for (const route of routes) {
+        const match = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s+(\/\S+)$/.exec(route);
+        if (!match)
+            throw new Error(`Route selector ${JSON.stringify(route)} needs METHOD /path`);
+        const item = candidates.find(candidate => candidate.method === match[1] && candidate.route === match[2]);
+        if (!item)
+            throw new Error(`Unknown API route ${route}`);
+        chosen.add(item);
+    }
+    return candidates.filter(item => chosen.has(item));
+}
+export async function materializeApiPages(configFile, apiId, options) {
+    const loaded = await loadConfig(configFile);
+    const config = loaded.value;
+    const root = path.dirname(path.resolve(configFile));
+    const contentDir = await canonical(path.resolve(root, config.site?.contentDir ?? 'content'));
+    const directory = await canonical(options.output ? path.resolve(options.output) : path.join(contentDir, 'api', apiId));
+    const relative = path.relative(contentDir, directory);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error(`MDX output must stay inside the content directory ${contentDir}`);
+    const { candidates } = await apiCandidates(configFile, apiId);
+    const selected = select(candidates, options);
+    const defaults = config.publications?.defaults;
+    if (!defaults?.channel || !defaults?.version)
+        throw new Error('API page materialization needs publication defaults');
+    const language = defaults.language ?? defaultLanguage(config);
+    const existing = new Map();
+    for (const file of await pageFiles(contentDir)) {
+        const identity = pageIdentity(await readFile(file, 'utf8'), file);
+        if (!identity.id)
+            continue;
+        const pages = existing.get(identity.id) ?? [];
+        pages.push({ file, ...identity });
+        existing.set(identity.id, pages);
+    }
+    const pending = [];
+    const skipped = [];
+    const targets = new Set();
+    for (const item of selected) {
+        const matches = (existing.get(item.reference) ?? []).filter(page => (page.publications ? page.publications.some(publication => publication.channel === defaults.channel && publication.version === defaults.version) : (page.channel ?? defaults.channel) === defaults.channel && (page.version ?? defaults.version) === defaults.version) && (page.language ?? language) === language);
+        if (matches.length > 1)
+            throw new Error(`Duplicate page ID ${item.reference} in the default publication: ${matches.map(page => page.file).join(', ')}`);
+        const prior = matches[0];
+        if (prior) {
+            if (prior.operation !== item.id)
+                throw new Error(`${prior.file}: page ${item.reference} is not bound to ${item.id}`);
+            skipped.push(prior.file);
+            continue;
+        }
+        const file = path.join(directory, item.filename);
+        if (targets.has(file))
+            throw new Error(`Two selected operations map to ${file}; no files written`);
+        targets.add(file);
+        const atFile = await readFile(file, 'utf8').catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (atFile !== undefined)
+            throw new Error(`${file}: target exists with another page ID; no files written`);
+        const summary = item.method === 'WEBHOOK' ? `Webhook event: ${item.route}` : `${item.method} ${item.route}`;
+        const header = YAML.stringify({ id: item.reference, title: item.title, summary, type: 'api-reference', slug: item.slug, channel: defaults.channel, version: defaults.version, language, operations: [item.id], access: { policy: 'draft' } });
+        const body = 'This draft reference is based on its linked OpenAPI operation.\n\n[[TODO: Explain when to use this endpoint, its prerequisites, and any behavior the OpenAPI contract cannot express. Verify every claim before publishing.]]\n';
+        pending.push({ item, file, content: `---\n${header}---\n\n${body}` });
+    }
+    for (const page of pending) {
+        await mkdir(path.dirname(page.file), { recursive: true });
+        await writeFile(page.file, page.content, { flag: 'wx' });
+    }
+    return { api: apiId, selected: selected.length, written: pending.map(page => page.file), skipped };
+}

package/dist/api-publication-plan.d.ts

@@ -0,0 +1,86 @@
+import { ApiReader } from './api.js';
+import { type Document, type Variant } from './content.js';
+import type { PublicationRoutingConfig } from './content-source.js';
+import { type ReaderSelection, type ReaderFiltersConfig } from './reader-filters.js';
+import { type loadConfig } from './config.js';
+import { type CompilerPublicationsConfig, type CompilerSiteConfig } from './compiler-config.js';
+type ApiDefinition = {
+    source?: {
+        kind: string;
+        path: string;
+        [key: string]: unknown;
+    };
+    publications?: Array<{
+        channel: string;
+        version: string;
+        source: {
+            kind: string;
+            path: string;
+            [key: string]: unknown;
+        };
+        discovery?: {
+            endpoint?: string;
+        };
+        [key: string]: unknown;
+    }>;
+    discovery?: {
+        endpoint?: string;
+    };
+    operations?: Array<{
+        id: string;
+        reference: string;
+        sourceOperationId?: string;
+    }>;
+    generateReferences?: boolean | {
+        pathPrefix?: string;
+        include?: string[];
+        exclude?: string[];
+    };
+    mappings?: unknown;
+    [key: string]: unknown;
+};
+export type ApiPublicationConfig = PublicationRoutingConfig & {
+    site: CompilerSiteConfig;
+    publications: CompilerPublicationsConfig;
+    apis?: unknown;
+    frontmatter?: unknown;
+};
+export declare function materializeApiReferences({ config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions }: {
+    config: ApiPublicationConfig;
+    loaded: Awaited<ReturnType<typeof loadConfig>>;
+    variants: Variant[];
+    docs: Map<string, Document>;
+    knownDocumentIds: Set<string>;
+    knownDocumentTypes: Map<string, string>;
+    authoredOperationIds: Set<string>;
+    routeOwners: Map<string, string>;
+    basePath: string;
+    readerFilters?: ReaderFiltersConfig;
+    contentFilter?: ReaderSelection;
+    allowRouteCollisions?: boolean;
+}): Promise<{
+    api: ApiReader;
+    queryRules: Map<string, import("./api.js").QuerySyntaxRule[]>;
+    lifecycleMappings: Map<string, {
+        from: string;
+        values: Record<string, "beta" | "in-development" | "deprecated" | "experimental">;
+    }>;
+    extensionValue: (operation: unknown, selector: string) => unknown;
+    sourceForVariant: (apiId: string, definition: ApiDefinition, variant: Variant) => {
+        file: string;
+        source: {
+            [key: string]: unknown;
+            kind: string;
+            path: string;
+        };
+        definition: ApiDefinition;
+        publicationIndex: number;
+        apiId: string;
+    } | undefined;
+    knownOperations: Map<string, {
+        apiId: string;
+        reference: string;
+    }>;
+    apiDefinitions: Record<string, ApiDefinition>;
+}>;
+export {};

package/dist/api-publication-plan.js

@@ -0,0 +1,187 @@
+import { matchesContentFilter } from './content-filter.js';
+import path from 'node:path';
+import { ApiReader, querySyntaxRules } from './api.js';
+import { generatedOperationIdentity } from './api-identity.js';
+import { markdownRoute, routeFor } from './content.js';
+import { pageReaderFilters } from './reader-filters.js';
+import { applyFormattingLocale, resolveFrontmatter, validateFrontmatter } from './frontmatter.js';
+import { explain } from './config.js';
+import { isConfigMapping } from './compiler-config.js';
+const generatedReferenceBody = 'This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.\n';
+const generatedWebhookBody = 'This webhook reference is generated from the OpenAPI description. The provider sends this event to the receiver.\n';
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+function validatedApiDefinitions(value) {
+    if (value === undefined)
+        return {};
+    if (!isConfigMapping(value))
+        throw new Error('apis must be a mapping');
+    const definitions = {};
+    for (const [id, raw] of Object.entries(value)) {
+        if (!isConfigMapping(raw))
+            throw new Error(`apis.${id} must be a mapping`);
+        const source = raw.source;
+        if (source !== undefined && (!isConfigMapping(source) || typeof source.kind !== 'string' || typeof source.path !== 'string'))
+            throw new Error(`apis.${id}.source needs kind and path`);
+        const publications = raw.publications;
+        if (publications !== undefined && (!Array.isArray(publications) || publications.some(item => !isConfigMapping(item) || typeof item.channel !== 'string' || typeof item.version !== 'string' || !isConfigMapping(item.source) || typeof item.source.kind !== 'string' || typeof item.source.path !== 'string' || (item.discovery !== undefined && (!isConfigMapping(item.discovery) || (item.discovery.endpoint !== undefined && typeof item.discovery.endpoint !== 'string'))))))
+            throw new Error(`apis.${id}.publications needs entries with channel, version, and a local source`);
+        const operations = raw.operations;
+        if (operations !== undefined && (!Array.isArray(operations) || operations.some(item => !isConfigMapping(item) || typeof item.id !== 'string' || typeof item.reference !== 'string' || (item.sourceOperationId !== undefined && typeof item.sourceOperationId !== 'string'))))
+            throw new Error(`API ${id} operation needs stable id and reference`);
+        const discovery = raw.discovery;
+        if (discovery !== undefined && (!isConfigMapping(discovery) || (discovery.endpoint !== undefined && typeof discovery.endpoint !== 'string')))
+            throw new Error(`apis.${id}.discovery.endpoint must be a string`);
+        definitions[id] = raw;
+    }
+    return definitions;
+}
+export async function materializeApiReferences({ config, loaded, variants, docs, knownDocumentIds, knownDocumentTypes, authoredOperationIds, routeOwners, basePath, readerFilters, contentFilter, allowRouteCollisions }) {
+    const definitions = validatedApiDefinitions(config.apis);
+    const api = new ApiReader();
+    const queryRules = new Map(Object.entries(definitions).map(([id, definition]) => [id, querySyntaxRules(definition.querySyntax)]));
+    const lifecycleMappings = new Map();
+    const extensionValue = (operation, selector) => selector.split('.').reduce((value, key) => isConfigMapping(value) && Object.hasOwn(value, key) ? value[key] : undefined, operation);
+    for (const [id, definition] of Object.entries(definitions)) {
+        if (definition.mappings !== undefined && (!definition.mappings || typeof definition.mappings !== 'object' || Array.isArray(definition.mappings) || Object.keys(definition.mappings).some(key => key !== 'subjectLifecycle')))
+            throw new Error(`apis.${id}.mappings accepts only subjectLifecycle`);
+        const mapping = definition.mappings?.subjectLifecycle;
+        if (mapping === undefined)
+            continue;
+        if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || Object.keys(mapping).some(key => !['from', 'values'].includes(key)) || typeof mapping.from !== 'string' || !/^x-[a-z0-9-]+(?:\.[a-z0-9_-]+)*$/i.test(mapping.from) || !mapping.values || typeof mapping.values !== 'object' || Array.isArray(mapping.values) || !Object.keys(mapping.values).length || Object.values(mapping.values).some(value => !['beta', 'in-development', 'deprecated', 'experimental'].includes(String(value))))
+            throw new Error(`apis.${id}.mappings.subjectLifecycle needs an x- extension name or dotted property path and values mapped to beta, in-development, deprecated, or experimental`);
+        lifecycleMappings.set(id, mapping);
+    }
+    const sourceForVariant = (apiId, definition, variant) => {
+        const defaults = config.publications.defaults;
+        if (definition.source !== undefined && (!defaults?.channel || !defaults?.version))
+            throw new Error(`apis.${apiId}.source needs publications.defaults with channel and version to choose its publication`);
+        const isDefault = variant.channel === defaults?.channel && variant.version === defaults?.version;
+        const publicationIndex = definition.publications?.findIndex(item => item.channel === variant.channel && item.version === variant.version) ?? -1;
+        const source = publicationIndex >= 0 ? definition.publications?.[publicationIndex].source : (isDefault ? definition.source : undefined);
+        if (!source)
+            return undefined;
+        if (source.kind !== 'file')
+            throw new Error(`pinned local OpenAPI source required for ${apiId} in ${variant.channel}/${variant.version}`);
+        const sourceKey = publicationIndex >= 0 ? `apis.${apiId}.publications.${publicationIndex}.source.path` : `apis.${apiId}.source.path`;
+        const sourceOrigin = explain(loaded, sourceKey).source.file;
+        return { file: path.resolve(path.dirname(sourceOrigin), source.path), source, definition, publicationIndex, apiId };
+    };
+    const knownOperations = new Map();
+    for (const [apiId, definition] of Object.entries(definitions)) {
+        for (const operation of definition.operations ?? []) {
+            if (typeof operation.id !== 'string' || typeof operation.reference !== 'string')
+                throw new Error(`API ${apiId} operation needs stable id and reference`);
+            if (knownOperations.has(operation.id))
+                throw new Error(`Duplicate stable operation ID ${operation.id}`);
+            knownOperations.set(operation.id, { apiId, reference: operation.reference });
+        }
+    }
+    const methods = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']);
+    for (const [apiId, definition] of Object.entries(definitions)) {
+        const generate = definition.generateReferences;
+        const implicitPages = [...authoredOperationIds].some(id => id.startsWith(`${apiId}.`) && !knownOperations.has(id));
+        if ((generate === undefined || generate === false) && !implicitPages)
+            continue;
+        if (generate !== undefined && generate !== false && generate !== true && (!generate || typeof generate !== 'object' || Array.isArray(generate) || Object.keys(generate).some(key => !['pathPrefix', 'include', 'exclude'].includes(key))))
+            throw new Error(`apis.${apiId}.generateReferences must be true or a mapping with pathPrefix, include, or exclude`);
+        const prefix = generate && generate !== true ? generate.pathPrefix ?? `/reference/${apiId}` : `/reference/${apiId}`;
+        if (generate && (typeof prefix !== 'string' || !prefix.startsWith('/') || prefix === '/' || prefix.endsWith('/') || prefix.includes('..') || /[?#]/.test(prefix)))
+            throw new Error(`apis.${apiId}.generateReferences.pathPrefix must be an absolute page path without a trailing slash`);
+        if (generate && generate !== true && generate.include !== undefined && generate.exclude !== undefined)
+            throw new Error(`apis.${apiId}.generateReferences cannot combine include and exclude`);
+        const selections = !generate || generate === true ? {} : { include: generate.include, exclude: generate.exclude };
+        for (const [name, ids] of Object.entries(selections)) {
+            if (ids === undefined)
+                continue;
+            if (!Array.isArray(ids) || ids.some(id => typeof id !== 'string' || !id.trim()) || new Set(ids).size !== ids.length)
+                throw new Error(`apis.${apiId}.generateReferences.${name} must be a unique list of operationId strings`);
+        }
+        const include = selections.include ? new Set(selections.include) : undefined;
+        const exclude = selections.exclude ? new Set(selections.exclude) : undefined;
+        const available = new Set();
+        const explicit = new Set();
+        for (const operation of definition.operations ?? []) {
+            if (typeof operation.sourceOperationId !== 'string' || !operation.sourceOperationId)
+                throw new Error(`API ${apiId} operation needs sourceOperationId`);
+            if (explicit.has(operation.sourceOperationId))
+                throw new Error(`API ${apiId} binds source operation ${operation.sourceOperationId} more than once`);
+            explicit.add(operation.sourceOperationId);
+        }
+        definition.operations ??= [];
+        for (const variant of variants) {
+            const binding = sourceForVariant(apiId, definition, variant);
+            if (!binding)
+                continue;
+            const rawSpec = (await api.load(binding.file)).value;
+            const spec = isConfigMapping(rawSpec) ? rawSpec : {};
+            if (!/^3\.(0|1)\./.test(String(spec.openapi)))
+                throw new Error(`${binding.file}: OpenAPI 3.0.x or 3.1.x required`);
+            const seen = new Set();
+            for (const [collection, webhook] of [[spec.paths ?? {}, false], [spec.webhooks ?? {}, true]])
+                for (const [route, initial] of Object.entries(isConfigMapping(collection) ? collection : {})) {
+                    const pathReference = isConfigMapping(initial) ? initial.$ref : undefined;
+                    if (pathReference !== undefined && typeof pathReference !== 'string')
+                        throw new Error(`${binding.file}: ${route} has an invalid path reference`);
+                    const pathItem = pathReference ? (await api.ref(await api.load(binding.file), pathReference)).value : initial;
+                    for (const [method, operation] of Object.entries(isConfigMapping(pathItem) ? pathItem : {})) {
+                        if (!methods.has(method))
+                            continue;
+                        const sourceOperationId = isConfigMapping(operation) ? operation.operationId : undefined;
+                        if (typeof sourceOperationId !== 'string' || !sourceOperationId.trim())
+                            throw new Error(`${binding.file}: ${webhook ? 'webhook' : method.toUpperCase()} ${route} needs operationId for generated references`);
+                        if (seen.has(sourceOperationId))
+                            throw new Error(`${binding.file}: duplicate operationId ${sourceOperationId}`);
+                        seen.add(sourceOperationId);
+                        available.add(sourceOperationId);
+                        if (explicit.has(sourceOperationId))
+                            continue;
+                        const generated = generatedOperationIdentity(apiId, sourceOperationId, prefix);
+                        const { id, reference } = generated;
+                        const selected = !!generate && (!include || include.has(sourceOperationId)) && !exclude?.has(sourceOperationId);
+                        if (!selected && !authoredOperationIds.has(id))
+                            continue;
+                        const registered = knownOperations.get(id);
+                        if (registered && (registered.apiId !== apiId || registered.reference !== reference))
+                            throw new Error(`Generated operation ID ${id} conflicts with an authored binding`);
+                        if (!registered) {
+                            knownOperations.set(id, { apiId, reference });
+                            definition.operations.push({ id, sourceOperationId, reference });
+                        }
+                        if (!selected)
+                            continue;
+                        const page = resolveFrontmatter({
+                            id: reference, title: String(isConfigMapping(operation) && operation.summary || `${webhook ? 'Webhook' : method.toUpperCase()} ${route}`),
+                            summary: webhook ? `Webhook event: ${route}` : `${method.toUpperCase()} ${route}`, type: 'api-reference',
+                            slug: generated.slug, ...variant, operations: [id], access: { policy: 'public' }
+                        }, config.frontmatter);
+                        applyFormattingLocale(page, config.frontmatter);
+                        validateFrontmatter(page, config.frontmatter, binding.file);
+                        knownDocumentIds.add(reference);
+                        knownDocumentTypes.set(reference, page.type);
+                        if (page.access?.policy !== 'public' || page.channel !== variant.channel || page.version !== variant.version || page.language !== variant.language)
+                            continue;
+                        const key = keyFor(reference, variant);
+                        const authored = docs.get(key);
+                        if (authored) {
+                            if (authored.frontmatter.type !== 'api-reference' || authored.frontmatter.operations?.length !== 1 || authored.frontmatter.operations[0] !== id)
+                                throw new Error(`Generated API reference ${reference} conflicts with an authored page`);
+                            continue;
+                        }
+                        const marks = pageReaderFilters(page, readerFilters, binding.file);
+                        if (!matchesContentFilter(marks, contentFilter))
+                            continue;
+                        const pageRoute = routeFor(page, variant, config);
+                        const collision = routeOwners.get(pageRoute.toLowerCase());
+                        if (collision && !allowRouteCollisions)
+                            throw new Error(`Route collision ${pageRoute}: ${collision} and ${key}`);
+                        routeOwners.set(pageRoute.toLowerCase(), key);
+                        docs.set(key, { file: binding.file, frontmatter: page, body: webhook ? generatedWebhookBody : generatedReferenceBody, tree: null, variant, route: pageRoute, markdownRoute: markdownRoute(pageRoute, basePath), readerFilters: marks });
+                    }
+                }
+        }
+        for (const id of [...(include ?? []), ...(exclude ?? [])])
+            if (!available.has(id))
+                throw new Error(`apis.${apiId}.generateReferences names unknown source operationId ${id}`);
+    }
+    return { api, queryRules, lifecycleMappings, extensionValue, sourceForVariant, knownOperations, apiDefinitions: definitions };
+}

package/dist/api-publication-review.d.ts

@@ -0,0 +1,23 @@
+import type { prepareContentWorkspace } from './content-workspace.js';
+import type { materializePages } from './page-materialization.js';
+export declare function reviewApiPublication(configFile: string, apiPlan: Awaited<ReturnType<typeof prepareContentWorkspace>>['apiPlan'], rendered: Awaited<ReturnType<typeof materializePages>>['rendered'], apiEmbedUses: Awaited<ReturnType<typeof materializePages>>['apiEmbedUses'], focusedContracts: Awaited<ReturnType<typeof materializePages>>['focusedContracts'], apiSources: Array<{
+    apiId: string;
+    sourceUrl: string;
+}>, sourceForOperation: Awaited<ReturnType<typeof prepareContentWorkspace>>['sourceForOperation'], mode?: 'report'): Promise<{
+    apiId: string;
+    digest: string;
+    pages: Array<{
+        id: string;
+        url: string;
+        markdownUrl: string;
+    }>;
+    focusedContracts: string[];
+    fullSources: string[];
+    inputs: Array<{
+        source: string;
+        files: Array<{
+            path: string;
+            digest: string;
+        }>;
+    }>;
+}[]>;

package/dist/api-publication-review.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isConfigMapping } from './compiler-config.js';
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const keyFor = (id, variant) => `${id}|${variant.channel}|${variant.version}|${variant.language}`;
+export async function reviewApiPublication(configFile, apiPlan, rendered, apiEmbedUses, focusedContracts, apiSources, sourceForOperation, mode) {
+    const { api, knownOperations, sourceForVariant } = apiPlan;
+    // Pin the source bytes and the API selections exposed by public pages. Authored
+    // page copy can change without requiring a new review of imported material.
+    const apiPublicationReview = [];
+    for (const [apiId, definition] of Object.entries(apiPlan.apiDefinitions)) {
+        const pages = rendered.filter(({ doc }) => {
+            const reference = doc.frontmatter.type === 'api-reference' && doc.frontmatter.operations?.some(id => knownOperations.get(id)?.apiId === apiId);
+            const embedded = apiEmbedUses.some(use => use.documentKey === keyFor(doc.frontmatter.id, doc.variant) && (use.api === apiId || (use.operation && knownOperations.get(use.operation)?.apiId === apiId)));
+            return reference || embedded;
+        }).sort((a, b) => a.doc.route.localeCompare(b.doc.route) || keyFor(a.doc.frontmatter.id, a.doc.variant).localeCompare(keyFor(b.doc.frontmatter.id, b.doc.variant)));
+        if (!pages.length)
+            continue;
+        const bindings = new Map();
+        for (const { doc } of pages) {
+            const key = `${doc.variant.channel}|${doc.variant.version}`;
+            if (!bindings.has(key))
+                bindings.set(key, sourceForVariant(apiId, definition, doc.variant));
+        }
+        const inputs = [];
+        for (const [publication, binding] of [...bindings].sort(([a], [b]) => a.localeCompare(b))) {
+            if (!binding)
+                throw new Error(`Missing OpenAPI source for public API ${apiId} ${publication}`);
+            const files = await api.collectReferences(binding.file);
+            inputs.push({ source: publication, files: await Promise.all(files.map(async (file) => ({
+                    path: path.relative(path.dirname(binding.file), file).split(path.sep).join('/'),
+                    digest: createHash('sha256').update(await readFile(file)).digest('hex')
+                }))) });
+        }
+        const reviewedPages = pages.map(({ doc }) => ({ id: doc.frontmatter.id, url: doc.route, markdownUrl: doc.markdownRoute }));
+        const references = pages.filter(({ doc }) => doc.frontmatter.type === 'api-reference').flatMap(({ doc }) => (doc.frontmatter.operations ?? []).filter(id => knownOperations.get(id)?.apiId === apiId).map(id => ({
+            channel: doc.variant.channel, version: doc.variant.version, language: doc.variant.language,
+            operation: sourceForOperation(id, doc.variant).sourceOperationId
+        }))).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+        const embeds = apiEmbedUses.filter(use => use.api === apiId || (use.operation && knownOperations.get(use.operation)?.apiId === apiId))
+            .map(({ sourceFile, documentKey, ...request }) => request)
+            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+        const contracts = [...new Set(pages.map(({ doc }) => doc.focusedContractUrl).filter((url) => !!url))].sort().map(url => ({ url, digest: focusedContracts.get(url).digest }));
+        const fullSources = apiSources.filter(source => source.apiId === apiId).map(source => source.sourceUrl).sort();
+        const fingerprint = digest(JSON.stringify({ version: 2, apiId, inputs, references, embeds, contracts: contracts.map(item => item.digest), fullSourcePublished: fullSources.length > 0 }));
+        const review = definition.publicReview;
+        if (review !== undefined && (!isConfigMapping(review) || Object.keys(review).some(key => key !== 'digest') || typeof review.digest !== 'string' || !/^[a-f0-9]{64}$/.test(review.digest))) {
+            throw new Error(`apis.${apiId}.publicReview needs a lowercase SHA-256 digest`);
+        }
+        const reviewDigest = isConfigMapping(review) ? review.digest : undefined;
+        apiPublicationReview.push({ apiId, digest: fingerprint, pages: reviewedPages, focusedContracts: contracts.map(item => item.url), fullSources, inputs });
+        if (mode !== 'report' && reviewDigest !== fingerprint) {
+            throw new Error(`apis.${apiId}.publicReview.digest is ${review ? 'stale' : 'missing'}; run shoalrun api review ${configFile} --output <local-directory>, inspect the candidate site, and pin the reported digest`);
+        }
+    }
+    return apiPublicationReview;
+}

package/dist/api-selection.d.ts

@@ -0,0 +1,21 @@
+export type ApiCandidate = {
+    operationId: string;
+    method: string;
+    route: string;
+    title: string;
+    authored: boolean;
+    id: string;
+    reference: string;
+    slug: string;
+    filename: string;
+};
+export declare function apiCandidates(configFile: string, apiId: string): Promise<{
+    candidates: ApiCandidate[];
+    selected: Set<string>;
+    pathPrefix: string;
+}>;
+export declare function selectApiReferences(configFile: string, apiId: string, outputFile: string): Promise<{
+    selected: string[];
+    total: number;
+    file: string;
+}>;