@task-mcp/shared 1.0.3 → 1.0.6

package/src/algorithms/tech-analysis.ts

@@ -0,0 +1,412 @@
+import type { Task, TechArea, RiskLevel } from "../schemas/task.js";
+
+/**
+ * Tech area ordering rules (lower = execute first)
+ * Based on dependency flow: DB changes → Infrastructure → Backend → Frontend → Tests
+ */
+const TECH_ORDER: Record<TechArea, number> = {
+  schema: 0,    // DB/schema changes first
+  infra: 0,     // Infrastructure setup
+  devops: 1,    // CI/CD pipelines
+  backend: 2,   // API/server
+  frontend: 3,  // UI
+  test: 4,      // Tests
+  docs: 4,      // Documentation
+  refactor: 5,  // Refactoring last
+};
+
+/**
+ * Risk level ordering (lower = safer, execute first)
+ */
+const RISK_ORDER: Record<RiskLevel, number> = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+/**
+ * Result of safe order suggestion
+ */
+export interface SafeOrderResult {
+  /** Tasks ordered for safe execution */
+  orderedTasks: Task[];
+  /** Grouping by phase/tech level */
+  phases: SafeOrderPhase[];
+  /** Summary statistics */
+  summary: {
+    totalTasks: number;
+    breakingChanges: number;
+    highRiskCount: number;
+  };
+}
+
+/**
+ * A phase in the safe execution order
+ */
+export interface SafeOrderPhase {
+  /** Phase number (1-based) */
+  phase: number;
+  /** Primary tech area for this phase */
+  primaryArea: TechArea | "mixed";
+  /** Tasks in this phase */
+  tasks: Task[];
+  /** Notes about this phase */
+  notes: string[];
+}
+
+/**
+ * Get the minimum tech order value for a task
+ * If multiple areas, use the lowest (most foundational)
+ */
+function getMinTechOrder(task: Task): number {
+  const areas = task.techStack?.areas ?? [];
+  if (areas.length === 0) return TECH_ORDER.backend; // Default to backend
+
+  return Math.min(...areas.map((area) => TECH_ORDER[area]));
+}
+
+/**
+ * Get the risk order value for a task
+ */
+function getRiskOrder(task: Task): number {
+  const riskLevel = task.techStack?.riskLevel ?? "medium";
+  return RISK_ORDER[riskLevel];
+}
+
+/**
+ * Check if a task has breaking changes
+ */
+function hasBreakingChange(task: Task): boolean {
+  return task.techStack?.hasBreakingChange === true;
+}
+
+/**
+ * Suggest safe execution order for tasks
+ *
+ * Ordering strategy:
+ * 1. Tech level (schema → infra → devops → backend → frontend → test → docs → refactor)
+ * 2. Risk level within same tech level (low → medium → high → critical)
+ * 3. Breaking changes last within same tech/risk level
+ * 4. Priority as tiebreaker (critical > high > medium > low)
+ */
+export function suggestSafeOrder(tasks: Task[]): SafeOrderResult {
+  // Filter to active tasks only
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  if (activeTasks.length === 0) {
+    return {
+      orderedTasks: [],
+      phases: [],
+      summary: {
+        totalTasks: 0,
+        breakingChanges: 0,
+        highRiskCount: 0,
+      },
+    };
+  }
+
+  // Sort tasks
+  const sorted = [...activeTasks].sort((a, b) => {
+    // 1. Tech level (lower first)
+    const techDiff = getMinTechOrder(a) - getMinTechOrder(b);
+    if (techDiff !== 0) return techDiff;
+
+    // 2. Risk level (lower first)
+    const riskDiff = getRiskOrder(a) - getRiskOrder(b);
+    if (riskDiff !== 0) return riskDiff;
+
+    // 3. Breaking changes last
+    const aBreaking = hasBreakingChange(a) ? 1 : 0;
+    const bBreaking = hasBreakingChange(b) ? 1 : 0;
+    if (aBreaking !== bBreaking) return aBreaking - bBreaking;
+
+    // 4. Priority as tiebreaker (higher priority first)
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    return (priorityOrder[a.priority] ?? 2) - (priorityOrder[b.priority] ?? 2);
+  });
+
+  // Group into phases by tech level
+  const phases: SafeOrderPhase[] = [];
+  let currentTechOrder = -1;
+  let currentPhase: SafeOrderPhase | null = null;
+
+  for (const task of sorted) {
+    const techOrder = getMinTechOrder(task);
+
+    if (techOrder !== currentTechOrder) {
+      // Start new phase
+      const primaryArea = getPrimaryArea(task);
+      currentPhase = {
+        phase: phases.length + 1,
+        primaryArea,
+        tasks: [task],
+        notes: [],
+      };
+      phases.push(currentPhase);
+      currentTechOrder = techOrder;
+    } else {
+      // Add to current phase
+      currentPhase!.tasks.push(task);
+    }
+  }
+
+  // Add notes to phases
+  for (const phase of phases) {
+    const breakingCount = phase.tasks.filter(hasBreakingChange).length;
+    const highRiskCount = phase.tasks.filter(
+      (t) => t.techStack?.riskLevel === "high" || t.techStack?.riskLevel === "critical"
+    ).length;
+
+    if (breakingCount > 0) {
+      phase.notes.push(`${breakingCount} breaking change(s) - test thoroughly`);
+    }
+    if (highRiskCount > 0) {
+      phase.notes.push(`${highRiskCount} high-risk task(s) - review carefully`);
+    }
+  }
+
+  // Calculate summary
+  const breakingChanges = sorted.filter(hasBreakingChange).length;
+  const highRiskCount = sorted.filter(
+    (t) => t.techStack?.riskLevel === "high" || t.techStack?.riskLevel === "critical"
+  ).length;
+
+  return {
+    orderedTasks: sorted,
+    phases,
+    summary: {
+      totalTasks: sorted.length,
+      breakingChanges,
+      highRiskCount,
+    },
+  };
+}
+
+/**
+ * Get the primary tech area for a task
+ */
+function getPrimaryArea(task: Task): TechArea | "mixed" {
+  const areas = task.techStack?.areas;
+  if (!areas || areas.length === 0) return "mixed";
+
+  // Return the one with lowest order (most foundational)
+  let primary: TechArea = areas[0]!;
+  for (let i = 1; i < areas.length; i++) {
+    const area = areas[i]!;
+    if (TECH_ORDER[area] < TECH_ORDER[primary]) {
+      primary = area;
+    }
+  }
+  return primary;
+}
+
+/**
+ * Find tasks with breaking changes
+ */
+export function findBreakingChanges(tasks: Task[]): Task[] {
+  return tasks.filter(
+    (t) =>
+      (t.status === "pending" || t.status === "in_progress") &&
+      hasBreakingChange(t)
+  );
+}
+
+/**
+ * Find high-risk tasks (high or critical risk level)
+ */
+export function findHighRiskTasks(tasks: Task[]): Task[] {
+  return tasks.filter(
+    (t) =>
+      (t.status === "pending" || t.status === "in_progress") &&
+      (t.techStack?.riskLevel === "high" || t.techStack?.riskLevel === "critical")
+  );
+}
+
+/**
+ * Group tasks by tech area
+ * A task may appear in multiple groups if it spans multiple areas
+ */
+export function groupByTechArea(tasks: Task[]): Map<TechArea, Task[]> {
+  const groups = new Map<TechArea, Task[]>();
+
+  // Initialize all groups
+  const allAreas: TechArea[] = [
+    "schema", "infra", "devops", "backend", "frontend", "test", "docs", "refactor"
+  ];
+  for (const area of allAreas) {
+    groups.set(area, []);
+  }
+
+  // Group active tasks
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  for (const task of activeTasks) {
+    const areas = task.techStack?.areas ?? [];
+    if (areas.length === 0) {
+      // Default to backend if no area specified
+      groups.get("backend")!.push(task);
+    } else {
+      for (const area of areas) {
+        groups.get(area)!.push(task);
+      }
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Complexity distribution by level
+ */
+export interface ComplexityDistribution {
+  low: number;    // 1-3
+  medium: number; // 4-6
+  high: number;   // 7-10
+}
+
+/**
+ * Get complexity summary for a project
+ */
+export interface ComplexitySummary {
+  /** Distribution of complexity scores */
+  distribution: ComplexityDistribution;
+  /** Tasks that should be broken down (score >= 7) */
+  needsBreakdown: Task[];
+  /** Average complexity score */
+  averageScore: number;
+  /** Tasks without complexity analysis */
+  unanalyzed: Task[];
+}
+
+/**
+ * Analyze complexity distribution across tasks
+ */
+export function getComplexitySummary(tasks: Task[]): ComplexitySummary {
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  const analyzed = activeTasks.filter((t) => t.complexity?.score !== undefined);
+  const unanalyzed = activeTasks.filter((t) => t.complexity?.score === undefined);
+
+  // Calculate distribution
+  const distribution: ComplexityDistribution = {
+    low: 0,
+    medium: 0,
+    high: 0,
+  };
+
+  let totalScore = 0;
+  const needsBreakdown: Task[] = [];
+
+  for (const task of analyzed) {
+    const score = task.complexity!.score!;
+    totalScore += score;
+
+    if (score <= 3) {
+      distribution.low++;
+    } else if (score <= 6) {
+      distribution.medium++;
+    } else {
+      distribution.high++;
+      needsBreakdown.push(task);
+    }
+  }
+
+  return {
+    distribution,
+    needsBreakdown,
+    averageScore: analyzed.length > 0 ? totalScore / analyzed.length : 0,
+    unanalyzed,
+  };
+}
+
+/**
+ * Get tech stack summary for a project
+ */
+export interface TechStackSummary {
+  /** Count of tasks per tech area */
+  areaCounts: Record<TechArea, number>;
+  /** Tasks with breaking changes */
+  breakingChanges: Task[];
+  /** Risk distribution */
+  riskDistribution: Record<RiskLevel, number>;
+  /** Tasks without tech stack analysis */
+  unanalyzed: Task[];
+}
+
+/**
+ * Analyze tech stack distribution across tasks
+ */
+export function getTechStackSummary(tasks: Task[]): TechStackSummary {
+  const activeTasks = tasks.filter(
+    (t) => t.status === "pending" || t.status === "in_progress"
+  );
+
+  const analyzed = activeTasks.filter((t) => t.techStack?.areas !== undefined);
+  const unanalyzed = activeTasks.filter((t) => t.techStack?.areas === undefined);
+
+  // Count by area
+  const areaCounts: Record<TechArea, number> = {
+    schema: 0,
+    infra: 0,
+    devops: 0,
+    backend: 0,
+    frontend: 0,
+    test: 0,
+    docs: 0,
+    refactor: 0,
+  };
+
+  for (const task of analyzed) {
+    for (const area of task.techStack!.areas!) {
+      areaCounts[area]++;
+    }
+  }
+
+  // Risk distribution
+  const riskDistribution: Record<RiskLevel, number> = {
+    low: 0,
+    medium: 0,
+    high: 0,
+    critical: 0,
+  };
+
+  for (const task of analyzed) {
+    const risk = task.techStack?.riskLevel ?? "medium";
+    riskDistribution[risk]++;
+  }
+
+  // Breaking changes
+  const breakingChanges = findBreakingChanges(activeTasks);
+
+  return {
+    areaCounts,
+    breakingChanges,
+    riskDistribution,
+    unanalyzed,
+  };
+}
+
+/**
+ * Suggest number of subtasks based on complexity score
+ *
+ * Mapping:
+ * 1-2: 0 (no breakdown needed)
+ * 3-4: 2
+ * 5-6: 3-4
+ * 7-8: 5-6
+ * 9-10: 7-10
+ */
+export function suggestSubtaskCount(score: number): number {
+  if (score <= 2) return 0;
+  if (score <= 4) return 2;
+  if (score <= 6) return Math.ceil((score - 4) * 0.5 + 3); // 3-4
+  if (score <= 8) return Math.ceil((score - 6) * 0.5 + 5); // 5-6
+  return Math.ceil((score - 8) * 1.5 + 7); // 7-10
+}

package/src/algorithms/topological-sort.ts

@@ -10,6 +10,67 @@ export interface TaskNode {
   estimate: number; // Duration in minutes
 }
 
+/**
+ * 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
+ */
+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;
+  }
+
+  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;
+    }
+  }
+}
+
 /**
  * Convert priority string to numeric value
  */
@@ -71,21 +132,19 @@ export function topologicalSort(tasks: Task[]): Task[] {
     }
   }
 
-  // Initialize queue with nodes that have no dependencies
-  const queue: TaskNode[] = [];
+  // Initialize priority queue with nodes that have no dependencies
+  // Using max-heap: higher priority comes out first
+  const queue = new PriorityQueue<TaskNode>((a, b) => a.priority - b.priority);
   for (const node of nodes) {
     if (inDegree.get(node.id) === 0) {
       queue.push(node);
     }
   }
 
-  // Sort by priority (higher first)
-  queue.sort((a, b) => b.priority - a.priority);
-
   const result: Task[] = [];
 
   while (queue.length > 0) {
-    const current = queue.shift()!;
+    const current = queue.pop()!;
     const task = taskMap.get(current.id);
     if (task) {
       result.push(task);
@@ -98,9 +157,7 @@ export function topologicalSort(tasks: Task[]): Task[] {
 
       if (newDegree === 0) {
         const neighborNode = nodeMap.get(neighborId)!;
-        queue.push(neighborNode);
-        // Re-sort to maintain priority order
-        queue.sort((a, b) => b.priority - a.priority);
+        queue.push(neighborNode); // O(log n) insertion maintains heap property
       }
     }
   }

package/src/schemas/inbox.ts

@@ -0,0 +1,32 @@
+import { type } from "arktype";
+
+// Inbox item status
+export const InboxStatus = type("'pending' | 'promoted' | 'discarded'");
+export type InboxStatus = typeof InboxStatus.infer;
+
+// Inbox item schema - lightweight idea/memo capture
+export const InboxItem = type({
+  id: "string",
+  content: "string", // The memo/idea content
+  capturedAt: "string", // ISO timestamp
+  "source?": "string", // Origin: 'cli', 'mcp', 'api', etc.
+  "tags?": "string[]", // Simple tags for organization
+  "promotedToTaskId?": "string", // Task ID if promoted
+  status: InboxStatus,
+});
+export type InboxItem = typeof InboxItem.infer;
+
+// Inbox item creation input (minimal)
+export const InboxCreateInput = type({
+  content: "string",
+  "source?": "string",
+  "tags?": "string[]",
+});
+export type InboxCreateInput = typeof InboxCreateInput.infer;
+
+// Inbox item update input
+export const InboxUpdateInput = type({
+  "content?": "string",
+  "tags?": "string[]",
+});
+export type InboxUpdateInput = typeof InboxUpdateInput.infer;

package/src/schemas/index.ts

@@ -6,6 +6,13 @@ export {
   Dependency,
   TimeEstimate,
   Recurrence,
+  // Analysis schemas
+  ComplexityFactor,
+  ComplexityAnalysis,
+  TechArea,
+  RiskLevel,
+  TechStackAnalysis,
+  // Core schemas
   Task,
   TaskCreateInput,
   TaskUpdateInput,
@@ -28,3 +35,27 @@ export {
   SmartView,
   BuiltInView,
 } from "./view.js";
+
+// Inbox schemas
+export {
+  InboxStatus,
+  InboxItem,
+  InboxCreateInput,
+  InboxUpdateInput,
+} from "./inbox.js";
+
+// Response format schemas (token optimization)
+export {
+  ResponseFormat,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+  type PaginatedResponse,
+  type TaskSummary,
+  type TaskPreview,
+  type ProjectSummary,
+  type ProjectPreview,
+  type InboxSummary,
+  type InboxPreview,
+  type CriticalPathSummary,
+  type BottleneckSummary,
+} from "./response-format.js";

package/src/schemas/response-format.ts

@@ -0,0 +1,108 @@
+import { type } from "arktype";
+
+/**
+ * Response Format Schema
+ *
+ * Token-efficient response formats for MCP tools.
+ * Based on Anthropic's recommended patterns for reducing token usage.
+ *
+ * - concise: Minimal fields (4-6), JSON format for machine processing
+ * - standard: Common fields (7-10), balanced for most use cases
+ * - detailed: Full object, human-readable format
+ */
+
+// Response format options
+export const ResponseFormat = type("'concise' | 'standard' | 'detailed'");
+export type ResponseFormat = typeof ResponseFormat.infer;
+
+// Default limits for pagination
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+
+/**
+ * Paginated response wrapper
+ */
+export interface PaginatedResponse<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+/**
+ * Task projection types - progressively more detailed
+ */
+
+// Concise: 4 essential fields (~30 tokens per task)
+export interface TaskSummary {
+  id: string;
+  title: string;
+  status: string;
+  priority: string;
+}
+
+// Standard: 8 common fields (~60 tokens per task)
+export interface TaskPreview extends TaskSummary {
+  dueDate?: string;
+  tags?: string[];
+  contexts?: string[];
+  parentId?: string;
+}
+
+// Detailed: Full Task object (~200+ tokens per task)
+// Use the full Task type from task.ts
+
+/**
+ * Project projection types
+ */
+
+// Concise: 4 essential fields
+export interface ProjectSummary {
+  id: string;
+  name: string;
+  status: string;
+  completionPercentage?: number;
+}
+
+// Standard: 7 common fields
+export interface ProjectPreview extends ProjectSummary {
+  description?: string;
+  totalTasks?: number;
+  completedTasks?: number;
+}
+
+/**
+ * Inbox projection types
+ */
+
+// Concise: 3 essential fields
+export interface InboxSummary {
+  id: string;
+  content: string;
+  status: string;
+}
+
+// Standard: 5 common fields
+export interface InboxPreview extends InboxSummary {
+  capturedAt: string;
+  tags?: string[];
+}
+
+/**
+ * Analysis result types - optimized for token efficiency
+ */
+
+// Critical path summary (concise format)
+export interface CriticalPathSummary {
+  totalDuration: number;
+  taskCount: number;
+  taskIds: string[];
+}
+
+// Bottleneck summary (concise format)
+export interface BottleneckSummary {
+  taskId: string;
+  title: string;
+  blockedCount: number;
+}