specweave 0.28.17 → 0.28.20

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

@@ -1,488 +0,0 @@
-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";
-import { EpicContentBuilder } from "./epic-content-builder.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 Epic with hierarchical content (US → Tasks)
-   */
-  async createIssue(epicId, increment, milestoneNumber) {
-    const title = `[${epicId}] ${increment.title}`;
-    const epicFolder = await this.findEpicFolder(epicId);
-    if (!epicFolder) {
-      throw new Error(`Epic folder not found for ${epicId}`);
-    }
-    const contentBuilder = new EpicContentBuilder(
-      epicFolder,
-      path.dirname(this.specsDir)
-      // Project root
-    );
-    const body = await contentBuilder.buildIssueBody();
-    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 Epic with hierarchical content (US → Tasks)
-   */
-  async updateIssue(epicId, issueNumber, increment, milestoneNumber) {
-    const title = `[${epicId}] ${increment.title}`;
-    const epicFolder = await this.findEpicFolder(epicId);
-    if (!epicFolder) {
-      throw new Error(`Epic folder not found for ${epicId}`);
-    }
-    const contentBuilder = new EpicContentBuilder(
-      epicFolder,
-      path.dirname(this.specsDir)
-      // Project root
-    );
-    const body = await contentBuilder.buildIssueBody();
-    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
-};