@kabran-tecnologia/kabran-config 1.5.0 → 1.7.0

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

@@ -305,6 +305,125 @@ export function extractComponents(steps) {
   return Array.from(components).sort()
 }
 
+/**
+ * Aggregate coverage data from multiple test steps
+ *
+ * @param {Array} steps - Array of step results with coverage data
+ * @returns {Object|null} Aggregated coverage or null if no coverage data
+ */
+export function aggregateCoverage(steps) {
+  const coverageData = []
+
+  for (const step of steps) {
+    if (step.output?.coverage) {
+      coverageData.push({
+        component: step.component || 'default',
+        coverage: step.output.coverage,
+        tests: {
+          passed: step.output.passed || 0,
+          failed: step.output.failed || 0,
+          skipped: step.output.skipped || 0,
+        },
+      })
+    }
+  }
+
+  if (coverageData.length === 0) {
+    return null
+  }
+
+  // Calculate weighted average based on test count
+  let totalTests = 0
+  let weightedLines = 0
+  let weightedBranches = 0
+  let weightedFunctions = 0
+  let weightedStatements = 0
+
+  const byComponent = {}
+
+  for (const data of coverageData) {
+    const testCount = data.tests.passed + data.tests.failed
+    totalTests += testCount
+
+    const cov = data.coverage
+    if (cov.lines !== undefined) weightedLines += cov.lines * testCount
+    if (cov.branches !== undefined) weightedBranches += cov.branches * testCount
+    if (cov.functions !== undefined) weightedFunctions += cov.functions * testCount
+    if (cov.statements !== undefined) weightedStatements += cov.statements * testCount
+
+    byComponent[data.component] = {
+      ...data.coverage,
+      tests: data.tests,
+    }
+  }
+
+  // Calculate averages
+  const avgLines = totalTests > 0 ? Math.round((weightedLines / totalTests) * 10) / 10 : 0
+  const avgBranches = totalTests > 0 ? Math.round((weightedBranches / totalTests) * 10) / 10 : 0
+  const avgFunctions = totalTests > 0 ? Math.round((weightedFunctions / totalTests) * 10) / 10 : 0
+  const avgStatements = totalTests > 0 ? Math.round((weightedStatements / totalTests) * 10) / 10 : 0
+
+  return {
+    lines: avgLines,
+    branches: avgBranches,
+    functions: avgFunctions,
+    statements: avgStatements,
+    by_component: byComponent,
+  }
+}
+
+/**
+ * Compare two CI results and calculate diff
+ *
+ * @param {Object} current - Current CI result
+ * @param {Object} baseline - Baseline CI result (e.g., from main branch)
+ * @returns {Object} Comparison result with diffs
+ */
+export function compareCiResults(current, baseline) {
+  const scoreDiff = current.summary.score - baseline.summary.score
+  const issuesDiff = current.summary.total_issues - baseline.summary.total_issues
+  const blockingDiff = current.summary.blocking - baseline.summary.blocking
+
+  // Determine trend
+  let trend = 'stable'
+  if (scoreDiff > 5) trend = 'improving'
+  else if (scoreDiff < -5) trend = 'degrading'
+
+  // Compare coverage if available
+  let coverageDiff = null
+  if (current.checks?.test?.coverage && baseline.checks?.test?.coverage) {
+    coverageDiff = {
+      lines: (current.checks.test.coverage.lines || 0) - (baseline.checks.test.coverage.lines || 0),
+      branches: (current.checks.test.coverage.branches || 0) - (baseline.checks.test.coverage.branches || 0),
+      functions: (current.checks.test.coverage.functions || 0) - (baseline.checks.test.coverage.functions || 0),
+    }
+  }
+
+  return {
+    trend,
+    score: {
+      current: current.summary.score,
+      baseline: baseline.summary.score,
+      diff: scoreDiff,
+    },
+    issues: {
+      current: current.summary.total_issues,
+      baseline: baseline.summary.total_issues,
+      diff: issuesDiff,
+    },
+    blocking: {
+      current: current.summary.blocking,
+      baseline: baseline.summary.blocking,
+      diff: blockingDiff,
+    },
+    coverage: coverageDiff,
+    status: {
+      current: current.summary.status,
+      baseline: baseline.summary.status,
+    },
+  }
+}
+
 /**
  * Create a minimal valid CI result object
  *
@@ -363,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,36 @@ export function generateCiResult(input) {
   // Determine exit code
   const exitCode = executionStats.steps_failed > 0 ? 1 : 0
 
+  // Get trace ID if available
+  const traceId = 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) {
+    extensions.telemetry = buildTelemetryExtension(traceId)
+  }
+
   // 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 +241,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 +266,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 +293,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 +317,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 +410,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 })