@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/quality-gate.cjs

@@ -0,0 +1,332 @@
+/**
+ * Quality Gate Coordinator
+ *
+ * Central registry and execution engine for quality gates.
+ * Supports gate registration, execution, bypass with audit trail, and status reporting.
+ * Uses Zod for schema validation of gate inputs/outputs.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { z } = require('zod');
+
+/**
+ * Get the audit trail file path (computed at runtime to support cwd changes)
+ * @returns {string}
+ */
+function getAuditFilePath() {
+  return path.join(process.cwd(), '.planning', 'gate-audit.json');
+}
+
+/**
+ * @typedef {Object} GateDefinition
+ * @property {string} id - Gate identifier
+ * @property {z.ZodSchema} schema - Zod schema for context validation
+ * @property {Function} executor - Gate execution function
+ */
+
+/**
+ * @typedef {Object} GateStatus
+ * @property {'registered' | 'passed' | 'failed' | 'bypassed'} state - Current gate state
+ * @property {string} [id] - Gate identifier
+ * @property {Date} [registeredAt] - Registration timestamp
+ * @property {Date} [executedAt] - Execution timestamp
+ * @property {Date} [bypassedAt] - Bypass timestamp
+ * @property {string} [bypassReason] - Reason for bypass
+ * @property {Array} [errors] - Errors from last execution
+ * @property {Array} [warnings] - Warnings from last execution
+ */
+
+/**
+ * @typedef {Object} ExecutionResult
+ * @property {boolean} passed - Whether the gate passed
+ * @property {Array<{path: string, message: string}>} [errors] - Validation or execution errors
+ * @property {Array<string>} [warnings] - Warnings
+ */
+
+/**
+ * @typedef {Object} AuditEntry
+ * @property {string} gateId - Gate identifier
+ * @property {'bypass'} action - Action type
+ * @property {string} reason - Reason for bypass
+ * @property {string} timestamp - ISO timestamp
+ */
+
+class QualityGate {
+  /**
+   * @type {Map<string, GateDefinition>}
+   */
+  #gates;
+
+  /**
+   * @type {Map<string, GateStatus>}
+   */
+  #status;
+
+  /**
+   * @type {Array<AuditEntry>}
+   */
+  #auditTrail;
+
+  constructor() {
+    this.#gates = new Map();
+    this.#status = new Map();
+    this.#auditTrail = this.#loadAuditTrail();
+  }
+
+  /**
+   * Load audit trail from file
+   * @returns {Array<AuditEntry>}
+   */
+  #loadAuditTrail() {
+    const auditFilePath = getAuditFilePath();
+    try {
+      if (fs.existsSync(auditFilePath)) {
+        const content = fs.readFileSync(auditFilePath, 'utf-8');
+        return JSON.parse(content);
+      }
+    } catch (err) {
+      // If file is corrupted or unreadable, start fresh
+      console.warn('Warning: Could not load gate audit trail, starting fresh');
+    }
+    return [];
+  }
+
+  /**
+   * Save audit trail to file
+   */
+  #saveAuditTrail() {
+    const auditFilePath = getAuditFilePath();
+    try {
+      const dir = path.dirname(auditFilePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(auditFilePath, JSON.stringify(this.#auditTrail, null, 2), 'utf-8');
+    } catch (err) {
+      console.error('Error saving gate audit trail:', err.message);
+    }
+  }
+
+  /**
+   * Format Zod validation errors into structured array with field paths
+   * @param {z.ZodError} zodError
+   * @returns {Array<{path: string, message: string}>}
+   */
+  #formatValidationErrors(zodError) {
+    const errors = [];
+    for (const issue of zodError.errors) {
+      const fieldPath = issue.path.join('.');
+      errors.push({
+        path: fieldPath || 'root',
+        message: issue.message,
+      });
+    }
+    return errors;
+  }
+
+  /**
+   * Register a quality gate
+   * @param {string} id - Unique gate identifier
+   * @param {z.ZodSchema} schema - Zod schema for context validation
+   * @param {Function} executor - Async function that executes the gate logic
+   * @returns {void}
+   */
+  registerGate(id, schema, executor) {
+    if (!id || typeof id !== 'string') {
+      throw new Error('Gate ID must be a non-empty string');
+    }
+
+    if (!schema || !schema.safeParse) {
+      throw new Error('Schema must be a valid Zod schema');
+    }
+
+    if (typeof executor !== 'function') {
+      throw new Error('Executor must be a function');
+    }
+
+    this.#gates.set(id, { id, schema, executor });
+    this.#status.set(id, {
+      state: 'registered',
+      id,
+      registeredAt: new Date(),
+    });
+  }
+
+  /**
+   * Execute a quality gate
+   * @param {string} id - Gate identifier
+   * @param {any} context - Context data to validate and pass to executor
+   * @returns {Promise<ExecutionResult>}
+   */
+  async executeGate(id, context) {
+    const gate = this.#gates.get(id);
+
+    if (!gate) {
+      throw new Error(`Gate not registered: ${id}`);
+    }
+
+    // Validate context against schema
+    const parseResult = gate.schema.safeParse(context);
+
+    if (!parseResult.success) {
+      const errors = this.#formatValidationErrors(parseResult.error);
+      const status = {
+        ...this.#status.get(id),
+        state: 'failed',
+        executedAt: new Date(),
+        errors,
+      };
+      this.#status.set(id, status);
+      return { passed: false, errors, warnings: [] };
+    }
+
+    // Run executor with validated context
+    try {
+      const result = await gate.executor(parseResult.data);
+
+      // Handle executor result
+      if (result.passed) {
+        const status = {
+          ...this.#status.get(id),
+          state: 'passed',
+          executedAt: new Date(),
+          errors: [],
+          warnings: result.warnings || [],
+        };
+        this.#status.set(id, status);
+        return { passed: true, errors: [], warnings: result.warnings || [] };
+      } else {
+        const errors = result.errors || [{ path: 'executor', message: 'Gate execution failed' }];
+        const status = {
+          ...this.#status.get(id),
+          state: 'failed',
+          executedAt: new Date(),
+          errors,
+          warnings: result.warnings || [],
+        };
+        this.#status.set(id, status);
+        return { passed: false, errors, warnings: result.warnings || [] };
+      }
+    } catch (err) {
+      const errors = [{ path: 'executor', message: err.message || 'Executor threw an exception' }];
+      const status = {
+        ...this.#status.get(id),
+        state: 'failed',
+        executedAt: new Date(),
+        errors,
+      };
+      this.#status.set(id, status);
+      return { passed: false, errors, warnings: [] };
+    }
+  }
+
+  /**
+   * Bypass a quality gate with mandatory audit reason
+   * @param {string} id - Gate identifier
+   * @param {string} reason - Reason for bypass (cannot be empty)
+   * @returns {void}
+   */
+  bypassGate(id, reason) {
+    const gate = this.#gates.get(id);
+
+    if (!gate) {
+      throw new Error(`Gate not registered: ${id}`);
+    }
+
+    if (!reason || typeof reason !== 'string' || reason.trim() === '') {
+      throw new Error('Bypass reason must be a non-empty string');
+    }
+
+    const status = {
+      ...this.#status.get(id),
+      state: 'bypassed',
+      bypassedAt: new Date(),
+      bypassReason: reason.trim(),
+    };
+    this.#status.set(id, status);
+
+    // Log to audit trail
+    const auditEntry = {
+      gateId: id,
+      action: 'bypass',
+      reason: reason.trim(),
+      timestamp: new Date().toISOString(),
+    };
+    this.#auditTrail.push(auditEntry);
+    this.#saveAuditTrail();
+  }
+
+  /**
+   * Get the current status of a gate
+   * @param {string} id - Gate identifier
+   * @returns {GateStatus}
+   */
+  getGateStatus(id) {
+    const status = this.#status.get(id);
+
+    if (!status) {
+      throw new Error(`Gate not registered: ${id}`);
+    }
+
+    return { ...status };
+  }
+
+  /**
+   * Get all registered gate IDs
+   * @returns {Array<string>}
+   */
+  getRegisteredGates() {
+    return Array.from(this.#gates.keys());
+  }
+
+  /**
+   * Get the audit trail
+   * @returns {Array<AuditEntry>}
+   */
+  getAuditTrail() {
+    return [...this.#auditTrail];
+  }
+
+  /**
+   * Check if a gate is registered
+   * @param {string} id - Gate identifier
+   * @returns {boolean}
+   */
+  isRegistered(id) {
+    return this.#gates.has(id);
+  }
+
+  /**
+   * Reset gate status (for testing)
+   * @param {string} id - Gate identifier
+   * @returns {void}
+   */
+  resetGate(id) {
+    const gate = this.#gates.get(id);
+    if (gate) {
+      this.#status.set(id, {
+        state: 'registered',
+        id,
+        registeredAt: new Date(),
+      });
+    }
+  }
+
+  /**
+   * Clear all gates and audit trail (for testing)
+   * @returns {void}
+   */
+  clear() {
+    this.#gates.clear();
+    this.#status.clear();
+    this.#auditTrail = [];
+    // Also clear the audit file
+    const auditFilePath = getAuditFilePath();
+    if (fs.existsSync(auditFilePath)) {
+      fs.writeFileSync(auditFilePath, '[]', 'utf-8');
+    }
+  }
+}
+
+module.exports = { QualityGate, z };

package/bin/lib/quality-metrics.cjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+/**
+ * Quality Metrics — Track quality gate metrics over time
+ *
+ * Provides:
+ * - Pass/fail rate tracking per gate
+ * - Trend analysis (improving, stable, degrading)
+ * - Quality reports per phase
+ * - Overall quality scoring
+ *
+ * Usage:
+ *   const QualityMetrics = require('./quality-metrics.cjs');
+ *   const metrics = new QualityMetrics();
+ *   metrics.recordGateResult('test', true, 5000);
+ *   const report = metrics.getReport();
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+const METRICS_PATH = path.join(process.cwd(), '.planning', 'quality-metrics.json');
+const REPORTS_DIR = path.join(process.cwd(), '.planning', 'reports');
+
+class QualityMetrics {
+  constructor() {
+    this.data = this.load();
+  }
+
+  /**
+   * Load metrics from disk
+   */
+  load() {
+    try {
+      if (fs.existsSync(METRICS_PATH)) {
+        const data = JSON.parse(fs.readFileSync(METRICS_PATH, 'utf8'));
+        return data;
+      }
+    } catch (err) {
+      logger.warn('Failed to load quality metrics, starting fresh', { error: err.message });
+    }
+
+    return {
+      gates: {},
+      phases: {},
+      overall: {
+        peakScore: 0,
+        currentScore: 0
+      }
+    };
+  }
+
+  /**
+   * Save metrics to disk
+   */
+  save() {
+    try {
+      const dir = path.dirname(METRICS_PATH);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      this.data.lastUpdated = new Date().toISOString();
+      fs.writeFileSync(METRICS_PATH, JSON.stringify(this.data, null, 2), 'utf8');
+      logger.debug('Quality metrics saved');
+    } catch (err) {
+      logger.error('Failed to save quality metrics', { error: err.message });
+    }
+  }
+
+  /**
+   * Record gate result
+   * @param {string} gateId - Gate identifier
+   * @param {boolean} passed - Whether gate passed
+   * @param {number} duration - Execution time in ms
+   */
+  recordGateResult(gateId, passed, duration = 0) {
+    if (!this.data.gates[gateId]) {
+      this.data.gates[gateId] = { history: [] };
+    }
+
+    const entry = {
+      passed,
+      duration,
+      timestamp: new Date().toISOString()
+    };
+
+    this.data.gates[gateId].history.push(entry);
+
+    // Keep last 100 runs
+    this.data.gates[gateId].history = this.data.gates[gateId].history.slice(-100);
+
+    this.save();
+  }
+
+  /**
+   * Get pass rate for a gate
+   * @param {string} gateId - Gate identifier
+   * @returns {number} Pass rate (0-1)
+   */
+  getPassRate(gateId) {
+    const history = this.data.gates[gateId]?.history || [];
+    if (history.length === 0) return 1.0;
+
+    const passed = history.filter(h => h.passed).length;
+    return passed / history.length;
+  }
+
+  /**
+   * Get trend for a gate
+   * @param {string} gateId - Gate identifier
+   * @returns {string} Trend: 'improving', 'stable', 'degrading', 'insufficient_data'
+   */
+  getTrend(gateId) {
+    const history = this.data.gates[gateId]?.history || [];
+    if (history.length < 5) return 'insufficient_data';
+
+    const recent = history.slice(-5);
+    const older = history.slice(-10, -5);
+
+    const recentRate = recent.filter(h => h.passed).length / recent.length;
+    const olderRate = older.filter(h => h.passed).length / older.length;
+
+    if (recentRate > olderRate + 0.1) return 'improving';
+    if (recentRate < olderRate - 0.1) return 'degrading';
+    return 'stable';
+  }
+
+  /**
+   * Calculate overall quality score
+   * @returns {number} Score (0-100)
+   */
+  calculateOverallScore() {
+    const gateIds = Object.keys(this.data.gates);
+    if (gateIds.length === 0) return 100;
+
+    let totalScore = 0;
+    for (const gateId of gateIds) {
+      totalScore += this.getPassRate(gateId) * 100;
+    }
+
+    const score = Math.round(totalScore / gateIds.length);
+
+    // Track peak and current
+    this.data.overall.currentScore = score;
+    if (score > this.data.overall.peakScore) {
+      this.data.overall.peakScore = score;
+    }
+
+    this.save();
+    return score;
+  }
+
+  /**
+   * Get quality report
+   * @returns {Object} Quality report
+   */
+  getReport() {
+    const report = {
+      gates: {},
+      overall: {
+        score: this.calculateOverallScore(),
+        peakScore: this.data.overall.peakScore,
+        trend: this.getOverallTrend()
+      },
+      generated: new Date().toISOString()
+    };
+
+    for (const [gateId, data] of Object.entries(this.data.gates)) {
+      report.gates[gateId] = {
+        passRate: this.getPassRate(gateId),
+        trend: this.getTrend(gateId),
+        totalRuns: data.history.length,
+        avgDuration: this.getAverageDuration(gateId)
+      };
+    }
+
+    return report;
+  }
+
+  /**
+   * Get overall trend
+   * @returns {string} Overall trend
+   */
+  getOverallTrend() {
+    const gateIds = Object.keys(this.data.gates);
+    if (gateIds.length === 0) return 'stable';
+
+    const trends = gateIds.map(id => this.getTrend(id));
+    const degrading = trends.filter(t => t === 'degrading').length;
+    const improving = trends.filter(t => t === 'improving').length;
+
+    if (degrading > improving) return 'degrading';
+    if (improving > degrading) return 'improving';
+    return 'stable';
+  }
+
+  /**
+   * Get average duration for a gate
+   * @param {string} gateId - Gate identifier
+   * @returns {number} Average duration in ms
+   */
+  getAverageDuration(gateId) {
+    const history = this.data.gates[gateId]?.history || [];
+    if (history.length === 0) return 0;
+
+    const total = history.reduce((sum, h) => sum + (h.duration || 0), 0);
+    return Math.round(total / history.length);
+  }
+
+  /**
+   * Generate quality report for a phase
+   * @param {string} phaseId - Phase identifier
+   * @returns {string} Markdown report
+   */
+  generatePhaseReport(phaseId) {
+    const report = this.getReport();
+
+    const markdown = `# Quality Report: Phase ${phaseId}
+
+**Generated:** ${new Date().toISOString()}
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Overall Score | ${report.overall.score}/100 |
+| Peak Score | ${report.overall.peakScore}/100 |
+| Trend | ${report.overall.trend} |
+
+## Gate Performance
+
+| Gate | Pass Rate | Trend | Avg Duration |
+|------|-----------|-------|--------------|
+${Object.entries(report.gates).map(([gate, data]) => 
+  `| ${gate} | ${(data.passRate * 100).toFixed(1)}% | ${data.trend} | ${data.avgDuration}ms |`
+).join('\n')}
+
+## Recommendations
+
+${this.generateRecommendations(report)}
+
+---
+*Report generated by EZ Agents Quality Metrics*
+`;
+
+    // Save report
+    try {
+      const dir = REPORTS_DIR;
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      const reportPath = path.join(dir, `quality-phase-${phaseId}.md`);
+      fs.writeFileSync(reportPath, markdown, 'utf8');
+      logger.info('Quality report generated', { path: reportPath });
+    } catch (err) {
+      logger.error('Failed to save quality report', { error: err.message });
+    }
+
+    return markdown;
+  }
+
+  /**
+   * Generate recommendations based on report
+   * @param {Object} report - Quality report
+   * @returns {string} Recommendations
+   */
+  generateRecommendations(report) {
+    const recommendations = [];
+
+    for (const [gateId, data] of Object.entries(report.gates)) {
+      if (data.passRate < 0.8) {
+        recommendations.push(`- **${gateId}**: Low pass rate (${(data.passRate * 100).toFixed(1)}%). Review gate configuration and fix flaky tests.`);
+      }
+      if (data.trend === 'degrading') {
+        recommendations.push(`- **${gateId}**: Quality degrading. Investigate recent changes.`);
+      }
+      if (data.avgDuration > 60000) {
+        recommendations.push(`- **${gateId}**: Slow execution (${data.avgDuration}ms). Consider optimization.`);
+      }
+    }
+
+    if (report.overall.trend === 'degrading') {
+      recommendations.push('- **Overall**: Quality trend is degrading. Consider pausing feature work and addressing technical debt.');
+    }
+
+    if (recommendations.length === 0) {
+      return 'No specific recommendations. Quality metrics are healthy.';
+    }
+
+    return recommendations.join('\n');
+  }
+
+  /**
+   * Check if quality allows phase completion
+   * @returns {Object} Result with allowed flag and reasons
+   */
+  canCompletePhase() {
+    const report = this.getReport();
+    const reasons = [];
+
+    // Check for degrading quality
+    const degradingGates = Object.entries(report.gates)
+      .filter(([_, data]) => data.trend === 'degrading');
+
+    if (degradingGates.length > 0) {
+      reasons.push(`Quality degrading on ${degradingGates.length} gate(s): ${degradingGates.map(([id, _]) => id).join(', ')}`);
+    }
+
+    // Check overall score
+    if (report.overall.score < 70) {
+      reasons.push(`Overall quality score too low: ${report.overall.score}/100 (minimum: 70)`);
+    }
+
+    return {
+      allowed: reasons.length === 0,
+      reasons
+    };
+  }
+}
+
+module.exports = { QualityMetrics };