@dooc-dev/dooc 0.0.0-stage → 0.0.2

package/dist/compiler/textfile.d.ts

@@ -0,0 +1,9 @@
+export { parseTextfileRange } from "../core/textfile.js";
+/** Select whole lines, preserving their original separators and excluding the final separator. */
+export declare const selectTextfileRange: (text: string, range?: string) => string;
+/** Embedded files must stay inside the docs root, including symlink targets. */
+export declare const textfilePath: (root: string, file: string) => string;
+export declare const readTextfile: (root: string, file: string, refresh?: boolean, domains?: readonly string[]) => string;
+export declare const readTextfileAsync: (root: string, file: string, refresh?: boolean, domains?: readonly string[]) => Promise<string>;
+/** Compare before writing; null means create only, never overwrite an existing file. */
+export declare const writeTextfile: (root: string, file: string, content: string, base: string | null) => boolean;

package/dist/compiler/textfile.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isRemoteTextfile, parseTextfileRange } from "../core/textfile.js";
+import { readRemoteTextfile, readRemoteTextfileAsync } from "./textfile-remote.js";
+export { parseTextfileRange } from "../core/textfile.js";
+/** Select whole lines, preserving their original separators and excluding the final separator. */
+export const selectTextfileRange = (text, range) => {
+    if (range === undefined)
+        return text;
+    const [start, end] = parseTextfileRange(range);
+    const starts = [
+        0,
+        ...[...text.matchAll(/\r\n|\n|\r/g)]
+            .map((match) => match.index + match[0].length)
+            .filter((offset) => offset < text.length),
+    ];
+    const from = starts[start - 1];
+    if (from === undefined)
+        throw new Error(`range line ${start} does not exist`);
+    if (starts[end - 1] === undefined)
+        throw new Error(`range line ${end} does not exist`);
+    return text.slice(from, starts[end] ?? text.length).replace(/(?:\r\n|\n|\r)$/, "");
+};
+/** Embedded files must stay inside the docs root, including symlink targets. */
+export const textfilePath = (root, file) => {
+    if (!file.trim() ||
+        /^[a-z][a-z\d+.-]*:/i.test(file) ||
+        /[\0\r\n]/.test(file) ||
+        isAbsolute(file) ||
+        file.includes("\\") ||
+        file.split("/").includes(".."))
+        throw new Error("expected a relative file path inside the docs root");
+    const path = resolve(root, file);
+    let ancestor = path;
+    while (!lstatSync(ancestor, { throwIfNoEntry: false }))
+        ancestor = dirname(ancestor);
+    let resolvedAncestor;
+    try {
+        resolvedAncestor = realpathSync(ancestor);
+    }
+    catch {
+        throw new Error("cannot resolve the file path (check symlink targets)");
+    }
+    const resolved = resolve(resolvedAncestor, relative(ancestor, path));
+    const rel = relative(realpathSync(root), resolved);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw new Error("file is outside the docs root");
+    return resolved;
+};
+export const readTextfile = (root, file, refresh = false, domains = []) => {
+    let data;
+    if (isRemoteTextfile(file)) {
+        data = readRemoteTextfile(file, domains, refresh);
+    }
+    else {
+        const path = textfilePath(root, file);
+        if (!statSync(path).isFile())
+            throw new Error("expected a regular UTF-8 text file");
+        data = readFileSync(path);
+    }
+    return decodeTextfile(data);
+};
+const decodeTextfile = (data) => {
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(data);
+    if (text.includes("\0"))
+        throw new Error("expected a UTF-8 text file, not binary data");
+    return text;
+};
+export const readTextfileAsync = async (root, file, refresh = false, domains = []) => {
+    if (isRemoteTextfile(file)) {
+        return decodeTextfile(await readRemoteTextfileAsync(file, domains, refresh));
+    }
+    const path = textfilePath(root, file);
+    if (!(await stat(path)).isFile())
+        throw new Error("expected a regular UTF-8 text file");
+    const handle = await open(path, "r");
+    try {
+        if (!(await handle.stat()).isFile())
+            throw new Error("expected a regular UTF-8 text file");
+        return decodeTextfile(await handle.readFile());
+    }
+    finally {
+        await handle.close();
+    }
+};
+/** Compare before writing; null means create only, never overwrite an existing file. */
+export const writeTextfile = (root, file, content, base) => {
+    if (/[\0\uD800-\uDFFF]/u.test(content))
+        throw new Error("expected UTF-8 text");
+    const path = textfilePath(root, file);
+    const exists = lstatSync(path, { throwIfNoEntry: false });
+    const current = exists ? readTextfile(root, file) : null;
+    if (current !== base)
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = join(dirname(path), `.textfile-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temp, content, {
+            flag: "wx",
+            mode: current === null ? 0o666 : statSync(path).mode,
+        });
+        if (current === null)
+            linkSync(temp, path);
+        else
+            renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+    return true;
+};

package/dist/compiler/theme-variants.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedManifest } from "../core/content-metadata.js";
+export declare const themeNames: (root: string) => string[];
+export declare const siteThemes: (root: string, manifest?: ParsedManifest) => string[];
+export declare const themeVariants: (root: string, file: string, themes?: string[]) => Record<string, string>;

package/dist/compiler/theme-variants.js

@@ -0,0 +1,22 @@
+import { existsSync, readdirSync } from "node:fs";
+import { localFile } from "../core/files.js";
+import { themeVariantFile } from "../core/theme-variants.js";
+import { readManifest } from "./manifest.js";
+import { textfilePath } from "./textfile.js";
+export const themeNames = (root) => {
+    const directory = textfilePath(root, "themes");
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && /^[a-z][a-z0-9-]*$/.test(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+};
+export const siteThemes = (root, manifest = readManifest(root)) => manifest.themes ?? themeNames(root);
+export const themeVariants = (root, file, themes = siteThemes(root)) => {
+    if (!localFile(file) || file.startsWith("themes/"))
+        return {};
+    return Object.fromEntries(themes
+        .map((theme) => [theme, themeVariantFile(file, theme)])
+        .filter(([, path]) => existsSync(textfilePath(root, path))));
+};

package/dist/compiler/zip.d.ts

@@ -0,0 +1,6 @@
+export interface ZipEntry {
+    /** Path inside the zip (`/`-separated). */
+    name: string;
+    data: Buffer;
+}
+export declare const zip: (entries: readonly ZipEntry[]) => Buffer;

package/dist/compiler/zip.js

@@ -0,0 +1,48 @@
+// Minimal zip writer (deflate, UTF-8 file names). Hand-rolled to avoid adding an external
+// dependency.
+// shortcut: no ZIP64 support = can't handle more than 4GB / 65535 entries; switch to a library if
+// the docs root outgrows that.
+import { crc32, deflateRawSync } from "node:zlib";
+// Fixed date (1980-01-01 00:00) = the same input yields the same zip (reproducible).
+const DOS_DATE = (0 << 9) | (1 << 5) | 1;
+export const zip = (entries) => {
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const { name, data } of entries) {
+        const nameBuf = Buffer.from(name, "utf8");
+        const body = deflateRawSync(data);
+        const crc = crc32(data);
+        // The "version … name length" part shared by the local and central headers.
+        const common = Buffer.alloc(26);
+        common.writeUInt16LE(20, 0); // version needed
+        common.writeUInt16LE(0x0800, 2); // flag: UTF-8 file names
+        common.writeUInt16LE(8, 4); // method: deflate
+        common.writeUInt16LE(0, 6); // time
+        common.writeUInt16LE(DOS_DATE, 8);
+        common.writeUInt32LE(crc, 10);
+        common.writeUInt32LE(body.length, 14);
+        common.writeUInt32LE(data.length, 18);
+        common.writeUInt16LE(nameBuf.length, 22);
+        common.writeUInt16LE(0, 24); // extra length
+        const local = Buffer.concat([Buffer.from([0x50, 0x4b, 0x03, 0x04]), common, nameBuf]);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(0x031e, 4); // version made by = Unix / 3.0 (unzip keeps UTF-8 names)
+        common.copy(central, 6);
+        // 32: comment length / 34: disk / 36: internal attr = 0; 38: external attr = Unix mode 0644
+        central.writeUInt32LE((0o100644 << 16) >>> 0, 38);
+        central.writeUInt32LE(offset, 42);
+        locals.push(local, body);
+        centrals.push(central, nameBuf);
+        offset += local.length + body.length;
+    }
+    const dir = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(dir.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, dir, end]);
+};

package/dist/core/blocks.d.ts

@@ -0,0 +1,99 @@
+import type { TermEntry } from "./content-types.js";
+import type { GraphModel } from "./graph.js";
+import type { SchemaModel } from "./schema-graph.js";
+import type { CodeLang } from "./taxonomy.js";
+/** Nestable list item. string = leaf, object = has children. ordered = whether the children are
+ * numbered (irrelevant for childless leaves). */
+export type ListItem = string | {
+    text: string;
+    children: ListItem[];
+    ordered?: boolean;
+} | {
+    blocks: Block[];
+};
+/** One element of a callout body. Paragraphs / lists can be mixed in any order. */
+export type CalloutItem = {
+    type: "p";
+    text: string;
+} | {
+    type: "list";
+    items: ListItem[];
+    ordered?: boolean;
+};
+export type Block = {
+    type: "themeVariants";
+    default: Block;
+    variants: Record<string, Block>;
+} | {
+    type: "external";
+    url: string;
+    alt?: string;
+} | {
+    type: "p";
+    text: string;
+} | {
+    type: "quote";
+    blocks: Block[];
+} | {
+    type: "h";
+    level: 1 | 2 | 3;
+    text: string;
+    slug: string;
+} | {
+    type: "list";
+    items: ListItem[];
+    ordered?: boolean;
+} | {
+    type: "code";
+    lines: string[];
+    lang?: CodeLang;
+    filename?: string;
+    range?: string;
+    tableMode?: "header";
+    alt?: string;
+    unavailable?: "missing" | "unreachable";
+} | {
+    type: "table";
+    dataSource?: string;
+    tableMode?: "header";
+    headers: string[];
+    rows: string[][];
+    alt?: string;
+    caption?: string;
+    collapsible?: boolean;
+} | {
+    type: "callout";
+    title?: string;
+    alt?: string;
+    body: CalloutItem[];
+} | {
+    type: "figureRef";
+    name: string;
+    alt?: string;
+    caption?: string;
+} | {
+    type: "term";
+    entry: TermEntry;
+} | {
+    type: "figures";
+} | {
+    type: "schemaGraph";
+    alt?: string;
+    caption?: string;
+    graph: SchemaModel;
+    source?: string;
+} | {
+    type: "graph";
+    alt?: string;
+    caption?: string;
+    graph: GraphModel;
+    source?: string;
+};
+export interface TocEntry {
+    /** heading depth (1 = `#`, 2 = `##`, 3 = `###`) */
+    depth: 1 | 2 | 3;
+    text: string;
+    slug: string;
+}
+export declare const walkBlocks: (blocks: readonly Block[]) => Block[];
+export declare const slugify: (text: string) => string;

package/dist/core/blocks.js

@@ -0,0 +1,29 @@
+export const walkBlocks = (blocks) => {
+    const listBlocks = (items) => items.flatMap((item) => typeof item === "string"
+        ? []
+        : "blocks" in item
+            ? walkBlocks(item.blocks)
+            : listBlocks(item.children));
+    return blocks.flatMap((block) => [
+        block,
+        ...(block.type === "themeVariants"
+            ? walkBlocks([block.default, ...Object.values(block.variants)])
+            : block.type === "quote"
+                ? walkBlocks(block.blocks)
+                : block.type === "list"
+                    ? listBlocks(block.items)
+                    : []),
+    ]);
+};
+// Slug for heading / term anchors: always ASCII, whatever the doc language (slugs are not part
+// of the language socket). Like github-slugger for ASCII text (lowercase / strip symbols /
+// whitespace → hyphen); accents are folded (`café` → `cafe`) and any other non-ASCII text is
+// dropped, so the result may be "" — callers supply a fallback (e.g. `section-N`). Used together
+// with routing.headingAnchor, which namespaces heading anchors (`<docId>__<slug>`).
+export const slugify = (text) => text
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9_\- ]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/^-+|-+$/g, "");

package/dist/core/code-file.d.ts

@@ -0,0 +1,12 @@
+import { type PreviewSettings } from "./previewers.js";
+export declare const codeFileName: (body: string, position: number, documentId: string) => string;
+/** Preserve the body bytes and replace only a standalone, closed fence. */
+export declare const codeFilePlan: (body: string, position: number, target: string, settings?: PreviewSettings) => {
+    file: string;
+    content: string;
+    change: {
+        from: number;
+        to: number;
+        insert: string;
+    };
+};

package/dist/core/code-file.js

@@ -0,0 +1,68 @@
+import { codeBlockAt } from "./markdown.js";
+import { resolvePreviewer } from "./previewers.js";
+import { CODE_TEMPLATES } from "./taxonomy.js";
+import { termFileUrl } from "./term-reference.js";
+export const codeFileName = (body, position, documentId) => {
+    const block = codeBlockAt(body, position);
+    const language = block.language.toLowerCase();
+    const aliases = {
+        javascript: "js",
+        typescript: "ts",
+        python: "py",
+        rust: "rs",
+        ruby: "rb",
+        csharp: "cs",
+        bash: "sh",
+        powershell: "ps1",
+        markdown: "md",
+        "c++": "cpp",
+    };
+    const extension = Object.hasOwn(aliases, language)
+        ? aliases[language]
+        : /^[a-z0-9_-]+$/.test(language)
+            ? language
+            : "txt";
+    const directory = language === "termth"
+        ? "terms"
+        : language === "graphth" || language === "schemath"
+            ? "figures"
+            : "examples";
+    return `${directory}/${documentId}-${body.slice(0, block.start).split("\n").length}.${extension}`;
+};
+/** Preserve the body bytes and replace only a standalone, closed fence. */
+export const codeFilePlan = (body, position, target, settings) => {
+    const block = codeBlockAt(body, position);
+    if (!block.topLevel)
+        throw new Error("Only standalone code blocks can become files");
+    const semantic = Object.hasOwn(CODE_TEMPLATES, block.language);
+    if (block.meta && (!semantic || block.language === "termth"))
+        throw new Error("Remove code fence metadata before creating a file");
+    const file = target.trim().replace(/^(\.\/)+/, "");
+    if (!file ||
+        /^[/\\]|^[a-z][a-z\d+.-]*:/i.test(file) ||
+        /[\\\0\r\n]/.test(file) ||
+        file.split("/").includes(".."))
+        throw new Error("Use a relative file path inside the docs root");
+    if (semantic && !file.endsWith(`.${block.language}`))
+        throw new Error(`Use the .${block.language} extension`);
+    const url = termFileUrl(file);
+    const previewer = resolvePreviewer(url, settings);
+    if (semantic && previewer && previewer !== "code" && previewer !== "table")
+        throw new Error("Register this extension with the Code previewer");
+    const sourceOnly = !semantic &&
+        ((previewer !== undefined && previewer !== "code") ||
+            /\.(callouth|schemath|graphth|termth)$/i.test(file));
+    const lastLine = block.code.split("\n").length;
+    const range = sourceOnly ? `#L1${lastLine > 1 ? `-L${lastLine}` : ""}` : "";
+    const caption = semantic ? block.meta.replace(/[\\[\]]/g, "\\$&") : "";
+    const from = body.lastIndexOf("\n", block.start - 1) + 1;
+    const before = body.slice(0, from);
+    const after = body.slice(block.end);
+    const prefix = before.trim() && !/\r?\n[ \t]*\r?\n$/.test(before) ? block.eol : "";
+    const suffix = after.trim() && !/^\r?\n[ \t]*\r?\n/.test(after) ? block.eol : "";
+    return {
+        file,
+        content: block.code.replaceAll("\n", block.eol) + (block.from === block.to ? "" : block.eol),
+        change: { from, to: block.end, insert: `${prefix}![${caption}](${url}${range})${suffix}` },
+    };
+};

package/dist/core/content-metadata.d.ts

@@ -0,0 +1,48 @@
+import { type FileLayout } from "./files.js";
+export declare const MANIFEST_FILE = "dooc.yaml";
+export interface DocNode {
+    id: string;
+    children: DocNode[];
+}
+export interface ParsedManifest {
+    tree: DocNode[];
+    title?: string;
+    icon?: string;
+    defaultLang?: string;
+    files?: FileLayout;
+    /** Content languages offered by the site, including defaultLang; normalized to ISO 639-3. */
+    languages?: string[];
+    /** Color themes offered by the site, with authored variants for embedded files. */
+    themes?: ("light" | "dark")[];
+    errors: string[];
+}
+export declare const DOC_ID_RE: RegExp;
+export declare const isDocId: (s: string) => boolean;
+/** Doc file name directly under content/ (`<id>.md`) → id. undefined if the shape differs. */
+export declare const docIdOfFile: (name: string) => string | undefined;
+/**
+ * Turn the parsed dooc.yaml (YAML → JS value) into a tree. Each element is `id` (no
+ * children) or `{ id: [children...] }` (a single-key map; a null value also means no children).
+ * Validates id shape and duplicates.
+ */
+export declare const parseManifest: (value: unknown) => ParsedManifest;
+/** Tree → dooc.yaml text (serialized in the hand-written shape, keeping git diffs clean). */
+export declare const serializeManifest: (tree: readonly DocNode[], { title, icon, defaultLang, files, languages, themes, }?: Omit<ParsedManifest, "tree" | "errors">) => string;
+/** Flatten the tree into display order (pre-order). parent omitted = top level. */
+export declare const flattenTree: (tree: readonly DocNode[]) => {
+    id: string;
+    parent?: string;
+    depth: number;
+}[];
+/** Append a new doc to the end of parent's children. Duplicate id / missing parent → undefined. */
+export declare const insertDoc: (tree: readonly DocNode[], id: string, parent?: string) => DocNode[] | undefined;
+/**
+ * Move a doc (with its children) to position index under parent. It can't be moved under
+ * itself or its own descendants (that would create a cycle). An invalid move returns undefined
+ * (no partial update).
+ */
+export declare const moveDoc: (tree: readonly DocNode[], id: string, parent: string | undefined, index: number) => DocNode[] | undefined;
+/** Remove a doc. Docs with children are not removed (we don't decide where the children go). */
+export declare const removeDoc: (tree: readonly DocNode[], id: string) => DocNode[] | undefined;
+/** Change a doc's id (position and children stay as they are). */
+export declare const renameDoc: (tree: readonly DocNode[], oldId: string, newId: string) => DocNode[] | undefined;