Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
import { describe, it, expect } from "vitest";
import { computeDocNav } from "../../src/docs/doc-nav.js";
import type { DocPage } from "@repowise-dev/types/docs";
function makePage(overrides: Partial<DocPage> = {}): DocPage {
return {
id: "p1",
repository_id: "r1",
page_type: "file_page",
title: "Page",
content: "",
target_path: "src/foo.ts",
source_hash: "h",
model_name: "m",
provider_name: "g",
input_tokens: 0,
output_tokens: 0,
cached_tokens: 0,
generation_level: 1,
version: 1,
confidence: 0.9,
freshness_status: "fresh",
metadata: {},
human_notes: null,
created_at: "2026-01-01T00:00:00Z",
updated_at: "2026-01-01T00:00:00Z",
...overrides,
};
}
const ROOT = makePage({
id: "repo_overview:demo",
page_type: "repo_overview",
title: "Repository Overview: demo",
target_path: "demo",
parent_page_id: null,
});
const LAYER = makePage({
id: "layer_page:layer:runtime",
page_type: "layer_page",
title: "Layer: Runtime",
target_path: "layer:runtime",
parent_page_id: ROOT.id,
display_order: 2,
});
const MODULE = makePage({
id: "module_page:community-7",
page_type: "module_page",
// A community-clustered module: its target_path is a clustering ordinal, so
// no file path can ever be a prefix of it. Path splitting cannot find this
// ancestor at all; the stored parent can.
title: "Module: runtime/engine",
target_path: "community-7",
parent_page_id: LAYER.id,
display_order: 1,
});
const FILE_B = makePage({
id: "file_page:runtime/engine/b.py",
title: "b.py",
target_path: "runtime/engine/b.py",
parent_page_id: MODULE.id,
display_order: 1,
});
const FILE_A = makePage({
id: "file_page:runtime/engine/a.py",
title: "a.py",
target_path: "runtime/engine/a.py",
parent_page_id: MODULE.id,
display_order: 2,
});
const PAGES = [ROOT, LAYER, MODULE, FILE_B, FILE_A];
describe("computeDocNav", () => {
it("walks stored parents rather than splitting the path", () => {
const nav = computeDocNav(FILE_B, PAGES);
expect(nav.breadcrumbs.map((b) => b.label)).toEqual([
"Runtime",
"runtime/engine",
"b.py",
]);
// Every ancestor crumb links to a real page, which is the point: a path
// segment often has no page behind it.
expect(nav.breadcrumbs.map((b) => b.pageId)).toEqual([
LAYER.id,
MODULE.id,
FILE_B.id,
]);
});
it("omits the repo root, which the caller prepends itself", () => {
const nav = computeDocNav(MODULE, PAGES);
expect(nav.breadcrumbs.map((b) => b.pageId)).toEqual([LAYER.id, MODULE.id]);
});
it("orders siblings by stored order, not by path", () => {
// b.py is stored first even though a.py sorts first alphabetically.
const nav = computeDocNav(FILE_B, PAGES);
expect(nav.prev).toBeUndefined();
expect(nav.next?.pageId).toBe(FILE_A.id);
expect(computeDocNav(FILE_A, PAGES).prev?.pageId).toBe(FILE_B.id);
});
it("stops at a parent cycle instead of looping forever", () => {
const a = makePage({ id: "a", target_path: "a.py", title: "a.py", parent_page_id: "b" });
const b = makePage({ id: "b", target_path: "b.py", title: "b.py", parent_page_id: "a" });
const nav = computeDocNav(a, [a, b]);
expect(nav.breadcrumbs.length).toBeLessThanOrEqual(3);
expect(nav.breadcrumbs.at(-1)?.pageId).toBe("a");
});
it("falls back to the path split when the store has no tree", () => {
// Pages written before the hierarchy existed carry no parent at all.
const mod = makePage({
id: "module_page:src",
page_type: "module_page",
title: "Module: src",
target_path: "src",
});
const file = makePage({ id: "f", target_path: "src/foo.ts", title: "foo.ts" });
const nav = computeDocNav(file, [mod, file]);
expect(nav.breadcrumbs.map((b) => b.label)).toEqual(["src", "foo.ts"]);
expect(nav.breadcrumbs[0]?.pageId).toBe(mod.id);
});
it("uses the stored tree for pages parented to the repo root", () => {
// Pages parented to the repo root use the stored tree (omitting the root crumb,
// which the caller prepends).
const loose = makePage({
id: "file_page:docs/design/contrast_check.py",
title: "contrast_check.py",
target_path: "docs/design/contrast_check.py",
parent_page_id: ROOT.id,
});
const nav = computeDocNav(loose, [ROOT, loose]);
expect(nav.breadcrumbs.map((b) => b.label)).toEqual(["contrast_check.py"]);
});
it("labels ancestors with their page type so callers need not guess", () => {
const nav = computeDocNav(FILE_B, PAGES);
expect(nav.breadcrumbs.map((b) => b.pageType)).toEqual([
"layer_page",
"module_page",
"file_page",
]);
});
it("keeps a cycle page's derived name rather than its raw graph id", () => {
const cycle = makePage({
id: "scc_page:scc-1050",
page_type: "scc_page",
title: "Circular Dependency: scc-1050",
// No back-ticked member paths in the content, so sccDisplayLabel has
// nothing to derive from and falls back to the title.
content: "These modules import each other.",
target_path: "scc-1050",
parent_page_id: LAYER.id,
});
const nav = computeDocNav(cycle, [ROOT, LAYER, cycle]);
expect(nav.breadcrumbs.at(-1)?.label).toBe("Circular Dependency: scc-1050");
});
it("shows a single label for a page with no path and no parent", () => {
const overview = makePage({
id: "o",
page_type: "repo_overview",
title: "Overview",
target_path: "",
});
expect(computeDocNav(overview, [overview]).breadcrumbs).toEqual([{ label: "Overview" }]);
});
it("shows prev/next sibling links for root-level pages using display_order", () => {
const tour = makePage({
id: "onboarding:tour",
page_type: "onboarding",
title: "Guided Tour",
target_path: "docs/guided_tour.md",
parent_page_id: ROOT.id,
display_order: 1,
});
const map = makePage({
id: "onboarding:map",
page_type: "onboarding",
title: "Codebase Map",
target_path: "docs/codebase_map.md",
parent_page_id: ROOT.id,
display_order: 2,
});
const nav = computeDocNav(tour, [ROOT, tour, map]);
expect(nav.prev).toBeUndefined();
expect(nav.next?.pageId).toBe(map.id);
expect(nav.next?.title).toBe("Codebase Map");
});
it("provides prev/next navigation between root-level layer pages", () => {
const layer1 = makePage({
id: "layer_page:layer:ui",
page_type: "layer_page",
title: "Layer: UI",
target_path: "layer:ui",
parent_page_id: ROOT.id,
display_order: 1,
});
const layer2 = makePage({
id: "layer_page:layer:core",
page_type: "layer_page",
title: "Layer: Core",
target_path: "layer:core",
parent_page_id: ROOT.id,
display_order: 2,
});
const nav = computeDocNav(layer1, [ROOT, layer1, layer2]);
expect(nav.next?.pageId).toBe(layer2.id);
expect(nav.next?.title).toBe("Layer: Core");
});
});