specweave 0.17.0 → 0.17.2

package/plugins/specweave-jira/lib/jira-spec-commit-sync.ts

@@ -0,0 +1,368 @@
+/**
+ * JIRA Spec Commit Sync
+ *
+ * Posts commit/PR comments to JIRA issues linked to living docs specs.
+ * This enables traceability from spec user stories to actual code changes.
+ */
+
+import axios, { AxiosInstance } from 'axios';
+import {
+  getRecentCommits,
+  detectRepository,
+  getCommitUrl,
+  findPRForCommit,
+  getLastSyncCommit,
+  updateLastSyncCommit,
+  GitCommit,
+  GitRepository,
+  PullRequest,
+} from '../../../src/utils/git-utils.js';
+import {
+  getSpecTaskMapping,
+  getCompletedUserStories,
+  SpecTaskMapping,
+  UserStory,
+} from '../../../src/core/spec-task-mapper.js';
+import {
+  buildUserStoryComment,
+  buildCommitBatchComment,
+  buildShortComment,
+  generateSmartSummary,
+  formatForJira,
+  CommentContent,
+} from '../../../src/core/comment-builder.js';
+import path from 'path';
+import fs from 'fs/promises';
+
+export interface JiraConfig {
+  domain: string;
+  email: string;
+  apiToken: string;
+  projectKey: string;
+}
+
+export interface SyncOptions {
+  incrementPath: string;
+  dryRun?: boolean;
+  verbose?: boolean;
+}
+
+export interface SyncResult {
+  success: boolean;
+  commentsPosted: number;
+  errors: string[];
+  commits: GitCommit[];
+  userStories: UserStory[];
+}
+
+/**
+ * Sync commits for completed user stories to JIRA epic/story
+ */
+export async function syncSpecCommitsToJira(
+  config: JiraConfig,
+  options: SyncOptions
+): Promise<SyncResult> {
+  const { incrementPath, dryRun = false, verbose = false } = options;
+
+  const result: SyncResult = {
+    success: true,
+    commentsPosted: 0,
+    errors: [],
+    commits: [],
+    userStories: [],
+  };
+
+  try {
+    // 1. Check if increment has JIRA issue linked
+    const metadataPath = path.join(incrementPath, 'metadata.json');
+    let metadata: any;
+
+    try {
+      metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+    } catch {
+      result.errors.push('No metadata.json found');
+      return result;
+    }
+
+    const jiraIssueKey = metadata.jira?.issueKey;
+    if (!jiraIssueKey) {
+      if (verbose) {
+        console.log('No JIRA issue linked to increment');
+      }
+      return result;
+    }
+
+    // 2. Create JIRA client
+    const client = axios.create({
+      baseURL: `https://${config.domain}/rest/api/3`,
+      auth: {
+        username: config.email,
+        password: config.apiToken,
+      },
+      headers: {
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+      },
+    });
+
+    // 3. Detect repository
+    const repo = await detectRepository('origin', incrementPath);
+    if (!repo) {
+      result.errors.push('Git repository not found');
+      result.success = false;
+      return result;
+    }
+
+    // 4. Get spec-task mapping
+    const mapping = await getSpecTaskMapping(incrementPath);
+    if (!mapping) {
+      if (verbose) {
+        console.log('No spec mapping found for increment');
+      }
+      return result;
+    }
+
+    // 5. Get completed user stories
+    const completedUserStories = getCompletedUserStories(mapping);
+    if (completedUserStories.length === 0) {
+      if (verbose) {
+        console.log('No completed user stories');
+      }
+      return result;
+    }
+
+    result.userStories = completedUserStories;
+
+    // 6. Get recent commits (since last sync)
+    const lastSyncCommit = await getLastSyncCommit(metadataPath);
+    const commits = lastSyncCommit
+      ? await getRecentCommits(undefined, lastSyncCommit, incrementPath)
+      : await getRecentCommits('7.days', undefined, incrementPath);
+
+    if (commits.length === 0) {
+      if (verbose) {
+        console.log('No new commits since last sync');
+      }
+      return result;
+    }
+
+    result.commits = commits;
+
+    // Add commit URLs
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+
+    // 7. Post comments for each completed user story
+    for (const userStory of completedUserStories) {
+      try {
+        // Get tasks for this user story
+        const relatedTasks = mapping.tasks.filter(t =>
+          t.userStories.includes(userStory.id)
+        );
+
+        // Find PRs for commits (optional, best effort)
+        const pullRequests: PullRequest[] = [];
+        if (repo.provider === 'github') {
+          for (const commit of commits.slice(0, 3)) {
+            const pr = await findPRForCommit(commit.sha, repo.owner, repo.repo);
+            if (pr && !pullRequests.find(p => p.number === pr.number)) {
+              pullRequests.push(pr);
+            }
+          }
+        }
+
+        // Build comment
+        const summary = generateSmartSummary(commits, relatedTasks);
+        const commentContent: CommentContent = {
+          userStory,
+          tasks: relatedTasks,
+          commits,
+          pullRequests,
+          summary,
+        };
+
+        const formattedComment = buildUserStoryComment(commentContent, repo);
+        const jiraComment = formatForJira(formattedComment);
+
+        if (verbose) {
+          console.log(`\nComment for ${userStory.id} (JIRA format):`);
+          console.log(jiraComment);
+          console.log('\n---\n');
+        }
+
+        // Post comment to JIRA
+        if (!dryRun) {
+          await client.post(`/issue/${jiraIssueKey}/comment`, {
+            body: {
+              type: 'doc',
+              version: 1,
+              content: [
+                {
+                  type: 'paragraph',
+                  content: [
+                    {
+                      type: 'text',
+                      text: jiraComment,
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error: any) {
+        result.errors.push(`Failed to post comment for ${userStory.id}: ${error.message}`);
+      }
+    }
+
+    // 8. If no user stories completed but there are commits, post a simple update
+    if (completedUserStories.length === 0 && commits.length > 0) {
+      try {
+        const summary = `Work in progress: ${commits.length} commit${commits.length > 1 ? 's' : ''}`;
+        const formattedComment = buildShortComment(commits, repo, summary);
+        const jiraComment = formatForJira(formattedComment);
+
+        if (verbose) {
+          console.log(`\nShort update comment (JIRA format):`);
+          console.log(jiraComment);
+          console.log('\n---\n');
+        }
+
+        if (!dryRun) {
+          await client.post(`/issue/${jiraIssueKey}/comment`, {
+            body: {
+              type: 'doc',
+              version: 1,
+              content: [
+                {
+                  type: 'paragraph',
+                  content: [
+                    {
+                      type: 'text',
+                      text: jiraComment,
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error: any) {
+        result.errors.push(`Failed to post short update: ${error.message}`);
+      }
+    }
+
+    // 9. Update last sync commit
+    if (!dryRun && commits.length > 0) {
+      await updateLastSyncCommit(metadataPath, commits[0].sha);
+    }
+
+  } catch (error: any) {
+    result.success = false;
+    result.errors.push(error.message);
+  }
+
+  return result;
+}
+
+/**
+ * Post batch commit update to JIRA issue
+ */
+export async function postCommitBatchUpdate(
+  config: JiraConfig,
+  incrementPath: string,
+  commits: GitCommit[],
+  issueKey: string,
+  repo: GitRepository,
+  dryRun: boolean = false
+): Promise<boolean> {
+  try {
+    const client = axios.create({
+      baseURL: `https://${config.domain}/rest/api/3`,
+      auth: {
+        username: config.email,
+        password: config.apiToken,
+      },
+      headers: {
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+      },
+    });
+
+    // Add commit URLs
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+
+    // Build and post comment
+    const formattedComment = buildCommitBatchComment(commits, repo, true);
+    const jiraComment = formatForJira(formattedComment);
+
+    if (!dryRun) {
+      await client.post(`/issue/${issueKey}/comment`, {
+        body: {
+          type: 'doc',
+          version: 1,
+          content: [
+            {
+              type: 'paragraph',
+              content: [
+                {
+                  type: 'text',
+                  text: jiraComment,
+                },
+              ],
+            },
+          ],
+        },
+      });
+    }
+
+    return true;
+  } catch (error: any) {
+    console.error(`Failed to post batch update: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Check if spec commit sync is enabled in config
+ */
+export async function isSpecCommitSyncEnabled(
+  projectRoot: string
+): Promise<boolean> {
+  try {
+    const configPath = path.join(projectRoot, '.specweave', 'config.json');
+    const config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
+
+    return config.sync?.settings?.postCommitComments !== false;
+  } catch {
+    return true; // Default: enabled
+  }
+}
+
+/**
+ * Get JIRA issue key from spec metadata
+ */
+export async function getJiraIssueForSpec(
+  specPath: string
+): Promise<string | null> {
+  try {
+    const content = await fs.readFile(specPath, 'utf-8');
+
+    // Extract JIRA issue from frontmatter or body
+    // Pattern: **JIRA Epic**: PROJ-123
+    const match = content.match(/\*\*JIRA Epic\*\*:\s*([A-Z]+-\d+)/);
+
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}

package/plugins/specweave-jira/lib/jira-spec-content-sync.js

@@ -0,0 +1,260 @@
+import axios from "axios";
+import {
+  parseSpecContent,
+  detectContentChanges,
+  hasExternalLink,
+  updateSpecWithExternalLink
+} from "../../../src/core/spec-content-sync.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecContentToJira(options) {
+  const { specPath, config, dryRun = false, verbose = false } = options;
+  try {
+    const spec = await parseSpecContent(specPath);
+    if (!spec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${spec.id}`);
+      console.log(`   Title: ${spec.title}`);
+      console.log(`   User Stories: ${spec.userStories.length}`);
+    }
+    const client = axios.create({
+      baseURL: `https://${config.domain}/rest/api/3`,
+      auth: {
+        username: config.email,
+        password: config.apiToken
+      },
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json"
+      }
+    });
+    const existingEpicKey = await hasExternalLink(specPath, "jira");
+    if (existingEpicKey) {
+      return await updateJiraEpic(client, spec, existingEpicKey, options);
+    } else {
+      return await createJiraEpic(client, spec, options);
+    }
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function createJiraEpic(client, spec, options) {
+  const { specPath, config, dryRun, verbose } = options;
+  try {
+    const summary = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    const description = buildJiraDescription(spec);
+    if (verbose) {
+      console.log(`
+\u{1F4DD} Creating JIRA epic:`);
+      console.log(`   Summary: ${summary}`);
+      console.log(`   Description length: ${description.length} chars`);
+    }
+    if (dryRun) {
+      console.log("\n\u{1F50D} Dry run - would create epic:");
+      console.log(`   Summary: ${summary}`);
+      console.log(`   Description:
+${description}`);
+      return {
+        success: true,
+        action: "created",
+        externalId: "DRY-RUN",
+        externalUrl: `https://${options.config.domain}/browse/DRY-RUN`
+      };
+    }
+    const response = await client.post("/issue", {
+      fields: {
+        project: { key: config.projectKey },
+        summary,
+        description: {
+          type: "doc",
+          version: 1,
+          content: [
+            {
+              type: "paragraph",
+              content: [
+                {
+                  type: "text",
+                  text: description
+                }
+              ]
+            }
+          ]
+        },
+        issuetype: { name: "Epic" },
+        labels: ["specweave", "spec", spec.metadata.priority || "P2"]
+      }
+    });
+    const epicKey = response.data.key;
+    const epicUrl = `https://${config.domain}/browse/${epicKey}`;
+    if (verbose) {
+      console.log(`\u2705 Created epic ${epicKey}`);
+      console.log(`   URL: ${epicUrl}`);
+    }
+    await updateSpecWithExternalLink(specPath, "jira", epicKey, epicUrl);
+    return {
+      success: true,
+      action: "created",
+      externalId: epicKey,
+      externalUrl: epicUrl
+    };
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: `Failed to create JIRA epic: ${error.message}`
+    };
+  }
+}
+async function updateJiraEpic(client, spec, epicKey, options) {
+  const { specPath, config, dryRun, verbose } = options;
+  try {
+    const response = await client.get(`/issue/${epicKey}`);
+    const epic = response.data;
+    if (verbose) {
+      console.log(`
+\u{1F504} Checking for changes in epic ${epicKey}`);
+    }
+    const changes = detectContentChanges(spec, {
+      title: epic.fields.summary.replace(/^\[SPEC-\d+\]\s*/, ""),
+      description: extractTextFromJiraADF(epic.fields.description),
+      userStoryCount: 0
+      // TODO: Parse from description
+    });
+    if (!changes.hasChanges) {
+      if (verbose) {
+        console.log("   \u2139\uFE0F  No changes detected");
+      }
+      return {
+        success: true,
+        action: "no-change",
+        externalId: epicKey,
+        externalUrl: `https://${config.domain}/browse/${epicKey}`
+      };
+    }
+    if (verbose) {
+      console.log("   \u{1F4DD} Changes detected:");
+      for (const change of changes.changes) {
+        console.log(`      - ${change}`);
+      }
+    }
+    const newSummary = `[${spec.id.toUpperCase()}] ${spec.title}`;
+    const newDescription = buildJiraDescription(spec);
+    if (dryRun) {
+      console.log("\n\u{1F50D} Dry run - would update epic:");
+      console.log(`   Summary: ${newSummary}`);
+      console.log(`   Description:
+${newDescription}`);
+      return {
+        success: true,
+        action: "updated",
+        externalId: epicKey,
+        externalUrl: `https://${config.domain}/browse/${epicKey}`
+      };
+    }
+    await client.put(`/issue/${epicKey}`, {
+      fields: {
+        summary: newSummary,
+        description: {
+          type: "doc",
+          version: 1,
+          content: [
+            {
+              type: "paragraph",
+              content: [
+                {
+                  type: "text",
+                  text: newDescription
+                }
+              ]
+            }
+          ]
+        }
+      }
+    });
+    if (verbose) {
+      console.log(`\u2705 Updated epic ${epicKey}`);
+    }
+    return {
+      success: true,
+      action: "updated",
+      externalId: epicKey,
+      externalUrl: `https://${config.domain}/browse/${epicKey}`
+    };
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: `Failed to update JIRA epic: ${error.message}`
+    };
+  }
+}
+function buildJiraDescription(spec) {
+  let description = "";
+  if (spec.description) {
+    description += spec.description + "\n\n";
+  }
+  if (spec.userStories.length > 0) {
+    description += "h2. User Stories\n\n";
+    for (const us of spec.userStories) {
+      description += `h3. ${us.id}: ${us.title}
+
+`;
+      if (us.acceptanceCriteria.length > 0) {
+        description += "*Acceptance Criteria:*\n";
+        for (const ac of us.acceptanceCriteria) {
+          const checkbox = ac.completed ? "(/)" : "(x)";
+          description += `* ${checkbox} ${ac.id}: ${ac.description}
+`;
+        }
+        description += "\n";
+      }
+    }
+  }
+  if (spec.metadata.priority) {
+    description += `
+*Priority:* ${spec.metadata.priority}
+`;
+  }
+  return description;
+}
+function extractTextFromJiraADF(adf) {
+  if (!adf || !adf.content) {
+    return "";
+  }
+  let text = "";
+  function traverse(node) {
+    if (node.type === "text") {
+      text += node.text;
+    }
+    if (node.content) {
+      for (const child of node.content) {
+        traverse(child);
+      }
+    }
+  }
+  traverse(adf);
+  return text.trim();
+}
+async function isContentSyncEnabled(projectRoot) {
+  try {
+    const configPath = path.join(projectRoot, ".specweave", "config.json");
+    const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+    return config.sync?.settings?.syncSpecContent !== false;
+  } catch {
+    return true;
+  }
+}
+export {
+  isContentSyncEnabled,
+  syncSpecContentToJira
+};