Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

6.6 KB
Raw Blame
// Framework-neutral navigation helpers for the wiki reader.
//
// The breadcrumb trail and the sibling prev/next links are read from the
// stored page tree (``parent_page_id`` / ``display_order``), the same one the
// docs tree renders and ``get_overview`` serves, so a page's ancestry is the
// same wherever it is shown. It used to be re-derived here by splitting
// ``target_path`` and matching module pages by path prefix, which was a third
// independent guess at the hierarchy.
//
// A store written before the tree existed has no parents at all; those pages
// fall back to the path split, so an un-rebuilt wiki keeps working breadcrumbs
// rather than losing them until it is re-indexed.
//
// The host app turns the returned ``pageId`` values into hrefs (route shape
// differs between the CLI web app and hosted frontend).

import type { DocPageSummary } from "@repowise-dev/types/docs";
import { treeLabel } from "./page-labels";

export interface DocNavSegment {
  label: string;
  /** Present when this segment maps to a real page that can be linked. */
  pageId?: string;
  /**
   * Page type of the linked page. Ancestors in the stored tree are whatever
   * the tree put there — a module, but equally a layer or the file a symbol
   * was spotted in — so a caller that wants "the module this sits in" has to
   * ask rather than assume the second-to-last crumb is one.
   */
  pageType?: string;
}

export interface DocSiblingLink {
  pageId: string;
  title: string;
}

export interface DocNavInfo {
  /** repo root is added by the caller; these are page-relative segments. */
  breadcrumbs: DocNavSegment[];
  prev?: DocSiblingLink;
  next?: DocSiblingLink;
}

function parentDir(path: string): string {
  const i = path.lastIndexOf("/");
  return i === -1 ? "" : path.slice(0, i);
}

/** Ancestors of ``page``, outermost first, excluding the root and the page. */
function ancestors(page: DocPageSummary, byId: Map<string, DocPageSummary>): DocPageSummary[] {
  const chain: DocPageSummary[] = [];
  const seen = new Set<string>([page.id]);
  let current = byId.get(page.parent_page_id ?? "");
  while (current && !seen.has(current.id)) {
    seen.add(current.id);
    // The repo root is the crumb the caller prepends; repeating it here would
    // show the repository name twice.
    if (current.parent_page_id) chain.unshift(current);
    current = byId.get(current.parent_page_id ?? "");
  }
  return chain;
}

/** The label a page carries in a trail — the same one the docs tree shows. */
function crumbLabel(page: DocPageSummary): string {
  return treeLabel(page, undefined);
}

/**
 * Breadcrumbs + sibling prev/next for ``page`` given the full page list.
 *
 * Ancestors are walked up ``parent_page_id`` and each links to a real page, so
 * a reader can zoom out one documented level at a time — a module, then the
 * layer it sits in — rather than through directory names that may have no page
 * behind them.
 */
export function computeDocNav(page: DocPageSummary, pages: DocPageSummary[]): DocNavInfo {
  const byId = new Map(pages.map((p) => [p.id, p]));
  const chain = page.parent_page_id ? ancestors(page, byId) : [];

  // Use the stored tree when page.parent_page_id exists and is in the store.
  // Root children have an empty ancestor chain (root crumb omitted), but still
  // rely on parent_page_id for display_order sibling sorting and clean labels.
  if (page.parent_page_id && byId.has(page.parent_page_id)) {
    const breadcrumbs: DocNavSegment[] = [
      ...chain.map((a) => ({
        label: crumbLabel(a),
        pageId: a.id,
        pageType: a.page_type,
      })),
      { label: crumbLabel(page), pageId: page.id, pageType: page.page_type },
    ];

    // Siblings are the pages sharing this parent, in stored order. Unlike the
    // old same-type/same-directory rule, "next" walks the outline the reader
    // is actually looking at.
    const siblings = pages
      .filter((p) => p.parent_page_id === page.parent_page_id)
      .sort(
        (a, b) =>
          (a.display_order ?? 0) - (b.display_order ?? 0) ||
          (a.target_path || a.title).localeCompare(b.target_path || b.title),
      );
    return { breadcrumbs, ...siblingLinks(siblings, page) };
  }

  // No stored parent: either a root/synthetic page, or a store predating the
  // tree. Special pages (overview, onboarding, architecture) have no
  // meaningful filesystem path — show a single label, no siblings.
  if (!page.target_path) {
    return { breadcrumbs: [{ label: page.title }] };
  }

  // A layer or cycle hanging off the root carries a synthetic target_path
  // ("layer:ui", "scc-103") rather than a directory trail. Splitting it would
  // show that raw id as a crumb; use the same clean label the tree does. The
  // pageId is the current page's own, so the reader renders it as plain text
  // (it only links crumbs whose pageId differs from the page).
  if (!page.target_path.includes("/")) {
    return { breadcrumbs: [{ label: crumbLabel(page), pageId: page.id }] };
  }

  // Index module pages by the directory they represent so an ancestor
  // directory segment can deep-link to its module overview.
  const moduleByPath = new Map<string, DocPageSummary>();
  for (const p of pages) {
    if (p.page_type === "module_page" && p.target_path) {
      moduleByPath.set(p.target_path, p);
    }
  }

  const parts = page.target_path.split("/").filter(Boolean);
  const breadcrumbs: DocNavSegment[] = [];
  for (let i = 0; i < parts.length; i++) {
    const segPath = parts.slice(0, i + 1).join("/");
    const isLeaf = i === parts.length - 1;
    const mod = moduleByPath.get(segPath);
    breadcrumbs.push({
      label: parts[i] ?? segPath,
      // The leaf is the current page; ancestors link to their module page
      // when we have one.
      ...(isLeaf
        ? { pageId: page.id }
        : mod
          ? { pageId: mod.id }
          : {}),
    });
  }

  const dir = parentDir(page.target_path);
  const siblings = pages
    .filter(
      (p) =>
        p.page_type === page.page_type &&
        p.target_path &&
        parentDir(p.target_path) === dir,
    )
    .sort((a, b) => a.target_path.localeCompare(b.target_path));

  return { breadcrumbs, ...siblingLinks(siblings, page) };
}

function siblingLinks(
  siblings: DocPageSummary[],
  page: DocPageSummary,
): { prev?: DocSiblingLink; next?: DocSiblingLink } {
  const idx = siblings.findIndex((p) => p.id === page.id);
  if (idx === -1) return {};
  const prev = siblings[idx - 1];
  const next = siblings[idx + 1];
  return {
    ...(prev ? { prev: { pageId: prev.id, title: prev.title } } : {}),
    ...(next ? { next: { pageId: next.id, title: next.title } } : {}),
  };
}