@kabran-tecnologia/kabran-config 1.6.0 → 1.8.0

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

@@ -27,6 +27,8 @@ NC='\033[0m'
 declare -a ERRORS=()
 declare -a STEP_RESULTS=()
 CI_START_TIME=""
+CI_TRACE_ID=""
+CI_SPAN_ID=""
 
 # ==============================================================================
 # Logging Functions
@@ -58,6 +60,128 @@ log_debug() {
   fi
 }
 
+# ==============================================================================
+# Trace Context Functions (OpenTelemetry W3C Trace Context)
+# ==============================================================================
+
+# Generate a random hex string of specified length
+# Usage: generate_hex_string 32
+generate_hex_string() {
+  local length="${1:-32}"
+  # Try multiple methods for generating random hex
+  if command -v openssl &>/dev/null; then
+    openssl rand -hex "$((length / 2))" 2>/dev/null
+  elif [ -r /dev/urandom ]; then
+    head -c "$((length / 2))" /dev/urandom | od -An -tx1 | tr -d ' \n' | head -c "$length"
+  else
+    # Fallback: use date + process ID + random
+    local seed="$$$(date +%s%N 2>/dev/null || date +%s)"
+    echo "$seed" | md5sum 2>/dev/null | head -c "$length" || echo "$seed" | head -c "$length"
+  fi
+}
+
+# Generate a W3C trace ID (32 hex chars = 128 bits)
+# Usage: generate_trace_id
+generate_trace_id() {
+  generate_hex_string 32
+}
+
+# Generate a W3C span ID (16 hex chars = 64 bits)
+# Usage: generate_span_id
+generate_span_id() {
+  generate_hex_string 16
+}
+
+# Initialize trace context for the CI run
+# Sets TRACEPARENT env var if not already set
+# Format: 00-{trace_id}-{span_id}-{flags}
+# Usage: setup_trace_context
+setup_trace_context() {
+  # Check if trace context already exists from environment
+  if [ -n "${TRACEPARENT:-}" ]; then
+    log_debug "Using existing TRACEPARENT: $TRACEPARENT"
+    # Extract trace_id and span_id from existing TRACEPARENT
+    CI_TRACE_ID=$(echo "$TRACEPARENT" | cut -d'-' -f2)
+    CI_SPAN_ID=$(echo "$TRACEPARENT" | cut -d'-' -f3)
+    return 0
+  fi
+
+  # Check for direct trace ID from environment
+  if [ -n "${OTEL_TRACE_ID:-}" ]; then
+    log_debug "Using OTEL_TRACE_ID: $OTEL_TRACE_ID"
+    CI_TRACE_ID="$OTEL_TRACE_ID"
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    return 0
+  fi
+
+  # Check for GitHub Actions run ID (use as fallback correlation)
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    log_debug "Using GitHub run ID for trace correlation"
+    # Create deterministic trace_id from GitHub run info
+    local gh_seed="${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT:-1}"
+    CI_TRACE_ID=$(echo "$gh_seed" | md5sum | head -c 32)
+    CI_SPAN_ID=$(generate_span_id)
+    TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+    export TRACEPARENT
+    log_debug "Generated TRACEPARENT from GitHub: $TRACEPARENT"
+    return 0
+  fi
+
+  # Generate new trace context for local execution
+  log_debug "Generating new trace context for local CI run"
+  CI_TRACE_ID=$(generate_trace_id)
+  CI_SPAN_ID=$(generate_span_id)
+  TRACEPARENT="00-${CI_TRACE_ID}-${CI_SPAN_ID}-01"
+  export TRACEPARENT
+
+  log_info "Trace ID: ${CI_TRACE_ID:0:8}... (local)"
+  log_debug "Full TRACEPARENT: $TRACEPARENT"
+  return 0
+}
+
+# Get the current trace ID
+# Usage: get_trace_id
+get_trace_id() {
+  echo "${CI_TRACE_ID:-}"
+}
+
+# Get trace context info for metadata
+# Usage: get_trace_context_json
+get_trace_context_json() {
+  local trace_id="${CI_TRACE_ID:-}"
+  local span_id="${CI_SPAN_ID:-}"
+  local traceparent="${TRACEPARENT:-}"
+
+  if [ -z "$trace_id" ]; then
+    echo "null"
+    return
+  fi
+
+  # Determine source of trace context
+  local source="local"
+  if [ -n "${GITHUB_RUN_ID:-}" ]; then
+    source="github"
+  elif [ -n "${OTEL_TRACE_ID:-}" ]; then
+    source="otel_env"
+  elif [ -n "${TRACEPARENT:-}" ] && [ "${CI_TRACE_ID:-}" != "$(echo "$TRACEPARENT" | cut -d'-' -f2)" ]; then
+    source="external"
+  fi
+
+  jq -n \
+    --arg trace_id "$trace_id" \
+    --arg span_id "$span_id" \
+    --arg traceparent "$traceparent" \
+    --arg source "$source" \
+    '{
+      trace_id: $trace_id,
+      span_id: $span_id,
+      traceparent: $traceparent,
+      source: $source
+    }'
+}
+
 # ==============================================================================
 # Version Compatibility Check
 # ==============================================================================
@@ -432,6 +556,10 @@ export_ci_data() {
   # Get scope
   local scope="${CI_SCOPE:-all}"
 
+  # Get trace context
+  local trace_context
+  trace_context=$(get_trace_context_json)
+
   # Generate intermediate data file for Node.js generator
   jq -n \
     --argjson steps "$steps_json" \
@@ -441,6 +569,7 @@ export_ci_data() {
     --arg finished_at "$now" \
     --arg project_name "$project_name" \
     --arg scope "$scope" \
+    --argjson trace_context "$trace_context" \
     '{
       steps: $steps,
       errors: $errors,
@@ -454,7 +583,8 @@ export_ci_data() {
       },
       metadata: {
         scope: $scope
-      }
+      },
+      trace_context: $trace_context
     }' > "$output_file"
 
   log_debug "CI data exported to: $output_file"

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
 # ==============================================================================
@@ -86,6 +171,9 @@ if [ "$CI_SCOPE" != "all" ]; then
 fi
 echo ""
 
+# Setup trace context (generates trace_id if not provided externally)
+setup_trace_context
+
 # Start timing
 ci_start
 

package/src/scripts/ci-result-history.mjs

@@ -0,0 +1,245 @@
+/**
+ * CI Result History Module
+ *
+ * Manages historical CI run data for trend analysis.
+ * Stores up to 30 recent runs in docs/quality/ci-result-history.json.
+ *
+ * @module ci-result-history
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Default maximum number of history entries to keep
+ */
+export const DEFAULT_MAX_ENTRIES = 30
+
+/**
+ * Extract a minimal history entry from a full CI result
+ *
+ * @param {Object} result - Full CI result object
+ * @returns {Object} Minimal history entry
+ */
+export function extractHistoryEntry(result) {
+  return {
+    run_id: result.meta?.run_id || 'unknown',
+    generated_at: result.meta?.generated_at || new Date().toISOString(),
+    branch: result.meta?.branch || 'unknown',
+    commit: result.meta?.commit || 'unknown',
+    score: result.summary?.score ?? 0,
+    status: result.summary?.status || 'unknown',
+    timing: {
+      total_ms: result.timing?.total_ms || 0,
+      total_human: result.timing?.total_human || '0ms',
+    },
+    summary: {
+      exit_code: result.summary?.exit_code ?? 0,
+      total_issues: result.summary?.total_issues ?? 0,
+      blocking: result.summary?.blocking ?? 0,
+      warnings: result.summary?.warnings ?? 0,
+    },
+  }
+}
+
+/**
+ * Load history from file
+ *
+ * @param {string} filePath - Path to history file
+ * @returns {Object} History object with entries array and metadata
+ */
+export function loadHistory(filePath) {
+  if (!existsSync(filePath)) {
+    return {
+      $schema: 'https://kabran.dev/schemas/ci-result-history.json',
+      version: '1.0.0',
+      meta: {
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        max_entries: DEFAULT_MAX_ENTRIES,
+      },
+      entries: [],
+    }
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf8')
+    const history = JSON.parse(content)
+
+    // Ensure entries is an array
+    if (!Array.isArray(history.entries)) {
+      history.entries = []
+    }
+
+    return history
+  } catch (error) {
+    // If file is corrupted, start fresh
+    return {
+      $schema: 'https://kabran.dev/schemas/ci-result-history.json',
+      version: '1.0.0',
+      meta: {
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        max_entries: DEFAULT_MAX_ENTRIES,
+        error: `Failed to load: ${error.message}`,
+      },
+      entries: [],
+    }
+  }
+}
+
+/**
+ * Prune history to maximum number of entries
+ *
+ * @param {Array} entries - History entries
+ * @param {number} maxEntries - Maximum entries to keep
+ * @returns {Array} Pruned entries (most recent first)
+ */
+export function pruneHistory(entries, maxEntries = DEFAULT_MAX_ENTRIES) {
+  if (!Array.isArray(entries)) {
+    return []
+  }
+
+  // Sort by generated_at descending (most recent first)
+  const sorted = [...entries].sort((a, b) => {
+    const dateA = new Date(a.generated_at || 0)
+    const dateB = new Date(b.generated_at || 0)
+    return dateB - dateA
+  })
+
+  // Keep only the most recent entries
+  return sorted.slice(0, maxEntries)
+}
+
+/**
+ * Add a CI result to history
+ *
+ * @param {Object} result - Full CI result object
+ * @param {Object} history - Existing history object
+ * @returns {Object} Updated history object
+ */
+export function addToHistory(result, history) {
+  const entry = extractHistoryEntry(result)
+
+  // Check for duplicate run_id
+  const existingIndex = history.entries.findIndex((e) => e.run_id === entry.run_id)
+
+  if (existingIndex >= 0) {
+    // Update existing entry
+    history.entries[existingIndex] = entry
+  } else {
+    // Add new entry at the beginning
+    history.entries.unshift(entry)
+  }
+
+  // Update metadata
+  history.meta = {
+    ...history.meta,
+    updated_at: new Date().toISOString(),
+  }
+
+  return history
+}
+
+/**
+ * Save history to file
+ *
+ * @param {Object} history - History object
+ * @param {string} filePath - Path to save
+ * @param {number} maxEntries - Maximum entries to keep
+ */
+export function saveHistory(history, filePath, maxEntries = DEFAULT_MAX_ENTRIES) {
+  // Prune before saving
+  history.entries = pruneHistory(history.entries, maxEntries)
+  history.meta.max_entries = maxEntries
+  history.meta.entry_count = history.entries.length
+
+  // Ensure directory exists
+  const dir = dirname(filePath)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  // Write file
+  writeFileSync(filePath, JSON.stringify(history, null, 2) + '\n')
+}
+
+/**
+ * Get entries for a specific branch
+ *
+ * @param {Array} entries - History entries
+ * @param {string} branch - Branch name to filter
+ * @returns {Array} Filtered entries
+ */
+export function filterByBranch(entries, branch) {
+  if (!branch) return entries
+  return entries.filter((e) => e.branch === branch)
+}
+
+/**
+ * Get entries within a date range
+ *
+ * @param {Array} entries - History entries
+ * @param {number} days - Number of days to include
+ * @returns {Array} Filtered entries
+ */
+export function filterByDays(entries, days) {
+  if (!days || days <= 0) return entries
+
+  const cutoff = new Date()
+  cutoff.setDate(cutoff.getDate() - days)
+
+  return entries.filter((e) => {
+    const date = new Date(e.generated_at)
+    return date >= cutoff
+  })
+}
+
+/**
+ * Get statistics from history
+ *
+ * @param {Array} entries - History entries
+ * @returns {Object} Statistics object
+ */
+export function getHistoryStats(entries) {
+  if (!entries || entries.length === 0) {
+    return {
+      total_runs: 0,
+      oldest_run: null,
+      newest_run: null,
+      unique_branches: 0,
+      branches: [],
+    }
+  }
+
+  const sorted = [...entries].sort((a, b) => {
+    return new Date(a.generated_at) - new Date(b.generated_at)
+  })
+
+  const branches = [...new Set(entries.map((e) => e.branch).filter(Boolean))]
+
+  return {
+    total_runs: entries.length,
+    oldest_run: sorted[0]?.generated_at || null,
+    newest_run: sorted[sorted.length - 1]?.generated_at || null,
+    unique_branches: branches.length,
+    branches,
+  }
+}
+
+/**
+ * Process a CI result and update history
+ *
+ * Convenience function that loads, updates, and saves history.
+ *
+ * @param {Object} result - Full CI result object
+ * @param {string} historyPath - Path to history file
+ * @param {number} maxEntries - Maximum entries to keep
+ * @returns {Object} Updated history object
+ */
+export function processHistory(result, historyPath, maxEntries = DEFAULT_MAX_ENTRIES) {
+  const history = loadHistory(historyPath)
+  addToHistory(result, history)
+  saveHistory(history, historyPath, maxEntries)
+  return history
+}