ecip-observability-stack 1.0.0

package/ci/check-observability-contract.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * ECIP M08 — CI Gate: Observability Contract Checker
+ *
+ * Validates that a module satisfies the M08 instrumentation contract (§5).
+ * Run against any module directory to verify compliance.
+ *
+ * Usage:
+ *   node ci/check-observability-contract.js <module-dir>
+ *   node ci/check-observability-contract.js ../ecip-api-gateway
+ *
+ * Checks performed:
+ *   1. @ecip/observability (or ecip-observability for Python) is in dependencies
+ *   2. initTracer() is called in an entry-point file (before server start)
+ *   3. createLogger() / get_logger() is used in at least one handler
+ *   4. No console.log / print() in production source files
+ *
+ * Exit codes:
+ *   0 — all checks pass
+ *   1 — one or more checks failed
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const NODEJS_SDK = '@ecip/observability';
+const PYTHON_SDK = 'ecip-observability';
+
+const ENTRY_PATTERNS = [
+  /server\.[tj]sx?$/,
+  /app\.[tj]sx?$/,
+  /main\.[tj]sx?$/,
+  /instrument\.[tj]sx?$/,
+];
+
+const EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', 'coverage',
+  '__pycache__', '.venv', 'venv', '.mypy_cache',
+]);
+
+const EXCLUDED_FILE_PATTERNS = [
+  /\.test\.[tj]sx?$/,
+  /\.spec\.[tj]sx?$/,
+  /test_.*\.py$/,
+  /conftest\.py$/,
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function walkDir(dir, ext) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (EXCLUDED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full, ext));
+    } else if (ext.some((e) => entry.name.endsWith(e))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function isTestFile(filePath) {
+  const rel = path.basename(filePath);
+  return EXCLUDED_FILE_PATTERNS.some((p) => p.test(rel));
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+function checkNodeDependency(moduleDir) {
+  const pkgPath = path.join(moduleDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { skip: true };
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  if (allDeps[NODEJS_SDK]) {
+    return { pass: true, detail: `${NODEJS_SDK} found in package.json` };
+  }
+  return {
+    pass: false,
+    detail: `${NODEJS_SDK} is NOT in package.json dependencies. Run: npm install ${NODEJS_SDK}`,
+  };
+}
+
+function checkPythonDependency(moduleDir) {
+  const pyprojectPath = path.join(moduleDir, 'pyproject.toml');
+  const requirementsPath = path.join(moduleDir, 'requirements.txt');
+
+  if (!fs.existsSync(pyprojectPath) && !fs.existsSync(requirementsPath)) {
+    return { skip: true };
+  }
+
+  if (fs.existsSync(pyprojectPath)) {
+    const content = fs.readFileSync(pyprojectPath, 'utf8');
+    if (content.includes(PYTHON_SDK)) {
+      return { pass: true, detail: `${PYTHON_SDK} found in pyproject.toml` };
+    }
+  }
+
+  if (fs.existsSync(requirementsPath)) {
+    const content = fs.readFileSync(requirementsPath, 'utf8');
+    if (content.includes(PYTHON_SDK)) {
+      return { pass: true, detail: `${PYTHON_SDK} found in requirements.txt` };
+    }
+  }
+
+  return {
+    pass: false,
+    detail: `${PYTHON_SDK} is NOT in pyproject.toml or requirements.txt. Run: pip install ${PYTHON_SDK}`,
+  };
+}
+
+function checkInitTracer(moduleDir) {
+  // Check Node.js files
+  const tsFiles = walkDir(path.join(moduleDir, 'src'), ['.ts', '.tsx', '.js', '.jsx']);
+  for (const f of tsFiles) {
+    const content = fs.readFileSync(f, 'utf8');
+    if (content.includes('initTracer(') || content.includes('initTracer (')) {
+      return { pass: true, detail: `initTracer() found in ${path.relative(moduleDir, f)}` };
+    }
+  }
+
+  // Check Python files
+  const pyFiles = walkDir(path.join(moduleDir, 'src'), ['.py']);
+  for (const f of pyFiles) {
+    const content = fs.readFileSync(f, 'utf8');
+    if (content.includes('init_tracer(') || content.includes('init_tracer (')) {
+      return { pass: true, detail: `init_tracer() found in ${path.relative(moduleDir, f)}` };
+    }
+  }
+
+  return {
+    pass: false,
+    detail: 'initTracer() / init_tracer() not found in any source file under src/. See runbooks/SDK-INTEGRATION.md.',
+  };
+}
+
+function checkLoggerUsage(moduleDir) {
+  const tsFiles = walkDir(path.join(moduleDir, 'src'), ['.ts', '.tsx', '.js', '.jsx']);
+  for (const f of tsFiles) {
+    if (isTestFile(f)) continue;
+    const content = fs.readFileSync(f, 'utf8');
+    if (content.includes('createLogger(') || content.includes('createLogger (')) {
+      return { pass: true, detail: `createLogger() found in ${path.relative(moduleDir, f)}` };
+    }
+  }
+
+  const pyFiles = walkDir(path.join(moduleDir, 'src'), ['.py']);
+  for (const f of pyFiles) {
+    if (isTestFile(f)) continue;
+    const content = fs.readFileSync(f, 'utf8');
+    if (content.includes('get_logger(') || content.includes('get_logger (')) {
+      return { pass: true, detail: `get_logger() found in ${path.relative(moduleDir, f)}` };
+    }
+  }
+
+  return {
+    pass: false,
+    detail: 'No createLogger() / get_logger() usage found in src/. At least one handler must use the structured logger.',
+  };
+}
+
+function checkNoConsoleLog(moduleDir) {
+  const violations = [];
+
+  // Node.js: console.log / console.warn / console.error
+  const tsFiles = walkDir(path.join(moduleDir, 'src'), ['.ts', '.tsx', '.js', '.jsx']);
+  for (const f of tsFiles) {
+    if (isTestFile(f)) continue;
+    const lines = fs.readFileSync(f, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      if (/console\.(log|warn|error|info|debug)\s*\(/.test(line)) {
+        violations.push(`${path.relative(moduleDir, f)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+
+  // Python: print()
+  const pyFiles = walkDir(path.join(moduleDir, 'src'), ['.py']);
+  for (const f of pyFiles) {
+    if (isTestFile(f)) continue;
+    const lines = fs.readFileSync(f, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      // Match print( but not # print( in comments
+      if (/^\s*[^#]*\bprint\s*\(/.test(line)) {
+        violations.push(`${path.relative(moduleDir, f)}:${i + 1}: ${line.trim()}`);
+      }
+    });
+  }
+
+  if (violations.length === 0) {
+    return { pass: true, detail: 'No console.log/print() found in production code' };
+  }
+
+  return {
+    pass: false,
+    detail: `Found ${violations.length} console.log/print() violation(s):\n${violations.map((v) => `    ${v}`).join('\n')}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const moduleDir = process.argv[2];
+  if (!moduleDir) {
+    console.error('Usage: node check-observability-contract.js <module-directory>');
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(moduleDir);
+  if (!fs.existsSync(resolved)) {
+    console.error(`Directory not found: ${resolved}`);
+    process.exit(1);
+  }
+
+  console.log(`\n🔍 ECIP M08 — Observability Contract Check`);
+  console.log(`   Module: ${path.basename(resolved)}`);
+  console.log(`   Path:   ${resolved}\n`);
+
+  // Detect language
+  const hasPackageJson = fs.existsSync(path.join(resolved, 'package.json'));
+  const hasPyproject = fs.existsSync(path.join(resolved, 'pyproject.toml'));
+  const hasRequirements = fs.existsSync(path.join(resolved, 'requirements.txt'));
+  const isPython = hasPyproject || hasRequirements;
+  const isNode = hasPackageJson;
+
+  if (!isNode && !isPython) {
+    console.log('⚠️  No package.json or pyproject.toml found — cannot determine language. Skipping.');
+    process.exit(0);
+  }
+
+  const checks = [
+    { name: 'SDK Dependency', fn: isNode ? () => checkNodeDependency(resolved) : () => checkPythonDependency(resolved) },
+    { name: 'initTracer() Present', fn: () => checkInitTracer(resolved) },
+    { name: 'Logger Usage', fn: () => checkLoggerUsage(resolved) },
+    { name: 'No console.log/print()', fn: () => checkNoConsoleLog(resolved) },
+  ];
+
+  let failures = 0;
+  for (const check of checks) {
+    const result = check.fn();
+    if (result.skip) {
+      console.log(`  ⏭  ${check.name}: skipped (not applicable)`);
+      continue;
+    }
+    if (result.pass) {
+      console.log(`  ✅ ${check.name}: ${result.detail}`);
+    } else {
+      console.log(`  ❌ ${check.name}: FAILED`);
+      console.log(`     ${result.detail}`);
+      failures++;
+    }
+  }
+
+  console.log('');
+  if (failures > 0) {
+    console.log(`❌ ${failures} check(s) failed. Module is NOT compliant with the M08 observability contract.`);
+    console.log('   See: ecip-observability-stack/runbooks/SDK-INTEGRATION.md\n');
+    process.exit(1);
+  } else {
+    console.log('✅ All checks passed. Module is compliant with the M08 observability contract.\n');
+    process.exit(0);
+  }
+}
+
+main();

package/ci/eslint-plugin-ecip/index.js

@@ -0,0 +1,209 @@
+/**
+ * eslint-plugin-ecip — Shared ESLint rules for ECIP modules
+ *
+ * Enforces M08 observability contract:
+ *   1. No console.log/warn/error in production code (use @ecip/observability logger)
+ *   2. @ecip/observability must be imported in entry files
+ *   3. initTracer() must be called before server starts
+ *
+ * Usage in consuming module:
+ *   npm install --save-dev eslint-plugin-ecip
+ *   // .eslintrc.json
+ *   { "plugins": ["ecip"], "extends": ["plugin:ecip/recommended"] }
+ */
+
+'use strict';
+
+module.exports = {
+  rules: {
+    /**
+     * Rule: no-console-log
+     *
+     * Bans console.log, console.warn, console.error, console.info in
+     * production source files. Test files and scripts are excluded via
+     * the recommended config's overrides.
+     *
+     * Why: console.* bypasses the structured logging pipeline. Logs
+     * emitted via console are unstructured plaintext without trace_id,
+     * module, repo, or branch context. They cannot be queried, alerted
+     * on, or correlated with distributed traces.
+     */
+    'no-console-log': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow console.log/warn/error in production code — use @ecip/observability createLogger() instead',
+          recommended: true,
+        },
+        messages: {
+          noConsole:
+            'Do not use console.{{ method }}() in production code. Use createLogger() from @ecip/observability instead. See runbooks/SDK-INTEGRATION.md.',
+        },
+        schema: [],
+      },
+      create(context) {
+        return {
+          CallExpression(node) {
+            if (
+              node.callee.type === 'MemberExpression' &&
+              node.callee.object.type === 'Identifier' &&
+              node.callee.object.name === 'console' &&
+              node.callee.property.type === 'Identifier' &&
+              ['log', 'warn', 'error', 'info', 'debug', 'trace'].includes(
+                node.callee.property.name,
+              )
+            ) {
+              context.report({
+                node,
+                messageId: 'noConsole',
+                data: { method: node.callee.property.name },
+              });
+            }
+          },
+        };
+      },
+    },
+
+    /**
+     * Rule: require-observability-import
+     *
+     * Ensures that files matching entry-point patterns (server.ts,
+     * app.ts, main.ts, index.ts) import from '@ecip/observability'.
+     */
+    'require-observability-import': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Entry-point files must import @ecip/observability',
+          recommended: true,
+        },
+        messages: {
+          missingImport:
+            'Entry-point file must import from \'@ecip/observability\'. See runbooks/SDK-INTEGRATION.md for setup instructions.',
+        },
+        schema: [],
+      },
+      create(context) {
+        const filename = context.getFilename();
+        const isEntryPoint = /(?:server|app|main|index)\.[tj]sx?$/.test(filename);
+
+        if (!isEntryPoint) return {};
+
+        let hasObservabilityImport = false;
+
+        return {
+          ImportDeclaration(node) {
+            if (
+              node.source.value === '@ecip/observability' ||
+              node.source.value.startsWith('@ecip/observability/')
+            ) {
+              hasObservabilityImport = true;
+            }
+          },
+          'Program:exit'(node) {
+            if (!hasObservabilityImport) {
+              context.report({
+                node,
+                messageId: 'missingImport',
+              });
+            }
+          },
+        };
+      },
+    },
+
+    /**
+     * Rule: require-init-tracer
+     *
+     * Entry point files that import @ecip/observability must call
+     * initTracer() before any server/app.listen/fastify.listen call.
+     */
+    'require-init-tracer': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'initTracer() must be called in entry-point files before the server starts',
+          recommended: true,
+        },
+        messages: {
+          missingInitTracer:
+            'Entry-point imports @ecip/observability but does not call initTracer(). Tracer must be initialized before the server starts accepting requests.',
+        },
+        schema: [],
+      },
+      create(context) {
+        const filename = context.getFilename();
+        const isEntryPoint = /(?:server|app|main|index)\.[tj]sx?$/.test(filename);
+
+        if (!isEntryPoint) return {};
+
+        let hasObservabilityImport = false;
+        let hasInitTracer = false;
+
+        return {
+          ImportDeclaration(node) {
+            if (
+              node.source.value === '@ecip/observability' ||
+              node.source.value.startsWith('@ecip/observability/')
+            ) {
+              hasObservabilityImport = true;
+            }
+          },
+          CallExpression(node) {
+            if (
+              node.callee.type === 'Identifier' &&
+              node.callee.name === 'initTracer'
+            ) {
+              hasInitTracer = true;
+            }
+          },
+          'Program:exit'(node) {
+            if (hasObservabilityImport && !hasInitTracer) {
+              context.report({
+                node,
+                messageId: 'missingInitTracer',
+              });
+            }
+          },
+        };
+      },
+    },
+  },
+
+  configs: {
+    recommended: {
+      plugins: ['ecip'],
+      rules: {
+        'ecip/no-console-log': 'error',
+        'ecip/require-observability-import': 'error',
+        'ecip/require-init-tracer': 'error',
+      },
+      overrides: [
+        {
+          // Exclude test files and scripts from console.log ban
+          files: [
+            '**/*.test.ts',
+            '**/*.test.js',
+            '**/*.spec.ts',
+            '**/*.spec.js',
+            '**/test/**',
+            '**/tests/**',
+            '**/scripts/**',
+            '**/__tests__/**',
+          ],
+          rules: {
+            'ecip/no-console-log': 'off',
+          },
+        },
+        {
+          // Only check init-tracer and observability-import in entry points
+          files: ['**/src/**'],
+          rules: {
+            'ecip/require-observability-import': 'error',
+            'ecip/require-init-tracer': 'error',
+          },
+        },
+      ],
+    },
+  },
+};

package/ci/eslint-plugin-ecip/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "eslint-plugin-ecip",
+  "version": "1.0.0",
+  "description": "ESLint rules enforcing ECIP M08 observability contract — console.log ban, initTracer() requirement",
+  "main": "index.js",
+  "keywords": ["eslint", "eslintplugin", "ecip", "observability"],
+  "author": "ECIP Platform Team",
+  "license": "UNLICENSED",
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  }
+}

package/ci/github-actions-observability-gate.yaml

@@ -0,0 +1,180 @@
+# =============================================================================
+# ECIP M08 — CI Gate: Observability Contract Enforcement
+# =============================================================================
+# Runs on every PR that modifies a module's source code.
+# Enforces the M08 SDK integration contract (Design Doc §5).
+#
+# Checks:
+#   1. ESLint ecip/no-console-log + require-observability-import + require-init-tracer
+#   2. Ruff T20 (print() ban) for Python modules
+#   3. Observability contract check (dependency, initTracer, logger, console.log)
+#   4. promtool check rules (alert YAML validation)
+#   5. Dashboard JSON lint
+# =============================================================================
+
+name: M08 Observability CI Gate
+
+on:
+  pull_request:
+    paths:
+      - 'ecip-api-gateway/src/**'
+      - 'ecip-analysis-engine/src/**'
+      - 'ecip-knowledge-store/src/**'
+      - 'ecip-query-service/src/**'
+      - 'ecip-mcp-server/src/**'
+      - 'ecip-registry-service/src/**'
+      - 'ecip-event-bus/src/**'
+      - 'ecip-observability-stack/alerts/**'
+      - 'ecip-observability-stack/dashboards/**'
+      - 'ecip-observability-stack/collector/**'
+  push:
+    branches: [main]
+    paths:
+      - 'ecip-observability-stack/alerts/**'
+      - 'ecip-observability-stack/dashboards/**'
+
+jobs:
+  # -------------------------------------------------------------------------
+  # Job 1: Verify module observability contract (per-module)
+  # -------------------------------------------------------------------------
+  contract-check:
+    name: Observability Contract — ${{ matrix.module }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        module:
+          - ecip-api-gateway
+          - ecip-event-bus
+          - ecip-knowledge-store
+          - ecip-registry-service
+          # Uncomment as modules come online:
+          # - ecip-query-service   # M04 — Week 11
+          # - ecip-mcp-server      # M05 — Week 17
+          # - ecip-analysis-engine # M02 — Week 5 (Python)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Check observability contract
+        run: node ecip-observability-stack/ci/check-observability-contract.js ${{ matrix.module }}
+
+  # -------------------------------------------------------------------------
+  # Job 2: ESLint with ecip plugin (Node.js modules)
+  # -------------------------------------------------------------------------
+  eslint-ecip:
+    name: ESLint ecip rules — ${{ matrix.module }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        module:
+          - ecip-api-gateway
+          - ecip-event-bus
+          - ecip-knowledge-store
+          - ecip-registry-service
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install module dependencies
+        working-directory: ${{ matrix.module }}
+        run: npm ci --ignore-scripts
+
+      - name: Install ESLint plugin
+        working-directory: ${{ matrix.module }}
+        run: npm install --no-save eslint ../ecip-observability-stack/ci/eslint-plugin-ecip
+
+      - name: Run ESLint with ecip rules
+        working-directory: ${{ matrix.module }}
+        run: npx eslint src/ --plugin ecip --rule 'ecip/no-console-log: error' --rule 'ecip/require-observability-import: error' --rule 'ecip/require-init-tracer: error'
+
+  # -------------------------------------------------------------------------
+  # Job 3: Ruff (Python modules)
+  # -------------------------------------------------------------------------
+  ruff-check:
+    name: Ruff — ecip-analysis-engine
+    runs-on: ubuntu-latest
+    # Only run if analysis-engine files changed
+    if: contains(github.event.pull_request.changed_files, 'ecip-analysis-engine/')
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Ruff
+        run: pip install ruff>=0.2.0
+
+      - name: Run Ruff with print() ban
+        working-directory: ecip-analysis-engine
+        run: ruff check src/ --config ../ecip-observability-stack/ci/ruff-shared.toml
+
+  # -------------------------------------------------------------------------
+  # Job 4: Alert rule validation (promtool)
+  # -------------------------------------------------------------------------
+  alert-validation:
+    name: Alert rule validation
+    runs-on: ubuntu-latest
+    if: |
+      contains(join(github.event.pull_request.changed_files, ','), 'alerts/') ||
+      github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install promtool
+        run: |
+          PROM_VERSION="2.50.1"
+          wget -q "https://github.com/prometheus/prometheus/releases/download/v${PROM_VERSION}/prometheus-${PROM_VERSION}.linux-amd64.tar.gz"
+          tar xzf "prometheus-${PROM_VERSION}.linux-amd64.tar.gz"
+          sudo mv "prometheus-${PROM_VERSION}.linux-amd64/promtool" /usr/local/bin/
+
+      - name: Validate alert rules
+        run: promtool check rules ecip-observability-stack/alerts/*.yaml
+
+  # -------------------------------------------------------------------------
+  # Job 5: Dashboard JSON lint
+  # -------------------------------------------------------------------------
+  dashboard-lint:
+    name: Dashboard lint
+    runs-on: ubuntu-latest
+    if: |
+      contains(join(github.event.pull_request.changed_files, ','), 'dashboards/') ||
+      github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Lint dashboard JSON
+        run: node ecip-observability-stack/scripts/lint-dashboards.js
+
+  # -------------------------------------------------------------------------
+  # Job 6: M08 unit tests
+  # -------------------------------------------------------------------------
+  m08-tests:
+    name: M08 unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        working-directory: ecip-observability-stack
+        run: npm ci
+
+      - name: Run tests
+        working-directory: ecip-observability-stack
+        run: npm test