@critical-path/core 0.20.2 → 0.22.0

package/src/status.test.ts

@@ -1,7 +1,22 @@
 import { describe, it, expect } from 'vitest';
 import { CriticalPathEngine } from './engine/index.js';
-import { resolveStatusDefinition, deriveTaskLifecycleState } from './utils/status.js';
-import type { Task, StatusDefinition } from './types/index.js';
+import {
+  resolveStatusDefinition,
+  deriveTaskLifecycleState,
+  isDraftTask,
+  isArchivedTask,
+  isTrashedTask,
+  isTrashedOrArchivedTask,
+  isWorkflowTask,
+  getTaskSemanticStatus,
+  isTaskCompleted,
+  isTaskInProgress,
+  isTaskNotStarted,
+  isTaskCanceled,
+  isTaskActive,
+  isTaskUnassigned
+} from './utils/status.js';
+import type { Task, StatusDefinition, Workflow } from './types/index.js';
 
 describe('Universal Semantic Statuses & Implied Statuses', () => {
   describe('resolveStatusDefinition', () => {
@@ -223,4 +238,117 @@ describe('Universal Semantic Statuses & Implied Statuses', () => {
       expect(stateB?.blockingTaskIds).toEqual([]);
     });
   });
+
+  describe('Canonical Task Lifecycle & Semantic Status Predicates', () => {
+    it('identifies draft, archived, and trashed tasks properly', () => {
+      expect(isDraftTask(null)).toBe(false);
+      expect(isDraftTask({ isDraft: true })).toBe(true);
+      expect(isDraftTask({ isDraft: false })).toBe(false);
+
+      expect(isArchivedTask(null)).toBe(false);
+      expect(isArchivedTask({ archived: true })).toBe(true);
+      expect(isArchivedTask({ archivedAt: '2026-09-01T00:00:00Z' })).toBe(true);
+      expect(isArchivedTask({ status: 'archived' })).toBe(true);
+      expect(isArchivedTask({ customFields: { isArchived: true } })).toBe(true);
+      expect(isArchivedTask({ status: 'todo' })).toBe(false);
+
+      expect(isTrashedTask(null)).toBe(false);
+      expect(isTrashedTask({ trashed: true })).toBe(true);
+      expect(isTrashedTask({ trashedAt: '2026-09-01T00:00:00Z' })).toBe(true);
+      expect(isTrashedTask({ status: 'trashed' })).toBe(true);
+      expect(isTrashedTask({ customFields: { isTrashed: true } })).toBe(true);
+      expect(isTrashedTask({ status: 'todo' })).toBe(false);
+
+      expect(isTrashedOrArchivedTask({ trashed: true })).toBe(true);
+      expect(isTrashedOrArchivedTask({ archived: true })).toBe(true);
+      expect(isTrashedOrArchivedTask({ status: 'todo' })).toBe(false);
+    });
+
+    it('identifies workflow tasks excluding draft, trashed, and archived tasks (UCH-137)', () => {
+      expect(isWorkflowTask(null)).toBe(false);
+      expect(isWorkflowTask({ status: 'todo' })).toBe(true);
+      expect(isWorkflowTask({ status: 'in_progress' })).toBe(true);
+      expect(isWorkflowTask({ status: 'done' })).toBe(true);
+
+      // Draft tasks are excluded
+      expect(isWorkflowTask({ status: 'todo', isDraft: true })).toBe(false);
+      // Trashed tasks are excluded
+      expect(isWorkflowTask({ status: 'todo', trashed: true })).toBe(false);
+      // Archived tasks are excluded
+      expect(isWorkflowTask({ status: 'done', archived: true })).toBe(false);
+    });
+
+    it('resolves semantic status using workflow, defaults, and custom definitions', () => {
+      const mockWorkflow: Workflow = {
+        id: 'wf_custom',
+        name: 'Custom Flow',
+        isDefault: true,
+        statuses: [
+          { key: 'discovery', label: 'Discovery', category: 'not_started' },
+          { key: 'developing', label: 'Developing', category: 'in_progress' },
+          { key: 'delivered', label: 'Delivered', category: 'completed' },
+          { key: 'dropped', label: 'Dropped', category: 'canceled' }
+        ],
+        transitions: [],
+        createdAt: '2026-09-01T00:00:00Z',
+        updatedAt: '2026-09-01T00:00:00Z'
+      };
+
+      expect(getTaskSemanticStatus({ status: 'developing' }, mockWorkflow)).toBe('in_progress');
+      expect(getTaskSemanticStatus({ status: 'delivered' }, mockWorkflow)).toBe('completed');
+      expect(getTaskSemanticStatus({ status: 'dropped' }, mockWorkflow)).toBe('canceled');
+      expect(getTaskSemanticStatus({ status: 'discovery' }, mockWorkflow)).toBe('not_started');
+
+      // Falls back to standard defaults when not in custom workflow
+      expect(getTaskSemanticStatus({ status: 'in_progress' }, mockWorkflow)).toBe('in_progress');
+      expect(getTaskSemanticStatus({ status: 'done' })).toBe('completed');
+      expect(getTaskSemanticStatus({ status: 'todo' })).toBe('not_started');
+      expect(getTaskSemanticStatus({ status: 'canceled' })).toBe('canceled');
+    });
+
+    it('verifies lifecycle predicates (completed, in_progress, not_started, canceled, active)', () => {
+      const taskDone = { status: 'done' };
+      const taskActive = { status: 'in_progress' };
+      const taskTodo = { status: 'todo' };
+      const taskCanceled = { status: 'canceled' };
+
+      expect(isTaskCompleted(taskDone)).toBe(true);
+      expect(isTaskCompleted(taskActive)).toBe(false);
+
+      expect(isTaskInProgress(taskActive)).toBe(true);
+      expect(isTaskInProgress(taskDone)).toBe(false);
+
+      expect(isTaskNotStarted(taskTodo)).toBe(true);
+      expect(isTaskNotStarted(taskActive)).toBe(false);
+
+      expect(isTaskCanceled(taskCanceled)).toBe(true);
+      expect(isTaskCanceled(taskDone)).toBe(false);
+
+      // Active tasks
+      expect(isTaskActive(taskTodo)).toBe(true);
+      expect(isTaskActive(taskActive)).toBe(true);
+      expect(isTaskActive(taskDone)).toBe(false);
+      expect(isTaskActive(taskCanceled)).toBe(false);
+      expect(isTaskActive({ ...taskActive, isDraft: true })).toBe(false);
+      expect(isTaskActive({ ...taskActive, archived: true })).toBe(false);
+      expect(isTaskActive({ ...taskActive, trashed: true })).toBe(false);
+    });
+
+    it('identifies unassigned tasks properly', () => {
+      expect(isTaskUnassigned(null)).toBe(true);
+      expect(isTaskUnassigned({})).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: undefined })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: '' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: 'unassigned' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: '  UNASSIGNED  ' })).toBe(true);
+      expect(isTaskUnassigned({ assigneeId: 'user_123' })).toBe(false);
+
+      // Assignees array checks
+      expect(isTaskUnassigned({ assignees: [] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: ['unassigned'] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: [{ id: 'unassigned', name: 'unassigned' }] })).toBe(true);
+      expect(isTaskUnassigned({ assignees: ['user_456'] })).toBe(false);
+      expect(isTaskUnassigned({ assignees: [{ id: 'user_456', name: 'Alice' }] })).toBe(false);
+    });
+  });
 });

package/src/store/sqlite.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SQLiteStore } from './sqlite.js';
 
 describe('SQLiteStore', () => {
@@ -194,3 +197,22 @@ describe('SQLiteStore', () => {
     expect(remaining).toHaveLength(0);
   });
 });
+
+describe('SQLiteStore outside the vitest runtime', () => {
+  const distEntry = fileURLToPath(new URL('../../dist/index.js', import.meta.url));
+
+  // vitest injects `require` into ESM modules, which once hid an `eval("require(...)")` failure
+  // that broke `new SQLiteStore({ filename })` in plain Node. Run the built package in a real Node process.
+  it.skipIf(!existsSync(distEntry))('constructs from a filename in a plain Node ESM process', () => {
+    const script = `
+      const { SQLiteStore } = await import(${JSON.stringify(pathToFileURL(distEntry).href)});
+      const store = new SQLiteStore({ filename: ':memory:' });
+      const project = await store.createProject({ key: 'SMOKE', name: 'Smoke' });
+      process.stdout.write(project.key);
+    `;
+    const output = execFileSync(process.execPath, ['--input-type=module', '--no-warnings', '-e', script], {
+      encoding: 'utf8'
+    });
+    expect(output).toBe('SMOKE');
+  });
+});

package/src/store/sqlite.ts

@@ -41,7 +41,13 @@ export class SQLiteStore implements StorageAdapter {
         throw new Error('SQLiteStore is only available in Node.js environments.');
       }
       try {
-        const nodeSqlite = eval("require('node:sqlite')");
+        // `require` is undefined in ESM, and a static import would break browser bundles of core.
+        const nodeSqlite = (globalThis as any).process?.getBuiltinModule?.('node:sqlite') as
+          | typeof import('node:sqlite')
+          | undefined;
+        if (!nodeSqlite) {
+          throw new Error('process.getBuiltinModule is unavailable (requires Node.js 22.3+)');
+        }
         this.db = new nodeSqlite.DatabaseSync(config.filename || ':memory:');
       } catch (err: any) {
         throw new Error(`Failed to load node:sqlite module: ${err.message}`);
@@ -123,6 +129,7 @@ export class SQLiteStore implements StorageAdapter {
         plannedStartDate TEXT,
         actualStartDate TEXT,
         actualEndDate TEXT,
+        completedAt TEXT,
         dueDate TEXT,
         estimatedHours REAL,
         loggedHours REAL,
@@ -266,6 +273,12 @@ export class SQLiteStore implements StorageAdapter {
     } catch {
       // Column may already exist
     }
+
+    try {
+      this.db.exec('ALTER TABLE tasks ADD COLUMN completedAt TEXT');
+    } catch {
+      // Column may already exist
+    }
   }
 
   // --- Projects ---
@@ -662,13 +675,13 @@ export class SQLiteStore implements StorageAdapter {
     const stmt = this.db.prepare(`
       INSERT INTO tasks (
         id, projectId, title, description, status, priority, taskType, assigneeId, assignees, reporterId,
-        reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate,
+        reviewerId, iterationId, teamId, containerId, deliverableId, plannedStartDate, actualStartDate, actualEndDate, completedAt,
         dueDate, estimatedHours, loggedHours, actualHours, billableHours,
         estimatedDurationMinutes, actualDurationMinutes, billableDurationMinutes,
         actualDurationSeconds, inProgressSince, blockedDurationSeconds, blockedSince, progress,
         isBlocked, blockedReason,
         tags, customFields, parentId, createdAt, updatedAt
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmt.run(
       newTask.id,
@@ -689,6 +702,7 @@ export class SQLiteStore implements StorageAdapter {
       newTask.plannedStartDate || null,
       newTask.actualStartDate || null,
       newTask.actualEndDate || null,
+      newTask.completedAt || null,
       newTask.dueDate || null,
       newTask.estimatedHours ?? null,
       newTask.loggedHours ?? null,
@@ -727,7 +741,7 @@ export class SQLiteStore implements StorageAdapter {
       UPDATE tasks SET
         projectId = ?, title = ?, description = ?, status = ?, priority = ?, taskType = ?,
         assigneeId = ?, assignees = ?, reporterId = ?, reviewerId = ?, iterationId = ?, teamId = ?, containerId = ?, deliverableId = ?,
-        plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, dueDate = ?,
+        plannedStartDate = ?, actualStartDate = ?, actualEndDate = ?, completedAt = ?, dueDate = ?,
         estimatedHours = ?, loggedHours = ?, actualHours = ?, billableHours = ?,
         estimatedDurationMinutes = ?, actualDurationMinutes = ?, billableDurationMinutes = ?,
         actualDurationSeconds = ?, inProgressSince = ?, blockedDurationSeconds = ?, blockedSince = ?, progress = ?,
@@ -753,6 +767,7 @@ export class SQLiteStore implements StorageAdapter {
       updated.plannedStartDate || null,
       updated.actualStartDate || null,
       updated.actualEndDate || null,
+      updated.completedAt || null,
       updated.dueDate || null,
       updated.estimatedHours ?? null,
       updated.loggedHours ?? null,
@@ -1214,6 +1229,8 @@ export class SQLiteStore implements StorageAdapter {
       inProgressSince: row.inProgressSince || undefined,
       blockedDurationSeconds: row.blockedDurationSeconds ?? undefined,
       blockedSince: row.blockedSince || undefined,
+      actualEndDate: row.actualEndDate || undefined,
+      completedAt: row.completedAt || undefined,
       isBlocked: row.isBlocked !== null && row.isBlocked !== undefined ? Boolean(row.isBlocked) : undefined,
       blockedReason: row.blockedReason || undefined,
       taskType: row.taskType || undefined,

package/src/types/index.ts

@@ -205,6 +205,7 @@ export interface Task {
   plannedStartDate?: string;
   actualStartDate?: string;
   actualEndDate?: string;
+  completedAt?: string;
   dueDate?: string;
   // Duration & Effort (in hours and/or minutes)
   estimatedHours?: number;
@@ -408,6 +409,7 @@ export interface Webhook {
 export type WebhookEvent =
   | 'project.created'
   | 'project.updated'
+  | 'project.deleted'
   | 'task.created'
   | 'task.updated'
   | 'task.deleted'

package/src/utils/fractional-index.test.ts

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'vitest';
+import {
+  encodeInteger,
+  decodeInteger,
+  getIntegerPart,
+  getInitialKey,
+  generateKeyBetween,
+  generateNKeysBetween,
+  compareOrderIndices
+} from './fractional-index.js';
+
+describe('fractional-index', () => {
+  describe('encodeInteger and decodeInteger', () => {
+    it('encodes and decodes non-negative integers', () => {
+      const cases = [0, 1, 2, 9, 10, 61, 62, 100, 1000, 3843, 3844];
+      for (const n of cases) {
+        const encoded = encodeInteger(n);
+        expect(decodeInteger(encoded)).toBe(n);
+      }
+    });
+
+    it('encodes and decodes negative integers', () => {
+      const cases = [-1, -2, -10, -62, -100, -1000];
+      for (const n of cases) {
+        const encoded = encodeInteger(n);
+        expect(decodeInteger(encoded)).toBe(n);
+      }
+    });
+
+    it('strictly maintains lexicographical sorting across integers', () => {
+      const sequence = [-100, -62, -10, -2, -1, 0, 1, 2, 9, 10, 61, 62, 100, 3843, 3844];
+      const encoded = sequence.map((n) => encodeInteger(n));
+
+      for (let i = 0; i < encoded.length - 1; i++) {
+        expect(encoded[i] < encoded[i + 1]).toBe(true);
+        expect(compareOrderIndices(encoded[i], encoded[i + 1])).toBeLessThan(0);
+      }
+
+      // Reversing and sorting with compareOrderIndices or standard sort() restores exact order
+      const reversed = [...encoded].reverse();
+      expect(reversed.sort(compareOrderIndices)).toEqual(encoded);
+      expect([...encoded].reverse().sort()).toEqual(encoded);
+    });
+  });
+
+  describe('getInitialKey', () => {
+    it('generates spaced initial keys', () => {
+      const k0 = getInitialKey(0);
+      const k1 = getInitialKey(1);
+      const k2 = getInitialKey(2);
+
+      expect(k0).toBe('a0');
+      expect(k1).toBe('a2');
+      expect(k2).toBe('a4');
+
+      expect(k0 < k1).toBe(true);
+      expect(k1 < k2).toBe(true);
+    });
+  });
+
+  describe('generateKeyBetween', () => {
+    it('returns default initial key when both bounds are null/undefined', () => {
+      expect(generateKeyBetween(null, null)).toBe('a0');
+      expect(generateKeyBetween(undefined, undefined)).toBe('a0');
+      expect(generateKeyBetween('', '')).toBe('a0');
+    });
+
+    it('generates a key before an upper bound', () => {
+      const b0 = 'a0';
+      const beforeB0 = generateKeyBetween(null, b0);
+      expect(beforeB0 < b0).toBe(true);
+
+      const b1 = 'a1';
+      const beforeB1 = generateKeyBetween(null, b1);
+      expect(beforeB1 < b1).toBe(true);
+
+      const bFractional = 'a0V';
+      const beforeFractional = generateKeyBetween(null, bFractional);
+      expect(beforeFractional < bFractional).toBe(true);
+    });
+
+    it('generates a key after a lower bound', () => {
+      const a0 = 'a0';
+      const afterA0 = generateKeyBetween(a0, null);
+      expect(a0 < afterA0).toBe(true);
+
+      const aFractional = 'a0V';
+      const afterFractional = generateKeyBetween(aFractional, null);
+      expect(aFractional < afterFractional).toBe(true);
+    });
+
+    it('generates key between spaced integers', () => {
+      const a = 'a0';
+      const b = 'a2';
+      const mid = generateKeyBetween(a, b);
+
+      expect(mid).toBe('a1');
+      expect(a < mid).toBe(true);
+      expect(mid < b).toBe(true);
+    });
+
+    it('generates fractional key between adjacent integers', () => {
+      const a = 'a0';
+      const b = 'a1';
+      const mid = generateKeyBetween(a, b);
+
+      expect(a < mid).toBe(true);
+      expect(mid < b).toBe(true);
+    });
+
+    it('handles nested fractional insertions without degradation', () => {
+      let current = 'a0';
+      const target = 'a1';
+
+      // Perform 50 sequential midpoint insertions
+      for (let i = 0; i < 50; i++) {
+        const next = generateKeyBetween(current, target);
+        expect(current < next).toBe(true);
+        expect(next < target).toBe(true);
+        current = next;
+      }
+    });
+
+    it('handles repeated insertions directly after the same lower bound', () => {
+      const lower = 'a0';
+      let upper = 'a1';
+
+      // Repeatedly drop a card just below the first card
+      for (let i = 0; i < 50; i++) {
+        const next = generateKeyBetween(lower, upper);
+        expect(lower < next).toBe(true);
+        expect(next < upper).toBe(true);
+        upper = next;
+      }
+    });
+
+    it('keeps keys strictly ordered under random insertions', () => {
+      const keys = ['a0', 'a1'];
+      let seed = 42;
+      const random = () => {
+        seed = (seed * 1103515245 + 12345) % 2147483648;
+        return seed / 2147483648;
+      };
+
+      for (let i = 0; i < 500; i++) {
+        const idx = Math.floor(random() * (keys.length + 1));
+        const next = generateKeyBetween(keys[idx - 1] ?? null, keys[idx] ?? null);
+        keys.splice(idx, 0, next);
+      }
+
+      for (let i = 1; i < keys.length; i++) {
+        expect(keys[i - 1] < keys[i]).toBe(true);
+      }
+    });
+
+    it('throws when the lower bound does not sort before the upper bound', () => {
+      expect(() => generateKeyBetween('a1', 'a0')).toThrow(RangeError);
+      expect(() => generateKeyBetween('a0', 'a0')).toThrow(RangeError);
+    });
+  });
+
+  describe('generateNKeysBetween', () => {
+    it('returns empty array for count <= 0', () => {
+      expect(generateNKeysBetween('a0', 'a2', 0)).toEqual([]);
+      expect(generateNKeysBetween('a0', 'a2', -1)).toEqual([]);
+    });
+
+    it('generates 1 key matching generateKeyBetween', () => {
+      const keys = generateNKeysBetween('a0', 'a2', 1);
+      expect(keys.length).toBe(1);
+      expect(keys[0]).toBe('a1');
+    });
+
+    it('generates N keys in strictly ascending order between a and b', () => {
+      const count = 5;
+      const a = 'a0';
+      const b = 'a1';
+      const keys = generateNKeysBetween(a, b, count);
+
+      expect(keys.length).toBe(count);
+
+      // Check strictly greater than a
+      expect(a < keys[0]).toBe(true);
+
+      // Check strictly increasing
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+
+      // Check strictly less than b
+      expect(keys[count - 1] < b).toBe(true);
+    });
+
+    it('generates N keys at swimlane start (a is null)', () => {
+      const count = 3;
+      const b = 'a0';
+      const keys = generateNKeysBetween(null, b, count);
+
+      expect(keys.length).toBe(count);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+      expect(keys[count - 1] < b).toBe(true);
+    });
+
+    it('generates N keys at swimlane end (b is null)', () => {
+      const count = 4;
+      const a = 'a5';
+      const keys = generateNKeysBetween(a, null, count);
+
+      expect(keys.length).toBe(count);
+      expect(a < keys[0]).toBe(true);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+    });
+
+    it('generates N keys in empty swimlane (both null)', () => {
+      const count = 6;
+      const keys = generateNKeysBetween(null, null, count);
+
+      expect(keys.length).toBe(count);
+      for (let i = 0; i < keys.length - 1; i++) {
+        expect(keys[i] < keys[i + 1]).toBe(true);
+      }
+    });
+  });
+});