@kabran-tecnologia/kabran-config 1.6.0 → 1.7.0

package/README.md

@@ -888,6 +888,283 @@ For detailed migration instructions from existing CI/CD scripts, see [CI-CD-MIGR
 
 ---
 
+## Telemetry (OpenTelemetry)
+
+Unified observability for Kabran projects. Distributed tracing, error tracking, and performance monitoring using OpenTelemetry.
+
+> **Optional Feature:** Telemetry dependencies are optional. Only install them if your project needs observability.
+
+### Quick Start
+
+```javascript
+// Frontend (React/Vite)
+import { initTelemetry, createSpan } from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+
+initTelemetry({ serviceName: 'my-app' })
+
+// Edge Functions (Supabase/Deno)
+import { withTelemetry, traceSupabaseQuery } from '@kabran-tecnologia/kabran-config/telemetry/edge'
+
+serve(withTelemetry('my-function', async (req, span) => {
+  const result = await traceSupabaseQuery('select', 'users', () => supabase.from('users').select())
+  return new Response(JSON.stringify(result.data))
+}))
+
+// Node.js Backend
+import { initTelemetry, telemetryMiddleware } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+await initTelemetry({ serviceName: 'my-api' })
+app.use(telemetryMiddleware())
+```
+
+### Installation
+
+Install the required peer dependencies only if using telemetry:
+
+```bash
+npm install --save-dev \
+  @opentelemetry/api@^1.9 \
+  @opentelemetry/sdk-trace-base@^1.28 \
+  @opentelemetry/exporter-trace-otlp-http@^0.56 \
+  @opentelemetry/resources@^1.28 \
+  @opentelemetry/semantic-conventions@^1.28 \
+  @opentelemetry/core@^1.28
+
+# Frontend additional
+npm install --save-dev \
+  @opentelemetry/sdk-trace-web@^1.28 \
+  @opentelemetry/instrumentation@^0.56 \
+  @opentelemetry/instrumentation-fetch@^0.56 \
+  @opentelemetry/instrumentation-document-load@^0.43 \
+  @opentelemetry/instrumentation-user-interaction@^0.43
+
+# Node.js additional
+npm install --save-dev @opentelemetry/sdk-trace-node@^1.28
+```
+
+### Frontend Module
+
+For browser/frontend applications (React, Vue, etc.):
+
+```javascript
+// main.tsx or App.tsx
+import { initTelemetry, createSpan, createAsyncSpan } from '@kabran-tecnologia/kabran-config/telemetry/frontend'
+
+// Initialize at app startup
+initTelemetry({
+  serviceName: 'my-frontend',
+  serviceVersion: '1.0.0',
+  endpoint: 'https://otel.example.com',
+})
+
+// Create custom spans for tracking operations
+function handleCheckout(items) {
+  return createSpan('checkout.process', (span) => {
+    span.setAttribute('items.count', items.length)
+    return processCheckout(items)
+  })
+}
+
+// Async operations
+async function fetchUserData(userId) {
+  return createAsyncSpan('user.fetch', async (span) => {
+    span.setAttribute('user.id', userId)
+    const response = await fetch(`/api/users/${userId}`)
+    return response.json()
+  })
+}
+```
+
+**Auto-instrumentation included:**
+
+- Fetch API requests
+- Document load performance
+- User interactions (click, submit)
+- Global error handlers
+
+### Edge Module (Supabase/Deno)
+
+For serverless/edge functions with immediate trace export:
+
+```javascript
+import { serve } from 'https://deno.land/std/http/server.ts'
+import { withTelemetry, traceSupabaseQuery, getTraceId } from '@kabran-tecnologia/kabran-config/telemetry/edge'
+
+serve(withTelemetry('user-api', async (req, span) => {
+  // Automatic HTTP attributes (method, url, status)
+  span.setAttribute('custom.attribute', 'value')
+
+  // Trace database queries
+  const { data, error } = await traceSupabaseQuery('select', 'users', () =>
+    supabase.from('users').select('*').limit(10)
+  )
+
+  if (error) {
+    return new Response(JSON.stringify({ error: error.message }), { status: 500 })
+  }
+
+  return new Response(JSON.stringify({ data, trace_id: getTraceId() }))
+}))
+```
+
+**Features:**
+
+- W3C Trace Context propagation
+- SimpleSpanProcessor for immediate export (serverless-friendly)
+- Supabase query wrapper with automatic attributes
+- Error response includes trace_id for debugging
+
+### Node.js Module
+
+For Node.js backends with Express/Fastify:
+
+```javascript
+import express from 'express'
+import { initTelemetry, telemetryMiddleware, createSpan } from '@kabran-tecnologia/kabran-config/telemetry/node'
+
+const app = express()
+
+// Initialize before routes
+await initTelemetry({
+  serviceName: 'my-api',
+  serviceVersion: '1.0.0',
+})
+
+// Add middleware (creates spans for all requests)
+app.use(telemetryMiddleware({
+  ignorePaths: ['/health', '/ready', '/metrics'],
+}))
+
+// Access span in handlers via req.span
+app.get('/users/:id', async (req, res) => {
+  req.span.setAttribute('user.id', req.params.id)
+  const user = await getUserById(req.params.id)
+  res.json(user)
+})
+
+// Graceful shutdown on SIGTERM/SIGINT
+```
+
+**Features:**
+
+- BatchSpanProcessor for efficient export
+- Express/Fastify middleware
+- Automatic request/response tracing
+- Parent context extraction from headers
+- Process signal handlers for graceful shutdown
+
+### Logger Module
+
+Structured logging with trace correlation:
+
+```javascript
+import { createLogger, createSpanLogger } from '@kabran-tecnologia/kabran-config/telemetry/logger'
+
+// Basic logger
+const logger = createLogger({
+  name: 'my-service',
+  level: 'info',
+  format: 'json', // or 'pretty'
+})
+
+logger.info('User logged in', { userId: '123' })
+
+// Span-aware logger (adds events to active span)
+const spanLogger = createSpanLogger(span)
+spanLogger.info('Processing started')
+spanLogger.error('Processing failed', { error: err.message })
+```
+
+### Configuration
+
+Configuration is resolved from multiple sources (in order of precedence):
+
+1. Explicit config object
+2. Environment variables (Vite-style: `VITE_*`)
+3. Environment variables (Node-style: `OTEL_*`)
+4. Smart defaults
+
+**Environment Variables:**
+
+| Variable | Vite Equivalent | Description | Default |
+|----------|-----------------|-------------|---------|
+| `OTEL_ENDPOINT` | `VITE_OTEL_ENDPOINT` | Collector endpoint URL | - |
+| `OTEL_ENABLED` | `VITE_OTEL_ENABLED` | Enable/disable telemetry | `true` in prod |
+| `SERVICE_NAME` | `VITE_SERVICE_NAME` | Service identifier | Required |
+| `SERVICE_VERSION` | `VITE_SERVICE_VERSION` | Service version | `1.0.0` |
+| `ENVIRONMENT` | `VITE_ENVIRONMENT` | Deployment environment | `development` |
+| `OTEL_SAMPLE_RATE` | `VITE_OTEL_SAMPLE_RATE` | Sampling rate (0.0-1.0) | `0.1` (10%) |
+
+**Programmatic Configuration:**
+
+```javascript
+import { defineTelemetryConfig } from '@kabran-tecnologia/kabran-config/telemetry/config'
+
+const config = defineTelemetryConfig({
+  serviceName: 'my-service',
+  serviceVersion: '1.0.0',
+  endpoint: 'https://otel.example.com',
+  environment: 'production',
+  sampleRate: 0.5, // 50% sampling
+  instrumentation: {
+    fetch: true,
+    documentLoad: true,
+    userInteraction: false,
+  },
+  resourceAttributes: {
+    'deployment.region': 'us-east-1',
+  },
+})
+```
+
+### API Reference
+
+**Frontend (`telemetry/frontend`):**
+
+- `initTelemetry(config)` - Initialize OpenTelemetry
+- `getTracer(name?)` - Get tracer instance
+- `getCurrentSpan()` - Get active span
+- `getTraceId()` - Get current trace ID
+- `createSpan(name, fn, attrs?)` - Create sync span
+- `createAsyncSpan(name, fn, attrs?)` - Create async span
+- `addSpanEvent(name, attrs?)` - Add event to current span
+- `setSpanAttributes(attrs)` - Set attributes on current span
+- `shutdownTelemetry()` - Graceful shutdown
+- `isInitialized()` - Check if initialized
+- `getConfig()` - Get resolved config
+
+**Edge (`telemetry/edge`):**
+
+- `withTelemetry(name, handler, config?)` - Wrap request handler
+- `traceSupabaseQuery(op, table, fn)` - Wrap Supabase query
+- `extractContext(headers)` - Extract W3C trace context
+- `injectContext(headers)` - Inject W3C trace context
+- `getTracer(name?)`, `getCurrentSpan()`, `getTraceId()`
+- `createSpan()`, `createAsyncSpan()`, `addSpanEvent()`, `setSpanAttributes()`
+- `shutdownTelemetry()`
+
+**Node (`telemetry/node`):**
+
+- `initTelemetry(config)` - Initialize OpenTelemetry
+- `telemetryMiddleware(options?)` - Express/Fastify middleware
+- `getTracer(name?)`, `getCurrentSpan()`, `getTraceId()`
+- `createSpan()`, `createAsyncSpan()`, `addSpanEvent()`, `setSpanAttributes()`
+- `shutdownTelemetry()`, `isInitialized()`, `getConfig()`
+
+**Logger (`telemetry/logger`):**
+
+- `createLogger(options)` - Create structured logger
+- `createSpanLogger(span)` - Create span-aware logger
+
+**Config (`telemetry/config`):**
+
+- `defineTelemetryConfig(config)` - Define configuration
+- `resolveConfig(config, env, mode)` - Resolve from sources
+- `validateConfig(config)` - Validate configuration
+- `detectEnabled(mode, env)` - Auto-detect if enabled
+
+---
+
 ## What's Included
 
 | Config | Description |
@@ -909,6 +1186,12 @@ For detailed migration instructions from existing CI/CD scripts, see [CI-CD-MIGR
 | `@kabran-tecnologia/kabran-config/scripts/ci/*` | Standardized CI pipeline runner and core functions |
 | `@kabran-tecnologia/kabran-config/scripts/deploy/*` | Standardized deployment orchestration |
 | `@kabran-tecnologia/kabran-config/scripts/setup` | Project setup CLI (`npx kabran-setup`) |
+| `@kabran-tecnologia/kabran-config/telemetry/config` | Telemetry configuration and validation |
+| `@kabran-tecnologia/kabran-config/telemetry/frontend` | OpenTelemetry for browser/frontend apps |
+| `@kabran-tecnologia/kabran-config/telemetry/edge` | OpenTelemetry for Supabase/Deno edge functions |
+| `@kabran-tecnologia/kabran-config/telemetry/node` | OpenTelemetry for Node.js backends |
+| `@kabran-tecnologia/kabran-config/telemetry/logger` | Structured logging with trace correlation |
+| `@kabran-tecnologia/kabran-config/telemetry/shared` | Shared telemetry utilities and types |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kabran-tecnologia/kabran-config",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Shared quality configurations, enforcement scripts, and CI/CD tooling for Kabran projects",
   "author": "Kabran",
   "license": "MIT",
@@ -33,8 +33,16 @@
     "./scripts/quality-standard-validator": "./src/scripts/quality-standard-validator.mjs",
     "./scripts/generate-ci-result": "./src/scripts/generate-ci-result.mjs",
     "./scripts/ci-result-utils": "./src/scripts/ci-result-utils.mjs",
+    "./scripts/ci-result-history": "./src/scripts/ci-result-history.mjs",
+    "./scripts/ci-result-trends": "./src/scripts/ci-result-trends.mjs",
     "./scripts/pr-quality-comment": "./src/scripts/pr-quality-comment.mjs",
-    "./schemas/ci-result": "./src/schemas/ci-result.v2.schema.json"
+    "./schemas/ci-result": "./src/schemas/ci-result.v2.schema.json",
+    "./telemetry/config": "./src/telemetry/config/index.mjs",
+    "./telemetry/frontend": "./src/telemetry/frontend/index.mjs",
+    "./telemetry/edge": "./src/telemetry/edge/index.mjs",
+    "./telemetry/node": "./src/telemetry/node/index.mjs",
+    "./telemetry/logger": "./src/telemetry/logger/index.mjs",
+    "./telemetry/shared": "./src/telemetry/shared/index.mjs"
   },
   "files": [
     "src",
@@ -52,6 +60,9 @@
     "ci",
     "cd",
     "deployment",
+    "telemetry",
+    "opentelemetry",
+    "observability",
     "kabran"
   ],
   "repository": {
@@ -76,7 +87,19 @@
     "prettier": ">=3.0.0",
     "prettier-plugin-tailwindcss": ">=0.5.0",
     "typescript": ">=5.0.0",
-    "typescript-eslint": ">=8.0.0"
+    "typescript-eslint": ">=8.0.0",
+    "@opentelemetry/api": ">=1.9.0",
+    "@opentelemetry/sdk-trace-web": ">=1.28.0",
+    "@opentelemetry/sdk-trace-node": ">=1.28.0",
+    "@opentelemetry/sdk-trace-base": ">=1.28.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.56.0",
+    "@opentelemetry/resources": ">=1.28.0",
+    "@opentelemetry/semantic-conventions": ">=1.28.0",
+    "@opentelemetry/core": ">=1.28.0",
+    "@opentelemetry/instrumentation": ">=0.56.0",
+    "@opentelemetry/instrumentation-fetch": ">=0.56.0",
+    "@opentelemetry/instrumentation-document-load": ">=0.43.0",
+    "@opentelemetry/instrumentation-user-interaction": ">=0.43.0"
   },
   "peerDependenciesMeta": {
     "eslint-plugin-jsdoc": {
@@ -84,6 +107,42 @@
     },
     "prettier-plugin-tailwindcss": {
       "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-web": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
+    "@opentelemetry/core": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-fetch": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-document-load": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-user-interaction": {
+      "optional": true
     }
   },
   "scripts": {
@@ -96,10 +155,6 @@
   },
   "devDependencies": {
     "bats": "^1.11.0",
-    "vitest": "^4.0.17",
-    "semantic-release": "^24.0.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "conventional-changelog-conventionalcommits": "^8.0.0"
+    "vitest": "^4.0.17"
   }
 }

package/src/schemas/ci-result.v2.schema.json

@@ -45,6 +45,10 @@
         "commit": {
           "type": "string",
           "description": "Git commit SHA (short or full)"
+        },
+        "trace_id": {
+          "type": "string",
+          "description": "OpenTelemetry trace ID for correlation with observability data"
         }
       }
     },
@@ -222,11 +226,132 @@
     "extensions": {
       "type": "object",
       "description": "Custom extensions for project-specific data",
+      "properties": {
+        "telemetry": {
+          "$ref": "#/$defs/telemetryExtension"
+        }
+      },
       "additionalProperties": true,
       "default": {}
+    },
+    "trends": {
+      "type": "object",
+      "description": "Trend analysis based on historical CI runs",
+      "properties": {
+        "score": {
+          "$ref": "#/$defs/metricTrend"
+        },
+        "performance": {
+          "$ref": "#/$defs/metricTrend"
+        },
+        "issues": {
+          "$ref": "#/$defs/metricTrend"
+        },
+        "data": {
+          "type": "object",
+          "properties": {
+            "total_runs": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total number of historical runs analyzed"
+            },
+            "branch_filter": {
+              "type": ["string", "null"],
+              "description": "Branch filter applied to history"
+            },
+            "calculated_at": {
+              "type": "string",
+              "format": "date-time",
+              "description": "When trends were calculated"
+            },
+            "date_range": {
+              "type": "object",
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "to": {
+                  "type": "string",
+                  "format": "date-time"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "$defs": {
+    "metricTrend": {
+      "type": "object",
+      "description": "Trend data for a single metric",
+      "properties": {
+        "direction": {
+          "type": "string",
+          "enum": ["improving", "degrading", "stable"],
+          "description": "Trend direction"
+        },
+        "current": {
+          "type": ["number", "null"],
+          "description": "Current value"
+        },
+        "change_7d": {
+          "type": ["number", "null"],
+          "description": "Change over last 7 days"
+        },
+        "change_30d": {
+          "type": ["number", "null"],
+          "description": "Change over last 30 days"
+        },
+        "avg_7d": {
+          "type": ["number", "null"],
+          "description": "7-day average"
+        },
+        "avg_30d": {
+          "type": ["number", "null"],
+          "description": "30-day average"
+        },
+        "data_points": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of data points used"
+        }
+      }
+    },
+    "telemetryExtension": {
+      "type": "object",
+      "description": "OpenTelemetry integration data",
+      "properties": {
+        "trace_id": {
+          "type": "string",
+          "description": "Trace ID for correlation"
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether telemetry is enabled"
+        },
+        "trace_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to view the trace"
+        },
+        "spans_exported": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of spans exported"
+        },
+        "errors_recorded": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of errors recorded"
+        },
+        "collector_endpoint": {
+          "type": "string",
+          "description": "OTel collector endpoint"
+        }
+      }
+    },
     "step": {
       "type": "object",
       "description": "Individual step result",

package/src/scripts/ci/ci-runner.sh

@@ -10,6 +10,64 @@ set -euo pipefail
 RUNNER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CORE_SCRIPT="$RUNNER_DIR/ci-core.sh"
 
+# ==============================================================================
+# Command Line Arguments
+# ==============================================================================
+
+show_help() {
+  cat << EOF
+Usage: $(basename "$0") [options]
+
+Kabran CI Runner - Execute project CI pipelines
+
+Options:
+  --list-scopes       List available scopes from ci-config.sh and exit
+  --scope <name>      Run only the specified scope (component)
+  --help              Show this help message and exit
+
+Environment Variables:
+  CI_SCOPE            Set the scope filter (default: all)
+  CI_VERBOSE          Enable verbose output (default: false)
+  CI_OUTPUT_FILE      Output file for legacy v1 format
+  CI_OUTPUT_FILE_V2   Output file for v2 format (default: docs/quality/ci-result.json)
+  CI_CONFIG_FILE      Path to project ci-config.sh
+
+Examples:
+  # Run all steps
+  $(basename "$0")
+
+  # Run only specific component
+  $(basename "$0") --scope app
+
+  # List available scopes
+  $(basename "$0") --list-scopes
+EOF
+}
+
+LIST_SCOPES=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --list-scopes)
+      LIST_SCOPES=true
+      shift
+      ;;
+    --scope)
+      CI_SCOPE="$2"
+      shift 2
+      ;;
+    --help|-h)
+      show_help
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      show_help
+      exit 1
+      ;;
+  esac
+done
+
 # Load core functions
 if [ ! -f "$CORE_SCRIPT" ]; then
   echo "ERROR: ci-core.sh not found at $CORE_SCRIPT" >&2
@@ -58,6 +116,33 @@ fi
 log_info "Loading project configuration: $CONFIG_FILE"
 source "$CONFIG_FILE"
 
+# ==============================================================================
+# List Scopes (if requested)
+# ==============================================================================
+
+if [ "$LIST_SCOPES" = "true" ]; then
+  echo "Available scopes in $PROJECT_NAME:"
+  echo ""
+
+  # Check if CI_COMPONENTS is defined (common pattern for monorepos)
+  if [ -n "${CI_COMPONENTS:-}" ]; then
+    echo "Components:"
+    for component in $CI_COMPONENTS; do
+      echo "  - $component"
+    done
+  elif declare -f list_scopes >/dev/null; then
+    # Project can define custom list_scopes function
+    list_scopes
+  else
+    echo "  all (single project - no components defined)"
+  fi
+
+  echo ""
+  echo "Usage: CI_SCOPE=<scope> $(basename "$0")"
+  echo "   or: $(basename "$0") --scope <scope>"
+  exit 0
+fi
+
 # ==============================================================================
 # Validate Configuration
 # ==============================================================================