specweave 0.21.2 → 0.22.0

package/plugins/specweave-github/lib/CodeValidator.ts

@@ -0,0 +1,284 @@
+/**
+ * Code Validator
+ *
+ * Validates that completed tasks have actual code implementation.
+ * Prevents marking tasks as complete when:
+ * - Files don't exist
+ * - Files are empty or have trivial content
+ * - Implementation is incomplete
+ *
+ * Used by ThreeLayerSyncManager to enforce code-completion discipline.
+ *
+ * @module CodeValidator
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * File validation result
+ */
+export interface FileValidationResult {
+  path: string;
+  exists: boolean;
+  hasContent: boolean;
+  lineCount: number;
+  reason?: string; // Why validation failed
+}
+
+/**
+ * Task validation result
+ */
+export interface TaskValidationResult {
+  taskId: string;
+  valid: boolean;
+  files: FileValidationResult[];
+  reason?: string; // Summary of why task validation failed
+}
+
+/**
+ * CodeValidator options
+ */
+export interface CodeValidatorOptions {
+  minLines?: number; // Minimum lines for a file to be considered non-empty (default: 3)
+  minChars?: number; // Minimum characters for meaningful content (default: 50)
+  projectRoot?: string; // Project root for resolving relative paths
+}
+
+export class CodeValidator {
+  private options: Required<CodeValidatorOptions>;
+
+  constructor(options: CodeValidatorOptions = {}) {
+    this.options = {
+      minLines: options.minLines ?? 3,
+      minChars: options.minChars ?? 50,
+      projectRoot: options.projectRoot ?? process.cwd()
+    };
+  }
+
+  /**
+   * Validate that code exists for a task
+   *
+   * Extracts file paths from task description and verifies:
+   * 1. Files exist
+   * 2. Files have meaningful content
+   * 3. Files are not just stubs
+   *
+   * @param taskDescription - Task description with file paths
+   * @param taskId - Task ID for error messages
+   * @returns Validation result
+   */
+  async validateTask(taskDescription: string, taskId: string): Promise<TaskValidationResult> {
+    const filePaths = this.extractFilePaths(taskDescription);
+
+    if (filePaths.length === 0) {
+      // No file paths specified - consider it valid (task might be non-code)
+      return {
+        taskId,
+        valid: true,
+        files: [],
+        reason: 'No file paths specified in task description'
+      };
+    }
+
+    const fileResults: FileValidationResult[] = [];
+    let allValid = true;
+    const reasons: string[] = [];
+
+    for (const filePath of filePaths) {
+      const result = await this.validateFile(filePath);
+      fileResults.push(result);
+
+      if (!result.exists) {
+        allValid = false;
+        reasons.push(`File not found: ${filePath}`);
+      } else if (!result.hasContent) {
+        allValid = false;
+        reasons.push(`File has no meaningful content: ${filePath} (${result.reason})`);
+      }
+    }
+
+    return {
+      taskId,
+      valid: allValid,
+      files: fileResults,
+      reason: reasons.length > 0 ? reasons.join('; ') : undefined
+    };
+  }
+
+  /**
+   * Validate a single file
+   *
+   * @param filePath - Path to file (relative or absolute)
+   * @returns File validation result
+   */
+  async validateFile(filePath: string): Promise<FileValidationResult> {
+    // Resolve relative paths
+    const absolutePath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(this.options.projectRoot, filePath);
+
+    // Check if file exists
+    const exists = await fs.pathExists(absolutePath);
+    if (!exists) {
+      return {
+        path: filePath,
+        exists: false,
+        hasContent: false,
+        lineCount: 0,
+        reason: 'File does not exist'
+      };
+    }
+
+    // Read file content
+    const content = await fs.readFile(absolutePath, 'utf-8');
+    const lines = content.split('\n');
+    const nonEmptyLines = lines.filter(line => line.trim().length > 0);
+
+    // Check line count
+    if (nonEmptyLines.length < this.options.minLines) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${nonEmptyLines.length} non-empty lines (minimum: ${this.options.minLines})`
+      };
+    }
+
+    // Check character count
+    const trimmedContent = content.trim();
+    if (trimmedContent.length < this.options.minChars) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: `Only ${trimmedContent.length} characters (minimum: ${this.options.minChars})`
+      };
+    }
+
+    // Check for stub patterns (common placeholder patterns)
+    const stubPatterns = [
+      /^\/\/\s*TODO:/i,
+      /^#\s*TODO:/i,
+      /^\s*throw new Error\(['"]Not implemented['"]\)/i,
+      /^\s*return null;?\s*$/m,
+      /^\s*pass\s*$/m, // Python
+      /^\s*\.\.\.$/m    // TypeScript
+    ];
+
+    const isStub = stubPatterns.some(pattern => pattern.test(trimmedContent));
+    if (isStub) {
+      return {
+        path: filePath,
+        exists: true,
+        hasContent: false,
+        lineCount: nonEmptyLines.length,
+        reason: 'File contains stub/placeholder code'
+      };
+    }
+
+    // All checks passed
+    return {
+      path: filePath,
+      exists: true,
+      hasContent: true,
+      lineCount: nonEmptyLines.length
+    };
+  }
+
+  /**
+   * Extract file paths from task description
+   *
+   * Supports multiple formats:
+   * - **Files**: src/foo.ts, src/bar.ts
+   * - **Files to create**: src/foo.ts
+   * - **Files to modify**: src/bar.ts
+   * - Inline code blocks with file paths
+   *
+   * @param description - Task description text
+   * @returns Array of file paths
+   */
+  extractFilePaths(description: string): string[] {
+    const paths: Set<string> = new Set();
+
+    // Pattern 1: **Files**: path1, path2, path3
+    const filesMatch = description.match(/\*\*Files\*\*:\s*([^\n]+)/i);
+    if (filesMatch) {
+      const filePaths = filesMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 2: **Files to create**: path1, path2
+    const createMatch = description.match(/\*\*Files to create\*\*:\s*([^\n]+)/i);
+    if (createMatch) {
+      const filePaths = createMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 3: **Files to modify**: path1, path2
+    const modifyMatch = description.match(/\*\*Files to modify\*\*:\s*([^\n]+)/i);
+    if (modifyMatch) {
+      const filePaths = modifyMatch[1].split(',').map(p => p.trim());
+      filePaths.forEach(p => paths.add(p));
+    }
+
+    // Pattern 4: Inline file references (e.g., `src/foo/bar.ts`)
+    const inlineMatches = description.matchAll(/`([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))`/g);
+    for (const match of inlineMatches) {
+      paths.add(match[1]);
+    }
+
+    // Pattern 5: Markdown list items with file paths
+    const listMatches = description.matchAll(/^[-*]\s+([a-zA-Z0-9_\-./]+\.(ts|js|tsx|jsx|py|java|go|rs|cpp|c|h))/gm);
+    for (const match of listMatches) {
+      paths.add(match[1]);
+    }
+
+    return Array.from(paths);
+  }
+
+  /**
+   * Batch validate multiple tasks
+   *
+   * @param tasks - Array of {taskId, description}
+   * @returns Array of validation results
+   */
+  async validateTasks(tasks: Array<{ taskId: string; description: string }>): Promise<TaskValidationResult[]> {
+    // Use parallel validation for performance
+    const validationPromises = tasks.map(task =>
+      this.validateTask(task.description, task.taskId)
+    );
+
+    return Promise.all(validationPromises);
+  }
+
+  /**
+   * Get summary of validation results
+   *
+   * @param results - Array of task validation results
+   * @returns Summary statistics
+   */
+  summarizeResults(results: TaskValidationResult[]): {
+    total: number;
+    valid: number;
+    invalid: number;
+    noFiles: number;
+    invalidTasks: string[];
+  } {
+    const total = results.length;
+    const valid = results.filter(r => r.valid).length;
+    const invalid = results.filter(r => !r.valid).length;
+    const noFiles = results.filter(r => r.files.length === 0).length;
+    const invalidTasks = results.filter(r => !r.valid).map(r => r.taskId);
+
+    return {
+      total,
+      valid,
+      invalid,
+      noFiles,
+      invalidTasks
+    };
+  }
+}

package/plugins/specweave-github/lib/IssueStateManager.js

@@ -0,0 +1,117 @@
+class IssueStateManager {
+  /**
+   * Determine issue state based on progress
+   *
+   * @param progress - Progress information
+   * @param currentState - Current issue state
+   * @returns State change result
+   */
+  static determineState(progress, currentState) {
+    const result = {
+      previousState: currentState,
+      newState: currentState,
+      changed: false,
+      labelsAdded: [],
+      labelsRemoved: []
+    };
+    if (progress.isComplete) {
+      result.newState = "closed";
+      result.labelsRemoved.push("in-progress");
+    } else if (progress.overallPercentage > 0) {
+      result.newState = "open";
+      result.labelsAdded.push("in-progress");
+    } else {
+      result.newState = "open";
+      result.labelsRemoved.push("in-progress");
+    }
+    result.changed = result.newState !== result.previousState;
+    return result;
+  }
+  /**
+   * Calculate progress from acceptance criteria and tasks
+   *
+   * @param acs - Acceptance criteria
+   * @param tasks - Tasks
+   * @returns Progress information
+   */
+  static calculateProgress(acs, tasks) {
+    const totalAcs = acs.length;
+    const completedAcs = acs.filter((ac) => ac.completed).length;
+    const acPercentage = totalAcs > 0 ? Math.round(completedAcs / totalAcs * 100) : 0;
+    const totalTasks = tasks.length;
+    const completedTasks = tasks.filter((t) => t.completed).length;
+    const taskPercentage = totalTasks > 0 ? Math.round(completedTasks / totalTasks * 100) : 0;
+    const overallPercentage = totalTasks > 0 ? Math.round((acPercentage + taskPercentage) / 2) : acPercentage;
+    const isComplete = totalAcs > 0 && completedAcs === totalAcs && (totalTasks === 0 || completedTasks === totalTasks);
+    return {
+      totalAcs,
+      completedAcs,
+      acPercentage,
+      totalTasks,
+      completedTasks,
+      taskPercentage,
+      overallPercentage,
+      isComplete
+    };
+  }
+  /**
+   * Format progress as markdown
+   *
+   * @param progress - Progress information
+   * @returns Markdown string
+   */
+  static formatProgressMarkdown(progress) {
+    const sections = [];
+    sections.push("## Progress");
+    sections.push("");
+    sections.push(`**Acceptance Criteria**: ${progress.completedAcs}/${progress.totalAcs} (${progress.acPercentage}%)`);
+    if (progress.totalTasks > 0) {
+      sections.push(`**Tasks**: ${progress.completedTasks}/${progress.totalTasks} (${progress.taskPercentage}%)`);
+    }
+    sections.push(`**Overall**: ${progress.overallPercentage}%`);
+    const progressBar = this.generateProgressBar(progress.overallPercentage);
+    sections.push("");
+    sections.push(progressBar);
+    return sections.join("\n");
+  }
+  /**
+   * Generate ASCII progress bar
+   *
+   * @param percentage - Completion percentage (0-100)
+   * @returns Progress bar string
+   */
+  static generateProgressBar(percentage) {
+    const total = 20;
+    const filled = Math.round(percentage / 100 * total);
+    const empty = total - filled;
+    const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
+    return `\`${bar}\` ${percentage}%`;
+  }
+  /**
+   * Build GitHub CLI command to update issue state
+   *
+   * @param issueNumber - GitHub issue number
+   * @param state - New state
+   * @param labelsToAdd - Labels to add
+   * @param labelsToRemove - Labels to remove
+   * @returns gh CLI command
+   */
+  static buildGitHubCommand(issueNumber, state, labelsToAdd, labelsToRemove) {
+    const commands = [];
+    if (state === "closed") {
+      commands.push(`gh issue close ${issueNumber}`);
+    } else {
+      commands.push(`gh issue reopen ${issueNumber}`);
+    }
+    if (labelsToAdd.length > 0) {
+      commands.push(`gh issue edit ${issueNumber} --add-label "${labelsToAdd.join(",")}"`);
+    }
+    if (labelsToRemove.length > 0) {
+      commands.push(`gh issue edit ${issueNumber} --remove-label "${labelsToRemove.join(",")}"`);
+    }
+    return commands.join(" && ");
+  }
+}
+export {
+  IssueStateManager
+};

package/plugins/specweave-github/lib/IssueStateManager.ts

@@ -0,0 +1,231 @@
+/**
+ * Issue State Manager - Auto-update GitHub issue state based on progress
+ *
+ * Rules:
+ * - 0% complete → State = open
+ * - 1-99% complete → State = open, label = in-progress
+ * - 100% complete → State = closed
+ */
+
+/**
+ * Issue state
+ */
+export type IssueState = 'open' | 'closed';
+
+/**
+ * State change result
+ */
+export interface StateChangeResult {
+  /** Previous state */
+  previousState: IssueState;
+
+  /** New state */
+  newState: IssueState;
+
+  /** State changed */
+  changed: boolean;
+
+  /** Labels added */
+  labelsAdded: string[];
+
+  /** Labels removed */
+  labelsRemoved: string[];
+}
+
+/**
+ * Progress info
+ */
+export interface ProgressInfo {
+  /** Total ACs */
+  totalAcs: number;
+
+  /** Completed ACs */
+  completedAcs: number;
+
+  /** AC completion percentage */
+  acPercentage: number;
+
+  /** Total tasks */
+  totalTasks: number;
+
+  /** Completed tasks */
+  completedTasks: number;
+
+  /** Task completion percentage */
+  taskPercentage: number;
+
+  /** Overall completion percentage */
+  overallPercentage: number;
+
+  /** Is 100% complete */
+  isComplete: boolean;
+}
+
+/**
+ * IssueStateManager - Manages GitHub issue state
+ */
+export class IssueStateManager {
+  /**
+   * Determine issue state based on progress
+   *
+   * @param progress - Progress information
+   * @param currentState - Current issue state
+   * @returns State change result
+   */
+  static determineState(
+    progress: ProgressInfo,
+    currentState: IssueState
+  ): StateChangeResult {
+    const result: StateChangeResult = {
+      previousState: currentState,
+      newState: currentState,
+      changed: false,
+      labelsAdded: [],
+      labelsRemoved: []
+    };
+
+    // Determine new state based on progress
+    if (progress.isComplete) {
+      // 100% complete → Close issue
+      result.newState = 'closed';
+      result.labelsRemoved.push('in-progress');
+    } else if (progress.overallPercentage > 0) {
+      // 1-99% complete → Open with in-progress label
+      result.newState = 'open';
+      result.labelsAdded.push('in-progress');
+    } else {
+      // 0% complete → Open without in-progress label
+      result.newState = 'open';
+      result.labelsRemoved.push('in-progress');
+    }
+
+    // Check if state changed
+    result.changed = result.newState !== result.previousState;
+
+    return result;
+  }
+
+  /**
+   * Calculate progress from acceptance criteria and tasks
+   *
+   * @param acs - Acceptance criteria
+   * @param tasks - Tasks
+   * @returns Progress information
+   */
+  static calculateProgress(
+    acs: Array<{ completed: boolean }>,
+    tasks: Array<{ completed: boolean }>
+  ): ProgressInfo {
+    const totalAcs = acs.length;
+    const completedAcs = acs.filter(ac => ac.completed).length;
+    const acPercentage = totalAcs > 0 ? Math.round((completedAcs / totalAcs) * 100) : 0;
+
+    const totalTasks = tasks.length;
+    const completedTasks = tasks.filter(t => t.completed).length;
+    const taskPercentage = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0;
+
+    // Overall percentage: average of AC and Task percentages
+    // If no tasks, use AC percentage only
+    const overallPercentage = totalTasks > 0
+      ? Math.round((acPercentage + taskPercentage) / 2)
+      : acPercentage;
+
+    const isComplete = totalAcs > 0 && completedAcs === totalAcs &&
+      (totalTasks === 0 || completedTasks === totalTasks);
+
+    return {
+      totalAcs,
+      completedAcs,
+      acPercentage,
+      totalTasks,
+      completedTasks,
+      taskPercentage,
+      overallPercentage,
+      isComplete
+    };
+  }
+
+  /**
+   * Format progress as markdown
+   *
+   * @param progress - Progress information
+   * @returns Markdown string
+   */
+  static formatProgressMarkdown(progress: ProgressInfo): string {
+    const sections: string[] = [];
+
+    sections.push('## Progress');
+    sections.push('');
+
+    // AC progress
+    sections.push(`**Acceptance Criteria**: ${progress.completedAcs}/${progress.totalAcs} (${progress.acPercentage}%)`);
+
+    // Task progress
+    if (progress.totalTasks > 0) {
+      sections.push(`**Tasks**: ${progress.completedTasks}/${progress.totalTasks} (${progress.taskPercentage}%)`);
+    }
+
+    // Overall progress
+    sections.push(`**Overall**: ${progress.overallPercentage}%`);
+
+    // Progress bar
+    const progressBar = this.generateProgressBar(progress.overallPercentage);
+    sections.push('');
+    sections.push(progressBar);
+
+    return sections.join('\n');
+  }
+
+  /**
+   * Generate ASCII progress bar
+   *
+   * @param percentage - Completion percentage (0-100)
+   * @returns Progress bar string
+   */
+  private static generateProgressBar(percentage: number): string {
+    const total = 20;
+    const filled = Math.round((percentage / 100) * total);
+    const empty = total - filled;
+
+    const bar = '█'.repeat(filled) + '░'.repeat(empty);
+
+    return `\`${bar}\` ${percentage}%`;
+  }
+
+  /**
+   * Build GitHub CLI command to update issue state
+   *
+   * @param issueNumber - GitHub issue number
+   * @param state - New state
+   * @param labelsToAdd - Labels to add
+   * @param labelsToRemove - Labels to remove
+   * @returns gh CLI command
+   */
+  static buildGitHubCommand(
+    issueNumber: number,
+    state: IssueState,
+    labelsToAdd: string[],
+    labelsToRemove: string[]
+  ): string {
+    const commands: string[] = [];
+
+    // Update state
+    if (state === 'closed') {
+      commands.push(`gh issue close ${issueNumber}`);
+    } else {
+      commands.push(`gh issue reopen ${issueNumber}`);
+    }
+
+    // Add labels
+    if (labelsToAdd.length > 0) {
+      commands.push(`gh issue edit ${issueNumber} --add-label "${labelsToAdd.join(',')}"`);
+    }
+
+    // Remove labels
+    if (labelsToRemove.length > 0) {
+      commands.push(`gh issue edit ${issueNumber} --remove-label "${labelsToRemove.join(',')}"`);
+    }
+
+    return commands.join(' && ');
+  }
+}