@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/compiler/code-languages.js

@@ -0,0 +1,109 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { languageAliasNames, languageNames } from "@shikijs/langs";
+import { bundledLanguages } from "shiki/langs";
+import { CODE_LANGS, CODE_TEMPLATES } from "../core/taxonomy.js";
+export const CODE_LANGUAGES_DIR = ".dooc/code-languages";
+const supported = new Set([
+    ...languageNames,
+    ...languageAliasNames,
+    ...Object.keys(CODE_TEMPLATES),
+]);
+const safeName = /^[a-z0-9][a-z0-9_-]*$/;
+const parseGrammars = (value, source) => {
+    const entries = Array.isArray(value) ? value : [value];
+    if (!entries.length)
+        throw new Error(`${source}: at least one TextMate grammar is required`);
+    return entries.map((entry) => {
+        if (typeof entry !== "object" ||
+            entry === null ||
+            typeof entry.name !== "string" ||
+            !safeName.test(entry.name) ||
+            typeof entry.scopeName !== "string" ||
+            !entry.scopeName ||
+            !Array.isArray(entry.patterns) ||
+            (entry.aliases !== undefined &&
+                (!Array.isArray(entry.aliases) ||
+                    entry.aliases.some((alias) => typeof alias !== "string" || !alias)))) {
+            throw new Error(`${source}: each grammar needs a safe name, scopeName, patterns array and optional string aliases`);
+        }
+        return entry;
+    });
+};
+const readGrammars = (file) => {
+    try {
+        return parseGrammars(JSON.parse(readFileSync(file, "utf8")), file);
+    }
+    catch (error) {
+        throw new Error(`${file}: ${error instanceof Error ? error.message : error}`);
+    }
+};
+export const loadCodeGrammars = async (names) => {
+    const grammars = await Promise.all(names.map(async (name) => {
+        if (name === "graphth")
+            return [
+                {
+                    name,
+                    scopeName: "source.graphth",
+                    patterns: [
+                        { match: "^\\s*#.*$", name: "comment.line.graphth" },
+                        { match: "\\[[^\\[\\]\\n]*\\]", name: "variable.other.graphth" },
+                        { match: "-->|->|--", name: "keyword.operator.graphth" },
+                        { match: "(?<=\\s)@\\S+", name: "entity.name.tag.graphth" },
+                    ],
+                },
+            ];
+        if (name === "termth" || name === "schemath" || name === "callouth") {
+            const language = name === "callouth" ? "markdown" : "yaml";
+            return [
+                ...(await bundledLanguages[language]()).default,
+                {
+                    name,
+                    scopeName: `source.${name}`,
+                    patterns: [
+                        {
+                            include: language === "markdown"
+                                ? "text.html.markdown"
+                                : `source.${language}`,
+                        },
+                    ],
+                },
+            ];
+        }
+        if (!supported.has(name))
+            throw new Error(`Unsupported Shiki language: ${name}`);
+        return (await bundledLanguages[name]()).default;
+    }));
+    return [...new Map(grammars.flat().map((grammar) => [grammar.name, grammar])).values()];
+};
+/** Renderer-owned registrations; Markdown content is never changed. */
+export const loadCodeLanguages = async (root) => {
+    const directory = join(root, CODE_LANGUAGES_DIR);
+    const extra = existsSync(directory)
+        ? readdirSync(directory)
+            .filter((file) => file.endsWith(".json"))
+            .sort()
+            .flatMap((file) => readGrammars(join(directory, file)))
+        : [];
+    const defaults = await loadCodeGrammars(CODE_LANGS);
+    return {
+        codeLanguages: [...new Set([...CODE_LANGS, ...extra.map((grammar) => grammar.name)])],
+        codeGrammars: [
+            ...new Map([...defaults, ...extra].map((grammar) => [grammar.name, grammar])).values(),
+        ],
+    };
+};
+/** Persist a Shiki language or imported TextMate JSON under the renderer's directory. */
+export const addCodeLanguage = async (root, input) => {
+    const grammars = supported.has(input)
+        ? await loadCodeGrammars([input])
+        : readGrammars(resolve(input));
+    const primary = grammars.find((grammar) => grammar.name === input || grammar.aliases?.includes(input)) ??
+        grammars.at(-1);
+    if (!primary || !safeName.test(primary.name))
+        throw new Error("Invalid code language name");
+    const target = join(root, CODE_LANGUAGES_DIR, `${primary.name}.json`);
+    mkdirSync(join(root, CODE_LANGUAGES_DIR), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(grammars, null, 2)}\n`, { flag: "wx" });
+    return relative(root, target);
+};

package/dist/compiler/compile.d.ts

@@ -0,0 +1,95 @@
+import { type TocEntry } from "../core/blocks.js";
+import type { CompiledDoc, FigureEntry, TermEntry } from "../core/content-types.js";
+import { type PreviewSettings } from "../core/previewers.js";
+import { type DocRef } from "../core/routing.js";
+import type { Frontmatter } from "../core/taxonomy.js";
+export type { CompiledDoc, FigureEntry, } from "../core/content-types.js";
+/** Authored links, including callout bodies; code examples do not create references. */
+export declare const collectDocLinks: (body: string) => string[];
+/** Source text and diagnostics for editing. key = CompiledDoc.file. */
+export interface DocSource {
+    terms: TermEntry[];
+    /**
+     * Raw text on disk (including front-matter). The editor's initial value and the base for
+     * detecting external changes.
+     */
+    raw: string;
+    /** Validated front-matter; undefined if broken (CompiledDoc then uses the id as title). */
+    frontmatter: Frontmatter | undefined;
+    /**
+     * For the editor's source-mapping display: each block's start line, relative to the body
+     * (same index as CompiledDoc.blocks).
+     */
+    lines: number[];
+    /**
+     * This doc's validation errors (dialect + resolution of figures/document links).
+     * No file prefix.
+     */
+    errors: string[];
+}
+export interface Compiled {
+    previews: PreviewSettings;
+    title?: string;
+    icon?: string;
+    /** Display order follows dooc.yaml. Invalid sources retain their diagnostics for editing. */
+    docs: CompiledDoc[];
+    terms: TermEntry[];
+    figures: FigureEntry[];
+    sources: Map<string, DocSource>;
+    /** Errors not tied to a doc (layout convention / manifest / figures / terms). */
+    siteErrors: string[];
+    /** All errors (siteErrors + each doc's errors with a file prefix). */
+    errors: string[];
+    /** Site default language (docs without front-matter `lang` resolve to it). */
+    defaultLang: string;
+    contentLanguages?: string[];
+    themes?: ("light" | "dark")[];
+}
+export interface CompileOptions {
+    /** Network permissions supplied by the host application, never by document metadata. */
+    previews?: PreviewSettings;
+    /** Selected content language; translations mirror source paths under locales/<locale>/. */
+    locale?: string;
+    /** Override dooc.yaml's defaultLang for programmatic compilation. */
+    defaultLang?: string;
+}
+export interface Compiler {
+    /**
+     * Compiles the whole docs root (content/ figures/). Unchanged files hit the
+     * cache.
+     */
+    compile(): Compiled;
+}
+/** Site context needed to check a draft's references (document file targets / figures). */
+export interface DraftContext {
+    previews?: PreviewSettings;
+    /** Docs root used to resolve embedded file paths. */
+    root?: string;
+    /** Unsaved local file contents, used only for draft previews. */
+    textfiles?: ReadonlyMap<string, string>;
+    /** file = CompiledDoc.file (`content/<id>.md`); used to look up a draft's id / parent. */
+    docs: readonly (DocRef & {
+        file: string;
+        toc?: readonly TocEntry[];
+    })[];
+    /** name → figure (file = `figures/<file>`). */
+    figures: {
+        get(name: string): {
+            file: string;
+        } | undefined;
+    };
+    /** Site default language for a draft without front-matter `lang`. Default: DEFAULT_LANG. */
+    defaultLang?: string;
+}
+export declare const createCompiler: (root: string, options?: CompileOptions) => Compiler;
+/**
+ * Compiles a single unsaved draft (file = `content/<id>.md`) in the site's context.
+ * Not cached, since it changes on every keystroke. id / parent are looked up from the ctx.docs
+ * entry with the same file ("" for a new doc).
+ */
+export declare const compileDraft: (ctx: DraftContext, file: string, raw: string) => {
+    doc: CompiledDoc;
+    source: DocSource;
+};
+/** One-shot compile (for the build CLI / tests). */
+export declare const compileSite: (root: string, options?: CompileOptions) => Compiled;

package/dist/compiler/compile.js

@@ -0,0 +1,410 @@
+// Reads dooc.yaml and source files into validated, in-memory content for the viewer and HTML
+// bundles. createCompiler caches unchanged files; compileSite performs a one-shot compilation.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { walkBlocks } from "../core/blocks.js";
+import { docIdOfFile, flattenTree, MANIFEST_FILE } from "../core/content-metadata.js";
+import { termMap } from "../core/inline.js";
+import { DEFAULT_LANG, isLangTag } from "../core/language.js";
+import { contentLinks, parseMdast } from "../core/markdown.js";
+import { defaultPreviewSettings, parsePreviewSettings, } from "../core/previewers.js";
+import { parseDocLink } from "../core/routing.js";
+import { isTermFile } from "../core/term-reference.js";
+import { isRemoteTextfile } from "../core/textfile.js";
+import { parseContentSource } from "./code-blocks.js";
+import { collectRefs, parseDoc } from "./dialect.js";
+import { figureName, loadFigures } from "./figures.js";
+import { createFileCache, createSigCache, dirSig, fileSig } from "./file-cache.js";
+import { projectFiles } from "./files.js";
+import { toBlocks } from "./from-mdast.js";
+import { loadIcons, squareSvg } from "./icons.js";
+import { contentLanguageCode, isContentLanguage } from "./language-codes.js";
+import { siteContentLanguages, translationFile } from "./locales.js";
+import { parseManifestText } from "./manifest.js";
+import { parseTermSource } from "./terms.js";
+import { readTextfile, selectTextfileRange } from "./textfile.js";
+import { TextfileUnavailable } from "./textfile-remote.js";
+import { siteThemes, themeVariants } from "./theme-variants.js";
+/** Authored links, including callout bodies; code examples do not create references. */
+export const collectDocLinks = (body) => contentLinks(parseMdast(body))
+    .map((node) => node.url)
+    .filter((url) => {
+    try {
+        return parseDocLink(url) !== undefined;
+    }
+    catch {
+        return false;
+    }
+});
+// Maps mdast line numbers (1-indexed in raw, which includes front-matter) to the body-relative
+// lines the editor shows. body is a suffix of raw (parseDoc only strips the front-matter), so
+// subtract the number of newlines before it.
+const toBodyLines = (raw, body, lines) => {
+    const before = raw.slice(0, raw.length - body.length).split("\n").length - 1;
+    return lines.map((l) => Math.max(1, l - before));
+};
+const parseFile = (raw, previews, file) => {
+    const parsed = parseDoc(raw, previews, file);
+    const { blocks, toc, lines } = toBlocks(parsed.root, parsed.source, previews, file);
+    const refs = collectRefs(parsed.root, previews);
+    const figureFiles = refs.figures;
+    return {
+        raw,
+        parsed,
+        blocks,
+        toc,
+        lines: toBodyLines(raw, parsed.body, lines),
+        refs: { figures: figureFiles.map(figureName), terms: refs.terms },
+        figureFiles,
+        docLinks: collectDocLinks(parsed.body),
+    };
+};
+const resolveFiles = (f, root, textfiles, previews, themes) => {
+    if (!f.refs.terms.length &&
+        !walkBlocks(f.blocks).some((b) => b.type === "figureRef" || (b.type === "code" && b.filename)))
+        return f;
+    const errors = [...f.parsed.errors];
+    const terms = [...f.parsed.terms];
+    const termFiles = new Set(f.refs.terms);
+    const figureFiles = new Set(f.figureFiles);
+    const docLinks = [...f.docLinks];
+    const resolveItem = (item) => typeof item === "string"
+        ? item
+        : "blocks" in item
+            ? { blocks: item.blocks.map(resolveBlock) }
+            : { ...item, children: item.children.map(resolveItem) };
+    const resolveBlock = (b) => {
+        const file = b.type === "code"
+            ? b.filename?.replace(/^(\.\/)+/, "")
+            : b.type === "figureRef"
+                ? f.figureFiles.find((file) => figureName(file) === b.name)
+                : undefined;
+        let variants = {};
+        try {
+            if (file && root)
+                variants = themeVariants(root, file, themes);
+        }
+        catch (error) {
+            errors.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const base = resolveContent(b);
+        if (!Object.keys(variants).length)
+            return base;
+        return {
+            type: "themeVariants",
+            default: base,
+            variants: Object.fromEntries(Object.entries(variants).map(([theme, path]) => {
+                if (b.type === "figureRef") {
+                    figureFiles.add(path);
+                    return [theme, { ...b, name: figureName(path) }];
+                }
+                return [theme, resolveContent({ ...b, filename: path })];
+            })),
+        };
+    };
+    const resolveContent = (b) => {
+        if (b.type === "quote")
+            return { ...b, blocks: b.blocks.map(resolveBlock) };
+        if (b.type === "list")
+            return { ...b, items: b.items.map(resolveItem) };
+        if (b.type !== "code" || !b.filename)
+            return b;
+        try {
+            if (!root)
+                throw new Error("docs root is required to read text files");
+            const source = selectTextfileRange(textfiles?.get(b.filename.replace(/^(\.\/)+/, "")) ??
+                readTextfile(root, b.filename, false, previews?.domains), b.range);
+            const parsed = b.range === undefined && !isRemoteTextfile(b.filename)
+                ? parseContentSource(b.lang ?? "", source, b.filename.replace(/^(\.\/)+/, ""))
+                : undefined;
+            if (parsed) {
+                if (b.lang === "callouth") {
+                    docLinks.push(...collectDocLinks(source));
+                    const refs = collectRefs(parseMdast(source));
+                    for (const file of refs.terms)
+                        termFiles.add(file);
+                    for (const file of refs.figures)
+                        figureFiles.add(file);
+                }
+                errors.push(...parsed.errors.map((error) => `${b.filename}: L${error.line + 1}: ${error.message}`));
+                for (const block of parsed.blocks)
+                    if (block.type === "term")
+                        terms.push(block.entry);
+                if (parsed.blocks[0]) {
+                    const block = { ...parsed.blocks[0], ...(b.alt ? { alt: b.alt } : {}) };
+                    return block.type === "table" && b.tableMode
+                        ? { ...block, tableMode: b.tableMode }
+                        : block;
+                }
+            }
+            return {
+                ...b,
+                lines: source.split("\n"),
+            };
+        }
+        catch (error) {
+            if (error instanceof TextfileUnavailable ||
+                error.code === "ENOENT")
+                return {
+                    ...b,
+                    unavailable: error instanceof TextfileUnavailable ? error.reason : "missing",
+                };
+            errors.push(`${b.filename}${b.range ?? ""}: ${error instanceof Error ? error.message : error}`);
+            return b;
+        }
+    };
+    const blocks = f.blocks.map(resolveBlock);
+    for (const file of termFiles) {
+        try {
+            if (!root)
+                throw new Error("docs root is required to read term files");
+            const parsed = parseTermSource(file, textfiles?.get(file) ?? readTextfile(root, file));
+            terms.push(...parsed.entries);
+            errors.push(...parsed.errors.map((error) => `${file}: L${error.line + 1}: ${error.message}`));
+        }
+        catch (error) {
+            errors.push(`${file}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    return {
+        ...f,
+        blocks,
+        docLinks,
+        figureFiles: [...figureFiles],
+        refs: {
+            ...f.refs,
+            figures: [...figureFiles].map(figureName),
+            terms: [
+                ...new Set([
+                    ...termFiles,
+                    ...terms.filter((term) => isTermFile(term.id)).map((term) => term.id),
+                ]),
+            ],
+        },
+        parsed: { ...f.parsed, errors, terms },
+    };
+};
+const toDoc = (id, parent, file, f, defaultLang) => ({
+    id,
+    ...(parent == null ? {} : { parent }),
+    file,
+    // Keep the doc even if its front-matter is broken (so it can be opened and fixed in the
+    // viewer). In that case parsed.errors is set, so it won't be distributed.
+    ...(f.parsed.frontmatter ?? { title: id }),
+    lang: f.parsed.frontmatter?.lang ?? defaultLang,
+    body: f.parsed.body,
+    blocks: f.blocks,
+    toc: f.toc,
+    refs: f.refs,
+});
+// Validate the dialect and resolution of visual assets, terms and document links.
+const docErrors = (f, { docs, figures }) => {
+    const errors = [...f.parsed.errors];
+    for (const file of f.figureFiles) {
+        if (figures.get(figureName(file))?.file !== file) {
+            errors.push(`"${file.replace(/^figures\//, "")}" is not in figures/`);
+        }
+    }
+    for (const url of f.docLinks) {
+        const ref = parseDocLink(url);
+        const target = ref && docs.find((doc) => doc.file === ref.file);
+        if (ref && !target)
+            errors.push(`Document link "${url}" is unresolved (check the file path)`);
+        else if (ref?.fragment &&
+            target?.toc &&
+            !target.toc.some((heading) => heading.slug === ref.fragment))
+            errors.push(`Document link "${url}" refers to a missing heading`);
+    }
+    return errors;
+};
+import { docFile } from "../core/files.js";
+import { textfilePath } from "./textfile.js";
+export const createCompiler = (root, options = {}) => {
+    if (options.locale && !isContentLanguage(options.locale))
+        throw new Error("Expected an ISO 639-3 language code");
+    const contentDir = join(root, "content");
+    const figuresDir = join(root, "figures");
+    let docCache = createFileCache();
+    let previewKey = "";
+    const manifestCache = createFileCache();
+    const figuresCache = createSigCache();
+    const compile = () => {
+        const manifestPath = join(root, MANIFEST_FILE);
+        const manifest = existsSync(manifestPath)
+            ? manifestCache.get(manifestPath, parseManifestText)
+            : { tree: [], errors: [`${MANIFEST_FILE} is required`] };
+        const defaultLang = options.defaultLang ?? manifest.defaultLang ?? DEFAULT_LANG;
+        if (options.locale &&
+            manifest.languages &&
+            !siteContentLanguages(root, manifest).includes(options.locale))
+            throw new Error(`Language ${options.locale} is not declared in dooc.yaml languages`);
+        const themes = siteThemes(root, manifest);
+        const visualFiles = projectFiles(root)
+            .map((file) => file.path)
+            .filter((file) => /\.(svg|html|png|webp|gif|mp4|webm|jpe?g)$/.test(file));
+        const { figures, errors: figErrors } = figuresCache.get(dirSig(figuresDir) +
+            visualFiles.map((file) => `${file}:${fileSig(textfilePath(root, file))}`).join("|"), () => loadFigures(figuresDir, visualFiles));
+        const siteErrors = figErrors.filter((error) => error.startsWith("figures/"));
+        if (!isLangTag(defaultLang)) {
+            siteErrors.push("defaultLang must be a BCP 47 language tag");
+        }
+        const previews = parsePreviewSettings(options.previews ?? defaultPreviewSettings());
+        let title;
+        let icon;
+        let iconFile;
+        const files = [];
+        if (!existsSync(contentDir) && !manifest.files) {
+            siteErrors.push(`${contentDir}: content/ is missing`);
+        }
+        else {
+            const { tree, title: manifestTitle, icon: manifestIcon, errors: manifestErrors, } = manifest;
+            const nextPreviewKey = JSON.stringify(previews);
+            if (nextPreviewKey !== previewKey) {
+                docCache = createFileCache();
+                previewKey = nextPreviewKey;
+            }
+            title = manifestTitle;
+            iconFile = manifestIcon;
+            if (iconFile) {
+                try {
+                    icon = squareSvg(readTextfile(root, iconFile));
+                    if (!icon)
+                        throw new Error("expected an SVG with a viewBox or width and height");
+                }
+                catch (error) {
+                    siteErrors.push(`${MANIFEST_FILE}: icon ${iconFile}: ${error instanceof Error ? error.message : error}`);
+                }
+            }
+            siteErrors.push(...manifestErrors);
+            // Directly under content/: flat <id>.md files only (no folders).
+            const onDisk = new Set();
+            for (const entry of existsSync(contentDir)
+                ? readdirSync(contentDir, { withFileTypes: true })
+                : []) {
+                if (entry.name.startsWith(".")) {
+                    continue;
+                }
+                const id = entry.isFile() ? docIdOfFile(entry.name) : undefined;
+                if (id == null) {
+                    if (manifest.files)
+                        continue;
+                    siteErrors.push(`content/${entry.name}: only <id>.md (lowercase alphanumerics and hyphens) are allowed directly under content/`);
+                    continue;
+                }
+                onDisk.add(id);
+            }
+            // Manifest pre-order is the display order.
+            for (const { id, parent } of flattenTree(tree)) {
+                const rel = docFile(id, manifest.files);
+                if (rel.startsWith("content/")) {
+                    const diskId = docIdOfFile(rel.slice("content/".length));
+                    if (diskId)
+                        onDisk.delete(diskId);
+                }
+                let path;
+                try {
+                    path = textfilePath(root, rel);
+                }
+                catch (error) {
+                    siteErrors.push(`${rel}: ${error}`);
+                    continue;
+                }
+                if (!existsSync(path)) {
+                    siteErrors.push(`${rel}: listed in ${MANIFEST_FILE} but the file is missing`);
+                    continue;
+                }
+                let parsed = docCache.get(path, (raw) => parseFile(raw, previews, rel));
+                let language = defaultLang;
+                if (options.locale && options.locale !== contentLanguageCode(defaultLang)) {
+                    const file = translationFile(rel, options.locale);
+                    try {
+                        const translated = textfilePath(root, file);
+                        if (existsSync(translated)) {
+                            parsed = docCache.get(translated, (raw) => parseFile(raw, previews, rel));
+                            language = options.locale;
+                        }
+                    }
+                    catch (error) {
+                        siteErrors.push(`${file}: ${error}`);
+                    }
+                }
+                parsed = resolveFiles(parsed, root, undefined, previews, themes);
+                files.push({ doc: toDoc(id, parent, rel, parsed, language), parsed });
+            }
+            for (const id of onDisk) {
+                siteErrors.push(`content/${id}.md: not registered in ${MANIFEST_FILE}`);
+            }
+        }
+        for (const file of new Set(files.flatMap(({ parsed }) => parsed.figureFiles)))
+            if (!file.startsWith("figures/"))
+                siteErrors.push(...figErrors.filter((error) => error.startsWith(`${file}:`)));
+        // Icons are small, so read them every time (no cache).
+        const { icons, errors: iconErrors } = loadIcons(root, new Set(files.map((f) => f.doc.id)), iconFile, manifest.files);
+        siteErrors.push(...iconErrors);
+        for (const { doc } of files) {
+            const icon = icons.get(doc.id);
+            if (icon != null) {
+                doc.icon = icon;
+            }
+        }
+        const docs = files.map((f) => f.doc);
+        if (docs.length === 0) {
+            siteErrors.push(`${contentDir}: no docs`);
+        }
+        const ctx = {
+            docs,
+            figures: new Map(figures.map((f) => [f.name, f])),
+            defaultLang,
+        };
+        const sources = new Map();
+        const errors = [...siteErrors];
+        for (const { doc, parsed } of files) {
+            const errs = docErrors(parsed, ctx);
+            errors.push(...errs.map((e) => `${doc.file}: ${e}`));
+            sources.set(doc.file, {
+                terms: parsed.parsed.terms,
+                raw: parsed.raw,
+                frontmatter: parsed.parsed.frontmatter,
+                lines: parsed.lines,
+                errors: errs,
+            });
+        }
+        return {
+            previews,
+            ...(manifest.languages ? { contentLanguages: manifest.languages } : {}),
+            ...(manifest.themes ? { themes: manifest.themes } : {}),
+            ...(title === undefined ? {} : { title }),
+            ...(icon === undefined ? {} : { icon }),
+            docs,
+            terms: [...termMap(files.flatMap(({ parsed }) => parsed.parsed.terms)).values()],
+            figures,
+            sources,
+            siteErrors,
+            errors,
+            defaultLang,
+        };
+    };
+    return { compile };
+};
+/**
+ * Compiles a single unsaved draft (file = `content/<id>.md`) in the site's context.
+ * Not cached, since it changes on every keystroke. id / parent are looked up from the ctx.docs
+ * entry with the same file ("" for a new doc).
+ */
+export const compileDraft = (ctx, file, raw) => {
+    const known = ctx.docs.find((d) => d.file === file);
+    const previews = ctx.previews;
+    const parsed = resolveFiles(parseFile(raw, previews, file), ctx.root, ctx.textfiles, previews);
+    return {
+        doc: toDoc(known?.id ?? "", known?.parent, file, parsed, ctx.defaultLang ?? DEFAULT_LANG),
+        source: {
+            terms: parsed.parsed.terms,
+            raw,
+            frontmatter: parsed.parsed.frontmatter,
+            lines: parsed.lines,
+            errors: docErrors(parsed, ctx),
+        },
+    };
+};
+/** One-shot compile (for the build CLI / tests). */
+export const compileSite = (root, options = {}) => createCompiler(root, options).compile();

package/dist/compiler/config.d.ts

@@ -0,0 +1,7 @@
+import { type LanguageAdapter } from "../core/language.js";
+export declare const CONFIG_FILE = "docs.config.mjs";
+export interface ResolvedConfig {
+    languages: LanguageAdapter[];
+}
+/** Reads docs.config.mjs; defaults when absent. Throws with a readable message when invalid. */
+export declare const loadDocsConfig: (root: string) => Promise<ResolvedConfig>;

package/dist/compiler/config.js

@@ -0,0 +1,52 @@
+// Loads `<docs root>/docs.config.mjs` (optional): language adapters.
+// The file is a JS module, so loading it runs
+// its code — it belongs to the docs root like a build config. Read once per process; restart
+// after changing it.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isLangTag } from "../core/language.js";
+export const CONFIG_FILE = "docs.config.mjs";
+const FUNCTION_KEYS = ["isTermBoundary", "compareTerms", "lint"];
+const checkAdapter = (value, i) => {
+    const at = `${CONFIG_FILE}: languages[${i}]`;
+    if (typeof value !== "object" || value == null || Array.isArray(value)) {
+        throw new Error(`${at} must be an object`);
+    }
+    const a = value;
+    if (typeof a.code !== "string" || !isLangTag(a.code)) {
+        throw new Error(`${at}.code must be a BCP 47 language tag`);
+    }
+    for (const key of FUNCTION_KEYS) {
+        if (a[key] !== undefined && typeof a[key] !== "function") {
+            throw new Error(`${at}.${key} must be a function`);
+        }
+    }
+    if (a.spellcheckLang !== undefined && typeof a.spellcheckLang !== "string") {
+        throw new Error(`${at}.spellcheckLang must be a string`);
+    }
+    return value;
+};
+/** Reads docs.config.mjs; defaults when absent. Throws with a readable message when invalid. */
+export const loadDocsConfig = async (root) => {
+    const file = join(root, CONFIG_FILE);
+    if (!existsSync(file)) {
+        return {
+            languages: [],
+        };
+    }
+    const mod = (await import(pathToFileURL(file).href));
+    const config = mod.default;
+    if (typeof config !== "object" || config == null || Array.isArray(config)) {
+        throw new Error(`${CONFIG_FILE}: the default export must be an object`);
+    }
+    if ("defaultLang" in config)
+        throw new Error(`${CONFIG_FILE}: move defaultLang to dooc.yaml`);
+    const { languages } = config;
+    if (languages !== undefined && !Array.isArray(languages)) {
+        throw new Error(`${CONFIG_FILE}: languages must be an array`);
+    }
+    return {
+        languages: (languages ?? []).map(checkAdapter),
+    };
+};