@zudojs/docs 0.1.0 → 1.0.0

package/dist/utils/utils.helper.js

@@ -1,34 +1,64 @@
 /**
  * Utility helpers for the documentation package.
  */
+/** Characters allowed in one segment of a document ID. */
+const ID_SEGMENT = /^[A-Za-z0-9_-]+$/;
+/**
+ * Returns true when `id` is a stable dot-separated identifier such as
+ * `guides.http.routing`: non-empty segments of letters, digits, `_`
+ * and `-`, with no whitespace or empty segments.
+ */
+export function isValidDocumentId(id) {
+    if (typeof id !== "string" || id.length === 0)
+        return false;
+    return id.split(".").every((segment) => ID_SEGMENT.test(segment));
+}
 /**
  * Normalizes a document ID to a consistent format.
- * Strips leading/trailing dots, collapses consecutive dots.
+ * Trims whitespace, collapses consecutive dots and strips leading/trailing dots.
  */
 export function normalizeDocumentId(id) {
-    return id
+    return (id
+        .trim()
         .replace(/\.+/g, ".")
-        .replace(/^\.|\.$/g, "")
-        .trim();
+        // Runs are already collapsed, so at most one dot can sit at each end.
+        // Matching a single dot keeps this linear; `\.+$` would backtrack.
+        .replace(/^\.|\.$/g, ""));
 }
 /**
  * Generates a document ID from a file path.
- * Converts path separators to dots and removes extension.
+ * Converts path separators to dots and removes the extension of the
+ * final segment only (`guides/v1.2/routing.md` → `guides.v1.2.routing`).
+ * Returns an empty string when the path has no usable segment
+ * (e.g. `.gitignore`).
  */
 export function documentIdFromPath(path) {
-    return normalizeDocumentId(path.replace(/\.[^.]+$/, "").replace(/[/\\]/g, "."));
+    const normalizedPath = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    const segments = normalizedPath.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return "";
+    const last = segments[segments.length - 1] ?? "";
+    const stem = last.replace(/\.[^.]+$/, "");
+    if (stem.length === 0)
+        return "";
+    segments[segments.length - 1] = stem;
+    return normalizeDocumentId(segments.join("."));
 }
 /**
  * Resolves a relative document link against a base ID.
  * "guides.http" + "./routing" → "guides.http.routing"
+ *
+ * Fragments (`#section`), `.md`/`.mdx` extensions and Windows
+ * separators are stripped before resolving.
  */
 export function resolveDocumentLink(baseId, link) {
-    if (link.startsWith("/")) {
-        return normalizeDocumentId(link.slice(1));
+    const cleaned = stripLinkDecorations(link);
+    if (cleaned.startsWith("/")) {
+        return normalizeDocumentId(cleaned.slice(1).replace(/\//g, "."));
     }
-    const baseParts = baseId.split(".");
+    const baseParts = baseId.split(".").filter((p) => p.length > 0);
     baseParts.pop();
-    const linkParts = link.split("/");
+    const linkParts = cleaned.split("/");
     for (const part of linkParts) {
         if (part === "..") {
             baseParts.pop();
@@ -40,43 +70,100 @@ export function resolveDocumentLink(baseId, link) {
     return normalizeDocumentId(baseParts.join("."));
 }
 /**
- * Extracts the title from markdown content (first heading).
+ * Removes a `#fragment`, a trailing `.md`/`.mdx` extension and
+ * converts `\` to `/` in a link target.
+ */
+export function stripLinkDecorations(link) {
+    const withoutFragment = link.split("#")[0] ?? "";
+    return withoutFragment.replace(/\\/g, "/").replace(/\.mdx?$/i, "");
+}
+/**
+ * Removes fenced code blocks (``` or ~~~) from markdown so that
+ * headings and links inside them are not interpreted.
+ */
+export function stripFencedCodeBlocks(markdown) {
+    return markdown.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, "");
+}
+/**
+ * Extracts the title from markdown content (first level-1 heading
+ * outside fenced code blocks).
  */
 export function extractTitleFromMarkdown(markdown) {
-    const match = markdown.match(/^# ([^\n]+)$/m);
-    return match?.[1]?.trim();
+    const match = stripFencedCodeBlocks(markdown).match(/^# ([^\n]+)$/m);
+    return match?.[1] ? cleanHeadingText(match[1]) : undefined;
 }
 /**
- * Extracts headings from markdown content.
+ * Extracts headings from markdown content (outside fenced code blocks).
  */
 export function extractHeadings(markdown) {
     const results = [];
     const pattern = /^(#{1,6}) ([^\n]+)$/gm;
+    const source = stripFencedCodeBlocks(markdown);
     let match;
-    while ((match = pattern.exec(markdown)) !== null) {
+    while ((match = pattern.exec(source)) !== null) {
         const hashes = match[1];
         const headingText = match[2];
         if (hashes && headingText) {
             results.push({
                 level: hashes.length,
-                text: headingText.trim(),
+                text: cleanHeadingText(headingText),
             });
         }
     }
     return Object.freeze(results);
 }
+/** 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 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(/\*\*([^*]+)\*\*/g, "$1")
-        .replace(/\*([^*]+)\*/g, "$1")
+        .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")
-        .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+        // blockquotes, list markers
+        .replace(/^\s*>\s?/gm, "")
         .replace(/^\s*[-*+]\s+/gm, "")
         .replace(/^\s*\d+\.\s+/gm, "")
-        .trim();
+        // 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());
 }
 //# sourceMappingURL=utils.helper.js.map

package/dist/validator/index.d.ts

@@ -5,7 +5,10 @@
  */
 export { validateDocument } from "./validatorDocument.core.js";
 export { validateNoDuplicateIds } from "./validatorDuplicates.core.js";
-export { validateLinks } from "./validatorLinks.core.js";
+export { validateLinks, DEFAULT_MAX_LINK_SCAN_LENGTH, } from "./validatorLinks.core.js";
 export { validateAll, validateNavigation } from "./validatorAll/index.js";
+export { toValidationResult } from "./validator.types.js";
 export type { ValidationIssue, ValidationResult } from "./validator.types.js";
+export type { ValidateLinksOptions } from "./validatorLinks.core.js";
+export type { ValidateAllOptions } from "./validatorAll/validatorAll.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/validator/index.js

@@ -5,6 +5,7 @@
  */
 export { validateDocument } from "./validatorDocument.core.js";
 export { validateNoDuplicateIds } from "./validatorDuplicates.core.js";
-export { validateLinks } from "./validatorLinks.core.js";
+export { validateLinks, DEFAULT_MAX_LINK_SCAN_LENGTH, } from "./validatorLinks.core.js";
 export { validateAll, validateNavigation } from "./validatorAll/index.js";
+export { toValidationResult } from "./validator.types.js";
 //# sourceMappingURL=index.js.map

package/dist/validator/validator.types.d.ts

@@ -12,9 +12,17 @@ export interface ValidationIssue {
 }
 /**
  * Result of validating documentation.
+ *
+ * `valid` is `false` only when at least one issue has severity
+ * `"error"`; warnings never make a result invalid.
  */
 export interface ValidationResult {
     readonly valid: boolean;
     readonly issues: readonly ValidationIssue[];
 }
+/**
+ * Builds a `ValidationResult` from a list of issues using the single
+ * rule shared by every validator in this package.
+ */
+export declare function toValidationResult(issues: readonly ValidationIssue[]): ValidationResult;
 //# sourceMappingURL=validator.types.d.ts.map

package/dist/validator/validator.types.js

@@ -1,5 +1,14 @@
 /**
  * Type definitions for document validation.
  */
-export {};
+/**
+ * Builds a `ValidationResult` from a list of issues using the single
+ * rule shared by every validator in this package.
+ */
+export function toValidationResult(issues) {
+    return {
+        valid: !issues.some((issue) => issue.severity === "error"),
+        issues,
+    };
+}
 //# sourceMappingURL=validator.types.js.map

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

@@ -2,9 +2,18 @@
  * Validates an entire documentation set.
  */
 import type { DocumentationDocument, DocumentationNavigationItem } from "../../docsTypes/index.js";
-import type { ValidationResult } from "../validator.types.js";
+import { type ValidationResult } from "../validator.types.js";
+import { type ValidateLinksOptions } from "../validatorLinks.core.js";
+/** Options for `validateAll`. */
+export interface ValidateAllOptions extends ValidateLinksOptions {
+    /**
+     * When a navigation tree is supplied, report documents that do not
+     * appear in it as `NAVIGATION_ORPHAN_DOCUMENT` warnings. Default true.
+     */
+    readonly reportOrphans?: boolean;
+}
 /**
  * Validates all documents and optionally a navigation tree.
  */
-export declare function validateAll(documents: readonly DocumentationDocument[], navigation?: readonly DocumentationNavigationItem[]): ValidationResult;
+export declare function validateAll(documents: readonly DocumentationDocument[], navigation?: readonly DocumentationNavigationItem[], options?: ValidateAllOptions): ValidationResult;
 //# sourceMappingURL=validatorAll.core.d.ts.map

package/dist/validator/validatorAll/validatorAll.core.js

@@ -1,14 +1,16 @@
 /**
  * Validates an entire documentation set.
  */
+import { flattenNavigation } from "../../navigation/navigation.core.js";
+import { toValidationResult, } from "../validator.types.js";
 import { validateDocument } from "../validatorDocument.core.js";
 import { validateNoDuplicateIds } from "../validatorDuplicates.core.js";
-import { validateLinks } from "../validatorLinks.core.js";
+import { validateLinks, } from "../validatorLinks.core.js";
 import { validateNavigation } from "./validatorNavigation.core.js";
 /**
  * Validates all documents and optionally a navigation tree.
  */
-export function validateAll(documents, navigation) {
+export function validateAll(documents, navigation, options = {}) {
     const allIssues = [];
     const idResult = validateNoDuplicateIds(documents);
     allIssues.push(...idResult.issues);
@@ -16,16 +18,26 @@ export function validateAll(documents, navigation) {
     for (const doc of documents) {
         const docResult = validateDocument(doc);
         allIssues.push(...docResult.issues);
-        const linkResult = validateLinks(doc, registeredIds);
+        const linkResult = validateLinks(doc, registeredIds, options);
         allIssues.push(...linkResult.issues);
     }
     if (navigation) {
         const navResult = validateNavigation(navigation, registeredIds);
         allIssues.push(...navResult.issues);
+        if (options.reportOrphans ?? true) {
+            const inNavigation = new Set(flattenNavigation(navigation));
+            for (const id of registeredIds) {
+                if (!inNavigation.has(id)) {
+                    allIssues.push({
+                        severity: "warning",
+                        code: "NAVIGATION_ORPHAN_DOCUMENT",
+                        message: `Document "${id}" is not reachable from the navigation.`,
+                        documentId: id,
+                    });
+                }
+            }
+        }
     }
-    return {
-        valid: allIssues.filter((i) => i.severity === "error").length === 0,
-        issues: allIssues,
-    };
+    return toValidationResult(allIssues);
 }
 //# sourceMappingURL=validatorAll.core.js.map

package/dist/validator/validatorAll/validatorNavigation.core.d.ts

@@ -2,9 +2,16 @@
  * Validates navigation tree references against registered documents.
  */
 import type { DocumentationNavigationItem } from "../../docsTypes/index.js";
-import type { ValidationResult } from "../validator.types.js";
+import { type ValidationResult } from "../validator.types.js";
 /**
  * Validates navigation tree references.
+ *
+ * Reports `NAVIGATION_UNKNOWN_DOCUMENT` (error) for references to
+ * unregistered documents, `NAVIGATION_CYCLE` (error) when a node is
+ * its own ancestor or the tree is deeper than `MAX_NAVIGATION_DEPTH`,
+ * `NAVIGATION_DUPLICATE_DOCUMENT` (warning) when a document is
+ * referenced more than once, and `NAVIGATION_EMPTY_ITEM` (warning)
+ * for items with neither `documentId` nor `children`.
  */
 export declare function validateNavigation(items: readonly DocumentationNavigationItem[], registeredIds: ReadonlySet<string>): ValidationResult;
 //# sourceMappingURL=validatorNavigation.core.d.ts.map

package/dist/validator/validatorAll/validatorNavigation.core.js

@@ -1,29 +1,83 @@
 /**
  * Validates navigation tree references against registered documents.
  */
+import { MAX_NAVIGATION_DEPTH } from "../../navigation/navigation.core.js";
+import { toValidationResult, } from "../validator.types.js";
 /**
  * Validates navigation tree references.
+ *
+ * Reports `NAVIGATION_UNKNOWN_DOCUMENT` (error) for references to
+ * unregistered documents, `NAVIGATION_CYCLE` (error) when a node is
+ * its own ancestor or the tree is deeper than `MAX_NAVIGATION_DEPTH`,
+ * `NAVIGATION_DUPLICATE_DOCUMENT` (warning) when a document is
+ * referenced more than once, and `NAVIGATION_EMPTY_ITEM` (warning)
+ * for items with neither `documentId` nor `children`.
  */
 export function validateNavigation(items, registeredIds) {
     const issues = [];
-    function walk(nodes) {
+    const seenIds = new Set();
+    const visited = new WeakSet();
+    function walk(nodes, ancestors) {
+        if (ancestors.length > MAX_NAVIGATION_DEPTH) {
+            issues.push({
+                severity: "error",
+                code: "NAVIGATION_CYCLE",
+                message: `Navigation tree exceeds the maximum depth of ${MAX_NAVIGATION_DEPTH}.`,
+            });
+            return;
+        }
         for (const node of nodes) {
-            if (node.documentId && !registeredIds.has(node.documentId)) {
+            if (!node || typeof node !== "object") {
+                issues.push({
+                    severity: "error",
+                    code: "NAVIGATION_EMPTY_ITEM",
+                    message: "Navigation item is not an object.",
+                });
+                continue;
+            }
+            if (ancestors.includes(node)) {
                 issues.push({
                     severity: "error",
-                    code: "NAVIGATION_UNKNOWN_DOCUMENT",
-                    message: `Navigation item "${node.title}" references unknown document "${node.documentId}".`,
+                    code: "NAVIGATION_CYCLE",
+                    message: `Navigation item "${node.title}" is its own ancestor.`,
+                });
+                continue;
+            }
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            if (node.documentId) {
+                if (!registeredIds.has(node.documentId)) {
+                    issues.push({
+                        severity: "error",
+                        code: "NAVIGATION_UNKNOWN_DOCUMENT",
+                        message: `Navigation item "${node.title}" references unknown document "${node.documentId}".`,
+                        documentId: node.documentId,
+                    });
+                }
+                if (seenIds.has(node.documentId)) {
+                    issues.push({
+                        severity: "warning",
+                        code: "NAVIGATION_DUPLICATE_DOCUMENT",
+                        message: `Document "${node.documentId}" is referenced more than once in the navigation.`,
+                        documentId: node.documentId,
+                    });
+                }
+                seenIds.add(node.documentId);
+            }
+            else if (!node.children || node.children.length === 0) {
+                issues.push({
+                    severity: "warning",
+                    code: "NAVIGATION_EMPTY_ITEM",
+                    message: `Navigation item "${node.title}" has neither a documentId nor children.`,
                 });
             }
             if (node.children) {
-                walk(node.children);
+                walk(node.children, [...ancestors, node]);
             }
         }
     }
-    walk(items);
-    return {
-        valid: issues.length === 0,
-        issues,
-    };
+    walk(items, []);
+    return toValidationResult(issues);
 }
 //# sourceMappingURL=validatorNavigation.core.js.map

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

@@ -2,9 +2,10 @@
  * Validates a single document for structural correctness.
  */
 import type { DocumentationDocument } from "../docsTypes/index.js";
-import type { ValidationResult } from "./validator.types.js";
+import { type ValidationResult } from "./validator.types.js";
 /**
- * Validates a single document.
+ * Validates a single document: ID syntax, required fields, content
+ * shape (including structured nodes), and the metadata enums.
  */
 export declare function validateDocument(document: DocumentationDocument): ValidationResult;
 //# sourceMappingURL=validatorDocument.core.d.ts.map