@in-the-loop-labs/pair-review 1.0.0

package/src/utils/instructions.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * Instructions Utility
+ *
+ * Shared utilities for handling custom instructions merging across analysis modes.
+ */
+
+/**
+ * Merge repository and request instructions with XML-like tags for AI clarity
+ * Server is the single source of truth for how instructions are merged.
+ *
+ * @param {string|null} repoInstructions - Default instructions from repository settings
+ * @param {string|null} requestInstructions - Custom instructions from the analysis request
+ * @returns {string|null} Merged instructions with XML tags, or null if both inputs are empty
+ */
+function mergeInstructions(repoInstructions, requestInstructions) {
+  if (!repoInstructions && !requestInstructions) {
+    return null;
+  }
+
+  const parts = [];
+  if (repoInstructions) {
+    parts.push(`These are default instructions for this repository:\n<repo_instructions>\n${repoInstructions}\n</repo_instructions>`);
+  }
+  if (requestInstructions) {
+    parts.push(`These are custom instructions for this analysis run. The following instructions take precedence over the repo_instructions in areas where they overlap or conflict:\n<custom_instructions>\n${requestInstructions}\n</custom_instructions>`);
+  }
+  return parts.join('\n\n');
+}
+
+module.exports = {
+  mergeInstructions
+};

package/src/utils/json-extractor.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+const logger = require('./logger');
+
+/**
+ * Extract JSON from text responses using multiple strategies
+ * This is a shared utility to ensure consistent JSON extraction across the application
+ * @param {string} response - Raw response text
+ * @param {string|number} level - Level identifier for logging (e.g., 1, 2, 3, 'orchestration', 'unknown')
+ * @returns {Object} Extraction result with success flag and data/error
+ */
+function extractJSON(response, level = 'unknown') {
+  const levelPrefix = `[Level ${level}]`;
+
+  if (!response || !response.trim()) {
+    return { success: false, error: 'Empty response' };
+  }
+
+  const strategies = [
+    // Strategy 1: Look for markdown code blocks with 'json' label
+    () => {
+      // First, try to find ```json specifically (more precise)
+      let codeBlockMatch = response.match(/```json\s*\n([\s\S]*?)\n```/);
+
+      // If not found, try generic ``` blocks
+      if (!codeBlockMatch) {
+        codeBlockMatch = response.match(/```\s*\n([\s\S]*?)\n```/);
+      }
+
+      if (codeBlockMatch && codeBlockMatch[1]) {
+        const content = codeBlockMatch[1].trim();
+        // Verify it looks like JSON before parsing
+        if (content.startsWith('{') && content.endsWith('}')) {
+          return JSON.parse(content);
+        }
+      }
+      throw new Error('No JSON code block found');
+    },
+    
+    // Strategy 2: Look for JSON between first { and last }
+    () => {
+      const firstBrace = response.indexOf('{');
+      const lastBrace = response.lastIndexOf('}');
+      if (firstBrace !== -1 && lastBrace !== -1 && lastBrace >= firstBrace) {
+        return JSON.parse(response.substring(firstBrace, lastBrace + 1));
+      }
+      throw new Error('No valid JSON braces found');
+    },
+    
+    // Strategy 3: Try to find JSON-like structure with bracket matching
+    () => {
+      const jsonMatch = response.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        // Try to find the complete JSON by matching brackets
+        const jsonStr = jsonMatch[0];
+        let braceCount = 0;
+        let endIndex = -1;
+        const maxIterations = Math.min(jsonStr.length, 100000); // Prevent infinite loops
+        
+        for (let i = 0; i < maxIterations; i++) {
+          if (jsonStr[i] === '{') braceCount++;
+          else if (jsonStr[i] === '}') {
+            braceCount--;
+            if (braceCount === 0) {
+              endIndex = i;
+              break;
+            }
+          }
+        }
+        
+        if (endIndex > -1) {
+          return JSON.parse(jsonStr.substring(0, endIndex + 1));
+        }
+      }
+      throw new Error('No balanced JSON structure found');
+    },
+    
+    // Strategy 4: Try the entire response as JSON (for simple cases)
+    () => {
+      return JSON.parse(response.trim());
+    }
+  ];
+
+  for (let i = 0; i < strategies.length; i++) {
+    try {
+      const data = strategies[i]();
+      if (data && typeof data === 'object') {
+        logger.info(`${levelPrefix} JSON extraction successful using strategy ${i + 1}`);
+        return { success: true, data };
+      }
+    } catch (error) {
+      // Continue to next strategy
+      if (i === strategies.length - 1) {
+        // Last strategy failed, log the error
+        logger.warn(`${levelPrefix} All JSON extraction strategies failed`);
+        logger.warn(`${levelPrefix} Response preview: ${response.substring(0, 200)}...`);
+      }
+    }
+  }
+
+  return { 
+    success: false, 
+    error: 'Failed to extract JSON from response',
+    response: response.substring(0, 500) // Include preview for debugging
+  };
+}
+
+module.exports = { extractJSON };

package/src/utils/line-validation.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const logger = require('./logger');
+
+/**
+ * Check if a file is binary using the `file` command
+ * @param {string} fullPath - Full path to the file
+ * @returns {boolean} True if file is binary
+ */
+function isBinaryFile(fullPath) {
+  try {
+    // First check if file is empty - empty files are reported as "binary" by the file command
+    // but we want to treat them as text files (with 0 lines)
+    const stats = fs.statSync(fullPath);
+    if (stats.size === 0) {
+      return false;
+    }
+
+    // Use 'file --mime-encoding' to detect encoding
+    // Binary files will show "binary" in the output
+    const result = execSync(`file --mime-encoding "${fullPath}"`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+    });
+    return result.includes('binary');
+  } catch {
+    // If command fails, fall back to assuming not binary
+    return false;
+  }
+}
+
+/**
+ * Build a map of file paths to their line counts
+ * @param {string} worktreePath - Path to the git worktree
+ * @param {Array<string>} validFiles - List of changed file paths
+ * @returns {Promise<Map<string, number>>} Map of filePath -> lineCount
+ */
+async function buildFileLineCountMap(worktreePath, validFiles) {
+  if (!validFiles || !Array.isArray(validFiles) || validFiles.length === 0) {
+    return new Map();
+  }
+
+  // Read all files in parallel
+  const results = await Promise.all(validFiles.map(async (filePath) => {
+    if (!filePath || typeof filePath !== 'string') {
+      return null;
+    }
+
+    const fullPath = path.join(worktreePath, filePath);
+
+    try {
+      // Skip binary files - can't meaningfully count their "lines"
+      if (isBinaryFile(fullPath)) {
+        return { filePath, lineCount: -1 };
+      }
+
+      const content = await fs.promises.readFile(fullPath, 'utf-8');
+      // Count lines by splitting on newlines
+      // Empty file has 0 lines, file with "a" has 1 line, file with "a\n" has 1 line,
+      // file with "a\nb" has 2 lines
+      let lineCount;
+      if (content.length === 0) {
+        // Empty file has 0 lines
+        lineCount = 0;
+      } else {
+        const lines = content.split('\n');
+        // If file ends with newline, last element is empty string - don't count it as a line
+        lineCount = content.endsWith('\n') && lines.length > 0
+          ? lines.length - 1
+          : lines.length;
+      }
+
+      return { filePath, lineCount };
+    } catch (error) {
+      // File doesn't exist or can't be read - mark as -1
+      return { filePath, lineCount: -1 };
+    }
+  }));
+
+  // Build the map from results
+  const fileLineCountMap = new Map();
+  for (const result of results) {
+    if (result !== null) {
+      fileLineCountMap.set(result.filePath, result.lineCount);
+    }
+  }
+
+  return fileLineCountMap;
+}
+
+/**
+ * Validate suggestion line numbers against file lengths
+ * @param {Array} suggestions - Array of suggestion objects with file, line_start, line_end
+ * @param {Map<string, number>} fileLineCountMap - Map of file paths to line counts
+ * @param {Object} options - { convertToFileLevel: boolean }
+ * @returns {Object} { valid: [], converted: [], dropped: [] }
+ */
+function validateSuggestionLineNumbers(suggestions, fileLineCountMap, options = {}) {
+  const { convertToFileLevel = false } = options;
+  const result = {
+    valid: [],
+    converted: [],
+    dropped: []
+  };
+
+  if (!suggestions || !Array.isArray(suggestions)) {
+    return result;
+  }
+
+  for (const suggestion of suggestions) {
+    // File-level suggestions (line_start === null) always pass through
+    if (suggestion.line_start === null || suggestion.line_start === undefined) {
+      result.valid.push(suggestion);
+      continue;
+    }
+
+    const filePath = suggestion.file;
+    const lineCount = fileLineCountMap.get(filePath);
+
+    // If file not in map, pass through (might be deleted file or file we couldn't process)
+    if (lineCount === undefined) {
+      result.valid.push(suggestion);
+      continue;
+    }
+
+    // Binary files (lineCount === -1) - pass through since we can't validate line numbers
+    if (lineCount === -1) {
+      result.valid.push(suggestion);
+      continue;
+    }
+
+    // Validate line numbers
+    const lineStart = suggestion.line_start;
+    const lineEnd = suggestion.line_end !== undefined && suggestion.line_end !== null
+      ? suggestion.line_end
+      : lineStart;
+
+    let isValid = true;
+    let reason = '';
+
+    // Check line_start is valid
+    if (lineStart <= 0) {
+      isValid = false;
+      reason = `line_start ${lineStart} is <= 0`;
+    } else if (lineStart > lineCount) {
+      isValid = false;
+      reason = `line_start ${lineStart} exceeds file length ${lineCount}`;
+    }
+
+    // Check line_end is valid
+    if (isValid && lineEnd < lineStart) {
+      isValid = false;
+      reason = `line_end ${lineEnd} is less than line_start ${lineStart}`;
+    } else if (isValid && lineEnd > lineCount) {
+      isValid = false;
+      reason = `line_end ${lineEnd} exceeds file length ${lineCount}`;
+    }
+
+    if (isValid) {
+      result.valid.push(suggestion);
+    } else if (convertToFileLevel) {
+      // Convert to file-level suggestion
+      const convertedSuggestion = {
+        ...suggestion,
+        line_start: null,
+        line_end: null,
+        is_file_level: true
+      };
+      result.converted.push(convertedSuggestion);
+      logger.warn(`[Line Validation] Converting suggestion to file-level: "${suggestion.title}" (${reason})`);
+    } else {
+      // Drop the suggestion
+      result.dropped.push(suggestion);
+      logger.warn(`[Line Validation] Dropping suggestion: "${suggestion.title}" (${reason})`);
+    }
+  }
+
+  return result;
+}
+
+module.exports = { buildFileLineCountMap, validateSuggestionLineNumbers };

package/src/utils/logger.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * Logger utility for AI analysis
+ * Provides formatted console output that stands out
+ */
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  
+  // Foreground colors
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  
+  // Background colors
+  bgBlue: '\x1b[44m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgRed: '\x1b[41m'
+};
+
+class AILogger {
+  constructor() {
+    this.enabled = true;
+    this.debugEnabled = false;
+  }
+
+  /**
+   * Enable or disable debug logging
+   * @param {boolean} enabled - Whether debug logging should be enabled
+   */
+  setDebugEnabled(enabled) {
+    this.debugEnabled = enabled;
+  }
+
+  /**
+   * Check if debug logging is enabled
+   * @returns {boolean} Whether debug logging is enabled
+   */
+  isDebugEnabled() {
+    return this.debugEnabled;
+  }
+
+  /**
+   * Log debug message (only shown when debug is enabled)
+   */
+  debug(message) {
+    if (!this.enabled || !this.debugEnabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    process.stdout.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.dim}[AI DBG]${COLORS.reset} ` +
+      `${COLORS.dim}${message}${COLORS.reset}\n`
+    );
+  }
+
+  /**
+   * Log AI analysis info
+   */
+  info(message) {
+    if (!this.enabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    process.stdout.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.bright}${COLORS.blue}[AI]${COLORS.reset} ` +
+      `${message}\n`
+    );
+  }
+
+  /**
+   * Log AI analysis success
+   */
+  success(message) {
+    if (!this.enabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    process.stdout.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.bright}${COLORS.green}[AI ✓]${COLORS.reset} ` +
+      `${COLORS.green}${message}${COLORS.reset}\n`
+    );
+  }
+
+  /**
+   * Log AI analysis error
+   */
+  error(message) {
+    if (!this.enabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    process.stderr.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.bright}${COLORS.red}[AI ✗]${COLORS.reset} ` +
+      `${COLORS.red}${message}${COLORS.reset}\n`
+    );
+  }
+
+  /**
+   * Log AI analysis warning
+   */
+  warn(message) {
+    if (!this.enabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    process.stdout.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.bright}${COLORS.yellow}[AI ⚠]${COLORS.reset} ` +
+      `${COLORS.yellow}${message}${COLORS.reset}\n`
+    );
+  }
+
+  /**
+   * Log with custom prefix
+   */
+  log(prefix, message, color = 'blue') {
+    if (!this.enabled) return;
+    const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+    const prefixColor = COLORS[color] || COLORS.blue;
+    process.stdout.write(
+      `${COLORS.cyan}[${timestamp}]${COLORS.reset} ` +
+      `${COLORS.bright}${prefixColor}[${prefix}]${COLORS.reset} ` +
+      `${message}\n`
+    );
+  }
+
+  /**
+   * Start a progress section
+   */
+  section(title) {
+    if (!this.enabled) return;
+    process.stdout.write(
+      `\n${COLORS.bright}${COLORS.cyan}${'─'.repeat(60)}${COLORS.reset}\n` +
+      `${COLORS.bright}${COLORS.cyan}▶ ${title}${COLORS.reset}\n` +
+      `${COLORS.cyan}${'─'.repeat(60)}${COLORS.reset}\n`
+    );
+  }
+}
+
+module.exports = new AILogger();

package/src/utils/paths.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/**
+ * Path normalization utilities for consistent path comparison
+ */
+
+/**
+ * Normalize a file path for consistent comparison
+ *
+ * This function:
+ * - Removes leading/trailing whitespace
+ * - Removes leading './' prefix (handles repeated patterns like '././')
+ * - Removes leading '/' prefix (handles repeated patterns like '//')
+ * - Handles interleaved patterns like '/./src' by iterating
+ * - Normalizes multiple consecutive slashes to single slash
+ * - Does NOT modify case (paths are case-sensitive on most systems)
+ *
+ * @param {string} filePath - The file path to normalize
+ * @returns {string} Normalized path
+ *
+ * @example
+ * normalizePath('./src/foo.js')    // => 'src/foo.js'
+ * normalizePath('/src/foo.js')     // => 'src/foo.js'
+ * normalizePath('src//foo.js')     // => 'src/foo.js'
+ * normalizePath('  src/foo.js  ')  // => 'src/foo.js'
+ * normalizePath('././src/foo.js')  // => 'src/foo.js'
+ * normalizePath('//./src/foo.js')  // => 'src/foo.js'
+ * normalizePath(null)              // => ''
+ * normalizePath(undefined)         // => ''
+ */
+function normalizePath(filePath) {
+  // Handle null, undefined, and non-string inputs
+  if (filePath == null || typeof filePath !== 'string') {
+    return '';
+  }
+
+  let result = filePath;
+
+  // Trim whitespace
+  result = result.trim();
+
+  // Return early if empty after trimming
+  if (result === '') {
+    return '';
+  }
+
+  // Collapse multiple consecutive slashes into single slashes
+  // Do this before removing leading slashes to handle cases like '//src/foo.js'
+  result = result.replace(/\/+/g, '/');
+
+  // Remove leading './' and '/' iteratively
+  // This handles cases like '/./src/foo.js' which need both removed
+  let prevLength;
+  do {
+    prevLength = result.length;
+
+    // Remove leading './'
+    while (result.startsWith('./')) {
+      result = result.slice(2);
+    }
+
+    // Remove leading '/'
+    while (result.startsWith('/')) {
+      result = result.slice(1);
+    }
+  } while (result.length !== prevLength);
+
+  return result;
+}
+
+/**
+ * Check if two paths are equivalent after normalization
+ *
+ * @param {string} path1 - First path to compare
+ * @param {string} path2 - Second path to compare
+ * @returns {boolean} True if paths are equivalent
+ */
+function pathsEqual(path1, path2) {
+  return normalizePath(path1) === normalizePath(path2);
+}
+
+/**
+ * Check if a path exists in a list of paths (using normalized comparison)
+ *
+ * @deprecated Use pathExistsInSet() with a pre-normalized Set for O(1) lookups
+ * @param {string} needle - Path to search for
+ * @param {Array<string>} haystack - Array of paths to search in
+ * @returns {boolean} True if path exists in the array
+ */
+function pathExistsInList(needle, haystack) {
+  if (!needle || !Array.isArray(haystack)) {
+    return false;
+  }
+
+  const normalizedNeedle = normalizePath(needle);
+  return haystack.some(path => normalizePath(path) === normalizedNeedle);
+}
+
+/**
+ * Check if a path exists in a Set of pre-normalized paths (O(1) lookup)
+ *
+ * This is the preferred method for checking path existence when performing
+ * multiple lookups against the same set of valid paths.
+ *
+ * @param {string} needle - Path to search for (will be normalized)
+ * @param {Set<string>} normalizedPathsSet - Set of pre-normalized paths
+ * @returns {boolean} True if path exists in the Set
+ *
+ * @example
+ * // Pre-normalize paths once
+ * const validPathsSet = new Set(validPaths.map(p => normalizePath(p)));
+ * // Then use O(1) lookups
+ * pathExistsInSet('./src/foo.js', validPathsSet) // => true
+ */
+function pathExistsInSet(needle, normalizedPathsSet) {
+  if (!needle || !(normalizedPathsSet instanceof Set)) {
+    return false;
+  }
+
+  const normalizedNeedle = normalizePath(needle);
+  return normalizedPathsSet.has(normalizedNeedle);
+}
+
+/**
+ * Normalize a GitHub repository identifier for case-insensitive matching.
+ *
+ * GitHub repository names and owner names are case-insensitive. URLs like
+ * github.com/Owner/Repo and github.com/owner/repo refer to the same repository.
+ * This function normalizes repository identifiers to lowercase to ensure
+ * consistent database lookups regardless of URL casing.
+ *
+ * @param {string} owner - Repository owner (GitHub username or org)
+ * @param {string} repo - Repository name
+ * @returns {string} Normalized repository identifier in "owner/repo" format (lowercase)
+ *
+ * @example
+ * normalizeRepository('Owner', 'Repo')     // => 'owner/repo'
+ * normalizeRepository('OWNER', 'REPO')     // => 'owner/repo'
+ * normalizeRepository('owner', 'repo')     // => 'owner/repo'
+ */
+function normalizeRepository(owner, repo) {
+  if (!owner || typeof owner !== 'string' || !repo || typeof repo !== 'string') {
+    throw new Error('owner and repo must be non-empty strings');
+  }
+
+  const trimmedOwner = owner.trim();
+  const trimmedRepo = repo.trim();
+
+  if (!trimmedOwner || !trimmedRepo) {
+    throw new Error('owner and repo must be non-empty strings');
+  }
+
+  return `${trimmedOwner.toLowerCase()}/${trimmedRepo.toLowerCase()}`;
+}
+
+module.exports = {
+  normalizePath,
+  pathsEqual,
+  pathExistsInList,
+  pathExistsInSet,
+  normalizeRepository
+};