IF Commons GitHub

types

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-githost FR-001

The one interface to a Git host (commons 0001-githost FR-002 to FR-006): GitHub, GitLab and plain Git are read through it, so that a check of change control and a workspace never name a host's own word. The types here are pure; the adapters (github.ts, gitlab.ts, git.ts) are the only code that does.

A host answers only what it has: a capability it lacks is unsupported, never a guess (0001-githost FR-003). A private repository is asked with a credential from the environment or a credential helper, never from a file; a refusal for want of one is unauthorized, which is a finding for a person to act on, not a retry.

Source: commons/githost/src/types.ts

2 of 12 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

BranchProtectiontypeno test imports it
type BranchProtection = { readonly branch: string; readonly protected: boolean; readonly requiresReview: boolean; … (514 characters)
type BranchProtection = {
  readonly branch: string;
  readonly protected: boolean;
  readonly requiresReview: boolean;
  readonly allowsForcePush: boolean;
  /**
   * `protected-only` where the host says the branch is protected and the credential may not read the rules (GitHub shows them to administrators only), so that `requiresReview` and
   * `allowsForcePush` are `false` for want of an answer, not by the host's word. Absent means `full`.
   */
  readonly detail?: "full" | "protected-only" | undefined;
};

Whether a branch of a repository is protected (no push, no force, review required).

Capabilitytypeno test imports it
type Capability =
  "CloneUrl" | "Credentials" | "DefaultBranch" | "SignedCommits" | "ProtectedBranches" | "Issues" | "ChangeRequests" | "NestedGroups";

The capabilities a host may offer: the keys of the code list ifccm:GitCapability.

ChangeRequestInfotypeno test imports it
type ChangeRequestInfo = {
  readonly number: number;
  readonly title: string;
  readonly state: "open" | "closed" | "merged";
  readonly url: string;
  readonly sourceBranch: string;
  readonly targetBranch: string;
};

What a host says of a pull request or a merge request.

describeFailurefunctionno test imports it
function describeFailure(f: HostFailure): string

The words of a failure, as a sentence for a finding.

GitHostClienttypeno test imports it
type GitHostClient = { readonly kind: HostKind; readonly capabilities: ReadonlySet<Capability>; repository(ref: Re… (572 characters)
type GitHostClient = {
  readonly kind: HostKind;
  readonly capabilities: ReadonlySet<Capability>;
  repository(ref: RepoRef): Promise<HostResult<RepoInfo>>;
  issue(ref: RepoRef, number: number): Promise<HostResult<IssueInfo>>;
  changeRequest(ref: RepoRef, number: number): Promise<HostResult<ChangeRequestInfo>>;
  branchProtection(ref: RepoRef, branch: string): Promise<HostResult<BranchProtection>>;
  /** Whether the commit's signature is verified by the host, where the host can say. */
  commitVerified(ref: RepoRef, sha: string): Promise<HostResult<boolean>>;
};

The one interface to a host. Every method that a host may lack returns unsupported for it, and capabilities says which.

HostFailuretypeno test imports it
type HostFailure = | { readonly kind: "unsupported"; readonly capability: Capability; readonly host: HostKind } | { … (470 characters)
type HostFailure =
  | { readonly kind: "unsupported"; readonly capability: Capability; readonly host: HostKind }
  | { readonly kind: "unauthorized"; readonly reason: string }
  | { readonly kind: "not-found"; readonly what: string }
  | { readonly kind: "rate-limited"; readonly retryAfterSeconds?: number | undefined }
  | { readonly kind: "unreachable"; readonly reason: string }
  | { readonly kind: "unexpected"; readonly status: number; readonly reason: string };

Why a host did not answer.

HostKindtype
type HostKind = "Github" | "Gitlab" | "Git";

The kinds of host: the keys of the code list ifccm:GitManagerKind, the one list of Git host kinds (ifccm:hostedOn ranges over it).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

HostResulttypeno test imports it
type HostResult<T> = Result<T, HostFailure>;

An answer of a host.

IssueInfotypeno test imports it
type IssueInfo = { /** The number the host gives it, in the repository (`#N` on GitHub, `#N` of a project on GitLab). … (850 characters)
type IssueInfo = {
  /** The number the host gives it, in the repository (`#N` on GitHub, `#N` of a project on GitLab). */
  readonly number: number;
  readonly title: string;
  readonly body: string;
  readonly state: "open" | "closed";
  readonly url: string;
  /** The issue this one is a child of, where the host has parent and child issues. */
  readonly parent?: number | undefined;
  /** The issues that are children of this one, where the host has them. */
  readonly children: readonly number[];
  readonly labels: readonly string[];
  /**
   * Whether `parent` and `children` are the host's answer (`known`) or the host's API offers no parent and child issues, so that they are empty for want of an answer
   * (`unavailable`: GitLab's REST API v4). Absent means `known`.
   */
  readonly hierarchy?: "known" | "unavailable" | undefined;
};

What a host says of an issue: the words and sections the change-control check reads.

RepoInfotypeno test imports it
type RepoInfo = {
  readonly ref: RepoRef;
  readonly visibility: Visibility;
  readonly defaultBranch: string;
  /** The URL a clone is made from (HTTPS), without a credential in it. */
  readonly cloneUrl: string;
  readonly archived: boolean;
};

What a host says of a repository.

RepoReftype
type RepoRef = {
  readonly kind: HostKind;
  /** The host name, such as `github.com`, `gitlab.com` or the name of a self-managed host. */
  readonly host: string;
  /** The path segments, the last being the repository. */
  readonly path: readonly string[];
};

A repository on a host: the host name, and the path from it (owner then repository on GitHub; groups to any depth then repository on GitLab). Never contains a scheme or .git.

Imported by 17 tests of the run (17 passed, 0 failed): the library's results

Visibilitytypeno test imports it
type Visibility = "public" | "private" | "internal" | "unknown";

Whether a repository may be seen by anyone: unknown where the host was not asked or does not say.

Titles, headings, exports, tables, columns and requirements. Esc closes.