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

package/dist/audit.js

@@ -0,0 +1,171 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { compile } from './compiler.js';
+import { explainSegments, loadConfig } from './config.js';
+import { auditReference } from './reference-audit.js';
+import { auditFocusedContracts } from './focused-audit.js';
+import { auditLinks } from './link-audit.js';
+import { checkEvalReport, evalBuildSnapshot, evalTasksDigest, loadEvalTasks, parseEvalSettings } from './docs-eval.js';
+export function parseAuditSettings(value) {
+    if (value === undefined)
+        return { tests: [], api: true, focusedContracts: true, links: true };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('audit must be a mapping');
+    const config = value;
+    const extra = Object.keys(config).filter(key => !['tests', 'api', 'focusedContracts', 'links', 'evals'].includes(key));
+    if (extra.length)
+        throw new Error(`audit does not accept ${extra.join(', ')}`);
+    const tests = config.tests ?? [];
+    if (!Array.isArray(tests))
+        throw new Error('audit.tests must be a list');
+    const seen = new Set();
+    const parsed = tests.map((item, index) => {
+        const where = `audit.tests[${index}]`;
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new Error(`${where} must be a mapping`);
+        const test = item;
+        if (Object.keys(test).some(key => !['id', 'run', 'inputs'].includes(key)))
+            throw new Error(`${where} accepts only id, run, and inputs`);
+        if (typeof test.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(test.id))
+            throw new Error(`${where}.id must use lowercase letters, digits, and hyphens`);
+        if (seen.has(test.id))
+            throw new Error(`Duplicate audit test ${test.id}`);
+        seen.add(test.id);
+        if (!Array.isArray(test.run) || !test.run.length || !test.run.every(arg => typeof arg === 'string' && arg.length))
+            throw new Error(`${where}.run must be a nonempty list of strings`);
+        if (test.inputs !== undefined && (!Array.isArray(test.inputs) || test.inputs.some(input => typeof input !== 'string' || !input.trim()) || new Set(test.inputs).size !== test.inputs.length))
+            throw new Error(`${where}.inputs must be a list of distinct nonempty paths`);
+        return { id: test.id, run: test.run, ...(test.inputs !== undefined ? { inputs: test.inputs } : {}) };
+    });
+    for (const key of ['api', 'focusedContracts', 'links'])
+        if (config[key] !== undefined && typeof config[key] !== 'boolean')
+            throw new Error(`audit.${key} must be true or false`);
+    return { tests: parsed, api: config.api !== false, focusedContracts: config.focusedContracts !== false, links: config.links !== false, evals: parseEvalSettings(config.evals) };
+}
+export async function runAuditTest(spec, cwd, env = {}) {
+    return new Promise(resolve => {
+        const child = spawn(spec.run[0], spec.run.slice(1), { cwd, env: { ...process.env, ...env }, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        // A spawn failure must clear the deadline too. Node's spawn timeout can
+        // otherwise retain a timer after ENOENT and keep the CLI alive for two minutes.
+        const deadline = setTimeout(() => child.kill(), 120000);
+        let output = '';
+        const append = (chunk) => { output = (output + chunk.toString()).slice(-16000); };
+        child.stdout.on('data', append);
+        child.stderr.on('data', append);
+        child.on('error', error => { clearTimeout(deadline); resolve({ id: `test:${spec.id}`, status: 'error', findings: [{ target: spec.id, message: error.message }] }); });
+        child.on('close', (code, signal) => {
+            clearTimeout(deadline);
+            if (code === 0)
+                resolve({ id: `test:${spec.id}`, status: 'ok', findings: [] });
+            else
+                resolve({ id: `test:${spec.id}`, status: 'error', findings: [{ target: spec.id, message: `Exited ${code === null ? `on signal ${signal}` : `with code ${code}`}${output.trim() ? `: ${output.trim()}` : ''}` }] });
+        });
+    });
+}
+export async function auditProject(configFile) {
+    const absoluteConfig = path.resolve(configFile);
+    const loaded = await loadConfig(absoluteConfig);
+    const config = parseAuditSettings(loaded.value.audit);
+    const results = [];
+    const cwd = path.dirname(absoluteConfig);
+    for (const spec of config.tests)
+        results.push(await runAuditTest(spec, cwd));
+    if (config.api) {
+        const apis = loaded.value.apis;
+        if (apis && typeof apis === 'object' && !Array.isArray(apis)) {
+            for (const [apiId, definition] of Object.entries(apis)) {
+                if (!definition || typeof definition !== 'object' || Array.isArray(definition))
+                    continue;
+                const publications = definition.publications;
+                const sources = [['source'], ...(Array.isArray(publications) ? publications : []).map((_, index) => ['publications', String(index), 'source'])];
+                for (const segments of sources) {
+                    let source = definition;
+                    for (const segment of segments)
+                        source = source?.[segment];
+                    if (source?.kind !== 'file' || typeof source.path !== 'string')
+                        continue;
+                    const key = ['apis', apiId, ...segments, 'path'];
+                    const origin = explainSegments(loaded, key).source.file;
+                    const file = path.resolve(path.dirname(origin), source.path);
+                    const id = `api:${apiId}${segments[0] === 'publications' ? `:publication-${segments[1]}` : ':default'}`;
+                    try {
+                        const report = await auditReference(file);
+                        results.push({ id, status: report.status, findings: report.failures.map(failure => ({ target: failure.operationId, message: failure.message })), details: { source: file, operations: report.operations, rendered: report.rendered, namedExamples: report.namedExamples } });
+                    }
+                    catch (error) {
+                        results.push({ id, status: 'error', findings: [{ target: file, message: error.message }] });
+                    }
+                }
+            }
+        }
+    }
+    const temporary = await mkdtemp(path.join(os.tmpdir(), 'shoalrun-audit-'));
+    try {
+        let manifest;
+        try {
+            manifest = await compile(absoluteConfig, path.join(temporary, 'site'));
+            results.push({ id: 'build', status: 'ok', findings: [], details: { documents: manifest.documents.length } });
+        }
+        catch (error) {
+            results.push({ id: 'build', status: 'error', findings: [{ target: absoluteConfig, message: error.message }] });
+            return { status: 'error', results };
+        }
+        if (config.focusedContracts) {
+            try {
+                const report = await auditFocusedContracts(path.join(temporary, 'site'));
+                results.push({ id: 'focused-contracts', status: report.status, findings: report.failures.map(failure => ({ target: failure.documentId, message: failure.message })), details: { contracts: report.contracts } });
+            }
+            catch (error) {
+                results.push({ id: 'focused-contracts', status: 'error', findings: [{ target: 'focused-contracts', message: error.message }] });
+            }
+        }
+        if (config.links) {
+            try {
+                const report = await auditLinks(path.join(temporary, 'site'), typeof loaded.value.site?.origin === 'string' ? loaded.value.site.origin : undefined);
+                results.push({ id: 'links', status: report.status, findings: report.findings, details: { documents: report.pages, links: report.checked } });
+            }
+            catch (error) {
+                results.push({ id: 'links', status: 'error', findings: [{ target: 'links', message: error.message }] });
+            }
+        }
+        if (config.evals) {
+            const tasksFile = path.resolve(path.dirname(explainSegments(loaded, ['audit', 'evals', 'tasks']).source.file), config.evals.tasks);
+            const reportFile = path.resolve(path.dirname(explainSegments(loaded, ['audit', 'evals', 'report']).source.file), config.evals.report);
+            const site = path.join(temporary, 'site');
+            try {
+                let originalDigest;
+                let originalTasksDigest;
+                if (config.evals.run) {
+                    const tasks = await loadEvalTasks(tasksFile);
+                    const snapshot = await evalBuildSnapshot(site);
+                    originalDigest = snapshot.buildDigest;
+                    originalTasksDigest = evalTasksDigest(tasks);
+                    const hook = await runAuditTest({ id: 'eval-run', run: config.evals.run }, cwd, {
+                        SHOALRUN_EVAL_SITE: site, SHOALRUN_EVAL_TASKS: tasksFile, SHOALRUN_EVAL_REPORT: reportFile,
+                        SHOALRUN_EVAL_BUILD_DIGEST: snapshot.buildDigest, SHOALRUN_EVAL_TASKS_DIGEST: originalTasksDigest,
+                    });
+                    results.push({ ...hook, id: 'eval-run' });
+                }
+                const report = await checkEvalReport(site, tasksFile, reportFile);
+                if (originalDigest && report.details.buildDigest !== originalDigest) {
+                    report.status = 'error';
+                    report.findings.push({ target: 'buildDigest', message: 'The evaluator modified the temporary documentation output; evaluate the unmodified audit build.' });
+                }
+                if (originalTasksDigest && evalTasksDigest(await loadEvalTasks(tasksFile)) !== originalTasksDigest) {
+                    report.status = 'error';
+                    report.findings.push({ target: 'tasksDigest', message: 'The evaluator modified the task definitions; evaluate the original audit tasks.' });
+                }
+                results.push({ id: 'evals', ...report });
+            }
+            catch (error) {
+                results.push({ id: 'evals', status: 'error', findings: [{ target: tasksFile, message: error.message }] });
+            }
+        }
+        return { status: results.some(result => result.status === 'error') ? 'error' : 'ok', results };
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/authored-change.d.ts

@@ -0,0 +1,22 @@
+import type { Document, Frontmatter } from './content-source.js';
+export declare const changeKinds: readonly ["editorial", "procedure", "behavior", "breaking"];
+export type AuthoredChange = {
+    kind: typeof changeKinds[number];
+    affects: string[];
+    migration?: string;
+};
+type Target = {
+    id: string;
+    title: string;
+    url: string;
+    markdownUrl: string;
+};
+export type ResolvedChange = {
+    kind: AuthoredChange['kind'];
+    affects: Target[];
+    migration?: Target;
+};
+export declare function validateAuthoredChange(frontmatter: Frontmatter, file: string): void;
+export declare function resolveAuthoredChange(doc: Document, docs: Map<string, Document>): ResolvedChange | undefined;
+export declare function authoredChangeNotice(value: ResolvedChange | undefined, format: 'html' | 'markdown'): any;
+export {};

package/dist/authored-change.js

@@ -0,0 +1,47 @@
+import { link, list, paragraph, root, text } from './semantic-markdown.js';
+export const changeKinds = ['editorial', 'procedure', 'behavior', 'breaking'];
+const labels = { editorial: 'Editorial correction', procedure: 'Procedure change', behavior: 'Behavior change', breaking: 'Breaking change' };
+export function validateAuthoredChange(frontmatter, file) {
+    const value = frontmatter.change;
+    if (value === undefined)
+        return;
+    const fail = (message) => { throw new Error(`${file}: change ${message}`); };
+    if (frontmatter.type !== 'changelog-entry')
+        fail('is supported only on changelog-entry pages');
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('must be a mapping');
+    for (const key of Object.keys(value))
+        if (!['kind', 'affects', 'migration'].includes(key))
+            fail(`has unknown field ${key}`);
+    if (!changeKinds.includes(value.kind))
+        fail(`kind must be ${changeKinds.join(', ')}`);
+    const id = (item) => typeof item === 'string' && !!item.trim() && item === item.trim();
+    if (!Array.isArray(value.affects) || !value.affects.length || value.affects.some(item => !id(item)) || new Set(value.affects).size !== value.affects.length)
+        fail('affects must be a nonempty list of unique, trimmed document IDs');
+    if (value.migration !== undefined && !id(value.migration))
+        fail('migration must be a nonempty, trimmed document ID');
+}
+export function resolveAuthoredChange(doc, docs) {
+    const value = doc.frontmatter.change;
+    if (!value)
+        return;
+    const target = (id, field) => {
+        const found = docs.get(`${id}|${doc.variant.channel}|${doc.variant.version}|${doc.variant.language}`);
+        if (id === doc.frontmatter.id || !found || found.frontmatter.access?.policy !== 'public')
+            throw new Error(`${doc.file}: change.${field} must name another public document in the same publication: ${id}`);
+        return { id, title: found.frontmatter.title, url: found.route, markdownUrl: found.markdownRoute };
+    };
+    return { kind: value.kind, affects: value.affects.map(id => target(id, 'affects')), ...(value.migration ? { migration: target(value.migration, 'migration') } : {}) };
+}
+export function authoredChangeNotice(value, format) {
+    if (!value)
+        return root([]);
+    const targetLink = (target) => ({ ...link(format === 'html' ? target.url : target.markdownUrl, target.title), exportDocumentId: target.id });
+    return root([{ type: 'blockquote', children: [
+                paragraph({ type: 'strong', children: [text('Authored change')] }, text(`: ${labels[value.kind]}.`)),
+                paragraph(text('Affected pages:')),
+                list(value.affects.map(target => [paragraph(targetLink(target))])),
+                ...(value.migration ? [paragraph(text('Migration guide: '), targetLink(value.migration), text('.'))] : []),
+                paragraph(text('Classification and scope are declared by the author. Read this entry for details.'))
+            ] }]);
+}

package/dist/authoring-api.d.ts

@@ -0,0 +1,18 @@
+export declare const authoringApiVersion = 1;
+export { loadConfig } from './config.js';
+export { docsContext, docsPlan, docsApply } from './docs-author.js';
+export { compile } from './compiler.js';
+export { validateAuthoringGuidance } from './authoring-guidance.js';
+export { inspectAuthoringProject, readAuthoringSource, projectToolSchemaVersion, projectSections, ProjectToolError, projectToolFailure } from './authoring-project.js';
+export type { ProjectOptions, ProjectSection, ProjectFinding } from './authoring-project.js';
+export { bundledDocumentation, searchDocumentation, getDocumentationPage, getDocumentationOutline, getDocumentationSection } from './documentation-core.js';
+export { captureAuthoringBaseline, writeAuthoringBaseline, snapshotSchemaVersion } from './authoring-snapshot.js';
+export type { AuthoringBaseline } from './authoring-snapshot.js';
+export { validateAuthoringChanges, authoringValidationStatus } from './authoring-validation.js';
+export type { ValidationOptions, ValidationReport, ValidationCheck } from './authoring-validation.js';
+export type { ValidationFinding } from './authoring-findings.js';
+export { authoringReview, authoringReviewMarkdown } from './authoring-review.js';
+export type { AuthoringReview } from './authoring-review.js';
+export { startAuthoringPreview } from './authoring-preview.js';
+export type { AuthoringPreview, AuthoringPreviewOptions } from './authoring-preview.js';
+export declare const authoringCapabilities: readonly ["create-page", "complete-bundle-validation", "project-discovery", "project-source-read", "documentation-search-read", "working-tree-validation", "task-baseline", "validation-freshness", "snapshot-preview", "authoring-review-report"];

package/dist/authoring-api.js

@@ -0,0 +1,15 @@
+// Optional authoring tools use this versioned surface instead of dist internals.
+export const authoringApiVersion = 1;
+export { loadConfig } from './config.js';
+export { docsContext, docsPlan, docsApply } from './docs-author.js';
+export { compile } from './compiler.js';
+export { validateAuthoringGuidance } from './authoring-guidance.js';
+export { inspectAuthoringProject, readAuthoringSource, projectToolSchemaVersion, projectSections, ProjectToolError, projectToolFailure } from './authoring-project.js';
+export { bundledDocumentation, searchDocumentation, getDocumentationPage, getDocumentationOutline, getDocumentationSection } from './documentation-core.js';
+export { captureAuthoringBaseline, writeAuthoringBaseline, snapshotSchemaVersion } from './authoring-snapshot.js';
+export { validateAuthoringChanges, authoringValidationStatus } from './authoring-validation.js';
+export { authoringReview, authoringReviewMarkdown } from './authoring-review.js';
+export { startAuthoringPreview } from './authoring-preview.js';
+// Optional capabilities let private authoring clients reject an older package
+// before spending provider budget. Existing version-1 update clients still work.
+export const authoringCapabilities = ['create-page', 'complete-bundle-validation', 'project-discovery', 'project-source-read', 'documentation-search-read', 'working-tree-validation', 'task-baseline', 'validation-freshness', 'snapshot-preview', 'authoring-review-report'];

package/dist/authoring-findings.d.ts

@@ -0,0 +1,31 @@
+import { type loadConfig } from './config.js';
+import type { SnapshotCapture } from './authoring-snapshot.js';
+export type ValidationFinding = {
+    code: string;
+    severity: 'error' | 'warning' | 'review-needed';
+    file?: string;
+    location?: {
+        line: number;
+        column: number;
+        key?: string;
+    };
+    relatedFiles?: string[];
+    explanation: string;
+    reference?: string;
+    nextAction: string;
+};
+export declare function configFindingLocation(loaded: Awaited<ReturnType<typeof loadConfig>>, segments: string[], capture: SnapshotCapture, shadow: string): {
+    file: string;
+    location?: undefined;
+} | {
+    file: string;
+    location: {
+        line: number;
+        column: number;
+        key: string;
+    };
+} | {
+    file?: undefined;
+    location?: undefined;
+};
+export declare function validationFinding(error: unknown, capture: SnapshotCapture, shadow: string, loaded?: Awaited<ReturnType<typeof loadConfig>>): ValidationFinding;

package/dist/authoring-findings.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import YAML from 'yaml';
+import { explainSegments } from './config.js';
+import { parse } from './semantic-markdown.js';
+export function configFindingLocation(loaded, segments, capture, shadow) {
+    try {
+        const owner = explainSegments(loaded, segments).source.file;
+        const file = path.relative(shadow, owner);
+        const content = capture.buffers.get(file)?.toString('utf8');
+        if (!content)
+            return { file };
+        const parsed = YAML.parseDocument(content);
+        // Includes may own a subtree rather than the project root. Find the longest
+        // suffix present in that source instead of assuming the root's YAML shape.
+        for (let start = 0; start < segments.length; start++) {
+            const node = parsed.getIn(segments.slice(start).map(segment => /^\d+$/.test(segment) ? Number(segment) : segment), true);
+            if (node?.range) {
+                const prefix = content.slice(0, node.range[0]);
+                return { file, location: { line: prefix.split('\n').length, column: prefix.length - prefix.lastIndexOf('\n'), key: segments.join('.') } };
+            }
+        }
+        return { file };
+    }
+    catch {
+        return {};
+    }
+}
+export function validationFinding(error, capture, shadow, loaded) {
+    const message = error instanceof Error ? error.message : String(error);
+    const component = /<([A-Za-z][A-Za-z0-9]*)>/.exec(message)?.[1];
+    const code = component ? 'validation.component' : /[Rr]elationship|Prerequisite cycle/.test(message) ? 'validation.relationship' : /[Nn]avigation/.test(message) ? 'validation.navigation' : /[Ll]ink|unknown document|doc:|card target/.test(message) ? 'validation.link' : /[Rr]oute|[Ss]lug|Duplicate document identity/.test(message) ? 'validation.identity' : /frontmatter|missing (?:id|title|type|summary)|updated|releaseVersion|publication/.test(message) ? 'validation.metadata' : 'validation.compile';
+    let file = capture.inputs.map(input => input.file).sort((a, b) => b.length - a.length).find(file => message.includes(path.resolve(shadow, file)) || message.startsWith(`${file}:`));
+    let location;
+    const relatedFiles = [];
+    if (!file && code === 'validation.identity') {
+        const identities = [...message.matchAll(/([A-Za-z0-9._-]+)\|/g)].map(match => match[1]);
+        const named = /^([^:]+): invalid slug/.exec(message)?.[1];
+        if (named)
+            identities.push(named);
+        for (const [candidate, content] of capture.buffers)
+            if (/\.mdx?$/.test(candidate)) {
+                const header = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content.toString('utf8'));
+                try {
+                    if (header && identities.includes(YAML.parse(header[1])?.id))
+                        relatedFiles.push(candidate);
+                }
+                catch { /* Malformed metadata is diagnosed independently. */ }
+            }
+        if (relatedFiles.length)
+            file = relatedFiles[0];
+    }
+    if (loaded && ['validation.navigation', 'validation.relationship'].includes(code)) {
+        const candidates = [];
+        if (code === 'validation.relationship')
+            (loaded.value.relationships ?? []).forEach((edge, index) => { if (message.includes(`Relationship ${edge.id} `))
+                candidates.push(['relationships', String(index)]); });
+        else {
+            const visit = (nodes, segments) => nodes.forEach((node, index) => {
+                const at = [...segments, String(index)];
+                if (node.doc && message.includes(`missing document ${node.doc}`) || node.id && message.endsWith(`: ${node.id}`))
+                    candidates.push(node.doc && message.includes(`missing document ${node.doc}`) ? [...at, 'doc'] : at);
+                if (Array.isArray(node.items))
+                    visit(node.items, [...at, 'items']);
+            });
+            if (Array.isArray(loaded.value.navigation))
+                visit(loaded.value.navigation, ['navigation']);
+        }
+        if (candidates.length === 1)
+            ({ file, location } = configFindingLocation(loaded, candidates[0], capture, shadow));
+    }
+    if (file) {
+        const source = capture.buffers.get(file)?.toString('utf8') ?? '';
+        const header = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(source);
+        if (component) {
+            try {
+                const candidates = [];
+                const visit = (node, parent) => {
+                    if (node.name === component && (component !== 'Step' || !/must be directly inside/.test(message) || !['Steps', 'Walkthrough'].includes(parent?.name)))
+                        candidates.push(node);
+                    for (const child of node.children ?? [])
+                        visit(child, node);
+                };
+                visit(parse.parse(source.slice(header?.[0].length ?? 0)));
+                if (candidates.length === 1 && candidates[0].position?.start)
+                    location = { line: candidates[0].position.start.line + (header?.[0].split('\n').length ?? 1) - 1, column: candidates[0].position.start.column };
+            }
+            catch { /* Parser/compiler details remain available when no exact node is known. */ }
+        }
+        else if (!location) {
+            const target = /unknown document (\S+)|missing document (\S+)/.exec(message);
+            const token = target ? `doc:${target[1] ?? target[2]}` : code === 'validation.identity' ? /Duplicate document identity/.test(message) ? 'id:' : 'slug:' : /missing (\w+)/.exec(message)?.[1] ?? /: (\w+) must/.exec(message)?.[1];
+            if (token) {
+                const positions = [...source.matchAll(new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'))];
+                if (positions.length === 1) {
+                    const prefix = source.slice(0, positions[0].index);
+                    location = { line: prefix.split('\n').length, column: prefix.length - prefix.lastIndexOf('\n') };
+                }
+            }
+        }
+    }
+    return { code, severity: 'error', ...(file ? { file } : {}), ...(location ? { location } : {}), ...(relatedFiles.length > 1 ? { relatedFiles } : {}), explanation: message.split(shadow + path.sep).join('') + (component === 'Step' ? ' <Step> is an authored MDX component; harness task-plan steps are separate.' : ''),
+        ...(component === 'Step' || component === 'Steps' ? { reference: 'guide.component.steps' } : code === 'validation.metadata' ? { reference: 'guide.frontmatter-reference' } : {}),
+        nextAction: component === 'Step' ? 'Group the authored procedure in <Steps> using the canonical Steps example, or use the separate Walkthrough contract; then validate again.' : 'Repair the reported source or configuration and validate the working tree again.' };
+}

package/dist/authoring-guidance.d.ts

@@ -0,0 +1,15 @@
+/** Project instructions and read-only source locations; no provider or model runtime. */
+export type AuthoringSourceRoot = {
+    name?: string;
+    path: string;
+    include?: string[];
+    exclude?: string[];
+};
+export type AuthoringGuidance = {
+    directives?: string;
+    guideFiles?: string[];
+    exemplarFiles?: string[];
+    sourceRoots?: AuthoringSourceRoot[];
+    pageSources?: Record<string, string[]>;
+};
+export declare function validateAuthoringGuidance(value: unknown): AuthoringGuidance | undefined;

package/dist/authoring-guidance.js

@@ -0,0 +1,57 @@
+export function validateAuthoringGuidance(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('authoring must be an object');
+    const input = value;
+    if (Object.keys(input).some(key => !['directives', 'guideFiles', 'exemplarFiles', 'sourceRoots', 'pageSources'].includes(key)))
+        throw new Error('authoring accepts directives, guideFiles, exemplarFiles, sourceRoots and pageSources');
+    if (input.directives !== undefined && (typeof input.directives !== 'string' || !input.directives.trim()))
+        throw new Error('authoring.directives must be nonempty text');
+    for (const key of ['guideFiles', 'exemplarFiles']) {
+        if (input[key] !== undefined && (!Array.isArray(input[key]) || input[key].some(file => typeof file !== 'string' || !file.trim() || file.startsWith('/') || /^[A-Za-z]:/.test(file) || file.split(/[\\/]/).includes('..'))))
+            throw new Error(`authoring.${key} must contain project-relative file paths`);
+    }
+    const localPath = (path, where) => {
+        if (typeof path !== 'string' || !path.trim() || /[\0\r\n]/.test(path) || /^[a-z][a-z0-9+.-]*:\/\//i.test(path))
+            throw new Error(`${where} must be a local path, not a URL`);
+        return path;
+    };
+    const patterns = (value, where) => {
+        if (!Array.isArray(value) || !value.length)
+            throw new Error(`${where} must be a nonempty list of patterns`);
+        return value.map(item => localPath(item, where));
+    };
+    let sourceRoots;
+    if (input.sourceRoots !== undefined) {
+        if (!Array.isArray(input.sourceRoots) || !input.sourceRoots.length || input.sourceRoots.length > 16)
+            throw new Error('authoring.sourceRoots must contain 1 to 16 source folders');
+        sourceRoots = input.sourceRoots.map((root, index) => {
+            const where = `authoring.sourceRoots[${index}]`;
+            if (!root || typeof root !== 'object' || Array.isArray(root) || Object.keys(root).some(key => !['name', 'path', 'include', 'exclude'].includes(key)))
+                throw new Error(`${where} accepts name, path, include and exclude`);
+            const record = root;
+            if (record.name !== undefined && (typeof record.name !== 'string' || !record.name.trim()))
+                throw new Error(`${where}.name must be nonempty text`);
+            const result = { path: localPath(record.path, `${where}.path`), ...(record.name === undefined ? {} : { name: record.name }) };
+            for (const key of ['include', 'exclude'])
+                if (record[key] !== undefined) {
+                    result[key] = patterns(record[key], `${where}.${key}`);
+                    if (result[key].some(pattern => pattern.startsWith('/') || /^[A-Za-z]:/.test(pattern) || pattern.split(/[\\/]/).includes('..')))
+                        throw new Error(`${where}.${key} patterns must stay inside their source folder`);
+                }
+            return result;
+        });
+    }
+    let pageSources;
+    if (input.pageSources !== undefined) {
+        if (!input.pageSources || typeof input.pageSources !== 'object' || Array.isArray(input.pageSources))
+            throw new Error('authoring.pageSources must map page IDs to source path lists');
+        pageSources = Object.fromEntries(Object.entries(input.pageSources).map(([id, files]) => {
+            if (!id.trim())
+                throw new Error('authoring.pageSources needs nonempty page IDs');
+            return [id, patterns(files, `authoring.pageSources.${id}`)];
+        }));
+    }
+    return { ...(input.directives === undefined ? {} : { directives: input.directives }), ...(input.guideFiles === undefined ? {} : { guideFiles: [...input.guideFiles] }), ...(input.exemplarFiles === undefined ? {} : { exemplarFiles: [...input.exemplarFiles] }), ...(sourceRoots === undefined ? {} : { sourceRoots }), ...(pageSources === undefined ? {} : { pageSources }) };
+}

package/dist/authoring-preview.d.ts

@@ -0,0 +1,24 @@
+import { type Server } from 'node:http';
+import { type AuthoringReview } from './authoring-review.js';
+export type AuthoringPreviewOptions = {
+    port?: number;
+};
+export type AuthoringPreview = {
+    schemaVersion: 1;
+    kind: 'shoalrun-authoring-preview';
+    snapshotId: string;
+    origin: string;
+    reviewUrl: string;
+    statusUrl: string;
+    pages: Array<AuthoringReview['pages'][number] & {
+        htmlUrl: string;
+        markdownUrl: string;
+    }>;
+    directory: string;
+    lifecycle: string;
+    server: Server;
+    review: () => Promise<AuthoringReview>;
+    close: () => Promise<void>;
+};
+/** Local foreground preview of one pinned snapshot; no watch, rebuild or provider. */
+export declare function startAuthoringPreview(reportFile: string, options?: AuthoringPreviewOptions): Promise<AuthoringPreview>;