specweave 0.18.1 → 0.20.0

package/plugins/specweave-github/lib/user-story-issue-builder.js

@@ -0,0 +1,344 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class UserStoryIssueBuilder {
+  constructor(userStoryPath, projectRoot, featureId, repoInfo) {
+    this.userStoryPath = userStoryPath;
+    this.projectRoot = projectRoot;
+    this.featureId = featureId;
+    this.repoOwner = repoInfo?.owner;
+    this.repoName = repoInfo?.repo;
+    this.branch = repoInfo?.branch || "develop";
+  }
+  /**
+   * Build GitHub issue body for a single User Story
+   *
+   * Format:
+   * - User Story statement
+   * - Acceptance Criteria (checkboxes)
+   * - Tasks (checkboxes)
+   * - Links (Feature, Increment, Spec file)
+   */
+  async buildIssueBody() {
+    const frontmatter = await this.readUserStoryFrontmatter();
+    const content = await readFile(this.userStoryPath, "utf-8");
+    const bodyContent = content.slice(content.indexOf("---", 3) + 3).trim();
+    const userStoryStatement = this.extractUserStoryStatement(bodyContent);
+    const acceptanceCriteria = this.extractAcceptanceCriteria(bodyContent);
+    const tasks = await this.extractTasks(bodyContent, frontmatter.id);
+    const title = `[${this.featureId}][${frontmatter.id}] ${frontmatter.title}`;
+    const body = this.buildBody({
+      frontmatter,
+      userStoryStatement,
+      acceptanceCriteria,
+      tasks,
+      bodyContent
+    });
+    const labels = this.buildLabels(frontmatter);
+    return {
+      title,
+      body,
+      labels,
+      userStoryId: frontmatter.id
+    };
+  }
+  /**
+   * Read User Story frontmatter
+   */
+  async readUserStoryFrontmatter() {
+    const content = await readFile(this.userStoryPath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error(`${this.userStoryPath}: Missing YAML frontmatter`);
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Extract "As a... I want... So that..." statement
+   */
+  extractUserStoryStatement(content) {
+    const userStoryMatch = content.match(
+      /##\s*User Story\s*\n+([\s\S]*?)(?=\n##|$)/i
+    );
+    if (userStoryMatch) {
+      return userStoryMatch[1].trim();
+    }
+    const asAMatch = content.match(/(\*\*As a\*\*[\s\S]*?\*\*So that\*\*[^\n]*)/i);
+    if (asAMatch) {
+      return asAMatch[1].trim();
+    }
+    return "";
+  }
+  /**
+   * Extract Acceptance Criteria with AC-IDs and checkbox state
+   */
+  extractAcceptanceCriteria(content) {
+    const criteria = [];
+    const acMatch = content.match(
+      /##\s*Acceptance Criteria\s*\n+([\s\S]*?)(?=\n##|$)/i
+    );
+    if (!acMatch) {
+      return criteria;
+    }
+    const acSection = acMatch[1];
+    const acPatternWithCheckbox = /(?:^|\n)\s*[-*]\s+\[([x ])\]\s+\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+    const acPatternNoCheckbox = /(?:^|\n)\s*[-*]?\s*\*\*([A-Z]+-(?:[A-Z]+\d+-)?(\d+))\*\*:\s*([^\n]+)/g;
+    let match;
+    let foundAny = false;
+    while ((match = acPatternWithCheckbox.exec(acSection)) !== null) {
+      foundAny = true;
+      criteria.push({
+        id: match[2],
+        // e.g., "AC-US1-01" or "AC-001"
+        description: match[4].trim(),
+        completed: match[1] === "x"
+        // ✅ Read checkbox state from source!
+      });
+    }
+    if (!foundAny) {
+      while ((match = acPatternNoCheckbox.exec(acSection)) !== null) {
+        criteria.push({
+          id: match[1],
+          // e.g., "AC-US1-01" or "AC-001"
+          description: match[3].trim(),
+          completed: false
+          // Default to not completed
+        });
+      }
+    }
+    return criteria;
+  }
+  /**
+   * Extract tasks from user story's ## Tasks section (NEW architecture)
+   *
+   * Previously: Read from increment tasks.md (LEGACY)
+   * Now: Read from user story's ## Tasks section directly
+   *
+   * This enables project-specific tasks with completion tracking per user story.
+   */
+  async extractTasks(userStoryContent, userStoryId) {
+    const tasks = [];
+    const tasksMatch = userStoryContent.match(
+      /##\s+Tasks\s*\n+([\s\S]*?)(?=\n##|>?\s*\*\*Note\*\*:|---+|$)/i
+    );
+    if (!tasksMatch) {
+      console.log(`   \u2139\uFE0F  No ## Tasks section found in ${userStoryId}, falling back to legacy extraction`);
+      return this.extractTasksLegacy(userStoryContent, userStoryId);
+    }
+    const tasksSection = tasksMatch[1];
+    const taskPattern = /^[-*]\s+\[([x ])\]\s+\*\*(T-\d+)\*\*:\s+(.+)$/gm;
+    let match;
+    while ((match = taskPattern.exec(tasksSection)) !== null) {
+      const completed = match[1] === "x";
+      const taskId = match[2];
+      const taskTitle = match[3].trim();
+      tasks.push({
+        id: taskId,
+        title: taskTitle,
+        completed
+        // ✅ Read checkbox state directly from user story!
+      });
+    }
+    return tasks;
+  }
+  /**
+   * LEGACY: Extract tasks from increment's tasks.md (backward compatibility)
+   *
+   * Used as fallback when user story file doesn't have ## Tasks section.
+   */
+  async extractTasksLegacy(userStoryContent, userStoryId) {
+    const tasks = [];
+    const implMatch = userStoryContent.match(
+      /##\s*Implementation\s*\n+([\s\S]*?)(?=\n##|$)/i
+    );
+    if (!implMatch) {
+      return tasks;
+    }
+    const implSection = implMatch[1];
+    const incrementMatch = implSection.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+    if (!incrementMatch) {
+      return tasks;
+    }
+    const incrementId = incrementMatch[1];
+    const tasksPath = path.join(
+      this.projectRoot,
+      ".specweave",
+      "increments",
+      incrementId,
+      "tasks.md"
+    );
+    if (!existsSync(tasksPath)) {
+      return tasks;
+    }
+    const tasksContent = await readFile(tasksPath, "utf-8");
+    const taskPattern = /###?\s+(T-\d+):\s*([^\n]+)\n([\s\S]*?)(?=\n###?\s+T-\d+:|$)/g;
+    let match;
+    while ((match = taskPattern.exec(tasksContent)) !== null) {
+      const taskId = match[1];
+      const taskTitle = match[2].trim();
+      const taskBody = match[3];
+      const acMatch = taskBody.match(/\*\*AC\*\*:\s*([^\n]+)/);
+      if (!acMatch) {
+        continue;
+      }
+      const acList = acMatch[1].trim();
+      const belongsToThisUS = acList.split(",").map((ac) => ac.trim()).some((acId) => {
+        const usMatch = acId.match(/AC-([A-Z]+\d+)-/);
+        if (!usMatch) return false;
+        return usMatch[1] === userStoryId.replace("US-", "US");
+      });
+      if (!belongsToThisUS) {
+        continue;
+      }
+      const statusMatch = taskBody.match(/\*\*Status\*\*:\s*\[([x ])\]/);
+      const completed = statusMatch ? statusMatch[1] === "x" : false;
+      tasks.push({
+        id: taskId,
+        title: taskTitle,
+        completed
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Build complete issue body
+   */
+  buildBody(data) {
+    const sections = [];
+    sections.push(`**Feature**: ${this.featureId}`);
+    sections.push(`**Status**: ${this.capitalize(data.frontmatter.status)}`);
+    sections.push(`**Priority**: ${data.frontmatter.priority || "P2"}`);
+    if (data.frontmatter.project && data.frontmatter.project !== "default") {
+      sections.push(`**Project**: ${data.frontmatter.project}`);
+    }
+    sections.push("");
+    if (data.userStoryStatement) {
+      sections.push("## User Story");
+      sections.push("");
+      sections.push(data.userStoryStatement);
+      sections.push("");
+    }
+    if (data.acceptanceCriteria.length > 0) {
+      sections.push("## Acceptance Criteria");
+      sections.push("");
+      for (const ac of data.acceptanceCriteria) {
+        const checkbox = ac.completed ? "[x]" : "[ ]";
+        sections.push(`- ${checkbox} **${ac.id}**: ${ac.description}`);
+      }
+      sections.push("");
+    }
+    if (data.tasks.length > 0) {
+      sections.push("## Tasks");
+      sections.push("");
+      for (const task of data.tasks) {
+        const checkbox = task.completed ? "[x]" : "[ ]";
+        sections.push(`- ${checkbox} **${task.id}**: ${task.title}`);
+      }
+      sections.push("");
+    }
+    const rationaleMatch = data.bodyContent.match(
+      /##\s*Business Rationale\s*\n+([\s\S]*?)(?=\n##|$)/i
+    );
+    if (rationaleMatch) {
+      sections.push("## Business Rationale");
+      sections.push("");
+      sections.push(rationaleMatch[1].trim());
+      sections.push("");
+    }
+    const relatedMatch = data.bodyContent.match(
+      /##\s*Related User Stories\s*\n+([\s\S]*?)(?=\n##|---+|$)/i
+    );
+    if (relatedMatch) {
+      sections.push("## Related User Stories");
+      sections.push("");
+      let relatedContent = relatedMatch[1].trim();
+      if (this.repoOwner && this.repoName) {
+        const baseUrl = `https://github.com/${this.repoOwner}/${this.repoName}/blob/${this.branch}`;
+        relatedContent = relatedContent.replace(
+          /\(([^)]+\.md)\)/g,
+          (match, filename) => {
+            if (filename.startsWith("http")) {
+              return match;
+            }
+            const projectMatch = this.userStoryPath.match(/\/specs\/([^/]+)\/FS-[^/]+\//);
+            const project = projectMatch ? projectMatch[1] : "default";
+            const featureId = this.featureId;
+            return `(${baseUrl}/.specweave/docs/internal/specs/${project}/${featureId}/${filename})`;
+          }
+        );
+      }
+      sections.push(relatedContent);
+      sections.push("");
+    }
+    const implMatch = data.bodyContent.match(
+      /##\s*Implementation\s*\n+([\s\S]*?)(?=\n##|$)/i
+    );
+    if (implMatch) {
+      sections.push("## Implementation");
+      sections.push("");
+      let implContent = implMatch[1].trim();
+      if (this.repoOwner && this.repoName) {
+        const baseUrl = `https://github.com/${this.repoOwner}/${this.repoName}/blob/${this.branch}`;
+        implContent = implContent.replace(
+          /\.\.(\/\.\.)+\/increments\/([\w-]+)\/([\w.-]+(?:#[\w-]+)?)/g,
+          `${baseUrl}/.specweave/increments/$2/$3`
+        );
+        implContent = implContent.replace(
+          /\.\.(\/\.\.)+\/specs\/([\w-]+)\/([\w-]+)\/([\w.-]+(?:#[\w-]+)?)/g,
+          `${baseUrl}/.specweave/docs/internal/specs/$2/$3/$4`
+        );
+      }
+      sections.push(implContent);
+      sections.push("");
+    }
+    sections.push("---");
+    sections.push("");
+    sections.push("## Links");
+    sections.push("");
+    if (this.repoOwner && this.repoName) {
+      const baseUrl = `https://github.com/${this.repoOwner}/${this.repoName}/blob/${this.branch}`;
+      sections.push(`- **Feature Spec**: [${this.featureId}](${baseUrl}/.specweave/docs/internal/specs/_features/${this.featureId}/FEATURE.md)`);
+      const relativeUSPath = path.relative(this.projectRoot, this.userStoryPath);
+      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${baseUrl}/${relativeUSPath})`);
+      const incrementMatch = implMatch?.[1]?.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      if (incrementMatch) {
+        const incrementId = incrementMatch[1];
+        sections.push(`- **Increment**: [${incrementId}](${baseUrl}/.specweave/increments/${incrementId})`);
+      }
+    } else {
+      sections.push(`- **Feature Spec**: [${this.featureId}](../.specweave/docs/internal/specs/_features/${this.featureId}/FEATURE.md)`);
+      sections.push(`- **User Story File**: [${path.basename(this.userStoryPath)}](${this.userStoryPath})`);
+    }
+    sections.push("");
+    sections.push("---");
+    sections.push("");
+    sections.push("\u{1F916} Auto-created by SpecWeave User Story Sync | Updates automatically");
+    return sections.join("\n");
+  }
+  /**
+   * Build labels for the issue
+   */
+  buildLabels(frontmatter) {
+    const labels = ["user-story", "specweave"];
+    if (frontmatter.status) {
+      labels.push(`status:${frontmatter.status}`);
+    }
+    if (frontmatter.priority) {
+      labels.push(frontmatter.priority.toLowerCase());
+    }
+    if (frontmatter.project && frontmatter.project !== "default") {
+      labels.push(`project:${frontmatter.project}`);
+    }
+    return labels;
+  }
+  /**
+   * Capitalize first letter
+   */
+  capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
+}
+export {
+  UserStoryIssueBuilder
+};