@zudojs/docs 0.0.1 → 1.0.0

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

package/dist/validator/validatorDocument.core.js

@@ -1,45 +1,227 @@
 /**
  * Validates a single document for structural correctness.
  */
+import { isValidDocumentId } from "../utils/utils.helper.js";
+import { toValidationResult, } from "./validator.types.js";
+const CONTENT_TYPES = new Set(["markdown", "mdx", "html", "structured"]);
+const STATUSES = new Set([
+    "stable",
+    "experimental",
+    "beta",
+    "deprecated",
+    "internal",
+]);
+const CATEGORIES = new Set([
+    "introduction",
+    "guide",
+    "tutorial",
+    "reference",
+    "api",
+    "architecture",
+    "configuration",
+    "deployment",
+    "security",
+    "migration",
+    "examples",
+]);
+const VISIBILITIES = new Set(["SERVER", "CLIENT"]);
+const NODE_TYPES = new Set([
+    "heading",
+    "paragraph",
+    "code",
+    "list",
+    "link",
+    "table",
+    "quote",
+    "callout",
+]);
+const CALLOUT_KINDS = new Set(["note", "warning", "tip", "danger"]);
 /**
- * Validates a single document.
+ * Validates a single document: ID syntax, required fields, content
+ * shape (including structured nodes), and the metadata enums.
  */
 export function validateDocument(document) {
     const issues = [];
-    if (!document.id || document.id.trim().length === 0) {
+    const id = document.id;
+    if (typeof id !== "string" || id.trim().length === 0) {
         issues.push({
             severity: "error",
             code: "MISSING_ID",
             message: "Document ID is required.",
         });
     }
-    if (!document.title || document.title.trim().length === 0) {
+    else if (!isValidDocumentId(id)) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_ID",
+            message: `Document ID "${id}" is invalid. Use dot-separated segments of letters, digits, "_" and "-".`,
+            documentId: id,
+        });
+    }
+    if (typeof document.title !== "string" || document.title.trim().length === 0) {
         issues.push({
             severity: "error",
             code: "MISSING_TITLE",
-            message: `Document "${document.id}" is missing a title.`,
-            documentId: document.id,
+            message: `Document "${id}" is missing a title.`,
+            documentId: id,
         });
     }
-    if (!document.content) {
+    validateContent(document, issues);
+    if (document.status !== undefined && !STATUSES.has(document.status)) {
         issues.push({
             severity: "error",
-            code: "MISSING_CONTENT",
-            message: `Document "${document.id}" is missing content.`,
-            documentId: document.id,
+            code: "INVALID_STATUS",
+            message: `Document "${id}" has unknown status "${String(document.status)}".`,
+            documentId: id,
+        });
+    }
+    if (document.category !== undefined && !CATEGORIES.has(document.category)) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_CATEGORY",
+            message: `Document "${id}" has unknown category "${String(document.category)}".`,
+            documentId: id,
+        });
+    }
+    if (document.visibility !== undefined &&
+        !VISIBILITIES.has(document.visibility)) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_VISIBILITY",
+            message: `Document "${id}" has unknown visibility "${String(document.visibility)}".`,
+            documentId: id,
+        });
+    }
+    if (document.tags !== undefined &&
+        (!Array.isArray(document.tags) ||
+            document.tags.some((tag) => typeof tag !== "string" || tag.trim() === ""))) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_TAGS",
+            message: `Document "${id}" has tags that are not non-empty strings.`,
+            documentId: id,
         });
     }
     if (document.deprecated && !document.deprecatedMessage) {
         issues.push({
             severity: "warning",
             code: "DEPRECATED_WITHOUT_MESSAGE",
-            message: `Document "${document.id}" is deprecated but has no deprecation message.`,
-            documentId: document.id,
+            message: `Document "${id}" is deprecated but has no deprecation message.`,
+            documentId: id,
+        });
+    }
+    if ((document.status === "deprecated") !== Boolean(document.deprecated) &&
+        (document.status === "deprecated" || document.deprecated)) {
+        issues.push({
+            severity: "warning",
+            code: "DEPRECATION_MISMATCH",
+            message: `Document "${id}" has status "${document.status ?? "unset"}" but deprecated=${String(Boolean(document.deprecated))}.`,
+            documentId: id,
+        });
+    }
+    return toValidationResult(issues);
+}
+function validateContent(document, issues) {
+    const id = document.id;
+    const content = document.content;
+    if (!content || typeof content !== "object") {
+        issues.push({
+            severity: "error",
+            code: "MISSING_CONTENT",
+            message: `Document "${id}" is missing content.`,
+            documentId: id,
+        });
+        return;
+    }
+    const type = content.type;
+    if (typeof type !== "string" || !CONTENT_TYPES.has(type)) {
+        issues.push({
+            severity: "error",
+            code: "INVALID_CONTENT_TYPE",
+            message: `Document "${id}" has unknown content type "${String(type)}".`,
+            documentId: id,
+        });
+        return;
+    }
+    if (type === "structured") {
+        const nodes = content.nodes;
+        if (!Array.isArray(nodes)) {
+            issues.push({
+                severity: "error",
+                code: "INVALID_NODE",
+                message: `Document "${id}" structured content must have a "nodes" array.`,
+                documentId: id,
+            });
+            return;
+        }
+        nodes.forEach((node, index) => {
+            const problem = describeNodeProblem(node);
+            if (problem) {
+                issues.push({
+                    severity: "error",
+                    code: "INVALID_NODE",
+                    message: `Document "${id}" node ${index}: ${problem}`,
+                    documentId: id,
+                });
+            }
+        });
+        return;
+    }
+    if (typeof content.value !== "string") {
+        issues.push({
+            severity: "error",
+            code: "INVALID_CONTENT_TYPE",
+            message: `Document "${id}" ${type} content must have a string "value".`,
+            documentId: id,
         });
     }
-    return {
-        valid: issues.filter((i) => i.severity === "error").length === 0,
-        issues,
-    };
+}
+/** Returns a description of what is wrong with a node, or undefined. */
+function describeNodeProblem(node) {
+    if (!node || typeof node !== "object")
+        return "node is not an object.";
+    const n = node;
+    if (typeof n.type !== "string" || !NODE_TYPES.has(n.type)) {
+        return `unknown node type "${String(n.type)}".`;
+    }
+    const isString = (v) => typeof v === "string";
+    const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+    switch (n.type) {
+        case "heading":
+            if (!Number.isInteger(n.level) || n.level < 1 || n.level > 6) {
+                return "heading level must be an integer from 1 to 6.";
+            }
+            return isString(n.value) ? undefined : "heading value must be a string.";
+        case "paragraph":
+        case "quote":
+            return isString(n.value) ? undefined : `${n.type} value must be a string.`;
+        case "code":
+            if (n.language !== undefined && !isString(n.language)) {
+                return "code language must be a string.";
+            }
+            return isString(n.value) ? undefined : "code value must be a string.";
+        case "list":
+            if (typeof n.ordered !== "boolean")
+                return "list ordered must be a boolean.";
+            return isStringArray(n.items) ? undefined : "list items must be strings.";
+        case "link":
+            if (!isString(n.href))
+                return "link href must be a string.";
+            return isString(n.value) ? undefined : "link value must be a string.";
+        case "table":
+            if (!isStringArray(n.headers))
+                return "table headers must be strings.";
+            if (!Array.isArray(n.rows) || !n.rows.every(isStringArray)) {
+                return "table rows must be arrays of strings.";
+            }
+            return undefined;
+        case "callout":
+            if (!isString(n.kind) || !CALLOUT_KINDS.has(n.kind)) {
+                return `unknown callout kind "${String(n.kind)}".`;
+            }
+            return isString(n.value) ? undefined : "callout value must be a string.";
+        default:
+            return undefined;
+    }
 }
 //# sourceMappingURL=validatorDocument.core.js.map

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

@@ -2,7 +2,7 @@
  * Validates that no documents share the same ID.
  */
 import type { DocumentationDocument } from "../docsTypes/index.js";
-import type { ValidationResult } from "./validator.types.js";
+import { type ValidationResult } from "./validator.types.js";
 /**
  * Validates no duplicate IDs exist in a collection of documents.
  */

package/dist/validator/validatorDuplicates.core.js

@@ -1,11 +1,12 @@
 /**
  * Validates that no documents share the same ID.
  */
+import { toValidationResult, } from "./validator.types.js";
 /**
  * Validates no duplicate IDs exist in a collection of documents.
  */
 export function validateNoDuplicateIds(documents) {
-    const seen = new Map();
+    const seen = new Set();
     const issues = [];
     for (const doc of documents) {
         if (seen.has(doc.id)) {
@@ -17,12 +18,9 @@ export function validateNoDuplicateIds(documents) {
             });
         }
         else {
-            seen.set(doc.id, doc.title);
+            seen.add(doc.id);
         }
     }
-    return {
-        valid: issues.length === 0,
-        issues,
-    };
+    return toValidationResult(issues);
 }
 //# sourceMappingURL=validatorDuplicates.core.js.map

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

@@ -1,10 +1,28 @@
 /**
- * Validates internal links within markdown documentation.
+ * Validates internal links within markdown and structured documentation.
  */
 import type { DocumentationDocument } from "../docsTypes/index.js";
-import type { ValidationResult } from "./validator.types.js";
+import { type ValidationResult } from "./validator.types.js";
+/** Default maximum markdown length that is scanned for links. */
+export declare const DEFAULT_MAX_LINK_SCAN_LENGTH = 100000;
+/** Options for `validateLinks`. */
+export interface ValidateLinksOptions {
+    /**
+     * Markdown longer than this (in characters) is not scanned; a
+     * `LINK_VALIDATION_SKIPPED` warning is reported instead.
+     * Defaults to {@link DEFAULT_MAX_LINK_SCAN_LENGTH}.
+     */
+    readonly maxContentLength?: number;
+}
 /**
- * Validates internal links in a document's markdown content.
+ * Validates internal links in a document's markdown content and in
+ * structured `link` nodes.
+ *
+ * Skipped (never reported): images, anchors (`#…`), any target 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
+ * both as-is and resolved.
  */
-export declare function validateLinks(document: DocumentationDocument, registeredIds: ReadonlySet<string>): ValidationResult;
+export declare function validateLinks(document: DocumentationDocument, registeredIds: ReadonlySet<string>, options?: ValidateLinksOptions): ValidationResult;
 //# sourceMappingURL=validatorLinks.core.d.ts.map