pumuki-ast-hooks 5.5.65 → 5.6.0

package/scripts/hooks-system/infrastructure/observability/MetricsCollector.js

@@ -0,0 +1,221 @@
+/**
+ * =============================================================================
+ * MetricsCollector - Enterprise Observability for AST Intelligence
+ * =============================================================================
+ * Collects and exposes metrics in Prometheus format
+ * Supports: counters, gauges, histograms
+ */
+
+class MetricsCollector {
+    constructor(options = {}) {
+        this.prefix = options.prefix || 'ast_intelligence';
+        this.labels = options.defaultLabels || {};
+        this.metrics = new Map();
+        this.histogramBuckets = options.histogramBuckets || [0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10];
+    }
+
+    counter(name, help, labelNames = []) {
+        const key = `${this.prefix}_${name}`;
+        if (!this.metrics.has(key)) {
+            this.metrics.set(key, {
+                type: 'counter',
+                name: key,
+                help,
+                labelNames,
+                values: new Map()
+            });
+        }
+        return {
+            inc: (labels = {}, value = 1) => this._incCounter(key, labels, value)
+        };
+    }
+
+    gauge(name, help, labelNames = []) {
+        const key = `${this.prefix}_${name}`;
+        if (!this.metrics.has(key)) {
+            this.metrics.set(key, {
+                type: 'gauge',
+                name: key,
+                help,
+                labelNames,
+                values: new Map()
+            });
+        }
+        return {
+            set: (labels = {}, value) => this._setGauge(key, labels, value),
+            inc: (labels = {}, value = 1) => this._incGauge(key, labels, value),
+            dec: (labels = {}, value = 1) => this._decGauge(key, labels, value)
+        };
+    }
+
+    histogram(name, help, labelNames = [], buckets = null) {
+        const key = `${this.prefix}_${name}`;
+        if (!this.metrics.has(key)) {
+            this.metrics.set(key, {
+                type: 'histogram',
+                name: key,
+                help,
+                labelNames,
+                buckets: buckets || this.histogramBuckets,
+                values: new Map()
+            });
+        }
+        return {
+            observe: (labels = {}, value) => this._observeHistogram(key, labels, value)
+        };
+    }
+
+    _labelKey(labels) {
+        return JSON.stringify(labels);
+    }
+
+    _incCounter(key, labels, value) {
+        const metric = this.metrics.get(key);
+        if (!metric) return;
+        const labelKey = this._labelKey(labels);
+        const current = metric.values.get(labelKey) || 0;
+        metric.values.set(labelKey, current + value);
+    }
+
+    _setGauge(key, labels, value) {
+        const metric = this.metrics.get(key);
+        if (!metric) return;
+        const labelKey = this._labelKey(labels);
+        metric.values.set(labelKey, value);
+    }
+
+    _incGauge(key, labels, value) {
+        const metric = this.metrics.get(key);
+        if (!metric) return;
+        const labelKey = this._labelKey(labels);
+        const current = metric.values.get(labelKey) || 0;
+        metric.values.set(labelKey, current + value);
+    }
+
+    _decGauge(key, labels, value) {
+        const metric = this.metrics.get(key);
+        if (!metric) return;
+        const labelKey = this._labelKey(labels);
+        const current = metric.values.get(labelKey) || 0;
+        metric.values.set(labelKey, current - value);
+    }
+
+    _observeHistogram(key, labels, value) {
+        const metric = this.metrics.get(key);
+        if (!metric) return;
+        const labelKey = this._labelKey(labels);
+
+        if (!metric.values.has(labelKey)) {
+            metric.values.set(labelKey, {
+                sum: 0,
+                count: 0,
+                buckets: new Map(metric.buckets.map(b => [b, 0]))
+            });
+        }
+
+        const data = metric.values.get(labelKey);
+        data.sum += value;
+        data.count += 1;
+
+        for (const bucket of metric.buckets) {
+            if (value <= bucket) {
+                data.buckets.set(bucket, data.buckets.get(bucket) + 1);
+            }
+        }
+    }
+
+    toPrometheusFormat() {
+        const lines = [];
+
+        for (const [, metric] of this.metrics) {
+            lines.push(`# HELP ${metric.name} ${metric.help}`);
+            lines.push(`# TYPE ${metric.name} ${metric.type}`);
+
+            for (const [labelKey, value] of metric.values) {
+                const labels = JSON.parse(labelKey);
+                const labelStr = Object.entries(labels)
+                    .map(([k, v]) => `${k}="${v}"`)
+                    .join(',');
+
+                if (metric.type === 'histogram') {
+                    for (const [bucket, count] of value.buckets) {
+                        const bucketLabels = labelStr ? `${labelStr},le="${bucket}"` : `le="${bucket}"`;
+                        lines.push(`${metric.name}_bucket{${bucketLabels}} ${count}`);
+                    }
+                    const infLabels = labelStr ? `${labelStr},le="+Inf"` : `le="+Inf"`;
+                    lines.push(`${metric.name}_bucket{${infLabels}} ${value.count}`);
+                    lines.push(`${metric.name}_sum{${labelStr}} ${value.sum}`);
+                    lines.push(`${metric.name}_count{${labelStr}} ${value.count}`);
+                } else {
+                    if (labelStr) {
+                        lines.push(`${metric.name}{${labelStr}} ${value}`);
+                    } else {
+                        lines.push(`${metric.name} ${value}`);
+                    }
+                }
+            }
+        }
+
+        return lines.join('\n');
+    }
+
+    getMetricsJSON() {
+        const result = {};
+        for (const [key, metric] of this.metrics) {
+            result[key] = {
+                type: metric.type,
+                help: metric.help,
+                values: Object.fromEntries(metric.values)
+            };
+        }
+        return result;
+    }
+
+    reset() {
+        for (const [, metric] of this.metrics) {
+            metric.values.clear();
+        }
+    }
+}
+
+const globalCollector = new MetricsCollector();
+
+const gateCheckCounter = globalCollector.counter(
+    'gate_check_total',
+    'Total number of AI gate checks',
+    ['status', 'branch_type']
+);
+
+const gateCheckDuration = globalCollector.histogram(
+    'gate_check_duration_seconds',
+    'Duration of AI gate checks in seconds',
+    ['status']
+);
+
+const violationsGauge = globalCollector.gauge(
+    'violations_current',
+    'Current number of violations',
+    ['severity']
+);
+
+const mcpToolCallCounter = globalCollector.counter(
+    'mcp_tool_call_total',
+    'Total MCP tool calls',
+    ['tool', 'success']
+);
+
+const evidenceAgeGauge = globalCollector.gauge(
+    'evidence_age_seconds',
+    'Age of AI evidence in seconds',
+    []
+);
+
+module.exports = {
+    MetricsCollector,
+    globalCollector,
+    gateCheckCounter,
+    gateCheckDuration,
+    violationsGauge,
+    mcpToolCallCounter,
+    evidenceAgeGauge
+};

package/scripts/hooks-system/infrastructure/observability/index.js

@@ -0,0 +1,23 @@
+/**
+ * Observability Module - Metrics & Monitoring
+ */
+
+const {
+    MetricsCollector,
+    globalCollector,
+    gateCheckCounter,
+    gateCheckDuration,
+    violationsGauge,
+    mcpToolCallCounter,
+    evidenceAgeGauge
+} = require('./MetricsCollector');
+
+module.exports = {
+    MetricsCollector,
+    globalCollector,
+    gateCheckCounter,
+    gateCheckDuration,
+    violationsGauge,
+    mcpToolCallCounter,
+    evidenceAgeGauge
+};

package/scripts/hooks-system/infrastructure/orchestration/__tests__/intelligent-audit.spec.js

@@ -196,3 +196,180 @@ describe('AI_EVIDENCE.json structure validation', () => {
     });
   });
 });
+
+describe('Cognitive Memory Layers', () => {
+  const createMockEvidenceWithLayers = (humanIntentOverride = null) => ({
+    timestamp: new Date().toISOString(),
+    platforms: {
+      backend: { detected: true, violations: 0 },
+      frontend: { detected: false, violations: 0 },
+      ios: { detected: false, violations: 0 },
+      android: { detected: false, violations: 0 }
+    },
+    current_context: {
+      working_on: 'Test',
+      current_branch: 'feature/test',
+      base_branch: 'develop'
+    },
+    session_id: 'session-123-abc',
+    watchers: {
+      token_monitor: { enabled: true },
+      evidence_watcher: { auto_refresh: true }
+    },
+    protocol_3_questions: { answered: true },
+    human_intent: humanIntentOverride,
+    semantic_snapshot: null
+  });
+
+  describe('human_intent layer (Intentional Memory)', () => {
+    it('should initialize human_intent with empty structure when not present', () => {
+      const { preserveOrInitHumanIntent } = jest.requireActual('../intelligent-audit');
+
+      if (typeof preserveOrInitHumanIntent !== 'function') {
+        const evidence = createMockEvidenceWithLayers(null);
+        expect(evidence.human_intent).toBeNull();
+        return;
+      }
+
+      const evidence = createMockEvidenceWithLayers(null);
+      const result = preserveOrInitHumanIntent(evidence);
+
+      expect(result).toBeDefined();
+      expect(result.primary_goal).toBeNull();
+      expect(result.secondary_goals).toEqual([]);
+      expect(result.non_goals).toEqual([]);
+      expect(result.constraints).toEqual([]);
+      expect(result.confidence_level).toBe('unset');
+      expect(result._hint).toBeDefined();
+    });
+
+    it('should preserve existing human_intent if not expired', () => {
+      const futureDate = new Date(Date.now() + 86400000).toISOString();
+      const existingIntent = {
+        primary_goal: 'Implement feature X',
+        secondary_goals: ['Add tests'],
+        non_goals: ['Refactor unrelated code'],
+        constraints: ['No breaking changes'],
+        confidence_level: 'high',
+        set_by: 'user',
+        set_at: new Date().toISOString(),
+        expires_at: futureDate,
+        preservation_count: 2
+      };
+
+      const evidence = createMockEvidenceWithLayers(existingIntent);
+
+      expect(evidence.human_intent).toBeDefined();
+      expect(evidence.human_intent.primary_goal).toBe('Implement feature X');
+      expect(evidence.human_intent.preservation_count).toBe(2);
+    });
+
+    it('should have required human_intent contract fields', () => {
+      const requiredFields = [
+        'primary_goal',
+        'secondary_goals',
+        'non_goals',
+        'constraints',
+        'confidence_level'
+      ];
+
+      const emptyIntent = {
+        primary_goal: null,
+        secondary_goals: [],
+        non_goals: [],
+        constraints: [],
+        confidence_level: 'unset'
+      };
+
+      requiredFields.forEach(field => {
+        expect(emptyIntent).toHaveProperty(field);
+      });
+    });
+  });
+
+  describe('semantic_snapshot layer (Semantic Memory)', () => {
+    it('should have required semantic_snapshot contract fields when generated', () => {
+      const snapshot = {
+        generated_at: new Date().toISOString(),
+        derivation_source: 'auto:updateAIEvidence',
+        context_hash: 'ctx-abc123',
+        summary: {
+          health_score: 100,
+          gate_status: 'PASSED',
+          active_platforms: ['backend'],
+          violation_count: 0,
+          violation_preview: 'No violations',
+          branch: 'feature/test',
+          session_id: 'session-123-abc'
+        },
+        feature_state: {
+          ai_gate_enabled: true,
+          token_monitoring: true,
+          auto_refresh: true,
+          protocol_3_active: true
+        },
+        decisions: {
+          last_gate_decision: 'allow',
+          blocking_reason: null,
+          recommended_action: 'proceed_with_development'
+        }
+      };
+
+      expect(snapshot.generated_at).toBeDefined();
+      expect(snapshot.derivation_source).toBe('auto:updateAIEvidence');
+      expect(snapshot.summary).toBeDefined();
+      expect(snapshot.summary.health_score).toBeGreaterThanOrEqual(0);
+      expect(snapshot.summary.health_score).toBeLessThanOrEqual(100);
+      expect(snapshot.feature_state).toBeDefined();
+      expect(snapshot.decisions).toBeDefined();
+    });
+
+    it('should calculate health_score based on violations', () => {
+      const noViolationsScore = 100;
+      const withCriticalScore = Math.max(0, 100 - 20);
+      const withHighScore = Math.max(0, 100 - 10);
+      const withManyViolations = Math.max(0, 100 - (10 * 5));
+
+      expect(noViolationsScore).toBe(100);
+      expect(withCriticalScore).toBe(80);
+      expect(withHighScore).toBe(90);
+      expect(withManyViolations).toBe(50);
+    });
+
+    it('should derive recommended_action from gate status', () => {
+      const passedDecision = {
+        last_gate_decision: 'allow',
+        recommended_action: 'proceed_with_development'
+      };
+
+      const blockedDecision = {
+        last_gate_decision: 'block',
+        recommended_action: 'fix_violations_before_commit'
+      };
+
+      expect(passedDecision.recommended_action).toBe('proceed_with_development');
+      expect(blockedDecision.recommended_action).toBe('fix_violations_before_commit');
+    });
+  });
+
+  describe('Layer integration', () => {
+    it('should include both layers in complete evidence structure', () => {
+      const completeEvidence = {
+        timestamp: new Date().toISOString(),
+        severity_metrics: { total_violations: 0 },
+        ai_gate: { status: 'ALLOWED' },
+        human_intent: {
+          primary_goal: null,
+          confidence_level: 'unset'
+        },
+        semantic_snapshot: {
+          generated_at: new Date().toISOString(),
+          summary: { health_score: 100 }
+        }
+      };
+
+      expect(completeEvidence.human_intent).toBeDefined();
+      expect(completeEvidence.semantic_snapshot).toBeDefined();
+    });
+  });
+});

package/scripts/hooks-system/infrastructure/resilience/CircuitBreaker.js

@@ -0,0 +1,229 @@
+/**
+ * =============================================================================
+ * CircuitBreaker - Enterprise Resilience for AST Intelligence
+ * =============================================================================
+ * Implements Circuit Breaker pattern to prevent cascading failures
+ * States: CLOSED (normal) → OPEN (failing) → HALF_OPEN (testing)
+ */
+
+const STATES = {
+    CLOSED: 'CLOSED',
+    OPEN: 'OPEN',
+    HALF_OPEN: 'HALF_OPEN'
+};
+
+class CircuitBreaker {
+    constructor(options = {}) {
+        this.name = options.name || 'default';
+        this.failureThreshold = options.failureThreshold || 5;
+        this.successThreshold = options.successThreshold || 2;
+        this.timeout = options.timeout || 30000;
+        this.resetTimeout = options.resetTimeout || 60000;
+
+        this.state = STATES.CLOSED;
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = null;
+        this.nextAttempt = null;
+
+        this.listeners = {
+            stateChange: [],
+            failure: [],
+            success: [],
+            rejected: []
+        };
+    }
+
+    async execute(fn, fallback = null) {
+        if (this.state === STATES.OPEN) {
+            if (Date.now() < this.nextAttempt) {
+                this._emit('rejected', { reason: 'Circuit is OPEN' });
+                if (fallback) return fallback();
+                throw new CircuitBreakerError(`Circuit ${this.name} is OPEN`, this.state);
+            }
+            this._transition(STATES.HALF_OPEN);
+        }
+
+        try {
+            const result = await this._executeWithTimeout(fn);
+            this._onSuccess();
+            return result;
+        } catch (error) {
+            this._onFailure(error);
+            if (fallback) return fallback();
+            throw error;
+        }
+    }
+
+    async _executeWithTimeout(fn) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Circuit ${this.name} timeout after ${this.timeout}ms`));
+            }, this.timeout);
+
+            Promise.resolve(fn())
+                .then(result => {
+                    clearTimeout(timer);
+                    resolve(result);
+                })
+                .catch(error => {
+                    clearTimeout(timer);
+                    reject(error);
+                });
+        });
+    }
+
+    _onSuccess() {
+        this.failures = 0;
+        this._emit('success', { state: this.state });
+
+        if (this.state === STATES.HALF_OPEN) {
+            this.successes++;
+            if (this.successes >= this.successThreshold) {
+                this._transition(STATES.CLOSED);
+            }
+        }
+    }
+
+    _onFailure(error) {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        this._emit('failure', { error, failures: this.failures, state: this.state });
+
+        if (this.state === STATES.HALF_OPEN) {
+            this._transition(STATES.OPEN);
+        } else if (this.failures >= this.failureThreshold) {
+            this._transition(STATES.OPEN);
+        }
+    }
+
+    _transition(newState) {
+        const oldState = this.state;
+        this.state = newState;
+
+        if (newState === STATES.OPEN) {
+            this.nextAttempt = Date.now() + this.resetTimeout;
+            this.successes = 0;
+        } else if (newState === STATES.CLOSED) {
+            this.failures = 0;
+            this.successes = 0;
+            this.nextAttempt = null;
+        } else if (newState === STATES.HALF_OPEN) {
+            this.successes = 0;
+        }
+
+        this._emit('stateChange', { from: oldState, to: newState });
+    }
+
+    on(event, callback) {
+        if (this.listeners[event]) {
+            this.listeners[event].push(callback);
+        }
+        return this;
+    }
+
+    _emit(event, data) {
+        if (this.listeners[event]) {
+            for (const callback of this.listeners[event]) {
+                try {
+                    callback({ ...data, circuitName: this.name, timestamp: Date.now() });
+                } catch (listenerError) {
+                    if (process.env.DEBUG) {
+                        process.stderr.write(`[CircuitBreaker] Listener error: ${listenerError.message}\n`);
+                    }
+                }
+            }
+        }
+    }
+
+    getState() {
+        return {
+            name: this.name,
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            lastFailureTime: this.lastFailureTime,
+            nextAttempt: this.nextAttempt,
+            isOpen: this.state === STATES.OPEN,
+            isClosed: this.state === STATES.CLOSED,
+            isHalfOpen: this.state === STATES.HALF_OPEN
+        };
+    }
+
+    reset() {
+        this._transition(STATES.CLOSED);
+    }
+
+    forceOpen() {
+        this._transition(STATES.OPEN);
+    }
+}
+
+class CircuitBreakerError extends Error {
+    constructor(message, state) {
+        super(message);
+        this.name = 'CircuitBreakerError';
+        this.state = state;
+    }
+}
+
+class CircuitBreakerRegistry {
+    constructor() {
+        this.breakers = new Map();
+    }
+
+    get(name, options = {}) {
+        if (!this.breakers.has(name)) {
+            this.breakers.set(name, new CircuitBreaker({ name, ...options }));
+        }
+        return this.breakers.get(name);
+    }
+
+    getAll() {
+        const result = {};
+        for (const [name, breaker] of this.breakers) {
+            result[name] = breaker.getState();
+        }
+        return result;
+    }
+
+    resetAll() {
+        for (const [, breaker] of this.breakers) {
+            breaker.reset();
+        }
+    }
+}
+
+const globalRegistry = new CircuitBreakerRegistry();
+
+const mcpCircuit = globalRegistry.get('mcp', {
+    failureThreshold: 3,
+    successThreshold: 2,
+    timeout: 5000,
+    resetTimeout: 30000
+});
+
+const gitCircuit = globalRegistry.get('git', {
+    failureThreshold: 5,
+    successThreshold: 2,
+    timeout: 10000,
+    resetTimeout: 60000
+});
+
+const astCircuit = globalRegistry.get('ast', {
+    failureThreshold: 3,
+    successThreshold: 1,
+    timeout: 15000,
+    resetTimeout: 45000
+});
+
+module.exports = {
+    CircuitBreaker,
+    CircuitBreakerError,
+    CircuitBreakerRegistry,
+    globalRegistry,
+    mcpCircuit,
+    gitCircuit,
+    astCircuit,
+    STATES
+};