@blogmcp/nav-core 0.1.0

package/src/resolve/index.ts

@@ -0,0 +1,303 @@
+/**
+ * @blogmcp/nav-core — resolve (auto-build + override merge)
+ *
+ * The heart of the "one resolved tree, never two" design (navigation-model.md §2/§4):
+ *
+ *   resolved = applyOverrides( buildDefaultTree(currentContent), curatedOverrides )
+ *
+ * `buildDefaultTree` is recomputed from the CURRENT published content on every
+ * resolve, so it is never stale: a new article appears automatically, a deleted
+ * one disappears, and an override that targets a now-absent node is simply
+ * skipped (non-fatal). The curated overrides (`doc` in `kb_navigation`) store
+ * only deviations — never the flattened tree.
+ *
+ * Pure: no I/O. The consumer (KB API service) supplies the content index from SQL
+ * and persists the overrides; this module just transforms data → tree.
+ *
+ * v1 auto-build policy: group published articles by their primary tag (first tag
+ * by slug); untagged articles land in an "Unfiled" group. `frontmatter`-based
+ * parent/order is intentionally NOT used (that column is legacy/empty in the KB).
+ */
+
+import { findNode, sortTree } from '../traverse/index.js';
+import { insertNode, moveNode, removeNode } from '../mutate/index.js';
+import type {
+  ArticleRefNode,
+  GroupNode,
+  Locale,
+  LocaleLabels,
+  NavData,
+  NavNode,
+  NavTree,
+} from '../types/index.js';
+import type { BadgeSpec } from '../types/index.js';
+
+/* -------------------------------------------------------------------------- */
+/* content index (auto-build input)                                            */
+/* -------------------------------------------------------------------------- */
+
+export interface ContentLocaleMeta {
+  readonly title: string;
+  readonly description?: string;
+}
+
+/** One published article, as needed to auto-build the default tree. */
+export interface ContentItem {
+  /** kb_articles.id */
+  readonly id: string;
+  /** Public URL handle (filename without extension). */
+  readonly slug?: string;
+  /** Tag slugs. */
+  readonly tags: readonly string[];
+  /** Per-locale title/description. */
+  readonly locales: Readonly<Record<Locale, ContentLocaleMeta>>;
+  /** Source language code (fallback locale for this item). */
+  readonly sourceLocale: Locale;
+  /** ISO timestamp, used as a secondary sort key. */
+  readonly updatedAt?: string;
+}
+
+export interface BuildOptions {
+  readonly nodeIdPrefix?: string;
+  readonly groupIdPrefix?: string;
+  readonly unfiledGroupId?: string;
+  readonly unfiledLabel?: string;
+  /** Per-tag display labels (e.g. from kb_tags). Falls back to the tag slug. */
+  readonly tagLabels?: Readonly<Record<string, LocaleLabels>>;
+  /** Choose an item's primary tag. Default: first tag by slug ascending. */
+  readonly primaryTag?: (item: ContentItem) => string | undefined;
+}
+
+const DEFAULTS = {
+  nodeIdPrefix: 'auto:',
+  groupIdPrefix: 'auto:group:',
+  unfiledLabel: 'Unfiled',
+} as const;
+
+/**
+ * Build the default navigation tree from the current published content.
+ * Deterministic: groups sorted by tag slug (Unfiled last), articles sorted by
+ * source-locale title then updatedAt. Labels are baked from content so the tree
+ * is self-contained; overrides may relabel.
+ */
+export function buildDefaultTree(items: readonly ContentItem[], options: BuildOptions = {}): NavNode[] {
+  const nodeIdPrefix = options.nodeIdPrefix ?? DEFAULTS.nodeIdPrefix;
+  const groupIdPrefix = options.groupIdPrefix ?? DEFAULTS.groupIdPrefix;
+  const unfiledGroupId = options.unfiledGroupId ?? `${groupIdPrefix}unfiled`;
+  const unfiledLabel = options.unfiledLabel ?? DEFAULTS.unfiledLabel;
+  const pickPrimary = options.primaryTag ?? defaultPrimaryTag;
+
+  const allLocales = collectLocales(items);
+
+  // bucket items by primary tag ('' = unfiled)
+  const buckets = new Map<string, ContentItem[]>();
+  for (const item of items) {
+    const key = pickPrimary(item) ?? '';
+    const bucket = buckets.get(key);
+    if (bucket) bucket.push(item);
+    else buckets.set(key, [item]);
+  }
+
+  const tagKeys = [...buckets.keys()].filter((k) => k !== '').sort();
+  const orderedKeys = buckets.has('') ? [...tagKeys, ''] : tagKeys;
+
+  return orderedKeys.map((key, groupIndex): GroupNode => {
+    const isUnfiled = key === '';
+    const groupId = isUnfiled ? unfiledGroupId : `${groupIdPrefix}${key}`;
+    const labels = isUnfiled
+      ? labelsForAll(allLocales, unfiledLabel)
+      : (options.tagLabels?.[key] ?? labelsForAll(allLocales, key));
+
+    const children = sortItems(buckets.get(key)!).map((item, i): ArticleRefNode => ({
+      id: `${nodeIdPrefix}${item.id}`,
+      type: 'article-ref',
+      ref: item.id,
+      slug: item.slug,
+      owned: true,
+      order: i,
+      labels: articleLabels(item),
+    }));
+
+    return {
+      id: groupId,
+      type: 'group',
+      order: groupIndex,
+      labels,
+      collapsible: true,
+      data: { auto: true, tag: isUnfiled ? null : key },
+      children,
+    };
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/* overrides                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** A per-node deviation from the auto-built tree. */
+export interface NodePatch {
+  /** Move under a new parent (null = root). */
+  readonly parentId?: string | null;
+  readonly order?: number;
+  readonly hidden?: boolean;
+  /** Merged over the node's existing labels. */
+  readonly labels?: LocaleLabels;
+  readonly badge?: BadgeSpec;
+  readonly icon?: string;
+  /** group only. */
+  readonly collapsed?: boolean;
+  /** article-ref only. */
+  readonly owned?: boolean;
+  /** Merged over the node's existing data bag. */
+  readonly data?: NavData;
+  /** Drop this node (and its subtree) from the menu. */
+  readonly removed?: boolean;
+}
+
+/** A hand-authored node not derivable from content (external link, custom group, separator…). */
+export interface PlacedNode {
+  readonly node: NavNode;
+  readonly parentId?: string | null;
+  readonly index?: number;
+}
+
+/** The curated overrides document persisted in `kb_navigation.doc`. */
+export interface NavOverrides {
+  readonly patches?: Readonly<Record<string, NodePatch>>;
+  readonly extra?: readonly PlacedNode[];
+}
+
+/**
+ * Apply curated overrides to a freshly auto-built tree. Order of operations:
+ * extra inserts → field patches + removals → moves → sort. Targets that no
+ * longer exist (e.g. an unpublished article) are skipped — the resolved tree
+ * always reflects current content.
+ *
+ * Extra (hand-authored) nodes are inserted FIRST so that field patches and
+ * removals below apply to them uniformly: an external link or custom group can
+ * be relabeled, hidden, reordered, or removed via the same `patches` mechanism
+ * as an auto-built node. (Previously inserts ran after patching, so any patch
+ * targeting a placed node — including `removed` — was silently a no-op.)
+ */
+export function applyOverrides(autoTree: NavTree, overrides: NavOverrides = {}): NavNode[] {
+  const patches = overrides.patches ?? {};
+  const extra = overrides.extra ?? [];
+
+  // 1. extra inserts. A placed `article-ref` (a cross-listed internal link) is
+  //    skipped when its target article is no longer a live auto node — deleted,
+  //    unpublished, or not visible at this access tier — so cross-listed links
+  //    never dangle, the same "never stale" guarantee the auto nodes get.
+  const liveRefs = collectArticleRefs(autoTree);
+  let tree: NavNode[] = [...autoTree];
+  for (const placed of extra) {
+    if (placed.node.type === 'article-ref' && !liveRefs.has(placed.node.ref)) continue;
+    if (findNode(tree, placed.node.id)) continue;
+    if (placed.parentId != null && !findNode(tree, placed.parentId)) continue;
+    tree = insertNode(tree, placed.node, { parentId: placed.parentId ?? null, index: placed.index });
+  }
+
+  // 2. field patches + removals (recursive, immutable) over the combined tree
+  const patchNode = (node: NavNode): NavNode | null => {
+    const patch = patches[node.id];
+    if (patch?.removed) return null;
+    let next: NavNode = patch ? applyFieldPatch(node, patch) : node;
+    if (next.children && next.children.length > 0) {
+      const kids = next.children
+        .map(patchNode)
+        .filter((n): n is NavNode => n !== null);
+      next = { ...next, children: kids } as NavNode;
+    }
+    return next;
+  };
+  tree = tree.map(patchNode).filter((n): n is NavNode => n !== null);
+
+  // 3. moves (parentId in a patch). Skip absent targets/parents; ignore cycles.
+  for (const [id, patch] of Object.entries(patches)) {
+    if (patch.parentId === undefined) continue;
+    if (!findNode(tree, id)) continue;
+    if (patch.parentId !== null && !findNode(tree, patch.parentId)) continue;
+    try {
+      tree = moveNode(tree, id, { parentId: patch.parentId });
+    } catch {
+      // cycle / invalid move → leave node where it is (non-fatal)
+    }
+  }
+
+  // 4. canonical display order
+  return sortTree(tree);
+}
+
+/** Convenience: build + apply in one call. */
+export function resolve(
+  items: readonly ContentItem[],
+  overrides: NavOverrides = {},
+  buildOptions: BuildOptions = {},
+): NavNode[] {
+  return applyOverrides(buildDefaultTree(items, buildOptions), overrides);
+}
+
+/* -------------------------------------------------------------------------- */
+/* helpers                                                                     */
+/* -------------------------------------------------------------------------- */
+
+function defaultPrimaryTag(item: ContentItem): string | undefined {
+  if (item.tags.length === 0) return undefined;
+  return [...item.tags].sort()[0];
+}
+
+/** Article ids that have a live node in the auto-built tree (for prune checks). */
+function collectArticleRefs(tree: NavTree): Set<string> {
+  const refs = new Set<string>();
+  const walk = (nodes: readonly NavNode[]): void => {
+    for (const n of nodes) {
+      if (n.type === 'article-ref') refs.add(n.ref);
+      if (n.children) walk(n.children);
+    }
+  };
+  walk(tree);
+  return refs;
+}
+
+/** Sorted union of locales present across the content index. */
+export function collectLocales(items: readonly ContentItem[]): Locale[] {
+  const set = new Set<Locale>();
+  for (const item of items) {
+    for (const locale of Object.keys(item.locales)) set.add(locale);
+  }
+  return [...set].sort();
+}
+
+function labelsForAll(locales: readonly Locale[], text: string): LocaleLabels {
+  return Object.fromEntries(locales.map((l) => [l, text]));
+}
+
+function articleLabels(item: ContentItem): LocaleLabels {
+  const out: Record<Locale, string> = {};
+  for (const [locale, meta] of Object.entries(item.locales)) {
+    out[locale] = meta.title;
+  }
+  return out;
+}
+
+function sortItems(items: ContentItem[]): ContentItem[] {
+  return [...items].sort((a, b) => {
+    const ta = a.locales[a.sourceLocale]?.title ?? '';
+    const tb = b.locales[b.sourceLocale]?.title ?? '';
+    const byTitle = ta.localeCompare(tb);
+    if (byTitle !== 0) return byTitle;
+    return (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '');
+  });
+}
+
+function applyFieldPatch(node: NavNode, patch: NodePatch): NavNode {
+  const next: Record<string, unknown> = { ...node };
+  if (patch.order !== undefined) next.order = patch.order;
+  if (patch.hidden !== undefined) next.hidden = patch.hidden;
+  if (patch.labels) next.labels = { ...(node.labels ?? {}), ...patch.labels };
+  if (patch.badge !== undefined) next.badge = patch.badge;
+  if (patch.icon !== undefined) next.icon = patch.icon;
+  if (patch.data) next.data = { ...(node.data ?? {}), ...patch.data };
+  if (patch.collapsed !== undefined && node.type === 'group') next.collapsed = patch.collapsed;
+  if (patch.owned !== undefined && node.type === 'article-ref') next.owned = patch.owned;
+  return next as unknown as NavNode;
+}

package/src/traverse/index.ts

@@ -0,0 +1,274 @@
+/**
+ * @blogmcp/nav-core — traverse
+ *
+ * Pure read helpers over a resolved tree. Two consumers with opposite needs use
+ * the same functions: the SDK runs them in-memory over a cached tree (zero
+ * round-trips), and the server exposes them as MCP tools (token-efficient).
+ *
+ * All functions are non-mutating. Functions that depend on display order sort
+ * siblings by `order` internally (stable: explicit order ascending, then
+ * undefined-order nodes in their original sequence).
+ */
+
+import type {
+  FlatNode,
+  LocalizedNode,
+  LocalizedTree,
+  Locale,
+  NavNode,
+  NavTree,
+} from '../types/index.js';
+
+/* -------------------------------------------------------------------------- */
+/* ordering                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Stable sort of siblings by `order` (undefined sorts last, ties keep input order). */
+export function sortSiblings(nodes: readonly NavNode[]): NavNode[] {
+  return [...nodes].sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity));
+}
+
+/** Return a new tree with every level's children sorted by `order`. */
+export function sortTree(tree: NavTree): NavNode[] {
+  return sortSiblings(tree).map((node) =>
+    node.children && node.children.length > 0
+      ? ({ ...node, children: sortTree(node.children) } as NavNode)
+      : node,
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* lookup                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Depth-first pre-order walk. Return `false` from the visitor to stop early. */
+export function walk(
+  tree: NavTree,
+  visitor: (node: NavNode, parent: NavNode | null, depth: number) => void | boolean,
+): void {
+  const recur = (nodes: readonly NavNode[], parent: NavNode | null, depth: number): boolean => {
+    for (const node of nodes) {
+      if (visitor(node, parent, depth) === false) return false;
+      if (node.children && !recur(node.children, node, depth + 1)) return false;
+    }
+    return true;
+  };
+  recur(tree, null, 0);
+}
+
+/** Find a node by id, or `undefined`. */
+export function findNode(tree: NavTree, id: string): NavNode | undefined {
+  let found: NavNode | undefined;
+  walk(tree, (node) => {
+    if (node.id === id) {
+      found = node;
+      return false;
+    }
+  });
+  return found;
+}
+
+/** Find a node's parent, or `null` if it is a root (or `undefined` if not found). */
+export function getParent(tree: NavTree, id: string): NavNode | null | undefined {
+  let result: NavNode | null | undefined;
+  walk(tree, (node, parent) => {
+    if (node.id === id) {
+      result = parent;
+      return false;
+    }
+  });
+  return result;
+}
+
+/**
+ * Ancestor path from root to the node, inclusive of the node itself.
+ * Empty array if not found. This is the basis for breadcrumbs.
+ */
+export function getPath(tree: NavTree, id: string): NavNode[] {
+  const path: NavNode[] = [];
+  let found = false;
+  const recur = (nodes: readonly NavNode[]): boolean => {
+    for (const node of nodes) {
+      path.push(node);
+      if (node.id === id) {
+        found = true;
+        return true;
+      }
+      if (node.children && recur(node.children)) return true;
+      path.pop();
+    }
+    return false;
+  };
+  recur(tree);
+  return found ? path : [];
+}
+
+/** Ancestors of a node, root → parent (excludes the node itself). */
+export function breadcrumbs(tree: NavTree, id: string): NavNode[] {
+  const path = getPath(tree, id);
+  return path.slice(0, -1);
+}
+
+/** Siblings of a node (same parent), excluding the node itself, in display order. */
+export function getSiblings(tree: NavTree, id: string): NavNode[] {
+  const parent = getParent(tree, id);
+  if (parent === undefined) return [];
+  const siblings = parent === null ? tree : (parent.children ?? []);
+  return sortSiblings(siblings).filter((n) => n.id !== id);
+}
+
+/** The node together with its descendants, or `undefined`. */
+export function getSubtree(tree: NavTree, id: string): NavNode | undefined {
+  return findNode(tree, id);
+}
+
+/* -------------------------------------------------------------------------- */
+/* sequential navigation (prev / next)                                         */
+/* -------------------------------------------------------------------------- */
+
+/** Default "navigable" predicate: visible article references only. */
+export function isNavigable(node: NavNode): boolean {
+  return node.type === 'article-ref' && node.hidden !== true;
+}
+
+export interface NextPrev {
+  readonly prev: NavNode | null;
+  readonly next: NavNode | null;
+}
+
+/**
+ * Previous/next navigable node in depth-first display order. By default only
+ * visible `article-ref` nodes participate; pass a predicate to change that.
+ */
+export function getNextPrev(
+  tree: NavTree,
+  id: string,
+  predicate: (node: NavNode) => boolean = isNavigable,
+): NextPrev {
+  const sequence: NavNode[] = [];
+  walk(sortTree(tree), (node) => {
+    if (predicate(node)) sequence.push(node);
+  });
+  const idx = sequence.findIndex((n) => n.id === id);
+  if (idx === -1) return { prev: null, next: null };
+  return {
+    prev: idx > 0 ? sequence[idx - 1]! : null,
+    next: idx < sequence.length - 1 ? sequence[idx + 1]! : null,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* projections of shape                                                        */
+/* -------------------------------------------------------------------------- */
+
+/** Flatten to FLAT form (parent pointer + index + depth), in display order. */
+export function flatten(tree: NavTree): FlatNode[] {
+  const out: FlatNode[] = [];
+  const recur = (nodes: readonly NavNode[], parentId: string | null, depth: number): void => {
+    sortSiblings(nodes).forEach((node, index) => {
+      out.push({ id: node.id, parentId, type: node.type, index, depth });
+      if (node.children) recur(node.children, node.id, depth + 1);
+    });
+  };
+  recur(tree, null, 0);
+  return out;
+}
+
+/* -------------------------------------------------------------------------- */
+/* access-tier visibility                                                      */
+/* -------------------------------------------------------------------------- */
+
+/** Default access-tier ranking (higher = more access). */
+export const DEFAULT_TIER_RANK: Readonly<Record<string, number>> = {
+  public: 0,
+  premium: 1,
+  partners: 2,
+  internal: 3,
+};
+
+/**
+ * Whether a node is visible to a viewer tier. A node with no `visibility.tiers`
+ * is public. Otherwise the viewer must meet (rank ≥) at least one declared tier.
+ * Pure helper; pair with {@link prune} to filter a tree. (Content-level access —
+ * which articles exist at all — is enforced upstream in the data query; this
+ * gates override-declared per-node visibility.)
+ */
+export function visibleToTier(
+  node: NavNode,
+  viewerTier: string,
+  ranks: Readonly<Record<string, number>> = DEFAULT_TIER_RANK,
+): boolean {
+  const tiers = node.visibility?.tiers;
+  if (!tiers || tiers.length === 0) return true;
+  const viewerRank = ranks[viewerTier] ?? 0;
+  return tiers.some((t) => viewerRank >= (ranks[t] ?? 0));
+}
+
+/** Remove every node (and its subtree) for which `keep` returns false. */
+export function prune(tree: NavTree, keep: (node: NavNode) => boolean): NavNode[] {
+  return tree
+    .filter(keep)
+    .map((node) =>
+      node.children && node.children.length > 0
+        ? ({ ...node, children: prune(node.children, keep) } as NavNode)
+        : node,
+    );
+}
+
+/* -------------------------------------------------------------------------- */
+/* localization                                                                */
+/* -------------------------------------------------------------------------- */
+
+export interface LocalizeOptions {
+  readonly locale: Locale;
+  readonly fallbackLocale?: Locale;
+  /**
+   * Supplies a default label when `labels` has none for the locale — typically
+   * the referenced article's title. nav-core does not know article content, so
+   * the consumer provides this.
+   */
+  readonly labelResolver?: (node: NavNode, locale: Locale) => string | undefined;
+}
+
+/** Resolve `labels` to a single locale, producing a {@link LocalizedTree}. */
+export function localize(tree: NavTree, options: LocalizeOptions): LocalizedTree {
+  const { locale, fallbackLocale, labelResolver } = options;
+
+  const resolveLabel = (node: NavNode): string | undefined => {
+    return (
+      node.labels?.[locale] ??
+      (fallbackLocale ? node.labels?.[fallbackLocale] : undefined) ??
+      labelResolver?.(node, locale) ??
+      (fallbackLocale ? labelResolver?.(node, fallbackLocale) : undefined)
+    );
+  };
+
+  const localizeNode = (node: NavNode): LocalizedNode => {
+    const base: LocalizedNode = {
+      id: node.id,
+      type: node.type,
+      label: resolveLabel(node),
+      order: node.order,
+      badge: node.badge,
+      icon: node.icon,
+      hidden: node.hidden,
+      visibility: node.visibility,
+      data: node.data,
+      children: node.children ? sortSiblings(node.children).map(localizeNode) : [],
+    };
+    switch (node.type) {
+      case 'article-ref':
+        return { ...base, ref: node.ref, owned: node.owned, slug: node.slug };
+      case 'external-link':
+        return { ...base, href: node.href };
+      case 'generated-section':
+        return { ...base, slug: node.slug };
+      case 'group':
+        return { ...base, link: node.link, collapsed: node.collapsed, collapsible: node.collapsible };
+      case 'separator':
+        return base;
+    }
+  };
+
+  return sortSiblings(tree).map(localizeNode);
+}