specweave 1.0.506 → 1.0.508

package/plugins/specweave/lib/integrations/github/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 GitHub sync to enforce code-completion discipline.
+ *
+ * @module CodeValidator
+ */
+
+import * as fs from '../../../../../src/utils/fs-native.js';
+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: string) => 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/lib/integrations/github/duplicate-detector.js

@@ -0,0 +1,397 @@
+import { execFileSync } from "child_process";
+import { getGitHubAuthFromProject } from "../../../../../src/utils/auth-helpers.js";
+function getGhEnv() {
+  const { token } = getGitHubAuthFromProject(process.cwd());
+  return token ? { ...process.env, GH_TOKEN: token } : process.env;
+}
+class DuplicateDetector {
+  /**
+   * PHASE 1: Detection (Before Creating Issue)
+   *
+   * Searches GitHub for existing issues matching the title pattern.
+   * This is the PRIMARY defense against duplicates.
+   *
+   * @param titlePattern - Pattern to search (e.g., "[FS-031]" current, "[INC-0031]" deprecated)
+   * @param incrementId - Optional increment ID for more precise matching
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Existing issue if found, null otherwise
+   */
+  static async checkBeforeCreate(titlePattern, incrementId, repo) {
+    console.log(`\u{1F50D} DETECTION: Checking for existing issue with pattern: ${titlePattern}`);
+    try {
+      const args = [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,url,body,createdAt",
+        "--limit",
+        "20",
+        "--state",
+        "all"
+        // Check both open and closed
+      ];
+      if (repo) {
+        args.push("--repo", repo);
+      }
+      const output = execFileSync("gh", args, { encoding: "utf-8", env: getGhEnv() });
+      const issues = JSON.parse(output);
+      if (issues.length === 0) {
+        console.log("   \u2705 No existing issues found (safe to create)");
+        return null;
+      }
+      console.log(`   \u{1F4CB} Found ${issues.length} issue(s) matching pattern`);
+      const exactMatch = issues.find(
+        (issue) => issue.title.includes(titlePattern)
+      );
+      if (exactMatch) {
+        console.log(`   \u26A0\uFE0F  DUPLICATE DETECTED: Issue #${exactMatch.number}`);
+        console.log(`   \u{1F4CE} URL: ${exactMatch.url}`);
+        return exactMatch;
+      }
+      if (incrementId) {
+        const bodyMatch = issues.find(
+          (issue) => issue.body && (issue.body.includes(`**Increment**: ${incrementId}`) || issue.body.includes(incrementId))
+        );
+        if (bodyMatch) {
+          console.log(`   \u26A0\uFE0F  DUPLICATE DETECTED (body match): Issue #${bodyMatch.number}`);
+          console.log(`   \u{1F4CE} URL: ${bodyMatch.url}`);
+          return bodyMatch;
+        }
+      }
+      console.log("   \u2705 No exact match found (safe to create)");
+      return null;
+    } catch (error) {
+      console.warn(`   \u26A0\uFE0F  Detection failed (continuing anyway): ${error.message}`);
+      return null;
+    }
+  }
+  /**
+   * PHASE 2: Verification (After Creating Issue)
+   *
+   * Counts issues matching the pattern and identifies duplicates.
+   * This is the SECONDARY defense - catches duplicates that slipped through.
+   *
+   * @param titlePattern - Pattern to search (e.g., "[FS-031]")
+   * @param expectedCount - Expected number of issues (usually 1)
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Verification result with duplicate list
+   */
+  static async verifyAfterCreate(titlePattern, expectedCount = 1, repo) {
+    console.log(`
+\u{1F50D} VERIFICATION: Checking issue count for pattern: ${titlePattern}`);
+    await new Promise((resolve) => setTimeout(resolve, 2e3));
+    try {
+      const args = [
+        "issue",
+        "list",
+        "--search",
+        `"${titlePattern}" in:title`,
+        "--json",
+        "number,title,url,createdAt",
+        "--limit",
+        "50",
+        "--state",
+        "all"
+      ];
+      if (repo) {
+        args.push("--repo", repo);
+      }
+      const output = execFileSync("gh", args, { encoding: "utf-8", env: getGhEnv() });
+      const issues = JSON.parse(output);
+      const exactMatches = issues.filter(
+        (issue) => issue.title.includes(titlePattern)
+      );
+      const actualCount = exactMatches.length;
+      console.log(`   Expected: ${expectedCount} issue(s)`);
+      console.log(`   Actual: ${actualCount} issue(s)`);
+      if (actualCount === expectedCount) {
+        console.log(`   \u2705 VERIFICATION PASSED: Count matches!`);
+        return {
+          success: true,
+          expectedCount,
+          actualCount,
+          duplicates: [],
+          message: "Verification passed"
+        };
+      } else if (actualCount > expectedCount) {
+        console.warn(`   \u26A0\uFE0F  VERIFICATION FAILED: ${actualCount - expectedCount} duplicate(s) detected!`);
+        const sorted = exactMatches.sort((a, b) => {
+          const dateA = new Date(a.createdAt || 0).getTime();
+          const dateB = new Date(b.createdAt || 0).getTime();
+          return dateA - dateB;
+        });
+        const duplicates = sorted.slice(1);
+        console.warn(`   \u{1F4CB} Duplicate issues:`);
+        duplicates.forEach((dup) => {
+          console.warn(`      - #${dup.number}: ${dup.title}`);
+        });
+        return {
+          success: false,
+          expectedCount,
+          actualCount,
+          duplicates,
+          message: `${duplicates.length} duplicate(s) found`
+        };
+      } else {
+        console.warn(`   \u26A0\uFE0F  VERIFICATION WARNING: Expected ${expectedCount} but found ${actualCount}`);
+        return {
+          success: false,
+          expectedCount,
+          actualCount,
+          duplicates: [],
+          message: "Count mismatch (fewer than expected)"
+        };
+      }
+    } catch (error) {
+      console.error(`   \u274C Verification failed: ${error.message}`);
+      return {
+        success: false,
+        expectedCount,
+        actualCount: -1,
+        duplicates: [],
+        message: `Verification error: ${error.message}`
+      };
+    }
+  }
+  /**
+   * PHASE 3: Reflection (Auto-Correct Duplicates)
+   *
+   * Automatically closes duplicate issues and keeps the oldest one.
+   * This is the CLEANUP phase - fixes problems that occurred.
+   *
+   * @param duplicates - List of duplicate issues to close
+   * @param keepIssueNumber - Issue number to keep (usually the oldest)
+   * @param repo - Optional repo (format: "owner/repo")
+   * @returns Correction result with count of closed issues
+   */
+  static async correctDuplicates(duplicates, keepIssueNumber, repo) {
+    if (duplicates.length === 0) {
+      return {
+        success: true,
+        duplicatesClosed: 0,
+        keptIssue: keepIssueNumber,
+        errors: []
+      };
+    }
+    console.log(`
+\u{1F527} REFLECTION: Auto-correcting ${duplicates.length} duplicate(s)...`);
+    const errors = [];
+    let closed = 0;
+    for (const duplicate of duplicates) {
+      try {
+        console.log(`   \u{1F5D1}\uFE0F  Closing duplicate #${duplicate.number}...`);
+        const comment = `Duplicate of #${keepIssueNumber}
+
+This issue was automatically closed by SpecWeave's Global Duplicate Detection System.
+
+The original issue (#${keepIssueNumber}) should be used for tracking instead.
+
+\u{1F916} Auto-closed by SpecWeave`;
+        const commentArgs = [
+          "issue",
+          "comment",
+          duplicate.number.toString(),
+          "--body",
+          comment
+        ];
+        if (repo) {
+          commentArgs.push("--repo", repo);
+        }
+        execFileSync("gh", commentArgs, { encoding: "utf-8", env: getGhEnv() });
+        const closeArgs = [
+          "issue",
+          "close",
+          duplicate.number.toString()
+        ];
+        if (repo) {
+          closeArgs.push("--repo", repo);
+        }
+        execFileSync("gh", closeArgs, { encoding: "utf-8", env: getGhEnv() });
+        console.log(`      \u2705 Closed #${duplicate.number}`);
+        closed++;
+      } catch (error) {
+        const errorMsg = `Failed to close #${duplicate.number}: ${error.message}`;
+        console.error(`      \u274C ${errorMsg}`);
+        errors.push(errorMsg);
+      }
+    }
+    console.log(`
+   \u2705 REFLECTION COMPLETE: Kept #${keepIssueNumber}, closed ${closed}/${duplicates.length} duplicate(s)`);
+    return {
+      success: errors.length === 0,
+      duplicatesClosed: closed,
+      keptIssue: keepIssueNumber,
+      errors
+    };
+  }
+  /**
+   * ALL-IN-ONE: Create Issue with Full Protection
+   *
+   * This is the RECOMMENDED way to create GitHub issues in SpecWeave.
+   * Combines all 3 phases: Detection → Creation → Verification → Reflection
+   *
+   * GUARANTEES:
+   * - No duplicates will be created
+   * - Existing duplicates will be detected and closed
+   * - Idempotent: can run multiple times safely
+   *
+   * @param options - Create options (title, body, labels, etc.)
+   * @returns Create result with issue details and duplicate stats
+   */
+  static async createWithProtection(options) {
+    const {
+      title,
+      body,
+      titlePattern,
+      incrementId,
+      labels = ["specweave"],
+      milestone,
+      assignees = [],
+      repo
+    } = options;
+    console.log(`
+\u{1F6E1}\uFE0F  Creating GitHub issue with FULL PROTECTION...`);
+    console.log(`   Title: ${title}`);
+    console.log(`   Pattern: ${titlePattern}`);
+    console.log(`
+\u2501\u2501\u2501 PHASE 1: DETECTION \u2501\u2501\u2501`);
+    const existing = await this.checkBeforeCreate(titlePattern, incrementId, repo);
+    let issueNumber;
+    let issueUrl;
+    let wasReused = false;
+    if (existing) {
+      console.log(`
+\u267B\uFE0F  Using existing issue #${existing.number} (skipping creation)`);
+      issueNumber = existing.number;
+      issueUrl = existing.url;
+      wasReused = true;
+    } else {
+      console.log(`
+\u2501\u2501\u2501 PHASE 2: CREATION \u2501\u2501\u2501`);
+      console.log(`   Creating new GitHub issue...`);
+      try {
+        const safeLabels = labels.filter((l) => /^[a-zA-Z0-9:_\- ]+$/.test(l));
+        if (repo) {
+          for (const label of safeLabels) {
+            try {
+              execFileSync("gh", [
+                "label",
+                "create",
+                label,
+                "--repo",
+                repo,
+                "--color",
+                "ededed",
+                "--description",
+                "SpecWeave auto-label",
+                "--force"
+              ], { encoding: "utf-8", env: getGhEnv() });
+            } catch {
+            }
+          }
+        }
+        const args = [
+          "issue",
+          "create",
+          "--title",
+          title,
+          "--body",
+          body
+        ];
+        if (repo) {
+          args.push("--repo", repo);
+        }
+        safeLabels.forEach((label) => {
+          args.push("--label", label);
+        });
+        if (milestone) {
+          args.push("--milestone", milestone);
+        }
+        assignees.forEach((assignee) => {
+          args.push("--assignee", assignee);
+        });
+        const output = execFileSync("gh", args, { encoding: "utf-8", env: getGhEnv() });
+        const match = output.match(/\/issues\/(\d+)/);
+        if (!match) {
+          throw new Error("Could not extract issue number from gh CLI output");
+        }
+        issueNumber = parseInt(match[1], 10);
+        issueUrl = output.trim();
+        console.log(`   \u2705 Created issue #${issueNumber}`);
+        console.log(`   \u{1F4CE} ${issueUrl}`);
+      } catch (error) {
+        throw new Error(`Failed to create GitHub issue: ${error.message}`);
+      }
+    }
+    let duplicatesClosed = 0;
+    if (process.env.SPECWEAVE_VERIFY_DUPLICATES === "1") {
+      console.log(`
+\u2501\u2501\u2501 PHASE 3: VERIFICATION \u2501\u2501\u2501`);
+      const verification = await this.verifyAfterCreate(titlePattern, 1, repo);
+      if (!verification.success && verification.duplicates.length > 0) {
+        console.log(`
+\u2501\u2501\u2501 PHASE 4: REFLECTION \u2501\u2501\u2501`);
+        console.warn(`   \u26A0\uFE0F  ${verification.duplicates.length} duplicate(s) detected!`);
+        const correction = await this.correctDuplicates(
+          verification.duplicates,
+          issueNumber,
+          repo
+        );
+        duplicatesClosed = correction.duplicatesClosed;
+        if (correction.errors.length > 0) {
+          console.warn(`   \u26A0\uFE0F  Some duplicates could not be closed:`);
+          correction.errors.forEach((err) => console.warn(`      - ${err}`));
+        }
+      } else if (verification.success) {
+        console.log(`   \u2705 No duplicates detected!`);
+      }
+    }
+    console.log(`
+\u2705 Issue creation complete!`);
+    console.log(`   Issue: #${issueNumber}`);
+    console.log(`   Duplicates closed: ${duplicatesClosed}`);
+    console.log(`   Reused existing: ${wasReused ? "Yes" : "No"}`);
+    return {
+      issue: {
+        number: issueNumber,
+        title,
+        url: issueUrl
+      },
+      duplicatesFound: duplicatesClosed,
+      duplicatesClosed,
+      wasReused
+    };
+  }
+  /**
+   * Utility: Extract title pattern from full title
+   *
+   * Examples:
+   * - "[FS-031] Feature Title" → "[FS-031]" (current format)
+   * - "[INC-0031] Increment Title" → "[INC-0031]" (deprecated, legacy support only)
+   *
+   * @param title - Full issue title
+   * @returns Extracted pattern or null
+   */
+  static extractTitlePattern(title) {
+    const match = title.match(/^(\[[^\]]+\])/);
+    return match ? match[1] : null;
+  }
+  /**
+   * Utility: Check if GitHub CLI is available and authenticated
+   *
+   * @returns true if gh CLI is ready, false otherwise
+   */
+  static checkGitHubCLI() {
+    try {
+      execFileSync("gh", ["auth", "status"], { encoding: "utf-8", env: getGhEnv() });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+export {
+  DuplicateDetector
+};