@kabran-tecnologia/kabran-config 1.5.0 → 1.7.0

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
@@ -27,6 +85,7 @@ OUTPUT_FILE_V2="${CI_OUTPUT_FILE_V2:-docs/quality/ci-result.json}"
 VERBOSE="${CI_VERBOSE:-false}"
 PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"
 USE_V2="${CI_USE_V2:-true}"
+CI_SCOPE="${CI_SCOPE:-all}"  # Scope filter: "all" or component name (e.g., "app", "website")
 
 # Track errors (reinitialize to avoid issues with sourced scripts)
 ERRORS=()
@@ -57,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
 # ==============================================================================
@@ -80,6 +166,9 @@ fi
 log_info "Starting Kabran CI - $PROJECT_NAME"
 log_info "Working directory: $PROJECT_ROOT"
 log_info "CI Core Version: $CI_CORE_VERSION"
+if [ "$CI_SCOPE" != "all" ]; then
+  log_info "Scope: $CI_SCOPE (filtered)"
+fi
 echo ""
 
 # Start timing

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
+}

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

@@ -0,0 +1,296 @@
+/**
+ * CI Result Trends Module
+ *
+ * Calculates trends from historical CI run data.
+ * Analyzes score, performance, and issues over time.
+ *
+ * @module ci-result-trends
+ */
+
+import { filterByDays, filterByBranch } from './ci-result-history.mjs'
+
+/**
+ * Direction indicators for trends
+ */
+export const DIRECTION = {
+  IMPROVING: 'improving',
+  DEGRADING: 'degrading',
+  STABLE: 'stable',
+}
+
+/**
+ * Threshold for determining significant change (percentage)
+ */
+export const SIGNIFICANCE_THRESHOLD = 5
+
+/**
+ * Calculate average of numeric values
+ *
+ * @param {number[]} values - Array of numbers
+ * @returns {number} Average value
+ */
+export function calculateAverage(values) {
+  if (!values || values.length === 0) return 0
+  const sum = values.reduce((acc, val) => acc + (val || 0), 0)
+  return sum / values.length
+}
+
+/**
+ * Calculate percentage change between two values
+ *
+ * @param {number} oldValue - Previous value
+ * @param {number} newValue - Current value
+ * @returns {number} Percentage change (null if cannot calculate)
+ */
+export function calculatePercentageChange(oldValue, newValue) {
+  if (oldValue === 0) {
+    if (newValue === 0) return 0
+    return newValue > 0 ? 100 : -100
+  }
+  return ((newValue - oldValue) / Math.abs(oldValue)) * 100
+}
+
+/**
+ * Calculate absolute change between two values
+ *
+ * @param {number} oldValue - Previous value
+ * @param {number} newValue - Current value
+ * @returns {number} Absolute change
+ */
+export function calculateAbsoluteChange(oldValue, newValue) {
+  return newValue - oldValue
+}
+
+/**
+ * Determine direction of trend
+ *
+ * @param {number} changePercent - Percentage change
+ * @param {number} threshold - Significance threshold
+ * @param {boolean} higherIsBetter - Whether higher values are better
+ * @returns {string} Direction: 'improving', 'degrading', or 'stable'
+ */
+export function determineDirection(changePercent, threshold = SIGNIFICANCE_THRESHOLD, higherIsBetter = true) {
+  if (Math.abs(changePercent) < threshold) {
+    return DIRECTION.STABLE
+  }
+
+  const isPositive = changePercent > 0
+
+  if (higherIsBetter) {
+    return isPositive ? DIRECTION.IMPROVING : DIRECTION.DEGRADING
+  } else {
+    return isPositive ? DIRECTION.DEGRADING : DIRECTION.IMPROVING
+  }
+}
+
+/**
+ * Extract field values from history entries
+ *
+ * @param {Object[]} entries - History entries
+ * @param {string} field - Field path (dot notation supported)
+ * @returns {number[]} Array of values
+ */
+export function extractValues(entries, field) {
+  return entries.map((entry) => {
+    const parts = field.split('.')
+    let value = entry
+    for (const part of parts) {
+      value = value?.[part]
+    }
+    return typeof value === 'number' ? value : 0
+  })
+}
+
+/**
+ * Calculate trend for a specific metric
+ *
+ * @param {Object[]} entries - History entries (newest first)
+ * @param {string} field - Field path to analyze
+ * @param {boolean} higherIsBetter - Whether higher values are better
+ * @returns {Object} Trend object with direction and changes
+ */
+export function calculateMetricTrend(entries, field, higherIsBetter = true) {
+  if (!entries || entries.length === 0) {
+    return {
+      direction: DIRECTION.STABLE,
+      current: null,
+      change_7d: null,
+      change_30d: null,
+      avg_7d: null,
+      avg_30d: null,
+      data_points: 0,
+    }
+  }
+
+  const values = extractValues(entries, field)
+  const current = values[0] || 0
+
+  // Get entries by time period
+  const entries7d = filterByDays(entries, 7)
+  const entries30d = filterByDays(entries, 30)
+
+  const values7d = extractValues(entries7d, field)
+  const values30d = extractValues(entries30d, field)
+
+  const avg7d = calculateAverage(values7d)
+  const avg30d = calculateAverage(values30d)
+
+  // Calculate changes
+  const change7d = values7d.length > 1 ? calculateAbsoluteChange(values7d[values7d.length - 1], current) : null
+
+  const change30d = values30d.length > 1 ? calculateAbsoluteChange(values30d[values30d.length - 1], current) : null
+
+  // Determine direction based on 7d vs 30d averages
+  let direction = DIRECTION.STABLE
+  if (avg30d !== 0 && values7d.length >= 2 && values30d.length >= 2) {
+    const percentChange = calculatePercentageChange(avg30d, avg7d)
+    direction = determineDirection(percentChange, SIGNIFICANCE_THRESHOLD, higherIsBetter)
+  }
+
+  return {
+    direction,
+    current: Math.round(current * 100) / 100,
+    change_7d: change7d !== null ? Math.round(change7d * 100) / 100 : null,
+    change_30d: change30d !== null ? Math.round(change30d * 100) / 100 : null,
+    avg_7d: Math.round(avg7d * 100) / 100,
+    avg_30d: Math.round(avg30d * 100) / 100,
+    data_points: entries.length,
+  }
+}
+
+/**
+ * Calculate all trends from history entries
+ *
+ * @param {Object[]} entries - History entries (newest first)
+ * @param {string} [branch] - Optional branch filter
+ * @returns {Object} Complete trends object
+ */
+export function calculateTrends(entries, branch = null) {
+  // Filter by branch if specified
+  const filteredEntries = branch ? filterByBranch(entries, branch) : entries
+
+  if (!filteredEntries || filteredEntries.length === 0) {
+    return {
+      score: createEmptyTrend(),
+      performance: createEmptyTrend(),
+      issues: createEmptyTrend(),
+      data: {
+        total_runs: 0,
+        branch_filter: branch,
+        calculated_at: new Date().toISOString(),
+      },
+    }
+  }
+
+  return {
+    score: calculateMetricTrend(filteredEntries, 'score', true),
+    performance: calculateMetricTrend(filteredEntries, 'timing.total_ms', false),
+    issues: calculateMetricTrend(filteredEntries, 'summary.total_issues', false),
+    data: {
+      total_runs: filteredEntries.length,
+      branch_filter: branch,
+      calculated_at: new Date().toISOString(),
+      date_range: {
+        from: filteredEntries[filteredEntries.length - 1]?.generated_at,
+        to: filteredEntries[0]?.generated_at,
+      },
+    },
+  }
+}
+
+/**
+ * Create an empty trend object
+ *
+ * @returns {Object} Empty trend structure
+ */
+function createEmptyTrend() {
+  return {
+    direction: DIRECTION.STABLE,
+    current: null,
+    change_7d: null,
+    change_30d: null,
+    avg_7d: null,
+    avg_30d: null,
+    data_points: 0,
+  }
+}
+
+/**
+ * Calculate trends grouped by branch
+ *
+ * @param {Object[]} entries - History entries
+ * @returns {Object} Trends by branch
+ */
+export function calculateTrendsByBranch(entries) {
+  if (!entries || entries.length === 0) {
+    return {}
+  }
+
+  const branches = [...new Set(entries.map((e) => e.branch).filter(Boolean))]
+  const result = {}
+
+  for (const branch of branches) {
+    result[branch] = calculateTrends(entries, branch)
+  }
+
+  return result
+}
+
+/**
+ * Generate time series data for visualization
+ *
+ * @param {Object[]} entries - History entries
+ * @param {string} field - Field to extract
+ * @param {number} [limit] - Maximum data points
+ * @returns {Object[]} Time series array
+ */
+export function generateTimeSeries(entries, field, limit = 30) {
+  if (!entries || entries.length === 0) return []
+
+  const values = extractValues(entries, field)
+
+  return entries.slice(0, limit).map((entry, index) => ({
+    date: entry.generated_at,
+    value: values[index],
+    run_id: entry.run_id,
+    branch: entry.branch,
+  }))
+}
+
+/**
+ * Calculate summary statistics for trend display
+ *
+ * @param {Object} trends - Trends object from calculateTrends
+ * @returns {Object} Summary for display
+ */
+export function getTrendSummary(trends) {
+  const summaryLines = []
+
+  if (trends.score.direction !== DIRECTION.STABLE) {
+    const emoji = trends.score.direction === DIRECTION.IMPROVING ? '+' : '-'
+    const change = trends.score.change_7d !== null ? Math.abs(trends.score.change_7d) : 0
+    summaryLines.push(`Score ${trends.score.direction} (${emoji}${change} over 7d)`)
+  }
+
+  if (trends.performance.direction !== DIRECTION.STABLE) {
+    const emoji = trends.performance.direction === DIRECTION.IMPROVING ? '-' : '+'
+    const change = trends.performance.change_7d !== null ? Math.abs(trends.performance.change_7d / 1000) : 0
+    summaryLines.push(`Performance ${trends.performance.direction} (${emoji}${change.toFixed(1)}s over 7d)`)
+  }
+
+  if (trends.issues.direction !== DIRECTION.STABLE) {
+    const emoji = trends.issues.direction === DIRECTION.IMPROVING ? '-' : '+'
+    const change = trends.issues.change_7d !== null ? Math.abs(trends.issues.change_7d) : 0
+    summaryLines.push(`Issues ${trends.issues.direction} (${emoji}${change} over 7d)`)
+  }
+
+  return {
+    lines: summaryLines,
+    overall:
+      summaryLines.length === 0
+        ? 'stable'
+        : summaryLines.some((l) => l.includes('degrading'))
+          ? 'degrading'
+          : 'improving',
+  }
+}