@task-mcp/shared 1.0.28 → 1.0.30

package/src/schemas/task.ts

@@ -28,22 +28,36 @@ export const TimeEstimate = z
     pessimistic: z.number().min(0).max(10080).optional(), // minutes
     confidence: z.enum(["low", "medium", "high"]).optional(),
   })
-  .refine(
-    (data) => {
-      const { optimistic, expected, pessimistic } = data;
-      if (optimistic !== undefined && expected !== undefined && optimistic > expected) {
-        return false;
-      }
-      if (expected !== undefined && pessimistic !== undefined && expected > pessimistic) {
-        return false;
-      }
-      if (optimistic !== undefined && pessimistic !== undefined && optimistic > pessimistic) {
-        return false;
-      }
-      return true;
-    },
-    { message: "Time estimates must satisfy: optimistic <= expected <= pessimistic" }
-  );
+  .superRefine((data, ctx) => {
+    const { optimistic, expected, pessimistic } = data;
+
+    // Check: optimistic <= expected
+    if (optimistic !== undefined && expected !== undefined && optimistic > expected) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `optimistic (${optimistic}min) must be <= expected (${expected}min)`,
+        path: ["optimistic"],
+      });
+    }
+
+    // Check: expected <= pessimistic
+    if (expected !== undefined && pessimistic !== undefined && expected > pessimistic) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `expected (${expected}min) must be <= pessimistic (${pessimistic}min)`,
+        path: ["expected"],
+      });
+    }
+
+    // Check: optimistic <= pessimistic (when expected is not provided)
+    if (optimistic !== undefined && pessimistic !== undefined && optimistic > pessimistic) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `optimistic (${optimistic}min) must be <= pessimistic (${pessimistic}min)`,
+        path: ["optimistic"],
+      });
+    }
+  });
 export type TimeEstimate = z.infer<typeof TimeEstimate>;
 
 // Recurrence pattern (discriminated union for type-safe pattern handling)
@@ -185,6 +199,7 @@ export const Task = z.object({
   // Hierarchy (subtask support)
   parentId: z.string().nullable().optional(), // Parent task ID for subtasks (null to unlink)
   level: z.number().optional(), // Hierarchy depth (0=root, 1=subtask, 2=sub-subtask, max 3)
+  optional: z.boolean().optional(), // If true, this subtask is not required for parent completion
 
   // Dependencies
   dependencies: z.array(Dependency).optional(),
@@ -231,6 +246,7 @@ export const TaskCreateInput = z.object({
   description: z.string().optional(),
   priority: Priority.optional(),
   parentId: z.string().nullable().optional(), // Parent task ID for creating subtasks (null to unlink)
+  optional: z.boolean().optional(), // If true, this subtask is not required for parent completion
   dependencies: z.array(Dependency).optional(),
   estimate: TimeEstimate.optional(),
   dueDate: z.string().optional(),
@@ -252,6 +268,7 @@ export const TaskUpdateInput = z.object({
   status: TaskStatus.optional(),
   priority: Priority.optional(),
   parentId: z.string().nullable().optional(), // Parent task ID for moving task in hierarchy (null to unlink)
+  optional: z.boolean().optional(), // If true, this subtask is not required for parent completion
   dependencies: z.array(Dependency).optional(),
   estimate: TimeEstimate.optional(),
   actualMinutes: z.number().optional(),

package/src/utils/clustering.test.ts

@@ -0,0 +1,285 @@
+import { describe, test, expect } from "bun:test";
+import {
+  tokenize,
+  jaccardSimilarity,
+  calculateTaskSimilarity,
+  findRelatedTasks,
+  clusterTasks,
+} from "./clustering.js";
+import type { Task } from "../schemas/task.js";
+
+// Helper to create minimal task for testing
+function createTask(overrides: Partial<Task> & { id: string; title: string }): Task {
+  return {
+    status: "pending",
+    priority: "medium",
+    workspace: "test-workspace",
+    tags: [],
+    contexts: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("tokenize", () => {
+  test("splits on whitespace and punctuation", () => {
+    expect(tokenize("Fix the bug")).toEqual(["fix", "bug"]);
+    expect(tokenize("user-authentication")).toEqual(["user", "authentication"]);
+    expect(tokenize("task.create")).toEqual(["task", "create"]);
+  });
+
+  test("removes stop words", () => {
+    expect(tokenize("the user is authenticated")).toEqual(["user", "authenticated"]);
+    expect(tokenize("to be or not to be")).toEqual([]);
+  });
+
+  test("removes short tokens (< 2 chars)", () => {
+    // "I" and "a" are 1 char, removed. "am" is a stop word
+    expect(tokenize("I am a user")).toEqual(["user"]);
+  });
+
+  test("handles Korean text", () => {
+    expect(tokenize("버그 수정하기")).toEqual(["버그", "수정하기"]);
+    // Korean particles are removed
+    expect(tokenize("사용자를")).toEqual(["사용자를"]); // 를 is suffix, not separate word
+  });
+
+  test("handles empty input", () => {
+    expect(tokenize("")).toEqual([]);
+    expect(tokenize("   ")).toEqual([]);
+  });
+});
+
+describe("jaccardSimilarity", () => {
+  test("returns 1 for identical sets", () => {
+    expect(jaccardSimilarity(["fix", "bug"], ["fix", "bug"])).toBe(1);
+  });
+
+  test("returns 0 for completely different sets", () => {
+    expect(jaccardSimilarity(["fix", "bug"], ["create", "feature"])).toBe(0);
+  });
+
+  test("returns 0.5 for half overlap", () => {
+    expect(jaccardSimilarity(["fix", "bug"], ["fix", "error"])).toBeCloseTo(0.333, 2);
+  });
+
+  test("handles empty arrays", () => {
+    expect(jaccardSimilarity([], [])).toBe(0);
+    expect(jaccardSimilarity(["fix"], [])).toBe(0);
+  });
+});
+
+describe("calculateTaskSimilarity", () => {
+  test("returns high similarity for tasks with same intent", () => {
+    const task1 = createTask({
+      id: "1",
+      title: "Fix login bug",
+      workContext: { intent: "Fix issue or bug" },
+    });
+    const task2 = createTask({
+      id: "2",
+      title: "Debug authentication",
+      workContext: { intent: "Fix issue or bug" },
+    });
+
+    const similarity = calculateTaskSimilarity(task1, task2);
+    expect(similarity).toBeGreaterThan(0.3);
+  });
+
+  test("returns high similarity for tasks with similar titles", () => {
+    const task1 = createTask({
+      id: "1",
+      title: "Implement user authentication",
+    });
+    const task2 = createTask({
+      id: "2",
+      title: "Implement admin authentication",
+    });
+
+    const similarity = calculateTaskSimilarity(task1, task2);
+    expect(similarity).toBeGreaterThan(0.3);
+  });
+
+  test("returns low similarity for unrelated tasks", () => {
+    const task1 = createTask({
+      id: "1",
+      title: "Fix login bug",
+      workContext: { intent: "Fix issue or bug" },
+    });
+    const task2 = createTask({
+      id: "2",
+      title: "Write documentation",
+      workContext: { intent: "Document functionality" },
+    });
+
+    const similarity = calculateTaskSimilarity(task1, task2);
+    expect(similarity).toBeLessThan(0.2);
+  });
+
+  test("handles tasks with missing fields", () => {
+    const task1 = createTask({ id: "1", title: "Task one" });
+    const task2 = createTask({ id: "2", title: "Task two" });
+
+    // Should not throw
+    const similarity = calculateTaskSimilarity(task1, task2);
+    expect(similarity).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe("findRelatedTasks", () => {
+  const tasks: Task[] = [
+    createTask({
+      id: "auth-1",
+      title: "Implement user authentication",
+      workContext: { intent: "Implement new functionality" },
+    }),
+    createTask({
+      id: "auth-2",
+      title: "Implement OAuth authentication",
+      workContext: { intent: "Implement new functionality" },
+    }),
+    createTask({
+      id: "bug-1",
+      title: "Fix login bug",
+      workContext: { intent: "Fix issue or bug" },
+    }),
+    createTask({
+      id: "doc-1",
+      title: "Write API documentation",
+      workContext: { intent: "Document functionality" },
+    }),
+    createTask({
+      id: "completed-1",
+      title: "Implement session authentication",
+      status: "completed",
+      workContext: { intent: "Implement new functionality" },
+    }),
+  ];
+
+  test("finds related tasks by similarity", () => {
+    const related = findRelatedTasks(tasks[0]!, tasks);
+
+    // auth-2 should be most similar to auth-1
+    expect(related.length).toBeGreaterThan(0);
+    expect(related[0]!.task.id).toBe("auth-2");
+  });
+
+  test("excludes completed tasks by default", () => {
+    const related = findRelatedTasks(tasks[0]!, tasks);
+
+    const hasCompleted = related.some((r) => r.task.status === "completed");
+    expect(hasCompleted).toBe(false);
+  });
+
+  test("includes completed tasks when requested", () => {
+    const related = findRelatedTasks(tasks[0]!, tasks, { excludeCompleted: false });
+
+    const hasCompleted = related.some((r) => r.task.status === "completed");
+    expect(hasCompleted).toBe(true);
+  });
+
+  test("respects limit option", () => {
+    const related = findRelatedTasks(tasks[0]!, tasks, { limit: 1 });
+
+    expect(related.length).toBe(1);
+  });
+
+  test("excludes self", () => {
+    const related = findRelatedTasks(tasks[0]!, tasks);
+
+    const hasSelf = related.some((r) => r.task.id === tasks[0]!.id);
+    expect(hasSelf).toBe(false);
+  });
+
+  test("excludes siblings when excludeSameParent is true", () => {
+    const parentId = "parent-1";
+    const tasksWithParent = [
+      createTask({ id: "child-1", title: "Task one", parentId }),
+      createTask({ id: "child-2", title: "Task one similar", parentId }),
+      createTask({ id: "other", title: "Task one other" }),
+    ];
+
+    const related = findRelatedTasks(tasksWithParent[0]!, tasksWithParent, {
+      excludeSameParent: true,
+    });
+
+    const hasSibling = related.some((r) => r.task.id === "child-2");
+    expect(hasSibling).toBe(false);
+  });
+});
+
+describe("clusterTasks", () => {
+  test("groups similar tasks together", () => {
+    const tasks: Task[] = [
+      createTask({
+        id: "auth-1",
+        title: "Implement user authentication",
+        priority: "high",
+        workContext: { intent: "Implement new functionality" },
+      }),
+      createTask({
+        id: "auth-2",
+        title: "Implement OAuth authentication",
+        priority: "medium",
+        workContext: { intent: "Implement new functionality" },
+      }),
+      createTask({
+        id: "bug-1",
+        title: "Fix critical login bug",
+        priority: "critical",
+        workContext: { intent: "Fix issue or bug" },
+      }),
+      createTask({
+        id: "bug-2",
+        title: "Fix authentication bug",
+        priority: "high",
+        workContext: { intent: "Fix issue or bug" },
+      }),
+    ];
+
+    const clusters = clusterTasks(tasks, { minClusterSize: 2 });
+
+    // Should have at least one cluster
+    expect(clusters.length).toBeGreaterThan(0);
+
+    // Each cluster should have at least minClusterSize members
+    for (const cluster of clusters) {
+      expect(cluster.members.length).toBeGreaterThanOrEqual(2);
+    }
+  });
+
+  test("uses higher priority tasks as representatives", () => {
+    const tasks: Task[] = [
+      createTask({
+        id: "low",
+        title: "Implement feature",
+        priority: "low",
+        workContext: { intent: "Implement new functionality" },
+      }),
+      createTask({
+        id: "high",
+        title: "Implement similar feature",
+        priority: "high",
+        workContext: { intent: "Implement new functionality" },
+      }),
+    ];
+
+    const clusters = clusterTasks(tasks, { minClusterSize: 2, similarityThreshold: 0.1 });
+
+    if (clusters.length > 0) {
+      expect(clusters[0]!.representative.id).toBe("high");
+    }
+  });
+
+  test("returns empty array for no matching clusters", () => {
+    const tasks: Task[] = [
+      createTask({ id: "1", title: "Unique task one" }),
+      createTask({ id: "2", title: "Different topic completely" }),
+    ];
+
+    const clusters = clusterTasks(tasks, { minClusterSize: 2, similarityThreshold: 0.5 });
+
+    expect(clusters.length).toBe(0);
+  });
+});

package/src/utils/clustering.ts

@@ -0,0 +1,336 @@
+/**
+ * Semantic clustering utilities for task similarity
+ *
+ * Uses lightweight text similarity without external APIs.
+ * Designed for session resumption to suggest related tasks.
+ */
+
+import type { Task } from "../schemas/task.js";
+
+/**
+ * Stop words to ignore in similarity calculation
+ * Common words that don't contribute to semantic meaning
+ */
+const STOP_WORDS = new Set([
+  // English
+  "a",
+  "am",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "must",
+  "can",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "and",
+  "or",
+  "but",
+  "if",
+  "then",
+  "else",
+  "when",
+  "where",
+  "why",
+  "how",
+  "all",
+  "each",
+  "every",
+  "both",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "no",
+  "nor",
+  "not",
+  "only",
+  "own",
+  "same",
+  "so",
+  "than",
+  "too",
+  "very",
+  "just",
+  "also",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  // Korean particles (common suffixes)
+  "을",
+  "를",
+  "이",
+  "가",
+  "은",
+  "는",
+  "에",
+  "에서",
+  "으로",
+  "로",
+  "와",
+  "과",
+  "의",
+  "도",
+  "만",
+  "까지",
+  "부터",
+  "하다",
+  "하기",
+  "해서",
+  "하고",
+]);
+
+/**
+ * Tokenize text into meaningful words
+ * - Converts to lowercase
+ * - Splits on whitespace and punctuation
+ * - Removes stop words
+ * - Removes short tokens (< 2 chars)
+ */
+export function tokenize(text: string): string[] {
+  if (!text) return [];
+
+  return text
+    .toLowerCase()
+    .split(/[\s\-_.,;:!?()\[\]{}'"\/\\]+/)
+    .filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+}
+
+/**
+ * Calculate Jaccard similarity between two token sets
+ * Returns value between 0 (no overlap) and 1 (identical)
+ */
+export function jaccardSimilarity(tokensA: string[], tokensB: string[]): number {
+  if (tokensA.length === 0 && tokensB.length === 0) return 0;
+  if (tokensA.length === 0 || tokensB.length === 0) return 0;
+
+  const setA = new Set(tokensA);
+  const setB = new Set(tokensB);
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) {
+      intersection++;
+    }
+  }
+
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Calculate weighted similarity between two tasks
+ *
+ * Weights:
+ * - Intent: 0.4 (highest priority - captures purpose)
+ * - Title: 0.3 (strong signal)
+ * - Description: 0.2 (additional context)
+ * - Tags: 0.1 (explicit categorization)
+ */
+export function calculateTaskSimilarity(task1: Task, task2: Task): number {
+  // Extract text fields
+  const intent1 = task1.workContext?.intent || "";
+  const intent2 = task2.workContext?.intent || "";
+
+  const title1 = task1.title || "";
+  const title2 = task2.title || "";
+
+  const desc1 = task1.description || "";
+  const desc2 = task2.description || "";
+
+  const tags1 = task1.tags?.join(" ") || "";
+  const tags2 = task2.tags?.join(" ") || "";
+
+  // Tokenize
+  const intentTokens1 = tokenize(intent1);
+  const intentTokens2 = tokenize(intent2);
+
+  const titleTokens1 = tokenize(title1);
+  const titleTokens2 = tokenize(title2);
+
+  const descTokens1 = tokenize(desc1);
+  const descTokens2 = tokenize(desc2);
+
+  const tagTokens1 = tokenize(tags1);
+  const tagTokens2 = tokenize(tags2);
+
+  // Calculate component similarities
+  const intentSim = jaccardSimilarity(intentTokens1, intentTokens2);
+  const titleSim = jaccardSimilarity(titleTokens1, titleTokens2);
+  const descSim = jaccardSimilarity(descTokens1, descTokens2);
+  const tagSim = jaccardSimilarity(tagTokens1, tagTokens2);
+
+  // Weighted combination
+  // Adjust weights based on available content
+  let totalWeight = 0;
+  let weightedSum = 0;
+
+  if (intentTokens1.length > 0 || intentTokens2.length > 0) {
+    weightedSum += intentSim * 0.4;
+    totalWeight += 0.4;
+  }
+
+  if (titleTokens1.length > 0 || titleTokens2.length > 0) {
+    weightedSum += titleSim * 0.3;
+    totalWeight += 0.3;
+  }
+
+  if (descTokens1.length > 0 || descTokens2.length > 0) {
+    weightedSum += descSim * 0.2;
+    totalWeight += 0.2;
+  }
+
+  if (tagTokens1.length > 0 || tagTokens2.length > 0) {
+    weightedSum += tagSim * 0.1;
+    totalWeight += 0.1;
+  }
+
+  return totalWeight === 0 ? 0 : weightedSum / totalWeight;
+}
+
+/**
+ * Find tasks related to a given task
+ *
+ * @param task - The reference task
+ * @param allTasks - All tasks to search from
+ * @param options - Configuration options
+ * @returns Array of related tasks sorted by similarity (highest first)
+ */
+export function findRelatedTasks(
+  task: Task,
+  allTasks: Task[],
+  options: {
+    limit?: number;
+    minSimilarity?: number;
+    excludeCompleted?: boolean;
+    excludeSameParent?: boolean;
+  } = {}
+): Array<{ task: Task; similarity: number }> {
+  const {
+    limit = 5,
+    minSimilarity = 0.1,
+    excludeCompleted = true,
+    excludeSameParent = true,
+  } = options;
+
+  const candidates = allTasks.filter((t) => {
+    // Exclude self
+    if (t.id === task.id) return false;
+
+    // Exclude completed if requested
+    if (excludeCompleted && t.status === "completed") return false;
+
+    // Exclude same parent (siblings are already contextually related)
+    if (excludeSameParent && task.parentId && t.parentId === task.parentId) return false;
+
+    // Exclude direct parent/child relationships
+    if (t.parentId === task.id || task.parentId === t.id) return false;
+
+    return true;
+  });
+
+  // Calculate similarities
+  const withSimilarity = candidates
+    .map((t) => ({
+      task: t,
+      similarity: calculateTaskSimilarity(task, t),
+    }))
+    .filter((item) => item.similarity >= minSimilarity)
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, limit);
+
+  return withSimilarity;
+}
+
+/**
+ * Cluster tasks by similarity
+ * Returns groups of related tasks
+ */
+export function clusterTasks(
+  tasks: Task[],
+  options: {
+    minClusterSize?: number;
+    similarityThreshold?: number;
+  } = {}
+): Array<{ representative: Task; members: Task[]; avgSimilarity: number }> {
+  const { minClusterSize = 2, similarityThreshold = 0.2 } = options;
+
+  // Simple greedy clustering
+  const assigned = new Set<string>();
+  const clusters: Array<{ representative: Task; members: Task[]; avgSimilarity: number }> = [];
+
+  // Sort by priority to use higher priority tasks as cluster representatives
+  const sortedTasks = [...tasks].sort((a, b) => {
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    return (priorityOrder[a.priority] ?? 2) - (priorityOrder[b.priority] ?? 2);
+  });
+
+  for (const task of sortedTasks) {
+    if (assigned.has(task.id)) continue;
+
+    // Find related tasks that haven't been assigned
+    const related = findRelatedTasks(task, tasks, {
+      minSimilarity: similarityThreshold,
+      excludeCompleted: false,
+      excludeSameParent: false,
+      limit: 10,
+    }).filter((r) => !assigned.has(r.task.id));
+
+    if (related.length >= minClusterSize - 1) {
+      // Create cluster
+      const members = [task, ...related.map((r) => r.task)];
+      const avgSimilarity =
+        related.length > 0 ? related.reduce((sum, r) => sum + r.similarity, 0) / related.length : 0;
+
+      clusters.push({
+        representative: task,
+        members,
+        avgSimilarity,
+      });
+
+      // Mark as assigned
+      for (const member of members) {
+        assigned.add(member.id);
+      }
+    }
+  }
+
+  return clusters;
+}