@blogmcp/nav-core 0.1.0

package/src/types/index.ts

@@ -0,0 +1,206 @@
+/**
+ * @blogmcp/nav-core — types
+ *
+ * The framework-agnostic contract for the KB navigation (menu) tree.
+ * See competitor-monitor/docs/internal/navigation-model.md §4 for the design.
+ *
+ * Design invariants encoded here:
+ *  - Stable UUID per node (deep links / anchored comments / moves survive reorder).
+ *  - Discriminated `type` union: article-ref | group | external-link |
+ *    generated-section | separator.
+ *  - Single multilingual tree: per-node `labels` map keyed by locale; the
+ *    referenced article's title is the default (resolved by the consumer via a
+ *    `labelResolver`, since nav-core does not know article content).
+ *  - `badge` and `icon` are typed first-class (Starlight precedent); everything
+ *    else genuinely arbitrary lives in the opaque, size-capped `data` bag.
+ *  - Trees are treated as immutable: every node/collection is `readonly`, and the
+ *    mutate module returns new trees rather than editing in place.
+ */
+
+/** Discriminator for {@link NavNode}. */
+export type NavNodeType =
+  | 'article-ref'
+  | 'group'
+  | 'external-link'
+  | 'generated-section'
+  | 'separator';
+
+/** All node type discriminators, for runtime validation. */
+export const NAV_NODE_TYPES: readonly NavNodeType[] = [
+  'article-ref',
+  'group',
+  'external-link',
+  'generated-section',
+  'separator',
+];
+
+/** BCP-47 / language code, e.g. `cs`, `en`, `pt-BR`. */
+export type Locale = string;
+
+/** Per-locale label overrides. Missing locales fall back (see localize). */
+export type LocaleLabels = Readonly<Record<Locale, string>>;
+
+/**
+ * Typed first-class presentation hint. Mirrors Astro Starlight's `badge`.
+ * `variant` is intentionally open (`string`) so themes can define their own.
+ */
+export interface BadgeSpec {
+  readonly text: string;
+  readonly variant?: string;
+  readonly class?: string;
+}
+
+/**
+ * Access-tier gating. nav-core stays policy-free: it only carries the declared
+ * tiers; consumers decide what a viewer may see (e.g. via {@link prune}).
+ * Omitted = inherit from ancestor / public.
+ */
+export interface Visibility {
+  readonly tiers?: readonly string[];
+}
+
+/**
+ * Opaque, namespaced customer extension bag. The platform stores and round-trips
+ * it but never interprets it. Size/depth-capped by {@link validate}. Renderers
+ * must treat values as untrusted.
+ */
+export type NavData = Readonly<Record<string, unknown>>;
+
+/** Fields shared by every node type. */
+export interface NavNodeBase {
+  /** Stable UUID. Unique across the whole tree. */
+  readonly id: string;
+  /** Sibling sort key. Fractional, so a node can be inserted between two siblings without renumbering. */
+  readonly order?: number;
+  /** Per-locale label overrides. */
+  readonly labels?: LocaleLabels;
+  /** Typed first-class badge hint. */
+  readonly badge?: BadgeSpec;
+  /** Typed first-class icon hint (icon name/key; renderer maps it). */
+  readonly icon?: string;
+  /** Reachable by direct URL but suppressed from this menu. Distinct from access-tier {@link visibility}. */
+  readonly hidden?: boolean;
+  /** Access-tier gating. */
+  readonly visibility?: Visibility;
+  /** Opaque customer extension bag. */
+  readonly data?: NavData;
+  /** Child nodes. Only `group` and `article-ref` may have children. */
+  readonly children?: readonly NavNode[];
+}
+
+/** References a `kb_articles.id`. */
+export interface ArticleRefNode extends NavNodeBase {
+  readonly type: 'article-ref';
+  /** `kb_articles.id`. */
+  readonly ref: string;
+  /** Public URL handle (filename without extension) — lets consumers build links without a second lookup. */
+  readonly slug?: string;
+  /**
+   * Exactly one nav location should *own* an article (drives prev/next pagination
+   * and the canonical breadcrumb). Other locations referencing the same article
+   * set `owned: false` (Docusaurus `doc` vs `ref`).
+   */
+  readonly owned?: boolean;
+}
+
+/** Optional clickable target for a {@link GroupNode} heading. */
+export type GroupLink =
+  | { readonly kind: 'article'; readonly ref: string }
+  | { readonly kind: 'generated'; readonly slug: string };
+
+/** A section. May be a clickable heading and may collapse. */
+export interface GroupNode extends NavNodeBase {
+  readonly type: 'group';
+  /** Optional clickable section heading (existing article or a generated-section). */
+  readonly link?: GroupLink;
+  /** Default open/closed state. */
+  readonly collapsed?: boolean;
+  /** Whether the group can be collapsed at all. */
+  readonly collapsible?: boolean;
+}
+
+/** Arbitrary external URL. Override-only — auto-build never emits these. */
+export interface ExternalLinkNode extends NavNodeBase {
+  readonly type: 'external-link';
+  readonly href: string;
+}
+
+/** Query backing a {@link GeneratedSectionNode}. Open shape; `tag` is the v1 case. */
+export interface GeneratedQuery {
+  readonly tag?: string;
+  readonly [key: string]: unknown;
+}
+
+/** A section resolved at read time (e.g. "all articles tagged X"). */
+export interface GeneratedSectionNode extends NavNodeBase {
+  readonly type: 'generated-section';
+  /** URL slug of the generated landing page. */
+  readonly slug: string;
+  /** Query that selects the members. */
+  readonly query: GeneratedQuery;
+  readonly title?: string;
+  readonly description?: string;
+}
+
+/** Pure visual divider. Leaf node. */
+export interface SeparatorNode extends NavNodeBase {
+  readonly type: 'separator';
+}
+
+/** Any navigation node. */
+export type NavNode =
+  | ArticleRefNode
+  | GroupNode
+  | ExternalLinkNode
+  | GeneratedSectionNode
+  | SeparatorNode;
+
+/** A navigation tree is an ordered list of root nodes. */
+export type NavTree = readonly NavNode[];
+
+/** Node types that are allowed to have children. */
+export const CONTAINER_NODE_TYPES: readonly NavNodeType[] = ['group', 'article-ref'];
+
+/* --------------------------------------------------------------------------
+ * Flattened (FLAT) representation — agent- and diff-friendly.
+ * ------------------------------------------------------------------------ */
+
+/** One node in FLAT form: parent pointer + depth instead of nesting. */
+export interface FlatNode {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly type: NavNodeType;
+  /** 0-based position among siblings (post-sort). */
+  readonly index: number;
+  /** Depth from root (root nodes = 0). */
+  readonly depth: number;
+}
+
+/* --------------------------------------------------------------------------
+ * Localized representation — labels resolved to a single locale.
+ * ------------------------------------------------------------------------ */
+
+/** A node with its label resolved to one locale (no `labels` map). */
+export interface LocalizedNode {
+  readonly id: string;
+  readonly type: NavNodeType;
+  /** Resolved label for the requested locale, if any could be determined. */
+  readonly label?: string;
+  readonly order?: number;
+  readonly badge?: BadgeSpec;
+  readonly icon?: string;
+  readonly hidden?: boolean;
+  readonly visibility?: Visibility;
+  readonly data?: NavData;
+  /** Carried through for renderers (ref/href/slug/link/collapsed…). */
+  readonly ref?: string;
+  readonly owned?: boolean;
+  readonly href?: string;
+  readonly slug?: string;
+  readonly link?: GroupLink;
+  readonly collapsed?: boolean;
+  readonly collapsible?: boolean;
+  readonly children: readonly LocalizedNode[];
+}
+
+export type LocalizedTree = readonly LocalizedNode[];

package/src/validate/index.ts

@@ -0,0 +1,233 @@
+/**
+ * @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,
+  type NavNode,
+  type NavTree,
+} 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;
+
+export interface ValidateOptions {
+  /** Max nesting depth (root nodes are depth 0). */
+  readonly maxDepth?: number;
+  /** Max serialized byte size of a single node's `data` bag. */
+  readonly maxDataBytes?: number;
+  /** Max nesting depth of a single node's `data` bag. */
+  readonly maxDataDepth?: number;
+}
+
+export type ValidationCode =
+  | 'DUPLICATE_ID'
+  | 'MISSING_ID'
+  | 'UNKNOWN_TYPE'
+  | 'MAX_DEPTH_EXCEEDED'
+  | 'CHILDREN_NOT_ALLOWED'
+  | 'MISSING_REQUIRED_FIELD'
+  | 'INVALID_ORDER'
+  | 'MULTIPLE_OWNERS'
+  | 'DATA_TOO_LARGE'
+  | 'DATA_TOO_DEEP'
+  | 'INVALID_OVERRIDES';
+
+export interface ValidationError {
+  readonly code: ValidationCode;
+  readonly message: string;
+  readonly nodeId?: string;
+}
+
+export interface ValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly ValidationError[];
+}
+
+/**
+ * Validate a navigation tree. Returns all errors found (does not throw); callers
+ * that prefer to throw can use {@link assertValid}.
+ */
+export function validate(tree: NavTree, options: ValidateOptions = {}): ValidationResult {
+  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: ValidationError[] = [];
+  const seenIds = new Set<string>();
+  /** ref → count of owned:true nodes, to enforce at most one owner per article. */
+  const ownerCounts = new Map<string, number>();
+
+  const visit = (node: NavNode, depth: number): void => {
+    // 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 as NavNode).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: NavTree, options?: ValidateOptions): void {
+  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 {
+  constructor(message: string, public readonly errors: readonly ValidationError[]) {
+    super(message);
+    this.name = 'NavValidationError';
+  }
+}
+
+function validateRequiredFields(node: NavNode, errors: ValidationError[]): void {
+  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: NavNode,
+  maxBytes: number,
+  maxDepth: number,
+  errors: ValidationError[],
+): void {
+  const data = node.data;
+  // byte size (UTF-8) of the serialized bag
+  let serialized: string;
+  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: string): number {
+  // 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: unknown, current = 1): number {
+  if (value === null || typeof value !== 'object') return current;
+  let max = current;
+  for (const v of Object.values(value as Record<string, unknown>)) {
+    max = Math.max(max, jsonDepth(v, current + 1));
+  }
+  return max;
+}