specweave 0.14.0 → 0.15.0

package/plugins/specweave-github/lib/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for GitHub sync plugin
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/plugins/specweave-jira/lib/jira-board-resolver.js

@@ -1,55 +1,84 @@
-async function fetchBoardsForProject(client, projectKey) {
-  console.log(`\u{1F50D} Fetching boards for project: ${projectKey}`);
-  try {
-    const baseUrl = client.baseUrl;
-    const authHeader = client.getAuthHeader();
-    const url = `${baseUrl}/rest/agile/1.0/board?projectKeyOrId=${projectKey}`;
-    const response = await fetch(url, {
-      method: "GET",
-      headers: {
-        "Authorization": authHeader,
-        "Content-Type": "application/json"
-      }
-    });
-    if (!response.ok) {
-      const error = await response.text();
-      console.error(`\u274C Failed to fetch boards for ${projectKey}:`, error);
-      throw new Error(`Jira API error: ${response.status} ${error}`);
+/**
+ * Jira Board Resolution for Hierarchical Sync
+ *
+ * Resolves board names to board IDs for use in JQL queries.
+ * Supports Jira Agile (Software) boards.
+ */
+/**
+ * Fetch all boards for a Jira project
+ *
+ * Uses Jira Agile REST API: GET /rest/agile/1.0/board?projectKeyOrId={projectKey}
+ *
+ * @param client JiraClient instance
+ * @param projectKey Jira project key (e.g., "PROJECT-A")
+ * @returns Array of boards in the project
+ */
+export async function fetchBoardsForProject(client, projectKey) {
+    console.log(`🔍 Fetching boards for project: ${projectKey}`);
+    try {
+        // Access private baseUrl and getAuthHeader via reflection (not ideal but necessary)
+        const baseUrl = client.baseUrl;
+        const authHeader = client.getAuthHeader();
+        const url = `${baseUrl}/rest/agile/1.0/board?projectKeyOrId=${projectKey}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authorization': authHeader,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            console.error(`❌ Failed to fetch boards for ${projectKey}:`, error);
+            throw new Error(`Jira API error: ${response.status} ${error}`);
+        }
+        const data = await response.json();
+        const boards = data.values || [];
+        console.log(`✅ Found ${boards.length} board(s) for project ${projectKey}`);
+        return boards;
+    }
+    catch (error) {
+        console.error(`❌ Error fetching boards for ${projectKey}:`, error.message);
+        throw error;
     }
-    const data = await response.json();
-    const boards = data.values || [];
-    console.log(`\u2705 Found ${boards.length} board(s) for project ${projectKey}`);
-    return boards;
-  } catch (error) {
-    console.error(`\u274C Error fetching boards for ${projectKey}:`, error.message);
-    throw error;
-  }
 }
-async function resolveBoardNames(client, projectKey, boardNames) {
-  if (!boardNames || boardNames.length === 0) {
-    return /* @__PURE__ */ new Map();
-  }
-  const boards = await fetchBoardsForProject(client, projectKey);
-  const boardMap = /* @__PURE__ */ new Map();
-  for (const boardName of boardNames) {
-    const board = boards.find(
-      (b) => b.name.toLowerCase() === boardName.toLowerCase()
-    );
-    if (board) {
-      boardMap.set(boardName, board.id);
-      console.log(`\u2705 Resolved board "${boardName}" \u2192 ID ${board.id}`);
-    } else {
-      console.warn(`\u26A0\uFE0F  Board "${boardName}" not found in project ${projectKey}`);
+/**
+ * Resolve board names to board IDs
+ *
+ * @param client JiraClient instance
+ * @param projectKey Jira project key
+ * @param boardNames Array of board names to resolve
+ * @returns Map of board name → board ID
+ */
+export async function resolveBoardNames(client, projectKey, boardNames) {
+    if (!boardNames || boardNames.length === 0) {
+        return new Map();
+    }
+    const boards = await fetchBoardsForProject(client, projectKey);
+    const boardMap = new Map();
+    for (const boardName of boardNames) {
+        const board = boards.find((b) => b.name.toLowerCase() === boardName.toLowerCase());
+        if (board) {
+            boardMap.set(boardName, board.id);
+            console.log(`✅ Resolved board "${boardName}" → ID ${board.id}`);
+        }
+        else {
+            console.warn(`⚠️  Board "${boardName}" not found in project ${projectKey}`);
+            // Don't throw - just skip this board (user may have typo or board was deleted)
+        }
     }
-  }
-  return boardMap;
+    return boardMap;
 }
-async function getBoardIds(client, projectKey, boardNames) {
-  const boardMap = await resolveBoardNames(client, projectKey, boardNames);
-  return Array.from(boardMap.values());
+/**
+ * Get board IDs for a list of board names (helper function)
+ *
+ * @param client JiraClient instance
+ * @param projectKey Jira project key
+ * @param boardNames Array of board names
+ * @returns Array of board IDs (skips boards not found)
+ */
+export async function getBoardIds(client, projectKey, boardNames) {
+    const boardMap = await resolveBoardNames(client, projectKey, boardNames);
+    return Array.from(boardMap.values());
 }
-export {
-  fetchBoardsForProject,
-  getBoardIds,
-  resolveBoardNames
-};
+//# sourceMappingURL=jira-board-resolver.js.map

package/plugins/specweave-jira/lib/jira-hierarchical-sync.js

@@ -1,134 +1,206 @@
-import {
-  isSimpleStrategy,
-  isFilteredStrategy,
-  isCustomStrategy
-} from "../../../src/core/types/sync-profile.js";
-import { getBoardIds } from "./jira-board-resolver.js";
-async function buildHierarchicalJQL(client, containers) {
-  const clauses = [];
-  for (const container of containers) {
-    const parts = [];
-    parts.push(`project=${container.id}`);
-    if (container.subOrganizations && container.subOrganizations.length > 0) {
-      try {
-        const boardIds = await getBoardIds(
-          client,
-          container.id,
-          container.subOrganizations
-        );
-        if (boardIds.length > 0) {
-          parts.push(`board IN (${boardIds.join(",")})`);
-        } else {
-          console.warn(
-            `\u26A0\uFE0F  No valid boards found for project ${container.id}, syncing all boards`
-          );
+/**
+ * Jira Hierarchical Sync Implementation
+ *
+ * Supports three sync strategies:
+ * 1. Simple: One project, all boards (backward compatible)
+ * 2. Filtered: Multiple projects + specific boards + filters
+ * 3. Custom: Raw JQL query
+ */
+import { isSimpleStrategy, isFilteredStrategy, isCustomStrategy, } from '../../../src/core/types/sync-profile.js';
+import { getBoardIds } from './jira-board-resolver.js';
+/**
+ * Build hierarchical JQL query from containers
+ *
+ * Example output:
+ * (project=PROJECT-A AND board IN (123, 456) AND labels IN (feature))
+ * OR
+ * (project=PROJECT-B AND board IN (789))
+ *
+ * @param client JiraClient instance
+ * @param containers Array of containers with projects + boards + filters
+ * @returns JQL query string
+ */
+export async function buildHierarchicalJQL(client, containers) {
+    const clauses = [];
+    for (const container of containers) {
+        const parts = [];
+        // Project clause
+        parts.push(`project=${container.id}`);
+        // Board filtering (if sub-organizations specified)
+        if (container.subOrganizations && container.subOrganizations.length > 0) {
+            try {
+                const boardIds = await getBoardIds(client, container.id, container.subOrganizations);
+                if (boardIds.length > 0) {
+                    parts.push(`board IN (${boardIds.join(',')})`);
+                }
+                else {
+                    console.warn(`⚠️  No valid boards found for project ${container.id}, syncing all boards`);
+                }
+            }
+            catch (error) {
+                console.warn(`⚠️  Failed to resolve boards for ${container.id}, syncing all boards:`, error.message);
+            }
         }
-      } catch (error) {
-        console.warn(
-          `\u26A0\uFE0F  Failed to resolve boards for ${container.id}, syncing all boards:`,
-          error.message
-        );
-      }
-    }
-    if (container.filters) {
-      const filterClauses = buildFilterClauses(container.filters);
-      parts.push(...filterClauses);
+        // Filters
+        if (container.filters) {
+            const filterClauses = buildFilterClauses(container.filters);
+            parts.push(...filterClauses);
+        }
+        // Combine parts with AND
+        clauses.push(`(${parts.join(' AND ')})`);
     }
-    clauses.push(`(${parts.join(" AND ")})`);
-  }
-  return clauses.join(" OR ");
+    // Combine clauses with OR
+    return clauses.join(' OR ');
 }
+/**
+ * Build filter clauses from container filters
+ *
+ * @param filters Container filters
+ * @returns Array of JQL filter clauses
+ */
 function buildFilterClauses(filters) {
-  const clauses = [];
-  if (filters.includeLabels && filters.includeLabels.length > 0) {
-    const labels = filters.includeLabels.map((l) => `"${l}"`).join(", ");
-    clauses.push(`labels IN (${labels})`);
-  }
-  if (filters.excludeLabels && filters.excludeLabels.length > 0) {
-    const labels = filters.excludeLabels.map((l) => `"${l}"`).join(", ");
-    clauses.push(`labels NOT IN (${labels})`);
-  }
-  if (filters.assignees && filters.assignees.length > 0) {
-    const assignees = filters.assignees.map((a) => `"${a}"`).join(", ");
-    clauses.push(`assignee IN (${assignees})`);
-  }
-  if (filters.statusCategories && filters.statusCategories.length > 0) {
-    const statuses = filters.statusCategories.map((s) => `"${s}"`).join(", ");
-    clauses.push(`status IN (${statuses})`);
-  }
-  if (filters.components && filters.components.length > 0) {
-    const components = filters.components.map((c) => `"${c}"`).join(", ");
-    clauses.push(`component IN (${components})`);
-  }
-  if (filters.sprints && filters.sprints.length > 0) {
-    const sprints = filters.sprints.map((s) => `"${s}"`).join(", ");
-    clauses.push(`sprint IN (${sprints})`);
-  }
-  if (filters.issueTypes && filters.issueTypes.length > 0) {
-    const types = filters.issueTypes.map((t) => `"${t}"`).join(", ");
-    clauses.push(`issuetype IN (${types})`);
-  }
-  return clauses;
+    const clauses = [];
+    // Include labels
+    if (filters.includeLabels && filters.includeLabels.length > 0) {
+        const labels = filters.includeLabels.map((l) => `"${l}"`).join(', ');
+        clauses.push(`labels IN (${labels})`);
+    }
+    // Exclude labels
+    if (filters.excludeLabels && filters.excludeLabels.length > 0) {
+        const labels = filters.excludeLabels.map((l) => `"${l}"`).join(', ');
+        clauses.push(`labels NOT IN (${labels})`);
+    }
+    // Assignees
+    if (filters.assignees && filters.assignees.length > 0) {
+        const assignees = filters.assignees.map((a) => `"${a}"`).join(', ');
+        clauses.push(`assignee IN (${assignees})`);
+    }
+    // Status categories
+    if (filters.statusCategories && filters.statusCategories.length > 0) {
+        const statuses = filters.statusCategories.map((s) => `"${s}"`).join(', ');
+        clauses.push(`status IN (${statuses})`);
+    }
+    // Components (Jira-specific)
+    if (filters.components && filters.components.length > 0) {
+        const components = filters.components.map((c) => `"${c}"`).join(', ');
+        clauses.push(`component IN (${components})`);
+    }
+    // Sprints (Jira-specific)
+    if (filters.sprints && filters.sprints.length > 0) {
+        const sprints = filters.sprints.map((s) => `"${s}"`).join(', ');
+        clauses.push(`sprint IN (${sprints})`);
+    }
+    // Issue types (Jira-specific)
+    if (filters.issueTypes && filters.issueTypes.length > 0) {
+        const types = filters.issueTypes.map((t) => `"${t}"`).join(', ');
+        clauses.push(`issuetype IN (${types})`);
+    }
+    return clauses;
 }
+/**
+ * Add time range filter to JQL query
+ *
+ * @param jql Base JQL query
+ * @param timeRange Time range preset (1W, 1M, 3M, 6M, ALL)
+ * @returns JQL with time range filter
+ */
 function addTimeRangeFilter(jql, timeRange) {
-  if (timeRange === "ALL") {
-    return jql;
-  }
-  const timeMap = {
-    "1W": "-1w",
-    "2W": "-2w",
-    "1M": "-1M",
-    "3M": "-3M",
-    "6M": "-6M",
-    "1Y": "-1y"
-  };
-  const jiraTime = timeMap[timeRange] || "-1M";
-  return `${jql} AND created >= ${jiraTime}`;
+    if (timeRange === 'ALL') {
+        return jql; // No time filter
+    }
+    // Convert time range to Jira format
+    const timeMap = {
+        '1W': '-1w',
+        '2W': '-2w',
+        '1M': '-1M',
+        '3M': '-3M',
+        '6M': '-6M',
+        '1Y': '-1y',
+    };
+    const jiraTime = timeMap[timeRange] || '-1M';
+    return `${jql} AND created >= ${jiraTime}`;
 }
-async function fetchIssuesHierarchical(client, profile, timeRange = "1M") {
-  const config = profile.config;
-  if (isSimpleStrategy(profile)) {
+/**
+ * Fetch issues hierarchically based on sync strategy
+ *
+ * @param client JiraClient instance
+ * @param profile Sync profile with strategy
+ * @param timeRange Time range preset
+ * @returns Array of Jira issues
+ */
+export async function fetchIssuesHierarchical(client, profile, timeRange = '1M') {
+    const config = profile.config;
+    // Strategy 1: SIMPLE (backward compatible)
+    if (isSimpleStrategy(profile)) {
+        return fetchIssuesSimple(client, config, timeRange);
+    }
+    // Strategy 2: CUSTOM (raw JQL)
+    if (isCustomStrategy(profile)) {
+        return fetchIssuesCustom(client, config, timeRange);
+    }
+    // Strategy 3: FILTERED (hierarchical)
+    if (isFilteredStrategy(profile)) {
+        return fetchIssuesFiltered(client, config, timeRange);
+    }
+    // Default to simple if strategy not recognized
+    console.warn('⚠️  Unknown strategy, defaulting to simple');
     return fetchIssuesSimple(client, config, timeRange);
-  }
-  if (isCustomStrategy(profile)) {
-    return fetchIssuesCustom(client, config, timeRange);
-  }
-  if (isFilteredStrategy(profile)) {
-    return fetchIssuesFiltered(client, config, timeRange);
-  }
-  console.warn("\u26A0\uFE0F  Unknown strategy, defaulting to simple");
-  return fetchIssuesSimple(client, config, timeRange);
 }
+/**
+ * Fetch issues using SIMPLE strategy (one project, all boards)
+ *
+ * @param client JiraClient instance
+ * @param config Jira configuration
+ * @param timeRange Time range preset
+ * @returns Array of Jira issues
+ */
 async function fetchIssuesSimple(client, config, timeRange) {
-  const projectKey = config.projectKey;
-  if (!projectKey) {
-    throw new Error("Simple strategy requires projectKey in config");
-  }
-  let jql = `project=${projectKey}`;
-  jql = addTimeRangeFilter(jql, timeRange);
-  console.log("\u{1F50D} Fetching issues (SIMPLE strategy):", jql);
-  return client.searchIssues({ jql });
+    const projectKey = config.projectKey;
+    if (!projectKey) {
+        throw new Error('Simple strategy requires projectKey in config');
+    }
+    let jql = `project=${projectKey}`;
+    // Add time range
+    jql = addTimeRangeFilter(jql, timeRange);
+    console.log('🔍 Fetching issues (SIMPLE strategy):', jql);
+    return client.searchIssues({ jql });
 }
+/**
+ * Fetch issues using CUSTOM strategy (raw JQL)
+ *
+ * @param client JiraClient instance
+ * @param config Jira configuration
+ * @param timeRange Time range preset
+ * @returns Array of Jira issues
+ */
 async function fetchIssuesCustom(client, config, timeRange) {
-  const customQuery = config.customQuery;
-  if (!customQuery) {
-    throw new Error("Custom strategy requires customQuery in config");
-  }
-  const jql = addTimeRangeFilter(customQuery, timeRange);
-  console.log("\u{1F50D} Fetching issues (CUSTOM strategy):", jql);
-  return client.searchIssues({ jql });
+    const customQuery = config.customQuery;
+    if (!customQuery) {
+        throw new Error('Custom strategy requires customQuery in config');
+    }
+    // Add time range to custom query
+    const jql = addTimeRangeFilter(customQuery, timeRange);
+    console.log('🔍 Fetching issues (CUSTOM strategy):', jql);
+    return client.searchIssues({ jql });
 }
+/**
+ * Fetch issues using FILTERED strategy (multiple projects + boards + filters)
+ *
+ * @param client JiraClient instance
+ * @param config Jira configuration
+ * @param timeRange Time range preset
+ * @returns Array of Jira issues
+ */
 async function fetchIssuesFiltered(client, config, timeRange) {
-  const containers = config.containers;
-  if (!containers || containers.length === 0) {
-    throw new Error("Filtered strategy requires containers array in config");
-  }
-  const baseJql = await buildHierarchicalJQL(client, containers);
-  const jql = addTimeRangeFilter(baseJql, timeRange);
-  console.log("\u{1F50D} Fetching issues (FILTERED strategy):", jql);
-  return client.searchIssues({ jql });
+    const containers = config.containers;
+    if (!containers || containers.length === 0) {
+        throw new Error('Filtered strategy requires containers array in config');
+    }
+    // Build hierarchical JQL
+    const baseJql = await buildHierarchicalJQL(client, containers);
+    // Add time range
+    const jql = addTimeRangeFilter(baseJql, timeRange);
+    console.log('🔍 Fetching issues (FILTERED strategy):', jql);
+    return client.searchIssues({ jql });
 }
-export {
-  buildHierarchicalJQL,
-  fetchIssuesHierarchical
-};
+//# sourceMappingURL=jira-hierarchical-sync.js.map

package/plugins/specweave-jira/lib/jira-multi-project-sync.js

@@ -1,5 +1,6 @@
 import { JiraClient } from "../../../src/integrations/jira/jira-client.js";
 import {
+  getPrimaryProject,
   suggestJiraItemType,
   mapUserStoryToProjects
 } from "../../../src/utils/project-mapper.js";
@@ -13,6 +14,25 @@ class JiraMultiProjectSync {
       apiToken: config.apiToken
     });
   }
+  /**
+   * Pre-flight validation: Verify all JIRA projects exist
+   *
+   * @throws Error if any projects are missing
+   */
+  async validateProjects() {
+    if (!this.config.projects || this.config.projects.length === 0) {
+      throw new Error("No JIRA projects configured for validation");
+    }
+    const missing = await validateJiraProjects(this.client, this.config.projects);
+    if (missing.length > 0) {
+      throw new Error(
+        `\u274C Pre-flight check failed: Missing JIRA projects:
+` + missing.map((p) => `  - ${p} (${this.config.domain})`).join("\n") + `
+
+Please verify project keys and access permissions.`
+      );
+    }
+  }
   /**
    * Sync spec to JIRA projects with intelligent mapping
    *
@@ -21,6 +41,7 @@ class JiraMultiProjectSync {
    */
   async syncSpec(specPath) {
     const results = [];
+    await this.validateProjects();
     const parsedSpec = await parseSpecFile(specPath);
     const epicsByProject = /* @__PURE__ */ new Map();
     if (this.config.autoCreateEpics !== false) {
@@ -33,14 +54,18 @@ class JiraMultiProjectSync {
     const projectStories = /* @__PURE__ */ new Map();
     for (const userStory of parsedSpec.userStories) {
       if (this.config.intelligentMapping !== false) {
-        const mappings = mapUserStoryToProjects(userStory);
-        if (mappings.length > 0 && mappings[0].confidence >= 0.3) {
-          const primary = mappings[0];
+        const mapperConfig = {
+          confidenceThreshold: this.config.confidenceThreshold
+        };
+        const primary = getPrimaryProject(userStory, void 0, mapperConfig);
+        if (primary) {
           const existing = projectStories.get(primary.projectId) || [];
           existing.push({ story: userStory, confidence: primary.confidence });
           projectStories.set(primary.projectId, existing);
         } else {
-          console.warn(`\u26A0\uFE0F  Low confidence for ${userStory.id} (${(mappings[0]?.confidence || 0) * 100}%) - assigning to ${this.config.projects[0]}`);
+          const mappings = mapUserStoryToProjects(userStory);
+          const threshold = this.config.confidenceThreshold ?? 0.3;
+          console.warn(`\u26A0\uFE0F  Low confidence for ${userStory.id} (${(mappings[0]?.confidence || 0) * 100}% < ${threshold * 100}% threshold) - assigning to ${this.config.projects[0]}`);
           const fallback = this.config.projects[0];
           const existing = projectStories.get(fallback) || [];
           existing.push({ story: userStory, confidence: mappings[0]?.confidence || 0 });
@@ -78,7 +103,7 @@ class JiraMultiProjectSync {
 
 *Status*: ${parsedSpec.metadata.status}
 *Priority*: ${parsedSpec.metadata.priority}
-*Estimated Effort*: ${parsedSpec.metadata.estimatedEffort || parsedSpec.metadata.estimated_effort}
+*Estimated Effort*: ${parsedSpec.metadata.estimatedEffort || "TBD"}
 
 h3. Executive Summary
 

package/plugins/specweave-jira/lib/jira-multi-project-sync.ts

@@ -71,6 +71,28 @@ export class JiraMultiProjectSync {
     });
   }
 
+  /**
+   * Pre-flight validation: Verify all JIRA projects exist
+   *
+   * @throws Error if any projects are missing
+   */
+  async validateProjects(): Promise<void> {
+    if (!this.config.projects || this.config.projects.length === 0) {
+      throw new Error('No JIRA projects configured for validation');
+    }
+
+    // Validate projects exist
+    const missing = await validateJiraProjects(this.client, this.config.projects);
+
+    if (missing.length > 0) {
+      throw new Error(
+        `❌ Pre-flight check failed: Missing JIRA projects:\n` +
+        missing.map(p => `  - ${p} (${this.config.domain})`).join('\n') +
+        `\n\nPlease verify project keys and access permissions.`
+      );
+    }
+  }
+
   /**
    * Sync spec to JIRA projects with intelligent mapping
    *
@@ -80,6 +102,9 @@ export class JiraMultiProjectSync {
   async syncSpec(specPath: string): Promise<JiraSyncResult[]> {
     const results: JiraSyncResult[] = [];
 
+    // Pre-flight validation: Verify all projects exist
+    await this.validateProjects();
+
     // Parse spec
     const parsedSpec = await parseSpecFile(specPath);
 
@@ -100,16 +125,20 @@ export class JiraMultiProjectSync {
     for (const userStory of parsedSpec.userStories) {
       if (this.config.intelligentMapping !== false) {
         // Intelligent mapping (default)
-        const mappings = mapUserStoryToProjects(userStory);
+        const mapperConfig = {
+          confidenceThreshold: this.config.confidenceThreshold
+        };
+        const primary = getPrimaryProject(userStory, undefined, mapperConfig);
 
-        if (mappings.length > 0 && mappings[0].confidence >= 0.3) {
-          const primary = mappings[0];
+        if (primary) {
           const existing = projectStories.get(primary.projectId) || [];
           existing.push({ story: userStory, confidence: primary.confidence });
           projectStories.set(primary.projectId, existing);
         } else {
           // No confident match - assign to first project or skip
-          console.warn(`⚠️  Low confidence for ${userStory.id} (${(mappings[0]?.confidence || 0) * 100}%) - assigning to ${this.config.projects[0]}`);
+          const mappings = mapUserStoryToProjects(userStory);
+          const threshold = this.config.confidenceThreshold ?? 0.3;
+          console.warn(`⚠️  Low confidence for ${userStory.id} (${(mappings[0]?.confidence || 0) * 100}% < ${threshold * 100}% threshold) - assigning to ${this.config.projects[0]}`);
           const fallback = this.config.projects[0];
           const existing = projectStories.get(fallback) || [];
           existing.push({ story: userStory, confidence: mappings[0]?.confidence || 0 });
@@ -156,7 +185,7 @@ export class JiraMultiProjectSync {
 
 *Status*: ${parsedSpec.metadata.status}
 *Priority*: ${parsedSpec.metadata.priority}
-*Estimated Effort*: ${parsedSpec.metadata.estimatedEffort || parsedSpec.metadata.estimated_effort}
+*Estimated Effort*: ${parsedSpec.metadata.estimatedEffort || 'TBD'}
 
 h3. Executive Summary