Enhance error handling with custom error classes, retry logic, and contextual help

[Copilot]

Extension lacked specific error handling for different failure scenarios, making debugging difficult and providing generic user messages. This adds typed error classes with retry logic and actionable error messages.

Changes

Custom Error Classes (src/utils/error-handler.ts)

• TeamXRayBaseError base class with category, help links, retry config, stack trace preservation
• Specialized errors: NetworkError, AuthenticationError, RateLimitError, RepositoryError, MCPServiceError, AIServiceError, ValidationError
• Discriminated union ErrorCategory for type-safe error classification

Retry Logic

• ErrorHandler.withRetry() with exponential backoff + jitter
• Configurable via RetryOptions: maxRetries, baseDelayMs, maxDelayMs, shouldRetry predicate

Improved Error Handling in Core Methods

• gatherRepositoryData(): MCP status check errors, retry on transient failures, graceful fallback
• performStandardAnalysis(): Specific HTTP status handling (401/403 → auth, 429 → rate limit, 5xx → service error)
• findExpertForFile(): Proper error classification with fallback to local analysis

Additional

• Contextual help links per error category (opens relevant docs)
• Detailed diagnostics logging with timestamps and context
• Opt-in telemetry: setTelemetryEnabled(), getTelemetryEvents()

Usage

// Retry transient failures with backoff
const result = await ErrorHandler.withRetry(
  () => axios.post('https://models.github.ai/...'),
  'AI analysis',
  { maxRetries: 2, baseDelayMs: 2000 }
);

// Typed error handling
try {
  await gatherData();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after: ${error.resetTime}`);
  }
}

Original prompt

Enhance error handling throughout the extension to provide more specific, actionable error messages for different failure scenarios.

Acceptance Criteria

• Create custom error classes for different failure types
• Improve error messages in gatherRepositoryData() method
• Add retry logic for transient failures
• Show contextual help links in error messages
• Log detailed diagnostics to output channel
• Add error telemetry (opt-in)

Error Categories to Handle

• Network/API failures
• Authentication issues
• Rate limiting
• Invalid repository state
• MCP service unavailable
• AI service errors

Technical Notes

• Extend existing ErrorHandler utility in src/utils/error-handler.ts
• Use discriminated unions for error types
• Follow VS Code error message conventions
• Preserve stack traces for debugging

Files to Modify/Create

• src/utils/error-handler.ts - Extend with custom errors
• src/core/copilot-mcp-service.ts - Improve error handling
• src/core/expertise-analyzer.ts - Add specific error cases

This addresses GitHub issue #10.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.