antigravity-ai-kit 2.1.0 → 3.0.1

package/lib/error-budget.js

@@ -0,0 +1,294 @@
+/**
+ * Antigravity AI Kit — Error Budget Tracker
+ *
+ * Enables reliability-config.json error budget tracking with
+ * basic metrics collection. Records test, build, and deployment
+ * results and calculates budget health.
+ *
+ * @module lib/error-budget
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_DIR = '.agent';
+const ENGINE_DIR = 'engine';
+const RELIABILITY_CONFIG = 'reliability-config.json';
+const METRICS_FILE = 'metrics.json';
+
+/**
+ * @typedef {'HEALTHY' | 'WARNING' | 'EXHAUSTED'} BudgetStatus
+ */
+
+/**
+ * @typedef {object} MetricsData
+ * @property {number} testsPassed - Total tests passed
+ * @property {number} testsFailed - Total tests failed
+ * @property {number} buildsSucceeded - Total successful builds
+ * @property {number} buildsFailed - Total failed builds
+ * @property {number} deploysSucceeded - Total successful deploys
+ * @property {number} deploysRolledBack - Total rolled-back deploys
+ * @property {string} periodStart - ISO timestamp of period start
+ * @property {string} lastUpdated - ISO timestamp of last update
+ */
+
+/**
+ * @typedef {object} BudgetReport
+ * @property {BudgetStatus} status - Overall budget health
+ * @property {object} rates - Current failure rates
+ * @property {number} rates.testFailureRate - Test failure rate (%)
+ * @property {number} rates.buildFailureRate - Build failure rate (%)
+ * @property {number} rates.deployRollbackRate - Deploy rollback rate (%)
+ * @property {object} thresholds - Configured thresholds
+ * @property {number} thresholds.testFailureRatePercent - Max test failure rate
+ * @property {number} thresholds.buildFailureRatePercent - Max build failure rate
+ * @property {number} thresholds.deployRollbackRatePercent - Max deploy rollback rate
+ * @property {string[]} violations - Which metrics exceeded thresholds
+ */
+
+/**
+ * Resolves the path to the metrics file.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to metrics.json
+ */
+function resolveMetricsPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, METRICS_FILE);
+}
+
+/**
+ * Resolves the path to the reliability config.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {string} Absolute path to reliability-config.json
+ */
+function resolveConfigPath(projectRoot) {
+  return path.join(projectRoot, AGENT_DIR, ENGINE_DIR, RELIABILITY_CONFIG);
+}
+
+/**
+ * Loads the reliability configuration.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Parsed reliability config
+ */
+function loadConfig(projectRoot) {
+  const configPath = resolveConfigPath(projectRoot);
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Reliability config not found: ${configPath}`);
+  }
+
+  return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+/**
+ * Loads metrics data from disk, or returns defaults if file doesn't exist.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {MetricsData}
+ */
+function loadMetrics(projectRoot) {
+  const metricsPath = resolveMetricsPath(projectRoot);
+
+  if (!fs.existsSync(metricsPath)) {
+    return createEmptyMetrics();
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(metricsPath, 'utf-8'));
+  } catch {
+    return createEmptyMetrics();
+  }
+}
+
+/**
+ * Creates an empty metrics object.
+ *
+ * @returns {MetricsData}
+ */
+function createEmptyMetrics() {
+  return {
+    testsPassed: 0,
+    testsFailed: 0,
+    buildsSucceeded: 0,
+    buildsFailed: 0,
+    deploysSucceeded: 0,
+    deploysRolledBack: 0,
+    periodStart: new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  };
+}
+
+/**
+ * Writes metrics data to disk atomically.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {MetricsData} metrics - Metrics data to write
+ * @returns {void}
+ */
+function writeMetrics(projectRoot, metrics) {
+  const metricsPath = resolveMetricsPath(projectRoot);
+  const tempPath = `${metricsPath}.tmp`;
+
+  metrics.lastUpdated = new Date().toISOString();
+
+  fs.writeFileSync(tempPath, JSON.stringify(metrics, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tempPath, metricsPath);
+}
+
+/**
+ * Records the result of a test run.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {number} passed - Number of tests passed
+ * @param {number} failed - Number of tests failed
+ * @returns {void}
+ */
+function recordTestResult(projectRoot, passed, failed) {
+  const metrics = loadMetrics(projectRoot);
+  metrics.testsPassed += passed;
+  metrics.testsFailed += failed;
+  writeMetrics(projectRoot, metrics);
+}
+
+/**
+ * Records the result of a build.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {boolean} success - Whether the build succeeded
+ * @returns {void}
+ */
+function recordBuildResult(projectRoot, success) {
+  const metrics = loadMetrics(projectRoot);
+
+  if (success) {
+    metrics.buildsSucceeded += 1;
+  } else {
+    metrics.buildsFailed += 1;
+  }
+
+  writeMetrics(projectRoot, metrics);
+}
+
+/**
+ * Records the result of a deployment.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @param {boolean} success - Whether deploy succeeded
+ * @param {boolean} [rolledBack=false] - Whether it was rolled back
+ * @returns {void}
+ */
+function recordDeployResult(projectRoot, success, rolledBack = false) {
+  const metrics = loadMetrics(projectRoot);
+
+  if (success && !rolledBack) {
+    metrics.deploysSucceeded += 1;
+  }
+
+  if (rolledBack) {
+    metrics.deploysRolledBack += 1;
+  }
+
+  writeMetrics(projectRoot, metrics);
+}
+
+/**
+ * Calculates a failure rate percentage safely.
+ *
+ * @param {number} failed - Number of failures
+ * @param {number} total - Total attempts
+ * @returns {number} Failure rate as percentage (0-100)
+ */
+function calculateRate(failed, total) {
+  if (total === 0) {
+    return 0;
+  }
+  return Number(((failed / total) * 100).toFixed(2));
+}
+
+/**
+ * Generates a budget health report.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {BudgetReport}
+ */
+function getBudgetReport(projectRoot) {
+  const config = loadConfig(projectRoot);
+  const metrics = loadMetrics(projectRoot);
+  const thresholds = config.errorBudget?.thresholds || {};
+
+  const testTotal = metrics.testsPassed + metrics.testsFailed;
+  const buildTotal = metrics.buildsSucceeded + metrics.buildsFailed;
+  const deployTotal = metrics.deploysSucceeded + metrics.deploysRolledBack;
+
+  const rates = {
+    testFailureRate: calculateRate(metrics.testsFailed, testTotal),
+    buildFailureRate: calculateRate(metrics.buildsFailed, buildTotal),
+    deployRollbackRate: calculateRate(metrics.deploysRolledBack, deployTotal),
+  };
+
+  /** @type {string[]} */
+  const violations = [];
+
+  if (rates.testFailureRate > (thresholds.testFailureRatePercent || 5)) {
+    violations.push('testFailureRate');
+  }
+  if (rates.buildFailureRate > (thresholds.buildFailureRatePercent || 2)) {
+    violations.push('buildFailureRate');
+  }
+  if (rates.deployRollbackRate > (thresholds.deployRollbackRatePercent || 10)) {
+    violations.push('deployRollbackRate');
+  }
+
+  /** @type {BudgetStatus} */
+  let status = 'HEALTHY';
+
+  if (violations.length > 0) {
+    status = 'EXHAUSTED';
+  } else {
+    // Warning if any rate is above 80% of threshold
+    const testWarning = rates.testFailureRate > (thresholds.testFailureRatePercent || 5) * 0.8;
+    const buildWarning = rates.buildFailureRate > (thresholds.buildFailureRatePercent || 2) * 0.8;
+    const deployWarning = rates.deployRollbackRate > (thresholds.deployRollbackRatePercent || 10) * 0.8;
+
+    if (testWarning || buildWarning || deployWarning) {
+      status = 'WARNING';
+    }
+  }
+
+  return {
+    status,
+    rates,
+    thresholds: {
+      testFailureRatePercent: thresholds.testFailureRatePercent || 5,
+      buildFailureRatePercent: thresholds.buildFailureRatePercent || 2,
+      deployRollbackRatePercent: thresholds.deployRollbackRatePercent || 10,
+    },
+    violations,
+  };
+}
+
+/**
+ * Resets metrics for a new tracking period.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {void}
+ */
+function resetMetrics(projectRoot) {
+  writeMetrics(projectRoot, createEmptyMetrics());
+}
+
+module.exports = {
+  loadConfig,
+  loadMetrics,
+  recordTestResult,
+  recordBuildResult,
+  recordDeployResult,
+  getBudgetReport,
+  resetMetrics,
+};

package/lib/hook-system.js

@@ -0,0 +1,252 @@
+/**
+ * Antigravity AI Kit — Hook Trigger System
+ *
+ * Event-driven lifecycle hook execution based on hooks.json.
+ * Evaluates hook actions and reports results with severity awareness.
+ *
+ * @module lib/hook-system
+ * @author Emre Dursun
+ * @since v3.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_DIR = '.agent';
+const HOOKS_DIR = 'hooks';
+const HOOKS_FILE = 'hooks.json';
+
+/**
+ * @typedef {object} ActionResult
+ * @property {string} action - Action description
+ * @property {'critical' | 'high' | 'medium' | 'low'} severity - Action severity
+ * @property {'block' | 'warn' | 'log'} onFailure - Failure behavior
+ * @property {'pass' | 'fail' | 'skip'} status - Evaluation result
+ * @property {string} reason - Reason for status
+ */
+
+/**
+ * @typedef {object} HookEvaluation
+ * @property {string} event - Hook event name
+ * @property {boolean} blocked - Whether any blocking action failed
+ * @property {number} passed - Count of passed actions
+ * @property {number} failed - Count of failed actions
+ * @property {number} skipped - Count of skipped actions
+ * @property {ActionResult[]} results - Individual action results
+ */
+
+/**
+ * Loads hooks definition from hooks.json.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object} Parsed hooks config
+ */
+function loadHooks(projectRoot) {
+  const hooksPath = path.join(projectRoot, AGENT_DIR, HOOKS_DIR, HOOKS_FILE);
+
+  if (!fs.existsSync(hooksPath)) {
+    return { hooks: [] };
+  }
+
+  return JSON.parse(fs.readFileSync(hooksPath, 'utf-8'));
+}
+
+/**
+ * Gets the action definitions for a specific event.
+ *
+ * @param {string} eventName - Hook event name (e.g., 'session-start')
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {object[]} Action definitions for this event
+ */
+function getHookActions(eventName, projectRoot) {
+  const config = loadHooks(projectRoot);
+  const hook = (config.hooks || []).find((h) => h.event === eventName);
+
+  if (!hook) {
+    return [];
+  }
+
+  return hook.actions || [];
+}
+
+/**
+ * Evaluates a hook event against the current project state.
+ *
+ * This performs a "check" pass — it determines which actions would
+ * pass or fail without actually executing them. Actions are evaluated
+ * based on the existence of required files and configurations.
+ *
+ * @param {string} eventName - Hook event name
+ * @param {object} context - Evaluation context
+ * @param {string} context.projectRoot - Root directory of the project
+ * @param {boolean} [context.gitClean] - Whether git status is clean
+ * @param {boolean} [context.testsPass] - Whether tests pass
+ * @param {boolean} [context.buildPass] - Whether build passes
+ * @param {boolean} [context.lintPass] - Whether lint passes
+ * @returns {HookEvaluation}
+ */
+function evaluateHook(eventName, context) {
+  const projectRoot = context.projectRoot;
+  const actions = getHookActions(eventName, projectRoot);
+
+  if (actions.length === 0) {
+    return { event: eventName, blocked: false, passed: 0, failed: 0, skipped: 0, results: [] };
+  }
+
+  /** @type {ActionResult[]} */
+  const results = [];
+  let blocked = false;
+
+  for (const action of actions) {
+    const result = evaluateAction(action, context);
+    results.push(result);
+
+    if (result.status === 'fail' && action.onFailure === 'block') {
+      blocked = true;
+    }
+  }
+
+  return {
+    event: eventName,
+    blocked,
+    passed: results.filter((r) => r.status === 'pass').length,
+    failed: results.filter((r) => r.status === 'fail').length,
+    skipped: results.filter((r) => r.status === 'skip').length,
+    results,
+  };
+}
+
+/**
+ * Evaluates a single action based on context.
+ *
+ * @param {object} action - Action definition from hooks.json
+ * @param {object} context - Evaluation context
+ * @returns {ActionResult}
+ */
+function evaluateAction(action, context) {
+  const actionLower = action.action.toLowerCase();
+  const projectRoot = context.projectRoot;
+
+  // File existence checks
+  if (actionLower.includes('session-context.md') || actionLower.includes('session-state.json')) {
+    const targetFile = actionLower.includes('session-context.md') ? 'session-context.md' : 'session-state.json';
+    const filePath = path.join(projectRoot, AGENT_DIR, targetFile);
+    const exists = fs.existsSync(filePath);
+
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: exists ? 'pass' : 'fail',
+      reason: exists ? `${targetFile} exists` : `${targetFile} not found`,
+    };
+  }
+
+  if (actionLower.includes('loading-rules.json') || actionLower.includes('workflow-state.json')) {
+    const targetFile = actionLower.includes('loading-rules.json') ? 'loading-rules.json' : 'workflow-state.json';
+    const filePath = path.join(projectRoot, AGENT_DIR, 'engine', targetFile);
+    const exists = fs.existsSync(filePath);
+
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: exists ? 'pass' : 'fail',
+      reason: exists ? `${targetFile} exists and readable` : `${targetFile} not found`,
+    };
+  }
+
+  // Git status check
+  if (actionLower.includes('git status')) {
+    const gitClean = context.gitClean !== undefined ? context.gitClean : true;
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: gitClean ? 'pass' : 'fail',
+      reason: gitClean ? 'Git status clean' : 'Git has uncommitted changes',
+    };
+  }
+
+  // Build/test/lint checks
+  if (actionLower.includes('build passes') || actionLower.includes('npm run build')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.buildPass ? 'pass' : context.buildPass === false ? 'fail' : 'skip',
+      reason: context.buildPass ? 'Build passes' : context.buildPass === false ? 'Build failed' : 'Build not checked',
+    };
+  }
+
+  if (actionLower.includes('tests pass') || actionLower.includes('npm test')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.testsPass ? 'pass' : context.testsPass === false ? 'fail' : 'skip',
+      reason: context.testsPass ? 'Tests pass' : context.testsPass === false ? 'Tests failed' : 'Tests not checked',
+    };
+  }
+
+  if (actionLower.includes('lint passes') || actionLower.includes('npm run lint')) {
+    return {
+      action: action.action,
+      severity: action.severity,
+      onFailure: action.onFailure,
+      status: context.lintPass ? 'pass' : context.lintPass === false ? 'fail' : 'skip',
+      reason: context.lintPass ? 'Lint passes' : context.lintPass === false ? 'Lint failed' : 'Lint not checked',
+    };
+  }
+
+  // Default: skip actions we can't evaluate programmatically
+  return {
+    action: action.action,
+    severity: action.severity,
+    onFailure: action.onFailure,
+    status: 'skip',
+    reason: 'Cannot evaluate programmatically — requires agent execution',
+  };
+}
+
+/**
+ * Lists all available hook events.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {Array<{ event: string, description: string, actionCount: number }>}
+ */
+function listEvents(projectRoot) {
+  const config = loadHooks(projectRoot);
+
+  return (config.hooks || []).map((hook) => ({
+    event: hook.event,
+    description: hook.description,
+    actionCount: (hook.actions || []).length,
+  }));
+}
+
+/**
+ * Generates a full hook readiness report for all events.
+ *
+ * @param {string} projectRoot - Root directory of the project
+ * @returns {{ events: HookEvaluation[], totalActions: number, readyCount: number }}
+ */
+function getHookReport(projectRoot) {
+  const events = listEvents(projectRoot);
+  const context = { projectRoot };
+
+  const evaluations = events.map((e) => evaluateHook(e.event, context));
+  const totalActions = evaluations.reduce((sum, e) => sum + e.passed + e.failed + e.skipped, 0);
+  const readyCount = evaluations.filter((e) => !e.blocked).length;
+
+  return { events: evaluations, totalActions, readyCount };
+}
+
+module.exports = {
+  getHookActions,
+  evaluateHook,
+  listEvents,
+  getHookReport,
+};