@skuba-lib/api 0.0.0 → 0.1.0-skuba-lib-api-20250925050503

package/lib/github-B4auwKt7.js

@@ -0,0 +1,310 @@
+const require_chunk = require('./chunk-odGzh3W-.js');
+const require_logging = require('./logging-6TTEX4U4.js');
+const require_git = require('./git-DVG_dHiI.js');
+const path = require_chunk.__toESM(require("path"));
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+
+//#region src/github/octokit.ts
+const createRestClient = async (options) => new (await (import("@octokit/rest"))).Octokit(options);
+const graphql = async (query, parameters) => (await import("@octokit/graphql")).graphql(query, parameters);
+
+//#endregion
+//#region src/github/checkRun.ts
+const GITHUB_MAX_ANNOTATIONS = 50;
+/**
+* Suffixes the title with the number of annotations added, e.g.
+*
+* ```text
+* Build #12 failed (24 annotations added)
+* ```
+*/
+const suffixTitle = (title, inputAnnotations) => {
+	const addedAnnotations = inputAnnotations > GITHUB_MAX_ANNOTATIONS ? GITHUB_MAX_ANNOTATIONS : inputAnnotations;
+	return `${title} (${require_logging.pluralise(addedAnnotations, "annotation")} added)`;
+};
+/**
+* Enriches the summary with more context about the check run.
+*/
+const createEnrichedSummary = (summary, inputAnnotations) => [summary, ...inputAnnotations > GITHUB_MAX_ANNOTATIONS ? [`${inputAnnotations} annotations were provided, but only the first ${GITHUB_MAX_ANNOTATIONS} are visible in GitHub.`] : []].join("\n\n");
+/**
+* Asynchronously creates a GitHub check run with annotations.
+*
+* The first 50 `annotations` are written in full to GitHub.
+*
+* A `GITHUB_API_TOKEN` or `GITHUB_TOKEN` with the `checks:write` permission
+* must be present on the environment.
+*/
+const createCheckRun = async ({ annotations, conclusion, name, summary, text, title }) => {
+	const dir = process.cwd();
+	const [commitId, { owner, repo }] = await Promise.all([require_git.getHeadCommitId({ dir }), require_git.getOwnerAndRepo({ dir })]);
+	const client = await createRestClient({ auth: require_git.apiTokenFromEnvironment() });
+	await client.checks.create({
+		conclusion,
+		head_sha: commitId,
+		name,
+		output: {
+			annotations: annotations.slice(0, GITHUB_MAX_ANNOTATIONS),
+			summary: createEnrichedSummary(summary, annotations.length),
+			text,
+			title: suffixTitle(title, annotations.length)
+		},
+		owner,
+		repo
+	});
+};
+
+//#endregion
+//#region src/github/pullRequest.ts
+/**
+* Gets the number of the current pull request.
+*
+* This tries to extract the pull request from common CI environment variables,
+* and falls back to querying the GitHub Repos API for the latest pull request
+* associated with the head commit. An error is thrown if there are no
+* associated pull requests, or if they are all closed or locked.
+*/
+const getPullRequestNumber = async (params = {}) => {
+	const env = params.env ?? process.env;
+	const dir = process.cwd();
+	const number = Number(env.BUILDKITE_PULL_REQUEST ?? env.GITHUB_REF?.replace(/^refs\/pull\/(\d+).*$/, "$1"));
+	if (Number.isSafeInteger(number)) return number;
+	const client = params.client ?? await createRestClient({ auth: require_git.apiTokenFromEnvironment() });
+	const [commitId, { owner, repo }] = await Promise.all([require_git.getHeadCommitId({
+		dir,
+		env
+	}), require_git.getOwnerAndRepo({ dir })]);
+	const response = await client.repos.listPullRequestsAssociatedWithCommit({
+		commit_sha: commitId,
+		owner,
+		repo
+	});
+	const data = response.data.filter((pr) => pr.state === "open" && !pr.locked).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+	const pullRequestData = data[0];
+	if (!pullRequestData) throw new Error(`Commit ${commitId} is not associated with an open GitHub pull request`);
+	return pullRequestData.number;
+};
+
+//#endregion
+//#region src/github/issueComment.ts
+const getUserId = async (client) => {
+	const { data } = await client.users.getAuthenticated();
+	return data.id;
+};
+/**
+* Asynchronously creates or updates a GitHub issue comment.
+*
+* This emulates `put` behaviour by overwriting the first existing comment by
+* the same author on the issue, enabling use cases like a persistent bot
+* comment at the top of the pull request that reflects the current status of a
+* CI check.
+*
+* A `GITHUB_API_TOKEN` or `GITHUB_TOKEN` with write permissions must be present
+* on the environment.
+*/
+const putIssueComment = async (params) => {
+	if (params.body === null && !params.internalId) throw new Error("Cannot remove comment without an internalId");
+	const env = params.env ?? process.env;
+	const dir = process.cwd();
+	const { owner, repo } = await require_git.getOwnerAndRepo({ dir });
+	const client = await createRestClient({ auth: require_git.apiTokenFromEnvironment() });
+	const issueNumber = params.issueNumber ?? await getPullRequestNumber({
+		client,
+		env
+	});
+	if (!issueNumber) throw new Error("Failed to infer an issue number");
+	const comments = await client.issues.listComments({
+		issue_number: issueNumber,
+		owner,
+		repo
+	});
+	const userId = params.userId === "seek-build-agency" ? 87109344 : params.userId ?? await getUserId(client);
+	const commentId = comments.data.find((comment) => comment.user?.id === userId && (params.internalId ? comment.body?.endsWith(`\n\n<!-- ${params.internalId} -->`) : true))?.id;
+	if (params.body === null) {
+		if (commentId) await client.issues.deleteComment({
+			comment_id: commentId,
+			owner,
+			repo
+		});
+		return null;
+	}
+	const body = params.internalId ? [params.body.trim(), `<!-- ${params.internalId} -->`].join("\n\n") : params.body.trim();
+	const response = await (commentId ? client.issues.updateComment({
+		body,
+		comment_id: commentId,
+		issue_number: issueNumber,
+		owner,
+		repo
+	}) : client.issues.createComment({
+		body,
+		issue_number: issueNumber,
+		owner,
+		repo
+	}));
+	return { id: response.data.id };
+};
+
+//#endregion
+//#region src/github/push.ts
+/**
+* Retrieves all file changes from the local Git repository using
+* `getChangedFiles`, then uploads the changes to a specified GitHub branch
+* using `uploadFileChanges`.
+*
+* Returns the commit ID, or `undefined` if there are no changes to commit.
+*
+* The file changes will appear as verified commits on GitHub.
+*
+* This will not update the local Git repository unless `updateLocal` is
+* specified.
+*/
+const uploadAllFileChanges = async ({ branch, dir, messageHeadline, ignore, messageBody, updateLocal = false }) => {
+	const changedFiles = await require_git.getChangedFiles({
+		dir,
+		ignore
+	});
+	if (!changedFiles.length) return;
+	const fileChanges = await readFileChanges(dir, changedFiles);
+	const commitId = await uploadFileChanges({
+		dir,
+		branch,
+		messageHeadline,
+		messageBody,
+		fileChanges
+	});
+	if (updateLocal) {
+		await Promise.all([...fileChanges.additions, ...fileChanges.deletions].map((file) => fs_extra.default.rm(file.path)));
+		await require_git.fastForwardBranch({
+			ref: branch,
+			auth: { type: "gitHubApp" },
+			dir
+		});
+	}
+	return commitId;
+};
+/**
+* Takes a list of `ChangedFiles`, reads them from the file system, and maps
+* them to GitHub GraphQL `FileChanges`.
+*
+* https://docs.github.com/en/graphql/reference/input-objects#filechanges
+*/
+const readFileChanges = async (dir, changedFiles) => {
+	const { added, deleted } = changedFiles.reduce((files, changedFile) => {
+		const filePath = changedFile.path;
+		if (changedFile.state === "deleted") files.deleted.push(filePath);
+		else files.added.push(filePath);
+		return files;
+	}, {
+		added: [],
+		deleted: []
+	});
+	const gitRoot = await require_git.findRoot({ dir });
+	const toRootPath = (filePath) => {
+		if (!gitRoot) return filePath;
+		return path.default.resolve(gitRoot, filePath);
+	};
+	const additions = await Promise.all(added.map(async (filePath) => ({
+		path: filePath,
+		contents: await fs_extra.default.promises.readFile(toRootPath(filePath), { encoding: "base64" })
+	})));
+	const deletions = deleted.map((filePath) => ({ path: filePath }));
+	return {
+		additions,
+		deletions
+	};
+};
+/**
+* Uploads file changes from the local workspace to a specified GitHub branch.
+*
+* The file changes will appear as verified commits on GitHub.
+*
+* This will not update the local Git repository.
+*/
+const uploadFileChanges = async ({ dir, branch, messageHeadline, messageBody, fileChanges }) => {
+	const authToken = require_git.apiTokenFromEnvironment();
+	if (!authToken) throw new Error("Could not read a GitHub API token from the environment. Please set GITHUB_API_TOKEN or GITHUB_TOKEN.");
+	const [{ owner, repo }, headCommitId] = await Promise.all([require_git.getOwnerAndRepo({ dir }), require_git.getHeadCommitId({ dir })]);
+	const input = {
+		branch: {
+			repositoryNameWithOwner: `${owner}/${repo}`,
+			branchName: branch
+		},
+		message: {
+			headline: messageHeadline,
+			body: messageBody
+		},
+		expectedHeadOid: headCommitId,
+		clientMutationId: "skuba",
+		fileChanges
+	};
+	const result = await graphql(`
+      mutation Mutation($input: CreateCommitOnBranchInput!) {
+        createCommitOnBranch(input: $input) {
+          commit {
+            oid
+          }
+        }
+      }
+    `, {
+		input,
+		headers: { authorization: `Bearer ${authToken}` }
+	});
+	return result.createCommitOnBranch.commit.oid;
+};
+
+//#endregion
+//#region src/github/index.ts
+var github_exports = {};
+require_chunk.__export(github_exports, {
+	buildNameFromEnvironment: () => require_git.buildNameFromEnvironment,
+	createCheckRun: () => createCheckRun,
+	enabledFromEnvironment: () => require_git.enabledFromEnvironment,
+	getPullRequestNumber: () => getPullRequestNumber,
+	putIssueComment: () => putIssueComment,
+	readFileChanges: () => readFileChanges,
+	uploadAllFileChanges: () => uploadAllFileChanges,
+	uploadFileChanges: () => uploadFileChanges
+});
+
+//#endregion
+Object.defineProperty(exports, 'createCheckRun', {
+  enumerable: true,
+  get: function () {
+    return createCheckRun;
+  }
+});
+Object.defineProperty(exports, 'getPullRequestNumber', {
+  enumerable: true,
+  get: function () {
+    return getPullRequestNumber;
+  }
+});
+Object.defineProperty(exports, 'github_exports', {
+  enumerable: true,
+  get: function () {
+    return github_exports;
+  }
+});
+Object.defineProperty(exports, 'putIssueComment', {
+  enumerable: true,
+  get: function () {
+    return putIssueComment;
+  }
+});
+Object.defineProperty(exports, 'readFileChanges', {
+  enumerable: true,
+  get: function () {
+    return readFileChanges;
+  }
+});
+Object.defineProperty(exports, 'uploadAllFileChanges', {
+  enumerable: true,
+  get: function () {
+    return uploadAllFileChanges;
+  }
+});
+Object.defineProperty(exports, 'uploadFileChanges', {
+  enumerable: true,
+  get: function () {
+    return uploadFileChanges;
+  }
+});

package/lib/github-vycKoVtK.mjs

@@ -0,0 +1,269 @@
+import { __export } from "./chunk-CZCtuq8p.mjs";
+import { pluralise } from "./logging-Dr8kuQ_p.mjs";
+import { apiTokenFromEnvironment, buildNameFromEnvironment, enabledFromEnvironment, fastForwardBranch, findRoot, getChangedFiles, getHeadCommitId, getOwnerAndRepo } from "./git-DDfcZdbm.mjs";
+import path from "path";
+import fs from "fs-extra";
+
+//#region src/github/octokit.ts
+const createRestClient = async (options) => new (await (import("@octokit/rest"))).Octokit(options);
+const graphql = async (query, parameters) => (await import("@octokit/graphql")).graphql(query, parameters);
+
+//#endregion
+//#region src/github/checkRun.ts
+const GITHUB_MAX_ANNOTATIONS = 50;
+/**
+* Suffixes the title with the number of annotations added, e.g.
+*
+* ```text
+* Build #12 failed (24 annotations added)
+* ```
+*/
+const suffixTitle = (title, inputAnnotations) => {
+	const addedAnnotations = inputAnnotations > GITHUB_MAX_ANNOTATIONS ? GITHUB_MAX_ANNOTATIONS : inputAnnotations;
+	return `${title} (${pluralise(addedAnnotations, "annotation")} added)`;
+};
+/**
+* Enriches the summary with more context about the check run.
+*/
+const createEnrichedSummary = (summary, inputAnnotations) => [summary, ...inputAnnotations > GITHUB_MAX_ANNOTATIONS ? [`${inputAnnotations} annotations were provided, but only the first ${GITHUB_MAX_ANNOTATIONS} are visible in GitHub.`] : []].join("\n\n");
+/**
+* Asynchronously creates a GitHub check run with annotations.
+*
+* The first 50 `annotations` are written in full to GitHub.
+*
+* A `GITHUB_API_TOKEN` or `GITHUB_TOKEN` with the `checks:write` permission
+* must be present on the environment.
+*/
+const createCheckRun = async ({ annotations, conclusion, name, summary, text, title }) => {
+	const dir = process.cwd();
+	const [commitId, { owner, repo }] = await Promise.all([getHeadCommitId({ dir }), getOwnerAndRepo({ dir })]);
+	const client = await createRestClient({ auth: apiTokenFromEnvironment() });
+	await client.checks.create({
+		conclusion,
+		head_sha: commitId,
+		name,
+		output: {
+			annotations: annotations.slice(0, GITHUB_MAX_ANNOTATIONS),
+			summary: createEnrichedSummary(summary, annotations.length),
+			text,
+			title: suffixTitle(title, annotations.length)
+		},
+		owner,
+		repo
+	});
+};
+
+//#endregion
+//#region src/github/pullRequest.ts
+/**
+* Gets the number of the current pull request.
+*
+* This tries to extract the pull request from common CI environment variables,
+* and falls back to querying the GitHub Repos API for the latest pull request
+* associated with the head commit. An error is thrown if there are no
+* associated pull requests, or if they are all closed or locked.
+*/
+const getPullRequestNumber = async (params = {}) => {
+	const env = params.env ?? process.env;
+	const dir = process.cwd();
+	const number = Number(env.BUILDKITE_PULL_REQUEST ?? env.GITHUB_REF?.replace(/^refs\/pull\/(\d+).*$/, "$1"));
+	if (Number.isSafeInteger(number)) return number;
+	const client = params.client ?? await createRestClient({ auth: apiTokenFromEnvironment() });
+	const [commitId, { owner, repo }] = await Promise.all([getHeadCommitId({
+		dir,
+		env
+	}), getOwnerAndRepo({ dir })]);
+	const response = await client.repos.listPullRequestsAssociatedWithCommit({
+		commit_sha: commitId,
+		owner,
+		repo
+	});
+	const data = response.data.filter((pr) => pr.state === "open" && !pr.locked).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+	const pullRequestData = data[0];
+	if (!pullRequestData) throw new Error(`Commit ${commitId} is not associated with an open GitHub pull request`);
+	return pullRequestData.number;
+};
+
+//#endregion
+//#region src/github/issueComment.ts
+const getUserId = async (client) => {
+	const { data } = await client.users.getAuthenticated();
+	return data.id;
+};
+/**
+* Asynchronously creates or updates a GitHub issue comment.
+*
+* This emulates `put` behaviour by overwriting the first existing comment by
+* the same author on the issue, enabling use cases like a persistent bot
+* comment at the top of the pull request that reflects the current status of a
+* CI check.
+*
+* A `GITHUB_API_TOKEN` or `GITHUB_TOKEN` with write permissions must be present
+* on the environment.
+*/
+const putIssueComment = async (params) => {
+	if (params.body === null && !params.internalId) throw new Error("Cannot remove comment without an internalId");
+	const env = params.env ?? process.env;
+	const dir = process.cwd();
+	const { owner, repo } = await getOwnerAndRepo({ dir });
+	const client = await createRestClient({ auth: apiTokenFromEnvironment() });
+	const issueNumber = params.issueNumber ?? await getPullRequestNumber({
+		client,
+		env
+	});
+	if (!issueNumber) throw new Error("Failed to infer an issue number");
+	const comments = await client.issues.listComments({
+		issue_number: issueNumber,
+		owner,
+		repo
+	});
+	const userId = params.userId === "seek-build-agency" ? 87109344 : params.userId ?? await getUserId(client);
+	const commentId = comments.data.find((comment) => comment.user?.id === userId && (params.internalId ? comment.body?.endsWith(`\n\n<!-- ${params.internalId} -->`) : true))?.id;
+	if (params.body === null) {
+		if (commentId) await client.issues.deleteComment({
+			comment_id: commentId,
+			owner,
+			repo
+		});
+		return null;
+	}
+	const body = params.internalId ? [params.body.trim(), `<!-- ${params.internalId} -->`].join("\n\n") : params.body.trim();
+	const response = await (commentId ? client.issues.updateComment({
+		body,
+		comment_id: commentId,
+		issue_number: issueNumber,
+		owner,
+		repo
+	}) : client.issues.createComment({
+		body,
+		issue_number: issueNumber,
+		owner,
+		repo
+	}));
+	return { id: response.data.id };
+};
+
+//#endregion
+//#region src/github/push.ts
+/**
+* Retrieves all file changes from the local Git repository using
+* `getChangedFiles`, then uploads the changes to a specified GitHub branch
+* using `uploadFileChanges`.
+*
+* Returns the commit ID, or `undefined` if there are no changes to commit.
+*
+* The file changes will appear as verified commits on GitHub.
+*
+* This will not update the local Git repository unless `updateLocal` is
+* specified.
+*/
+const uploadAllFileChanges = async ({ branch, dir, messageHeadline, ignore, messageBody, updateLocal = false }) => {
+	const changedFiles = await getChangedFiles({
+		dir,
+		ignore
+	});
+	if (!changedFiles.length) return;
+	const fileChanges = await readFileChanges(dir, changedFiles);
+	const commitId = await uploadFileChanges({
+		dir,
+		branch,
+		messageHeadline,
+		messageBody,
+		fileChanges
+	});
+	if (updateLocal) {
+		await Promise.all([...fileChanges.additions, ...fileChanges.deletions].map((file) => fs.rm(file.path)));
+		await fastForwardBranch({
+			ref: branch,
+			auth: { type: "gitHubApp" },
+			dir
+		});
+	}
+	return commitId;
+};
+/**
+* Takes a list of `ChangedFiles`, reads them from the file system, and maps
+* them to GitHub GraphQL `FileChanges`.
+*
+* https://docs.github.com/en/graphql/reference/input-objects#filechanges
+*/
+const readFileChanges = async (dir, changedFiles) => {
+	const { added, deleted } = changedFiles.reduce((files, changedFile) => {
+		const filePath = changedFile.path;
+		if (changedFile.state === "deleted") files.deleted.push(filePath);
+		else files.added.push(filePath);
+		return files;
+	}, {
+		added: [],
+		deleted: []
+	});
+	const gitRoot = await findRoot({ dir });
+	const toRootPath = (filePath) => {
+		if (!gitRoot) return filePath;
+		return path.resolve(gitRoot, filePath);
+	};
+	const additions = await Promise.all(added.map(async (filePath) => ({
+		path: filePath,
+		contents: await fs.promises.readFile(toRootPath(filePath), { encoding: "base64" })
+	})));
+	const deletions = deleted.map((filePath) => ({ path: filePath }));
+	return {
+		additions,
+		deletions
+	};
+};
+/**
+* Uploads file changes from the local workspace to a specified GitHub branch.
+*
+* The file changes will appear as verified commits on GitHub.
+*
+* This will not update the local Git repository.
+*/
+const uploadFileChanges = async ({ dir, branch, messageHeadline, messageBody, fileChanges }) => {
+	const authToken = apiTokenFromEnvironment();
+	if (!authToken) throw new Error("Could not read a GitHub API token from the environment. Please set GITHUB_API_TOKEN or GITHUB_TOKEN.");
+	const [{ owner, repo }, headCommitId] = await Promise.all([getOwnerAndRepo({ dir }), getHeadCommitId({ dir })]);
+	const input = {
+		branch: {
+			repositoryNameWithOwner: `${owner}/${repo}`,
+			branchName: branch
+		},
+		message: {
+			headline: messageHeadline,
+			body: messageBody
+		},
+		expectedHeadOid: headCommitId,
+		clientMutationId: "skuba",
+		fileChanges
+	};
+	const result = await graphql(`
+      mutation Mutation($input: CreateCommitOnBranchInput!) {
+        createCommitOnBranch(input: $input) {
+          commit {
+            oid
+          }
+        }
+      }
+    `, {
+		input,
+		headers: { authorization: `Bearer ${authToken}` }
+	});
+	return result.createCommitOnBranch.commit.oid;
+};
+
+//#endregion
+//#region src/github/index.ts
+var github_exports = {};
+__export(github_exports, {
+	buildNameFromEnvironment: () => buildNameFromEnvironment,
+	createCheckRun: () => createCheckRun,
+	enabledFromEnvironment: () => enabledFromEnvironment,
+	getPullRequestNumber: () => getPullRequestNumber,
+	putIssueComment: () => putIssueComment,
+	readFileChanges: () => readFileChanges,
+	uploadAllFileChanges: () => uploadAllFileChanges,
+	uploadFileChanges: () => uploadFileChanges
+});
+
+//#endregion
+export { createCheckRun, getPullRequestNumber, github_exports, putIssueComment, readFileChanges, uploadAllFileChanges, uploadFileChanges };