@eduardbar/drift 1.2.0 → 1.4.0

package/src/trust-kpi-types.ts

@@ -0,0 +1,19 @@
+import type { MergeRiskLevel, TrustDiffContext } from './types.js'
+
+export interface ParsedTrustArtifact {
+  filePath: string
+  trustScore: number
+  mergeRisk: MergeRiskLevel
+  diffContext?: TrustDiffContext
+}
+
+export interface DiscoverResult {
+  files: string[]
+  diagnostics: import('./types.js').TrustKpiDiagnostic[]
+}
+
+export type DiffStatus = 'improved' | 'regressed' | 'neutral'
+
+export interface TrustKpiOptions {
+  cwd?: string
+}

package/src/trust-kpi.ts

@@ -0,0 +1,210 @@
+import { normalizeMergeRiskLevel } from './trust.js'
+import type { DriftTrustReport, MergeRiskLevel, TrustDiffTrendSummary, TrustKpiReport } from './types.js'
+import { discoverTrustJsonFiles } from './trust-kpi-fs.js'
+import { parseTrustArtifact } from './trust-kpi-parse.js'
+import type { ParsedTrustArtifact, TrustKpiOptions } from './trust-kpi-types.js'
+
+function round(value: number, decimals = 2): number {
+  return Number(value.toFixed(decimals))
+}
+
+function median(values: number[]): number | null {
+  if (values.length === 0) return null
+  const sorted = [...values].sort((a, b) => a - b)
+  const mid = Math.floor(sorted.length / 2)
+  if (sorted.length % 2 === 0) {
+    return round((sorted[mid - 1] + sorted[mid]) / 2)
+  }
+  return round(sorted[mid])
+}
+
+function average(values: number[]): number | null {
+  if (values.length === 0) return null
+  return round(values.reduce((sum, value) => sum + value, 0) / values.length)
+}
+
+
+function buildDiffTrend(records: ParsedTrustArtifact[]): TrustDiffTrendSummary {
+  const withDiff = records.filter((record) => record.diffContext)
+
+  if (withDiff.length === 0) {
+    return {
+      available: false,
+      samples: 0,
+      statusDistribution: {
+        improved: 0,
+        regressed: 0,
+        neutral: 0,
+      },
+      scoreDelta: {
+        average: null,
+        median: null,
+      },
+      issues: {
+        newTotal: 0,
+        resolvedTotal: 0,
+        netNew: 0,
+      },
+    }
+  }
+
+  const scoreDeltas = withDiff.map((record) => record.diffContext!.scoreDelta)
+  const newIssues = withDiff.reduce((sum, record) => sum + record.diffContext!.newIssues, 0)
+  const resolvedIssues = withDiff.reduce((sum, record) => sum + record.diffContext!.resolvedIssues, 0)
+
+  const statusDistribution = {
+    improved: withDiff.filter((record) => record.diffContext!.status === 'improved').length,
+    regressed: withDiff.filter((record) => record.diffContext!.status === 'regressed').length,
+    neutral: withDiff.filter((record) => record.diffContext!.status === 'neutral').length,
+  }
+
+  return {
+    available: true,
+    samples: withDiff.length,
+    statusDistribution,
+    scoreDelta: {
+      average: average(scoreDeltas),
+      median: median(scoreDeltas),
+    },
+    issues: {
+      newTotal: newIssues,
+      resolvedTotal: resolvedIssues,
+      netNew: newIssues - resolvedIssues,
+    },
+  }
+}
+
+const KPI_RATIO_DECIMALS = 4
+
+export function computeTrustKpis(input: string, options?: TrustKpiOptions): TrustKpiReport {
+  const cwd = options?.cwd ?? process.cwd()
+  const discovered = discoverTrustJsonFiles(input, cwd)
+
+  const records: ParsedTrustArtifact[] = []
+  const diagnostics = [...discovered.diagnostics]
+
+  for (const filePath of discovered.files) {
+    const parsed = parseTrustArtifact(filePath)
+    diagnostics.push(...parsed.diagnostics)
+    if (parsed.record) records.push(parsed.record)
+  }
+
+  const trustScores = records.map((record) => record.trustScore)
+  const mergeRiskDistribution: Record<MergeRiskLevel, number> = {
+    LOW: 0,
+    MEDIUM: 0,
+    HIGH: 0,
+    CRITICAL: 0,
+  }
+
+  for (const record of records) {
+    mergeRiskDistribution[record.mergeRisk] += 1
+  }
+
+  const highRiskCount = mergeRiskDistribution.HIGH + mergeRiskDistribution.CRITICAL
+
+  return {
+    generatedAt: new Date().toISOString(),
+    input,
+    files: {
+      matched: discovered.files.length,
+      parsed: records.length,
+      malformed: discovered.files.length - records.length,
+    },
+    prsEvaluated: records.length,
+    mergeRiskDistribution,
+    trustScore: {
+      average: average(trustScores),
+      median: median(trustScores),
+      min: trustScores.length > 0 ? Math.min(...trustScores) : null,
+      max: trustScores.length > 0 ? Math.max(...trustScores) : null,
+    },
+    highRiskRatio: records.length > 0 ? round(highRiskCount / records.length, KPI_RATIO_DECIMALS) : null,
+    diffTrend: buildDiffTrend(records),
+    diagnostics,
+  }
+}
+
+export function formatTrustKpiConsole(kpi: TrustKpiReport): string {
+  const parts = [
+    'drift kpi',
+    '',
+    `Input: ${kpi.input}`,
+    `Files matched: ${kpi.files.matched} | parsed: ${kpi.files.parsed} | malformed: ${kpi.files.malformed}`,
+    `PRs evaluated: ${kpi.prsEvaluated}`,
+    `Trust score (avg/median): ${kpi.trustScore.average ?? 'n/a'} / ${kpi.trustScore.median ?? 'n/a'}`,
+    `High-risk ratio (HIGH+CRITICAL): ${kpi.highRiskRatio == null ? 'n/a' : `${round(kpi.highRiskRatio * 100, 2)}%`}`,
+    `Merge risk distribution: LOW=${kpi.mergeRiskDistribution.LOW} MEDIUM=${kpi.mergeRiskDistribution.MEDIUM} HIGH=${kpi.mergeRiskDistribution.HIGH} CRITICAL=${kpi.mergeRiskDistribution.CRITICAL}`,
+  ]
+
+  if (kpi.diffTrend.available) {
+    const avgDelta = kpi.diffTrend.scoreDelta.average
+    const signedDelta = avgDelta == null ? 'n/a' : `${avgDelta >= 0 ? '+' : ''}${avgDelta}`
+    parts.push(
+      `Diff trend samples: ${kpi.diffTrend.samples} | avg score delta: ${signedDelta} | new/resolved: +${kpi.diffTrend.issues.newTotal}/-${kpi.diffTrend.issues.resolvedTotal}`,
+    )
+  } else {
+    parts.push('Diff trend samples: 0 (no diff_context found)')
+  }
+
+  if (kpi.diagnostics.length > 0) {
+    const errorCount = kpi.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length
+    const warningCount = kpi.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length
+    parts.push(`Diagnostics: ${errorCount} error(s), ${warningCount} warning(s)`) 
+  }
+
+  return parts.join('\n')
+}
+
+export function formatTrustKpiJson(kpi: TrustKpiReport): string {
+  return JSON.stringify(kpi, null, 2)
+}
+
+export function computeTrustKpisFromReports(reports: DriftTrustReport[]): TrustKpiReport {
+  const tempRecords: ParsedTrustArtifact[] = reports.reduce<ParsedTrustArtifact[]>((acc, report, index) => {
+      const mergeRisk = normalizeMergeRiskLevel(report.merge_risk)
+      if (!mergeRisk || typeof report.trust_score !== 'number') return acc
+      acc.push({
+        filePath: `report-${index + 1}`,
+        trustScore: report.trust_score,
+        mergeRisk,
+        diffContext: report.diff_context,
+      })
+      return acc
+    }, [])
+
+  const trustScores = tempRecords.map((record) => record.trustScore)
+  const mergeRiskDistribution: Record<MergeRiskLevel, number> = {
+    LOW: 0,
+    MEDIUM: 0,
+    HIGH: 0,
+    CRITICAL: 0,
+  }
+
+  for (const record of tempRecords) {
+    mergeRiskDistribution[record.mergeRisk] += 1
+  }
+
+  const highRiskCount = mergeRiskDistribution.HIGH + mergeRiskDistribution.CRITICAL
+
+  return {
+    generatedAt: new Date().toISOString(),
+    input: 'in-memory',
+    files: {
+      matched: reports.length,
+      parsed: tempRecords.length,
+      malformed: reports.length - tempRecords.length,
+    },
+    prsEvaluated: tempRecords.length,
+    mergeRiskDistribution,
+    trustScore: {
+      average: average(trustScores),
+      median: median(trustScores),
+      min: trustScores.length > 0 ? Math.min(...trustScores) : null,
+      max: trustScores.length > 0 ? Math.max(...trustScores) : null,
+    },
+    highRiskRatio: tempRecords.length > 0 ? round(highRiskCount / tempRecords.length, KPI_RATIO_DECIMALS) : null,
+    diffTrend: buildDiffTrend(tempRecords),
+    diagnostics: [],
+  }
+}

package/src/trust-policy.ts

@@ -0,0 +1,246 @@
+import type { DriftConfig, MergeRiskLevel, TrustGatePolicyPack, TrustGatePolicyPreset } from './types.js'
+
+export interface TrustGateOptions {
+  enabled?: boolean
+  minTrust?: number
+  maxRisk?: MergeRiskLevel
+}
+
+export interface TrustGatePolicyResolutionOptions {
+  branchName?: string
+  policyPack?: string
+  overrides?: TrustGateOptions
+}
+
+export interface TrustGatePolicyResolutionStep {
+  source: 'base' | 'policy-pack' | 'branch-preset' | 'overrides'
+  name: string
+  values: TrustGateOptions
+}
+
+export interface TrustGatePolicyExplanation {
+  effectivePolicy: TrustGateOptions
+  branchName?: string
+  selectedPolicyPack?: string
+  invalidPolicyPack?: string
+  steps: TrustGatePolicyResolutionStep[]
+}
+
+export const MERGE_RISK_ORDER: MergeRiskLevel[] = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL']
+
+const BRANCH_ENV_CANDIDATES = [
+  'DRIFT_BRANCH',
+  'GITHUB_HEAD_REF',
+  'GITHUB_REF_NAME',
+  'CI_COMMIT_REF_NAME',
+  'BRANCH_NAME',
+] as const
+
+const PATTERN_EXACT_BOOST = 10_000
+const PATTERN_STATIC_CHAR_WEIGHT = 10
+
+function formatTrustGatePolicyValues(values: TrustGateOptions): string {
+  const enabled = typeof values.enabled === 'boolean' ? String(values.enabled) : 'inherit'
+  const minTrust = typeof values.minTrust === 'number' ? String(values.minTrust) : 'inherit'
+  const maxRisk = values.maxRisk ?? 'inherit'
+  return `enabled=${enabled} minTrust=${minTrust} maxRisk=${maxRisk}`
+}
+
+export function normalizeMergeRiskLevel(value: string): MergeRiskLevel | undefined {
+  const normalized = value.toUpperCase()
+  return MERGE_RISK_ORDER.find((level) => level === normalized)
+}
+
+function branchPatternToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+function patternSpecificity(pattern: string): number {
+  const wildcardCount = (pattern.match(/\*/g) ?? []).length
+  const staticChars = pattern.replace(/\*/g, '').length
+  const exactBoost = wildcardCount === 0 ? PATTERN_EXACT_BOOST : 0
+  return exactBoost + staticChars * PATTERN_STATIC_CHAR_WEIGHT - wildcardCount
+}
+
+function resolvePresetsForBranch(
+  branchName: string,
+  presets: TrustGatePolicyPreset[] | undefined,
+): TrustGatePolicyPreset[] {
+  if (!presets || presets.length === 0) return []
+  const matched: Array<{ preset: TrustGatePolicyPreset; specificity: number; index: number }> = []
+
+  for (let index = 0; index < presets.length; index += 1) {
+    const preset = presets[index]
+    if (!preset?.branch) continue
+
+    const regex = branchPatternToRegExp(preset.branch)
+    if (!regex.test(branchName)) continue
+    matched.push({ preset, specificity: patternSpecificity(preset.branch), index })
+  }
+
+  matched.sort((a, b) => a.specificity - b.specificity || a.index - b.index)
+  return matched.map((entry) => entry.preset)
+}
+
+function normalizeMinTrust(value: unknown): number | undefined {
+  return typeof value === 'number' && !Number.isNaN(value) ? value : undefined
+}
+
+function normalizeMaxRisk(value: unknown): MergeRiskLevel | undefined {
+  if (typeof value !== 'string') return undefined
+  return normalizeMergeRiskLevel(value)
+}
+
+function normalizeTrustGateOptions(
+  source: { enabled?: unknown; minTrust?: unknown; maxRisk?: unknown } | undefined,
+): TrustGateOptions {
+  if (!source) return {}
+
+  return {
+    enabled: typeof source.enabled === 'boolean' ? source.enabled : undefined,
+    minTrust: normalizeMinTrust(source.minTrust),
+    maxRisk: normalizeMaxRisk(source.maxRisk),
+  }
+}
+
+function mergeTrustGateOptions(base: TrustGateOptions, layer: TrustGateOptions): TrustGateOptions {
+  return {
+    enabled: typeof layer.enabled === 'boolean' ? layer.enabled : base.enabled,
+    minTrust: layer.minTrust ?? base.minTrust,
+    maxRisk: layer.maxRisk ?? base.maxRisk,
+  }
+}
+
+function normalizeResolutionOptions(
+  branchNameOrOptions?: string | TrustGatePolicyResolutionOptions,
+  explicitOverrides?: TrustGateOptions,
+): TrustGatePolicyResolutionOptions {
+  if (typeof branchNameOrOptions === 'string') {
+    return {
+      branchName: branchNameOrOptions,
+      overrides: explicitOverrides,
+    }
+  }
+
+  if (!branchNameOrOptions) {
+    return { overrides: explicitOverrides }
+  }
+
+  return {
+    ...branchNameOrOptions,
+    overrides: explicitOverrides
+      ? mergeTrustGateOptions(normalizeTrustGateOptions(branchNameOrOptions.overrides), normalizeTrustGateOptions(explicitOverrides))
+      : branchNameOrOptions.overrides,
+  }
+}
+
+function resolvePolicyPack(
+  policyPacks: Record<string, TrustGatePolicyPack> | undefined,
+  policyPackName: string | undefined,
+): { name?: string; pack?: TrustGatePolicyPack; invalid?: string } {
+  const normalizedName = policyPackName?.trim()
+  if (!normalizedName) return {}
+  if (!policyPacks) return { name: normalizedName, invalid: normalizedName }
+
+  const pack = policyPacks[normalizedName]
+  if (!pack) return { name: normalizedName, invalid: normalizedName }
+  return { name: normalizedName, pack }
+}
+
+export function detectBranchName(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  for (const key of BRANCH_ENV_CANDIDATES) {
+    const value = env[key]?.trim()
+    if (value) return value
+  }
+  return undefined
+}
+
+export function explainTrustGatePolicy(
+  config: DriftConfig | undefined,
+  branchName?: string,
+  overrides?: TrustGateOptions,
+): TrustGatePolicyExplanation
+export function explainTrustGatePolicy(
+  config: DriftConfig | undefined,
+  options?: TrustGatePolicyResolutionOptions,
+): TrustGatePolicyExplanation
+export function explainTrustGatePolicy(
+  config: DriftConfig | undefined,
+  branchNameOrOptions?: string | TrustGatePolicyResolutionOptions,
+  explicitOverrides?: TrustGateOptions,
+): TrustGatePolicyExplanation {
+  const policy = config?.trustGate
+  const resolution = normalizeResolutionOptions(branchNameOrOptions, explicitOverrides)
+  const normalizedBranch = resolution.branchName?.trim()
+  const packResolution = resolvePolicyPack(policy?.policyPacks, resolution.policyPack)
+
+  const steps: TrustGatePolicyResolutionStep[] = []
+  const base = normalizeTrustGateOptions(policy)
+  let effective = base
+  steps.push({ source: 'base', name: 'trustGate', values: base })
+
+  if (packResolution.pack) {
+    const packOptions = normalizeTrustGateOptions(packResolution.pack)
+    effective = mergeTrustGateOptions(effective, packOptions)
+    steps.push({ source: 'policy-pack', name: packResolution.name ?? 'unknown', values: packOptions })
+  }
+
+  if (normalizedBranch) {
+    const matchedPresets = resolvePresetsForBranch(normalizedBranch, policy?.presets)
+    for (const preset of matchedPresets) {
+      const presetOptions = normalizeTrustGateOptions(preset)
+      effective = mergeTrustGateOptions(effective, presetOptions)
+      steps.push({ source: 'branch-preset', name: preset.branch, values: presetOptions })
+    }
+  }
+
+  const normalizedOverrides = normalizeTrustGateOptions(resolution.overrides)
+  if (Object.values(normalizedOverrides).some((value) => value !== undefined)) {
+    effective = mergeTrustGateOptions(effective, normalizedOverrides)
+    steps.push({ source: 'overrides', name: 'cli', values: normalizedOverrides })
+  }
+
+  return {
+    effectivePolicy: effective,
+    branchName: normalizedBranch,
+    selectedPolicyPack: packResolution.name,
+    invalidPolicyPack: packResolution.invalid,
+    steps,
+  }
+}
+
+export function resolveTrustGatePolicy(
+  config: DriftConfig | undefined,
+  branchName?: string,
+  overrides?: TrustGateOptions,
+): TrustGateOptions
+export function resolveTrustGatePolicy(
+  config: DriftConfig | undefined,
+  options?: TrustGatePolicyResolutionOptions,
+): TrustGateOptions
+export function resolveTrustGatePolicy(
+  config: DriftConfig | undefined,
+  branchNameOrOptions?: string | TrustGatePolicyResolutionOptions,
+  explicitOverrides?: TrustGateOptions,
+): TrustGateOptions {
+  const options = normalizeResolutionOptions(branchNameOrOptions, explicitOverrides)
+  return explainTrustGatePolicy(config, options).effectivePolicy
+}
+
+export function formatTrustGatePolicyExplanation(explanation: TrustGatePolicyExplanation): string {
+  const lines = ['Trust gate policy resolution:']
+  lines.push(`- branch: ${explanation.branchName ?? 'not provided'}`)
+  lines.push(`- policy pack: ${explanation.selectedPolicyPack ?? 'not selected'}`)
+  if (explanation.invalidPolicyPack) {
+    lines.push(`- invalid policy pack: ${explanation.invalidPolicyPack}`)
+  }
+  lines.push('- steps:')
+
+  for (const [index, step] of explanation.steps.entries()) {
+    lines.push(`  ${index + 1}. ${step.source} (${step.name}): ${formatTrustGatePolicyValues(step.values)}`)
+  }
+
+  lines.push(`- effective: ${formatTrustGatePolicyValues(explanation.effectivePolicy)}`)
+  return lines.join('\n')
+}

package/src/trust-render.ts

@@ -0,0 +1,61 @@
+import type { DriftTrustReport, TrustDiffContext, TrustFixPriority, TrustReason } from './types.js'
+
+export function renderTrustReasons(reasons: TrustReason[]): string {
+  if (reasons.length === 0) return '- none'
+  return reasons.map((reason) => `- ${reason.label}: ${reason.detail} (impact ${reason.impact})`).join('\n')
+}
+
+export function renderTrustPriorities(priorities: TrustFixPriority[]): string {
+  if (priorities.length === 0) return '- none'
+  return priorities
+    .map((priority) =>
+      `- #${priority.rank} ${priority.rule} (${priority.severity}, x${priority.occurrences}${priority.confidence ? `, confidence ${priority.confidence}` : ''}): ${priority.suggestion}`
+    )
+    .join('\n')
+}
+
+export function renderTrustMarkdownReasons(reasons: TrustReason[]): string {
+  if (reasons.length === 0) return '- none'
+  return reasons.map((reason) => `- **${reason.label}**: ${reason.detail} (impact ${reason.impact})`).join('\n')
+}
+
+export function renderTrustMarkdownPriorities(priorities: TrustFixPriority[]): string {
+  if (priorities.length === 0) return '- none'
+  return priorities
+    .map((priority) =>
+      `- #${priority.rank} \`${priority.rule}\` (${priority.severity}, x${priority.occurrences}, effort: ${priority.effort}${priority.confidence ? `, confidence: ${priority.confidence}` : ''}) - ${priority.suggestion}${priority.explanation ? ` ${priority.explanation}` : ''}`
+    )
+    .join('\n')
+}
+
+export function renderTrustDiffBlock(diffContext: TrustDiffContext | undefined): string {
+  if (!diffContext) {
+    return [
+      '- Base ref: not provided',
+      '- Diff-aware adjustment: not applied',
+    ].join('\n')
+  }
+
+  return [
+    `- Base ref: \`${diffContext.baseRef}\``,
+    `- Diff status: **${diffContext.status.toUpperCase()}**`,
+    `- Score delta: **${diffContext.scoreDelta >= 0 ? '+' : ''}${diffContext.scoreDelta}**`,
+    `- Issues: **+${diffContext.newIssues}** new / **-${diffContext.resolvedIssues}** resolved`,
+    `- Trust adjustment: **+${diffContext.penalty}** penalty / **-${diffContext.bonus}** bonus (net ${diffContext.netImpact >= 0 ? '+' : ''}${diffContext.netImpact})`,
+  ].join('\n')
+}
+
+export function renderTrustAdvancedComparison(advancedContext: DriftTrustReport['advanced_context']): string {
+  if (!advancedContext?.comparison) return '- Historical comparison not available'
+
+  return [
+    `- Source: \`${advancedContext.comparison.source}\``,
+    `- Trend: **${advancedContext.comparison.trend.toUpperCase()}**`,
+    `- Summary: ${advancedContext.comparison.summary}`,
+  ].join('\n')
+}
+
+export function renderTrustAdvancedGuidance(advancedContext: DriftTrustReport['advanced_context']): string {
+  if (!advancedContext?.team_guidance?.length) return '- none'
+  return advancedContext.team_guidance.map((item) => `- ${item}`).join('\n')
+}