@eduardbar/drift 1.2.0 → 1.4.0

package/src/sarif.ts

@@ -0,0 +1,232 @@
+import { createRequire } from 'node:module'
+import type { DriftIssue, DriftReport } from './types.js'
+import type { DriftDiff } from './types.js'
+import { RULE_WEIGHTS } from './analyzer.js'
+
+const require = createRequire(import.meta.url)
+const { version: VERSION } = require('../package.json') as { version: string }
+
+const HTTPS_SCHEME = 'https:'
+const URL_SEPARATOR = '//'
+const SARIF_SCHEMA_HOST_AND_PATH = 'json.schemastore.org/sarif-2.1.0.json'
+const DRIFT_INFORMATION_HOST_AND_PATH = 'github.com/eduardbar/drift'
+const SARIF_SCHEMA_URL = `${HTTPS_SCHEME}${URL_SEPARATOR}${SARIF_SCHEMA_HOST_AND_PATH}`
+const DRIFT_INFORMATION_URI = `${HTTPS_SCHEME}${URL_SEPARATOR}${DRIFT_INFORMATION_HOST_AND_PATH}`
+
+export type SarifLevel = 'error' | 'warning' | 'note'
+
+export interface DriftSarifRule {
+  id: string
+  name?: string
+  shortDescription?: {
+    text: string
+  }
+  defaultConfiguration?: {
+    level: SarifLevel
+  }
+  properties?: {
+    weight?: number
+  }
+}
+
+export interface DriftSarifResult {
+  ruleId: string
+  level: SarifLevel
+  message: {
+    text: string
+  }
+  locations: Array<{
+    physicalLocation: {
+      artifactLocation: {
+        uri: string
+      }
+      region: {
+        startLine: number
+        startColumn: number
+      }
+    }
+  }>
+  properties?: {
+    weight?: number
+    fileScore?: number
+    driftSeverity: DriftIssue['severity']
+    baseRef?: string
+    scoreBefore?: number
+    scoreAfter?: number
+    scoreDelta?: number
+    changeType?: 'new-issue'
+  }
+}
+
+export interface DriftSarifRun {
+  tool: {
+    driver: {
+      name: string
+      version: string
+      informationUri: string
+      rules: DriftSarifRule[]
+    }
+  }
+  results: DriftSarifResult[]
+  properties: {
+    scannedAt: string
+    targetPath: string
+    totalIssues: number
+    totalScore: number
+    totalFiles: number
+    baseRef?: string
+    totalDelta?: number
+    newIssuesCount?: number
+    resolvedIssuesCount?: number
+  }
+}
+
+export interface DriftSarifLog {
+  $schema: string
+  version: '2.1.0'
+  runs: DriftSarifRun[]
+}
+
+interface SarifRunMetrics {
+  scannedAt: string
+  targetPath: string
+  totalIssues: number
+  totalScore: number
+  totalFiles: number
+  baseRef?: string
+  totalDelta?: number
+  newIssuesCount?: number
+  resolvedIssuesCount?: number
+}
+
+function mapSeverityToSarifLevel(severity: DriftIssue['severity']): SarifLevel {
+  switch (severity) {
+    case 'error':
+      return 'error'
+    case 'warning':
+      return 'warning'
+    default:
+      return 'note'
+  }
+}
+
+function normalizeArtifactUri(filePath: string): string {
+  return filePath.replaceAll('\\', '/')
+}
+
+function toSarifResult(
+  filePath: string,
+  fileScore: number,
+  issue: DriftIssue,
+  extraProperties?: Omit<NonNullable<DriftSarifResult['properties']>, 'weight' | 'fileScore' | 'driftSeverity'>,
+): DriftSarifResult {
+  const line = Math.max(issue.line, 1)
+  const column = Math.max(issue.column, 1)
+  const weight = RULE_WEIGHTS[issue.rule]?.weight
+
+  return {
+    ruleId: issue.rule,
+    level: mapSeverityToSarifLevel(issue.severity),
+    message: {
+      text: issue.message,
+    },
+    locations: [{
+      physicalLocation: {
+        artifactLocation: {
+          uri: normalizeArtifactUri(filePath),
+        },
+        region: {
+          startLine: line,
+          startColumn: column,
+        },
+      },
+    }],
+    properties: {
+      weight,
+      fileScore,
+      driftSeverity: issue.severity,
+      ...extraProperties,
+    },
+  }
+}
+
+function buildRules(results: DriftSarifResult[]): DriftSarifRule[] {
+  const byRule = new Map<string, DriftSarifRule>()
+
+  for (const result of results) {
+    if (byRule.has(result.ruleId)) continue
+
+    byRule.set(result.ruleId, {
+      id: result.ruleId,
+      name: result.ruleId,
+      shortDescription: {
+        text: `drift rule: ${result.ruleId}`,
+      },
+      defaultConfiguration: {
+        level: result.level,
+      },
+      properties: {
+        weight: result.properties?.weight,
+      },
+    })
+  }
+
+  return [...byRule.values()]
+}
+
+function buildSarifLog(results: DriftSarifResult[], metrics: SarifRunMetrics): DriftSarifLog {
+  return {
+    $schema: SARIF_SCHEMA_URL,
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'drift',
+          version: VERSION,
+          informationUri: DRIFT_INFORMATION_URI,
+          rules: buildRules(results),
+        },
+      },
+      results,
+      properties: metrics,
+    }],
+  }
+}
+
+export function toSarif(report: DriftReport): DriftSarifLog {
+  const results = report.files.flatMap((file) => file.issues.map((issue) => toSarifResult(file.path, file.score, issue)))
+
+  return buildSarifLog(results, {
+    scannedAt: report.scannedAt,
+    targetPath: report.targetPath,
+    totalIssues: report.totalIssues,
+    totalScore: report.totalScore,
+    totalFiles: report.totalFiles,
+  })
+}
+
+export function diffToSarif(diff: DriftDiff): DriftSarifLog {
+  const results = diff.files.flatMap((file) =>
+    file.newIssues.map((issue) =>
+      toSarifResult(file.path, file.scoreAfter, issue, {
+        baseRef: diff.baseRef,
+        scoreBefore: file.scoreBefore,
+        scoreAfter: file.scoreAfter,
+        scoreDelta: file.scoreDelta,
+        changeType: 'new-issue',
+      }),
+    ),
+  )
+
+  return buildSarifLog(results, {
+    scannedAt: diff.scannedAt,
+    targetPath: diff.projectPath,
+    totalIssues: diff.newIssuesCount,
+    totalScore: diff.totalScoreAfter,
+    totalFiles: diff.files.length,
+    baseRef: diff.baseRef,
+    totalDelta: diff.totalDelta,
+    newIssuesCount: diff.newIssuesCount,
+    resolvedIssuesCount: diff.resolvedIssuesCount,
+  })
+}

package/src/trust-advanced.ts

@@ -0,0 +1,99 @@
+import type { DriftReport, DriftTrustReport, TrustAdvancedComparison, TrustDiffContext, TrustFixPriority } from './types.js'
+import type { SnapshotEntry } from './snapshot.js'
+
+const SYSTEMIC_GUIDANCE_LIMIT = 2
+const TEAM_GUIDANCE_LIMIT = 3
+
+function buildComparisonFromPreviousTrust(
+  trustScore: number,
+  previousTrust: Partial<DriftTrustReport> | undefined,
+): TrustAdvancedComparison | undefined {
+  if (!previousTrust || typeof previousTrust.trust_score !== 'number') return undefined
+
+  const trustDelta = trustScore - previousTrust.trust_score
+  const trend = trustDelta > 0 ? 'improving' : trustDelta < 0 ? 'regressing' : 'stable'
+
+  return {
+    source: 'previous-trust-json',
+    trend,
+    summary: `Trust moved ${trustDelta >= 0 ? '+' : ''}${trustDelta} vs provided previous trust JSON.`,
+    trust_delta: trustDelta,
+    previous_trust_score: previousTrust.trust_score,
+    previous_merge_risk: previousTrust.merge_risk,
+  }
+}
+
+function buildComparisonFromSnapshotHistory(
+  report: DriftReport,
+  snapshots: SnapshotEntry[] | undefined,
+): TrustAdvancedComparison | undefined {
+  const lastSnapshot = snapshots && snapshots.length > 0 ? snapshots[snapshots.length - 1] : undefined
+  if (!lastSnapshot) return undefined
+
+  const snapshotScoreDelta = report.totalScore - lastSnapshot.score
+  const trend = snapshotScoreDelta < 0 ? 'improving' : snapshotScoreDelta > 0 ? 'regressing' : 'stable'
+  const snapshotContext = lastSnapshot.label
+    ? `${lastSnapshot.timestamp} (${lastSnapshot.label})`
+    : lastSnapshot.timestamp
+
+  return {
+    source: 'snapshot-history',
+    trend,
+    summary: `Drift score moved ${snapshotScoreDelta >= 0 ? '+' : ''}${snapshotScoreDelta} vs snapshot ${snapshotContext}.`,
+    snapshot_score_delta: snapshotScoreDelta,
+    snapshot_label: lastSnapshot.label || undefined,
+    snapshot_timestamp: lastSnapshot.timestamp,
+  }
+}
+
+function buildTeamGuidance(
+  priorities: TrustFixPriority[],
+  comparison: TrustAdvancedComparison | undefined,
+  diffContext: TrustDiffContext | undefined,
+): string[] {
+  const systemicTargets = priorities
+    .filter((priority) => priority.systemic)
+    .slice(0, SYSTEMIC_GUIDANCE_LIMIT)
+    .map((priority) => `${priority.rule} (x${priority.occurrences})`)
+
+  const guidance: string[] = []
+  if (systemicTargets.length > 0) {
+    guidance.push(`Start with systemic rules: ${systemicTargets.join(', ')}.`)
+  }
+
+  if (comparison?.trend === 'regressing') {
+    guidance.push('Trend regressed; freeze net-new debt in CI and assign owners per systemic rule.')
+  }
+
+  if (diffContext && diffContext.newIssues > 0) {
+    guidance.push(`Block net-new issue growth first (+${diffContext.newIssues} new issue(s) in diff context).`)
+  }
+
+  if (guidance.length === 0) {
+    guidance.push('Maintain current baseline and schedule periodic systemic debt cleanup by rule ownership.')
+  }
+
+  return guidance.slice(0, TEAM_GUIDANCE_LIMIT)
+}
+
+export function buildAdvancedContext(input: {
+  report: DriftReport
+  advancedOptions: {
+    enabled?: boolean
+    previousTrust?: Partial<DriftTrustReport>
+    snapshots?: SnapshotEntry[]
+  } | undefined
+  trustScore: number
+  fixPriorities: TrustFixPriority[]
+  diffContext: TrustDiffContext | undefined
+}): DriftTrustReport['advanced_context'] {
+  if (input.advancedOptions?.enabled !== true) return undefined
+
+  const comparison = buildComparisonFromPreviousTrust(input.trustScore, input.advancedOptions.previousTrust)
+    ?? buildComparisonFromSnapshotHistory(input.report, input.advancedOptions.snapshots)
+
+  return {
+    comparison,
+    team_guidance: buildTeamGuidance(input.fixPriorities, comparison, input.diffContext),
+  }
+}

package/src/trust-kpi-fs.ts

@@ -0,0 +1,169 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, resolve } from 'node:path'
+import type { TrustKpiDiagnostic } from './types.js'
+import type { DiscoverResult } from './trust-kpi-types.js'
+
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', 'dist', '.next', 'build'])
+
+function toPosixPath(path: string): string {
+  return path.replace(/\\/g, '/')
+}
+
+function processDirectoryEntry(current: string, entry: string, stack: string[], out: string[]): void {
+  const fullPath = resolve(current, entry)
+  const info = statSync(fullPath)
+  if (!info.isDirectory()) {
+    out.push(fullPath)
+    return
+  }
+
+  if (IGNORED_DIRECTORIES.has(entry)) return
+  stack.push(fullPath)
+}
+
+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)) {
+      processDirectoryEntry(current, entry, stack, out)
+    }
+  }
+
+  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 discoverFromGlob(source: string, cwd: string): DiscoverResult {
+  const diagnostics: TrustKpiDiagnostic[] = []
+  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 }
+}
+
+function discoverFromPath(source: string, cwd: string): DiscoverResult {
+  const diagnostics: TrustKpiDiagnostic[] = []
+  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 }
+}
+
+export function discoverTrustJsonFiles(input: string, cwd: string): DiscoverResult {
+  const source = input.trim() || '.'
+  return isGlobPattern(source)
+    ? discoverFromGlob(source, cwd)
+    : discoverFromPath(source, cwd)
+}

package/src/trust-kpi-parse.ts

@@ -0,0 +1,219 @@
+import { readFileSync } from 'node:fs'
+import { MERGE_RISK_ORDER, normalizeMergeRiskLevel } from './trust.js'
+import type { MergeRiskLevel, TrustDiffContext, TrustKpiDiagnostic } from './types.js'
+import type { DiffStatus, ParsedTrustArtifact } from './trust-kpi-types.js'
+
+const DIFF_STATUS_VALUES = new Set(['improved', 'regressed', 'neutral'])
+
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function createDiffContextWarning(message: string): { diagnostic: TrustKpiDiagnostic } {
+  return {
+    diagnostic: {
+      level: 'warning',
+      code: 'invalid-diff-context',
+      message,
+    },
+  }
+}
+
+function getFiniteNumber(raw: Record<string, unknown>, key: string): number | null {
+  const value = raw[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function resolveDiffStatus(rawStatus: unknown, scoreDelta: number): DiffStatus {
+  if (typeof rawStatus === 'string' && DIFF_STATUS_VALUES.has(rawStatus)) {
+    return rawStatus as DiffStatus
+  }
+  if (scoreDelta < 0) return 'improved'
+  if (scoreDelta > 0) return 'regressed'
+  return 'neutral'
+}
+
+function parseDiffContextBase(raw: Record<string, unknown>): {
+  baseRef: string
+  scoreDelta: number | null
+  newIssues: number | null
+  resolvedIssues: number | null
+  filesChanged: number
+  penalty: number
+  bonus: number
+  netImpact: number
+} {
+  return {
+    baseRef: typeof raw.baseRef === 'string' ? raw.baseRef : 'unknown',
+    scoreDelta: getFiniteNumber(raw, 'scoreDelta'),
+    newIssues: getFiniteNumber(raw, 'newIssues'),
+    resolvedIssues: getFiniteNumber(raw, 'resolvedIssues'),
+    filesChanged: getFiniteNumber(raw, 'filesChanged') ?? 0,
+    penalty: getFiniteNumber(raw, 'penalty') ?? 0,
+    bonus: getFiniteNumber(raw, 'bonus') ?? 0,
+    netImpact: getFiniteNumber(raw, 'netImpact') ?? 0,
+  }
+}
+
+function normalizeDiffContext(raw: unknown): { diffContext?: TrustDiffContext; diagnostic?: TrustKpiDiagnostic } {
+  if (!isObjectLike(raw)) {
+    return createDiffContextWarning('diff_context is present but malformed; skipping diff trend fields for this artifact')
+  }
+
+  const parsed = parseDiffContextBase(raw)
+
+  if (parsed.scoreDelta == null || parsed.newIssues == null || parsed.resolvedIssues == null) {
+    return createDiffContextWarning('diff_context is missing numeric scoreDelta/newIssues/resolvedIssues; skipping diff trend fields for this artifact')
+  }
+
+  const normalizedStatus = resolveDiffStatus(raw.status, parsed.scoreDelta)
+
+  return {
+    diffContext: {
+      baseRef: parsed.baseRef,
+      status: normalizedStatus,
+      scoreDelta: parsed.scoreDelta,
+      newIssues: parsed.newIssues,
+      resolvedIssues: parsed.resolvedIssues,
+      filesChanged: parsed.filesChanged,
+      penalty: parsed.penalty,
+      bonus: parsed.bonus,
+      netImpact: parsed.netImpact,
+    },
+  }
+}
+
+function readJsonFile(filePath: string): { parsed?: unknown; diagnostics: TrustKpiDiagnostic[] } {
+  let rawContent = ''
+  try {
+    rawContent = readFileSync(filePath, 'utf8')
+  } catch (error) {
+    return {
+      diagnostics: [{
+        level: 'error',
+        code: 'read-failed',
+        file: filePath,
+        message: error instanceof Error ? error.message : String(error),
+      }],
+    }
+  }
+
+  try {
+    return { parsed: JSON.parse(rawContent), diagnostics: [] }
+  } catch (error) {
+    return {
+      diagnostics: [{
+        level: 'error',
+        code: 'parse-failed',
+        file: filePath,
+        message: error instanceof Error ? error.message : String(error),
+      }],
+    }
+  }
+}
+
+function normalizeArtifactShape(parsed: unknown, filePath: string): { artifact?: Record<string, unknown>; diagnostics: TrustKpiDiagnostic[] } {
+  if (isObjectLike(parsed)) {
+    const rawSchema = parsed.$schema
+    if (rawSchema !== undefined && rawSchema !== 'schemas/drift-trust.v1.json') {
+      return {
+        diagnostics: [{
+          level: 'error',
+          code: 'invalid-shape',
+          file: filePath,
+          message: 'Invalid $schema for trust artifact (expected schemas/drift-trust.v1.json)',
+        }],
+      }
+    }
+
+    return { artifact: parsed, diagnostics: [] }
+  }
+
+  return {
+    diagnostics: [{
+      level: 'error',
+      code: 'invalid-shape',
+      file: filePath,
+      message: 'Trust artifact must be a JSON object',
+    }],
+  }
+}
+
+function parseTrustScore(raw: Record<string, unknown>, filePath: string): { trustScore?: number; diagnostics: TrustKpiDiagnostic[] } {
+  const trustScore = raw.trust_score
+  if (typeof trustScore === 'number' && Number.isFinite(trustScore)) {
+    return { trustScore, diagnostics: [] }
+  }
+
+  return {
+    diagnostics: [{
+      level: 'error',
+      code: 'invalid-shape',
+      file: filePath,
+      message: 'Missing numeric trust_score',
+    }],
+  }
+}
+
+function parseMergeRisk(raw: Record<string, unknown>, filePath: string): { mergeRisk?: MergeRiskLevel; diagnostics: TrustKpiDiagnostic[] } {
+  const mergeRisk = typeof raw.merge_risk === 'string'
+    ? normalizeMergeRiskLevel(raw.merge_risk)
+    : undefined
+
+  if (mergeRisk) {
+    return { mergeRisk, diagnostics: [] }
+  }
+
+  return {
+    diagnostics: [{
+      level: 'error',
+      code: 'invalid-shape',
+      file: filePath,
+      message: `Missing/invalid merge_risk (expected one of ${MERGE_RISK_ORDER.join(', ')})`,
+    }],
+  }
+}
+
+export function parseTrustArtifact(filePath: string): { record?: ParsedTrustArtifact; diagnostics: TrustKpiDiagnostic[] } {
+  const readResult = readJsonFile(filePath)
+  if (readResult.diagnostics.length > 0) {
+    return { diagnostics: readResult.diagnostics }
+  }
+
+  const shape = normalizeArtifactShape(readResult.parsed, filePath)
+  if (!shape.artifact) {
+    return { diagnostics: shape.diagnostics }
+  }
+
+  const trustScoreResult = parseTrustScore(shape.artifact, filePath)
+  if (trustScoreResult.trustScore === undefined) {
+    return { diagnostics: trustScoreResult.diagnostics }
+  }
+
+  const mergeRiskResult = parseMergeRisk(shape.artifact, filePath)
+  if (!mergeRiskResult.mergeRisk) {
+    return { diagnostics: mergeRiskResult.diagnostics }
+  }
+
+  const diagnostics: TrustKpiDiagnostic[] = []
+  let diffContext: TrustDiffContext | undefined
+
+  if (shape.artifact.diff_context !== undefined) {
+    const normalized = normalizeDiffContext(shape.artifact.diff_context)
+    if (normalized.diagnostic) {
+      diagnostics.push({ ...normalized.diagnostic, file: filePath })
+    } else {
+      diffContext = normalized.diffContext
+    }
+  }
+
+  return {
+    record: {
+      filePath,
+      trustScore: trustScoreResult.trustScore,
+      mergeRisk: mergeRiskResult.mergeRisk,
+      diffContext,
+    },
+    diagnostics,
+  }
+}