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

package/lib/index-1eEu26nG.d.ts

@@ -0,0 +1,255 @@
+import { ChangedFile } from "./index-B91wXiwr.js";
+import { Endpoints } from "@octokit/types";
+import { Octokit } from "@octokit/rest";
+
+//#region src/github/checkRun.d.ts
+type Output = NonNullable<Endpoints['PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}']['parameters']['output']>;
+type Annotation = NonNullable<Output['annotations']>[number];
+/**
+ * {@link https://docs.github.com/en/rest/reference/checks#create-a-check-run}
+ */
+interface CreateCheckRunParameters {
+  /**
+   * Adds information from your analysis to specific lines of code.
+   * Annotations are visible on GitHub in the **Checks** and **Files changed**
+   * tab of the pull request.
+   */
+  annotations: Annotation[];
+  /**
+   * The final conclusion of the check.
+   */
+  conclusion: 'failure' | 'success';
+  /**
+   * The name of the check. For example, "code-coverage".
+   */
+  name: string;
+  /**
+   * The summary of the check run. This parameter supports Markdown.
+   */
+  summary: string;
+  /**
+   * The details of the check run. This parameter supports Markdown.
+   */
+  text?: string;
+  /**
+   * The title of the check run.
+   */
+  title: string;
+}
+/**
+ * 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.
+ */
+declare const createCheckRun: ({
+  annotations,
+  conclusion,
+  name,
+  summary,
+  text,
+  title
+}: CreateCheckRunParameters) => Promise<void>;
+//#endregion
+//#region src/github/environment.d.ts
+/**
+ * Returns the name of the build as seen in GitHub status checks.
+ *
+ * This is driven off of environment variables and falls back to `Build`.
+ */
+declare const buildNameFromEnvironment: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * Whether GitHub API interactions should be enabled.
+ *
+ * This checks environment variables to see if the code is executing in a CI
+ * environment and has access to a GitHub API token.
+ */
+declare const enabledFromEnvironment: (env?: NodeJS.ProcessEnv) => boolean;
+//#endregion
+//#region src/github/pullRequest.d.ts
+interface GetPullRequestParameters {
+  /**
+   * A preconstructed Octokit client to interact with GitHub's APIs.
+   *
+   * A `GITHUB_API_TOKEN` or `GITHUB_TOKEN` with write permissions must be
+   * present on the environment if this is not provided.
+   */
+  client?: Octokit;
+  env?: Record<string, string | undefined>;
+}
+/**
+ * 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.
+ */
+declare const getPullRequestNumber: (params?: GetPullRequestParameters) => Promise<number>;
+//#endregion
+//#region src/github/issueComment.d.ts
+/**
+ * https://docs.github.com/en/rest/reference/issues#create-an-issue-comment
+ */
+interface PutIssueCommentParameters {
+  /**
+   * The body of the issue comment.
+   *
+   * An explicit `null` value will remove the comment, if `internalId` is provided.
+   */
+  body: string | null;
+  /**
+   * An internal identifier for the issue comment.
+   *
+   * This can be used to scope a given `put` to a particular comment, preventing
+   * it from clobbering other comments from the same bot or user.
+   *
+   * The identifier is embedded as hidden content in the comment body.
+   */
+  internalId?: string;
+  env?: Record<string, string | undefined>;
+  /**
+   * The number that identifies the GitHub issue.
+   *
+   * If this is not provided, the number will be inferred from the GitHub Repos
+   * API by finding the latest pull request associated with the head commit.
+   *
+   * https://docs.github.com/en/rest/reference/repos#list-pull-requests-associated-with-a-commit
+   */
+  issueNumber?: number;
+  /**
+   * The ID of authenticated bot or user that is putting the issue comment.
+   *
+   * This drives our `put` behaviour, which tries to locate and edit an existing
+   * comment before creating a new one. If this is not provided, the ID will be
+   * inferred from the GitHub Users API.
+   *
+   * https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
+   *
+   * If you're at SEEK and using BuildAgency's GitHub API integration, you may
+   * use `'seek-build-agency'` as an optimisation to skip the user lookup.
+   *
+   * https://api.github.com/users/buildagencygitapitoken[bot]
+   */
+  userId?: number | 'seek-build-agency';
+}
+interface IssueComment {
+  id: number;
+}
+/**
+ * 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.
+ */
+declare const putIssueComment: (params: PutIssueCommentParameters) => Promise<IssueComment | null>;
+//#endregion
+//#region src/github/push.d.ts
+interface UploadAllFileChangesParams {
+  dir: string;
+  /**
+   * The branch name
+   */
+  branch: string;
+  /**
+   * The headline of the commit message
+   */
+  messageHeadline: string;
+  /**
+   * File changes to exclude from the upload.
+   *
+   * Defaults to `[]` (no exclusions).
+   */
+  ignore?: ChangedFile[];
+  /**
+   * The body of the commit message
+   */
+  messageBody?: string;
+  /**
+   * Updates the local Git repository to match the new remote branch state
+   */
+  updateLocal?: boolean;
+}
+/**
+ * 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.
+ */
+declare const uploadAllFileChanges: ({
+  branch,
+  dir,
+  messageHeadline,
+  ignore,
+  messageBody,
+  updateLocal
+}: UploadAllFileChangesParams) => Promise<string | undefined>;
+interface FileAddition {
+  contents: unknown;
+  path: string;
+}
+interface FileDeletion {
+  path: string;
+}
+interface FileChanges {
+  additions: FileAddition[];
+  deletions: FileDeletion[];
+}
+/**
+ * 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
+ */
+declare const readFileChanges: (dir: string, changedFiles: ChangedFile[]) => Promise<FileChanges>;
+interface UploadFileChangesParams {
+  dir: string;
+  /**
+   * The branch name
+   */
+  branch: string;
+  /**
+   * The headline of the commit message
+   */
+  messageHeadline: string;
+  /**
+   * The body of the commit message
+   */
+  messageBody?: string;
+  /**
+   * File additions and deletions
+   */
+  fileChanges: FileChanges;
+}
+/**
+ * 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.
+ */
+declare const uploadFileChanges: ({
+  dir,
+  branch,
+  messageHeadline,
+  messageBody,
+  fileChanges
+}: UploadFileChangesParams) => Promise<string>;
+declare namespace index_d_exports {
+  export { Annotation, buildNameFromEnvironment, createCheckRun, enabledFromEnvironment, getPullRequestNumber, putIssueComment, readFileChanges, uploadAllFileChanges, uploadFileChanges };
+}
+//#endregion
+export { type Annotation, buildNameFromEnvironment, createCheckRun, enabledFromEnvironment, getPullRequestNumber, index_d_exports, putIssueComment, readFileChanges, uploadAllFileChanges, uploadFileChanges };

package/lib/index-9i8gHTGu.d.mts

@@ -0,0 +1,38 @@
+//#region src/net/socket.d.ts
+interface SocketAddress {
+  host: string;
+  port: number;
+}
+//#endregion
+//#region src/net/waitFor.d.ts
+/**
+ * Wait for a resource to start listening on a socket address.
+ *
+ * The socket is polled on an interval until it accepts a connection or the
+ * `timeout` is reached.
+ */
+declare const waitFor: ({
+  host,
+  port,
+  resolveCompose,
+  timeout
+}: {
+  host?: string;
+  port: number;
+  /**
+   * Whether to treat the `host` and `port` arguments as a private Docker
+   * Compose network address and to resolve them to a public local address.
+   *
+   * This is typically:
+   *
+   * - Enabled locally, when the application is running directly on the machine
+   * - Disabled in CI, when running in a container on the Docker Compose network
+   */
+  resolveCompose?: boolean;
+  timeout?: number;
+}) => Promise<SocketAddress>;
+declare namespace index_d_exports {
+  export { waitFor };
+}
+//#endregion
+export { index_d_exports as index_d_exports$1, waitFor as waitFor$1 };

package/lib/index-B91wXiwr.d.ts

@@ -0,0 +1,278 @@
+//#region src/git/commit.d.ts
+interface Identity {
+  email?: string;
+  name?: string;
+}
+interface CommitParameters {
+  author?: Identity;
+  committer?: Identity;
+  dir: string;
+  message: string;
+}
+/**
+ * Writes a commit to the local Git repository.
+ */
+declare const commit: ({
+  author,
+  committer,
+  dir,
+  message
+}: CommitParameters) => Promise<string>;
+//#endregion
+//#region src/git/getChangedFiles.d.ts
+type ChangedFileState = 'added' | 'modified' | 'deleted';
+interface ChangedFile {
+  path: string;
+  state: ChangedFileState;
+}
+interface ChangedFilesParameters {
+  dir: string;
+  /**
+   * File changes to exclude from the result.
+   *
+   * Defaults to `[]` (no exclusions).
+   */
+  ignore?: ChangedFile[];
+}
+/**
+ * Returns all the files which have been added, modified or deleted in the
+ * working directory of the local Git repository since the last commit.
+ */
+declare const getChangedFiles: ({
+  dir,
+  ignore
+}: ChangedFilesParameters) => Promise<ChangedFile[]>;
+//#endregion
+//#region src/git/commitAllChanges.d.ts
+interface CommitAllParameters {
+  dir: string;
+  message: string;
+  author?: Identity;
+  committer?: Identity;
+  /**
+   * File changes to exclude from the commit.
+   *
+   * Defaults to `[]` (no exclusions).
+   */
+  ignore?: ChangedFile[];
+}
+/**
+ * Stages all changes and writes a commit to the local Git repository.
+ */
+declare const commitAllChanges: ({
+  dir,
+  message,
+  author,
+  committer,
+  ignore
+}: CommitAllParameters) => Promise<string | undefined>;
+//#endregion
+//#region src/git/currentBranch.d.ts
+interface CurrentBranchParameters {
+  dir?: string;
+  env?: Record<string, string | undefined>;
+}
+/**
+ * Tries to return a Git branch name from CI environment variables, falling back
+ * to the local Git repository when the current working `dir` is supplied.
+ */
+declare const currentBranch: ({
+  dir,
+  env
+}?: CurrentBranchParameters) => Promise<string | undefined>;
+//#endregion
+//#region src/git/findRoot.d.ts
+interface FindRootParameters {
+  dir: string;
+}
+/**
+ * Returns the first Git root directory encountered walking up from the provided
+ * `dir`.
+ */
+declare const findRoot: ({
+  dir
+}: FindRootParameters) => Promise<string | null>;
+//#endregion
+//#region src/git/log.d.ts
+interface GetHeadCommitParameters {
+  dir: string;
+  env?: Record<string, string | undefined>;
+}
+/**
+ * Gets the object ID of the head commit.
+ *
+ * This tries to extract the commit ID from common CI environment variables,
+ * and falls back to the local Git repository log.
+ */
+declare const getHeadCommitId: ({
+  dir,
+  env
+}: GetHeadCommitParameters) => Promise<string>;
+/**
+ * Gets the message of the head commit.
+ *
+ * This tries to extract the message from common CI environment variables,
+ * and falls back to the local Git repository log.
+ */
+declare const getHeadCommitMessage: ({
+  dir,
+  env
+}: GetHeadCommitParameters) => Promise<string>;
+//#endregion
+//#region src/git/remote.d.ts
+interface GetOwnerAndRepoParameters {
+  dir: string;
+  env?: Record<string, string | undefined>;
+}
+/**
+ * Extracts the owner and repository names from CI environment variables,
+ * falling back to local Git remotes.
+ *
+ * Currently, only GitHub repository URLs are supported:
+ *
+ * ```console
+ * git@github.com:seek-oss/skuba.git
+ * https://github.com/seek-oss/skuba.git
+ * ```
+ */
+declare const getOwnerAndRepo: ({
+  dir,
+  env
+}: GetOwnerAndRepoParameters) => Promise<{
+  owner: string;
+  repo: string;
+}>;
+//#endregion
+//#region src/git/push.d.ts
+/**
+ * Use a GitHub app token to auth the Git push.
+ *
+ * This defaults to the `GITHUB_API_TOKEN` and `GITHUB_TOKEN` environment
+ * variables if `token` is not provided.
+ */
+interface GitHubAppAuth$1 {
+  type: 'gitHubApp';
+  token?: string;
+}
+interface PushParameters {
+  /**
+   * The auth mechanism for the push.
+   *
+   * Currently, only GitHub app tokens are supported.
+   */
+  auth: GitHubAppAuth$1;
+  dir: string;
+  /**
+   * The reference to push to the remote.
+   *
+   * This may be a commit, branch or tag in the local repository.
+   */
+  ref: string;
+  remote?: string;
+  /**
+   * The destination branch or tag on the remote.
+   *
+   * This defaults to `ref`.
+   */
+  remoteRef?: string;
+  /**
+   * Forcefully override any conflicts.
+   *
+   * This defaults to `false`.
+   */
+  force?: boolean;
+}
+interface PushResult {
+  ok: boolean;
+  error: string | null;
+  refs: Record<string, {
+    ok: boolean;
+    error: string;
+  }>;
+  headers?: Record<string, string> | undefined;
+}
+/**
+ * Pushes the specified `ref` from the local Git repository to a remote.
+ */
+declare const push: ({
+  auth,
+  dir,
+  ref,
+  remote,
+  remoteRef,
+  force
+}: PushParameters) => Promise<PushResult>;
+//#endregion
+//#region src/git/pull.d.ts
+/**
+ * Use a GitHub app token to auth the Git push.
+ *
+ * This defaults to the `GITHUB_API_TOKEN` and `GITHUB_TOKEN` environment
+ * variables if `token` is not provided.
+ */
+interface GitHubAppAuth {
+  type: 'gitHubApp';
+  token?: string;
+}
+interface PullParameters {
+  /**
+   * The auth mechanism for the push.
+   *
+   * Currently, only GitHub app tokens are supported.
+   */
+  auth: GitHubAppAuth;
+  dir: string;
+  /**
+   * The local branch to fast forward.
+   */
+  ref: string;
+  remote?: string;
+  /**
+   * The branch or tag on the remote to reference.
+   *
+   * This defaults to `ref`.
+   */
+  remoteRef?: string;
+}
+/**
+ * Fast forwards the specified `ref` on the local Git repository to match the remote branch.
+ */
+declare const fastForwardBranch: ({
+  auth,
+  dir,
+  ref,
+  remote,
+  remoteRef
+}: PullParameters) => Promise<void>;
+//#endregion
+//#region src/git/reset.d.ts
+interface ResetParameters {
+  dir: string;
+  branch: string;
+  commitId: string;
+  hard?: boolean;
+}
+/**
+ * Resets the specified branch in the local Git repository to a particular
+ * commit.
+ */
+declare const reset: ({
+  dir,
+  branch,
+  commitId,
+  hard
+}: ResetParameters) => Promise<void>;
+//#endregion
+//#region src/git/isFileGitIgnored.d.ts
+declare const isFileGitIgnored: ({
+  absolutePath,
+  gitRoot
+}: {
+  absolutePath: string;
+  gitRoot: string;
+}) => Promise<boolean>;
+declare namespace index_d_exports {
+  export { ChangedFile, commit, commitAllChanges, currentBranch, fastForwardBranch, findRoot, getChangedFiles, getHeadCommitId, getHeadCommitMessage, getOwnerAndRepo, isFileGitIgnored, push, reset };
+}
+//#endregion
+export { type ChangedFile, commit, commitAllChanges, currentBranch, fastForwardBranch, findRoot, getChangedFiles, getHeadCommitId, getHeadCommitMessage, getOwnerAndRepo, index_d_exports as index_d_exports$1, isFileGitIgnored, push, reset };

package/lib/index-CfnlMf_4.d.ts

@@ -0,0 +1,39 @@
+//#region src/buildkite/annotate.d.ts
+type AnnotationStyle = 'success' | 'info' | 'warning' | 'error';
+interface AnnotationOptions {
+  context?: string;
+  /**
+   * Scopes an annotation's context to the Buildkite step ID.
+   *
+   * This lets you emit distinct annotations per step, and only takes effect if
+   * the `BUILDKITE_STEP_ID` environment variable is present.
+   */
+  scopeContextToStep?: boolean;
+  style?: AnnotationStyle;
+}
+/**
+ * Asynchronously uploads a Buildkite annotation.
+ *
+ * If the following environment variables are not present,
+ * the function will silently return without attempting to annotate:
+ *
+ * - `BUILDKITE`
+ * - `BUILDKITE_AGENT_ACCESS_TOKEN`
+ * - `BUILDKITE_JOB_ID`
+ *
+ * The `buildkite-agent` binary must also be on your `PATH`.
+ */
+declare const annotate: (markdown: string, opts?: AnnotationOptions) => Promise<void>;
+//#endregion
+//#region src/buildkite/md.d.ts
+/**
+ * @internal
+ */
+declare const md: {
+  terminal: (code: string) => string;
+};
+declare namespace index_d_exports {
+  export { AnnotationStyle, annotate, md };
+}
+//#endregion
+export { type AnnotationStyle, annotate, index_d_exports as index_d_exports$2, md };