project-roadmap-tracking 0.1.0 → 0.2.0

package/dist/commands/validate.d.ts

@@ -3,6 +3,9 @@ export default class Validate extends Command {
     static args: {};
     static description: string;
     static examples: string[];
-    static flags: {};
+    static flags: {
+        'no-repo': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/validate.js

@@ -1,49 +1,91 @@
-import { Command } from '@oclif/core';
+import { Command, Flags } from '@oclif/core';
 import { readFile } from 'node:fs/promises';
+import { getDefaultConfigRepository } from '../repositories/config.repository.js';
+import { RoadmapRepository } from '../repositories/roadmap.repository.js';
+import displayService from '../services/display.service.js';
+import errorHandlerService from '../services/error-handler.service.js';
+import taskDependencyService from '../services/task-dependency.service.js';
 import { readConfigFile } from '../util/read-config.js';
 import { validateTask } from '../util/validate-task.js';
 export default class Validate extends Command {
     static args = {
     // file: Args.string({description: 'file to read'}),
     };
-    static description = 'describe the command here';
+    static description = 'Validate roadmap structure, task data, and check for circular dependencies';
     static examples = ['<%= config.bin %> <%= command.id %>'];
     static flags = {
-    // flag with no value (-f, --force)
-    // force: Flags.boolean({char: 'f'}),
-    // flag with a value (-n, --name=VALUE)
-    // name: Flags.string({char: 'n', description: 'name to print'}),
+        'no-repo': Flags.boolean({
+            default: false,
+            description: 'use legacy direct file I/O instead of repository pattern',
+        }),
+        // flag with no value (-f, --force)
+        // force: Flags.boolean({char: 'f'}),
+        // flag with a value (-n, --name=VALUE)
+        // name: Flags.string({char: 'n', description: 'name to print'}),
+        verbose: Flags.boolean({
+            char: 'v',
+            default: false,
+            description: 'show detailed error information including stack traces',
+        }),
     };
     async run() {
-        await this.parse(Validate);
-        this.log(`validating roadmap...`);
-        const config = await readConfigFile().catch((error) => {
-            this.error(`failed to read config file: ${error ? error.message : String(error)}`);
-        });
-        const roadmapPath = config.path;
-        const roadmapData = await readFile(roadmapPath, 'utf8');
-        let roadmap;
+        const { flags } = await this.parse(Validate);
         try {
-            roadmap = JSON.parse(roadmapData);
-            this.log(`roadmap at ${roadmapPath} is valid JSON`);
-        }
-        catch (error) {
-            this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
-        }
-        if (roadmap.tasks.length === 0) {
-            this.log('roadmap contains no tasks to validate');
-            this.log('roadmap validation complete');
-            return;
-        }
-        for (const task of roadmap.tasks) {
-            try {
-                validateTask(task);
+            this.log(`validating roadmap...`);
+            // Use repository pattern by default, unless --no-repo flag is set
+            const config = flags['no-repo'] ? await readConfigFile() : await getDefaultConfigRepository().load();
+            const roadmapPath = config.path;
+            let roadmap;
+            if (flags['no-repo']) {
+                const roadmapData = await readFile(roadmapPath, 'utf8');
+                try {
+                    roadmap = JSON.parse(roadmapData);
+                    this.log(`roadmap at ${roadmapPath} is valid JSON`);
+                }
+                catch (error) {
+                    this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                try {
+                    roadmap = await RoadmapRepository.fromConfig(config).load(roadmapPath);
+                    this.log(`roadmap at ${roadmapPath} is valid JSON`);
+                }
+                catch (error) {
+                    this.error(`roadmap at ${roadmapPath} is not valid JSON: ${error ? error.message : String(error)}`);
+                }
             }
-            catch (error) {
-                this.error(`task ID ${task.id} is invalid: ${error ? error.message : String(error)}`);
+            if (roadmap.tasks.length === 0) {
+                this.log('roadmap contains no tasks to validate');
+                this.log('roadmap validation complete');
+                return;
             }
+            for (const task of roadmap.tasks) {
+                try {
+                    validateTask(task);
+                }
+                catch (error) {
+                    this.error(`task ID ${task.id} is invalid: ${error ? error.message : String(error)}`);
+                }
+            }
+            // this.log(roadmap.tasks.length > 1 ? `all ${roadmap.tasks.length} tasks are valid` : `1 task is valid`)
+            // Validate dependencies (including circular dependency check)
+            this.log(`validating task dependencies...`);
+            const dependencyErrors = taskDependencyService.validateDependencies(roadmap);
+            if (dependencyErrors.length > 0) {
+                const errorLines = displayService.formatValidationErrors(dependencyErrors);
+                for (const line of errorLines) {
+                    this.log(line);
+                }
+                // Exit with error if any dependency errors found
+                this.error('Dependency validation failed');
+            }
+            this.log(`all task dependencies are valid`);
+            this.log(`roadmap validation complete`);
+        }
+        catch (error) {
+            const exitCode = errorHandlerService.handleError(error);
+            this.error(errorHandlerService.formatErrorMessage(error, flags.verbose), { exit: exitCode });
         }
-        this.log(roadmap.tasks.length > 1 ? `all ${roadmap.tasks.length} tasks are valid` : `1 task is valid`);
-        this.log(`roadmap validation complete`);
     }
 }

package/dist/errors/base.error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error codes for all PRT errors
+ */
+export declare enum PrtErrorCode {
+    PRT_FILE_CONFIG_NOT_FOUND = "PRT_FILE_CONFIG_NOT_FOUND",
+    PRT_FILE_ROADMAP_NOT_FOUND = "PRT_FILE_ROADMAP_NOT_FOUND",
+    PRT_TASK_ID_INVALID = "PRT_TASK_ID_INVALID",
+    PRT_TASK_INVALID = "PRT_TASK_INVALID",
+    PRT_TASK_NOT_FOUND = "PRT_TASK_NOT_FOUND",
+    PRT_UNKNOWN = "PRT_UNKNOWN",
+    PRT_VALIDATION_CIRCULAR_DEPENDENCY = "PRT_VALIDATION_CIRCULAR_DEPENDENCY",
+    PRT_VALIDATION_FAILED = "PRT_VALIDATION_FAILED"
+}
+/**
+ * Base error class for all PRT custom errors
+ */
+export declare class PrtError extends Error {
+    readonly code: PrtErrorCode;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code?: PrtErrorCode, context?: Record<string, unknown>);
+}

package/dist/errors/base.error.js

@@ -0,0 +1,35 @@
+/**
+ * Error codes for all PRT errors
+ */
+export var PrtErrorCode;
+(function (PrtErrorCode) {
+    PrtErrorCode["PRT_FILE_CONFIG_NOT_FOUND"] = "PRT_FILE_CONFIG_NOT_FOUND";
+    // File errors
+    PrtErrorCode["PRT_FILE_ROADMAP_NOT_FOUND"] = "PRT_FILE_ROADMAP_NOT_FOUND";
+    PrtErrorCode["PRT_TASK_ID_INVALID"] = "PRT_TASK_ID_INVALID";
+    PrtErrorCode["PRT_TASK_INVALID"] = "PRT_TASK_INVALID";
+    // Task errors
+    PrtErrorCode["PRT_TASK_NOT_FOUND"] = "PRT_TASK_NOT_FOUND";
+    // Generic
+    PrtErrorCode["PRT_UNKNOWN"] = "PRT_UNKNOWN";
+    PrtErrorCode["PRT_VALIDATION_CIRCULAR_DEPENDENCY"] = "PRT_VALIDATION_CIRCULAR_DEPENDENCY";
+    // Validation errors
+    PrtErrorCode["PRT_VALIDATION_FAILED"] = "PRT_VALIDATION_FAILED";
+})(PrtErrorCode || (PrtErrorCode = {}));
+/**
+ * Base error class for all PRT custom errors
+ */
+export class PrtError extends Error {
+    code;
+    context;
+    constructor(message, code = PrtErrorCode.PRT_UNKNOWN, context) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}

package/dist/errors/circular-dependency.error.d.ts

@@ -0,0 +1,8 @@
+import type { TaskID } from '../util/types.js';
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when circular dependencies are detected in tasks
+ */
+export declare class CircularDependencyError extends PrtError {
+    constructor(cycle: TaskID[], message?: string);
+}

package/dist/errors/circular-dependency.error.js

@@ -0,0 +1,13 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when circular dependencies are detected in tasks
+ */
+export class CircularDependencyError extends PrtError {
+    constructor(cycle, message) {
+        const defaultMessage = `Circular dependency detected: ${cycle.join(' -> ')} -> ${cycle[0]}`;
+        super(message || defaultMessage, PrtErrorCode.PRT_VALIDATION_CIRCULAR_DEPENDENCY, {
+            cycle,
+            cycleLength: cycle.length,
+        });
+    }
+}

package/dist/errors/config-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a config file (.prtrc.json) cannot be found
+ */
+export declare class ConfigNotFoundError extends PrtError {
+    constructor(filePath?: string, cause?: Error);
+}

package/dist/errors/config-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a config file (.prtrc.json) cannot be found
+ */
+export class ConfigNotFoundError extends PrtError {
+    constructor(filePath = '.prtrc.json', cause) {
+        super(`Config file not found: ${filePath}`, PrtErrorCode.PRT_FILE_CONFIG_NOT_FOUND, {
+            filePath,
+            ...(cause && { cause: cause.message }),
+        });
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,16 @@
+export { PrtError, PrtErrorCode } from './base.error.js';
+export { CircularDependencyError } from './circular-dependency.error.js';
+export { ConfigNotFoundError } from './config-not-found.error.js';
+export { InvalidTaskError } from './invalid-task.error.js';
+export { RoadmapNotFoundError } from './roadmap-not-found.error.js';
+export { TaskNotFoundError } from './task-not-found.error.js';
+export { ValidationError, type ValidationErrorDetail } from './validation.error.js';
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Type guard to check if an error is a PrtError
+ */
+export declare function isPrtError(error: unknown): error is PrtError;
+/**
+ * Get the error code from an error, or null if not a PrtError
+ */
+export declare function getErrorCode(error: unknown): null | PrtErrorCode;

package/dist/errors/index.js

@@ -0,0 +1,26 @@
+// Base error and error codes
+export { PrtError, PrtErrorCode } from './base.error.js';
+export { CircularDependencyError } from './circular-dependency.error.js';
+// Specific error classes
+export { ConfigNotFoundError } from './config-not-found.error.js';
+export { InvalidTaskError } from './invalid-task.error.js';
+export { RoadmapNotFoundError } from './roadmap-not-found.error.js';
+export { TaskNotFoundError } from './task-not-found.error.js';
+export { ValidationError } from './validation.error.js';
+// Import for type guards
+import { PrtError } from './base.error.js';
+/**
+ * Type guard to check if an error is a PrtError
+ */
+export function isPrtError(error) {
+    return error instanceof PrtError;
+}
+/**
+ * Get the error code from an error, or null if not a PrtError
+ */
+export function getErrorCode(error) {
+    if (isPrtError(error)) {
+        return error.code;
+    }
+    return null;
+}

package/dist/errors/invalid-task.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a task fails validation
+ */
+export declare class InvalidTaskError extends PrtError {
+    constructor(message: string, taskId?: string, validationField?: string);
+}

package/dist/errors/invalid-task.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a task fails validation
+ */
+export class InvalidTaskError extends PrtError {
+    constructor(message, taskId, validationField) {
+        super(message, PrtErrorCode.PRT_TASK_INVALID, {
+            ...(taskId && { taskId }),
+            ...(validationField && { validationField }),
+        });
+    }
+}

package/dist/errors/roadmap-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a roadmap file cannot be found
+ */
+export declare class RoadmapNotFoundError extends PrtError {
+    constructor(filePath: string, cause?: Error);
+}

package/dist/errors/roadmap-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a roadmap file cannot be found
+ */
+export class RoadmapNotFoundError extends PrtError {
+    constructor(filePath, cause) {
+        super(`Roadmap file not found: ${filePath}`, PrtErrorCode.PRT_FILE_ROADMAP_NOT_FOUND, {
+            filePath,
+            ...(cause && { cause: cause.message }),
+        });
+    }
+}

package/dist/errors/task-not-found.error.d.ts

@@ -0,0 +1,7 @@
+import { PrtError } from './base.error.js';
+/**
+ * Error thrown when a task cannot be found by its ID
+ */
+export declare class TaskNotFoundError extends PrtError {
+    constructor(taskId: string, roadmapPath?: string);
+}

package/dist/errors/task-not-found.error.js

@@ -0,0 +1,12 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when a task cannot be found by its ID
+ */
+export class TaskNotFoundError extends PrtError {
+    constructor(taskId, roadmapPath) {
+        super(`Task not found: ${taskId}`, PrtErrorCode.PRT_TASK_NOT_FOUND, {
+            taskId,
+            ...(roadmapPath && { roadmapPath }),
+        });
+    }
+}

package/dist/errors/validation.error.d.ts

@@ -0,0 +1,16 @@
+import { PrtError } from './base.error.js';
+/**
+ * Details about a single validation error
+ */
+export interface ValidationErrorDetail {
+    field?: string;
+    message: string;
+    taskId?: string;
+    type: 'circular-dependency' | 'duplicate-id' | 'invalid-reference' | 'invalid-value' | 'missing-field' | 'missing-task' | 'structure' | 'task';
+}
+/**
+ * Error thrown when validation fails with multiple issues
+ */
+export declare class ValidationError extends PrtError {
+    constructor(errors: ValidationErrorDetail[]);
+}

package/dist/errors/validation.error.js

@@ -0,0 +1,16 @@
+import { PrtError, PrtErrorCode } from './base.error.js';
+/**
+ * Error thrown when validation fails with multiple issues
+ */
+export class ValidationError extends PrtError {
+    constructor(errors) {
+        const errorCount = errors.length;
+        const errorTypes = [...new Set(errors.map((e) => e.type))];
+        const message = `Validation failed with ${errorCount} error${errorCount === 1 ? '' : 's'}`;
+        super(message, PrtErrorCode.PRT_VALIDATION_FAILED, {
+            errorCount,
+            errors,
+            errorTypes,
+        });
+    }
+}

package/dist/repositories/config.repository.d.ts

@@ -0,0 +1,76 @@
+import { Config } from '../util/types.js';
+/**
+ * Configuration for ConfigRepository
+ */
+export interface ConfigRepositoryConfig {
+    cacheEnabled?: boolean;
+    searchPaths?: string[];
+}
+/**
+ * ConfigRepository provides caching, validation, and inheritance for config files.
+ * Features:
+ * - In-memory cache with mtime-based invalidation
+ * - Multi-level config inheritance (project → user → global)
+ * - JSON schema validation using schemas/config/v1.1.json
+ * - Shallow merge strategy for inherited configs
+ */
+export declare class ConfigRepository {
+    private static configSchema;
+    private cache;
+    private config;
+    private validateSchema;
+    constructor(config?: ConfigRepositoryConfig);
+    /**
+     * Get the currently cached config (if any)
+     */
+    getCachedConfig(): Config | null;
+    /**
+     * Clear the in-memory cache
+     */
+    invalidateCache(): void;
+    /**
+     * Load config with caching and inheritance
+     * Searches for config files in order: project → user → global
+     * Merges configs with shallow merge (project overrides user overrides global)
+     */
+    load(): Promise<Config>;
+    /**
+     * Reload config from disk, bypassing cache
+     */
+    reload(): Promise<Config>;
+    /**
+     * Get default config file search paths
+     * Order: project → user → global
+     */
+    private getDefaultSearchPaths;
+    /**
+     * Check if cached config is still valid by comparing mtime
+     */
+    private isCacheValid;
+    /**
+     * Load all available configs from search paths
+     * Returns array in order of precedence (project first, global last)
+     */
+    private loadAllConfigs;
+    /**
+     * Load config from a specific path
+     */
+    private loadConfigFromPath;
+    /**
+     * Merge configs using shallow merge strategy
+     * Project-level config takes precedence over user-level over global-level
+     */
+    private mergeConfigs;
+    /**
+     * Validate config against JSON schema
+     */
+    private validateConfig;
+}
+/**
+ * Get the default config repository instance
+ */
+export declare function getDefaultConfigRepository(): ConfigRepository;
+/**
+ * Reset the default config repository instance (useful for testing)
+ */
+export declare function resetDefaultConfigRepository(): void;