@fabasoad/sarif-to-slack 0.2.5 → 1.1.0

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

@@ -2,24 +2,45 @@
  * Sarif to Slack message converter library.
  *
  * @remarks
- * This library provides a service to send a Slack messages based on the provided
+ * This library provides a client to send a Slack messages based on the provided
  * SARIF (Static Analysis Results Interchange Format) files.
  *
  * @example
  * ```typescript
- * import { SarifToSlackService, FooterType } from '@fabasoad/sarif-to-slack';
+ * import {
+ *   Color,
+ *   FooterType,
+ *   LogLevel,
+ *   RepresentationType,
+ *   SarifToSlackClient,
+ *   SendIf
+ * } from '@fabasoad/sarif-to-slack';
  *
- * const service = await SarifToSlackService.create({
+ * const client: SarifToSlackClient = await SarifToSlackClient.create({
  *   webhookUrl: 'https://hooks.slack.com/services/your/webhook/url',
- *   sarifPath: 'path/to/your/sarif/file.sarif',
+ *   username: 'SARIF to Slack Bot',
+ *   iconUrl: 'https://example.com/icon.png',
+ *   color: {
+ *     bySeverity: {
+ *       critical: new Color('#ff0000'),
+ *       high: new Color('#ff4500'),
+ *       medium: new Color('#ffa500'),
+ *       low: new Color('#ffff00'),
+ *       none: new Color('#808080'),
+ *       unknown: new Color('#800080'),
+ *       empty: new Color('#d3d3d3'),
+ *     },
+ *   },
+ *   sarif: {
+ *     path: 'path/to/your/sarif-files',
+ *     recursive: true,
+ *     extension: 'sarif',
+ *   },
  *   log: {
  *     level: LogLevel.Info,
  *     template: '[{{logLevelName}}] [{{name}}] {{dateIsoStr}} ',
  *     colored: false,
  *   },
- *   username: 'SARIF Bot',
- *   iconUrl: 'https://example.com/icon.png',
- *   color: '#36a64f',
  *   header: {
  *     include: true,
  *     value: 'SARIF Analysis Results'
@@ -36,40 +57,100 @@
  *   run: {
  *     include: true
  *   },
+ *   representation: RepresentationType.CompactGroupByToolNamePerSeverity,
+ *   sendIf: SendIf.MediumOrHigher,
  * });
- * await service.sendAll();
+ * await client.send();
  * ```
  *
- * @see {@link SarifToSlackService}
+ * @see {@link SarifToSlackClient}
  *
  * @packageDocumentation
  */
 
-import type { Log } from 'sarif';
-
 /**
- * Enum representing how to calculate results.
+ * This class represents a color in hex format.
  * @public
  */
-export declare enum CalculateResultsBy {
+export declare class Color {
+    private readonly _color?;
     /**
-     * Calculates results by the security level of the findings: Error, Warning,
-     * Note and Unknown. At first, it tries to get the security level from runs[].results[].level
-     * property. If it is not defined, it tries to get the security level from the
-     * respective rule of each result, using the rules[].properties['problem.severity']
-     * property.
+     * Creates an instance of {@link Color} class. Before creating an instance of
+     * {@link Color} class, it (if applicable) maps CI status into the hex color,
+     * and also validates {@param color} to be a valid string that represents a
+     * color in hex format.
+     * @param color Can be either undefined, valid color in hex format or GitHub
+     * CI status (one of: success, failure, cancelled, skipped)
+     * @public
      */
-    Level = 0,
+    constructor(color?: string);
     /**
-     * Calculates results by the security severity of the findings: Critical, High,
-     * Medium, Low, None and Unknown. it tries to get the security severity from the
-     * respective rule of each result, using the rules[].properties['security-severity']
-     * property. This property contains CVSS score, which is then mapped to the
-     * security severity value.
+     * Returns a valid string that represents a color in hex format, or undefined.
      */
-    Severity = 1
+    get value(): string | undefined;
+    private validateHexColor;
+    private mapColor;
 }
 
+/**
+ * Color schema for the findings with the certain level. Color is used by the
+ * level importance, i.e. if at least 1 error finding exists then
+ * {@link ColorGroupByLevel.error} color is used, then if at least 1 warning
+ * finding exists then {@link ColorGroupByLevel.warning} color is used, etc.
+ * @public
+ */
+export declare type ColorGroupByLevel = ColorGroupCommon & {
+    error?: Color;
+    warning?: Color;
+    note?: Color;
+};
+
+/**
+ * Color schema for the findings with the certain severity. Color is used by the
+ * severity importance, i.e. if at least 1 critical finding exists then
+ * {@link ColorGroupBySeverity.critical} color is used, then if at least 1 high
+ * finding exists then {@link ColorGroupBySeverity.high} color is used, etc.
+ * @public
+ */
+export declare type ColorGroupBySeverity = ColorGroupCommon & {
+    critical?: Color;
+    high?: Color;
+    medium?: Color;
+    low?: Color;
+};
+
+/**
+ * Base type that has common fields for both {@link ColorGroupByLevel} and
+ * {@link ColorGroupBySeverity}.
+ * @private
+ */
+declare type ColorGroupCommon = {
+    none?: Color;
+    unknown?: Color;
+    empty?: Color;
+};
+
+/**
+ * Represents configuration of the color scheme. If both {@link ColorOptions.byLevel}
+ * and {@link ColorOptions.bySeverity} are defined, then {@link ColorOptions.bySeverity}
+ * takes precedence.
+ * @public
+ */
+export declare type ColorOptions = {
+    /**
+     * Default color if specific color was not found. It is a fallback option.
+     */
+    default?: Color;
+    /**
+     * Color scheme for the findings where certain level is presented.
+     */
+    byLevel?: ColorGroupByLevel;
+    /**
+     * Color scheme for the findings where certain severity is presented.
+     */
+    bySeverity?: ColorGroupBySeverity;
+};
+
 /**
  * Options for the footer of a Slack message. "type" is ignored if "value" is
  * not defined.
@@ -95,27 +176,6 @@ export declare enum FooterType {
     Markdown = "mrkdwn"
 }
 
-/**
- * Enum representing how to group results.
- * @public
- */
-export declare enum GroupResultsBy {
-    /**
-     * Groups results by the tool name. Particularly, groups by the runs[].tool.driver.name
-     * property from the SARIF file(s).
-     */
-    ToolName = 0,
-    /**
-     * Groups results by the run. It provides the result from each run individually.
-     */
-    Run = 1,
-    /**
-     * Does not group results. It provides the result from all the runs from all
-     * the provided SARIF files.
-     */
-    Total = 2
-}
-
 /**
  * Type representing properties that indicate whether to include certain information
  * in the Slack message.
@@ -189,76 +249,278 @@ export declare type LogOptions = {
 };
 
 /**
- * Type representing a SARIF log.
+ * This represents what type of message should be sent. There are various options
+ * to show information from SARIF in Slack message.
+ * @public
+ */
+export declare enum RepresentationType {
+    /**
+     * Compact information about findings grouped by Run with the level representation.
+     * @example
+     * ```text
+     * [Run 1] Grype
+     * Error: 1, Warning: 4
+     * [Run 2] Grype
+     * Warning: 1, Note: 20
+     * ```
+     */
+    CompactGroupByRunPerLevel = 0,
+    /**
+     * Compact information about findings grouped by Run with the severity representation.
+     * @example
+     * ```text
+     * [Run 1] Grype
+     * Critical: 1, High: 3, Medium: 1
+     * [Run 2] Grype
+     * Medium: 1, Low: 20
+     * ```
+     */
+    CompactGroupByRunPerSeverity = 1,
+    /**
+     * Compact information about findings grouped by tool name with the level representation.
+     * @example
+     * ```text
+     * Grype
+     * Error: 1, Warning: 5, Note: 20
+     * ```
+     */
+    CompactGroupByToolNamePerLevel = 2,
+    /**
+     * Compact information about findings grouped by tool name with the severity representation.
+     * @example
+     * ```text
+     * Grype
+     * Critical: 1, High: 3, Medium: 2, Low: 20
+     * ```
+     */
+    CompactGroupByToolNamePerSeverity = 3,
+    /**
+     * Compact information about findings grouped by SARIF file with the level representation.
+     * @example
+     * ```text
+     * grype-results-01.sarif
+     * Error: 1, Warning: 2, Note: 1
+     * grype-results-02.sarif
+     * Warning: 3, Note: 19
+     * ```
+     */
+    CompactGroupBySarifPerLevel = 4,
+    /**
+     * Compact information about findings grouped by SARIF file with the severity
+     * representation.
+     * @example
+     * ```text
+     * grype-results-01.sarif
+     * High: 3, Medium: 1, Low: 11
+     * grype-results-02.sarif
+     * Critical: 1, Medium: 1, Low: 9
+     * ```
+     */
+    CompactGroupBySarifPerSeverity = 5,
+    /**
+     * Compact information about findings with the level representation.
+     * @example
+     * ```text
+     * Total
+     * Error: 1, Warning: 5, Note: 20
+     * ```
+     */
+    CompactTotalPerLevel = 6,
+    /**
+     * Compact information about findings with the severity representation.
+     * @example
+     * ```text
+     * Total
+     * Critical: 1, High: 3, Medium: 2, Low: 20
+     * ```
+     */
+    CompactTotalPerSeverity = 7
+}
+
+/**
+ * SARIF file extension.
  * @public
  */
-export declare type SarifLog = Log;
+export declare type SarifFileExtension = 'sarif' | 'json';
 
 /**
- * Options for how to output the results in the Slack message.
+ * Represents options for the provided SARIF file(s), such as path, should files
+ * from this path be retrieved recursively or not, and file extension.
  * @public
  */
-export declare type SarifToSlackOutput = {
-    groupBy?: GroupResultsBy;
-    calculateBy?: CalculateResultsBy;
+export declare type SarifOptions = {
+    path: string;
+    recursive?: boolean;
+    extension?: SarifFileExtension;
 };
 
 /**
  * Service to convert SARIF files to Slack messages and send them.
  * @public
  */
-export declare class SarifToSlackService {
-    private readonly _slackMessages;
+export declare class SarifToSlackClient {
+    private _message?;
+    private _sarifModel?;
+    private _sendIf;
     private constructor();
+    private static createRunIdGenerator;
+    static create(opts: SarifToSlackClientOptions): Promise<SarifToSlackClient>;
+    private static buildModel;
     /**
-     * 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
+     * The main function to initialize a list of {@link SlackMessage} objects based
+     * on the given SARIF file(s).
+     * @param sarifModel An instance of {@link SarifModel} object.
+     * @param opts An instance of {@link SarifToSlackClientOptions} object.
+     * @returns A map where key is the SARIF file and value is an instance of
+     * {@link SlackMessage} object
+     * @private
      */
-    static create(opts: SarifToSlackServiceOptions): Promise<SarifToSlackService>;
+    private static initialize;
     /**
-     * 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.
+     * Sends a Slack message.
      * @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>;
+    send(): Promise<void>;
+    private get shouldSendMessage();
 }
 
 /**
- * Options for the SarifToSlackService.
+ * Options for the SarifToSlackClient.
  * @public
  */
-export declare type SarifToSlackServiceOptions = {
+export declare type SarifToSlackClientOptions = {
     webhookUrl: string;
-    sarifPath: string;
+    sarif: SarifOptions;
     username?: string;
     iconUrl?: string;
-    color?: string;
+    color?: ColorOptions;
     log?: LogOptions;
     header?: IncludeAwareWithValueOptions;
     footer?: FooterOptions;
     actor?: IncludeAwareWithValueOptions;
     run?: IncludeAwareOptions;
-    output?: SarifToSlackOutput;
+    representation?: RepresentationType;
+    sendIf?: SendIf;
 };
 
+/**
+ * This enum represents the condition on when message should be sent. If this
+ * condition is satisfied then message is sent, otherwise - message is not sent.
+ * @public
+ */
+export declare enum SendIf {
+    /**
+     * Send message only if there is at least one finding with "Critical" severity.
+     * Since it is the higher possible severity, it is the same as "Critical" or
+     * higher.
+     */
+    SeverityCritical = 0,
+    /**
+     * Send message only if there is at least one finding with "High" severity.
+     */
+    SeverityHigh = 1,
+    /**
+     * Send message only if there is at least one finding with "High" severity or
+     * higher, that includes "High" and "Critical".
+     */
+    SeverityHighOrHigher = 2,
+    /**
+     * Send message only if there is at least one finding with "Medium" severity.
+     */
+    SeverityMedium = 3,
+    /**
+     * Send message only if there is at least one finding with "Medium" severity
+     * or higher, that includes "Medium", "High" and "Critical".
+     */
+    SeverityMediumOrHigher = 4,
+    /**
+     * Send message only if there is at least one finding with "Low" severity.
+     */
+    SeverityLow = 5,
+    /**
+     * Send message only if there is at least one finding with "Low" severity or
+     * higher, that includes "Low", "Medium", "High" and "Critical".
+     */
+    SeverityLowOrHigher = 6,
+    /**
+     * Send message only if there is at least one finding with "None" severity.
+     */
+    SeverityNone = 7,
+    /**
+     * Send message only if there is at least one finding with "None" severity or
+     * higher, that includes "None", "Low", "Medium", "High" and "Critical".
+     */
+    SeverityNoneOrHigher = 8,
+    /**
+     * Send message only if there is at least one finding with "Unknown" severity.
+     */
+    SeverityUnknown = 9,
+    /**
+     * Send message only if there is at least one finding with "Unknown" severity
+     * or higher, that includes "Unknown", "None", "Low", "Medium", "High" and "Critical".
+     */
+    SeverityUnknownOrHigher = 10,
+    /**
+     * Send message only if there is at least one finding with "Error" level.
+     * Since it is the higher possible level, it is the same as "Error" or higher.
+     */
+    LevelError = 11,
+    /**
+     * Send message only if there is at least one finding with "Warning" level.
+     */
+    LevelWarning = 12,
+    /**
+     * Send message only if there is at least one finding with "Warning" level or
+     * higher, that includes "Warning" and "Error".
+     */
+    LevelWarningOrHigher = 13,
+    /**
+     * Send message only if there is at least one finding with "Note" level.
+     */
+    LevelNote = 14,
+    /**
+     * Send message only if there is at least one finding with "Note" level or
+     * higher, that includes "Note", "Warning" and "Error.
+     */
+    LevelNoteOrHigher = 15,
+    /**
+     * Send message only if there is at least one finding with "None" level.
+     */
+    LevelNone = 16,
+    /**
+     * Send message only if there is at least one finding with "None" level or
+     * higher, that includes "None", "Note", "Warning" and "Error.
+     */
+    LevelNoneOrHigher = 17,
+    /**
+     * Send message only if there is at least one finding with "Unknown" level.
+     */
+    LevelUnknown = 18,
+    /**
+     * Send message only if there is at least one finding with "Unknown" level or
+     * higher, that includes "Unknown", "None", "Note", "Warning" and "Error.
+     */
+    LevelUnknownOrHigher = 19,
+    /**
+     * Always send a message.
+     */
+    Always = 20,
+    /**
+     * Send a message if at least 1 vulnerability is found.
+     */
+    Some = 21,
+    /**
+     * Send a message only if no vulnerabilities are found.
+     */
+    Empty = 22,
+    /**
+     * Never send a message.
+     */
+    Never = 23
+}
+
 /**
  * Interface for a Slack message that can be sent.
  * @public
@@ -269,10 +531,10 @@ export declare interface SlackMessage {
      * @returns A promise that resolves to the response from the Slack webhook.
      */
     send: () => Promise<string>;
-    /**
-     * The SARIF log associated with this Slack message.
-     */
-    sarif: SarifLog;
+    withActor(actor?: string): void;
+    withFooter(text?: string, type?: FooterType): void;
+    withHeader(header?: string): void;
+    withRun(): void;
 }
 
 export { }

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.9"
+      "packageVersion": "7.52.10"
     }
   ]
 }