IF Commons GitHub

physical/sources/githost

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0004-planning-sources FR-010

The source for a Git host (0037-planning FR-028): the issues of a repository and the references of its commits, read through a client of the Git host contract of githost and never one of its own. The contract reads one issue by its number, so the issues read are the ones the configuration names and the ones the commits name: the line Refs #N that repoctl commit writes (a convention of this repository, which Git does not read as a trailer) and the closing keywords of the host (close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, then #N or OWNER/REPOSITORY#N). The source is read only: it declares only read, so every patch for it waits in the outbox, and what the contract does not hold (the close reason, the assignees, the comments, the events) is unexpressed with that reason.

The commits that name an issue are carried in the issue's observation (its record as read and its evidence), and not as an observation of their own: reconcile matches one observation to an item in a run, so a second observation of the same issue in the same source would be a new item. A closed issue is read as closed as completed, which is the host's default and the one reason the contract can neither confirm nor deny.

import { commitReferences } from "./githost.ts";
commitReferences("Fix the thing\n\nRefs #12\nCloses #13", ["owner", "repo"]); // [{ number: 12, how: "refs" }, { number: 13, how: "closes" }]

Source: commons/planning/src/physical/sources/githost.ts

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

physical.CommitReferencetypeno test imports it
type CommitReference = { readonly number: number; readonly how: "refs" | "closes" };

How a commit names an issue.

physical.commitReferencesfunctionno test imports it
function commitReferences(message: string, path: readonly string[]): readonly CommitReference[]

The issues a commit message names: its Refs #N lines and its closing keywords, in order of appearance, each issue once; an OWNER/REPOSITORY#N of another repository than path is not this one's.

physical.GithostConfigtypeno test imports it
type GithostConfig = { readonly client: GitHostClient; readonly ref: RepoRef; /** The numbers of issues to read be… (401 characters)
type GithostConfig = {
  readonly client: GitHostClient;
  readonly ref: RepoRef;
  /** The numbers of issues to read besides those the commits name. */
  readonly issues?: readonly number[];
  /** A local clone whose commits are read for references; none where it is left out. */
  readonly repo?: string;
  /** How many commits to read (500 where none is said). */
  readonly maxCommits?: number;
};

What a configuration of the Git host source says.

physical.githostSourcefunctionno test imports it
function githostSource(config: GithostConfig): Result<Source, DefineProblem>

The source for the issues and commit references of a repository on a Git host; read only.

CommitReferencetypeno test imports it
type CommitReference = { readonly number: number; readonly how: "refs" | "closes" };

How a commit names an issue.

commitReferencesfunctionno test imports it
function commitReferences(message: string, path: readonly string[]): readonly CommitReference[]

The issues a commit message names: its Refs #N lines and its closing keywords, in order of appearance, each issue once; an OWNER/REPOSITORY#N of another repository than path is not this one's.

GithostConfigtypeno test imports it
type GithostConfig = { readonly client: GitHostClient; readonly ref: RepoRef; /** The numbers of issues to read be… (401 characters)
type GithostConfig = {
  readonly client: GitHostClient;
  readonly ref: RepoRef;
  /** The numbers of issues to read besides those the commits name. */
  readonly issues?: readonly number[];
  /** A local clone whose commits are read for references; none where it is left out. */
  readonly repo?: string;
  /** How many commits to read (500 where none is said). */
  readonly maxCommits?: number;
};

What a configuration of the Git host source says.

githostSourcefunctionno test imports it
function githostSource(config: GithostConfig): Result<Source, DefineProblem>

The source for the issues and commit references of a repository on a Git host; read only.

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