specweave 1.0.506 → 1.0.508

package/plugins/specweave/lib/integrations/jira/jira-hierarchical-sync.ts

@@ -0,0 +1,294 @@
+/**
+ * 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 {
+  SyncProfile,
+  SyncContainer,
+  JiraConfig,
+  isSimpleStrategy,
+  isFilteredStrategy,
+  isCustomStrategy,
+} from '../../../../../src/core/types/sync-profile.js';
+import { JiraClient, JiraIssue } from '../../../../../src/integrations/jira/jira-client.js';
+import { getBoardIds } from './jira-board-resolver.js';
+import { searchAllIssues } from './jira-paginated-search.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: JiraClient,
+  containers: SyncContainer[]
+): Promise<string> {
+  const clauses: string[] = [];
+
+  for (const container of containers) {
+    const parts: string[] = [];
+
+    // 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 as Error).message
+        );
+      }
+    }
+
+    // Filters
+    if (container.filters) {
+      const filterClauses = buildFilterClauses(container.filters);
+      parts.push(...filterClauses);
+    }
+
+    // Combine parts with AND
+    clauses.push(`(${parts.join(' AND ')})`);
+  }
+
+  // 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: any): string[] {
+  const clauses: string[] = [];
+
+  // Include labels
+  if (filters.includeLabels && filters.includeLabels.length > 0) {
+    const labels = filters.includeLabels.map((l: string) => `"${l}"`).join(', ');
+    clauses.push(`labels IN (${labels})`);
+  }
+
+  // Exclude labels
+  if (filters.excludeLabels && filters.excludeLabels.length > 0) {
+    const labels = filters.excludeLabels.map((l: string) => `"${l}"`).join(', ');
+    clauses.push(`labels NOT IN (${labels})`);
+  }
+
+  // Assignees
+  if (filters.assignees && filters.assignees.length > 0) {
+    const assignees = filters.assignees.map((a: string) => `"${a}"`).join(', ');
+    clauses.push(`assignee IN (${assignees})`);
+  }
+
+  // Status categories
+  if (filters.statusCategories && filters.statusCategories.length > 0) {
+    const statuses = filters.statusCategories.map((s: string) => `"${s}"`).join(', ');
+    clauses.push(`status IN (${statuses})`);
+  }
+
+  // Components (Jira-specific)
+  if (filters.components && filters.components.length > 0) {
+    const components = filters.components.map((c: string) => `"${c}"`).join(', ');
+    clauses.push(`component IN (${components})`);
+  }
+
+  // Sprints (Jira-specific)
+  if (filters.sprints && filters.sprints.length > 0) {
+    const sprints = filters.sprints.map((s: string) => `"${s}"`).join(', ');
+    clauses.push(`sprint IN (${sprints})`);
+  }
+
+  // Issue types (Jira-specific)
+  if (filters.issueTypes && filters.issueTypes.length > 0) {
+    const types = filters.issueTypes.map((t: string) => `"${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: string, timeRange: string): string {
+  if (timeRange === 'ALL') {
+    return jql; // No time filter
+  }
+
+  // Convert time range to Jira format
+  const timeMap: Record<string, string> = {
+    '1W': '-1w',
+    '2W': '-2w',
+    '1M': '-1M',
+    '3M': '-3M',
+    '6M': '-6M',
+    '1Y': '-1y',
+  };
+
+  const jiraTime = timeMap[timeRange] || '-1M';
+
+  return `${jql} AND created >= ${jiraTime}`;
+}
+
+/**
+ * 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: JiraClient,
+  profile: SyncProfile,
+  timeRange: string = '1M'
+): Promise<JiraIssue[]> {
+  const config = profile.config as JiraConfig;
+
+  // 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);
+}
+
+/**
+ * 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: JiraClient,
+  config: JiraConfig,
+  timeRange: string
+): Promise<JiraIssue[]> {
+  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);
+
+  // Use paginated search if client exposes axios instance, otherwise fallback
+  if (typeof (client as any).getAxiosClient === 'function') {
+    return searchAllIssues((client as any).getAxiosClient(), { 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: JiraClient,
+  config: JiraConfig,
+  timeRange: string
+): Promise<JiraIssue[]> {
+  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);
+
+  if (typeof (client as any).getAxiosClient === 'function') {
+    return searchAllIssues((client as any).getAxiosClient(), { 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: JiraClient,
+  config: JiraConfig,
+  timeRange: string
+): Promise<JiraIssue[]> {
+  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);
+
+  if (typeof (client as any).getAxiosClient === 'function') {
+    return searchAllIssues((client as any).getAxiosClient(), { jql });
+  }
+  return client.searchIssues({ jql });
+}

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

@@ -0,0 +1,279 @@
+import { JiraClient } from "../../../../../src/integrations/jira/jira-client.js";
+import {
+  getPrimaryProject,
+  suggestJiraItemType,
+  mapUserStoryToProjects
+} from "../../../../../src/utils/project-mapper.js";
+import { parseSpecFile } from "../../../../../src/utils/spec-splitter.js";
+import { getEpicLinkFieldForProject } from "./jira-field-discovery.js";
+class JiraMultiProjectSync {
+  constructor(config) {
+    this.config = config;
+    this.client = new JiraClient({
+      domain: config.domain,
+      email: config.email,
+      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
+   *
+   * @param specPath Path to spec file
+   * @returns Array of sync results
+   */
+  async syncSpec(specPath) {
+    const results = [];
+    await this.validateProjects();
+    const parsedSpec = await parseSpecFile(specPath);
+    const projectStories = /* @__PURE__ */ new Map();
+    for (const userStory of parsedSpec.userStories) {
+      if (this.config.intelligentMapping !== false) {
+        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 {
+          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 });
+          projectStories.set(fallback, existing);
+        }
+      } else {
+        const projectHint = this.extractProjectHint(userStory);
+        if (projectHint && this.config.projects.includes(projectHint)) {
+          const existing = projectStories.get(projectHint) || [];
+          existing.push({ story: userStory, confidence: 1 });
+          projectStories.set(projectHint, existing);
+        } else {
+          const fallback = this.config.projects[0];
+          const existing = projectStories.get(fallback) || [];
+          existing.push({ story: userStory, confidence: 0 });
+          projectStories.set(fallback, existing);
+        }
+      }
+    }
+    const epicsByProject = /* @__PURE__ */ new Map();
+    if (this.config.autoCreateEpics !== false) {
+      for (const projectId of projectStories.keys()) {
+        const epicResult = await this.createEpicForProject(parsedSpec, projectId);
+        epicsByProject.set(projectId, epicResult.issueKey);
+        results.push(epicResult);
+      }
+    }
+    for (const [projectId, stories] of projectStories.entries()) {
+      const epicKey = epicsByProject.get(projectId);
+      for (const { story, confidence } of stories) {
+        const result = await this.createIssueForUserStory(projectId, story, epicKey, confidence);
+        results.push(result);
+      }
+    }
+    return results;
+  }
+  /**
+   * Create epic for project
+   */
+  async createEpicForProject(parsedSpec, projectId) {
+    const summary = `${parsedSpec.metadata.title} - ${projectId}`;
+    const description = `h2. ${projectId} Implementation
+
+*Status*: ${parsedSpec.metadata.status}
+*Priority*: ${parsedSpec.metadata.priority}
+*Estimated Effort*: ${parsedSpec.metadata.estimatedEffort || "TBD"}
+
+h3. Executive Summary
+
+${parsedSpec.executiveSummary}
+
+h3. Scope (${projectId})
+
+This epic covers all ${projectId}-related user stories for "${parsedSpec.metadata.title}".
+
+User stories will be added as child issues.
+
+---
+
+\u{1F916} Auto-generated by SpecWeave
+`;
+    const issue = await this.client.createIssue({
+      project: { key: projectId },
+      summary,
+      description,
+      issuetype: { name: this.config.itemTypeMapping?.epic || "Epic" }
+    });
+    return {
+      project: projectId,
+      issueKey: issue.key,
+      issueType: "Epic",
+      summary,
+      url: `https://${this.config.domain}/browse/${issue.key}`,
+      action: "created"
+    };
+  }
+  /**
+   * Create issue for user story
+   */
+  async createIssueForUserStory(projectId, userStory, epicKey, confidence) {
+    const summary = `${userStory.id}: ${userStory.title}`;
+    const itemType = suggestJiraItemType(userStory);
+    const description = `h3. ${userStory.title}
+
+${userStory.description}
+
+h4. Acceptance Criteria
+
+${userStory.acceptanceCriteria.map((ac, i) => `* ${ac}`).join("\n")}
+
+${userStory.technicalContext ? `
+h4. Technical Context
+
+${userStory.technicalContext}
+` : ""}
+
+${confidence !== void 0 ? `
+_Classification confidence: ${(confidence * 100).toFixed(0)}%_
+` : ""}
+
+\u{1F916} Auto-generated by SpecWeave
+`;
+    const issueData = {
+      project: { key: projectId },
+      summary,
+      description,
+      issuetype: { name: this.getIssueTypeName(itemType) }
+    };
+    if (epicKey) {
+      const { field: epicField, style } = await getEpicLinkFieldForProject(
+        this.config.domain,
+        projectId,
+        { email: this.config.email, apiToken: this.config.apiToken }
+      );
+      if (style === "next-gen") {
+        issueData.parent = { key: epicKey };
+      } else {
+        issueData[epicField] = epicKey;
+      }
+    }
+    const issue = await this.client.createIssue(issueData);
+    return {
+      project: projectId,
+      issueKey: issue.key,
+      issueType: itemType,
+      summary,
+      url: `https://${this.config.domain}/browse/${issue.key}`,
+      action: "created",
+      confidence
+    };
+  }
+  /**
+   * Get JIRA issue type name from suggested type
+   */
+  getIssueTypeName(itemType) {
+    const mapping = this.config.itemTypeMapping || {};
+    switch (itemType) {
+      case "Epic":
+        return mapping.epic || "Epic";
+      case "Story":
+        return mapping.story || "Story";
+      case "Task":
+        return mapping.task || "Task";
+      case "Subtask":
+        return mapping.subtask || "Sub-task";
+      default:
+        return "Story";
+    }
+  }
+  /**
+   * Extract project hint from user story (manual override)
+   *
+   * Looks for hints like:
+   * - Title: "[FE] Login UI"
+   * - Description: "Project: FE"
+   * - Technical context: "Frontend: React"
+   */
+  extractProjectHint(userStory) {
+    const titleMatch = userStory.title.match(/^\[([A-Z]+)\]/);
+    if (titleMatch) {
+      return titleMatch[1];
+    }
+    const descMatch = userStory.description.match(/Project:\s*([A-Z]+)/i);
+    if (descMatch) {
+      return descMatch[1].toUpperCase();
+    }
+    return void 0;
+  }
+}
+function formatJiraSyncResults(results) {
+  const lines = [];
+  lines.push("\u{1F4CA} JIRA Multi-Project Sync Results:\n");
+  const byProject = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    const existing = byProject.get(result.project) || [];
+    existing.push(result);
+    byProject.set(result.project, existing);
+  }
+  for (const [project, projectResults] of byProject.entries()) {
+    lines.push(`
+**JIRA Project ${project}**:`);
+    for (const result of projectResults) {
+      const icon = result.action === "created" ? "\u2705" : result.action === "updated" ? "\u{1F504}" : "\u23ED\uFE0F";
+      const confidence = result.confidence !== void 0 ? ` (${(result.confidence * 100).toFixed(0)}% confidence)` : "";
+      lines.push(`  ${icon} ${result.issueKey} [${result.issueType}]: ${result.summary}${confidence}`);
+      lines.push(`     ${result.url}`);
+    }
+  }
+  lines.push(`
+\u2705 Total: ${results.length} issues synced
+`);
+  const epicCount = results.filter((r) => r.issueType === "Epic").length;
+  const storyCount = results.filter((r) => r.issueType === "Story").length;
+  const taskCount = results.filter((r) => r.issueType === "Task").length;
+  const subtaskCount = results.filter((r) => r.issueType === "Subtask").length;
+  lines.push("\u{1F4C8} Item Type Distribution:");
+  if (epicCount > 0) lines.push(`  - Epics: ${epicCount}`);
+  if (storyCount > 0) lines.push(`  - Stories: ${storyCount}`);
+  if (taskCount > 0) lines.push(`  - Tasks: ${taskCount}`);
+  if (subtaskCount > 0) lines.push(`  - Subtasks: ${subtaskCount}`);
+  return lines.join("\n");
+}
+async function validateJiraProjects(client, projectKeys) {
+  const missing = [];
+  for (const key of projectKeys) {
+    try {
+      await client.getProject(key);
+    } catch (error) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
+export {
+  JiraMultiProjectSync,
+  formatJiraSyncResults,
+  validateJiraProjects
+};