@wgtechlabs/mdd-engine 0.1.0 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@ The headless Markdown documentation compiler behind mdd. Give it a local project
 
 Built with TypeScript and Bun. Runs on Node.js 22, 24, and 26 without Bun. The default is the latest Node LTS, currently pinned to **24.21.0**.
 
-> Initial implementation. Publishing to npm and GitHub Packages is configured for eligible pushes to `main`. Verify the first release before using registry installation instructions. See [releasing](docs/RELEASING.md).
+> Build Flow's default channels publish development, PR, and manual preview packages alongside regular releases to npm and GitHub Packages. See [build channels and releasing](docs/RELEASING.md).
 
 ## A documentation project
 
@@ -38,7 +38,9 @@ All settings are optional. Custom paths are relative to `mdd/config.json` and mu
 
 ## Compile without a website
 
-After installing a locally packed copy of `@wgtechlabs/mdd-engine` in your Node project:
+Install the regular package with `bun add @wgtechlabs/mdd-engine`. After a successful preview publication, use `bun add @wgtechlabs/mdd-engine@dev` for development builds or `bun add @wgtechlabs/mdd-engine@pr` for PRs targeting `dev`. Preview tags track the most recently published package in their channel; install an exact version to test a particular PR. You can also install a locally packed copy.
+
+In your Node project:
 
 ```js
 import { compileProject } from '@wgtechlabs/mdd-engine';
@@ -59,6 +61,8 @@ if (!result.site) {
 
 `site` is absent whenever authoring errors exist. Diagnostics contain a stable code, severity, message, and source location where available. Unexpected filesystem failures reject the promise with context. Identical inputs produce identical output.
 
+Excessive Markdown nesting that exceeds the runtime's call stack produces a `CONTENT_TOO_DEEP` diagnostic identifying the source file.
+
 The result includes:
 
 - `pages`: source, route, public URL, title, description, article HTML, readable Markdown, headings, and navigation metadata.

package/dist/index.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { resolveLinks } from "./links.js";
-import { parseDocument, renderDocument } from "./markdown.js";
+import { parseDocument, renderDocument, } from "./markdown.js";
 import { loadProject, relativeSource } from "./project.js";
 import { navigationFor, normalizeBasePath, publicUrl, routeFor, } from "./routes.js";
 const reserved = new Set([
@@ -13,6 +13,18 @@ const reserved = new Set([
     "robots.txt",
     "404.html",
 ]);
+function nestingDiagnostic(error, file) {
+    // V8 reports this error for excessive nesting in both parsing and rendering.
+    if (!(error instanceof RangeError) ||
+        error.message !== "Maximum call stack size exceeded")
+        throw error;
+    return {
+        severity: "error",
+        code: "CONTENT_TOO_DEEP",
+        message: "Markdown nesting is too deep; reduce nested blocks or formatting.",
+        file,
+    };
+}
 /** Compile a local checkout; never fetch repositories, execute author code, or emit files. */
 export async function compileProject(options) {
     const diagnostics = [];
@@ -58,7 +70,15 @@ export async function compileProject(options) {
                 file: source,
             });
         routes.set(key, source);
-        const document = parseDocument(await readFile(file, "utf8"), source, diagnostics);
+        const text = await readFile(file, "utf8");
+        let document;
+        try {
+            document = parseDocument(text, source, diagnostics);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, source));
+            return { diagnostics };
+        }
         sources.push({ file, relative, route, document });
     }
     const assets = await resolveLinks(sources, project, basePath, diagnostics);
@@ -67,7 +87,14 @@ export async function compileProject(options) {
     const pages = [];
     for (const source of sources) {
         const { document } = source;
-        const rendered = await renderDocument(document);
+        let rendered;
+        try {
+            rendered = await renderDocument(document);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, relativeSource(project.root, source.file)));
+            return { diagnostics };
+        }
         pages.push({
             source: relativeSource(project.root, source.file),
             route: source.route,

package/dist/links.js

@@ -60,8 +60,10 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                     throw new AuthoringError("PATH_ESCAPE", "Local links must stay inside the content root");
                 let target = !decoded ? page : byFile.get(targetFile);
                 const extension = path.extname(decoded).toLowerCase();
-                let assetExists = false;
+                let asset = decoded.endsWith("/") ? undefined : assets.get(targetFile);
+                let assetExists = asset !== undefined;
                 if (!target &&
+                    !assetExists &&
                     !decoded.endsWith("/") &&
                     assetExtensions.has(extension)) {
                     try {
@@ -106,21 +108,23 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                 if (isImage && [".pdf", ".txt"].includes(extension)) {
                     throw new AuthoringError("INVALID_IMAGE", "Images must reference a supported raster image");
                 }
-                if (!assetExists)
-                    await safeFile(project.contentsRoot, targetFile);
-                const source = relativeSource(project.root, targetFile);
-                const destination = `_assets/${relativeSource(project.contentsRoot, targetFile)}`;
-                const key = destination.normalize("NFC").toLowerCase();
-                const existing = destinations.get(key);
-                if (existing && existing !== source)
-                    throw new AuthoringError("ASSET_COLLISION", `Asset output collides with ${existing}`);
-                destinations.set(key, source);
-                const asset = {
-                    source,
-                    destination,
-                    url: publicUrl(basePath, encodePath(destination)),
-                };
-                assets.set(source, asset);
+                if (!asset) {
+                    if (!assetExists)
+                        await safeFile(project.contentsRoot, targetFile);
+                    const source = relativeSource(project.root, targetFile);
+                    const destination = `_assets/${relativeSource(project.contentsRoot, targetFile)}`;
+                    const key = destination.normalize("NFC").toLowerCase();
+                    const existing = destinations.get(key);
+                    if (existing && existing !== source)
+                        throw new AuthoringError("ASSET_COLLISION", `Asset output collides with ${existing}`);
+                    destinations.set(key, source);
+                    asset = {
+                        source,
+                        destination,
+                        url: publicUrl(basePath, encodePath(destination)),
+                    };
+                    assets.set(targetFile, asset);
+                }
                 node.url =
                     asset.url + query + (hash ? `#${encodeURIComponent(hash)}` : "");
             }
@@ -139,15 +143,6 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                         message: `Malformed URL encoding in '${url}'`,
                         ...location,
                     });
-                else if (error instanceof Error &&
-                    "code" in error &&
-                    error.code === "ENOENT")
-                    diagnostics.push({
-                        severity: "error",
-                        code: "MISSING_ASSET",
-                        message: `Asset not found: '${url}'`,
-                        ...location,
-                    });
                 else
                     throw new Error(`Unable to resolve '${url}' in ${location.file}`, {
                         cause: error,

package/dist/markdown.js

@@ -160,6 +160,10 @@ export function parseDocument(source, file, diagnostics) {
     visit(tree, (node, index, parent) => {
         if (node.type === "html") {
             report("RAW_HTML", "Raw HTML is not supported; use Markdown or an mdd component.", node);
+            if (parent && index !== undefined) {
+                parent.children.splice(index, 1);
+                return [SKIP, index];
+            }
         }
         if ((node.type === "link" ||
             node.type === "image" ||
@@ -238,17 +242,8 @@ export function parseDocument(source, file, diagnostics) {
 }
 export async function renderDocument(document) {
     const htmlTree = await htmlRenderer.run(document.tree);
-    const markdownTree = structuredClone(document.tree);
-    visit(markdownTree, (node, index, parent) => {
-        if ((node.type === "html" || node.type === "yaml") &&
-            parent &&
-            index !== undefined) {
-            parent.children.splice(index, 1);
-            return [SKIP, index];
-        }
-    });
     return {
         html: String(htmlRenderer.stringify(htmlTree)),
-        markdown: String(markdownRenderer.stringify(markdownTree)),
+        markdown: String(markdownRenderer.stringify(document.tree)),
     };
 }

package/dist/project.d.ts

@@ -1,9 +1,7 @@
 import type { CompileOptions, Diagnostic, Theme } from "./types.js";
 export interface Project {
     root: string;
-    mddRoot: string;
     contentsRoot: string;
-    themesRoot: string;
     title?: string;
     theme: Theme;
     files: string[];

package/dist/project.js

@@ -236,7 +236,7 @@ export async function loadProject(options, diagnostics) {
         }
         if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             return undefined;
-        return { root, mddRoot, contentsRoot, themesRoot, title, theme, files };
+        return { root, contentsRoot, title, theme, files };
     }
     catch (error) {
         if (!(error instanceof AuthoringError))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/mdd-engine",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Headless Markdown documentation compiler for mdd",
   "type": "module",
   "license": "MIT",