project-roadmap-tracking 0.1.0 → 0.2.1

package/dist/services/task-query.service.js

@@ -0,0 +1,259 @@
+import { PRIORITY, STATUS } from '../util/types.js';
+/**
+ * Sort order for sorting operations
+ */
+export var SortOrder;
+(function (SortOrder) {
+    SortOrder["Ascending"] = "asc";
+    SortOrder["Descending"] = "desc";
+})(SortOrder || (SortOrder = {}));
+/**
+ * TaskQueryService provides operations for querying, filtering, and sorting tasks.
+ * All operations are pure functions that do not mutate the input arrays.
+ */
+export class TaskQueryService {
+    /**
+     * Filters tasks based on the provided criteria.
+     * Returns tasks that match ALL specified criteria (AND logic).
+     *
+     * @param tasks - The tasks to filter
+     * @param criteria - The filter criteria to apply
+     * @returns A new array of tasks matching the criteria
+     *
+     * @example
+     * ```typescript
+     * const highPriorityTasks = taskQueryService.filter(tasks, {
+     *   priority: PRIORITY.High,
+     *   status: STATUS.InProgress
+     * });
+     * ```
+     */
+    filter(tasks, criteria) {
+        const filtered = tasks.filter((task) => {
+            // Check status filter - support both single status and array of statuses
+            if (criteria.status !== undefined) {
+                const statusMatch = Array.isArray(criteria.status)
+                    ? criteria.status.includes(task.status)
+                    : task.status === criteria.status;
+                if (!statusMatch) {
+                    return false;
+                }
+            }
+            // Check type filter
+            if (criteria.type !== undefined && task.type !== criteria.type) {
+                return false;
+            }
+            // Check priority filter
+            if (criteria.priority !== undefined && task.priority !== criteria.priority) {
+                return false;
+            }
+            // Check assignedTo filter
+            if (criteria.assignedTo !== undefined && task.assignedTo !== criteria.assignedTo) {
+                return false;
+            }
+            // Check tags filter - task must have all specified tags
+            if (criteria.tags !== undefined && criteria.tags.length > 0) {
+                const hasAllTags = criteria.tags.every((tag) => task.tags.includes(tag));
+                if (!hasAllTags) {
+                    return false;
+                }
+            }
+            // Check hasBlocks filter
+            if (criteria.hasBlocks !== undefined) {
+                const taskHasBlocks = task.blocks.length > 0;
+                if (taskHasBlocks !== criteria.hasBlocks) {
+                    return false;
+                }
+            }
+            // Check hasDependencies filter
+            if (criteria.hasDependencies !== undefined) {
+                const taskHasDependencies = task['depends-on'].length > 0;
+                if (taskHasDependencies !== criteria.hasDependencies) {
+                    return false;
+                }
+            }
+            return true;
+        });
+        return filtered;
+    }
+    /**
+     * Gets all tasks with a specific status.
+     * This is a convenience method that uses the filter method.
+     *
+     * @param tasks - The tasks to search
+     * @param status - The status to filter by
+     * @returns A new array of tasks with the specified status
+     *
+     * @example
+     * ```typescript
+     * const completedTasks = taskQueryService.getByStatus(tasks, STATUS.Completed);
+     * ```
+     */
+    getByStatus(tasks, status) {
+        const criteria = { status };
+        const filtered = tasks.filter((task) => {
+            if (criteria.status !== undefined && task.status !== criteria.status) {
+                return false;
+            }
+            return true;
+        });
+        return filtered;
+    }
+    /**
+     * Gets all tasks of a specific type.
+     * This is a convenience method that uses the filter method.
+     *
+     * @param tasks - The tasks to search
+     * @param type - The type to filter by
+     * @returns A new array of tasks with the specified type
+     *
+     * @example
+     * ```typescript
+     * const featureTasks = taskQueryService.getByType(tasks, TASK_TYPE.Feature);
+     * ```
+     */
+    getByType(tasks, type) {
+        const criteria = { type };
+        const filtered = tasks.filter((task) => {
+            if (criteria.type !== undefined && task.type !== criteria.type) {
+                return false;
+            }
+            return true;
+        });
+        return filtered;
+    }
+    /**
+     * Searches for tasks matching a query string in title or details.
+     * The search is case-insensitive.
+     *
+     * @param tasks - The tasks to search
+     * @param query - The search query string
+     * @returns A new array of tasks matching the query
+     *
+     * @example
+     * ```typescript
+     * const loginTasks = taskQueryService.search(tasks, 'login');
+     * ```
+     */
+    search(tasks, query) {
+        if (!query || query.trim() === '') {
+            return [...tasks];
+        }
+        const lowerQuery = query.toLowerCase();
+        return tasks.filter((task) => {
+            const titleMatch = task.title.toLowerCase().includes(lowerQuery);
+            const detailsMatch = task.details.toLowerCase().includes(lowerQuery);
+            return detailsMatch || titleMatch;
+        });
+    }
+    /**
+     * Sorts tasks by the specified field and order.
+     * Returns a new sorted array without mutating the original.
+     *
+     * @param tasks - The tasks to sort
+     * @param field - The field to sort by
+     * @param order - The sort order (ascending or descending)
+     * @returns A new sorted array of tasks
+     *
+     * @example
+     * ```typescript
+     * const sorted = taskQueryService.sort(tasks, 'priority', SortOrder.Descending);
+     * ```
+     */
+    sort(tasks, field, order = SortOrder.Ascending) {
+        const sortedTasks = [...tasks];
+        // eslint-disable-next-line complexity
+        sortedTasks.sort((a, b) => {
+            let aValue;
+            let bValue;
+            // Get values based on field
+            switch (field) {
+                case 'createdAt': {
+                    aValue = a.createdAt ?? '';
+                    bValue = b.createdAt ?? '';
+                    break;
+                }
+                case 'dueDate': {
+                    aValue = a.dueDate ?? '';
+                    bValue = b.dueDate ?? '';
+                    break;
+                }
+                case 'effort': {
+                    aValue = a.effort;
+                    bValue = b.effort;
+                    break;
+                }
+                case 'priority': {
+                    // Sort priority as: high > medium > low
+                    const priorityOrder = {
+                        [PRIORITY.High]: 3,
+                        [PRIORITY.Low]: 1,
+                        [PRIORITY.Medium]: 2,
+                    };
+                    aValue = priorityOrder[a.priority];
+                    bValue = priorityOrder[b.priority];
+                    break;
+                }
+                case 'status': {
+                    // Sort status as: not-started > in-progress > completed
+                    const statusOrder = {
+                        [STATUS.Completed]: 3,
+                        [STATUS.InProgress]: 2,
+                        [STATUS.NotStarted]: 1,
+                    };
+                    aValue = statusOrder[a.status];
+                    bValue = statusOrder[b.status];
+                    break;
+                }
+                case 'title': {
+                    aValue = a.title.toLowerCase();
+                    bValue = b.title.toLowerCase();
+                    break;
+                }
+                case 'type': {
+                    // Sort type alphabetically by enum value
+                    aValue = a.type;
+                    bValue = b.type;
+                    break;
+                }
+                case 'updatedAt': {
+                    aValue = a.updatedAt ?? '';
+                    bValue = b.updatedAt ?? '';
+                    break;
+                }
+                default: {
+                    return 0;
+                }
+            }
+            // Handle null/undefined values - push them to the end
+            if (aValue === null || aValue === undefined || aValue === '') {
+                return 1;
+            }
+            if (bValue === null || bValue === undefined || bValue === '') {
+                return -1;
+            }
+            // Compare values
+            let comparison = 0;
+            if (aValue < bValue) {
+                comparison = -1;
+            }
+            else if (aValue > bValue) {
+                comparison = 1;
+            }
+            // Apply sort order
+            return order === SortOrder.Ascending ? comparison : -comparison;
+        });
+        return sortedTasks;
+    }
+}
+/**
+ * Default export instance of TaskQueryService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import taskQueryService from './services/task-query.service.js';
+ * const filtered = taskQueryService.filter(tasks, { status: STATUS.InProgress });
+ * ```
+ */
+export default new TaskQueryService();

package/dist/services/task.service.d.ts

@@ -0,0 +1,155 @@
+import { PRIORITY, Roadmap, STATUS, Task, TASK_TYPE, TaskID } from '../util/types.js';
+/**
+ * TaskService provides core operations for managing tasks in a roadmap.
+ * This service handles task creation, ID generation, and task manipulation.
+ */
+export declare class TaskService {
+    /**
+     * Adds a task to the roadmap and returns a new roadmap object.
+     * This method does not mutate the original roadmap.
+     * Validates the task before adding to ensure data integrity.
+     *
+     * @param roadmap - The roadmap to add the task to
+     * @param task - The task to add
+     * @returns A new Roadmap object with the task added
+     * @throws Error if the task is invalid
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.createTask({ ... });
+     * const updatedRoadmap = taskService.addTask(roadmap, task);
+     * ```
+     */
+    addTask(roadmap: Roadmap, task: Task): Roadmap;
+    /**
+     * Creates a new task object with the provided data and default values.
+     * Automatically sets createdAt, updatedAt timestamps and initializes arrays.
+     *
+     * @name createTask
+     *
+     * @param data - Partial task data to create the task from
+     * @param {Array<Task['id']> | undefined} data.blocks - IDs of tasks blocked by this task
+     * @param {boolean | undefined} data.passes-tests - Whether the task passes tests
+     * @param {Array<Task['id']> | undefined} data.depends-on - IDs of tasks this task depends on
+     * @param {string} data.details - Detailed description of the task
+     * @param {TaskID} data.id - Unique identifier for the task
+     * @param {string | undefined} data.notes - Additional notes for the task
+     * @param {PRIORITY | undefined} data.priority - Priority level of the task
+     * @param {STATUS | undefined} data.status - Current status of the task
+     * @param {Array<string> | undefined} data.tags - Tags associated with the task
+     * @param {string} data.title - Title of the task
+     * @param {TASK_TYPE} data.type - Type of the task (bug, feature, etc.)
+     * @returns A complete Task object with all required fields
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.createTask({
+     *   id: 'F-001',
+     *   title: 'Add login feature',
+     *   details: 'Implement user authentication',
+     *   type: TASK_TYPE.Feature,
+     *   priority: PRIORITY.High,
+     * });
+     * ```
+     */
+    createTask(data: {
+        blocks?: Array<Task['id']>;
+        'depends-on'?: Array<Task['id']>;
+        details: string;
+        id: TaskID;
+        notes?: string;
+        'passes-tests'?: boolean;
+        priority?: PRIORITY;
+        status?: STATUS;
+        tags?: Array<string>;
+        title: string;
+        type: TASK_TYPE;
+    }): Task;
+    /**
+     * Finds a task in the roadmap by its ID.
+     *
+     * @param roadmap - The roadmap to search
+     * @param taskId - The ID of the task to find
+     * @returns The task if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.findTask(roadmap, 'F-001');
+     * if (task) {
+     *   console.log(task.title);
+     * }
+     * ```
+     */
+    findTask(roadmap: Roadmap, taskId: string): Task | undefined;
+    /**
+     * Generates the next available task ID for a given task type.
+     * IDs follow the format: {TYPE_LETTER}-{NNN} where TYPE_LETTER is B, F, I, P, or R
+     * and NNN is a zero-padded 3-digit number starting from 001.
+     *
+     * @param roadmap - The roadmap containing existing tasks
+     * @param taskType - The type of task (bug, feature, improvement, planning, research)
+     * @returns The next available task ID for the given type
+     *
+     * @example
+     * ```typescript
+     * const nextId = taskService.generateNextId(roadmap, TASK_TYPE.Feature);
+     * // Returns "F-001" if no features exist, or "F-042" if F-041 is the highest
+     * ```
+     */
+    generateNextId(roadmap: Roadmap, taskType: TASK_TYPE): TaskID;
+    /**
+     * Updates an existing task in the roadmap with the provided updates.
+     * Automatically updates the updatedAt timestamp.
+     * This method does not mutate the original roadmap.
+     *
+     * @param roadmap - The roadmap containing the task to update
+     * @param taskId - The ID of the task to update
+     * @param updates - Partial task object with fields to update
+     * @returns A new Roadmap object with the task updated
+     * @throws Error if the task with the given ID is not found
+     *
+     * @example
+     * ```typescript
+     * const updatedRoadmap = taskService.updateTask(roadmap, 'F-001', {
+     *   status: STATUS.Completed,
+     *   'passes-tests': true,
+     * });
+     * ```
+     */
+    updateTask(roadmap: Roadmap, taskId: string, updates: Partial<Task>): Roadmap;
+    /**
+     * Updates a task's type, reassigning its ID and cascading the change to all references.
+     * When a task type is changed, a new ID is generated to match the new type prefix.
+     * All other tasks that reference the old ID in their depends-on or blocks arrays
+     * will be updated to reference the new ID.
+     *
+     * @param roadmap - The roadmap containing the task to update
+     * @param taskId - The current ID of the task to update
+     * @param newType - The new task type to assign
+     * @returns An object containing the updated Roadmap and the new task ID
+     * @throws Error if the task with the given ID is not found
+     *
+     * @example
+     * ```typescript
+     * // Change task F-001 to a bug (will become B-001 or next available B-XXX)
+     * const {roadmap: updatedRoadmap, newTaskId} = taskService.updateTaskType(roadmap, 'F-001', TASK_TYPE.Bug);
+     * // All tasks that had 'F-001' in depends-on or blocks will now have the new bug ID
+     * ```
+     */
+    updateTaskType(roadmap: Roadmap, taskId: string, newType: TASK_TYPE): {
+        newTaskId: TaskID;
+        roadmap: Roadmap;
+    };
+}
+/**
+ * Default export instance of TaskService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import taskService from './services/task.service.js';
+ * const nextId = taskService.generateNextId(roadmap, TASK_TYPE.Feature);
+ * ```
+ */
+declare const _default: TaskService;
+export default _default;

package/dist/services/task.service.js

@@ -0,0 +1,233 @@
+/* eslint-disable jsdoc/check-param-names */
+import { TaskNotFoundError } from '../errors/index.js';
+import { PRIORITY, STATUS, TASK_TYPE_MAP } from '../util/types.js';
+import { validateTask } from '../util/validate-task.js';
+/**
+ * TaskService provides core operations for managing tasks in a roadmap.
+ * This service handles task creation, ID generation, and task manipulation.
+ */
+export class TaskService {
+    /**
+     * Adds a task to the roadmap and returns a new roadmap object.
+     * This method does not mutate the original roadmap.
+     * Validates the task before adding to ensure data integrity.
+     *
+     * @param roadmap - The roadmap to add the task to
+     * @param task - The task to add
+     * @returns A new Roadmap object with the task added
+     * @throws Error if the task is invalid
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.createTask({ ... });
+     * const updatedRoadmap = taskService.addTask(roadmap, task);
+     * ```
+     */
+    addTask(roadmap, task) {
+        validateTask(task);
+        return {
+            ...roadmap,
+            tasks: [...roadmap.tasks, task],
+        };
+    }
+    /**
+     * Creates a new task object with the provided data and default values.
+     * Automatically sets createdAt, updatedAt timestamps and initializes arrays.
+     *
+     * @name createTask
+     *
+     * @param data - Partial task data to create the task from
+     * @param {Array<Task['id']> | undefined} data.blocks - IDs of tasks blocked by this task
+     * @param {boolean | undefined} data.passes-tests - Whether the task passes tests
+     * @param {Array<Task['id']> | undefined} data.depends-on - IDs of tasks this task depends on
+     * @param {string} data.details - Detailed description of the task
+     * @param {TaskID} data.id - Unique identifier for the task
+     * @param {string | undefined} data.notes - Additional notes for the task
+     * @param {PRIORITY | undefined} data.priority - Priority level of the task
+     * @param {STATUS | undefined} data.status - Current status of the task
+     * @param {Array<string> | undefined} data.tags - Tags associated with the task
+     * @param {string} data.title - Title of the task
+     * @param {TASK_TYPE} data.type - Type of the task (bug, feature, etc.)
+     * @returns A complete Task object with all required fields
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.createTask({
+     *   id: 'F-001',
+     *   title: 'Add login feature',
+     *   details: 'Implement user authentication',
+     *   type: TASK_TYPE.Feature,
+     *   priority: PRIORITY.High,
+     * });
+     * ```
+     */
+    createTask(data) {
+        return {
+            blocks: data.blocks ?? [],
+            createdAt: new Date().toISOString(),
+            'depends-on': data['depends-on'] ?? [],
+            details: data.details,
+            id: data.id,
+            notes: data.notes ?? '',
+            'passes-tests': data['passes-tests'] ?? false,
+            priority: data.priority ?? PRIORITY.Medium,
+            status: data.status ?? STATUS.NotStarted,
+            tags: data.tags ?? [],
+            title: data.title,
+            type: data.type,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Finds a task in the roadmap by its ID.
+     *
+     * @param roadmap - The roadmap to search
+     * @param taskId - The ID of the task to find
+     * @returns The task if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const task = taskService.findTask(roadmap, 'F-001');
+     * if (task) {
+     *   console.log(task.title);
+     * }
+     * ```
+     */
+    findTask(roadmap, taskId) {
+        return roadmap.tasks.find((task) => task.id === taskId);
+    }
+    /**
+     * Generates the next available task ID for a given task type.
+     * IDs follow the format: {TYPE_LETTER}-{NNN} where TYPE_LETTER is B, F, I, P, or R
+     * and NNN is a zero-padded 3-digit number starting from 001.
+     *
+     * @param roadmap - The roadmap containing existing tasks
+     * @param taskType - The type of task (bug, feature, improvement, planning, research)
+     * @returns The next available task ID for the given type
+     *
+     * @example
+     * ```typescript
+     * const nextId = taskService.generateNextId(roadmap, TASK_TYPE.Feature);
+     * // Returns "F-001" if no features exist, or "F-042" if F-041 is the highest
+     * ```
+     */
+    generateNextId(roadmap, taskType) {
+        const existingTaskIDs = new Set(roadmap.tasks.filter((task) => task.type === taskType).map((task) => task.id));
+        let newIDNumber = 1;
+        let newTaskID;
+        while (true) {
+            const potentialID = `${TASK_TYPE_MAP.get(taskType)}-${String(newIDNumber).padStart(3, '0')}`;
+            if (!existingTaskIDs.has(potentialID)) {
+                newTaskID = potentialID;
+                break;
+            }
+            newIDNumber++;
+        }
+        return newTaskID;
+    }
+    /**
+     * Updates an existing task in the roadmap with the provided updates.
+     * Automatically updates the updatedAt timestamp.
+     * This method does not mutate the original roadmap.
+     *
+     * @param roadmap - The roadmap containing the task to update
+     * @param taskId - The ID of the task to update
+     * @param updates - Partial task object with fields to update
+     * @returns A new Roadmap object with the task updated
+     * @throws Error if the task with the given ID is not found
+     *
+     * @example
+     * ```typescript
+     * const updatedRoadmap = taskService.updateTask(roadmap, 'F-001', {
+     *   status: STATUS.Completed,
+     *   'passes-tests': true,
+     * });
+     * ```
+     */
+    updateTask(roadmap, taskId, updates) {
+        const taskIndex = roadmap.tasks.findIndex((task) => task.id === taskId);
+        if (taskIndex === -1) {
+            throw new TaskNotFoundError(taskId);
+        }
+        const updatedTask = {
+            ...roadmap.tasks[taskIndex],
+            ...updates,
+            updatedAt: new Date().toISOString(),
+        };
+        return {
+            ...roadmap,
+            tasks: [...roadmap.tasks.slice(0, taskIndex), updatedTask, ...roadmap.tasks.slice(taskIndex + 1)],
+        };
+    }
+    /**
+     * Updates a task's type, reassigning its ID and cascading the change to all references.
+     * When a task type is changed, a new ID is generated to match the new type prefix.
+     * All other tasks that reference the old ID in their depends-on or blocks arrays
+     * will be updated to reference the new ID.
+     *
+     * @param roadmap - The roadmap containing the task to update
+     * @param taskId - The current ID of the task to update
+     * @param newType - The new task type to assign
+     * @returns An object containing the updated Roadmap and the new task ID
+     * @throws Error if the task with the given ID is not found
+     *
+     * @example
+     * ```typescript
+     * // Change task F-001 to a bug (will become B-001 or next available B-XXX)
+     * const {roadmap: updatedRoadmap, newTaskId} = taskService.updateTaskType(roadmap, 'F-001', TASK_TYPE.Bug);
+     * // All tasks that had 'F-001' in depends-on or blocks will now have the new bug ID
+     * ```
+     */
+    updateTaskType(roadmap, taskId, newType) {
+        const task = this.findTask(roadmap, taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        // If the type isn't changing, just return the roadmap unchanged with the same task ID
+        if (task.type === newType) {
+            return { newTaskId: taskId, roadmap };
+        }
+        // Generate a new ID for the new type
+        const newTaskId = this.generateNextId(roadmap, newType);
+        // Update the task with the new type and new ID
+        let updatedRoadmap = this.updateTask(roadmap, taskId, {
+            id: newTaskId,
+            type: newType,
+        });
+        // Cascade the ID change to all tasks that reference the old ID
+        updatedRoadmap = {
+            ...updatedRoadmap,
+            tasks: updatedRoadmap.tasks.map((t) => {
+                // Skip the task we just updated
+                if (t.id === newTaskId) {
+                    return t;
+                }
+                // Check if this task references the old ID in depends-on or blocks
+                const hasDependency = t['depends-on'].includes(taskId);
+                const hasBlock = t.blocks.includes(taskId);
+                if (!hasDependency && !hasBlock) {
+                    return t;
+                }
+                // Update the references
+                return {
+                    ...t,
+                    blocks: hasBlock ? t.blocks.map((id) => (id === taskId ? newTaskId : id)) : t.blocks,
+                    'depends-on': hasDependency ? t['depends-on'].map((id) => (id === taskId ? newTaskId : id)) : t['depends-on'],
+                    updatedAt: new Date().toISOString(),
+                };
+            }),
+        };
+        return { newTaskId, roadmap: updatedRoadmap };
+    }
+}
+/**
+ * Default export instance of TaskService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import taskService from './services/task.service.js';
+ * const nextId = taskService.generateNextId(roadmap, TASK_TYPE.Feature);
+ * ```
+ */
+export default new TaskService();

package/dist/util/read-config.js

@@ -1,5 +1,15 @@
 import { readFile } from 'node:fs/promises';
+import { ConfigNotFoundError } from '../errors/index.js';
 export async function readConfigFile() {
-    const data = await readFile('.prtrc.json', 'utf8');
-    return JSON.parse(data);
+    try {
+        const data = await readFile('.prtrc.json', 'utf8');
+        return JSON.parse(data);
+    }
+    catch (error) {
+        // Re-throw SyntaxError for JSON parsing issues
+        if (error instanceof SyntaxError) {
+            throw error;
+        }
+        throw new ConfigNotFoundError('.prtrc.json', error instanceof Error ? error : undefined);
+    }
 }

package/dist/util/read-roadmap.js

@@ -1,5 +1,15 @@
 import { readFile } from 'node:fs/promises';
+import { RoadmapNotFoundError } from '../errors/index.js';
 export async function readRoadmapFile(path) {
-    const data = await readFile(path, 'utf8');
-    return JSON.parse(data);
+    try {
+        const data = await readFile(path, 'utf8');
+        return JSON.parse(data);
+    }
+    catch (error) {
+        // Re-throw SyntaxError for JSON parsing issues
+        if (error instanceof SyntaxError) {
+            throw error;
+        }
+        throw new RoadmapNotFoundError(path, error instanceof Error ? error : undefined);
+    }
 }

package/dist/util/types.d.ts

@@ -1,5 +1,10 @@
 export type Config = {
     $schema: string;
+    cache?: {
+        enabled?: boolean;
+        maxSize?: number;
+        watchFiles?: boolean;
+    };
     metadata: {
         description: string;
         name: string;