Add support for notice annotation and additional properties

packages/core/src/command.ts

@@ -6,7 +6,7 @@ import {toCommandValue} from './utils'
 // We use any as a valid input type
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-interface CommandProperties {
+export interface CommandProperties {
   [key: string]: any
 }
 

packages/core/src/core.ts

@@ -1,6 +1,6 @@
 import {issue, issueCommand} from './command'
 import {issueCommand as issueFileCommand} from './file-command'
-import {toCommandValue} from './utils'
+import {toCommandProperties, toCommandValue} from './utils'
 
 import * as os from 'os'
 import * as path from 'path'
@@ -31,6 +31,38 @@ export enum ExitCode {
   Failure = 1
 }
 
+/**
+ * Optional properties that can be sent with annotatation commands (notice, error, and warning)
+ * See: https://docs.github.com/en/rest/reference/checks#create-a-check-run for more information about annotations. 
+ */
+export interface AnnotationProperties {
+  /**
+   * A title for the annotation. 
+  */
+  title?: string
+
+  /**
+   * The start line for the annotation.
+  */
+  startLine?: string
+
+  /**
+   * The end line for the annotation. Defaults to `startLine` when `startLine` is provided. 
+  */
+  endLine?: string
+
+  /**
+   * The start column for the annotation. Cannot be sent when `startLine` and `endLine` are different values. 
+  */
+  startColumn?: string
+
+  /**
+   * The start column for the annotation. Cannot be sent when `startLine` and `endLine` are different values. 
+   * Defaults to `startColumn` when `startColumn` is provided. 
+  */
+  endColumn?: string
+}
+
 //-----------------------------------------------------------------------
 // Variables
 //-----------------------------------------------------------------------
@@ -199,17 +231,28 @@ export function debug(message: string): void {
 /**
  * Adds an error issue
  * @param message error issue message. Errors will be converted to string via toString()
+ * @param properties optional properties to add to the annotation. 
  */
-export function error(message: string | Error): void {
-  issue('error', message instanceof Error ? message.toString() : message)
+export function error(message: string | Error, properties: AnnotationProperties = {}): void {
+  issueCommand('error', toCommandProperties(properties), message instanceof Error ? message.toString() : message)
 }
 
 /**
- * Adds an warning issue
+ * Adds a warning issue
  * @param message warning issue message. Errors will be converted to string via toString()
+ * @param properties optional properties to add to the annotation. 
+ */
+export function warning(message: string | Error, properties: AnnotationProperties = {}): void {
+  issueCommand('warning', toCommandProperties(properties), message instanceof Error ? message.toString() : message)
+}
+
+/**
+ * Adds a notice issue
+ * @param message notice issue message. Errors will be converted to string via toString()
+ * @param properties optional properties to add to the annotation. 
  */
-export function warning(message: string | Error): void {
-  issue('warning', message instanceof Error ? message.toString() : message)
+export function notice(message: string | Error, properties: AnnotationProperties = {}): void {
+  issueCommand('notice', toCommandProperties(properties), message instanceof Error ? message.toString() : message)
 }
 
 /**

packages/core/src/utils.ts

@@ -1,6 +1,9 @@
 // We use any as a valid input type
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { AnnotationProperties} from "./core"
+import {CommandProperties} from './command'
+
 /**
  * Sanitizes an input into a string so it can be passed into issueCommand safely
  * @param input input to sanitize into a string
@@ -13,3 +16,25 @@ export function toCommandValue(input: any): string {
   }
   return JSON.stringify(input)
 }
+
+
+/**
+ * 
+ * @param annotationProperties 
+ * @returns The command properties to send with the actual annotaiton command
+ * See: https://github.com/actions/runner/blob/ee34f4842e747b452e13235836c92b2bb1606816/src/Runner.Worker/ActionCommandManager.cs#L566
+ */
+export function toCommandProperties(annotationProperties: AnnotationProperties): CommandProperties {
+
+  if (!Object.keys(annotationProperties).length) {
+    return {}
+  }
+
+  return {
+    title: annotationProperties.title,
+    line: annotationProperties.startLine,
+    end_line: annotationProperties.endLine,
+    col: annotationProperties.startColumn,
+    end_column: annotationProperties.endColumn,
+  }
+}