feat(config): sort navigation by group.rank and rank, strip ordering fields from response

- Add rank and group.rank to NavigationItemInput document type
- Add sortNavigation() pure function with group.rank → rank sort, key tiebreaker, sentinel for unranked items
- Replace spread pattern in transformer with explicit field construction to prevent rank leakage
- Export NavigationItemInput type for testability
- Add 4 sortNavigation unit tests and 1 integration test for sorted output with rank stripping

Author: wax911

src/package/config/config.document.ts

@@ -2,10 +2,17 @@ import { Config } from './config.types.ts';
 import { WithId } from 'mongodb';
 
 /** Raw MongoDB navigation item — key is optional because the transformer
- * generates it from destination when absent in the persisted document. */
-type NavigationItemInput = Omit<Config['navigation'][number], 'key'> & {
-  key?: string | null;
-};
+ * generates it from destination when absent in the persisted document.
+ * rank and group.rank are ordering fields stripped before the response. */
+export type NavigationItemInput =
+  & Omit<Config['navigation'][number], 'key' | 'group'>
+  & {
+    key?: string | null;
+    rank?: number;
+    group: Config['navigation'][number]['group'] & {
+      rank?: number;
+    };
+  };
 
 export type ConfigDocument =
   & WithId<

src/package/config/config.service.test.ts

@@ -4,7 +4,9 @@ import { NotFoundException } from '@danet/core';
 import { createMockLogger } from '@scope/common/testing';
 import { ConfigService } from './config.service.ts';
 import { validateNavigation } from './config.validation.ts';
+import { sortNavigation } from './config.transformer.ts';
 import type { Config } from './config.types.ts';
+import type { NavigationItemInput } from './config.document.ts';
 import type { ConfigRepository } from './config.repository.ts';
 import type { ExperimentService } from '@scope/experiment';
 
@@ -190,6 +192,119 @@ describe('validateNavigation', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Unit: sortNavigation
+// ---------------------------------------------------------------------------
+
+function makeDocNavItem(
+  overrides?: Partial<NavigationItemInput>,
+): NavigationItemInput {
+  return {
+    criteria: 'test',
+    destination: '/test',
+    i18n: 'nav.test',
+    icon: 'test',
+    group: { authenticated: false, i18n: 'nav.group.main' },
+    ...overrides,
+  };
+}
+
+describe('sortNavigation', () => {
+  it('sorts by group.rank ascending, then rank ascending', () => {
+    const nav: NavigationItemInput[] = [
+      makeDocNavItem({
+        key: 'catalogs-1',
+        group: { authenticated: false, i18n: 'nav.group.catalogs', rank: 2 },
+        rank: 1,
+      }),
+      makeDocNavItem({
+        key: 'general-1',
+        group: { authenticated: false, i18n: 'nav.group.general', rank: 0 },
+        rank: 0,
+      }),
+      makeDocNavItem({
+        key: 'general-2',
+        group: { authenticated: false, i18n: 'nav.group.general', rank: 0 },
+        rank: 1,
+      }),
+      makeDocNavItem({
+        key: 'manage-1',
+        group: { authenticated: true, i18n: 'nav.group.manage', rank: 1 },
+        rank: 0,
+      }),
+      makeDocNavItem({
+        key: 'support-1',
+        group: { authenticated: false, i18n: 'nav.group.support', rank: 3 },
+        rank: 0,
+      }),
+    ];
+    const sorted = sortNavigation(nav);
+    assertEquals(sorted.map((i) => i.key), [
+      'general-1',
+      'general-2',
+      'manage-1',
+      'catalogs-1',
+      'support-1',
+    ]);
+  });
+
+  it('sorts items with undefined rank after ranked items', () => {
+    const nav: NavigationItemInput[] = [
+      makeDocNavItem({
+        key: 'has-rank',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 0,
+      }),
+      makeDocNavItem({
+        key: 'no-rank',
+        group: { authenticated: false, i18n: 'group' },
+      }),
+    ];
+    const sorted = sortNavigation(nav);
+    assertEquals(sorted.map((i) => i.key), ['has-rank', 'no-rank']);
+  });
+
+  it('does not mutate the input array', () => {
+    const nav: NavigationItemInput[] = [
+      makeDocNavItem({
+        key: 'b',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 1,
+      }),
+      makeDocNavItem({
+        key: 'a',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 0,
+      }),
+    ];
+    const copy = [...nav];
+    sortNavigation(nav);
+    assertEquals(nav, copy);
+  });
+
+  it('uses key as tiebreaker for deterministic ordering', () => {
+    const nav: NavigationItemInput[] = [
+      makeDocNavItem({
+        key: 'z',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 0,
+      }),
+      makeDocNavItem({
+        key: 'a',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 0,
+      }),
+      makeDocNavItem({
+        key: 'm',
+        group: { authenticated: false, i18n: 'group', rank: 0 },
+        rank: 0,
+      }),
+    ];
+    const sorted = sortNavigation(nav);
+    assertEquals(sorted.map((i) => i.key), ['a', 'm', 'z']);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Stub classes for integration tests
 // ---------------------------------------------------------------------------
@@ -207,7 +322,7 @@ type ConfigDocumentStub = {
   _id: { toString(): string };
   image: Record<string, string>;
   genres: Array<{ name: string; mediaId: number }>;
-  navigation: Config['navigation'];
+  navigation: NavigationItemInput[];
 };
 
 function makeDocumentStub(
@@ -265,6 +380,65 @@ describe('ConfigService.getConfig', () => {
     assertEquals(result.navigation[1].key, 'search');
   });
 
+  it('returns navigation sorted by group.rank then rank, without rank fields in output', async () => {
+    const repository = {
+      getConfig: async () =>
+        makeDocumentStub({
+          navigation: [
+            makeDocNavItem({
+              key: 'support',
+              destination: '/support',
+              group: { authenticated: false, i18n: 'support', rank: 3 },
+              rank: 0,
+            }),
+            makeDocNavItem({
+              key: 'general',
+              destination: '/home',
+              group: { authenticated: false, i18n: 'general', rank: 0 },
+              rank: 0,
+            }),
+            makeDocNavItem({
+              key: 'catalogs',
+              destination: '/discover',
+              group: { authenticated: false, i18n: 'catalogs', rank: 2 },
+              rank: 0,
+            }),
+            makeDocNavItem({
+              key: 'manage',
+              destination: '/animelist',
+              group: { authenticated: true, i18n: 'manage', rank: 1 },
+              rank: 0,
+            }),
+          ],
+        }),
+    };
+    const experiment = new ExperimentStub();
+    const { logger } = createMockLogger();
+    const service = new ConfigService(
+      repository as unknown as ConfigRepository,
+      experiment as unknown as ExperimentService,
+      logger,
+    );
+
+    const result = await service.getConfig();
+    assertEquals(result.navigation.length, 4);
+    // Expected order: General(0) → Manage(1) → Catalogs(2) → Support(3)
+    assertEquals(result.navigation.map((i) => i.key), [
+      'general',
+      'manage',
+      'catalogs',
+      'support',
+    ]);
+    // Verify rank is not in the output
+    for (const item of result.navigation) {
+      assertEquals((item as Record<string, unknown>).rank, undefined);
+      assertEquals(
+        ((item.group as unknown) as Record<string, unknown>).rank,
+        undefined,
+      );
+    }
+  });
+
   it('throws Error when navigation has duplicate keys', async () => {
     const repository = {
       getConfig: async () =>

src/package/config/config.transformer.ts

@@ -1,5 +1,5 @@
 import { Transform } from '@scope/common/transformer';
-import { ConfigDocument } from './config.document.ts';
+import { ConfigDocument, NavigationItemInput } from './config.document.ts';
 import { Config } from './config.types.ts';
 import { PlatformSource } from '@scope/experiment';
 
@@ -18,6 +18,27 @@ const toImageUrl = (image: string, source: PlatformSource): string => {
 const keyFromDestination = (destination: string): string =>
   destination.replace(/^\/+/, '').replace(/\//g, '-') || 'unknown';
 
+/**
+ * Sort navigation items by group.rank ascending, then by item rank
+ * ascending. Items with undefined ranks sort last. The item key is
+ * used as a tiebreaker for deterministic ordering.
+ */
+export function sortNavigation(
+  navigation: NavigationItemInput[],
+): NavigationItemInput[] {
+  const sorted = [...navigation];
+  sorted.sort((a, b) => {
+    const groupRankA = a.group?.rank ?? Number.MAX_SAFE_INTEGER;
+    const groupRankB = b.group?.rank ?? Number.MAX_SAFE_INTEGER;
+    if (groupRankA !== groupRankB) return groupRankA - groupRankB;
+    const rankA = a.rank ?? Number.MAX_SAFE_INTEGER;
+    const rankB = b.rank ?? Number.MAX_SAFE_INTEGER;
+    if (rankA !== rankB) return rankA - rankB;
+    return (a.key ?? '').localeCompare(b.key ?? '');
+  });
+  return sorted;
+}
+
 export const transform: Transform<
   {
     document: ConfigDocument;
@@ -42,8 +63,15 @@ export const transform: Transform<
       info: toImageUrl(image.info, platformSource),
       default: toImageUrl(image.default, platformSource),
     },
-    navigation: navigation.map((item) => ({
-      ...item,
+    navigation: sortNavigation(navigation).map((item) => ({
+      criteria: item.criteria,
+      destination: item.destination,
+      i18n: item.i18n,
+      icon: item.icon,
+      group: {
+        authenticated: item.group?.authenticated ?? false,
+        i18n: item.group?.i18n ?? '',
+      },
       key: item.key || keyFromDestination(item.destination),
     })),
   };