project-roadmap-tracking 0.1.0 → 0.2.0

package/dist/services/error-handler.service.js

@@ -0,0 +1,169 @@
+import { getErrorCode, isPrtError, PrtErrorCode } from '../errors/index.js';
+/**
+ * Exit codes used by the CLI application.
+ * These follow common UNIX conventions:
+ * - 0: Success
+ * - 1: General error
+ * - 2: Validation error
+ * - 3: Not found error
+ * - 4: Dependency error
+ */
+export const ExitCodes = {
+    DEPENDENCY_ERROR: 4,
+    GENERAL_ERROR: 1,
+    NOT_FOUND: 3,
+    SUCCESS: 0,
+    VALIDATION_ERROR: 2,
+};
+/**
+ * ErrorHandlerService provides centralized error handling for CLI commands.
+ * This service handles error formatting, exit code mapping, and verbose output.
+ */
+export class ErrorHandlerService {
+    /**
+     * Formats an error message for CLI display.
+     * When verbose=true, includes stack traces and context information.
+     *
+     * @param error - The error to format
+     * @param verbose - Whether to include verbose information (stack traces, context)
+     * @returns Formatted error message string
+     *
+     * @example
+     * ```typescript
+     * // Basic error message
+     * const message = errorHandlerService.formatErrorMessage(error, false)
+     * console.error(message)
+     *
+     * // Verbose error message with stack trace
+     * const verboseMessage = errorHandlerService.formatErrorMessage(error, true)
+     * console.error(verboseMessage)
+     * ```
+     */
+    formatErrorMessage(error, verbose = false) {
+        const parts = [];
+        // Basic error message
+        if (isPrtError(error)) {
+            parts.push(`Error: ${error.message}`, `Code: ${error.code}`);
+            // Add context if in verbose mode
+            if (verbose && error.context && Object.keys(error.context).length > 0) {
+                parts.push('\nContext:', JSON.stringify(error.context, null, 2));
+            }
+        }
+        else if (error instanceof Error) {
+            parts.push(`Error: ${error.message}`);
+        }
+        else {
+            parts.push(`Error: ${String(error)}`);
+        }
+        // Add stack trace in verbose mode
+        if (verbose && error instanceof Error && error.stack) {
+            parts.push('\nStack trace:', error.stack);
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Maps a PrtErrorCode to the appropriate CLI exit code.
+     *
+     * @param code - The PrtErrorCode to map
+     * @returns The corresponding exit code
+     *
+     * @example
+     * ```typescript
+     * const exitCode = errorHandlerService.getExitCodeForErrorCode(PrtErrorCode.PRT_FILE_CONFIG_NOT_FOUND)
+     * // Returns ExitCodes.NOT_FOUND (3)
+     * ```
+     */
+    getExitCodeForErrorCode(code) {
+        switch (code) {
+            case PrtErrorCode.PRT_FILE_CONFIG_NOT_FOUND:
+            case PrtErrorCode.PRT_FILE_ROADMAP_NOT_FOUND:
+            case PrtErrorCode.PRT_TASK_NOT_FOUND: {
+                return ExitCodes.NOT_FOUND;
+            }
+            case PrtErrorCode.PRT_TASK_ID_INVALID:
+            case PrtErrorCode.PRT_TASK_INVALID:
+            case PrtErrorCode.PRT_VALIDATION_FAILED: {
+                return ExitCodes.VALIDATION_ERROR;
+            }
+            case PrtErrorCode.PRT_VALIDATION_CIRCULAR_DEPENDENCY: {
+                return ExitCodes.DEPENDENCY_ERROR;
+            }
+            default: {
+                return ExitCodes.GENERAL_ERROR;
+            }
+        }
+    }
+    /**
+     * Handles an error and returns the appropriate exit code.
+     * This is the main entry point for command error handling.
+     *
+     * @param error - The error to handle
+     * @returns The exit code to use when exiting the process
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Command logic
+     * } catch (error) {
+     *   const exitCode = errorHandlerService.handleError(error)
+     *   this.error(errorHandlerService.formatErrorMessage(error), {exit: exitCode})
+     * }
+     * ```
+     */
+    handleError(error) {
+        const errorCode = getErrorCode(error);
+        if (errorCode !== null) {
+            return this.getExitCodeForErrorCode(errorCode);
+        }
+        // Default to general error for non-PRT errors
+        return ExitCodes.GENERAL_ERROR;
+    }
+    /**
+     * Determines if an error is recoverable.
+     * Recoverable errors allow the command to continue or retry,
+     * while non-recoverable errors should terminate the command.
+     *
+     * Currently, most PRT errors are non-recoverable as they indicate
+     * fundamental issues with the roadmap data or configuration.
+     *
+     * @param error - The error to check
+     * @returns True if the error is recoverable, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (errorHandlerService.isRecoverableError(error)) {
+     *   console.log('Attempting retry...')
+     * } else {
+     *   process.exit(1)
+     * }
+     * ```
+     */
+    isRecoverableError(error) {
+        // For now, we don't have any recoverable errors
+        // This could be extended in the future for retry logic
+        // or graceful degradation scenarios
+        if (isPrtError(error)) {
+            // All PRT errors are currently non-recoverable
+            return false;
+        }
+        // Generic errors are also non-recoverable
+        return false;
+    }
+}
+/**
+ * Default export instance of ErrorHandlerService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import errorHandlerService from './services/error-handler.service.js'
+ *
+ * try {
+ *   // Command logic
+ * } catch (error) {
+ *   const exitCode = errorHandlerService.handleError(error)
+ *   this.error(errorHandlerService.formatErrorMessage(error, flags.verbose), {exit: exitCode})
+ * }
+ * ```
+ */
+export default new ErrorHandlerService();

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

@@ -0,0 +1,142 @@
+import { ValidationErrorDetail } from '../errors/index.js';
+import { PRIORITY, Roadmap, STATUS, TASK_TYPE } from '../util/types.js';
+/**
+ * Statistics about a roadmap's tasks
+ */
+export interface RoadmapStats {
+    /** Count of tasks by priority */
+    byPriority: {
+        [PRIORITY.High]: number;
+        [PRIORITY.Low]: number;
+        [PRIORITY.Medium]: number;
+    };
+    /** Count of tasks by status */
+    byStatus: {
+        [STATUS.Completed]: number;
+        [STATUS.InProgress]: number;
+        [STATUS.NotStarted]: number;
+    };
+    /** Count of tasks by type */
+    byType: {
+        [TASK_TYPE.Bug]: number;
+        [TASK_TYPE.Feature]: number;
+        [TASK_TYPE.Improvement]: number;
+        [TASK_TYPE.Planning]: number;
+        [TASK_TYPE.Research]: number;
+    };
+    /** Total number of tasks in the roadmap */
+    totalTasks: number;
+}
+/**
+ * RoadmapService provides core operations for managing roadmaps.
+ * This service abstracts all file I/O and roadmap-level operations.
+ */
+export declare class RoadmapService {
+    /**
+     * Gets statistics about a roadmap's tasks.
+     * Provides counts by status, type, and priority.
+     *
+     * @param roadmap - The roadmap to analyze
+     * @returns Statistics object with task counts
+     *
+     * @example
+     * ```typescript
+     * const stats = roadmapService.getStats(roadmap);
+     * console.log(`Completed: ${stats.byStatus.completed}`);
+     * console.log(`Total: ${stats.totalTasks}`);
+     * ```
+     */
+    getStats(roadmap: Roadmap): RoadmapStats;
+    /**
+     * Loads a roadmap from a file.
+     * Reads and parses the roadmap JSON file.
+     *
+     * @param path - The file path to read the roadmap from
+     * @returns A Promise resolving to the Roadmap object
+     * @throws RoadmapNotFoundError if the file cannot be read
+     * @throws SyntaxError if the file contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * const roadmap = await roadmapService.load('./prt.json');
+     * ```
+     */
+    load(path: string): Promise<Roadmap>;
+    /**
+     * Saves a roadmap to a file.
+     * Validates the roadmap before writing to ensure data integrity.
+     *
+     * @param path - The file path to write the roadmap to
+     * @param roadmap - The roadmap object to save
+     * @returns A Promise that resolves when the file is written
+     * @throws ValidationError if validation fails
+     * @throws Error if the file cannot be written
+     *
+     * @example
+     * ```typescript
+     * await roadmapService.save('./prt.json', roadmap);
+     * ```
+     */
+    save(path: string, roadmap: Roadmap): Promise<void>;
+    /**
+     * Validates a roadmap's structure and data integrity.
+     * Checks for valid structure, task validation, duplicate IDs, and reference integrity.
+     *
+     * @param roadmap - The roadmap to validate
+     * @returns An array of validation errors (empty if valid)
+     *
+     * @example
+     * ```typescript
+     * const errors = roadmapService.validate(roadmap);
+     * if (errors.length > 0) {
+     *   console.error('Validation errors:', errors);
+     * }
+     * ```
+     */
+    validate(roadmap: Roadmap): ValidationErrorDetail[];
+    /**
+     * Validates dependency integrity including circular dependencies
+     * @param roadmap - The roadmap to validate
+     * @param errors - Array to collect errors
+     */
+    private validateDependencyIntegrity;
+    /**
+     * Validates roadmap metadata
+     * @param metadata - The metadata to validate
+     * @param errors - Array to collect errors
+     */
+    private validateMetadata;
+    /**
+     * Validates task references (depends-on and blocks)
+     * @param tasks - The tasks to validate
+     * @param taskIds - Set of valid task IDs
+     * @param errors - Array to collect errors
+     */
+    private validateReferences;
+    /**
+     * Validates the basic structure of a roadmap
+     * @param roadmap - The roadmap to validate
+     * @param errors - Array to collect errors
+     */
+    private validateStructure;
+    /**
+     * Validates tasks and checks for duplicates
+     * @param tasks - The tasks to validate
+     * @param errors - Array to collect errors
+     * @returns Set of valid task IDs
+     */
+    private validateTasks;
+}
+/**
+ * Default export instance of RoadmapService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import roadmapService from './services/roadmap.service.js';
+ * const roadmap = await roadmapService.load('./prt.json');
+ * ```
+ */
+declare const _default: RoadmapService;
+export default _default;
+export { type ValidationErrorDetail } from '../errors/index.js';

package/dist/services/roadmap.service.js

@@ -0,0 +1,269 @@
+import { ValidationError } from '../errors/index.js';
+import { readRoadmapFile } from '../util/read-roadmap.js';
+import { PRIORITY, STATUS, TASK_TYPE } from '../util/types.js';
+import { validateTask } from '../util/validate-task.js';
+import { writeRoadmapFile } from '../util/write-roadmap.js';
+import taskDependencyService from './task-dependency.service.js';
+/**
+ * RoadmapService provides core operations for managing roadmaps.
+ * This service abstracts all file I/O and roadmap-level operations.
+ */
+export class RoadmapService {
+    /**
+     * Gets statistics about a roadmap's tasks.
+     * Provides counts by status, type, and priority.
+     *
+     * @param roadmap - The roadmap to analyze
+     * @returns Statistics object with task counts
+     *
+     * @example
+     * ```typescript
+     * const stats = roadmapService.getStats(roadmap);
+     * console.log(`Completed: ${stats.byStatus.completed}`);
+     * console.log(`Total: ${stats.totalTasks}`);
+     * ```
+     */
+    getStats(roadmap) {
+        const stats = {
+            byPriority: {
+                [PRIORITY.High]: 0,
+                [PRIORITY.Low]: 0,
+                [PRIORITY.Medium]: 0,
+            },
+            byStatus: {
+                [STATUS.Completed]: 0,
+                [STATUS.InProgress]: 0,
+                [STATUS.NotStarted]: 0,
+            },
+            byType: {
+                [TASK_TYPE.Bug]: 0,
+                [TASK_TYPE.Feature]: 0,
+                [TASK_TYPE.Improvement]: 0,
+                [TASK_TYPE.Planning]: 0,
+                [TASK_TYPE.Research]: 0,
+            },
+            totalTasks: roadmap.tasks.length,
+        };
+        for (const task of roadmap.tasks) {
+            // Count by status
+            if (task.status in stats.byStatus) {
+                stats.byStatus[task.status]++;
+            }
+            // Count by type
+            if (task.type in stats.byType) {
+                stats.byType[task.type]++;
+            }
+            // Count by priority
+            if (task.priority in stats.byPriority) {
+                stats.byPriority[task.priority]++;
+            }
+        }
+        return stats;
+    }
+    /**
+     * Loads a roadmap from a file.
+     * Reads and parses the roadmap JSON file.
+     *
+     * @param path - The file path to read the roadmap from
+     * @returns A Promise resolving to the Roadmap object
+     * @throws RoadmapNotFoundError if the file cannot be read
+     * @throws SyntaxError if the file contains invalid JSON
+     *
+     * @example
+     * ```typescript
+     * const roadmap = await roadmapService.load('./prt.json');
+     * ```
+     */
+    async load(path) {
+        return readRoadmapFile(path);
+    }
+    /**
+     * Saves a roadmap to a file.
+     * Validates the roadmap before writing to ensure data integrity.
+     *
+     * @param path - The file path to write the roadmap to
+     * @param roadmap - The roadmap object to save
+     * @returns A Promise that resolves when the file is written
+     * @throws ValidationError if validation fails
+     * @throws Error if the file cannot be written
+     *
+     * @example
+     * ```typescript
+     * await roadmapService.save('./prt.json', roadmap);
+     * ```
+     */
+    async save(path, roadmap) {
+        const errors = this.validate(roadmap);
+        if (errors.length > 0) {
+            throw new ValidationError(errors);
+        }
+        try {
+            await writeRoadmapFile(path, roadmap);
+        }
+        catch (error) {
+            throw new Error(`Failed to save roadmap to ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Validates a roadmap's structure and data integrity.
+     * Checks for valid structure, task validation, duplicate IDs, and reference integrity.
+     *
+     * @param roadmap - The roadmap to validate
+     * @returns An array of validation errors (empty if valid)
+     *
+     * @example
+     * ```typescript
+     * const errors = roadmapService.validate(roadmap);
+     * if (errors.length > 0) {
+     *   console.error('Validation errors:', errors);
+     * }
+     * ```
+     */
+    validate(roadmap) {
+        const errors = [];
+        // Validate roadmap structure
+        this.validateStructure(roadmap, errors);
+        // If structure is invalid (null/not an object or missing tasks array), return early
+        if (errors.some((e) => e.type === 'structure' && (e.message.includes('tasks array') || e.message.includes('must be an object')))) {
+            return errors;
+        }
+        // Validate tasks and collect IDs
+        const taskIds = this.validateTasks(roadmap.tasks, errors);
+        // Validate task references
+        this.validateReferences(roadmap.tasks, taskIds, errors);
+        // Validate dependency integrity (circular dependencies, etc.)
+        this.validateDependencyIntegrity(roadmap, errors);
+        return errors;
+    }
+    /**
+     * Validates dependency integrity including circular dependencies
+     * @param roadmap - The roadmap to validate
+     * @param errors - Array to collect errors
+     */
+    validateDependencyIntegrity(roadmap, errors) {
+        const depErrors = taskDependencyService.validateDependencies(roadmap);
+        for (const depError of depErrors) {
+            errors.push({
+                message: depError.message,
+                taskId: depError.taskId,
+                type: depError.type === 'circular' ? 'circular-dependency' : depError.type,
+            });
+        }
+    }
+    /**
+     * Validates roadmap metadata
+     * @param metadata - The metadata to validate
+     * @param errors - Array to collect errors
+     */
+    validateMetadata(metadata, errors) {
+        if (!metadata.name || typeof metadata.name !== 'string') {
+            errors.push({ message: 'Roadmap metadata must have a name', type: 'structure' });
+        }
+        if (!metadata.description || typeof metadata.description !== 'string') {
+            errors.push({ message: 'Roadmap metadata must have a description', type: 'structure' });
+        }
+        if (!metadata.createdBy || typeof metadata.createdBy !== 'string') {
+            errors.push({ message: 'Roadmap metadata must have a createdBy', type: 'structure' });
+        }
+        if (!metadata.createdAt || typeof metadata.createdAt !== 'string') {
+            errors.push({ message: 'Roadmap metadata must have a createdAt', type: 'structure' });
+        }
+    }
+    /**
+     * Validates task references (depends-on and blocks)
+     * @param tasks - The tasks to validate
+     * @param taskIds - Set of valid task IDs
+     * @param errors - Array to collect errors
+     */
+    validateReferences(tasks, taskIds, errors) {
+        for (const task of tasks) {
+            if (task['depends-on']) {
+                for (const depId of task['depends-on']) {
+                    if (!taskIds.has(depId)) {
+                        errors.push({
+                            message: `Task ${task.id} depends on non-existent task ${depId}`,
+                            taskId: task.id,
+                            type: 'invalid-reference',
+                        });
+                    }
+                }
+            }
+            if (task.blocks) {
+                for (const blockId of task.blocks) {
+                    if (!taskIds.has(blockId)) {
+                        errors.push({
+                            message: `Task ${task.id} blocks non-existent task ${blockId}`,
+                            taskId: task.id,
+                            type: 'invalid-reference',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Validates the basic structure of a roadmap
+     * @param roadmap - The roadmap to validate
+     * @param errors - Array to collect errors
+     */
+    validateStructure(roadmap, errors) {
+        if (!roadmap || typeof roadmap !== 'object') {
+            errors.push({ message: 'Roadmap must be an object', type: 'structure' });
+            return;
+        }
+        if (!roadmap.$schema || typeof roadmap.$schema !== 'string') {
+            errors.push({ message: 'Roadmap must have a $schema property', type: 'structure' });
+        }
+        if (!roadmap.metadata || typeof roadmap.metadata !== 'object') {
+            errors.push({ message: 'Roadmap must have a metadata object', type: 'structure' });
+        }
+        else {
+            this.validateMetadata(roadmap.metadata, errors);
+        }
+        if (!Array.isArray(roadmap.tasks)) {
+            errors.push({ message: 'Roadmap must have a tasks array', type: 'structure' });
+        }
+    }
+    /**
+     * Validates tasks and checks for duplicates
+     * @param tasks - The tasks to validate
+     * @param errors - Array to collect errors
+     * @returns Set of valid task IDs
+     */
+    validateTasks(tasks, errors) {
+        const taskIds = new Set();
+        for (const task of tasks) {
+            try {
+                validateTask(task);
+            }
+            catch (error) {
+                errors.push({
+                    message: error instanceof Error ? error.message : String(error),
+                    taskId: task.id,
+                    type: 'task',
+                });
+            }
+            // Check for duplicate IDs
+            if (taskIds.has(task.id)) {
+                errors.push({
+                    message: `Duplicate task ID: ${task.id}`,
+                    taskId: task.id,
+                    type: 'duplicate-id',
+                });
+            }
+            taskIds.add(task.id);
+        }
+        return taskIds;
+    }
+}
+/**
+ * Default export instance of RoadmapService for convenience.
+ * Can be imported and used directly without instantiation.
+ *
+ * @example
+ * ```typescript
+ * import roadmapService from './services/roadmap.service.js';
+ * const roadmap = await roadmapService.load('./prt.json');
+ * ```
+ */
+export default new RoadmapService();