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

package/dist/documentation-core.js

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { markdownTokens } from './markdown-size.js';
+import { queryBuiltSite } from './search-query.js';
+export const bundledDocumentation = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../agent-docs');
+export class DocumentationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export const documentationFailure = (error) => ({ status: 'error', error: { code: error instanceof DocumentationError ? error.code : 'internal_error', message: error instanceof DocumentationError ? error.message : 'Documentation could not be loaded; check the built site files.' } });
+export const documentationTokens = markdownTokens;
+function validate(options) {
+    const maxTokens = options.maxTokens ?? 4096;
+    if (!Number.isSafeInteger(maxTokens) || maxTokens < 256 || maxTokens > 100_000)
+        throw new DocumentationError('invalid_input', 'maxTokens must be an integer from 256 to 100000');
+    for (const key of ['channel', 'version', 'language'])
+        if (options[key] !== undefined && (typeof options[key] !== 'string' || !options[key]?.trim() || options[key].length > 128))
+            throw new DocumentationError('invalid_input', `${key} must be nonempty text of at most 128 characters`);
+    return maxTokens;
+}
+function budget(data, maxTokens, truncated) {
+    const result = { ...data, budget: { maxTokens, encoding: 'cl100k_base', tokens: 0, truncated } };
+    // Reserve all digits of the largest possible count, including the metadata itself.
+    result.budget.tokens = maxTokens;
+    result.budget.tokens = documentationTokens(JSON.stringify(result));
+    let actual = documentationTokens(JSON.stringify(result));
+    for (let i = 0; actual > result.budget.tokens && i < 8; i++) {
+        result.budget.tokens = actual;
+        actual = documentationTokens(JSON.stringify(result));
+    }
+    return { result, fits: actual <= result.budget.tokens && result.budget.tokens <= maxTokens };
+}
+async function loadJson(directory, name) {
+    try {
+        return JSON.parse(await readFile(path.join(directory, name), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new DocumentationError('missing_index', `Missing ${name}; build the documentation first${name === 'search-index.json' ? ' with search indexing enabled' : ''}.`);
+        throw new DocumentationError('internal_error', `Cannot read valid ${name}. Rebuild the documentation.`);
+    }
+}
+export async function searchDocumentation(directory, query, options = {}) {
+    const maxTokens = validate(options);
+    if (typeof query !== 'string' || !query.trim() || query.length > 512)
+        throw new DocumentationError('invalid_input', 'query must be nonempty text of at most 512 characters');
+    if (options.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit < 1 || options.limit > 100))
+        throw new DocumentationError('invalid_input', 'limit must be an integer from 1 to 100');
+    await loadJson(directory, 'search-index.json');
+    let search;
+    try {
+        search = await queryBuiltSite(directory, query, options);
+    }
+    catch (error) {
+        const message = error.message;
+        if (/selected publication|multiple publications/.test(message))
+            throw new DocumentationError('invalid_input', message);
+        throw new DocumentationError('internal_error', 'Cannot search the documentation index. Rebuild the documentation.');
+    }
+    let results = search.results;
+    while (true) {
+        const bounded = budget({ ...search, results }, maxTokens, results.length < search.total);
+        if (bounded.fits)
+            return bounded.result;
+        if (!results.length)
+            throw new DocumentationError('invalid_input', 'maxTokens is too small for the search metadata. Increase the budget or shorten the query.');
+        results = results.slice(0, -1);
+    }
+}
+async function selectDocument(directory, id, options) {
+    if (typeof id !== 'string' || !id.trim() || id.length > 256)
+        throw new DocumentationError('invalid_input', 'id must be nonempty text of at most 256 characters');
+    const manifest = await loadJson(directory, 'documents.json');
+    if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.documents) || manifest.documents.some((doc) => !doc || typeof doc.id !== 'string' || typeof doc.title !== 'string' || typeof doc.url !== 'string' || typeof doc.markdownUrl !== 'string' || !doc.variant || ['channel', 'version', 'language'].some(key => typeof doc.variant[key] !== 'string')))
+        throw new DocumentationError('internal_error', 'Invalid documents.json. Rebuild the documentation.');
+    const matching = manifest.documents.filter((doc) => doc.id === id);
+    if (!matching.length)
+        throw new DocumentationError('unknown_page', `No document with ID ${id}; search the documentation first.`);
+    const selected = matching.filter((doc) => ['channel', 'version', 'language'].every(key => !options[key] || doc.variant[key] === options[key]));
+    if (selected.length !== 1)
+        throw new DocumentationError('invalid_input', selected.length ? 'Page has multiple publications; select channel, version, and language.' : 'Page does not match the selected publication.');
+    return selected[0];
+}
+async function readMarkdown(directory, markdownUrl) {
+    let content;
+    try {
+        const root = await realpath(directory);
+        if (!markdownUrl.startsWith('/') || /[?#\\]/.test(markdownUrl))
+            throw new Error('Invalid Markdown URL');
+        const file = await realpath(path.resolve(root, decodeURIComponent(markdownUrl.slice(1))));
+        if (!file.startsWith(`${root}${path.sep}`) || !file.endsWith('.md'))
+            throw new Error('Markdown path escapes site');
+        content = await readFile(file, 'utf8');
+    }
+    catch {
+        throw new DocumentationError('internal_error', 'Cannot read the published Markdown page. Rebuild the documentation.');
+    }
+    return content;
+}
+export async function getDocumentationPage(directory, id, options = {}) {
+    const maxTokens = validate(options);
+    const doc = await selectDocument(directory, id, options);
+    const content = await readMarkdown(directory, doc.markdownUrl);
+    const metadata = { status: 'ok', id: doc.id, title: doc.title, url: doc.url, markdownUrl: doc.markdownUrl, publication: doc.variant };
+    const full = budget({ ...metadata, content }, maxTokens, false);
+    if (full.fits)
+        return full.result;
+    if (!budget({ ...metadata, content: '' }, maxTokens, true).fits)
+        throw new DocumentationError('invalid_input', 'maxTokens is too small for the page metadata. Increase the budget.');
+    const characters = [...content];
+    let low = 0, high = characters.length;
+    // Each accepted candidate fits; a final count is made over the serialized result.
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (budget({ ...metadata, content: characters.slice(0, middle).join('') }, maxTokens, true).fits)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return budget({ ...metadata, content: characters.slice(0, low).join('') }, maxTokens, true).result;
+}
+export async function getDocumentationOutline(directory, id, options = {}) {
+    const maxTokens = validate(options);
+    const doc = await selectDocument(directory, id, options);
+    if (!Array.isArray(doc.sections))
+        throw new DocumentationError('missing_index', 'Section outline is unavailable; rebuild the documentation.');
+    const data = { status: 'ok', id: doc.id, title: doc.title, publication: doc.variant, markdownUrl: doc.markdownUrl, digest: doc.digest, sections: doc.sections };
+    const result = budget(data, maxTokens, false);
+    if (!result.fits) {
+        const complete = budget(data, 100_000, false);
+        if (!complete.fits)
+            throw new DocumentationError('invalid_input', 'The complete outline exceeds the 100000-token limit. Use search_docs to find a page or section read instead.');
+        const retryTokens = Math.min(100_000, Math.ceil(complete.result.budget.tokens / 1000) * 1000);
+        throw new DocumentationError('invalid_input', `The complete outline needs about ${complete.result.budget.tokens} tokens including metadata. Retry get_outline with maxTokens=${retryTokens}.`);
+    }
+    return result.result;
+}
+export async function getDocumentationSection(directory, id, sectionId, options = {}) {
+    const maxTokens = validate(options);
+    if (typeof sectionId !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(sectionId) || sectionId.length > 512)
+        throw new DocumentationError('invalid_input', 'section must be an ID returned by the page outline');
+    const doc = await selectDocument(directory, id, options);
+    if (!Array.isArray(doc.sections))
+        throw new DocumentationError('missing_index', 'Section outline is unavailable; rebuild the documentation.');
+    const section = doc.sections.find((item) => item.id === sectionId);
+    if (!section)
+        throw new DocumentationError('unknown_section', `No section ${sectionId}; read the page outline first.`);
+    const content = await readMarkdown(directory, section.markdownUrl);
+    if (section.parentDigest !== doc.digest || section.parentMarkdownUrl !== doc.markdownUrl || createHash('sha256').update(content).digest('hex') !== section.digest)
+        throw new DocumentationError('internal_error', 'Section or parent metadata is stale; rebuild the documentation.');
+    const result = budget({ status: 'ok', id: doc.id, publication: doc.variant, section, content }, maxTokens, false);
+    if (!result.fits)
+        throw new DocumentationError('invalid_input', 'maxTokens is too small for the complete section. Increase the budget; sections are never cut mid-block.');
+    return result.result;
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,68 @@
+import { type Chunk, type ChunkIndex } from './index-build.js';
+import { type Transport } from './provider-http.js';
+export type EmbedInputType = 'document' | 'query';
+export type EmbeddingProvider = {
+    name: string;
+    model: string;
+    dimension: number;
+    space: string;
+    backend?: string;
+    documentFingerprint?: string;
+    embed(texts: string[], inputType: EmbedInputType, signal?: AbortSignal): Promise<Float32Array[]>;
+};
+export type VoyageOptions = Transport & {
+    model: string;
+    dimension?: number;
+    apiKey?: string;
+    keyEnv?: string;
+    endpoint?: string;
+    batchSize?: number;
+};
+export declare function voyageProvider(options: VoyageOptions): EmbeddingProvider;
+export type OpenAIOptions = Transport & {
+    model: string;
+    dimension?: number;
+    apiKey?: string;
+    keyEnv?: string;
+    baseUrl?: string;
+    batchSize?: number;
+    queryPrefix?: string;
+    documentPrefix?: string;
+};
+export declare function openAIProvider(options: OpenAIOptions): EmbeddingProvider;
+export type ProviderConfig = Partial<OpenAIOptions & VoyageOptions> & {
+    provider?: string;
+};
+export declare function createProvider(config?: ProviderConfig): EmbeddingProvider;
+export type EmbeddingsMeta = {
+    schemaVersion: 1;
+    provider: string;
+    model: string;
+    space?: string;
+    dimension: number;
+    sourceDigest: string;
+    ids: string[];
+    digests: string[];
+    backend?: string;
+    documentFingerprint?: string;
+    inputDigests?: string[];
+};
+export type StoredEmbeddings = {
+    meta: EmbeddingsMeta;
+    vectors: Float32Array[];
+};
+export declare function writeEmbeddings(directory: string, meta: EmbeddingsMeta, vectors: Float32Array[]): Promise<{
+    metaFile: string;
+    vectorFile: string;
+    bytes: number;
+}>;
+export declare function readEmbeddings(directory: string): Promise<StoredEmbeddings | undefined>;
+export type EmbedResult = {
+    passages: number;
+    embedded: number;
+    reused: number;
+    model: string;
+    dimension: number;
+    bytes: number;
+};
+export declare function embedChunkIndex(directory: string, index: ChunkIndex, provider: EmbeddingProvider, input: (chunk: Chunk) => string): Promise<EmbedResult>;

package/dist/embeddings.js

@@ -0,0 +1,198 @@
+import { readFile, realpath, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { aiDirectory } from './index-build.js';
+import { postJson, throwIfCancelled } from './provider-http.js';
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function normalize(vector) {
+    let length = 0;
+    for (const value of vector)
+        length = Math.hypot(length, value);
+    return length ? vector.map(value => value / length) : vector;
+}
+function validVector(vector) {
+    let length = 0;
+    for (const value of vector) {
+        if (!Number.isFinite(value))
+            return false;
+        length = Math.hypot(length, value);
+    }
+    return length > 0;
+}
+// Both APIs answer `{ data: [{ index, embedding }] }`. Check the answer matches the request before trusting it.
+function vectorsFrom(label, body, count, dimension, model) {
+    const invalid = () => new Error(`${label} returned an unexpected response for model ${model} at ${dimension} dimensions`);
+    const rows = body?.data;
+    if (!Array.isArray(rows) || rows.length !== count)
+        throw invalid();
+    const seen = new Set();
+    const vectors = rows.map((row) => {
+        if (!row || typeof row !== 'object')
+            throw invalid();
+        const { index, embedding } = row;
+        if (!Number.isInteger(index) || index < 0 || index >= count || seen.has(index) || !Array.isArray(embedding) || embedding.length !== dimension || embedding.some(value => typeof value !== 'number' || !Number.isFinite(value)))
+            throw invalid();
+        seen.add(index);
+        const vector = Float32Array.from(embedding);
+        if (!validVector(vector))
+            throw invalid();
+        return { index: index, vector: normalize(vector) };
+    });
+    return vectors.sort((a, b) => a.index - b.index).map(row => row.vector);
+}
+function batched(texts, size, request, signal) {
+    return (async () => {
+        const vectors = [];
+        for (let start = 0; start < texts.length; start += size) {
+            throwIfCancelled(signal);
+            vectors.push(...await request(texts.slice(start, start + size)));
+        }
+        return vectors;
+    })();
+}
+function checkBatch(size, limit, label) {
+    if (!Number.isSafeInteger(size) || size < 1 || size > limit)
+        throw new Error(`${label} batch size must be an integer from 1 to ${limit}`);
+    return size;
+}
+const voyageDimensions = [256, 512, 1024, 2048];
+const voyageSharedSpace = new Set(['voyage-4-large', 'voyage-4', 'voyage-4-lite', 'voyage-4-nano']);
+const voyageSpace = (model) => voyageSharedSpace.has(model) ? 'voyage-4' : model;
+// Voyage separates queries from documents with `input_type`. The key comes from VOYAGE_API_KEY, or from the variable `keyEnv`
+// names, and is never stored.
+export function voyageProvider(options) {
+    const model = options.model;
+    if (!model)
+        throw new Error('Choose a Voyage model, for example voyage-4-large');
+    const dimension = options.dimension ?? 1024;
+    if (!voyageDimensions.includes(dimension))
+        throw new Error(`Voyage dimension must be one of ${voyageDimensions.join(', ')}`);
+    const batchSize = checkBatch(options.batchSize ?? 64, 1000, 'Voyage');
+    const endpoint = options.endpoint ?? 'https://api.voyageai.com/v1/embeddings';
+    return {
+        name: 'voyage', model, dimension, space: voyageSpace(model), backend: hash(endpoint), documentFingerprint: hash(['voyage', endpoint, model, dimension, 'document', true]),
+        embed(texts, inputType, signal) {
+            return batched(texts, batchSize, async (input) => {
+                const keyEnv = options.keyEnv ?? 'VOYAGE_API_KEY';
+                const apiKey = options.apiKey ?? process.env[keyEnv];
+                if (!apiKey)
+                    throw new Error(`Set ${keyEnv} to embed text`);
+                const body = await postJson('Voyage', endpoint, { authorization: `Bearer ${apiKey}` }, { input, model, input_type: inputType, output_dimension: dimension, truncation: true }, { ...options, signal });
+                return vectorsFrom('Voyage', body, input.length, dimension, model);
+            }, signal);
+        }
+    };
+}
+const openAIDimensions = { 'text-embedding-3-small': 1536, 'text-embedding-3-large': 3072, 'text-embedding-ada-002': 1536 };
+// OpenAI's embeddings API and the many servers that copy it (Azure, OpenRouter, Ollama, vLLM, and others). It has no query or
+// document distinction, so both use the same call, and each model is its own space. The optional prefixes serve models that
+// expect one, such as `query: ` and `passage: `. Only `text-embedding-3` models accept a `dimensions` request.
+export function openAIProvider(options) {
+    const model = options.model;
+    if (!model)
+        throw new Error('Choose an embedding model, for example text-embedding-3-small');
+    const dimension = options.dimension ?? openAIDimensions[model];
+    if (!dimension)
+        throw new Error(`Pass a dimension for model ${model}; only OpenAI's own models have a known default`);
+    if (!Number.isSafeInteger(dimension) || dimension < 1)
+        throw new Error('Dimension must be a positive integer');
+    const batchSize = checkBatch(options.batchSize ?? 64, 2048, 'OpenAI');
+    const baseUrl = (options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/+$/, '');
+    const local = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(baseUrl);
+    const keyEnv = options.keyEnv ?? 'OPENAI_API_KEY';
+    const sendDimensions = model.startsWith('text-embedding-3');
+    return {
+        name: 'openai', model, dimension, space: model, backend: hash(baseUrl), documentFingerprint: hash(['openai', baseUrl, model, dimension, options.documentPrefix ?? '', sendDimensions]),
+        embed(texts, inputType, signal) {
+            const prefix = inputType === 'query' ? options.queryPrefix : options.documentPrefix;
+            return batched(texts, batchSize, async (input) => {
+                const apiKey = options.apiKey ?? process.env[keyEnv];
+                if (!apiKey && !local)
+                    throw new Error(`Set ${keyEnv} to embed text`);
+                const body = await postJson('Embeddings API', `${baseUrl}/embeddings`, apiKey ? { authorization: `Bearer ${apiKey}` } : {}, { input: prefix ? input.map(text => prefix + text) : input, model, encoding_format: 'float', ...(sendDimensions ? { dimensions: dimension } : {}) }, { ...options, signal });
+                return vectorsFrom('Embeddings API', body, input.length, dimension, model);
+            }, signal);
+        }
+    };
+}
+export function createProvider(config = {}) {
+    const { provider, model } = config;
+    if (!provider)
+        throw new Error('Choose an embedding provider: voyage or openai');
+    if (!model)
+        throw new Error(`Choose an embedding model for ${provider}`);
+    if (provider === 'voyage') {
+        if (config.baseUrl)
+            throw new Error('baseUrl applies only to the openai provider');
+        return voyageProvider({ ...config, model });
+    }
+    if (provider === 'openai')
+        return openAIProvider({ ...config, model });
+    throw new Error(`Unknown embedding provider ${provider}; use voyage or openai`);
+}
+// Vectors are unit-length float32, one row per passage in `ids` order. The metadata file says which model made them and which
+// passage text each row was made from, so a vector is never reused for text that changed.
+export async function writeEmbeddings(directory, meta, vectors) {
+    if (vectors.length !== meta.ids.length || meta.digests.length !== meta.ids.length || (meta.inputDigests && meta.inputDigests.length !== meta.ids.length) || vectors.some(vector => vector.length !== meta.dimension || !validVector(vector)))
+        throw new Error('Embeddings do not match their metadata');
+    const target = await aiDirectory(directory);
+    const buffer = Buffer.alloc(vectors.length * meta.dimension * 4);
+    vectors.forEach((vector, row) => Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).copy(buffer, row * meta.dimension * 4));
+    const vectorFile = path.join(target, 'embeddings.bin');
+    const metaFile = path.join(target, 'embeddings.json');
+    await writeFile(vectorFile, buffer);
+    await writeFile(metaFile, JSON.stringify(meta) + '\n');
+    return { metaFile, vectorFile, bytes: buffer.length };
+}
+export async function readEmbeddings(directory) {
+    const target = path.join(path.resolve(directory), 'ai');
+    try {
+        const real = await realpath(target);
+        const root = await realpath(path.resolve(directory));
+        if (real !== root && !real.startsWith(root + path.sep))
+            throw new Error('The ai directory leaves the site directory');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let meta;
+    let bytes;
+    try {
+        meta = JSON.parse(await readFile(path.join(target, 'embeddings.json'), 'utf8'));
+        bytes = await readFile(path.join(target, 'embeddings.bin'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (meta?.schemaVersion !== 1 || !Number.isSafeInteger(meta.dimension) || meta.dimension < 1 || !Array.isArray(meta.ids) || !Array.isArray(meta.digests) || meta.ids.length !== meta.digests.length || (meta.inputDigests !== undefined && (!Array.isArray(meta.inputDigests) || meta.inputDigests.length !== meta.ids.length)))
+        throw new Error('Unsupported or invalid embeddings.json');
+    if (bytes.length !== meta.ids.length * meta.dimension * 4)
+        throw new Error('embeddings.bin does not match embeddings.json; run shoalrun index --embed again');
+    const floats = new Float32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+    meta.space ??= meta.provider === 'voyage' ? voyageSpace(meta.model) : meta.model;
+    const vectors = meta.ids.map((_, row) => floats.slice(row * meta.dimension, (row + 1) * meta.dimension));
+    if (vectors.some(vector => !validVector(vector)))
+        throw new Error('embeddings.bin contains invalid vectors; run shoalrun index --embed again');
+    return { meta, vectors };
+}
+// Embed every passage that has no current vector. Reuse requires the same provider, model, vector space, dimension, and
+// passage digest, so editing one page re-embeds that page's passages and nothing else.
+export async function embedChunkIndex(directory, index, provider, input) {
+    const stored = await readEmbeddings(directory).catch(() => undefined);
+    const inputs = index.chunks.map(input);
+    const inputDigests = inputs.map(text => hash(text));
+    const known = new Map();
+    if (stored && stored.meta.provider === provider.name && stored.meta.model === provider.model && stored.meta.space === provider.space && stored.meta.dimension === provider.dimension && stored.meta.backend === provider.backend && stored.meta.documentFingerprint === provider.documentFingerprint && stored.meta.inputDigests)
+        stored.meta.inputDigests.forEach((digest, row) => known.set(digest, stored.vectors[row]));
+    const missing = [...new Map(inputDigests.map((digest, at) => [digest, inputs[at]]).filter(([digest]) => !known.has(digest))).values()];
+    const fresh = missing.length ? await provider.embed(missing, 'document') : [];
+    if (fresh.length !== missing.length)
+        throw new Error('Embedding provider returned the wrong number of vectors');
+    missing.forEach((item, at) => known.set(hash(item), fresh[at]));
+    const written = await writeEmbeddings(directory, { schemaVersion: 1, provider: provider.name, model: provider.model, space: provider.space, dimension: provider.dimension, sourceDigest: index.sourceDigest, ids: index.chunks.map(chunk => chunk.id), digests: index.chunks.map(chunk => chunk.digest), inputDigests, ...(provider.backend ? { backend: provider.backend } : {}), ...(provider.documentFingerprint ? { documentFingerprint: provider.documentFingerprint } : {}) }, inputDigests.map(digest => known.get(digest)));
+    return { passages: index.chunks.length, embedded: missing.length, reused: index.chunks.length - missing.length, model: provider.model, dimension: provider.dimension, bytes: written.bytes };
+}

package/dist/focused-audit.d.ts

@@ -0,0 +1,10 @@
+export declare function auditFocusedContracts(siteDirectory: string): Promise<{
+    status: string;
+    contracts: any;
+    totalBytes: number;
+    largestBytes: number;
+    failures: {
+        documentId: string;
+        message: string;
+    }[];
+}>;

package/dist/focused-audit.js

@@ -0,0 +1,69 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+const methods = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']);
+export async function auditFocusedContracts(siteDirectory) {
+    const root = path.resolve(siteDirectory);
+    const manifest = JSON.parse(await readFile(path.join(root, 'documents.json'), 'utf8'));
+    const pages = manifest.documents.filter((doc) => doc.focusedContractUrl);
+    const failures = [];
+    let totalBytes = 0;
+    let largestBytes = 0;
+    for (const page of pages) {
+        try {
+            const route = page.focusedContractUrl;
+            if (!/^\/api\/operations\/[A-Za-z0-9._/-]+\.json$/.test(route) || route.includes('..'))
+                throw new Error(`Unsafe focused contract route ${route}`);
+            const file = path.join(root, route.slice(1));
+            const contract = JSON.parse(await readFile(file, 'utf8'));
+            const bytes = (await stat(file)).size;
+            totalBytes += bytes;
+            largestBytes = Math.max(largestBytes, bytes);
+            if (!/^3\.(0|1)\./.test(String(contract.openapi)))
+                throw new Error('Missing supported OpenAPI version');
+            if (typeof contract.info?.title !== 'string' || typeof contract.info?.version !== 'string')
+                throw new Error('Missing OpenAPI info');
+            const paths = Object.entries(contract.paths ?? contract.webhooks ?? {});
+            if (contract.paths && contract.webhooks)
+                throw new Error('Contract must select paths or webhooks, not both');
+            if (paths.length !== 1 || Object.keys(paths[0][1]).filter(key => methods.has(key)).length !== 1)
+                throw new Error('Contract must contain exactly one operation');
+            const operation = Object.values(paths[0][1]).find(value => value?.operationId);
+            if (!operation)
+                throw new Error('Contract operation lacks operationId');
+            const walk = (value) => {
+                if (!value || typeof value !== 'object')
+                    return;
+                if (Array.isArray(value)) {
+                    value.forEach(walk);
+                    return;
+                }
+                if (typeof value.$ref === 'string') {
+                    const ref = value.$ref;
+                    if (!ref.startsWith('#/components/'))
+                        throw new Error(`External reference ${ref}`);
+                    const resolved = ref.slice(2).split('/').reduce((at, segment) => at?.[segment.replaceAll('~1', '/').replaceAll('~0', '~')], contract);
+                    if (resolved === undefined || resolved === null)
+                        throw new Error(`Unresolved reference ${ref}`);
+                }
+                if (value.discriminator?.mapping) {
+                    for (const target of Object.values(value.discriminator.mapping)) {
+                        if (typeof target !== 'string' || !target.startsWith('#/components/'))
+                            throw new Error(`Unresolved discriminator mapping ${target}`);
+                        const resolved = target.slice(2).split('/').reduce((at, segment) => at?.[segment.replaceAll('~1', '/').replaceAll('~0', '~')], contract);
+                        if (resolved === undefined || resolved === null)
+                            throw new Error(`Missing discriminator target ${target}`);
+                    }
+                }
+                Object.values(value).forEach(walk);
+            };
+            walk(contract);
+            const markdown = await readFile(path.join(root, page.markdownUrl.slice(1)), 'utf8');
+            if (!markdown.includes(route))
+                throw new Error('Markdown page does not link to its contract');
+        }
+        catch (error) {
+            failures.push({ documentId: page.id, message: error.message });
+        }
+    }
+    return { status: failures.length ? 'error' : 'ok', contracts: pages.length, totalBytes, largestBytes, failures };
+}

package/dist/focused-openapi.d.ts

@@ -0,0 +1,2 @@
+import { ApiReader } from './api.js';
+export declare function focusedOpenApi(reader: ApiReader, sourceFile: string, sourceOperationId: string): Promise<any>;

package/dist/focused-openapi.js

@@ -0,0 +1,140 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const componentKinds = new Set(['schemas', 'responses', 'parameters', 'examples', 'requestBodies', 'headers', 'securitySchemes', 'links', 'callbacks', 'pathItems']);
+const kindByField = { schema: 'schemas', schemas: 'schemas', parameters: 'parameters', requestBody: 'requestBodies', requestBodies: 'requestBodies', responses: 'responses', examples: 'examples', headers: 'headers', links: 'links', callbacks: 'callbacks', securitySchemes: 'securitySchemes', pathItems: 'pathItems' };
+const escapePointer = (value) => value.replaceAll('~', '~0').replaceAll('/', '~1');
+const unescapePointer = (value) => value.replaceAll('~1', '/').replaceAll('~0', '~');
+const hash = (value) => createHash('sha256').update(value).digest('hex').slice(0, 10);
+export async function focusedOpenApi(reader, sourceFile, sourceOperationId) {
+    const source = await reader.load(sourceFile);
+    const api = source.value;
+    if (!/^3\.(0|1)\./.test(String(api.openapi)))
+        throw new Error('Focused OpenAPI export supports 3.0.x and 3.1.x');
+    let match;
+    for (const [collection, webhook] of [[api.paths ?? {}, false], [api.webhooks ?? {}, true]])
+        for (const [route, initial] of Object.entries(collection)) {
+            const selected = initial?.$ref ? await reader.ref(source, initial.$ref) : { value: initial, source };
+            const pathItem = selected.value;
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (!['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'].includes(method) || operation?.operationId !== sourceOperationId)
+                    continue;
+                if (match)
+                    throw new Error(`Duplicate OpenAPI operationId ${sourceOperationId}`);
+                match = { route, method, pathItem, pathSource: selected.source, operation, webhook };
+            }
+        }
+    if (!match)
+        throw new Error(`Missing OpenAPI operationId ${sourceOperationId}`);
+    if (match.pathItem.$ref)
+        throw new Error(`Focused OpenAPI does not yet support Path Item references: ${sourceOperationId}`);
+    const components = {};
+    const names = new Map();
+    const register = async (from, reference, inferredKind) => {
+        const separator = reference.indexOf('#');
+        const relative = separator < 0 ? reference : reference.slice(0, separator);
+        const pointer = separator < 0 ? '' : reference.slice(separator + 1);
+        const parsed = /^\/components\/([^/]+)\/([^/]+)(\/.*)?$/.exec(pointer);
+        const declaredKind = parsed?.[1];
+        if (declaredKind && !componentKinds.has(declaredKind))
+            throw new Error(`Unsupported component kind ${declaredKind}`);
+        const kind = declaredKind ?? inferredKind;
+        if (!kind || !componentKinds.has(kind))
+            throw new Error(`Cannot classify focused OpenAPI reference ${reference}`);
+        const basePointer = parsed ? `/components/${parsed[1]}/${parsed[2]}` : pointer;
+        const baseReference = `${relative}#${basePointer}`;
+        const resolved = await reader.ref(from, baseReference);
+        const identity = `${resolved.source.file}#${basePointer}|${kind}`;
+        let target = names.get(identity);
+        if (!target) {
+            const originalName = parsed ? unescapePointer(parsed[2]) : '';
+            const portableIdentity = `${path.relative(path.dirname(source.file), resolved.source.file).split(path.sep).join('/')}#${basePointer}|${kind}`;
+            const localName = resolved.source.file === source.file && parsed ? originalName : `Focused_${hash(portableIdentity)}`;
+            if (!/^[A-Za-z0-9._-]+$/.test(localName))
+                throw new Error(`Invalid focused component name ${localName}`);
+            target = { kind, name: localName };
+            names.set(identity, target);
+            const bucket = (components[kind] ??= {});
+            if (bucket[localName] !== undefined)
+                throw new Error(`Focused component collision ${kind}/${localName}`);
+            bucket[localName] = null;
+            bucket[localName] = await walk(resolved.value, resolved.source, kind);
+        }
+        return `#/components/${target.kind}/${escapePointer(target.name)}${parsed?.[3] ?? ''}`;
+    };
+    const walk = async (value, from, kind) => {
+        if (Array.isArray(value))
+            return Promise.all(value.map(item => walk(item, from, kind)));
+        if (!value || typeof value !== 'object')
+            return value;
+        if (kind === 'schemas' && (value.$id || value.$anchor || value.$dynamicRef || value.$dynamicAnchor))
+            throw new Error(`Focused OpenAPI needs an adapter for JSON Schema IDs or anchors in ${from.file}`);
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key.startsWith('x-'))
+                continue;
+            if (key === '$ref') {
+                if (typeof child !== 'string')
+                    throw new Error(`Invalid $ref in ${from.file}`);
+                result.$ref = await register(from, child, kind);
+            }
+            else if (key === 'discriminator' && child?.mapping && kind === 'schemas') {
+                const mapping = {};
+                for (const [name, target] of Object.entries(child.mapping)) {
+                    if (typeof target !== 'string')
+                        throw new Error(`Invalid discriminator mapping ${name}`);
+                    if (from.value.components?.schemas?.[target])
+                        mapping[name] = await register(from, `#/components/schemas/${escapePointer(target)}`, 'schemas');
+                    else if (target.includes('#') || target.startsWith('.') || target.includes('/') || /\.(?:ya?ml|json)$/i.test(target))
+                        mapping[name] = await register(from, target, 'schemas');
+                    else
+                        throw new Error(`Unresolved discriminator mapping ${name}: ${target}`);
+                }
+                result[key] = { ...child, mapping };
+            }
+            else if (['example', 'default', 'enum', 'const', 'security'].includes(key) || (kind === 'examples' && key === 'value') || (kind === 'schemas' && key === 'examples')) {
+                // Payloads and requirement names are data, not OpenAPI objects.
+                result[key] = child;
+            }
+            else {
+                const childKind = kind === 'schemas' ? 'schemas' : kindByField[key] ?? kind;
+                const isMap = kind === 'schemas'
+                    ? ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas'].includes(key)
+                    : ['content', 'responses', 'examples', 'headers', 'links', 'callbacks', 'variables', 'flows', 'scopes'].includes(key);
+                // Map keys are user-defined names, including names such as x-trace or $ref.
+                result[key] = isMap && child && typeof child === 'object' && !Array.isArray(child)
+                    ? Object.fromEntries(await Promise.all(Object.entries(child).map(async ([name, entry]) => [name, await walk(entry, from, childKind)])))
+                    : await walk(child, from, childKind);
+            }
+        }
+        return result;
+    };
+    const { route, method, pathItem, pathSource, operation, webhook } = match;
+    const operationFields = ['tags', 'summary', 'description', 'externalDocs', 'operationId', 'parameters', 'requestBody', 'responses', 'deprecated', 'security', 'servers'];
+    const selectedOperation = Object.fromEntries(operationFields.filter(key => operation[key] !== undefined).map(key => [key, operation[key]]));
+    const selectedPath = Object.fromEntries(['summary', 'description', 'parameters', 'servers'].filter(key => pathItem[key] !== undefined).map(key => [key, pathItem[key]]));
+    const focusedPath = { ...await walk(selectedPath, pathSource), [method]: await walk(selectedOperation, pathSource) };
+    const effectiveSecurity = operation.security ?? api.security;
+    for (const requirement of effectiveSecurity ?? []) {
+        for (const name of Object.keys(requirement)) {
+            if (!api.components?.securitySchemes?.[name])
+                throw new Error(`Unknown security scheme ${name}`);
+            await register(source, `#/components/securitySchemes/${escapePointer(name)}`, 'securitySchemes');
+        }
+    }
+    const info = { title: String(api.info?.title ?? 'API'), version: String(api.info?.version ?? 'unspecified') };
+    const output = { openapi: api.openapi, info };
+    if (api.jsonSchemaDialect)
+        output.jsonSchemaDialect = api.jsonSchemaDialect;
+    if (!webhook && api.servers && !pathItem.servers && !operation.servers)
+        output.servers = await walk(api.servers, source);
+    if (operation.security === undefined && api.security !== undefined)
+        output.security = api.security;
+    if (Array.isArray(api.tags) && Array.isArray(operation.tags))
+        output.tags = api.tags.filter((tag) => operation.tags.includes(tag.name));
+    output[webhook ? 'webhooks' : 'paths'] = { [route]: focusedPath };
+    if (Object.keys(components).length)
+        output.components = Object.fromEntries(Object.entries(components).sort(([a], [b]) => a.localeCompare(b)).map(([kind, bucket]) => [
+            kind, Object.fromEntries(Object.entries(bucket).sort(([a], [b]) => a.localeCompare(b)))
+        ]));
+    return output;
+}