@oculum/scanner 1.0.9 → 1.0.11

package/src/baseline/types.ts

@@ -0,0 +1,97 @@
+/**
+ * Baseline Types
+ * Types for baseline/diff mode functionality
+ */
+
+import type { VulnerabilityCategory, VulnerabilitySeverity, SeverityCounts, ScanDepth } from '../types'
+
+/**
+ * A finding stored in the baseline
+ * Contains enough information to identify and display the finding
+ */
+export interface BaselineFinding {
+  /** Finding hash (from computeFindingHash) */
+  hash: string
+  /** File path relative to project root */
+  filePath: string
+  /** Line number in the file */
+  lineNumber: number
+  /** Vulnerability category */
+  category: VulnerabilityCategory
+  /** Severity level */
+  severity: VulnerabilitySeverity
+  /** Finding title */
+  title: string
+}
+
+/**
+ * Baseline data stored in .oculum/baseline.json
+ */
+export interface BaselineData {
+  /** Schema version for forward compatibility */
+  version: 1
+  /** ISO 8601 timestamp when baseline was created */
+  createdAt: string
+  /** Git commit SHA when baseline was created (optional) */
+  commit?: string
+  /** Git branch name when baseline was created (optional) */
+  branch?: string
+  /** Scan depth used when creating baseline */
+  scanDepth?: ScanDepth
+  /** List of findings in the baseline */
+  findings: BaselineFinding[]
+  /** Summary statistics */
+  stats: {
+    total: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+    info: number
+  }
+}
+
+/**
+ * Result of comparing current findings against baseline
+ */
+export interface DiffResult {
+  /** Findings in current scan but NOT in baseline (new issues) */
+  new: import('../types').Vulnerability[]
+  /** Findings in baseline but NOT in current scan (fixed issues) */
+  fixed: BaselineFinding[]
+  /** Findings in both current scan AND baseline (existing issues) */
+  existing: import('../types').Vulnerability[]
+  /** Summary statistics */
+  stats: {
+    newCount: number
+    fixedCount: number
+    existingCount: number
+    newBySeverity: SeverityCounts
+    fixedBySeverity: SeverityCounts
+  }
+}
+
+/**
+ * Baseline diff metadata attached to ScanResult
+ * Only present when --new flag is used
+ */
+export interface BaselineDiff {
+  /** When the baseline was created */
+  baselineCreatedAt: string
+  /** Git commit of the baseline (if available) */
+  baselineCommit?: string
+  /** Number of new findings (not in baseline) */
+  newCount: number
+  /** Number of fixed findings (in baseline, not in current) */
+  fixedCount: number
+  /** Number of existing findings (in both) */
+  existingCount: number
+  /** Details of fixed findings for display */
+  fixedFindings: BaselineFinding[]
+}
+
+/** Default baseline file path relative to project root */
+export const BASELINE_FILE_PATH = '.oculum/baseline.json'
+
+/** Directory for oculum files */
+export const OCULUM_DIR = '.oculum'

package/src/formatters/cli-terminal.ts

@@ -5,6 +5,7 @@
 
 import type { ScanResult, Vulnerability, VulnerabilitySeverity } from '../types'
 import { groupByTheme, getBlockingIssues, GroupedFindings, THEME_CONFIG } from './grouping'
+import { computeFindingHash } from '../suppression/hash'
 
 /**
  * ANSI color codes
@@ -57,28 +58,101 @@ function severityBadge(severity: VulnerabilitySeverity): string {
   return c(style.color, `${style.symbol} ${style.label}`)
 }
 
+/**
+ * Format options for single finding
+ */
+interface FormatFindingOptions {
+  indent?: string
+  compact?: boolean
+  verbose?: boolean
+}
+
 /**
  * Format a single finding for terminal
+ * Default: Actionable output with impact, code, and fix steps
+ * Compact: Severity + title + location only
+ * Verbose: All of the above plus references and validation notes
  */
-function formatFinding(finding: Vulnerability, indent: string = '  '): string {
+function formatFinding(finding: Vulnerability, options: FormatFindingOptions = {}): string {
+  const { indent = '  ', compact = false, verbose = false } = options
   const badge = severityBadge(finding.severity)
   const location = c(colors.cyan, `${finding.filePath}:${finding.lineNumber}`)
+  const hash = computeFindingHash(finding)
 
+  // Compact mode: just severity, title, and location
+  if (compact) {
+    return `${indent}${badge} ${c(colors.bold, finding.title)}  ${location}\n`
+  }
+
+  // Default actionable output
   let output = `${indent}${badge} ${c(colors.bold, finding.title)}\n`
   output += `${indent}   ${location}\n`
-  output += `${indent}   ${c(colors.dim, finding.description)}\n`
+  output += '\n'
+
+  // Impact (why this matters) - shown by default
+  if (finding.impact) {
+    output += `${indent}   ${c(colors.yellow + colors.bold, 'Impact:')} ${finding.impact}\n`
+    output += '\n'
+  }
+
+  // Code snippet
+  if (finding.lineContent && finding.lineContent.trim()) {
+    output += `${indent}   ${c(colors.dim, 'Code:')} ${c(colors.white, finding.lineContent.trim().substring(0, 80))}${finding.lineContent.trim().length > 80 ? '...' : ''}\n`
+    output += '\n'
+  }
 
-  if (finding.suggestedFix) {
+  // Fix steps - shown by default (numbered list)
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    output += `${indent}   ${c(colors.green + colors.bold, 'Fix:')}\n`
+    finding.fixSteps.forEach((step, i) => {
+      output += `${indent}   ${c(colors.green, `${i + 1}. ${step}`)}\n`
+    })
+    output += '\n'
+  } else if (finding.suggestedFix) {
+    // Fallback to legacy suggestedFix field
     output += `${indent}   ${c(colors.green, '💡 ' + finding.suggestedFix)}\n`
+    output += '\n'
   }
 
+  // Verbose mode: show additional details
+  if (verbose) {
+    // Description
+    output += `${indent}   ${c(colors.dim, finding.description)}\n`
+
+    // References (OWASP/CWE links)
+    if (finding.references && finding.references.length > 0) {
+      output += `${indent}   ${c(colors.blue, 'References:')}\n`
+      finding.references.forEach(ref => {
+        output += `${indent}   ${c(colors.blue, `  • ${ref}`)}\n`
+      })
+    }
+
+    // Validation notes (if AI validated)
+    if (finding.validationNotes) {
+      output += `${indent}   ${c(colors.dim, `[AI] ${finding.validationNotes}`)}\n`
+    }
+
+    // AI enhanced indicator
+    if (finding.aiEnhanced) {
+      output += `${indent}   ${c(colors.magenta, '✨ AI-enhanced fix suggestion')}\n`
+    }
+  }
+
+  // Suppress command - always shown
+  output += `${indent}   ${c(colors.dim, `Suppress: oculum ignore ${hash} --file "${finding.filePath}:${finding.lineNumber}" --reason "..."`)}\n`
+
   return output
 }
 
 /**
  * Format a group of findings
  */
-function formatGroup(group: GroupedFindings, maxFindings: number = 10): string {
+function formatGroup(group: GroupedFindings, options: {
+  maxFindings?: number
+  compact?: boolean
+  verbose?: boolean
+} = {}): string {
+  const { maxFindings = 10, compact = false, verbose = false } = options
   const { theme, themeName, findings, severityCounts } = group
   const config = THEME_CONFIG[theme]
 
@@ -96,7 +170,7 @@ function formatGroup(group: GroupedFindings, maxFindings: number = 10): string {
   // Show findings
   const shown = findings.slice(0, maxFindings)
   for (const finding of shown) {
-    output += formatFinding(finding) + '\n'
+    output += formatFinding(finding, { compact, verbose }) + '\n'
   }
 
   // Truncation notice
@@ -107,6 +181,32 @@ function formatGroup(group: GroupedFindings, maxFindings: number = 10): string {
   return output
 }
 
+/**
+ * Format baseline diff summary
+ */
+function formatDiffSummary(baselineDiff: NonNullable<ScanResult['baselineDiff']>): string {
+  let output = ''
+
+  output += c(colors.bold, 'Baseline Comparison') + '\n'
+  output += c(colors.dim, '─'.repeat(40)) + '\n'
+  output += `  🆕 ${c(colors.yellow, `${baselineDiff.newCount} new`)} findings\n`
+  output += `  ✅ ${c(colors.green, `${baselineDiff.fixedCount} fixed`)} since baseline\n`
+  output += `  📋 ${c(colors.dim, `${baselineDiff.existingCount} existing`)} (in baseline)\n`
+  output += '\n'
+
+  // Format baseline date
+  const baselineDate = new Date(baselineDiff.baselineCreatedAt)
+  const dateStr = baselineDate.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  })
+  const commitStr = baselineDiff.baselineCommit ? ` (${baselineDiff.baselineCommit})` : ''
+  output += c(colors.dim, `Baseline from ${dateStr}${commitStr}`) + '\n\n'
+
+  return output
+}
+
 /**
  * Format full scan result for terminal
  */
@@ -114,13 +214,17 @@ export function formatTerminalOutput(result: ScanResult, options: {
   maxFindingsPerGroup?: number
   showAllFindings?: boolean
   noColor?: boolean
+  compact?: boolean
+  verbose?: boolean
 } = {}): string {
   const {
     maxFindingsPerGroup = 10,
     showAllFindings = false,
+    compact = false,
+    verbose = false,
   } = options
 
-  const { vulnerabilities, severityCounts, hasBlockingIssues, filesScanned, scanDuration } = result
+  const { vulnerabilities, severityCounts, hasBlockingIssues, filesScanned, scanDuration, baselineDiff } = result
 
   let output = '\n'
 
@@ -129,6 +233,11 @@ export function formatTerminalOutput(result: ScanResult, options: {
   output += c(colors.bold, '  OCULUM SECURITY SCAN RESULTS') + '\n'
   output += c(colors.bold, '═'.repeat(60)) + '\n\n'
 
+  // Baseline diff summary (if present)
+  if (baselineDiff) {
+    output += formatDiffSummary(baselineDiff)
+  }
+
   // Status
   if (hasBlockingIssues) {
     const blocking = severityCounts.critical + severityCounts.high
@@ -157,7 +266,7 @@ export function formatTerminalOutput(result: ScanResult, options: {
     output += c(colors.red, 'These must be fixed before merging:') + '\n\n'
 
     for (const finding of blockingIssues.slice(0, 10)) {
-      output += formatFinding(finding)
+      output += formatFinding(finding, { compact, verbose })
       output += '\n'
     }
 
@@ -182,7 +291,47 @@ export function formatTerminalOutput(result: ScanResult, options: {
       if (nonBlocking.length === 0 && blockingIssues.length > 0) continue
     }
 
-    output += formatGroup(group, maxFindingsPerGroup)
+    output += formatGroup(group, { maxFindings: maxFindingsPerGroup, compact, verbose })
+  }
+
+  // Suppressed findings section (if any)
+  if (result.suppressedVulnerabilities && result.suppressedVulnerabilities.length > 0) {
+    output += '\n' + c(colors.dim, '─'.repeat(60)) + '\n'
+    output += c(colors.dim + colors.bold, 'SUPPRESSED FINDINGS') + '\n'
+    output += c(colors.dim, `${result.suppressedVulnerabilities.length} findings suppressed`) + '\n\n'
+
+    for (const suppressed of result.suppressedVulnerabilities.slice(0, 5)) {
+      const typeLabel = suppressed.suppressionType === 'inline' ? 'inline'
+        : suppressed.suppressionType === 'config-finding' ? 'config'
+        : 'rule'
+      output += c(colors.dim, `  ${suppressed.hash.slice(0, 8)} ${suppressed.filePath}:${suppressed.lineNumber}`) + '\n'
+      output += c(colors.dim, `    ${suppressed.title}`) + '\n'
+      output += c(colors.dim, `    [${typeLabel}] ${suppressed.suppressionReason}`) + '\n'
+      if (suppressed.expires) {
+        output += c(colors.dim, `    Expires: ${suppressed.expires}`) + '\n'
+      }
+      output += '\n'
+    }
+
+    if (result.suppressedVulnerabilities.length > 5) {
+      output += c(colors.dim, `  ... and ${result.suppressedVulnerabilities.length - 5} more suppressed\n`)
+    }
+  }
+
+  // Suppression stats (if any)
+  if (result.suppressionStats && (result.suppressionStats.inlineSuppressed > 0 ||
+      result.suppressionStats.configFindingSuppressed > 0 ||
+      result.suppressionStats.configRuleSuppressed > 0)) {
+    const stats = result.suppressionStats
+    const parts: string[] = []
+    if (stats.inlineSuppressed > 0) parts.push(`${stats.inlineSuppressed} inline`)
+    if (stats.configFindingSuppressed > 0) parts.push(`${stats.configFindingSuppressed} config`)
+    if (stats.configRuleSuppressed > 0) parts.push(`${stats.configRuleSuppressed} rule`)
+    if (stats.expired > 0) parts.push(`${stats.expired} expired`)
+
+    if (!result.suppressedVulnerabilities) {
+      output += '\n' + c(colors.dim, `Suppressed: ${parts.join(', ')}`) + '\n'
+    }
   }
 
   // Footer
@@ -192,6 +341,222 @@ export function formatTerminalOutput(result: ScanResult, options: {
   return output
 }
 
+/**
+ * Compact summary options
+ */
+export interface CompactSummaryOptions {
+  /** Number findings for reference with show command */
+  showNumbers?: boolean
+  /** Limit shown per severity (default: 5) */
+  maxPerSeverity?: number
+  /** Show "Run oculum show..." hint */
+  showHint?: boolean
+  /** Disable colors */
+  noColor?: boolean
+}
+
+/**
+ * Format compact summary grouped by severity
+ * Output format:
+ *   HIGH (2)
+ *      1. SQL injection in src/api/users.ts:42
+ *      2. Missing auth in src/api/admin.ts:15
+ */
+export function formatCompactSummary(
+  vulnerabilities: Vulnerability[],
+  options: CompactSummaryOptions = {}
+): string {
+  const {
+    showNumbers = true,
+    maxPerSeverity = 5,
+    showHint = true,
+    noColor = false,
+  } = options
+
+  if (vulnerabilities.length === 0) {
+    return noColor
+      ? 'No security issues found.'
+      : c(colors.green, '✓ No security issues found.')
+  }
+
+  // Group by severity
+  const bySeverity: Record<VulnerabilitySeverity, Vulnerability[]> = {
+    critical: [],
+    high: [],
+    medium: [],
+    low: [],
+    info: [],
+  }
+
+  for (const v of vulnerabilities) {
+    bySeverity[v.severity].push(v)
+  }
+
+  // Build output
+  let output = ''
+  let globalIndex = 1
+
+  const severityOrder: VulnerabilitySeverity[] = ['critical', 'high', 'medium', 'low', 'info']
+  const severityColors: Record<VulnerabilitySeverity, string> = {
+    critical: colors.bgRed + colors.white,
+    high: colors.red,
+    medium: colors.yellow,
+    low: colors.blue,
+    info: colors.gray,
+  }
+
+  for (const severity of severityOrder) {
+    const findings = bySeverity[severity]
+    if (findings.length === 0) continue
+
+    // Severity header
+    const label = severity.toUpperCase()
+    const header = noColor
+      ? `${label} (${findings.length})`
+      : c(severityColors[severity] + colors.bold, `${label} (${findings.length})`)
+    output += `\n  ${header}\n`
+
+    // Show findings
+    const shown = findings.slice(0, maxPerSeverity)
+    for (const finding of shown) {
+      const num = showNumbers ? `${globalIndex}. ` : ''
+      const location = noColor
+        ? `${finding.filePath}:${finding.lineNumber}`
+        : c(colors.cyan, `${finding.filePath}:${finding.lineNumber}`)
+
+      output += noColor
+        ? `     ${num}${finding.title} in ${location}\n`
+        : `     ${c(colors.dim, num)}${finding.title} ${c(colors.dim, 'in')} ${location}\n`
+
+      globalIndex++
+    }
+
+    // Show truncation notice
+    if (findings.length > maxPerSeverity) {
+      const more = findings.length - maxPerSeverity
+      const truncated = noColor
+        ? `     ... and ${more} more\n`
+        : c(colors.dim, `     ... and ${more} more\n`)
+      output += truncated
+      globalIndex += more // Increment for hidden findings
+    }
+  }
+
+  // Hint at bottom
+  if (showHint && vulnerabilities.length > 0) {
+    output += '\n'
+    output += noColor
+      ? "Run 'oculum show 1' for details · 'oculum fix' for suggestions\n"
+      : c(colors.dim, "Run 'oculum show 1' for details · 'oculum fix' for suggestions\n")
+  }
+
+  return output
+}
+
+/**
+ * Format a numbered finding list for the show command
+ * Returns findings with their numbers for reference
+ */
+export function getNumberedFindings(vulnerabilities: Vulnerability[]): Array<{ number: number; finding: Vulnerability }> {
+  return vulnerabilities.map((finding, index) => ({
+    number: index + 1,
+    finding,
+  }))
+}
+
+/**
+ * Format a single finding detail view for the show command
+ */
+export function formatFindingDetail(
+  finding: Vulnerability,
+  number: number,
+  options: { verbose?: boolean; noColor?: boolean } = {}
+): string {
+  const { verbose = false, noColor = false } = options
+
+  let output = ''
+
+  // Header
+  const badge = noColor
+    ? `[${finding.severity.toUpperCase()}]`
+    : severityBadge(finding.severity)
+  const title = noColor ? finding.title : c(colors.bold, finding.title)
+  output += `\n#${number} ${badge} ${title}\n`
+
+  // Location
+  const location = noColor
+    ? finding.filePath + ':' + finding.lineNumber
+    : c(colors.cyan, `${finding.filePath}:${finding.lineNumber}`)
+  output += `   ${location}\n`
+  output += '\n'
+
+  // Impact
+  if (finding.impact) {
+    const impactLabel = noColor ? 'Impact:' : c(colors.yellow + colors.bold, 'Impact:')
+    output += `   ${impactLabel} ${finding.impact}\n`
+    output += '\n'
+  }
+
+  // Code snippet
+  if (finding.lineContent && finding.lineContent.trim()) {
+    const codeLabel = noColor ? 'Code:' : c(colors.dim, 'Code:')
+    const code = finding.lineContent.trim().substring(0, 100)
+    const codeText = noColor ? code : c(colors.white, code)
+    output += `   ${codeLabel} ${codeText}${finding.lineContent.trim().length > 100 ? '...' : ''}\n`
+    output += '\n'
+  }
+
+  // Description
+  output += noColor
+    ? `   ${finding.description}\n`
+    : `   ${c(colors.dim, finding.description)}\n`
+  output += '\n'
+
+  // Fix steps
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    const fixLabel = noColor ? 'How to fix:' : c(colors.green + colors.bold, 'How to fix:')
+    output += `   ${fixLabel}\n`
+    finding.fixSteps.forEach((step, i) => {
+      const stepText = noColor ? `${i + 1}. ${step}` : c(colors.green, `${i + 1}. ${step}`)
+      output += `   ${stepText}\n`
+    })
+    output += '\n'
+  } else if (finding.suggestedFix) {
+    const fixLabel = noColor ? 'Suggested fix:' : c(colors.green + colors.bold, 'Suggested fix:')
+    output += `   ${fixLabel} ${finding.suggestedFix}\n`
+    output += '\n'
+  }
+
+  // Verbose mode: additional details
+  if (verbose) {
+    // References
+    if (finding.references && finding.references.length > 0) {
+      const refLabel = noColor ? 'References:' : c(colors.blue, 'References:')
+      output += `   ${refLabel}\n`
+      finding.references.forEach(ref => {
+        output += noColor
+          ? `   - ${ref}\n`
+          : `   ${c(colors.blue, `- ${ref}`)}\n`
+      })
+      output += '\n'
+    }
+
+    // Validation notes
+    if (finding.validationNotes) {
+      const notesLabel = noColor ? '[AI]' : c(colors.magenta, '[AI]')
+      output += `   ${notesLabel} ${finding.validationNotes}\n`
+      output += '\n'
+    }
+
+    // Category and confidence
+    output += noColor
+      ? `   Category: ${finding.category} · Confidence: ${finding.confidence || 'medium'} · Layer: ${finding.layer}\n`
+      : c(colors.dim, `   Category: ${finding.category} · Confidence: ${finding.confidence || 'medium'} · Layer: ${finding.layer}\n`)
+  }
+
+  return output
+}
+
 /**
  * Format as simple list (no grouping, no colors)
  */
@@ -317,6 +682,76 @@ const RULE_METADATA: Record<string, { name: string; description: string; helpUri
  * For integration with GitHub Code Scanning
  */
 export function formatSARIF(result: ScanResult): object {
+  // Build results from active vulnerabilities
+  const activeResults = result.vulnerabilities.map((v, index) => ({
+    ruleId: v.category,
+    ruleIndex: getRuleIndex(result.vulnerabilities, v.category),
+    level: mapSeverityToSARIF(v.severity),
+    message: {
+      text: v.description,
+    },
+    locations: [{
+      physicalLocation: {
+        artifactLocation: {
+          uri: v.filePath,
+          uriBaseId: '%SRCROOT%',
+        },
+        region: {
+          startLine: v.lineNumber,
+          startColumn: 1,
+          snippet: v.lineContent ? { text: v.lineContent } : undefined,
+        },
+      },
+    }],
+    fingerprints: {
+      'oculum/v1': `${v.category}:${v.filePath}:${v.lineNumber}`,
+    },
+    fixes: v.suggestedFix ? [{
+      description: {
+        text: v.suggestedFix,
+      },
+    }] : undefined,
+    properties: {
+      confidence: v.confidence,
+      layer: v.layer,
+    },
+  }))
+
+  // Build results from suppressed vulnerabilities (with SARIF suppression state)
+  const suppressedResults = (result.suppressedVulnerabilities || []).map((s) => ({
+    ruleId: s.category,
+    ruleIndex: 0, // Will be resolved by GitHub
+    level: mapSeverityToSARIF(s.severity),
+    message: {
+      text: s.title,
+    },
+    locations: [{
+      physicalLocation: {
+        artifactLocation: {
+          uri: s.filePath,
+          uriBaseId: '%SRCROOT%',
+        },
+        region: {
+          startLine: s.lineNumber,
+          startColumn: 1,
+        },
+      },
+    }],
+    fingerprints: {
+      'oculum/v1': `${s.category}:${s.filePath}:${s.lineNumber}`,
+      'oculum/hash': s.hash,
+    },
+    suppressions: [{
+      kind: s.suppressionType === 'inline' ? 'inSource' : 'external',
+      justification: s.suppressionReason,
+      state: 'accepted',
+    }],
+    properties: {
+      suppressionType: s.suppressionType,
+      expires: s.expires,
+    },
+  }))
+
   return {
     $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
     version: '2.1.0',
@@ -330,39 +765,7 @@ export function formatSARIF(result: ScanResult): object {
           rules: getUniqueRules(result.vulnerabilities),
         },
       },
-      results: result.vulnerabilities.map((v, index) => ({
-        ruleId: v.category,
-        ruleIndex: getRuleIndex(result.vulnerabilities, v.category),
-        level: mapSeverityToSARIF(v.severity),
-        message: {
-          text: v.description,
-        },
-        locations: [{
-          physicalLocation: {
-            artifactLocation: {
-              uri: v.filePath,
-              uriBaseId: '%SRCROOT%',
-            },
-            region: {
-              startLine: v.lineNumber,
-              startColumn: 1,
-              snippet: v.lineContent ? { text: v.lineContent } : undefined,
-            },
-          },
-        }],
-        fingerprints: {
-          'oculum/v1': `${v.category}:${v.filePath}:${v.lineNumber}`,
-        },
-        fixes: v.suggestedFix ? [{
-          description: {
-            text: v.suggestedFix,
-          },
-        }] : undefined,
-        properties: {
-          confidence: v.confidence,
-          layer: v.layer,
-        },
-      })),
+      results: [...activeResults, ...suppressedResults],
       columnKind: 'utf16CodeUnits',
     }],
   }