@dogsbay/format-dogsbay-md 0.2.0-beta.124 → 0.2.0-beta.125

package/dist/browser.d.ts

@@ -12,6 +12,7 @@
  * module load and would drag `node:fs` back into this graph.
  */
 export { dogsbayMdToTree, parseInline, type ParseResult, type ParseOptions } from "./parse.js";
+export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export type { SerializeOptions } from "./types.js";
 export { inlineToDogsbayMd } from "./inline.js";

package/dist/browser.js

@@ -12,6 +12,7 @@
  * module load and would drag `node:fs` back into this graph.
  */
 export { dogsbayMdToTree, parseInline } from "./parse.js";
+export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 export { treeToDogsbayMd, nodeToDogsbayMd } from "./serialize.js";
 export { inlineToDogsbayMd } from "./inline.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker, } from "./code-regions.js";

package/dist/diagnostics.d.ts

@@ -0,0 +1,39 @@
+export interface ParseDiagnostic {
+    /** 1-based line in the source (front matter counted). */
+    line: number;
+    /** Stable kind, for filtering. */
+    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "bad-attributes";
+    message: string;
+}
+/**
+ * Whether a source line closes a container opened with `colons` colons. The
+ * line may sit in a blockquote or a list item: its `>` markers and
+ * indentation come first.
+ */
+export declare const closesContainer: (line: string | undefined, colons: number) => boolean;
+/** The inline directives the parser turns into nodes (parse.ts inlineDirectiveToNode); any other name stays literal text. */
+export declare const KNOWN_INLINE_DIRECTIVES: ReadonlySet<string>;
+type Token = {
+    type: string;
+    tag: string;
+    info: string;
+    markup: string;
+    content: string;
+    map?: [number, number] | null;
+    children: Token[] | null;
+    meta: {
+        unclosed?: boolean;
+    } | null;
+};
+/**
+ * Why an attribute block `{…}` cannot be read, or undefined when it can.
+ * parseAttrs never fails: it reads what it can and drops the rest, so a
+ * missing brace or an unterminated quote loses attributes silently.
+ */
+export declare function attributeProblem(block: string): string | undefined;
+/**
+ * Diagnostics for a token stream. `lines` is the parsed text split at `\n`;
+ * `lineOf` maps a 0-based line of it to a 1-based source line.
+ */
+export declare function collectDiagnostics(tokens: Token[], lines: string[], lineOf: (line0: number) => number | undefined): ParseDiagnostic[];
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,117 @@
+/**
+ * Problems in Dogsbay MD source that the parser recovers from without a word
+ * (ParseOptions.diagnostics): each would otherwise reach the page as literal
+ * text, a plain box, or a block that swallows the rest of the document.
+ *
+ * Read from markdown-it's tokens, so they describe what the parser actually
+ * did, not a second grammar's guess. A `::leaf` with an unknown name is not
+ * here: the parser passes any leaf through as a node of that type, and only a
+ * renderer knows whether it can draw it (render-html reports the ones it can't).
+ */
+import { GENERIC_CONTAINER } from "./plugin-containers.js";
+/**
+ * Whether a source line closes a container opened with `colons` colons. The
+ * line may sit in a blockquote or a list item: its `>` markers and
+ * indentation come first.
+ */
+export const closesContainer = (line, colons) => line !== undefined && new RegExp(`^:{${colons},}\\s*$`).test(line.replace(/^[\s>]*/, ""));
+/** The inline directives the parser turns into nodes (parse.ts inlineDirectiveToNode); any other name stays literal text. */
+export const KNOWN_INLINE_DIRECTIVES = new Set(["kbd", "icon", "math", "mark", "highlight", "button", "badge"]);
+/**
+ * Why an attribute block `{…}` cannot be read, or undefined when it can.
+ * parseAttrs never fails: it reads what it can and drops the rest, so a
+ * missing brace or an unterminated quote loses attributes silently.
+ */
+export function attributeProblem(block) {
+    if (!block.trimEnd().endsWith("}"))
+        return "has no closing }";
+    const inner = block.trim().slice(1, -1);
+    let quote;
+    for (const c of inner) {
+        if (quote) {
+            if (c === quote)
+                quote = undefined;
+        }
+        else if (c === '"' || c === "'")
+            quote = c;
+    }
+    if (quote)
+        return `has an unterminated ${quote === '"' ? "double" : "single"} quote`;
+    return undefined;
+}
+/**
+ * Diagnostics for a token stream. `lines` is the parsed text split at `\n`;
+ * `lineOf` maps a 0-based line of it to a 1-based source line.
+ */
+export function collectDiagnostics(tokens, lines, lineOf) {
+    const out = [];
+    const add = (line0, code, message) => {
+        const line = line0 === undefined ? undefined : lineOf(line0);
+        if (line !== undefined)
+            out.push({ line, code, message });
+    };
+    const walk = (list) => {
+        for (const tok of list) {
+            const open = /^container_(.+)_open$/.exec(tok.type);
+            if (open && tok.map) {
+                const generic = open[1] === GENERIC_CONTAINER;
+                const info = (tok.info ?? "").trim();
+                const name = generic ? (/^[A-Za-z][\w-]*/.exec(info)?.[0] ?? info) : open[1];
+                const colons = (tok.markup ?? ":::").length;
+                const closed = closesContainer(lines[tok.map[1]], colons);
+                if (!closed) {
+                    add(tok.map[0], "unclosed-container", generic
+                        ? `:::${name} is never closed — it is shown as text (close it with a line of ${":".repeat(colons)})`
+                        : `:::${name} is never closed — it takes in everything after it, to the end of the page or of the block it sits in (close it with a line of ${":".repeat(colons)})`);
+                }
+                else if (generic) {
+                    add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`);
+                }
+                const rest = info.slice(name.length).trim();
+                if (rest.startsWith("{")) {
+                    const problem = attributeProblem(rest);
+                    if (problem)
+                        add(tok.map[0], "bad-attributes", `the attributes of :::${name} ${problem} — they are ignored`);
+                }
+            }
+            // A `:::` line markdown-it-container did not take as a closer: the container it was
+            // meant to close ended earlier (an inner block of the same fence closed it), or there is none
+            if (tok.type === "inline" && tok.map) {
+                (tok.content ?? "").split("\n").forEach((l, k) => {
+                    if (/^\s*:{3,}\s*$/.test(l)) {
+                        add(tok.map[0] + k, "stray-closer", `stray \`${l.trim()}\` — it closes nothing and is shown as text; to nest a directive, give the outer one more colons (::::steps around :::tabs)`);
+                    }
+                });
+            }
+            if (tok.type === "inline" && tok.map && tok.children) {
+                const text = tok.content ?? "";
+                let from = 0;
+                for (const child of tok.children) {
+                    if (child.type !== "dogsbay_inline_directive_open" && child.type !== "dogsbay_leaf_directive")
+                        continue;
+                    if (KNOWN_INLINE_DIRECTIVES.has(child.tag))
+                        continue;
+                    const form = child.type === "dogsbay_leaf_directive" ? `::${child.tag}` : `:${child.tag}[`;
+                    const at = text.indexOf(form, from);
+                    from = at >= 0 ? at + form.length : from;
+                    const offset = at >= 0 ? (text.slice(0, at).match(/\n/g) ?? []).length : 0;
+                    const shown = child.type === "dogsbay_leaf_directive" ? `::${child.tag}` : `:${child.tag}[…]`;
+                    add(tok.map[0] + offset, "unknown-inline", `${shown} is not a known inline directive — it is shown as text`);
+                }
+            }
+            // A heading's attribute block that markdown-it-attrs could not read stays in its text
+            if (tok.type === "heading_open" && tok.map) {
+                const inline = list[list.indexOf(tok) + 1];
+                // markdown-it-attrs takes a block it reads out of the text tokens (not out of `content`)
+                const last = [...(inline?.children ?? [])].reverse().find((c) => c.type === "text");
+                const tail = /\{\s*(?:[#.][^{}]*|[\w-]+\s*=[^{}]*)\}?\s*$/.exec(last?.content ?? "");
+                if (tail) {
+                    const problem = attributeProblem(tail[0]) ?? "could not be read";
+                    add(tok.map[0], "bad-attributes", `the heading's attribute block ${problem} — it is shown as text`);
+                }
+            }
+        }
+    };
+    walk(tokens);
+    return out.sort((a, b) => a.line - b.line);
+}

package/dist/directive-preserve.d.ts

@@ -11,6 +11,12 @@ export interface DirectiveSpan {
 export interface ProtectResult {
     source: string;
     table: DirectiveSpan[];
+    /**
+     * For each line of `source`, the 0-based line of the input it came from: a
+     * stashed construct that spanned lines is one placeholder line, and an
+     * isolating blank line maps to the line it was inserted before.
+     */
+    lineMap: number[];
 }
 /**
  * Replace directive constructs in prose with placeholders and isolate

package/dist/directive-preserve.js

@@ -72,7 +72,18 @@ export function protectDirectives(source, options = {}) {
     // lines, so markdown-it gives each its own paragraph. Variables stay
     // inline (a lone `{{ x }}` line is inline content, not structure).
     const lines = out.split("\n");
+    // Each placeholder stands for its construct's lines, so the input line of
+    // every output line is the count of line breaks consumed before it
+    const inputLine = [];
+    let at = 0;
+    for (const line of lines) {
+        inputLine.push(at);
+        at += 1;
+        for (const m of line.matchAll(/\uE000(\d+)\uE001/g))
+            at += (table[Number(m[1])]?.raw.match(/\n/g) ?? []).length;
+    }
     const isolated = [];
+    const lineMap = [];
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         const only = line.match(/^\s*\uE000(\d+)\uE001\s*$/);
@@ -82,14 +93,17 @@ export function protectDirectives(source, options = {}) {
             ((options.isolate ?? "all") === "all" || entry.keyword === "include");
         if (isBlockish && isolated.length && isolated[isolated.length - 1].trim() !== "") {
             isolated.push("");
+            lineMap.push(inputLine[i]);
         }
         isolated.push(line);
+        lineMap.push(inputLine[i]);
         if (isBlockish && i + 1 < lines.length && lines[i + 1].trim() !== "") {
             isolated.push("");
+            lineMap.push(inputLine[i + 1]);
         }
     }
     out = isolated.join("\n");
-    return { source: out, table };
+    return { source: out, table, lineMap };
 }
 /** Stash whole `{% raw %}…{% endraw %}` regions found in prose. */
 function stashRawRegions(source, stash) {
@@ -170,29 +184,32 @@ function foldBlocks(nodes, table, nodesFor = "all") {
             continue;
         }
         const entry = table[index];
+        // The node keeps the source line of the paragraph it replaces (ParseOptions.sourceLines)
+        const line = node.meta?.line;
+        const at = (made) => (line === undefined ? made : { ...made, meta: { ...made.meta, line } });
         // resolve-first: only an include becomes a node; the rest is literal text.
         if (nodesFor === "include" && entry.keyword !== "include") {
-            target().push({ type: "paragraph", inline: [{ type: "text", text: entry.raw }] });
+            target().push(at({ type: "paragraph", inline: [{ type: "text", text: entry.raw }] }));
             continue;
         }
         const test = (entry.rest ?? "").trim();
         if (entry.keyword === "if" && test) {
-            stack.push({ node: { type: "conditional", props: { test }, children: [] }, opener: entry });
+            stack.push({ node: at({ type: "conditional", props: { test }, children: [] }), opener: entry });
         }
         else if (entry.keyword === "endif") {
             const open = stack.pop();
             if (open)
                 target().push(open.node);
             else
-                target().push(rawBlock(entry)); // orphan endif — preserved verbatim
+                target().push(at(rawBlock(entry))); // orphan endif — preserved verbatim
         }
         else if (entry.keyword === "elif" || entry.keyword === "else") {
             // Not modeled first-class: preserved as raw chips inside (or beside)
             // the conditional; the serializer emits them in place, byte-exact.
-            target().push(rawBlock(entry));
+            target().push(at(rawBlock(entry)));
         }
         else {
-            target().push(tagToBlock(entry));
+            target().push(at(tagToBlock(entry)));
         }
     }
     // Unclosed conditionals: demote each opener to directive-raw and splice

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { extractHeadings, slugifyHeadingText, type HeadingInfo } from "./heading
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker } from "./code-regions.js";
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
 export type { ParseResult, ParseOptions } from "./parse.js";
+export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export { dogsbayMdToTree, parseInline } from "./parse.js";
 export { extractHeadings, slugifyHeadingText } from "./headings.js";
 export { transformCodeRegions, transformProseLines, transformProseSegments, fenceOpenBefore, createFenceTracker } from "./code-regions.js";
 export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcessedFence, stripInlineMinjaMarkers, stripFenceMinjaMarkers } from "./minja-mask.js";
+export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";

package/dist/parse.d.ts

@@ -1,7 +1,10 @@
 import type { TreeNode, InlineNode } from "@dogsbay/types";
+import { type ParseDiagnostic } from "./diagnostics.js";
 export interface ParseResult {
     tree: TreeNode[];
     frontmatter: Record<string, unknown>;
+    /** With ParseOptions.diagnostics: what the parser recovered from, by line. */
+    diagnostics?: ParseDiagnostic[];
 }
 export interface ParseOptions {
     /** Strip surrounding whitespace from block content. Default: true */
@@ -17,6 +20,19 @@ export interface ParseOptions {
      * plans/editor-directive-model.md.
      */
     directives?: "resolve-first" | "preserve";
+    /**
+     * Put each block node's 1-based line in the source (front matter counted)
+     * on `meta.line`, so a host can map the rendered page back to the source
+     * (render-html writes it as `data-line` when asked). Off by default. Lines
+     * end at `\n` or `\r\n`; a file with lone `\r` line breaks gets none.
+     */
+    sourceLines?: boolean;
+    /**
+     * Report what the parser recovers from silently, with source lines, in
+     * `diagnostics`: an unclosed `:::container`, an unknown `:::name` or inline
+     * `:name[]`, an attribute block it cannot read. Off by default.
+     */
+    diagnostics?: boolean;
 }
 /**
  * Parse Dogsbay Markdown into TreeNode[] plus extracted frontmatter.

package/dist/parse.js

@@ -21,6 +21,7 @@ import { mathPlugin } from "./plugin-math.js";
 import { attrsToProps } from "./parse-attrs.js";
 import { splitFrontmatter } from "./frontmatter.js";
 import { protectDirectives, restoreDirectives } from "./directive-preserve.js";
+import { closesContainer, collectDiagnostics } from "./diagnostics.js";
 import { treeToDogsbayMd } from "./serialize.js";
 /**
  * Parse Dogsbay Markdown into TreeNode[] plus extracted frontmatter.
@@ -52,6 +53,11 @@ export function dogsbayMdToTree(source, options) {
     // resolves them in a preprocessing pass beforehand. Protecting in both modes
     // makes the contract true; the RESTORE below is what differs.
     let directiveTable = null;
+    // Source lines: the line of the full source each line of `content` came from,
+    // through the front matter split and each pre-pass below
+    const wantLines = (options?.sourceLines === true || options?.diagnostics === true) && !/\r(?!\n)/.test(source);
+    const bodyStart = wantLines ? (source.slice(0, source.length - content.length).match(/\n/g) ?? []).length : 0;
+    let lineMap = null;
     const preserveMode = options?.directives === "preserve";
     {
         // resolve-first leaves `{% raw %}` regions alone — see ProtectOptions.
@@ -61,17 +67,33 @@ export function dogsbayMdToTree(source, options) {
         });
         content = protectedResult.source;
         directiveTable = protectedResult.table;
+        if (wantLines)
+            lineMap = protectedResult.lineMap;
     }
     // Pre-pass: lift YAML body forms (e.g. `:::card\n---\n...\n---\n:::`)
     // into a synthetic `__yaml__` attr on the directive opener. Done at
     // the source level because markdown-it would otherwise mangle the
     // YAML — the leading `---` becomes a horizontal rule and the body's
     // newlines collapse into a single inline run. See preprocessYamlBodies.
-    content = preprocessYamlBodies(content);
+    const yamlLifted = preprocessYamlBodies(content);
+    content = yamlLifted.source;
+    const lineOf = lineMap
+        ? (line0) => {
+            const protectedLine = yamlLifted.lineMap[line0];
+            const input = protectedLine === undefined ? undefined : lineMap[protectedLine];
+            return input === undefined ? undefined : bodyStart + input + 1;
+        }
+        : undefined;
     const md = sharedParser();
     const tokens = md.parse(content, {});
     markUnclosedGenericContainers(tokens, content);
-    let tree = foldRelated(tokensToTree(tokens));
+    // Before tokensToTree: it changes nothing these read, but read the parse as markdown-it left it
+    const diagnostics = options?.diagnostics
+        ? collectDiagnostics(tokens, 
+        // markdown-it splits at \r too; a lone-CR file has no line map, so its lines are counted here
+        content.split(/\r\n|\r|\n/), lineOf ?? ((line0) => (source.slice(0, source.length - content.length).match(/\r\n|\r|\n/g) ?? []).length + line0 + 1))
+        : undefined;
+    let tree = foldRelated(tokensToTree(tokens, options?.sourceLines ? lineOf : undefined));
     if (directiveTable) {
         // `preserve` restores every construct as a first-class node. `resolve-first`
         // restores INCLUDES as nodes too — they are transclusions of real content,
@@ -81,7 +103,7 @@ export function dogsbayMdToTree(source, options) {
             nodesFor: preserveMode ? "all" : "include",
         });
     }
-    return { tree, frontmatter };
+    return { tree, frontmatter, ...(diagnostics ? { diagnostics } : {}) };
 }
 // #384 R3: roles whose caption + following list fold into a semantic `related`
 // node (maps to DITA <related-links>). Mirrors CONTAINER_ROLES in
@@ -180,6 +202,7 @@ const YAML_BODY_COMPONENTS = new Set([
 function preprocessYamlBodies(source) {
     const lines = source.split("\n");
     const out = [];
+    const lineMap = [];
     let i = 0;
     while (i < lines.length) {
         const line = lines[i];
@@ -210,14 +233,16 @@ function preprocessYamlBodies(source) {
                     newAttrs = `{__yaml__="${encoded}"}`;
                 }
                 out.push(`${fence}${name}${newAttrs}`);
+                lineMap.push(i);
                 i = j + 1; // skip past the closing `---`
                 continue;
             }
         }
         out.push(line);
+        lineMap.push(i);
         i++;
     }
-    return out.join("\n");
+    return { source: out.join("\n"), lineMap };
 }
 /**
  * Parse a single inline string to InlineNode[] (useful for testing).
@@ -285,20 +310,20 @@ function createParser() {
  * holding the rest of the page, so such an opener is marked and parsed back as text.
  */
 function markUnclosedGenericContainers(tokens, src) {
-    const lines = src.split("\n");
+    // markdown-it's lines: it splits at \r\n, \r and \n
+    const lines = src.split(/\r\n|\r|\n/);
     const open = `container_${GENERIC_CONTAINER}_open`;
     for (const tok of tokens) {
         const map = tok.map;
         if (tok.type !== open || !map)
             continue;
-        const close = lines[map[1]];
-        if (close === undefined || !/^\s*:{3,}\s*$/.test(close))
+        if (!closesContainer(lines[map[1]], (tok.markup ?? ":::").length))
             tok.meta = { ...(tok.meta ?? {}), unclosed: true };
     }
 }
-function tokensToTree(tokens) {
+function tokensToTree(tokens, lineOf) {
     const nodes = [];
-    const ctx = { tokens, i: 0 };
+    const ctx = { tokens, i: 0, ...(lineOf ? { lineOf } : {}) };
     while (ctx.i < ctx.tokens.length) {
         const node = consumeBlock(ctx);
         if (node) {
@@ -316,6 +341,20 @@ function tokensToTree(tokens) {
     return nodes;
 }
 function consumeBlock(ctx) {
+    const tok = ctx.tokens[ctx.i];
+    const result = consumeBlockAt(ctx);
+    // Source lines: every node the block became starts at its first token's line
+    // (nested blocks came through here first and keep their own)
+    const line = ctx.lineOf && tok?.map ? ctx.lineOf(tok.map[0]) : undefined;
+    if (line !== undefined && result) {
+        for (const node of Array.isArray(result) ? result : [result]) {
+            if (node.meta?.line === undefined)
+                node.meta = { ...node.meta, line };
+        }
+    }
+    return result;
+}
+function consumeBlockAt(ctx) {
     const tok = ctx.tokens[ctx.i];
     if (!tok)
         return null;
@@ -581,6 +620,14 @@ function consumeList(ctx, ordered) {
     return node;
 }
 function consumeListItem(ctx) {
+    const open = ctx.tokens[ctx.i];
+    const item = consumeListItemAt(ctx);
+    const line = ctx.lineOf && open?.map ? ctx.lineOf(open.map[0]) : undefined;
+    if (line !== undefined && item.meta?.line === undefined)
+        item.meta = { ...item.meta, line };
+    return item;
+}
+function consumeListItemAt(ctx) {
     ctx.i++; // list_item_open
     const children = [];
     let depth = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.124",
+  "version": "0.2.0-beta.125",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -40,9 +40,9 @@
     "markdown-it-deflist": "^3.0.1",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
-    "@dogsbay/minja": "0.2.0-beta.124",
-    "@dogsbay/serialize-core": "0.2.0-beta.124",
-    "@dogsbay/types": "0.2.0-beta.124"
+    "@dogsbay/minja": "0.2.0-beta.125",
+    "@dogsbay/serialize-core": "0.2.0-beta.125",
+    "@dogsbay/types": "0.2.0-beta.125"
   },
   "license": "MIT",
   "repository": {