@task-mcp/shared 1.0.28 → 1.0.29

package/src/utils/plan-parser.ts

@@ -0,0 +1,478 @@
+import type { Priority, WorkContext } from "../schemas/task.js";
+import { extractMetadata } from "./natural-language.js";
+
+/**
+ * Parsed task from plan text
+ */
+export interface ParsedPlanTask {
+  title: string;
+  description?: string;
+  level: number; // 0 = root phase, 1 = section, 2 = task, 3 = subtask
+  tempId: string;
+  parentTempId?: string;
+  dependsOn?: string[];
+  workContext?: Partial<WorkContext>;
+  priority?: Priority;
+  tags?: string[];
+}
+
+/**
+ * Options for parsing plan text
+ */
+export interface ParsePlanOptions {
+  /** Default priority for tasks without explicit priority (default: medium) */
+  defaultPriority?: Priority;
+  /** Parse natural language patterns like !high, #tag (default: true) */
+  parseNaturalLanguage?: boolean;
+  /** Infer dependencies from 'depends on', 'after' patterns (default: true) */
+  inferDependencies?: boolean;
+}
+
+/**
+ * Result of parsing plan text
+ */
+export interface ParsePlanResult {
+  tasks: ParsedPlanTask[];
+  phases: string[];
+  warnings: string[];
+}
+
+/**
+ * Maximum input length to prevent DoS
+ */
+const MAX_PLAN_LENGTH = 50000;
+
+/**
+ * Preprocess input to remove code blocks and YAML frontmatter
+ */
+function preprocessInput(input: string): string {
+  let result = input;
+
+  // Remove YAML frontmatter (--- at start of file)
+  // Must be at the very beginning of the document
+  const frontmatterMatch = result.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (frontmatterMatch) {
+    result = result.slice(frontmatterMatch[0].length);
+  }
+
+  // Remove fenced code blocks (``` or ~~~)
+  // Matches both backticks and tildes, with optional language identifier
+  result = result.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\1$/gm, "");
+
+  // Also handle code blocks that might not have matching closing fence
+  // (replace opening fence and content until next fence or end)
+  result = result.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?=\n(`{3,}|~{3,})|$)/gm, (match) => {
+    // Only remove if it looks like a code block (has content)
+    if (match.includes("\n")) {
+      return "";
+    }
+    return match;
+  });
+
+  return result;
+}
+
+/**
+ * Parse markdown/structured text into hierarchical tasks
+ *
+ * Parsing rules:
+ * - `# Header` → Top-level phase (level 0)
+ * - `## SubHeader` → Section (level 1)
+ * - `- Item` → Task (level based on indentation)
+ * - `depends on X`, `after X` → Dependency inference
+ * - `!high`, `#tag` → Natural language patterns
+ *
+ * @example
+ * ```typescript
+ * const result = parsePlan(`
+ * # Phase 1: Setup
+ * - Create database schema !high
+ *   - Define user table
+ *   - Define session table
+ * - Setup API endpoints (depends on database)
+ * `);
+ * ```
+ */
+export function parsePlan(
+  input: string,
+  options: ParsePlanOptions = {}
+): ParsePlanResult {
+  if (input.length > MAX_PLAN_LENGTH) {
+    return {
+      tasks: [],
+      phases: [],
+      warnings: [`Input exceeds maximum length of ${MAX_PLAN_LENGTH} characters`],
+    };
+  }
+
+  const {
+    defaultPriority = "medium",
+    parseNaturalLanguage = true,
+    inferDependencies = true,
+  } = options;
+
+  // Preprocess to remove code blocks and YAML frontmatter
+  const processedInput = preprocessInput(input);
+  const lines = processedInput.split("\n");
+  const tasks: ParsedPlanTask[] = [];
+  const phases: string[] = [];
+  const warnings: string[] = [];
+
+  let taskCounter = 0;
+  let currentPhase: { tempId: string; title: string } | null = null;
+  let currentSection: { tempId: string; level: number } | null = null;
+  let currentParent: { tempId: string; level: number; indent: number } | null = null;
+  const parentStack: Array<{ tempId: string; level: number; indent: number }> = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines
+    if (!trimmed) continue;
+
+    // Parse H1 headers as phases (level 0)
+    const h1Match = trimmed.match(/^#\s+(.+)$/);
+    if (h1Match) {
+      const phaseTitle = h1Match[1]!.trim();
+      const tempId = `phase-${++taskCounter}`;
+      currentPhase = { tempId, title: phaseTitle };
+      phases.push(phaseTitle);
+
+      // Extract metadata if enabled
+      let title = phaseTitle;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(phaseTitle);
+        title = metadata.remaining || phaseTitle;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      tasks.push({
+        title,
+        level: 0,
+        tempId,
+        priority: priority ?? "high",
+        ...(tags && tags.length > 0 && { tags }),
+      });
+
+      // Reset section and parent stack
+      currentSection = null;
+      currentParent = null;
+      parentStack.length = 0;
+      continue;
+    }
+
+    // Parse H2 headers as sections (level 1)
+    const h2Match = trimmed.match(/^##\s+(.+)$/);
+    if (h2Match) {
+      const sectionTitle = h2Match[1]!.trim();
+      const tempId = `section-${++taskCounter}`;
+
+      let title = sectionTitle;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(sectionTitle);
+        title = metadata.remaining || sectionTitle;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      tasks.push({
+        title,
+        level: 1,
+        tempId,
+        ...(currentPhase && { parentTempId: currentPhase.tempId }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+      });
+
+      currentSection = { tempId, level: 1 };
+      currentParent = null;
+      parentStack.length = 0;
+      continue;
+    }
+
+    // Parse list items as tasks
+    const listMatch = line.match(/^(\s*)[-*]\s+(.+)$/);
+    if (listMatch) {
+      const indent = listMatch[1]!.length;
+      const content = listMatch[2]!.trim();
+      const tempId = `task-${++taskCounter}`;
+
+      // Determine parent based on indentation
+      let parentTempId: string | undefined;
+      let level: number;
+
+      // Pop parents from stack that have same or greater indentation
+      while (parentStack.length > 0 && parentStack[parentStack.length - 1]!.indent >= indent) {
+        parentStack.pop();
+      }
+
+      if (parentStack.length > 0) {
+        // Use the last item on stack as parent
+        const parent = parentStack[parentStack.length - 1]!;
+        parentTempId = parent.tempId;
+        level = Math.min(parent.level + 1, 3); // Max depth 3
+      } else if (currentSection) {
+        parentTempId = currentSection.tempId;
+        level = 2;
+      } else if (currentPhase) {
+        parentTempId = currentPhase.tempId;
+        level = 1;
+      } else {
+        level = 0;
+      }
+
+      // Extract metadata from content
+      let title = content;
+      let description: string | undefined;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+      let dependsOn: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(content);
+        title = metadata.remaining || content;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      // Infer dependencies from text
+      if (inferDependencies) {
+        dependsOn = inferDependenciesFromText(title, tasks);
+        // Clean up dependency text from title
+        title = cleanDependencyText(title);
+      }
+
+      // Extract description from remaining parentheses (not dependency-related)
+      const descExtracted = extractDescription(title);
+      title = descExtracted.title;
+      description = descExtracted.description;
+
+      const task: ParsedPlanTask = {
+        title,
+        level,
+        tempId,
+        ...(parentTempId && { parentTempId }),
+        ...(description && { description }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+        ...(dependsOn && dependsOn.length > 0 && { dependsOn }),
+      };
+
+      tasks.push(task);
+
+      // Push to parent stack for potential children
+      parentStack.push({ tempId, level, indent });
+      currentParent = { tempId, level, indent };
+      continue;
+    }
+
+    // Parse numbered list items
+    const numberedMatch = line.match(/^(\s*)(\d+)[.)]\s+(.+)$/);
+    if (numberedMatch) {
+      const indent = numberedMatch[1]!.length;
+      const content = numberedMatch[3]!.trim();
+      const tempId = `task-${++taskCounter}`;
+
+      // Same logic as unordered lists
+      while (parentStack.length > 0 && parentStack[parentStack.length - 1]!.indent >= indent) {
+        parentStack.pop();
+      }
+
+      let parentTempId: string | undefined;
+      let level: number;
+
+      if (parentStack.length > 0) {
+        const parent = parentStack[parentStack.length - 1]!;
+        parentTempId = parent.tempId;
+        level = Math.min(parent.level + 1, 3);
+      } else if (currentSection) {
+        parentTempId = currentSection.tempId;
+        level = 2;
+      } else if (currentPhase) {
+        parentTempId = currentPhase.tempId;
+        level = 1;
+      } else {
+        level = 0;
+      }
+
+      let title = content;
+      let description: string | undefined;
+      let priority: Priority | undefined;
+      let tags: string[] | undefined;
+      let dependsOn: string[] | undefined;
+
+      if (parseNaturalLanguage) {
+        const metadata = extractMetadata(content);
+        title = metadata.remaining || content;
+        priority = metadata.priority;
+        tags = metadata.tags;
+      }
+
+      if (inferDependencies) {
+        dependsOn = inferDependenciesFromText(title, tasks);
+        title = cleanDependencyText(title);
+      }
+
+      // Extract description from remaining parentheses
+      const descExtracted = extractDescription(title);
+      title = descExtracted.title;
+      description = descExtracted.description;
+
+      tasks.push({
+        title,
+        level,
+        tempId,
+        ...(parentTempId && { parentTempId }),
+        ...(description && { description }),
+        priority: priority ?? defaultPriority,
+        ...(tags && tags.length > 0 && { tags }),
+        ...(dependsOn && dependsOn.length > 0 && { dependsOn }),
+      });
+
+      parentStack.push({ tempId, level, indent });
+      continue;
+    }
+  }
+
+  return { tasks, phases, warnings };
+}
+
+/**
+ * Infer dependencies from text patterns like "depends on X", "after X"
+ */
+function inferDependenciesFromText(
+  content: string,
+  existingTasks: ParsedPlanTask[]
+): string[] {
+  const deps: string[] = [];
+  const lower = content.toLowerCase();
+
+  // Pattern: (depends on|after|requires|following) "phrase" or phrase
+  const patterns = [
+    /\(?\s*depends?\s+on\s+(.+?)\s*\)?/gi,
+    /\(?\s*after\s+(.+?)\s*\)?/gi,
+    /\(?\s*requires?\s+(.+?)\s*\)?/gi,
+    /\(?\s*following\s+(.+?)\s*\)?/gi,
+    /\(?\s*blocked\s+by\s+(.+?)\s*\)?/gi,
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(lower)) !== null) {
+      const depPhrase = match[1]!.trim();
+
+      // Try to find matching task by title
+      const found = existingTasks.find((t) => {
+        const taskTitle = t.title.toLowerCase();
+        return (
+          taskTitle.includes(depPhrase) ||
+          depPhrase.includes(taskTitle) ||
+          fuzzyMatch(taskTitle, depPhrase)
+        );
+      });
+
+      if (found && !deps.includes(found.tempId)) {
+        deps.push(found.tempId);
+      }
+    }
+  }
+
+  return deps;
+}
+
+/**
+ * Simple fuzzy matching for dependency detection
+ */
+function fuzzyMatch(a: string, b: string): boolean {
+  // Remove common words and compare
+  const stopWords = ["the", "a", "an", "to", "for", "of", "in", "on", "at"];
+  const normalize = (s: string) =>
+    s
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => !stopWords.includes(w))
+      .join(" ");
+
+  const aNorm = normalize(a);
+  const bNorm = normalize(b);
+
+  // Check if significant overlap
+  const aWords = aNorm.split(" ");
+  const bWords = bNorm.split(" ");
+
+  const matches = aWords.filter((w) => bWords.includes(w));
+  return matches.length >= Math.min(2, Math.min(aWords.length, bWords.length));
+}
+
+/**
+ * Remove dependency text from title
+ */
+function cleanDependencyText(title: string): string {
+  return title
+    .replace(/\(?\s*depends?\s+on\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*after\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*requires?\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*following\s+.+?\s*\)?/gi, "")
+    .replace(/\(?\s*blocked\s+by\s+.+?\s*\)?/gi, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Extract description from title
+ *
+ * Patterns supported:
+ * - "제목: 설명" → colon separator
+ * - "제목 -- 설명" → double dash separator
+ * - "제목 (설명)" → parentheses (after dependency cleanup)
+ *
+ * @example
+ * extractDescription("API 구현: 라우팅, 인증 담당")
+ * // → { title: "API 구현", description: "라우팅, 인증 담당" }
+ *
+ * extractDescription("API 구현 (라우팅, 인증 담당)")
+ * // → { title: "API 구현", description: "라우팅, 인증 담당" }
+ */
+function extractDescription(title: string): { title: string; description?: string } {
+  // Pattern 1: Colon separator (but not time like "10:30")
+  // Match "제목: 설명" but not "10:30" or "http://..."
+  const colonMatch = title.match(/^(.+?):\s+([^/].{5,})$/);
+  if (colonMatch && !/^\d+:\d+/.test(colonMatch[2]!)) {
+    return {
+      title: colonMatch[1]!.trim(),
+      description: colonMatch[2]!.trim(),
+    };
+  }
+
+  // Pattern 2: Double dash separator "제목 -- 설명"
+  const dashMatch = title.match(/^(.+?)\s+--\s+(.+)$/);
+  if (dashMatch) {
+    return {
+      title: dashMatch[1]!.trim(),
+      description: dashMatch[2]!.trim(),
+    };
+  }
+
+  // Pattern 3: Parentheses at end (only if not dependency-like)
+  // Already cleaned by cleanDependencyText, so remaining () is description
+  const parenMatch = title.match(/^(.+?)\s*\(([^)]+)\)\s*$/);
+  if (parenMatch) {
+    const content = parenMatch[2]!.trim();
+    // Skip if looks like a short annotation (single word, abbreviation)
+    if (content.length > 3 && content.includes(" ")) {
+      return {
+        title: parenMatch[1]!.trim(),
+        description: content,
+      };
+    }
+  }
+
+  return { title };
+}