specweave 1.0.506 → 1.0.508

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

@@ -0,0 +1,398 @@
+/**
+ * JIRA Multi-Project Sync with Intelligent Mapping
+ *
+ * Automatically maps user stories to JIRA projects based on content analysis:
+ * - FE user stories → JIRA Project FE
+ * - BE user stories → JIRA Project BE
+ * - MOBILE user stories → JIRA Project MOBILE
+ *
+ * Supports hierarchical issue types:
+ * - Epic (> 13 story points): Large feature area
+ * - Story (3-13 story points): Standard user story
+ * - Task (1-2 story points): Small implementation task
+ * - Subtask (< 1 story point): Granular work item
+ *
+ * @module jira-multi-project-sync
+ */
+
+import { JiraClient, JiraIssue } from '../../../../../src/integrations/jira/jira-client.js';
+import {
+  UserStory,
+  getPrimaryProject,
+  suggestJiraItemType,
+  mapUserStoryToProjects
+} from '../../../../../src/utils/project-mapper.js';
+import { parseSpecFile } from '../../../../../src/utils/spec-splitter.js';
+import { getEpicLinkFieldForProject } from './jira-field-discovery.js';
+
+export interface JiraMultiProjectConfig {
+  domain: string;
+  email: string;
+  apiToken: string;
+
+  // Simple: List of JIRA projects
+  projects: string[];  // ['FE', 'BE', 'MOBILE']
+
+  // Item type mapping (optional)
+  itemTypeMapping?: {
+    epic: string;    // Default: 'Epic'
+    story: string;   // Default: 'Story'
+    task: string;    // Default: 'Task'
+    subtask: string; // Default: 'Sub-task'
+  };
+
+  // Settings
+  intelligentMapping?: boolean;  // Default: true (auto-classify user stories)
+  autoCreateEpics?: boolean;     // Default: true (create epic per project)
+}
+
+export interface JiraSyncResult {
+  project: string;
+  issueKey: string;
+  issueType: string;
+  summary: string;
+  url: string;
+  action: 'created' | 'updated' | 'skipped';
+  confidence?: number;  // Classification confidence (0.0-1.0)
+}
+
+/**
+ * JIRA Multi-Project Sync Client
+ */
+export class JiraMultiProjectSync {
+  private client: JiraClient;
+  private config: JiraMultiProjectConfig;
+
+  constructor(config: JiraMultiProjectConfig) {
+    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(): 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
+   *
+   * @param specPath Path to spec file
+   * @returns Array of sync results
+   */
+  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);
+
+    // Step 1: Classify user stories by project FIRST (before creating epics)
+    const projectStories = new Map<string, Array<{ story: UserStory; confidence: number }>>();
+
+    for (const userStory of parsedSpec.userStories) {
+      if (this.config.intelligentMapping !== false) {
+        // Intelligent mapping (default)
+        const mapperConfig = {
+          confidenceThreshold: this.config.confidenceThreshold
+        };
+        const primary = getPrimaryProject(userStory, undefined, mapperConfig);
+
+        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
+          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 });
+          projectStories.set(fallback, existing);
+        }
+      } else {
+        // Manual mapping (user specified project in frontmatter)
+        const projectHint = this.extractProjectHint(userStory);
+
+        if (projectHint && this.config.projects.includes(projectHint)) {
+          const existing = projectStories.get(projectHint) || [];
+          existing.push({ story: userStory, confidence: 1.0 });
+          projectStories.set(projectHint, existing);
+        } else {
+          // No hint - assign to first project
+          const fallback = this.config.projects[0];
+          const existing = projectStories.get(fallback) || [];
+          existing.push({ story: userStory, confidence: 0 });
+          projectStories.set(fallback, existing);
+        }
+      }
+    }
+
+    // Step 2: Create epics ONLY for projects that have classified stories
+    const epicsByProject = new Map<string, string>();  // projectId → epicKey
+
+    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);
+      }
+    }
+
+    // Step 3: Create issues in each project
+    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
+   */
+  private async createEpicForProject(parsedSpec: any, projectId: string): Promise<JiraSyncResult> {
+    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.
+
+---
+
+🤖 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
+   */
+  private async createIssueForUserStory(
+    projectId: string,
+    userStory: UserStory,
+    epicKey?: string,
+    confidence?: number
+  ): Promise<JiraSyncResult> {
+    const summary = `${userStory.id}: ${userStory.title}`;
+
+    // Determine issue type based on story points
+    const itemType = suggestJiraItemType(userStory);
+
+    const description = `h3. ${userStory.title}
+
+${userStory.description}
+
+h4. Acceptance Criteria
+
+${userStory.acceptanceCriteria.map((ac, i) => `* ${ac}`).join('\n')}
+
+${userStory.technicalContext ? `\nh4. Technical Context\n\n${userStory.technicalContext}\n` : ''}
+
+${confidence !== undefined ? `\n_Classification confidence: ${(confidence * 100).toFixed(0)}%_\n` : ''}
+
+🤖 Auto-generated by SpecWeave
+`;
+
+    const issueData: any = {
+      project: { key: projectId },
+      summary,
+      description,
+      issuetype: { name: this.getIssueTypeName(itemType) }
+    };
+
+    // Link to epic using dynamic field discovery
+    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
+   */
+  private getIssueTypeName(itemType: 'Epic' | 'Story' | 'Task' | 'Subtask'): string {
+    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"
+   */
+  private extractProjectHint(userStory: UserStory): string | undefined {
+    // Check title for [PROJECT] prefix
+    const titleMatch = userStory.title.match(/^\[([A-Z]+)\]/);
+    if (titleMatch) {
+      return titleMatch[1];
+    }
+
+    // Check description for "Project: XXX"
+    const descMatch = userStory.description.match(/Project:\s*([A-Z]+)/i);
+    if (descMatch) {
+      return descMatch[1].toUpperCase();
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Format JIRA sync results for display
+ */
+export function formatJiraSyncResults(results: JiraSyncResult[]): string {
+  const lines: string[] = [];
+
+  lines.push('📊 JIRA Multi-Project Sync Results:\n');
+
+  const byProject = new Map<string, JiraSyncResult[]>();
+
+  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(`\n**JIRA Project ${project}**:`);
+
+    for (const result of projectResults) {
+      const icon = result.action === 'created' ? '✅' : result.action === 'updated' ? '🔄' : '⏭️';
+      const confidence = result.confidence !== undefined ? ` (${(result.confidence * 100).toFixed(0)}% confidence)` : '';
+      lines.push(`  ${icon} ${result.issueKey} [${result.issueType}]: ${result.summary}${confidence}`);
+      lines.push(`     ${result.url}`);
+    }
+  }
+
+  lines.push(`\n✅ Total: ${results.length} issues synced\n`);
+
+  // Show classification summary
+  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('📈 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');
+}
+
+/**
+ * Validate JIRA projects exist
+ *
+ * @param client JIRA client
+ * @param projectKeys Array of project keys to validate
+ * @returns Validation results (missing projects)
+ */
+export async function validateJiraProjects(
+  client: JiraClient,
+  projectKeys: string[]
+): Promise<string[]> {
+  const missing: string[] = [];
+
+  for (const key of projectKeys) {
+    try {
+      await client.getProject(key);
+    } catch (error) {
+      missing.push(key);
+    }
+  }
+
+  return missing;
+}

package/plugins/specweave/lib/integrations/jira/jira-spec-commit-sync.d.ts

@@ -0,0 +1,43 @@
+/**
+ * JIRA Spec Commit Sync
+ *
+ * Posts commit/PR comments to JIRA issues linked to living docs specs.
+ * This enables traceability from spec user stories to actual code changes.
+ */
+import { GitCommit, GitRepository } from '../../../../../src/utils/git-utils.js';
+import { UserStory } from '../../../../../src/core/specs/spec-task-mapper.js';
+export interface JiraConfig {
+    domain: string;
+    email: string;
+    apiToken: string;
+    projectKey: string;
+}
+export interface SyncOptions {
+    incrementPath: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export interface SyncResult {
+    success: boolean;
+    commentsPosted: number;
+    errors: string[];
+    commits: GitCommit[];
+    userStories: UserStory[];
+}
+/**
+ * Sync commits for completed user stories to JIRA epic/story
+ */
+export declare function syncSpecCommitsToJira(config: JiraConfig, options: SyncOptions): Promise<SyncResult>;
+/**
+ * Post batch commit update to JIRA issue
+ */
+export declare function postCommitBatchUpdate(config: JiraConfig, incrementPath: string, commits: GitCommit[], issueKey: string, repo: GitRepository, dryRun?: boolean): Promise<boolean>;
+/**
+ * Check if spec commit sync is enabled in config
+ */
+export declare function isSpecCommitSyncEnabled(projectRoot: string): Promise<boolean>;
+/**
+ * Get JIRA issue key from spec metadata
+ */
+export declare function getJiraIssueForSpec(specPath: string): Promise<string | null>;
+//# sourceMappingURL=jira-spec-commit-sync.d.ts.map

package/plugins/specweave/lib/integrations/jira/jira-spec-commit-sync.js

@@ -0,0 +1,262 @@
+import axios from "axios";
+import {
+  getRecentCommits,
+  detectRepository,
+  getCommitUrl,
+  findPRForCommit,
+  getLastSyncCommit,
+  updateLastSyncCommit
+} from "../../../../../src/utils/git-utils.js";
+import {
+  getSpecTaskMapping,
+  getCompletedUserStories
+} from "../../../../../src/core/specs/spec-task-mapper.js";
+import {
+  buildUserStoryComment,
+  buildCommitBatchComment,
+  buildShortComment,
+  generateSmartSummary,
+  formatForJira
+} from "../../../../../src/core/comment-builder.js";
+import { readIssueKey } from "./metadata-paths.js";
+import { getApiBaseUrl } from "./jira-deployment-detector.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecCommitsToJira(config, options) {
+  const { incrementPath, dryRun = false, verbose = false } = options;
+  const result = {
+    success: true,
+    commentsPosted: 0,
+    errors: [],
+    commits: [],
+    userStories: []
+  };
+  try {
+    const metadataPath = path.join(incrementPath, "metadata.json");
+    let metadata;
+    try {
+      metadata = JSON.parse(await fs.readFile(metadataPath, "utf-8"));
+    } catch {
+      result.errors.push("No metadata.json found");
+      return result;
+    }
+    const jiraIssueKey = readIssueKey(metadata);
+    if (!jiraIssueKey) {
+      if (verbose) {
+        console.log("No JIRA issue linked to increment");
+      }
+      return result;
+    }
+    const client = axios.create({
+      baseURL: getApiBaseUrl(config.domain),
+      auth: {
+        username: config.email,
+        password: config.apiToken
+      },
+      headers: {
+        "Accept": "application/json",
+        "Content-Type": "application/json"
+      }
+    });
+    const repo = await detectRepository("origin", incrementPath);
+    if (!repo) {
+      result.errors.push("Git repository not found");
+      result.success = false;
+      return result;
+    }
+    const mapping = await getSpecTaskMapping(incrementPath);
+    if (!mapping) {
+      if (verbose) {
+        console.log("No spec mapping found for increment");
+      }
+      return result;
+    }
+    const completedUserStories = getCompletedUserStories(mapping);
+    if (completedUserStories.length === 0) {
+      if (verbose) {
+        console.log("No completed user stories");
+      }
+      return result;
+    }
+    result.userStories = completedUserStories;
+    const lastSyncCommit = await getLastSyncCommit(metadataPath);
+    const commits = lastSyncCommit ? await getRecentCommits(void 0, lastSyncCommit, incrementPath) : await getRecentCommits("7.days", void 0, incrementPath);
+    if (commits.length === 0) {
+      if (verbose) {
+        console.log("No new commits since last sync");
+      }
+      return result;
+    }
+    result.commits = commits;
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+    for (const userStory of completedUserStories) {
+      try {
+        const relatedTasks = mapping.tasks.filter(
+          (t) => t.userStories.includes(userStory.id)
+        );
+        const pullRequests = [];
+        if (repo.provider === "github") {
+          for (const commit of commits.slice(0, 3)) {
+            const pr = await findPRForCommit(commit.sha, repo.owner, repo.repo);
+            if (pr && !pullRequests.find((p) => p.number === pr.number)) {
+              pullRequests.push(pr);
+            }
+          }
+        }
+        const summary = generateSmartSummary(commits, relatedTasks);
+        const commentContent = {
+          userStory,
+          tasks: relatedTasks,
+          commits,
+          pullRequests,
+          summary
+        };
+        const formattedComment = buildUserStoryComment(commentContent, repo);
+        const jiraComment = formatForJira(formattedComment);
+        if (verbose) {
+          console.log(`
+Comment for ${userStory.id} (JIRA format):`);
+          console.log(jiraComment);
+          console.log("\n---\n");
+        }
+        if (!dryRun) {
+          await client.post(`/issue/${jiraIssueKey}/comment`, {
+            body: {
+              type: "doc",
+              version: 1,
+              content: [
+                {
+                  type: "paragraph",
+                  content: [
+                    {
+                      type: "text",
+                      text: jiraComment
+                    }
+                  ]
+                }
+              ]
+            }
+          });
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error) {
+        result.errors.push(`Failed to post comment for ${userStory.id}: ${error.message}`);
+      }
+    }
+    if (completedUserStories.length === 0 && commits.length > 0) {
+      try {
+        const summary = `Work in progress: ${commits.length} commit${commits.length > 1 ? "s" : ""}`;
+        const formattedComment = buildShortComment(commits, repo, summary);
+        const jiraComment = formatForJira(formattedComment);
+        if (verbose) {
+          console.log(`
+Short update comment (JIRA format):`);
+          console.log(jiraComment);
+          console.log("\n---\n");
+        }
+        if (!dryRun) {
+          await client.post(`/issue/${jiraIssueKey}/comment`, {
+            body: {
+              type: "doc",
+              version: 1,
+              content: [
+                {
+                  type: "paragraph",
+                  content: [
+                    {
+                      type: "text",
+                      text: jiraComment
+                    }
+                  ]
+                }
+              ]
+            }
+          });
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error) {
+        result.errors.push(`Failed to post short update: ${error.message}`);
+      }
+    }
+    if (!dryRun && commits.length > 0) {
+      await updateLastSyncCommit(metadataPath, commits[0].sha);
+    }
+  } catch (error) {
+    result.success = false;
+    result.errors.push(error.message);
+  }
+  return result;
+}
+async function postCommitBatchUpdate(config, incrementPath, commits, issueKey, repo, dryRun = false) {
+  try {
+    const client = axios.create({
+      baseURL: getApiBaseUrl(config.domain),
+      auth: {
+        username: config.email,
+        password: config.apiToken
+      },
+      headers: {
+        "Accept": "application/json",
+        "Content-Type": "application/json"
+      }
+    });
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+    const formattedComment = buildCommitBatchComment(commits, repo, true);
+    const jiraComment = formatForJira(formattedComment);
+    if (!dryRun) {
+      await client.post(`/issue/${issueKey}/comment`, {
+        body: {
+          type: "doc",
+          version: 1,
+          content: [
+            {
+              type: "paragraph",
+              content: [
+                {
+                  type: "text",
+                  text: jiraComment
+                }
+              ]
+            }
+          ]
+        }
+      });
+    }
+    return true;
+  } catch (error) {
+    console.error(`Failed to post batch update: ${error.message}`);
+    return false;
+  }
+}
+async function isSpecCommitSyncEnabled(projectRoot) {
+  try {
+    const configPath = path.join(projectRoot, ".specweave", "config.json");
+    const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+    return config.sync?.settings?.postCommitComments !== false;
+  } catch {
+    return true;
+  }
+}
+async function getJiraIssueForSpec(specPath) {
+  try {
+    const content = await fs.readFile(specPath, "utf-8");
+    const match = content.match(/\*\*JIRA Epic\*\*:\s*([A-Z]+-\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  getJiraIssueForSpec,
+  isSpecCommitSyncEnabled,
+  postCommitBatchUpdate,
+  syncSpecCommitsToJira
+};