specweave 0.17.16 → 0.17.17

package/plugins/specweave-github/lib/github-epic-sync.js

@@ -0,0 +1,489 @@
+import { readdir, readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { DuplicateDetector } from "./duplicate-detector.js";
+class GitHubEpicSync {
+  constructor(client, specsDir) {
+    this.client = client;
+    this.specsDir = specsDir;
+  }
+  /**
+   * Sync Epic folder to GitHub (Milestone + Issues)
+   */
+  async syncEpicToGitHub(epicId) {
+    console.log(`
+\u{1F504} Syncing Epic ${epicId} to GitHub...`);
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic ${epicId} not found in ${this.specsDir}`);
+    }
+    const readmePath = path.join(epicFolder, "FEATURE.md");
+    const epicData = await this.parseEpicReadme(readmePath);
+    console.log(`   \u{1F4E6} Epic: ${epicData.title}`);
+    console.log(`   \u{1F4CA} Increments: ${epicData.total_increments}`);
+    let milestoneNumber = epicData.external_tools.github.id;
+    let milestoneUrl = epicData.external_tools.github.url;
+    if (!milestoneNumber) {
+      console.log(`   \u{1F680} Creating GitHub Milestone...`);
+      const milestone = await this.createMilestone(epicData);
+      milestoneNumber = milestone.number;
+      milestoneUrl = milestone.url;
+      console.log(`   \u2705 Created Milestone #${milestoneNumber}`);
+      await this.updateEpicReadme(readmePath, {
+        type: "milestone",
+        id: milestoneNumber,
+        url: milestoneUrl
+      });
+    } else {
+      console.log(`   \u267B\uFE0F  Updating existing Milestone #${milestoneNumber}...`);
+      await this.updateMilestone(milestoneNumber, epicData);
+      console.log(`   \u2705 Updated Milestone #${milestoneNumber}`);
+    }
+    let issuesCreated = 0;
+    let issuesUpdated = 0;
+    let duplicatesDetected = 0;
+    console.log(`
+   \u{1F4DD} Syncing ${epicData.increments.length} increments...`);
+    for (const increment of epicData.increments) {
+      const incrementFile = path.join(epicFolder, `${increment.id}.md`);
+      if (!existsSync(incrementFile)) {
+        console.log(`   \u26A0\uFE0F  Increment file not found: ${increment.id}.md`);
+        continue;
+      }
+      const incrementData = await this.parseIncrementFile(incrementFile);
+      const existingIssue = increment.external.github;
+      if (!existingIssue) {
+        console.log(`   \u{1F50D} Checking GitHub for existing issue: ${increment.id}...`);
+        const githubIssue = await this.findExistingIssue(epicData.id, increment.id);
+        if (githubIssue) {
+          console.log(`   \u267B\uFE0F  Found existing Issue #${githubIssue} for ${increment.id} (self-healing)`);
+          await this.updateIncrementExternalLink(
+            readmePath,
+            incrementFile,
+            increment.id,
+            githubIssue
+          );
+          issuesUpdated++;
+          duplicatesDetected++;
+        } else {
+          const issueNumber = await this.createIssue(
+            epicData.id,
+            incrementData,
+            milestoneNumber
+          );
+          issuesCreated++;
+          console.log(`   \u2705 Created Issue #${issueNumber} for ${increment.id}`);
+          await this.updateIncrementExternalLink(
+            readmePath,
+            incrementFile,
+            increment.id,
+            issueNumber
+          );
+        }
+      } else {
+        await this.updateIssue(
+          epicData.id,
+          existingIssue,
+          incrementData,
+          milestoneNumber
+        );
+        issuesUpdated++;
+        console.log(`   \u267B\uFE0F  Updated Issue #${existingIssue} for ${increment.id}`);
+      }
+    }
+    console.log(`
+\u2705 Epic sync complete!`);
+    console.log(`   Milestone: ${milestoneUrl}`);
+    console.log(`   Issues created: ${issuesCreated}`);
+    console.log(`   Issues updated: ${issuesUpdated}`);
+    if (duplicatesDetected > 0) {
+      console.log(`   \u{1F517} Self-healed: ${duplicatesDetected} (found existing issues)`);
+    }
+    console.log(`
+\u{1F50D} Post-sync validation...`);
+    const validation = await this.validateSync(epicData.id);
+    if (validation.duplicatesFound > 0) {
+      console.warn(`
+\u26A0\uFE0F  WARNING: ${validation.duplicatesFound} duplicate(s) detected!`);
+      console.warn(`   This may indicate a previous sync created duplicates.`);
+      console.warn(`   Run cleanup command to resolve:`);
+      console.warn(`   /specweave-github:cleanup-duplicates ${epicData.id}`);
+      console.warn(`
+   Duplicate groups:`);
+      for (const [title, numbers] of validation.duplicateGroups) {
+        console.warn(`   - "${title}": Issues #${numbers.join(", #")}`);
+      }
+    } else {
+      console.log(`   \u2705 No duplicates found`);
+    }
+    return {
+      milestoneNumber,
+      milestoneUrl,
+      issuesCreated,
+      issuesUpdated,
+      duplicatesDetected
+    };
+  }
+  /**
+   * Validate sync results - check for duplicate issues
+   *
+   * Searches GitHub for all issues with the Epic ID and detects duplicates
+   * (multiple issues with the same title).
+   *
+   * @param epicId - Epic ID (e.g., FS-031)
+   * @returns Validation result with duplicate count and groups
+   */
+  async validateSync(epicId) {
+    try {
+      const titlePattern = `[${epicId}]`;
+      const result = await execFileNoThrow("gh", [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,state",
+        "--limit",
+        "100",
+        // Check up to 100 issues
+        "--state",
+        "all"
+        // Include both open and closed
+      ]);
+      if (result.exitCode !== 0 || !result.stdout) {
+        console.warn(`   \u26A0\uFE0F  Validation failed: ${result.stderr || "unknown error"}`);
+        return { totalIssues: 0, duplicatesFound: 0, duplicateGroups: [] };
+      }
+      const issues = JSON.parse(result.stdout);
+      const titleGroups = /* @__PURE__ */ new Map();
+      for (const issue of issues) {
+        const title = issue.title;
+        if (!titleGroups.has(title)) {
+          titleGroups.set(title, []);
+        }
+        titleGroups.get(title).push(issue.number);
+      }
+      const duplicateGroups = [];
+      for (const [title, numbers] of titleGroups.entries()) {
+        if (numbers.length > 1) {
+          duplicateGroups.push([title, numbers]);
+        }
+      }
+      return {
+        totalIssues: issues.length,
+        duplicatesFound: duplicateGroups.length,
+        duplicateGroups
+      };
+    } catch (error) {
+      console.warn(`   \u26A0\uFE0F  Validation error: ${error}`);
+      return { totalIssues: 0, duplicatesFound: 0, duplicateGroups: [] };
+    }
+  }
+  /**
+   * Find existing GitHub issue for increment (duplicate detection!)
+   *
+   * Searches GitHub for issues matching the Epic ID and Increment ID.
+   * This prevents creating duplicates when frontmatter is lost/corrupted.
+   *
+   * @param epicId - Epic ID (e.g., FS-031)
+   * @param incrementId - Increment ID (e.g., 0031-feature-name)
+   * @returns GitHub issue number if found, null otherwise
+   */
+  async findExistingIssue(epicId, incrementId) {
+    try {
+      const titlePattern = `[${epicId}]`;
+      const result = await execFileNoThrow("gh", [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,body",
+        "--limit",
+        "50"
+        // Check up to 50 issues (should cover most Epics)
+      ]);
+      if (result.exitCode !== 0 || !result.stdout) {
+        console.warn(`   \u26A0\uFE0F  GitHub search failed: ${result.stderr || "unknown error"}`);
+        return null;
+      }
+      const issues = JSON.parse(result.stdout);
+      if (issues.length === 0) {
+        return null;
+      }
+      for (const issue of issues) {
+        if (issue.body && issue.body.includes(`**Increment**: ${incrementId}`)) {
+          console.log(
+            `   \u{1F517} Found existing issue #${issue.number} for ${incrementId}`
+          );
+          return issue.number;
+        }
+      }
+      for (const issue of issues) {
+        if (issue.title.toLowerCase().includes(incrementId.toLowerCase())) {
+          console.log(
+            `   \u{1F517} Found existing issue #${issue.number} for ${incrementId} (title match)`
+          );
+          return issue.number;
+        }
+      }
+      return null;
+    } catch (error) {
+      console.warn(`   \u26A0\uFE0F  Error searching for existing issue: ${error}`);
+      return null;
+    }
+  }
+  /**
+   * Find Epic folder by ID (FS-001 or just 001)
+   */
+  async findEpicFolder(epicId) {
+    const normalizedId = epicId.startsWith("FS-") ? epicId : `FS-${epicId.padStart(3, "0")}`;
+    const folders = await readdir(this.specsDir);
+    for (const folder of folders) {
+      if (folder.startsWith(normalizedId)) {
+        return path.join(this.specsDir, folder);
+      }
+    }
+    return null;
+  }
+  /**
+   * Parse Epic FEATURE.md to extract frontmatter
+   */
+  async parseEpicReadme(readmePath) {
+    const content = await readFile(readmePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("Epic FEATURE.md missing YAML frontmatter");
+    }
+    const frontmatter = yaml.parse(match[1]);
+    return frontmatter;
+  }
+  /**
+   * Parse increment file to extract title and overview
+   */
+  async parseIncrementFile(filePath) {
+    const content = await readFile(filePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    let frontmatter = { id: "", epic: "" };
+    let bodyContent = content;
+    if (match) {
+      frontmatter = yaml.parse(match[1]);
+      bodyContent = content.slice(match[0].length).trim();
+    }
+    const titleMatch = bodyContent.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : frontmatter.id || path.basename(filePath, ".md");
+    const overviewMatch = bodyContent.match(/^#[^\n]+\n+([^\n]+)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : "No overview available";
+    return {
+      id: frontmatter.id,
+      title,
+      overview,
+      content: bodyContent,
+      frontmatter
+    };
+  }
+  /**
+   * Create GitHub Milestone
+   */
+  async createMilestone(epic) {
+    const title = `[${epic.id}] ${epic.title}`;
+    const description = `Epic: ${epic.title}
+
+Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
+
+Priority: ${epic.priority}
+Status: ${epic.status}`;
+    const state = epic.status === "complete" ? "closed" : "open";
+    const result = await execFileNoThrow("gh", [
+      "api",
+      "/repos/{owner}/{repo}/milestones",
+      "-X",
+      "POST",
+      "-f",
+      `title=${title}`,
+      "-f",
+      `description=${description}`,
+      "-f",
+      `state=${state}`
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Failed to create GitHub Milestone: ${result.stderr || result.stdout}`
+      );
+    }
+    const milestone = JSON.parse(result.stdout);
+    return {
+      number: milestone.number,
+      url: milestone.html_url
+    };
+  }
+  /**
+   * Update GitHub Milestone
+   */
+  async updateMilestone(milestoneNumber, epic) {
+    const title = `[${epic.id}] ${epic.title}`;
+    const description = `Epic: ${epic.title}
+
+Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
+
+Priority: ${epic.priority}
+Status: ${epic.status}`;
+    const state = epic.status === "complete" ? "closed" : "open";
+    const result = await execFileNoThrow("gh", [
+      "api",
+      `/repos/{owner}/{repo}/milestones/${milestoneNumber}`,
+      "-X",
+      "PATCH",
+      "-f",
+      `title=${title}`,
+      "-f",
+      `description=${description}`,
+      "-f",
+      `state=${state}`
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Failed to update GitHub Milestone: ${result.stderr || result.stdout}`
+      );
+    }
+  }
+  /**
+   * Create GitHub Issue for increment with FULL DUPLICATE PROTECTION
+   */
+  async createIssue(epicId, increment, milestoneNumber) {
+    const title = `[${epicId}] ${increment.title}`;
+    const body = `# ${increment.title}
+
+${increment.overview}
+
+---
+
+**Increment**: ${increment.id}
+**Epic**: ${epicId}
+**Milestone**: See milestone for Epic progress
+
+\u{1F916} Auto-created by SpecWeave Epic Sync`;
+    try {
+      const result = await DuplicateDetector.createWithProtection({
+        title,
+        body,
+        titlePattern: `[${epicId}]`,
+        incrementId: increment.id,
+        // For body matching
+        labels: ["increment", "epic-sync"],
+        milestone: milestoneNumber.toString()
+      });
+      if (result.wasReused) {
+        console.log(`      \u267B\uFE0F  Reused existing issue #${result.issue.number} (duplicate prevention)`);
+      }
+      if (result.duplicatesFound > 0) {
+        console.log(`      \u{1F6E1}\uFE0F  Duplicates: ${result.duplicatesFound} found, ${result.duplicatesClosed} closed`);
+      }
+      return result.issue.number;
+    } catch (error) {
+      throw new Error(`Failed to create GitHub Issue: ${error.message}`);
+    }
+  }
+  /**
+   * Update GitHub Issue for increment
+   */
+  async updateIssue(epicId, issueNumber, increment, milestoneNumber) {
+    const title = `[${epicId}] ${increment.title}`;
+    const body = `# ${increment.title}
+
+${increment.overview}
+
+---
+
+**Increment**: ${increment.id}
+**Epic**: ${epicId}
+**Milestone**: See milestone for Epic progress
+
+\u{1F916} Auto-updated by SpecWeave Epic Sync`;
+    const result = await execFileNoThrow("gh", [
+      "issue",
+      "edit",
+      issueNumber.toString(),
+      "--title",
+      title,
+      "--body",
+      body,
+      "--milestone",
+      milestoneNumber.toString()
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Failed to update GitHub Issue: ${result.stderr || result.stdout}`
+      );
+    }
+  }
+  /**
+   * Update Epic FEATURE.md with GitHub Milestone ID
+   */
+  async updateEpicReadme(readmePath, github) {
+    const content = await readFile(readmePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("Epic FEATURE.md missing YAML frontmatter");
+    }
+    const frontmatter = yaml.parse(match[1]);
+    frontmatter.external_tools.github = github;
+    const newFrontmatter = yaml.stringify(frontmatter);
+    const newContent = content.replace(
+      /^---\n[\s\S]*?\n---/,
+      `---
+${newFrontmatter}---`
+    );
+    await writeFile(readmePath, newContent, "utf-8");
+  }
+  /**
+   * Update increment external link in both Epic README and increment file
+   */
+  async updateIncrementExternalLink(readmePath, incrementFile, incrementId, issueNumber) {
+    const issueUrl = `https://github.com/{owner}/{repo}/issues/${issueNumber}`;
+    const readmeContent = await readFile(readmePath, "utf-8");
+    const readmeMatch = readmeContent.match(/^---\n([\s\S]*?)\n---/);
+    if (readmeMatch) {
+      const frontmatter = yaml.parse(readmeMatch[1]);
+      const increment = frontmatter.increments.find(
+        (inc) => inc.id === incrementId
+      );
+      if (increment) {
+        increment.external.github = issueNumber;
+        const newFrontmatter = yaml.stringify(frontmatter);
+        const newContent = readmeContent.replace(
+          /^---\n[\s\S]*?\n---/,
+          `---
+${newFrontmatter}---`
+        );
+        await writeFile(readmePath, newContent, "utf-8");
+      }
+    }
+    const incrementContent = await readFile(incrementFile, "utf-8");
+    const incrementMatch = incrementContent.match(/^---\n([\s\S]*?)\n---/);
+    if (incrementMatch) {
+      const frontmatter = yaml.parse(
+        incrementMatch[1]
+      );
+      if (!frontmatter.external) {
+        frontmatter.external = {};
+      }
+      frontmatter.external.github = {
+        issue: issueNumber,
+        url: issueUrl
+      };
+      const newFrontmatter = yaml.stringify(frontmatter);
+      const newContent = incrementContent.replace(
+        /^---\n[\s\S]*?\n---/,
+        `---
+${newFrontmatter}---`
+      );
+      await writeFile(incrementFile, newContent, "utf-8");
+    }
+  }
+}
+export {
+  GitHubEpicSync
+};