specweave 0.23.10 → 0.23.14

package/dist/src/integrations/jira/jira-dependency-loader.js

@@ -0,0 +1,200 @@
+/**
+ * JiraDependencyLoader - Three-Tier Dependency Loading for JIRA
+ *
+ * Architecture (ADR-0056):
+ * - Tier 1 (Init): Metadata only (< 5 seconds, 1 API call)
+ * - Tier 2 (On-Demand): Lazy loading per project (2-5 seconds, 4-7 API calls)
+ * - Tier 3 (Bulk): Optional pre-load command (1-2 minutes for 50 projects)
+ *
+ * Features:
+ * - 24-hour TTL caching via CacheManager
+ * - Rate limit detection and stale cache fallback
+ * - Per-project dependency caching
+ * - Automatic cache invalidation on 404 errors
+ *
+ * @module integrations/jira/jira-dependency-loader
+ */
+import { RateLimitChecker } from '../../core/cache/rate-limit-checker.js';
+import { consoleLogger } from '../../utils/logger.js';
+/**
+ * JiraDependencyLoader - Three-tier dependency loading with smart caching
+ */
+export class JiraDependencyLoader {
+    constructor(options) {
+        this.jiraClient = options.jiraClient;
+        this.cacheManager = options.cacheManager;
+        this.rateLimitChecker = options.rateLimitChecker ?? new RateLimitChecker();
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Tier 1: Load project metadata only (init)
+     *
+     * Performance: < 5 seconds for 50 projects (1 API call)
+     * Cache: 24-hour TTL in `jira-projects.json`
+     *
+     * @param maxProjects Maximum projects to load (default: 50)
+     * @returns Array of project metadata
+     */
+    async loadProjectMetadata(maxProjects = 50) {
+        const cacheKey = 'jira-projects';
+        // Check cache first
+        const cached = await this.cacheManager.get(cacheKey);
+        if (cached) {
+            this.logger.log(`Cache hit: ${cacheKey} (${cached.projects.length} projects)`);
+            return cached.projects;
+        }
+        // Cache miss - fetch from API
+        this.logger.log(`Cache miss: ${cacheKey}, fetching from JIRA API...`);
+        try {
+            // Use JIRA search API for batch loading
+            const response = await this.jiraClient.searchProjects({
+                maxResults: maxProjects,
+                orderBy: 'name',
+            });
+            // Extract rate limit headers
+            const rateLimitHeaders = this.rateLimitChecker.extractHeaders(response);
+            const rateLimitCheck = this.rateLimitChecker.shouldProceed(rateLimitHeaders);
+            if (!rateLimitCheck.canProceed) {
+                this.logger.warn(`Rate limit warning: ${rateLimitCheck.reason}. Consider using cached data.`);
+            }
+            // Parse projects
+            const projects = response.values.map((project) => ({
+                key: project.key,
+                name: project.name,
+                type: project.projectTypeKey || 'software',
+                lead: project.lead
+                    ? {
+                        displayName: project.lead.displayName,
+                    }
+                    : undefined,
+            }));
+            // Cache result
+            await this.cacheManager.set(cacheKey, { projects });
+            this.logger.log(`Cached ${projects.length} projects with 24-hour TTL`);
+            return projects;
+        }
+        catch (error) {
+            // Check for rate limit error (429)
+            if (this.rateLimitChecker.isRateLimitError(error)) {
+                await this.rateLimitChecker.handleRateLimitError(error);
+                // Try to use stale cache
+                const staleCache = await this.cacheManager.getStale(cacheKey);
+                if (staleCache) {
+                    return staleCache.projects;
+                }
+            }
+            // Re-throw if not rate limit or no stale cache available
+            throw error;
+        }
+    }
+    /**
+     * Tier 2: Load dependencies for specific project (on-demand)
+     *
+     * Performance: 2-5 seconds per project (4-7 API calls, cached)
+     * Cache: 24-hour TTL in `jira-{PROJECT}-deps.json`
+     *
+     * @param projectKey Project key (e.g., "BACKEND")
+     * @returns Project dependencies
+     */
+    async loadProjectDependencies(projectKey) {
+        const cacheKey = `jira-${projectKey}-deps`;
+        // Check cache first
+        const cached = await this.cacheManager.get(cacheKey);
+        if (cached) {
+            this.logger.log(`Cache hit: ${cacheKey}`);
+            return cached;
+        }
+        // Cache miss - fetch from API
+        this.logger.log(`Cache miss: ${cacheKey}, fetching from JIRA API...`);
+        try {
+            // Fetch boards, components, versions in parallel
+            const [boardsResponse, componentsResponse, versionsResponse] = await Promise.all([
+                this.jiraClient.getBoards(projectKey),
+                this.jiraClient.getComponents(projectKey),
+                this.jiraClient.getVersions(projectKey),
+            ]);
+            // Build dependencies object
+            const dependencies = {
+                projectKey,
+                boards: boardsResponse.values?.map((board) => ({
+                    id: board.id,
+                    name: board.name,
+                    type: board.type,
+                })) || [],
+                components: componentsResponse.map((component) => ({
+                    id: component.id,
+                    name: component.name,
+                })),
+                versions: versionsResponse.map((version) => ({
+                    id: version.id,
+                    name: version.name,
+                    released: version.released,
+                })),
+                lastUpdated: new Date().toISOString(),
+            };
+            // Cache result
+            await this.cacheManager.set(cacheKey, dependencies);
+            this.logger.log(`Cached dependencies for ${projectKey}: ${dependencies.boards.length} boards, ${dependencies.components.length} components, ${dependencies.versions.length} versions`);
+            return dependencies;
+        }
+        catch (error) {
+            // Handle 404 (project not found) - invalidate cache
+            if (error.response?.status === 404) {
+                this.logger.warn(`Project ${projectKey} not found (404), invalidating cache...`);
+                await this.cacheManager.delete(cacheKey);
+                throw new Error(`Project ${projectKey} not found`);
+            }
+            // Handle rate limit errors
+            if (this.rateLimitChecker.isRateLimitError(error)) {
+                await this.rateLimitChecker.handleRateLimitError(error);
+                // Try to use stale cache
+                const staleCache = await this.cacheManager.getStale(cacheKey);
+                if (staleCache) {
+                    return staleCache;
+                }
+            }
+            // Re-throw if not handled
+            throw error;
+        }
+    }
+    /**
+     * Tier 3: Bulk pre-load all dependencies (optional command)
+     *
+     * Performance: 1-2 minutes for 50 projects (200-350 API calls, batched)
+     * Progress: Real-time progress tracking, cancelation support
+     *
+     * @param projectKeys Array of project keys to preload
+     * @returns void (results cached)
+     */
+    async preloadAllDependencies(projectKeys, options = {}) {
+        const { onProgress, signal } = options;
+        const total = projectKeys.length;
+        this.logger.log(`Preloading dependencies for ${total} projects...`);
+        for (let i = 0; i < total; i++) {
+            // Check for cancelation
+            if (signal?.aborted) {
+                this.logger.warn('Preload canceled by user');
+                throw new Error('Preload canceled');
+            }
+            const projectKey = projectKeys[i];
+            this.logger.log(`[${i + 1}/${total}] Preloading ${projectKey}...`);
+            try {
+                await this.loadProjectDependencies(projectKey);
+                // Report progress
+                if (onProgress) {
+                    onProgress(i + 1, total);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to preload ${projectKey}: ${error.message}`);
+                // Continue with next project (don't fail entire batch)
+            }
+            // Add delay to avoid rate limiting (200ms between requests)
+            if (i < total - 1) {
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+        }
+        this.logger.log('Preload complete!');
+    }
+}
+//# sourceMappingURL=jira-dependency-loader.js.map

package/dist/src/integrations/jira/jira-dependency-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jira-dependency-loader.js","sourceRoot":"","sources":["../../../../src/integrations/jira/jira-dependency-loader.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.23.10",
+  "version": "0.23.14",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -30,6 +30,26 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-spec.sh",
+            "timeout": 2
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-write-spec.sh",
+            "timeout": 2
+          }
+        ]
       }
     ],
     "PostToolUse": [