@eduardbar/drift 1.3.0 → 1.5.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

@@ -1,25 +1,8 @@
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
-import { dirname, isAbsolute, resolve } from 'node:path'
-import { MERGE_RISK_ORDER, normalizeMergeRiskLevel } from './trust.js'
-import type { DriftTrustReport, MergeRiskLevel, TrustDiffContext, TrustDiffTrendSummary, TrustKpiDiagnostic, TrustKpiReport } from './types.js'
-
-interface ParsedTrustArtifact {
-  filePath: string
-  trustScore: number
-  mergeRisk: MergeRiskLevel
-  diffContext?: TrustDiffContext
-}
-
-interface DiscoverResult {
-  files: string[]
-  diagnostics: TrustKpiDiagnostic[]
-}
-
-const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next', 'build'])
-
-function toPosixPath(path: string): string {
-  return path.replace(/\\/g, '/')
-}
+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))
@@ -40,295 +23,6 @@ function average(values: number[]): number | null {
   return round(values.reduce((sum, value) => sum + value, 0) / values.length)
 }
 
-function listFilesRecursively(root: string): string[] {
-  if (!existsSync(root)) return []
-  const out: string[] = []
-  const stack = [root]
-
-  while (stack.length > 0) {
-    const current = stack.pop()!
-    for (const entry of readdirSync(current)) {
-      const fullPath = resolve(current, entry)
-      const info = statSync(fullPath)
-      if (info.isDirectory()) {
-        if (IGNORED_DIRECTORIES.has(entry)) continue
-        stack.push(fullPath)
-      } else {
-        out.push(fullPath)
-      }
-    }
-  }
-
-  return out
-}
-
-function isGlobPattern(input: string): boolean {
-  return /[*?[\]{}]/.test(input)
-}
-
-function escapeRegex(char: string): string {
-  return /[\\^$+?.()|{}\[\]]/.test(char) ? `\\${char}` : char
-}
-
-function globToRegex(pattern: string): RegExp {
-  const normalized = toPosixPath(pattern)
-  let expression = '^'
-
-  for (let index = 0; index < normalized.length; index += 1) {
-    const char = normalized[index]
-    const nextChar = normalized[index + 1]
-    const nextNextChar = normalized[index + 2]
-
-    if (char === '*' && nextChar === '*') {
-      if (nextNextChar === '/') {
-        expression += '(?:.*/)?'
-        index += 2
-        continue
-      }
-      expression += '.*'
-      index += 1
-      continue
-    }
-
-    if (char === '*') {
-      expression += '[^/]*'
-      continue
-    }
-
-    if (char === '?') {
-      expression += '[^/]'
-      continue
-    }
-
-    expression += escapeRegex(char)
-  }
-
-  expression += '$'
-  return new RegExp(expression)
-}
-
-function globBaseDir(pattern: string): string {
-  const normalized = toPosixPath(pattern)
-  const wildcardIndex = normalized.search(/[*?[\]{}]/)
-
-  if (wildcardIndex < 0) return dirname(pattern)
-
-  const prefix = normalized.slice(0, wildcardIndex)
-  const slashIndex = prefix.lastIndexOf('/')
-
-  if (slashIndex < 0) return '.'
-  if (slashIndex === 0) return '/'
-
-  return prefix.slice(0, slashIndex)
-}
-
-function discoverTrustJsonFiles(input: string, cwd: string): DiscoverResult {
-  const diagnostics: TrustKpiDiagnostic[] = []
-  const source = input.trim() || '.'
-
-  if (isGlobPattern(source)) {
-    const absolutePattern = isAbsolute(source) ? source : resolve(cwd, source)
-    const regex = globToRegex(toPosixPath(absolutePattern))
-    const base = resolve(cwd, globBaseDir(source))
-
-    if (!existsSync(base)) {
-      diagnostics.push({
-        level: 'error',
-        code: 'path-not-found',
-        message: `Glob base path does not exist: ${base}`,
-      })
-      return { files: [], diagnostics }
-    }
-
-    const matched = listFilesRecursively(base)
-      .filter((filePath) => regex.test(toPosixPath(filePath)))
-      .filter((filePath) => filePath.toLowerCase().endsWith('.json'))
-      .sort((a, b) => a.localeCompare(b))
-
-    return { files: matched, diagnostics }
-  }
-
-  const absolute = isAbsolute(source) ? source : resolve(cwd, source)
-  if (!existsSync(absolute)) {
-    diagnostics.push({
-      level: 'error',
-      code: 'path-not-found',
-      message: `Path does not exist: ${absolute}`,
-    })
-    return { files: [], diagnostics }
-  }
-
-  const info = statSync(absolute)
-  if (info.isDirectory()) {
-    const files = listFilesRecursively(absolute)
-      .filter((filePath) => filePath.toLowerCase().endsWith('.json'))
-      .sort((a, b) => a.localeCompare(b))
-    return { files, diagnostics }
-  }
-
-  if (info.isFile()) {
-    if (!absolute.toLowerCase().endsWith('.json')) {
-      diagnostics.push({
-        level: 'warning',
-        code: 'path-not-supported',
-        file: absolute,
-        message: 'Input file is not JSON; attempting to parse anyway',
-      })
-    }
-    return { files: [absolute], diagnostics }
-  }
-
-  diagnostics.push({
-    level: 'error',
-    code: 'path-not-supported',
-    message: `Path is neither a file nor directory: ${absolute}`,
-  })
-
-  return { files: [], diagnostics }
-}
-
-function isObjectLike(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-function normalizeDiffContext(raw: unknown): { diffContext?: TrustDiffContext; diagnostic?: TrustKpiDiagnostic } {
-  if (!isObjectLike(raw)) {
-    return {
-      diagnostic: {
-        level: 'warning',
-        code: 'invalid-diff-context',
-        message: 'diff_context is present but malformed; skipping diff trend fields for this artifact',
-      },
-    }
-  }
-
-  const baseRef = typeof raw.baseRef === 'string' ? raw.baseRef : 'unknown'
-  const status = raw.status
-  const scoreDelta = typeof raw.scoreDelta === 'number' && Number.isFinite(raw.scoreDelta) ? raw.scoreDelta : null
-  const newIssues = typeof raw.newIssues === 'number' && Number.isFinite(raw.newIssues) ? raw.newIssues : null
-  const resolvedIssues = typeof raw.resolvedIssues === 'number' && Number.isFinite(raw.resolvedIssues) ? raw.resolvedIssues : null
-  const filesChanged = typeof raw.filesChanged === 'number' && Number.isFinite(raw.filesChanged) ? raw.filesChanged : 0
-  const penalty = typeof raw.penalty === 'number' && Number.isFinite(raw.penalty) ? raw.penalty : 0
-  const bonus = typeof raw.bonus === 'number' && Number.isFinite(raw.bonus) ? raw.bonus : 0
-  const netImpact = typeof raw.netImpact === 'number' && Number.isFinite(raw.netImpact) ? raw.netImpact : 0
-
-  if (scoreDelta == null || newIssues == null || resolvedIssues == null) {
-    return {
-      diagnostic: {
-        level: 'warning',
-        code: 'invalid-diff-context',
-        message: 'diff_context is missing numeric scoreDelta/newIssues/resolvedIssues; skipping diff trend fields for this artifact',
-      },
-    }
-  }
-
-  const normalizedStatus = status === 'improved' || status === 'regressed' || status === 'neutral'
-    ? status
-    : scoreDelta < 0
-      ? 'improved'
-      : scoreDelta > 0
-        ? 'regressed'
-        : 'neutral'
-
-  return {
-    diffContext: {
-      baseRef,
-      status: normalizedStatus,
-      scoreDelta,
-      newIssues,
-      resolvedIssues,
-      filesChanged,
-      penalty,
-      bonus,
-      netImpact,
-    },
-  }
-}
-
-function parseTrustArtifact(filePath: string): { record?: ParsedTrustArtifact; diagnostics: TrustKpiDiagnostic[] } {
-  const diagnostics: TrustKpiDiagnostic[] = []
-
-  let rawContent = ''
-  try {
-    rawContent = readFileSync(filePath, 'utf8')
-  } catch (error) {
-    diagnostics.push({
-      level: 'error',
-      code: 'read-failed',
-      file: filePath,
-      message: error instanceof Error ? error.message : String(error),
-    })
-    return { diagnostics }
-  }
-
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(rawContent)
-  } catch (error) {
-    diagnostics.push({
-      level: 'error',
-      code: 'parse-failed',
-      file: filePath,
-      message: error instanceof Error ? error.message : String(error),
-    })
-    return { diagnostics }
-  }
-
-  if (!isObjectLike(parsed)) {
-    diagnostics.push({
-      level: 'error',
-      code: 'invalid-shape',
-      file: filePath,
-      message: 'Trust artifact must be a JSON object',
-    })
-    return { diagnostics }
-  }
-
-  const trustScore = parsed.trust_score
-  if (typeof trustScore !== 'number' || !Number.isFinite(trustScore)) {
-    diagnostics.push({
-      level: 'error',
-      code: 'invalid-shape',
-      file: filePath,
-      message: 'Missing numeric trust_score',
-    })
-    return { diagnostics }
-  }
-
-  const mergeRisk = typeof parsed.merge_risk === 'string'
-    ? normalizeMergeRiskLevel(parsed.merge_risk)
-    : undefined
-
-  if (!mergeRisk) {
-    diagnostics.push({
-      level: 'error',
-      code: 'invalid-shape',
-      file: filePath,
-      message: `Missing/invalid merge_risk (expected one of ${MERGE_RISK_ORDER.join(', ')})`,
-    })
-    return { diagnostics }
-  }
-
-  let diffContext: TrustDiffContext | undefined
-  if (parsed.diff_context !== undefined) {
-    const normalized = normalizeDiffContext(parsed.diff_context)
-    if (normalized.diagnostic) {
-      diagnostics.push({ ...normalized.diagnostic, file: filePath })
-    } else {
-      diffContext = normalized.diffContext
-    }
-  }
-
-  return {
-    record: {
-      filePath,
-      trustScore,
-      mergeRisk,
-      diffContext,
-    },
-    diagnostics,
-  }
-}
 
 function buildDiffTrend(records: ParsedTrustArtifact[]): TrustDiffTrendSummary {
   const withDiff = records.filter((record) => record.diffContext)
@@ -380,9 +74,7 @@ function buildDiffTrend(records: ParsedTrustArtifact[]): TrustDiffTrendSummary {
   }
 }
 
-export interface TrustKpiOptions {
-  cwd?: string
-}
+const KPI_RATIO_DECIMALS = 4
 
 export function computeTrustKpis(input: string, options?: TrustKpiOptions): TrustKpiReport {
   const cwd = options?.cwd ?? process.cwd()
@@ -427,7 +119,7 @@ export function computeTrustKpis(input: string, options?: TrustKpiOptions): Trus
       min: trustScores.length > 0 ? Math.min(...trustScores) : null,
       max: trustScores.length > 0 ? Math.max(...trustScores) : null,
     },
-    highRiskRatio: records.length > 0 ? round(highRiskCount / records.length, 4) : null,
+    highRiskRatio: records.length > 0 ? round(highRiskCount / records.length, KPI_RATIO_DECIMALS) : null,
     diffTrend: buildDiffTrend(records),
     diagnostics,
   }
@@ -511,7 +203,7 @@ export function computeTrustKpisFromReports(reports: DriftTrustReport[]): TrustK
       min: trustScores.length > 0 ? Math.min(...trustScores) : null,
       max: trustScores.length > 0 ? Math.max(...trustScores) : null,
     },
-    highRiskRatio: tempRecords.length > 0 ? round(highRiskCount / tempRecords.length, 4) : 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')
+}