@task-mcp/shared 1.0.22 → 1.0.24

package/src/algorithms/dependency-integrity.ts

@@ -35,9 +35,7 @@ export interface ValidateDependencyOptions {
 /**
  * Validates if a dependency can be added between two tasks
  */
-export function validateDependency(
-  options: ValidateDependencyOptions
-): DependencyValidationResult {
+export function validateDependency(options: ValidateDependencyOptions): DependencyValidationResult {
   const { taskId, blockedBy, tasks, checkDuplicates = true } = options;
 
   // 1. Self-dependency check
@@ -117,9 +115,7 @@ export interface InvalidDependencyReference {
 /**
  * Find all invalid dependency references (orphaned references)
  */
-export function findInvalidDependencies(
-  tasks: Task[]
-): InvalidDependencyReference[] {
+export function findInvalidDependencies(tasks: Task[]): InvalidDependencyReference[] {
   const taskIds = new Set(tasks.map((t) => t.id));
   const invalid: InvalidDependencyReference[] = [];
 
@@ -242,17 +238,12 @@ export interface DependencyIntegrityReport {
 /**
  * Check overall dependency integrity of a project
  */
-export function checkDependencyIntegrity(
-  tasks: Task[]
-): DependencyIntegrityReport {
+export function checkDependencyIntegrity(tasks: Task[]): DependencyIntegrityReport {
   const selfDeps = findSelfDependencies(tasks);
   const invalidRefs = findInvalidDependencies(tasks);
   const cycles = detectCircularDependencies(tasks);
 
-  const totalDependencies = tasks.reduce(
-    (sum, t) => sum + (t.dependencies?.length ?? 0),
-    0
-  );
+  const totalDependencies = tasks.reduce((sum, t) => sum + (t.dependencies?.length ?? 0), 0);
 
   const issueCount = selfDeps.length + invalidRefs.length + cycles.length;
   const valid = issueCount === 0;

package/src/algorithms/tech-analysis.test.ts

@@ -0,0 +1,405 @@
+import { describe, test, expect } from "bun:test";
+import {
+  suggestSafeOrder,
+  findBreakingChanges,
+  findHighRiskTasks,
+  groupByTechArea,
+  getComplexitySummary,
+  getTechStackSummary,
+  suggestSubtaskCount,
+} from "./tech-analysis.js";
+import type { Task, TechArea, RiskLevel } from "../schemas/task.js";
+
+// Helper to create mock tasks with tech stack analysis
+function createTask(
+  id: string,
+  options: {
+    priority?: "critical" | "high" | "medium" | "low";
+    status?: "pending" | "in_progress" | "completed" | "blocked" | "cancelled";
+    areas?: TechArea[];
+    riskLevel?: RiskLevel;
+    hasBreakingChange?: boolean;
+    complexityScore?: number;
+  } = {}
+): Task {
+  const task: Task = {
+    id,
+    title: `Task ${id}`,
+    status: options.status ?? "pending",
+    priority: options.priority ?? "medium",
+    workspace: "test-workspace",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  if (options.areas || options.riskLevel !== undefined || options.hasBreakingChange !== undefined) {
+    task.techStack = {};
+    if (options.areas) {
+      task.techStack.areas = options.areas;
+    }
+    if (options.riskLevel !== undefined) {
+      task.techStack.riskLevel = options.riskLevel;
+    }
+    if (options.hasBreakingChange !== undefined) {
+      task.techStack.hasBreakingChange = options.hasBreakingChange;
+    }
+  }
+
+  if (options.complexityScore !== undefined) {
+    task.complexity = {
+      score: options.complexityScore,
+    };
+  }
+
+  return task;
+}
+
+describe("suggestSafeOrder", () => {
+  test("returns empty result for empty input", () => {
+    const result = suggestSafeOrder([]);
+    expect(result.orderedTasks).toEqual([]);
+    expect(result.phases).toEqual([]);
+    expect(result.summary.totalTasks).toBe(0);
+  });
+
+  test("returns empty for all completed tasks", () => {
+    const tasks = [createTask("A", { status: "completed" })];
+    const result = suggestSafeOrder(tasks);
+    expect(result.orderedTasks).toEqual([]);
+  });
+
+  test("orders by tech level (schema before backend)", () => {
+    const tasks = [
+      createTask("backend-task", { areas: ["backend"] }),
+      createTask("schema-task", { areas: ["schema"] }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    expect(result.orderedTasks[0]!.id).toBe("schema-task");
+    expect(result.orderedTasks[1]!.id).toBe("backend-task");
+  });
+
+  test("orders by tech level (full chain)", () => {
+    const tasks = [
+      createTask("frontend", { areas: ["frontend"] }),
+      createTask("backend", { areas: ["backend"] }),
+      createTask("schema", { areas: ["schema"] }),
+      createTask("test", { areas: ["test"] }),
+      createTask("devops", { areas: ["devops"] }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    const order = result.orderedTasks.map((t) => t.id);
+    expect(order).toEqual(["schema", "devops", "backend", "frontend", "test"]);
+  });
+
+  test("orders by risk level within same tech level", () => {
+    const tasks = [
+      createTask("high-risk", { areas: ["backend"], riskLevel: "high" }),
+      createTask("low-risk", { areas: ["backend"], riskLevel: "low" }),
+      createTask("medium-risk", { areas: ["backend"], riskLevel: "medium" }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    const order = result.orderedTasks.map((t) => t.id);
+    expect(order).toEqual(["low-risk", "medium-risk", "high-risk"]);
+  });
+
+  test("puts breaking changes last within same tech/risk level", () => {
+    const tasks = [
+      createTask("breaking", { areas: ["backend"], riskLevel: "low", hasBreakingChange: true }),
+      createTask("safe", { areas: ["backend"], riskLevel: "low", hasBreakingChange: false }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    expect(result.orderedTasks[0]!.id).toBe("safe");
+    expect(result.orderedTasks[1]!.id).toBe("breaking");
+  });
+
+  test("uses priority as tiebreaker", () => {
+    const tasks = [
+      createTask("low-priority", { areas: ["backend"], priority: "low" }),
+      createTask("high-priority", { areas: ["backend"], priority: "high" }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    expect(result.orderedTasks[0]!.id).toBe("high-priority");
+    expect(result.orderedTasks[1]!.id).toBe("low-priority");
+  });
+
+  test("groups tasks into phases by tech level", () => {
+    const tasks = [
+      createTask("schema1", { areas: ["schema"] }),
+      createTask("schema2", { areas: ["schema"] }),
+      createTask("backend1", { areas: ["backend"] }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    expect(result.phases.length).toBe(2);
+    expect(result.phases[0]!.primaryArea).toBe("schema");
+    expect(result.phases[0]!.tasks.length).toBe(2);
+    expect(result.phases[1]!.primaryArea).toBe("backend");
+    expect(result.phases[1]!.tasks.length).toBe(1);
+  });
+
+  test("calculates summary statistics correctly", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], hasBreakingChange: true }),
+      createTask("t2", { areas: ["backend"], riskLevel: "high" }),
+      createTask("t3", { areas: ["backend"], riskLevel: "critical" }),
+      createTask("t4", { areas: ["backend"] }),
+    ];
+    const result = suggestSafeOrder(tasks);
+
+    expect(result.summary.totalTasks).toBe(4);
+    expect(result.summary.breakingChanges).toBe(1);
+    expect(result.summary.highRiskCount).toBe(2);
+  });
+});
+
+describe("findBreakingChanges", () => {
+  test("returns empty for no breaking changes", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], hasBreakingChange: false }),
+      createTask("t2", { areas: ["backend"] }),
+    ];
+    const result = findBreakingChanges(tasks);
+    expect(result).toEqual([]);
+  });
+
+  test("finds tasks with breaking changes", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], hasBreakingChange: true }),
+      createTask("t2", { areas: ["backend"], hasBreakingChange: false }),
+      createTask("t3", { areas: ["schema"], hasBreakingChange: true }),
+    ];
+    const result = findBreakingChanges(tasks);
+    expect(result.length).toBe(2);
+    expect(result.map((t) => t.id).sort()).toEqual(["t1", "t3"]);
+  });
+
+  test("excludes completed tasks", () => {
+    const tasks = [
+      createTask("t1", { status: "completed", areas: ["backend"], hasBreakingChange: true }),
+      createTask("t2", { status: "pending", areas: ["backend"], hasBreakingChange: true }),
+    ];
+    const result = findBreakingChanges(tasks);
+    expect(result.length).toBe(1);
+    expect(result[0]!.id).toBe("t2");
+  });
+});
+
+describe("findHighRiskTasks", () => {
+  test("returns empty for no high-risk tasks", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], riskLevel: "low" }),
+      createTask("t2", { areas: ["backend"], riskLevel: "medium" }),
+    ];
+    const result = findHighRiskTasks(tasks);
+    expect(result).toEqual([]);
+  });
+
+  test("finds high and critical risk tasks", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], riskLevel: "low" }),
+      createTask("t2", { areas: ["backend"], riskLevel: "high" }),
+      createTask("t3", { areas: ["backend"], riskLevel: "critical" }),
+    ];
+    const result = findHighRiskTasks(tasks);
+    expect(result.length).toBe(2);
+    expect(result.map((t) => t.id).sort()).toEqual(["t2", "t3"]);
+  });
+});
+
+describe("groupByTechArea", () => {
+  test("returns all areas with empty arrays for empty input", () => {
+    const result = groupByTechArea([]);
+    expect(result.get("schema")).toEqual([]);
+    expect(result.get("backend")).toEqual([]);
+    expect(result.get("frontend")).toEqual([]);
+  });
+
+  test("groups tasks by their tech areas", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"] }),
+      createTask("t2", { areas: ["backend"] }),
+      createTask("t3", { areas: ["frontend"] }),
+    ];
+    const result = groupByTechArea(tasks);
+
+    expect(result.get("backend")!.length).toBe(2);
+    expect(result.get("frontend")!.length).toBe(1);
+    expect(result.get("schema")!.length).toBe(0);
+  });
+
+  test("task appears in multiple groups if it spans multiple areas", () => {
+    const tasks = [createTask("fullstack", { areas: ["backend", "frontend"] })];
+    const result = groupByTechArea(tasks);
+
+    expect(result.get("backend")!.length).toBe(1);
+    expect(result.get("frontend")!.length).toBe(1);
+    expect(result.get("backend")![0]!.id).toBe("fullstack");
+  });
+
+  test("defaults to backend if no area specified", () => {
+    const tasks = [createTask("t1", {})];
+    const result = groupByTechArea(tasks);
+    expect(result.get("backend")!.length).toBe(1);
+  });
+
+  test("excludes completed tasks", () => {
+    const tasks = [
+      createTask("t1", { status: "completed", areas: ["backend"] }),
+      createTask("t2", { status: "pending", areas: ["backend"] }),
+    ];
+    const result = groupByTechArea(tasks);
+    expect(result.get("backend")!.length).toBe(1);
+  });
+});
+
+describe("getComplexitySummary", () => {
+  test("returns empty summary for no tasks", () => {
+    const result = getComplexitySummary([]);
+    expect(result.distribution).toEqual({ low: 0, medium: 0, high: 0 });
+    expect(result.needsBreakdown).toEqual([]);
+    expect(result.averageScore).toBe(0);
+    expect(result.unanalyzed).toEqual([]);
+  });
+
+  test("calculates distribution correctly", () => {
+    const tasks = [
+      createTask("t1", { complexityScore: 2 }), // low
+      createTask("t2", { complexityScore: 3 }), // low
+      createTask("t3", { complexityScore: 5 }), // medium
+      createTask("t4", { complexityScore: 8 }), // high
+    ];
+    const result = getComplexitySummary(tasks);
+
+    expect(result.distribution.low).toBe(2);
+    expect(result.distribution.medium).toBe(1);
+    expect(result.distribution.high).toBe(1);
+  });
+
+  test("identifies tasks needing breakdown (score >= 7)", () => {
+    const tasks = [
+      createTask("t1", { complexityScore: 6 }),
+      createTask("t2", { complexityScore: 7 }),
+      createTask("t3", { complexityScore: 9 }),
+    ];
+    const result = getComplexitySummary(tasks);
+
+    expect(result.needsBreakdown.length).toBe(2);
+    expect(result.needsBreakdown.map((t) => t.id).sort()).toEqual(["t2", "t3"]);
+  });
+
+  test("calculates average score correctly", () => {
+    const tasks = [
+      createTask("t1", { complexityScore: 2 }),
+      createTask("t2", { complexityScore: 6 }),
+      createTask("t3", { complexityScore: 10 }),
+    ];
+    const result = getComplexitySummary(tasks);
+
+    expect(result.averageScore).toBe(6); // (2+6+10)/3
+  });
+
+  test("identifies unanalyzed tasks", () => {
+    const tasks = [createTask("analyzed", { complexityScore: 5 }), createTask("not-analyzed", {})];
+    const result = getComplexitySummary(tasks);
+
+    expect(result.unanalyzed.length).toBe(1);
+    expect(result.unanalyzed[0]!.id).toBe("not-analyzed");
+  });
+
+  test("excludes completed tasks", () => {
+    const tasks = [
+      createTask("t1", { status: "completed", complexityScore: 10 }),
+      createTask("t2", { status: "pending", complexityScore: 5 }),
+    ];
+    const result = getComplexitySummary(tasks);
+
+    expect(result.distribution.high).toBe(0);
+    expect(result.distribution.medium).toBe(1);
+  });
+});
+
+describe("getTechStackSummary", () => {
+  test("returns empty summary for no tasks", () => {
+    const result = getTechStackSummary([]);
+    expect(result.areaCounts.schema).toBe(0);
+    expect(result.breakingChanges).toEqual([]);
+    expect(result.unanalyzed).toEqual([]);
+  });
+
+  test("counts tasks by area correctly", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"] }),
+      createTask("t2", { areas: ["backend", "frontend"] }),
+      createTask("t3", { areas: ["schema"] }),
+    ];
+    const result = getTechStackSummary(tasks);
+
+    expect(result.areaCounts.backend).toBe(2);
+    expect(result.areaCounts.frontend).toBe(1);
+    expect(result.areaCounts.schema).toBe(1);
+  });
+
+  test("tracks risk distribution", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], riskLevel: "low" }),
+      createTask("t2", { areas: ["backend"], riskLevel: "medium" }),
+      createTask("t3", { areas: ["backend"], riskLevel: "high" }),
+    ];
+    const result = getTechStackSummary(tasks);
+
+    expect(result.riskDistribution.low).toBe(1);
+    expect(result.riskDistribution.medium).toBe(1);
+    expect(result.riskDistribution.high).toBe(1);
+  });
+
+  test("identifies breaking changes", () => {
+    const tasks = [
+      createTask("t1", { areas: ["backend"], hasBreakingChange: true }),
+      createTask("t2", { areas: ["backend"], hasBreakingChange: false }),
+    ];
+    const result = getTechStackSummary(tasks);
+
+    expect(result.breakingChanges.length).toBe(1);
+    expect(result.breakingChanges[0]!.id).toBe("t1");
+  });
+
+  test("identifies unanalyzed tasks", () => {
+    const tasks = [createTask("analyzed", { areas: ["backend"] }), createTask("not-analyzed", {})];
+    const result = getTechStackSummary(tasks);
+
+    expect(result.unanalyzed.length).toBe(1);
+    expect(result.unanalyzed[0]!.id).toBe("not-analyzed");
+  });
+});
+
+describe("suggestSubtaskCount", () => {
+  test("returns 0 for very low complexity (1-2)", () => {
+    expect(suggestSubtaskCount(1)).toBe(0);
+    expect(suggestSubtaskCount(2)).toBe(0);
+  });
+
+  test("returns 2 for low complexity (3-4)", () => {
+    expect(suggestSubtaskCount(3)).toBe(2);
+    expect(suggestSubtaskCount(4)).toBe(2);
+  });
+
+  test("returns 3-4 for medium complexity (5-6)", () => {
+    expect(suggestSubtaskCount(5)).toBe(4);
+    expect(suggestSubtaskCount(6)).toBe(4);
+  });
+
+  test("returns 5-6 for high complexity (7-8)", () => {
+    expect(suggestSubtaskCount(7)).toBe(6);
+    expect(suggestSubtaskCount(8)).toBe(6);
+  });
+
+  test("returns 7-10 for very high complexity (9-10)", () => {
+    expect(suggestSubtaskCount(9)).toBe(9);
+    expect(suggestSubtaskCount(10)).toBe(10);
+  });
+});

package/src/algorithms/tech-analysis.ts

@@ -5,14 +5,14 @@ import type { Task, TechArea, RiskLevel } from "../schemas/task.js";
  * 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
+  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
 };
 
 /**
@@ -143,9 +143,7 @@ function hasBreakingChange(task: Task): boolean {
  */
 export function suggestSafeOrder(tasks: Task[]): SafeOrderResult {
   // Filter to active tasks only
-  const activeTasks = tasks.filter(
-    (t) => t.status === "pending" || t.status === "in_progress"
-  );
+  const activeTasks = tasks.filter((t) => t.status === "pending" || t.status === "in_progress");
 
   if (activeTasks.length === 0) {
     return {
@@ -175,7 +173,10 @@ export function suggestSafeOrder(tasks: Task[]): SafeOrderResult {
     if (aBreaking !== bBreaking) return aBreaking - bBreaking;
 
     // 4. Priority as tiebreaker (higher priority first)
-    return (PRIORITY_ORDER[a.priority] ?? DEFAULT_PRIORITY_ORDER) - (PRIORITY_ORDER[b.priority] ?? DEFAULT_PRIORITY_ORDER);
+    return (
+      (PRIORITY_ORDER[a.priority] ?? DEFAULT_PRIORITY_ORDER) -
+      (PRIORITY_ORDER[b.priority] ?? DEFAULT_PRIORITY_ORDER)
+    );
   });
 
   // Group into phases by tech level
@@ -258,9 +259,7 @@ function getPrimaryArea(task: Task): TechArea | "mixed" {
  */
 export function findBreakingChanges(tasks: Task[]): Task[] {
   return tasks.filter(
-    (t) =>
-      (t.status === "pending" || t.status === "in_progress") &&
-      hasBreakingChange(t)
+    (t) => (t.status === "pending" || t.status === "in_progress") && hasBreakingChange(t)
   );
 }
 
@@ -284,16 +283,21 @@ export function groupByTechArea(tasks: Task[]): Map<TechArea, Task[]> {
 
   // Initialize all groups
   const allAreas: TechArea[] = [
-    "schema", "infra", "devops", "backend", "frontend", "test", "docs", "refactor"
+    "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"
-  );
+  const activeTasks = tasks.filter((t) => t.status === "pending" || t.status === "in_progress");
 
   for (const task of activeTasks) {
     const areas = task.techStack?.areas ?? [];
@@ -314,9 +318,9 @@ export function groupByTechArea(tasks: Task[]): Map<TechArea, Task[]> {
  * Complexity distribution by level
  */
 export interface ComplexityDistribution {
-  low: number;    // 1 to LOW_MAX
+  low: number; // 1 to LOW_MAX
   medium: number; // LOW_MAX+1 to MEDIUM_MAX
-  high: number;   // MEDIUM_MAX+1 to 10
+  high: number; // MEDIUM_MAX+1 to 10
 }
 
 /**
@@ -337,9 +341,7 @@ export interface ComplexitySummary {
  * Analyze complexity distribution across tasks
  */
 export function getComplexitySummary(tasks: Task[]): ComplexitySummary {
-  const activeTasks = tasks.filter(
-    (t) => t.status === "pending" || t.status === "in_progress"
-  );
+  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);
@@ -394,9 +396,7 @@ export interface TechStackSummary {
  * 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 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);