specweave 0.33.2 → 0.33.4

package/dist/src/sync/sync-coordinator.js

@@ -16,6 +16,8 @@ import { autoDetectProjectIdSync } from '../utils/project-detection.js';
 import { UserStoryContentBuilder } from '../../plugins/specweave-github/lib/user-story-content-builder.js';
 import { AdoClient } from '../integrations/ado/ado-client.js';
 import { getAdoPat } from '../integrations/ado/ado-pat-provider.js';
+import { deriveFeatureId } from '../utils/feature-id-derivation.js';
+import { createClosureMetrics } from './closure-metrics.js';
 export class SyncCoordinator {
     constructor(options) {
         this.projectRoot = options.projectRoot;
@@ -26,6 +28,23 @@ export class SyncCoordinator {
         this.projectId = autoDetectProjectIdSync(this.projectRoot, { silent: true });
         // Store resolved ADO profile for multi-project sync
         this.adoProfile = options.adoProfile;
+        // Initialize closure metrics (v0.34.0)
+        this.metrics = createClosureMetrics(this.projectRoot, this.incrementId, this.logger);
+    }
+    /**
+     * Get closure sync metrics summary (v0.34.0)
+     *
+     * Returns aggregated metrics for all external tool closure operations.
+     * Useful for monitoring and alerting on sync health.
+     */
+    getClosureMetrics() {
+        return this.metrics.getSummary();
+    }
+    /**
+     * Get formatted closure metrics for display (v0.34.0)
+     */
+    getFormattedClosureMetrics() {
+        return this.metrics.formatSummary();
     }
     /**
      * Create GitHub issues for all User Stories in the feature (NEW in v0.25.0)
@@ -70,13 +89,14 @@ export class SyncCoordinator {
                 }
             }
             if (!featureId) {
-                // AUTO-GENERATE feature ID from increment number (ADR-0139)
-                const incrementMatch = this.incrementId.match(/^(\d+)/);
-                if (incrementMatch) {
-                    featureId = `FS-${incrementMatch[1]}`;
+                // AUTO-GENERATE feature ID using deriveFeatureId() (ADR-0139)
+                // CRITICAL FIX (v0.34.0): Must use deriveFeatureId() to get correct format (FS-128, not FS-0128)
+                // The old code used raw regex match which preserved leading zeros, causing duplicates
+                try {
+                    featureId = deriveFeatureId(this.incrementId);
                     this.logger.log(`📝 Auto-generated feature ID: ${featureId} (no epic/feature_id in spec.md)`);
                 }
-                else {
+                catch {
                     this.logger.log('⚠️  No feature ID found and could not auto-generate - skipping GitHub sync');
                     this.logger.log('   💡 Add epic: FS-XXX or feature_id: FS-XXX to spec.md frontmatter');
                     return createdIssues;
@@ -189,7 +209,32 @@ export class SyncCoordinator {
                         }
                         continue;
                     }
-                    // All 3 layers miss - create new issue
+                    // All 3 layers miss - but check for DUPLICATES with wrong format first!
+                    // ========================================================================
+                    // DUPLICATE DETECTION (v0.34.0): Prevent FS-0128 vs FS-128 duplicates
+                    // ========================================================================
+                    // Before creating, search for issues with similar titles but different feature ID formats.
+                    // This catches cases where an old bug created issues with leading zeros (FS-0128)
+                    // but the correct format is without (FS-128).
+                    const duplicateCheck = await this.detectDuplicateIssue(client, featureId, usFile.id);
+                    if (duplicateCheck) {
+                        this.logger.log(`  ⚠️  DUPLICATE DETECTED: Issue #${duplicateCheck.number} exists with format "${duplicateCheck.format}"`);
+                        this.logger.log(`     Current format: [${featureId}][${usFile.id}]`);
+                        this.logger.log(`     Existing issue: ${duplicateCheck.title}`);
+                        this.logger.log(`     ⏭️  Skipping creation to avoid duplicate. Use existing issue #${duplicateCheck.number}`);
+                        // Backfill metadata with the existing issue (even if wrong format)
+                        await this.frontmatterUpdater.updateUserStoryFrontmatter({
+                            projectRoot: this.projectRoot,
+                            featureId,
+                            userStoryId: usFile.id,
+                            githubIssue: {
+                                number: duplicateCheck.number,
+                                url: duplicateCheck.url,
+                                createdAt: new Date().toISOString(),
+                            },
+                        });
+                        continue;
+                    }
                     this.logger.log(`  📝 Creating GitHub issue for ${usFile.id}...`);
                     // Format issue body - use UserStoryContentBuilder for rich content with ACs
                     let issueBody;
@@ -323,13 +368,13 @@ export class SyncCoordinator {
                 }
             }
             if (!featureId) {
-                // AUTO-GENERATE feature ID from increment number (same logic as create)
-                const incrementMatch = this.incrementId.match(/^(\d+)/);
-                if (incrementMatch) {
-                    featureId = `FS-${incrementMatch[1]}`;
+                // AUTO-GENERATE feature ID using deriveFeatureId() (same logic as create)
+                // CRITICAL FIX (v0.34.0): Must use deriveFeatureId() to get correct format (FS-128, not FS-0128)
+                try {
+                    featureId = deriveFeatureId(this.incrementId);
                     this.logger.log(`📝 Auto-generated feature ID: ${featureId}`);
                 }
-                else {
+                catch {
                     this.logger.log('⚠️  No feature ID found - skipping GitHub issue closure');
                     return closedIssues;
                 }
@@ -338,14 +383,16 @@ export class SyncCoordinator {
             for (const usFile of userStories) {
                 try {
                     // Search for the GitHub issue by title pattern
+                    // v0.34.0: includeClosedIssues=true to correctly detect already-closed issues
+                    // Without this, we'd report "No issue found" instead of "already closed"
                     const searchTitle = `[${featureId}][${usFile.id}]`;
-                    const existingIssue = await client.searchIssueByTitle(searchTitle);
+                    const existingIssue = await client.searchIssueByTitle(searchTitle, true);
                     if (!existingIssue) {
                         this.logger.log(`  ⏭️  ${usFile.id} - No GitHub issue found (skipping)`);
                         continue;
                     }
-                    // Check if already closed (GitHub returns lowercase state)
-                    if (existingIssue.state === 'closed') {
+                    // Check if already closed (GitHub API returns UPPERCASE: "OPEN" or "CLOSED")
+                    if (existingIssue.state.toLowerCase() === 'closed') {
                         this.logger.log(`  ⏭️  ${usFile.id} - Issue #${existingIssue.number} already closed`);
                         continue;
                     }
@@ -365,9 +412,18 @@ Increment \`${this.incrementId}\` has been marked as **completed**.
 
 ---
 🤖 Auto-closed by SpecWeave on increment completion`;
-                    await client.closeIssue(existingIssue.number, completionComment);
-                    closedIssues.push(existingIssue.number);
-                    this.logger.log(`  ✅ Closed issue #${existingIssue.number}`);
+                    // Track metrics (v0.34.0)
+                    this.metrics.startOperation();
+                    try {
+                        await client.closeIssue(existingIssue.number, completionComment);
+                        closedIssues.push(existingIssue.number);
+                        this.metrics.recordClosure('github', existingIssue.number, true);
+                        this.logger.log(`  ✅ Closed issue #${existingIssue.number}`);
+                    }
+                    catch (closeError) {
+                        this.metrics.recordClosure('github', existingIssue.number, false, String(closeError));
+                        throw closeError;
+                    }
                 }
                 catch (error) {
                     this.logger.error(`  ❌ Failed to close issue for ${usFile.id}:`, error);
@@ -386,6 +442,186 @@ Increment \`${this.incrementId}\` has been marked as **completed**.
             throw error;
         }
     }
+    /**
+     * Close JIRA issues for completed user stories (v0.34.0)
+     *
+     * Transitions JIRA issues to "Done" status when increment is completed.
+     * Reads issue references from user story frontmatter (external.jira.issue_key).
+     *
+     * @param config - Project config with JIRA settings
+     * @returns Number of closed JIRA issues
+     */
+    async closeJiraIssuesForUserStories(config) {
+        let closedCount = 0;
+        try {
+            const userStories = await this.loadUserStoriesForIncrement();
+            this.logger.log(`📚 Found ${userStories.length} user stor${userStories.length === 1 ? 'y' : 'ies'} for JIRA closure`);
+            if (userStories.length === 0) {
+                return 0;
+            }
+            // Get JIRA config
+            const jiraConfig = config.sync?.jira;
+            if (!jiraConfig?.domain || !jiraConfig?.email) {
+                this.logger.log('⚠️  JIRA config incomplete (missing domain or email)');
+                return 0;
+            }
+            // Import JIRA client dynamically to avoid circular deps
+            // JiraClient uses credentialsManager internally to get credentials from env
+            const { JiraClient } = await import('../integrations/jira/jira-client.js');
+            const jiraClient = new JiraClient();
+            // Target status for completion (configurable via statusSync.mappings.jira.completed)
+            const targetStatus = config.sync?.statusSync?.mappings?.jira?.completed || 'Done';
+            for (const usFile of userStories) {
+                try {
+                    // Check if US has JIRA reference in frontmatter (key not issue_key per type def)
+                    const jiraKey = usFile.external_tools?.jira?.key || usFile.external_id;
+                    if (!jiraKey || !String(jiraKey).includes('-')) {
+                        this.logger.log(`  ⏭️  ${usFile.id} - No JIRA issue reference`);
+                        continue;
+                    }
+                    // Get current issue status
+                    const issue = await jiraClient.getIssue(jiraKey);
+                    if (!issue) {
+                        this.logger.log(`  ⚠️  ${usFile.id} - JIRA issue ${jiraKey} not found`);
+                        continue;
+                    }
+                    // Check if already in target status (status is nested in fields)
+                    const currentStatus = issue.fields?.status?.name || '';
+                    if (currentStatus.toLowerCase() === targetStatus.toLowerCase()) {
+                        this.logger.log(`  ⏭️  ${usFile.id} - ${jiraKey} already ${targetStatus}`);
+                        continue;
+                    }
+                    // Transition to Done
+                    this.logger.log(`  🔒 Transitioning JIRA ${jiraKey} to ${targetStatus}...`);
+                    // Track metrics (v0.34.0)
+                    this.metrics.startOperation();
+                    try {
+                        await jiraClient.updateIssue({
+                            key: jiraKey,
+                            status: targetStatus
+                        });
+                        this.metrics.recordClosure('jira', jiraKey, true);
+                        this.logger.log(`  ✅ Transitioned ${jiraKey}`);
+                        closedCount++;
+                    }
+                    catch (updateError) {
+                        this.metrics.recordClosure('jira', jiraKey, false, String(updateError));
+                        throw updateError;
+                    }
+                }
+                catch (error) {
+                    this.logger.error(`  ❌ Failed to close JIRA issue for ${usFile.id}:`, error);
+                }
+            }
+            return closedCount;
+        }
+        catch (error) {
+            this.logger.error('❌ Failed to close JIRA issues:', error);
+            throw error;
+        }
+    }
+    /**
+     * Close ADO work items for completed user stories (v0.34.0)
+     *
+     * Transitions ADO work items to "Closed" state when increment is completed.
+     * Reads work item references from user story frontmatter (external.ado.id).
+     *
+     * @param config - Project config with ADO settings
+     * @returns Number of closed ADO work items
+     */
+    async closeAdoWorkItemsForUserStories(config) {
+        let closedCount = 0;
+        try {
+            const userStories = await this.loadUserStoriesForIncrement();
+            this.logger.log(`📚 Found ${userStories.length} user stor${userStories.length === 1 ? 'y' : 'ies'} for ADO closure`);
+            if (userStories.length === 0) {
+                return 0;
+            }
+            // Get ADO config
+            const adoConfig = config.sync?.ado;
+            if (!adoConfig?.organization || !adoConfig?.project) {
+                this.logger.log('⚠️  ADO config incomplete (missing organization or project)');
+                return 0;
+            }
+            // Get PAT from environment
+            const adoPat = await getAdoPat(adoConfig.organization);
+            if (!adoPat) {
+                this.logger.log('⚠️  ADO PAT not available');
+                return 0;
+            }
+            // Create ADO client
+            const adoClient = new AdoClient({
+                organization: adoConfig.organization,
+                project: adoConfig.project,
+                pat: adoPat
+            });
+            // Target state for completion (configurable via statusSync.mappings.ado.completed)
+            const targetStateConfig = config.sync?.statusSync?.mappings?.ado?.completed || { state: 'Closed' };
+            const targetState = typeof targetStateConfig === 'string' ? targetStateConfig : targetStateConfig.state;
+            // Collect work item IDs to fetch
+            const workItemIds = [];
+            for (const usFile of userStories) {
+                // Check if US has ADO reference in frontmatter (id not work_item_id per type def)
+                const adoId = usFile.external_tools?.ado?.id || usFile.external_id;
+                if (adoId && !isNaN(Number(adoId))) {
+                    workItemIds.push({ id: Number(adoId), usId: usFile.id });
+                }
+                else {
+                    this.logger.log(`  ⏭️  ${usFile.id} - No ADO work item reference`);
+                }
+            }
+            if (workItemIds.length === 0) {
+                return 0;
+            }
+            // Fetch work items in batch (ADO supports batch retrieval)
+            const workItems = await adoClient.listWorkItems({
+                workItemIds: workItemIds.map(w => w.id)
+            });
+            // Create lookup map
+            const workItemMap = new Map(workItems.map(w => [w.id, w]));
+            // Close each work item
+            for (const { id: workItemId, usId } of workItemIds) {
+                try {
+                    const workItem = workItemMap.get(workItemId);
+                    if (!workItem) {
+                        this.logger.log(`  ⚠️  ${usId} - ADO work item #${workItemId} not found`);
+                        continue;
+                    }
+                    // Check if already in target state (state is in fields['System.State'])
+                    const currentState = workItem.fields?.['System.State'] || '';
+                    if (currentState.toLowerCase() === targetState.toLowerCase()) {
+                        this.logger.log(`  ⏭️  ${usId} - #${workItemId} already ${targetState}`);
+                        continue;
+                    }
+                    // Update to Closed state
+                    this.logger.log(`  🔒 Closing ADO work item #${workItemId}...`);
+                    // Track metrics (v0.34.0)
+                    this.metrics.startOperation();
+                    try {
+                        await adoClient.updateWorkItem({
+                            id: workItemId,
+                            state: targetState
+                        });
+                        this.metrics.recordClosure('ado', workItemId, true);
+                        this.logger.log(`  ✅ Closed #${workItemId}`);
+                        closedCount++;
+                    }
+                    catch (updateError) {
+                        this.metrics.recordClosure('ado', workItemId, false, String(updateError));
+                        throw updateError;
+                    }
+                }
+                catch (error) {
+                    this.logger.error(`  ❌ Failed to close ADO work item for ${usId}:`, error);
+                }
+            }
+            return closedCount;
+        }
+        catch (error) {
+            this.logger.error('❌ Failed to close ADO work items:', error);
+            throw error;
+        }
+    }
     /**
      * Sync increment closure to external tools (NEW in v0.28.1)
      *
@@ -430,38 +666,87 @@ Increment \`${this.incrementId}\` has been marked as **completed**.
                 result.success = true;
                 return result;
             }
-            if (!githubEnabled) {
-                this.logger.log('ℹ️  GitHub sync disabled (sync.github.enabled=false)');
+            // Check which external tools are enabled
+            const jiraEnabled = config.sync?.jira?.enabled ?? false;
+            const adoEnabled = config.sync?.ado?.enabled ?? false;
+            if (!githubEnabled && !jiraEnabled && !adoEnabled) {
+                this.logger.log('ℹ️  No external tools enabled (GitHub/JIRA/ADO all disabled)');
                 result.syncMode = 'external-disabled';
                 result.success = true;
                 return result;
             }
-            this.logger.log('✅ All gates passed - closing GitHub issues for user stories');
-            // 2. First, ensure all issues exist (idempotent creation)
-            this.logger.log('\n🔹 Step 1: Ensuring all GitHub issues exist...');
-            try {
-                await this.createGitHubIssuesForUserStories(config);
-            }
-            catch (error) {
-                this.logger.error('⚠️  GitHub issue creation failed (non-blocking):', error);
-                result.errors.push(`GitHub issue creation error: ${error}`);
+            this.logger.log('✅ All gates passed - closing external issues for user stories');
+            // Track closed items across all tools
+            let totalClosed = 0;
+            // ========================================================================
+            // GitHub Closure
+            // ========================================================================
+            if (githubEnabled) {
+                this.logger.log('\n🔹 GitHub: Ensuring all issues exist...');
+                try {
+                    await this.createGitHubIssuesForUserStories(config);
+                }
+                catch (error) {
+                    this.logger.error('⚠️  GitHub issue creation failed (non-blocking):', error);
+                    result.errors.push(`GitHub issue creation error: ${error}`);
+                }
+                this.logger.log('\n🔹 GitHub: Closing issues for completed user stories...');
+                try {
+                    result.closedIssues = await this.closeGitHubIssuesForUserStories(config);
+                    totalClosed += result.closedIssues.length;
+                }
+                catch (error) {
+                    this.logger.error('⚠️  GitHub issue closure failed:', error);
+                    result.errors.push(`GitHub issue closure error: ${error}`);
+                }
             }
-            // 3. Close all User Story issues
-            this.logger.log('\n🔹 Step 2: Closing GitHub issues for completed user stories...');
-            try {
-                result.closedIssues = await this.closeGitHubIssuesForUserStories(config);
+            // ========================================================================
+            // JIRA Closure (v0.34.0)
+            // ========================================================================
+            if (jiraEnabled) {
+                this.logger.log('\n🔹 JIRA: Closing issues for completed user stories...');
+                try {
+                    const jiraClosed = await this.closeJiraIssuesForUserStories(config);
+                    totalClosed += jiraClosed;
+                    this.logger.log(`   ✅ Closed ${jiraClosed} JIRA issue(s)`);
+                }
+                catch (error) {
+                    this.logger.error('⚠️  JIRA issue closure failed:', error);
+                    result.errors.push(`JIRA issue closure error: ${error}`);
+                }
             }
-            catch (error) {
-                this.logger.error('⚠️  GitHub issue closure failed:', error);
-                result.errors.push(`GitHub issue closure error: ${error}`);
+            // ========================================================================
+            // ADO Closure (v0.34.0)
+            // ========================================================================
+            if (adoEnabled) {
+                this.logger.log('\n🔹 ADO: Closing work items for completed user stories...');
+                try {
+                    const adoClosed = await this.closeAdoWorkItemsForUserStories(config);
+                    totalClosed += adoClosed;
+                    this.logger.log(`   ✅ Closed ${adoClosed} ADO work item(s)`);
+                }
+                catch (error) {
+                    this.logger.error('⚠️  ADO work item closure failed:', error);
+                    result.errors.push(`ADO work item closure error: ${error}`);
+                }
             }
             result.success = result.errors.length === 0;
             result.syncMode = 'full-sync';
             this.logger.log(`\n✅ Increment closure sync complete`);
-            this.logger.log(`   Issues closed: ${result.closedIssues.length}`);
+            this.logger.log(`   Total items closed: ${totalClosed}`);
+            if (result.closedIssues.length > 0) {
+                this.logger.log(`   GitHub: ${result.closedIssues.length}`);
+            }
             if (result.errors.length > 0) {
                 this.logger.log(`   ⚠️  ${result.errors.length} error(s) occurred`);
             }
+            // Check for high failure rate and warn (v0.34.0 metrics)
+            const tools = ['github', 'jira', 'ado'];
+            for (const tool of tools) {
+                if (this.metrics.isFailureRateHigh(tool)) {
+                    this.logger.log(`   ⚠️  ${tool.toUpperCase()} has high failure rate - check credentials/permissions`);
+                }
+            }
             return result;
         }
         catch (error) {
@@ -470,6 +755,66 @@ Increment \`${this.incrementId}\` has been marked as **completed**.
             return result;
         }
     }
+    /**
+     * Detect duplicate issues with different feature ID formats (v0.34.0)
+     *
+     * Searches for issues that match the user story but have a different feature ID format.
+     * This prevents creating duplicates like:
+     * - [FS-0128][US-001] (old bug format with leading zeros)
+     * - [FS-128][US-001] (correct format)
+     *
+     * The search uses a regex pattern that matches any FS-XXX format for the same US-XXX.
+     *
+     * @param client - GitHub client
+     * @param featureId - Current feature ID (e.g., "FS-128")
+     * @param userStoryId - User story ID (e.g., "US-001")
+     * @returns Duplicate info if found, null otherwise
+     */
+    async detectDuplicateIssue(client, featureId, userStoryId) {
+        try {
+            // Extract the numeric part of the feature ID (e.g., "128" from "FS-128" or "FS-0128")
+            const featureNumMatch = featureId.match(/FS-0*(\d+)E?/i);
+            if (!featureNumMatch) {
+                return null;
+            }
+            const featureNum = featureNumMatch[1];
+            // Search for issues with ANY format of this feature ID + user story
+            // Patterns to check:
+            // - [FS-128][US-001]   (correct, no leading zeros)
+            // - [FS-0128][US-001]  (bug format, with leading zeros)
+            // - [FS-00128][US-001] (edge case, multiple leading zeros)
+            const searchPatterns = [
+                `[FS-${featureNum}][${userStoryId}]`, // FS-128
+                `[FS-0${featureNum}][${userStoryId}]`, // FS-0128
+                `[FS-00${featureNum}][${userStoryId}]`, // FS-00128
+                `[FS-${featureNum}E][${userStoryId}]`, // FS-128E (external)
+                `[FS-0${featureNum}E][${userStoryId}]`, // FS-0128E
+            ];
+            // Filter out the exact current format (we already checked that)
+            const currentFormat = `[${featureId}][${userStoryId}]`;
+            const alternatePatterns = searchPatterns.filter(p => p !== currentFormat);
+            for (const pattern of alternatePatterns) {
+                const existingIssue = await client.searchIssueByTitle(pattern, true); // Include closed
+                if (existingIssue) {
+                    // Extract the format from the issue title
+                    const formatMatch = existingIssue.title.match(/\[(FS-\d+E?)\]/i);
+                    const detectedFormat = formatMatch ? formatMatch[1] : 'unknown';
+                    return {
+                        number: existingIssue.number,
+                        url: existingIssue.html_url,
+                        title: existingIssue.title,
+                        format: detectedFormat,
+                    };
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            // Don't block issue creation on duplicate detection failure
+            this.logger.log(`    ⚠️ Duplicate detection failed (non-blocking): ${error}`);
+            return null;
+        }
+    }
     /**
      * Update issue if it has placeholder content
      * Fetches issue from GitHub, checks for placeholder, and updates with rich content
@@ -799,7 +1144,24 @@ Increment \`${this.incrementId}\` has been marked as **completed**.
             return [];
         }
         const frontmatter = yaml.parse(frontmatterMatch[1]);
-        const featureId = frontmatter.feature_id || frontmatter.epic || frontmatter.feature;
+        let featureId = frontmatter.feature_id || frontmatter.epic || frontmatter.feature;
+        // v0.34.0: Fallback to metadata.json if spec.md doesn't have feature_id
+        // This handles legacy increments where feature_id was only in metadata.json
+        if (!featureId) {
+            const metadataFile = path.join(this.projectRoot, '.specweave/increments', this.incrementId, 'metadata.json');
+            if (existsSync(metadataFile)) {
+                try {
+                    const metadata = JSON.parse(await fs.readFile(metadataFile, 'utf-8'));
+                    featureId = metadata.feature_id || metadata.epic_id;
+                    if (featureId) {
+                        this.logger.log(`  📎 Using feature_id from metadata.json: ${featureId}`);
+                    }
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+        }
         if (!featureId) {
             return [];
         }