vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/ship-gate.js

@@ -0,0 +1,832 @@
+/**
+ * Ship Gate - The Final Arbiter
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ONE VERDICT: SHIP / WARN / BLOCK - BACKED BY EVIDENCE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * The Ship Gate orchestrates three verification layers:
+ * 
+ *   1. AUDIT    - Static analysis findings (truthpack, analyzers)
+ *   2. REALITY  - Runtime verification (browser testing)
+ *   3. SHIELD   - Agent firewall status (intent enforcement)
+ * 
+ * Each layer contributes evidence. The gate combines them into a final verdict.
+ * 
+ * Key guarantees:
+ * - DETERMINISTIC: Same repo state → same verdict
+ * - EVIDENCE-BACKED: Every verdict has a "why tree"
+ * - CI-READY: Exit codes, receipts, badges
+ * 
+ * @module ship-gate
+ * @version 1.1.0 - Hardened
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ERROR TYPES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+class GateError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = "GateError";
+    this.code = code;
+    this.details = details;
+    this.recoverable = true;
+  }
+}
+
+class ConfigurationError extends GateError {
+  constructor(message, field) {
+    super(message, "CONFIG_ERROR", { field });
+    this.name = "ConfigurationError";
+  }
+}
+
+class EvaluationError extends GateError {
+  constructor(message, phase, cause) {
+    super(message, "EVAL_ERROR", { phase, cause: cause?.message });
+    this.name = "EvaluationError";
+    this.cause = cause;
+  }
+}
+
+// Lazy imports for performance
+let _shipManifest = null;
+let _verdictEngine = null;
+let _truth = null;
+let _analyzers = null;
+
+function getShipManifest() {
+  if (!_shipManifest) {
+    _shipManifest = require("./ship-manifest");
+  }
+  return _shipManifest;
+}
+
+function getVerdictEngine() {
+  if (!_verdictEngine) {
+    _verdictEngine = require("./verdict-engine");
+  }
+  return _verdictEngine;
+}
+
+function getTruth() {
+  if (!_truth) {
+    _truth = require("./truth");
+  }
+  return _truth;
+}
+
+function getAnalyzers() {
+  if (!_analyzers) {
+    _analyzers = require("./analyzers");
+  }
+  return _analyzers;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// GATE CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const DEFAULT_CONFIG = {
+  // Verdict rules
+  blockOn: {
+    auditBlockers: true,       // Block if audit finds BLOCK-severity issues
+    realityFailures: true,     // Block if reality tests fail
+    shieldViolations: false,   // Block if shield has violations (default: warn only)
+    dirtyWorkingTree: false,   // Block if git working tree is dirty
+    coverageThreshold: 0,      // Block if route coverage below this %
+  },
+  
+  // Warn rules
+  warnOn: {
+    auditWarnings: true,       // Warn on WARN-severity issues
+    staletruthpack: true,      // Warn if truthpack is stale (>1hr old)
+    noReality: true,           // Warn if no reality tests ran
+    observeMode: true,         // Warn if shield is in observe mode
+  },
+  
+  // Strict mode (warnings become blockers)
+  strict: false,
+  
+  // Score calculation
+  scoring: {
+    baseScore: 100,
+    blockerPenalty: 15,
+    warningPenalty: 5,
+    infoPenalty: 1,
+    realityBonus: 10,          // Bonus for passing reality tests
+    shieldBonus: 5,            // Bonus for shield in enforce mode
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SHIP GATE ORCHESTRATOR
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * ShipGate - The orchestrator class
+ * 
+ * Usage:
+ *   const gate = new ShipGate(repoRoot, config);
+ *   const result = await gate.evaluate();
+ *   // result.verdict === "SHIP" | "WARN" | "BLOCK"
+ */
+class ShipGate {
+  /**
+   * Create a new ShipGate instance.
+   * 
+   * @param {string} repoRoot - Repository root path
+   * @param {Object} config - Gate configuration
+   * @throws {ConfigurationError} If configuration is invalid
+   */
+  constructor(repoRoot, config = {}) {
+    // Validate and set repo root
+    this.repoRoot = this._validateRepoRoot(repoRoot);
+    
+    // Merge and validate config
+    this.config = this._validateConfig({ ...DEFAULT_CONFIG, ...config });
+    
+    // Timing
+    this.startTime = Date.now();
+    this.timeoutMs = 5 * 60 * 1000; // 5 minute timeout
+    
+    // Evidence collectors
+    this.evidence = {
+      audit: null,
+      reality: null,
+      shield: null,
+    };
+    
+    // Findings from all sources
+    this.findings = [];
+    
+    // Verdict tracking
+    this.blockReasons = [];
+    this.warnReasons = [];
+    this.passReasons = [];
+    
+    // Error tracking
+    this.errors = [];
+    this.warnings = [];
+  }
+
+  /**
+   * Validate repository root path
+   * @private
+   */
+  _validateRepoRoot(repoRoot) {
+    const root = repoRoot || process.cwd();
+    
+    if (typeof root !== "string" || !root.trim()) {
+      throw new ConfigurationError("repoRoot must be a non-empty string", "repoRoot");
+    }
+
+    // Prevent null byte injection
+    if (root.includes("\0")) {
+      throw new ConfigurationError("repoRoot contains invalid characters", "repoRoot");
+    }
+
+    const resolved = path.resolve(root);
+
+    // Check if directory exists
+    try {
+      const stats = fs.statSync(resolved);
+      if (!stats.isDirectory()) {
+        throw new ConfigurationError(`repoRoot is not a directory: ${resolved}`, "repoRoot");
+      }
+    } catch (err) {
+      if (err instanceof ConfigurationError) throw err;
+      throw new ConfigurationError(`repoRoot does not exist: ${resolved}`, "repoRoot");
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Validate gate configuration
+   * @private
+   */
+  _validateConfig(config) {
+    if (!config || typeof config !== "object") {
+      return { ...DEFAULT_CONFIG };
+    }
+
+    // Ensure nested objects exist
+    const validated = {
+      blockOn: { ...DEFAULT_CONFIG.blockOn, ...(config.blockOn || {}) },
+      warnOn: { ...DEFAULT_CONFIG.warnOn, ...(config.warnOn || {}) },
+      strict: Boolean(config.strict),
+      scoring: { ...DEFAULT_CONFIG.scoring, ...(config.scoring || {}) },
+    };
+
+    // Validate scoring values are numbers
+    for (const [key, value] of Object.entries(validated.scoring)) {
+      validated.scoring[key] = Math.max(0, Number(value) || 0);
+    }
+
+    return validated;
+  }
+
+  /**
+   * Check if gate has timed out
+   * @private
+   */
+  _checkTimeout() {
+    if (Date.now() - this.startTime > this.timeoutMs) {
+      throw new EvaluationError(
+        `Gate evaluation timed out after ${Math.round(this.timeoutMs / 1000)}s`,
+        "timeout"
+      );
+    }
+  }
+
+  /**
+   * Safe wrapper for async operations
+   * @private
+   */
+  async _safeAsync(fn, phase, fallback = null) {
+    try {
+      this._checkTimeout();
+      return await fn();
+    } catch (err) {
+      this.errors.push({
+        phase,
+        message: err.message,
+        code: err.code,
+      });
+      
+      if (process.env.DEBUG || process.env.VIBECHECK_DEBUG) {
+        console.error(`[ShipGate] ${phase} failed:`, err.message);
+      }
+      
+      return fallback;
+    }
+  }
+
+  /**
+   * Run the full gate evaluation.
+   * 
+   * @param {Object} options - Evaluation options
+   * @returns {Object} Gate result with verdict, evidence, manifest
+   * @throws {EvaluationError} If evaluation fails critically
+   */
+  async evaluate(options = {}) {
+    const safeOptions = options || {};
+    const {
+      skipAudit = false,
+      skipReality = false,
+      skipShield = false,
+      truthpack = null,
+      realityReport = null,
+      shieldStatus = null,
+    } = safeOptions;
+
+    try {
+      // Phase 1: Collect evidence from each layer
+      if (!skipAudit) {
+        this.evidence.audit = truthpack || await this._safeAsync(
+          () => this.collectAuditEvidence(),
+          "audit",
+          null
+        );
+      }
+
+      if (!skipReality) {
+        this.evidence.reality = realityReport || await this._safeAsync(
+          () => Promise.resolve(this.loadRealityEvidence()),
+          "reality",
+          null
+        );
+      }
+
+      if (!skipShield) {
+        this.evidence.shield = shieldStatus || await this._safeAsync(
+          () => Promise.resolve(this.loadShieldEvidence()),
+          "shield",
+          null
+        );
+      }
+
+      // Phase 2: Run analyzers and collect findings
+      await this._safeAsync(
+        () => this.collectFindings(),
+        "analyzers"
+      );
+
+      // Phase 3: Compute verdict
+      const verdict = this.computeVerdict();
+
+      // Phase 4: Calculate score
+      const score = this.calculateScore(verdict);
+
+      // Phase 5: Generate manifest
+      const shipManifest = getShipManifest();
+      if (!shipManifest) {
+        throw new EvaluationError("Ship manifest module not available", "manifest");
+      }
+      
+      const { generateShipManifest, writeShipManifest } = shipManifest;
+      
+      let manifest;
+      try {
+        manifest = generateShipManifest({
+          repoRoot: this.repoRoot,
+          verdict,
+          score,
+          findings: this.findings,
+          truthpack: this.evidence.audit,
+          realityReport: this.evidence.reality,
+          shieldStatus: this.evidence.shield,
+          durationMs: Date.now() - this.startTime,
+        });
+      } catch (err) {
+        throw new EvaluationError(`Manifest generation failed: ${err.message}`, "manifest", err);
+      }
+
+      // Phase 6: Write artifacts (non-fatal if fails)
+      let artifactPaths = {};
+      try {
+        artifactPaths = writeShipManifest(this.repoRoot, manifest);
+      } catch (err) {
+        this.errors.push({
+          phase: "artifacts",
+          message: err.message,
+        });
+        // Continue without failing - verdict is still valid
+        artifactPaths = {
+          manifest: null,
+          receipt: null,
+          githubOutput: null,
+        };
+      }
+
+      return this._buildResult(verdict, score, manifest, artifactPaths);
+      
+    } catch (err) {
+      // If we get here, something critical failed
+      // Return a BLOCK verdict with error info
+      if (err instanceof GateError) {
+        throw err;
+      }
+      
+      throw new EvaluationError(
+        `Gate evaluation failed: ${err.message}`,
+        "unknown",
+        err
+      );
+    }
+  }
+
+  /**
+   * Build the final result object
+   * @private
+   */
+  _buildResult(verdict, score, manifest, artifactPaths) {
+    const blockerCount = this.findings.filter(f => f.severity === "BLOCK").length;
+    const warningCount = this.findings.filter(f => f.severity === "WARN").length;
+
+    return {
+      // Core verdict
+      verdict,
+      score,
+      canShip: verdict === "SHIP",
+      exitCode: manifest?.verdict?.exitCode ?? 2,
+      
+      // Evidence summary
+      evidence: {
+        audit: {
+          ran: this.evidence.audit !== null,
+          findings: this.findings.length,
+          blockers: blockerCount,
+          warnings: warningCount,
+        },
+        reality: {
+          ran: this.evidence.reality !== null,
+          actions: Math.max(0, this.evidence.reality?.actions?.length || 0),
+          requests: Math.max(0, this.evidence.reality?.requests?.length || 0),
+        },
+        shield: {
+          ran: this.evidence.shield !== null,
+          mode: this.evidence.shield?.mode || "unknown",
+          enforcing: this.evidence.shield?.mode === "enforce",
+        },
+      },
+      
+      // Why tree (top 3 blockers/warnings)
+      whyTree: manifest?.evidence?.whyTree || {
+        summary: blockerCount > 0 ? `${blockerCount} blocker(s)` : "Unknown",
+        topIssues: [],
+        fixMissions: [],
+      },
+      
+      // Full findings (limited)
+      findings: this.findings.slice(0, 100),
+      
+      // Errors encountered during evaluation
+      errors: this.errors.length > 0 ? this.errors : undefined,
+      
+      // Manifest and artifacts
+      manifest,
+      artifactPaths,
+      
+      // Timing
+      durationMs: Date.now() - this.startTime,
+    };
+  }
+
+  /**
+   * Collect audit evidence (truthpack and findings)
+   */
+  async collectAuditEvidence() {
+    const { buildTruthpackSmart, detectFastifyEntry } = getTruth();
+    
+    try {
+      const fastifyEntry = detectFastifyEntry(this.repoRoot);
+      const truthpack = await buildTruthpackSmart({
+        repoRoot: this.repoRoot,
+        fastifyEntry,
+      });
+      
+      return truthpack;
+    } catch (err) {
+      this.warnReasons.push(`Truthpack generation failed: ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Load reality evidence from disk
+   */
+  loadRealityEvidence() {
+    const realityPath = path.join(this.repoRoot, ".vibecheck", "reality", "last_reality.json");
+    
+    if (!fs.existsSync(realityPath)) {
+      if (this.config.warnOn.noReality) {
+        this.warnReasons.push("No reality tests found. Run 'vibecheck reality' for runtime verification.");
+      }
+      return null;
+    }
+
+    try {
+      const report = JSON.parse(fs.readFileSync(realityPath, "utf8"));
+      
+      // Check freshness (warn if older than 1 hour)
+      const age = Date.now() - new Date(report.meta?.timestamp || 0).getTime();
+      if (age > 3600000 && this.config.warnOn.staletruthpack) {
+        this.warnReasons.push("Reality report is older than 1 hour. Consider re-running 'vibecheck reality'.");
+      }
+      
+      return report;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Load shield evidence from disk
+   */
+  loadShieldEvidence() {
+    const policyPath = path.join(this.repoRoot, ".vibecheck", "policy.json");
+    const statusPath = path.join(this.repoRoot, ".vibecheck", "shield-status.json");
+    
+    let status = {
+      mode: "observe",
+      locked: false,
+      installed: false,
+    };
+
+    // Load policy
+    if (fs.existsSync(policyPath)) {
+      try {
+        const policy = JSON.parse(fs.readFileSync(policyPath, "utf8"));
+        status.mode = policy.mode || "observe";
+      } catch {
+        // Use defaults
+      }
+    }
+
+    // Load status
+    if (fs.existsSync(statusPath)) {
+      try {
+        const savedStatus = JSON.parse(fs.readFileSync(statusPath, "utf8"));
+        status = { ...status, ...savedStatus };
+      } catch {
+        // Use defaults
+      }
+    }
+
+    // Check for observe mode warning
+    if (status.mode === "observe" && this.config.warnOn.observeMode) {
+      this.warnReasons.push("Shield is in OBSERVE mode. Run 'vibecheck shield enforce' for full protection.");
+    }
+
+    return status;
+  }
+
+  /**
+   * Collect findings from all analyzers with timeout and error handling
+   */
+  async collectFindings() {
+    const truthpack = this.evidence.audit;
+    const allFindings = [];
+
+    // Get analyzers module
+    const analyzers = getAnalyzers();
+    if (!analyzers) {
+      this.warnings.push("Analyzers module not available");
+      this.findings = [];
+      return;
+    }
+
+    // Define analyzer functions with safety wrappers
+    const safeAnalyzer = (fn, name) => async () => {
+      try {
+        this._checkTimeout();
+        const result = fn();
+        return Array.isArray(result) ? result : [];
+      } catch (err) {
+        this.errors.push({
+          phase: `analyzer:${name}`,
+          message: err.message,
+        });
+        return [];
+      }
+    };
+
+    // Build analyzer list based on what's available
+    const analyzerList = [];
+
+    // Truthpack-based analyzers (only if truthpack available)
+    if (truthpack) {
+      if (analyzers.findMissingRoutes) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findMissingRoutes(truthpack), "missingRoutes"));
+      }
+      if (analyzers.findEnvGaps) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findEnvGaps(truthpack), "envGaps"));
+      }
+      if (analyzers.findGhostAuth) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findGhostAuth(truthpack, this.repoRoot), "ghostAuth"));
+      }
+      if (analyzers.findStripeWebhookViolations) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findStripeWebhookViolations(truthpack), "stripeWebhook"));
+      }
+      if (analyzers.findPaidSurfaceNotEnforced) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findPaidSurfaceNotEnforced(truthpack), "paidSurface"));
+      }
+      if (analyzers.findMethodMismatch) {
+        analyzerList.push(safeAnalyzer(() => analyzers.findMethodMismatch(truthpack), "methodMismatch"));
+      }
+    }
+    
+    // File-based analyzers (always run)
+    if (analyzers.findFakeSuccess) {
+      analyzerList.push(safeAnalyzer(() => analyzers.findFakeSuccess(this.repoRoot), "fakeSuccess"));
+    }
+    if (analyzers.findOptimisticNoRollback) {
+      analyzerList.push(safeAnalyzer(() => analyzers.findOptimisticNoRollback(this.repoRoot), "optimisticNoRollback"));
+    }
+    if (analyzers.findSilentCatch) {
+      analyzerList.push(safeAnalyzer(() => analyzers.findSilentCatch(this.repoRoot), "silentCatch"));
+    }
+    if (analyzers.findDeadUI) {
+      analyzerList.push(safeAnalyzer(() => analyzers.findDeadUI(this.repoRoot), "deadUI"));
+    }
+    if (analyzers.findOwnerModeBypass) {
+      analyzerList.push(safeAnalyzer(() => analyzers.findOwnerModeBypass(this.repoRoot), "ownerModeBypass"));
+    }
+
+    // Run analyzers with Promise.allSettled to handle individual failures
+    if (analyzerList.length > 0) {
+      const results = await Promise.allSettled(analyzerList.map(fn => fn()));
+      
+      for (const result of results) {
+        if (result.status === "fulfilled" && Array.isArray(result.value)) {
+          allFindings.push(...result.value);
+        }
+      }
+    }
+
+    // Add reality findings if available
+    if (this.evidence.reality) {
+      try {
+        const { findingsFromReality } = require("./reality-findings");
+        if (typeof findingsFromReality === "function") {
+          const realityFindings = findingsFromReality(this.repoRoot);
+          if (Array.isArray(realityFindings)) {
+            allFindings.push(...realityFindings);
+          }
+        }
+      } catch {
+        // Reality findings module not available - not an error
+      }
+    }
+
+    // Deduplicate, validate, and store
+    this.findings = this.deduplicateFindings(allFindings)
+      .filter(f => f && typeof f === "object")
+      .slice(0, 1000); // Limit total findings
+  }
+
+  /**
+   * Deduplicate findings by fingerprint
+   */
+  deduplicateFindings(findings) {
+    const seen = new Set();
+    const deduped = [];
+
+    for (const f of findings) {
+      const key = f.fingerprint || `${f.category}:${f.title}:${f.evidence?.[0]?.file}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        deduped.push(f);
+      }
+    }
+
+    return deduped;
+  }
+
+  /**
+   * Compute final verdict from all evidence
+   */
+  computeVerdict() {
+    const { blockOn, warnOn, strict } = this.config;
+
+    // Count findings by severity
+    const blockers = this.findings.filter(f => f.severity === "BLOCK");
+    const warnings = this.findings.filter(f => f.severity === "WARN");
+
+    // Check block conditions
+    if (blockOn.auditBlockers && blockers.length > 0) {
+      this.blockReasons.push(...blockers.map(b => b.title || b.message));
+    }
+
+    if (blockOn.realityFailures && this.evidence.reality?.failures?.length > 0) {
+      this.blockReasons.push(...this.evidence.reality.failures.map(f => `Reality: ${f}`));
+    }
+
+    if (blockOn.shieldViolations && this.evidence.shield?.violations?.length > 0) {
+      this.blockReasons.push(...this.evidence.shield.violations.map(v => `Shield: ${v}`));
+    }
+
+    // Check repo state
+    const { generateRepoFingerprint } = getShipManifest();
+    const repoFP = generateRepoFingerprint(this.repoRoot);
+    
+    if (blockOn.dirtyWorkingTree && repoFP.isDirty) {
+      this.blockReasons.push("Working tree has uncommitted changes");
+    }
+
+    // Check warn conditions
+    if (warnOn.auditWarnings && warnings.length > 0) {
+      this.warnReasons.push(...warnings.slice(0, 5).map(w => w.title || w.message));
+    }
+
+    // Apply strict mode
+    if (strict && this.warnReasons.length > 0) {
+      this.blockReasons.push("Strict mode: warnings treated as blockers");
+      this.blockReasons.push(...this.warnReasons);
+    }
+
+    // Determine verdict
+    if (this.blockReasons.length > 0) {
+      return "BLOCK";
+    }
+
+    if (this.warnReasons.length > 0) {
+      return "WARN";
+    }
+
+    this.passReasons.push("All checks passed");
+    return "SHIP";
+  }
+
+  /**
+   * Calculate score based on findings and bonuses
+   */
+  calculateScore(verdict) {
+    const { scoring } = this.config;
+    let score = scoring.baseScore;
+
+    // Apply penalties
+    for (const f of this.findings) {
+      switch (f.severity) {
+        case "BLOCK":
+          score -= scoring.blockerPenalty;
+          break;
+        case "WARN":
+          score -= scoring.warningPenalty;
+          break;
+        case "INFO":
+          score -= scoring.infoPenalty;
+          break;
+      }
+    }
+
+    // Apply bonuses
+    if (this.evidence.reality && !this.evidence.reality.failures?.length) {
+      score += scoring.realityBonus;
+    }
+
+    if (this.evidence.shield?.mode === "enforce") {
+      score += scoring.shieldBonus;
+    }
+
+    // Clamp to 0-100
+    return Math.max(0, Math.min(100, score));
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// QUICK GATE FUNCTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Quick gate evaluation (one-liner API)
+ * 
+ * @param {Object} options - Gate options
+ * @returns {Object} Gate result
+ */
+async function evaluateShipGate(options = {}) {
+  const {
+    repoRoot = process.cwd(),
+    strict = false,
+    ...rest
+  } = options;
+
+  const gate = new ShipGate(repoRoot, { strict });
+  return gate.evaluate(rest);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CACHING SYSTEM
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if we can use a cached verdict.
+ * Cache is valid if repo fingerprint hasn't changed.
+ */
+function checkVerdictCache(repoRoot) {
+  const { loadShipManifest, generateRepoFingerprint } = getShipManifest();
+  
+  const cached = loadShipManifest(repoRoot);
+  if (!cached) {
+    return { valid: false, reason: "No cached manifest" };
+  }
+
+  const currentFP = generateRepoFingerprint(repoRoot);
+  
+  if (cached.repo.fingerprint !== currentFP.fingerprint) {
+    return { 
+      valid: false, 
+      reason: "Repo state changed",
+      cached: cached.repo.fingerprint,
+      current: currentFP.fingerprint,
+    };
+  }
+
+  // Check age (default max: 1 hour)
+  const age = Date.now() - new Date(cached.meta.generatedAt).getTime();
+  if (age > 3600000) {
+    return {
+      valid: false,
+      reason: "Cache expired (>1 hour old)",
+      age,
+    };
+  }
+
+  return {
+    valid: true,
+    manifest: cached,
+    age,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Main class
+  ShipGate,
+  
+  // Quick function
+  evaluateShipGate,
+  
+  // Caching
+  checkVerdictCache,
+  
+  // Configuration
+  DEFAULT_CONFIG,
+  
+  // Error classes
+  GateError,
+  ConfigurationError,
+  EvaluationError,
+};