clearctx 3.0.0

package/src/dependency-resolver.js

@@ -0,0 +1,453 @@
+/**
+ * dependency-resolver.js
+ * Layer 2: Dependency Resolution Engine for clearctx
+ *
+ * This is the CORE algorithm that automatically advances contracts when their
+ * dependencies are satisfied. It runs after every artifact publish and contract
+ * status change to check if new work can be started or completed.
+ *
+ * Think of it like a project manager who:
+ * 1. Checks if blocked tasks can now start (dependencies satisfied)
+ * 2. Checks if running tasks are taking too long (timeouts)
+ * 3. Checks if completed work meets acceptance criteria (auto-completion)
+ * 4. Notifies team members when their tasks are ready
+ *
+ * @class DependencyResolver
+ */
+
+const ArtifactStore = require('./artifact-store');
+const ContractStore = require('./contract-store');
+const TeamHub = require('./team-hub');
+const { acquireLock, releaseLock } = require('./file-lock');
+const path = require('path');
+const os = require('os');
+
+/**
+ * DependencyResolver - Automatically advances contracts when dependencies are met
+ *
+ * This class is called after:
+ * - An artifact is published (might satisfy artifact dependencies)
+ * - A contract changes status (might satisfy contract dependencies)
+ *
+ * It performs a cascade of checks and transitions:
+ * - Pending contracts → Ready (when dependencies satisfied)
+ * - In-progress contracts → Failed (when timeout exceeded)
+ * - In-progress contracts → Completed (when acceptance criteria met)
+ */
+class DependencyResolver {
+  /**
+   * Create a new DependencyResolver
+   *
+   * @param {string} teamName - The team name (default: 'default')
+   */
+  constructor(teamName = 'default') {
+    // Store the team name for later use
+    this.teamName = teamName;
+
+    // Create instances of the three core stores
+    // These let us read artifacts, contracts, and send messages
+    this.artifacts = new ArtifactStore(teamName);
+    this.contracts = new ContractStore(teamName);
+    this.teamHub = new TeamHub(teamName);
+
+    // Maximum cascade depth - prevents infinite loops
+    // If resolve() calls itself too many times, we stop
+    this.maxCascadeDepth = Number(process.env.CMS_MAX_CASCADE_DEPTH) || 10;
+
+    // Pipeline engine reference (set later to avoid circular require)
+    this.pipelineEngine = null;
+
+    // Set up the locks directory path
+    const baseDir = path.join(os.homedir(), '.clearctx');
+    this.locksDir = path.join(baseDir, 'team', teamName, 'locks');
+  }
+
+  /**
+   * Set the pipeline engine reference
+   * This is called after the pipeline engine is created to avoid circular dependencies
+   *
+   * @param {Object} engine - The pipeline engine instance
+   */
+  setPipelineEngine(engine) {
+    this.pipelineEngine = engine;
+  }
+
+  /**
+   * Main resolution method - checks all contracts and advances them if possible
+   *
+   * This is the heart of the dependency resolver. It:
+   * 1. Checks for timeouts
+   * 2. Advances pending contracts to ready
+   * 3. Auto-completes contracts that meet criteria
+   * 4. Cascades to handle newly completed contracts
+   *
+   * @param {Object} trigger - What triggered this resolution (for debugging)
+   * @param {number} depth - Current cascade depth (prevents infinite loops)
+   * @returns {Promise<Object>} Object with transitions array and depth
+   */
+  async resolve(trigger = {}, depth = 0) {
+    // Step 1: Check if we've cascaded too deep (safety check)
+    if (depth >= this.maxCascadeDepth) {
+      // Send a warning message to the orchestrator
+      const orchestratorInbox = this.teamHub.getInbox('orchestrator');
+      if (orchestratorInbox) {
+        this.teamHub.sendDirect(
+          'dependency-resolver',
+          'orchestrator',
+          `Cascade depth limit reached (${this.maxCascadeDepth}). Some contracts may need manual intervention.`,
+          { priority: 'urgent' }
+        );
+      }
+
+      return { cascadeLimited: true, depth };
+    }
+
+    // Step 2: Track all transitions that happen in this cycle
+    // A transition is when a contract moves from one status to another
+    const transitions = [];
+
+    // Step 3: Check for timed-out contracts
+    // Get all contracts that are currently in progress
+    const inProgressContracts = this.contracts.list({ status: 'in_progress' });
+
+    for (const contract of inProgressContracts) {
+      // Only check timeout if timeoutMs is set
+      if (contract.timeoutMs && contract.startedAt) {
+        // Calculate how long the contract has been running
+        const now = Date.now();
+        const startedTime = new Date(contract.startedAt).getTime();
+        const elapsedTime = now - startedTime;
+
+        // If elapsed time exceeds timeout, fail the contract
+        if (elapsedTime > contract.timeoutMs) {
+          try {
+            this.contracts.fail(contract.contractId, 'Timeout exceeded');
+
+            // Record this transition
+            transitions.push({
+              contractId: contract.contractId,
+              from: 'in_progress',
+              to: 'failed',
+              reason: 'timeout'
+            });
+
+            // Notify the assignee that their contract timed out
+            this.teamHub.sendDirect(
+              'dependency-resolver',
+              contract.assignee,
+              `Contract "${contract.contractId}" timed out after ${contract.timeoutMs}ms`,
+              { priority: 'urgent' }
+            );
+          } catch (err) {
+            // If failing the contract throws an error, log it but continue
+            // (contract might have been modified by another process)
+            console.error(`Failed to timeout contract ${contract.contractId}:`, err.message);
+          }
+        }
+      }
+    }
+
+    // Step 4: Check pending contracts for satisfied dependencies
+    // Get all contracts that are waiting for dependencies
+    const pendingContracts = this.contracts.list({ status: 'pending' });
+
+    for (const contract of pendingContracts) {
+      // Check if ALL dependencies are satisfied
+      let allSatisfied = true;
+
+      // Loop through each dependency
+      for (const dep of contract.dependencies) {
+        const satisfied = this._checkDependency(dep);
+        if (!satisfied) {
+          allSatisfied = false;
+          break; // No need to check more if one is not satisfied
+        }
+      }
+
+      // If all dependencies are satisfied, transition to ready
+      if (allSatisfied) {
+        try {
+          // Use the helper method to transition pending → ready
+          this._transitionToReady(contract.contractId);
+
+          // Record this transition
+          transitions.push({
+            contractId: contract.contractId,
+            from: 'pending',
+            to: 'ready',
+            reason: 'dependencies_satisfied'
+          });
+
+          // Notify the assignee that their contract is ready to start
+          this.teamHub.sendDirect(
+            'dependency-resolver',
+            contract.assignee,
+            `Contract "${contract.contractId}" is ready to start (all dependencies satisfied)`,
+            { priority: 'normal' }
+          );
+        } catch (err) {
+          // If transition fails, log but continue
+          console.error(`Failed to transition contract ${contract.contractId} to ready:`, err.message);
+        }
+      }
+    }
+
+    // Step 5: Evaluate acceptance criteria for in_progress contracts
+    // Re-fetch in-progress contracts (some might have timed out in step 3)
+    const currentInProgress = this.contracts.list({ status: 'in_progress' });
+
+    for (const contract of currentInProgress) {
+      // Skip if autoComplete is disabled
+      if (!contract.autoComplete) {
+        continue;
+      }
+
+      // Check if ALL acceptance criteria are met
+      let allCriteriaMet = true;
+
+      // If there are no criteria, we can't auto-complete
+      if (contract.acceptanceCriteria.length === 0) {
+        continue;
+      }
+
+      // Loop through each criterion
+      for (const criterion of contract.acceptanceCriteria) {
+        const met = this._evaluateCriterion(criterion, contract);
+        if (!met) {
+          allCriteriaMet = false;
+          break; // No need to check more if one is not met
+        }
+      }
+
+      // If all criteria met, auto-complete the contract
+      if (allCriteriaMet) {
+        try {
+          this.contracts.complete(contract.contractId, {
+            summary: 'Auto-completed: all acceptance criteria met'
+          });
+
+          // Record this transition
+          transitions.push({
+            contractId: contract.contractId,
+            from: 'in_progress',
+            to: 'completed',
+            reason: 'auto_complete'
+          });
+
+          // Notify both assignee and assigner
+          this.teamHub.sendDirect(
+            'dependency-resolver',
+            contract.assignee,
+            `Contract "${contract.contractId}" auto-completed (all criteria met)`,
+            { priority: 'normal' }
+          );
+
+          this.teamHub.sendDirect(
+            'dependency-resolver',
+            contract.assigner,
+            `Contract "${contract.contractId}" completed by ${contract.assignee}`,
+            { priority: 'normal' }
+          );
+        } catch (err) {
+          console.error(`Failed to auto-complete contract ${contract.contractId}:`, err.message);
+        }
+      }
+    }
+
+    // Step 6: Handle cascading and notifications
+    if (transitions.length > 0) {
+      // Send summary notification to orchestrator if it exists
+      try {
+        this.teamHub.sendDirect(
+          'dependency-resolver',
+          'orchestrator',
+          `Resolution cycle complete: ${transitions.length} transition(s) at depth ${depth}`,
+          { priority: 'normal' }
+        );
+      } catch (err) {
+        // Orchestrator might not exist, that's okay
+      }
+
+      // If pipeline engine is configured, evaluate it for each transition
+      if (this.pipelineEngine) {
+        for (const transition of transitions) {
+          try {
+            await this.pipelineEngine.evaluate(transition);
+          } catch (err) {
+            console.error('Pipeline evaluation failed:', err.message);
+          }
+        }
+      }
+
+      // Cascade: recursively call resolve for any completed contracts
+      // This allows newly completed contracts to unlock other pending ones
+      const completedTransitions = transitions.filter(t => t.to === 'completed');
+
+      if (completedTransitions.length > 0) {
+        // Recursively resolve with increased depth
+        await this.resolve({ cascadeFrom: completedTransitions }, depth + 1);
+      }
+    }
+
+    // Step 7: Return results
+    return { transitions, depth };
+  }
+
+  /**
+   * Check if a single dependency is satisfied
+   *
+   * @private
+   * @param {Object} dep - The dependency object
+   * @param {string} dep.type - Type of dependency ('artifact' or 'contract')
+   * @param {string} dep.artifactId - Artifact ID (if type is 'artifact')
+   * @param {string} dep.contractId - Contract ID (if type is 'contract')
+   * @returns {boolean} True if dependency is satisfied, false otherwise
+   */
+  _checkDependency(dep) {
+    // Handle artifact dependency
+    if (dep.type === 'artifact') {
+      // Check if the artifact exists
+      const artifact = this.artifacts.get(dep.artifactId);
+      return artifact !== null;
+    }
+
+    // Handle contract dependency
+    if (dep.type === 'contract') {
+      // Check if the referenced contract is completed
+      const contract = this.contracts.get(dep.contractId);
+      return contract !== null && contract.status === 'completed';
+    }
+
+    // Unknown dependency type - consider it unsatisfied
+    return false;
+  }
+
+  /**
+   * Evaluate a single acceptance criterion
+   *
+   * @private
+   * @param {Object} criterion - The acceptance criterion object
+   * @param {string} criterion.type - Type of criterion
+   * @param {Object} contract - The contract being evaluated
+   * @returns {boolean} True if criterion is met, false otherwise
+   */
+  _evaluateCriterion(criterion, contract) {
+    // Handle 'artifact_published' criterion
+    // Checks if a specific artifact exists
+    if (criterion.type === 'artifact_published') {
+      const artifact = this.artifacts.get(criterion.artifactId);
+      return artifact !== null;
+    }
+
+    // Handle 'tests_passing' criterion
+    // Checks if test-results artifact shows no failures
+    if (criterion.type === 'tests_passing') {
+      // Look for a test-results artifact
+      const testArtifacts = this.artifacts.list({ type: 'test-results' });
+
+      // If no test results, criterion not met
+      if (testArtifacts.length === 0) {
+        return false;
+      }
+
+      // Get the latest test results
+      const latestTest = testArtifacts[testArtifacts.length - 1];
+      const testData = this.artifacts.get(latestTest.artifactId);
+
+      if (!testData || !testData.data) {
+        return false;
+      }
+
+      // Check if failures are zero (or within threshold if specified)
+      const threshold = criterion.maxFailures || 0;
+      return testData.data.failed <= threshold;
+    }
+
+    // Handle 'contract_completed' criterion
+    // Checks if another contract is completed
+    if (criterion.type === 'contract_completed') {
+      const referencedContract = this.contracts.get(criterion.contractId);
+      return referencedContract !== null && referencedContract.status === 'completed';
+    }
+
+    // Handle 'all_outputs_published' criterion
+    // Checks if all expected outputs have matching artifacts
+    if (criterion.type === 'all_outputs_published') {
+      // Get the expected outputs from the contract
+      const expectedOutputs = contract.expectedOutputs || [];
+
+      if (expectedOutputs.length === 0) {
+        // No outputs expected - criterion met
+        return true;
+      }
+
+      // Check each expected output
+      for (const output of expectedOutputs) {
+        // Each output should have an artifactId
+        if (output.artifactId) {
+          const artifact = this.artifacts.get(output.artifactId);
+          if (!artifact) {
+            return false; // Missing artifact
+          }
+        }
+      }
+
+      return true; // All outputs published
+    }
+
+    // Unknown criterion type - consider it not met
+    return false;
+  }
+
+  /**
+   * Transition a contract from pending to ready
+   * Uses locking to ensure thread-safety
+   *
+   * @private
+   * @param {string} contractId - The contract to transition
+   */
+  _transitionToReady(contractId) {
+    // Acquire lock on contracts index
+    acquireLock(this.locksDir, 'contracts-index');
+
+    try {
+      // Get the contract
+      const contract = this.contracts.get(contractId);
+
+      if (!contract) {
+        throw new Error(`Contract ${contractId} not found`);
+      }
+
+      // Verify it's in pending status
+      if (contract.status !== 'pending') {
+        throw new Error(`Contract ${contractId} is not pending (status: ${contract.status})`);
+      }
+
+      // Read the entire index
+      const { readJsonSafe, atomicWriteJson } = require('./atomic-io');
+      const indexPath = path.join(
+        os.homedir(),
+        '.clearctx',
+        'team',
+        this.teamName,
+        'contracts',
+        'index.json'
+      );
+      const index = readJsonSafe(indexPath, {});
+
+      // Update the contract status
+      index[contractId].status = 'ready';
+      index[contractId].updatedAt = new Date().toISOString();
+
+      // Save the index
+      atomicWriteJson(indexPath, index);
+
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'contracts-index');
+    }
+  }
+}
+
+// Export the DependencyResolver class
+module.exports = DependencyResolver;