@fabasoad/sarif-to-slack 0.1.0

package/src/SlackMessageBuilder.ts

@@ -0,0 +1,176 @@
+import { AnyBlock } from '@slack/types'
+import { HeaderBlock, ContextBlock } from '@slack/types/dist/block-kit/blocks'
+import { IncomingWebhook } from '@slack/webhook'
+import type { Run, Result, ReportingDescriptor } from 'sarif'
+import { Sarif, SlackMessage } from './types'
+
+/**
+ * Options for the SlackMessageBuilder.
+ * @internal
+ */
+export type SlackMessageBuilderOptions = {
+  username?: string
+  iconUrl?: string
+  color?: string
+  sarif: Sarif
+}
+
+type RuleData = { id?: string, index?: number }
+
+/**
+ * Class for building and sending Slack messages based on SARIF logs.
+ * @internal
+ */
+export class SlackMessageBuilder implements SlackMessage {
+  private readonly webhook: IncomingWebhook
+  private readonly gitHubServerUrl: string
+  private readonly color?: string
+
+  private header?: HeaderBlock
+  private footer?: ContextBlock
+  private actor?: string
+  private runId?: string
+
+  public readonly sarif: Sarif
+
+  constructor(url: string, opts: SlackMessageBuilderOptions) {
+    this.webhook = new IncomingWebhook(url, {
+      username: opts.username || 'SARIF results',
+      icon_url: opts.iconUrl
+    })
+    this.color = opts.color
+    this.sarif = opts.sarif
+    this.gitHubServerUrl = process.env.GITHUB_SERVER_URL || 'https://github.com'
+  }
+
+  withHeader(header?: string): void {
+    this.header = {
+      type: 'header',
+      text: {
+        type: 'plain_text',
+        text: header || process.env.GITHUB_REPOSITORY || 'SARIF results'
+      }
+    }
+  }
+
+  withActor(actor?: string): void {
+    this.actor = actor || process.env.GITHUB_ACTOR
+  }
+
+  withRun(): void {
+    this.runId = process.env.GITHUB_RUN_ID
+  }
+
+  withFooter(footer?: string): void {
+    const repoName = 'fabasoad/sarif-to-slack-action'
+    this.footer = {
+      type: 'context',
+      elements: [{
+        type: footer ? 'plain_text' : 'mrkdwn',
+        text: footer || `Generated by <${this.gitHubServerUrl}/${repoName}|${repoName}>`
+      }],
+    }
+  }
+
+  async send(): Promise<string> {
+    const blocks: AnyBlock[] = []
+    if (this.header) {
+      blocks.push(this.header)
+    }
+    blocks.push({
+      type: 'section',
+      text: {
+        type: 'mrkdwn',
+        text: this.buildText()
+      }
+    })
+    if (this.footer) {
+      blocks.push(this.footer)
+    }
+    const { text } = await this.webhook.send({
+      attachments: [{ color: this.color, blocks }]
+    })
+    return text
+  }
+
+  private buildText(): string {
+    const text: string[] = []
+    if (this.actor) {
+      const actorUrl = `${this.gitHubServerUrl}/${this.actor}`
+      text.push(`_Triggered by <${actorUrl}|${this.actor}>_`)
+    }
+    text.push(this.composeSummary())
+    if (this.runId) {
+      let runText: string = 'Job '
+      if (process.env.GITHUB_REPOSITORY) {
+        runText += `<${this.gitHubServerUrl}/${process.env.GITHUB_REPOSITORY}/actions/runs/${this.runId}|#${this.runId}>`
+      } else {
+        runText += `#${this.runId}`
+      }
+      text.push(runText)
+    }
+    return text.join('\n')
+  }
+
+  private composeRunSummary(toolName: string, map: Map<string, number>): string {
+    const levelsText: string[] = []
+    for (const [level, count] of map.entries()) {
+      const levelCapitalized = level.charAt(0).toUpperCase() + level.slice(1)
+      levelsText.push(`*${levelCapitalized}*: ${count}`)
+    }
+    return `*${toolName}*\n${levelsText.join(', ')}`
+  }
+
+  private composeSummary(): string {
+    const data = new Map<string, Map<string, number>>()
+    for (const run of this.sarif.runs) {
+      const toolName = run.tool.driver.name
+      if (!data.has(toolName)) {
+        data.set(toolName, new Map<string, number>())
+      }
+      const results: Result[] = run.results ?? []
+      for (const result of results) {
+        const level: string = this.tryGetLevel(run, result)
+        const count: number = data.get(toolName)?.get(level) || 0
+        data.get(toolName)?.set(level, count + 1)
+      }
+    }
+    const summaries: string[] = []
+    for (const [toolName, map] of data.entries()) {
+      summaries.push(this.composeRunSummary(toolName, map))
+    }
+    return summaries.join('\n')
+  }
+
+  private tryGetLevel(run: Run, result: Result): string {
+    if (result.level) {
+      return result.level
+    }
+
+    const ruleData: RuleData = {}
+
+    if (result.rule) {
+      if (result.rule?.index) {
+        ruleData.index = result.rule.index
+      }
+      if (result.rule?.id) {
+        ruleData.id = result.rule.id
+      }
+    }
+
+    if (!ruleData.index && result.ruleIndex) {
+      ruleData.index = result.ruleIndex
+    }
+
+    if (ruleData.index
+      && run.tool.driver?.rules
+      && ruleData.index < run.tool.driver.rules.length) {
+      const rule: ReportingDescriptor = run.tool.driver.rules[ruleData.index]
+      if (rule.properties && 'problem.severity' in rule.properties) {
+        return rule.properties['problem.severity'] as string
+      }
+    }
+
+    return 'unknown'
+  }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Yevhen Fabizhevskyi. All rights reserved. Licensed under the MIT license.
+
+/**
+ * Sarif to Slack message converter library.
+ *
+ * @remarks
+ * This library provides a service to send a Slack messages based on the provided
+ * SARIF (Static Analysis Results Interchange Format) files.
+ *
+ * @example
+ * ```typescript
+ * import { SarifToSlackService } from 'sarif-to-slack';
+ *
+ * const service = new SarifToSlackService({
+ *   webhookUrl: 'https://hooks.slack.com/services/your/webhook/url',
+ *   sarifPath: 'path/to/your/sarif/file.sarif',
+ *   logLevel: 'info',
+ *   username: 'SARIF Bot',
+ *   iconUrl: 'https://example.com/icon.png',
+ *   color: '#36a64f',
+ *   header: {
+ *     include: true,
+ *     value: 'SARIF Analysis Results'
+ *   },
+ *   footer: {
+ *     include: true,
+ *     value: 'Generated by @fabasoad/sarif-to-slack'
+ *   },
+ *   actor: {
+ *     include: true,
+ *     value: 'fabasoad'
+ *   },
+ *   run: {
+ *     include: true
+ *   },
+ * });
+ * await service.sendAll();
+ * ```
+ *
+ * @see {@link SarifToSlackService}
+ *
+ * @packageDocumentation
+ */
+export { SarifToSlackService } from './SarifToSlackService'
+export {
+  IncludeAwareProps,
+  IncludeAwareWithValueProps,
+  LogLevel,
+  Sarif,
+  SarifToSlackServiceOptions,
+  SlackMessage,
+} from './types'

package/src/types.ts

@@ -0,0 +1,94 @@
+import type { Log } from 'sarif'
+
+/**
+ * Type representing a SARIF log.
+ * @public
+ */
+export type Sarif = Log
+
+/**
+ * Interface for a Slack message that can be sent.
+ * @public
+ */
+export interface SlackMessage {
+  /**
+   * Sends the Slack message.
+   * @returns A promise that resolves to the response from the Slack webhook.
+   */
+  send: () => Promise<string>
+  /**
+   * The SARIF log associated with this Slack message.
+   */
+  sarif: Sarif
+}
+
+/**
+ * Enum representing log levels for the service.
+ * @public
+ */
+export enum LogLevel {
+  /**
+   * Represents the most verbose logging level, typically used for detailed debugging information.
+   */
+  Silly = 0,
+  /**
+   * Represents a logging level for tracing the flow of the application.
+   */
+  Trace = 1,
+  /**
+   * Represents a logging level for debugging information that is less verbose than silly.
+   */
+  Debug = 2,
+  /**
+   * Represents a logging level for general informational messages that highlight the progress of the application.
+   */
+  Info = 3,
+  /**
+   * Represents a logging level for potentially harmful situations that require attention.
+   */
+  Warning = 4,
+  /**
+   * Represents a logging level for error conditions that do not require immediate action but should be noted.
+   */
+  Error = 5,
+  /**
+   * Represents a logging level for critical errors that require immediate attention and may cause the application to terminate.
+   */
+  Fatal = 6
+}
+
+/**
+ * Type representing properties that indicate whether to include certain information
+ * in the Slack message.
+ * @public
+ */
+export type IncludeAwareProps = {
+  include: boolean
+}
+
+/**
+ * Type representing properties that indicate whether to include certain information
+ * in the Slack message, along with an optional value.
+ * @public
+ */
+export type IncludeAwareWithValueProps = IncludeAwareProps & {
+  value?: string
+}
+
+/**
+ * Options for the SarifToSlackService.
+ * @public
+ */
+export type SarifToSlackServiceOptions = {
+  // The Slack webhook URL to send messages to.
+  webhookUrl: string,
+  sarifPath: string,
+  username?: string,
+  iconUrl?: string,
+  color?: string,
+  logLevel?: LogLevel | string,
+  header?: IncludeAwareWithValueProps,
+  footer?: IncludeAwareWithValueProps,
+  actor?: IncludeAwareWithValueProps,
+  run?: IncludeAwareProps,
+}

package/tests/Processors.spec.ts

@@ -0,0 +1,115 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import { processColor, processSarifPath, processLogLevel } from '../src/Processors'
+
+jest.mock('fs')
+const mockedFs = fs as jest.Mocked<typeof fs>
+
+jest.mock('../src/Logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), debug: jest.fn() }
+}))
+
+describe('processColor', () => {
+  test('returns correct hex for success', () => {
+    expect(processColor('success')).toBe('#008000')
+  })
+
+  test('returns correct hex for failure', () => {
+    expect(processColor('failure')).toBe('#ff0000')
+  })
+
+  test('returns correct hex for cancelled', () => {
+    expect(processColor('cancelled')).toBe('#0047ab')
+  })
+
+  test('returns correct hex for skipped', () => {
+    expect(processColor('skipped')).toBe('#808080')
+  })
+
+  test('returns input for unknown color', () => {
+    expect(processColor('other')).toBe('other')
+  })
+
+  test('returns undefined for undefined input', () => {
+    expect(processColor(undefined)).toBeUndefined()
+  })
+})
+
+describe('processSarifPath', () => {
+  const fakeDir = '/fake/dir'
+  const fakeFile = '/fake/file.sarif'
+
+  afterEach(() => {
+    jest.resetAllMocks()
+  })
+
+  test('throws if path does not exist', () => {
+    mockedFs.existsSync.mockReturnValue(false)
+    expect(() => processSarifPath(fakeFile)).toThrow(/does not exist/)
+  })
+
+  test('returns .sarif files in directory', () => {
+    mockedFs.existsSync.mockReturnValue(true)
+    mockedFs.statSync.mockReturnValue({ isDirectory: () => true, isFile: () => false } as any)
+    // @ts-ignore: mocking readdirSync with a specific return value
+    mockedFs.readdirSync.mockReturnValue(['a.sarif', 'b.SARIF', 'c.txt'])
+    const result: string[] = processSarifPath(fakeDir)
+    expect(result).toEqual(
+      ['a.sarif', 'b.SARIF'].map((file: string) => path.join(fakeDir, file))
+    )
+  })
+
+  test('returns file path if it is a file', () => {
+    mockedFs.existsSync.mockReturnValue(true)
+    mockedFs.statSync.mockReturnValue({ isDirectory: () => false, isFile: () => true } as any)
+    const result: string[] = processSarifPath(fakeFile)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual(fakeFile)
+  })
+
+  test('throws if path is neither file nor directory', () => {
+    mockedFs.existsSync.mockReturnValue(true)
+    mockedFs.statSync.mockReturnValue({ isDirectory: () => false, isFile: () => false } as any)
+    expect(() => processSarifPath('/weird/path')).toThrow(/neither a file nor a directory/)
+  })
+})
+
+describe('processLogLevel', () => {
+  test('returns 0 for silly', () => {
+    expect(processLogLevel('silly')).toBe(0)
+  })
+
+  test('returns 1 for trace', () => {
+    expect(processLogLevel('trace')).toBe(1)
+  })
+
+  test('returns 2 for debug', () => {
+    expect(processLogLevel('debug')).toBe(2)
+  })
+
+  test('returns 3 for info', () => {
+    expect(processLogLevel('info')).toBe(3)
+  })
+
+  test('returns 4 for warning', () => {
+    expect(processLogLevel('warning')).toBe(4)
+  })
+
+  test('returns 5 for error', () => {
+    expect(processLogLevel('error')).toBe(5)
+  })
+
+  test('returns 6 for fatal', () => {
+    expect(processLogLevel('fatal')).toBe(6)
+  })
+
+  test('is case-insensitive', () => {
+    expect(processLogLevel('ERROR')).toBe(5)
+    expect(processLogLevel('Info')).toBe(3)
+  })
+
+  test('throws for unknown log level', () => {
+    expect(() => processLogLevel('unknown')).toThrow(/Unknown log level/)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "commonjs",
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "stripInternal": true,
+    "types": ["node", "jest"],
+    "newLine": "lf",
+    "lib": [
+      "es2024"
+    ],
+    "outDir": "lib"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": ["node_modules", "tests"]
+}