ci-cost-diff-action 0.1.0

package/src/github.js

@@ -0,0 +1,670 @@
+const API_VERSION = "2022-11-28";
+const MAX_PAGE_SIZE = 100;
+const MAX_PAGINATION_PAGES = 1000;
+const MAX_FILTERED_WORKFLOW_RUNS = 1000;
+const MAX_REQUEST_ATTEMPTS = 3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+const DEFAULT_RETRY_DELAY_MS = 250;
+const MAX_FALLBACK_RETRY_DELAY_MS = 30000;
+const MAX_SERVER_RETRY_DELAY_MS = 60000;
+
+/**
+ * Generic GitHub REST request options.
+ * @typedef {object} ApiRequestOptions
+ * @property {string} token GitHub token.
+ * @property {string} path Absolute API URL or path under `GITHUB_API_URL`.
+ * @property {string} [method="GET"] HTTP method.
+ * @property {unknown} [body] JSON-serializable request body.
+ * @property {boolean} [allow404=false] Return null instead of throwing on 404.
+ * @property {number} [timeoutMs=30000] Fetch timeout in milliseconds.
+ * @property {number} [retryDelayMs=250] Base retry delay in milliseconds.
+ */
+
+/**
+ * Workflow run fields used by baseline lookup and report links.
+ * @typedef {object} GitHubWorkflowRun
+ * @property {string|number} id Workflow run id.
+ * @property {string|number} [run_number] Human-readable run number.
+ * @property {string} [head_branch] Branch name associated with the run.
+ * @property {string} [html_url] Browser URL for the run.
+ * @property {string|number} [workflow_id] Workflow id used for baseline lookup.
+ * @property {string} [created_at] Run creation timestamp.
+ * @property {string} [run_started_at] Run start timestamp.
+ * @property {string} [conclusion] Run conclusion.
+ */
+
+/**
+ * Authenticated GitHub user fields used for comment ownership checks.
+ * @typedef {object} GitHubUser
+ * @property {string} [login] GitHub login.
+ */
+
+/**
+ * GitHub App fields used for Actions-authored comments.
+ * @typedef {object} GitHubApp
+ * @property {string} [slug] GitHub App slug.
+ */
+
+/**
+ * Minimal issue comment shape returned by the GitHub API calls in this module.
+ * @typedef {object} GitHubIssueComment
+ * @property {string|number} id Issue comment id.
+ * @property {string} [body] Comment body.
+ * @property {GitHubUser} [user] Comment author.
+ * @property {GitHubApp} [performed_via_github_app] App that created the comment.
+ */
+
+/**
+ * Options for finding the nearest older successful baseline run.
+ * @typedef {object} FindBaselineRunOptions
+ * @property {string} token GitHub token.
+ * @property {string} owner Repository owner.
+ * @property {string} repo Repository name.
+ * @property {string|number} workflowId Workflow id or workflow file name.
+ * @property {string} branch Baseline branch.
+ * @property {string} [event] Optional workflow event filter.
+ * @property {number} [limit] Total number of successful runs to inspect.
+ * @property {string|number} [currentRunId] Current workflow run id to exclude.
+ * @property {string} [currentRunCreatedAt] Current workflow run creation timestamp.
+ * @property {string} [currentRunStartedAt] Current workflow run start timestamp.
+ * @property {string|number} [currentRunNumber] Current workflow run number.
+ */
+
+function apiBaseUrl() {
+  return (process.env.GITHUB_API_URL || "https://api.github.com").replace(/\/+$/g, "");
+}
+
+/**
+ * Performs a GitHub REST API request with action-standard headers.
+ * @param {ApiRequestOptions} options Request options.
+ * @returns {Promise<unknown|null>} Parsed JSON response, or null for 204 responses.
+ */
+export async function apiRequest({ token, path, method = "GET", body, allow404 = false, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, retryDelayMs = DEFAULT_RETRY_DELAY_MS }) {
+  const request = apiRequestContext({ token, path, method, body, allow404, timeoutMs, retryDelayMs });
+
+  for (let attempt = 1; attempt <= MAX_REQUEST_ATTEMPTS; attempt += 1) {
+    const outcome = await apiRequestAttempt(request, attempt);
+    if (outcome.done) {
+      return outcome.value;
+    }
+  }
+
+  throw new Error(`GitHub API ${request.method} ${request.url} failed after ${MAX_REQUEST_ATTEMPTS} attempts.`);
+}
+
+function apiRequestContext({ token, path, method, body, allow404, timeoutMs, retryDelayMs }) {
+  return {
+    token,
+    method,
+    body,
+    allow404,
+    timeoutMs,
+    retryDelayMs,
+    url: path.startsWith("http") ? path : `${apiBaseUrl()}${path}`
+  };
+}
+
+async function apiRequestAttempt(request, attempt) {
+  const response = await fetchApiResponseOrRetry(request.url, request, attempt, request.retryDelayMs);
+  if (!response) {
+    return { done: false };
+  }
+
+  const result = await apiResultFromResponse(response, request);
+  return handleApiResult(result, response, request, attempt);
+}
+
+async function handleApiResult(result, response, request, attempt) {
+  if (shouldRetryResult(result, attempt)) {
+    await sleep(retryDelay(response, attempt, request.retryDelayMs));
+    return { done: false };
+  }
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return { done: true, value: result.value };
+}
+
+function shouldRetryResult(result, attempt) {
+  return result.retry && attempt < MAX_REQUEST_ATTEMPTS;
+}
+
+async function fetchApiResponseOrRetry(url, request, attempt, retryDelayMs) {
+  try {
+    return await fetchApiResponse(url, request);
+  } catch (error) {
+    if (attempt >= MAX_REQUEST_ATTEMPTS) {
+      throw error;
+    }
+
+    await sleep(retryDelay(null, attempt, retryDelayMs));
+    return null;
+  }
+}
+
+async function fetchApiResponse(url, request) {
+  return fetch(url, {
+    method: request.method,
+    headers: apiHeaders(request.token),
+    body: request.body === undefined ? undefined : JSON.stringify(request.body),
+    signal: requestSignal(request.timeoutMs)
+  });
+}
+
+function apiHeaders(token) {
+  return {
+    Accept: "application/vnd.github+json",
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "X-GitHub-Api-Version": API_VERSION,
+    "User-Agent": "ci-cost-diff-action"
+  };
+}
+
+function requestSignal(timeoutMs) {
+  return timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+}
+
+async function apiResultFromResponse(response, { method, url, allow404 }) {
+  if (allow404 && response.status === 404) {
+    return { value: null };
+  }
+
+  if (response.ok) {
+    return { value: await apiSuccessValue(response, method, url) };
+  }
+
+  const message = await response.text();
+  return {
+    error: new Error(`GitHub API ${method} ${url} failed with ${response.status}: ${message}`),
+    retry: isRetryableResponse(response, message)
+  };
+}
+
+async function apiSuccessValue(response, method, url) {
+  if (response.status === 204) {
+    return null;
+  }
+
+  try {
+    return await response.json();
+  } catch (error) {
+    throw new Error(`GitHub API ${method} ${url} returned invalid JSON: ${error.message}`);
+  }
+}
+
+function isRetryableResponse(response, message) {
+  return response.status === 429
+    || response.status >= 500
+    || response.headers.has("retry-after")
+    || response.headers.get("x-ratelimit-remaining") === "0"
+    || isSecondaryRateLimitResponse(response, message);
+}
+
+function isSecondaryRateLimitResponse(response, message) {
+  return response.status === 403 && /secondary rate limit|abuse detection/i.test(message);
+}
+
+function retryDelay(response, attempt, retryDelayMs) {
+  const headerDelay = response ? retryAfterDelay(response) ?? rateLimitResetDelay(response) : null;
+  const fallbackDelay = retryDelayMs * 2 ** (attempt - 1);
+  return headerDelay === null
+    ? Math.min(fallbackDelay, MAX_FALLBACK_RETRY_DELAY_MS)
+    : Math.min(headerDelay, MAX_SERVER_RETRY_DELAY_MS);
+}
+
+function retryAfterDelay(response) {
+  const header = response.headers.get("retry-after");
+  if (header === null) {
+    return null;
+  }
+
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+
+  const delayMs = Date.parse(header) - Date.now();
+  return Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : null;
+}
+
+function rateLimitResetDelay(response) {
+  const header = response.headers.get("x-ratelimit-reset");
+  if (header === null) {
+    return null;
+  }
+
+  const seconds = Number(header);
+  const delayMs = seconds * 1000 - Date.now();
+  return Number.isFinite(delayMs) && delayMs >= 0 ? delayMs : null;
+}
+
+function sleep(ms) {
+  return ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+}
+
+/**
+ * Fetches one workflow run.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.runId Workflow run id.
+ * @returns {Promise<GitHubWorkflowRun>} Workflow run response.
+ */
+export async function getWorkflowRun({ token, owner, repo, runId }) {
+  const data = await apiRequest({
+    token,
+    path: `/repos/${repoPath(owner, repo)}/actions/runs/${numericPathSegment(runId, "run-id")}`
+  });
+
+  return workflowRunResponse(data, "workflow run");
+}
+
+/**
+ * Fetches the authenticated token user.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @returns {Promise<GitHubUser>} Authenticated user response.
+ */
+export async function getAuthenticatedUser({ token }) {
+  return apiRequest({
+    token,
+    path: "/user"
+  });
+}
+
+/**
+ * Lists all jobs for a workflow run, following pagination.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.runId Workflow run id.
+ * @param {"all"|"latest"} [options.filter="all"] GitHub job attempt filter.
+ * @returns {Promise<import("./cost.js").GitHubJob[]>} Workflow jobs.
+ */
+export async function listJobsForRun({ token, owner, repo, runId, filter = "all" }) {
+  const jobs = [];
+
+  for (let page = 1; ; page += 1) {
+    assertPaginationPage(page, "workflow jobs");
+    const params = new URLSearchParams({
+      per_page: String(MAX_PAGE_SIZE),
+      page: String(page),
+      filter
+    });
+
+    const data = await apiRequest({
+      token,
+      path: `/repos/${repoPath(owner, repo)}/actions/runs/${numericPathSegment(runId, "run-id")}/jobs?${params.toString()}`
+    });
+    const pageJobs = workflowJobArrayField(data, "jobs", "workflow jobs");
+
+    jobs.push(...pageJobs);
+    if (pageJobs.length < MAX_PAGE_SIZE) {
+      return jobs;
+    }
+  }
+}
+
+function assertPaginationPage(page, resource) {
+  if (page > MAX_PAGINATION_PAGES) {
+    throw new Error(`GitHub ${resource} pagination exceeded ${MAX_PAGINATION_PAGES} pages; refusing to continue after ${MAX_PAGINATION_PAGES * MAX_PAGE_SIZE} items.`);
+  }
+}
+
+/**
+ * Lists successful workflow runs for a workflow, branch, and optional event.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.workflowId Workflow id or workflow file name.
+ * @param {string} options.branch Branch to search.
+ * @param {string} [options.event] Optional event filter.
+ * @param {number} [options.limit=20] Compatibility default for page size.
+ * @param {number} [options.page=1] Page number to fetch.
+ * @param {number} [options.perPage] Page size before GitHub's 100 item cap.
+ * @returns {Promise<GitHubWorkflowRun[]>} Successful workflow runs.
+ */
+export async function listSuccessfulWorkflowRuns({ token, owner, repo, workflowId, branch, event, limit = 20, page = 1, perPage = limit }) {
+  const params = new URLSearchParams({
+    status: "success"
+  });
+
+  if (branch) {
+    params.set("branch", branch);
+  }
+
+  params.set("per_page", String(Math.min(Math.max(perPage, 1), MAX_PAGE_SIZE)));
+  params.set("page", String(page));
+
+  if (event) {
+    params.set("event", event);
+  }
+
+  const data = await apiRequest({
+    token,
+    path: `/repos/${repoPath(owner, repo)}/actions/workflows/${pathSegment(workflowId, "workflow-id")}/runs?${params.toString()}`,
+    allow404: true
+  });
+
+  return data === null ? [] : workflowRunArrayField(data, "workflow_runs", "workflow runs");
+}
+
+/**
+ * Finds the nearest older successful run to use as the cost baseline.
+ * @param {FindBaselineRunOptions} options Baseline lookup options.
+ * @returns {Promise<GitHubWorkflowRun|null>} Baseline run, or null when none is found.
+ */
+export async function findBaselineRun(options) {
+  const search = baselineSearchContext(options);
+
+  for (let page = 1, inspected = 0; shouldScanBaselinePage(inspected, search); page += 1) {
+    assertPaginationPage(page, "workflow runs");
+    const result = await inspectBaselinePage(options, page, inspected, search);
+
+    if (result.done) {
+      return result.baselineRun;
+    }
+
+    inspected = result.inspected;
+  }
+
+  return null;
+}
+
+function baselineSearchContext(options) {
+  const requestedLookbackRuns = Math.max(parseRunNumber(options.limit) ?? 20, 1);
+  const lookbackRuns = Math.min(requestedLookbackRuns, MAX_FILTERED_WORKFLOW_RUNS);
+  return {
+    currentRunId: String(options.currentRunId ?? ""),
+    currentRunCreatedAt: parseTimestamp(options.currentRunStartedAt ?? options.currentRunCreatedAt),
+    currentRunNumber: parseRunNumber(options.currentRunNumber),
+    lookbackRuns,
+    perPage: Math.min(lookbackRuns, MAX_PAGE_SIZE)
+  };
+}
+
+function shouldScanBaselinePage(inspected, search) {
+  return inspected < search.lookbackRuns;
+}
+
+async function inspectBaselinePage(options, page, inspected, search) {
+  const runs = await baselinePageRuns(options, page, search);
+  const inspectedRuns = runs.slice(0, search.lookbackRuns - inspected);
+  const baselineRun = firstBaselineRun(inspectedRuns, search);
+  return baselineRun
+    ? { done: true, baselineRun }
+    : baselinePageResult(runs, inspected, inspectedRuns.length, search);
+}
+
+async function baselinePageRuns(options, page, search) {
+  return listSuccessfulWorkflowRuns({ ...options, page, perPage: search.perPage });
+}
+
+function baselinePageResult(runs, inspected, inspectedCount, search) {
+  const nextInspected = inspected + inspectedCount;
+  return runs.length < search.perPage || nextInspected >= search.lookbackRuns
+    ? { done: true, baselineRun: null }
+    : { done: false, inspected: nextInspected };
+}
+
+function firstBaselineRun(runs, search) {
+  return runs.reduce((bestRun, run) => (
+    isBaselineCandidate(run, search) && isNearerBaselineRun(run, bestRun) ? run : bestRun
+  ), null);
+}
+
+function isBaselineCandidate(run, search) {
+  return (
+    String(run.id) !== search.currentRunId
+    && run.conclusion === "success"
+    && isOlderThanCurrentRun(run, search)
+  );
+}
+
+function isNearerBaselineRun(run, bestRun) {
+  return !bestRun || compareBaselineRunOrder(run, bestRun) > 0;
+}
+
+function compareBaselineRunOrder(left, right) {
+  const timestampOrder = compareNullableNumber(
+    parseTimestamp(left.run_started_at ?? left.created_at),
+    parseTimestamp(right.run_started_at ?? right.created_at)
+  );
+
+  return timestampOrder === 0
+    ? compareNullableNumber(parseRunNumber(left.run_number), parseRunNumber(right.run_number))
+    : timestampOrder;
+}
+
+function compareNullableNumber(left, right) {
+  if (left === null && right === null) {
+    return 0;
+  }
+
+  if (left === null) {
+    return -1;
+  }
+
+  return right === null ? 1 : Math.sign(left - right);
+}
+
+function isOlderThanCurrentRun(run, { currentRunCreatedAt, currentRunNumber }) {
+  const runCreatedAt = parseTimestamp(run.run_started_at ?? run.created_at);
+  if (currentRunCreatedAt !== null && runCreatedAt !== null && runCreatedAt !== currentRunCreatedAt) {
+    return runCreatedAt < currentRunCreatedAt;
+  }
+
+  const runNumber = parseRunNumber(run.run_number);
+  if (currentRunNumber !== null && runNumber !== null) {
+    return runNumber < currentRunNumber;
+  }
+
+  return false;
+}
+
+function parseTimestamp(value) {
+  const parsed = new Date(value ?? "").getTime();
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseRunNumber(value) {
+  const rawValue = String(value ?? "").trim();
+  if (!rawValue) {
+    return null;
+  }
+
+  const parsed = Number(rawValue);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/**
+ * Lists all issue comments, following pagination.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.issueNumber Issue or pull request number.
+ * @returns {Promise<GitHubIssueComment[]>} Issue comments.
+ */
+export async function listIssueComments({ token, owner, repo, issueNumber }) {
+  const comments = [];
+
+  for (let page = 1; ; page += 1) {
+    assertPaginationPage(page, "issue comments");
+    const data = await apiRequest({
+      token,
+      path: `/repos/${repoPath(owner, repo)}/issues/${numericPathSegment(issueNumber, "issue-number")}/comments?per_page=${MAX_PAGE_SIZE}&page=${page}`
+    });
+    const pageComments = objectResponseArray(data, "issue comments");
+
+    comments.push(...pageComments);
+    if (pageComments.length < MAX_PAGE_SIZE) {
+      return comments;
+    }
+  }
+}
+
+function objectArrayField(data, field, resource) {
+  if (data && Array.isArray(data[field])) {
+    return validateObjectArray(data[field], resource);
+  }
+
+  throw new Error(`GitHub API returned an invalid ${resource} response: expected ${field} array.`);
+}
+
+function workflowRunArrayField(data, field, resource) {
+  const runs = objectArrayField(data, field, resource);
+  for (const [index, run] of runs.entries()) {
+    const itemResource = `${resource} item ${index}`;
+    assertWorkflowRunField(run, "id", itemResource);
+    assertWorkflowRunField(run, "conclusion", itemResource);
+    assertWorkflowRunOrderField(run, itemResource);
+  }
+
+  return runs;
+}
+
+function workflowJobArrayField(data, field, resource) {
+  const jobs = objectArrayField(data, field, resource);
+  for (const [index, job] of jobs.entries()) {
+    assertWorkflowRunField(job, "id", `${resource} item ${index}`);
+  }
+
+  return jobs;
+}
+
+function objectResponseArray(data, resource) {
+  if (Array.isArray(data)) {
+    return validateObjectArray(data, resource);
+  }
+
+  throw new Error(`GitHub API returned an invalid ${resource} response: expected an array.`);
+}
+
+function workflowRunResponse(data, resource) {
+  const run = objectResponse(data, resource);
+  assertWorkflowRunField(run, "id", resource);
+  assertWorkflowRunField(run, "workflow_id", resource);
+  assertWorkflowRunOrderField(run, resource);
+
+  return run;
+}
+
+function objectResponse(data, resource) {
+  if (data && !Array.isArray(data) && typeof data === "object") {
+    return data;
+  }
+
+  throw new Error(`GitHub API returned an invalid ${resource} response: expected an object.`);
+}
+
+function assertWorkflowRunField(run, field, resource) {
+  if (!hasNonEmptyScalar(run[field])) {
+    throw new Error(`GitHub API returned an invalid ${resource} response: expected ${field}.`);
+  }
+}
+
+function assertWorkflowRunOrderField(run, resource) {
+  if (parseTimestamp(run.run_started_at ?? run.created_at) !== null || parseRunNumber(run.run_number) !== null) {
+    return;
+  }
+
+  throw new Error(`GitHub API returned an invalid ${resource} response: expected run_started_at, created_at, or run_number.`);
+}
+
+function hasNonEmptyScalar(value) {
+  return (typeof value === "string" && value.trim() !== "") || typeof value === "number";
+}
+
+function validateObjectArray(items, resource) {
+  for (const [index, item] of items.entries()) {
+    if (!item || Array.isArray(item) || typeof item !== "object") {
+      throw new Error(`GitHub API returned an invalid ${resource} response: expected item ${index} to be an object.`);
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Creates a pull request issue comment.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.issueNumber Issue or pull request number.
+ * @param {string} options.body Comment body.
+ * @returns {Promise<GitHubIssueComment>} Created comment.
+ */
+export async function createIssueComment({ token, owner, repo, issueNumber, body }) {
+  return apiRequest({
+    token,
+    path: `/repos/${repoPath(owner, repo)}/issues/${numericPathSegment(issueNumber, "issue-number")}/comments`,
+    method: "POST",
+    body: { body }
+  });
+}
+
+/**
+ * Updates an existing issue comment.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.commentId Issue comment id.
+ * @param {string} options.body Replacement comment body.
+ * @returns {Promise<GitHubIssueComment>} Updated comment.
+ */
+export async function updateIssueComment({ token, owner, repo, commentId, body }) {
+  return apiRequest({
+    token,
+    path: `/repos/${repoPath(owner, repo)}/issues/comments/${numericPathSegment(commentId, "comment-id")}`,
+    method: "PATCH",
+    body: { body }
+  });
+}
+
+/**
+ * Deletes an existing issue comment.
+ * @param {object} options
+ * @param {string} options.token GitHub token.
+ * @param {string} options.owner Repository owner.
+ * @param {string} options.repo Repository name.
+ * @param {string|number} options.commentId Issue comment id.
+ * @returns {Promise<null>} Null on successful deletion.
+ */
+export async function deleteIssueComment({ token, owner, repo, commentId }) {
+  return apiRequest({
+    token,
+    path: `/repos/${repoPath(owner, repo)}/issues/comments/${numericPathSegment(commentId, "comment-id")}`,
+    method: "DELETE"
+  });
+}
+
+function repoPath(owner, repo) {
+  return `${pathSegment(owner, "owner")}/${pathSegment(repo, "repo")}`;
+}
+
+function pathSegment(value, name) {
+  const segment = String(value ?? "").trim();
+  if (!segment) {
+    throw new Error(`${name} must be a non-empty path segment.`);
+  }
+
+  return encodeURIComponent(segment);
+}
+
+function numericPathSegment(value, name) {
+  const segment = String(value ?? "").trim();
+  if (!/^[0-9]+$/.test(segment)) {
+    throw new Error(`${name} must be a numeric id.`);
+  }
+
+  return segment;
+}