@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/autonomous-build-loop.js

@@ -0,0 +1,637 @@
+/**
+ * Autonomous Build Loop
+ *
+ * Iterates the build-test-fix cycle until all quality criteria pass.
+ * Implements Constitution Article V: Quality First.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ * project structure. Runs quality checks (lint, test, typecheck) and
+ * attempts automated fixes on failure.
+ *
+ * @module core/execution/autonomous-build-loop
+ * @version 3.0.0
+ */
+
+const { execSync } = require("child_process");
+const { EventEmitter } = require("events");
+const { AttemptJournal } = require("./attempt-journal");
+
+// ---------------------------------------------------------------------------
+//  Enums
+// ---------------------------------------------------------------------------
+
+const BuildStatus = {
+  IDLE: "idle",
+  BUILDING: "building",
+  TESTING: "testing",
+  FIXING: "fixing",
+  PASSED: "passed",
+  FAILED: "failed",
+};
+
+// ---------------------------------------------------------------------------
+//  AutonomousBuildLoop
+// ---------------------------------------------------------------------------
+
+class AutonomousBuildLoop extends EventEmitter {
+  /**
+   * @param {string} projectRoot - Absolute path to the project root.
+   * @param {Object} [options]
+   * @param {number} [options.maxIterations=5]   Max build-test-fix cycles.
+   * @param {number} [options.timeoutMs=600000]  Global timeout (10 min).
+   * @param {boolean} [options.runTests=true]    Run `npm test`.
+   * @param {boolean} [options.runLint=true]     Run `npm run lint`.
+   * @param {boolean} [options.runTypecheck=false] Run `npm run typecheck`.
+   * @param {string}  [options.testCommand]      Override test command.
+   * @param {string}  [options.lintCommand]      Override lint command.
+   * @param {string}  [options.typecheckCommand] Override typecheck command.
+   */
+  constructor(projectRoot, options = {}) {
+    super();
+    this.projectRoot = projectRoot;
+    this.options = {
+      maxIterations: 3, // v3.0.0: reduced from 5 to force earlier escalation
+      timeoutMs: 600000,
+      runTests: true,
+      runLint: true,
+      runTypecheck: false,
+      testCommand: "npm test -- --passWithNoTests",
+      lintCommand: "npm run lint",
+      typecheckCommand: "npm run typecheck",
+      ...options,
+    };
+    this.status = BuildStatus.IDLE;
+    this.iterations = [];
+    this._aborted = false;
+    this._startTime = null;
+
+    // v3.0.0 — Attempt journal for approach diversity enforcement
+    this.attemptJournal =
+      options.attemptJournal ||
+      new AttemptJournal({
+        maxAttempts: this.options.maxIterations,
+        debug: options.debug,
+      });
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Run the autonomous build loop for a given task.
+   *
+   * @param {Object} task - Task descriptor (id, description, files, ...).
+   * @returns {Promise<Object>} Final result with status, iterations, duration.
+   */
+  async run(task) {
+    this._aborted = false;
+    this._startTime = Date.now();
+    this.status = BuildStatus.BUILDING;
+    this.iterations = [];
+
+    for (let i = 1; i <= this.options.maxIterations; i++) {
+      if (this._aborted) {
+        this.status = BuildStatus.FAILED;
+        return this._result("Aborted by user");
+      }
+
+      if (this._isTimedOut()) {
+        this.status = BuildStatus.FAILED;
+        return this._result("Global timeout exceeded");
+      }
+
+      const iterStart = Date.now();
+      this.emit("iteration-start", { number: i, task });
+
+      // --- 1. Run quality checks ---
+      this.status = BuildStatus.TESTING;
+      const checks = await this._runQualityChecks();
+
+      if (checks.passed) {
+        const iteration = {
+          number: i,
+          status: "passed",
+          errors: [],
+          duration: Date.now() - iterStart,
+          fixes: [],
+        };
+        this.iterations.push(iteration);
+        this.status = BuildStatus.PASSED;
+        this.emit("iteration-end", iteration);
+        this.emit("build-pass", {
+          iteration: i,
+          duration: Date.now() - this._startTime,
+        });
+        return this._result(null);
+      }
+
+      // --- 2. Collect errors from failed checks ---
+      const errors = checks.results
+        .filter((r) => !r.passed)
+        .map((r) => ({ check: r.check, output: r.output }));
+
+      // --- 2b. Record failure in attempt journal ---
+      const approachDesc = errors
+        .map((e) => `${e.check}: ${(e.output || "").substring(0, 150)}`)
+        .join("; ");
+      this.attemptJournal.record(task.id || "build-loop", {
+        approach: `build-iteration-${i}: ${approachDesc}`,
+        error: approachDesc,
+        success: false,
+        context: { iteration: i, checks: errors.map((e) => e.check) },
+      });
+
+      // --- 2c. Check approach diversity before next fix ---
+      if (i > 1) {
+        const diversityCheck = this.attemptJournal.checkApproach(
+          task.id || "build-loop",
+          approachDesc,
+        );
+        if (!diversityCheck.allowed) {
+          // Same errors repeating — force early escalation instead of wasting iterations
+          this.status = BuildStatus.FAILED;
+          const escalation = {
+            iteration: i,
+            errors,
+            fixesAttempted: this.iterations.flatMap((it) => it.fixes || []),
+            recommendation:
+              `APPROACH DIVERSITY BLOCK: ${diversityCheck.reason}. ` +
+              this._buildEscalationMessage(errors, this.iterations),
+            suggestions: diversityCheck.suggestions,
+            journal: this.attemptJournal.getSummary(task.id || "build-loop"),
+          };
+          this.emit("build-escalate", escalation);
+          this.emit("build-fail", { iteration: i, errors });
+          const result = this._result(
+            `Approach diversity check failed at iteration ${i}: identical errors repeating`,
+          );
+          result.escalation = escalation;
+          return result;
+        }
+      }
+
+      // --- 3. Attempt automated fix ---
+      this.status = BuildStatus.FIXING;
+      const fixResult = await this._attemptFix(errors);
+
+      const iteration = {
+        number: i,
+        status: "failed",
+        errors,
+        duration: Date.now() - iterStart,
+        fixes: fixResult.fixes,
+      };
+      this.iterations.push(iteration);
+      this.emit("iteration-end", iteration);
+
+      if (!fixResult.fixed && i === this.options.maxIterations) {
+        this.status = BuildStatus.FAILED;
+
+        // Structured escalation with what was tried/failed
+        const escalation = {
+          iteration: i,
+          errors,
+          fixesAttempted: this.iterations.flatMap((it) => it.fixes || []),
+          recommendation: this._buildEscalationMessage(errors, this.iterations),
+        };
+        this.emit("build-escalate", escalation);
+        this.emit("build-fail", { iteration: i, errors });
+
+        // Call escalation callback if provided
+        if (typeof this.options.escalationCallback === "function") {
+          this.options.escalationCallback(errors, this.iterations);
+        }
+
+        const result = this._result(
+          "Max iterations reached without passing quality checks",
+        );
+        result.escalation = escalation;
+        return result;
+      }
+    }
+
+    this.status = BuildStatus.FAILED;
+    return this._result("Max iterations reached");
+  }
+
+  /**
+   * Abort a running build loop.
+   */
+  abort() {
+    this._aborted = true;
+  }
+
+  /**
+   * @returns {Array} Copy of recorded iterations.
+   */
+  getIterations() {
+    return [...this.iterations];
+  }
+
+  /**
+   * @returns {string} Current build status.
+   */
+  getStatus() {
+    return this.status;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Quality Checks
+  // -----------------------------------------------------------------------
+
+  /**
+   * Run the configured quality checks (lint, test, typecheck).
+   *
+   * @returns {Promise<{passed: boolean, results: Array}>}
+   */
+  async _runQualityChecks() {
+    const results = [];
+
+    if (this.options.runLint) {
+      results.push(this._execCheck("lint", this.options.lintCommand));
+    }
+
+    if (this.options.runTests) {
+      results.push(this._execCheck("test", this.options.testCommand));
+    }
+
+    if (this.options.runTypecheck) {
+      results.push(this._execCheck("typecheck", this.options.typecheckCommand));
+    }
+
+    const passed = results.every((r) => r.passed);
+    return { passed, results };
+  }
+
+  /**
+   * Execute a single quality check command.
+   *
+   * @param {string} check - Check name (lint | test | typecheck).
+   * @param {string} command - Shell command to run.
+   * @returns {{check: string, passed: boolean, output: string}}
+   */
+  _execCheck(check, command) {
+    try {
+      const output = execSync(command, {
+        cwd: this.projectRoot,
+        encoding: "utf-8",
+        stdio: "pipe",
+        timeout: Math.min(this.options.timeoutMs, 120000),
+      });
+      return { check, passed: true, output: output.trim() };
+    } catch (err) {
+      const output =
+        (err.stdout ? err.stdout.toString() : "") +
+        (err.stderr ? err.stderr.toString() : "");
+      return { check, passed: false, output: output.trim() };
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  //  Automated Fix Attempt
+  // -----------------------------------------------------------------------
+
+  /**
+   * Analyse errors and attempt lightweight automated fixes.
+   *
+   * Categories handled:
+   *  - lint-error  : try `npm run lint -- --fix`
+   *  - test-failure: no auto-fix, return suggestions
+   *  - type-error  : no auto-fix, return suggestions
+   *  - build-error : no auto-fix, return suggestions
+   *
+   * @param {Array} errors - Array of {check, output}.
+   * @returns {Promise<{fixed: boolean, fixes: Array}>}
+   */
+  async _attemptFix(errors) {
+    const fixes = [];
+
+    for (const error of errors) {
+      const classification = this._categoriseError(error);
+
+      // Environment recovery attempt
+      if (classification.isEnvironment) {
+        const recovery = this._attemptEnvironmentRecovery(classification);
+        if (recovery.attempted && recovery.success) {
+          fixes.push({
+            category: classification.category,
+            subcategory: classification.subcategory,
+            action: "env-recovery",
+            description: `Environment recovery: ${recovery.action}`,
+          });
+          continue;
+        }
+      }
+
+      if (classification.recovery === "auto-fix") {
+        // Attempt auto-fix via lint --fix
+        try {
+          execSync(`${this.options.lintCommand} -- --fix`, {
+            cwd: this.projectRoot,
+            encoding: "utf-8",
+            stdio: "pipe",
+            timeout: 60000,
+          });
+          fixes.push({
+            category: classification.category,
+            subcategory: classification.subcategory,
+            action: "auto-fix",
+            description: "Ran lint --fix successfully",
+          });
+        } catch {
+          fixes.push({
+            category: classification.category,
+            subcategory: classification.subcategory,
+            action: "suggestion",
+            description: "Lint --fix was attempted but some issues remain",
+          });
+        }
+      } else {
+        fixes.push({
+          category: classification.category,
+          subcategory: classification.subcategory,
+          action: "suggestion",
+          description: `${classification.category} (${classification.subcategory}): ${classification.recovery}`,
+        });
+      }
+    }
+
+    // Consider it "fixed" only if every error produced an auto-fix or env-recovery action
+    const fixed =
+      fixes.length > 0 &&
+      fixes.every(
+        (f) => f.action === "auto-fix" || f.action === "env-recovery",
+      );
+    return { fixed, fixes };
+  }
+
+  /**
+   * Classify an error into a category with detailed failure analysis.
+   *
+   * Returns both the category and a recovery strategy to guide the fix attempt.
+   *
+   * @param {{check: string, output: string}} error
+   * @returns {{category: string, subcategory: string, recovery: string, isEnvironment: boolean}}
+   */
+  _categoriseError(error) {
+    const output = (error.output || "").toLowerCase();
+
+    // Check-based primary classification
+    if (error.check === "lint") {
+      return {
+        category: "lint-error",
+        subcategory: "style",
+        recovery: "auto-fix",
+        isEnvironment: false,
+      };
+    }
+
+    if (error.check === "typecheck") {
+      // Distinguish missing type definitions from logic type errors
+      if (
+        output.includes("cannot find module") ||
+        output.includes("could not find a declaration file")
+      ) {
+        return {
+          category: "type-error",
+          subcategory: "missing-types",
+          recovery: "install-types",
+          isEnvironment: true,
+        };
+      }
+      return {
+        category: "type-error",
+        subcategory: "logic",
+        recovery: "manual-fix",
+        isEnvironment: false,
+      };
+    }
+
+    if (error.check === "test") {
+      // Environment issues
+      if (
+        output.includes("enoent") ||
+        output.includes("command not found") ||
+        output.includes("not recognized")
+      ) {
+        return {
+          category: "test-failure",
+          subcategory: "missing-tool",
+          recovery: "install-dependency",
+          isEnvironment: true,
+        };
+      }
+      if (output.includes("eacces") || output.includes("permission denied")) {
+        return {
+          category: "test-failure",
+          subcategory: "permission",
+          recovery: "fix-permissions",
+          isEnvironment: true,
+        };
+      }
+      if (
+        output.includes("eaddrinuse") ||
+        output.includes("address already in use")
+      ) {
+        return {
+          category: "test-failure",
+          subcategory: "port-conflict",
+          recovery: "kill-process",
+          isEnvironment: true,
+        };
+      }
+      if (
+        output.includes("cannot find module") ||
+        output.includes("module not found")
+      ) {
+        return {
+          category: "test-failure",
+          subcategory: "missing-module",
+          recovery: "install-dependency",
+          isEnvironment: true,
+        };
+      }
+      if (output.includes("out of memory") || output.includes("heap")) {
+        return {
+          category: "test-failure",
+          subcategory: "oom",
+          recovery: "increase-memory",
+          isEnvironment: true,
+        };
+      }
+      if (output.includes("timeout") || output.includes("timed out")) {
+        return {
+          category: "test-failure",
+          subcategory: "timeout",
+          recovery: "increase-timeout",
+          isEnvironment: false,
+        };
+      }
+      // Default: assertion failure (logic error in code)
+      return {
+        category: "test-failure",
+        subcategory: "assertion",
+        recovery: "manual-fix",
+        isEnvironment: false,
+      };
+    }
+
+    // Build errors
+    if (
+      output.includes("cannot find module") ||
+      output.includes("module not found")
+    ) {
+      return {
+        category: "build-error",
+        subcategory: "missing-module",
+        recovery: "install-dependency",
+        isEnvironment: true,
+      };
+    }
+    return {
+      category: "build-error",
+      subcategory: "unknown",
+      recovery: "manual-fix",
+      isEnvironment: false,
+    };
+  }
+
+  /**
+   * Attempt environment recovery based on failure classification.
+   *
+   * @param {{category: string, subcategory: string, recovery: string}} classification
+   * @returns {{attempted: boolean, success: boolean, action: string}}
+   */
+  _attemptEnvironmentRecovery(classification) {
+    const { recovery } = classification;
+
+    try {
+      switch (recovery) {
+        case "install-dependency": {
+          execSync("npm install", {
+            cwd: this.projectRoot,
+            encoding: "utf-8",
+            stdio: "pipe",
+            timeout: 120000,
+          });
+          return { attempted: true, success: true, action: "npm install" };
+        }
+        case "install-types": {
+          // Try installing missing @types packages
+          execSync("npm install", {
+            cwd: this.projectRoot,
+            encoding: "utf-8",
+            stdio: "pipe",
+            timeout: 120000,
+          });
+          return {
+            attempted: true,
+            success: true,
+            action: "npm install (types)",
+          };
+        }
+        case "kill-process": {
+          // Cannot safely kill processes — flag for manual intervention
+          return {
+            attempted: false,
+            success: false,
+            action: "port-conflict requires manual resolution",
+          };
+        }
+        case "increase-memory": {
+          // Cannot change memory limits — flag for manual intervention
+          return {
+            attempted: false,
+            success: false,
+            action: "OOM requires NODE_OPTIONS=--max-old-space-size",
+          };
+        }
+        case "fix-permissions": {
+          return {
+            attempted: false,
+            success: false,
+            action: "Permission issue requires manual resolution",
+          };
+        }
+        default:
+          return {
+            attempted: false,
+            success: false,
+            action: "no-recovery-available",
+          };
+      }
+    } catch {
+      return { attempted: true, success: false, action: `${recovery} failed` };
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  //  Escalation
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build a structured escalation message for human review.
+   *
+   * @param {Array} errors - Current errors
+   * @param {Array} iterations - All iteration records
+   * @returns {string} Escalation message
+   */
+  _buildEscalationMessage(errors, iterations) {
+    const fixesAttempted = iterations.flatMap((it) => it.fixes || []);
+    const uniqueErrors = [
+      ...new Set(
+        errors.map((e) => `${e.check}: ${(e.output || "").substring(0, 200)}`),
+      ),
+    ];
+    const uniqueFixes = [
+      ...new Set(fixesAttempted.map((f) => `${f.action}: ${f.description}`)),
+    ];
+    const envIssues = fixesAttempted.filter((f) => f.action === "env-recovery");
+    const ciFallback =
+      envIssues.length > 0
+        ? "Environment issues detected — consider running via CI instead of local environment."
+        : "";
+
+    return [
+      `Failed after ${iterations.length} attempts.`,
+      `Errors: ${uniqueErrors.join("; ")}`,
+      `Fixes tried: ${uniqueFixes.join("; ") || "none"}`,
+      ciFallback,
+      "Recommendation: manual review required.",
+    ]
+      .filter(Boolean)
+      .join(" ");
+  }
+
+  // -----------------------------------------------------------------------
+  //  Helpers
+  // -----------------------------------------------------------------------
+
+  /** @returns {boolean} */
+  _isTimedOut() {
+    if (!this._startTime) return false;
+    return Date.now() - this._startTime > this.options.timeoutMs;
+  }
+
+  /**
+   * Build a standardised result object.
+   * @param {string|null} error
+   * @returns {Object}
+   */
+  _result(error) {
+    return {
+      status: this.status,
+      passed: this.status === BuildStatus.PASSED,
+      error,
+      iterations: this.getIterations(),
+      duration: Date.now() - this._startTime,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { AutonomousBuildLoop, BuildStatus };