specweave 0.17.16 → 0.17.19

package/plugins/specweave-jira/lib/enhanced-jira-sync.js

@@ -0,0 +1,134 @@
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import * as path from "path";
+import * as fs from "fs/promises";
+async function syncSpecToJiraWithEnhancedContent(options) {
+  const { specPath, domain, project, dryRun = false, verbose = false } = options;
+  try {
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (verbose) {
+      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
+    }
+    const taskMapping = buildTaskMapping(mapping.increments);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+    const enhancedSpec = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+    if (verbose) {
+      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
+    }
+    if (dryRun) {
+      console.log("\u{1F50D} DRY RUN - Would create/update epic with:");
+      console.log(`   Summary: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: "no-change",
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (!dryRun && (!domain || !project)) {
+      return {
+        success: false,
+        action: "error",
+        error: "JIRA domain/project not specified (required for actual sync)"
+      };
+    }
+    const result = {
+      success: true,
+      action: dryRun ? "no-change" : "created",
+      // Assume create if not dry run
+      tasksLinked: taskMapping?.tasks.length || 0
+    };
+    if (domain && project && !dryRun) {
+      result.epicKey = `SPEC-001`;
+      result.epicUrl = `https://${domain}/browse/SPEC-001`;
+      if (verbose) {
+        console.log(`\u26A0\uFE0F  JIRA API integration not implemented in this file`);
+        console.log(`   Use jira-spec-sync.ts for actual JIRA synchronization`);
+      }
+    }
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+function buildTaskMapping(increments) {
+  if (increments.length === 0) return void 0;
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `tasks.md`
+    // JIRA doesn't support external links in same way
+  };
+}
+async function findArchitectureDocs(rootDir, specId) {
+  const docs = [];
+  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
+  try {
+    const adrDir = path.join(archDir, "adr");
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: "adr",
+          path: path.join(adrDir, adr),
+          title: adr.replace(".md", "").replace(/-/g, " ")
+        });
+      }
+    } catch {
+    }
+  } catch {
+  }
+  return docs;
+}
+export {
+  syncSpecToJiraWithEnhancedContent
+};

package/plugins/specweave-jira/lib/enhanced-jira-sync.ts

@@ -0,0 +1,196 @@
+/**
+ * Enhanced JIRA Spec Content Sync
+ *
+ * Uses EnhancedContentBuilder and SpecIncrementMapper for rich epic descriptions.
+ *
+ * NOTE: This version focuses on enhanced content building.
+ * Actual JIRA API integration requires jira-spec-sync.ts
+ */
+
+import { EnhancedContentBuilder, EnhancedSpecContent } from '../../../src/core/sync/enhanced-content-builder.js';
+import { SpecIncrementMapper, TaskInfo } from '../../../src/core/sync/spec-increment-mapper.js';
+import { parseSpecContent } from '../../../src/core/spec-content-sync.js';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+export interface EnhancedJiraSyncOptions {
+  specPath: string;
+  domain?: string;
+  project?: string;
+  dryRun?: boolean;
+  verbose?: boolean;
+}
+
+export interface EnhancedJiraSyncResult {
+  success: boolean;
+  action: 'created' | 'updated' | 'no-change' | 'error';
+  epicKey?: string;
+  epicUrl?: string;
+  error?: string;
+  tasksLinked?: number;
+}
+
+/**
+ * Enhanced sync with rich content including task mappings
+ */
+export async function syncSpecToJiraWithEnhancedContent(
+  options: EnhancedJiraSyncOptions
+): Promise<EnhancedJiraSyncResult> {
+  const { specPath, domain, project, dryRun = false, verbose = false } = options;
+
+  try {
+    // 1. Parse spec content
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: 'error',
+        error: 'Failed to parse spec content',
+      };
+    }
+
+    if (verbose) {
+      console.log(`📄 Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+
+    // 2. Build enhanced spec with task mappings
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+
+    if (verbose) {
+      console.log(`🔗 Found ${mapping.increments.length} related increments`);
+    }
+
+    // 3. Build enhanced spec content
+    const taskMapping = buildTaskMapping(mapping.increments);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+
+    const enhancedSpec: EnhancedSpecContent = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+
+    // 4. Build external description
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+
+    if (verbose) {
+      console.log(`📝 Generated description: ${description.length} characters`);
+    }
+
+    if (dryRun) {
+      console.log('🔍 DRY RUN - Would create/update epic with:');
+      console.log(`   Summary: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: 'no-change',
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+
+    // 5. Validate domain/project (if not dry run)
+    if (!dryRun && (!domain || !project)) {
+      return {
+        success: false,
+        action: 'error',
+        error: 'JIRA domain/project not specified (required for actual sync)',
+      };
+    }
+
+    // For now, we focus on content building
+    // Actual JIRA API integration is in jira-spec-sync.ts
+    const result: EnhancedJiraSyncResult = {
+      success: true,
+      action: dryRun ? 'no-change' : 'created', // Assume create if not dry run
+      tasksLinked: taskMapping?.tasks.length || 0
+    };
+
+    if (domain && project && !dryRun) {
+      // In a real implementation, this would use JIRA API
+      // For now, just simulate success
+      result.epicKey = `SPEC-001`; // Placeholder
+      result.epicUrl = `https://${domain}/browse/SPEC-001`;
+
+      if (verbose) {
+        console.log(`⚠️  JIRA API integration not implemented in this file`);
+        console.log(`   Use jira-spec-sync.ts for actual JIRA synchronization`);
+      }
+    }
+
+    return result;
+  } catch (error: any) {
+    return {
+      success: false,
+      action: 'error',
+      error: error.message
+    };
+  }
+}
+
+// Helper functions (similar to GitHub sync)
+
+async function findSpecWeaveRoot(specPath: string): Promise<string> {
+  let currentDir = path.dirname(specPath);
+
+  while (true) {
+    const specweaveDir = path.join(currentDir, '.specweave');
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error('.specweave directory not found');
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+
+function buildTaskMapping(increments: any[]): any {
+  if (increments.length === 0) return undefined;
+
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task: TaskInfo) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `tasks.md` // JIRA doesn't support external links in same way
+  };
+}
+
+async function findArchitectureDocs(rootDir: string, specId: string): Promise<any[]> {
+  const docs: any[] = [];
+  const archDir = path.join(rootDir, '.specweave/docs/internal/architecture');
+
+  try {
+    const adrDir = path.join(archDir, 'adr');
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter(file => file.includes(specId.replace('spec-', '')));
+
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: 'adr',
+          path: path.join(adrDir, adr),
+          title: adr.replace('.md', '').replace(/-/g, ' ')
+        });
+      }
+    } catch {}
+  } catch {}
+
+  return docs;
+}
+
+// NOTE: findExistingEpic not needed in this simplified version
+// Real JIRA API integration is in jira-spec-sync.ts

package/plugins/specweave-jira/lib/jira-epic-sync.js

@@ -0,0 +1,304 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as yaml from "yaml";
+class JiraEpicSync {
+  constructor(client, specsDir, projectKey) {
+    this.client = client;
+    this.specsDir = specsDir;
+    this.projectKey = projectKey;
+  }
+  /**
+   * Sync Epic folder to JIRA (Epic + Stories)
+   */
+  async syncEpicToJira(epicId) {
+    console.log(`
+\u{1F504} Syncing Epic ${epicId} to JIRA...`);
+    const epicFolder = await this.findEpicFolder(epicId);
+    if (!epicFolder) {
+      throw new Error(`Epic ${epicId} not found in ${this.specsDir}`);
+    }
+    const readmePath = path.join(epicFolder, "README.md");
+    const epicData = await this.parseEpicReadme(readmePath);
+    console.log(`   \u{1F4E6} Epic: ${epicData.title}`);
+    console.log(`   \u{1F4CA} Increments: ${epicData.total_increments}`);
+    let epicKey = epicData.external_tools.jira.key;
+    let epicUrl = epicData.external_tools.jira.url;
+    if (!epicKey) {
+      console.log(`   \u{1F680} Creating JIRA Epic...`);
+      const epic = await this.createEpic(epicData);
+      epicKey = epic.key;
+      epicUrl = epic.url;
+      console.log(`   \u2705 Created Epic ${epicKey}`);
+      await this.updateEpicReadme(readmePath, {
+        type: "epic",
+        key: epicKey,
+        url: epicUrl
+      });
+    } else {
+      console.log(`   \u267B\uFE0F  Updating existing Epic ${epicKey}...`);
+      await this.updateEpic(epicKey, epicData);
+      console.log(`   \u2705 Updated Epic ${epicKey}`);
+    }
+    let storiesCreated = 0;
+    let storiesUpdated = 0;
+    console.log(`
+   \u{1F4DD} Syncing ${epicData.increments.length} increments...`);
+    for (const increment of epicData.increments) {
+      const incrementFile = path.join(epicFolder, `${increment.id}.md`);
+      if (!await fs.pathExists(incrementFile)) {
+        console.log(`   \u26A0\uFE0F  Increment file not found: ${increment.id}.md`);
+        continue;
+      }
+      const incrementData = await this.parseIncrementFile(incrementFile);
+      const existingStory = increment.external.jira;
+      if (!existingStory) {
+        const storyKey = await this.createStory(
+          epicData.id,
+          incrementData,
+          epicKey
+        );
+        storiesCreated++;
+        console.log(`   \u2705 Created Story ${storyKey} for ${increment.id}`);
+        await this.updateIncrementExternalLink(
+          readmePath,
+          incrementFile,
+          increment.id,
+          storyKey
+        );
+      } else {
+        await this.updateStory(
+          epicData.id,
+          existingStory,
+          incrementData,
+          epicKey
+        );
+        storiesUpdated++;
+        console.log(`   \u267B\uFE0F  Updated Story ${existingStory} for ${increment.id}`);
+      }
+    }
+    console.log(`
+\u2705 Epic sync complete!`);
+    console.log(`   Epic: ${epicUrl}`);
+    console.log(`   Stories created: ${storiesCreated}`);
+    console.log(`   Stories updated: ${storiesUpdated}`);
+    return {
+      epicKey,
+      epicUrl,
+      storiesCreated,
+      storiesUpdated
+    };
+  }
+  /**
+   * Find Epic folder by ID (FS-001 or just 001)
+   */
+  async findEpicFolder(epicId) {
+    const normalizedId = epicId.startsWith("FS-") ? epicId : `FS-${epicId.padStart(3, "0")}`;
+    const folders = await fs.readdir(this.specsDir);
+    for (const folder of folders) {
+      if (folder.startsWith(normalizedId)) {
+        return path.join(this.specsDir, folder);
+      }
+    }
+    return null;
+  }
+  /**
+   * Parse Epic README.md to extract frontmatter
+   */
+  async parseEpicReadme(readmePath) {
+    const content = await fs.readFile(readmePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("Epic README.md missing YAML frontmatter");
+    }
+    const frontmatter = yaml.parse(match[1]);
+    return frontmatter;
+  }
+  /**
+   * Parse increment file to extract title and overview
+   */
+  async parseIncrementFile(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    let frontmatter = { id: "", epic: "" };
+    let bodyContent = content;
+    if (match) {
+      frontmatter = yaml.parse(match[1]);
+      bodyContent = content.slice(match[0].length).trim();
+    }
+    const titleMatch = bodyContent.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : frontmatter.id || path.basename(filePath, ".md");
+    const overviewMatch = bodyContent.match(/^#[^\n]+\n+([^\n]+)/);
+    const overview = overviewMatch ? overviewMatch[1].trim() : "No overview available";
+    return {
+      id: frontmatter.id,
+      title,
+      overview,
+      content: bodyContent,
+      frontmatter
+    };
+  }
+  /**
+   * Create JIRA Epic
+   */
+  async createEpic(epic) {
+    const summary = `[${epic.id}] ${epic.title}`;
+    const description = `Epic: ${epic.title}
+
+Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
+
+Priority: ${epic.priority}
+Status: ${epic.status}`;
+    const issueData = {
+      issueType: "Epic",
+      summary,
+      description,
+      priority: this.mapPriorityToJira(epic.priority),
+      labels: ["epic-sync", epic.id.toLowerCase()]
+    };
+    const issue = await this.client.createIssue(issueData, this.projectKey);
+    return {
+      key: issue.key,
+      url: issue.self.replace("/rest/api/3/issue/", "/browse/")
+    };
+  }
+  /**
+   * Update JIRA Epic
+   */
+  async updateEpic(epicKey, epic) {
+    const summary = `[${epic.id}] ${epic.title}`;
+    const description = `Epic: ${epic.title}
+
+Progress: ${epic.completed_increments}/${epic.total_increments} increments (${epic.progress})
+
+Priority: ${epic.priority}
+Status: ${epic.status}`;
+    await this.client.updateIssue({
+      key: epicKey,
+      summary,
+      description,
+      priority: this.mapPriorityToJira(epic.priority),
+      labels: ["epic-sync", epic.id.toLowerCase()]
+    });
+  }
+  /**
+   * Create JIRA Story for increment
+   */
+  async createStory(epicId, increment, epicKey) {
+    const summary = `[${epicId}] ${increment.title}`;
+    const description = `${increment.overview}
+
+---
+
+**Increment**: ${increment.id}
+**Epic**: ${epicId} (${epicKey})
+
+\u{1F916} Auto-created by SpecWeave Epic Sync`;
+    const issueData = {
+      issueType: "Story",
+      summary,
+      description,
+      epicKey,
+      // Link to Epic via Epic Link field
+      labels: ["increment", "epic-sync"]
+    };
+    const issue = await this.client.createIssue(issueData, this.projectKey);
+    return issue.key;
+  }
+  /**
+   * Update JIRA Story for increment
+   */
+  async updateStory(epicId, storyKey, increment, epicKey) {
+    const summary = `[${epicId}] ${increment.title}`;
+    const description = `${increment.overview}
+
+---
+
+**Increment**: ${increment.id}
+**Epic**: ${epicId} (${epicKey})
+
+\u{1F916} Auto-updated by SpecWeave Epic Sync`;
+    await this.client.updateIssue({
+      key: storyKey,
+      summary,
+      description,
+      labels: ["increment", "epic-sync"]
+    });
+  }
+  /**
+   * Map SpecWeave priority to JIRA priority
+   */
+  mapPriorityToJira(priority) {
+    const map = {
+      P0: "Highest",
+      P1: "High",
+      P2: "Medium",
+      P3: "Low"
+    };
+    return map[priority] || "Medium";
+  }
+  /**
+   * Update Epic README.md with JIRA Epic key
+   */
+  async updateEpicReadme(readmePath, jira) {
+    const content = await fs.readFile(readmePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("Epic README.md missing YAML frontmatter");
+    }
+    const frontmatter = yaml.parse(match[1]);
+    frontmatter.external_tools.jira = jira;
+    const newFrontmatter = yaml.stringify(frontmatter);
+    const newContent = content.replace(
+      /^---\n[\s\S]*?\n---/,
+      `---
+${newFrontmatter}---`
+    );
+    await fs.writeFile(readmePath, newContent, "utf-8");
+  }
+  /**
+   * Update increment external link in both Epic README and increment file
+   */
+  async updateIncrementExternalLink(readmePath, incrementFile, incrementId, storyKey) {
+    const storyUrl = `https://${this.client["credentials"].domain}/browse/${storyKey}`;
+    const readmeContent = await fs.readFile(readmePath, "utf-8");
+    const readmeMatch = readmeContent.match(/^---\n([\s\S]*?)\n---/);
+    if (readmeMatch) {
+      const frontmatter = yaml.parse(readmeMatch[1]);
+      const increment = frontmatter.increments.find(
+        (inc) => inc.id === incrementId
+      );
+      if (increment) {
+        increment.external.jira = storyKey;
+        const newFrontmatter = yaml.stringify(frontmatter);
+        const newContent = readmeContent.replace(
+          /^---\n[\s\S]*?\n---/,
+          `---
+${newFrontmatter}---`
+        );
+        await fs.writeFile(readmePath, newContent, "utf-8");
+      }
+    }
+    const incrementContent = await fs.readFile(incrementFile, "utf-8");
+    const incrementMatch = incrementContent.match(/^---\n([\s\S]*?)\n---/);
+    if (incrementMatch) {
+      const frontmatter = yaml.parse(incrementMatch[1]);
+      if (!frontmatter.external) {
+        frontmatter.external = {};
+      }
+      frontmatter.external.jira = {
+        story: storyKey,
+        url: storyUrl
+      };
+      const newFrontmatter = yaml.stringify(frontmatter);
+      const newContent = incrementContent.replace(
+        /^---\n[\s\S]*?\n---/,
+        `---
+${newFrontmatter}---`
+      );
+      await fs.writeFile(incrementFile, newContent, "utf-8");
+    }
+  }
+}
+export {
+  JiraEpicSync
+};