specweave 0.4.1 → 0.6.3

package/plugins/specweave-github/lib/task-parser.ts

@@ -0,0 +1,246 @@
+/**
+ * Parser for tasks.md files
+ * Extracts task information for GitHub sync
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { Task, Subtask } from './types';
+
+export class TaskParser {
+  /**
+   * Parse tasks.md file and extract all tasks
+   */
+  static parseTasksFile(incrementPath: string): Task[] {
+    const tasksPath = path.join(incrementPath, 'tasks.md');
+
+    if (!fs.existsSync(tasksPath)) {
+      throw new Error(`tasks.md not found at ${tasksPath}`);
+    }
+
+    const content = fs.readFileSync(tasksPath, 'utf-8');
+    return this.parseTasks(content);
+  }
+
+  /**
+   * Parse task content into structured Task objects
+   */
+  static parseTasks(content: string): Task[] {
+    const tasks: Task[] = [];
+
+    // Split by task headers (### T-XXX:)
+    const taskPattern = /###\s+(T-\d+(?:-[A-Z])?):\s+(.+?)$/gm;
+    const matches = [...content.matchAll(taskPattern)];
+
+    for (let i = 0; i < matches.length; i++) {
+      const match = matches[i];
+      const taskId = match[1];
+      const taskTitle = match[2].trim();
+      const startIndex = match.index!;
+      const endIndex = i < matches.length - 1 ? matches[i + 1].index! : content.length;
+      const taskContent = content.substring(startIndex, endIndex);
+
+      const task = this.parseTask(taskId, taskTitle, taskContent);
+      if (task) {
+        tasks.push(task);
+      }
+    }
+
+    return tasks;
+  }
+
+  /**
+   * Parse individual task section
+   */
+  private static parseTask(taskId: string, taskTitle: string, content: string): Task | null {
+    try {
+      const task: Task = {
+        id: taskId,
+        title: taskTitle,
+        priority: this.extractPriority(content),
+        estimate: this.extractEstimate(content),
+        status: this.extractStatus(content),
+        description: this.extractDescription(content),
+      };
+
+      // Optional fields
+      task.githubIssue = this.extractGitHubIssue(content);
+      task.assignee = this.extractAssignee(content);
+      task.subtasks = this.extractSubtasks(content);
+      task.filesToCreate = this.extractFiles(content, 'Files to Create');
+      task.filesToModify = this.extractFiles(content, 'Files to Modify');
+      task.implementation = this.extractImplementation(content);
+      task.acceptanceCriteria = this.extractAcceptanceCriteria(content);
+      task.dependencies = this.extractDependencies(content);
+      task.blocks = this.extractBlocks(content);
+      task.phase = this.extractPhase(content);
+
+      return task;
+    } catch (error) {
+      console.error(`Error parsing task ${taskId}:`, error);
+      return null;
+    }
+  }
+
+  private static extractPriority(content: string): 'P0' | 'P1' | 'P2' | 'P3' {
+    const match = content.match(/\*\*Priority\*\*:\s+(P[0-3])/);
+    return (match?.[1] as 'P0' | 'P1' | 'P2' | 'P3') || 'P1';
+  }
+
+  private static extractEstimate(content: string): string {
+    const match = content.match(/\*\*Estimate\*\*:\s+(.+?)$/m);
+    return match?.[1]?.trim() || 'Unknown';
+  }
+
+  private static extractStatus(content: string): 'pending' | 'in_progress' | 'completed' | 'blocked' {
+    const match = content.match(/\*\*Status\*\*:\s+(\w+)/);
+    const status = match?.[1];
+    if (status === 'pending' || status === 'in_progress' || status === 'completed' || status === 'blocked') {
+      return status;
+    }
+    return 'pending';
+  }
+
+  private static extractDescription(content: string): string {
+    const match = content.match(/\*\*Description\*\*:\s*\n(.+?)(?=\n\*\*|$)/s);
+    return match?.[1]?.trim() || '';
+  }
+
+  private static extractGitHubIssue(content: string): number | undefined {
+    const match = content.match(/\*\*GitHub Issue\*\*:\s+#(\d+)/);
+    return match ? parseInt(match[1], 10) : undefined;
+  }
+
+  private static extractAssignee(content: string): string | undefined {
+    const match = content.match(/\*\*Assignee\*\*:\s+@?(\w+)/);
+    return match?.[1];
+  }
+
+  private static extractSubtasks(content: string): Subtask[] | undefined {
+    const subtaskSection = content.match(/\*\*Subtasks\*\*:?\s*\n((?:- \[.\] .+\n?)+)/);
+    if (!subtaskSection) return undefined;
+
+    const subtaskLines = subtaskSection[1].match(/- \[(x| )\] (.+?)(?:\((.+?)\))?$/gm);
+    if (!subtaskLines) return undefined;
+
+    return subtaskLines.map(line => {
+      const match = line.match(/- \[(x| )\] (.+?)(?:\((.+?)\))?$/);
+      if (!match) return null;
+
+      const completed = match[1] === 'x';
+      const description = match[2].trim();
+      const estimate = match[3]?.trim() || 'Unknown';
+
+      // Extract subtask ID if present (S-XXX-XX format)
+      const idMatch = description.match(/^(S-\d+-\d+):\s*(.+)/);
+      const id = idMatch ? idMatch[1] : `S-${Date.now()}`; // Fallback ID
+      const cleanDescription = idMatch ? idMatch[2] : description;
+
+      return {
+        id,
+        description: cleanDescription,
+        estimate,
+        completed
+      };
+    }).filter((st): st is Subtask => st !== null);
+  }
+
+  private static extractFiles(content: string, section: string): string[] | undefined {
+    const pattern = new RegExp(`\\*\\*${section}\\*\\*:?\\s*\\n((?:- \`.+?\`\\n?)+)`, 's');
+    const match = content.match(pattern);
+    if (!match) return undefined;
+
+    const files = match[1].match(/- `(.+?)`/g);
+    return files?.map(f => f.replace(/- `(.+?)`/, '$1'));
+  }
+
+  private static extractImplementation(content: string): string | undefined {
+    const match = content.match(/\*\*Implementation\*\*:?\s*\n```[\w]*\n([\s\S]+?)\n```/);
+    return match?.[1]?.trim();
+  }
+
+  private static extractAcceptanceCriteria(content: string): string[] | undefined {
+    const match = content.match(/\*\*Acceptance Criteria\*\*:?\s*\n((?:- .+\n?)+)/);
+    if (!match) return undefined;
+
+    const criteria = match[1].match(/- (.+)/g);
+    return criteria?.map(c => c.replace(/^- /, '').replace(/^✅\s*/, ''));
+  }
+
+  private static extractDependencies(content: string): string[] | undefined {
+    const match = content.match(/\*\*Dependencies\*\*:?\s*\n((?:- .+\n?)+)/);
+    if (!match) return undefined;
+
+    const deps = match[1].match(/- (T-\d+(?:-[A-Z])?)/g);
+    return deps?.map(d => d.replace(/^- /, '').match(/(T-\d+(?:-[A-Z])?)/)?.[1]).filter((d): d is string => !!d);
+  }
+
+  private static extractBlocks(content: string): string[] | undefined {
+    const match = content.match(/\*\*Blocks\*\*:?\s*\n((?:- .+\n?)+)/);
+    if (!match) return undefined;
+
+    const blocks = match[1].match(/- (T-\d+(?:-[A-Z])?)/g);
+    return blocks?.map(b => b.replace(/^- /, '').match(/(T-\d+(?:-[A-Z])?)/)?.[1]).filter((b): b is string => !!b);
+  }
+
+  private static extractPhase(content: string): string | undefined {
+    // Look backwards in content to find phase header
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.startsWith('##') && !line.startsWith('###')) {
+        const phaseMatch = line.match(/##\s+(.+?)(?:\s+-\s+\d+\s+tasks)?$/);
+        if (phaseMatch) {
+          return phaseMatch[1].trim();
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Update tasks.md file with GitHub issue numbers
+   */
+  static updateTasksWithGitHubIssues(
+    incrementPath: string,
+    taskIssueMap: Record<string, number>
+  ): void {
+    const tasksPath = path.join(incrementPath, 'tasks.md');
+    let content = fs.readFileSync(tasksPath, 'utf-8');
+
+    for (const [taskId, issueNumber] of Object.entries(taskIssueMap)) {
+      // Find task section
+      const taskHeaderPattern = new RegExp(`(###\\s+${taskId}:.+?$)`, 'm');
+      const match = content.match(taskHeaderPattern);
+      if (!match) continue;
+
+      const taskStart = match.index!;
+      const nextTaskPattern = /###\s+T-\d+(?:-[A-Z])?:/g;
+      nextTaskPattern.lastIndex = taskStart + match[0].length;
+      const nextMatch = nextTaskPattern.exec(content);
+      const taskEnd = nextMatch ? nextMatch.index : content.length;
+      const taskSection = content.substring(taskStart, taskEnd);
+
+      // Check if GitHub Issue field already exists
+      if (taskSection.includes('**GitHub Issue**:')) {
+        // Update existing
+        const updatedSection = taskSection.replace(
+          /\*\*GitHub Issue\*\*:.+$/m,
+          `**GitHub Issue**: #${issueNumber}`
+        );
+        content = content.substring(0, taskStart) + updatedSection + content.substring(taskEnd);
+      } else {
+        // Add after Status line
+        const statusLinePattern = /(\*\*Status\*\*:.+?$)/m;
+        const statusMatch = taskSection.match(statusLinePattern);
+        if (statusMatch) {
+          const insertPoint = taskStart + taskSection.indexOf(statusMatch[0]) + statusMatch[0].length;
+          const insertion = `\n**GitHub Issue**: #${issueNumber}`;
+          content = content.substring(0, insertPoint) + insertion + content.substring(insertPoint);
+        }
+      }
+    }
+
+    fs.writeFileSync(tasksPath, content, 'utf-8');
+  }
+}

package/plugins/specweave-github/lib/task-sync.ts

@@ -0,0 +1,402 @@
+/**
+ * Task-level GitHub synchronization
+ * Orchestrates syncing tasks.md to GitHub issues
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { GitHubClient } from './github-client';
+import { TaskParser } from './task-parser';
+import { Task, IncrementMetadata, SyncResult, GitHubSyncOptions } from './types';
+
+export class TaskSync {
+  private client: GitHubClient;
+  private incrementPath: string;
+
+  constructor(incrementPath: string, repo?: string) {
+    this.incrementPath = incrementPath;
+    this.client = new GitHubClient(repo);
+  }
+
+  /**
+   * Sync all tasks to GitHub (main entry point)
+   */
+  async syncTasks(options: GitHubSyncOptions = {}): Promise<SyncResult> {
+    const {
+      force = false,
+      dryRun = false,
+      batchDelay = 6000,
+      batchSize = 10,
+      milestoneDays = 2, // SpecWeave default: 2 days (AI velocity)
+      projectName,
+      fastMode = false
+    } = options;
+
+    console.log(`\n🔄 Syncing increment to GitHub...`);
+
+    // 1. Check prerequisites
+    const ghCheck = GitHubClient.checkGitHubCLI();
+    if (!ghCheck.installed || !ghCheck.authenticated) {
+      throw new Error(ghCheck.error || 'GitHub CLI check failed');
+    }
+
+    // 2. Load increment metadata
+    const metadata = this.loadIncrementMetadata();
+    console.log(`📦 Increment: ${metadata.id} - ${metadata.title}`);
+
+    // 3. Parse tasks
+    const tasks = TaskParser.parseTasksFile(this.incrementPath);
+    console.log(`📋 Found ${tasks.length} tasks`);
+
+    if (dryRun) {
+      console.log(`\n🔍 DRY RUN MODE - No changes will be made`);
+      this.printDryRunSummary(tasks, metadata);
+      return {
+        epic: {} as any,
+        tasks: [],
+        errors: []
+      };
+    }
+
+    // 4. Check if already synced (and force not set)
+    if (metadata.github?.epic_issue && !force) {
+      console.log(`\n⚠️  Increment already synced to GitHub (epic #${metadata.github.epic_issue})`);
+      console.log(`   Use --force to re-sync (WARNING: will create duplicate issues)`);
+      throw new Error('Already synced. Use --force to override.');
+    }
+
+    const errors: Array<{ taskId?: string; error: string }> = [];
+
+    try {
+      // 5. Create or get milestone (with SpecWeave AI velocity: 1-2 days)
+      const milestoneTitle = this.getMilestoneTitle(metadata);
+      console.log(`\n📍 Creating milestone: ${milestoneTitle} (due in ${milestoneDays} days)`);
+      const milestone = await this.client.createOrGetMilestone(
+        milestoneTitle,
+        `Milestone for increment ${metadata.id}`,
+        milestoneDays
+      );
+      console.log(`   ✅ Milestone #${milestone.number}: ${milestone.title}`);
+
+      // 6. Create epic issue
+      console.log(`\n🎯 Creating epic issue for increment ${metadata.id}...`);
+      const epicBody = this.generateEpicBody(metadata, tasks);
+      const epic = await this.client.createEpicIssue(
+        `[INC-${metadata.id}] ${metadata.title}`,
+        epicBody,
+        milestone.title,
+        ['increment', 'specweave', metadata.priority.toLowerCase()]
+      );
+      console.log(`   ✅ Epic issue #${epic.number}: ${epic.html_url}`);
+
+      // 7. Create task issues (with smart rate limiting)
+      // Fast mode: Skip delays for small increments (< 10 tasks) or when explicitly requested
+      const useFastMode = fastMode || tasks.length < 10;
+      const effectiveDelay = useFastMode ? 0 : batchDelay;
+
+      if (useFastMode) {
+        console.log(`\n📝 Creating ${tasks.length} task issues (fast mode - no rate limiting)...`);
+      } else {
+        console.log(`\n📝 Creating ${tasks.length} task issues (batch size: ${batchSize}, delay: ${effectiveDelay}ms)...`);
+      }
+
+      const taskIssues: Array<{ taskId: string; issue: any }> = [];
+      const issueData = tasks.map(task => ({
+        title: `[${task.id}] ${task.title}`,
+        body: this.generateTaskBody(task),
+        labels: ['task', task.priority.toLowerCase(), ...(task.phase ? [this.slugify(task.phase)] : [])]
+      }));
+
+      const createdIssues = await this.client.batchCreateIssues(
+        issueData,
+        milestone.title,
+        epic.number,
+        { batchSize, delayMs: effectiveDelay }
+      );
+
+      // TODO: GitHub Projects integration (if projectName provided)
+      // if (projectName) {
+      //   await this.addIssuesToProject(projectName, [epic, ...createdIssues]);
+      // }
+
+      // Map issues to tasks
+      for (let i = 0; i < tasks.length; i++) {
+        if (createdIssues[i]) {
+          taskIssues.push({
+            taskId: tasks[i].id,
+            issue: createdIssues[i]
+          });
+          console.log(`   ✅ #${createdIssues[i].number}: [${tasks[i].id}] ${tasks[i].title}`);
+        } else {
+          errors.push({
+            taskId: tasks[i].id,
+            error: 'Failed to create issue'
+          });
+          console.log(`   ❌ [${tasks[i].id}] ${tasks[i].title} - Failed`);
+        }
+      }
+
+      // 8. Update tasks.md with GitHub issue numbers
+      console.log(`\n📄 Updating tasks.md with GitHub issue numbers...`);
+      const taskIssueMap: Record<string, number> = {};
+      taskIssues.forEach(({ taskId, issue }) => {
+        taskIssueMap[taskId] = issue.number;
+      });
+      TaskParser.updateTasksWithGitHubIssues(this.incrementPath, taskIssueMap);
+      console.log(`   ✅ Updated tasks.md`);
+
+      // 9. Save sync mapping
+      console.log(`\n💾 Saving sync mapping...`);
+      this.saveSyncMapping({
+        milestone: milestone.number,
+        epic_issue: epic.number,
+        task_issues: taskIssueMap,
+        last_sync: new Date().toISOString()
+      });
+      console.log(`   ✅ Saved to .github-sync.yaml`);
+
+      // 10. Update increment metadata
+      metadata.github = {
+        milestone: milestone.number,
+        epic_issue: epic.number,
+        task_issues: taskIssueMap,
+        last_sync: new Date().toISOString()
+      };
+      this.saveIncrementMetadata(metadata);
+
+      // Success summary
+      console.log(`\n🎉 GitHub sync complete!`);
+      console.log(`   📍 Milestone: #${milestone.number} ${milestone.title}`);
+      console.log(`   🎯 Epic: #${epic.number} ${epic.html_url}`);
+      console.log(`   📝 Tasks: #${createdIssues[0]?.number}-#${createdIssues[createdIssues.length - 1]?.number} (${createdIssues.length} issues)`);
+
+      return {
+        milestone,
+        epic,
+        tasks: taskIssues,
+        errors
+      };
+
+    } catch (error: any) {
+      console.error(`\n❌ Sync failed:`, error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Generate epic issue body
+   */
+  private generateEpicBody(metadata: IncrementMetadata, tasks: Task[]): string {
+    const specPath = path.join(this.incrementPath, 'spec.md');
+    let summary = 'No summary available';
+
+    if (fs.existsSync(specPath)) {
+      const specContent = fs.readFileSync(specPath, 'utf-8');
+      const summaryMatch = specContent.match(/## Executive Summary\s+(.+?)(?=\n##|$)/s);
+      summary = summaryMatch?.[1]?.trim() || summary;
+    }
+
+    // Group tasks by phase
+    const phases = new Map<string, Task[]>();
+    tasks.forEach(task => {
+      const phase = task.phase || 'Other';
+      if (!phases.has(phase)) {
+        phases.set(phase, []);
+      }
+      phases.get(phase)!.push(task);
+    });
+
+    let phaseChecklist = '';
+    for (const [phase, phaseTasks] of phases.entries()) {
+      phaseChecklist += `\n### ${phase}\n\n`;
+      phaseTasks.forEach(task => {
+        phaseChecklist += `- [ ] [${task.id}] ${task.title} (${task.estimate})\n`;
+      });
+    }
+
+    return `# [Increment ${metadata.id}] ${metadata.title}
+
+**Status**: ${metadata.status}
+**Priority**: ${metadata.priority}
+**Created**: ${new Date().toISOString().split('T')[0]}
+
+## Summary
+
+${summary}
+
+## Tasks (${tasks.length} total)
+${phaseChecklist}
+
+## SpecWeave Increment
+
+This epic tracks SpecWeave increment \`${metadata.id}\`.
+
+- **Spec**: [\`spec.md\`](${this.getGitHubFileURL('spec.md')})
+- **Plan**: [\`plan.md\`](${this.getGitHubFileURL('plan.md')})
+- **Tasks**: [\`tasks.md\`](${this.getGitHubFileURL('tasks.md')})
+
+---
+
+🤖 Auto-synced by [SpecWeave](https://spec-weave.com)`;
+  }
+
+  /**
+   * Generate task issue body
+   */
+  private generateTaskBody(task: Task): string {
+    let body = `**Priority**: ${task.priority}
+**Estimate**: ${task.estimate}
+**Phase**: ${task.phase || 'N/A'}
+
+## Description
+
+${task.description}
+`;
+
+    if (task.subtasks && task.subtasks.length > 0) {
+      body += `\n## Subtasks\n\n`;
+      task.subtasks.forEach(subtask => {
+        const checked = subtask.completed ? 'x' : ' ';
+        body += `- [${checked}] ${subtask.id}: ${subtask.description} (${subtask.estimate})\n`;
+      });
+    }
+
+    if (task.filesToCreate && task.filesToCreate.length > 0) {
+      body += `\n## Files to Create\n\n`;
+      task.filesToCreate.forEach(file => {
+        body += `- \`${file}\`\n`;
+      });
+    }
+
+    if (task.filesToModify && task.filesToModify.length > 0) {
+      body += `\n## Files to Modify\n\n`;
+      task.filesToModify.forEach(file => {
+        body += `- \`${file}\`\n`;
+      });
+    }
+
+    if (task.implementation) {
+      body += `\n## Implementation\n\n\`\`\`typescript\n${task.implementation}\n\`\`\`\n`;
+    }
+
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      body += `\n## Acceptance Criteria\n\n`;
+      task.acceptanceCriteria.forEach(criterion => {
+        body += `- ✅ ${criterion}\n`;
+      });
+    }
+
+    if (task.dependencies && task.dependencies.length > 0) {
+      body += `\n## Dependencies\n\nThis task depends on:\n`;
+      task.dependencies.forEach(dep => {
+        body += `- ${dep} (must complete first)\n`;
+      });
+    }
+
+    if (task.blocks && task.blocks.length > 0) {
+      body += `\n## Blocks\n\nThis task blocks:\n`;
+      task.blocks.forEach(blocked => {
+        body += `- ${blocked} (waiting on this)\n`;
+      });
+    }
+
+    body += `\n---\n\n🤖 Synced from SpecWeave increment \`${path.basename(this.incrementPath)}\`\n`;
+    body += `- **Tasks**: [\`tasks.md\`](${this.getGitHubFileURL('tasks.md')})\n`;
+
+    return body;
+  }
+
+  /**
+   * Load increment metadata
+   */
+  private loadIncrementMetadata(): IncrementMetadata {
+    const metadataPath = path.join(this.incrementPath, '.metadata.yaml');
+
+    if (fs.existsSync(metadataPath)) {
+      const content = fs.readFileSync(metadataPath, 'utf-8');
+      return yaml.load(content) as IncrementMetadata;
+    }
+
+    // Fallback: extract from directory name and spec
+    const incrementId = path.basename(this.incrementPath);
+    const specPath = path.join(this.incrementPath, 'spec.md');
+    let title = 'Unknown';
+    let priority: 'P0' | 'P1' | 'P2' | 'P3' = 'P1';
+
+    if (fs.existsSync(specPath)) {
+      const specContent = fs.readFileSync(specPath, 'utf-8');
+      const titleMatch = specContent.match(/\*\*Title\*\*:\s*(.+)/);
+      const priorityMatch = specContent.match(/\*\*Priority\*\*:\s*(P[0-3])/);
+      title = titleMatch?.[1]?.trim() || title;
+      priority = (priorityMatch?.[1] as any) || priority;
+    }
+
+    return {
+      id: incrementId,
+      title,
+      priority,
+      status: 'planning'
+    };
+  }
+
+  /**
+   * Save increment metadata
+   */
+  private saveIncrementMetadata(metadata: IncrementMetadata): void {
+    const metadataPath = path.join(this.incrementPath, '.metadata.yaml');
+    fs.writeFileSync(metadataPath, yaml.dump(metadata), 'utf-8');
+  }
+
+  /**
+   * Save sync mapping
+   */
+  private saveSyncMapping(githubData: any): void {
+    const syncPath = path.join(this.incrementPath, '.github-sync.yaml');
+    fs.writeFileSync(syncPath, yaml.dump(githubData), 'utf-8');
+  }
+
+  /**
+   * Get milestone title from metadata
+   */
+  private getMilestoneTitle(metadata: IncrementMetadata): string {
+    return metadata.version ? `v${metadata.version}` : `Increment ${metadata.id}`;
+  }
+
+  /**
+   * Get GitHub file URL
+   */
+  private getGitHubFileURL(filename: string): string {
+    try {
+      const remote = this.client['detectRepo']();
+      const incrementId = path.basename(this.incrementPath);
+      return `https://github.com/${remote}/blob/develop/.specweave/increments/${incrementId}/${filename}`;
+    } catch {
+      return `#`;
+    }
+  }
+
+  /**
+   * Convert string to slug
+   */
+  private slugify(str: string): string {
+    return str
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+
+  /**
+   * Print dry run summary
+   */
+  private printDryRunSummary(tasks: Task[], metadata: IncrementMetadata): void {
+    console.log(`\n📊 Dry Run Summary:`);
+    console.log(`   Milestone: ${this.getMilestoneTitle(metadata)}`);
+    console.log(`   Epic: [INC-${metadata.id}] ${metadata.title}`);
+    console.log(`   Task Issues: ${tasks.length}`);
+    console.log(`\n📝 Would create:`);
+    tasks.forEach((task, i) => {
+      console.log(`   ${i + 1}. [${task.id}] ${task.title} (${task.estimate})`);
+    });
+  }
+}