@shoalrun/cli 0.1.0-beta.1 → 1.1.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

@@ -39,6 +39,14 @@ export declare function compile(configFile: string, destination?: string, proven
             }>;
         }>;
     }[];
+    contentSelection: {
+        selection: import("./reader-filters.js").ReaderSelection | null;
+        decisions: Record<string, unknown>[];
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
     profileSelection: {
         schemaVersion: number;
         profileDigest: string;

package/dist/compiler.js

@@ -1,3 +1,4 @@
+import { sectionSelectionReport, writeSectionSelectionReport } from './section-selection.js';
 import { buildPdfSiteArtifacts } from './pdf-site.js';
 import { resolvePdfButton, validatePdfButtonStyle } from './pdf-button.js';
 import { documentKey, publicationKey, samePublication } from './publication-identity.js';
@@ -18,7 +19,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';
@@ -175,6 +176,7 @@ async function compileProject(configFile, destination, provenance, options, ownH
     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.
@@ -305,7 +307,7 @@ async function compileProject(configFile, destination, provenance, options, ownH
     const varying = (field) => new Set(variants.map(variant => variant[field])).size > 1;
     const editionLabel = (variant) => editionBadge === 'never' ? '' : ['product', 'channel', 'version', 'language']
         .filter(field => variant[field] !== undefined && (editionBadge === 'always' || varying(field))).map(field => variant[field]).join(' · ');
-    const { docs, knownDocumentIds, knownDocumentTypes, routeOwners, contentDir, snippets, apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation } = await prepareContentWorkspace({
+    const { sectionSelection, docs, knownDocumentIds, knownDocumentTypes, routeOwners, contentDir, snippets, apiPlan, api, sourceForVariant, knownOperations, relatedApiTargets, guidesByApi, sourceForOperation } = await prepareContentWorkspace({
         base, basePath, config, loaded, variants, language, readerFilters, contentFilter, metadataProvider, metadataDependencies,
         sourceOverrides: options.sourceOverrides, authoringFiles: options.authoringFiles
     });
@@ -397,7 +399,7 @@ async function compileProject(configFile, destination, provenance, options, ownH
         freshness,
         rendered, docs, relationships, knownOperations, cardUses, publishedRelationships, cookbooks, documentRoutes,
         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,
+        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
     });
@@ -480,12 +482,15 @@ async function compileProject(configFile, destination, provenance, options, ownH
     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 ?? [])]),
+        privateDependencies: new Set([
+            ...[...snippets.values()].filter(snippet => !snippetUses.some(use => use.file === snippet.file)).map(snippet => snippet.file),
+            ...(sectionSelection.hasConditions || contentFilter ? componentPlugins.dependencies : []), ...(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,
-        faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
+        fontFiles, projectFontAssets, fonts, shareImages, shareFor, themePreset, shareFontFiles, shareCache, faviconFile,
+        faviconRoute, customStyleFile, scriptFiles, componentAssets: loaded.deployment?.context.grants || sectionSelection.hasConditions || contentFilter ? componentPlugins.assets.filter(asset => usedComponentAssets.has(asset.route)) : componentPlugins.assets, redirects, apiPublications, api, catalog, headers,
         documentRoutes, readerFilters, apiSources
     });
     if (destination) {
@@ -499,9 +504,11 @@ async function compileProject(configFile, destination, provenance, options, ownH
             if (loaded.deployment?.context.grants && !options.authoringFiles)
                 await writeFile(path.join(localGuide, 'profile-selection.json'), JSON.stringify({ ...profileSelection(loaded.deployment), buildId, configDigest: loaded.digest }, null, 2) + '\n');
         });
+        if (!options.authoringFiles)
+            await writeSectionSelectionReport(base, sectionSelection, { target: { kind: 'site', output: target }, buildId, configDigest: loaded.digest, filterOrigin: 'site.contentFilter' });
         // Authoring captures resolve revision dates without changing captured inputs.
         if (!options.authoringFiles)
             await freshness?.commit();
     }
-    return { ...manifest, buildId, apiPublicationReview, profileSelection: profileSelection(loaded.deployment), ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
+    return { ...manifest, buildId, apiPublicationReview, contentSelection: sectionSelectionReport(sectionSelection), profileSelection: profileSelection(loaded.deployment), ...(options.authoringFiles ? { authoringSources: rendered.map(({ doc }) => ({ id: doc.frontmatter.id, file: doc.file, url: doc.route, markdownUrl: doc.markdownRoute })) } : {}) };
 }

package/dist/component-names.js

@@ -1 +1 @@
-export const builtinComponentNames = new Set('Anchor FrontmatterReference ForFeature ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));
+export const builtinComponentNames = new Set('Anchor FrontmatterReference ForFeature ForFacet ForPublication ReaderSection ReaderChoice ReaderFilter Only Badge Kbd Tooltip InfoHint Progress Math ActionLink Button DefinitionList Term Definition Steps Timeline Milestone FileTree Tree Folder File Table CollapsibleGroup Collapsible Section Hero ThemePreview Diagram Image Tabs Walkthrough Step Tab Fields Field CookbookChooser DocCard DocCards DocCollection RelatedReading ApiExample ApiSchema Snippet Var DocLink Callout'.split(' '));

package/dist/component-transform.js

@@ -1,5 +1,5 @@
 import { documentKey } from './publication-identity.js';
-import { pruneFeatureTree } from './deployment-profile.js';
+import { createSectionSelection, evaluatePublicationGuard, pruneSelectedTree, warnReaderSection } from './section-selection.js';
 import { lowerComponent } from './component-plugins.js';
 import { cardComponent } from './cards.js';
 import { cookbookChooserComponent } from './cookbook-chooser.js';
@@ -61,8 +61,10 @@ function literalAttributes(attributes) {
 export function transformMdx(tree, current, registry, snippets = new Map(), projectValues = {}, uses = [], calloutTypes = resolveCalloutTypes(undefined, current.file), projectRoot, readerConfig, frontmatterConfig = {}, publicationConfig, badgeVariants = resolveBadgeVariants(undefined, current.file), componentPlugins = new Map(), publicationRegistry) {
     if (!isMdxRoot(tree))
         throw new Error(`${current.file}: parsed content must be a root with children`);
-    tree = lowerSectionMarkers(pruneFeatureTree(tree, current.featureContext, current.file), current.file);
-    snippets = new Map([...snippets].map(([id, definition]) => [id, { ...definition, tree: pruneFeatureTree(definition.tree, current.featureContext, definition.file) }]));
+    current.sectionSelection ??= createSectionSelection(readerConfig, undefined, publicationConfig);
+    const originalSnippets = snippets;
+    tree = lowerSectionMarkers(pruneSelectedTree(tree, current), current.file);
+    snippets = new Map([...snippets].map(([id, definition]) => [id, { ...definition, tree: pruneSelectedTree(definition.tree, current, definition.file, false) }]));
     let pluginDepth = 0;
     let tabsIndex = 0;
     let walkthroughIndex = 0;
@@ -133,27 +135,14 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                     throw new Error(`${sourceFile}: <FrontmatterReference> must be an empty block`);
                 return childrenOf(parsePlainMarkdown(frontmatterReference(frontmatterConfig, true)), scope, stack, sourceFile);
             }
-            if (node.name === 'ForFeature') {
-                const selected = pruneFeatureTree({ type: 'root', children: [node] }, current.featureContext, sourceFile);
+            if (node.name === 'ForFeature' || node.name === 'ForFacet') {
+                const selected = pruneSelectedTree({ type: 'root', children: [node] }, current, sourceFile);
                 return childrenOf(selected.children, scope, stack, sourceFile);
             }
             if (node.name === 'ForPublication') {
-                const attributes = node.attributes ?? [];
-                const allowed = ['product', 'channel', 'version', 'language'];
-                if (node.type !== 'mdxJsxFlowElement' || !node.children?.length || !attributes.length || !literalAttributes(attributes) || attributes.some((item) => !allowed.includes(item.name) || !item.value.trim()) || new Set(attributes.map((item) => item.name)).size !== attributes.length) {
-                    throw new Error(`${sourceFile}: <ForPublication> needs block content and distinct literal channel, version, or language attributes`);
-                }
-                const product = attributes.find(item => item.name === 'product')?.value ?? current.variant.product;
-                for (const item of attributes) {
-                    const catalog = item.name === 'product' ? publicationConfig?.products
-                        : item.name === 'channel' ? publicationConfig?.channels
-                            : item.name === 'version' ? (product ? publicationConfig?.products?.[product]?.versions : publicationConfig?.versions) : undefined;
-                    if (publicationConfig && item.name !== 'language' && (!catalog || !Object.hasOwn(catalog, item.value)))
-                        throw new Error(`${sourceFile}: <ForPublication> names unknown ${item.name} ${item.value}`);
-                }
-                if (attributes.some((item) => current.variant[item.name] !== item.value))
+                if (!evaluatePublicationGuard(node, current, sourceFile, publicationConfig))
                     return [];
-                return childrenOf(node.children, scope, stack, sourceFile);
+                return childrenOf(node.children ?? [], scope, stack, sourceFile);
             }
             if (node.name === 'ReaderSection' || node.name === 'ReaderChoice' || node.name === 'ReaderFilter') {
                 if (!readerConfig || node.type !== 'mdxJsxFlowElement')
@@ -179,6 +168,8 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                 const selection = validateReaderSelection(choices, readerConfig, `${sourceFile}: <${node.name}>`);
                 if (!Object.keys(selection).length)
                     throw new Error(`${sourceFile}: <${node.name}> needs at least one filter choice`);
+                if (node.name === 'ReaderSection')
+                    warnReaderSection(current, sourceFile, node.position?.start?.line ?? 1, selection);
                 const description = Object.entries(selection).map(([facet, values]) => `${readerConfig.facets[facet].label}: ${values.map(value => readerConfig.facets[facet].options[value]).join(' or ')}`).join('; ');
                 const children = node.name === 'ReaderSection' ? childrenOf(node.children ?? [], scope, stack, sourceFile) : [];
                 const containsSection = (item) => item.type === 'docReaderSection' || (item.children ?? []).some(containsSection);
@@ -628,8 +619,9 @@ export function transformMdx(tree, current, registry, snippets = new Map(), proj
                 if (!invocation || typeof invocation !== 'object' || Array.isArray(invocation))
                     throw new Error(`${sourceFile}: snippet values must be a literal mapping`);
                 const values = resolveSnippetValues(id, definition, projectValues, { ...(current.frontmatter.variables ?? {}), ...scope }, invocation);
-                uses.push({ id, file: definition.file, documentId: current.frontmatter.id });
-                return childrenOf(definition.tree.children, values, [...stack, id], definition.file);
+                uses.push({ id, file: definition.file, documentId: current.frontmatter.id, documentKey: documentKey(current.frontmatter.id, current.variant) });
+                const selectedTree = pruneSelectedTree(originalSnippets.get(id).tree, current, definition.file);
+                return childrenOf(selectedTree.children, values, [...stack, id], definition.file);
             }
             if (node.name === 'Var') {
                 if (!stack.length || node.type !== 'mdxJsxTextElement' || node.children?.length)

package/dist/conditional-tree.d.ts

@@ -0,0 +1,2 @@
+/** Validate every guard, including excluded descendants, without expanding dependencies. */
+export declare function pruneConditionalTree(tree: any, evaluate: (node: any, ancestorIncluded: boolean) => boolean | undefined): any;

package/dist/conditional-tree.js

@@ -0,0 +1,14 @@
+/** Validate every guard, including excluded descendants, without expanding dependencies. */
+export function pruneConditionalTree(tree, evaluate) {
+    const walk = (node, ancestorIncluded = true) => {
+        if (!node || typeof node !== 'object')
+            return [node];
+        const match = evaluate(node, ancestorIncluded);
+        if (match !== undefined) {
+            const children = (node.children ?? []).flatMap((child) => walk(child, ancestorIncluded && match));
+            return ancestorIncluded && match ? children : [];
+        }
+        return [{ ...node, ...(node.children ? { children: node.children.flatMap((child) => walk(child, ancestorIncluded)) } : {}) }];
+    };
+    return walk(tree)[0];
+}

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 {