@jsenv/github-check-run 0.0.1

package/README.md

@@ -0,0 +1,53 @@
+# GitHub check run [![npm package](https://img.shields.io/npm/v/@jsenv/github-check-run.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/github-check-run)
+
+```js
+import { startGithubCheckRun } from "@jsenv/github-check-run";
+
+const values = [1_000, 2_000, 4_000];
+
+const githubCheck = await startGithubCheckRun({
+  githubToken: "",
+  repositoryOwner: "dmail",
+  repositoryName: "repo-name",
+  commitSha: "",
+  checkName: "demo",
+  checkTitle: "Running demo",
+  checkSummary: `preparing execution of ${values.length} timeouts`,
+});
+
+try {
+  let index = 0;
+  for (const value of values) {
+    githubCheck.progress({
+      summary: `executing timeout ${index + 1}/${values.length}`,
+    });
+    await new Promise((resolve) => {
+      setTimeout(resolve, value);
+    });
+    index++;
+  }
+  await githubCheck.pass({
+    summary: `${values.length} timeout execution done`,
+  });
+} catch (e) {
+  await githubCheck.fail({
+    summary: `error while executing timeout number ${index + 1}: ${e.stack}`,
+  });
+}
+```
+
+If the code is executed inside a Github workflow, several parameters can be retrieved using `readGitHubWorkflowEnv`:
+
+```js
+import {
+  startGithubCheckRun,
+  readGitHubWorkflowEnv,
+} from "@jsenv/github-check-run";
+
+const githubCheck = await startGithubCheckRun({
+  ...readGitHubWorkflowEnv(),
+  checkName: "demo",
+  checkTitle: "Running demo",
+  checkSummary: `Executing ${values.length} setTimeouts`,
+});
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jsenv/github-check-run",
+  "version": "0.0.1",
+  "description": "Interact with GitHub check rest API",
+  "license": "MIT",
+  "author": {
+    "name": "dmail",
+    "email": "dmaillard06@gmail.com",
+    "url": "https://twitter.com/damienmaillard"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsenv/workflow",
+    "directory": "packages/github-check-run"
+  },
+  "engines": {
+    "node": ">=18.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/main.js"
+    },
+    "./*": "./*"
+  },
+  "main": "./src/main.js",
+  "files": [
+    "/src/"
+  ],
+  "scripts": {
+    "test": "node ./scripts/test.mjs"
+  },
+  "dependencies": {
+    "@jsenv/fetch": "1.1.40",
+    "@jsenv/log": "3.4.0"
+  }
+}

package/src/internal/github_rest_api.js

@@ -0,0 +1,117 @@
+import { fetchUrl } from "@jsenv/fetch";
+
+export const GET = ({ url, githubToken, headers }) => {
+  return sendHttpRequest({
+    url,
+    method: "GET",
+    headers: {
+      ...tokenToHeaders(githubToken),
+      headers,
+    },
+    responseStatusHandlers: {
+      200: async (response) => {
+        const json = await response.json();
+        return json;
+      },
+      404: () => null,
+    },
+  });
+};
+
+export const POST = ({ url, body, githubToken, headers }) => {
+  return sendHttpRequest({
+    url,
+    method: "POST",
+    headers: {
+      ...tokenToHeaders(githubToken),
+      headers,
+    },
+    body: JSON.stringify(body),
+    responseStatusHandlers: {
+      201: async (response) => {
+        const json = await response.json();
+        return json;
+      },
+    },
+  });
+};
+
+export const PATCH = ({ signal, url, body, githubToken, headers }) => {
+  return sendHttpRequest({
+    signal,
+    url,
+    method: "PATCH",
+    headers: {
+      ...tokenToHeaders(githubToken),
+      headers,
+    },
+    body: JSON.stringify(body),
+    responseStatusHandlers: {
+      200: async (response) => {
+        const json = await response.json();
+        return json;
+      },
+    },
+  });
+};
+
+const tokenToHeaders = (token) => {
+  if (!token) {
+    throw new Error(`missing token, request will not be authorized.`);
+  }
+  return {
+    authorization: `token ${token}`,
+  };
+};
+
+const sendHttpRequest = async ({
+  signal,
+  url,
+  method,
+  headers,
+  body,
+  responseStatusHandlers = {},
+}) => {
+  let response;
+  try {
+    response = await fetchUrl(url, {
+      signal,
+      method,
+      headers: {
+        ...(typeof body === "undefined"
+          ? {}
+          : { "content-length": Buffer.byteLength(body) }),
+        ...headers,
+      },
+      body,
+    });
+  } catch (error) {
+    throw new Error(`network error during request.
+--- request method ---
+${method}
+--- request url ---
+${url}
+--- error stack ---
+${error.stack}`);
+  }
+
+  const { status } = response;
+  const responseStatusHandler = responseStatusHandlers[status];
+  if (responseStatusHandler) {
+    return responseStatusHandler(response);
+  }
+  const responseBodyAsJson = await response.json();
+  const error = new Error(`unexpected response status.
+--- response status ---
+${response.status}
+--- expected response status ---
+${Object.keys(responseStatusHandlers).join(", ")}
+--- request method ---
+${method}
+--- request url ---
+${url}
+--- response json ---
+${(JSON.stringify(responseBodyAsJson), null, "  ")}`);
+  error.responseStatus = status;
+  throw error;
+};

package/src/main.js

@@ -0,0 +1,2 @@
+export { startGithubCheckRun } from "./start_github_check_run.js";
+export { readGitHubWorkflowEnv } from "./read_github_workflow_env.js";

package/src/read_github_workflow_env.js

@@ -0,0 +1,28 @@
+// https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables
+export const readGitHubWorkflowEnv = () => {
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  if (!eventName) {
+    throw new Error(
+      `missing process.env.GITHUB_EVENT_NAME, we are not in a github workflow`,
+    );
+  }
+  if (eventName !== "pull_request" && eventName !== "pull_request_target") {
+    throw new Error(`must be called only in a pull request`);
+  }
+  const githubToken = process.env.GITHUB_TOKEN;
+  if (!githubToken) {
+    throw new Error(`missing githubToken`);
+  }
+  const githubRepository = process.env.GITHUB_REPOSITORY;
+  if (!githubRepository) {
+    throw new Error(`missing process.env.GITHUB_REPOSITORY`);
+  }
+  const [repositoryOwner, repositoryName] = githubRepository.split("/");
+  return {
+    rootDirectoryUrl: process.env.GITHUB_WORKSPACE,
+    githubToken,
+    repositoryOwner,
+    repositoryName,
+    commitSha: process.env.GITHUB_SHA,
+  };
+};

package/src/start_github_check_run.js

@@ -0,0 +1,201 @@
+/**
+ *
+ * https://github.com/IgnusG/jest-report-action/blob/c006b890ba3c3b650e6c55916a643ca82b64133b/tasks/github-api.js#L12
+ */
+
+import { createLogger } from "@jsenv/log";
+
+import { POST, PATCH } from "./internal/github_rest_api.js";
+
+/*
+annotation object contains the following:
+{path: filePath,
+title: `${ describe } > ${ test }`,
+start_line: location.start.line,
+end_line: location.end.line,
+annotation_level: 'failure',
+message: `${ title }\n${ expectations }\n\n${ stacktrace }`
+*/
+
+// https://docs.github.com/fr/rest/checks/runs?apiVersion=2022-11-28#create-a-check-run
+export const startGithubCheckRun = async ({
+  logLevel,
+  githubToken,
+  repositoryOwner,
+  repositoryName,
+  commitSha,
+  checkStatus = "in_progress",
+  checkName,
+  checkTitle,
+  checkSummary,
+}) => {
+  if (typeof githubToken !== "string") {
+    throw new TypeError(
+      `githubToken must be a string but received ${githubToken}`,
+    );
+  }
+  if (typeof repositoryOwner !== "string") {
+    throw new TypeError(
+      `repositoryOwner must be a string but received ${repositoryOwner}`,
+    );
+  }
+  if (typeof repositoryName !== "string") {
+    throw new TypeError(
+      `repositoryName must be a string but received ${repositoryName}`,
+    );
+  }
+  if (typeof commitSha !== "string") {
+    throw new TypeError(`commitSha must be a string but received ${commitSha}`);
+  }
+  if (typeof checkName !== "string") {
+    throw new TypeError(`checkName must be a string but received ${checkName}`);
+  }
+
+  const logger = createLogger({ logLevel });
+  logger.debug("create check on");
+
+  const check = await POST({
+    url: `/repos/${repositoryOwner}/${repositoryName}/check-runs`,
+    githubToken,
+    body: {
+      head_sha: commitSha,
+      status: checkStatus,
+      name: checkName,
+      output: {
+        title: checkTitle,
+        summary: checkSummary,
+      },
+    },
+  });
+
+  let previousUpdatePromise;
+  const update = async ({
+    status,
+    conclusion,
+    title,
+    summary,
+    annotations = [],
+  }) => {
+    if (previousUpdatePromise) {
+      await previousUpdatePromise;
+    }
+    previousUpdatePromise = (async () => {
+      let annotationsSent = 0;
+      const annotationsBatch = annotations.slice(annotationsSent, 50);
+      await PATCH({
+        url: `/repos/${repositoryOwner}/${repositoryName}/check-runs`,
+        githubToken,
+        body: {
+          head_sha: commitSha,
+          check_run_id: check.id,
+          ...(status ? { status } : {}),
+          ...(conclusion ? { conclusion } : {}),
+          output: {
+            ...(title ? { title } : {}),
+            ...(summary ? { summary } : {}),
+            annotations: annotationsBatch,
+          },
+        },
+      });
+      if (status) {
+        checkStatus = status;
+      }
+      if (title) {
+        checkTitle = title;
+      }
+      if (summary) {
+        checkSummary = summary;
+      }
+
+      annotationsSent += annotationsBatch.length;
+      while (annotationsSent < annotations.length) {
+        const annotationsBatch = annotations.slice(annotationsSent, 50);
+        await PATCH({
+          url: `/repos/${repositoryOwner}/${repositoryName}/check-runs`,
+          githubToken,
+          body: {
+            head_sha: commitSha,
+            check_run_id: check.id,
+            output: {
+              annotations: annotationsBatch,
+            },
+          },
+        });
+        annotationsSent += annotationsBatch.length;
+      }
+
+      previousUpdatePromise = null;
+    })();
+    return previousUpdatePromise;
+  };
+
+  let lastProgressCall;
+  let pendingAnnotations = [];
+  let pendingAbortController;
+  let msBetweenProgressCalls = 500;
+
+  return {
+    progress: async ({ title, summary, annotations = [] }) => {
+      const nowMs = Date.now();
+      const isFirstCall = !lastProgressCall;
+      lastProgressCall = nowMs;
+      if (isFirstCall) {
+        await update({
+          title,
+          summary,
+          annotations,
+        });
+        return;
+      }
+      if (pendingAbortController) {
+        pendingAbortController.abort();
+      }
+      const msEllapsedSinceLastProgressCall = nowMs - lastProgressCall;
+      const msEllapsedIsBigEnough =
+        msEllapsedSinceLastProgressCall > msBetweenProgressCalls;
+      if (msEllapsedIsBigEnough) {
+        annotations = [...pendingAnnotations, ...annotations];
+        pendingAnnotations.length = 0;
+        await update({
+          title,
+          summary,
+          annotations,
+        });
+        return;
+      }
+      pendingAnnotations.push(...annotations);
+      pendingAbortController = new AbortController();
+      await new Promise((resolve) => {
+        pendingAbortController.signal.onabort = resolve;
+        setTimeout(resolve, msBetweenProgressCalls);
+      });
+      if (pendingAbortController.signal.aborted) {
+        return;
+      }
+      pendingAbortController = null;
+      await update({
+        title,
+        summary,
+        annotations,
+      });
+    },
+    fail: ({ title, summary, annotations } = {}) => {
+      return update({
+        status: "completed",
+        conclusion: "failure",
+        title,
+        summary,
+        annotations,
+      });
+    },
+    pass: ({ title, summary, annotations } = {}) => {
+      return update({
+        status: "completed",
+        conclusion: "success",
+        title,
+        summary,
+        annotations,
+      });
+    },
+  };
+};