@smartergpt/lexrunner 1.0.0

package/src/ai/conflictStrategyCache.ts

@@ -0,0 +1,164 @@
+/**
+ * Caching layer for AI conflict resolution strategies
+ *
+ * Uses SHA-256 hashing of input parameters to cache resolution strategies.
+ * Provides cache hit/miss tracking and TTL support.
+ */
+
+import { createHash } from "crypto";
+import type {
+  ConflictResolutionInput,
+  ConflictResolutionOutput,
+  CachedResolution,
+} from "./conflictStrategySchema.js";
+
+/**
+ * Generate cache key from conflict resolution input
+ *
+ * Creates a deterministic SHA-256 hash from:
+ * - Sorted file paths
+ * - Sorted hunk hashes
+ * - Sorted symbols (by name, type, path)
+ * - Sorted hints (by type, message)
+ *
+ * @param input - Conflict resolution input
+ * @returns SHA-256 hash (64 hex characters)
+ */
+export function generateCacheKey(input: ConflictResolutionInput): string {
+  // Create deterministic canonical representation
+  const canonical = JSON.stringify({
+    paths: [...input.paths].sort(),
+    hunkHashes: [...input.hunkHashes].sort(),
+    symbols: [...input.symbols].sort((a, b) => {
+      if (a.name !== b.name) return a.name.localeCompare(b.name);
+      if (a.type !== b.type) return a.type.localeCompare(b.type);
+      return a.path.localeCompare(b.path);
+    }),
+    hints: [...input.hints].sort((a, b) => {
+      if (a.type !== b.type) return a.type.localeCompare(b.type);
+      return a.message.localeCompare(b.message);
+    }),
+  });
+
+  // Generate SHA-256 hash
+  const hash = createHash("sha256");
+  hash.update(canonical);
+  return hash.digest("hex");
+}
+
+/**
+ * In-memory cache for conflict resolutions
+ *
+ * Production implementation should use persistent storage
+ * (e.g., Redis, filesystem, database)
+ */
+export class ConflictResolutionCache {
+  private cache: Map<string, CachedResolution> = new Map();
+  private hits = 0;
+  private misses = 0;
+
+  /**
+   * Get cached resolution if available and not expired
+   *
+   * @param cacheKey - SHA-256 cache key
+   * @returns Cached resolution or null if miss/expired
+   */
+  get(cacheKey: string): ConflictResolutionOutput | null {
+    const entry = this.cache.get(cacheKey);
+
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    // Check TTL if specified
+    if (entry.ttl) {
+      const entryTime = new Date(entry.timestamp).getTime();
+      const now = Date.now();
+      const age = (now - entryTime) / 1000; // seconds
+
+      if (age > entry.ttl) {
+        // Expired, remove from cache
+        this.cache.delete(cacheKey);
+        this.misses++;
+        return null;
+      }
+    }
+
+    this.hits++;
+    return entry.resolution;
+  }
+
+  /**
+   * Store resolution in cache
+   *
+   * @param cacheKey - SHA-256 cache key
+   * @param resolution - Resolution output to cache
+   * @param ttl - Optional TTL in seconds
+   */
+  set(cacheKey: string, resolution: ConflictResolutionOutput, ttl?: number): void {
+    const entry: CachedResolution = {
+      cacheKey,
+      resolution,
+      timestamp: new Date().toISOString(),
+      ttl,
+    };
+
+    this.cache.set(cacheKey, entry);
+  }
+
+  /**
+   * Check if cache contains valid entry
+   *
+   * @param cacheKey - SHA-256 cache key
+   * @returns true if valid entry exists
+   */
+  has(cacheKey: string): boolean {
+    return this.get(cacheKey) !== null;
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): { hits: number; misses: number; size: number; hitRate: number } {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0,
+    };
+  }
+
+  /**
+   * Remove expired entries
+   */
+  cleanup(): void {
+    const now = Date.now();
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.ttl) {
+        const entryTime = new Date(entry.timestamp).getTime();
+        const age = (now - entryTime) / 1000;
+
+        if (age > entry.ttl) {
+          this.cache.delete(key);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Global singleton cache instance
+ */
+export const globalConflictCache = new ConflictResolutionCache();

package/src/ai/conflictStrategyPrompt.ts

@@ -0,0 +1,128 @@
+/**
+ * AI prompt template for conflict resolution strategy
+ *
+ * Provides the prompt structure for querying an AI model to resolve conflicts.
+ * Uses JSON I/O for structured input/output.
+ */
+
+import type { ConflictResolutionInput } from "./conflictStrategySchema.js";
+
+/**
+ * System prompt for conflict resolution AI
+ *
+ * Sets the context and rules for the AI's behavior
+ */
+export const SYSTEM_PROMPT = `You are a conflict resolution expert for git merge operations.
+
+Your task is to analyze merge conflicts and propose resolution strategies.
+
+Input format (JSON):
+{
+  "paths": ["file1.ts", "file2.ts"],
+  "hunkHashes": ["abc123...", "def456..."],
+  "symbols": [{"name": "MyClass", "type": "class", "path": "file1.ts"}],
+  "hints": [{"type": "import-order", "message": "...", "confidence": 0.9}]
+}
+
+Output format (JSON):
+{
+  "strategy": "auto-resolve" | "manual-review" | "abort",
+  "ops": [
+    {
+      "type": "accept-ours" | "accept-theirs" | "accept-base" | "merge-both" | "manual-review",
+      "path": "file1.ts",
+      "hunkHash": "abc123...",
+      "rationale": "Explanation of why this operation is safe"
+    }
+  ],
+  "risk": 0.25,  // 0-1 scale
+  "explanation": "Overall strategy explanation"
+}
+
+Rules:
+1. Always output valid JSON
+2. Calculate risk conservatively (prefer higher risk scores when uncertain)
+3. Only suggest "auto-resolve" for trivial conflicts (imports, whitespace, formatting)
+4. Suggest "manual-review" for semantic conflicts
+5. Suggest "abort" for high-risk structural conflicts
+6. Provide clear rationale for each operation
+7. Risk threshold: if risk > 0.35, recommend manual review`;
+
+/**
+ * Generate user prompt for specific conflict
+ *
+ * @param input - Conflict resolution input
+ * @returns Formatted prompt string
+ */
+export function generateConflictPrompt(input: ConflictResolutionInput): string {
+  const inputJson = JSON.stringify(input, null, 2);
+
+  return `Analyze the following merge conflict and provide a resolution strategy:
+
+${inputJson}
+
+Provide your response as JSON following the output format specified in the system prompt.`;
+}
+
+/**
+ * Parse AI response to extract JSON
+ *
+ * Handles cases where AI includes markdown formatting or extra text
+ *
+ * @param response - Raw AI response
+ * @returns Parsed JSON object
+ */
+export function parseAIResponse(response: string): unknown {
+  // Try to extract JSON from markdown code blocks
+  const jsonBlockMatch = response.match(/```json\n([\s\S]*?)\n```/);
+  if (jsonBlockMatch) {
+    return JSON.parse(jsonBlockMatch[1]);
+  }
+
+  // Try to extract JSON from regular code blocks
+  const codeBlockMatch = response.match(/```\n([\s\S]*?)\n```/);
+  if (codeBlockMatch) {
+    return JSON.parse(codeBlockMatch[1]);
+  }
+
+  // Try to find JSON object in response
+  const jsonMatch = response.match(/\{[\s\S]*\}/);
+  if (jsonMatch) {
+    return JSON.parse(jsonMatch[0]);
+  }
+
+  // If no JSON found, try parsing the whole response
+  return JSON.parse(response);
+}
+
+/**
+ * Build complete prompt for AI model
+ *
+ * @param input - Conflict resolution input
+ * @returns Object with system and user prompts
+ */
+export function buildPrompt(input: ConflictResolutionInput): {
+  system: string;
+  user: string;
+} {
+  return {
+    system: SYSTEM_PROMPT,
+    user: generateConflictPrompt(input),
+  };
+}
+
+/**
+ * Estimate token count for prompt (rough approximation)
+ *
+ * Uses ~4 characters per token heuristic
+ *
+ * @param input - Conflict resolution input
+ * @returns Estimated token count
+ */
+export function estimateTokenCount(input: ConflictResolutionInput): number {
+  const systemTokens = Math.ceil(SYSTEM_PROMPT.length / 4);
+  const userPrompt = generateConflictPrompt(input);
+  const userTokens = Math.ceil(userPrompt.length / 4);
+
+  return systemTokens + userTokens;
+}

package/src/ai/conflictStrategySchema.ts

@@ -0,0 +1,165 @@
+/**
+ * JSON schemas for AI conflict resolution strategy
+ *
+ * Defines input/output contracts for AI-driven conflict resolution
+ * with caching, risk scoring, and abstention logic.
+ */
+
+import { z } from "zod";
+
+/**
+ * Input schema for AI conflict resolution
+ *
+ * Contains all context needed for the AI to determine a resolution strategy:
+ * - File paths involved in the conflict
+ * - Hunk hashes (SHA-256 of conflict hunks)
+ * - Symbol information (functions, classes modified)
+ * - Hints from static analysis
+ */
+export const ConflictResolutionInputSchema = z.object({
+  /**
+   * Paths of files with conflicts
+   */
+  paths: z.array(z.string()).min(1, "At least one file path required"),
+
+  /**
+   * SHA-256 hashes of conflict hunks
+   * Used for caching and change detection
+   */
+  hunkHashes: z.array(z.string().regex(/^[a-f0-9]{64}$/, "Must be valid SHA-256 hash")),
+
+  /**
+   * Symbols affected by the conflict (functions, classes, variables)
+   */
+  symbols: z
+    .array(
+      z.object({
+        name: z.string(),
+        type: z.enum(["function", "class", "variable", "import", "export", "other"]),
+        path: z.string(),
+      })
+    )
+    .default([]),
+
+  /**
+   * Hints from static analysis or heuristics
+   */
+  hints: z
+    .array(
+      z.object({
+        type: z.enum(["import-order", "whitespace", "formatting", "semantic", "structural"]),
+        message: z.string(),
+        confidence: z.number().min(0).max(1),
+      })
+    )
+    .default([]),
+});
+
+export type ConflictResolutionInput = z.infer<typeof ConflictResolutionInputSchema>;
+
+/**
+ * Resolution operation schema
+ *
+ * Defines atomic operations to resolve conflicts
+ */
+export const ResolutionOperationSchema = z.object({
+  /**
+   * Type of resolution operation
+   */
+  type: z.enum([
+    "accept-ours", // Accept current branch version
+    "accept-theirs", // Accept incoming branch version
+    "accept-base", // Accept common ancestor version
+    "merge-both", // Merge both changes
+    "manual-review", // Requires manual review
+  ]),
+
+  /**
+   * File path for the operation
+   */
+  path: z.string(),
+
+  /**
+   * Hunk hash this operation applies to
+   */
+  hunkHash: z.string().regex(/^[a-f0-9]{64}$/),
+
+  /**
+   * Optional rationale for the operation
+   */
+  rationale: z.string().optional(),
+});
+
+export type ResolutionOperation = z.infer<typeof ResolutionOperationSchema>;
+
+/**
+ * Output schema for AI conflict resolution
+ *
+ * Contains the resolution strategy and confidence/risk assessment
+ */
+export const ConflictResolutionOutputSchema = z.object({
+  /**
+   * Overall resolution strategy
+   */
+  strategy: z.enum([
+    "auto-resolve", // Can be automatically resolved
+    "manual-review", // Requires human review
+    "abort", // Too risky, abort merge
+  ]),
+
+  /**
+   * Array of resolution operations
+   */
+  ops: z.array(ResolutionOperationSchema),
+
+  /**
+   * Risk score (0-1)
+   * Higher values indicate greater risk of incorrect resolution
+   * Threshold for abstention: 0.35
+   */
+  risk: z.number().min(0).max(1),
+
+  /**
+   * Optional explanation of the strategy
+   */
+  explanation: z.string().optional(),
+
+  /**
+   * Whether the AI abstained from providing a strategy
+   */
+  abstained: z.boolean().default(false),
+
+  /**
+   * Fallback method used if abstained
+   */
+  fallbackMethod: z.enum(["heuristic", "manual", "none"]).optional(),
+});
+
+export type ConflictResolutionOutput = z.infer<typeof ConflictResolutionOutputSchema>;
+
+/**
+ * Cached resolution entry schema
+ */
+export const CachedResolutionSchema = z.object({
+  /**
+   * Cache key (SHA-256 of input)
+   */
+  cacheKey: z.string().regex(/^[a-f0-9]{64}$/),
+
+  /**
+   * Cached resolution output
+   */
+  resolution: ConflictResolutionOutputSchema,
+
+  /**
+   * Timestamp of cache entry
+   */
+  timestamp: z.string().datetime(),
+
+  /**
+   * TTL in seconds (optional)
+   */
+  ttl: z.number().positive().optional(),
+});
+
+export type CachedResolution = z.infer<typeof CachedResolutionSchema>;

package/src/ai/heuristicFallback.ts

@@ -0,0 +1,162 @@
+/**
+ * Heuristic fallback strategies for conflict resolution
+ *
+ * Used when AI abstains due to high risk or unavailability.
+ * Provides rule-based resolution for common conflict patterns.
+ */
+
+import type {
+  ConflictResolutionInput,
+  ConflictResolutionOutput,
+  ResolutionOperation,
+} from "./conflictStrategySchema.js";
+
+/**
+ * Apply heuristic-based conflict resolution
+ *
+ * Uses pattern matching to handle common conflict types:
+ * - Import order conflicts → merge both
+ * - Whitespace conflicts → accept-theirs
+ * - Formatting conflicts → accept-theirs
+ * - Everything else → manual-review
+ *
+ * @param input - Conflict resolution input
+ * @returns Heuristic resolution strategy
+ */
+export function applyHeuristicFallback(input: ConflictResolutionInput): ConflictResolutionOutput {
+  const ops: ResolutionOperation[] = [];
+  let maxRisk = 0.0;
+
+  // Analyze hints to determine conflict types
+  const importHints = input.hints.filter((h) => h.type === "import-order");
+  const whitespaceHints = input.hints.filter((h) => h.type === "whitespace");
+  const formattingHints = input.hints.filter((h) => h.type === "formatting");
+  const semanticHints = input.hints.filter((h) => h.type === "semantic");
+  const structuralHints = input.hints.filter((h) => h.type === "structural");
+
+  // Strategy 1: Import order conflicts - merge both
+  if (importHints.length > 0 && semanticHints.length === 0 && structuralHints.length === 0) {
+    for (let i = 0; i < Math.min(input.hunkHashes.length, input.paths.length); i++) {
+      ops.push({
+        type: "merge-both",
+        path: input.paths[i] || input.paths[0],
+        hunkHash: input.hunkHashes[i],
+        rationale: "Import order conflict - safe to merge both imports",
+      });
+    }
+    maxRisk = 0.15;
+  }
+  // Strategy 2: Whitespace/formatting only - accept theirs
+  else if (
+    (whitespaceHints.length > 0 || formattingHints.length > 0) &&
+    semanticHints.length === 0 &&
+    structuralHints.length === 0
+  ) {
+    for (let i = 0; i < Math.min(input.hunkHashes.length, input.paths.length); i++) {
+      ops.push({
+        type: "accept-theirs",
+        path: input.paths[i] || input.paths[0],
+        hunkHash: input.hunkHashes[i],
+        rationale: "Whitespace/formatting conflict - accepting incoming changes",
+      });
+    }
+    maxRisk = 0.1;
+  }
+  // Strategy 3: Semantic or structural - manual review
+  else {
+    for (let i = 0; i < Math.min(input.hunkHashes.length, input.paths.length); i++) {
+      ops.push({
+        type: "manual-review",
+        path: input.paths[i] || input.paths[0],
+        hunkHash: input.hunkHashes[i],
+        rationale: "Complex conflict requires manual review",
+      });
+    }
+    maxRisk = 0.5;
+  }
+
+  // Determine overall strategy
+  const hasManualReview = ops.some((op) => op.type === "manual-review");
+  const strategy = hasManualReview ? "manual-review" : "auto-resolve";
+
+  return {
+    strategy,
+    ops,
+    risk: maxRisk,
+    explanation: `Heuristic fallback: ${getHeuristicExplanation(importHints, whitespaceHints, formattingHints, semanticHints, structuralHints)}`,
+    abstained: false,
+    fallbackMethod: "heuristic",
+  };
+}
+
+/**
+ * Generate explanation for heuristic strategy
+ */
+function getHeuristicExplanation(
+  importHints: any[],
+  whitespaceHints: any[],
+  formattingHints: any[],
+  semanticHints: any[],
+  structuralHints: any[]
+): string {
+  if (importHints.length > 0 && semanticHints.length === 0 && structuralHints.length === 0) {
+    return "Import order conflicts detected - merging both import sets";
+  }
+
+  if (
+    (whitespaceHints.length > 0 || formattingHints.length > 0) &&
+    semanticHints.length === 0 &&
+    structuralHints.length === 0
+  ) {
+    return "Whitespace/formatting conflicts detected - accepting incoming changes";
+  }
+
+  return "Complex conflict patterns detected - requiring manual review";
+}
+
+/**
+ * Check if conflict is trivial and safe for auto-resolution
+ *
+ * Trivial conflicts:
+ * - Import order only
+ * - Whitespace only
+ * - Formatting only
+ * - No semantic or structural changes
+ *
+ * @param input - Conflict resolution input
+ * @returns true if trivial
+ */
+export function isTrivialConflict(input: ConflictResolutionInput): boolean {
+  const semanticHints = input.hints.filter((h) => h.type === "semantic");
+  const structuralHints = input.hints.filter((h) => h.type === "structural");
+  const structuralSymbols = input.symbols.filter(
+    (s) => s.type === "function" || s.type === "class"
+  );
+
+  // No semantic/structural hints and no structural symbols
+  return (
+    semanticHints.length === 0 && structuralHints.length === 0 && structuralSymbols.length === 0
+  );
+}
+
+/**
+ * Get confidence score for heuristic resolution
+ *
+ * @param input - Conflict resolution input
+ * @returns Confidence score (0-1)
+ */
+export function getHeuristicConfidence(input: ConflictResolutionInput): number {
+  if (isTrivialConflict(input)) {
+    // High confidence for trivial conflicts
+    return 0.85;
+  }
+
+  // Lower confidence for complex conflicts
+  const semanticHints = input.hints.filter((h) => h.type === "semantic");
+  const structuralSymbols = input.symbols.filter(
+    (s) => s.type === "function" || s.type === "class"
+  );
+
+  const complexity = semanticHints.length + structuralSymbols.length;
+  return Math.max(0.2, 1.0 - complexity * 0.1);
+}

package/src/ai/index.ts

@@ -0,0 +1,64 @@
+/**
+ * AI Module - Conflict Resolution Strategy
+ *
+ * Provides AI-driven conflict resolution with:
+ * - JSON I/O contracts
+ * - SHA-256 caching
+ * - Risk-based abstention (threshold: 0.35)
+ * - Heuristic fallback
+ *
+ * @packageDocumentation
+ */
+
+// Main API
+export {
+  resolveConflict,
+  resolveConflictsBatch,
+  getCacheStats,
+  clearCache,
+  type ResolveConflictOptions,
+} from "./conflictStrategy.js";
+
+// Schemas
+export {
+  ConflictResolutionInputSchema,
+  ConflictResolutionOutputSchema,
+  ResolutionOperationSchema,
+  CachedResolutionSchema,
+  type ConflictResolutionInput,
+  type ConflictResolutionOutput,
+  type ResolutionOperation,
+  type CachedResolution,
+} from "./conflictStrategySchema.js";
+
+// Caching
+export {
+  ConflictResolutionCache,
+  generateCacheKey,
+  globalConflictCache,
+} from "./conflictStrategyCache.js";
+
+// Risk Scoring
+export {
+  calculateRiskScore,
+  shouldAbstain,
+  getRiskLevel,
+  assessRisk,
+  RISK_THRESHOLD,
+} from "./riskScoring.js";
+
+// Prompt Generation
+export {
+  buildPrompt,
+  parseAIResponse,
+  generateConflictPrompt,
+  estimateTokenCount,
+  SYSTEM_PROMPT,
+} from "./conflictStrategyPrompt.js";
+
+// Heuristic Fallback
+export {
+  applyHeuristicFallback,
+  isTrivialConflict,
+  getHeuristicConfidence,
+} from "./heuristicFallback.js";