tlc-claude-code 1.6.2 → 1.6.4

package/server/lib/release-config.test.js

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest';
+import {
+  loadReleaseConfig,
+  getGatesForTier,
+  getPreviewUrl,
+  validateReleaseConfig,
+  DEFAULT_RELEASE_CONFIG,
+} from './release-config.js';
+
+describe('Release Config', () => {
+  describe('loadReleaseConfig', () => {
+    it('loads valid release config from object', () => {
+      const input = {
+        release: {
+          tagPattern: 'v*',
+          previewUrlTemplate: 'qa-{tag}.example.com',
+          tiers: {
+            rc: {
+              gates: ['tests', 'security', 'coverage', 'qa-approval'],
+              coverageThreshold: 80,
+              autoPromote: false,
+            },
+          },
+          notifications: {
+            onDeploy: ['slack'],
+          },
+        },
+      };
+      const config = loadReleaseConfig(input);
+      expect(config.tagPattern).toBe('v*');
+      expect(config.previewUrlTemplate).toBe('qa-{tag}.example.com');
+      expect(config.tiers.rc.gates).toEqual(['tests', 'security', 'coverage', 'qa-approval']);
+      expect(config.notifications.onDeploy).toEqual(['slack']);
+    });
+
+    it('applies defaults for missing fields', () => {
+      const config = loadReleaseConfig({});
+      expect(config.tagPattern).toBe('v*');
+      expect(config.previewUrlTemplate).toBe('qa-{tag}.{domain}');
+      expect(config.tiers).toBeDefined();
+      expect(config.tiers.rc).toBeDefined();
+      expect(config.tiers.beta).toBeDefined();
+      expect(config.tiers.release).toBeDefined();
+      expect(config.notifications).toBeDefined();
+    });
+
+    it('handles empty/missing release section gracefully', () => {
+      expect(() => loadReleaseConfig({})).not.toThrow();
+      expect(() => loadReleaseConfig(null)).not.toThrow();
+      expect(() => loadReleaseConfig(undefined)).not.toThrow();
+      expect(() => loadReleaseConfig({ release: null })).not.toThrow();
+
+      const config = loadReleaseConfig(null);
+      expect(config.tagPattern).toBe('v*');
+      expect(config.tiers.rc.gates).toBeDefined();
+    });
+
+    it('merges release config with existing config without clobbering other fields', () => {
+      const input = {
+        project: 'TLC',
+        version: '1.0.0',
+        release: {
+          tagPattern: 'release-*',
+        },
+      };
+      const config = loadReleaseConfig(input);
+      // loadReleaseConfig returns only the release section
+      expect(config.tagPattern).toBe('release-*');
+      // defaults still applied for missing tiers
+      expect(config.tiers.rc).toBeDefined();
+      expect(config.tiers.beta).toBeDefined();
+    });
+
+    it('config is immutable (returns copy, not reference)', () => {
+      const input = {
+        release: {
+          tagPattern: 'v*',
+          tiers: {
+            rc: {
+              gates: ['tests', 'security'],
+              coverageThreshold: 90,
+            },
+          },
+        },
+      };
+      const config1 = loadReleaseConfig(input);
+      const config2 = loadReleaseConfig(input);
+      config1.tiers.rc.gates.push('qa-approval');
+      config1.tiers.rc.coverageThreshold = 50;
+      // config2 should be unaffected
+      expect(config2.tiers.rc.gates).not.toContain('qa-approval');
+      expect(config2.tiers.rc.coverageThreshold).toBe(90);
+    });
+  });
+
+  describe('validateReleaseConfig', () => {
+    it('rejects unknown gate names (only: tests, security, coverage, qa-approval)', () => {
+      const config = loadReleaseConfig({
+        release: {
+          tiers: {
+            rc: { gates: ['tests', 'unknown-gate'] },
+          },
+        },
+      });
+      const result = validateReleaseConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('unknown-gate'))).toBe(true);
+    });
+
+    it('validates URL templates contain {tag} placeholder', () => {
+      const config = loadReleaseConfig({
+        release: {
+          previewUrlTemplate: 'qa.example.com',
+        },
+      });
+      const result = validateReleaseConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('{tag}'))).toBe(true);
+    });
+
+    it('validates notification channel names', () => {
+      const config = loadReleaseConfig({
+        release: {
+          notifications: {
+            onDeploy: [''],
+            onAccept: [123],
+          },
+        },
+      });
+      const result = validateReleaseConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('notification'))).toBe(true);
+    });
+
+    it('validates tagPattern is valid glob', () => {
+      const config = loadReleaseConfig({
+        release: {
+          tagPattern: '',
+        },
+      });
+      const result = validateReleaseConfig(config);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('tagPattern'))).toBe(true);
+    });
+
+    it('returns valid for correct default config', () => {
+      const config = loadReleaseConfig({});
+      const result = validateReleaseConfig(config);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  describe('getGatesForTier', () => {
+    it('returns tier-specific gate list', () => {
+      const config = loadReleaseConfig({});
+      const rcGates = getGatesForTier(config, 'rc');
+      expect(rcGates).toEqual(['tests', 'security', 'coverage', 'qa-approval']);
+    });
+
+    it('default gates: rc requires all 4 gates', () => {
+      const config = loadReleaseConfig({});
+      const gates = getGatesForTier(config, 'rc');
+      expect(gates).toContain('tests');
+      expect(gates).toContain('security');
+      expect(gates).toContain('coverage');
+      expect(gates).toContain('qa-approval');
+      expect(gates).toHaveLength(4);
+    });
+
+    it('default gates: beta requires tests+security', () => {
+      const config = loadReleaseConfig({});
+      const gates = getGatesForTier(config, 'beta');
+      expect(gates).toEqual(['tests', 'security']);
+    });
+
+    it('default gates: release requires tests+security+coverage', () => {
+      const config = loadReleaseConfig({});
+      const gates = getGatesForTier(config, 'release');
+      expect(gates).toEqual(['tests', 'security', 'coverage']);
+    });
+
+    it('returns empty array for unknown tier', () => {
+      const config = loadReleaseConfig({});
+      const gates = getGatesForTier(config, 'nonexistent');
+      expect(gates).toEqual([]);
+    });
+  });
+
+  describe('getPreviewUrl', () => {
+    it('returns preview URL template with defaults', () => {
+      const config = loadReleaseConfig({});
+      const url = getPreviewUrl(config, 'v1.0.0', 'example.com');
+      expect(url).toBe('qa-v1.0.0.example.com');
+    });
+
+    it('uses custom template', () => {
+      const config = loadReleaseConfig({
+        release: { previewUrlTemplate: 'preview-{tag}.{domain}/app' },
+      });
+      const url = getPreviewUrl(config, 'v2.0.0-rc.1', 'myapp.io');
+      expect(url).toBe('preview-v2.0.0-rc.1.myapp.io/app');
+    });
+  });
+
+  describe('DEFAULT_RELEASE_CONFIG', () => {
+    it('default coverage threshold: 80 for rc', () => {
+      expect(DEFAULT_RELEASE_CONFIG.tiers.rc.coverageThreshold).toBe(80);
+    });
+
+    it('default coverage threshold: 70 for beta', () => {
+      expect(DEFAULT_RELEASE_CONFIG.tiers.beta.coverageThreshold).toBe(70);
+    });
+
+    it('default coverage threshold: 80 for release', () => {
+      expect(DEFAULT_RELEASE_CONFIG.tiers.release.coverageThreshold).toBe(80);
+    });
+
+    it('has expected structure', () => {
+      expect(DEFAULT_RELEASE_CONFIG.tagPattern).toBe('v*');
+      expect(DEFAULT_RELEASE_CONFIG.previewUrlTemplate).toBe('qa-{tag}.{domain}');
+      expect(DEFAULT_RELEASE_CONFIG.tiers).toBeDefined();
+      expect(DEFAULT_RELEASE_CONFIG.notifications).toBeDefined();
+    });
+  });
+});

package/server/lib/release-gate.js

@@ -0,0 +1,267 @@
+/**
+ * Release Gate Engine - Configurable quality gates that must pass before
+ * a tag can be promoted. Gates run in sequence; any failure blocks promotion.
+ *
+ * @module release-gate
+ */
+
+/**
+ * @typedef {Object} GateResult
+ * @property {string} gate - Name of the gate
+ * @property {'pass'|'fail'|'pending'|'skipped'} status - Gate outcome
+ * @property {number} duration - Execution time in milliseconds
+ * @property {Object} details - Gate-specific detail object
+ * @property {Function} [approve] - Only on qa-approval gates with pending status
+ * @property {Function} [reject] - Only on qa-approval gates with pending status
+ */
+
+/**
+ * @typedef {Object} GateRunResult
+ * @property {boolean} passed - True only if every gate passed
+ * @property {GateResult[]} results - Ordered array of individual gate results
+ */
+
+/**
+ * Built-in gate: tests.
+ * Delegates to the provided checker function, which should return
+ * { passed: boolean, total: number, failed: number }.
+ *
+ * @param {Object} tag - Parsed tag info from parseTag()
+ * @param {Object} config - Release config from loadReleaseConfig()
+ * @param {Function} checker - Injected test-runner function
+ * @returns {Promise<GateResult>}
+ */
+async function runTestsGate(tag, config, checker) {
+  const start = Date.now();
+  const result = await checker(tag, config);
+  const duration = Date.now() - start;
+
+  return {
+    gate: 'tests',
+    status: result.passed ? 'pass' : 'fail',
+    duration,
+    details: {
+      total: result.total,
+      failed: result.failed,
+    },
+  };
+}
+
+/**
+ * Built-in gate: security.
+ * Delegates to the provided checker function, which should return
+ * { passed: boolean, secrets: Array }.
+ *
+ * @param {Object} tag - Parsed tag info
+ * @param {Object} config - Release config
+ * @param {Function} checker - Injected security-scan function
+ * @returns {Promise<GateResult>}
+ */
+async function runSecurityGate(tag, config, checker) {
+  const start = Date.now();
+  const result = await checker(tag, config);
+  const duration = Date.now() - start;
+
+  return {
+    gate: 'security',
+    status: result.passed ? 'pass' : 'fail',
+    duration,
+    details: {
+      secrets: result.secrets,
+    },
+  };
+}
+
+/**
+ * Built-in gate: coverage.
+ * Delegates to the provided checker function, which should return
+ * { passed: boolean, percentage: number }.
+ * Includes the configured threshold in the details on failure.
+ *
+ * @param {Object} tag - Parsed tag info
+ * @param {Object} config - Release config
+ * @param {Function} checker - Injected coverage-check function
+ * @returns {Promise<GateResult>}
+ */
+async function runCoverageGate(tag, config, checker) {
+  const start = Date.now();
+  const result = await checker(tag, config);
+  const duration = Date.now() - start;
+
+  // Look up threshold from config for the tag's tier
+  const tier = tag.tier;
+  const threshold =
+    config.tiers && config.tiers[tier] && config.tiers[tier].coverageThreshold != null
+      ? config.tiers[tier].coverageThreshold
+      : 80;
+
+  return {
+    gate: 'coverage',
+    status: result.passed ? 'pass' : 'fail',
+    duration,
+    details: {
+      percentage: result.percentage,
+      threshold,
+    },
+  };
+}
+
+/**
+ * Built-in gate: qa-approval.
+ * Returns a pending result with approve() and reject() methods.
+ * Calling approve() transitions status to 'pass'.
+ * Calling reject(reason) transitions status to 'fail' with a reason in details.
+ *
+ * @param {Object} _tag - Parsed tag info (unused)
+ * @param {Object} _config - Release config (unused)
+ * @returns {Promise<GateResult>}
+ */
+async function runQaApprovalGate(_tag, _config) {
+  const start = Date.now();
+  const duration = Date.now() - start;
+
+  const gateResult = {
+    gate: 'qa-approval',
+    status: 'pending',
+    duration,
+    details: {},
+  };
+
+  gateResult.approve = () => {
+    gateResult.status = 'pass';
+  };
+
+  gateResult.reject = (reason) => {
+    gateResult.status = 'fail';
+    gateResult.details.reason = reason;
+  };
+
+  return gateResult;
+}
+
+/** Map of built-in gate names to their runner functions */
+const BUILTIN_GATES = {
+  tests: runTestsGate,
+  security: runSecurityGate,
+  coverage: runCoverageGate,
+  'qa-approval': runQaApprovalGate,
+};
+
+/**
+ * Run a sequence of quality gates for a given tag.
+ * Gates execute in order. If any gate fails, subsequent gates are marked 'skipped'.
+ * Custom gate checker functions can be injected via options.checkers.
+ *
+ * @param {Object} tag - Parsed tag info (from parseTag())
+ * @param {string[]} gates - Ordered list of gate names to run
+ * @param {Object} config - Release config (from loadReleaseConfig())
+ * @param {Object} [options={}] - Options
+ * @param {Object.<string, Function>} [options.checkers] - Map of gate name to checker function
+ * @returns {Promise<GateRunResult>} Overall result with per-gate details
+ */
+export async function runGates(tag, gates, config, options = {}) {
+  const checkers = (options && options.checkers) || {};
+  const results = [];
+  let blocked = false;
+
+  for (const gateName of gates) {
+    if (blocked) {
+      results.push({
+        gate: gateName,
+        status: 'skipped',
+        duration: 0,
+        details: {},
+      });
+      continue;
+    }
+
+    // Determine how to run this gate
+    const isBuiltin = gateName in BUILTIN_GATES;
+    const hasChecker = gateName in checkers;
+
+    if (gateName === 'qa-approval') {
+      // qa-approval is always handled by the built-in runner
+      const gateResult = await runQaApprovalGate(tag, config);
+      results.push(gateResult);
+      // pending counts as not-passed, blocks subsequent gates
+      if (gateResult.status !== 'pass') {
+        blocked = true;
+      }
+    } else if (hasChecker && isBuiltin) {
+      // Built-in gate with injected checker
+      const gateResult = await BUILTIN_GATES[gateName](tag, config, checkers[gateName]);
+      results.push(gateResult);
+      if (gateResult.status !== 'pass') {
+        blocked = true;
+      }
+    } else if (hasChecker && !isBuiltin) {
+      // Custom gate with injected checker - run it as a generic checker
+      const start = Date.now();
+      const checkerResult = await checkers[gateName](tag, config);
+      const duration = Date.now() - start;
+      const gateResult = {
+        gate: gateName,
+        status: checkerResult.passed ? 'pass' : 'fail',
+        duration,
+        details: { ...checkerResult },
+      };
+      // Remove 'passed' from details since it's represented by status
+      delete gateResult.details.passed;
+      results.push(gateResult);
+      if (gateResult.status !== 'pass') {
+        blocked = true;
+      }
+    } else if (isBuiltin && !hasChecker) {
+      // Built-in gate without checker - this shouldn't happen for tests/security/coverage
+      // but we handle it gracefully
+      results.push({
+        gate: gateName,
+        status: 'fail',
+        duration: 0,
+        details: { error: `No checker provided for built-in gate: ${gateName}` },
+      });
+      blocked = true;
+    } else {
+      // Unknown gate type
+      results.push({
+        gate: gateName,
+        status: 'fail',
+        duration: 0,
+        details: { error: `Unknown gate type: ${gateName}` },
+      });
+      blocked = true;
+    }
+  }
+
+  const passed = results.length === 0 || results.every(r => r.status === 'pass');
+
+  return { passed, results };
+}
+
+/**
+ * Create a gate runner instance bound to a specific config.
+ * The returned runner has a `run` method that uses the bound config.
+ *
+ * @param {Object} config - Release config (from loadReleaseConfig())
+ * @returns {{ run: (tag: Object, gates: string[], options?: Object) => Promise<GateRunResult> }}
+ */
+export function createGateRunner(config) {
+  return {
+    /**
+     * Run gates using the config bound at creation time.
+     *
+     * @param {Object} tag - Parsed tag info
+     * @param {string[]} gates - Ordered list of gate names
+     * @param {Object} [options={}] - Options (checkers, etc.)
+     * @returns {Promise<GateRunResult>}
+     */
+    run(tag, gates, options = {}) {
+      return runGates(tag, gates, config, options);
+    },
+  };
+}
+
+export default {
+  createGateRunner,
+  runGates,
+};