specweave 0.13.6 → 0.14.0

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

@@ -0,0 +1,461 @@
+/**
+ * GitHub Multi-Project Sync
+ *
+ * Supports two patterns:
+ * 1. **Multiple Repos**: Separate repos for each project (FE, BE, MOBILE)
+ * 2. **Master + Nested**: Master repo (epics) + nested repos (detailed tasks)
+ *
+ * @module github-multi-project-sync
+ */
+
+import { Octokit } from '@octokit/rest';
+import { UserStory, getPrimaryProject, ProjectMapping } from '../../../src/utils/project-mapper.js';
+import { parseSpecFile } from '../../../src/utils/spec-splitter.js';
+
+export interface GitHubMultiProjectConfig {
+  owner: string;
+  token: string;
+
+  // Pattern 1: Multiple repos (simple)
+  repos?: string[];  // ['frontend-web', 'backend-api', 'mobile-app']
+
+  // Pattern 2: Master + nested repos (advanced)
+  masterRepo?: string;  // 'master-project' (high-level epics)
+  nestedRepos?: string[];  // ['frontend-web', 'backend-api', 'mobile-app'] (detailed tasks)
+
+  // Settings
+  masterRepoLevel?: 'epic';  // Master repo contains epics
+  nestedRepoLevel?: 'story-task';  // Nested repos contain stories/tasks
+  crossLinking?: boolean;  // Enable epic → issue links
+}
+
+export interface GitHubIssue {
+  number: number;
+  title: string;
+  body: string;
+  state: 'open' | 'closed';
+  html_url: string;
+  labels: Array<{ name: string }>;
+}
+
+export interface SyncResult {
+  project: string;
+  repo: string;
+  issueNumber: number;
+  url: string;
+  action: 'created' | 'updated' | 'skipped';
+}
+
+/**
+ * GitHub Multi-Project Sync Client
+ */
+export class GitHubMultiProjectSync {
+  private octokit: Octokit;
+  private config: GitHubMultiProjectConfig;
+
+  constructor(config: GitHubMultiProjectConfig) {
+    this.config = config;
+    this.octokit = new Octokit({ auth: config.token });
+  }
+
+  /**
+   * Sync spec to appropriate GitHub repos based on project mapping
+   *
+   * @param specPath Path to spec file
+   * @returns Array of sync results
+   */
+  async syncSpec(specPath: string): Promise<SyncResult[]> {
+    const results: SyncResult[] = [];
+
+    // Parse spec
+    const parsedSpec = await parseSpecFile(specPath);
+
+    // Determine sync pattern
+    const isMasterNested = !!this.config.masterRepo && !!this.config.nestedRepos;
+
+    if (isMasterNested) {
+      // Pattern 2: Master + Nested
+      results.push(...await this.syncMasterNested(parsedSpec));
+    } else if (this.config.repos) {
+      // Pattern 1: Multiple Repos
+      results.push(...await this.syncMultipleRepos(parsedSpec));
+    } else {
+      throw new Error('Invalid config: Must specify repos[] or masterRepo+nestedRepos[]');
+    }
+
+    return results;
+  }
+
+  /**
+   * Pattern 1: Sync to multiple repos (simple)
+   *
+   * Each project → separate repo
+   * - FE user stories → company/frontend-web
+   * - BE user stories → company/backend-api
+   * - MOBILE user stories → company/mobile-app
+   */
+  private async syncMultipleRepos(parsedSpec: any): Promise<SyncResult[]> {
+    const results: SyncResult[] = [];
+
+    // Classify user stories by project
+    const projectStories = new Map<string, UserStory[]>();
+
+    for (const userStory of parsedSpec.userStories) {
+      const primaryProject = getPrimaryProject(userStory);
+
+      if (primaryProject) {
+        const existing = projectStories.get(primaryProject.projectId) || [];
+        existing.push(userStory);
+        projectStories.set(primaryProject.projectId, existing);
+      } else {
+        // No confident match - skip or assign to default repo
+        console.warn(`⚠️  No confident project match for ${userStory.id} - skipping`);
+      }
+    }
+
+    // Sync each project to its repo
+    for (const [projectId, stories] of projectStories.entries()) {
+      const repo = this.findRepoForProject(projectId);
+
+      if (!repo) {
+        console.warn(`⚠️  No GitHub repo configured for project ${projectId} - skipping`);
+        continue;
+      }
+
+      // Create or update issue for each story
+      for (const story of stories) {
+        const result = await this.createOrUpdateIssue(repo, story, projectId);
+        results.push(result);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Pattern 2: Sync to master + nested repos (advanced)
+   *
+   * - Master repo (epic-level): High-level overview
+   * - Nested repos (task-level): Detailed implementation
+   *
+   * Example:
+   * Master (company/master-project):
+   *   Epic #10: User Authentication
+   *     → Links to: frontend-web#42, backend-api#15, mobile-app#8
+   *
+   * Nested (company/frontend-web):
+   *   Issue #42: Implement Login UI
+   *     Task 1: Create login component
+   *     Task 2: Add form validation
+   */
+  private async syncMasterNested(parsedSpec: any): Promise<SyncResult[]> {
+    const results: SyncResult[] = [];
+
+    if (!this.config.masterRepo || !this.config.nestedRepos) {
+      throw new Error('Master+nested mode requires masterRepo and nestedRepos');
+    }
+
+    // Step 1: Create epic in master repo
+    const epicResult = await this.createEpicInMasterRepo(parsedSpec);
+    results.push(epicResult);
+
+    // Step 2: Classify user stories by project
+    const projectStories = new Map<string, UserStory[]>();
+
+    for (const userStory of parsedSpec.userStories) {
+      const primaryProject = getPrimaryProject(userStory);
+
+      if (primaryProject) {
+        const existing = projectStories.get(primaryProject.projectId) || [];
+        existing.push(userStory);
+        projectStories.set(primaryProject.projectId, existing);
+      }
+    }
+
+    // Step 3: Create issues in nested repos + link to epic
+    for (const [projectId, stories] of projectStories.entries()) {
+      const repo = this.findNestedRepoForProject(projectId);
+
+      if (!repo) {
+        console.warn(`⚠️  No nested repo for project ${projectId} - skipping`);
+        continue;
+      }
+
+      for (const story of stories) {
+        const result = await this.createIssueInNestedRepo(repo, story, projectId, epicResult.issueNumber);
+        results.push(result);
+      }
+    }
+
+    // Step 4: Update epic with links to nested issues
+    if (this.config.crossLinking) {
+      await this.updateEpicWithLinks(epicResult.issueNumber, results.filter(r => r.repo !== this.config.masterRepo));
+    }
+
+    return results;
+  }
+
+  /**
+   * Create epic issue in master repo
+   */
+  private async createEpicInMasterRepo(parsedSpec: any): Promise<SyncResult> {
+    const title = `Epic: ${parsedSpec.metadata.title}`;
+
+    const body = `# ${parsedSpec.metadata.title}
+
+**Status**: ${parsedSpec.metadata.status}
+**Priority**: ${parsedSpec.metadata.priority}
+**Estimated Effort**: ${parsedSpec.metadata.estimatedEffort || parsedSpec.metadata.estimated_effort}
+
+## Executive Summary
+
+${parsedSpec.executiveSummary}
+
+## User Stories (${parsedSpec.userStories.length} total)
+
+${parsedSpec.userStories.map((s: UserStory, i: number) => `${i + 1}. ${s.id}: ${s.title}`).join('\n')}
+
+---
+
+📊 **This is a high-level epic** - detailed implementation tracked in nested repos
+🔗 **Links to implementation issues** (will be added automatically)
+
+🤖 Auto-generated by SpecWeave
+`;
+
+    const response = await this.octokit.issues.create({
+      owner: this.config.owner,
+      repo: this.config.masterRepo!,
+      title,
+      body,
+      labels: ['epic', 'specweave']
+    });
+
+    return {
+      project: 'MASTER',
+      repo: this.config.masterRepo!,
+      issueNumber: response.data.number,
+      url: response.data.html_url,
+      action: 'created'
+    };
+  }
+
+  /**
+   * Create issue in nested repo + link to epic
+   */
+  private async createIssueInNestedRepo(
+    repo: string,
+    userStory: UserStory,
+    projectId: string,
+    epicNumber?: number
+  ): Promise<SyncResult> {
+    const title = `${userStory.id}: ${userStory.title}`;
+
+    let body = `# ${userStory.title}
+
+${userStory.description}
+
+## Acceptance Criteria
+
+${userStory.acceptanceCriteria.map((ac, i) => `- [ ] ${ac}`).join('\n')}
+`;
+
+    // Add technical context if present
+    if (userStory.technicalContext) {
+      body += `\n## Technical Context\n\n${userStory.technicalContext}\n`;
+    }
+
+    // Add link to epic if cross-linking enabled
+    if (this.config.crossLinking && epicNumber) {
+      body += `\n---\n\n📊 Part of Epic: ${this.config.owner}/${this.config.masterRepo}#${epicNumber}\n`;
+    }
+
+    body += `\n🤖 Auto-generated by SpecWeave\n`;
+
+    const response = await this.octokit.issues.create({
+      owner: this.config.owner,
+      repo,
+      title,
+      body,
+      labels: ['story', 'specweave', projectId.toLowerCase()]
+    });
+
+    return {
+      project: projectId,
+      repo,
+      issueNumber: response.data.number,
+      url: response.data.html_url,
+      action: 'created'
+    };
+  }
+
+  /**
+   * Create or update issue (for simple multi-repo pattern)
+   */
+  private async createOrUpdateIssue(repo: string, userStory: UserStory, projectId: string): Promise<SyncResult> {
+    const title = `${userStory.id}: ${userStory.title}`;
+
+    const body = `# ${userStory.title}
+
+${userStory.description}
+
+## Acceptance Criteria
+
+${userStory.acceptanceCriteria.map((ac, i) => `- [ ] ${ac}`).join('\n')}
+
+${userStory.technicalContext ? `\n## Technical Context\n\n${userStory.technicalContext}\n` : ''}
+
+🤖 Auto-generated by SpecWeave
+`;
+
+    // Check if issue already exists (search by title)
+    const existingIssues = await this.octokit.issues.listForRepo({
+      owner: this.config.owner,
+      repo,
+      labels: 'specweave',
+      state: 'all'
+    });
+
+    const existing = existingIssues.data.find(issue => issue.title === title);
+
+    if (existing) {
+      // Update existing issue
+      const response = await this.octokit.issues.update({
+        owner: this.config.owner,
+        repo,
+        issue_number: existing.number,
+        body
+      });
+
+      return {
+        project: projectId,
+        repo,
+        issueNumber: response.data.number,
+        url: response.data.html_url,
+        action: 'updated'
+      };
+    } else {
+      // Create new issue
+      const response = await this.octokit.issues.create({
+        owner: this.config.owner,
+        repo,
+        title,
+        body,
+        labels: ['specweave', projectId.toLowerCase()]
+      });
+
+      return {
+        project: projectId,
+        repo,
+        issueNumber: response.data.number,
+        url: response.data.html_url,
+        action: 'created'
+      };
+    }
+  }
+
+  /**
+   * Update epic with links to nested issues
+   */
+  private async updateEpicWithLinks(epicNumber: number, nestedResults: SyncResult[]): Promise<void> {
+    if (!this.config.masterRepo) return;
+
+    const linksSection = `\n\n## Implementation Issues\n\n${nestedResults
+      .map(r => `- ${r.project}: ${this.config.owner}/${r.repo}#${r.issueNumber} - ${r.url}`)
+      .join('\n')}\n`;
+
+    // Get current epic body
+    const epic = await this.octokit.issues.get({
+      owner: this.config.owner,
+      repo: this.config.masterRepo,
+      issue_number: epicNumber
+    });
+
+    // Append links section
+    const updatedBody = epic.data.body + linksSection;
+
+    // Update epic
+    await this.octokit.issues.update({
+      owner: this.config.owner,
+      repo: this.config.masterRepo,
+      issue_number: epicNumber,
+      body: updatedBody
+    });
+  }
+
+  /**
+   * Find GitHub repo for project ID
+   *
+   * Maps project IDs to repo names:
+   * - FE → frontend-web
+   * - BE → backend-api
+   * - MOBILE → mobile-app
+   */
+  private findRepoForProject(projectId: string): string | undefined {
+    if (!this.config.repos) return undefined;
+
+    // Try exact match first
+    let match = this.config.repos.find(repo => repo.toLowerCase().includes(projectId.toLowerCase()));
+
+    if (!match) {
+      // Try fuzzy match (FE → frontend, BE → backend, MOBILE → mobile)
+      const fuzzyMap: Record<string, string[]> = {
+        FE: ['frontend', 'web', 'ui', 'client'],
+        BE: ['backend', 'api', 'server'],
+        MOBILE: ['mobile', 'app', 'ios', 'android'],
+        INFRA: ['infra', 'infrastructure', 'devops', 'platform']
+      };
+
+      const keywords = fuzzyMap[projectId] || [];
+
+      match = this.config.repos.find(repo =>
+        keywords.some(keyword => repo.toLowerCase().includes(keyword))
+      );
+    }
+
+    return match;
+  }
+
+  /**
+   * Find nested repo for project ID (same logic as findRepoForProject)
+   */
+  private findNestedRepoForProject(projectId: string): string | undefined {
+    if (!this.config.nestedRepos) return undefined;
+
+    // Reuse same logic
+    const tempConfig = { ...this.config, repos: this.config.nestedRepos };
+    const tempSync = new GitHubMultiProjectSync(tempConfig);
+    return tempSync.findRepoForProject(projectId);
+  }
+}
+
+/**
+ * Format sync results for display
+ */
+export function formatSyncResults(results: SyncResult[]): string {
+  const lines: string[] = [];
+
+  lines.push('📊 GitHub Multi-Project Sync Results:\n');
+
+  const byProject = new Map<string, SyncResult[]>();
+
+  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**${project}**:`);
+
+    for (const result of projectResults) {
+      const icon = result.action === 'created' ? '✅' : result.action === 'updated' ? '🔄' : '⏭️';
+      lines.push(`  ${icon} ${result.repo}#${result.issueNumber} (${result.action})`);
+      lines.push(`     ${result.url}`);
+    }
+  }
+
+  lines.push(`\n✅ Total: ${results.length} issues synced\n`);
+
+  return lines.join('\n');
+}

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

@@ -0,0 +1,244 @@
+import { JiraClient } from "../../../src/integrations/jira/jira-client.js";
+import {
+  suggestJiraItemType,
+  mapUserStoryToProjects
+} from "../../../src/utils/project-mapper.js";
+import { parseSpecFile } from "../../../src/utils/spec-splitter.js";
+class JiraMultiProjectSync {
+  constructor(config) {
+    this.config = config;
+    this.client = new JiraClient({
+      domain: config.domain,
+      email: config.email,
+      apiToken: config.apiToken
+    });
+  }
+  /**
+   * Sync spec to JIRA projects with intelligent mapping
+   *
+   * @param specPath Path to spec file
+   * @returns Array of sync results
+   */
+  async syncSpec(specPath) {
+    const results = [];
+    const parsedSpec = await parseSpecFile(specPath);
+    const epicsByProject = /* @__PURE__ */ new Map();
+    if (this.config.autoCreateEpics !== false) {
+      for (const project of this.config.projects) {
+        const epicResult = await this.createEpicForProject(parsedSpec, project);
+        epicsByProject.set(project, epicResult.issueKey);
+        results.push(epicResult);
+      }
+    }
+    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 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 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);
+        }
+      }
+    }
+    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 || parsedSpec.metadata.estimated_effort}
+
+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) {
+      issueData.parent = { key: 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
+};