@task-mcp/shared 1.0.29 → 1.0.30

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;
+}

package/src/utils/env.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment detection utilities
+ */
+
+/**
+ * Check if running in test environment.
+ * Detects: NODE_ENV=test, BUN_TEST (set by bun test), VITEST, JEST_WORKER_ID
+ */
+export function isTestEnv(): boolean {
+  return (
+    process.env.NODE_ENV === "test" ||
+    process.env["BUN_TEST"] !== undefined ||
+    process.env["VITEST"] !== undefined ||
+    process.env["JEST_WORKER_ID"] !== undefined
+  );
+}
+
+/**
+ * Check if debug mode is enabled via environment variable
+ */
+export function isDebugEnabled(): boolean {
+  const debugEnv = process.env["TASK_MCP_DEBUG"];
+  return debugEnv === "true" || debugEnv === "1";
+}
+
+/**
+ * Check if verbose logging should be suppressed.
+ *
+ * Logs are suppressed if:
+ * - In test environment AND
+ * - TASK_MCP_DEBUG is not set AND
+ * - TASK_MCP_TEST_VERBOSE is not set
+ *
+ * Set TASK_MCP_TEST_VERBOSE=true to enable logs in specific tests.
+ */
+export function shouldSuppressLogs(): boolean {
+  if (!isTestEnv()) return false;
+  if (isDebugEnabled()) return false;
+  if (process.env["TASK_MCP_TEST_VERBOSE"] === "true") return false;
+  return true;
+}

package/src/utils/hierarchy.ts

@@ -1,4 +1,5 @@
 import type { Task } from "../schemas/task.js";
+import { shouldSuppressLogs } from "./env.js";
 
 /**
  * Maximum allowed hierarchy depth (0-indexed)
@@ -34,9 +35,11 @@ export function getTaskLevel(tasks: Task[], taskId: string): number {
   while (currentTask.parentId) {
     const parent = taskMap.get(currentTask.parentId);
     if (!parent) {
-      console.warn(
-        `[task-mcp] Orphaned parent reference: task "${currentTask.id}" references non-existent parent "${currentTask.parentId}"`
-      );
+      if (!shouldSuppressLogs()) {
+        console.warn(
+          `[task-mcp] Detached parent reference: task "${currentTask.id}" references non-existent parent "${currentTask.parentId}"`
+        );
+      }
       break;
     }
     level++;
@@ -240,8 +243,9 @@ export function buildTaskTree(
     return [buildNode(rootTask, 0, new Set())];
   }
 
-  // Return all root tasks (no parent)
-  const rootTasks = tasks.filter((t) => !t.parentId);
+  // Return all root tasks (no parent OR parent not in filtered tasks)
+  // This ensures orphaned subtasks (whose parent was filtered out) are still visible
+  const rootTasks = tasks.filter((t) => !t.parentId || !taskMap.has(t.parentId));
   return rootTasks.map((task) => buildNode(task, 0, new Set()));
 }
 

package/src/utils/index.ts

@@ -42,6 +42,8 @@ export {
   MAX_HIERARCHY_DEPTH,
   getTaskLevel,
   validateHierarchyDepth,
+  validateHierarchy,
+  type HierarchyValidationResult,
   getAncestorIds,
   getDescendantIds,
   getChildTasks,
@@ -171,3 +173,18 @@ export {
   type ParsePlanOptions,
   type ParsePlanResult,
 } from "./plan-parser.js";
+
+// Intent extractor (auto-generate intent from title/description)
+export { extractIntent, generateFallbackIntent, getIntent } from "./intent-extractor.js";
+
+// Semantic clustering (task similarity for session resumption)
+export {
+  tokenize,
+  jaccardSimilarity,
+  calculateTaskSimilarity,
+  findRelatedTasks,
+  clusterTasks,
+} from "./clustering.js";
+
+// Environment detection
+export { isTestEnv, isDebugEnabled, shouldSuppressLogs } from "./env.js";

package/src/utils/intent-extractor.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from "bun:test";
+import { extractIntent, generateFallbackIntent, getIntent } from "./intent-extractor.js";
+
+describe("extractIntent", () => {
+  test("extracts intent from fix patterns", () => {
+    expect(extractIntent("Fix login bug")).toBe("Fix issue or bug");
+    expect(extractIntent("Debug authentication issue")).toBe("Fix issue or bug");
+    expect(extractIntent("로그인 버그 수정")).toBe("Fix issue or bug");
+  });
+
+  test("extracts intent from implement patterns", () => {
+    expect(extractIntent("Implement user authentication")).toBe("Implement new functionality");
+    expect(extractIntent("Create new dashboard")).toBe("Implement new functionality");
+    expect(extractIntent("사용자 인증 구현")).toBe("Implement new functionality");
+  });
+
+  test("extracts intent from refactor patterns", () => {
+    expect(extractIntent("Refactor database layer")).toBe("Improve code quality");
+    expect(extractIntent("API 리팩토링")).toBe("Improve code quality");
+  });
+
+  test("extracts intent from add patterns", () => {
+    expect(extractIntent("Add dark mode support")).toBe("Extend with new feature");
+    expect(extractIntent("다크 모드 추가")).toBe("Extend with new feature");
+  });
+
+  test("extracts intent from update patterns", () => {
+    expect(extractIntent("Update dependencies")).toBe("Modify existing behavior");
+    expect(extractIntent("의존성 업데이트")).toBe("Modify existing behavior");
+  });
+
+  test("extracts intent from remove patterns", () => {
+    expect(extractIntent("Remove deprecated code")).toBe("Remove or clean up");
+    expect(extractIntent("레거시 코드 삭제")).toBe("Remove or clean up");
+  });
+
+  test("extracts intent from test patterns", () => {
+    expect(extractIntent("Test payment flow")).toBe("Verify functionality");
+    expect(extractIntent("결제 플로우 테스트")).toBe("Verify functionality");
+  });
+
+  test("extracts intent from description when title has no match", () => {
+    expect(extractIntent("API endpoints", "Fix the bug in user endpoint")).toBe("Fix issue or bug");
+  });
+
+  test("returns undefined when no pattern matches", () => {
+    expect(extractIntent("Random task title")).toBeUndefined();
+    expect(extractIntent("Something else")).toBeUndefined();
+  });
+});
+
+describe("generateFallbackIntent", () => {
+  test("generates intent from verb-like first word", () => {
+    expect(generateFallbackIntent("Get user data")).toBe("Get operation");
+    expect(generateFallbackIntent("Run tests")).toBe("Run operation");
+  });
+
+  test("generates fallback for non-verb titles", () => {
+    expect(generateFallbackIntent("Dashboard redesign")).toBe("Complete: Dashboard redesign");
+    // Test truncation for titles > 50 chars
+    const longTitle =
+      "This is a very long task title that definitely exceeds fifty characters limit";
+    expect(generateFallbackIntent(longTitle)).toContain("...");
+  });
+});
+
+describe("getIntent", () => {
+  test("returns extracted intent when pattern matches", () => {
+    expect(getIntent("Fix bug")).toBe("Fix issue or bug");
+    expect(getIntent("Implement feature")).toBe("Implement new functionality");
+  });
+
+  test("returns fallback when autoGenerate is true", () => {
+    expect(getIntent("Random task")).toBe("Complete: Random task");
+  });
+
+  test("returns undefined when autoGenerate is false and no match", () => {
+    expect(getIntent("Random task", undefined, false)).toBeUndefined();
+  });
+
+  test("uses description for extraction", () => {
+    expect(getIntent("Task", "Fix the authentication bug")).toBe("Fix issue or bug");
+  });
+});

package/src/utils/intent-extractor.ts

@@ -0,0 +1,156 @@
+/**
+ * Intent Extractor
+ *
+ * Extracts intent from task title/description using pattern matching.
+ * Provides fallback intent generation when workContext.intent is not provided.
+ */
+
+interface IntentPattern {
+  patterns: RegExp[];
+  intent: string;
+}
+
+const INTENT_PATTERNS: IntentPattern[] = [
+  // Fix/Bug patterns
+  {
+    patterns: [/^fix\b/i, /^debug\b/i, /^resolve\b/i, /버그/, /수정/, /고치/],
+    intent: "Fix issue or bug",
+  },
+  // Implementation patterns
+  {
+    patterns: [/^implement\b/i, /^create\b/i, /^build\b/i, /구현/, /만들/],
+    intent: "Implement new functionality",
+  },
+  // Refactoring patterns
+  {
+    patterns: [/^refactor\b/i, /^restructure\b/i, /^reorganize\b/i, /리팩/, /개선/],
+    intent: "Improve code quality",
+  },
+  // Add/Extend patterns
+  {
+    patterns: [/^add\b/i, /^extend\b/i, /^include\b/i, /추가/, /확장/],
+    intent: "Extend with new feature",
+  },
+  // Update/Modify patterns
+  {
+    patterns: [/^update\b/i, /^modify\b/i, /^change\b/i, /업데이트/, /변경/],
+    intent: "Modify existing behavior",
+  },
+  // Remove/Delete patterns
+  {
+    patterns: [/^remove\b/i, /^delete\b/i, /^clean\b/i, /삭제/, /제거/],
+    intent: "Remove or clean up",
+  },
+  // Test patterns
+  {
+    patterns: [/^test\b/i, /^verify\b/i, /^validate\b/i, /테스트/, /검증/],
+    intent: "Verify functionality",
+  },
+  // Documentation patterns
+  {
+    patterns: [/^document\b/i, /^write doc/i, /문서/, /docs/i],
+    intent: "Document or explain",
+  },
+  // Research/Analysis patterns
+  {
+    patterns: [/^research\b/i, /^analyze\b/i, /^investigate\b/i, /조사/, /분석/],
+    intent: "Research or analyze",
+  },
+  // Migration patterns
+  {
+    patterns: [/^migrate\b/i, /^upgrade\b/i, /^convert\b/i, /마이그레이션/, /전환/],
+    intent: "Migrate or upgrade",
+  },
+  // Setup/Config patterns
+  {
+    patterns: [/^setup\b/i, /^configure\b/i, /^initialize\b/i, /설정/, /초기화/],
+    intent: "Setup or configure",
+  },
+  // Review patterns
+  {
+    patterns: [/^review\b/i, /^check\b/i, /^audit\b/i, /리뷰/, /검토/],
+    intent: "Review or audit",
+  },
+];
+
+/**
+ * Extract intent from task title and description
+ *
+ * @param title - Task title
+ * @param description - Optional task description
+ * @returns Extracted intent or undefined if no pattern matches
+ */
+export function extractIntent(title: string, description?: string): string | undefined {
+  const text = title.toLowerCase();
+
+  // Try to match patterns against title
+  for (const { patterns, intent } of INTENT_PATTERNS) {
+    for (const pattern of patterns) {
+      if (pattern.test(text)) {
+        return intent;
+      }
+    }
+  }
+
+  // If no match found in title, try description
+  if (description) {
+    const descText = description.toLowerCase();
+    for (const { patterns, intent } of INTENT_PATTERNS) {
+      for (const pattern of patterns) {
+        if (pattern.test(descText)) {
+          return intent;
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Generate a fallback intent based on title structure
+ *
+ * Used when no pattern matches but we still want some intent
+ */
+export function generateFallbackIntent(title: string): string {
+  // Extract first verb-like word
+  const words = title.split(/\s+/);
+  const firstWord = words[0]?.toLowerCase() || "";
+
+  // If it looks like a verb (common task action words)
+  const verbPatterns =
+    /^(get|set|make|do|run|use|find|show|hide|load|save|send|fetch|call|start|stop|enable|disable)/i;
+  if (verbPatterns.test(firstWord)) {
+    return `${firstWord.charAt(0).toUpperCase() + firstWord.slice(1)} operation`;
+  }
+
+  // Default: use truncated title as intent
+  const truncatedTitle = title.length > 50 ? title.slice(0, 47) + "..." : title;
+  return `Complete: ${truncatedTitle}`;
+}
+
+/**
+ * Get intent for a task, extracting from content or generating fallback
+ *
+ * @param title - Task title
+ * @param description - Optional task description
+ * @param autoGenerate - Whether to generate fallback if no pattern matches (default: true)
+ * @returns Intent string
+ */
+export function getIntent(
+  title: string,
+  description?: string,
+  autoGenerate: boolean = true
+): string | undefined {
+  const extracted = extractIntent(title, description);
+
+  if (extracted) {
+    return extracted;
+  }
+
+  if (autoGenerate) {
+    return generateFallbackIntent(title);
+  }
+
+  return undefined;
+}