mdcontext 0.1.0 → 0.2.0

package/src/summarization/error-handler.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Tests for Error Handler Module
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  formatSummarizationError,
+  isRecoverableError,
+} from './error-handler.js'
+import { SummarizationError } from './types.js'
+
+describe('formatSummarizationError', () => {
+  describe('SummarizationError handling', () => {
+    it('should format PROVIDER_NOT_AVAILABLE with install URL', () => {
+      const error = new SummarizationError(
+        'Claude not installed',
+        'PROVIDER_NOT_AVAILABLE',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('not available')
+      expect(message).toContain('https://claude.ai/download')
+    })
+
+    it('should format NO_API_KEY with env var hint', () => {
+      const error = new SummarizationError(
+        'API key missing',
+        'NO_API_KEY',
+        'deepseek',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('API key')
+      expect(message).toContain('DEEPSEEK_API_KEY')
+    })
+
+    it('should format RATE_LIMITED with CLI suggestion', () => {
+      const error = new SummarizationError(
+        'Rate limit hit',
+        'RATE_LIMITED',
+        'openai',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('Rate limit')
+      expect(message).toContain('CLI provider')
+    })
+
+    it('should format CLI_EXECUTION_FAILED with details', () => {
+      const error = new SummarizationError(
+        'Process exited with code 1',
+        'CLI_EXECUTION_FAILED',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('CLI error')
+      expect(message).toContain('Process exited with code 1')
+    })
+
+    it('should handle TIMEOUT errors', () => {
+      const error = new SummarizationError(
+        'Something went wrong',
+        'TIMEOUT',
+        'claude',
+      )
+      const message = formatSummarizationError(error)
+
+      expect(message).toContain('timed out')
+    })
+  })
+
+  describe('generic Error handling', () => {
+    it('should extract message from regular Error', () => {
+      const error = new Error('Network failed')
+      const message = formatSummarizationError(error)
+
+      expect(message).toBe('Network failed')
+    })
+  })
+
+  describe('unknown error handling', () => {
+    it('should handle null/undefined', () => {
+      expect(formatSummarizationError(null)).toBe(
+        'An unknown error occurred during summarization.',
+      )
+      expect(formatSummarizationError(undefined)).toBe(
+        'An unknown error occurred during summarization.',
+      )
+    })
+  })
+})
+
+describe('isRecoverableError', () => {
+  it('should return true for API_REQUEST_FAILED', () => {
+    const error = new SummarizationError(
+      'Request failed',
+      'API_REQUEST_FAILED',
+      'deepseek',
+    )
+    expect(isRecoverableError(error)).toBe(true)
+  })
+
+  it('should return true for TIMEOUT', () => {
+    const error = new SummarizationError('Timed out', 'TIMEOUT', 'claude')
+    expect(isRecoverableError(error)).toBe(true)
+  })
+
+  it('should return false for RATE_LIMITED', () => {
+    const error = new SummarizationError(
+      'Rate limited',
+      'RATE_LIMITED',
+      'openai',
+    )
+    expect(isRecoverableError(error)).toBe(false)
+  })
+
+  it('should return false for NO_API_KEY', () => {
+    const error = new SummarizationError('No key', 'NO_API_KEY', 'anthropic')
+    expect(isRecoverableError(error)).toBe(false)
+  })
+
+  it('should return false for non-SummarizationError', () => {
+    expect(isRecoverableError(new Error('Generic'))).toBe(false)
+  })
+})

package/src/summarization/error-handler.ts

@@ -0,0 +1,111 @@
+/**
+ * Error Handler for Summarization
+ *
+ * Provides user-friendly error messages and graceful degradation.
+ * Ensures summarization failures don't crash the CLI.
+ */
+
+import { SummarizationError, type SummarizationErrorCode } from './types.js'
+
+/**
+ * Error message templates for different error codes.
+ */
+const ERROR_MESSAGES: Record<SummarizationErrorCode, string> = {
+  PROVIDER_NOT_FOUND: 'Summarization provider not found.',
+  PROVIDER_NOT_AVAILABLE:
+    'Summarization provider is not available. Check installation.',
+  CLI_EXECUTION_FAILED: 'CLI execution failed.',
+  API_REQUEST_FAILED: 'API request failed.',
+  RATE_LIMITED: 'Rate limit exceeded. Please try again later.',
+  INVALID_RESPONSE: 'Received invalid response from provider.',
+  TIMEOUT: 'Request timed out. Try again or reduce result count.',
+  NO_API_KEY: 'API key not configured.',
+}
+
+/**
+ * Installation URLs for CLI providers.
+ */
+const CLI_INSTALL_URLS: Record<string, string> = {
+  claude: 'https://claude.ai/download',
+  copilot: 'https://github.com/features/copilot',
+  opencode: 'https://github.com/opencode-ai/opencode',
+  aider: 'https://aider.chat',
+  cline: 'https://github.com/cline/cline',
+}
+
+/**
+ * Environment variable names for API keys.
+ */
+const API_KEY_ENV_VARS: Record<string, string> = {
+  deepseek: 'DEEPSEEK_API_KEY',
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  gemini: 'GOOGLE_API_KEY',
+  qwen: 'QWEN_API_KEY',
+}
+
+/**
+ * Format a SummarizationError into a user-friendly message.
+ */
+export const formatSummarizationError = (error: unknown): string => {
+  if (error instanceof SummarizationError) {
+    const baseMessage = ERROR_MESSAGES[error.code] ?? error.message
+
+    // Add provider-specific hints
+    if (error.code === 'PROVIDER_NOT_AVAILABLE' && error.provider) {
+      const installUrl = CLI_INSTALL_URLS[error.provider]
+      if (installUrl) {
+        return `${baseMessage}\n   Install ${error.provider}: ${installUrl}`
+      }
+    }
+
+    if (error.code === 'NO_API_KEY' && error.provider) {
+      const envVar = API_KEY_ENV_VARS[error.provider]
+      if (envVar) {
+        return `${baseMessage}\n   Set environment variable: ${envVar}`
+      }
+    }
+
+    if (error.code === 'RATE_LIMITED') {
+      return `${baseMessage}\n   Try using a CLI provider (free with subscription) instead.`
+    }
+
+    if (error.code === 'CLI_EXECUTION_FAILED' && error.message) {
+      // Include the actual error message for CLI failures
+      return `CLI error: ${error.message}`
+    }
+
+    return baseMessage
+  }
+
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'An unknown error occurred during summarization.'
+}
+
+/**
+ * Check if an error is recoverable (can retry).
+ */
+export const isRecoverableError = (error: unknown): boolean => {
+  if (error instanceof SummarizationError) {
+    // These errors might succeed on retry
+    return ['API_REQUEST_FAILED', 'TIMEOUT'].includes(error.code)
+  }
+  return false
+}
+
+/**
+ * Create a console-friendly error display.
+ */
+export const displaySummarizationError = (error: unknown): void => {
+  const message = formatSummarizationError(error)
+
+  console.error('')
+  console.error('Summarization failed:')
+  console.error(`   ${message}`)
+  console.error('')
+  console.error('   Showing search results without summary.')
+  console.error('')
+}

package/src/summarization/index.ts

@@ -0,0 +1,102 @@
+/**
+ * Summarization Module
+ *
+ * AI-powered summarization of search results using CLI tools (free)
+ * or API providers (pay-per-use via Vercel AI SDK).
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createSummarizer, buildPrompt } from './summarization/index.js'
+ *
+ * // Create a summarizer from config
+ * const summarizer = await createSummarizer({
+ *   mode: 'cli',
+ *   provider: 'claude',
+ * })
+ *
+ * // Build prompt with context
+ * const prompt = buildPrompt({
+ *   query: 'authentication',
+ *   resultCount: 10,
+ *   searchMode: 'hybrid',
+ * })
+ *
+ * // Generate summary
+ * const result = await summarizer.summarize(searchResultsText, prompt)
+ * console.log(result.summary)
+ * ```
+ *
+ * ## Architecture
+ *
+ * - **CLI Providers**: Free with subscription (Claude Code, Copilot, etc.)
+ * - **API Providers**: Pay-per-use via Vercel AI SDK (DeepSeek, OpenAI, etc.)
+ * - **Detection**: Auto-detect installed CLI tools
+ * - **Factory**: Create providers from config
+ */
+
+// CLI providers
+export {
+  ClaudeCLISummarizer,
+  detectInstalledCLIs,
+  getCLIInfo,
+  isCLIInstalled,
+  KNOWN_CLIS,
+} from './cli-providers/index.js'
+// Cost estimation
+export type { CostEstimate } from './cost.js'
+export {
+  API_PRICING,
+  estimateSummaryCost,
+  estimateTokens,
+  formatCostDisplay,
+} from './cost.js'
+// Error handling
+export {
+  displaySummarizationError,
+  formatSummarizationError,
+  isRecoverableError,
+} from './error-handler.js'
+// Pipeline
+export type {
+  PipelineOptions,
+  PipelineResult,
+  SummarizableResult,
+} from './pipeline.js'
+export {
+  formatResultsForSummary,
+  runSummarizationPipeline,
+  summarizeResults,
+} from './pipeline.js'
+// Prompts
+export type { PromptTemplate, SearchContext } from './prompts.js'
+export {
+  ACTIONABLE_PROMPT,
+  buildPrompt,
+  CONCISE_PROMPT,
+  DEFAULT_PROMPT,
+  DETAILED_PROMPT,
+  getPromptTemplate,
+  TECHNICAL_PROMPT,
+} from './prompts.js'
+// Provider factory
+export {
+  createSummarizer,
+  getBestAvailableSummarizer,
+} from './provider-factory.js'
+// Core types
+export type {
+  AISummarizationConfig,
+  APIProviderName,
+  APIProviderPricing,
+  CLIInfo,
+  CLIProviderName,
+  StreamingSummarizer,
+  StreamOptions,
+  SummarizationErrorCode,
+  SummarizationMode,
+  Summarizer,
+  SummarizerFactory,
+  SummaryResult,
+} from './types.js'
+export { SummarizationError } from './types.js'