@zudojs/docs 1.0.1 → 1.0.3

package/README.md

@@ -2,6 +2,12 @@
 
 Documentation infrastructure with structured document model, registry, validation, navigation, frontmatter parsing, and markdown/JSON generation.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-docs](https://zudojs.oyinlola.site/docs/packages-docs) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-docs.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -46,11 +52,13 @@ const index = generateIndex(registry.getAll()); // SERVER-only docs excluded
 
 ## Features
 
-- Document model with frontmatter (`parseFrontmatter` / `serializeFrontmatter` round-trip safely)
+- Document model with frontmatter (`parseFrontmatter` / `serializeFrontmatter` round-trip safely; `tags` always parses to a string array, and the body keeps its indentation)
 - Document registry and discovery (`DuplicateDocumentError` on duplicate IDs, deep-frozen copies)
 - Navigation tree helpers (breadcrumbs, siblings, previous/next, cycle-safe walkers)
-- Markdown and JSON generation with escaping for untrusted content and `visibility` filtering
-- Document, link and navigation validation with a single `valid` rule (errors only)
+- Markdown and JSON generation with escaping for untrusted content: structured text is HTML-escaped and links are limited to http, https, mailto, tel, ftp and ftps (others are written as plain text)
+- Fail-closed `visibility` filtering: only an unset or exactly `"CLIENT"` visibility reaches a client index
+- `stripMarkdown` and link validation run in linear time on untrusted input
+- Document, link and navigation validation with a single `valid` rule (errors only); `javascript:` and other non-allow-listed link schemes are `UNSAFE_LINK` errors
 - Documentation error classes re-exported from `@zudojs/errors`
 
 ## Use Cases

package/dist/document/documentBuilder.core.js

@@ -7,6 +7,7 @@
 import { DocumentValidationError } from "@zudojs/errors";
 import { deepFreezeClone } from "../utils/utils.freeze.js";
 import { isValidDocumentId } from "../utils/utils.helper.js";
+import { toTagList } from "./documentBuilder.normalize.js";
 /**
  * Creates a documentation document from structured options.
  *
@@ -36,7 +37,7 @@ export function createDocument(options) {
         description: options.description,
         content: options.content,
         category: options.category,
-        tags: options.tags ? [...options.tags] : undefined,
+        tags: toTagList(options.tags),
         version: options.version,
         status: options.status,
         metadata: options.metadata,

package/dist/document/documentBuilder.normalize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Input normalization for `createDocument`.
+ *
+ * @module document/documentBuilder.normalize
+ */
+/**
+ * Copies a tag list. A lone string (from untyped callers or older parsed
+ * frontmatter) becomes a one-item list instead of being spread into
+ * one-character tags.
+ */
+export declare function toTagList(tags: readonly string[] | string | undefined): string[] | undefined;
+//# sourceMappingURL=documentBuilder.normalize.d.ts.map

package/dist/document/documentBuilder.normalize.js

@@ -0,0 +1,18 @@
+/**
+ * Input normalization for `createDocument`.
+ *
+ * @module document/documentBuilder.normalize
+ */
+/**
+ * Copies a tag list. A lone string (from untyped callers or older parsed
+ * frontmatter) becomes a one-item list instead of being spread into
+ * one-character tags.
+ */
+export function toTagList(tags) {
+    if (tags === undefined)
+        return undefined;
+    if (typeof tags === "string")
+        return tags === "" ? [] : [tags];
+    return [...tags];
+}
+//# sourceMappingURL=documentBuilder.normalize.js.map

package/dist/frontmatter/frontmatter.parser.d.ts

@@ -5,7 +5,8 @@
  * and extracts metadata alongside the remaining content.
  *
  * Supported subset:
- * - `key: scalar` (strings, canonical numbers, booleans, null)
+ * - `key: scalar` (strings, lossless numbers, booleans, null)
+ * - `[]` / `{}` as empty collections; `tags` always parses to a string list
  * - single- and double-quoted strings with escapes
  * - `key:` followed by `- item` lines (list of scalars)
  * - one level of nested mapping (`key:` followed by indented `sub: value`)

package/dist/frontmatter/frontmatter.parser.js

@@ -5,7 +5,8 @@
  * and extracts metadata alongside the remaining content.
  *
  * Supported subset:
- * - `key: scalar` (strings, canonical numbers, booleans, null)
+ * - `key: scalar` (strings, lossless numbers, booleans, null)
+ * - `[]` / `{}` as empty collections; `tags` always parses to a string list
  * - single- and double-quoted strings with escapes
  * - `key:` followed by `- item` lines (list of scalars)
  * - one level of nested mapping (`key:` followed by indented `sub: value`)
@@ -15,13 +16,12 @@
  * result object's prototype (`__proto__`, `constructor`, `prototype`)
  * are rejected.
  */
+import { STRING_LIST_KEYS, emptyCollection, losslessNumber, parseInlineList, } from "./frontmatter.values.js";
 const FRONTMATTER_DELIMITER = "---";
 /** Keys that must never be assigned onto a plain object. */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 /** Valid frontmatter key syntax. */
 const KEY_PATTERN = /^[A-Za-z_][\w.-]*$/;
-/** Canonical number: optional sign, no leading zeros, optional fraction. */
-const CANONICAL_NUMBER = /^-?(0|[1-9]\d*)(\.\d+)?$/;
 /**
  * Keys whose values are declared as strings in `FrontmatterMetadata`.
  * Their scalars are never coerced, so `version: 1.0` stays `"1.0"`.
@@ -35,8 +35,6 @@ const STRING_KEYS = new Set([
     "deprecatedMessage",
     "visibility",
 ]);
-/** Keys whose list items are always strings. */
-const STRING_LIST_KEYS = new Set(["tags"]);
 /**
  * Parses YAML-like frontmatter from a markdown string.
  *
@@ -65,11 +63,10 @@ export function parseFrontmatter(raw) {
         return { metadata: Object.freeze({}), content: raw };
     }
     const yamlLines = lines.slice(start + 1, end);
-    const remainingContent = lines
-        .slice(end + 1)
-        .join("\n")
-        .replace(/^\s*\n/, "")
-        .trimStart();
+    // Drop only the one blank separator line that serializeFrontmatter writes.
+    // Trimming more stripped the indentation of a leading code block.
+    const bodyStart = lines[end + 1]?.trim() === "" ? end + 2 : end + 1;
+    const remainingContent = lines.slice(bodyStart).join("\n");
     const metadata = parseYamlLike(yamlLines);
     return { metadata, content: remainingContent };
 }
@@ -91,7 +88,9 @@ function parseYamlLike(lines) {
             result[currentKey] = Object.freeze(currentMap);
         }
         else {
-            result[currentKey] = "";
+            result[currentKey] = STRING_LIST_KEYS.has(currentKey)
+                ? Object.freeze([])
+                : "";
         }
         currentKey = null;
         currentArray = null;
@@ -141,9 +140,12 @@ function parseYamlLike(lines) {
             currentKey = entry.key;
             continue;
         }
-        result[entry.key] = STRING_KEYS.has(entry.key)
-            ? parseStringScalar(entry.value)
-            : parseScalar(entry.value);
+        result[entry.key] = STRING_LIST_KEYS.has(entry.key)
+            ? parseInlineList(entry.value, parseStringScalar)
+            : (emptyCollection(entry.value) ??
+                (STRING_KEYS.has(entry.key)
+                    ? parseStringScalar(entry.value)
+                    : parseScalar(entry.value)));
     }
     flush();
     return Object.freeze({ ...result });
@@ -190,8 +192,8 @@ function stripComment(line) {
  * Parses a scalar YAML value into its appropriate JS type.
  *
  * Quoted strings are unquoted (with escape handling) and never coerced.
- * Only canonical numbers within the safe-integer range become numbers;
- * anything else stays a string.
+ * A numeric literal becomes a number only when the conversion is lossless
+ * (`String(Number(text)) === text`); anything else stays a string.
  */
 function parseScalar(value) {
     if (value.length >= 2) {
@@ -210,13 +212,7 @@ function parseScalar(value) {
         return false;
     if (value === "null" || value === "~")
         return null;
-    if (CANONICAL_NUMBER.test(value)) {
-        const parsed = Number(value);
-        if (Number.isFinite(parsed) && Math.abs(parsed) <= Number.MAX_SAFE_INTEGER) {
-            return parsed;
-        }
-    }
-    return value;
+    return losslessNumber(value) ?? value;
 }
 /** Parses a scalar that must remain a string (unquotes, never coerces). */
 function parseStringScalar(value) {

package/dist/frontmatter/frontmatter.serializer.js

@@ -6,6 +6,7 @@
  * whitespace, or text that looks like a number/boolean/null), so
  * `parseFrontmatter(serializeFrontmatter(m, c))` round-trips `m`.
  */
+import { losslessNumber } from "./frontmatter.values.js";
 const FRONTMATTER_DELIMITER = "---";
 /** Keys that are never written. */
 const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
@@ -26,7 +27,13 @@ export function serializeFrontmatter(metadata, content) {
             continue;
         if (!isSerializableKey(key))
             continue;
-        if (Array.isArray(value)) {
+        if (Array.isArray(value) && value.length === 0) {
+            lines.push(`${key}: []`);
+        }
+        else if (isPlainObject(value) && !hasSerializableEntry(value)) {
+            lines.push(`${key}: {}`);
+        }
+        else if (Array.isArray(value)) {
             lines.push(`${key}:`);
             for (const item of value) {
                 lines.push(`  - ${formatScalar(item)}`);
@@ -90,7 +97,7 @@ function needsQuotes(value) {
         return true;
     if (value === "null" || value === "~")
         return true;
-    if (/^-?(0|[1-9]\d*)(\.\d+)?$/.test(value))
+    if (losslessNumber(value) !== undefined)
         return true;
     return false;
 }
@@ -104,6 +111,10 @@ function quote(value) {
             .replace(/\t/g, "\\t") +
         '"');
 }
+/** Whether a mapping has at least one entry the serializer would write. */
+function hasSerializableEntry(value) {
+    return Object.entries(value).some(([key, entry]) => entry !== undefined && entry !== null && isSerializableKey(key));
+}
 function isSerializableKey(key) {
     return !FORBIDDEN_KEYS.has(key) && KEY_PATTERN.test(key);
 }

package/dist/frontmatter/frontmatter.values.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Value rules shared by the frontmatter parser and serializer.
+ *
+ * - List keys (`tags`) always parse to a string array: `tags: http` is
+ *   `["http"]`, `tags:` and `tags: []` are `[]`, and `tags: [a, b]` is
+ *   `["a", "b"]`. A string here used to reach `createDocument`, which spread
+ *   it into one-character tags.
+ * - `[]` and `{}` are the empty collections, so the serializer can write an
+ *   empty array or object and get it back (they used to come back as `""`).
+ * - A bare numeric literal becomes a number only when `String(Number(text))`
+ *   gives the text back, so the conversion is lossless both ways (`1e+21`
+ *   and `1.5e-7` round-trip; `007` and 20-digit IDs stay strings).
+ */
+/** Keys whose value is always a list of strings. */
+export declare const STRING_LIST_KEYS: ReadonlySet<string>;
+/** The number a literal denotes, when converting it loses nothing. */
+export declare function losslessNumber(text: string): number | undefined;
+/** `[]` or `{}` written as a value: the empty collection it denotes. */
+export declare function emptyCollection(value: string): readonly never[] | Readonly<Record<string, never>> | undefined;
+/**
+ * Parses the inline value of a list key into items. `[a, "b, c"]` is a flow
+ * list; anything else is a single item. Items go through `parseItem`.
+ */
+export declare function parseInlineList(value: string, parseItem: (item: string) => string): readonly string[];
+//# sourceMappingURL=frontmatter.values.d.ts.map

package/dist/frontmatter/frontmatter.values.js

@@ -0,0 +1,70 @@
+/**
+ * Value rules shared by the frontmatter parser and serializer.
+ *
+ * - List keys (`tags`) always parse to a string array: `tags: http` is
+ *   `["http"]`, `tags:` and `tags: []` are `[]`, and `tags: [a, b]` is
+ *   `["a", "b"]`. A string here used to reach `createDocument`, which spread
+ *   it into one-character tags.
+ * - `[]` and `{}` are the empty collections, so the serializer can write an
+ *   empty array or object and get it back (they used to come back as `""`).
+ * - A bare numeric literal becomes a number only when `String(Number(text))`
+ *   gives the text back, so the conversion is lossless both ways (`1e+21`
+ *   and `1.5e-7` round-trip; `007` and 20-digit IDs stay strings).
+ */
+/** Keys whose value is always a list of strings. */
+export const STRING_LIST_KEYS = new Set(["tags"]);
+/** Plain decimal or exponent notation; the text round-trip decides the rest. */
+const NUMERIC_LITERAL = /^-?(?:\d+)(?:\.\d+)?(?:e[+-]?\d+)?$/;
+/** The number a literal denotes, when converting it loses nothing. */
+export function losslessNumber(text) {
+    if (!NUMERIC_LITERAL.test(text))
+        return undefined;
+    const parsed = Number(text);
+    return Number.isFinite(parsed) && String(parsed) === text
+        ? parsed
+        : undefined;
+}
+/** `[]` or `{}` written as a value: the empty collection it denotes. */
+export function emptyCollection(value) {
+    if (value === "[]")
+        return Object.freeze([]);
+    if (value === "{}")
+        return Object.freeze(Object.create(null));
+    return undefined;
+}
+/**
+ * Parses the inline value of a list key into items. `[a, "b, c"]` is a flow
+ * list; anything else is a single item. Items go through `parseItem`.
+ */
+export function parseInlineList(value, parseItem) {
+    if (!(value.startsWith("[") && value.endsWith("]"))) {
+        return Object.freeze([parseItem(value)]);
+    }
+    const items = [];
+    let current = "";
+    let quote;
+    for (const ch of value.slice(1, -1)) {
+        if (quote) {
+            if (ch === quote)
+                quote = undefined;
+            current += ch;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+        }
+        else if (ch === ",") {
+            items.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    items.push(current);
+    return Object.freeze(items
+        .map((item) => item.trim())
+        .filter((item) => item !== "")
+        .map(parseItem));
+}
+//# sourceMappingURL=frontmatter.values.js.map

package/dist/generator/generatorMarkdown.core.js

@@ -2,6 +2,7 @@
  * Markdown output generation for documentation documents.
  */
 import { formatScalar } from "../frontmatter/frontmatter.serializer.js";
+import { escapeHtmlText } from "../utils/utils.href.js";
 import { nodesToMarkdown } from "./generatorMarkdownNodes.js";
 /**
  * Generates a markdown string from a document.
@@ -51,7 +52,7 @@ export function generateMarkdown(document, options = {}) {
         if (document.deprecatedMessage) {
             lines.push(">");
             for (const line of document.deprecatedMessage.split(/\r?\n/)) {
-                lines.push(`> ${line}`);
+                lines.push(`> ${escapeHtmlText(line)}`);
             }
         }
         lines.push("");
@@ -84,8 +85,12 @@ function contentToMarkdown(content, sanitizer) {
             return nodesToMarkdown(content.nodes);
     }
 }
-/** Collapses newlines so a value cannot break out of its line. */
+/**
+ * Collapses newlines so a value cannot break out of its line, then HTML-escapes
+ * it for the same reason the structured `quote` and `callout` nodes do: the
+ * value can come from untrusted document JSON.
+ */
 function escapeInline(value) {
-    return value.replace(/\r?\n/g, " ");
+    return escapeHtmlText(value.replace(/\r?\n/g, " "));
 }
 //# sourceMappingURL=generatorMarkdown.core.js.map

package/dist/generator/generatorMarkdownNodes.d.ts

@@ -3,7 +3,10 @@
  *
  * Every value is escaped for the position it is written to, so
  * untrusted node content cannot break out of a table, code fence,
- * heading or link.
+ * heading or link. Text outside code blocks is HTML-escaped (`&`, `<`,
+ * `>`), and a link whose href uses a scheme outside `SAFE_LINK_SCHEMES`
+ * (http, https, mailto, tel, ftp, ftps) is written as plain text, so a structured document from
+ * untrusted JSON cannot produce live HTML or a `javascript:` link.
  */
 import type { DocumentationNode } from "../docsTypes/index.js";
 /**

package/dist/generator/generatorMarkdownNodes.js

@@ -3,8 +3,12 @@
  *
  * Every value is escaped for the position it is written to, so
  * untrusted node content cannot break out of a table, code fence,
- * heading or link.
+ * heading or link. Text outside code blocks is HTML-escaped (`&`, `<`,
+ * `>`), and a link whose href uses a scheme outside `SAFE_LINK_SCHEMES`
+ * (http, https, mailto, tel, ftp, ftps) is written as plain text, so a structured document from
+ * untrusted JSON cannot produce live HTML or a `javascript:` link.
  */
+import { escapeHtmlText, isSafeLinkHref } from "../utils/utils.href.js";
 const CALLOUT_LABELS = new Map([
     ["note", "NOTE"],
     ["warning", "WARNING"],
@@ -27,7 +31,7 @@ export function nodesToMarkdown(nodes) {
                 break;
             }
             case "paragraph":
-                lines.push(node.value);
+                lines.push(escapeHtmlText(node.value));
                 lines.push("");
                 break;
             case "code": {
@@ -46,7 +50,9 @@ export function nodesToMarkdown(nodes) {
                 lines.push("");
                 break;
             case "link":
-                lines.push(`[${escapeLinkText(node.value)}](${escapeLinkHref(node.href)})`);
+                lines.push(isSafeLinkHref(node.href)
+                    ? `[${escapeLinkText(node.value)}](${escapeLinkHref(node.href)})`
+                    : escapeLinkText(node.value));
                 lines.push("");
                 break;
             case "table": {
@@ -60,7 +66,7 @@ export function nodesToMarkdown(nodes) {
             }
             case "quote":
                 for (const line of node.value.split(/\r?\n/)) {
-                    lines.push(`> ${line}`);
+                    lines.push(`> ${escapeHtmlText(line)}`);
                 }
                 lines.push("");
                 break;
@@ -71,9 +77,9 @@ export function nodesToMarkdown(nodes) {
                 const label = CALLOUT_LABELS.get(node.kind) ??
                     singleLine(String(node.kind)).toUpperCase();
                 const [first = "", ...rest] = node.value.split(/\r?\n/);
-                lines.push(`> **${label}:** ${first}`);
+                lines.push(`> **${label}:** ${escapeHtmlText(first)}`);
                 for (const line of rest) {
-                    lines.push(`> ${line}`);
+                    lines.push(`> ${escapeHtmlText(line)}`);
                 }
                 lines.push("");
                 break;
@@ -115,13 +121,14 @@ export function sanitizeLanguage(language) {
 }
 /** Escapes `|` and newlines so a value stays inside its table cell. */
 export function tableCell(value) {
-    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+    return escapeHtmlText(value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|"))
+        .replace(/\r?\n/g, "<br>");
 }
 function singleLine(value) {
-    return value.replace(/\r?\n/g, " ");
+    return escapeHtmlText(value.replace(/\r?\n/g, " "));
 }
 function listItem(value) {
-    return value.replace(/\r?\n/g, "\n  ");
+    return escapeHtmlText(value).replace(/\r?\n/g, "\n  ");
 }
 function escapeLinkText(value) {
     // Backslash first: escaping it after the brackets would turn the escapes we
@@ -132,7 +139,9 @@ function escapeLinkText(value) {
         .replace(/\]/g, "\\]");
 }
 function escapeLinkHref(href) {
-    const clean = href.replace(/[\r\n]/g, "");
+    // `&` is escaped so a character reference cannot spell out a scheme
+    // (`&#106;avascript:`) once the renderer decodes it.
+    const clean = href.replace(/[\r\n]/g, "").replace(/&/g, "&amp;");
     return /[\s()]/.test(clean) ? `<${clean.replace(/[<>]/g, "")}>` : clean;
 }
 //# sourceMappingURL=generatorMarkdownNodes.js.map

package/dist/registry/registry.core.d.ts

@@ -11,13 +11,18 @@ export type DocumentVisibilityFilter = "SERVER" | "CLIENT" | "ALL";
 export interface GetAllOptions {
     /**
      * Which documents to return. `"CLIENT"` returns documents whose
-     * `visibility` is `"CLIENT"` or unset; `"SERVER"` returns only
-     * server-only documents; `"ALL"` (default) returns everything.
+     * `visibility` is exactly `"CLIENT"` or unset; `"SERVER"` returns every
+     * other document, including unrecognised values (fail closed); `"ALL"`
+     * (default) returns everything.
      */
     readonly visibility?: DocumentVisibilityFilter;
 }
 /**
  * Returns true when `document` should be included for the given filter.
+ *
+ * Fails closed: only an unset `visibility` or exactly `"CLIENT"` is client
+ * visible. Any other value (`"server"`, a typo, a non-string from parsed
+ * frontmatter) is treated as server-only, so it never reaches a client index.
  */
 export declare function matchesVisibility(document: DocumentationDocument, filter?: DocumentVisibilityFilter): boolean;
 /**

package/dist/registry/registry.core.js

@@ -8,13 +8,17 @@ import { DuplicateDocumentError } from "@zudojs/errors";
 import { deepFreezeClone } from "../utils/utils.freeze.js";
 /**
  * Returns true when `document` should be included for the given filter.
+ *
+ * Fails closed: only an unset `visibility` or exactly `"CLIENT"` is client
+ * visible. Any other value (`"server"`, a typo, a non-string from parsed
+ * frontmatter) is treated as server-only, so it never reaches a client index.
  */
 export function matchesVisibility(document, filter = "ALL") {
     if (filter === "ALL")
         return true;
-    if (filter === "SERVER")
-        return document.visibility === "SERVER";
-    return document.visibility !== "SERVER";
+    const visibility = document.visibility;
+    const clientVisible = visibility === undefined || visibility === "CLIENT";
+    return filter === "CLIENT" ? clientVisible : !clientVisible;
 }
 /**
  * Registry for managing documentation documents.

package/dist/utils/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Utility helpers for document ID normalization, link resolution, and markdown parsing.
  */
-export { isValidDocumentId, normalizeDocumentId, documentIdFromPath, resolveDocumentLink, stripLinkDecorations, stripFencedCodeBlocks, extractTitleFromMarkdown, extractHeadings, stripMarkdown, } from "./utils.helper.js";
+export { isValidDocumentId, normalizeDocumentId, documentIdFromPath, resolveDocumentLink, stripLinkDecorations, stripFencedCodeBlocks, extractTitleFromMarkdown, extractHeadings, } from "./utils.helper.js";
+export { stripMarkdown } from "./utils.markdownText.js";
 export { deepFreeze, deepFreezeClone } from "./utils.freeze.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -3,6 +3,7 @@
  *
  * Utility helpers for document ID normalization, link resolution, and markdown parsing.
  */
-export { isValidDocumentId, normalizeDocumentId, documentIdFromPath, resolveDocumentLink, stripLinkDecorations, stripFencedCodeBlocks, extractTitleFromMarkdown, extractHeadings, stripMarkdown, } from "./utils.helper.js";
+export { isValidDocumentId, normalizeDocumentId, documentIdFromPath, resolveDocumentLink, stripLinkDecorations, stripFencedCodeBlocks, extractTitleFromMarkdown, extractHeadings, } from "./utils.helper.js";
+export { stripMarkdown } from "./utils.markdownText.js";
 export { deepFreeze, deepFreezeClone } from "./utils.freeze.js";
 //# sourceMappingURL=index.js.map

package/dist/utils/utils.helper.d.ts

@@ -50,8 +50,4 @@ export declare function extractHeadings(markdown: string): readonly {
     level: number;
     text: string;
 }[];
-/**
- * Strips markdown formatting to plain text.
- */
-export declare function stripMarkdown(markdown: string): string;
 //# sourceMappingURL=utils.helper.d.ts.map

package/dist/utils/utils.helper.js

@@ -82,7 +82,7 @@ export function stripLinkDecorations(link) {
  * headings and links inside them are not interpreted.
  */
 export function stripFencedCodeBlocks(markdown) {
-    return markdown.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, "");
+    return markdown.replace(/^(`{3,}(?!`)|~{3,}(?!~))[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, "");
 }
 /**
  * Extracts the title from markdown content (first level-1 heading
@@ -114,56 +114,11 @@ export function extractHeadings(markdown) {
 }
 /** Trims a heading and removes ATX closing hashes (`# Title #`). */
 function cleanHeadingText(text) {
-    return text.replace(/\s+#+\s*$/, "").trim();
-}
-const HTML_TAG = /<\/?[a-zA-Z][^>\n]*>/g;
-/**
- * Removes HTML tags until the result stops changing. A single pass is not
- * enough: stripping the inner tag of `<<b>b>x` re-forms `<b>x`, so a lone pass
- * can leave a tag behind in text that is later rendered as HTML.
- */
-function stripHtmlTags(text) {
-    let current = text;
-    let previous;
-    do {
-        previous = current;
-        current = current.replace(HTML_TAG, "");
-    } while (current !== previous);
-    return current;
-}
-/**
- * Strips markdown formatting to plain text.
- */
-export function stripMarkdown(markdown) {
-    return (stripHtmlTags(
-    // fenced code blocks: keep the code, drop the fences
-    markdown.replace(/^(`{3,}|~{3,})[^\n]*\n([\s\S]*?)^\1[^\n]*$/gm, "$2"))
-        // images before links
-        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
-        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-        // headings
-        .replace(/^#{1,6}\s+/gm, "")
-        .replace(/\s+#+\s*$/gm, "")
-        // emphasis (bold before italic, non-greedy)
-        .replace(/\*\*(.+?)\*\*/g, "$1")
-        .replace(/__(.+?)__/g, "$1")
-        .replace(/\*(.+?)\*/g, "$1")
-        .replace(/(^|[^\w])_(.+?)_(?=[^\w]|$)/g, "$1$2")
-        .replace(/~~(.+?)~~/g, "$1")
-        // inline code
-        .replace(/`([^`]+)`/g, "$1")
-        // blockquotes, list markers
-        .replace(/^\s*>\s?/gm, "")
-        .replace(/^\s*[-*+]\s+/gm, "")
-        .replace(/^\s*\d+\.\s+/gm, "")
-        // tables: drop separator rows, unpipe cells
-        .replace(/^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/gm, "")
-        .replace(/^\s*\|/gm, "")
-        .replace(/\|\s*$/gm, "")
-        .replace(/\s*\|\s*/g, " ")
-        // horizontal rules
-        .replace(/^\s*([-*_]\s*){3,}$/gm, "")
-        .replace(/\n{3,}/g, "\n\n")
-        .trim());
+    const trimmed = text.trim();
+    const withoutHashes = trimmed.replace(/(?<!#)#+$/, "");
+    const last = withoutHashes.at(-1);
+    return withoutHashes !== trimmed && (last === " " || last === "\t")
+        ? withoutHashes.trim()
+        : trimmed;
 }
 //# sourceMappingURL=utils.helper.js.map

package/dist/utils/utils.href.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Link-target and inline-text safety for generated markdown.
+ *
+ * Markdown renderers turn `[x](javascript:…)` into a live link and pass raw
+ * `<tag>` text through as HTML. Structured documents can come from untrusted
+ * JSON, so generated hrefs are limited to an allow-list of schemes and text
+ * is HTML-escaped.
+ *
+ * @module utils/utils.href
+ */
+/** Schemes a generated or validated link may use. Relative and `#` links need none. */
+export declare const SAFE_LINK_SCHEMES: ReadonlySet<string>;
+/**
+ * The scheme of a link target, lower-cased, or undefined for a relative,
+ * protocol-relative or fragment link. Whitespace and control characters are
+ * ignored first, as browsers do (`java\tscript:`, ` JavaScript:`).
+ */
+export declare function linkScheme(href: string): string | undefined;
+/** Whether a link target is relative, a fragment, or uses an allow-listed scheme. */
+export declare function isSafeLinkHref(href: string): boolean;
+/**
+ * Escapes `&`, `<` and `>` so text renders literally instead of as HTML or
+ * as a character reference.
+ */
+export declare function escapeHtmlText(value: string): string;
+//# sourceMappingURL=utils.href.d.ts.map

package/dist/utils/utils.href.js

@@ -0,0 +1,45 @@
+/**
+ * Link-target and inline-text safety for generated markdown.
+ *
+ * Markdown renderers turn `[x](javascript:…)` into a live link and pass raw
+ * `<tag>` text through as HTML. Structured documents can come from untrusted
+ * JSON, so generated hrefs are limited to an allow-list of schemes and text
+ * is HTML-escaped.
+ *
+ * @module utils/utils.href
+ */
+/** Schemes a generated or validated link may use. Relative and `#` links need none. */
+export const SAFE_LINK_SCHEMES = new Set([
+    "http",
+    "https",
+    "mailto",
+    "tel",
+    "ftp",
+    "ftps",
+]);
+/**
+ * The scheme of a link target, lower-cased, or undefined for a relative,
+ * protocol-relative or fragment link. Whitespace and control characters are
+ * ignored first, as browsers do (`java\tscript:`, ` JavaScript:`).
+ */
+export function linkScheme(href) {
+    const compact = href.replace(/[\u0000- \u007f]/g, "");
+    const match = /^([^/?#]*?):/.exec(compact);
+    return match ? (match[1] ?? "").toLowerCase() : undefined;
+}
+/** Whether a link target is relative, a fragment, or uses an allow-listed scheme. */
+export function isSafeLinkHref(href) {
+    const scheme = linkScheme(href);
+    return scheme === undefined || SAFE_LINK_SCHEMES.has(scheme);
+}
+/**
+ * Escapes `&`, `<` and `>` so text renders literally instead of as HTML or
+ * as a character reference.
+ */
+export function escapeHtmlText(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+//# sourceMappingURL=utils.href.js.map

package/dist/utils/utils.markdownText.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Markdown → plain text, in linear time.
+ *
+ * `stripMarkdown` is exported for building search excerpts, so it sees
+ * untrusted input. The previous version used `\s` inside `m`-flag line
+ * regexes; there `\s` also matches `\n`, and adjacent `\s*` runs let the
+ * engine split one whitespace run in O(n²) ways from each of n line starts
+ * (2 KB of newlines took ~6 s). Every pattern here is unambiguous: line
+ * patterns use `[ \t]` only, no two quantifiers compete for the same
+ * characters, and bracketed spans cannot contain their own opener, so each
+ * start position scans only up to the next opener.
+ */
+/**
+ * Removes HTML tags until the result stops changing. A single pass is not
+ * enough: stripping the inner tag of `<<b>b>x` re-forms `<b>x`.
+ */
+export declare function stripHtmlTags(text: string): string;
+/**
+ * Strips markdown formatting to plain text.
+ */
+export declare function stripMarkdown(markdown: string): string;
+//# sourceMappingURL=utils.markdownText.d.ts.map

package/dist/utils/utils.markdownText.js

@@ -0,0 +1,88 @@
+/**
+ * Markdown → plain text, in linear time.
+ *
+ * `stripMarkdown` is exported for building search excerpts, so it sees
+ * untrusted input. The previous version used `\s` inside `m`-flag line
+ * regexes; there `\s` also matches `\n`, and adjacent `\s*` runs let the
+ * engine split one whitespace run in O(n²) ways from each of n line starts
+ * (2 KB of newlines took ~6 s). Every pattern here is unambiguous: line
+ * patterns use `[ \t]` only, no two quantifiers compete for the same
+ * characters, and bracketed spans cannot contain their own opener, so each
+ * start position scans only up to the next opener.
+ */
+/** HTML tags. `[^<>\n]` stops at the next `<`, so `<a<a<a…` stays linear. */
+const HTML_TAG = /<\/?[a-zA-Z][^<>\n]*>/g;
+/**
+ * Removes HTML tags until the result stops changing. A single pass is not
+ * enough: stripping the inner tag of `<<b>b>x` re-forms `<b>x`.
+ */
+export function stripHtmlTags(text) {
+    let current = text;
+    let previous;
+    do {
+        previous = current;
+        current = current.replace(HTML_TAG, "");
+    } while (current !== previous);
+    return current;
+}
+/**
+ * Drops the outer pipes of table rows, then turns each inner separator (a
+ * run of spaces/tabs/pipes that holds a pipe) into one space.
+ */
+function unpipeCells(text) {
+    return text
+        .replace(/^[ \t]*\|[ \t]*/gm, "")
+        .replace(/\|[ \t]*$/gm, "")
+        .replace(/[ \t|]+/g, (run) => (run.includes("|") ? " " : run));
+}
+/** A table separator row such as `| --- | :-: |`. */
+const TABLE_SEPARATOR = /^[ \t]*(?:\|[ \t]*)?:?-{3,}:?[ \t]*(?:\|[ \t]*:?-{3,}:?[ \t]*)*(?:\|[ \t]*)?$/gm;
+/**
+ * Closing ATX hashes (`# Title ##`). The lookbehind anchors each attempt at
+ * the start of a hash run, so a long run not at line end is scanned once.
+ */
+function stripClosingHashes(text) {
+    return text.replace(/(?<!#)#+[ \t]*$/gm, (hashes, offset, whole) => {
+        const before = whole[offset - 1];
+        return before === " " || before === "\t" ? "" : hashes;
+    });
+}
+/** Trailing spaces/tabs on each line, removed with a single linear pass. */
+function trimLineEnds(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n");
+}
+/**
+ * Strips markdown formatting to plain text.
+ */
+export function stripMarkdown(markdown) {
+    const withoutFences = markdown.replace(/^(`{3,}(?!`)|~{3,}(?!~))[^\n]*\n([\s\S]*?)^\1[^\n]*$/gm, "$2");
+    const text = stripHtmlTags(withoutFences)
+        // images before links; text and target cannot contain their own opener
+        .replace(/!\[([^[\]\n]*)\]\([^()\n]*\)/g, "$1")
+        .replace(/\[([^[\]\n]+)\]\([^()\n]+\)/g, "$1")
+        // headings
+        .replace(/^#{1,6}[ \t]+/gm, "");
+    return trimLineEnds(unpipeCells(stripClosingHashes(text)
+        // emphasis (bold before italic); spans cannot hold their delimiter
+        .replace(/\*\*((?:[^*\n]|\*(?!\*))+)\*\*/g, "$1")
+        .replace(/__((?:[^_\n]|_(?!_))+)__/g, "$1")
+        .replace(/\*([^*\n]+)\*/g, "$1")
+        .replace(/(^|[^\w])_([^_\n]+)_(?=[^\w]|$)/gm, "$1$2")
+        .replace(/~~([^~\n]+)~~/g, "$1")
+        // inline code
+        .replace(/`([^`\n]+)`/g, "$1")
+        // blockquotes, list markers
+        .replace(/^[ \t]*>[ \t]?/gm, "")
+        .replace(/^[ \t]*[-*+][ \t]+/gm, "")
+        .replace(/^[ \t]*\d+\.[ \t]+/gm, "")
+        // tables: drop separator rows, then unpipe cells
+        .replace(TABLE_SEPARATOR, "")
+        // horizontal rules
+        .replace(/^[ \t]*(?:[-*_][ \t]*){3,}$/gm, "")))
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+//# sourceMappingURL=utils.markdownText.js.map

package/dist/validator/validatorLinks.core.d.ts

@@ -18,7 +18,9 @@ export interface ValidateLinksOptions {
  * Validates internal links in a document's markdown content and in
  * structured `link` nodes.
  *
- * Skipped (never reported): images, anchors (`#…`), any target with a
+ * A target whose scheme is not allowed (http, https, mailto, tel, ftp, ftps).(`javascript:`,
+ * `data:`, `vbscript:` …) is reported as an `UNSAFE_LINK` error.
+ * Skipped (never reported): images, anchors (`#…`), other targets with a
  * URL scheme or `//` prefix, links inside fenced or inline code.
  * Relative targets (`./x`, `../x`, `/x`) are resolved against the
  * document ID with `resolveDocumentLink`; bare targets are looked up

package/dist/validator/validatorLinks.core.js

@@ -2,6 +2,7 @@
  * Validates internal links within markdown and structured documentation.
  */
 import { resolveDocumentLink, stripFencedCodeBlocks, stripLinkDecorations, } from "../utils/utils.helper.js";
+import { isSafeLinkHref } from "../utils/utils.href.js";
 import { toValidationResult, } from "./validator.types.js";
 /** Default maximum markdown length that is scanned for links. */
 export const DEFAULT_MAX_LINK_SCAN_LENGTH = 100_000;
@@ -9,15 +10,23 @@ export const DEFAULT_MAX_LINK_SCAN_LENGTH = 100_000;
  * Matches `[text](target)` and `![alt](target)` links. Group 1 is the
  * optional image bang, group 2 the target (optionally `<…>` wrapped
  * and followed by a `"title"`).
+ *
+ * Linear by construction: link text cannot contain `[`/`]` and a target
+ * cannot contain `(`/`)`, so each start scans only to the next opener; the
+ * target is non-empty, so leading whitespace is never split between two
+ * quantifiers; and whitespace is `[ \t]` (the old `\s` ran across lines).
+ * The old pattern took ~30 s on a 99 KB run of `[`.
  */
-const LINK_PATTERN = /(!?)\[[^\]\n]*\]\(\s*(<[^>\n]*>|[^)\s]*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+const LINK_PATTERN = /(!?)\[[^[\]\n]*\]\((?:[ \t]*(<[^<>\n]*>|[^()\s<>]+)(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'))?)?[ \t]*\)/g;
 /** `scheme:` (mailto:, ftp:, http:) or protocol-relative `//`. */
 const EXTERNAL_PATTERN = /^([a-zA-Z][a-zA-Z0-9+.-]*:|\/\/)/;
 /**
  * Validates internal links in a document's markdown content and in
  * structured `link` nodes.
  *
- * Skipped (never reported): images, anchors (`#…`), any target with a
+ * A target whose scheme is not allowed (http, https, mailto, tel, ftp, ftps).(`javascript:`,
+ * `data:`, `vbscript:` …) is reported as an `UNSAFE_LINK` error.
+ * Skipped (never reported): images, anchors (`#…`), other targets with a
  * URL scheme or `//` prefix, links inside fenced or inline code.
  * Relative targets (`./x`, `../x`, `/x`) are resolved against the
  * document ID with `resolveDocumentLink`; bare targets are looked up
@@ -64,6 +73,15 @@ function checkTarget(rawTarget, document, registeredIds, issues) {
     const target = rawTarget.trim();
     if (target === "" || target.startsWith("#"))
         return;
+    if (!isSafeLinkHref(target)) {
+        issues.push({
+            severity: "error",
+            code: "UNSAFE_LINK",
+            message: `Document "${document.id}" links to "${rawTarget}", whose scheme is not allowed (http, https, mailto, tel, ftp, ftps).`,
+            documentId: document.id,
+        });
+        return;
+    }
     if (EXTERNAL_PATTERN.test(target))
         return;
     const stripped = stripLinkDecorations(target);
@@ -85,8 +103,12 @@ function checkTarget(rawTarget, document, registeredIds, issues) {
         documentId: document.id,
     });
 }
-/** Blanks out inline code spans so links inside them are ignored. */
+/**
+ * Blanks out inline code spans so links inside them are ignored. The
+ * lookarounds anchor each attempt at a whole backtick run, so a long run is
+ * not re-scanned from every position inside it.
+ */
 function stripInlineCode(markdown) {
-    return markdown.replace(/(`+)[^`\n][\s\S]*?\1/g, (m) => " ".repeat(m.length));
+    return markdown.replace(/(?<!`)(`+)(?![`\n])[\s\S]*?(?<!`)\1(?!`)/g, (m) => " ".repeat(m.length));
 }
 //# sourceMappingURL=validatorLinks.core.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/docs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Documentation infrastructure with structured document model, registry, validation, navigation, and generation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",