zudoku 0.0.0-feat-openapi-docs-redesign.dab3fc6a → 0.0.0-feat-navigation-at-property.z8cd07fa5

package/src/lib/navigation/pathMatcher.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+import { findByPath } from "./pathMatcher.js";
+
+const mockNavigation: NavigationItem[] = [
+  {
+    type: "category",
+    label: "Shipments",
+    items: [
+      { type: "link", label: "Track a Shipment", to: "/track" },
+      { type: "link", label: "Create Shipment", to: "/create" },
+      {
+        type: "category",
+        label: "Nested Category",
+        items: [
+          { type: "link", label: "First Nested", to: "/nested/first" },
+          { type: "link", label: "Second Nested", to: "/nested/second" },
+        ],
+      },
+    ],
+  },
+  { type: "link", label: "About", to: "/about" },
+];
+
+describe("pathMatcher", () => {
+  describe("findByPath", () => {
+    it("should find item by label", () => {
+      const result = findByPath(mockNavigation, "Shipments");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Shipments");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find nested item by label path", () => {
+      const result = findByPath(mockNavigation, "Shipments/Track a Shipment");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find item by index", () => {
+      const result = findByPath(mockNavigation, "Shipments/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find nested item by mixed path (label + index)", () => {
+      const result = findByPath(mockNavigation, "Shipments/2/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("First Nested");
+      expect(result.index).toBe(0);
+    });
+
+    it("should be case-insensitive for label matching", () => {
+      const result = findByPath(mockNavigation, "shipments/track a shipment");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should find deeply nested items", () => {
+      const result = findByPath(
+        mockNavigation,
+        "Shipments/Nested Category/Second Nested",
+      );
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Second Nested");
+      expect(result.index).toBe(1);
+    });
+
+    it("should return found=false for non-existent path", () => {
+      const result = findByPath(mockNavigation, "Nonexistent/Path");
+      expect(result.found).toBe(false);
+      expect(result.item).toBeUndefined();
+    });
+
+    it("should return found=false for invalid index", () => {
+      const result = findByPath(mockNavigation, "Shipments/999");
+      expect(result.found).toBe(false);
+    });
+
+    it("should handle root-level items", () => {
+      const result = findByPath(mockNavigation, "About");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("About");
+      expect(result.index).toBe(1);
+    });
+
+    it("should provide parentItems for inserting siblings", () => {
+      const result = findByPath(mockNavigation, "Shipments/0");
+      expect(result.parentItems).toBeDefined();
+      expect(result.parentItems?.length).toBe(3); // 2 links + 1 category
+    });
+
+    it("should handle empty path", () => {
+      const result = findByPath(mockNavigation, "");
+      expect(result.found).toBe(false);
+    });
+
+    it("should support negative indices (-1 for last item)", () => {
+      const result = findByPath(mockNavigation, "Shipments/-1");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Nested Category");
+    });
+
+    it("should support negative indices (-2 for second-to-last)", () => {
+      const result = findByPath(mockNavigation, "Shipments/-2");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Create Shipment");
+    });
+
+    it("should support negative indices in nested paths", () => {
+      const result = findByPath(mockNavigation, "Shipments/-1/-1");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Second Nested");
+    });
+
+    it("should handle paths with trailing slashes", () => {
+      const result = findByPath(mockNavigation, "Shipments/0/");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should handle paths with double slashes", () => {
+      const result = findByPath(mockNavigation, "Shipments//0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should handle paths with leading slashes", () => {
+      const result = findByPath(mockNavigation, "/Shipments/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+  });
+});

package/src/lib/navigation/pathMatcher.ts

@@ -0,0 +1,93 @@
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+
+type PathSegment = string | number;
+
+export type PathMatchResult = {
+  found: boolean;
+  item?: NavigationItem;
+  parentItems?: NavigationItem[];
+  index?: number;
+};
+
+const parsePath = (path: string): PathSegment[] => {
+  if (!path || path === "/") return [];
+
+  return path
+    .split("/")
+    .filter((segment) => segment !== "")
+    .map((segment) => {
+      const num = Number(segment);
+      return Number.isInteger(num) ? num : segment;
+    });
+};
+
+const matchesSegment = (
+  segment: PathSegment,
+  item: NavigationItem,
+  index: number,
+  arrayLength: number,
+): boolean => {
+  if (typeof segment === "number") {
+    // Support negative indices (-1 for last, -2 for second-to-last, etc.)
+    const normalizedIndex = segment < 0 ? arrayLength + segment : segment;
+    return normalizedIndex === index;
+  }
+
+  return item.label?.toLowerCase() === segment.toLowerCase();
+};
+
+export const findByPath = (
+  navigation: NavigationItem[],
+  pathString: string,
+): PathMatchResult => {
+  const segments = parsePath(pathString);
+
+  if (segments.length === 0) {
+    return { found: false };
+  }
+
+  let currentItems = navigation;
+  let currentItem: NavigationItem | undefined;
+  let parentItems: NavigationItem[] | undefined;
+  let itemIndex: number | undefined;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment === undefined) {
+      return { found: false };
+    }
+    const isLastSegment = i === segments.length - 1;
+
+    const foundIndex = currentItems.findIndex((item, idx) =>
+      matchesSegment(segment, item, idx, currentItems.length),
+    );
+
+    if (foundIndex === -1) {
+      return { found: false };
+    }
+
+    currentItem = currentItems[foundIndex];
+    if (!currentItem) {
+      return { found: false };
+    }
+
+    if (isLastSegment) {
+      parentItems = currentItems;
+      itemIndex = foundIndex;
+      break;
+    }
+
+    if (currentItem.type === "category") {
+      currentItems = currentItem.items;
+    } else {
+      return { found: false };
+    }
+  }
+
+  return {
+    found: true,
+    item: currentItem,
+    parentItems,
+    index: itemIndex,
+  };
+};

package/src/lib/navigation/positionItems.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AtPosition } from "../../config/validators/InputNavigationSchema.js";
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+import { repositionItems } from "./positionItems.js";
+
+type NavigationItemWithAt = NavigationItem & { at?: AtPosition };
+
+describe("positionItems", () => {
+  it("should return navigation unchanged if no items have `at` property", () => {
+    const navigation: NavigationItem[] = [
+      { type: "link", label: "Home", to: "/" },
+      { type: "link", label: "About", to: "/about" },
+    ];
+
+    const result = repositionItems(navigation);
+    expect(result).toEqual(navigation);
+  });
+
+  it("should position item with 'before' relative to target", () => {
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "Docs",
+        items: [
+          { type: "link", label: "First", to: "/first" },
+          { type: "link", label: "Second", to: "/second" },
+        ],
+      },
+      {
+        type: "link",
+        label: "Inserted",
+        to: "/inserted",
+        at: { path: "Docs/Second", position: "before" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+    const docsCategory = result[0];
+
+    expect(docsCategory).toBeDefined();
+    expect(docsCategory?.type).toBe("category");
+    if (docsCategory?.type === "category") {
+      expect(docsCategory.items[0]?.label).toBe("First");
+      expect(docsCategory.items[1]?.label).toBe("Inserted");
+      expect(docsCategory.items[2]?.label).toBe("Second");
+    }
+  });
+
+  it("should position item with 'after' relative to target", () => {
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "Docs",
+        items: [
+          { type: "link", label: "First", to: "/first" },
+          { type: "link", label: "Second", to: "/second" },
+        ],
+      },
+      {
+        type: "link",
+        label: "Inserted",
+        to: "/inserted",
+        at: { path: "Docs/First", position: "after" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+    const docsCategory = result[0];
+
+    expect(docsCategory).toBeDefined();
+    expect(docsCategory?.type).toBe("category");
+    if (docsCategory?.type === "category") {
+      expect(docsCategory.items[0]?.label).toBe("First");
+      expect(docsCategory.items[1]?.label).toBe("Inserted");
+      expect(docsCategory.items[2]?.label).toBe("Second");
+    }
+  });
+
+  it("should handle multiple items with `at` property", () => {
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "API",
+        items: [{ type: "link", label: "Original", to: "/original" }],
+      },
+      {
+        type: "link",
+        label: "First",
+        to: "/first",
+        at: { path: "API/Original", position: "before" },
+      },
+      {
+        type: "link",
+        label: "Last",
+        to: "/last",
+        at: { path: "API/Original", position: "after" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+    const apiCategory = result[0];
+
+    expect(apiCategory?.type).toBe("category");
+    if (apiCategory?.type === "category") {
+      expect(apiCategory?.items[0]?.label).toBe("First");
+      expect(apiCategory?.items[1]?.label).toBe("Original");
+      expect(apiCategory?.items[2]?.label).toBe("Last");
+    }
+  });
+
+  it("should handle nested items with `at` property", () => {
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "Outer",
+        items: [{ type: "link", label: "Item", to: "/item" }],
+      },
+      {
+        type: "category",
+        label: "Inner Category",
+        at: { path: "Outer/Item", position: "after" },
+        items: [
+          {
+            type: "link",
+            label: "Nested",
+            to: "/nested",
+            at: { path: "Outer/Item", position: "after" },
+          },
+        ],
+      },
+    ];
+
+    const result = repositionItems(navigation);
+    const outerCategory = result[0];
+
+    expect(outerCategory).toBeDefined();
+    expect(outerCategory?.type).toBe("category");
+    if (outerCategory?.type === "category") {
+      // Both items positioned after Item
+      expect(outerCategory?.items.length).toBe(3);
+      expect(outerCategory?.items[0]?.label).toBe("Item");
+      expect(outerCategory?.items[1]?.label).toBe("Nested");
+      expect(outerCategory?.items[2]?.label).toBe("Inner Category");
+    }
+  });
+
+  it("should keep item at root if target path not found", () => {
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(() => {});
+
+    const navigation: NavigationItemWithAt[] = [
+      { type: "link", label: "Home", to: "/" },
+      {
+        type: "link",
+        label: "Orphan",
+        to: "/orphan",
+        at: { path: "Nonexistent/Path", position: "before" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+
+    expect(result.length).toBe(2);
+    expect(result[1]?.label).toBe("Orphan");
+    expect("at" in (result[1] ?? {})).toBe(false);
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('target path "Nonexistent/Path" not found'),
+    );
+
+    consoleWarnSpy.mockRestore();
+  });
+
+  it("should remove `at` property from positioned items", () => {
+    const navigation: NavigationItemWithAt[] = [
+      { type: "link", label: "Target", to: "/target" },
+      {
+        type: "link",
+        label: "Item",
+        to: "/item",
+        at: { path: "Target", position: "before" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+
+    result.forEach((item) => {
+      expect("at" in item).toBe(false);
+    });
+  });
+
+  it("should handle positioning by index", () => {
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "Shipments",
+        items: [
+          { type: "link", label: "Op1", to: "/op1" },
+          { type: "link", label: "Op2", to: "/op2" },
+        ],
+      },
+      {
+        type: "doc",
+        file: "overview",
+        label: "Overview",
+        path: "/overview",
+        at: { path: "Shipments/0", position: "before" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+    const shipmentsCategory = result[0];
+
+    expect(shipmentsCategory).toBeDefined();
+    expect(shipmentsCategory?.type).toBe("category");
+    if (shipmentsCategory?.type === "category") {
+      expect(shipmentsCategory.items[0]?.label).toBe("Overview");
+      expect(shipmentsCategory?.items[1]?.label).toBe("Op1");
+      expect(shipmentsCategory?.items[2]?.label).toBe("Op2");
+    }
+  });
+
+  it("should not share nested array references between failed and successful insertions", () => {
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(() => {});
+
+    const navigation: NavigationItemWithAt[] = [
+      {
+        type: "category",
+        label: "Cat1",
+        items: [{ type: "link", label: "Original", to: "/original" }],
+      },
+      {
+        type: "link",
+        label: "BadTarget",
+        to: "/bad",
+        at: { path: "Nonexistent/Path", position: "before" },
+      },
+      {
+        type: "link",
+        label: "GoodTarget",
+        to: "/good",
+        at: { path: "Cat1/Original", position: "before" },
+      },
+    ];
+
+    const result = repositionItems(navigation);
+
+    // Verify BadTarget is at root level (failed positioning)
+    expect(result.length).toBe(2);
+    expect(result[1]?.label).toBe("BadTarget");
+
+    // Verify GoodTarget was inserted correctly into Cat1
+    const cat1 = result[0];
+    expect(cat1?.type).toBe("category");
+    if (cat1?.type === "category") {
+      expect(cat1.items.length).toBe(2);
+      expect(cat1.items[0]?.label).toBe("GoodTarget");
+      expect(cat1.items[1]?.label).toBe("Original");
+    }
+
+    consoleWarnSpy.mockRestore();
+  });
+});

package/src/lib/navigation/positionItems.ts

@@ -0,0 +1,111 @@
+import type { AtPosition } from "../../config/validators/InputNavigationSchema.js";
+import type {
+  NavigationCategory,
+  NavigationCustomPage,
+  NavigationDoc,
+  NavigationItem,
+  NavigationLink,
+} from "../../config/validators/NavigationSchema.js";
+import { findByPath } from "./pathMatcher.js";
+
+type PositionedItem = (
+  | NavigationDoc
+  | NavigationLink
+  | NavigationCustomPage
+  | NavigationCategory
+) & { at: AtPosition };
+
+export const isPositionedItem = (
+  item: NavigationItem,
+): item is PositionedItem => "at" in item && item.at !== undefined;
+
+const cloneWithoutPositioned = (items: NavigationItem[]): NavigationItem[] =>
+  items.flatMap<NavigationItem>((item) =>
+    isPositionedItem(item)
+      ? []
+      : item.type === "category"
+        ? { ...item, items: cloneWithoutPositioned(item.items) }
+        : { ...item },
+  );
+
+export const extractPositionedItems = (
+  navigation: NavigationItem[],
+): PositionedItem[] => {
+  return navigation.flatMap((item) => {
+    const nested =
+      item.type === "category" ? extractPositionedItems(item.items) : [];
+
+    return isPositionedItem(item) ? [item, ...nested] : nested;
+  });
+};
+
+const removeAt = ({ at: _at, ...item }: PositionedItem): NavigationItem => item;
+
+const insertItem = (
+  navigation: NavigationItem[],
+  item: PositionedItem,
+): NavigationItem[] => {
+  const match = findByPath(navigation, item.at.path);
+
+  if (!match.found || !match.parentItems || match.index === undefined) {
+    // biome-ignore lint/suspicious/noConsole: Intentional warning for positioning debug
+    console.warn(
+      `Navigation positioning: target path "${item.at.path}" not found, keeping item in place`,
+    );
+
+    return [...navigation, removeAt(item)];
+  }
+
+  const insertIndex =
+    item.at.position === "before" ? match.index : match.index + 1;
+
+  match.parentItems.splice(insertIndex, 0, removeAt(item));
+
+  return navigation;
+};
+
+export const repositionItems = (
+  navigation: NavigationItem[],
+): NavigationItem[] => {
+  const itemsToPosition = extractPositionedItems(navigation);
+
+  if (itemsToPosition.length === 0) return navigation;
+
+  return itemsToPosition.reduce(
+    (result, item) => insertItem(result, item),
+    cloneWithoutPositioned(navigation),
+  );
+};
+
+// Filter and normalize positioned items for the current section
+// Only keeps items whose paths start with topNavLabel, then strips that prefix
+const filterAndNormalizePaths = (
+  items: PositionedItem[],
+  topNavLabel?: string,
+): PositionedItem[] => {
+  if (!topNavLabel) return [];
+
+  const normalizedLabel = topNavLabel.toLowerCase();
+
+  return items.flatMap((item) => {
+    const [firstSegment, ...rest] = item.at.path.split("/");
+    if (firstSegment?.toLowerCase() === normalizedLabel) {
+      return { ...item, at: { ...item.at, path: rest.join("/") } };
+    }
+    return [];
+  });
+};
+
+// Merge positioned items from rootNavigation into baseNavigation
+// Normalizes paths to handle top-level category nesting
+export const mergePositionedItems = (
+  baseNavigation: NavigationItem[],
+  rootNavigation: NavigationItem[],
+  topNavLabel?: string,
+): NavigationItem[] => {
+  const itemsToPosition = extractPositionedItems(rootNavigation);
+  const normalizedItems = filterAndNormalizePaths(itemsToPosition, topNavLabel);
+  const combined = [...baseNavigation, ...normalizedItems];
+
+  return repositionItems(combined);
+};