specweave 2.3.0 → 3.0.1

package/plugins/specweave/lib/integrations/ado/per-us-sync.ts

@@ -1,459 +0,0 @@
-/**
- * Per-US Azure DevOps Sync (v0.34.0+)
- *
- * Syncs each User Story to its explicitly declared project's ADO project/area.
- * Uses the **Project**: and **Board**: fields in spec.md (NOT keyword-based classification).
- *
- * Key difference from multi-project-sync:
- * - Multi-project sync uses keyword/heuristic classification
- * - Per-US sync uses EXPLICIT **Project**: and **Board**: fields from spec.md
- *
- * @module per-us-sync
- * @since v0.34.0
- */
-
-import type { UserStoryData } from '../../../../../src/core/living-docs/types.js';
-import type { ProjectMappings, AdoMapping } from '../../../../../src/core/types/config.js';
-import type { USExternalRefsMap } from '../../../../../src/core/types/increment-metadata.js';
-import { Logger, consoleLogger } from '../../../../../src/utils/logger.js';
-
-/**
- * Result of syncing a single US to ADO
- */
-export interface USSyncResult {
-  usId: string;
-  projectId: string;
-  adoProject: string;
-  areaPath: string;
-  workItemId: number;
-  url: string;
-  action: 'created' | 'updated' | 'skipped';
-  error?: string;
-}
-
-/**
- * Result of syncing all USs in an increment
- */
-export interface PerUSSyncResult {
-  success: boolean;
-  synced: USSyncResult[];
-  failed: USSyncResult[];
-  externalRefs: USExternalRefsMap;
-  summary: {
-    total: number;
-    created: number;
-    updated: number;
-    skipped: number;
-    failed: number;
-  };
-}
-
-/**
- * Options for per-US sync
- */
-export interface PerUSSyncOptions {
-  dryRun?: boolean;
-  force?: boolean;
-  defaultProject?: string;
-  defaultBoard?: string;
-  logger?: Logger;
-}
-
-/**
- * ADO client interface (to be injected)
- */
-export interface AdoClient {
-  createWorkItem(
-    project: string,
-    workItemType: string,
-    title: string,
-    description: string,
-    areaPath?: string
-  ): Promise<{ id: number; url: string }>;
-  updateWorkItem(
-    project: string,
-    workItemId: number,
-    title: string,
-    description: string,
-    areaPath?: string
-  ): Promise<void>;
-  searchWorkItems(project: string, query: string): Promise<Array<{ id: number; fields: { 'System.Title': string } }>>;
-  getWorkItemUrl(project: string, workItemId: number): string;
-}
-
-/**
- * Default work item type by process template
- */
-const WORK_ITEM_TYPE_BY_TEMPLATE: Record<string, string> = {
-  agile: 'User Story',
-  scrum: 'Product Backlog Item',
-  cmmi: 'Requirement',
-  basic: 'Issue',
-};
-
-/**
- * Per-US ADO Sync
- *
- * Syncs each US to its declared project's ADO project/area path.
- * For 2-level structures, uses **Board**: to determine area path.
- */
-export class PerUSAdoSync {
-  private projectMappings: ProjectMappings;
-  private adoClient: AdoClient;
-  private logger: Logger;
-  private workItemType: string;
-
-  constructor(
-    adoClient: AdoClient,
-    projectMappings: ProjectMappings,
-    options: { logger?: Logger; workItemType?: string; processTemplate?: string } = {}
-  ) {
-    this.adoClient = adoClient;
-    this.projectMappings = projectMappings;
-    this.logger = options.logger ?? consoleLogger;
-    // Explicit workItemType takes priority, then process template lookup, then default
-    this.workItemType = options.workItemType
-      ?? WORK_ITEM_TYPE_BY_TEMPLATE[options.processTemplate?.toLowerCase() ?? '']
-      ?? 'User Story';
-  }
-
-  /**
-   * Sync all user stories to their respective ADO projects
-   *
-   * @param userStories - User stories with explicit project/board fields
-   * @param featureId - Feature ID (e.g., "FS-137")
-   * @param options - Sync options
-   */
-  async syncUserStories(
-    userStories: UserStoryData[],
-    featureId: string,
-    options: PerUSSyncOptions = {}
-  ): Promise<PerUSSyncResult> {
-    const synced: USSyncResult[] = [];
-    const failed: USSyncResult[] = [];
-    const externalRefs: USExternalRefsMap = {};
-
-    // Group USs by their declared project
-    const groups = this.groupByProject(userStories, options.defaultProject);
-
-    this.logger.log(`📡 Per-US ADO Sync: ${userStories.length} USs across ${groups.size} projects`);
-
-    for (const [projectId, stories] of groups) {
-      // Get ADO mapping for this project
-      const mapping = this.projectMappings[projectId]?.ado;
-
-      if (!mapping) {
-        // No ADO mapping for this project
-        this.logger.warn(`   ⚠️  No ADO mapping for project "${projectId}" - skipping ${stories.length} USs`);
-        for (const story of stories) {
-          failed.push({
-            usId: story.id,
-            projectId,
-            adoProject: 'N/A',
-            areaPath: '',
-            workItemId: 0,
-            url: '',
-            action: 'skipped',
-            error: `No ADO mapping for project "${projectId}"`
-          });
-        }
-        continue;
-      }
-
-      // Sync each US to this project's ADO project
-      for (const story of stories) {
-        try {
-          const result = await this.syncUserStory(story, mapping, featureId, options);
-          synced.push({
-            ...result,
-            projectId
-          });
-
-          // Build external ref
-          if (!options.dryRun && result.action !== 'skipped') {
-            externalRefs[story.id] = {
-              ado: {
-                provider: 'ado',
-                issueNumber: result.workItemId,
-                url: result.url,
-                targetProject: projectId,
-                lastSynced: new Date().toISOString()
-              }
-            };
-          }
-        } catch (error) {
-          failed.push({
-            usId: story.id,
-            projectId,
-            adoProject: mapping.project,
-            areaPath: mapping.areaPath || '',
-            workItemId: 0,
-            url: '',
-            action: 'skipped',
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-    }
-
-    // Calculate summary
-    const created = synced.filter(r => r.action === 'created').length;
-    const updated = synced.filter(r => r.action === 'updated').length;
-    const skipped = synced.filter(r => r.action === 'skipped').length;
-
-    return {
-      success: failed.length === 0,
-      synced,
-      failed,
-      externalRefs,
-      summary: {
-        total: userStories.length,
-        created,
-        updated,
-        skipped,
-        failed: failed.length
-      }
-    };
-  }
-
-  /**
-   * Sync a single user story to ADO
-   *
-   * For 2-level structures:
-   * - **Project**: maps to ADO project
-   * - **Board**: maps to area path under the project
-   */
-  private async syncUserStory(
-    story: UserStoryData,
-    mapping: AdoMapping,
-    featureId: string,
-    options: PerUSSyncOptions
-  ): Promise<USSyncResult> {
-    const title = `[${featureId}][${story.id}] ${story.title}`;
-    const description = this.buildWorkItemDescription(story, featureId);
-
-    // Determine area path:
-    // - Use story.board if available (2-level structure)
-    // - Fall back to mapping.areaPath
-    // - Fall back to project root
-    let areaPath = mapping.areaPath || mapping.project;
-    if (story.board) {
-      // 2-level structure: append board as area path segment
-      areaPath = `${mapping.project}\\${story.board}`;
-    }
-
-    if (options.dryRun) {
-      this.logger.log(`   🔍 [DRY-RUN] Would sync ${story.id} to ${mapping.project} (area: ${areaPath})`);
-      return {
-        usId: story.id,
-        projectId: story.project || 'unknown',
-        adoProject: mapping.project,
-        areaPath,
-        workItemId: 0,
-        url: '',
-        action: 'skipped'
-      };
-    }
-
-    // Check for existing work item (scoped to current feature to prevent cross-increment matches)
-    const existingItem = await this.findExistingWorkItem(mapping.project, featureId, story.id);
-
-    if (existingItem) {
-      // Update existing work item
-      await this.adoClient.updateWorkItem(
-        mapping.project,
-        existingItem.id,
-        title,
-        description,
-        areaPath
-      );
-
-      this.logger.log(`   🔄 Updated ${story.id} → ${mapping.project}/${existingItem.id}`);
-
-      return {
-        usId: story.id,
-        projectId: story.project || 'unknown',
-        adoProject: mapping.project,
-        areaPath,
-        workItemId: existingItem.id,
-        url: this.adoClient.getWorkItemUrl(mapping.project, existingItem.id),
-        action: 'updated'
-      };
-    } else {
-      // Create new work item
-      const newItem = await this.adoClient.createWorkItem(
-        mapping.project,
-        this.workItemType,
-        title,
-        description,
-        areaPath
-      );
-
-      this.logger.log(`   ✅ Created ${story.id} → ${mapping.project}/${newItem.id}`);
-
-      return {
-        usId: story.id,
-        projectId: story.project || 'unknown',
-        adoProject: mapping.project,
-        areaPath,
-        workItemId: newItem.id,
-        url: newItem.url,
-        action: 'created'
-      };
-    }
-  }
-
-  /**
-   * Find existing work item by Feature ID + US ID in title.
-   * Scoped to current feature to prevent cross-increment matches (FS-604).
-   */
-  private async findExistingWorkItem(
-    project: string,
-    featureId: string,
-    usId: string
-  ): Promise<{ id: number } | null> {
-    try {
-      const query = `[System.Title] Contains '[${featureId}][${usId}]'`;
-      const results = await this.adoClient.searchWorkItems(project, query);
-
-      return results.length > 0 ? { id: results[0].id } : null;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Build work item description from user story
-   *
-   * Includes full User Story format with description and Acceptance Criteria.
-   * Uses `acceptanceCriteriaFull` if available (v1.0.59+) for AC descriptions,
-   * otherwise falls back to AC IDs only.
-   */
-  private buildWorkItemDescription(story: UserStoryData, featureId: string): string {
-    const lines: string[] = [];
-
-    lines.push(`<h1>${this.escapeHtml(story.title)}</h1>`);
-    lines.push('');
-
-    // User Story description (As a... I want... So that...)
-    if (story.description) {
-      // Convert markdown bold to HTML
-      const htmlDesc = story.description
-        .replace(/\*\*As a\*\*/g, '<strong>As a</strong>')
-        .replace(/\*\*I want\*\*/g, '<strong>I want</strong>')
-        .replace(/\*\*So that\*\*/g, '<strong>So that</strong>')
-        .replace(/\n/g, '<br/>');
-      lines.push(`<p>${htmlDesc}</p>`);
-      lines.push('');
-    }
-
-    // Acceptance Criteria - prefer full descriptions if available
-    if (story.acceptanceCriteriaFull && story.acceptanceCriteriaFull.length > 0) {
-      // Use full AC data with descriptions (v1.0.59+)
-      lines.push('<h2>Acceptance Criteria</h2>');
-      lines.push('<ul>');
-      for (const ac of story.acceptanceCriteriaFull) {
-        const checkbox = ac.completed ? '☑' : '☐';
-        lines.push(`  <li>${checkbox} <strong>${this.escapeHtml(ac.id)}</strong>: ${this.escapeHtml(ac.description)}</li>`);
-      }
-      lines.push('</ul>');
-      lines.push('');
-    } else if (story.acceptanceCriteria && story.acceptanceCriteria.length > 0) {
-      // Fallback: AC IDs only (backward compatible)
-      lines.push('<h2>Acceptance Criteria</h2>');
-      lines.push('<ul>');
-      for (const ac of story.acceptanceCriteria) {
-        lines.push(`  <li>☐ ${this.escapeHtml(ac)}</li>`);
-      }
-      lines.push('</ul>');
-      lines.push('');
-    }
-
-    lines.push('<hr/>');
-    lines.push('');
-    lines.push(`<p><strong>Feature</strong>: ${this.escapeHtml(featureId)}</p>`);
-    lines.push(`<p><strong>User Story</strong>: ${this.escapeHtml(story.id)}</p>`);
-    if (story.project) {
-      lines.push(`<p><strong>Project</strong>: ${this.escapeHtml(story.project)}</p>`);
-    }
-    if (story.board) {
-      lines.push(`<p><strong>Board</strong>: ${this.escapeHtml(story.board)}</p>`);
-    }
-    return lines.join('\n');
-  }
-
-  /**
-   * Escape HTML special characters
-   */
-  private escapeHtml(str: string): string {
-    return str
-      .replace(/&/g, '&amp;')
-      .replace(/</g, '&lt;')
-      .replace(/>/g, '&gt;')
-      .replace(/"/g, '&quot;')
-      .replace(/'/g, '&#39;');
-  }
-
-  /**
-   * Group user stories by their explicit project field
-   */
-  private groupByProject(
-    userStories: UserStoryData[],
-    defaultProject?: string
-  ): Map<string, UserStoryData[]> {
-    const groups = new Map<string, UserStoryData[]>();
-
-    for (const story of userStories) {
-      const project = story.project || defaultProject || 'default';
-
-      if (!groups.has(project)) {
-        groups.set(project, []);
-      }
-      groups.get(project)!.push(story);
-    }
-
-    return groups;
-  }
-}
-
-/**
- * Format per-US sync results for display
- */
-export function formatPerUSSyncResults(result: PerUSSyncResult): string {
-  const lines: string[] = [];
-
-  lines.push('');
-  lines.push('📊 Per-US ADO Sync Results');
-  lines.push('');
-
-  // Group by project
-  const byProject = new Map<string, USSyncResult[]>();
-  for (const r of [...result.synced, ...result.failed]) {
-    const existing = byProject.get(r.projectId) || [];
-    existing.push(r);
-    byProject.set(r.projectId, existing);
-  }
-
-  for (const [projectId, results] of byProject) {
-    const adoProject = results[0]?.adoProject || 'N/A';
-    const areaPath = results[0]?.areaPath || '';
-    lines.push(`**${projectId}** (→ ${adoProject}${areaPath ? ` [${areaPath}]` : ''}):`);
-    for (const r of results) {
-      const icon = r.action === 'created' ? '✅' :
-                   r.action === 'updated' ? '🔄' :
-                   r.error ? '❌' : '⏭️';
-      if (r.workItemId > 0) {
-        lines.push(`  ${icon} ${r.usId} → ${r.adoProject}/${r.workItemId}`);
-      } else if (r.error) {
-        lines.push(`  ${icon} ${r.usId}: ${r.error}`);
-      } else {
-        lines.push(`  ${icon} ${r.usId} (${r.action})`);
-      }
-    }
-    lines.push('');
-  }
-
-  lines.push(`📈 Summary: ${result.summary.created} created, ${result.summary.updated} updated, ${result.summary.failed} failed`);
-
-  return lines.join('\n');
-}

package/plugins/specweave/lib/integrations/ado/project-selector.js

@@ -1,172 +0,0 @@
-import { select, checkbox, input, Separator } from "@inquirer/prompts";
-async function fetchAllAdoProjects(client) {
-  console.log("\u{1F50D} Fetching Azure DevOps projects...");
-  try {
-    const projects = await client.getProjects();
-    console.log(`\u2705 Found ${projects.length} Azure DevOps projects
-`);
-    return projects;
-  } catch (error) {
-    console.error("\u274C Failed to fetch ADO projects:", error.message);
-    throw error;
-  }
-}
-async function selectAdoProjects(client, options = {}) {
-  const {
-    allowManualEntry = true,
-    allowSelectAll = true,
-    preSelected = [],
-    minSelection = 1,
-    maxSelection,
-    pageSize = 15
-  } = options;
-  const allProjects = await fetchAllAdoProjects(client);
-  if (allProjects.length === 0) {
-    console.log("\u26A0\uFE0F  No Azure DevOps projects found");
-    return {
-      selectedNames: [],
-      method: "interactive"
-    };
-  }
-  console.log("\u{1F4CB} Available Azure DevOps Projects:\n");
-  console.log(`   Total: ${allProjects.length} projects
-`);
-  const selectionMethod = await select({
-    message: "How would you like to select projects?",
-    choices: [
-      {
-        name: `\u{1F4CB} Interactive (browse and select from ${allProjects.length} projects)`,
-        value: "interactive"
-      },
-      {
-        name: "\u270F\uFE0F  Manual entry (type project names)",
-        value: "manual"
-      },
-      ...allowSelectAll ? [
-        {
-          name: `\u2728 Select all (${allProjects.length} projects)`,
-          value: "all"
-        }
-      ] : []
-    ]
-  });
-  if (selectionMethod === "all") {
-    return {
-      selectedNames: allProjects.map((p) => p.name),
-      method: "all"
-    };
-  }
-  if (selectionMethod === "manual") {
-    return await manualProjectEntry(allProjects, minSelection, maxSelection);
-  }
-  return await interactiveProjectSelection(
-    allProjects,
-    preSelected,
-    minSelection,
-    maxSelection,
-    pageSize
-  );
-}
-async function interactiveProjectSelection(allProjects, preSelected, minSelection, maxSelection, pageSize) {
-  console.log("\u{1F4A1} Use <space> to select, <a> to toggle all, <i> to invert\n");
-  const choices = [
-    ...allProjects.map((p) => ({
-      name: formatProjectChoice(p),
-      value: p.name,
-      checked: preSelected.includes(p.name)
-    })),
-    // Add separator and manual entry option at the end
-    new Separator(),
-    {
-      name: "\u270F\uFE0F  Enter project names manually instead",
-      value: "__MANUAL__",
-      checked: false
-    }
-  ];
-  const selectedNames = await checkbox({
-    message: `Select Azure DevOps projects (${minSelection}${maxSelection ? `-${maxSelection}` : "+"} required):`,
-    choices,
-    pageSize,
-    loop: false,
-    validate: (selected) => {
-      const actualSelected = selected.filter((k) => k !== "__MANUAL__");
-      if (actualSelected.length < minSelection) {
-        return `Please select at least ${minSelection} project(s)`;
-      }
-      if (maxSelection && actualSelected.length > maxSelection) {
-        return `Please select at most ${maxSelection} project(s)`;
-      }
-      return true;
-    }
-  });
-  if (selectedNames.includes("__MANUAL__")) {
-    return await manualProjectEntry(allProjects, minSelection, maxSelection);
-  }
-  console.log(`
-\u2705 Selected ${selectedNames.length} projects: ${selectedNames.join(", ")}
-`);
-  return {
-    selectedNames,
-    method: "interactive"
-  };
-}
-async function manualProjectEntry(allProjects, minSelection, maxSelection) {
-  console.log("\n\u{1F4DD} Enter project names manually\n");
-  console.log("\u{1F4A1} Format: Comma-separated project names (e.g., AI Meme Generator,Project 2,Project 3)\n");
-  if (allProjects.length > 0) {
-    console.log("Available project names:");
-    console.log(
-      allProjects.map((p) => p.name).join(", ").substring(0, 100) + (allProjects.length > 20 ? "..." : "")
-    );
-    console.log("");
-  }
-  const manualNames = await input({
-    message: "Project names:",
-    validate: (inputValue) => {
-      if (!inputValue.trim()) {
-        return "Please enter at least one project name";
-      }
-      const names = inputValue.split(",").map((n) => n.trim()).filter((n) => n.length > 0);
-      if (names.length < minSelection) {
-        return `Please enter at least ${minSelection} project name(s)`;
-      }
-      if (maxSelection && names.length > maxSelection) {
-        return `Please enter at most ${maxSelection} project name(s)`;
-      }
-      return true;
-    }
-  });
-  const selectedNames = manualNames.split(",").map((n) => n.trim()).filter((n) => n.length > 0);
-  const knownNames = allProjects.map((p) => p.name);
-  const unknownNames = selectedNames.filter((n) => !knownNames.includes(n));
-  if (unknownNames.length > 0) {
-    console.log(`
-\u26A0\uFE0F  Unknown project names (will be used anyway): ${unknownNames.join(", ")}`);
-    console.log("   Make sure these projects exist in your Azure DevOps organization.\n");
-  }
-  console.log(`\u2705 Selected ${selectedNames.length} projects: ${selectedNames.join(", ")}
-`);
-  return {
-    selectedNames,
-    method: "manual"
-  };
-}
-function formatProjectChoice(project) {
-  const visibility = project.visibility || "private";
-  const state = project.state || "wellFormed";
-  return `${project.name.padEnd(30)} - ${project.description || "No description"} (${visibility}, ${state})`;
-}
-async function selectSingleAdoProject(client, message = "Select Azure DevOps project:") {
-  const result = await selectAdoProjects(client, {
-    allowManualEntry: true,
-    allowSelectAll: false,
-    minSelection: 1,
-    maxSelection: 1
-  });
-  return result.selectedNames[0];
-}
-export {
-  fetchAllAdoProjects,
-  selectAdoProjects,
-  selectSingleAdoProject
-};