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

package/dist/reader-filters.js

@@ -0,0 +1,105 @@
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const identifier = /^[a-z][a-z0-9-]*$/;
+export function validateReaderSelection(value, config, where) {
+    if (!object(value))
+        throw new Error(`${where} must be a mapping of filter names to lists of choices`);
+    const result = {};
+    for (const [facet, choices] of Object.entries(value)) {
+        if (!Object.hasOwn(config.facets, facet))
+            throw new Error(`${where}.${facet} is not a configured reader filter`);
+        if (!Array.isArray(choices) || choices.some(choice => typeof choice !== 'string' || !config.facets[facet].options[choice]) || new Set(choices).size !== choices.length) {
+            throw new Error(`${where}.${facet} must be a unique list of configured choices`);
+        }
+        result[facet] = choices;
+    }
+    return result;
+}
+export function validateReaderFilters(value) {
+    if (value === undefined)
+        return undefined;
+    if (!object(value) || Object.keys(value).some(key => !['facets', 'typeDefaults', 'controls', 'module'].includes(key)) || !object(value.facets) || !Object.keys(value.facets).length) {
+        throw new Error('readerFilters needs a nonempty facets mapping and optional typeDefaults');
+    }
+    const facets = {};
+    for (const [name, raw] of Object.entries(value.facets)) {
+        if (!identifier.test(name) || !object(raw) || Object.keys(raw).some(key => !['label', 'options'].includes(key)) || typeof raw.label !== 'string' || !raw.label.trim() || !object(raw.options) || !Object.keys(raw.options).length) {
+            throw new Error(`readerFilters.facets.${name} needs a label and nonempty options mapping`);
+        }
+        const options = {};
+        for (const [id, label] of Object.entries(raw.options)) {
+            if (!identifier.test(id) || typeof label !== 'string' || !label.trim())
+                throw new Error(`readerFilters.facets.${name}.options.${id} needs a readable label`);
+            options[id] = label;
+        }
+        facets[name] = { label: raw.label, options };
+    }
+    const config = { facets, typeDefaults: {}, controls: { sidebar: true } };
+    if (value.typeDefaults !== undefined) {
+        if (!object(value.typeDefaults))
+            throw new Error('readerFilters.typeDefaults must be a mapping by page type');
+        for (const [type, filters] of Object.entries(value.typeDefaults)) {
+            if (!identifier.test(type))
+                throw new Error(`readerFilters.typeDefaults has invalid page type ${type}`);
+            config.typeDefaults[type] = validateReaderSelection(filters, config, `readerFilters.typeDefaults.${type}`);
+        }
+    }
+    if (value.controls !== undefined) {
+        if (!object(value.controls) || Object.keys(value.controls).some(key => !['sidebar', 'header'].includes(key)))
+            throw new Error('readerFilters.controls accepts sidebar and header');
+        if (value.controls.sidebar !== undefined) {
+            if (typeof value.controls.sidebar !== 'boolean')
+                throw new Error('readerFilters.controls.sidebar must be true or false');
+            config.controls.sidebar = value.controls.sidebar;
+        }
+        if (value.controls.header !== undefined)
+            config.controls.header = validateReaderFilterControl(value.controls.header, config, 'readerFilters.controls.header');
+    }
+    if (value.module !== undefined) {
+        if (typeof value.module !== 'string' || !/\.m?js$/.test(value.module) || /^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(value.module))
+            throw new Error('readerFilters.module must be a local .js or .mjs path');
+        config.module = value.module;
+    }
+    return config;
+}
+export function validateReaderFilterControl(value, config, where, allowPageScope = false) {
+    if (!object(value) || Object.keys(value).some(key => !['facet', 'display', 'label', ...(allowPageScope ? ['scope'] : [])].includes(key)))
+        throw new Error(`${where} accepts facet, display, label${allowPageScope ? ', and scope' : ''}`);
+    if (value.facet !== undefined && (typeof value.facet !== 'string' || !Object.hasOwn(config.facets, value.facet)))
+        throw new Error(`${where}.facet must name a configured facet`);
+    if (value.display !== undefined && !['select', 'checks'].includes(String(value.display)))
+        throw new Error(`${where}.display must be select or checks`);
+    if (value.label !== undefined && (typeof value.label !== 'string' || !value.label.trim()))
+        throw new Error(`${where}.label must be nonempty text`);
+    if (value.scope !== undefined && value.scope !== 'site' && value.scope !== 'page')
+        throw new Error(`${where}.scope must be site or page`);
+    return { ...(value.facet ? { facet: value.facet } : {}), display: value.display ?? 'select', ...(value.label ? { label: value.label } : {}), ...(value.scope === 'page' ? { scope: 'page' } : {}) };
+}
+export function pageReaderFilters(frontmatter, config, file) {
+    if (!config) {
+        if (frontmatter.readerFilters !== undefined)
+            throw new Error(`${file}: readerFilters needs readerFilters.facets in the site config`);
+        return {};
+    }
+    const explicit = frontmatter.readerFilters === undefined ? {} : validateReaderSelection(frontmatter.readerFilters, config, `${file}: readerFilters`);
+    if (frontmatter.audiences && config.facets.audience) {
+        if (object(frontmatter.readerFilters) && Object.hasOwn(frontmatter.readerFilters, 'audience'))
+            throw new Error(`${file}: use audiences or readerFilters.audience, not both`);
+        explicit.audience = validateReaderSelection({ audience: frontmatter.audiences }, config, `${file}: audiences`).audience ?? [];
+    }
+    for (const facet of ['product', 'area', 'subarea']) {
+        const category = frontmatter[facet];
+        if (category === undefined || !config.facets[facet])
+            continue;
+        if (object(frontmatter.readerFilters) && Object.hasOwn(frontmatter.readerFilters, facet))
+            throw new Error(`${file}: use ${facet} or readerFilters.${facet}, not both`);
+        explicit[facet] = validateReaderSelection({ [facet]: Array.isArray(category) ? category : [category] }, config, `${file}: category`)[facet];
+    }
+    return Object.fromEntries(Object.entries({ ...(config.typeDefaults[frontmatter.type] ?? {}), ...explicit }).filter(([, choices]) => choices.length));
+}
+export function readerFilterAttribute(selection) {
+    return JSON.stringify(selection);
+}
+export function readerViewParam(selection) {
+    const parts = Object.entries(selection).filter(([, values]) => values.length).map(([facet, values]) => `${facet}:${values.join(',')}`);
+    return parts.length ? parts.join(';') : 'all';
+}

package/dist/recipe-draft.d.ts

@@ -0,0 +1,17 @@
+export declare function renderRecipeDraft(configFile: string, specFile: string): Promise<{
+    content: string;
+    sourceDigest: string;
+    ingredients: string[];
+}>;
+export declare function writeRecipeDraft(configFile: string, specFile: string, outputFile: string, checkOnly?: boolean): Promise<{
+    content: string;
+    sourceDigest: string;
+    ingredients: string[];
+    status: string;
+    output: string;
+} | {
+    status: string;
+    output: string;
+    sourceDigest: string;
+    ingredients: string[];
+}>;

package/dist/recipe-draft.js

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { loadConfig } from './config.js';
+import { defaultLanguage } from './frontmatter.js';
+import { ingredientWorkflow, workflowValues } from './ingredient-workflow.js';
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+function parseYaml(source, file) {
+    const document = YAML.parseDocument(source, { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`${file}: ${document.errors.map(error => error.message).join('; ')}`);
+    return document.toJS();
+}
+function parseSpec(value) {
+    if (!object(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !['schemaVersion', 'id', 'title', 'summary', 'slug', 'ingredients', 'inputs', 'outcome'].includes(key)))
+        throw new Error('Recipe spec needs schemaVersion: 1 and only supported fields');
+    workflowValues(value.inputs, 'Recipe inputs');
+    if (value.outcome !== undefined && (typeof value.outcome !== 'string' || !value.outcome.trim()))
+        throw new Error('Recipe outcome must be nonempty text');
+    for (const field of ['id', 'title', 'summary', 'slug'])
+        if (typeof value[field] !== 'string' || !value[field].trim())
+            throw new Error(`Recipe spec needs ${field}`);
+    if (!/^\/[a-z0-9/-]+$/.test(value.slug) || value.slug.includes('//'))
+        throw new Error('Recipe slug must be a lowercase absolute path');
+    if (!Array.isArray(value.ingredients) || !value.ingredients.length || value.ingredients.some(item => typeof item !== 'string' || !item.trim()))
+        throw new Error('Recipe spec needs an ordered list of ingredient files');
+    return value;
+}
+function parseIngredient(source, file) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
+    if (!match)
+        throw new Error(`${file}: ingredient needs YAML frontmatter and a body`);
+    const header = parseYaml(match[1], file);
+    if (!object(header) || header.type !== 'ingredient' || typeof header.id !== 'string' || !header.id.trim() || typeof header.title !== 'string' || !header.title.trim())
+        throw new Error(`${file}: ingredient needs type: ingredient, id, and title`);
+    if (!match[2].trim())
+        throw new Error(`${file}: ingredient body is empty`);
+    return { header, body: match[2].trim() };
+}
+function nestHeadings(body) {
+    const lines = body.split('\n');
+    const tree = unified().use(remarkParse).use(remarkMdx).parse(body);
+    for (const node of tree.children) {
+        if (node.type !== 'heading' || node.depth < 2 || node.depth > 5 || !node.position)
+            continue;
+        const line = node.position.start.line - 1;
+        lines[line] = lines[line].replace(new RegExp(`^#{${node.depth}}(?=\\s)`), '#'.repeat(node.depth + 1));
+    }
+    return lines.join('\n');
+}
+export async function renderRecipeDraft(configFile, specFile) {
+    const configPath = path.resolve(configFile);
+    const root = path.dirname(configPath);
+    const config = (await loadConfig(configPath)).value;
+    const spec = parseSpec(parseYaml(await readFile(specFile, 'utf8'), specFile));
+    const defaults = config.publications?.defaults ?? {};
+    if (!defaults.channel || !defaults.version)
+        throw new Error('Recipe draft needs a default channel and version');
+    const language = defaults.language ?? defaultLanguage(config);
+    const seen = new Set();
+    const operations = new Set();
+    const sources = [];
+    const sections = [];
+    const available = new Map(Object.keys(spec.inputs ?? {}).map(name => [name, 'Before you start']));
+    const prerequisites = new Set();
+    for (const ingredientPath of spec.ingredients) {
+        const file = await realpath(path.resolve(path.dirname(specFile), ingredientPath));
+        const relative = path.relative(root, file);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            throw new Error(`Ingredient file must be inside the project: ${ingredientPath}`);
+        const source = await readFile(file, 'utf8');
+        const { header, body } = parseIngredient(source, file);
+        if (seen.has(header.id))
+            throw new Error(`Recipe repeats ingredient ${header.id}`);
+        seen.add(header.id);
+        const workflow = ingredientWorkflow(header.workflow, `Ingredient ${header.id} workflow`);
+        const handoffs = [];
+        if (workflow) {
+            for (const [name, description] of Object.entries(workflow.inputs)) {
+                const producer = available.get(name);
+                if (!producer)
+                    throw new Error(`Ingredient ${header.id} needs ${name}; declare it in recipe inputs or produce it in an earlier ingredient`);
+                handoffs.push(`- Use \`${name}\` from **${producer}**: ${description}`);
+            }
+            for (const name of Object.keys(workflow.outputs)) {
+                if (available.has(name))
+                    throw new Error(`Ingredient ${header.id} repeats output ${name}; use a distinct value name`);
+                available.set(name, header.title);
+            }
+            for (const prerequisite of workflow.prerequisites)
+                prerequisites.add(prerequisite);
+        }
+        if (header.channel !== defaults.channel || header.version !== defaults.version || header.language !== language)
+            throw new Error(`Ingredient ${header.id} must match the recipe's default publication`);
+        if (header.operations !== undefined) {
+            if (!Array.isArray(header.operations) || header.operations.some(value => typeof value !== 'string'))
+                throw new Error(`Ingredient ${header.id} has invalid operations`);
+            for (const operation of header.operations)
+                operations.add(operation);
+        }
+        sources.push(`${relative}\n${source}`);
+        const nestedBody = nestHeadings(body);
+        sections.push(workflow
+            ? [`## ${header.title}`, handoffs.join('\n'), nestedBody, ...Object.entries(workflow.outputs).map(([name, description]) => `Save \`${name}\`: ${description}`), `**Continue when:** ${workflow.check}`].filter(Boolean).join('\n\n')
+            : `## ${header.title}\n\n> Ingredient: \`${header.id}\` from \`${relative}\`. Review how it connects to the other steps.\n\n${nestedBody}`);
+    }
+    const header = {
+        id: spec.id, title: spec.title, summary: spec.summary, type: 'recipe', slug: spec.slug,
+        channel: defaults.channel, version: defaults.version, language,
+        ...(operations.size ? { operations: [...operations] } : {}), access: { policy: 'draft' }
+    };
+    const sourceDigest = digest([JSON.stringify(spec), ...sources].join('\n'));
+    const body = [
+        `> Assembled draft from ${spec.ingredients.length} configured ingredient${spec.ingredients.length === 1 ? '' : 's'} (${sourceDigest.slice(0, 12)}). Review the complete workflow before publishing.`,
+        spec.summary,
+        '## Before you start',
+        Object.keys(spec.inputs ?? {}).length || prerequisites.size
+            ? [...Object.entries(spec.inputs ?? {}).map(([name, description]) => `- \`${name}\`: ${description}`), ...[...prerequisites].map(value => `- ${value}`)].join('\n')
+            : '[[TODO: Combine the prerequisites for this whole outcome. Remove repeated setup and name the exact starting state.]]',
+        ...sections,
+        '## Check the outcome',
+        spec.outcome ?? '[[TODO: Verify the customer goal end to end, not just each ingredient. Give an observable success value and a first failure check.]]',
+        '## Review before publishing',
+        '- Confirm ingredient order and that outputs from one step satisfy inputs to the next.\n- Test the complete workflow in a safe environment.\n- Replace TODOs and remove this review section.\n- Inspect both HTML and Markdown output.'
+    ].join('\n\n');
+    return { content: `---\n${YAML.stringify(header).trimEnd()}\n---\n\n${body}\n`, sourceDigest, ingredients: [...seen] };
+}
+export async function writeRecipeDraft(configFile, specFile, outputFile, checkOnly = false) {
+    const result = await renderRecipeDraft(configFile, specFile);
+    const output = path.resolve(outputFile);
+    if (checkOnly) {
+        const current = await readFile(output, 'utf8').catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        return { status: current === undefined ? 'would-create' : current === result.content ? 'unchanged' : 'would-change', output, ...result };
+    }
+    await mkdir(path.dirname(output), { recursive: true });
+    await writeFile(output, result.content, { flag: 'wx' });
+    return { status: 'created', output, sourceDigest: result.sourceDigest, ingredients: result.ingredients };
+}

package/dist/reference-audit.d.ts

@@ -0,0 +1,18 @@
+type Failure = {
+    operationId: string;
+    message: string;
+    source?: string;
+    location?: string;
+    keyword?: string;
+};
+export declare function auditReference(file: string): Promise<{
+    status: string;
+    operations: number;
+    rendered: number;
+    namedExamples: number;
+    htmlBytes: number;
+    markdownBytes: number;
+    failures: Failure[];
+    dependencies: string[];
+}>;
+export {};

package/dist/reference-audit.js

@@ -0,0 +1,169 @@
+import { ApiReader, supportedSchemaKeywords } from './api.js';
+import { renderHtml, renderMarkdown, root } from './content.js';
+const methods = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']);
+const pointer = (parts) => `#/${parts.map(part => part.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`;
+// Audit traverses schema-bearing OpenAPI objects only. Examples, defaults, and
+// extension values can contain arbitrary JSON and must never be read as schemas.
+async function schemaFailures(reader, source, operationId, pathParts, method, pathItem, operation) {
+    const failures = [];
+    const found = new Set();
+    const base = [...pathParts, method];
+    async function scan(value, at, parts, scope, refs) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return;
+        for (const key of Object.keys(value)) {
+            if (supportedSchemaKeywords.has(key) || key.startsWith('x-'))
+                continue;
+            const location = pointer([...parts, key]);
+            const identity = `${at.file}|${location}`;
+            if (found.has(identity))
+                continue;
+            found.add(identity);
+            failures.push({ operationId, message: `Unsupported schema keyword ${key} at ${scope.join('/')} in ${at.file} (${location})`, source: at.file, location, keyword: key });
+        }
+        if (typeof value.$ref === 'string') {
+            const resolved = await reader.ref(at, value.$ref);
+            if (!refs.has(resolved.identity)) {
+                const fragment = resolved.identity.slice(resolved.source.file.length + 1);
+                const nextParts = fragment.startsWith('/') ? fragment.slice(1).split('/').map(part => part.replaceAll('~1', '/').replaceAll('~0', '~')) : [];
+                await scan(resolved.value, resolved.source, nextParts, scope, new Set([...refs, resolved.identity]));
+            }
+        }
+        for (const name of ['items', 'additionalProperties'])
+            if (value[name] && typeof value[name] === 'object')
+                await scan(value[name], at, [...parts, name], [...scope, name], refs);
+        for (const name of ['properties'])
+            for (const [key, child] of Object.entries(value[name] ?? {}))
+                await scan(child, at, [...parts, name, key], [...scope, key], refs);
+        for (const name of ['allOf', 'oneOf', 'anyOf'])
+            for (const [index, child] of (value[name] ?? []).entries())
+                await scan(child, at, [...parts, name, String(index)], [...scope, name, String(index + 1)], refs);
+    }
+    async function resolved(initial, at, parts) {
+        if (typeof initial?.$ref !== 'string')
+            return { value: initial, source: at, parts };
+        const ref = await reader.ref(at, initial.$ref);
+        const fragment = ref.identity.slice(ref.source.file.length + 1);
+        return { value: ref.value, source: ref.source, parts: fragment.startsWith('/') ? fragment.slice(1).split('/').map(part => part.replaceAll('~1', '/').replaceAll('~0', '~')) : [] };
+    }
+    const parameters = new Map();
+    for (const [index, initial] of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])].entries()) {
+        const where = index < (pathItem.parameters?.length ?? 0) ? [...pathParts, 'parameters', String(index)] : [...base, 'parameters', String(index - (pathItem.parameters?.length ?? 0))];
+        const parameter = await resolved(initial, source, where);
+        parameters.set(`${parameter.value?.in}|${parameter.value?.name}`, parameter);
+    }
+    for (const parameter of parameters.values()) {
+        if (parameter.value?.schema)
+            await scan(parameter.value.schema, parameter.source, [...parameter.parts, 'schema'], ['parameter', parameter.value.in ?? '', parameter.value.name ?? ''], new Set());
+    }
+    if (operation.requestBody) {
+        const body = await resolved(operation.requestBody, source, [...base, 'requestBody']);
+        for (const [mediaType, media] of Object.entries(body.value?.content ?? {}))
+            if (media?.schema)
+                await scan(media.schema, body.source, [...body.parts, 'content', mediaType, 'schema'], ['request', mediaType], new Set());
+    }
+    for (const [status, initial] of Object.entries(operation.responses ?? {})) {
+        const response = await resolved(initial, source, [...base, 'responses', status]);
+        for (const [mediaType, media] of Object.entries(response.value?.content ?? {}))
+            if (media?.schema)
+                await scan(media.schema, response.source, [...response.parts, 'content', mediaType, 'schema'], ['response', status, mediaType], new Set());
+    }
+    return failures;
+}
+export async function auditReference(file) {
+    const reader = new ApiReader();
+    const source = (await reader.load(file)).value;
+    const mapping = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+    if (!mapping(source))
+        throw new Error(`${file}: OpenAPI root must be a mapping. Supply an OpenAPI YAML or JSON document.`);
+    if (typeof source.openapi !== 'string' || !/^3\.(0|1)\.\d+$/.test(source.openapi))
+        throw new Error(`${file}: OpenAPI 3.0.x or 3.1.x required. Set the openapi version or convert the source to a supported version.`);
+    if (!mapping(source.info) || typeof source.info.title !== 'string' || !source.info.title.trim() || typeof source.info.version !== 'string' || !source.info.version.trim())
+        throw new Error(`${file}: info.title and info.version must be nonempty strings.`);
+    for (const key of ['paths', 'webhooks'])
+        if (source[key] !== undefined && !mapping(source[key]))
+            throw new Error(`${file}: ${key} must be a mapping of names to path items.`);
+    if (source.webhooks !== undefined && source.openapi.startsWith('3.0.'))
+        throw new Error(`${file}: webhooks require OpenAPI 3.1. Use a supported 3.1.x source.`);
+    const operations = [];
+    const failures = [];
+    const operationSites = new Map();
+    for (const [collection, webhook] of [[source.paths ?? {}, false], [source.webhooks ?? {}, true]])
+        for (const [route, initial] of Object.entries(collection)) {
+            const rootSource = await reader.load(file);
+            const selected = initial?.$ref ? await reader.ref(rootSource, initial.$ref) : undefined;
+            const pathItem = selected?.value ?? initial;
+            if (!mapping(pathItem)) {
+                failures.push({ operationId: route, source: file, location: pointer([webhook ? 'webhooks' : 'paths', route]), message: `Path item must be a mapping at ${route}. Supply an operation object or a local $ref.` });
+                continue;
+            }
+            const pathSource = selected?.source ?? rootSource;
+            const fragment = selected?.identity.slice(pathSource.file.length + 1);
+            const pathParts = fragment?.startsWith('/') ? fragment.slice(1).split('/').map(part => part.replaceAll('~1', '/').replaceAll('~0', '~')) : [webhook ? 'webhooks' : 'paths', route];
+            for (const [method, operation] of Object.entries(pathItem ?? {})) {
+                if (!methods.has(method))
+                    continue;
+                if (typeof operation?.operationId !== 'string' || !operation.operationId) {
+                    failures.push({ operationId: `${webhook ? 'WEBHOOK' : method.toUpperCase()} ${route}`, message: 'Missing operationId' });
+                }
+                else {
+                    operations.push(operation.operationId);
+                    if (!operationSites.has(operation.operationId))
+                        operationSites.set(operation.operationId, { source: pathSource, pathParts, method, pathItem, operation });
+                }
+            }
+        }
+    const seen = new Set();
+    let rendered = 0;
+    let examples = 0;
+    let htmlBytes = 0;
+    let markdownBytes = 0;
+    for (const operationId of operations) {
+        if (seen.has(operationId)) {
+            failures.push({ operationId, message: 'Duplicate operationId' });
+            continue;
+        }
+        seen.add(operationId);
+        const site = operationSites.get(operationId);
+        let unsupported = [];
+        try {
+            unsupported = await schemaFailures(reader, site.source, operationId, site.pathParts, site.method, site.pathItem, site.operation);
+            failures.push(...unsupported);
+        }
+        catch (error) {
+            failures.push({ operationId, message: `Schema audit: ${error.message}` });
+        }
+        try {
+            const generated = await reader.operation(file, operationId);
+            const tree = root(generated.blocks);
+            const html = renderHtml(tree);
+            const markdown = renderMarkdown(tree);
+            const anchors = [...html.matchAll(/<li id="(field-[^"]+)"/g)].map(match => match[1]);
+            if (new Set(anchors).size !== anchors.length)
+                throw new Error('Duplicate field anchor');
+            for (const example of generated.examples) {
+                if (!html.includes(example.title) || !markdown.includes(example.title))
+                    throw new Error(`Named example missing from a representation: ${example.key}`);
+            }
+            if (!unsupported.length)
+                rendered += 1;
+            examples += generated.examples.length;
+            htmlBytes += Buffer.byteLength(html);
+            markdownBytes += Buffer.byteLength(markdown);
+        }
+        catch (error) {
+            if (!unsupported.length || !/^Unsupported schema keyword /.test(error.message))
+                failures.push({ operationId, message: error.message });
+        }
+    }
+    return {
+        status: failures.length ? 'error' : 'ok',
+        operations: operations.length,
+        rendered,
+        namedExamples: examples,
+        htmlBytes,
+        markdownBytes,
+        failures,
+        dependencies: [...reader.dependencies].sort()
+    };
+}

package/dist/remote-import.d.ts

@@ -0,0 +1,62 @@
+type Download = (url: URL) => Promise<Buffer>;
+type Options = {
+    download?: Download;
+    output?: string;
+};
+export declare function isPublicImportAddress(address: string, family: number): boolean;
+export declare function importRemoteOpenApi(url: string, directory: string, options?: Options): Promise<{
+    status: "imported";
+    directory: string;
+    entry: string;
+    files: {
+        url: string;
+        path: string;
+        digest: string;
+        snapshotDigest: string;
+    }[];
+    changes: {
+        url: string;
+        before: string | null;
+        after: string | null;
+        snapshotBefore: string | null;
+        snapshotAfter: string | null;
+    }[];
+}>;
+export declare function refreshRemoteOpenApi(directory: string, options?: Options): Promise<{
+    status: "unchanged";
+    directory: string;
+    entry: string;
+    files: {
+        url: string;
+        path: string;
+        digest: string;
+        snapshotDigest: string;
+    }[];
+    changes: {
+        url: string;
+        before: string | null;
+        after: string | null;
+        snapshotBefore: string | null;
+        snapshotAfter: string | null;
+    }[];
+    previousDirectory?: undefined;
+} | {
+    status: "updated";
+    directory: string;
+    previousDirectory: string;
+    entry: string;
+    files: {
+        url: string;
+        path: string;
+        digest: string;
+        snapshotDigest: string;
+    }[];
+    changes: {
+        url: string;
+        before: string | null;
+        after: string | null;
+        snapshotBefore: string | null;
+        snapshotAfter: string | null;
+    }[];
+}>;
+export {};