@blogmcp/nav-core 0.1.0

package/dist/validate/index.js

@@ -0,0 +1,175 @@
+/**
+ * @blogmcp/nav-core — validate
+ *
+ * Structural validation of a navigation tree. Server-authoritative: the API
+ * layer re-runs this on every mutation (clients can't be trusted not to create
+ * a cycle / oversized data bag). nav-core never *interprets* the `data` bag — it
+ * only enforces size/depth caps so the JSONB-source-of-truth stays a small,
+ * one-row-read, cacheable artifact (see navigation-model.md §2, §4).
+ */
+import { CONTAINER_NODE_TYPES, NAV_NODE_TYPES, } from '../types/index.js';
+/** Default caps. Override per call via {@link ValidateOptions}. */
+export const DEFAULT_MAX_DEPTH = 6;
+export const DEFAULT_MAX_DATA_BYTES = 4096;
+export const DEFAULT_MAX_DATA_DEPTH = 8;
+/**
+ * Validate a navigation tree. Returns all errors found (does not throw); callers
+ * that prefer to throw can use {@link assertValid}.
+ */
+export function validate(tree, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxDataBytes = options.maxDataBytes ?? DEFAULT_MAX_DATA_BYTES;
+    const maxDataDepth = options.maxDataDepth ?? DEFAULT_MAX_DATA_DEPTH;
+    const errors = [];
+    const seenIds = new Set();
+    /** ref → count of owned:true nodes, to enforce at most one owner per article. */
+    const ownerCounts = new Map();
+    const visit = (node, depth) => {
+        // id present + unique
+        if (!node.id) {
+            errors.push({ code: 'MISSING_ID', message: `Node of type "${node.type}" is missing an id.` });
+        }
+        else if (seenIds.has(node.id)) {
+            errors.push({ code: 'DUPLICATE_ID', message: `Duplicate node id "${node.id}".`, nodeId: node.id });
+        }
+        else {
+            seenIds.add(node.id);
+        }
+        // known type
+        if (!NAV_NODE_TYPES.includes(node.type)) {
+            errors.push({ code: 'UNKNOWN_TYPE', message: `Unknown node type "${node.type}".`, nodeId: node.id });
+        }
+        // depth
+        if (depth > maxDepth) {
+            errors.push({
+                code: 'MAX_DEPTH_EXCEEDED',
+                message: `Node "${node.id}" at depth ${depth} exceeds max depth ${maxDepth}.`,
+                nodeId: node.id,
+            });
+        }
+        // order must be a finite number when present
+        if (node.order !== undefined && !Number.isFinite(node.order)) {
+            errors.push({ code: 'INVALID_ORDER', message: `Node "${node.id}" has a non-finite order.`, nodeId: node.id });
+        }
+        // type-specific required fields
+        validateRequiredFields(node, errors);
+        // children only on container types
+        const children = node.children ?? [];
+        if (children.length > 0 && !CONTAINER_NODE_TYPES.includes(node.type)) {
+            errors.push({
+                code: 'CHILDREN_NOT_ALLOWED',
+                message: `Node "${node.id}" of type "${node.type}" cannot have children.`,
+                nodeId: node.id,
+            });
+        }
+        // owner accounting
+        if (node.type === 'article-ref' && node.owned === true) {
+            ownerCounts.set(node.ref, (ownerCounts.get(node.ref) ?? 0) + 1);
+        }
+        // data bag caps
+        if (node.data !== undefined) {
+            validateDataBag(node, maxDataBytes, maxDataDepth, errors);
+        }
+        for (const child of children) {
+            visit(child, depth + 1);
+        }
+    };
+    for (const root of tree) {
+        visit(root, 0);
+    }
+    for (const [ref, count] of ownerCounts) {
+        if (count > 1) {
+            errors.push({
+                code: 'MULTIPLE_OWNERS',
+                message: `Article "${ref}" is marked owned by ${count} nodes; at most one location may own an article.`,
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/** Throwing variant. */
+export function assertValid(tree, options) {
+    const result = validate(tree, options);
+    if (!result.valid) {
+        const summary = result.errors.map((e) => `${e.code}: ${e.message}`).join('; ');
+        throw new NavValidationError(summary, result.errors);
+    }
+}
+/** Error thrown by {@link assertValid}. */
+export class NavValidationError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors;
+        this.name = 'NavValidationError';
+    }
+}
+function validateRequiredFields(node, errors) {
+    switch (node.type) {
+        case 'article-ref':
+            if (!node.ref) {
+                errors.push({ code: 'MISSING_REQUIRED_FIELD', message: `article-ref "${node.id}" is missing "ref".`, nodeId: node.id });
+            }
+            break;
+        case 'external-link':
+            if (!node.href) {
+                errors.push({ code: 'MISSING_REQUIRED_FIELD', message: `external-link "${node.id}" is missing "href".`, nodeId: node.id });
+            }
+            break;
+        case 'generated-section':
+            if (!node.slug) {
+                errors.push({ code: 'MISSING_REQUIRED_FIELD', message: `generated-section "${node.id}" is missing "slug".`, nodeId: node.id });
+            }
+            if (!node.query) {
+                errors.push({ code: 'MISSING_REQUIRED_FIELD', message: `generated-section "${node.id}" is missing "query".`, nodeId: node.id });
+            }
+            break;
+        case 'group':
+        case 'separator':
+            break;
+    }
+}
+function validateDataBag(node, maxBytes, maxDepth, errors) {
+    const data = node.data;
+    // byte size (UTF-8) of the serialized bag
+    let serialized;
+    try {
+        serialized = JSON.stringify(data) ?? '';
+    }
+    catch {
+        serialized = '';
+    }
+    const bytes = utf8ByteLength(serialized);
+    if (bytes > maxBytes) {
+        errors.push({
+            code: 'DATA_TOO_LARGE',
+            message: `Node "${node.id}" data bag is ${bytes} bytes, exceeding the ${maxBytes}-byte cap. Large payloads belong on the article, not the nav node.`,
+            nodeId: node.id,
+        });
+    }
+    const depth = jsonDepth(data);
+    if (depth > maxDepth) {
+        errors.push({
+            code: 'DATA_TOO_DEEP',
+            message: `Node "${node.id}" data bag nests ${depth} levels, exceeding the ${maxDepth}-level cap.`,
+            nodeId: node.id,
+        });
+    }
+}
+function utf8ByteLength(s) {
+    // Avoid a hard dependency on Node's Buffer for portability (SDK/browser reuse).
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder().encode(s).length;
+    }
+    return s.length;
+}
+function jsonDepth(value, current = 1) {
+    if (value === null || typeof value !== 'object')
+        return current;
+    let max = current;
+    for (const v of Object.values(value)) {
+        max = Math.max(max, jsonDepth(v, current + 1));
+    }
+    return max;
+}
+//# sourceMappingURL=index.js.map

package/dist/validate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validate/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@blogmcp/nav-core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic navigation tree core — types, validation, traversal, and immutable mutations for the KB information-architecture (menu) layer. Zero framework dependencies; consumed by the API service, MCP tools, and the blog SDK.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./src/types/index.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./validate": {
+      "types": "./src/validate/index.ts",
+      "import": "./dist/validate/index.js"
+    },
+    "./traverse": {
+      "types": "./src/traverse/index.ts",
+      "import": "./dist/traverse/index.js"
+    },
+    "./mutate": {
+      "types": "./src/mutate/index.ts",
+      "import": "./dist/mutate/index.js"
+    },
+    "./resolve": {
+      "types": "./src/resolve/index.ts",
+      "import": "./dist/resolve/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "navigation",
+    "menu",
+    "tree",
+    "information-architecture",
+    "blog"
+  ],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @blogmcp/nav-core
+ *
+ * Framework-agnostic core for the KB navigation (menu) tree: the node-model
+ * contract, structural validation, pure traversal, and immutable mutations.
+ * Pure TypeScript — no I/O, no framework. Consumed by the KB API service, the
+ * MCP nav tools, and the blog SDK.
+ *
+ * What lives here: types, validate, traverse, mutate, and resolve (the
+ * content→default-tree auto-builder + the auto-build⊕overrides merge). See
+ * competitor-monitor/docs/internal/navigation-model.md §2, §4, §9.
+ */
+
+export * from './types/index.js';
+export * from './validate/index.js';
+export * from './traverse/index.js';
+export * from './mutate/index.js';
+export * from './resolve/index.js';

package/src/mutate/index.ts

@@ -0,0 +1,162 @@
+/**
+ * @blogmcp/nav-core — mutate
+ *
+ * Immutable tree mutations. Every function returns a NEW tree and never edits
+ * its input. These back both the optimistic client-side apply (SDK) and the
+ * server-authoritative MCP/API tools — the server always re-runs `validate()`
+ * after a mutation (see navigation-model.md §5).
+ *
+ * Invalid operations throw {@link NavMutationError} (e.g. unknown id, or moving
+ * a node into its own descendant).
+ */
+
+import { findNode, walk } from '../traverse/index.js';
+import type { NavNode, NavTree } from '../types/index.js';
+
+export class NavMutationError extends Error {
+  constructor(message: string, public readonly code: NavMutationCode) {
+    super(message);
+    this.name = 'NavMutationError';
+  }
+}
+
+export type NavMutationCode =
+  | 'NODE_NOT_FOUND'
+  | 'PARENT_NOT_FOUND'
+  | 'DUPLICATE_ID'
+  | 'CYCLE'
+  | 'NOT_A_CONTAINER';
+
+export interface InsertOptions {
+  /** Parent id, or null/undefined to insert at the root level. */
+  readonly parentId?: string | null;
+  /** Position among target siblings; clamped to [0, len]. Defaults to end. */
+  readonly index?: number;
+}
+
+/** Insert a (sub)tree. Throws if the id already exists or the parent is missing. */
+export function insertNode(tree: NavTree, node: NavNode, options: InsertOptions = {}): NavNode[] {
+  if (findNode(tree, node.id)) {
+    throw new NavMutationError(`Node "${node.id}" already exists.`, 'DUPLICATE_ID');
+  }
+  const { parentId = null, index } = options;
+
+  if (parentId === null) {
+    return insertAt([...tree], node, index);
+  }
+  if (!findNode(tree, parentId)) {
+    throw new NavMutationError(`Parent "${parentId}" not found.`, 'PARENT_NOT_FOUND');
+  }
+  return mapInto(tree, parentId, (children) => insertAt([...children], node, index));
+}
+
+/** Remove a node and its subtree. Throws if the node is not found. */
+export function removeNode(tree: NavTree, id: string): NavNode[] {
+  if (!findNode(tree, id)) {
+    throw new NavMutationError(`Node "${id}" not found.`, 'NODE_NOT_FOUND');
+  }
+  const recur = (nodes: readonly NavNode[]): NavNode[] =>
+    nodes
+      .filter((n) => n.id !== id)
+      .map((n) => (n.children ? ({ ...n, children: recur(n.children) } as NavNode) : n));
+  return recur(tree);
+}
+
+export interface MoveOptions {
+  /** New parent id, or null for the root level. */
+  readonly parentId?: string | null;
+  /** Position among the new siblings; clamped. Defaults to end. */
+  readonly index?: number;
+}
+
+/** Move a node (with its subtree) under a new parent. Throws on cycles. */
+export function moveNode(tree: NavTree, id: string, options: MoveOptions = {}): NavNode[] {
+  const node = findNode(tree, id);
+  if (!node) {
+    throw new NavMutationError(`Node "${id}" not found.`, 'NODE_NOT_FOUND');
+  }
+  const { parentId = null, index } = options;
+
+  if (parentId !== null) {
+    if (parentId === id) {
+      throw new NavMutationError(`Cannot move node "${id}" into itself.`, 'CYCLE');
+    }
+    if (descendantIds(node).has(parentId)) {
+      throw new NavMutationError(`Cannot move node "${id}" into its own descendant "${parentId}".`, 'CYCLE');
+    }
+    if (!findNode(tree, parentId)) {
+      throw new NavMutationError(`Parent "${parentId}" not found.`, 'PARENT_NOT_FOUND');
+    }
+  }
+
+  const detached = removeNode(tree, id);
+  return insertNode(detached, node, { parentId, index });
+}
+
+/**
+ * Reorder a parent's children to match `orderedIds`, reassigning each child's
+ * `order` to its new index. Ids present in the tree but absent from `orderedIds`
+ * keep their relative order at the end. Throws on unknown ids or missing parent.
+ */
+export function reorderChildren(tree: NavTree, parentId: string | null, orderedIds: readonly string[]): NavNode[] {
+  const apply = (children: readonly NavNode[]): NavNode[] => {
+    const byId = new Map(children.map((c) => [c.id, c]));
+    for (const oid of orderedIds) {
+      if (!byId.has(oid)) {
+        throw new NavMutationError(`Cannot reorder: "${oid}" is not a child of "${parentId ?? '<root>'}".`, 'NODE_NOT_FOUND');
+      }
+    }
+    const ordered = [
+      ...orderedIds.map((oid) => byId.get(oid)!),
+      ...children.filter((c) => !orderedIds.includes(c.id)),
+    ];
+    return ordered.map((child, i) => ({ ...child, order: i }) as NavNode);
+  };
+
+  if (parentId === null) {
+    return apply(tree);
+  }
+  if (!findNode(tree, parentId)) {
+    throw new NavMutationError(`Parent "${parentId}" not found.`, 'PARENT_NOT_FOUND');
+  }
+  return mapInto(tree, parentId, apply);
+}
+
+/* -------------------------------------------------------------------------- */
+/* helpers                                                                     */
+/* -------------------------------------------------------------------------- */
+
+function insertAt(siblings: NavNode[], node: NavNode, index?: number): NavNode[] {
+  const at = index === undefined ? siblings.length : clamp(index, 0, siblings.length);
+  siblings.splice(at, 0, node);
+  return siblings;
+}
+
+/** Rebuild the tree, replacing the children array of the node with id === targetId. */
+function mapInto(
+  tree: NavTree,
+  targetId: string,
+  transform: (children: readonly NavNode[]) => NavNode[],
+): NavNode[] {
+  return tree.map((node) => {
+    if (node.id === targetId) {
+      return { ...node, children: transform(node.children ?? []) } as NavNode;
+    }
+    if (node.children) {
+      return { ...node, children: mapInto(node.children, targetId, transform) } as NavNode;
+    }
+    return node;
+  });
+}
+
+function descendantIds(node: NavNode): Set<string> {
+  const ids = new Set<string>();
+  walk(node.children ?? [], (n) => {
+    ids.add(n.id);
+  });
+  return ids;
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, n));
+}