IF Commons GitHub

host/branch

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-quality-evidence FR-021

The append-only quality branch and its notes, with real git (commons 0001-quality-evidence FR-021 to FR-023, FR-026): keepRun makes a run's record canonical (chained to the file before it), writes it as one new file quality/evidence/YYYY/MM/DD/<trace id>.otlp.json in a commit on the orphan branch quality (signed through the host's own Git signing where asked) and puts a note under refs/notes/quality on the tested commit; verifyBranch walks the branch and its chain and names the first thing that does not match; gradeOfCommit says what a commit's evidence is worth (a commit with no note is E0).

The branch is written with Git's plumbing (hash-object, a temporary index, write-tree, commit-tree, update-ref with the old tip as its guard), so the working tree and the index of the repository are never touched, and a branch that moved while a run was kept is refused rather than overwritten. A file already on the branch is never replaced (exists). Git signs: gpg.format, user.signingkey and commit.gpgsign are the host's, and no key is read here. A force-push cannot be refused by a client; refuseRewrite configures a repository that receives pushes to refuse non-fast-forward updates and deletions, and verifyBranch finds a branch that was rewritten (a commit that changes or removes a file, or a chain that no longer matches).

import { keepRun, verifyBranch } from "./branch.ts";
// const kept = await keepRun({ repo: ".", record: assembled.record });
// const ok = await verifyBranch(".");

Source: commons/quality/src/host/branch.ts

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

BranchCommittypeno test imports it
type BranchCommit = {
  readonly commit: string;
  readonly parents: readonly string[];
  readonly changes: readonly { readonly status: string; readonly path: string }[];
  /** Git's one-letter signature status (`G` good, `N` none, `U` good with unknown validity, `B`, `E`, ...). */
  readonly signature: string;
};

One commit of the branch: what it added and whether it is signed.

branchTipfunction
function branchTip(repo: string): Promise<Result<string | undefined, HostError>>

The tip of the branch, or none where the repository has no quality branch yet.

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

listCommitsfunction
function listCommits(repo: string, options?: { readonly allowedSigners?: string | undefined; }): Promise<Result<readonly BranchCommit[], HostError>>

The commits of the branch, oldest first, each with its changes and signature status.

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

blobAtfunctionno test imports it
function blobAt(repo: string, commit: string, path: string): Promise<Result<string, HostError>>

The text of a file at a commit of a repository, read with Git.

KeepOptionstypeno test imports it
type KeepOptions = { readonly repo: string; /** The run's document as 0008-test-evidence assembles it, or its text. … (732 characters)
type KeepOptions = {
  readonly repo: string;
  /** The run's document as 0008-test-evidence assembles it, or its text. */
  readonly record: unknown;
  /** What was planned and did not run (FR-013). */
  readonly notRun?: readonly NotRun[];
  /** The tested commit; the record's own revision, else `HEAD`, where it is not given. */
  readonly commit?: string;
  /** Whether to sign the commit that keeps it: true, false, or (not given) as the host's `commit.gpgsign` says. */
  readonly sign?: boolean;
  /** Facts every resource of the record carries besides the installation: the SHA-256 of the plan that governs the run (`ifc.quality.plan.sha256`, 0001-quality-evidence FR-042). */
  readonly resourceAttributes?: Attributes;
};

What keepRun is given.

Kepttypeno test imports it
type Kept = {
  readonly path: EvidencePath;
  readonly sha256: Sha256;
  readonly grade: Grade;
  /** The commit of the `quality` branch that holds the file. */
  readonly branchCommit: string;
  /** The commit that was tested, and so carries the note; none where the repository has no commit to name. */
  readonly tested?: string;
  readonly signed: boolean;
  readonly record: QualityRecord;
};

A run that was kept.

KeepErrortypeno test imports it
type KeepError = HostError | { readonly kind: "record"; readonly reason: string };

Why a run could not be kept.

formatKeepErrorfunctionno test imports it
function formatKeepError(e: KeepError): string

A keep error as one sentence.

signedCommitfunctionno test imports it
function signedCommit(repo: string, commit: string): Promise<Result<boolean, HostError>>

Whether a commit carries a signature that Git verifies.

writeCommitfunction
function writeCommit(repo: string, tip: string | undefined, path: string, body: string, message: string, sign: boolean | undefined): Promise<Result<string, HostError>>

Writes a commit on the evidence branch with Git's plumbing, guarded by the tip it was made on.

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

signingFollowsConfigfunctionno test imports it
function signingFollowsConfig(repo: string): Promise<boolean>

Whether the repository's Git configuration asks for commits to be signed.

keepRunfunction
function keepRun(options: KeepOptions): Promise<Result<Kept, KeepError>>

Keeps a run (FR-021 to FR-023): the record is made canonical with the digest of the last file of the branch as its predecessor, written as a new file in a commit on the orphan quality branch (created by this commit where there is none), and noted on the tested commit with the file's path, its SHA-256 and its grade. A path already kept is refused, and so is a trace already kept; a branch that moved is refused and nothing is changed. The grade is E4 where the commit is signed and E3 where it is not.

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

BranchProblemtypeno test imports it
type BranchProblem = | { readonly kind: "no-branch" } | { readonly kind: "not-append"; readonly commit: string; read… (475 characters)
type BranchProblem =
  | { readonly kind: "no-branch" }
  | { readonly kind: "not-append"; readonly commit: string; readonly reason: string }
  | { readonly kind: "chain"; readonly break: ChainBreak }
  | { readonly kind: "unsigned-commit"; readonly commit: string; readonly path: string; readonly status: string }
  | { readonly kind: "ledger"; readonly path: string; readonly reason: string }
  | { readonly kind: "note"; readonly commit: string; readonly reason: string };

The first thing wrong with the branch (FR-021 to FR-023): what, and where.

VerifyErrortypeno test imports it
type VerifyError = HostError | BranchProblem;

What can go wrong verifying: the host, or the branch.

formatVerifyErrorfunction
function formatVerifyError(e: VerifyError): string

A verification failure as one sentence.

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

VerifiedFiletypeno test imports it
type VerifiedFile = { readonly path: string; readonly commit: string; readonly traceId: string; readonly signed: boolean };

One evidence file as the verifier found it.

CommitGradetypeno test imports it
type CommitGrade = { readonly commit: string; readonly grade: Grade; readonly path: string };

A tested commit and what its evidence is worth.

Verifiedtypeno test imports it
type Verified = {
  readonly count: number;
  readonly head: Sha256;
  readonly files: readonly VerifiedFile[];
  readonly grades: readonly CommitGrade[];
  /** The files of the ledger of nonconformances and CAPA (FR-046), which verify as a chain of their own. */
  readonly records: number;
};

A branch that verifies.

VerifyOptionstypeno test imports it
type VerifyOptions = {
  /** An SSH allowed-signers file the harness trusts; where given, a commit is signed only when Git verifies it against it. */
  readonly allowedSigners?: string;
  /** Fail on a commit that is not signed (and trusted, where `allowedSigners` is given). */
  readonly requireSigned?: boolean;
};

How to verify.

verifyBranchfunction
function verifyBranch(repo: string, options?: VerifyOptions): Promise<Result<Verified, VerifyError>>

Walks the quality branch (FR-021 to FR-023): every commit only appends one evidence file, the chain of ifc.quality.previous.sha256 holds from the first file to the last, and, where asked, every commit is signed. Then each note under refs/notes/quality is read and must name a file on the branch with the SHA-256 it says. The first thing that does not match is returned, naming the file or the commit.

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

gradeOfCommitfunction
function gradeOfCommit(repo: string, commit: string, options?: VerifyOptions): Promise<Result<Grade, HostError>>

What the evidence of a commit is worth (FR-023, FR-026): E0 where the commit has no note, where its note does not match its file or the branch does not verify; else the grade of its newest run, E4 where that run is signed and chained and E3 where it is not.

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

readKeptRunfunction
function readKeptRun(repo: string, traceId: string): Promise<Result<string, HostError>>

The evidence file text of a run kept on the branch, by its trace id.

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

extendsTipfunction
function extendsTip(repo: string, earlier: string): Promise<Result<boolean, HostError>>

Whether the branch is still an extension of an earlier tip (FR-021): a rewrite of the branch is not. A CI job that remembers the tip it saw last (or a hook on the repository that receives pushes) refuses the update where this is false.

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

refuseRewritefunction
function refuseRewrite(repo: string): Promise<Result<void, HostError>>

Configures a repository that receives pushes (a bare one) to refuse a force-push and the deletion of any branch (FR-021): receive.denyNonFastForwards and receive.denyDeletes. A host that is not Git itself (a forge) has its own protected-branch setting.

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

pushQualityfunction
function pushQuality(repo: string, remote: string): Promise<Result<void, HostError>>

Pushes the branch and its notes, never forced: a remote that has moved on, or been rewritten, refuses it.

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

writeOncefunction
function writeOnce(path: string, body: string): Promise<Result<void, HostError>>

Writes a file for tests and tools that keep an evidence file outside Git (a copy for an assessor): refuses to overwrite one (FR-021).

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

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