@company-semantics/contracts 1.7.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/org/__tests__/tree-ordering.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { orderTreeNodes, type TreeOrderableNode } from '../tree-ordering.js';
+
+interface TestNode extends TreeOrderableNode {
+  label?: string;
+}
+
+function shuffle<T>(input: readonly T[], seed: number): T[] {
+  const out = input.slice();
+  let s = seed >>> 0 || 1;
+  for (let i = out.length - 1; i > 0; i--) {
+    s = (s * 1664525 + 1013904223) >>> 0;
+    const j = s % (i + 1);
+    const tmp = out[i];
+    out[i] = out[j];
+    out[j] = tmp;
+  }
+  return out;
+}
+
+const FIXTURE: TestNode[] = [
+  { id: 'root-1', parentId: null, orderKey: '10' },
+  { id: 'root-2', parentId: null, orderKey: '20' },
+  { id: 'a', parentId: 'root-1', orderKey: '20' },
+  { id: 'b', parentId: 'root-1', orderKey: '10' },
+  { id: 'c', parentId: 'root-1', orderKey: '30' },
+  { id: 'aa', parentId: 'a', orderKey: '10' },
+  { id: 'ab', parentId: 'a', orderKey: '20' },
+  { id: 'ba', parentId: 'b', orderKey: '10' },
+  { id: 'x', parentId: 'root-2', orderKey: '10' },
+  { id: 'y', parentId: 'root-2', orderKey: '10' },
+];
+
+describe('orderTreeNodes', () => {
+  it('emits a parent-before-children flat order sorted per parent', () => {
+    const ordered = orderTreeNodes(FIXTURE).map((n) => n.id);
+    expect(ordered).toEqual(['root-1', 'b', 'ba', 'a', 'aa', 'ab', 'c', 'root-2', 'x', 'y']);
+  });
+
+  it('is idempotent — running twice produces the same result', () => {
+    const once = orderTreeNodes(FIXTURE);
+    const twice = orderTreeNodes(once);
+    expect(twice).toEqual(once);
+  });
+
+  it('is stable under input shuffle — order depends only on (orderKey, id), not insertion order', () => {
+    const baseline = orderTreeNodes(FIXTURE).map((n) => n.id);
+    for (const seed of [1, 2, 3, 42, 1337, 999999]) {
+      const shuffled = shuffle(FIXTURE, seed);
+      const result = orderTreeNodes(shuffled).map((n) => n.id);
+      expect(result).toEqual(baseline);
+    }
+  });
+
+  it('uses id as deterministic tiebreaker when orderKey is identical', () => {
+    const ties: TestNode[] = [
+      { id: 'zeta', parentId: null, orderKey: '50' },
+      { id: 'alpha', parentId: null, orderKey: '50' },
+      { id: 'mike', parentId: null, orderKey: '50' },
+    ];
+    const order = orderTreeNodes(ties).map((n) => n.id);
+    expect(order).toEqual(['alpha', 'mike', 'zeta']);
+
+    const shuffled = orderTreeNodes(shuffle(ties, 7)).map((n) => n.id);
+    expect(shuffled).toEqual(['alpha', 'mike', 'zeta']);
+  });
+
+  it('places nodes with null parentId in the root group, before any descendants', () => {
+    const nodes: TestNode[] = [
+      { id: 'child-of-r2', parentId: 'r2', orderKey: '10' },
+      { id: 'r1', parentId: null, orderKey: '20' },
+      { id: 'r2', parentId: null, orderKey: '10' },
+      { id: 'child-of-r1', parentId: 'r1', orderKey: '10' },
+    ];
+    const ordered = orderTreeNodes(nodes).map((n) => n.id);
+    expect(ordered).toEqual(['r2', 'child-of-r2', 'r1', 'child-of-r1']);
+
+    const roots = orderTreeNodes(nodes).filter((n) => n.parentId === null).map((n) => n.id);
+    expect(roots).toEqual(['r2', 'r1']);
+  });
+
+  it('preserves all input fields on the output nodes', () => {
+    const rich: TestNode[] = [
+      { id: 'only', parentId: null, orderKey: '1', label: 'hello' },
+    ];
+    const [out] = orderTreeNodes(rich);
+    expect(out).toEqual({ id: 'only', parentId: null, orderKey: '1', label: 'hello' });
+  });
+
+  it('returns a new array without mutating the input list', () => {
+    const input = FIXTURE.slice();
+    const snapshotIds = input.map((n) => n.id);
+    orderTreeNodes(input);
+    expect(input.map((n) => n.id)).toEqual(snapshotIds);
+  });
+
+  it('is strictly synchronous (no Promise return)', () => {
+    const result = orderTreeNodes(FIXTURE);
+    expect(Array.isArray(result)).toBe(true);
+    expect(typeof (result as unknown as { then?: unknown }).then).toBe('undefined');
+  });
+});

package/src/org/index.ts

@@ -80,6 +80,10 @@ export type {
 export type { AuthorizableView } from './view-scopes';
 export { VIEW_SCOPE_MAP, getViewScope } from './view-scopes';
 
+// Canonical OrgUnit tree ordering (PRD-00506)
+export type { TreeOrderableNode } from './tree-ordering';
+export { orderTreeNodes } from './tree-ordering';
+
 // Company.md domain types (PRD-00173)
 export type {
   CompanyMdVisibility,
@@ -200,7 +204,9 @@ export type {
   OrgUnitMembershipStatus,
   OrgUnitMembershipSource,
   OrgUnitErrorCode,
+  OrgTreeResponse,
 } from './org-units';
+export { ORG_UNITS_ROUTES } from './org-units';
 export {
   OrgUnitClassificationSchema,
   OrgUnitSyncModeSchema,

package/src/org/org-units.ts

@@ -45,6 +45,48 @@ export type OrgUnitMembershipStatus = 'active' | 'pending' | 'removed';
 /** External directory origin of a membership row. */
 export type OrgUnitMembershipSource = 'manual' | 'google_groups' | 'scim' | 'hris';
 
+/**
+ * Canonical route path constants for the `/api/org-units` surface.
+ *
+ * Consumers (backend route handlers, app hooks, typed clients) MUST import
+ * these rather than inlining path literals so a single rename stays
+ * consistent across the system. Parameterised paths are exposed as
+ * functions so callers cannot forget to interpolate the id.
+ *
+ * `tree` returns an `OrgTreeResponse` (alias for `OrgUnitTreeResponse`,
+ * shape `{ nodes, levelConfig }` — see `./schemas`).
+ *
+ * Used by PRD-00511 to consolidate the legacy `/api/org-tree` handler
+ * into `/api/org-units/tree` without changing the response shape.
+ */
+export const ORG_UNITS_ROUTES = {
+  list: '/api/org-units',
+  tree: '/api/org-units/tree',
+  byId: (unitId: string) => `/api/org-units/${unitId}`,
+  children: (unitId: string) => `/api/org-units/${unitId}/children`,
+  ancestors: (unitId: string) => `/api/org-units/${unitId}/ancestors`,
+  descendants: (unitId: string) => `/api/org-units/${unitId}/descendants`,
+  archive: (unitId: string) => `/api/org-units/${unitId}/archive`,
+  reparent: (unitId: string) => `/api/org-units/${unitId}/reparent`,
+  reorder: (unitId: string) => `/api/org-units/${unitId}/reorder`,
+  relationships: (unitId: string) => `/api/org-units/${unitId}/relationships`,
+  memberships: (unitId: string) => `/api/org-units/${unitId}/memberships`,
+  membershipByUser: (unitId: string, userId: string) =>
+    `/api/org-units/${unitId}/memberships/${userId}`,
+  membershipRole: (unitId: string, userId: string) =>
+    `/api/org-units/${unitId}/memberships/${userId}/role`,
+  permissions: (unitId: string) => `/api/org-units/${unitId}/permissions`,
+} as const;
+
+/**
+ * Domain-level alias for the tree endpoint response type.
+ *
+ * The canonical schema lives in `./schemas` as `OrgUnitTreeResponseSchema`
+ * / `OrgUnitTreeResponse`. This alias gives consumers the shorter
+ * `OrgTreeResponse` name used by `GET /api/org-units/tree`.
+ */
+export type { OrgUnitTreeResponse as OrgTreeResponse } from './schemas';
+
 /**
  * Error codes returned by `POST /api/org-units/:id/reparent` and related
  * mutation endpoints. Clients must handle these explicitly.

package/src/org/tree-ordering.ts

@@ -0,0 +1,63 @@
+/**
+ * Canonical per-parent sibling ordering for OrgUnit trees.
+ *
+ * Sort rule: ascending `orderKey`, with `id` as deterministic tiebreaker.
+ * Applied per parent. The output is a flat array produced by a depth-first
+ * traversal from the root set (nodes with `parentId === null`), emitting each
+ * parent before its children, with siblings in sorted order.
+ *
+ * This is the single source of truth for tree ordering. Backend and app
+ * consumers MUST import from this module rather than reimplementing the
+ * sibling sort. Keeping one implementation ensures server-rendered and
+ * client-rendered trees agree byte-for-byte.
+ *
+ * Invariants:
+ * - Pure and strictly synchronous (no Promise / async return type) — see
+ *   feedback `sync_derivers_as_invariant`.
+ * - Per-parent ordering: siblings under the same parent are sorted together;
+ *   cross-parent ordering is determined by traversal from the root set.
+ * - Stable tiebreaker: nodes with identical `orderKey` fall back to `id`
+ *   ascending (string comparison). Never fall through to implementation-
+ *   defined Array.prototype.sort behavior.
+ * - Generic over the input node type: the function preserves all input
+ *   fields on output. Callers can extend `TreeOrderableNode` with their own
+ *   fields without losing them.
+ * - Orphan nodes (non-null `parentId` that does not match any node's `id`)
+ *   are dropped from the flat output. Callers that need orphan surfacing
+ *   must handle that at their own layer (as `buildOrgTree` does in the app).
+ */
+
+export interface TreeOrderableNode {
+  id: string;
+  parentId: string | null;
+  orderKey: string;
+}
+
+export function orderTreeNodes<T extends TreeOrderableNode>(nodes: readonly T[]): T[] {
+  const byParent = new Map<string | null, T[]>();
+  for (const node of nodes) {
+    const bucket = byParent.get(node.parentId) ?? [];
+    bucket.push(node);
+    byParent.set(node.parentId, bucket);
+  }
+  for (const bucket of byParent.values()) {
+    bucket.sort(compareSiblings);
+  }
+  const result: T[] = [];
+  const emit = (parentId: string | null): void => {
+    const bucket = byParent.get(parentId);
+    if (!bucket) return;
+    for (const node of bucket) {
+      result.push(node);
+      emit(node.id);
+    }
+  };
+  emit(null);
+  return result;
+}
+
+function compareSiblings(a: TreeOrderableNode, b: TreeOrderableNode): number {
+  if (a.orderKey !== b.orderKey) return a.orderKey < b.orderKey ? -1 : 1;
+  if (a.id === b.id) return 0;
+  return a.id < b.id ? -1 : 1;
+}