@kabran-tecnologia/kabran-config 1.6.0 → 1.8.0

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

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

@@ -482,3 +482,107 @@ export function createMinimalResult({ projectName, passed = true }) {
     extensions: {},
   }
 }
+
+/**
+ * Get trace ID from environment variables
+ *
+ * Checks common OpenTelemetry and CI environment variables for trace IDs.
+ *
+ * @returns {string|null} Trace ID or null if not available
+ */
+export function getTraceId() {
+  // Direct trace ID from environment
+  if (process.env.OTEL_TRACE_ID) {
+    return process.env.OTEL_TRACE_ID
+  }
+
+  // W3C traceparent header format: 00-{trace_id}-{span_id}-{flags}
+  if (process.env.TRACEPARENT) {
+    const parts = process.env.TRACEPARENT.split('-')
+    if (parts.length >= 2) {
+      return parts[1]
+    }
+  }
+
+  // GitHub Actions run ID as fallback trace correlation
+  if (process.env.GITHUB_RUN_ID) {
+    return `gh-${process.env.GITHUB_RUN_ID}`
+  }
+
+  return null
+}
+
+/**
+ * Build trace URL from trace ID and endpoint
+ *
+ * @param {string} traceId - The trace ID
+ * @param {string} [endpoint] - OTel endpoint (default: from env)
+ * @param {string} [template] - URL template with {trace_id} placeholder
+ * @returns {string|null} Trace URL or null
+ */
+export function buildTraceUrl(traceId, endpoint = null, template = null) {
+  if (!traceId) return null
+
+  const otelEndpoint = endpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_ENDPOINT
+
+  // Use custom template if provided
+  if (template) {
+    return template.replace('{trace_id}', traceId).replace('{endpoint}', otelEndpoint || '')
+  }
+
+  // Use env template if available
+  if (process.env.OTEL_TRACE_URL_TEMPLATE) {
+    return process.env.OTEL_TRACE_URL_TEMPLATE.replace('{trace_id}', traceId).replace(
+      '{endpoint}',
+      otelEndpoint || ''
+    )
+  }
+
+  // Default Jaeger-style URL if endpoint is known
+  if (otelEndpoint) {
+    // Extract base URL from endpoint (remove /v1/traces if present)
+    const baseUrl = otelEndpoint.replace(/\/v1\/traces\/?$/, '').replace(/\/$/, '')
+    return `${baseUrl}/trace/${traceId}`
+  }
+
+  return null
+}
+
+/**
+ * Build telemetry extension object for ci-result.json
+ *
+ * @param {string} traceId - The trace ID
+ * @param {Object} [options] - Additional options
+ * @param {number} [options.spansExported] - Number of spans exported
+ * @param {number} [options.errorsRecorded] - Number of errors recorded
+ * @param {string} [options.endpoint] - OTel endpoint
+ * @returns {Object} Telemetry extension object
+ */
+export function buildTelemetryExtension(traceId, options = {}) {
+  const { spansExported = 0, errorsRecorded = 0, endpoint = null } = options
+
+  const extension = {
+    trace_id: traceId,
+    enabled: true,
+  }
+
+  // Add trace URL if we can build one
+  const traceUrl = buildTraceUrl(traceId, endpoint)
+  if (traceUrl) {
+    extension.trace_url = traceUrl
+  }
+
+  // Add metrics if provided
+  if (spansExported > 0 || errorsRecorded > 0) {
+    extension.spans_exported = spansExported
+    extension.errors_recorded = errorsRecorded
+  }
+
+  // Add endpoint info
+  const otelEndpoint = endpoint || process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_ENDPOINT
+  if (otelEndpoint) {
+    extension.collector_endpoint = otelEndpoint
+  }
+
+  return extension
+}

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

@@ -34,8 +34,14 @@ import {
   calculateExecutionStats,
   countIssues,
   extractComponents,
+  getTraceId,
+  buildTelemetryExtension,
 } from './ci-result-utils.mjs'
 
+// History and trends imports
+import { loadHistory, addToHistory, saveHistory } from './ci-result-history.mjs'
+import { calculateTrends } from './ci-result-trends.mjs'
+
 // Validator imports
 import { getLicenseCheckResult } from './license-check.mjs'
 import { getReadmeCheckResult } from './readme-validator.mjs'
@@ -132,6 +138,7 @@ async function runValidators(projectRoot, options = {}) {
  * @param {Object} input.project - Project information
  * @param {Object} input.metadata - Additional metadata
  * @param {Object} input.validators - Validator results (from runValidators)
+ * @param {Object} input.trends - Pre-calculated trends (optional)
  * @returns {Object} CI result object
  */
 export function generateCiResult(input) {
@@ -143,6 +150,7 @@ export function generateCiResult(input) {
     metadata = {},
     issues = [],
     validators = {},
+    trends = null,
   } = input
 
   const now = new Date().toISOString()
@@ -169,19 +177,49 @@ export function generateCiResult(input) {
   // Determine exit code
   const exitCode = executionStats.steps_failed > 0 ? 1 : 0
 
+  // Get trace ID - prefer trace_context from input (shell-generated) over env vars
+  const traceContext = input.trace_context || {}
+  const traceId = traceContext.trace_id || getTraceId()
+
+  // Build meta object
+  const meta = {
+    generated_at: now,
+    generator: getGeneratorVersion(),
+    run_id: generateRunId(),
+    trigger: detectTrigger(),
+    branch: getGitBranch(),
+    commit: getGitCommit(),
+  }
+
+  // Add trace_id if available
+  if (traceId) {
+    meta.trace_id = traceId
+  }
+
+  // Build extensions with telemetry if trace_id exists
+  const extensions = { ...(metadata.extensions || {}) }
+  if (traceId) {
+    // Count errors from failed steps
+    const errorsRecorded = executionStats.steps_failed || 0
+
+    extensions.telemetry = buildTelemetryExtension(traceId, {
+      errorsRecorded,
+      // spans_exported remains 0 until we implement actual OTel export (GAP-004/Q12)
+      spansExported: 0,
+    })
+
+    // Add trace source info if available
+    if (traceContext.source) {
+      extensions.telemetry.trace_source = traceContext.source
+    }
+  }
+
   // Build result object
   const result = {
     $schema: 'https://kabran.dev/schemas/ci-result.v2.json',
     version: '1.0.0',
 
-    meta: {
-      generated_at: now,
-      generator: getGeneratorVersion(),
-      run_id: generateRunId(),
-      trigger: detectTrigger(),
-      branch: getGitBranch(),
-      commit: getGitCommit(),
-    },
+    meta,
 
     project: {
       name: project.name || 'unknown',
@@ -216,7 +254,12 @@ export function generateCiResult(input) {
     checks,
     issues,
     errors,
-    extensions: metadata.extensions || {},
+    extensions,
+  }
+
+  // Add trends if provided
+  if (trends) {
+    result.trends = trends
   }
 
   return result
@@ -236,6 +279,10 @@ function parseArgs(args) {
     skipReadme: false,
     skipEnv: false,
     skipQualityStandard: false,
+    trackHistory: false,
+    historyFile: null,
+    maxHistoryEntries: 30,
+    calculateTrends: false,
   }
 
   for (let i = 0; i < args.length; i++) {
@@ -259,6 +306,16 @@ function parseArgs(args) {
       options.skipEnv = true
     } else if (arg === '--skip-quality-standard') {
       options.skipQualityStandard = true
+    } else if (arg === '--track-history') {
+      options.trackHistory = true
+    } else if (arg === '--history-file') {
+      options.historyFile = args[++i]
+      options.trackHistory = true
+    } else if (arg === '--max-history') {
+      options.maxHistoryEntries = parseInt(args[++i], 10) || 30
+    } else if (arg === '--calculate-trends') {
+      options.calculateTrends = true
+      options.trackHistory = true
     } else if (arg === '--help' || arg === '-h') {
       console.log(`
 Usage: generate-ci-result.mjs [options]
@@ -273,6 +330,10 @@ Options:
   --skip-readme             Skip README check when running validators
   --skip-env                Skip env check when running validators
   --skip-quality-standard   Skip quality-standard check when running validators
+  --track-history           Track result in history file (max 30 entries)
+  --history-file <file>     Custom history file path (default: docs/quality/ci-result-history.json)
+  --max-history <n>         Maximum history entries to keep (default: 30)
+  --calculate-trends        Calculate and include trends from history
   -h, --help                Show this help message
 
 Input format:
@@ -362,15 +423,35 @@ async function main() {
       })
     }
 
+    // Determine paths
+    const outputPath = options.output || resolve(options.projectRoot, 'docs/quality/ci-result.json')
+    const historyPath = options.historyFile || resolve(options.projectRoot, 'docs/quality/ci-result-history.json')
+
+    // Load history and calculate trends if requested
+    let history = null
+    if (options.trackHistory || options.calculateTrends) {
+      history = loadHistory(historyPath)
+
+      // Calculate trends if requested
+      if (options.calculateTrends && history.entries.length > 0) {
+        input.trends = calculateTrends(history.entries)
+      }
+    }
+
     // Generate result
     const result = generateCiResult(input)
 
+    // Update history with new result
+    if (options.trackHistory && history) {
+      addToHistory(result, history)
+      saveHistory(history, historyPath, options.maxHistoryEntries)
+      console.log(`History updated: ${historyPath} (${history.entries.length} entries)`)
+    }
+
     // Output
     if (options.stdout) {
       console.log(JSON.stringify(result, null, 2))
     } else {
-      const outputPath = options.output || resolve(options.projectRoot, 'docs/quality/ci-result.json')
-
       // Ensure directory exists
       mkdirSync(dirname(outputPath), { recursive: true })
 

package/src/scripts/pr-quality-comment.mjs

@@ -142,12 +142,48 @@ export function generateComment(comparison, current, baseline) {
     }
   }
 
+  // Trends section (if available)
+  if (current.trends && current.trends.data?.total_runs > 1) {
+    lines.push(`### 📈 Trends`)
+    lines.push('')
+    lines.push(`| Metric | Direction | Change (7d) | Avg (30d) |`)
+    lines.push(`|--------|-----------|-------------|-----------|`)
+
+    const scoreTrend = current.trends.score
+    if (scoreTrend) {
+      const dirEmoji = scoreTrend.direction === 'improving' ? '📈' : scoreTrend.direction === 'degrading' ? '📉' : '➡️'
+      lines.push(`| Score | ${dirEmoji} ${scoreTrend.direction} | ${scoreTrend.change_7d !== null ? formatDiff(scoreTrend.change_7d) : 'N/A'} | ${scoreTrend.avg_30d || 'N/A'} |`)
+    }
+
+    const perfTrend = current.trends.performance
+    if (perfTrend && perfTrend.avg_30d) {
+      const dirEmoji = perfTrend.direction === 'improving' ? '📈' : perfTrend.direction === 'degrading' ? '📉' : '➡️'
+      const change7d = perfTrend.change_7d !== null ? `${(perfTrend.change_7d / 1000).toFixed(1)}s` : 'N/A'
+      lines.push(`| Duration | ${dirEmoji} ${perfTrend.direction} | ${change7d} | ${(perfTrend.avg_30d / 1000).toFixed(1)}s |`)
+    }
+
+    lines.push('')
+    lines.push(`<sub>Based on ${current.trends.data.total_runs} runs</sub>`)
+    lines.push('')
+  }
+
   // Timing info
   lines.push(`---`)
   lines.push(`<sub>`)
   lines.push(`⏱️ Duration: ${current.timing?.total_human || 'N/A'} | `)
   lines.push(`🔀 Branch: ${current.meta?.branch || 'N/A'} | `)
   lines.push(`📝 Commit: ${current.meta?.commit || 'N/A'}`)
+
+  // Add trace link if available
+  if (current.meta?.trace_id) {
+    const traceUrl = current.extensions?.telemetry?.trace_url
+    if (traceUrl) {
+      lines.push(` | 🔍 [Trace](${traceUrl})`)
+    } else {
+      lines.push(` | 🔍 Trace: ${current.meta.trace_id}`)
+    }
+  }
+
   lines.push(`</sub>`)
 
   return lines.join('\n')