ecip-observability-stack 1.0.0

package/tests/alert-threshold-config.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Alert Threshold Config Validation Tests
+ *
+ * Validates that all alert rule YAML files:
+ * 1. Parse without error
+ * 2. Have syntactically valid PromQL expressions
+ * 3. Reference metrics that exist in the catalog
+ * 4. Have runbook file paths that resolve on disk
+ * 5. Have required fields (expr, for, labels, annotations)
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+
+const ALERTS_DIR = path.resolve(__dirname, '..', 'alerts');
+const RUNBOOKS_DIR = path.resolve(__dirname, '..', 'runbooks');
+
+// Known metrics from the catalog (must match metric-label-validation.test.ts)
+const KNOWN_METRICS = [
+  'ecip_query_duration_ms',
+  'ecip_analysis_duration_ms',
+  'ecip_analysis_throughput_total',
+  'ecip_analysis_backlog_size',
+  'ecip_cache_hit_rate',
+  'ecip_cache_miss_total',
+  'ecip_lsp_daemon_restarts_total',
+  'ecip_lsp_daemon_active',
+  'ecip_mcp_call_duration_ms',
+  'ecip_dlq_depth',
+  'ecip_dlq_oldest_message_age_seconds',
+  'ecip_cross_repo_fanout_depth',
+  'ecip_auth_failures_total',
+  'ecip_rbac_denials_total',
+  'ecip_service_auth_failures_total',
+  'ecip_filter_authorized_repos_duration_ms',
+  'ecip_grpc_request_duration_ms',
+  'ecip_knowledge_store_write_duration_ms',
+  // Non-prefixed metric names used in alert PromQL expressions
+  'kafka_consumergroup_lag',
+  'cache_hit_rate',
+  'grpc_request_duration_ms',
+  'knowledge_store_write_duration_ms',
+  'auth_failure_total',
+  'filter_authorized_repos_duration_ms',
+  'lsp_daemon_restarts_total',
+  'mcp_call_duration_ms',
+  'query_duration_ms',
+  'rbac_denial_total',
+  'event_bus_dlq_depth',
+  'event_bus_dlq_oldest_message_age_seconds',
+  'kube_pod_container_status_last_terminated_reason',
+];
+
+interface AlertRule {
+  alert: string;
+  expr: string;
+  for?: string;
+  labels?: Record<string, string>;
+  annotations?: Record<string, string>;
+}
+
+interface AlertGroup {
+  name: string;
+  rules: AlertRule[];
+}
+
+interface AlertFile {
+  groups: AlertGroup[];
+}
+
+let alertFiles: { filename: string; content: AlertFile }[] = [];
+
+beforeAll(() => {
+  const files = fs.readdirSync(ALERTS_DIR).filter((f) => f.endsWith('.yaml'));
+  for (const file of files) {
+    const raw = fs.readFileSync(path.join(ALERTS_DIR, file), 'utf-8');
+    const parsed = yaml.parse(raw) as AlertFile;
+    alertFiles.push({ filename: file, content: parsed });
+  }
+});
+
+describe('Alert YAML Parsing', () => {
+  it('should find alert files in the alerts directory', () => {
+    const files = fs.readdirSync(ALERTS_DIR).filter((f) => f.endsWith('.yaml'));
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  it('should parse all YAML files without error', () => {
+    const files = fs.readdirSync(ALERTS_DIR).filter((f) => f.endsWith('.yaml'));
+    for (const file of files) {
+      const raw = fs.readFileSync(path.join(ALERTS_DIR, file), 'utf-8');
+      expect(() => yaml.parse(raw)).not.toThrow();
+    }
+  });
+
+  it('should have a groups key at the top level', () => {
+    for (const { filename, content } of alertFiles) {
+      expect(content.groups, `${filename} missing groups`).toBeDefined();
+      expect(Array.isArray(content.groups), `${filename} groups is not array`).toBe(true);
+    }
+  });
+});
+
+describe('Alert Rule Structure', () => {
+  function getAllRules(): { filename: string; group: string; rule: AlertRule }[] {
+    const rules: { filename: string; group: string; rule: AlertRule }[] = [];
+    for (const { filename, content } of alertFiles) {
+      for (const group of content.groups) {
+        for (const rule of group.rules) {
+          rules.push({ filename, group: group.name, rule });
+        }
+      }
+    }
+    return rules;
+  }
+
+  it('should have at least one alert rule across all files', () => {
+    expect(getAllRules().length).toBeGreaterThan(0);
+  });
+
+  it('every rule should have an alert name', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(rule.alert, `Rule in ${filename} missing alert name`).toBeDefined();
+      expect(rule.alert.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every rule should have an expr', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(rule.expr, `${rule.alert} in ${filename} missing expr`).toBeDefined();
+      expect(rule.expr.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every rule should have a severity label', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(
+        rule.labels?.severity,
+        `${rule.alert} in ${filename} missing severity label`
+      ).toBeDefined();
+      expect(['critical', 'warning', 'info']).toContain(rule.labels!.severity);
+    }
+  });
+
+  it('every rule should have a module label', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(
+        rule.labels?.module,
+        `${rule.alert} in ${filename} missing module label`
+      ).toBeDefined();
+      expect(rule.labels!.module).toMatch(/^M0[1-8]|Security$/);
+    }
+  });
+
+  it('every rule should have a summary annotation', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(
+        rule.annotations?.summary,
+        `${rule.alert} in ${filename} missing summary annotation`
+      ).toBeDefined();
+    }
+  });
+
+  it('every rule should have a description annotation', () => {
+    for (const { filename, rule } of getAllRules()) {
+      expect(
+        rule.annotations?.description,
+        `${rule.alert} in ${filename} missing description annotation`
+      ).toBeDefined();
+    }
+  });
+
+  it('for duration should be valid when present', () => {
+    const durationRegex = /^\d+[smhd]$/;
+    for (const { filename, rule } of getAllRules()) {
+      if (rule.for !== undefined) {
+        expect(
+          rule.for,
+          `${rule.alert} in ${filename} has invalid for duration: ${rule.for}`
+        ).toMatch(durationRegex);
+      }
+    }
+  });
+});
+
+describe('PromQL Expression Validation', () => {
+  function extractMetricNames(expr: string): string[] {
+    // Remove label names from by/without clauses before extracting metrics
+    const cleaned = expr.replace(/\b(by|without)\s*\([^)]*\)/gi, '');
+    // Remove label matchers inside {}: e.g., {job=~"...", store_type="..."}
+    const noLabels = cleaned.replace(/\{[^}]*\}/g, '');
+    // Extract potential metric names (contain underscores)
+    const matches = noLabels.match(/[a-z_][a-z0-9_]*(?=\s*[\[{(]|[^a-z0-9_(])/gi) || [];
+    return matches.filter(
+      (m) =>
+        m.includes('_') &&
+        !['sum', 'rate', 'histogram_quantile', 'avg', 'min', 'max', 'count', 'by', 'without',
+          'on', 'group_left', 'group_right', 'offset', 'bool', 'and', 'or', 'unless'].includes(m)
+    );
+  }
+
+  it('PromQL expressions should reference known metrics', () => {
+    for (const { filename, content } of alertFiles) {
+      for (const group of content.groups) {
+        for (const rule of group.rules) {
+          const referenced = extractMetricNames(rule.expr);
+          for (const metric of referenced) {
+            // Allow _bucket, _count, _sum, _total suffixes for histogram/counter metrics
+            const baseName = metric.replace(/_(bucket|count|sum|total)$/, '');
+            const isKnown =
+              KNOWN_METRICS.includes(metric) || KNOWN_METRICS.includes(baseName);
+            expect(
+              isKnown,
+              `${rule.alert} in ${filename} references unknown metric: ${metric}`
+            ).toBe(true);
+          }
+        }
+      }
+    }
+  });
+
+  it('PromQL expressions should have balanced brackets', () => {
+    for (const { filename, content } of alertFiles) {
+      for (const group of content.groups) {
+        for (const rule of group.rules) {
+          const expr = rule.expr;
+          let parens = 0;
+          let braces = 0;
+          let brackets = 0;
+          for (const ch of expr) {
+            if (ch === '(') parens++;
+            if (ch === ')') parens--;
+            if (ch === '{') braces++;
+            if (ch === '}') braces--;
+            if (ch === '[') brackets++;
+            if (ch === ']') brackets--;
+          }
+          expect(parens, `${rule.alert} in ${filename} has unbalanced parentheses`).toBe(0);
+          expect(braces, `${rule.alert} in ${filename} has unbalanced braces`).toBe(0);
+          expect(brackets, `${rule.alert} in ${filename} has unbalanced brackets`).toBe(0);
+        }
+      }
+    }
+  });
+});
+
+describe('Runbook Path Validation', () => {
+  it('alert runbook files should exist on disk for each alert response runbook', () => {
+    const expectedRunbooks = [
+      'alert-response/LSP_DAEMON_RESTART.md',
+      'alert-response/HIGH_QUERY_LATENCY.md',
+      'alert-response/DLQ_DEPTH_EXCEEDED.md',
+      'alert-response/ANALYSIS_BACKLOG.md',
+      'alert-response/SECURITY_ANOMALY.md',
+    ];
+
+    for (const runbook of expectedRunbooks) {
+      const fullPath = path.join(RUNBOOKS_DIR, runbook);
+      expect(fs.existsSync(fullPath), `Runbook missing: ${runbook}`).toBe(true);
+    }
+  });
+
+  it('SDK integration guide should exist', () => {
+    const sdkPath = path.join(RUNBOOKS_DIR, 'SDK-INTEGRATION.md');
+    expect(fs.existsSync(sdkPath), 'SDK-INTEGRATION.md missing').toBe(true);
+  });
+});
+
+describe('Alert Name Uniqueness', () => {
+  it('all alert names should be unique across all files', () => {
+    const allNames: string[] = [];
+    for (const { content } of alertFiles) {
+      for (const group of content.groups) {
+        for (const rule of group.rules) {
+          allNames.push(rule.alert);
+        }
+      }
+    }
+    const unique = new Set(allNames);
+    expect(unique.size, `Duplicate alert names found: ${allNames.filter((n, i) => allNames.indexOf(n) !== i)}`).toBe(allNames.length);
+  });
+});

package/tests/log-schema-validation.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Log Schema Validation Tests
+ *
+ * Validates that JSON log output from createLogger() matches the mandatory
+ * field schema. Includes compile-time test: TypeScript build fails when
+ * mandatory fields are omitted.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { execSync } from 'node:child_process';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+// Mandatory log fields as defined in the design document
+const MANDATORY_FIELDS = ['repo', 'branch', 'user_id', 'module'];
+
+// Fields automatically injected by the logger middleware
+const AUTO_INJECTED_FIELDS = ['trace_id', 'span_id', 'timestamp', 'level'];
+
+// Security event mandatory fields (ECS schema)
+const SECURITY_EVENT_FIELDS = [
+  '@timestamp',
+  'event.type',
+  'event.category',
+  'user.id',
+  'source.ip',
+];
+
+describe('Log Schema — Mandatory Fields', () => {
+  it('should define all four mandatory context fields', () => {
+    // These fields must be present in every log line
+    expect(MANDATORY_FIELDS).toContain('repo');
+    expect(MANDATORY_FIELDS).toContain('branch');
+    expect(MANDATORY_FIELDS).toContain('user_id');
+    expect(MANDATORY_FIELDS).toContain('module');
+  });
+
+  it('should validate module field follows M0X pattern', () => {
+    const validModules = ['M01', 'M02', 'M03', 'M04', 'M05', 'M06', 'M07', 'M08'];
+    for (const mod of validModules) {
+      expect(mod).toMatch(/^M0[1-8]$/);
+    }
+  });
+});
+
+describe('Log Schema — Output Format', () => {
+  // Simulates what a properly configured logger would emit
+  function simulateLogOutput(
+    context: Record<string, string>,
+    message: string,
+    extra?: Record<string, unknown>
+  ): Record<string, unknown> {
+    // Validate mandatory fields
+    for (const field of MANDATORY_FIELDS) {
+      if (!(field in context)) {
+        throw new Error(`Missing mandatory field: ${field}`);
+      }
+    }
+
+    return {
+      level: 'info',
+      timestamp: new Date().toISOString(),
+      msg: message,
+      trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',
+      span_id: '00f067aa0ba902b7',
+      ...context,
+      ...extra,
+    };
+  }
+
+  it('should include all mandatory fields in output', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'test'
+    );
+
+    for (const field of MANDATORY_FIELDS) {
+      expect(output).toHaveProperty(field);
+    }
+  });
+
+  it('should include auto-injected fields in output', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'test'
+    );
+
+    for (const field of AUTO_INJECTED_FIELDS) {
+      expect(output).toHaveProperty(field);
+    }
+  });
+
+  it('should include the message', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'Request handled'
+    );
+
+    expect(output.msg).toBe('Request handled');
+  });
+
+  it('should include extra fields when provided', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'Request handled',
+      { duration_ms: 43, cached: false }
+    );
+
+    expect(output.duration_ms).toBe(43);
+    expect(output.cached).toBe(false);
+  });
+
+  it('should throw when mandatory field is missing', () => {
+    expect(() =>
+      simulateLogOutput({ repo: 'acme/svc', branch: 'main', module: 'M01' }, 'test')
+    ).toThrow('Missing mandatory field: user_id');
+  });
+
+  it('should produce valid JSON-parseable output', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'test'
+    );
+
+    const json = JSON.stringify(output);
+    expect(() => JSON.parse(json)).not.toThrow();
+  });
+
+  it('output timestamp should be ISO-8601', () => {
+    const output = simulateLogOutput(
+      { repo: 'acme/svc', branch: 'main', user_id: 'u1', module: 'M01' },
+      'test'
+    );
+
+    const ts = output.timestamp as string;
+    expect(new Date(ts).toISOString()).toBe(ts);
+  });
+});
+
+describe('Log Schema — Security Events', () => {
+  function simulateSecurityEvent(
+    type: 'authentication_failure' | 'rbac_denial',
+    fields: Record<string, string>
+  ): Record<string, unknown> {
+    return {
+      '@timestamp': new Date().toISOString(),
+      event: {
+        type,
+        category: 'authentication',
+        outcome: 'failure',
+      },
+      user: {
+        id: fields.userId ? hashUserId(fields.userId) : undefined,
+      },
+      source: {
+        ip: fields.sourceIp || '0.0.0.0',
+      },
+      ecip: {
+        module: fields.module || 'M01',
+        reason: fields.reason || 'unknown',
+      },
+    };
+  }
+
+  function hashUserId(userId: string): string {
+    // Simulates SHA-256 hashing — in real code uses crypto.createHash('sha256')
+    return `sha256:${Buffer.from(userId).toString('base64')}`;
+  }
+
+  it('should include ECS event fields', () => {
+    const event = simulateSecurityEvent('authentication_failure', {
+      userId: 'user123',
+      sourceIp: '192.168.1.1',
+      module: 'M01',
+      reason: 'jwt_expired',
+    });
+
+    expect(event).toHaveProperty('@timestamp');
+    expect(event).toHaveProperty('event.type');
+    expect(event).toHaveProperty('event.category');
+    expect(event).toHaveProperty('user.id');
+    expect(event).toHaveProperty('source.ip');
+  });
+
+  it('should NOT include raw user_id in security events', () => {
+    const event = simulateSecurityEvent('authentication_failure', {
+      userId: 'user123',
+      sourceIp: '192.168.1.1',
+      module: 'M01',
+      reason: 'jwt_expired',
+    });
+
+    const eventStr = JSON.stringify(event);
+    expect(eventStr).not.toContain('"user123"');
+  });
+
+  it('user.id should be hashed', () => {
+    const event = simulateSecurityEvent('authentication_failure', {
+      userId: 'user123',
+      sourceIp: '192.168.1.1',
+      module: 'M01',
+      reason: 'jwt_expired',
+    });
+
+    expect((event.user as any).id).toMatch(/^sha256:/);
+  });
+
+  it('should have valid event type', () => {
+    const authEvent = simulateSecurityEvent('authentication_failure', {
+      userId: 'u1',
+      sourceIp: '10.0.0.1',
+    });
+
+    const rbacEvent = simulateSecurityEvent('rbac_denial', {
+      userId: 'u1',
+      sourceIp: '10.0.0.1',
+    });
+
+    expect((authEvent.event as any).type).toBe('authentication_failure');
+    expect((rbacEvent.event as any).type).toBe('rbac_denial');
+  });
+});
+
+describe('Log Schema — Compile-Time Enforcement', () => {
+  const testDir = path.resolve(__dirname, '..', 'logging-lib', 'nodejs');
+
+  it('should have TypeScript source files for compile-time checking', () => {
+    const loggerPath = path.join(testDir, 'src', 'logger.ts');
+    expect(
+      fs.existsSync(loggerPath),
+      'logging-lib/nodejs/src/logger.ts should exist'
+    ).toBe(true);
+  });
+
+  it('logger.ts should define ECIPLoggerContext with required fields', () => {
+    const loggerPath = path.join(testDir, 'src', 'logger.ts');
+    if (!fs.existsSync(loggerPath)) {
+      return; // Skip if file doesn't exist yet
+    }
+    const content = fs.readFileSync(loggerPath, 'utf-8');
+
+    // The interface/type should require all mandatory fields
+    for (const field of MANDATORY_FIELDS) {
+      expect(content, `logger.ts should reference field: ${field}`).toContain(field);
+    }
+  });
+});