@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/code-references.js

@@ -0,0 +1,371 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { renderHtmlWithHeadings } from './html-renderer.js';
+import { readCodeReference } from './code-reference-model.js';
+import { explainSegments } from './config.js';
+import { resolvePublication } from './compiler-config.js';
+import { resolveFrontmatter, validateFrontmatter, applyFormattingLocale } from './frontmatter.js';
+import { matchesFeatures, validateFeatureClassification } from './deployment-profile.js';
+import { pageReaderFilters } from './reader-filters.js';
+import { matchesContentFilter } from './content-filter.js';
+import { documentKey } from './publication-identity.js';
+import { routeFor, markdownRoute } from './content-source.js';
+import { heading, paragraph, text, parsePlainMarkdown, root } from './semantic-markdown.js';
+const mapping = z.record(z.string(), z.unknown());
+const source = z.object({ kind: z.literal('file'), path: z.string().min(1) }).strict();
+const override = z.object({ documentId: z.string().min(1).optional(), slug: z.string().startsWith('/').optional(), metadata: mapping.optional() }).strict();
+const catalogSchema = z.object({
+    source: source.optional(),
+    sourceLink: z.object({ baseUrl: z.string().url().refine(value => { const url = new URL(value); return url.protocol === 'https:' && !url.username && !url.password && !url.search && !url.hash; }, 'Source links need an HTTPS base URL without credentials, query or fragment') }).strict().optional(),
+    publications: z.array(z.object({ product: z.string().optional(), channel: z.string(), version: z.string(), language: z.string().optional(), source }).strict()).min(1).optional(),
+    layout: z.enum(['symbols', 'classes', 'modules']).default('symbols'),
+    singlePage: z.union([z.literal(false), z.object({ documentId: z.string().min(1).optional(), slug: z.string().startsWith('/').optional(), title: z.string().min(1).default('Complete API reference'), summary: z.string().min(1).default('Classes, functions, and fields in this publication.'), metadata: mapping.optional() }).strict()]).optional(),
+    pathPrefix: z.string().regex(/^\/[a-zA-Z0-9_/-]+$/).default('/reference/code'),
+    metadata: mapping.optional(),
+    include: z.array(z.string()).optional(), exclude: z.array(z.string()).optional(),
+    symbols: z.record(z.string(), override).optional()
+}).strict().refine(value => !!value.source !== !!value.publications, 'Declare source or publications');
+const hash = (value) => createHash('sha256').update(value).digest('hex').slice(0, 16);
+export function codeDocumentId(catalog, symbol) { return `reference.${catalog}.${/^[A-Za-z0-9_.-]+$/.test(symbol) ? symbol : hash(symbol)}`; }
+export async function materializeCodeReferences(input) {
+    const { config, loaded, plan, base, basePath, variants, language, readerFilters, contentFilter, dependencies } = input;
+    if (config.codeReferences === undefined)
+        return;
+    const catalogs = z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), catalogSchema).parse(config.codeReferences);
+    const owners = new Map([...plan.knownDocumentIds].map(id => [id, 'authored']));
+    for (const [catalogId, catalog] of Object.entries(catalogs)) {
+        const bindings = catalog.publications ?? [{ ...resolvePublication(config.publications, config.publications.defaults ?? {}, language), source: catalog.source }];
+        const seenPublications = new Set();
+        for (const [index, binding] of bindings.entries()) {
+            const variant = resolvePublication(config.publications, binding, language);
+            const identity = documentKey(catalogId, variant);
+            if (seenPublications.has(identity))
+                throw new Error(`Duplicate code reference publication ${identity}`);
+            seenPublications.add(identity);
+            const segments = ['codeReferences', catalogId, ...(catalog.publications ? ['publications', String(index)] : []), 'source', 'path'];
+            const owner = explainSegments(loaded, segments).source.file;
+            if (path.isAbsolute(binding.source.path) || /^[a-z][a-z0-9+.-]*:/i.test(binding.source.path))
+                throw new Error('Code reference sources need local relative paths');
+            const file = path.resolve(path.dirname(owner), binding.source.path);
+            dependencies.add(file);
+            const snapshot = await readCodeReference(file, base);
+            const symbols = new Map(snapshot.symbols.map(symbol => [symbol.id, symbol]));
+            for (const name of [...catalog.include ?? [], ...catalog.exclude ?? [], ...Object.keys(catalog.symbols ?? {})])
+                if (!symbols.has(name))
+                    throw new Error(`Code reference ${catalogId}: unknown selected symbol ${name}`);
+            const visibility = new Map();
+            for (const symbol of snapshot.symbols) {
+                const chain = [];
+                let ancestor = symbol;
+                while (ancestor && !visibility.has(ancestor.id)) {
+                    chain.push(ancestor);
+                    ancestor = ancestor.parent ? symbols.get(ancestor.parent) : undefined;
+                }
+                let visible = ancestor ? visibility.get(ancestor.id) : true;
+                for (const entry of chain.reverse()) {
+                    visible = visible && entry.visibility === 'public';
+                    visibility.set(entry.id, visible);
+                }
+            }
+            for (const symbol of snapshot.symbols) {
+                const selected = visibility.get(symbol.id) && (!catalog.include || catalog.include.includes(symbol.id)) && !catalog.exclude?.includes(symbol.id);
+                const setting = catalog.symbols?.[symbol.id];
+                const inherited = { ...catalog.metadata };
+                if (setting?.metadata && (Object.hasOwn(setting.metadata, 'shared') || Object.hasOwn(setting.metadata, 'requires'))) {
+                    delete inherited.shared;
+                    delete inherited.requires;
+                }
+                const metadata = { ...inherited, ...setting?.metadata };
+                const id = setting?.documentId ?? codeDocumentId(catalogId, symbol.id);
+                const ownerId = `${catalogId}:${symbol.id}`;
+                if (owners.has(id) && owners.get(id) !== ownerId)
+                    throw new Error(`Duplicate code reference document ID ${id}`);
+                owners.set(id, ownerId);
+                plan.knownDocumentIds.add(id);
+                const existing = plan.knownDocumentTypes.get(id);
+                if (existing && existing !== 'code-reference')
+                    throw new Error(`Duplicate code reference document ID ${id}`);
+                plan.knownDocumentTypes.set(id, 'code-reference');
+                const pageSource = {
+                    ...metadata, id, title: symbol.name, summary: symbol.summary ?? `${symbol.kind}: ${symbol.id}`,
+                    type: 'code-reference', slug: setting?.slug ?? `${catalog.pathPrefix}/${symbol.id.toLowerCase().replace(/[^a-z0-9_-]+/g, '-')}-${hash(symbol.id)}`,
+                    ...variant
+                };
+                const frontmatter = resolveFrontmatter(pageSource, config.frontmatter);
+                frontmatter.access ??= { policy: 'public' };
+                if (catalog.layout !== 'symbols')
+                    frontmatter.tocDepth ??= 2;
+                for (const [field, expected] of Object.entries({ id, type: 'code-reference', ...variant }))
+                    if (frontmatter[field] !== expected)
+                        throw new Error(`Code reference ${id}: enforced ${field} conflicts with its catalog`);
+                applyFormattingLocale(frontmatter, config.frontmatter, pageSource);
+                validateFrontmatter(frontmatter, config.frontmatter, file, pageSource);
+                const classification = loaded.deployment?.context.classificationPublications ?? variants;
+                if (selected && frontmatter.access?.policy === 'public' && classification.some(item => documentKey(catalogId, item) === identity))
+                    validateFeatureClassification(metadata, loaded.deployment?.context, `${file}: ${symbol.id}`);
+                if (!selected || !matchesFeatures(frontmatter.requires, loaded.deployment?.context, `${file}: ${symbol.id}`) || !variants.some(item => documentKey(catalogId, item) === identity))
+                    continue;
+                if (frontmatter.access?.policy !== 'public')
+                    continue;
+                const marks = pageReaderFilters(frontmatter, readerFilters, file);
+                if (!matchesContentFilter(marks, contentFilter))
+                    continue;
+                const key = documentKey(id, variant);
+                if (plan.docs.has(key))
+                    throw new Error(`Duplicate code reference document ${id}`);
+                const route = routeFor(frontmatter, variant, config);
+                const collision = plan.routeOwners.get(route.toLowerCase());
+                if (collision && !input.allowRouteCollisions)
+                    throw new Error(`Code reference route collision ${route}`);
+                plan.routeOwners.set(route.toLowerCase(), key);
+                plan.docs.set(key, { file, frontmatter, variant, route, markdownRoute: markdownRoute(route, basePath), readerFilters: marks, featureContext: loaded.deployment?.context, body: '', tree: null, codeReference: { catalog: catalogId, programmingLanguage: snapshot.programmingLanguage, symbol, layout: catalog.layout, ...(catalog.sourceLink && symbol.source ? { sourceUrl: catalog.sourceLink.baseUrl.replace(/\/$/, '') + '/' + symbol.source.path.split('/').map(encodeURIComponent).join('/') + (symbol.source.line ? `#L${symbol.source.line}` : '') } : {}) } });
+            }
+            if (catalog.singlePage) {
+                const single = catalog.singlePage;
+                const id = single.documentId ?? `reference.${catalogId}.complete`;
+                const ownerId = `${catalogId}:complete-page`;
+                if (owners.has(id) && owners.get(id) !== ownerId)
+                    throw new Error(`Duplicate code reference document ID ${id}`);
+                owners.set(id, ownerId);
+                plan.knownDocumentIds.add(id);
+                plan.knownDocumentTypes.set(id, 'code-reference');
+                const inherited = { ...catalog.metadata };
+                if (single.metadata && (Object.hasOwn(single.metadata, 'shared') || Object.hasOwn(single.metadata, 'requires'))) {
+                    delete inherited.shared;
+                    delete inherited.requires;
+                }
+                const metadata = { ...inherited, ...single.metadata };
+                const source = { ...metadata, id, title: single.title, summary: single.summary, type: 'code-reference', slug: single.slug ?? `${catalog.pathPrefix}/all`, ...variant };
+                const frontmatter = resolveFrontmatter(source, config.frontmatter);
+                frontmatter.access ??= { policy: 'public' };
+                for (const [field, expected] of Object.entries({ id, type: 'code-reference', ...variant }))
+                    if (frontmatter[field] !== expected)
+                        throw new Error(`Code reference ${id}: enforced ${field} conflicts with its catalog`);
+                applyFormattingLocale(frontmatter, config.frontmatter, source);
+                validateFrontmatter(frontmatter, config.frontmatter, file, source);
+                frontmatter.tocDepth ??= 2;
+                const active = variants.some(item => documentKey(catalogId, item) === identity);
+                const classification = loaded.deployment?.context.classificationPublications ?? variants;
+                if (frontmatter.access?.policy === 'public' && classification.some(item => documentKey(catalogId, item) === identity))
+                    validateFeatureClassification(metadata, loaded.deployment?.context, `${file}: ${id}`);
+                const granted = matchesFeatures(frontmatter.requires, loaded.deployment?.context, `${file}: ${id}`);
+                const marks = pageReaderFilters(frontmatter, readerFilters, file);
+                const hasContent = [...plan.docs.values()].some(doc => doc.codeReference?.catalog === catalogId && documentKey(catalogId, doc.variant) === identity);
+                if (active && granted && hasContent && frontmatter.access.policy === 'public' && matchesContentFilter(marks, contentFilter)) {
+                    const key = documentKey(id, variant);
+                    if (plan.docs.has(key))
+                        throw new Error(`Duplicate code reference document ${id}`);
+                    const route = routeFor(frontmatter, variant, config);
+                    if (plan.routeOwners.has(route.toLowerCase()) && !input.allowRouteCollisions)
+                        throw new Error(`Code reference route collision ${route}`);
+                    plan.routeOwners.set(route.toLowerCase(), key);
+                    plan.docs.set(key, { file, frontmatter, variant, route, markdownRoute: markdownRoute(route, basePath), readerFilters: marks, featureContext: loaded.deployment?.context, body: '', tree: null,
+                        codeReference: { catalog: catalogId, programmingLanguage: snapshot.programmingLanguage, complete: true, symbol: { id, name: single.title, kind: 'module', visibility: 'public' } } });
+                }
+            }
+        }
+    }
+}
+/** Imported prose is inert Markdown; it never enters MDX or project directive expansion. */
+export function renderCodeReference(reference, doc, documents) {
+    const eligible = new Map();
+    for (const candidate of documents.values())
+        if (candidate.codeReference?.catalog === reference.catalog && !candidate.codeReference.complete && documentKey('scope', candidate.variant) === documentKey('scope', doc.variant))
+            eligible.set(candidate.codeReference.symbol.id, candidate);
+    const owner = (page) => {
+        let parent = page.codeReference.symbol.parent;
+        while (parent) {
+            const candidate = eligible.get(parent);
+            if (!candidate)
+                return;
+            const kind = candidate.codeReference.symbol.kind;
+            if (['module', 'namespace'].includes(kind) || reference.layout === 'classes' && ['class', 'interface', 'enum', 'type'].includes(kind))
+                return parent;
+            parent = candidate.codeReference.symbol.parent;
+        }
+    };
+    const embedded = [...eligible.values()].filter(page => reference.complete || reference.layout !== undefined && reference.layout !== 'symbols' && owner(page) === reference.symbol.id)
+        .sort((a, b) => a.codeReference.symbol.id < b.codeReference.symbol.id ? -1 : 1);
+    const blocks = reference.complete ? [] : renderCodeSymbol(reference, doc, eligible, false).children;
+    const headings = new Map();
+    for (const page of embedded) {
+        const entry = heading(2, page.codeReference.symbol.id);
+        headings.set(entry, page);
+        const content = renderCodeSymbol(page.codeReference, page, eligible, true).children;
+        const deepen = (node) => { if (node.type === 'heading')
+            node.depth = Math.min(6, node.depth + 1); for (const child of node.children ?? [])
+            deepen(child); };
+        content.forEach(deepen);
+        blocks.push(entry, ...content);
+    }
+    const tree = root(blocks);
+    if (embedded.length) {
+        // Use the renderer's actual heading allocation, including duplicate headings.
+        const reserved = ['main', 'docs-navigation', 'docs-sections', 'documentation-menu', 'page-outline', 'nav-filter', 'examples-title', 'api-view-select'];
+        const rendered = renderHtmlWithHeadings(tree, undefined, reserved).headings;
+        const targets = new Map();
+        let index = 0;
+        const collect = (node) => {
+            if (node.type === 'heading' && node.depth >= 2 && node.depth <= 6) {
+                const target = headings.get(node);
+                if (target)
+                    targets.set(target.frontmatter.id, rendered[index].id);
+                index++;
+            }
+            for (const child of node.children ?? [])
+                collect(child);
+        };
+        collect(tree);
+        const relink = (node) => {
+            const anchor = targets.get(node.exportDocumentId);
+            if (node.type === 'link' && anchor) {
+                node.url = `${doc.route}#${anchor}`;
+                node.exportDocumentId = doc.frontmatter.id;
+            }
+            for (const child of node.children ?? [])
+                relink(child);
+        };
+        relink(tree);
+    }
+    return tree;
+}
+function renderCodeSymbol(reference, doc, eligible, embedded) {
+    const prose = (value = '') => {
+        const parsed = parsePlainMarkdown(value);
+        const definitions = new Map();
+        const collect = (node) => { if (node.type === 'definition')
+            definitions.set(node.identifier.toLowerCase(), node); for (const child of node.children ?? [])
+            collect(child); };
+        parsed.forEach(collect);
+        const clean = (node) => {
+            if (node.type === 'definition')
+                return [];
+            if (node.type === 'linkReference') {
+                const definition = definitions.get(node.identifier.toLowerCase());
+                if (!definition)
+                    return (node.children ?? []).flatMap(clean);
+                node = { type: 'link', url: definition.url, title: definition.title, children: node.children };
+            }
+            if (node.type === 'image' || node.type === 'imageReference')
+                throw new Error(`${doc.file}: code reference prose images need explicit asset support`);
+            if (typeof node.url === 'string') {
+                if (node.url.startsWith('symbol:')) {
+                    const target = eligible.get(node.url.slice(7));
+                    if (!target)
+                        return (node.children ?? []).flatMap(clean);
+                    node = { ...node, url: target.route, exportDocumentId: target.frontmatter.id };
+                }
+                else {
+                    const url = new URL(node.url, 'https://code-reference.invalid');
+                    if (!['https:', 'mailto:'].includes(url.protocol) || url.username || url.password || url.origin === 'https://code-reference.invalid')
+                        throw new Error(`${doc.file}: unsupported code reference prose URL ${node.url}`);
+                }
+            }
+            return [{ ...node, ...(node.children ? { children: node.children.flatMap(clean) } : {}) }];
+        };
+        return parsed.flatMap(clean);
+    };
+    const symbol = reference.symbol;
+    const inlineCode = (value) => ({ type: 'inlineCode', value });
+    const code = (value, signature = false) => ({ type: 'code', lang: reference.programmingLanguage, value,
+        ...(signature ? { data: { hProperties: { className: [`language-${reference.programmingLanguage}`, 'code-reference-signature'] } } } : {}) });
+    const pageLink = (page, label = page.frontmatter.title) => ({ type: 'link', url: page.route, exportDocumentId: page.frontmatter.id, children: [inlineCode(label)] });
+    // References are explicit converter data; never guess an ambiguous short name.
+    const typeNodes = (value, context = symbol) => {
+        const tokens = Object.keys(context.typeReferences ?? {}).sort((a, b) => b.length - a.length);
+        if (!tokens.length)
+            return [inlineCode(value)];
+        const output = [];
+        let plain = '';
+        for (let offset = 0; offset < value.length;) {
+            const match = tokens.find(token => value.startsWith(token, offset) && !/[\p{L}\p{N}_.$]/u.test(value[offset - 1] ?? '') && !/[\p{L}\p{N}_.$]/u.test(value[offset + token.length] ?? ''));
+            const page = match ? eligible.get(context.typeReferences[match]) : undefined;
+            if (match && page) {
+                if (plain)
+                    output.push(inlineCode(plain));
+                plain = '';
+                output.push(pageLink(page, match));
+                offset += match.length;
+            }
+            else {
+                plain += value[offset];
+                offset++;
+            }
+        }
+        if (plain)
+            output.push(inlineCode(plain));
+        return output;
+    };
+    const table = (headers, rows, label) => ({ type: 'table', align: headers.map(() => null),
+        data: { referenceTableLabel: label, hProperties: { className: ['code-reference-table'] } }, children: [headers.map(value => [text(value)]), ...rows].map(cells => ({ type: 'tableRow', children: cells.map(children => ({ type: 'tableCell', children })) })) });
+    const summary = (value) => {
+        const nodes = prose(value);
+        const paragraph = nodes.find(node => node.type === 'paragraph');
+        return paragraph?.children ?? [text('—')];
+    };
+    const description = prose(symbol.description);
+    // Hide the repeated summary only in the website shell; exports retain it.
+    if (description[0]?.type === 'paragraph') {
+        const plain = (node) => node.value ?? (node.children ?? []).map(plain).join('');
+        if (!embedded && plain(description[0]).trim() === doc.frontmatter.summary.trim())
+            description[0] = { ...description[0], data: { hProperties: { className: ['code-reference-summary'] } } };
+    }
+    const identity = paragraph({ type: 'strong', children: [text(symbol.kind.charAt(0).toUpperCase() + symbol.kind.slice(1))] }, text(' '), inlineCode(symbol.id), ...(reference.sourceUrl ? [text(' · '), { type: 'link', url: reference.sourceUrl, children: [text('View source')] }] : []));
+    identity.data = { hProperties: { className: ['code-reference-identity'] } };
+    const blocks = [identity, ...(symbol.signatures?.length ? [code(symbol.signatures.join('\n\n'), true)] : []), ...description];
+    if (symbol.constructorSignature)
+        blocks.push(heading(2, 'Constructor'), code(symbol.constructorSignature, true));
+    if (symbol.bases?.length)
+        blocks.push(paragraph({ type: 'strong', children: [text('Bases: ')] }, ...symbol.bases.flatMap((base, i) => [...(i ? [text(', ')] : []), ...typeNodes(base)])));
+    if (symbol.annotation)
+        blocks.push(paragraph({ type: 'strong', children: [text('Type: ')] }, ...typeNodes(symbol.annotation)));
+    if (symbol.required !== undefined || symbol.default !== undefined)
+        blocks.push(paragraph(...(symbol.required === undefined ? [] : [text(symbol.required ? 'Required' : 'Optional')]), ...(symbol.default === undefined ? [] : [text(symbol.required === undefined ? 'Default: ' : ' · Default: '), inlineCode(symbol.default)])));
+    const details = (title, items) => {
+        if (!items.length)
+            return;
+        blocks.push(heading(2, title));
+        blocks.push(table(title === 'Parameters' ? ['Parameter', 'Type / default', 'Description'] : ['Exception', 'Description'], items.map(item => {
+            const kind = [...(item.type ? typeNodes(item.type) : [text('—')]), ...(item.default === undefined ? [] : [text(' = '), inlineCode(item.default)])];
+            return title === 'Parameters' ? [[inlineCode(item.name)], kind, summary(item.description)] : [typeNodes(item.name), summary(item.description)];
+        }), title));
+        // Preserve richer Markdown without forcing block content into a table cell.
+        for (const item of items) {
+            const content = prose(item.description);
+            if (content.length > 1 || content.some(node => node.type !== 'paragraph'))
+                blocks.push(heading(3, item.name), ...content);
+        }
+    };
+    details('Parameters', symbol.parameters ?? []);
+    for (const [title, result] of [['Returns', symbol.returns], ['Yields', symbol.yields]])
+        if (result) {
+            blocks.push(heading(2, title));
+            if (result.type)
+                blocks.push(paragraph(...typeNodes(result.type)));
+            blocks.push(...prose(result.description));
+        }
+    details('Raises', symbol.raises ?? []);
+    if (symbol.examples?.length) {
+        blocks.push(heading(2, 'Examples'));
+        for (const example of symbol.examples)
+            blocks.push(...(example.title ? [heading(3, example.title)] : []), code(example.code));
+    }
+    const members = [...eligible.values()].filter(item => item.codeReference?.symbol.parent === symbol.id).sort((a, b) => a.frontmatter.title < b.frontmatter.title ? -1 : a.frontmatter.title > b.frontmatter.title ? 1 : 0);
+    const fields = members.filter(page => ['attribute', 'property', 'constant'].includes(page.codeReference.symbol.kind));
+    const callables = members.filter(page => ['function', 'method', 'constructor'].includes(page.codeReference.symbol.kind));
+    const types = members.filter(page => !fields.includes(page) && !callables.includes(page));
+    for (const [title, pages] of [['Fields', fields], [['module', 'namespace'].includes(symbol.kind) ? 'Functions' : 'Methods', callables], ['Members', types]])
+        if (pages.length) {
+            blocks.push(heading(2, title), table(title === 'Fields' ? ['Name', 'Type', 'Required / default', 'Description'] : ['Name', 'Kind', 'Description'], pages.map(page => {
+                const member = page.codeReference.symbol;
+                const declaration = member.signatures?.[0];
+                const annotation = declaration?.startsWith(member.name + ': ') ? declaration.slice(member.name.length + 2) : undefined;
+                return title === 'Fields' ? [[pageLink(page)], typeNodes(member.annotation ?? annotation ?? member.kind, member), [...(member.required === undefined ? [] : [text(member.required ? 'Required' : 'Optional')]), ...(member.default === undefined ? [] : [text(member.required === undefined ? '' : ' · '), inlineCode(member.default)]), ...(member.required === undefined && member.default === undefined ? [text('—')] : [])], summary(member.summary ?? member.description)] : [[pageLink(page)], [inlineCode(member.kind)], summary(member.summary ?? member.description)];
+            }), title));
+        }
+    const related = (symbol.seeAlso ?? []).flatMap(id => eligible.has(id) ? [eligible.get(id)] : []);
+    if (related.length)
+        blocks.push(heading(2, 'See also'), { type: 'list', ordered: false, children: related.map(page => ({ type: 'listItem', children: [paragraph(pageLink(page))] })) });
+    return root(blocks);
+}

package/dist/compiler-config.d.ts

@@ -13,6 +13,7 @@ export interface ResolvedCompilerConfig extends ConfigMapping {
     navigation?: unknown;
     redirects?: unknown;
     apis?: unknown;
+    codeReferences?: unknown;
     relationships?: unknown;
     variables?: unknown;
     snippets?: unknown;

package/dist/compiler.d.ts

@@ -6,13 +6,14 @@ export declare function checkThemeContrast(configFile: string): Promise<{
     modes: Mode[];
     palette: string;
 }>;
-export declare function compile(configFile: string, destination?: string, provenance?: BuildProvenance, options?: {
+type CompileOptions = {
     apiReview?: 'report';
     sourceOverrides?: ReadonlyMap<string, string>;
     authoringFiles?: ReadonlySet<string>;
     profile?: string;
     onDependency?: (file: string) => void;
-}): Promise<{
+};
+export declare function compile(configFile: string, destination?: string, provenance?: BuildProvenance, options?: CompileOptions): Promise<{
     authoringSources?: {
         id: string;
         file: string;
@@ -240,3 +241,4 @@ export declare function compile(configFile: string, destination?: string, proven
     schemaVersion: number;
     configDigest: string;
 }>;
+export {};

package/dist/compiler.js

@@ -1,3 +1,5 @@
+import { buildPdfSiteArtifacts } from './pdf-site.js';
+import { resolvePdfButton, validatePdfButtonStyle } from './pdf-button.js';
 import { documentKey, publicationKey, samePublication } from './publication-identity.js';
 import { validateHeader, validateFooter } from './site-identity.js';
 import { profileSelection } from './deployment-profile.js';
@@ -16,7 +18,7 @@ import { validateAuthoringGuidance } from './authoring-guidance.js';
 import { loadFreshness } from './freshness.js';
 import { resolveAgentDiscovery } from './agent-discovery.js';
 import { iconLicenseFile } from './icons.js';
-import { bundledFontLicenses, bundledFonts, fontsCss, resolveFonts } from './fonts.js';
+import { bundledFontLicenses, bundledFonts, fontsCss, resolveFonts, prepareFontAssets, customFontPreloads } from './fonts.js';
 import { bundledShareFonts, resolveShareImages, shareRoute } from './share-images.js';
 import { buildInfo } from './build-info.js';
 import { validateRelationships } from './cards.js';
@@ -102,6 +104,15 @@ export async function checkThemeContrast(configFile) {
     return { modes, palette: palette.name };
 }
 export async function compile(configFile, destination, provenance = {}, options = {}) {
+    let dispose;
+    try {
+        return await compileProject(configFile, destination, provenance, options, release => { dispose = release; });
+    }
+    finally {
+        dispose?.();
+    }
+}
+async function compileProject(configFile, destination, provenance, options, ownHighlighter) {
     const loaded = await loadConfig(configFile, { profile: options.profile, onDependency: options.onDependency });
     const componentPlugins = await loadComponentPlugins(loaded);
     const provenanceRecord = buildInfo(loaded.digest, provenance);
@@ -118,9 +129,15 @@ export async function compile(configFile, destination, provenance = {}, options
     const calloutTypes = resolveCalloutTypes(config.callouts, configFile);
     const badgeVariants = resolveBadgeVariants(config.badges, configFile);
     const htmlOptions = configField(config.outputs, 'html');
+    const pdfButton = resolvePdfButton(config.outputs);
+    validatePdfButtonStyle(pdfButton, config.exports);
     const highlighting = configField(htmlOptions, 'highlighting');
     const highlightingOrigin = configField(highlighting, 'module') === undefined ? configFile : explainSegments(loaded, ['outputs', 'html', 'highlighting', 'module']).source.file;
-    const highlighter = await createCodeHighlighter(highlighting, highlightingOrigin);
+    const highlighter = await createCodeHighlighter(highlighting, highlightingOrigin, {
+        grammarOrigin: index => explainSegments(loaded, ['outputs', 'html', 'highlighting', 'languages', String(index), 'grammar']).source.file,
+        onDependency: options.onDependency
+    });
+    ownHighlighter(highlighter.dispose);
     const base = path.dirname(path.resolve(configFile));
     if (config.site.customCss !== undefined && (typeof config.site.customCss !== 'string' || !config.site.customCss.endsWith('.css')))
         throw new Error('site.customCss must be a local .css path');
@@ -158,6 +175,7 @@ export async function compile(configFile, destination, provenance = {}, options
     for (const face of fonts.faces)
         if (fonts.faces.some(other => other.route === face.route && other.file !== face.file))
             throw new Error(`theme.fonts: two font files share the name ${path.basename(face.file)}; rename one`);
+    const projectFontAssets = await prepareFontAssets(fonts);
     const generatedFontsCss = fontsCss(fonts);
     // A temporary preview aid: a floating shape and palette switcher on every page. Remove it before launch.
     // `demo` ships it hidden until a page is opened with ?theme-switcher.
@@ -313,7 +331,7 @@ export async function compile(configFile, destination, provenance = {}, options
     const cardUses = new Map();
     const publishedRelationships = [];
     const styleFiles = ['site.css', 'tokens.css', 'header.css'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../styles', name));
-    const scriptFiles = [...(analyticsModule ? ['analytics.js'] : []), 'code-samples.js', 'cookbook-chooser.js', 'example-panel.js', 'mode.js', 'copy-markdown.js', 'components.js', 'navigation.js', 'reader.js', ...(readerFilters ? ['reader-filters.js'] : []), 'search-highlight.js', 'search.js', 'table-filter.js', 'tabs.js', 'tooltips.js', 'file-tree.js', 'image-viewer.js', 'walkthrough.js'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets', name));
+    const scriptFiles = [...(analyticsModule ? ['analytics.js'] : []), 'code-samples.js', 'cookbook-chooser.js', 'example-panel.js', 'mode.js', ...(pdfButton?.mode === 'print' ? ['print.js', 'print-view.js'] : []), 'copy-markdown.js', 'components.js', 'navigation.js', 'reader.js', ...(readerFilters ? ['reader-filters.js'] : []), 'search-highlight.js', 'search.js', 'table-filter.js', 'tabs.js', 'tooltips.js', 'file-tree.js', 'image-viewer.js', 'walkthrough.js'].map(name => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets', name));
     const documentRoutes = new Set([...docs.values()].map(doc => doc.route));
     const { apiPublications, focusedContracts, navigationEntries, navigationTagOrder, rendered, snippetUses, apiEmbedUses, operations } = await materializePages({
         variables: isConfigMapping(config.variables) ? config.variables : {}, frontmatterConfig: config.frontmatter,
@@ -379,8 +397,8 @@ export async function compile(configFile, destination, provenance = {}, options
     const resolvedNavigation = renderPublicationPages({
         freshness,
         rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes,
-        basePath, siteOrigin, colorMode, config, highlighter, editionLabel, customStyleFile, themePreset, palette,
-        themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload: fonts.preload,
+        basePath, siteOrigin, colorMode, config: options.authoringFiles ? { ...config, outputs: { ...config.outputs, html: { ...htmlOptions, pdf: false } } } : config, highlighter, editionLabel, customStyleFile, themePreset, palette,
+        themeStyleFile, generatedPaletteCss, generatedBadgeCss, themeSwitcherData, generatedFontsCss, fontsPreload: fonts.preload, customFontPreloads: customFontPreloads(fonts),
         shareFor, faviconRoute, logoRoute, modeToggle, header, footer, search, readerFilters, variants, externalDocuments,
         externalSiteLinks, navigationSpec, navigationEntries, navigationTagOrder
     });
@@ -442,7 +460,14 @@ export async function compile(configFile, destination, provenance = {}, options
             ] };
     }
     const apiPublicationReview = await reviewApiPublication(configFile, apiPlan, rendered, apiEmbedUses, focusedContracts, apiSources, sourceForOperation, options.apiReview);
-    const manifestDependencies = [...new Set([...loaded.dependencies, ...componentPlugins.dependencies, ...externalManifestFiles, ...api.dependencies, ...(metadataProvider ? [metadataProvider.module] : []), ...metadataDependencies, ...(highlighter.dependency ? [highlighter.dependency] : []), ...styleFiles, ...(themeStyleFile ? [themeStyleFile] : []), ...palette.files, ...(search.module ? [search.module] : []), ...previewFiles, ...(customStyleFile ? [customStyleFile] : []), ...(customReaderModule ? [customReaderModule] : []), ...(analyticsModule ? [analyticsModule] : []), ...(mcpAnalyticsModule ? [mcpAnalyticsModule] : []), ...(shareImages.template ? [shareImages.template] : []), ...shareImages.fonts, ...(faviconFile ? [faviconFile] : []), ...heroImages.values(), ...walkthroughSources, ...fontFiles, ...fonts.faces.map(face => face.file), ...scriptFiles, iconLicenseFile, ...[...snippets.values()].map(s => s.file), ...[...docs.values()].map(d => d.file)])].sort();
+    if (pdfButton?.mode === 'endpoint') {
+        const endpoint = publicPath(pdfButton.endpoint);
+        const mcpEndpoint = configField(config.mcp, 'path') ?? '/mcp';
+        if (rendered.some(({ doc }) => doc.route === endpoint || endpoint.startsWith(`${doc.route}/`)) || redirects.some(rule => rule.from === endpoint) || endpoint === publicPath(String(mcpEndpoint)))
+            throw new Error(`PDF endpoint shadows an existing route: ${endpoint}`);
+    }
+    const sitePdfs = options.authoringFiles ? { artifacts: new Map(), dependencies: new Set() } : await buildPdfSiteArtifacts(configFile, { outputs: config.outputs, exports: config.exports, documents: rendered.map(page => page.doc), knownDocumentIds, basePath, profile: options.profile });
+    const manifestDependencies = [...new Set([...sitePdfs.dependencies, ...loaded.dependencies, ...componentPlugins.dependencies, ...externalManifestFiles, ...api.dependencies, ...(metadataProvider ? [metadataProvider.module] : []), ...metadataDependencies, ...(highlighter.dependency ? [highlighter.dependency] : []), ...(highlighter.dependencies ?? []), ...styleFiles, ...(themeStyleFile ? [themeStyleFile] : []), ...palette.files, ...(search.module ? [search.module] : []), ...previewFiles, ...(customStyleFile ? [customStyleFile] : []), ...(customReaderModule ? [customReaderModule] : []), ...(analyticsModule ? [analyticsModule] : []), ...(mcpAnalyticsModule ? [mcpAnalyticsModule] : []), ...(shareImages.template ? [shareImages.template] : []), ...shareImages.fonts, ...(faviconFile ? [faviconFile] : []), ...heroImages.values(), ...walkthroughSources, ...fontFiles, ...fonts.faces.map(face => face.file), ...scriptFiles, iconLicenseFile, ...[...snippets.values()].map(s => s.file), ...[...docs.values()].map(d => d.file)])].sort();
     const llmsDiscovery = resolveLlmsDiscovery(configField(config.outputs, 'llms'));
     const { manifest, headers, sitemaps } = buildPublicationManifest({
         configPublications: config.publications,
@@ -454,12 +479,13 @@ export async function compile(configFile, destination, provenance = {}, options
     });
     const artifactConfig = options.authoringFiles ? { ...config, mcp: false } : config;
     const { artifacts, buildId } = await assembleArtifacts({
+        extraArtifacts: sitePdfs.artifacts,
         base, basePath, publicPath, canonical, siteOrigin, manifest, provenanceRecord, rendered, sitemaps,
         privateDependencies: new Set([...(loaded.deployment?.file ? [loaded.deployment.file] : []), ...(loaded.deployment?.assetFiles ?? [])]),
         diagramAssets, heroImages, focusedContracts, styleFiles, themeStyleFile, generatedPaletteCss,
         generatedBadgeCss, search, synonyms, config: artifactConfig, builtInSearchProvider, customReaderModule, analyticsModule, mcpAnalyticsModule,
         previewFiles, assetDirectory, themeSwitcher, themeDirectory, palette, colorMode, generatedFontsCss,
-        fontFiles, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile,
+        fontFiles, projectFontAssets, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile,
         faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
         documentRoutes, readerFilters, apiSources
     });

package/dist/config.js

@@ -9,7 +9,7 @@ import { parseYaml } from './yaml-value.js';
 import { validateSearch } from './search-config.js';
 import { resolveTaxonomy } from './taxonomy.js';
 import { validateCookbooks } from './cookbook-chooser.js';
-const allowed = new Set(['profiles', 'exports', 'schemaVersion', 'site', 'navigation', 'redirects', 'apis', 'relationships', 'variables', 'snippets', 'callouts', 'badges', 'publications', 'outputs', 'templates', 'theme', 'frontmatter', 'metadata', 'audit', 'readerFilters', 'retrieval', 'chat', 'authoring', 'search', 'cookbooks', 'analytics', 'mcp', 'components']);
+const allowed = new Set(['profiles', 'exports', 'schemaVersion', 'site', 'navigation', 'redirects', 'apis', 'codeReferences', 'relationships', 'variables', 'snippets', 'callouts', 'badges', 'publications', 'outputs', 'templates', 'theme', 'frontmatter', 'metadata', 'audit', 'readerFilters', 'retrieval', 'chat', 'authoring', 'search', 'cookbooks', 'analytics', 'mcp', 'components']);
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const treeObject = (v) => object(v) && !('kind' in v && 'items' in v);
 export class ConfigError extends Error {

package/dist/content-export-command.d.ts

@@ -1,5 +1,81 @@
-export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both] [--document ID]...\n       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
+export declare const exportHelp = "Usage: shoalrun export [config] --out DIRECTORY [--target NAME]\n       [--format markdown|html|both|pdf] [--document ID]...\n       [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]\n       [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]\n\nExport selected pages, sections, and named snippets as Markdown and passive HTML.\nConfigure typed resources in an export target; --document selects whole pages.\nNavigation, facets, and a prior website build are not required.\n--format pdf exports one publication, or the selected whole pages, as a styled PDF.\nPDF uses outputs.pdf defaults and target pdf overrides; it follows navigation order\nand appends eligible unlisted pages. PDF defaults to the site's contentFilter.\n--review writes an API-review candidate; status needs-review exits 2 until pinned.\n--previous-manifest compares public references with an earlier reviewed export.\n--fail-on-removed requires that baseline and refuses to replace output if references disappear.\n";
 export declare function runExportCommand(args: string[]): Promise<{
+    digest: string;
+    preparedPdf: import("./content-export.js").PdfExportPreparation;
+    status: string;
+    output: string;
+    publication: import("./content-source.js").Variant;
+    formats: import("./content-export-config.js").ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
+    digest: string;
+    pdf: string;
+    status: string;
+    output: string;
+    publication: import("./content-source.js").Variant;
+    formats: import("./content-export-config.js").ExportFormat[];
+    profileSelection: {
+        schemaVersion: number;
+        profileDigest: string;
+        features: string[];
+        provenance: Record<string, string[]>;
+        decisions: {
+            kind: "page" | "section";
+            id: string;
+            included: boolean;
+            requires?: import("./deployment-profile.js").FeatureRequirements;
+        }[];
+    } | undefined;
+    resources: number;
+    documents: number;
+    documentIds: string[];
+    comparison: {
+        status: "no-baseline";
+        added: never[];
+        removed: never[];
+        diagnostics: never[];
+    };
+    assets: number;
+    apiReview: {
+        apiId: string;
+        digest: string;
+    }[];
+    diagnostics: {
+        code: string;
+        documentId?: string;
+        message: string;
+    }[];
+} | {
     status: string;
     output: string;
     publication: import("./content-source.js").Variant;

package/dist/content-export-command.js

@@ -1,12 +1,15 @@
 import { exportContent } from './content-export.js';
 export const exportHelp = `Usage: shoalrun export [config] --out DIRECTORY [--target NAME]
-       [--format markdown|html|both] [--document ID]...
+       [--format markdown|html|both|pdf] [--document ID]...
        [--channel C --version V --language L [--product P]] [--public-base /help/] [--review]
        [--profile FILE] [--previous-manifest FILE] [--fail-on-removed]
 
 Export selected pages, sections, and named snippets as Markdown and passive HTML.
 Configure typed resources in an export target; --document selects whole pages.
 Navigation, facets, and a prior website build are not required.
+--format pdf exports one publication, or the selected whole pages, as a styled PDF.
+PDF uses outputs.pdf defaults and target pdf overrides; it follows navigation order
+and appends eligible unlisted pages. PDF defaults to the site's contentFilter.
 --review writes an API-review candidate; status needs-review exits 2 until pinned.
 --previous-manifest compares public references with an earlier reviewed export.
 --fail-on-removed requires that baseline and refuses to replace output if references disappear.
@@ -51,7 +54,7 @@ export async function runExportCommand(args) {
     if (!output)
         throw new Error(exportHelp);
     const format = values.get('--format');
-    if (format && !['html', 'markdown', 'both'].includes(format))
+    if (format && !['html', 'markdown', 'both', 'pdf'].includes(format))
         throw new Error(exportHelp);
     if (format)
         options.formats = format === 'both' ? ['markdown', 'html'] : [format];