specweave 0.21.2 → 0.22.0

package/plugins/specweave-github/lib/ThreeLayerSyncManager.js

@@ -0,0 +1,545 @@
+import fs from "fs-extra";
+import path from "path";
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { CodeValidator } from "./CodeValidator.js";
+class ThreeLayerSyncManager {
+  constructor(projectRoot = process.cwd()) {
+    this.userStoryFileCache = /* @__PURE__ */ new Map();
+    this.projectRoot = projectRoot;
+    this.codeValidator = new CodeValidator({ projectRoot });
+  }
+  /**
+   * Clear User Story file cache
+   * Call this when file structure changes or for testing
+   */
+  clearCache() {
+    this.userStoryFileCache.clear();
+  }
+  /**
+   * Sync from GitHub to Increment (Flow 1: GitHub → Living Docs → Increment)
+   *
+   * Triggered when stakeholder checks AC/Task checkbox in GitHub issue.
+   */
+  async syncGitHubToIncrement(issueNumber, incrementPath, livingDocsPath) {
+    const result = {
+      acsUpdated: 0,
+      tasksUpdated: 0,
+      tasksReopened: 0,
+      conflicts: [],
+      errors: []
+    };
+    try {
+      console.log(`\u{1F504} Syncing GitHub issue #${issueNumber} \u2192 Increment`);
+      const githubState = await this.fetchGitHubIssueState(issueNumber);
+      const githubAcs = this.extractAcsFromIssue(githubState.body);
+      const githubTasks = this.extractTasksFromIssue(githubState.body);
+      const acUpdatePromises = githubAcs.map(async (ac) => {
+        const userStoryPath = await this.findUserStoryFile(livingDocsPath, ac.userStoryId);
+        if (userStoryPath) {
+          await this.updateUserStoryAc(userStoryPath, ac.id, ac.completed);
+          result.acsUpdated++;
+        }
+      });
+      const taskUpdatePromises = githubTasks.map(async (task) => {
+        const userStoryPath = await this.findUserStoryFileForTask(livingDocsPath, task.id);
+        if (userStoryPath) {
+          await this.updateUserStoryTask(userStoryPath, task.id, task.completed);
+          result.tasksUpdated++;
+        }
+      });
+      await Promise.all([...acUpdatePromises, ...taskUpdatePromises]);
+      await this.updateIncrementAcsWithConflictResolution(incrementPath, githubAcs, result);
+      await this.updateIncrementTasksWithConflictResolution(incrementPath, githubTasks, result);
+      const completedTasks = githubTasks.filter((t) => t.completed);
+      const validationPromises = completedTasks.map(async (task) => {
+        const codeExists = await this.validateCodeExists(task);
+        if (!codeExists) {
+          console.log(`\u26A0\uFE0F  Task ${task.id} marked complete but code missing - reopening`);
+          await this.reopenTask(task.id, incrementPath, livingDocsPath, issueNumber);
+          result.tasksReopened++;
+        }
+      });
+      await Promise.all(validationPromises);
+      console.log(`\u2705 Sync complete: ${result.acsUpdated} ACs, ${result.tasksUpdated} tasks updated`);
+      if (result.tasksReopened > 0) {
+        console.log(`   ${result.tasksReopened} tasks reopened due to missing code`);
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      result.errors.push(errorMsg);
+      console.error(`\u274C Error syncing GitHub \u2192 Increment:`, error);
+    }
+    return result;
+  }
+  /**
+   * Sync from Increment to GitHub (Flow 2: Increment → Living Docs → GitHub)
+   *
+   * Triggered when developer completes work and updates increment files.
+   */
+  async syncIncrementToGitHub(incrementPath, livingDocsPath, issueNumber) {
+    const result = {
+      acsUpdated: 0,
+      tasksUpdated: 0,
+      tasksReopened: 0,
+      conflicts: [],
+      errors: []
+    };
+    try {
+      console.log(`\u{1F504} Syncing Increment \u2192 GitHub issue #${issueNumber}`);
+      const specPath = path.join(incrementPath, "spec.md");
+      const tasksPath = path.join(incrementPath, "tasks.md");
+      const specContent = await fs.readFile(specPath, "utf-8");
+      const tasksContent = await fs.readFile(tasksPath, "utf-8");
+      const acs = this.parseAcceptanceCriteria(specContent);
+      const tasks = this.parseTasks(tasksContent);
+      const acsByUserStory = this.groupAcsByUserStory(acs);
+      for (const [userStoryId, userStoryAcs] of Object.entries(acsByUserStory)) {
+        const userStoryPath = await this.findUserStoryFile(livingDocsPath, userStoryId);
+        if (userStoryPath) {
+          await this.updateUserStoryAcs(userStoryPath, userStoryAcs);
+          result.acsUpdated += userStoryAcs.length;
+          const acIds = userStoryAcs.map((ac) => ac.id);
+          const userStoryTasks = this.filterTasksByAcIds(tasks, acIds);
+          await this.updateUserStoryTasks(userStoryPath, userStoryTasks);
+          result.tasksUpdated += userStoryTasks.length;
+        }
+      }
+      await this.updateGitHubIssue(issueNumber, acs, tasks);
+      console.log(`\u2705 Sync complete: ${result.acsUpdated} ACs, ${result.tasksUpdated} tasks updated`);
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      result.errors.push(errorMsg);
+      console.error(`\u274C Error syncing Increment \u2192 GitHub:`, error);
+    }
+    return result;
+  }
+  /**
+   * Validate that code exists for completed task
+   * Uses CodeValidator for comprehensive validation
+   */
+  async validateCodeExists(task) {
+    const validationResult = await this.codeValidator.validateTask(task.title, task.id);
+    return validationResult.valid;
+  }
+  /**
+   * Reopen task if code validation fails
+   */
+  async reopenTask(taskId, incrementPath, livingDocsPath, issueNumber) {
+    const tasksPath = path.join(incrementPath, "tasks.md");
+    let tasksContent = await fs.readFile(tasksPath, "utf-8");
+    const taskRegex = new RegExp(`(### ${taskId}:[^#]*?)\\*\\*Completed\\*\\*:[^\\n]*\\n`, "s");
+    tasksContent = tasksContent.replace(taskRegex, "$1");
+    await fs.writeFile(tasksPath, tasksContent, "utf-8");
+    const userStoryPath = await this.findUserStoryFileForTask(livingDocsPath, taskId);
+    if (userStoryPath) {
+      await this.updateUserStoryTask(userStoryPath, taskId, false);
+    }
+    await this.addGitHubComment(
+      issueNumber,
+      `\u26A0\uFE0F Task ${taskId} reopened: Code validation failed (missing or empty file). Please implement the required code.`
+    );
+  }
+  /**
+   * Propagate completion from Tasks → ACs → User Stories (bottom-up)
+   */
+  async propagateCompletion(incrementPath, livingDocsPath) {
+    const specPath = path.join(incrementPath, "spec.md");
+    const tasksPath = path.join(incrementPath, "tasks.md");
+    const specContent = await fs.readFile(specPath, "utf-8");
+    const tasksContent = await fs.readFile(tasksPath, "utf-8");
+    const acs = this.parseAcceptanceCriteria(specContent);
+    const tasks = this.parseTasks(tasksContent);
+    for (const ac of acs) {
+      const acTasks = tasks.filter((t) => t.acIds.includes(ac.id));
+      const allTasksComplete = acTasks.length > 0 && acTasks.every((t) => t.completed);
+      if (allTasksComplete && !ac.completed) {
+        console.log(`\u2705 All tasks for ${ac.id} complete - marking AC as complete`);
+        await this.updateIncrementAc(incrementPath, ac.id, true);
+        const userStoryPath = await this.findUserStoryFile(livingDocsPath, ac.userStoryId);
+        if (userStoryPath) {
+          await this.updateUserStoryAc(userStoryPath, ac.id, true);
+        }
+      }
+    }
+    const acsByUserStory = this.groupAcsByUserStory(acs);
+    for (const [userStoryId, userStoryAcs] of Object.entries(acsByUserStory)) {
+      const allAcsComplete = userStoryAcs.every((ac) => ac.completed);
+      if (allAcsComplete) {
+        console.log(`\u2705 All ACs for ${userStoryId} complete - User Story complete`);
+      }
+    }
+  }
+  // ==================== Helper Methods ====================
+  /**
+   * Fetch GitHub issue state
+   */
+  async fetchGitHubIssueState(issueNumber) {
+    const result = await execFileNoThrow("gh", [
+      "issue",
+      "view",
+      String(issueNumber),
+      "--json",
+      "body,state"
+    ]);
+    if (result.stderr) {
+      throw new Error(`Failed to fetch GitHub issue: ${result.stderr}`);
+    }
+    return JSON.parse(result.stdout);
+  }
+  /**
+   * Extract ACs from GitHub issue body
+   */
+  extractAcsFromIssue(body) {
+    const acs = [];
+    const lines = body.split("\n");
+    const acRegex = /^- \[([ x])\] (AC-[A-Z0-9]+-\d+):\s*(.+)$/;
+    for (const line of lines) {
+      const match = line.match(acRegex);
+      if (match) {
+        const completed = match[1] === "x";
+        const id = match[2];
+        const description = match[3];
+        const userStoryMatch = id.match(/AC-([A-Z0-9]+)-\d+/);
+        const userStoryId = userStoryMatch ? userStoryMatch[1] : "";
+        acs.push({
+          id,
+          userStoryId,
+          description,
+          completed,
+          projects: [],
+          rawLine: line
+        });
+      }
+    }
+    return acs;
+  }
+  /**
+   * Extract Tasks from GitHub issue body
+   */
+  extractTasksFromIssue(body) {
+    const tasks = [];
+    const lines = body.split("\n");
+    const taskRegex = /^- \[([ x])\] (T-\d+):\s*(.+)$/;
+    for (const line of lines) {
+      const match = line.match(taskRegex);
+      if (match) {
+        const completed = match[1] === "x";
+        const id = match[2];
+        const title = match[3];
+        tasks.push({
+          id,
+          title,
+          completed,
+          acIds: []
+        });
+      }
+    }
+    return tasks;
+  }
+  /**
+   * Parse ACs from spec.md
+   */
+  parseAcceptanceCriteria(specContent) {
+    const acs = [];
+    const lines = specContent.split("\n");
+    const acRegex = /^- \[([ x])\] (AC-[A-Z0-9]+-\d+):\s*(.+)$/;
+    for (const line of lines) {
+      const match = line.match(acRegex);
+      if (match) {
+        const completed = match[1] === "x";
+        const id = match[2];
+        const description = match[3];
+        const userStoryMatch = id.match(/AC-([A-Z0-9]+)-\d+/);
+        const userStoryId = userStoryMatch ? userStoryMatch[1] : "";
+        acs.push({
+          id,
+          userStoryId,
+          description,
+          completed,
+          projects: [],
+          rawLine: line
+        });
+      }
+    }
+    return acs;
+  }
+  /**
+   * Parse Tasks from tasks.md
+   */
+  parseTasks(tasksContent) {
+    const tasks = [];
+    const lines = tasksContent.split("\n");
+    let currentTask = null;
+    for (const line of lines) {
+      const headerMatch = line.match(/^### (T-\d+):\s*(.+?)\s*\(P\d+\)$/);
+      if (headerMatch) {
+        if (currentTask && currentTask.id) {
+          tasks.push(currentTask);
+        }
+        currentTask = {
+          id: headerMatch[1],
+          title: headerMatch[2],
+          completed: false,
+          acIds: []
+        };
+        continue;
+      }
+      const completedMatch = line.match(/^\*\*Completed\*\*:\s*(.+)$/);
+      if (completedMatch && currentTask) {
+        currentTask.completed = true;
+        currentTask.completedDate = completedMatch[1];
+      }
+      const acMatch = line.match(/\*\*AC\*\*:\s*(.+)$/);
+      if (acMatch && currentTask) {
+        const acIds = acMatch[1].split(",").map((id) => id.trim());
+        currentTask.acIds = acIds;
+      }
+    }
+    if (currentTask && currentTask.id) {
+      tasks.push(currentTask);
+    }
+    return tasks;
+  }
+  /**
+   * Group ACs by User Story ID
+   */
+  groupAcsByUserStory(acs) {
+    const grouped = {};
+    for (const ac of acs) {
+      if (!grouped[ac.userStoryId]) {
+        grouped[ac.userStoryId] = [];
+      }
+      grouped[ac.userStoryId].push(ac);
+    }
+    return grouped;
+  }
+  /**
+   * Filter tasks by AC IDs
+   */
+  filterTasksByAcIds(tasks, acIds) {
+    return tasks.filter(
+      (task) => task.acIds.some((acId) => acIds.includes(acId))
+    );
+  }
+  /**
+   * Find User Story file by ID (with caching for performance)
+   */
+  async findUserStoryFile(livingDocsPath, userStoryId) {
+    const cacheKey = `${livingDocsPath}:${userStoryId}`;
+    if (this.userStoryFileCache.has(cacheKey)) {
+      return this.userStoryFileCache.get(cacheKey);
+    }
+    const specsPath = path.join(livingDocsPath, "internal", "specs");
+    const pattern = `**/us-*${userStoryId.toLowerCase()}*.md`;
+    const { glob } = await import("glob");
+    const files = await glob(pattern, { cwd: specsPath, absolute: true });
+    const result = files.length > 0 ? files[0] : null;
+    this.userStoryFileCache.set(cacheKey, result);
+    return result;
+  }
+  /**
+   * Find User Story file that contains specific task
+   */
+  async findUserStoryFileForTask(livingDocsPath, taskId) {
+    const specsPath = path.join(livingDocsPath, "internal", "specs");
+    const { glob } = await import("glob");
+    const files = await glob("**/us-*.md", { cwd: specsPath, absolute: true });
+    for (const file of files) {
+      const content = await fs.readFile(file, "utf-8");
+      if (content.includes(taskId)) {
+        return file;
+      }
+    }
+    return null;
+  }
+  /**
+   * Update AC in User Story file
+   */
+  async updateUserStoryAc(userStoryPath, acId, completed) {
+    let content = await fs.readFile(userStoryPath, "utf-8");
+    const checkboxState = completed ? "x" : " ";
+    const regex = new RegExp(`(- \\[)[ x](\\] ${acId}:)`, "g");
+    content = content.replace(regex, `$1${checkboxState}$2`);
+    await fs.writeFile(userStoryPath, content, "utf-8");
+  }
+  /**
+   * Update Task in User Story file
+   */
+  async updateUserStoryTask(userStoryPath, taskId, completed) {
+    let content = await fs.readFile(userStoryPath, "utf-8");
+    const checkboxState = completed ? "x" : " ";
+    const regex = new RegExp(`(- \\[)[ x](\\] ${taskId}:)`, "g");
+    content = content.replace(regex, `$1${checkboxState}$2`);
+    await fs.writeFile(userStoryPath, content, "utf-8");
+  }
+  /**
+   * Update multiple ACs in User Story file
+   */
+  async updateUserStoryAcs(userStoryPath, acs) {
+    let content = await fs.readFile(userStoryPath, "utf-8");
+    for (const ac of acs) {
+      const checkboxState = ac.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${ac.id}:)`, "g");
+      content = content.replace(regex, `$1${checkboxState}$2`);
+    }
+    await fs.writeFile(userStoryPath, content, "utf-8");
+  }
+  /**
+   * Update multiple Tasks in User Story file
+   */
+  async updateUserStoryTasks(userStoryPath, tasks) {
+    let content = await fs.readFile(userStoryPath, "utf-8");
+    for (const task of tasks) {
+      const checkboxState = task.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${task.id}:)`, "g");
+      content = content.replace(regex, `$1${checkboxState}$2`);
+    }
+    await fs.writeFile(userStoryPath, content, "utf-8");
+  }
+  /**
+   * Update AC in increment spec.md
+   */
+  async updateIncrementAc(incrementPath, acId, completed) {
+    const specPath = path.join(incrementPath, "spec.md");
+    let content = await fs.readFile(specPath, "utf-8");
+    const checkboxState = completed ? "x" : " ";
+    const regex = new RegExp(`(- \\[)[ x](\\] ${acId}:)`, "g");
+    content = content.replace(regex, `$1${checkboxState}$2`);
+    await fs.writeFile(specPath, content, "utf-8");
+  }
+  /**
+   * Update multiple ACs in increment spec.md
+   */
+  async updateIncrementAcs(incrementPath, acs) {
+    const specPath = path.join(incrementPath, "spec.md");
+    let content = await fs.readFile(specPath, "utf-8");
+    for (const ac of acs) {
+      const checkboxState = ac.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${ac.id}:)`, "g");
+      content = content.replace(regex, `$1${checkboxState}$2`);
+    }
+    await fs.writeFile(specPath, content, "utf-8");
+  }
+  /**
+   * Update multiple Tasks in increment tasks.md
+   */
+  async updateIncrementTasks(incrementPath, tasks) {
+    const tasksPath = path.join(incrementPath, "tasks.md");
+    let content = await fs.readFile(tasksPath, "utf-8");
+    for (const task of tasks) {
+      if (task.completed) {
+        const taskHeader = `### ${task.id}:`;
+        const completedMarker = `**Completed**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`;
+        if (!content.includes(`${taskHeader}`) || !content.includes(`**Completed**`)) {
+          const regex = new RegExp(`(### ${task.id}:[^#]*?)(###|$)`, "s");
+          content = content.replace(regex, `$1
+${completedMarker}
+
+$2`);
+        }
+      }
+    }
+    await fs.writeFile(tasksPath, content, "utf-8");
+  }
+  /**
+   * Update ACs in increment with conflict resolution (Increment wins)
+   *
+   * If GitHub and Increment disagree, Increment state wins as it's the source of truth.
+   * Conflicts are logged for transparency.
+   */
+  async updateIncrementAcsWithConflictResolution(incrementPath, githubAcs, result) {
+    const specPath = path.join(incrementPath, "spec.md");
+    const currentContent = await fs.readFile(specPath, "utf-8");
+    const currentAcs = this.parseAcceptanceCriteria(currentContent);
+    let content = currentContent;
+    for (const githubAc of githubAcs) {
+      const currentAc = currentAcs.find((ac) => ac.id === githubAc.id);
+      if (currentAc && currentAc.completed !== githubAc.completed) {
+        const conflictMsg = `AC ${githubAc.id}: GitHub says ${githubAc.completed ? "complete" : "incomplete"}, Increment says ${currentAc.completed ? "complete" : "incomplete"} \u2192 Increment wins`;
+        result.conflicts.push(conflictMsg);
+        console.log(`\u26A0\uFE0F  CONFLICT RESOLVED: ${conflictMsg}`);
+        continue;
+      }
+      const checkboxState = githubAc.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${githubAc.id}:)`, "g");
+      content = content.replace(regex, `$1${checkboxState}$2`);
+    }
+    await fs.writeFile(specPath, content, "utf-8");
+  }
+  /**
+   * Update Tasks in increment with conflict resolution (Increment wins)
+   */
+  async updateIncrementTasksWithConflictResolution(incrementPath, githubTasks, result) {
+    const tasksPath = path.join(incrementPath, "tasks.md");
+    const currentContent = await fs.readFile(tasksPath, "utf-8");
+    const currentTasks = this.parseTasks(currentContent);
+    let content = currentContent;
+    for (const githubTask of githubTasks) {
+      const currentTask = currentTasks.find((t) => t.id === githubTask.id);
+      if (currentTask && currentTask.completed !== githubTask.completed) {
+        const conflictMsg = `Task ${githubTask.id}: GitHub says ${githubTask.completed ? "complete" : "incomplete"}, Increment says ${currentTask.completed ? "complete" : "incomplete"} \u2192 Increment wins`;
+        result.conflicts.push(conflictMsg);
+        console.log(`\u26A0\uFE0F  CONFLICT RESOLVED: ${conflictMsg}`);
+        continue;
+      }
+      if (githubTask.completed) {
+        const taskHeader = `### ${githubTask.id}:`;
+        const completedMarker = `**Completed**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`;
+        if (!content.includes(`${taskHeader}`) || !content.includes(`**Completed**`)) {
+          const regex = new RegExp(`(### ${githubTask.id}:[^#]*?)(###|$)`, "s");
+          content = content.replace(regex, `$1
+${completedMarker}
+
+$2`);
+        }
+      }
+    }
+    await fs.writeFile(tasksPath, content, "utf-8");
+  }
+  /**
+   * Update GitHub issue with ACs and Tasks
+   */
+  async updateGitHubIssue(issueNumber, acs, tasks) {
+    const result = await execFileNoThrow("gh", [
+      "issue",
+      "view",
+      String(issueNumber),
+      "--json",
+      "body"
+    ]);
+    const { body } = JSON.parse(result.stdout);
+    let updatedBody = body;
+    for (const ac of acs) {
+      const checkboxState = ac.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${ac.id}:)`, "g");
+      updatedBody = updatedBody.replace(regex, `$1${checkboxState}$2`);
+    }
+    for (const task of tasks) {
+      const checkboxState = task.completed ? "x" : " ";
+      const regex = new RegExp(`(- \\[)[ x](\\] ${task.id}:)`, "g");
+      updatedBody = updatedBody.replace(regex, `$1${checkboxState}$2`);
+    }
+    await execFileNoThrow("gh", [
+      "issue",
+      "edit",
+      String(issueNumber),
+      "--body",
+      updatedBody
+    ]);
+  }
+  /**
+   * Add comment to GitHub issue
+   */
+  async addGitHubComment(issueNumber, comment) {
+    await execFileNoThrow("gh", [
+      "issue",
+      "comment",
+      String(issueNumber),
+      "--body",
+      comment
+    ]);
+  }
+}
+export {
+  ThreeLayerSyncManager
+};