project-roadmap-tracking 0.1.0 → 0.2.1

package/dist/repositories/config.repository.js

@@ -0,0 +1,282 @@
+import Ajv from 'ajv';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ConfigNotFoundError, ValidationError } from '../errors/index.js';
+/**
+ * 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 class ConfigRepository {
+    static configSchema = {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        additionalProperties: false,
+        properties: {
+            $schema: {
+                description: 'Reference to the JSON schema for validation',
+                type: 'string',
+            },
+            cache: {
+                additionalProperties: false,
+                description: 'Caching configuration for the roadmap repository',
+                properties: {
+                    enabled: {
+                        default: true,
+                        description: 'Enable in-memory caching of roadmap data',
+                        type: 'boolean',
+                    },
+                    maxSize: {
+                        default: 10,
+                        description: 'Maximum number of roadmaps to cache (LRU eviction)',
+                        minimum: 1,
+                        type: 'number',
+                    },
+                    watchFiles: {
+                        default: true,
+                        description: 'Watch roadmap files for external changes and auto-invalidate cache',
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+            metadata: {
+                additionalProperties: false,
+                description: 'Metadata about the project roadmap',
+                properties: {
+                    description: {
+                        description: 'Description of the project roadmap',
+                        type: 'string',
+                    },
+                    name: {
+                        description: 'Name of the project roadmap',
+                        type: 'string',
+                    },
+                },
+                type: 'object',
+            },
+            path: {
+                default: './prt.json',
+                description: 'Path to the prt.json roadmap file',
+                type: 'string',
+            },
+        },
+        required: ['path'],
+        type: 'object',
+    };
+    cache = null;
+    config;
+    validateSchema;
+    constructor(config) {
+        this.config = {
+            cacheEnabled: config?.cacheEnabled ?? true,
+            searchPaths: config?.searchPaths ?? this.getDefaultSearchPaths(),
+        };
+        // Initialize JSON schema validator
+        const ajv = new Ajv({ allErrors: true });
+        this.validateSchema = ajv.compile(ConfigRepository.configSchema);
+    }
+    /**
+     * Get the currently cached config (if any)
+     */
+    getCachedConfig() {
+        return this.cache?.data ?? null;
+    }
+    /**
+     * Clear the in-memory cache
+     */
+    invalidateCache() {
+        this.cache = null;
+    }
+    /**
+     * 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)
+     */
+    async load() {
+        // Check cache if enabled
+        if (this.config.cacheEnabled && this.cache) {
+            const isValid = await this.isCacheValid();
+            if (isValid) {
+                return this.cache.data;
+            }
+        }
+        // Load and merge configs from all search paths
+        const configs = await this.loadAllConfigs();
+        if (configs.length === 0) {
+            throw new ConfigNotFoundError('.prtrc.json');
+        }
+        // Shallow merge: project overrides user overrides global
+        const merged = this.mergeConfigs(configs);
+        // Validate merged config
+        this.validateConfig(merged);
+        // Cache the result
+        if (this.config.cacheEnabled) {
+            const stats = await stat(configs[0].path); // Use mtime of project-level config
+            this.cache = {
+                data: merged,
+                mtime: stats.mtimeMs,
+                path: configs[0].path,
+            };
+        }
+        return merged;
+    }
+    /**
+     * Reload config from disk, bypassing cache
+     */
+    async reload() {
+        this.invalidateCache();
+        return this.load();
+    }
+    /**
+     * Get default config file search paths
+     * Order: project → user → global
+     */
+    getDefaultSearchPaths() {
+        const paths = [
+            '.prtrc.json', // Project level (current directory)
+            join(homedir(), '.prtrc.json'), // User level
+        ];
+        // Global level (Unix-like systems only)
+        if (process.platform !== 'win32') {
+            paths.push('/etc/prt/.prtrc.json');
+        }
+        return paths;
+    }
+    /**
+     * Check if cached config is still valid by comparing mtime
+     */
+    async isCacheValid() {
+        if (!this.cache) {
+            return false;
+        }
+        try {
+            const stats = await stat(this.cache.path);
+            return stats.mtimeMs === this.cache.mtime;
+        }
+        catch {
+            // If stat fails, cache is invalid
+            return false;
+        }
+    }
+    /**
+     * Load all available configs from search paths
+     * Returns array in order of precedence (project first, global last)
+     */
+    async loadAllConfigs() {
+        const paths = this.config.searchPaths ?? [];
+        const configPromises = paths.map(async (path) => {
+            const config = await this.loadConfigFromPath(path);
+            return config ? { config, path } : null;
+        });
+        const results = await Promise.all(configPromises);
+        return results.filter((result) => result !== null);
+    }
+    /**
+     * Load config from a specific path
+     */
+    async loadConfigFromPath(path) {
+        try {
+            const data = await readFile(path, 'utf8');
+            const config = JSON.parse(data);
+            return config;
+        }
+        catch (error) {
+            // Re-throw SyntaxError for JSON parsing issues
+            if (error instanceof SyntaxError) {
+                throw error;
+            }
+            // Return null for file not found (not an error during inheritance search)
+            return null;
+        }
+    }
+    /**
+     * Merge configs using shallow merge strategy
+     * Project-level config takes precedence over user-level over global-level
+     */
+    mergeConfigs(configs) {
+        if (configs.length === 0) {
+            throw new ConfigNotFoundError('.prtrc.json');
+        }
+        // Start with the lowest precedence config (last in array)
+        const lastConfig = configs.at(-1);
+        if (!lastConfig) {
+            throw new ConfigNotFoundError('.prtrc.json');
+        }
+        let merged = { ...lastConfig.config };
+        // Apply each higher-precedence config (working backwards)
+        for (let i = configs.length - 2; i >= 0; i--) {
+            merged = {
+                ...merged,
+                ...configs[i].config,
+                // Deep merge for nested objects
+                cache: configs[i].config.cache ? { ...merged.cache, ...configs[i].config.cache } : merged.cache,
+                metadata: configs[i].config.metadata ? { ...merged.metadata, ...configs[i].config.metadata } : merged.metadata,
+            };
+        }
+        return merged;
+    }
+    /**
+     * Validate config against JSON schema
+     */
+    validateConfig(config) {
+        try {
+            const valid = this.validateSchema(config);
+            if (!valid) {
+                // Handle case where validateSchema.errors might be null/undefined
+                if (!this.validateSchema.errors || !Array.isArray(this.validateSchema.errors)) {
+                    throw new ValidationError([
+                        {
+                            field: 'config',
+                            message: 'Schema validation failed',
+                            type: 'structure',
+                        },
+                    ]);
+                }
+                const errorDetails = this.validateSchema.errors.map((err) => ({
+                    field: err.dataPath || 'config',
+                    message: err.message || 'Unknown error',
+                    type: 'structure',
+                }));
+                throw new ValidationError(errorDetails);
+            }
+        }
+        catch (error) {
+            // If it's already a ValidationError, re-throw it
+            if (error instanceof ValidationError) {
+                throw error;
+            }
+            // Wrap any other error (like TypeError) in ValidationError
+            throw new ValidationError([
+                {
+                    field: 'config',
+                    message: error instanceof Error ? error.message : String(error),
+                    type: 'structure',
+                },
+            ]);
+        }
+    }
+}
+// Singleton instance with default configuration
+let defaultInstance = null;
+/**
+ * Get the default config repository instance
+ */
+export function getDefaultConfigRepository() {
+    if (!defaultInstance) {
+        defaultInstance = new ConfigRepository();
+    }
+    return defaultInstance;
+}
+/**
+ * Reset the default config repository instance (useful for testing)
+ */
+export function resetDefaultConfigRepository() {
+    if (defaultInstance) {
+        defaultInstance.invalidateCache();
+        defaultInstance = null;
+    }
+}

package/dist/repositories/index.d.ts

@@ -0,0 +1,2 @@
+export * from './config.repository.js';
+export * from './roadmap.repository.js';

package/dist/repositories/index.js

@@ -0,0 +1,2 @@
+export * from './config.repository.js';
+export * from './roadmap.repository.js';

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

@@ -0,0 +1,82 @@
+import { Config, Roadmap } from '../util/types.js';
+/**
+ * Configuration for RoadmapRepository
+ */
+export interface RepositoryConfig {
+    cacheEnabled?: boolean;
+    maxCacheSize?: number;
+    watchFiles?: boolean;
+}
+/**
+ * RoadmapRepository provides caching and file watching for roadmap data.
+ * Features:
+ * - In-memory LRU cache with configurable size
+ * - Automatic cache invalidation on writes
+ * - File system watching for external changes (using chokidar)
+ * - Configuration via .prtrc.json cache settings
+ */
+export declare class RoadmapRepository {
+    private cache;
+    private config;
+    private watchers;
+    constructor(config?: RepositoryConfig);
+    /**
+     * Create a repository instance from a Config object
+     */
+    static fromConfig(config: Config): RoadmapRepository;
+    /**
+     * Stop all file watchers and clear cache
+     */
+    dispose(): Promise<void>;
+    /**
+     * Get current cache size
+     */
+    getCacheSize(): number;
+    /**
+     * Invalidate cache for a specific path
+     * @param path - Path to invalidate
+     */
+    invalidate(path: string): void;
+    /**
+     * Invalidate all cached roadmaps
+     */
+    invalidateAll(): void;
+    /**
+     * Check if a path is cached
+     */
+    isCached(path: string): boolean;
+    /**
+     * Load a roadmap from the file system with caching
+     * @param path - Path to the roadmap file
+     * @returns The loaded roadmap
+     */
+    load(path: string): Promise<Roadmap>;
+    /**
+     * Save a roadmap to the file system and update cache
+     * @param path - Path to the roadmap file
+     * @param roadmap - The roadmap to save
+     */
+    save(path: string, roadmap: Roadmap): Promise<void>;
+    /**
+     * Add entry to cache with LRU eviction
+     */
+    private addToCache;
+    /**
+     * Load roadmap from disk without caching
+     */
+    private loadFromDisk;
+    /**
+     * Set up file watcher for a path
+     */
+    private setupWatcher;
+}
+/**
+ * Get the default repository instance
+ */
+export declare function getDefaultRepository(): RoadmapRepository;
+/**
+ * Reset the default repository instance (useful for testing)
+ */
+export declare function resetDefaultRepository(): void;
+declare const _default: RoadmapRepository;
+export default _default;

package/dist/repositories/roadmap.repository.js

@@ -0,0 +1,201 @@
+import { watch } from 'chokidar';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+/**
+ * RoadmapRepository provides caching and file watching for roadmap data.
+ * Features:
+ * - In-memory LRU cache with configurable size
+ * - Automatic cache invalidation on writes
+ * - File system watching for external changes (using chokidar)
+ * - Configuration via .prtrc.json cache settings
+ */
+export class RoadmapRepository {
+    cache = new Map();
+    config;
+    watchers = new Map();
+    constructor(config) {
+        this.config = {
+            cacheEnabled: config?.cacheEnabled ?? true,
+            maxCacheSize: config?.maxCacheSize ?? 10,
+            watchFiles: config?.watchFiles ?? true,
+        };
+    }
+    /**
+     * Create a repository instance from a Config object
+     */
+    static fromConfig(config) {
+        return new RoadmapRepository({
+            cacheEnabled: config.cache?.enabled ?? true,
+            maxCacheSize: config.cache?.maxSize ?? 10,
+            watchFiles: config.cache?.watchFiles ?? true,
+        });
+    }
+    /**
+     * Stop all file watchers and clear cache
+     */
+    async dispose() {
+        // Close all watchers
+        await Promise.all([...this.watchers.values()].map((watcher) => watcher.close()));
+        this.watchers.clear();
+        this.cache.clear();
+    }
+    /**
+     * Get current cache size
+     */
+    getCacheSize() {
+        return this.cache.size;
+    }
+    /**
+     * Invalidate cache for a specific path
+     * @param path - Path to invalidate
+     */
+    invalidate(path) {
+        this.cache.delete(path);
+    }
+    /**
+     * Invalidate all cached roadmaps
+     */
+    invalidateAll() {
+        this.cache.clear();
+    }
+    /**
+     * Check if a path is cached
+     */
+    isCached(path) {
+        return this.cache.has(path);
+    }
+    /**
+     * Load a roadmap from the file system with caching
+     * @param path - Path to the roadmap file
+     * @returns The loaded roadmap
+     */
+    async load(path) {
+        // Check if caching is disabled
+        if (!this.config.cacheEnabled) {
+            return this.loadFromDisk(path);
+        }
+        // Check if we have a cached version
+        const cached = this.cache.get(path);
+        if (cached) {
+            // Verify cache is still valid by checking mtime
+            try {
+                const stats = await stat(path);
+                const currentMtime = stats.mtimeMs;
+                if (currentMtime === cached.mtime) {
+                    // Cache hit - move to end for LRU
+                    this.cache.delete(path);
+                    this.cache.set(path, cached);
+                    return cached.data;
+                }
+            }
+            catch {
+                // If stat fails, invalidate cache and reload
+                this.invalidate(path);
+            }
+        }
+        // Cache miss or stale - load from disk
+        const roadmap = await this.loadFromDisk(path);
+        const stats = await stat(path);
+        // Add to cache with LRU eviction
+        this.addToCache(path, roadmap, stats.mtimeMs);
+        // Set up file watcher if enabled
+        if (this.config.watchFiles && !this.watchers.has(path)) {
+            this.setupWatcher(path);
+        }
+        return roadmap;
+    }
+    /**
+     * Save a roadmap to the file system and update cache
+     * @param path - Path to the roadmap file
+     * @param roadmap - The roadmap to save
+     */
+    async save(path, roadmap) {
+        await writeFile(path, JSON.stringify(roadmap, null, 2), 'utf8');
+        // Update cache if caching is enabled
+        if (this.config.cacheEnabled) {
+            const stats = await stat(path);
+            this.addToCache(path, roadmap, stats.mtimeMs);
+        }
+    }
+    /**
+     * Add entry to cache with LRU eviction
+     */
+    addToCache(path, data, mtime) {
+        // Remove old entry if exists (for LRU reordering)
+        if (this.cache.has(path)) {
+            this.cache.delete(path);
+        }
+        // Evict oldest entry if cache is full
+        if (this.cache.size >= (this.config.maxCacheSize ?? 10)) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey) {
+                this.cache.delete(firstKey);
+                // Also stop watching evicted file
+                const watcher = this.watchers.get(firstKey);
+                if (watcher) {
+                    watcher.close().catch(() => {
+                        /* ignore close errors */
+                    });
+                    this.watchers.delete(firstKey);
+                }
+            }
+        }
+        // Add new entry
+        this.cache.set(path, { data, mtime, path });
+    }
+    /**
+     * Load roadmap from disk without caching
+     */
+    async loadFromDisk(path) {
+        const data = await readFile(path, 'utf8');
+        return JSON.parse(data);
+    }
+    /**
+     * Set up file watcher for a path
+     */
+    setupWatcher(path) {
+        const watcher = watch(path, {
+            awaitWriteFinish: {
+                pollInterval: 100,
+                stabilityThreshold: 250,
+            },
+            persistent: false,
+        });
+        watcher.on('change', () => {
+            this.invalidate(path);
+        });
+        watcher.on('unlink', () => {
+            this.invalidate(path);
+            this.watchers
+                .get(path)
+                ?.close()
+                .catch(() => {
+                /* ignore close errors */
+            });
+            this.watchers.delete(path);
+        });
+        this.watchers.set(path, watcher);
+    }
+}
+// Singleton instance with default configuration
+let defaultInstance = null;
+/**
+ * Get the default repository instance
+ */
+export function getDefaultRepository() {
+    if (!defaultInstance) {
+        defaultInstance = new RoadmapRepository();
+    }
+    return defaultInstance;
+}
+/**
+ * Reset the default repository instance (useful for testing)
+ */
+export function resetDefaultRepository() {
+    if (defaultInstance) {
+        defaultInstance.dispose().catch(() => {
+            /* ignore disposal errors */
+        });
+        defaultInstance = null;
+    }
+}
+export default getDefaultRepository();