@task-mcp/shared 1.0.13 → 1.0.14

package/src/utils/hierarchy.test.ts

@@ -0,0 +1,411 @@
+import { describe, test, expect } from "bun:test";
+import {
+  MAX_HIERARCHY_DEPTH,
+  getTaskLevel,
+  validateHierarchyDepth,
+  getAncestorIds,
+  getDescendantIds,
+  getChildTasks,
+  getRootTask,
+  buildTaskTree,
+} from "./hierarchy.js";
+import type { Task } from "../schemas/task.js";
+
+// Helper to create mock tasks
+function createTask(
+  id: string,
+  parentId?: string,
+  overrides: Partial<Task> = {}
+): Task {
+  return {
+    id,
+    title: `Task ${id}`,
+    status: "pending",
+    priority: "medium",
+    projectId: "test-project",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    parentId,
+    ...overrides,
+  };
+}
+
+describe("MAX_HIERARCHY_DEPTH", () => {
+  test("is set to 3", () => {
+    expect(MAX_HIERARCHY_DEPTH).toBe(3);
+  });
+});
+
+describe("getTaskLevel", () => {
+  test("returns -1 for non-existent task", () => {
+    const tasks = [createTask("A")];
+    expect(getTaskLevel(tasks, "nonexistent")).toBe(-1);
+  });
+
+  test("returns 0 for root task (no parent)", () => {
+    const tasks = [createTask("A")];
+    expect(getTaskLevel(tasks, "A")).toBe(0);
+  });
+
+  test("returns 1 for direct child", () => {
+    const tasks = [createTask("A"), createTask("B", "A")];
+    expect(getTaskLevel(tasks, "B")).toBe(1);
+  });
+
+  test("returns 2 for grandchild", () => {
+    const tasks = [createTask("A"), createTask("B", "A"), createTask("C", "B")];
+    expect(getTaskLevel(tasks, "C")).toBe(2);
+  });
+
+  test("returns 3 for great-grandchild", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    expect(getTaskLevel(tasks, "D")).toBe(3);
+  });
+
+  test("handles missing parent gracefully", () => {
+    // Task B references non-existent parent "missing"
+    const tasks = [createTask("A"), createTask("B", "missing")];
+    // Should return 0 since parent lookup fails immediately
+    expect(getTaskLevel(tasks, "B")).toBe(0);
+  });
+
+  test("handles broken chain (middle parent missing)", () => {
+    // C -> B -> A, but B is missing
+    const tasks = [createTask("A"), createTask("C", "B")];
+    // C's parent "B" doesn't exist, so level stays 0
+    expect(getTaskLevel(tasks, "C")).toBe(0);
+  });
+});
+
+describe("validateHierarchyDepth", () => {
+  test("returns false for non-existent parent", () => {
+    const tasks = [createTask("A")];
+    expect(validateHierarchyDepth(tasks, "nonexistent")).toBe(false);
+  });
+
+  test("returns true when parent is at level 0", () => {
+    const tasks = [createTask("A")];
+    // Can add child at level 1
+    expect(validateHierarchyDepth(tasks, "A")).toBe(true);
+  });
+
+  test("returns true when parent is at level 1", () => {
+    const tasks = [createTask("A"), createTask("B", "A")];
+    // Can add child at level 2
+    expect(validateHierarchyDepth(tasks, "B")).toBe(true);
+  });
+
+  test("returns true when parent is at level 2", () => {
+    const tasks = [createTask("A"), createTask("B", "A"), createTask("C", "B")];
+    // Can add child at level 3 (MAX_HIERARCHY_DEPTH)
+    expect(validateHierarchyDepth(tasks, "C")).toBe(true);
+  });
+
+  test("returns false when parent is at level 3 (max depth)", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    // D is at level 3, cannot add child at level 4
+    expect(validateHierarchyDepth(tasks, "D")).toBe(false);
+  });
+});
+
+describe("getAncestorIds", () => {
+  test("returns empty array for non-existent task", () => {
+    const tasks = [createTask("A")];
+    expect(getAncestorIds(tasks, "nonexistent")).toEqual([]);
+  });
+
+  test("returns empty array for root task", () => {
+    const tasks = [createTask("A")];
+    expect(getAncestorIds(tasks, "A")).toEqual([]);
+  });
+
+  test("returns single ancestor for direct child", () => {
+    const tasks = [createTask("A"), createTask("B", "A")];
+    expect(getAncestorIds(tasks, "B")).toEqual(["A"]);
+  });
+
+  test("returns ancestors ordered from immediate parent to root", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    expect(getAncestorIds(tasks, "D")).toEqual(["C", "B", "A"]);
+  });
+
+  test("handles missing ancestor in chain", () => {
+    // C -> B -> missing
+    const tasks = [createTask("B", "missing"), createTask("C", "B")];
+    // Returns B and "missing" (the parentId), then stops when "missing" lookup fails
+    expect(getAncestorIds(tasks, "C")).toEqual(["B", "missing"]);
+  });
+});
+
+describe("getDescendantIds", () => {
+  test("returns empty array for task with no children", () => {
+    const tasks = [createTask("A"), createTask("B")];
+    expect(getDescendantIds(tasks, "A")).toEqual([]);
+  });
+
+  test("returns direct children", () => {
+    const tasks = [createTask("A"), createTask("B", "A"), createTask("C", "A")];
+    const descendants = getDescendantIds(tasks, "A");
+    expect(descendants.sort()).toEqual(["B", "C"]);
+  });
+
+  test("returns all descendants (children and grandchildren)", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "A"),
+      createTask("D", "B"),
+      createTask("E", "B"),
+    ];
+    const descendants = getDescendantIds(tasks, "A");
+    expect(descendants.sort()).toEqual(["B", "C", "D", "E"]);
+  });
+
+  test("returns descendants in BFS order", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "A"),
+      createTask("D", "B"),
+    ];
+    const descendants = getDescendantIds(tasks, "A");
+    // BFS: first level (B, C), then second level (D)
+    // B and C come before D
+    const dIndex = descendants.indexOf("D");
+    const bIndex = descendants.indexOf("B");
+    const cIndex = descendants.indexOf("C");
+    expect(bIndex).toBeLessThan(dIndex);
+    expect(cIndex).toBeLessThan(dIndex);
+  });
+
+  test("returns empty array for non-existent task", () => {
+    const tasks = [createTask("A")];
+    expect(getDescendantIds(tasks, "nonexistent")).toEqual([]);
+  });
+});
+
+describe("getChildTasks", () => {
+  test("returns empty array for task with no children", () => {
+    const tasks = [createTask("A"), createTask("B")];
+    expect(getChildTasks(tasks, "A")).toEqual([]);
+  });
+
+  test("returns only direct children", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "A"),
+      createTask("D", "B"), // grandchild, should not be included
+    ];
+    const children = getChildTasks(tasks, "A");
+    expect(children.map((t) => t.id).sort()).toEqual(["B", "C"]);
+  });
+
+  test("returns empty array for non-existent parent", () => {
+    const tasks = [createTask("A")];
+    expect(getChildTasks(tasks, "nonexistent")).toEqual([]);
+  });
+
+  test("returns full task objects", () => {
+    const tasks = [createTask("A"), createTask("B", "A", { title: "Custom Title" })];
+    const children = getChildTasks(tasks, "A");
+    expect(children.length).toBe(1);
+    expect(children[0]!.id).toBe("B");
+    expect(children[0]!.title).toBe("Custom Title");
+  });
+});
+
+describe("getRootTask", () => {
+  test("returns null for non-existent task", () => {
+    const tasks = [createTask("A")];
+    expect(getRootTask(tasks, "nonexistent")).toBeNull();
+  });
+
+  test("returns the task itself if it has no parent", () => {
+    const tasks = [createTask("A")];
+    const root = getRootTask(tasks, "A");
+    expect(root?.id).toBe("A");
+  });
+
+  test("returns root for direct child", () => {
+    const tasks = [createTask("A"), createTask("B", "A")];
+    const root = getRootTask(tasks, "B");
+    expect(root?.id).toBe("A");
+  });
+
+  test("returns root for deeply nested task", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    const root = getRootTask(tasks, "D");
+    expect(root?.id).toBe("A");
+  });
+
+  test("handles broken chain (returns earliest found task)", () => {
+    // C -> B -> missing
+    const tasks = [createTask("B", "missing"), createTask("C", "B")];
+    const root = getRootTask(tasks, "C");
+    // B's parent "missing" doesn't exist, so B is the root
+    expect(root?.id).toBe("B");
+  });
+});
+
+describe("buildTaskTree", () => {
+  test("returns empty array for empty task list", () => {
+    expect(buildTaskTree([])).toEqual([]);
+  });
+
+  test("returns single root task as tree", () => {
+    const tasks = [createTask("A")];
+    const tree = buildTaskTree(tasks);
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children).toEqual([]);
+  });
+
+  test("builds tree with children", () => {
+    const tasks = [createTask("A"), createTask("B", "A"), createTask("C", "A")];
+    const tree = buildTaskTree(tasks);
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children.length).toBe(2);
+    expect(tree[0]!.children.map((c) => c.task.id).sort()).toEqual(["B", "C"]);
+  });
+
+  test("builds nested tree structure", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    const tree = buildTaskTree(tasks);
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.task.id).toBe("B");
+    expect(tree[0]!.children[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.children[0]!.task.id).toBe("C");
+    expect(tree[0]!.children[0]!.children[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.children[0]!.children[0]!.task.id).toBe("D");
+  });
+
+  test("returns multiple root tasks", () => {
+    const tasks = [createTask("A"), createTask("B"), createTask("C")];
+    const tree = buildTaskTree(tasks);
+    expect(tree.length).toBe(3);
+    expect(tree.map((n) => n.task.id).sort()).toEqual(["A", "B", "C"]);
+  });
+
+  test("builds tree from specific root", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("X"),
+      createTask("Y", "X"),
+    ];
+    const tree = buildTaskTree(tasks, "A");
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.task.id).toBe("B");
+  });
+
+  test("returns empty array for non-existent root", () => {
+    const tasks = [createTask("A")];
+    const tree = buildTaskTree(tasks, "nonexistent");
+    expect(tree).toEqual([]);
+  });
+
+  test("can build subtree from middle of hierarchy", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "B"),
+    ];
+    const tree = buildTaskTree(tasks, "B");
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("B");
+    expect(tree[0]!.children.length).toBe(2);
+    expect(tree[0]!.children.map((c) => c.task.id).sort()).toEqual(["C", "D"]);
+  });
+
+  test("respects maxDepth parameter", () => {
+    const tasks = [
+      createTask("A"),
+      createTask("B", "A"),
+      createTask("C", "B"),
+      createTask("D", "C"),
+    ];
+    // maxDepth of 2 should include A (depth 0), B (depth 1), but stop children at C
+    const tree = buildTaskTree(tasks, "A", 2);
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.task.id).toBe("B");
+    // C should be included but with no children (depth 2 is the limit)
+    expect(tree[0]!.children[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.children[0]!.task.id).toBe("C");
+    expect(tree[0]!.children[0]!.children[0]!.children).toEqual([]);
+  });
+
+  test("handles circular references gracefully", () => {
+    // Create tasks with circular reference: A -> B -> C -> A
+    const taskA = createTask("A", "C");
+    const taskB = createTask("B", "A");
+    const taskC = createTask("C", "B");
+    const tasks = [taskA, taskB, taskC];
+
+    // Should not throw or hang - circular ref is detected
+    const tree = buildTaskTree(tasks);
+    // All tasks have parents, so no "root" tasks exist
+    expect(tree).toEqual([]);
+  });
+
+  test("handles self-referencing task", () => {
+    // Task references itself as parent
+    const selfRef = createTask("A", "A");
+    const tasks = [selfRef];
+
+    // No root tasks (A has parent), should return empty
+    const tree = buildTaskTree(tasks);
+    expect(tree).toEqual([]);
+  });
+
+  test("handles circular reference when building from specific root", () => {
+    // A -> B -> A (circular)
+    const taskA = createTask("A");
+    const taskB = createTask("B", "A");
+    // Manually create circular: make A's children include B which points back
+    // by creating a scenario where childrenMap would loop
+    const tasks = [taskA, taskB];
+    // Simulate circular by modifying childrenMap behavior won't work directly,
+    // but we can test that visited set prevents infinite recursion
+    // Let's create a more direct test case
+    const tree = buildTaskTree(tasks, "A");
+    expect(tree.length).toBe(1);
+    expect(tree[0]!.task.id).toBe("A");
+    expect(tree[0]!.children.length).toBe(1);
+    expect(tree[0]!.children[0]!.task.id).toBe("B");
+  });
+});

package/src/utils/hierarchy.ts

@@ -189,7 +189,11 @@ export interface TaskTreeNode {
   children: TaskTreeNode[];
 }
 
-export function buildTaskTree(tasks: Task[], rootId?: string): TaskTreeNode[] {
+export function buildTaskTree(
+  tasks: Task[],
+  rootId?: string,
+  maxDepth: number = MAX_HIERARCHY_DEPTH + 1
+): TaskTreeNode[] {
   const taskMap = new Map(tasks.map((t) => [t.id, t]));
   const childrenMap = new Map<string, Task[]>();
 
@@ -202,11 +206,24 @@ export function buildTaskTree(tasks: Task[], rootId?: string): TaskTreeNode[] {
     }
   }
 
-  function buildNode(task: Task): TaskTreeNode {
+  function buildNode(task: Task, depth: number, visited: Set<string>): TaskTreeNode {
+    // Guard against circular references
+    if (visited.has(task.id)) {
+      return { task, children: [] };
+    }
+
+    // Guard against exceeding max depth
+    if (depth >= maxDepth) {
+      return { task, children: [] };
+    }
+
+    const newVisited = new Set(visited);
+    newVisited.add(task.id);
+
     const children = childrenMap.get(task.id) || [];
     return {
       task,
-      children: children.map(buildNode),
+      children: children.map((child) => buildNode(child, depth + 1, newVisited)),
     };
   }
 
@@ -215,10 +232,10 @@ export function buildTaskTree(tasks: Task[], rootId?: string): TaskTreeNode[] {
     if (!rootTask) {
       return [];
     }
-    return [buildNode(rootTask)];
+    return [buildNode(rootTask, 0, new Set())];
   }
 
   // Return all root tasks (no parent)
   const rootTasks = tasks.filter((t) => !t.parentId);
-  return rootTasks.map(buildNode);
+  return rootTasks.map((task) => buildNode(task, 0, new Set()));
 }

package/src/utils/id.ts

@@ -4,7 +4,7 @@
  */
 export function generateId(prefix: string = ""): string {
   // Use crypto.randomUUID for better randomness and collision resistance
-  // Format: prefix_xxxxxxxx (8 chars from UUID, sufficient for local uniqueness)
+  // Format: prefix_xxxxxxxxxxxx (12 chars from UUID, sufficient for local uniqueness)
   const uuid = crypto.randomUUID().replace(/-/g, "").slice(0, 12);
   return prefix ? `${prefix}_${uuid}` : uuid;
 }

package/src/utils/index.ts

@@ -17,7 +17,22 @@ export {
   assertValidProjectId,
   assertValidInboxId,
 } from "./id.js";
-export { now, parseRelativeDate, formatDate, formatDisplayDate, isToday, isPastDue, isWithinDays } from "./date.js";
+export { PriorityQueue } from "./priority-queue.js";
+export {
+  now,
+  parseRelativeDate,
+  parseRelativeDateSafe,
+  parseDateString,
+  formatDate,
+  formatDisplayDate,
+  isToday,
+  isPastDue,
+  isWithinDays,
+  isValidDate,
+  DateParseError,
+  type DateParseErrorReason,
+  type DateParseResult,
+} from "./date.js";
 export { parseTaskInput, parseInboxInput, parseInput, type ParseTarget, type ParsedInput } from "./natural-language.js";
 export {
   MAX_HIERARCHY_DEPTH,
@@ -44,6 +59,7 @@ export {
   applyPagination,
   truncate,
   summarizeList,
+  sortTasks,
 } from "./projection.js";
 
 // Dashboard renderer

package/src/utils/natural-language.test.ts

@@ -117,6 +117,34 @@ describe("parseTaskInput", () => {
     });
   });
 
+  describe("sortOrder parsing", () => {
+    test("parses ^1 as sortOrder 1", () => {
+      const result = parseTaskInput("First task ^1");
+      expect(result.sortOrder).toBe(1);
+      expect(result.title).toBe("First task");
+    });
+
+    test("parses ^10 as sortOrder 10", () => {
+      const result = parseTaskInput("Tenth task ^10");
+      expect(result.sortOrder).toBe(10);
+      expect(result.title).toBe("Tenth task");
+    });
+
+    test("parses sortOrder in middle of input", () => {
+      const result = parseTaskInput("Task ^5 with more text");
+      expect(result.sortOrder).toBe(5);
+      expect(result.title).toBe("Task with more text");
+    });
+
+    test("parses sortOrder with other metadata", () => {
+      const result = parseTaskInput("Task ^3 #dev !high");
+      expect(result.sortOrder).toBe(3);
+      expect(result.tags).toEqual(["dev"]);
+      expect(result.priority).toBe("high");
+      expect(result.title).toBe("Task");
+    });
+  });
+
   describe("combined parsing", () => {
     test("parses full English input", () => {
       const result = parseTaskInput("Review PR #dev !high @focus");

package/src/utils/natural-language.ts

@@ -212,6 +212,14 @@ export function parseTaskInput(input: string): TaskCreateInput {
     }
   }
 
+  // Extract sortOrder (^1, ^10, ^순서1)
+  // Used for manual ordering within task lists
+  const sortMatch = remaining.match(/\^(\d+)/);
+  if (sortMatch) {
+    result.sortOrder = parseInt(sortMatch[1]!, 10);
+    remaining = remaining.replace(sortMatch[0], "").trim();
+  }
+
   // Clean up extra spaces
   result.title = remaining.replace(/\s+/g, " ").trim();
 

package/src/utils/priority-queue.ts

@@ -0,0 +1,68 @@
+/**
+ * Max-heap implementation for priority queue (higher priority = higher value comes first)
+ * O(log n) insert and extract operations vs O(n log n) for sort-based approach
+ */
+export class PriorityQueue<T> {
+  private heap: T[] = [];
+  private compare: (a: T, b: T) => number;
+
+  constructor(compare: (a: T, b: T) => number) {
+    this.compare = compare;
+  }
+
+  get length(): number {
+    return this.heap.length;
+  }
+
+  push(item: T): void {
+    this.heap.push(item);
+    this.bubbleUp(this.heap.length - 1);
+  }
+
+  pop(): T | undefined {
+    if (this.heap.length === 0) return undefined;
+    if (this.heap.length === 1) return this.heap.pop();
+
+    const result = this.heap[0];
+    this.heap[0] = this.heap.pop()!;
+    this.bubbleDown(0);
+    return result;
+  }
+
+  peek(): T | undefined {
+    return this.heap[0];
+  }
+
+  isEmpty(): boolean {
+    return this.heap.length === 0;
+  }
+
+  private bubbleUp(index: number): void {
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      if (this.compare(this.heap[index]!, this.heap[parentIndex]!) <= 0) break;
+      [this.heap[index], this.heap[parentIndex]] = [this.heap[parentIndex]!, this.heap[index]!];
+      index = parentIndex;
+    }
+  }
+
+  private bubbleDown(index: number): void {
+    const length = this.heap.length;
+    while (true) {
+      const leftChild = 2 * index + 1;
+      const rightChild = 2 * index + 2;
+      let largest = index;
+
+      if (leftChild < length && this.compare(this.heap[leftChild]!, this.heap[largest]!) > 0) {
+        largest = leftChild;
+      }
+      if (rightChild < length && this.compare(this.heap[rightChild]!, this.heap[largest]!) > 0) {
+        largest = rightChild;
+      }
+
+      if (largest === index) break;
+      [this.heap[index], this.heap[largest]] = [this.heap[largest]!, this.heap[index]!];
+      index = largest;
+    }
+  }
+}

package/src/utils/projection.ts

@@ -17,8 +17,6 @@ import type {
   InboxSummary,
   InboxPreview,
   PaginatedResponse,
-  DEFAULT_LIMIT,
-  MAX_LIMIT,
 } from "../schemas/response-format.js";
 
 /**
@@ -249,3 +247,49 @@ export function summarizeList<T>(
     remainingIds: remaining.map(getId),
   };
 }
+
+/**
+ * Sort tasks by sortOrder, then by other criteria.
+ * Tasks with sortOrder come first (ascending), then tasks without sortOrder (by updatedAt descending).
+ *
+ * @param tasks - Array of tasks to sort
+ * @param secondarySort - Optional secondary sort when sortOrder is equal or both undefined
+ * @returns Sorted array (mutates the original)
+ */
+export function sortTasks(
+  tasks: Task[],
+  secondarySort: "updatedAt" | "priority" | "dueDate" = "updatedAt"
+): Task[] {
+  const priorityWeight: Record<string, number> = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+  };
+
+  return tasks.sort((a, b) => {
+    // Primary: sortOrder (ascending, undefined goes last)
+    const orderA = a.sortOrder ?? Infinity;
+    const orderB = b.sortOrder ?? Infinity;
+
+    if (orderA !== orderB) {
+      return orderA - orderB;
+    }
+
+    // Secondary sort when sortOrder is equal or both undefined
+    switch (secondarySort) {
+      case "priority":
+        return (priorityWeight[a.priority] ?? 2) - (priorityWeight[b.priority] ?? 2);
+
+      case "dueDate": {
+        const dateA = a.dueDate ? new Date(a.dueDate).getTime() : Infinity;
+        const dateB = b.dueDate ? new Date(b.dueDate).getTime() : Infinity;
+        return dateA - dateB;
+      }
+
+      case "updatedAt":
+      default:
+        return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+    }
+  });
+}