/** * Global Duplicate Detection System for GitHub Issues * * CRITICAL ARCHITECTURE: * ALL GitHub issue creation in SpecWeave MUST use this module. * This is the SINGLE SOURCE OF TRUTH for duplicate prevention. * * THREE-PHASE PROTECTION: * 1. Detection (Before Create): Search GitHub for existing issues * 2. Verification (After Create): Count check to detect duplicates * 3. Reflection (Auto-Correct): Close duplicate issues automatically * * USAGE: * ```typescript * // Simple: Create with full protection * const result = await DuplicateDetector.createWithProtection({ * title: '[FS-031] Feature Title', * body: 'Description...', * titlePattern: '[FS-031]', * labels: ['specweave', 'feature'] * }); * * // Manual: Check before creating * const existing = await DuplicateDetector.checkBeforeCreate('[FS-031]'); * if (!existing) { * // Create issue... * } * ``` * * @module duplicate-detector */ export interface GitHubIssue { number: number; title: string; url: string; body?: string; state?: 'open' | 'closed'; createdAt?: string; } export interface VerificationResult { success: boolean; expectedCount: number; actualCount: number; duplicates: GitHubIssue[]; message: string; } export interface CorrectionResult { success: boolean; duplicatesClosed: number; keptIssue: number; errors: string[]; } export interface CreateOptions { title: string; body: string; titlePattern: string; incrementId?: string; labels?: string[]; milestone?: string; assignees?: string[]; repo?: string; } export interface CreateResult { issue: GitHubIssue; duplicatesFound: number; duplicatesClosed: number; wasReused: boolean; } export declare 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 checkBeforeCreate(titlePattern: string, incrementId?: string, repo?: string): Promise; /** * 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 verifyAfterCreate(titlePattern: string, expectedCount?: number, repo?: string): Promise; /** * 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 correctDuplicates(duplicates: GitHubIssue[], keepIssueNumber: number, repo?: string): Promise; /** * 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 createWithProtection(options: CreateOptions): Promise; /** * 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: string): string | null; /** * Utility: Check if GitHub CLI is available and authenticated * * @returns true if gh CLI is ready, false otherwise */ static checkGitHubCLI(): boolean; } //# sourceMappingURL=duplicate-detector.d.ts.map