specweave 0.16.7 → 0.16.12

package/plugins/specweave-ado/lib/ado-spec-commit-sync.js

@@ -0,0 +1,210 @@
+/**
+ * Azure DevOps Spec Commit Sync
+ *
+ * Posts commit/PR comments to ADO work items linked to living docs specs.
+ * This enables traceability from spec user stories to actual code changes.
+ */
+import { getRecentCommits, detectRepository, getCommitUrl, findPRForCommit, getLastSyncCommit, updateLastSyncCommit, } from '../../../src/utils/git-utils.js';
+import { getSpecTaskMapping, getCompletedUserStories, } from '../../../src/core/spec-task-mapper.js';
+import { buildUserStoryComment, buildCommitBatchComment, buildShortComment, generateSmartSummary, formatForAdo, } from '../../../src/core/comment-builder.js';
+import path from 'path';
+import fs from 'fs/promises';
+/**
+ * Sync commits for completed user stories to ADO work item
+ */
+export async function syncSpecCommitsToAdo(client, options) {
+    const { incrementPath, dryRun = false, verbose = false } = options;
+    const result = {
+        success: true,
+        commentsPosted: 0,
+        errors: [],
+        commits: [],
+        userStories: [],
+    };
+    try {
+        // 1. Check if increment has ADO work item linked
+        const metadataPath = path.join(incrementPath, 'metadata.json');
+        let metadata;
+        try {
+            metadata = JSON.parse(await fs.readFile(metadataPath, 'utf-8'));
+        }
+        catch {
+            result.errors.push('No metadata.json found');
+            return result;
+        }
+        const adoWorkItemId = metadata.ado?.workItemId;
+        if (!adoWorkItemId) {
+            if (verbose) {
+                console.log('No ADO work item linked to increment');
+            }
+            return result;
+        }
+        // 2. Detect repository
+        const repo = await detectRepository('origin', incrementPath);
+        if (!repo) {
+            result.errors.push('Git repository not found');
+            result.success = false;
+            return result;
+        }
+        // 3. Get spec-task mapping
+        const mapping = await getSpecTaskMapping(incrementPath);
+        if (!mapping) {
+            if (verbose) {
+                console.log('No spec mapping found for increment');
+            }
+            return result;
+        }
+        // 4. 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;
+        // 5. 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);
+        }
+        // 6. 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 = [];
+                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 = {
+                    userStory,
+                    tasks: relatedTasks,
+                    commits,
+                    pullRequests,
+                    summary,
+                };
+                const formattedComment = buildUserStoryComment(commentContent, repo);
+                const adoComment = formatForAdo(formattedComment);
+                if (verbose) {
+                    console.log(`\nComment for ${userStory.id} (ADO format):`);
+                    console.log(adoComment);
+                    console.log('\n---\n');
+                }
+                // Post comment to ADO
+                if (!dryRun) {
+                    await client.addComment(adoWorkItemId, adoComment);
+                    result.commentsPosted++;
+                }
+                else {
+                    result.commentsPosted++;
+                }
+            }
+            catch (error) {
+                result.errors.push(`Failed to post comment for ${userStory.id}: ${error.message}`);
+            }
+        }
+        // 7. 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 adoComment = formatForAdo(formattedComment);
+                if (verbose) {
+                    console.log(`\nShort update comment (ADO format):`);
+                    console.log(adoComment);
+                    console.log('\n---\n');
+                }
+                if (!dryRun) {
+                    await client.addComment(adoWorkItemId, adoComment);
+                    result.commentsPosted++;
+                }
+                else {
+                    result.commentsPosted++;
+                }
+            }
+            catch (error) {
+                result.errors.push(`Failed to post short update: ${error.message}`);
+            }
+        }
+        // 8. Update last sync commit
+        if (!dryRun && commits.length > 0) {
+            await updateLastSyncCommit(metadataPath, commits[0].sha);
+        }
+    }
+    catch (error) {
+        result.success = false;
+        result.errors.push(error.message);
+    }
+    return result;
+}
+/**
+ * Post batch commit update to ADO work item
+ */
+export async function postCommitBatchUpdate(client, incrementPath, commits, workItemId, repo, dryRun = false) {
+    try {
+        // Add commit URLs
+        for (const commit of commits) {
+            commit.url = getCommitUrl(commit, repo);
+        }
+        // Build and post comment
+        const formattedComment = buildCommitBatchComment(commits, repo, true);
+        const adoComment = formatForAdo(formattedComment);
+        if (!dryRun) {
+            await client.addComment(workItemId, adoComment);
+        }
+        return true;
+    }
+    catch (error) {
+        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) {
+    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 ADO work item ID from spec metadata
+ */
+export async function getAdoWorkItemForSpec(specPath) {
+    try {
+        const content = await fs.readFile(specPath, 'utf-8');
+        // Extract ADO work item from frontmatter or body
+        // Pattern: **ADO Feature**: #12345
+        const match = content.match(/\*\*ADO Feature\*\*:\s*#?(\d+)/);
+        return match ? parseInt(match[1], 10) : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=ado-spec-commit-sync.js.map

package/plugins/specweave-ado/lib/ado-spec-commit-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ado-spec-commit-sync.js","sourceRoot":"","sources":["ado-spec-commit-sync.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,288 @@
+/**
+ * Azure DevOps Spec Commit Sync
+ *
+ * Posts commit/PR comments to ADO work items linked to living docs specs.
+ * This enables traceability from spec user stories to actual code changes.
+ */
+
+import { AdoClientV2 } from './ado-client-v2.js';
+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,
+  formatForAdo,
+  CommentContent,
+} from '../../../src/core/comment-builder.js';
+import path from 'path';
+import fs from 'fs/promises';
+
+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 ADO work item
+ */
+export async function syncSpecCommitsToAdo(
+  client: AdoClientV2,
+  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 ADO work item 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 adoWorkItemId = metadata.ado?.workItemId;
+    if (!adoWorkItemId) {
+      if (verbose) {
+        console.log('No ADO work item linked to increment');
+      }
+      return result;
+    }
+
+    // 2. Detect repository
+    const repo = await detectRepository('origin', incrementPath);
+    if (!repo) {
+      result.errors.push('Git repository not found');
+      result.success = false;
+      return result;
+    }
+
+    // 3. Get spec-task mapping
+    const mapping = await getSpecTaskMapping(incrementPath);
+    if (!mapping) {
+      if (verbose) {
+        console.log('No spec mapping found for increment');
+      }
+      return result;
+    }
+
+    // 4. 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;
+
+    // 5. 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);
+    }
+
+    // 6. 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 adoComment = formatForAdo(formattedComment);
+
+        if (verbose) {
+          console.log(`\nComment for ${userStory.id} (ADO format):`);
+          console.log(adoComment);
+          console.log('\n---\n');
+        }
+
+        // Post comment to ADO
+        if (!dryRun) {
+          await client.addComment(adoWorkItemId, adoComment);
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error: any) {
+        result.errors.push(`Failed to post comment for ${userStory.id}: ${error.message}`);
+      }
+    }
+
+    // 7. 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 adoComment = formatForAdo(formattedComment);
+
+        if (verbose) {
+          console.log(`\nShort update comment (ADO format):`);
+          console.log(adoComment);
+          console.log('\n---\n');
+        }
+
+        if (!dryRun) {
+          await client.addComment(adoWorkItemId, adoComment);
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error: any) {
+        result.errors.push(`Failed to post short update: ${error.message}`);
+      }
+    }
+
+    // 8. 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 ADO work item
+ */
+export async function postCommitBatchUpdate(
+  client: AdoClientV2,
+  incrementPath: string,
+  commits: GitCommit[],
+  workItemId: number,
+  repo: GitRepository,
+  dryRun: boolean = false
+): Promise<boolean> {
+  try {
+    // Add commit URLs
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+
+    // Build and post comment
+    const formattedComment = buildCommitBatchComment(commits, repo, true);
+    const adoComment = formatForAdo(formattedComment);
+
+    if (!dryRun) {
+      await client.addComment(workItemId, adoComment);
+    }
+
+    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 ADO work item ID from spec metadata
+ */
+export async function getAdoWorkItemForSpec(
+  specPath: string
+): Promise<number | null> {
+  try {
+    const content = await fs.readFile(specPath, 'utf-8');
+
+    // Extract ADO work item from frontmatter or body
+    // Pattern: **ADO Feature**: #12345
+    const match = content.match(/\*\*ADO Feature\*\*:\s*#?(\d+)/);
+
+    return match ? parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}