@fabasoad/sarif-to-slack 0.1.0

package/dist/sarif-to-slack.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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
+ */
+
+import type { Log } from 'sarif';
+
+/**
+ * Type representing properties that indicate whether to include certain information
+ * in the Slack message.
+ * @public
+ */
+export declare 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 declare type IncludeAwareWithValueProps = IncludeAwareProps & {
+    value?: string;
+};
+
+/**
+ * Enum representing log levels for the service.
+ * @public
+ */
+export declare 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 a SARIF log.
+ * @public
+ */
+export declare type Sarif = Log;
+
+/**
+ * Service to convert SARIF files to Slack messages and send them.
+ * @public
+ */
+export declare class SarifToSlackService {
+    private _slackMessages;
+    private constructor();
+    /**
+     * Gets the Slack messages prepared for each SARIF file.
+     * @returns A read-only map where keys are SARIF file paths and values are SlackMessage instances.
+     * @public
+     */
+    get slackMessages(): ReadonlyMap<string, SlackMessage>;
+    /**
+     * Creates an instance of SarifToSlackService.
+     * @param opts - Options for the service, including webhook URL, SARIF path, and other configurations.
+     * @returns A promise that resolves to an instance of SarifToSlackService.
+     * @throws Error if no SARIF files are found at the provided path.
+     * @public
+     */
+    static create(opts: SarifToSlackServiceOptions): Promise<SarifToSlackService>;
+    /**
+     * Sends all prepared Slack messages.
+     * @returns A promise that resolves when all messages have been sent.
+     * @throws Error if a Slack message was not prepared for a SARIF path.
+     * @public
+     */
+    sendAll(): Promise<void>;
+    /**
+     * Sends a Slack message for a specific SARIF path.
+     * @param sarifPath - The path of the SARIF file for which the message should be sent.
+     * @returns A promise that resolves when the message has been sent.
+     * @throws Error if a Slack message was not prepared for the given SARIF path.
+     * @public
+     */
+    send(sarifPath: string): Promise<void>;
+}
+
+/**
+ * Options for the SarifToSlackService.
+ * @public
+ */
+export declare type SarifToSlackServiceOptions = {
+    webhookUrl: string;
+    sarifPath: string;
+    username?: string;
+    iconUrl?: string;
+    color?: string;
+    logLevel?: LogLevel | string;
+    header?: IncludeAwareWithValueProps;
+    footer?: IncludeAwareWithValueProps;
+    actor?: IncludeAwareWithValueProps;
+    run?: IncludeAwareProps;
+};
+
+/**
+ * Interface for a Slack message that can be sent.
+ * @public
+ */
+export declare 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;
+}
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.52.8"
+    }
+  ]
+}

package/etc/sarif-to-slack.api.md

@@ -0,0 +1,61 @@
+## API Report File for "@fabasoad/sarif-to-slack"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import type { Log } from 'sarif';
+
+// @public
+export type IncludeAwareProps = {
+    include: boolean;
+};
+
+// @public
+export type IncludeAwareWithValueProps = IncludeAwareProps & {
+    value?: string;
+};
+
+// @public
+export enum LogLevel {
+    Debug = 2,
+    Error = 5,
+    Fatal = 6,
+    Info = 3,
+    Silly = 0,
+    Trace = 1,
+    Warning = 4
+}
+
+// @public
+export type Sarif = Log;
+
+// @public
+export class SarifToSlackService {
+    static create(opts: SarifToSlackServiceOptions): Promise<SarifToSlackService>;
+    send(sarifPath: string): Promise<void>;
+    sendAll(): Promise<void>;
+    get slackMessages(): ReadonlyMap<string, SlackMessage>;
+}
+
+// @public
+export type SarifToSlackServiceOptions = {
+    webhookUrl: string;
+    sarifPath: string;
+    username?: string;
+    iconUrl?: string;
+    color?: string;
+    logLevel?: LogLevel | string;
+    header?: IncludeAwareWithValueProps;
+    footer?: IncludeAwareWithValueProps;
+    actor?: IncludeAwareWithValueProps;
+    run?: IncludeAwareProps;
+};
+
+// @public
+export interface SlackMessage {
+    sarif: Sarif;
+    send: () => Promise<string>;
+}
+
+```

package/jest.config.json

@@ -0,0 +1,33 @@
+{
+  "clearMocks": true,
+  "collectCoverageFrom": [
+    "**/*.ts",
+    "!**/*.d.ts",
+    "!**/node_modules/**"
+  ],
+  "coverageReporters": [
+    "lcov", "text", "text-summary"
+  ],
+  "coverageThreshold": {
+    "global": {
+      "branches": 20,
+      "functions": 15,
+      "lines": 25,
+      "statements": 25
+    }
+  },
+  "moduleFileExtensions": [
+    "js",
+    "ts"
+  ],
+  "testEnvironment": "node",
+  "testMatch": [
+    "**/*.spec.ts"
+  ],
+  "testRunner": "jest-circus/runner",
+  "testTimeout": 20000,
+  "transform": {
+    "^.+\\.ts$": "ts-jest"
+  },
+  "verbose": true
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@fabasoad/sarif-to-slack",
+  "version": "0.1.0",
+  "description": "TypeScript library to send results of SARIF file to Slack webhook URL.",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "scripts": {
+    "lint": "biome lint --write src",
+    "test": "jest --config=jest.config.json --json --outputFile=jest-report.json --coverage",
+    "clean": "rm -rf coverage && rm -rf temp",
+    "clean:unsafe": "rm -f package-lock.json && rm -rf node_modules && rm -rf dist && rm -rf lib",
+    "build": "tsc && api-extractor run --local --verbose",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch --commit-hooks --git-tag-version --message 'chore: bump to version %s'",
+    "version:minor": "npm version minor --commit-hooks --git-tag-version --message 'chore: bump to version %s'",
+    "version:major": "npm version major --commit-hooks --git-tag-version --message 'chore: bump to version %s'",
+    "preversion": "npm test",
+    "version": "npm run build && git add .",
+    "postversion": "git push && git push --tags && npm run clean"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fabasoad/sarif-to-slack.git"
+  },
+  "keywords": [
+    "npm",
+    "sarif",
+    "slack"
+  ],
+  "author": "Yevhen Fabizhevskyi",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fabasoad/sarif-to-slack-action/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/fabasoad/sarif-to-slack-action#readme",
+  "dependencies": {
+    "@slack/webhook": "7.0.5",
+    "@types/sarif": "2.1.7",
+    "tslog": "4.9.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@microsoft/api-documenter": "7.26.29",
+    "@microsoft/api-extractor": "7.52.8",
+    "@types/jest": "30.0.0",
+    "jest": "30.0.3",
+    "jest-circus": "30.0.3",
+    "ts-jest": "29.4.0",
+    "typescript": "5.8.3"
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,34 @@
+import { Logger as TSLogger, ILogObj } from 'tslog'
+import { LogLevel } from './types'
+
+/**
+ * Logger options for configuring the logging behavior.
+ * @internal
+ */
+export type LoggerOptions = {
+  logLevel?: LogLevel
+}
+
+/**
+ * Logger class for managing logging operations.
+ * @internal
+ */
+export default class Logger {
+  private static instance: TSLogger<ILogObj> = new TSLogger();
+
+  public static initialize({ logLevel = LogLevel.Info }: LoggerOptions): void {
+    if (!Logger.instance) {
+      Logger.instance = new TSLogger({
+        minLevel: process.env.ACTIONS_STEP_DEBUG === 'true' ? 0 : logLevel,
+      })
+    }
+  }
+
+  public static info(...args: string[]): void {
+    Logger.instance.info(args)
+  }
+
+  public static debug(...args: string[]): void {
+    Logger.instance.debug(args)
+  }
+}

package/src/Processors.ts

@@ -0,0 +1,100 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import Logger from './Logger'
+import { LogLevel } from './types'
+
+/**
+ * Processes a color string and converts it to a specific hex code if it matches
+ * a CI status identifier.
+ * @param color - The color string to process, which can be a CI status identifier
+ * or a custom color.
+ * @returns The processed color as a hex string or undefined if the input is not
+ * a recognized CI status identifier.
+ * @internal
+ */
+export function processColor(color?: string): string | undefined {
+  switch (color) {
+    case 'success':
+      Logger.info(`Converting "${color}" to #008000`)
+      return '#008000'
+    case 'failure':
+      Logger.info(`Converting "${color}" to #ff0000`)
+      return '#ff0000'
+    case 'cancelled':
+      Logger.info(`Converting "${color}" to #0047ab`)
+      return '#0047ab'
+    case 'skipped':
+      Logger.info(`Converting "${color}" to #808080`)
+      return '#808080'
+    default:
+      Logger.debug(`"${color}" color is not a CI status identifier. Returning as is...`)
+      return color
+  }
+}
+
+/**
+ * Processes a log level string or number and converts it to a numeric log level.
+ * @param logLevel
+ * @returns The numeric log level corresponding to the input string or number.
+ * @throws Error If the input string does not match any known log level.
+ * @internal
+ */
+export function processLogLevel(logLevel?: LogLevel | string): LogLevel | undefined {
+  if (typeof logLevel === 'string') {
+    switch (logLevel.toLowerCase()) {
+      case 'silly':
+        return 0
+      case 'trace':
+        return 1
+      case 'debug':
+        return 2
+      case 'info':
+        return 3
+      case 'warning':
+        return 4
+      case 'error':
+        return 5
+      case 'fatal':
+        return 6
+      default:
+        throw new Error(`Unknown log level: ${logLevel}`)
+    }
+  }
+  return logLevel
+}
+
+/**
+ * Processes the SARIF path, which can be a file or a directory. If it's a
+ * directory, it returns an array of paths to all `.sarif` files, otherwise it
+ * returns an array with a single path to the file.
+ * @param sarifPath - The path to the SARIF file or directory.
+ * @returns An array of strings representing the paths to the SARIF files.
+ * @throws Error If the path does not exist, or if it is neither a file nor a
+ * directory.
+ * @internal
+ */
+export function processSarifPath(sarifPath: string): string[] {
+  if (!fs.existsSync(sarifPath)) {
+    throw new Error(`"sarif-path" does not exist: ${sarifPath}`)
+  }
+
+  const sarifStats: fs.Stats = fs.statSync(sarifPath)
+
+  if (sarifStats.isDirectory()) {
+    Logger.info(`"sarif-path" is a directory: ${sarifPath}`)
+    const files: string[] = fs.readdirSync(sarifPath)
+    const filteredFiles: string[] = files.filter((file: string) =>
+      path.extname(file).toLowerCase() === '.sarif'
+    )
+    Logger.info(`Found ${filteredFiles.length} SARIF files in ${sarifPath} directory`)
+    Logger.debug(`Filtered SARIF files: ${filteredFiles.join(', ')}`)
+    return filteredFiles.map((file: string) => path.join(sarifPath, file))
+  }
+
+  if (sarifStats.isFile()) {
+    Logger.info(`"sarif-path" is a file: ${sarifPath}`)
+    return [sarifPath]
+  }
+
+  throw new Error(`"sarif-path" is neither a file nor a directory: ${sarifPath}`)
+}

package/src/SarifToSlackService.ts

@@ -0,0 +1,106 @@
+import { promises as fs } from 'fs';
+import Logger from './Logger'
+import { processColor, processLogLevel, processSarifPath } from './Processors'
+import { SlackMessageBuilder } from './SlackMessageBuilder'
+import {
+  Sarif,
+  SarifToSlackServiceOptions,
+  SlackMessage
+} from './types'
+
+async function initialize(opts: SarifToSlackServiceOptions): Promise<Map<string, SlackMessage>> {
+  const slackMessages = new Map<string, SlackMessage>();
+  const sarifFiles: string[] = processSarifPath(opts.sarifPath)
+  if (sarifFiles.length === 0) {
+    throw new Error(`No SARIF files found at the provided path: ${opts.sarifPath}`)
+  }
+
+  for (const sarifFile of sarifFiles) {
+    const jsonString: string = await fs.readFile(sarifFile, 'utf8')
+
+    const messageBuilder = new SlackMessageBuilder(opts.webhookUrl, {
+      username: opts.username,
+      iconUrl: opts.iconUrl,
+      color: processColor(opts.color),
+      sarif: JSON.parse(jsonString) as Sarif
+    })
+    if (opts.header?.include) {
+      messageBuilder.withHeader(opts.header?.value)
+    }
+    if (opts.footer?.include) {
+      messageBuilder.withFooter(opts.footer?.value)
+    }
+    if (opts.actor?.include) {
+      messageBuilder.withActor(opts.actor?.value)
+    }
+    if (opts.run?.include) {
+      messageBuilder.withRun()
+    }
+    slackMessages.set(sarifFile, messageBuilder)
+  }
+  return slackMessages;
+}
+
+/**
+ * Service to convert SARIF files to Slack messages and send them.
+ * @public
+ */
+export class SarifToSlackService {
+  private _slackMessages: ReadonlyMap<string, SlackMessage>;
+
+  private constructor() {
+  }
+
+  /**
+   * Gets the Slack messages prepared for each SARIF file.
+   * @returns A read-only map where keys are SARIF file paths and values are SlackMessage instances.
+   * @public
+   */
+  public get slackMessages(): ReadonlyMap<string, SlackMessage> {
+    return this._slackMessages;
+  }
+
+  /**
+   * Creates an instance of SarifToSlackService.
+   * @param opts - Options for the service, including webhook URL, SARIF path, and other configurations.
+   * @returns A promise that resolves to an instance of SarifToSlackService.
+   * @throws Error if no SARIF files are found at the provided path.
+   * @public
+   */
+  public static async create(opts: SarifToSlackServiceOptions): Promise<SarifToSlackService> {
+    Logger.initialize({
+      logLevel: processLogLevel(opts.logLevel)
+    })
+    const instance: SarifToSlackService = new SarifToSlackService()
+    instance._slackMessages = await initialize(opts)
+    return instance
+  }
+
+  /**
+   * Sends all prepared Slack messages.
+   * @returns A promise that resolves when all messages have been sent.
+   * @throws Error if a Slack message was not prepared for a SARIF path.
+   * @public
+   */
+  public async sendAll(): Promise<void> {
+    for (const sarifPath of this._slackMessages.keys()) {
+      await this.send(sarifPath);
+    }
+  }
+
+  /**
+   * Sends a Slack message for a specific SARIF path.
+   * @param sarifPath - The path of the SARIF file for which the message should be sent.
+   * @returns A promise that resolves when the message has been sent.
+   * @throws Error if a Slack message was not prepared for the given SARIF path.
+   * @public
+   */
+  public async send(sarifPath: string): Promise<void> {
+    const message: SlackMessage | undefined = this._slackMessages.get(sarifPath)
+    if (!message) {
+      throw new Error(`Slack message was not prepared for SARIF path: ${sarifPath}.`)
+    }
+    const text: string = await message.send()
+    Logger.info(`Message sent for ${sarifPath} file. Status:`, text)
+  }
+}