From e1fb887f2ce61975299a9c556f5dbdb10b58c4d4 Mon Sep 17 00:00:00 2001
From: hugoalh <32359235+hugoalh@users.noreply.github.com>
Date: Fri, 22 Mar 2024 11:22:55 +0800
Subject: [PATCH] Update JSDoc and types

---
 environment_variable.ts | 12 ++++-----
 log.ts                  |  6 +++++
 utility.ts              | 56 ++++++++++++++++++++++++++++++++++++-----
 3 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/environment_variable.ts b/environment_variable.ts
index 10263ed..1a8e188 100644
--- a/environment_variable.ts
+++ b/environment_variable.ts
@@ -153,7 +153,7 @@ export function setEnvironmentVariables(pairs: { [key: string]: string; } | Map<
 	}
 }
 /**
- * **\[🅰️ ADVANCED\]** Handle the exportation of PATH in the GitHub Actions runner.
+ * **\[🅰️ ADVANCED\]** Handle the exportation of `PATH` in the GitHub Actions runner.
  * 
  * > **🛡️ Require Permission**
  * >
@@ -166,7 +166,7 @@ export class GitHubActionsPATHExportation {
 	#scopeCurrent: boolean;
 	#scopeSubsequent: boolean;
 	/**
-	 * **\[🅰️ ADVANCED\]** Create new instance to handle the exportation of PATH in the GitHub Actions runner.
+	 * **\[🅰️ ADVANCED\]** Create new instance to handle the exportation of `PATH` in the GitHub Actions runner.
 	 * 
 	 * > **🛡️ Require Permission**
 	 * >
@@ -180,7 +180,7 @@ export class GitHubActionsPATHExportation {
 		this.#scopeSubsequent = options.scopeSubsequent ?? true;
 	}
 	/**
-	 * Add the PATH.
+	 * Add the `PATH`.
 	 * @param {...string} paths
 	 * @returns {this}
 	 */
@@ -209,7 +209,7 @@ export class GitHubActionsPATHExportation {
 		return this;
 	}
 	/**
-	 * Clear the PATH for all of the subsequent steps which set in the current step.
+	 * Clear the `PATH` for all of the subsequent steps which set in the current step.
 	 * @returns {this}
 	 */
 	clearSubsequent(): this {
@@ -219,7 +219,7 @@ export class GitHubActionsPATHExportation {
 		return this;
 	}
 	/**
-	 * Optimize the PATH for all of the subsequent steps which set in the current step to reduce size whenever possible.
+	 * Optimize the `PATH` for all of the subsequent steps which set in the current step to reduce size whenever possible.
 	 * @returns {this}
 	 */
 	optimizeSubsequent(): this {
@@ -230,7 +230,7 @@ export class GitHubActionsPATHExportation {
 	}
 }
 /**
- * Add the PATH.
+ * Add the `PATH`.
  * 
  * > **🛡️ Require Permission**
  * >
diff --git a/log.ts b/log.ts
index af2aefd..37ab458 100644
--- a/log.ts
+++ b/log.ts
@@ -41,6 +41,9 @@ export function exitLogGroup(): void {
 export {
 	exitLogGroup as endLogGroup
 };
+/**
+ * GitHub Actions annotation type.
+ */
 export enum GitHubActionsAnnotationType {
 	error = "error",
 	Error = "error",
@@ -53,6 +56,9 @@ export enum GitHubActionsAnnotationType {
 	warning = "warning",
 	Warning = "warning"
 }
+/**
+ * GitHub Actions annotation properties.
+ */
 export interface GitHubActionsAnnotationProperties {
 	/**
 	 * Path of the issue file of the annotation.
diff --git a/utility.ts b/utility.ts
index 0ddfa32..6cae606 100644
--- a/utility.ts
+++ b/utility.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { isAbsolute as isPathAbsolute } from "node:path";
 import { getEnv } from "https://raw.githubusercontent.com/hugoalh-studio/cross-env-ts/v1.0.1/mod.ts";
-import { type JSONObject } from "https://raw.githubusercontent.com/hugoalh-studio/is-json-ts/v1.0.0/mod.ts";
+import { type JSONValueExtend } from "https://raw.githubusercontent.com/hugoalh-studio/is-json-ts/v1.0.0/mod.ts";
 /**
  * Get the URL of the GitHub API.
  * 
@@ -77,7 +77,7 @@ export function getRunnerArchitecture(): GitHubActionsRunnerArchitecture {
 }
 export {
 	getRunnerArchitecture as getRunnerArch
-}
+};
 /**
  * Get the debug status of the GitHub Actions runner.
  * 
@@ -479,7 +479,51 @@ export function getWorkflowRunURL(): URL {
 	if (typeof repository === "undefined") {
 		throw new ReferenceError(`Unable to get the GitHub Actions workflow run URI, environment variable \`GITHUB_REPOSITORY\` is not defined!`);
 	}
-	return new URL(`${getGitHubServerURL().toString()}/${repository}/actions/runs/${getWorkflowRunID()}`);
+	const serverURLString: string = getGitHubServerURL().toString();
+	return new URL(`${serverURLString}${serverURLString.endsWith("/") ? "" : "/"}${repository}/actions/runs/${getWorkflowRunID()}`);
+}
+export interface GitHubWebhookPayloadRepository {
+	full_name?: string;
+	html_url?: string;
+	name: string;
+	owner: {
+		login: string;
+		name?: string;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	[key: string]: JSONValueExtend | undefined;
+}
+/**
+ * GitHub Actions webhook event payload.
+ */
+export interface GitHubActionsWebhookEventPayload {
+	action?: string;
+	comment?: {
+		id: number;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	installation?: {
+		id: number;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	issue?: {
+		number: number;
+		html_url?: string;
+		body?: string;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	pull_request?: {
+		number: number;
+		html_url?: string;
+		body?: string;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	repository?: GitHubWebhookPayloadRepository;
+	sender?: {
+		type: string;
+		[key: string]: JSONValueExtend | undefined;
+	};
+	[key: string]: JSONValueExtend | undefined;
 }
 /**
  * Get the webhook event payload of the workflow run.
@@ -488,9 +532,9 @@ export function getWorkflowRunURL(): URL {
  * >
  * > - Environment Variable (`allow-env`)
  * > - File System - Read (`allow-read`)
- * @returns {JSONObject} Webhook event payload of the workflow run.
+ * @returns {GitHubActionsWebhookEventPayload} Webhook event payload of the workflow run.
  */
-export function getWorkflowRunWebhookEventPayload(): JSONObject {
+export function getWorkflowRunWebhookEventPayload(): GitHubActionsWebhookEventPayload {
 	const path: string | undefined = getEnv("GITHUB_EVENT_PATH");
 	if (typeof path === "undefined") {
 		throw new ReferenceError(`Unable to get the GitHub Actions workflow run webhook event payload, environment variable \`GITHUB_EVENT_PATH\` is not defined!`);
@@ -498,7 +542,7 @@ export function getWorkflowRunWebhookEventPayload(): JSONObject {
 	if (!isPathAbsolute(path)) {
 		throw new ReferenceError(`Unable to get the GitHub Actions workflow run webhook event payload, \`${path}\` (environment variable \`GITHUB_EVENT_PATH\`) is not a valid absolute path!`);
 	}
-	return JSON.parse(readFileSync(path, { encoding: "utf-8" })) as JSONObject;
+	return JSON.parse(readFileSync(path, { encoding: "utf-8" })) as GitHubActionsWebhookEventPayload;
 }
 /**
  * Get the SHA of the workflow.