@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/core/markdown.d.ts

@@ -0,0 +1,27 @@
+import type { Image, Link, List as MdList, PhrasingContent, Root, RootContent } from "mdast";
+import type { Block, ListItem } from "./blocks.js";
+export declare const parseMdast: (raw: string) => Root;
+/** File previews occupy whole paragraphs; prose, lists and tables keep their inline layout. */
+export declare const standaloneImages: (node: RootContent) => Image[];
+export declare const embeddedImages: (root: Root) => Image[];
+export declare const offsetAt: (body: string, line: number, column: number) => number;
+/** A closed fenced block. Offsets are UTF-16 offsets in the editor body. */
+export declare function codeBlockAt(body: string, position: number): {
+    start: number;
+    end: number;
+    topLevel: boolean;
+    meta: string;
+    from: number;
+    to: number;
+    language: string;
+    code: string;
+    indent: string;
+    eol: string;
+    marker: string;
+    offsets: number[];
+};
+/** Keep inline content as standard Markdown, including escapes and nested emphasis. */
+export declare const inlineToText: (nodes: PhrasingContent[]) => string;
+export declare const listItems: (n: MdList, convert?: (nodes: RootContent[]) => Block[]) => ListItem[];
+/** Links inside callouts are authored Markdown; other code fences remain opaque. */
+export declare const contentLinks: (root: Root) => Link[];

package/dist/core/markdown.js

@@ -0,0 +1,154 @@
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+import { visit } from "unist-util-visit";
+import { parseFigureLink } from "./file-embed.js";
+import { parseDocLink } from "./routing.js";
+import { parseTermReference, termFileUrl } from "./term-reference.js";
+const processor = unified().use(remarkParse).use(remarkFrontmatter).use(remarkGfm);
+const inlinePrinter = unified().use(remarkGfm).use(remarkStringify);
+export const parseMdast = (raw) => processor.parse(raw);
+/** File previews occupy whole paragraphs; prose, lists and tables keep their inline layout. */
+export const standaloneImages = (node) => node.type === "paragraph" &&
+    node.children.every((child) => child.type === "image" || (child.type === "text" && !child.value.trim()))
+    ? node.children.filter((child) => child.type === "image")
+    : [];
+export const embeddedImages = (root) => {
+    const images = [];
+    visit(root, "paragraph", (node, _index, parent) => {
+        if (parent?.type === "root" || parent?.type === "blockquote")
+            images.push(...standaloneImages(node));
+    });
+    return images;
+};
+export const offsetAt = (body, line, column) => body
+    .split("\n")
+    .slice(0, line - 1)
+    .reduce((offset, text) => offset + text.length + 1, 0) +
+    column -
+    1;
+/** A closed fenced block. Offsets are UTF-16 offsets in the editor body. */
+export function codeBlockAt(body, position) {
+    if (!Number.isInteger(position) || position < 0 || position > body.length) {
+        throw new Error("Invalid cursor position");
+    }
+    const tree = parseMdast(body);
+    let block;
+    visit(tree, (node, _index, parent) => {
+        if (node.type !== "code")
+            return;
+        const start = node.position
+            ? offsetAt(body, node.position.start.line, node.position.start.column)
+            : undefined;
+        const end = node.position
+            ? offsetAt(body, node.position.end.line, node.position.end.column)
+            : undefined;
+        if (start == null || end == null || position < start || position > end)
+            return;
+        const raw = body.slice(start, end);
+        const opening = /^( {0,3})(`{3,}|~{3,})[^\r\n]*\r?\n/.exec(raw);
+        if (!opening?.[2])
+            throw new Error("Select a fenced code block");
+        const closing = /(?:^|\n)([ \t>]*)(`{3,}|~{3,})[ \t]*$/.exec(raw);
+        if (!closing?.[2] ||
+            closing[2][0] !== opening[2][0] ||
+            closing[2].length < opening[2].length)
+            throw new Error("Close the code fence before running a tool");
+        const from = start + opening[0].length;
+        const to = start + closing.index + (raw[closing.index] === "\n" ? 1 : 0);
+        if (to < from)
+            throw new Error("Invalid code fence");
+        const offsets = [];
+        let offset = from;
+        const lines = body.slice(from, to).split(/\r?\n/);
+        lines.pop();
+        const values = node.value.replaceAll("\r\n", "\n").split("\n");
+        for (const [index, line] of lines.entries()) {
+            const value = values[index] ?? "";
+            if (!line.endsWith(value))
+                throw new Error("Unsupported code indentation");
+            offsets.push(offset + line.length - value.length);
+            offset += line.length + (body[offset + line.length] === "\r" ? 2 : 1);
+        }
+        const code = node.value.replaceAll("\r\n", "\n");
+        if (!offsets.length)
+            offsets.push(from);
+        block = {
+            start,
+            end,
+            topLevel: parent?.type === "root",
+            meta: node.meta ?? "",
+            from,
+            to,
+            language: node.lang ?? "",
+            code,
+            indent: closing[1] ?? "",
+            eol: opening[0].endsWith("\r\n") ? "\r\n" : "\n",
+            marker: opening[2],
+            offsets,
+        };
+    });
+    if (!block)
+        throw new Error("Place the cursor inside a fenced code block");
+    return block;
+}
+/** Keep inline content as standard Markdown, including escapes and nested emphasis. */
+export const inlineToText = (nodes) => {
+    const root = {
+        type: "root",
+        children: [{ type: "paragraph", children: structuredClone(nodes) }],
+    };
+    visit(root, "link", (node) => {
+        try {
+            const file = parseTermReference(node.url);
+            if (file)
+                node.url = termFileUrl(file);
+            const ref = parseDocLink(node.url) ?? parseFigureLink(node.url);
+            if (ref)
+                node.url =
+                    termFileUrl(ref.file) +
+                        (ref.fragment ? `#${encodeURIComponent(ref.fragment)}` : "");
+        }
+        catch {
+            /* Reported by validation. */
+        }
+    });
+    return inlinePrinter.stringify(root).replace(/\n$/, "");
+};
+export const listItems = (n, convert) => n.children.map((li) => {
+    if (convert && li.children.some((child) => child.type === "blockquote"))
+        return { blocks: convert(li.children) };
+    const text = li.children
+        .filter((c) => c.type === "paragraph")
+        .map((c) => inlineToText(c.children))
+        .join("");
+    const nested = li.children.filter((c) => c.type === "list");
+    if (nested.length === 0) {
+        return text;
+    }
+    return {
+        text,
+        children: nested.flatMap((c) => listItems(c, convert)),
+        ...(nested[0]?.ordered ? { ordered: true } : {}),
+    };
+});
+/** Links inside callouts are authored Markdown; other code fences remain opaque. */
+export const contentLinks = (root) => {
+    const links = [];
+    visit(root, (node) => {
+        if (node.type === "link")
+            links.push(node);
+        if (node.type === "code" && node.lang === "callouth") {
+            for (const link of contentLinks(parseMdast(node.value))) {
+                if (link.position) {
+                    link.position.start.line += node.position?.start.line ?? 0;
+                    link.position.end.line += node.position?.start.line ?? 0;
+                }
+                links.push(link);
+            }
+        }
+    });
+    return links;
+};

package/dist/core/previewers.d.ts

@@ -0,0 +1,37 @@
+export declare const PREVIEWERS: readonly [{
+    readonly id: "table";
+    readonly label: "Table";
+    readonly extensions: readonly ["csv", "tsv"];
+}, {
+    readonly id: "image";
+    readonly label: "Image";
+    readonly extensions: readonly ["png", "jpg", "jpeg", "webp", "gif", "svg"];
+}, {
+    readonly id: "html";
+    readonly label: "HTML";
+    readonly extensions: readonly ["html", "htm"];
+}, {
+    readonly id: "markdown";
+    readonly label: "Markdown";
+    readonly extensions: readonly ["md", "markdown"];
+}, {
+    readonly id: "code";
+    readonly label: "Code";
+    readonly extensions: readonly ["txt", "log", "json", "yaml", "yml", "toml", "xml", "css", "js", "jsx", "ts", "tsx", "mjs", "cjs", "py", "rs", "go", "java", "c", "h", "cpp", "hpp", "cs", "rb", "php", "swift", "kt", "sh", "bash", "ps1", "sql", "tdl"];
+}, {
+    readonly id: "video";
+    readonly label: "Video";
+    readonly extensions: readonly ["mp4", "webm"];
+}];
+export type PreviewerId = (typeof PREVIEWERS)[number]["id"];
+export interface PreviewSettings {
+    domains: string[];
+}
+export declare const defaultPreviewSettings: () => PreviewSettings;
+/** Exact DNS names only: no schemes, credentials, ports, wildcard or implicit subdomains. */
+export declare const normalizePreviewDomain: (input: string) => string;
+/** Application-owned policy; document sources cannot grant network access. */
+export declare const parsePreviewSettings: (input: unknown) => PreviewSettings;
+export declare const allowedPreviewUrl: (source: string, domains: readonly string[]) => URL;
+/** Selects a registered previewer only; reading files and executing content are separate. */
+export declare const resolvePreviewer: (source: string, settings?: PreviewSettings) => PreviewerId | undefined;

package/dist/core/previewers.js

@@ -0,0 +1,103 @@
+import { parseFileReference } from "./textfile.js";
+export const PREVIEWERS = [
+    { id: "table", label: "Table", extensions: ["csv", "tsv"] },
+    { id: "image", label: "Image", extensions: ["png", "jpg", "jpeg", "webp", "gif", "svg"] },
+    { id: "html", label: "HTML", extensions: ["html", "htm"] },
+    { id: "markdown", label: "Markdown", extensions: ["md", "markdown"] },
+    {
+        id: "code",
+        label: "Code",
+        extensions: [
+            "txt",
+            "log",
+            "json",
+            "yaml",
+            "yml",
+            "toml",
+            "xml",
+            "css",
+            "js",
+            "jsx",
+            "ts",
+            "tsx",
+            "mjs",
+            "cjs",
+            "py",
+            "rs",
+            "go",
+            "java",
+            "c",
+            "h",
+            "cpp",
+            "hpp",
+            "cs",
+            "rb",
+            "php",
+            "swift",
+            "kt",
+            "sh",
+            "bash",
+            "ps1",
+            "sql",
+            "tdl",
+        ],
+    },
+    { id: "video", label: "Video", extensions: ["mp4", "webm"] },
+];
+export const defaultPreviewSettings = () => ({
+    domains: [],
+});
+/** Exact DNS names only: no schemes, credentials, ports, wildcard or implicit subdomains. */
+export const normalizePreviewDomain = (input) => {
+    const domain = input.trim().toLowerCase();
+    if (domain.length > 253 ||
+        !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(domain) ||
+        /\.(?:localhost|local|internal|invalid|test)$/.test(domain))
+        throw new Error(`Invalid public domain: ${input}`);
+    return domain;
+};
+/** Application-owned policy; document sources cannot grant network access. */
+export const parsePreviewSettings = (input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("previews must be an object");
+    const value = input;
+    for (const key of Object.keys(value))
+        if (key !== "domains")
+            throw new Error(`Unknown previews field: ${key}`);
+    const settings = defaultPreviewSettings();
+    if (value.domains !== undefined) {
+        if (!Array.isArray(value.domains) || value.domains.some((d) => typeof d !== "string"))
+            throw new Error("previews.domains must be a list of domains");
+        settings.domains = value.domains.map(normalizePreviewDomain);
+        if (new Set(settings.domains).size !== settings.domains.length)
+            throw new Error("Duplicate allowed domain");
+    }
+    return settings;
+};
+export const allowedPreviewUrl = (source, domains) => {
+    const url = new URL(source);
+    if (url.protocol !== "https:" ||
+        url.username ||
+        url.password ||
+        url.port ||
+        /[\\\s]/.test(source))
+        throw new Error("External previews require an HTTPS URL without credentials or a custom port");
+    if (!domains.includes(url.hostname))
+        throw new Error(`Domain is not allowed: ${url.hostname}`);
+    return url;
+};
+/** Selects a registered previewer only; reading files and executing content are separate. */
+export const resolvePreviewer = (source, settings = defaultPreviewSettings()) => {
+    let path;
+    try {
+        path =
+            /^[a-z][a-z\d+.-]*:/i.test(source) || source.startsWith("//")
+                ? decodeURIComponent(allowedPreviewUrl(source, settings.domains).pathname)
+                : parseFileReference(source).file;
+    }
+    catch {
+        return undefined;
+    }
+    const name = path.split("/").at(-1)?.toLowerCase() ?? "";
+    return PREVIEWERS.find((previewer) => previewer.extensions.some((extension) => name.endsWith(`.${extension}`)))?.id;
+};

package/dist/core/routing.d.ts

@@ -0,0 +1,20 @@
+import type { CompiledDoc } from "./content-types.js";
+/** The minimal doc reference routing needs (a shape CompiledDoc satisfies). */
+export type DocRef = Pick<CompiledDoc, "id" | "parent">;
+/** Parse `<docId>` (leading/trailing `/` are ignored). undefined if the shape differs. */
+export declare const parseRoutePath: (path: string) => string | undefined;
+/** Document links use paths relative to the docs root and optional heading fragments. */
+export declare const parseDocLink: (url: string) => {
+    file: string;
+    fragment: string;
+} | undefined;
+/** Docs directly under parent (keeps input order = manifest order). parent omitted = top level. */
+export declare const childrenOf: <D extends DocRef>(docs: readonly D[], parent?: string) => D[];
+/** Ancestors (ordered top level → parent, excluding self). For breadcrumbs. */
+export declare const ancestorsOf: <D extends DocRef>(docs: readonly D[], id: string) => D[];
+/** DOM anchor id for a heading — namespaced by doc id. */
+export declare const headingAnchor: (docId: string, slug: string) => string;
+/** Canonical page URL: manifest ancestors form the path; headings use a separate fragment. */
+export declare const docPath: (docs: readonly DocRef[], id: string) => string;
+/** Resolve only the complete hierarchy path; no legacy single-id aliases. */
+export declare const resolveDocPath: (docs: readonly DocRef[], path: string) => string | undefined;

package/dist/core/routing.js

@@ -0,0 +1,64 @@
+// SoT for URL / id resolution logic (browser-safe, no node dependencies). Consumers resolve docs
+// through here and never build paths themselves — a consumer is a display-only wrapper, and this
+// package owns routing.
+//
+// Page URLs follow the manifest hierarchy; heading fragments stay separate.
+// Body links reference source files; page URLs use the manifest hierarchy.
+import { isDocId } from "./content-metadata.js";
+import { localFile } from "./files.js";
+import { parseFileReference } from "./textfile.js";
+/** Parse `<docId>` (leading/trailing `/` are ignored). undefined if the shape differs. */
+export const parseRoutePath = (path) => {
+    const seg = path.split("/").filter((s) => s !== "");
+    const [id] = seg;
+    return id != null && seg.length === 1 && isDocId(id) ? id : undefined;
+};
+/** Document links use paths relative to the docs root and optional heading fragments. */
+export const parseDocLink = (url) => {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(url))
+        return undefined;
+    const path = url.split(/[?#]/)[0] ?? "";
+    let decoded;
+    try {
+        decoded = decodeURIComponent(path);
+    }
+    catch {
+        throw new Error("Invalid file link encoding");
+    }
+    if (!decoded.toLowerCase().endsWith(".md"))
+        return undefined;
+    const ref = parseFileReference(url);
+    const file = ref.file.replace(/^(\.\/)+/, "");
+    if (!localFile(file))
+        throw new Error("Document links require a file inside the docs root");
+    return { file, fragment: ref.range?.slice(1) ?? "" };
+};
+/** Docs directly under parent (keeps input order = manifest order). parent omitted = top level. */
+export const childrenOf = (docs, parent) => docs.filter((d) => d.parent === parent);
+/** Ancestors (ordered top level → parent, excluding self). For breadcrumbs. */
+export const ancestorsOf = (docs, id) => {
+    const byId = new Map(docs.map((d) => [d.id, d]));
+    const out = [];
+    const seen = new Set([id]);
+    for (let p = byId.get(id)?.parent; p != null && !seen.has(p); p = byId.get(p)?.parent) {
+        seen.add(p);
+        const d = byId.get(p);
+        if (!d) {
+            break;
+        }
+        out.unshift(d);
+    }
+    return out;
+};
+/** DOM anchor id for a heading — namespaced by doc id. */
+export const headingAnchor = (docId, slug) => `${docId}__${slug}`;
+/** Canonical page URL: manifest ancestors form the path; headings use a separate fragment. */
+export const docPath = (docs, id) => `/${[...ancestorsOf(docs, id).map((doc) => doc.id), id].join("/")}`;
+/** Resolve only the complete hierarchy path; no legacy single-id aliases. */
+export const resolveDocPath = (docs, path) => {
+    const parts = path.split("/").filter(Boolean);
+    const id = parts.at(-1);
+    if (!id || !parts.every(isDocId) || !docs.some((doc) => doc.id === id))
+        return undefined;
+    return docPath(docs, id) === path ? id : undefined;
+};

package/dist/core/schema-comments.d.ts

@@ -0,0 +1,14 @@
+/** Replaces schema DSL comments with whitespace, preserving line numbers and edit offsets. */
+export declare const scanSchemaComments: (source: string) => {
+    source: string;
+    comments: {
+        from: number;
+        to: number;
+        kind: "line" | "block";
+        closed: boolean;
+    }[];
+    errors: {
+        line: number;
+        message: string;
+    }[];
+};

package/dist/core/schema-comments.js

@@ -0,0 +1,52 @@
+/** Replaces schema DSL comments with whitespace, preserving line numbers and edit offsets. */
+export const scanSchemaComments = (source) => {
+    const comments = [];
+    const errors = [];
+    let quoted = false;
+    let line = 0;
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i];
+        if (char === "\n") {
+            line++;
+            quoted = false;
+            continue;
+        }
+        if (quoted) {
+            if (char === "\\" && source[i + 1] !== "\n")
+                i++;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+            continue;
+        }
+        if (char !== "/")
+            continue;
+        if (source[i + 1] === "/") {
+            const end = source.indexOf("\n", i + 2);
+            const to = end < 0 ? source.length : end;
+            comments.push({ from: i, to, kind: "line", closed: end >= 0 });
+            i = to - 1;
+        }
+        else if (source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            const to = end < 0 ? source.length : end + 2;
+            comments.push({ from: i, to, kind: "block", closed: end >= 0 });
+            if (end < 0)
+                errors.push({ line, message: "/* comment is not closed — */ is required" });
+            line += source.slice(i, to).split("\n").length - 1;
+            i = to - 1;
+        }
+    }
+    const chunks = [];
+    let from = 0;
+    for (const comment of comments) {
+        chunks.push(source.slice(from, comment.from));
+        chunks.push(source.slice(comment.from, comment.to).replace(/[^\r\n]/g, " "));
+        from = comment.to;
+    }
+    chunks.push(source.slice(from));
+    return { source: chunks.join(""), comments, errors };
+};

package/dist/core/schema-graph-flow.d.ts

@@ -0,0 +1,9 @@
+import { type JSX } from "react";
+import { type SchemaGraphClientData } from "./schema-graph.js";
+export interface SchemaGraphFlowProps {
+    data: SchemaGraphClientData;
+    /** Height in normal view (default = sized to content, max 62vh). */
+    height?: number | string;
+}
+/** Interactive UI for the schema graph (React Flow). Pass the static SVG's payload as-is. */
+export declare const SchemaGraphFlow: (props: SchemaGraphFlowProps) => JSX.Element;