@dooc-dev/dooc 0.0.0-stage → 0.0.2

package/dist/compiler/from-mdast.js

@@ -0,0 +1,142 @@
+// Converter from dialect mdast → normalized Block AST (internal module for build / preview only,
+// outside the publish surface). The consumer contract (Block / TocEntry / slugify) lives in
+// blocks.ts; validation is handled by dialect.ts.
+import { basename, extname } from "node:path";
+import { slugify } from "../core/blocks.js";
+import { parseFileEmbed } from "../core/file-embed.js";
+import { inlineSegmenter } from "../core/inline.js";
+import { inlineToText, listItems, standaloneImages } from "../core/markdown.js";
+import { textfileName } from "../core/textfile.js";
+import { parseContentCode } from "./code-blocks.js";
+import { figureName } from "./figures.js";
+const tableBlock = (t) => {
+    const [head, ...rows] = t.children;
+    return {
+        type: "table",
+        headers: (head?.children ?? []).map((c) => inlineToText(c.children)),
+        rows: rows.map((r) => r.children.map((c) => inlineToText(c.children))),
+    };
+};
+/**
+ * Dialect mdast → normalized Block[] + TOC. Heading slugs are made unique within the document.
+ * `raw` is the whole source document, used to validate semantic code fences.
+ * `lines` holds the source start line at the same index as blocks (1-indexed relative to the
+ * whole raw, as root is).
+ * Only the edit tool's "body element ↔ source line" mapping uses it (the rendering model
+ * is unaffected).
+ */
+export const toBlocks = (root, raw, settings, file) => {
+    const toc = [];
+    const lines = [];
+    const seen = new Map();
+    let unslugged = 0;
+    const inline = inlineSegmenter();
+    const convert = (nodes, topLevel = false) => {
+        const blocks = [];
+        for (const n of nodes) {
+            // Every push to blocks also pushes the source line in lockstep (defined in one place).
+            const add = (b) => {
+                blocks.push(b);
+                if (topLevel)
+                    lines.push(n.position?.start.line ?? 1);
+            };
+            switch (n.type) {
+                case "yaml":
+                    break;
+                case "heading": {
+                    const h = n;
+                    const depth = h.depth;
+                    const text = inlineToText(h.children);
+                    // Headings with no ASCII slug (e.g. all-Japanese text) are numbered per doc.
+                    const label = inline(text)
+                        .map((part) => part.text)
+                        .join("");
+                    const base = slugify(label) || `section-${++unslugged}`;
+                    const dup = seen.get(base) ?? 0;
+                    seen.set(base, dup + 1);
+                    const slug = dup === 0 ? base : `${base}-${dup}`;
+                    toc.push({ depth, text: label, slug });
+                    add({ type: "h", level: depth, text, slug });
+                    break;
+                }
+                case "blockquote":
+                    add({ type: "quote", blocks: convert(n.children) });
+                    break;
+                case "paragraph": {
+                    const images = standaloneImages(n);
+                    if (!images.length)
+                        add({ type: "p", text: inlineToText(n.children) });
+                    for (const image of images) {
+                        try {
+                            const { file, range, tableMode, kind } = parseFileEmbed(image.url, settings);
+                            if (kind === "external") {
+                                add({
+                                    type: "external",
+                                    url: file,
+                                    ...(image.alt ? { alt: image.alt } : {}),
+                                });
+                                if (topLevel)
+                                    lines[lines.length - 1] = image.position?.start.line ?? 1;
+                                continue;
+                            }
+                            if (kind !== "textfile") {
+                                add({
+                                    type: "figureRef",
+                                    name: figureName(file),
+                                    alt: image.alt ?? "",
+                                });
+                                if (topLevel)
+                                    lines[lines.length - 1] = image.position?.start.line ?? 1;
+                                continue;
+                            }
+                            add({
+                                type: "code",
+                                filename: file,
+                                ...(range !== undefined ? { range } : {}),
+                                ...(tableMode ? { tableMode } : {}),
+                                ...(image.alt ? { alt: image.alt } : {}),
+                                lang: (extname(textfileName(file)).slice(1) ||
+                                    basename(textfileName(file))).toLowerCase(),
+                                lines: [],
+                            });
+                            if (topLevel)
+                                lines[lines.length - 1] = image.position?.start.line ?? 1;
+                        }
+                        catch {
+                            // parseDoc reports malformed URLs; do not try to read them.
+                        }
+                    }
+                    break;
+                }
+                case "list":
+                    add({
+                        type: "list",
+                        items: listItems(n, convert),
+                        ...(n.ordered ? { ordered: true } : {}),
+                    });
+                    break;
+                case "code": {
+                    const parsed = parseContentCode(n, raw, file);
+                    if (parsed) {
+                        for (const block of parsed.blocks)
+                            add(block);
+                        break;
+                    }
+                    add({
+                        type: "code",
+                        lines: n.value.split("\n"),
+                        ...(n.lang != null ? { lang: n.lang } : {}),
+                    });
+                    break;
+                }
+                case "table":
+                    add(tableBlock(n));
+                    break;
+                default:
+                    break;
+            }
+        }
+        return blocks;
+    };
+    return { blocks: convert(root.children, true), toc, lines };
+};

package/dist/compiler/icons.d.ts

@@ -0,0 +1,14 @@
+import { type FileLayout } from "../core/files.js";
+export declare const ICONS_DIR = "icons";
+/**
+ * Normalize an SVG to 1:1 (padding is added automatically = the shorter side is widened, centered;
+ * nothing is cropped). Builds a square viewBox from the root's viewBox (or width / height if it has
+ * none) and removes fixed width / height (so it scales to the display box). Returns undefined for
+ * SVGs whose dimensions can't be read.
+ */
+export declare const squareSvg: (svg: string) => string | undefined;
+/** Read icons/ (docId → svg markup). An icon with no doc is an error (missed rename / delete). */
+export declare const loadIcons: (root: string, docIds: ReadonlySet<string>, siteIconFile?: string, layout?: FileLayout) => {
+    icons: Map<string, string>;
+    errors: string[];
+};

package/dist/compiler/icons.js

@@ -0,0 +1,85 @@
+// A doc's icon (1:1 SVG shown on its sidebar row). It lives at icons/<docId>.svg in the docs root.
+// Separate from body-text figures (figures/): one per doc, following the doc's rename / deletion.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { docIconFile } from "../core/files.js";
+import { textfilePath } from "./textfile.js";
+export const ICONS_DIR = "icons";
+const ROOT_SVG_RE = /<svg\b[^>]*>/i;
+const num = (v) => {
+    const n = v == null ? Number.NaN : Number.parseFloat(v);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+/**
+ * Normalize an SVG to 1:1 (padding is added automatically = the shorter side is widened, centered;
+ * nothing is cropped). Builds a square viewBox from the root's viewBox (or width / height if it has
+ * none) and removes fixed width / height (so it scales to the display box). Returns undefined for
+ * SVGs whose dimensions can't be read.
+ */
+export const squareSvg = (svg) => {
+    const root = ROOT_SVG_RE.exec(svg)?.[0];
+    if (!root) {
+        return undefined;
+    }
+    const attr = (name) => new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, "i").exec(root)?.[1];
+    const vb = attr("viewBox")
+        ?.trim()
+        .split(/[\s,]+/)
+        .map(Number);
+    let [x, y, w, h] = vb && vb.length === 4 && vb.every(Number.isFinite)
+        ? vb
+        : [0, 0, num(attr("width")), num(attr("height"))];
+    if (x == null || y == null || w == null || h == null || w <= 0 || h <= 0) {
+        return undefined;
+    }
+    const side = Math.max(w, h);
+    x -= (side - w) / 2;
+    y -= (side - h) / 2;
+    const round = (n) => Math.round(n * 1000) / 1000;
+    // Rendered via <img> (data URI), so it won't draw without xmlns — add it if missing.
+    const xmlns = /\sxmlns\s*=/.test(root) ? "" : ' xmlns="http://www.w3.org/2000/svg"';
+    const next = root
+        .replace(/\s(viewBox|width|height|preserveAspectRatio)\s*=\s*(["'])[^"']*\2/gi, "")
+        .replace(/^<svg\b/i, `<svg${xmlns} viewBox="${[x, y, side, side].map(round).join(" ")}" preserveAspectRatio="xMidYMid meet"`);
+    return svg.replace(root, next);
+};
+/** Read icons/ (docId → svg markup). An icon with no doc is an error (missed rename / delete). */
+export const loadIcons = (root, docIds, siteIconFile, layout) => {
+    const dir = join(root, ICONS_DIR);
+    const icons = new Map();
+    const errors = [];
+    for (const f of existsSync(dir) ? readdirSync(dir) : []) {
+        if (f.startsWith(".")) {
+            continue;
+        }
+        const id = f.endsWith(".svg") ? f.slice(0, -4) : "";
+        if (!docIds.has(id)) {
+            if (siteIconFile?.replace(/^\.\//, "") === `${ICONS_DIR}/${f}`)
+                continue;
+            errors.push(`${ICONS_DIR}/${f}: no matching doc (content/${id || f}.md)`);
+            continue;
+        }
+        const svg = readFileSync(join(dir, f), "utf8");
+        if (!ROOT_SVG_RE.test(svg)) {
+            errors.push(`${ICONS_DIR}/${f}: not an svg`);
+            continue;
+        }
+        icons.set(id, svg);
+    }
+    for (const id of docIds)
+        if (layout?.icons?.[id]) {
+            try {
+                const file = textfilePath(root, docIconFile(id, layout));
+                if (!existsSync(file))
+                    continue;
+                const svg = readFileSync(file, "utf8");
+                if (!ROOT_SVG_RE.test(svg))
+                    throw new Error("not an svg");
+                icons.set(id, svg);
+            }
+            catch (error) {
+                errors.push(`${docIconFile(id, layout)}: ${error}`);
+            }
+        }
+    return { icons, errors };
+};

package/dist/compiler/language-codes.d.ts

@@ -0,0 +1,7 @@
+export { contentLanguageCode, isContentLanguage } from "../core/language.js";
+export declare const contentLanguages: {
+    code: string;
+    name: string;
+}[];
+export declare const webLanguage: (code: string) => string;
+export declare const languageName: (code: string) => string;

package/dist/compiler/language-codes.js

@@ -0,0 +1,17 @@
+import { iso6393, iso6393To1 } from "iso-639-3";
+export { contentLanguageCode, isContentLanguage } from "../core/language.js";
+export const contentLanguages = iso6393
+    .map(({ iso6393: code, name }) => ({ code, name }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+const codes = new Map(iso6393.map((language) => [language.iso6393, language.name]));
+export const webLanguage = (code) => iso6393To1[code] ?? code;
+export const languageName = (code) => {
+    try {
+        return (new Intl.DisplayNames([webLanguage(code)], { type: "language" }).of(webLanguage(code)) ??
+            codes.get(code) ??
+            code);
+    }
+    catch {
+        return codes.get(code) ?? code;
+    }
+};

package/dist/compiler/locales.d.ts

@@ -0,0 +1,7 @@
+import { type ParsedManifest } from "../core/content-metadata.js";
+export declare const translationFile: (file: string, language: string) => string;
+export declare const translationLanguages: (root: string) => string[];
+/** Declared languages are authoritative; older sites retain directory discovery. */
+export declare const siteContentLanguages: (root: string, manifest?: ParsedManifest) => string[];
+export declare const translationFiles: (root: string) => string[];
+export declare const setDocTranslation: (root: string, sourceLanguage: string, id: string, language: string, added: boolean) => void;

package/dist/compiler/locales.js

@@ -0,0 +1,67 @@
+// Translations mirror source paths under locales/<ISO 639-3>/ as ordinary Markdown files.
+import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join, relative } from "node:path";
+import { isDocId } from "../core/content-metadata.js";
+import { localFile } from "../core/files.js";
+import { contentLanguageCode, DEFAULT_LANG } from "../core/language.js";
+import { parseDoc } from "./dialect.js";
+import { isContentLanguage } from "./language-codes.js";
+import { docFile, readManifest } from "./manifest.js";
+import { assembleDoc } from "./serialize.js";
+import { readTextfile, textfilePath, writeTextfile } from "./textfile.js";
+export const translationFile = (file, language) => {
+    if (!isContentLanguage(language))
+        throw new Error("Expected an ISO 639-3 language code");
+    if (!localFile(file) || !file.endsWith(".md"))
+        throw new Error("Expected a Markdown file path");
+    return `locales/${language}/${file}`;
+};
+export const translationLanguages = (root) => {
+    const dir = textfilePath(root, "locales");
+    return existsSync(dir)
+        ? readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && isContentLanguage(entry.name))
+            .map((entry) => entry.name)
+            .sort()
+        : [];
+};
+/** Declared languages are authoritative; older sites retain directory discovery. */
+export const siteContentLanguages = (root, manifest = readManifest(root)) => manifest.languages ?? [
+    ...new Set([
+        contentLanguageCode(manifest.defaultLang ?? DEFAULT_LANG),
+        ...translationLanguages(root),
+    ]),
+];
+export const translationFiles = (root) => translationLanguages(root).flatMap((language) => {
+    const directory = `locales/${language}`;
+    return readdirSync(textfilePath(root, directory), { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => relative(root, join(entry.parentPath, entry.name)).replaceAll("\\", "/"))
+        .filter(localFile)
+        .sort();
+});
+export const setDocTranslation = (root, sourceLanguage, id, language, added) => {
+    if (!isDocId(id))
+        throw new Error("Invalid document id");
+    if (language === sourceLanguage)
+        throw new Error("Source language cannot be removed");
+    const manifest = readManifest(root);
+    if (manifest.errors.length)
+        throw new Error(manifest.errors.join("\n"));
+    if (manifest.languages && !manifest.languages.includes(language))
+        throw new Error(`Language ${language} is not declared in dooc.yaml languages`);
+    const file = docFile(id, manifest.files);
+    const translated = translationFile(file, language);
+    const path = textfilePath(root, translated);
+    const source = readTextfile(root, file);
+    if (added === existsSync(path))
+        return;
+    if (added) {
+        const doc = parseDoc(source);
+        if (!doc.frontmatter)
+            throw new Error("Fix the source front-matter before translating");
+        writeTextfile(root, translated, assembleDoc({ ...doc.frontmatter, lang: language }, doc.body), null);
+    }
+    else
+        unlinkSync(path);
+};

package/dist/compiler/manifest.d.ts

@@ -0,0 +1,6 @@
+import { type DocNode, type ParsedManifest } from "../core/content-metadata.js";
+export declare const parseManifestText: (raw: string) => ParsedManifest;
+/** Empty tree if missing (a new docs root with zero docs). */
+export declare const readManifest: (root: string) => ParsedManifest;
+export declare const writeManifest: (root: string, tree: readonly DocNode[], metadata?: Omit<ParsedManifest, "tree" | "errors">) => void;
+export { docFile } from "../core/files.js";

package/dist/compiler/manifest.js

@@ -0,0 +1,30 @@
+// Reads/writes dooc.yaml (node-dependent). Tree validation and manipulation live in
+// core/content-metadata.ts.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { MANIFEST_FILE, parseManifest, serializeManifest, } from "../core/content-metadata.js";
+export const parseManifestText = (raw) => {
+    let value;
+    try {
+        value = parse(raw);
+    }
+    catch (e) {
+        return {
+            tree: [],
+            errors: [`${MANIFEST_FILE}: invalid YAML (${e instanceof Error ? e.message : e})`],
+        };
+    }
+    return parseManifest(value);
+};
+/** Empty tree if missing (a new docs root with zero docs). */
+export const readManifest = (root) => {
+    const path = join(root, MANIFEST_FILE);
+    return existsSync(path)
+        ? parseManifestText(readFileSync(path, "utf8"))
+        : { tree: [], errors: [] };
+};
+export const writeManifest = (root, tree, metadata = {}) => {
+    writeFileSync(join(root, MANIFEST_FILE), serializeManifest(tree, metadata));
+};
+export { docFile } from "../core/files.js";

package/dist/compiler/ops.d.ts

@@ -0,0 +1,44 @@
+import { type ParsedManifest } from "../core/content-metadata.js";
+export interface OpError {
+    error: string;
+    status: 400 | 404 | 409;
+    referencedBy?: string[];
+}
+export type OpResult<T> = T | OpError;
+export declare const isOpError: (r: unknown) => r is OpError;
+export { assembleDoc } from "./serialize.js";
+export declare const createDocOps: (root: string) => {
+    contentDir: string;
+    figuresDir: string;
+    loadTree: () => OpResult<ParsedManifest>;
+    referencingFiles: (id: string, removed: readonly string[]) => string[];
+    figureFiles: () => Map<string, string>;
+    add: (id: string, title: string, parent?: string, filename?: string) => OpResult<{
+        id: string;
+    }>;
+    addFile: (name: string, title: string, parent?: string) => OpResult<{
+        id: string;
+    }>;
+    move: (id: string, parent?: string, index?: number) => OpResult<{
+        id: string;
+    }>;
+    rename: (oldId: string, newId: string) => OpResult<{
+        id: string;
+        updatedRefs: number;
+    }>;
+    remove: (id: string, force?: boolean) => OpResult<{
+        parent: string | undefined;
+        danglingRefs: number;
+    }>;
+    write: (id: string, raw: string) => OpResult<{
+        id: string;
+    }>;
+    addFigure: (file: string, data: Buffer) => OpResult<{
+        file: string;
+        path?: string;
+    }>;
+    removeFigure: (name: string, force?: boolean) => OpResult<{
+        file: string;
+    }>;
+};
+export type DocOps = ReturnType<typeof createDocOps>;