@zudojs/docs 0.1.0 → 1.0.0

package/dist/navigation/navigation.core.d.ts

@@ -3,23 +3,42 @@
  *
  * Provides breadcrumb generation, tree flattening, and
  * link resolution for documentation navigation structures.
+ *
+ * Every walker tolerates shared or cyclic nodes (a node is visited at
+ * most once) and stops at `MAX_NAVIGATION_DEPTH`, so malformed trees
+ * never overflow the stack.
  */
 import type { DocumentationBreadcrumb, DocumentationNavigationItem } from "../docsTypes/index.js";
+/** Maximum nesting depth any walker will descend. */
+export declare const MAX_NAVIGATION_DEPTH = 64;
+type Nodes = readonly DocumentationNavigationItem[];
 /**
  * Generates breadcrumbs for a given document ID
- * by walking the navigation tree.
+ * by walking the navigation tree. Intermediate section nodes keep
+ * their `documentId` when they have one, so section landing pages
+ * stay linkable.
  */
-export declare function getBreadcrumbs(documentId: string, items: readonly DocumentationNavigationItem[]): readonly DocumentationBreadcrumb[];
+export declare function getBreadcrumbs(documentId: string, items: Nodes): readonly DocumentationBreadcrumb[];
 /**
  * Flattens a navigation tree into a list of all document IDs in order.
+ * A document referenced more than once appears once, at its first position.
  */
-export declare function flattenNavigation(items: readonly DocumentationNavigationItem[]): readonly string[];
+export declare function flattenNavigation(items: Nodes): readonly string[];
 /**
  * Finds a navigation item by document ID.
  */
-export declare function findNavigationItem(documentId: string, items: readonly DocumentationNavigationItem[]): DocumentationNavigationItem | undefined;
+export declare function findNavigationItem(documentId: string, items: Nodes): DocumentationNavigationItem | undefined;
+/**
+ * Gets sibling document IDs for a given document (the other documents
+ * at the same navigation level, excluding the document itself).
+ */
+export declare function getSiblings(documentId: string, items: Nodes): readonly string[];
 /**
- * Gets sibling document IDs for a given document.
+ * Gets the previous and next document IDs at the same navigation level.
  */
-export declare function getSiblings(documentId: string, items: readonly DocumentationNavigationItem[]): readonly string[];
+export declare function getAdjacent(documentId: string, items: Nodes): {
+    readonly previous?: string;
+    readonly next?: string;
+};
+export {};
 //# sourceMappingURL=navigation.core.d.ts.map

package/dist/navigation/navigation.core.js

@@ -3,22 +3,36 @@
  *
  * Provides breadcrumb generation, tree flattening, and
  * link resolution for documentation navigation structures.
+ *
+ * Every walker tolerates shared or cyclic nodes (a node is visited at
+ * most once) and stops at `MAX_NAVIGATION_DEPTH`, so malformed trees
+ * never overflow the stack.
  */
+/** Maximum nesting depth any walker will descend. */
+export const MAX_NAVIGATION_DEPTH = 64;
 /**
  * Generates breadcrumbs for a given document ID
- * by walking the navigation tree.
+ * by walking the navigation tree. Intermediate section nodes keep
+ * their `documentId` when they have one, so section landing pages
+ * stay linkable.
  */
 export function getBreadcrumbs(documentId, items) {
     const path = [];
-    function walk(nodes) {
+    const seen = new WeakSet();
+    function walk(nodes, depth) {
+        if (depth > MAX_NAVIGATION_DEPTH)
+            return false;
         for (const node of nodes) {
+            if (seen.has(node))
+                continue;
+            seen.add(node);
             if (node.documentId === documentId) {
-                path.push({ title: node.title, documentId: node.documentId });
+                path.push(toBreadcrumb(node));
                 return true;
             }
             if (node.children) {
-                path.push({ title: node.title });
-                if (walk(node.children)) {
+                path.push(toBreadcrumb(node));
+                if (walk(node.children, depth + 1)) {
                     return true;
                 }
                 path.pop();
@@ -26,60 +40,114 @@ export function getBreadcrumbs(documentId, items) {
         }
         return false;
     }
-    walk(items);
+    walk(items, 0);
     return Object.freeze(path);
 }
+function toBreadcrumb(node) {
+    return node.documentId === undefined
+        ? { title: node.title }
+        : { title: node.title, documentId: node.documentId };
+}
 /**
  * Flattens a navigation tree into a list of all document IDs in order.
+ * A document referenced more than once appears once, at its first position.
  */
 export function flattenNavigation(items) {
     const result = [];
-    function walk(nodes) {
+    const ids = new Set();
+    const seen = new WeakSet();
+    function walk(nodes, depth) {
+        if (depth > MAX_NAVIGATION_DEPTH)
+            return;
         for (const node of nodes) {
-            if (node.documentId) {
+            if (seen.has(node))
+                continue;
+            seen.add(node);
+            if (node.documentId && !ids.has(node.documentId)) {
+                ids.add(node.documentId);
                 result.push(node.documentId);
             }
             if (node.children) {
-                walk(node.children);
+                walk(node.children, depth + 1);
             }
         }
     }
-    walk(items);
+    walk(items, 0);
     return Object.freeze(result);
 }
 /**
  * Finds a navigation item by document ID.
  */
 export function findNavigationItem(documentId, items) {
-    for (const node of items) {
-        if (node.documentId === documentId) {
-            return node;
-        }
-        if (node.children) {
-            const found = findNavigationItem(documentId, node.children);
-            if (found)
-                return found;
+    const seen = new WeakSet();
+    function walk(nodes, depth) {
+        if (depth > MAX_NAVIGATION_DEPTH)
+            return undefined;
+        for (const node of nodes) {
+            if (seen.has(node))
+                continue;
+            seen.add(node);
+            if (node.documentId === documentId) {
+                return node;
+            }
+            if (node.children) {
+                const found = walk(node.children, depth + 1);
+                if (found)
+                    return found;
+            }
         }
+        return undefined;
     }
-    return undefined;
+    return walk(items, 0);
 }
 /**
- * Gets sibling document IDs for a given document.
+ * Returns the list of document IDs at the same level as `documentId`,
+ * including the document itself, in navigation order.
  */
-export function getSiblings(documentId, items) {
-    function walk(nodes) {
+function getLevel(documentId, items) {
+    const seen = new WeakSet();
+    function walk(nodes, depth) {
+        if (depth > MAX_NAVIGATION_DEPTH)
+            return undefined;
         for (const node of nodes) {
+            if (seen.has(node))
+                continue;
+            seen.add(node);
             if (node.documentId === documentId) {
-                return nodes.filter((n) => n.documentId).map((n) => n.documentId);
+                return nodes
+                    .map((n) => n.documentId)
+                    .filter((id) => typeof id === "string");
             }
             if (node.children) {
-                const result = walk(node.children);
+                const result = walk(node.children, depth + 1);
                 if (result)
                     return result;
             }
         }
         return undefined;
     }
-    return Object.freeze(walk(items) ?? []);
+    return walk(items, 0) ?? [];
+}
+/**
+ * Gets sibling document IDs for a given document (the other documents
+ * at the same navigation level, excluding the document itself).
+ */
+export function getSiblings(documentId, items) {
+    return Object.freeze(getLevel(documentId, items).filter((id) => id !== documentId));
+}
+/**
+ * Gets the previous and next document IDs at the same navigation level.
+ */
+export function getAdjacent(documentId, items) {
+    const level = getLevel(documentId, items);
+    const index = level.indexOf(documentId);
+    if (index === -1)
+        return Object.freeze({});
+    const previous = level[index - 1];
+    const next = level[index + 1];
+    return Object.freeze({
+        ...(previous !== undefined ? { previous } : {}),
+        ...(next !== undefined ? { next } : {}),
+    });
 }
 //# sourceMappingURL=navigation.core.js.map

package/dist/registry/index.d.ts

@@ -3,5 +3,6 @@
  *
  * Document registry for storing, retrieving, and filtering documentation.
  */
-export { DocumentRegistry, createDocumentRegistry } from "./registry.core.js";
+export { DocumentRegistry, createDocumentRegistry, matchesVisibility, } from "./registry.core.js";
+export type { DocumentVisibilityFilter, GetAllOptions, } from "./registry.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -3,5 +3,5 @@
  *
  * Document registry for storing, retrieving, and filtering documentation.
  */
-export { DocumentRegistry, createDocumentRegistry } from "./registry.core.js";
+export { DocumentRegistry, createDocumentRegistry, matchesVisibility, } from "./registry.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -5,13 +5,34 @@
  * documentation documents. Prevents duplicate IDs.
  */
 import type { DocumentationDocument, DocumentationProvider } from "../docsTypes/index.js";
+/** Visibility filter accepted by `getAll` and the generators. */
+export type DocumentVisibilityFilter = "SERVER" | "CLIENT" | "ALL";
+/** Options for `DocumentRegistry.getAll`. */
+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.
+     */
+    readonly visibility?: DocumentVisibilityFilter;
+}
+/**
+ * Returns true when `document` should be included for the given filter.
+ */
+export declare function matchesVisibility(document: DocumentationDocument, filter?: DocumentVisibilityFilter): boolean;
 /**
  * Registry for managing documentation documents.
+ *
+ * Registered documents are stored as deep-frozen copies, so the
+ * caller's object is never mutated and later changes to it do not
+ * leak into the registry.
  */
 export declare class DocumentRegistry implements DocumentationProvider {
     private readonly documents;
     /**
-     * Registers a document. Throws if the ID is already registered.
+     * Registers a document.
+     *
+     * @throws {DuplicateDocumentError} if the ID is already registered.
      */
     register(document: DocumentationDocument): void;
     /**
@@ -23,9 +44,9 @@ export declare class DocumentRegistry implements DocumentationProvider {
      */
     get(id: string): DocumentationDocument | undefined;
     /**
-     * Returns all registered documents.
+     * Returns all registered documents, optionally filtered by visibility.
      */
-    getAll(): readonly DocumentationDocument[];
+    getAll(options?: GetAllOptions): readonly DocumentationDocument[];
     /**
      * Returns the number of registered documents.
      */
@@ -46,6 +67,11 @@ export declare class DocumentRegistry implements DocumentationProvider {
      * Returns all document IDs.
      */
     ids(): readonly string[];
+    /**
+     * Returns the registered IDs as a set, suitable for `validateLinks`
+     * and `validateNavigation`.
+     */
+    idSet(): ReadonlySet<string>;
     /**
      * Filters documents by category.
      */

package/dist/registry/registry.core.js

@@ -4,19 +4,37 @@
  * Provides registration, retrieval, and iteration over
  * documentation documents. Prevents duplicate IDs.
  */
+import { DuplicateDocumentError } from "@zudojs/errors";
+import { deepFreezeClone } from "../utils/utils.freeze.js";
+/**
+ * Returns true when `document` should be included for the given filter.
+ */
+export function matchesVisibility(document, filter = "ALL") {
+    if (filter === "ALL")
+        return true;
+    if (filter === "SERVER")
+        return document.visibility === "SERVER";
+    return document.visibility !== "SERVER";
+}
 /**
  * Registry for managing documentation documents.
+ *
+ * Registered documents are stored as deep-frozen copies, so the
+ * caller's object is never mutated and later changes to it do not
+ * leak into the registry.
  */
 export class DocumentRegistry {
     documents = new Map();
     /**
-     * Registers a document. Throws if the ID is already registered.
+     * Registers a document.
+     *
+     * @throws {DuplicateDocumentError} if the ID is already registered.
      */
     register(document) {
         if (this.documents.has(document.id)) {
-            throw new Error(`Duplicate document ID: "${document.id}".`);
+            throw new DuplicateDocumentError(document.id);
         }
-        this.documents.set(document.id, Object.freeze(document));
+        this.documents.set(document.id, deepFreezeClone(document));
     }
     /**
      * Registers multiple documents.
@@ -33,10 +51,11 @@ export class DocumentRegistry {
         return this.documents.get(id);
     }
     /**
-     * Returns all registered documents.
+     * Returns all registered documents, optionally filtered by visibility.
      */
-    getAll() {
-        return Object.freeze([...this.documents.values()]);
+    getAll(options = {}) {
+        const filter = options.visibility ?? "ALL";
+        return Object.freeze([...this.documents.values()].filter((doc) => matchesVisibility(doc, filter)));
     }
     /**
      * Returns the number of registered documents.
@@ -68,6 +87,13 @@ export class DocumentRegistry {
     ids() {
         return Object.freeze([...this.documents.keys()]);
     }
+    /**
+     * Returns the registered IDs as a set, suitable for `validateLinks`
+     * and `validateNavigation`.
+     */
+    idSet() {
+        return new Set(this.documents.keys());
+    }
     /**
      * Filters documents by category.
      */

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

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

package/dist/utils/utils.freeze.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Deep-freeze helpers for immutable value objects.
+ */
+/**
+ * Recursively freezes a value in place. Cycles are tolerated.
+ * Only plain objects and arrays are traversed; class instances such
+ * as `Date` are frozen but not walked.
+ */
+export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;
+/**
+ * Returns a deep-frozen copy of `value`, leaving the caller's object
+ * untouched. Falls back to freezing a shallow copy when the value
+ * cannot be structurally cloned (e.g. contains functions).
+ */
+export declare function deepFreezeClone<T>(value: T): T;
+//# sourceMappingURL=utils.freeze.d.ts.map

package/dist/utils/utils.freeze.js

@@ -0,0 +1,53 @@
+/**
+ * Deep-freeze helpers for immutable value objects.
+ */
+/**
+ * Recursively freezes a value in place. Cycles are tolerated.
+ * Only plain objects and arrays are traversed; class instances such
+ * as `Date` are frozen but not walked.
+ */
+export function deepFreeze(value, seen = new WeakSet()) {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return value;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreeze(item, seen);
+    }
+    else if (isPlainObject(value)) {
+        for (const item of Object.values(value))
+            deepFreeze(item, seen);
+    }
+    return Object.freeze(value);
+}
+/**
+ * Returns a deep-frozen copy of `value`, leaving the caller's object
+ * untouched. Falls back to freezing a shallow copy when the value
+ * cannot be structurally cloned (e.g. contains functions).
+ */
+export function deepFreezeClone(value) {
+    let copy;
+    try {
+        copy = structuredClone(value);
+    }
+    catch {
+        copy = shallowCopy(value);
+    }
+    return deepFreeze(copy);
+}
+function shallowCopy(value) {
+    if (Array.isArray(value))
+        return [...value];
+    if (isPlainObject(value))
+        return { ...value };
+    return value;
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+//# sourceMappingURL=utils.freeze.js.map

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

@@ -1,27 +1,50 @@
 /**
  * Utility helpers for the documentation package.
  */
+/**
+ * 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 declare function isValidDocumentId(id: string): boolean;
 /**
  * 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 declare function normalizeDocumentId(id: string): string;
 /**
  * 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 declare function documentIdFromPath(path: string): string;
 /**
  * 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 declare function resolveDocumentLink(baseId: string, link: string): string;
 /**
- * Extracts the title from markdown content (first heading).
+ * Removes a `#fragment`, a trailing `.md`/`.mdx` extension and
+ * converts `\` to `/` in a link target.
+ */
+export declare function stripLinkDecorations(link: string): string;
+/**
+ * Removes fenced code blocks (``` or ~~~) from markdown so that
+ * headings and links inside them are not interpreted.
+ */
+export declare function stripFencedCodeBlocks(markdown: string): string;
+/**
+ * Extracts the title from markdown content (first level-1 heading
+ * outside fenced code blocks).
  */
 export declare function extractTitleFromMarkdown(markdown: string): string | undefined;
 /**
- * Extracts headings from markdown content.
+ * Extracts headings from markdown content (outside fenced code blocks).
  */
 export declare function extractHeadings(markdown: string): readonly {
     level: number;