tribunal-kit 9.2.6 → 9.2.8

package/src/execution/schemas.js

@@ -0,0 +1,298 @@
+'use strict';
+
+/**
+ * schemas.js — Strict Schemas and Parsers for Review Execution
+ * =============================================================
+ * Phase 1C: Strict Result Schema
+ *
+ * Guarantees:
+ * 1. Valid verdicts: APPROVED, WARNING, REJECTED, ERROR
+ * 2. Valid severities: INFO, LOW, MEDIUM, HIGH, CRITICAL
+ * 3. Reject malformed model output — never silently parse prose as approval.
+ * 4. Malformed output becomes ERROR.
+ */
+
+const VALID_VERDICTS = Object.freeze(new Set(['APPROVED', 'WARNING', 'REJECTED', 'ERROR']));
+const VALID_SEVERITIES = Object.freeze(new Set(['INFO', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL']));
+
+/**
+ * Normalizes severity string to valid uppercase enum.
+ * @param {string} sev
+ * @returns {'INFO'|'LOW'|'MEDIUM'|'HIGH'|'CRITICAL'}
+ */
+function normalizeSeverity(sev) {
+  if (typeof sev !== 'string') return 'MEDIUM';
+  const upper = sev.trim().toUpperCase();
+  if (VALID_SEVERITIES.has(upper)) return upper;
+  if (upper === 'MINOR') return 'LOW';
+  if (upper === 'IMPORTANT') return 'HIGH';
+  if (upper === 'WARN' || upper === 'WARNING') return 'MEDIUM';
+  return 'MEDIUM';
+}
+
+/**
+ * Validates a single review finding against strict schema.
+ * @param {any} item
+ * @param {number} index
+ * @returns {{ valid: boolean, finding?: Object, error?: string }}
+ */
+function validateFinding(item, index) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    return { valid: false, error: `Finding at index ${index} must be an object.` };
+  }
+
+  const id = typeof item.id === 'string' && item.id.trim() ? item.id.trim() : `F-${index + 1}`;
+  const severity = normalizeSeverity(item.severity);
+  const title =
+    typeof item.title === 'string' && item.title.trim()
+      ? item.title.trim()
+      : typeof item.issue === 'string' && item.issue.trim()
+        ? item.issue.trim()
+        : typeof item.description === 'string' && item.description.trim()
+          ? item.description.trim().slice(0, 80)
+          : `Issue ${index + 1}`;
+
+  const description =
+    typeof item.description === 'string' && item.description.trim()
+      ? item.description.trim()
+      : typeof item.issue === 'string' && item.issue.trim()
+        ? item.issue.trim()
+        : title;
+
+  const evidence = typeof item.evidence === 'string' ? item.evidence.trim() : '';
+  const location =
+    typeof item.location === 'string'
+      ? item.location.trim()
+      : typeof item.file === 'string'
+        ? `${item.file}${item.line ? ':' + item.line : ''}`
+        : 'unspecified';
+
+  const recommendation =
+    typeof item.recommendation === 'string' && item.recommendation.trim()
+      ? item.recommendation.trim()
+      : typeof item.fix === 'string' && item.fix.trim()
+        ? item.fix.trim()
+        : 'Review and address identified issue';
+
+  return {
+    valid: true,
+    finding: {
+      id,
+      severity,
+      title,
+      description,
+      evidence,
+      location,
+      recommendation,
+    },
+  };
+}
+
+/**
+ * Strips markdown code fences from raw LLM output before parsing.
+ * @param {string} raw
+ * @returns {string}
+ */
+function extractJsonPayload(raw) {
+  if (typeof raw !== 'string') return '';
+  let cleaned = raw.trim();
+
+  // If wrapped in ```json ... ``` or ``` ... ```
+  const codeBlockMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+  if (codeBlockMatch && codeBlockMatch[1]) {
+    cleaned = codeBlockMatch[1].trim();
+  } else {
+    // If output has extra leading text, attempt to find first '{' and last '}'
+    const firstBrace = cleaned.indexOf('{');
+    const lastBrace = cleaned.lastIndexOf('}');
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+      cleaned = cleaned.substring(firstBrace, lastBrace + 1).trim();
+    }
+  }
+
+  return cleaned;
+}
+
+/**
+ * Parses and strictly validates raw model output against the ReviewerResult schema.
+ * If output is malformed, returns a fail-closed ERROR result.
+ *
+ * @param {string|Object} rawOutput
+ * @param {string} [reviewerId='reviewer']
+ * @returns {{
+ *   isValid: boolean,
+ *   verdict: 'APPROVED'|'WARNING'|'REJECTED'|'ERROR',
+ *   confidence: number,
+ *   findings: Array<Object>,
+ *   recommendations: Array<string>,
+ *   error?: string,
+ *   rawParsed?: Object
+ * }}
+ */
+function parseAndValidateReviewerOutput(rawOutput, reviewerId = 'reviewer') {
+  if (rawOutput === null || rawOutput === undefined) {
+    return {
+      isValid: false,
+      verdict: 'ERROR',
+      confidence: 0.0,
+      findings: [],
+      recommendations: [],
+      error: 'EMPTY_OUTPUT: Model returned null or undefined.',
+    };
+  }
+
+  let parsed = null;
+  if (typeof rawOutput === 'object' && !Array.isArray(rawOutput)) {
+    parsed = rawOutput;
+  } else if (typeof rawOutput === 'string') {
+    const jsonStr = extractJsonPayload(rawOutput);
+    if (!jsonStr) {
+      return {
+        isValid: false,
+        verdict: 'ERROR',
+        confidence: 0.0,
+        findings: [],
+        recommendations: [],
+        error: 'EMPTY_PAYLOAD: No valid JSON block detected in model response.',
+      };
+    }
+    try {
+      parsed = JSON.parse(jsonStr);
+    } catch (parseErr) {
+      return {
+        isValid: false,
+        verdict: 'ERROR',
+        confidence: 0.0,
+        findings: [],
+        recommendations: [],
+        error: `JSON_PARSE_ERROR: Failed to parse model output as JSON (${parseErr.message}).`,
+      };
+    }
+  } else {
+    return {
+      isValid: false,
+      verdict: 'ERROR',
+      confidence: 0.0,
+      findings: [],
+      recommendations: [],
+      error: `INVALID_TYPE: Expected string or object, got ${typeof rawOutput}.`,
+    };
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      isValid: false,
+      verdict: 'ERROR',
+      confidence: 0.0,
+      findings: [],
+      recommendations: [],
+      error: 'INVALID_ROOT: Root of model output must be a JSON object.',
+    };
+  }
+
+  // 1. Validate verdict
+  const rawVerdict =
+    typeof parsed.verdict === 'string' ? parsed.verdict.trim().toUpperCase() : null;
+  if (!rawVerdict || !VALID_VERDICTS.has(rawVerdict)) {
+    return {
+      isValid: false,
+      verdict: 'ERROR',
+      confidence: 0.0,
+      findings: [],
+      recommendations: [],
+      error: `INVALID_VERDICT: Verdict must be one of [APPROVED, WARNING, REJECTED, ERROR], got "${parsed.verdict}".`,
+      rawParsed: parsed,
+    };
+  }
+
+  // 2. Validate confidence
+  let confidence = 0.0;
+  if (typeof parsed.confidence === 'number' && !isNaN(parsed.confidence)) {
+    confidence = Math.max(0.0, Math.min(1.0, parseFloat(parsed.confidence.toFixed(2))));
+  } else if (typeof parsed.confidence === 'string') {
+    const num = parseFloat(parsed.confidence);
+    if (!isNaN(num)) {
+      confidence = Math.max(0.0, Math.min(1.0, parseFloat(num.toFixed(2))));
+    }
+  }
+
+  // 3. Validate findings
+  const findings = [];
+  if (parsed.findings !== undefined && parsed.findings !== null) {
+    if (!Array.isArray(parsed.findings)) {
+      return {
+        isValid: false,
+        verdict: 'ERROR',
+        confidence: 0.0,
+        findings: [],
+        recommendations: [],
+        error: 'INVALID_FINDINGS: "findings" must be an array.',
+        rawParsed: parsed,
+      };
+    }
+    for (let i = 0; i < parsed.findings.length; i++) {
+      const res = validateFinding(parsed.findings[i], i);
+      if (!res.valid) {
+        return {
+          isValid: false,
+          verdict: 'ERROR',
+          confidence: 0.0,
+          findings: [],
+          recommendations: [],
+          error: `INVALID_FINDING: ${res.error}`,
+          rawParsed: parsed,
+        };
+      }
+      findings.push(res.finding);
+    }
+  }
+
+  // 4. Validate recommendations
+  const recommendations = [];
+  if (parsed.recommendations !== undefined && parsed.recommendations !== null) {
+    if (!Array.isArray(parsed.recommendations)) {
+      return {
+        isValid: false,
+        verdict: 'ERROR',
+        confidence: 0.0,
+        findings: [],
+        recommendations: [],
+        error: 'INVALID_RECOMMENDATIONS: "recommendations" must be an array.',
+        rawParsed: parsed,
+      };
+    }
+    for (const rec of parsed.recommendations) {
+      if (typeof rec === 'string' && rec.trim()) {
+        recommendations.push(rec.trim());
+      }
+    }
+  }
+
+  // 5. Invariant check: If reviewer claims APPROVED but includes CRITICAL or HIGH findings,
+  // that is a contradictory malformed response. Coerce to REJECTED.
+  const hasCritical = findings.some(f => f.severity === 'CRITICAL');
+  const hasHigh = findings.some(f => f.severity === 'HIGH');
+  let finalVerdict = rawVerdict;
+
+  if (rawVerdict === 'APPROVED' && (hasCritical || hasHigh)) {
+    finalVerdict = 'REJECTED';
+  }
+
+  return {
+    isValid: true,
+    verdict: finalVerdict,
+    confidence,
+    findings,
+    recommendations,
+    rawParsed: parsed,
+  };
+}
+
+module.exports = {
+  VALID_VERDICTS,
+  VALID_SEVERITIES,
+  normalizeSeverity,
+  validateFinding,
+  extractJsonPayload,
+  parseAndValidateReviewerOutput,
+};

package/src/execution/transaction_manager.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Phase 2B: Transaction Manager
+ * Implements a production-grade multi-file transaction engine (WAL) for Tribunal Kit.
+ * Lifecycle: PREPARE -> VALIDATE -> COMMIT / ROLLBACK
+ */
+class TransactionManager {
+  constructor(options = {}) {
+    this.workspace = options.workspace || process.cwd();
+    this.agentDir = options.agentDir || path.join(this.workspace, '.agent');
+    this.txDir = path.join(this.agentDir, 'transactions');
+    this.lockPath = path.join(this.txDir, 'tx.lock');
+    this.walPath = path.join(this.txDir, 'wal.json');
+    this.undoDir = path.join(this.txDir, 'undo');
+
+    this.activeTxId = null;
+    this.operations = []; // Array of { action: 'WRITE'|'DELETE', path, data, encoding }
+    this.state = 'IDLE';
+  }
+
+  _isLocked() {
+    return fs.existsSync(this.lockPath);
+  }
+
+  _isStaleLock() {
+    try {
+      const stats = fs.statSync(this.lockPath);
+      return Date.now() - stats.mtimeMs > 15000; // 15 seconds stale
+    } catch (e) {
+      return false;
+    }
+  }
+
+  _applyUndoLog() {
+    if (fs.existsSync(this.undoDir)) {
+      const mapPath = path.join(this.undoDir, 'mapping.json');
+      if (fs.existsSync(mapPath)) {
+        const mapping = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
+        for (const [realPath, backupName] of Object.entries(mapping)) {
+          const backupPath = path.join(this.undoDir, backupName);
+          if (backupName === '__DELETED__') {
+            if (fs.existsSync(realPath)) fs.unlinkSync(realPath);
+          } else if (fs.existsSync(backupPath)) {
+            fs.copyFileSync(backupPath, realPath);
+          }
+        }
+      }
+    }
+    // Clean up
+    fs.rmSync(this.undoDir, { recursive: true, force: true });
+    if (fs.existsSync(this.walPath)) fs.unlinkSync(this.walPath);
+  }
+
+  recover() {
+    if (this._isLocked()) {
+      if (this._isStaleLock()) {
+        // Stale lock detected, try recovering
+        if (fs.existsSync(this.walPath)) {
+          let wal;
+          try {
+            wal = JSON.parse(fs.readFileSync(this.walPath, 'utf8'));
+          } catch (e) {
+            wal = null;
+          }
+          if (wal && wal.state !== 'COMMITTED') {
+            this._applyUndoLog();
+          }
+        }
+        this._releaseLock();
+      } else {
+        throw new Error(
+          'Active transaction lock found. Cannot safely recover while another process holds the lock.',
+        );
+      }
+    }
+  }
+
+  begin() {
+    if (this.state !== 'IDLE' && this.state !== 'ROLLED_BACK') {
+      throw new Error('Transaction already active in memory.');
+    }
+    this.recover();
+
+    if (!fs.existsSync(this.txDir)) fs.mkdirSync(this.txDir, { recursive: true });
+
+    const maxRetries = 30;
+    let acquired = false;
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        const fd = fs.openSync(this.lockPath, 'wx');
+        fs.closeSync(fd);
+        acquired = true;
+        break;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        try {
+          const waitBuf = new Int32Array(new SharedArrayBuffer(4));
+          Atomics.wait(waitBuf, 0, 0, 30);
+        } catch (e) {} // fallback if Atomics unavailable or blocked
+      }
+    }
+
+    if (!acquired) {
+      if (this._isStaleLock()) {
+        this.recover();
+        const fd = fs.openSync(this.lockPath, 'wx');
+        fs.closeSync(fd);
+      } else {
+        throw new Error('Could not acquire concurrency lock for transaction.');
+      }
+    }
+
+    this.activeTxId = `TX-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    this.operations = [];
+    this.state = 'PREPARING';
+  }
+
+  prepareWrite(targetPath, data, encoding = 'utf8') {
+    if (this.state !== 'PREPARING')
+      throw new Error('Can only prepare operations in PREPARING state.');
+    const resolvedPath = path.resolve(this.workspace, targetPath);
+    if (!resolvedPath.startsWith(path.resolve(this.workspace))) {
+      throw new Error('Path security violation: Cannot modify files outside workspace.');
+    }
+    this.operations.push({ action: 'WRITE', path: resolvedPath, data, encoding });
+  }
+
+  prepareDelete(targetPath) {
+    if (this.state !== 'PREPARING')
+      throw new Error('Can only prepare operations in PREPARING state.');
+    const resolvedPath = path.resolve(this.workspace, targetPath);
+    if (!resolvedPath.startsWith(path.resolve(this.workspace))) {
+      throw new Error('Path security violation: Cannot modify files outside workspace.');
+    }
+    this.operations.push({ action: 'DELETE', path: resolvedPath });
+  }
+
+  validate() {
+    if (this.state !== 'PREPARING') throw new Error('Can only validate from PREPARING state.');
+    this.state = 'VALIDATING';
+
+    if (fs.existsSync(this.undoDir)) fs.rmSync(this.undoDir, { recursive: true, force: true });
+    fs.mkdirSync(this.undoDir, { recursive: true });
+
+    const mapping = {};
+    for (let i = 0; i < this.operations.length; i++) {
+      const op = this.operations[i];
+      if (fs.existsSync(op.path)) {
+        const backupName = `backup_${i}_${path.basename(op.path)}`;
+        const backupPath = path.join(this.undoDir, backupName);
+        fs.copyFileSync(op.path, backupPath);
+        mapping[op.path] = backupName;
+      } else {
+        mapping[op.path] = '__DELETED__';
+      }
+    }
+
+    fs.writeFileSync(
+      path.join(this.undoDir, 'mapping.json'),
+      JSON.stringify(mapping, null, 2),
+      'utf8',
+    );
+
+    const wal = {
+      id: this.activeTxId,
+      state: 'VALIDATED',
+      timestamp: new Date().toISOString(),
+      operations: this.operations.map(op => ({ action: op.action, path: op.path })),
+    };
+    fs.writeFileSync(this.walPath, JSON.stringify(wal, null, 2), 'utf8');
+  }
+
+  commit() {
+    if (this.state !== 'VALIDATING') throw new Error('Must validate before committing.');
+    this.state = 'COMMITTING';
+
+    try {
+      for (const op of this.operations) {
+        if (op.action === 'WRITE') {
+          const dir = path.dirname(op.path);
+          if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(op.path, op.data, op.encoding);
+        } else if (op.action === 'DELETE') {
+          if (fs.existsSync(op.path)) {
+            fs.unlinkSync(op.path);
+          }
+        }
+      }
+
+      const wal = JSON.parse(fs.readFileSync(this.walPath, 'utf8'));
+      wal.state = 'COMMITTED';
+      fs.writeFileSync(this.walPath, JSON.stringify(wal, null, 2), 'utf8');
+
+      fs.rmSync(this.undoDir, { recursive: true, force: true });
+      fs.unlinkSync(this.walPath);
+
+      this.state = 'IDLE';
+      this.activeTxId = null;
+      this.operations = [];
+      this._releaseLock();
+    } catch (err) {
+      this.rollback();
+      throw new Error(`Transaction failed during commit and was rolled back: ${err.message}`);
+    }
+  }
+
+  rollback() {
+    if (this.state === 'IDLE' || this.state === 'ROLLED_BACK') return;
+    this.state = 'ROLLING_BACK';
+
+    try {
+      this._applyUndoLog();
+    } catch (e) {
+      console.error(`CRITICAL: Rollback failed for TX ${this.activeTxId}`, e);
+    }
+
+    this.state = 'ROLLED_BACK';
+    this.activeTxId = null;
+    this.operations = [];
+    this._releaseLock();
+  }
+
+  _releaseLock() {
+    try {
+      if (fs.existsSync(this.lockPath)) {
+        fs.unlinkSync(this.lockPath);
+      }
+    } catch (_) {}
+  }
+}
+
+module.exports = TransactionManager;

package/src/execution/validation_runner.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+const path = require('path');
+
+const VALIDATION_REGISTRY = {
+  unit_tests: {
+    command: 'npm',
+    args: ['run', 'test'],
+    timeout: 120000,
+    riskLevel: 'LOW',
+    parser: 'jest',
+  },
+  lint: {
+    command: 'npm',
+    args: ['run', 'lint'],
+    timeout: 60000,
+    riskLevel: 'LOW',
+    parser: 'eslint',
+  },
+};
+
+class TestResultParser {
+  static parse(output, parserType) {
+    const result = {
+      testsPassed: 0,
+      testsFailed: 0,
+      testsSkipped: 0,
+      failedTestNames: [],
+      suiteCount: 0,
+    };
+
+    if (parserType === 'jest') {
+      // Basic heuristic parsing for standard Jest output
+      // Note: A real implementation might use jest --json, but we parse text here as fallback
+      const matchPass = output.match(/Tests:\s+(\d+)\s+passed/);
+      if (matchPass) result.testsPassed = parseInt(matchPass[1], 10);
+
+      const matchFail = output.match(/Tests:\s+(\d+)\s+failed/);
+      if (matchFail) result.testsFailed = parseInt(matchFail[1], 10);
+
+      const matchTotal = output.match(/Tests:\s+(.*?)(?:,|$)/);
+      if (matchTotal && !matchPass && !matchFail) {
+        // Fallback logic
+      }
+
+      const suiteMatch = output.match(/Test Suites:\s+(\d+)\s+passed/);
+      if (suiteMatch) result.suiteCount = parseInt(suiteMatch[1], 10);
+
+      // Attempt to extract failed test names
+      const fails = [...output.matchAll(/FAIL\s+(.*)/g)];
+      result.failedTestNames = fails.map(f => f[1].trim());
+    }
+
+    return result;
+  }
+}
+
+class ValidationRunner {
+  constructor(options = {}) {
+    this.workspaceRoot = options.workspaceRoot || process.cwd();
+    // Security: Only allow specific benign environment variables
+    this.allowedEnv = {
+      PATH: process.env.PATH,
+      NODE_ENV: 'test',
+      CI: 'true',
+    };
+  }
+
+  async run(validationId, customArgs = []) {
+    const config = VALIDATION_REGISTRY[validationId];
+    if (!config) {
+      return this._failClosed(`Unknown validation ID: ${validationId}`);
+    }
+
+    const start = Date.now();
+    const commandFingerprint = crypto
+      .createHash('sha256')
+      .update(`${config.command} ${config.args.join(' ')}`)
+      .digest('hex');
+
+    return new Promise(resolve => {
+      let stdout = '';
+      let stderr = '';
+      const MAX_BUFFER = 1024 * 1024 * 5; // 5MB
+
+      // Enforce Workspace Boundary
+      const runDir = path.resolve(this.workspaceRoot);
+      const systemRoot = path.resolve(process.cwd());
+      if (!runDir.startsWith(systemRoot)) {
+        return resolve(this._failClosed('Path traversal detected in workspace root.'));
+      }
+
+      const args = [...config.args, ...customArgs];
+
+      // We explicitly avoid shell: true to prevent injection
+      const proc = spawn(config.command, args, {
+        cwd: runDir,
+        env: this.allowedEnv,
+        shell: false,
+        detached: false,
+      });
+
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill('SIGKILL');
+      }, config.timeout);
+
+      proc.stdout.on('data', data => {
+        if (stdout.length < MAX_BUFFER) stdout += data.toString();
+      });
+
+      proc.stderr.on('data', data => {
+        if (stderr.length < MAX_BUFFER) stderr += data.toString();
+      });
+
+      proc.on('close', code => {
+        clearTimeout(timer);
+        const duration = Date.now() - start;
+
+        let status = 'PASSED';
+        if (timedOut) status = 'TIMEOUT';
+        else if (code !== 0) status = 'FAILED';
+
+        const parsed = TestResultParser.parse(stdout + '\n' + stderr, config.parser);
+
+        resolve({
+          validationId,
+          status,
+          exitCode: code,
+          duration,
+          stdout: stdout.substring(0, 10000), // Trim for payload size
+          stderr: stderr.substring(0, 10000),
+          testsPassed: parsed.testsPassed,
+          testsFailed: parsed.testsFailed,
+          testsSkipped: parsed.testsSkipped,
+          startedAt: new Date(start).toISOString(),
+          completedAt: new Date().toISOString(),
+          commandFingerprint,
+          repositoryFingerprint: 'repo-hash-placeholder',
+        });
+      });
+
+      proc.on('error', err => {
+        clearTimeout(timer);
+        resolve(
+          this._failClosed(`Process crash: ${err.message}`, validationId, commandFingerprint),
+        );
+      });
+    });
+  }
+
+  _failClosed(reason, validationId = 'UNKNOWN', fingerprint = 'UNKNOWN') {
+    return {
+      validationId,
+      status: 'CRASHED',
+      exitCode: -1,
+      duration: 0,
+      stdout: '',
+      stderr: reason,
+      testsPassed: 0,
+      testsFailed: 1, // Treat structural failure as a failed test
+      testsSkipped: 0,
+      startedAt: new Date().toISOString(),
+      completedAt: new Date().toISOString(),
+      commandFingerprint: fingerprint,
+      repositoryFingerprint: 'UNKNOWN',
+    };
+  }
+}
+
+module.exports = { ValidationRunner, TestResultParser, VALIDATION_REGISTRY };