codereview-aia 0.1.0

package/src/clients/base/responseProcessor.ts

@@ -0,0 +1,586 @@
+/**
+ * @fileoverview Common response processing and error handling for AI API clients.
+ *
+ * This module provides shared functionality for processing API responses,
+ * extracting structured data, handling errors, and standardizing output formats
+ * across different AI providers.
+ */
+
+import type { AIJsonResponse } from '../../types/apiResponses';
+import type { CostInfo, ReviewResult, ReviewType } from '../../types/review';
+import type { StructuredReview } from '../../types/structuredReview';
+import { ApiError } from '../../utils/apiErrorHandler';
+import { configurationService } from '../../core/ConfigurationService';
+import logger from '../../utils/logger';
+import { getCostInfoFromText } from '../utils/tokenCounter';
+
+/**
+ * Attempt to recover JSON from malformed responses using various strategies
+ * @param content The malformed response content
+ * @returns Parsed StructuredReview object or null if recovery fails
+ */
+function attemptJsonRecovery(content: string): StructuredReview | null {
+  const strategies = [
+    // Strategy 1: Remove leading language identifiers (e.g., "typescript\n{...}")
+    (text: string) => {
+      const match = text.match(/^(?:typescript|javascript|json|ts|js)\s*\n?\s*({[\s\S]*})$/i);
+      return match ? match[1] : null;
+    },
+
+    // Strategy 2: Extract JSON from markdown code blocks (most common case)
+    (text: string) => {
+      // Match various code block formats
+      const patterns = [
+        /```(?:json)?\s*([\s\S]*?)\s*```/,
+        /```(?:typescript|javascript|ts|js)?\s*([\s\S]*?)\s*```/,
+        /`([\s\S]*?)`/, // Single backtick blocks
+      ];
+
+      for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match && match[1]) {
+          const content = match[1].trim();
+          // Check if it looks like JSON
+          if (content.startsWith('{') && content.endsWith('}')) {
+            return content;
+          }
+        }
+      }
+      return null;
+    },
+
+    // Strategy 3: Extract JSON from mixed content (find first complete JSON object)
+    (text: string) => {
+      // Find balanced braces
+      const startIdx = text.indexOf('{');
+      if (startIdx === -1) return null;
+
+      let depth = 0;
+      let inString = false;
+      let escapeNext = false;
+
+      for (let i = startIdx; i < text.length; i++) {
+        const char = text[i];
+
+        if (escapeNext) {
+          escapeNext = false;
+          continue;
+        }
+
+        if (char === '\\') {
+          escapeNext = true;
+          continue;
+        }
+
+        if (char === '"' && !escapeNext) {
+          inString = !inString;
+          continue;
+        }
+
+        if (!inString) {
+          if (char === '{') depth++;
+          else if (char === '}') {
+            depth--;
+            if (depth === 0) {
+              return text.substring(startIdx, i + 1);
+            }
+          }
+        }
+      }
+
+      return null;
+    },
+
+    // Strategy 4: Look for JSON between quotes (e.g., "typescript\n{...}")
+    (text: string) => {
+      const match = text.match(/"[^"]*"\s*\n?\s*({[\s\S]*})/);
+      return match ? match[1] : null;
+    },
+
+    // Strategy 5: Remove everything before the first opening brace
+    (text: string) => {
+      const braceIndex = text.indexOf('{');
+      if (braceIndex === -1) return null;
+      return text.substring(braceIndex);
+    },
+
+    // Strategy 6: Fix unterminated strings by closing them
+    (text: string) => {
+      // If JSON parse fails due to unterminated string, try to fix it
+      const braceIndex = text.indexOf('{');
+      if (braceIndex === -1) return null;
+
+      let jsonStr = text.substring(braceIndex);
+
+      // Count open and closing quotes
+      let inString = false;
+      let escapeNext = false;
+      let lastQuoteIndex = -1;
+
+      for (let i = 0; i < jsonStr.length; i++) {
+        if (escapeNext) {
+          escapeNext = false;
+          continue;
+        }
+
+        if (jsonStr[i] === '\\') {
+          escapeNext = true;
+          continue;
+        }
+
+        if (jsonStr[i] === '"') {
+          inString = !inString;
+          if (inString) {
+            lastQuoteIndex = i;
+          }
+        }
+      }
+
+      // If we're still in a string at the end, close it
+      if (inString && lastQuoteIndex !== -1) {
+        // Find a reasonable place to close the string
+        // Look for common JSON structure patterns
+        const patterns = ['}', ']', ','];
+        let closeIndex = jsonStr.length;
+
+        for (const pattern of patterns) {
+          const idx = jsonStr.lastIndexOf(pattern);
+          if (idx > lastQuoteIndex) {
+            closeIndex = idx;
+            break;
+          }
+        }
+
+        // Insert closing quote before the structural character
+        jsonStr = jsonStr.substring(0, closeIndex) + '"' + jsonStr.substring(closeIndex);
+      }
+
+      return jsonStr;
+    },
+  ];
+
+  for (const strategy of strategies) {
+    try {
+      const extracted = strategy(content.trim());
+      if (extracted) {
+        const parsed = JSON.parse(extracted) as StructuredReview;
+        // Basic validation
+        if (typeof parsed === 'object' && parsed !== null) {
+          logger.debug('Successfully recovered JSON using recovery strategy');
+          return parsed;
+        }
+      }
+    } catch (_error) {}
+  }
+
+  return null;
+}
+
+/**
+ * Process API response content and extract structured data if possible
+ * @param content The API response content
+ * @returns Structured data object or null if not valid JSON
+ */
+export function extractStructuredData(content: string): StructuredReview | undefined {
+  // Declare these outside try block so they're accessible in catch block
+  let jsonBlockMatch: RegExpMatchArray | null = null;
+  let anyCodeBlockMatch: RegExpMatchArray | null = null;
+
+  try {
+    // Check if the response is wrapped in any code block with improved language marker handling
+    // Handle various formats:
+    // 1. ```json {...}```
+    // 2. ```typescript {...}``` or other language markers
+    // 3. ```{...}```
+    // 4. Plain JSON without code blocks
+
+    // Enhanced regex to handle various language markers
+    // First try to find explicit JSON blocks
+    jsonBlockMatch = content.match(/```(?:json)\s*([\s\S]*?)\s*```/) || null;
+
+    // If no explicit JSON block, look for any code block
+    if (!jsonBlockMatch) {
+      // Try different code block patterns
+      const codeBlockPatterns = [
+        /```(?:typescript|ts)\s*([\s\S]*?)\s*```/,
+        /```(?:javascript|js)\s*([\s\S]*?)\s*```/,
+        /```\s*([\s\S]*?)\s*```/, // Code block without language
+      ];
+
+      for (const pattern of codeBlockPatterns) {
+        anyCodeBlockMatch = content.match(pattern);
+        if (anyCodeBlockMatch) {
+          logger.debug(`Found code block with pattern: ${pattern.source}`);
+          break;
+        }
+      }
+
+      // Additional check for typescript blocks specifically
+      if (anyCodeBlockMatch && (content.includes('```typescript') || content.includes('```ts'))) {
+        logger.debug('Detected typescript code block, will check if it contains valid JSON');
+      }
+    }
+
+    let jsonContent = '';
+
+    if (jsonBlockMatch) {
+      // If we have a JSON code block, use its content
+      jsonContent = jsonBlockMatch[1] || '';
+      logger.debug('Found JSON code block, extracting content');
+    } else if (anyCodeBlockMatch) {
+      // If we have any other code block, use its content but check if it starts with {
+      const blockContent = (anyCodeBlockMatch[1] || '').trim();
+
+      // Special handling for TypeScript blocks that might contain JSON objects
+      if (content.includes('```typescript') || content.includes('```ts')) {
+        logger.debug('Analyzing TypeScript code block for JSON content');
+
+        // Check if the TypeScript block contains a JSON object literal
+        if (blockContent.includes('{') && blockContent.includes('}')) {
+          // Look for a properly formatted object within the TypeScript code
+          const objectMatch = blockContent.match(/(\{[\s\S]*\})/);
+          if (objectMatch?.[1]) {
+            const potentialJson = objectMatch[1].trim();
+            try {
+              // Try to verify it's parsable JSON
+              JSON.parse(potentialJson);
+              jsonContent = potentialJson;
+              logger.debug('Successfully extracted JSON object from TypeScript code block');
+            } catch (_parseError) {
+              // Not valid JSON, continue with regular processing
+              logger.debug('TypeScript block contains object syntax but not valid JSON');
+              if (blockContent.startsWith('{') && blockContent.endsWith('}')) {
+                jsonContent = blockContent;
+                logger.debug('Using TypeScript block content for potential parsing');
+              } else {
+                logger.debug(
+                  'TypeScript code block is not JSON-compatible, falling back to raw content',
+                );
+                jsonContent = content;
+              }
+            }
+          } else {
+            logger.debug('No valid object literal found in TypeScript code block');
+            jsonContent = content;
+          }
+        } else {
+          logger.debug(
+            "TypeScript code block doesn't contain object literals, falling back to raw content",
+          );
+          jsonContent = content;
+        }
+      } else if (blockContent.startsWith('{') && blockContent.endsWith('}')) {
+        // For non-TypeScript blocks, check if the content looks like JSON
+        jsonContent = blockContent;
+        logger.debug('Found code block with JSON-like content, attempting to parse');
+      } else {
+        // If the code block doesn't look like JSON, use the raw content
+        logger.debug("Code block found but doesn't appear to be JSON, falling back to raw content");
+        jsonContent = content;
+      }
+    } else {
+      // No code block, use the raw content
+      jsonContent = content;
+      logger.debug('No code blocks found, attempting to parse raw content');
+    }
+
+    // Parse the JSON content
+    const parsedData = JSON.parse(jsonContent) as AIJsonResponse | StructuredReview;
+
+    // Attempt to determine which format we have (AIJsonResponse or direct StructuredReview)
+    if ('review' in parsedData) {
+      // We have an AIJsonResponse, convert it to StructuredReview
+      const aiResponse = parsedData as AIJsonResponse;
+
+      if (!aiResponse.review) {
+        logger.warn('Response is valid JSON but missing "review" property');
+        return undefined;
+      }
+
+      // Convert the AIJsonResponse format to StructuredReview format
+      const review: StructuredReview = {
+        summary: aiResponse.review.summary
+          ? typeof aiResponse.review.summary === 'string'
+            ? aiResponse.review.summary
+            : JSON.stringify(aiResponse.review.summary)
+          : 'No summary provided',
+        issues: [],
+      };
+
+      // Process issues if available
+      if (aiResponse.review.files && Array.isArray(aiResponse.review.files)) {
+        // Collect issues from all files
+        aiResponse.review.files.forEach((file) => {
+          if (file.issues && Array.isArray(file.issues)) {
+            file.issues.forEach((issue) => {
+              if (issue.id && issue.description) {
+                review.issues.push({
+                  title: issue.id,
+                  description: issue.description,
+                  priority: mapPriority(issue.priority),
+                  type: 'other',
+                  filePath: file.filePath || '',
+                  lineNumbers:
+                    issue.location && (issue.location.startLine || issue.location.endLine)
+                      ? `${issue.location.startLine || ''}-${issue.location.endLine || ''}`
+                      : undefined,
+                  codeSnippet: issue.currentCode,
+                  suggestedFix: issue.suggestedCode,
+                  impact: issue.explanation,
+                });
+              }
+            });
+          }
+        });
+      }
+
+      // Add recommendations and positive aspects if available
+      if (aiResponse.review.recommendations) {
+        review.recommendations = aiResponse.review.recommendations;
+      }
+
+      if (aiResponse.review.positiveAspects) {
+        review.positiveAspects = aiResponse.review.positiveAspects;
+      }
+
+      return review;
+    }
+    // We assume it's already a StructuredReview format
+    const structuredData = parsedData as StructuredReview;
+
+    // Validate basic structure
+    if (typeof structuredData.summary === 'undefined' || !Array.isArray(structuredData.issues)) {
+      logger.warn(
+        'Response is valid JSON but does not have the expected StructuredReview structure',
+      );
+      return undefined;
+    }
+
+    return structuredData;
+  } catch (parseError) {
+    const errorMsg = parseError instanceof Error ? parseError.message : String(parseError);
+    logger.warn(`Response is not valid JSON: ${errorMsg}`);
+
+    // Always provide basic info regardless of log level
+    const contentPreview = content.substring(0, 50).replace(/\n/g, ' ');
+    logger.info(`JSON parse error with content starting with: "${contentPreview}..."`);
+
+    // Try additional recovery strategies for common malformed response patterns
+    try {
+      const recoveredJson = attemptJsonRecovery(content);
+      if (recoveredJson) {
+        logger.info('Successfully recovered JSON from malformed response');
+        return recoveredJson;
+      }
+    } catch (recoveryError) {
+      logger.debug('JSON recovery attempt failed:', recoveryError);
+    }
+
+    // Check for common patterns that might be causing issues
+    if (content.includes('```typescript') || content.includes('```ts')) {
+      logger.info('Content contains TypeScript code blocks that may be causing parsing issues');
+    }
+
+    if (content.includes('```json')) {
+      logger.info('Content contains JSON code blocks that could not be parsed properly');
+    }
+
+    // Check for language identifier patterns that might indicate Gemini response issues
+    if (content.match(/^(?:typescript|javascript|json|ts|js)\s*\n/i)) {
+      logger.info(
+        'Content starts with language identifier, which may indicate a Gemini response formatting issue',
+      );
+    }
+
+    // Check for quoted language identifiers
+    if (content.match(/"(?:typescript|javascript|json|ts|js)"/i)) {
+      logger.info(
+        'Content contains quoted language identifiers, which may indicate a parsing issue',
+      );
+    }
+
+    // In debug mode, log additional details to help diagnose the issue
+    if (configurationService.getApplicationConfig().logLevel.value === 'debug') {
+      const snippet =
+        content.length > 200
+          ? `${content.substring(0, 100)}...${content.substring(content.length - 100)}`
+          : content;
+      logger.debug(`Content snippet causing JSON parse error: ${snippet}`);
+
+      // Also log if we found code blocks but couldn't parse the content
+      if (jsonBlockMatch) {
+        if (jsonBlockMatch?.[1]) {
+          logger.debug(
+            `Found JSON code block but content couldn't be parsed as JSON: ${jsonBlockMatch[1].substring(0, 100)}`,
+          );
+        }
+      } else if (anyCodeBlockMatch) {
+        if (anyCodeBlockMatch?.[1]) {
+          logger.debug(
+            `Found non-JSON code block but content couldn't be parsed as JSON: ${anyCodeBlockMatch[1].substring(0, 100)}`,
+          );
+        }
+      }
+    }
+
+    // Try to create a basic structured response as a fallback
+    try {
+      // If we can't parse JSON but have a content string, create a simple summary
+      return {
+        summary: "AI generated a response that couldn't be parsed as structured data",
+        issues: [
+          {
+            title: 'Response format issue',
+            description:
+              "The response couldn't be parsed into structured format. Please see the full text for details.",
+            priority: 'medium',
+            type: 'other',
+            filePath: 'unknown', // Required field in ReviewIssue
+          },
+        ],
+      };
+    } catch (_fallbackError) {
+      logger.debug('Failed to create fallback structured response');
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Map priority string to IssuePriority type
+ * @param priority String priority value (may be undefined or in different case)
+ * @returns Normalized IssuePriority value
+ */
+function mapPriority(priority: string | undefined): 'high' | 'medium' | 'low' {
+  if (!priority) return 'medium';
+
+  const normalizedPriority = priority.toLowerCase();
+
+  if (normalizedPriority.includes('high')) return 'high';
+  if (normalizedPriority.includes('low')) return 'low';
+
+  return 'medium';
+}
+
+/**
+ * Create a standardized review result object
+ * @param content The review content
+ * @param prompt The original prompt (for cost calculation)
+ * @param modelName The full model name
+ * @param filePath The file path or identifier
+ * @param reviewType The review type
+ * @param options Optional review options to determine expected output format
+ * @returns Standardized review result
+ */
+export function createStandardReviewResult(
+  content: string,
+  prompt: string,
+  modelName: string,
+  filePath: string,
+  reviewType: ReviewType,
+  options?: { interactive?: boolean; output?: string },
+): ReviewResult {
+  // Only attempt to extract structured data if we expect JSON output
+  const expectsJsonOutput = options?.interactive === true || options?.output === 'json';
+
+  // Extract structured data only when appropriate
+  const structuredData = expectsJsonOutput ? extractStructuredData(content) : undefined;
+
+  // Calculate cost information
+  let cost: CostInfo | undefined;
+  try {
+    cost = getCostInfoFromText(prompt, content, modelName);
+  } catch (error) {
+    logger.warn(
+      `Failed to calculate cost information: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  // Return standardized review result
+  return {
+    content,
+    cost,
+    modelUsed: modelName,
+    filePath,
+    reviewType,
+    timestamp: new Date().toISOString(),
+    structuredData: structuredData as StructuredReview | undefined,
+  };
+}
+
+/**
+ * Handle API errors with standardized logging and wrapping
+ * @param error The original error
+ * @param operation Description of the operation that failed
+ * @param modelName The model being used
+ * @param context Additional context for debugging
+ * @returns Wrapped ApiError
+ */
+export function handleApiError(
+  error: unknown,
+  operation: string,
+  modelName: string,
+  context?: {
+    endpoint?: string;
+    statusCode?: number;
+    requestId?: string;
+    filePath?: string;
+    additionalInfo?: Record<string, any>;
+  },
+): ApiError {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+
+  // Build detailed error message with context
+  let formattedError = `Failed to ${operation} with ${modelName}`;
+
+  if (context) {
+    const contextParts: string[] = [];
+
+    if (context.endpoint) {
+      contextParts.push(`Endpoint: ${context.endpoint}`);
+    }
+
+    if (context.statusCode) {
+      contextParts.push(`Status: ${context.statusCode}`);
+    }
+
+    if (context.requestId) {
+      contextParts.push(`Request ID: ${context.requestId}`);
+    }
+
+    if (context.filePath) {
+      contextParts.push(`File: ${context.filePath}`);
+    }
+
+    if (context.additionalInfo) {
+      Object.entries(context.additionalInfo).forEach(([key, value]) => {
+        contextParts.push(`${key}: ${value}`);
+      });
+    }
+
+    if (contextParts.length > 0) {
+      formattedError += `\n  Context: ${contextParts.join(', ')}`;
+    }
+  }
+
+  formattedError += `\n  Error: ${errorMessage}`;
+
+  logger.error(formattedError);
+
+  // Log stack trace in debug mode
+  if (
+    error instanceof Error &&
+    error.stack &&
+      configurationService.getApplicationConfig().logLevel.value === 'debug'
+  ) {
+    logger.debug(`Stack trace: ${error.stack}`);
+  }
+
+  if (error instanceof ApiError) {
+    return error;
+  }
+
+  return new ApiError(formattedError);
+}

package/src/clients/factory/clientFactory.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Factory for creating API clients based on model selection.
+ *
+ * This module provides a factory for creating the appropriate API client
+ * based on the selected model. It handles client instantiation, model detection,
+ * and initialization.
+ *
+ * The factory includes robust model name cleaning to handle malformed input
+ * such as trailing quotes or backticks that can occur during configuration
+ * or environment variable parsing.
+ */
+
+import { getConfig } from '../../core/ConfigurationService';
+import logger from '../../utils/logger';
+import type { AbstractClient } from '../base';
+import { OpenRouterClient } from '../implementations';
+
+/**
+ * Factory for creating API clients
+ */
+export class ClientFactory {
+  /**
+   * Create an appropriate client instance based on the selected model
+   * @param overrideModel Optional model to use instead of the configured one
+   * @returns The client instance
+   */
+  public static createClient(overrideModel?: string): AbstractClient {
+    const config = getConfig();
+    const selectedModel = overrideModel || config.model || '';
+
+    // Clean the model name early to handle malformed quotes and backticks
+    const cleanedModel = selectedModel.replace(/['"``]/g, '').trim();
+
+    logger.debug(
+      `[ClientFactory] Creating client for model: ${selectedModel} (cleaned: ${cleanedModel})`,
+    );
+
+    const [adapter, modelName] = cleanedModel.includes(':')
+      ? cleanedModel.split(':', 2)
+      : ['openrouter', cleanedModel];
+
+    if (adapter.toLowerCase() !== 'openrouter') {
+      logger.warn(
+        `[ClientFactory] Non-OpenRouter adapter "${adapter}" detected for model "${selectedModel}". Forcing OpenRouter client.`,
+      );
+    }
+
+    if (!modelName) {
+      throw new Error('A valid OpenRouter model must be specified (e.g. openrouter:meta-llama/...).');
+    }
+
+    logger.info(`Creating OpenRouter client for model: ${modelName}`);
+    return new OpenRouterClient();
+  }
+}

package/src/clients/factory/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Factory for creating API clients.
+ *
+ * This module serves as the main entry point for the client factory functionality,
+ * providing a unified interface for client instantiation.
+ */
+
+export * from './clientFactory';

package/src/clients/implementations/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Client implementations for various AI providers.
+ *
+ * This module serves as the main entry point for client implementations,
+ * exporting all client classes.
+ */
+
+export * from './openRouterClient';