@oculum/scanner 1.0.10 → 1.0.12

package/src/formatters/github-comment.ts

@@ -35,7 +35,29 @@ const CATEGORY_DOCS: Partial<Record<VulnerabilityCategory, string>> = {
 }
 
 /**
- * Format a single finding as a markdown list item
+ * Helper to determine language from file path
+ */
+function getLanguageFromPath(filePath: string): string {
+  const ext = filePath.split('.').pop()?.toLowerCase() || ''
+  const langMap: Record<string, string> = {
+    ts: 'typescript',
+    tsx: 'typescript',
+    js: 'javascript',
+    jsx: 'javascript',
+    py: 'python',
+    go: 'go',
+    java: 'java',
+    rb: 'ruby',
+    php: 'php',
+    yaml: 'yaml',
+    yml: 'yaml',
+    json: 'json',
+  }
+  return langMap[ext] || ''
+}
+
+/**
+ * Format a single finding as a markdown section with actionable info (PRO-82)
  */
 function formatFinding(finding: Vulnerability, options: { showFile?: boolean; showDocs?: boolean } = {}): string {
   const { showFile = true, showDocs = true } = options
@@ -44,18 +66,43 @@ function formatFinding(finding: Vulnerability, options: { showFile?: boolean; sh
     ? `\`${finding.filePath}:${finding.lineNumber}\``
     : `Line ${finding.lineNumber}`
 
-  let md = `- ${badge} **${finding.title}**\n`
-  md += `  - 📍 ${location}\n`
-  md += `  - ${finding.description}\n`
+  let md = `#### ${badge} ${finding.title}\n\n`
+  md += `📍 ${location}\n\n`
+
+  // Impact (why this matters) - shown if available
+  if (finding.impact) {
+    md += `**Impact:** ${finding.impact}\n\n`
+  }
+
+  // Code snippet in collapsible
+  if (finding.lineContent && finding.lineContent.trim()) {
+    const language = getLanguageFromPath(finding.filePath)
+    md += `<details>\n<summary>View code</summary>\n\n`
+    md += `\`\`\`${language}\n${finding.lineContent.trim()}\n\`\`\`\n\n`
+    md += `</details>\n\n`
+  }
 
-  if (finding.suggestedFix) {
-    md += `  - 💡 **Fix:** ${finding.suggestedFix}\n`
+  // Fix steps - shown as numbered list (PRO-82)
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    md += `**Fix:**\n`
+    finding.fixSteps.forEach((step, i) => {
+      md += `${i + 1}. ${step}\n`
+    })
+    md += '\n'
+  } else if (finding.suggestedFix) {
+    // Fallback to legacy field
+    md += `💡 **Fix:** ${finding.suggestedFix}\n\n`
   }
 
-  // Add documentation link if available
+  // Documentation links
   const docsUrl = CATEGORY_DOCS[finding.category]
-  if (showDocs && docsUrl) {
-    md += `  - 📚 [Learn more](${docsUrl})\n`
+  const referenceUrl = finding.references && finding.references.length > 0 ? finding.references[0] : null
+
+  if (showDocs && (docsUrl || referenceUrl)) {
+    const links: string[] = []
+    if (docsUrl) links.push(`[Learn more](${docsUrl})`)
+    if (referenceUrl && referenceUrl !== docsUrl) links.push(`[OWASP/CWE](${referenceUrl})`)
+    md += links.join(' · ') + '\n\n'
   }
 
   return md
@@ -103,7 +150,7 @@ export interface GitHubCommentOptions {
   maxFindingsPerGroup?: number
   showAllFindings?: boolean
   includeFooter?: boolean
-  scanDepth?: 'cheap' | 'validated' | 'deep'
+  scanDepth?: 'local' | 'verified' | 'deep'
   previousScanCounts?: {
     critical: number
     high: number
@@ -293,8 +340,8 @@ function formatScanMetadata(result: ScanResult, scanDepth?: string): string {
   md += `| Scan duration | ${(result.scanDuration / 1000).toFixed(1)}s |\n`
   if (scanDepth) {
     const depthLabels: Record<string, string> = {
-      cheap: 'Fast (pattern matching)',
-      validated: 'Validated (AI-assisted)',
+      local: 'Fast (pattern matching)',
+      verified: 'Verified (AI-assisted)',
       deep: 'Deep (full semantic)',
     }
     md += `| Scan depth | ${depthLabels[scanDepth] || scanDepth} |\n`
@@ -357,7 +404,7 @@ export function formatShortStatus(result: ScanResult): string {
 }
 
 /**
- * Format as inline annotation for GitHub check run
+ * Format as inline annotation for GitHub check run (PRO-82: actionable output)
  */
 export function formatAnnotation(finding: Vulnerability): {
   path: string
@@ -371,12 +418,33 @@ export function formatAnnotation(finding: Vulnerability): {
     finding.severity === 'critical' || finding.severity === 'high' ? 'failure' :
     finding.severity === 'medium' ? 'warning' : 'notice'
 
+  // Build actionable message
+  let message = ''
+
+  // Impact first (why this matters)
+  if (finding.impact) {
+    message += `Impact: ${finding.impact}\n\n`
+  }
+
+  // Description
+  message += finding.description
+
+  // Fix steps or legacy suggestedFix
+  if (finding.fixSteps && finding.fixSteps.length > 0) {
+    message += '\n\n💡 Fix:\n'
+    finding.fixSteps.forEach((step, i) => {
+      message += `${i + 1}. ${step}\n`
+    })
+  } else if (finding.suggestedFix) {
+    message += `\n\n💡 Fix: ${finding.suggestedFix}`
+  }
+
   return {
     path: finding.filePath,
     start_line: finding.lineNumber,
     end_line: finding.lineNumber,
     annotation_level: level,
     title: `${SEVERITY_BADGE[finding.severity]} ${finding.title}`,
-    message: finding.description + (finding.suggestedFix ? `\n\n💡 Fix: ${finding.suggestedFix}` : ''),
+    message,
   }
 }

package/src/formatters/ide/__tests__/ide.test.ts

@@ -0,0 +1,319 @@
+/**
+ * IDE Integration Tests
+ */
+
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import {
+  formatCursorRules,
+  formatWindsurfRules,
+  formatClaudeCodeSection,
+  detectIDEConfigs,
+  writeIDEFile,
+  updateClaudeMdSection,
+  clearIDEFiles,
+} from '../index'
+import type { ScanResult, Vulnerability } from '../../../types'
+
+const createMockVulnerability = (overrides: Partial<Vulnerability> = {}): Vulnerability => ({
+  id: 'test-vuln-1',
+  filePath: 'src/api/users.ts',
+  lineNumber: 42,
+  lineContent: 'const query = `SELECT * FROM users WHERE id = ${userId}`',
+  severity: 'high',
+  category: 'sql_injection',
+  title: 'SQL Injection Vulnerability',
+  description: 'User input is directly concatenated into SQL query without parameterization.',
+  suggestedFix: 'Use parameterized queries instead of string concatenation.',
+  confidence: 'high',
+  layer: 2,
+  fixSteps: [
+    'Replace string concatenation with parameterized query',
+    'Use prepared statements or an ORM',
+  ],
+  ...overrides,
+})
+
+const createMockScanResult = (vulnerabilities: Vulnerability[] = []): ScanResult => ({
+  repoName: 'test-repo',
+  repoUrl: 'https://github.com/test/test-repo',
+  branch: 'main',
+  filesScanned: 50,
+  filesSkipped: 5,
+  vulnerabilities,
+  severityCounts: {
+    critical: vulnerabilities.filter(v => v.severity === 'critical').length,
+    high: vulnerabilities.filter(v => v.severity === 'high').length,
+    medium: vulnerabilities.filter(v => v.severity === 'medium').length,
+    low: vulnerabilities.filter(v => v.severity === 'low').length,
+    info: vulnerabilities.filter(v => v.severity === 'info').length,
+  },
+  categoryCounts: {},
+  hasBlockingIssues: vulnerabilities.some(v => v.severity === 'critical' || v.severity === 'high'),
+  scanDuration: 1500,
+  timestamp: '2024-01-15T10:30:00.000Z',
+})
+
+describe('formatCursorRules', () => {
+  it('should generate MDC format with frontmatter', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatCursorRules(result)
+
+    // Check frontmatter
+    expect(output).toContain('---')
+    expect(output).toContain('description: Oculum Security Findings')
+    expect(output).toContain('alwaysApply: false')
+    expect(output).toContain('---')
+  })
+
+  it('should include glob patterns for affected files', () => {
+    const vulns = [
+      createMockVulnerability({ filePath: 'src/api/users.ts' }),
+      createMockVulnerability({ id: 'v2', filePath: 'src/api/orders.ts' }),
+      createMockVulnerability({ id: 'v3', filePath: 'src/config/db.ts' }),
+    ]
+    const result = createMockScanResult(vulns)
+
+    const output = formatCursorRules(result)
+
+    // Should include globs for affected directories
+    expect(output).toContain('globs:')
+    expect(output).toContain('src/api/**')
+    expect(output).toContain('src/config/**')
+  })
+
+  it('should include security findings', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatCursorRules(result)
+
+    expect(output).toContain('SQL Injection Vulnerability')
+    expect(output).toContain('src/api/users.ts:42')
+  })
+
+  it('should include fix instructions', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatCursorRules(result)
+
+    expect(output).toContain('DO NOT')
+    // The fix shows example code with '?' instead of the word 'parameterized'
+    expect(output).toContain('GOOD')
+    expect(output).toContain("'SELECT * FROM users WHERE id = ?'")
+  })
+
+  it('should return minimal output for zero findings', () => {
+    const result = createMockScanResult([])
+
+    const output = formatCursorRules(result)
+
+    expect(output).toContain('description: Oculum Security Findings')
+    expect(output).toContain('No security issues found')
+  })
+})
+
+describe('formatWindsurfRules', () => {
+  it('should generate markdown security rules', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatWindsurfRules(result)
+
+    expect(output).toContain('# Oculum Security Rules')
+    expect(output).toContain('## Security Issues')
+  })
+
+  it('should list findings by file', () => {
+    const vulns = [
+      createMockVulnerability({ filePath: 'src/api/users.ts' }),
+      createMockVulnerability({ id: 'v2', filePath: 'src/api/orders.ts' }),
+    ]
+    const result = createMockScanResult(vulns)
+
+    const output = formatWindsurfRules(result)
+
+    expect(output).toContain('src/api/users.ts')
+    expect(output).toContain('src/api/orders.ts')
+    expect(output).toContain('Line 42')
+  })
+
+  it('should include code patterns section', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatWindsurfRules(result)
+
+    expect(output).toContain('## Code Patterns')
+    expect(output).toContain('ALWAYS')
+  })
+})
+
+describe('formatClaudeCodeSection', () => {
+  it('should return section with markers', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatClaudeCodeSection(result)
+
+    expect(output).toContain('<!-- OCULUM_SECURITY_START -->')
+    expect(output).toContain('<!-- OCULUM_SECURITY_END -->')
+  })
+
+  it('should include security issues', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatClaudeCodeSection(result)
+
+    expect(output).toContain('## Security Issues')
+    expect(output).toContain('SQL Injection')
+    expect(output).toContain('src/api/users.ts:42')
+  })
+
+  it('should include verification instructions', () => {
+    const vuln = createMockVulnerability()
+    const result = createMockScanResult([vuln])
+
+    const output = formatClaudeCodeSection(result)
+
+    expect(output).toContain('oculum scan')
+  })
+})
+
+describe('detectIDEConfigs', () => {
+  const testDir = join(tmpdir(), 'oculum-ide-detect-test-' + Date.now())
+
+  beforeAll(() => {
+    mkdirSync(testDir, { recursive: true })
+  })
+
+  afterAll(() => {
+    try {
+      rmSync(testDir, { recursive: true, force: true })
+    } catch {
+      // Ignore cleanup errors
+    }
+  })
+
+  it('should detect .cursor directory', () => {
+    // Create .cursor directory
+    mkdirSync(join(testDir, '.cursor'), { recursive: true })
+
+    const detected = detectIDEConfigs(testDir)
+
+    expect(detected).toContain('cursor')
+  })
+
+  it('should detect CLAUDE.md file', () => {
+    // Create CLAUDE.md file
+    writeFileSync(join(testDir, 'CLAUDE.md'), '# Claude Code\n')
+
+    const detected = detectIDEConfigs(testDir)
+
+    expect(detected).toContain('claude-code')
+  })
+
+  it('should return array of detected IDEs', () => {
+    const detected = detectIDEConfigs(testDir)
+
+    expect(Array.isArray(detected)).toBe(true)
+  })
+})
+
+describe('IDE file operations', () => {
+  const testDir = join(tmpdir(), 'oculum-ide-ops-test-' + Date.now())
+
+  beforeAll(() => {
+    mkdirSync(testDir, { recursive: true })
+  })
+
+  afterAll(() => {
+    try {
+      rmSync(testDir, { recursive: true, force: true })
+    } catch {
+      // Ignore cleanup errors
+    }
+  })
+
+  it('should write IDE file and create directories', () => {
+    const result = writeIDEFile(
+      testDir,
+      '.cursor/rules/security.mdc',
+      '# Security Rules'
+    )
+
+    expect(result.success).toBe(true)
+    expect(existsSync(join(testDir, '.cursor/rules/security.mdc'))).toBe(true)
+  })
+
+  it('should update CLAUDE.md section between markers', () => {
+    // Create initial CLAUDE.md
+    const initialContent = `# Project
+
+Some existing content.
+
+<!-- OCULUM_SECURITY_START -->
+Old security content
+<!-- OCULUM_SECURITY_END -->
+
+More content.
+`
+    writeFileSync(join(testDir, 'CLAUDE.md'), initialContent)
+
+    // Update section
+    const result = updateClaudeMdSection(
+      testDir,
+      '<!-- OCULUM_SECURITY_START -->\nNew security content\n<!-- OCULUM_SECURITY_END -->'
+    )
+
+    expect(result.success).toBe(true)
+
+    // Read and verify
+    const { readFileSync } = require('fs')
+    const updated = readFileSync(join(testDir, 'CLAUDE.md'), 'utf-8')
+
+    expect(updated).toContain('New security content')
+    expect(updated).not.toContain('Old security content')
+    expect(updated).toContain('Some existing content')
+    expect(updated).toContain('More content')
+  })
+
+  it('should append section if no markers exist', () => {
+    // Create CLAUDE.md without markers
+    const noMarkersDir = join(testDir, 'no-markers')
+    mkdirSync(noMarkersDir, { recursive: true })
+    writeFileSync(join(noMarkersDir, 'CLAUDE.md'), '# Project\n\nSome content.\n')
+
+    const result = updateClaudeMdSection(
+      noMarkersDir,
+      '<!-- OCULUM_SECURITY_START -->\nSecurity content\n<!-- OCULUM_SECURITY_END -->'
+    )
+
+    expect(result.success).toBe(true)
+
+    const { readFileSync } = require('fs')
+    const updated = readFileSync(join(noMarkersDir, 'CLAUDE.md'), 'utf-8')
+
+    expect(updated).toContain('Security content')
+    expect(updated).toContain('Some content')
+  })
+
+  it('should clear IDE files', () => {
+    // Create some IDE files
+    const clearDir = join(testDir, 'clear-test')
+    mkdirSync(join(clearDir, '.cursor/rules'), { recursive: true })
+    writeFileSync(join(clearDir, '.cursor/rules/security.mdc'), 'content')
+    writeFileSync(join(clearDir, '.windsurfrules'), 'content')
+
+    const result = clearIDEFiles(clearDir)
+
+    expect(result.success).toBe(true)
+    expect(existsSync(join(clearDir, '.cursor/rules/security.mdc'))).toBe(false)
+    expect(existsSync(join(clearDir, '.windsurfrules'))).toBe(false)
+  })
+})

package/src/formatters/ide/claude-code.ts

@@ -0,0 +1,110 @@
+/**
+ * Claude Code IDE Integration
+ * Generates CLAUDE.md section format
+ */
+
+import type { ScanResult, Vulnerability, VulnerabilityCategory } from '../../types'
+import { sortBySeverity } from '../grouping'
+
+/** Start marker for Oculum section in CLAUDE.md */
+export const OCULUM_SECTION_START = '<!-- OCULUM_SECURITY_START -->'
+
+/** End marker for Oculum section in CLAUDE.md */
+export const OCULUM_SECTION_END = '<!-- OCULUM_SECURITY_END -->'
+
+/**
+ * Get "ALWAYS" rule for a category
+ */
+function getAlwaysRule(category: VulnerabilityCategory): string | null {
+  const rules: Partial<Record<VulnerabilityCategory, string>> = {
+    sql_injection: 'Use parameterized queries for all database operations',
+    xss: 'Escape or sanitize user input before rendering in HTML',
+    hardcoded_secret: 'Use environment variables for secrets and API keys',
+    high_entropy_string: 'Store credentials in secure vaults, not in code',
+    missing_auth: 'Add authentication middleware to API endpoints',
+    dangerous_function: 'Avoid eval() and exec() - use safe alternatives',
+    command_injection: 'Sanitize all input passed to shell commands',
+    data_exposure: 'Never log sensitive data or expose it in responses',
+    weak_crypto: 'Use modern cryptographic algorithms (SHA-256+, AES-256)',
+    ai_prompt_injection: 'Sanitize user input before including in prompts',
+    ai_unsafe_execution: 'Validate AI-generated code before execution',
+  }
+
+  return rules[category] || null
+}
+
+/**
+ * Format scan result as CLAUDE.md section
+ *
+ * @param result - The scan result to format
+ * @returns Markdown string with markers for CLAUDE.md
+ */
+export function formatClaudeCodeSection(result: ScanResult): string {
+  const { vulnerabilities, timestamp } = result
+
+  // Sort by severity
+  const sorted = sortBySeverity(vulnerabilities)
+
+  let md = ''
+
+  // Section markers
+  md += `${OCULUM_SECTION_START}\n`
+  md += `## Security Issues (Auto-Generated)\n\n`
+  md += `> Last scan: ${timestamp}\n\n`
+
+  // No findings case
+  if (vulnerabilities.length === 0) {
+    md += `No security issues detected.\n\n`
+    md += `Run \`oculum scan\` to scan for vulnerabilities.\n`
+    md += `${OCULUM_SECTION_END}\n`
+    return md
+  }
+
+  // Summary
+  const { severityCounts, hasBlockingIssues } = result
+  if (hasBlockingIssues) {
+    md += `**BLOCKING ISSUES:** ${severityCounts.critical + severityCounts.high} issues must be fixed.\n\n`
+  }
+
+  // DO NOT section - list findings
+  md += `**DO NOT** ignore these findings:\n\n`
+
+  let count = 0
+  for (const vuln of sorted.slice(0, 10)) {
+    count++
+    const severityLabel =
+      vuln.severity === 'critical' ? 'CRITICAL' :
+      vuln.severity === 'high' ? 'HIGH' :
+      vuln.severity.toUpperCase()
+
+    md += `${count}. **${vuln.title}** [${severityLabel}] in \`${vuln.filePath}:${vuln.lineNumber}\`\n`
+  }
+
+  if (sorted.length > 10) {
+    md += `\n... and ${sorted.length - 10} more issues.\n`
+  }
+  md += '\n'
+
+  // ALWAYS section - best practices
+  const alwaysRules = new Set<string>()
+  for (const vuln of vulnerabilities) {
+    const rule = getAlwaysRule(vuln.category)
+    if (rule) {
+      alwaysRules.add(rule)
+    }
+  }
+
+  if (alwaysRules.size > 0) {
+    md += `**ALWAYS:**\n`
+    for (const rule of alwaysRules) {
+      md += `- ${rule}\n`
+    }
+    md += '\n'
+  }
+
+  // Verification instructions
+  md += `Run \`oculum scan\` to verify fixes.\n`
+  md += `${OCULUM_SECTION_END}\n`
+
+  return md
+}