@smartergpt/lexrunner 1.0.0

package/src/orchestration/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Types for conflict prediction and orchestration
+ */
+
+/**
+ * Conflict graph representation
+ */
+export interface ConflictGraph {
+  nodes: string[];
+  edges: Array<{
+    from: string;
+    to: string;
+    sharedFiles: string[];
+  }>;
+}
+
+/**
+ * Maximal Independent Set batch
+ */
+export interface MISBatch {
+  id: string;
+  prs: string[];
+  reason: string;
+}
+
+/**
+ * Conflict details from merge-tree simulation
+ */
+export interface ConflictDetail {
+  file: string;
+  lines: string;
+  type: string;
+}
+
+/**
+ * Merge simulation result
+ */
+export interface MergeSimulationResult {
+  status: "clean" | "conflict";
+  conflicts: ConflictDetail[];
+}
+
+/**
+ * Complete conflict report
+ */
+export interface ConflictReport {
+  analyzedAt: string;
+  baseBranch: string;
+  conflictGraph: ConflictGraph;
+  misBatches: MISBatch[];
+  mergeTreeSimulation: Record<string, MergeSimulationResult>;
+  recommendations: {
+    safeBatch: string[];
+    sequential: string[];
+  };
+}
+
+/**
+ * PR with file list for conflict analysis
+ */
+export interface PRWithFiles {
+  number: number;
+  files: string[];
+  head?: string;
+}
+
+/**
+ * Symbol information extracted from code
+ */
+export interface Symbol {
+  name: string;
+  type: "function" | "class" | "interface" | "type" | "const" | "let" | "var" | "import" | "export";
+  line: number;
+  signature?: string;
+}
+
+/**
+ * Clustered conflict group by file and symbol
+ */
+export interface ConflictCluster {
+  file: string;
+  symbols: string[];
+  conflictType: "both-modified" | "rename" | "whitespace" | "mixed";
+  details: {
+    lineRange: string;
+    affectedSymbols: Symbol[];
+  };
+}
+
+/**
+ * Complete conflict clustering report
+ */
+export interface ClusteredConflictReport {
+  analyzedAt: string;
+  baseBranch: string;
+  clusters: ConflictCluster[];
+  summary: {
+    totalClusters: number;
+    fileCount: number;
+    symbolCount: number;
+    conflictTypes: Record<string, number>;
+  };
+}

package/src/performance.README.md

@@ -0,0 +1,99 @@
+# Performance Utilities
+
+High-throughput execution utilities for large-scale merge pyramids.
+
+## Quick Start
+
+```typescript
+import { MemoryMonitor, OperationCache, BatchProcessor, WorkerPool } from "./performance";
+
+// Memory monitoring with throttling
+const monitor = new MemoryMonitor({
+  maxMemoryMB: 2048,
+  memoryThresholdPercent: 80,
+});
+
+await monitor.throttleIfNeeded(); // Waits if memory high
+
+// Operation caching
+const cache = new OperationCache<string>(3600); // 1 hour TTL
+const result = await cache.execute("key", () => expensiveOperation());
+
+// Batch processing
+const processor = new BatchProcessor<Item>(50); // Batch size 50
+const results = await processor.processBatches(items, processBatch);
+
+// Worker pool management
+const pool = new WorkerPool(8); // Max 8 workers
+if (pool.acquire()) {
+  // Do work
+  pool.release();
+}
+```
+
+## Modules
+
+### MemoryMonitor
+
+Tracks heap memory and throttles execution when threshold exceeded.
+
+**Configuration via Policy**:
+
+```yaml
+policy:
+  performance:
+    maxMemoryMB: 2048
+    memoryThresholdPercent: 80
+    throttleOnMemory: true
+```
+
+### OperationCache
+
+Generic cache with TTL for expensive operations.
+
+**Features**:
+
+- Configurable TTL
+- Cache statistics
+- Execute-with-cache helper
+
+### BatchProcessor
+
+Processes large arrays in configurable batches.
+
+**Use cases**:
+
+- Large plan processing (100+ PRs)
+- Memory-efficient iteration
+- Progress tracking
+
+### WorkerPool
+
+Manages concurrent worker slots with capacity tracking.
+
+**Features**:
+
+- Acquire/release semantics
+- Capacity checking
+- Wait for capacity
+
+## Integration
+
+Used by:
+
+- `src/gates.ts` - Gate execution with memory throttling
+- `src/mergeOrder.ts` - Dependency resolution caching
+- `src/git/operations.ts` - Merge operation profiling
+
+## Testing
+
+```bash
+npm test -- performance.spec.ts
+```
+
+23 tests covering all utilities with benchmarks.
+
+## See Also
+
+- [Performance & Scale Documentation](../docs/performance-scale.md)
+- [Monitoring Metrics](./monitoring/metrics.ts)

package/src/performance.ts

@@ -0,0 +1,279 @@
+/**
+ * Performance utilities for high-throughput execution
+ * Provides resource monitoring, throttling, and caching
+ */
+
+import { PerformanceConfig } from "./schema.js";
+import { metrics, METRICS } from "./monitoring/metrics.js";
+import { performance } from "node:perf_hooks";
+
+/**
+ * Memory monitor for tracking and throttling based on memory usage
+ */
+export class MemoryMonitor {
+  private config: Partial<PerformanceConfig>;
+
+  constructor(config: Partial<PerformanceConfig> = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Get current memory usage info
+   */
+  getMemoryUsage(): NodeJS.MemoryUsage {
+    return process.memoryUsage();
+  }
+
+  /**
+   * Check if memory usage exceeds threshold
+   */
+  isMemoryHigh(): boolean {
+    if (!this.config.maxMemoryMB) {
+      return false;
+    }
+
+    const usage = this.getMemoryUsage();
+    const usedMB = usage.heapUsed / (1024 * 1024);
+    const maxMB = this.config.maxMemoryMB;
+    const usagePercent = (usedMB / maxMB) * 100;
+
+    // Update metrics
+    metrics.setGauge(METRICS.MEMORY_USAGE_BYTES, usage.heapUsed, { type: "heap_used" });
+
+    return usagePercent >= (this.config.memoryThresholdPercent || 80);
+  }
+
+  /**
+   * Wait if memory is high (throttling)
+   */
+  async throttleIfNeeded(): Promise<void> {
+    if (this.config.throttleOnMemory === false) {
+      return;
+    }
+
+    while (this.isMemoryHigh()) {
+      // Force garbage collection if available
+      if (global.gc) {
+        global.gc();
+      }
+
+      // Wait before checking again
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  /**
+   * Get memory stats as percentage
+   */
+  getMemoryStats(): { usedMB: number; maxMB: number; usagePercent: number } {
+    const usage = this.getMemoryUsage();
+    const usedMB = usage.heapUsed / (1024 * 1024);
+    const maxMB = this.config.maxMemoryMB || usedMB * 2; // Default to 2x current
+    const usagePercent = (usedMB / maxMB) * 100;
+
+    return { usedMB, maxMB, usagePercent };
+  }
+}
+
+/**
+ * Generic cache for expensive operations
+ */
+export class OperationCache<T> {
+  private cache: Map<string, { value: T; timestamp: number }> = new Map();
+  private ttlMs: number;
+  private enabled: boolean;
+
+  constructor(ttlSeconds: number = 3600, enabled: boolean = true) {
+    this.ttlMs = ttlSeconds * 1000;
+    this.enabled = enabled;
+  }
+
+  /**
+   * Get cached value if available and not expired
+   */
+  get(key: string): T | null {
+    if (!this.enabled) {
+      return null;
+    }
+
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+
+    // Use a monotonic clock so tests or consumers mocking Date.now() don't
+    // accidentally disable expiration semantics.
+    const now = performance.now();
+    if (now - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Set cached value
+   */
+  set(key: string, value: T): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    this.cache.set(key, {
+      value,
+      timestamp: performance.now(),
+    });
+  }
+
+  /**
+   * Clear all cached values
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): { size: number; entries: string[] } {
+    return {
+      size: this.cache.size,
+      entries: Array.from(this.cache.keys()),
+    };
+  }
+
+  /**
+   * Execute operation with caching
+   */
+  async execute<R>(key: string, operation: () => Promise<R>): Promise<R> {
+    const cached = this.get(key);
+    if (cached !== null) {
+      return cached as unknown as R;
+    }
+
+    const result = await operation();
+    this.set(key, result as unknown as T);
+    return result;
+  }
+}
+
+/**
+ * Batch processor for handling large plans efficiently
+ */
+export class BatchProcessor<T> {
+  private batchSize: number;
+
+  constructor(batchSize: number = 50) {
+    this.batchSize = batchSize;
+  }
+
+  /**
+   * Process items in batches with concurrency control
+   */
+  async processBatches<R>(
+    items: T[],
+    processor: (batch: T[]) => Promise<R[]>,
+    onBatchComplete?: (results: R[], batchIndex: number) => void
+  ): Promise<R[]> {
+    const results: R[] = [];
+    const batches = this.createBatches(items);
+
+    for (let i = 0; i < batches.length; i++) {
+      const batch = batches[i];
+      const batchResults = await processor(batch);
+      results.push(...batchResults);
+
+      if (onBatchComplete) {
+        onBatchComplete(batchResults, i);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Split items into batches
+   */
+  private createBatches(items: T[]): T[][] {
+    const batches: T[][] = [];
+
+    for (let i = 0; i < items.length; i += this.batchSize) {
+      batches.push(items.slice(i, i + this.batchSize));
+    }
+
+    return batches;
+  }
+
+  /**
+   * Get batch count for given items
+   */
+  getBatchCount(itemCount: number): number {
+    return Math.ceil(itemCount / this.batchSize);
+  }
+}
+
+/**
+ * Worker pool manager for tracking active workers
+ */
+export class WorkerPool {
+  private maxWorkers: number;
+  private activeWorkers: number = 0;
+
+  constructor(maxWorkers: number) {
+    this.maxWorkers = maxWorkers;
+  }
+
+  /**
+   * Check if pool has capacity
+   */
+  hasCapacity(): boolean {
+    return this.activeWorkers < this.maxWorkers;
+  }
+
+  /**
+   * Acquire worker slot
+   */
+  acquire(): boolean {
+    if (!this.hasCapacity()) {
+      return false;
+    }
+
+    this.activeWorkers++;
+    metrics.setGauge(METRICS.ACTIVE_WORKERS, this.activeWorkers);
+    return true;
+  }
+
+  /**
+   * Release worker slot
+   */
+  release(): void {
+    if (this.activeWorkers > 0) {
+      this.activeWorkers--;
+      metrics.setGauge(METRICS.ACTIVE_WORKERS, this.activeWorkers);
+    }
+  }
+
+  /**
+   * Get current worker count
+   */
+  getActiveCount(): number {
+    return this.activeWorkers;
+  }
+
+  /**
+   * Get max workers
+   */
+  getMaxWorkers(): number {
+    return this.maxWorkers;
+  }
+
+  /**
+   * Wait for capacity
+   */
+  async waitForCapacity(pollMs: number = 50): Promise<void> {
+    while (!this.hasCapacity()) {
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+  }
+}

package/src/planner/README.md

@@ -0,0 +1,215 @@
+# File-Change Analysis Engine
+
+The file-change analysis engine detects implicit dependencies between PRs by analyzing file modifications, additions, deletions, and renames.
+
+## Features
+
+- **File Intersection Detection**: Identify PRs that modify the same files
+- **Change Type Classification**: Track additions, deletions, modifications, and renames
+- **Conflict Prediction**: Detect potential merge conflicts before attempting to merge
+- **Dependency Scoring**: Confidence levels (0.0-1.0) for inferred relationships
+- **Smart Caching**: Cache file analysis results for performance
+- **Scope Validation**: Static analysis to validate agent edit scope (NEW)
+
+## Modules
+
+### File Analysis (`fileAnalysis.ts`)
+
+Analyzes file changes across PRs to detect dependencies and conflicts.
+
+### Scope Validation (`scopeValidator.ts`)
+
+**NEW**: Validates that agent edits match declared scope to prevent unintended modifications.
+
+See [Scope Validation Documentation](../../docs/scope-validation.md) for details.
+
+**Key capabilities:**
+
+- Detects global variable writes (`window.*`, `global.*`)
+- Validates function/class modifications match declarations
+- Identifies side effects (module-level vs. global)
+- Supports ESM, CommonJS, AMD, UMD module systems
+- AST-based analysis for JavaScript/TypeScript
+
+**Quick example:**
+
+```typescript
+import { validateEditScope } from "./planner/scopeValidator.js";
+
+const declaredPlan = {
+  functions_modified: ["processPayment"],
+  side_effects: "none",
+  globals_written: [],
+};
+
+await validateEditScope("/path/to/file.js", declaredPlan);
+// Throws ScopeValidationError if actual changes don't match
+```
+
+## Usage
+
+### Basic Usage with GitHub Client
+
+```typescript
+import { createGitHubClient } from "./github/client.js";
+import { analyzeGitHubPRFiles } from "./core/githubPlan.js";
+
+// Create GitHub client
+const client = await createGitHubClient({
+  token: process.env.GITHUB_TOKEN,
+  owner: "your-org",
+  repo: "your-repo",
+});
+
+// Get PR details
+const prs = await client.listOpenPRs();
+const prDetails = await Promise.all(prs.map((pr) => client.getPRDetails(pr.number)));
+
+// Analyze file changes
+const analysis = await analyzeGitHubPRFiles(client, prDetails);
+
+// Review results
+console.log("File Intersections:", analysis.fileIntersections);
+console.log("Dependency Suggestions:", analysis.suggestions);
+console.log("Potential Conflicts:", analysis.conflicts);
+```
+
+### Direct FileAnalyzer Usage
+
+```typescript
+import { createFileAnalyzer } from "./planner/fileAnalysis.js";
+import { Octokit } from "@octokit/rest";
+
+const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+const analyzer = createFileAnalyzer(octokit, "owner", "repo");
+
+// Analyze specific PRs
+const result = await analyzer.analyzeFiles([
+  { number: 101, name: "PR-101", sha: "abc123" },
+  { number: 102, name: "PR-102", sha: "def456" },
+]);
+```
+
+## Output Format
+
+### File Intersections
+
+```json
+{
+  "fileIntersections": [
+    {
+      "prs": ["PR-101", "PR-102"],
+      "files": ["src/core.ts", "src/utils.ts"],
+      "confidence": 0.9
+    }
+  ]
+}
+```
+
+### Dependency Suggestions
+
+```json
+{
+  "suggestions": [
+    {
+      "from": "PR-101",
+      "to": "PR-102",
+      "reason": "shared file modifications",
+      "confidence": 0.85,
+      "sharedFiles": ["src/core.ts"]
+    }
+  ]
+}
+```
+
+### Conflict Predictions
+
+```json
+{
+  "conflicts": [
+    {
+      "prs": ["PR-101", "PR-102"],
+      "files": ["src/core.ts"],
+      "severity": "high",
+      "reason": "Both modify src/core.ts"
+    }
+  ]
+}
+```
+
+## Confidence Scoring
+
+The confidence score (0.0-1.0) is calculated based on:
+
+- **1.0**: Both PRs modify the same file (highest confidence)
+- **0.6**: Mixed modifications (rename, delete)
+- **0.5**: One PR deletes what another modifies
+- **0.3**: Both PRs add the same new file (lower confidence)
+
+## Conflict Severity
+
+- **high**: Both PRs substantially modify the same file (>10 lines), or one deletes what another modifies
+- **medium**: Both PRs modify the same file with small changes (<10 lines)
+- **low**: Minimal overlap (not reported)
+
+## Caching
+
+The file analyzer caches file changes per PR to avoid redundant API calls:
+
+```typescript
+// Get cache statistics
+const stats = analyzer.getCacheStats();
+console.log(`Cache size: ${stats.size}`);
+console.log(`Cached entries: ${stats.entries}`);
+
+// Clear cache if needed
+analyzer.clearCache();
+```
+
+## Integration with Plan Generation
+
+The file analysis integrates with GitHub-based plan generation to suggest additional dependencies:
+
+```typescript
+import { generatePlanFromGitHub } from "./core/githubPlan.js";
+
+const plan = await generatePlanFromGitHub(client, {
+  labels: ["stack:feature"],
+  target: "main",
+});
+
+// Optionally analyze file changes to suggest additional dependencies
+const analysis = await analyzeGitHubPRFiles(client, prDetails);
+```
+
+## API Reference
+
+### `FileAnalyzer`
+
+- `getPRFileChanges(prNumber, sha?)`: Fetch file changes for a PR
+- `buildIntersectionMatrix(prs)`: Build file intersection matrix
+- `predictConflicts(prs)`: Predict potential conflicts
+- `suggestDependencies(prs)`: Generate dependency suggestions
+- `analyzeFiles(prs)`: Perform complete analysis
+- `clearCache()`: Clear the cache
+- `getCacheStats()`: Get cache statistics
+
+### `analyzeGitHubPRFiles(client, prs)`
+
+Convenience function to analyze file changes using a GitHubClient instance.
+
+## Testing
+
+The file analysis engine includes comprehensive test coverage:
+
+```bash
+npm test -- tests/fileAnalysis.spec.ts
+```
+
+Tests cover:
+
+- File change fetching and caching
+- Intersection matrix calculation
+- Conflict prediction with severity levels
+- Dependency suggestion with confidence scoring
+- Cache management