IF Commons GitHub

host/ledger-branch

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

The ledger of nonconformances and CAPA on the quality branch (commons 0001-quality-evidence FR-031 to FR-036, FR-046), with real git: each event is one new file quality/records/NNNNNN-<kind>.json in a commit that only appends, chained to the file before it by its digest, signed where Git is set to sign; reading folds the files into the state of every nonconformance and CAPA, refusing a chain that does not verify.

Same plumbing as the evidence files (branch.ts): a temporary index, write-tree, commit-tree and update-ref guarded by the tip it read, so a branch that moved is refused and the working tree and the index of the repository are never touched.

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

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

LedgerHostErrortypeno test imports it
type LedgerHostError = HostError | { readonly kind: "ledger"; readonly reason: string };

Why the ledger could not be read or extended.

formatLedgerHostErrorfunctionno test imports it
function formatLedgerHostError(e: LedgerHostError): string

A ledger error as one sentence.

LedgerReadtypeno test imports it
type LedgerRead = {
  readonly ledger: Ledger;
  /** The events in the order they were kept. */
  readonly events: readonly LedgerEvent[];
  readonly files: number;
  readonly head: Sha256;
  readonly tip: string | undefined;
};

The ledger as it stands on the branch: the state, the number of files and the digest of the last (the next file's predecessor).

filesAtfunctionno test imports it
function filesAt(repo: string, tip: string): Promise<Result<readonly { readonly path: string; readonly text: string; }[], HostError>>

The files of the ledger on a commit, in sequence.

readLedgerfunction
function readLedger(repo: string): Promise<Result<LedgerRead, LedgerHostError>>

Reads the ledger from the tip of the quality branch: its chain must verify and its events must follow one another (FR-032 to FR-035). A repository with no branch has the empty ledger.

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

AppendOptionstypeno test imports it
type AppendOptions = {
  /** Whether to sign the commits: true, false, or (not given) as the host's `commit.gpgsign` says. */
  readonly sign?: boolean;
};

What appendEvents is given.

appendEventsfunction
function appendEvents(repo: string, asked: readonly (import("/home/runner/work/.github/.github/commons/core/src/decode")… (17650 characters)
function appendEvents(repo: string, asked: readonly (import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"plan-registered">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; plan: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ title: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; cases: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; requirements: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">[]>; acceptance: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { file: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>[]>; }, Record<never, never>>>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Record<never, never>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"sample-drawn">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; subject: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent-reviews" | "records" | "runs">; rule: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"hash-ranked/1">; seed: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; population: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ count: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; sha256: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "Sha256">>; }, Record<never, never>>>; size: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; items: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly string[]>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { ratePermille: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"sample-attested">; sample: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; results: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ item: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; verdict: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"fail" | "pass">; }, { note: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>[]>; person: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, {}> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"mutation-run">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; tool: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, { version: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; results: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<readonly import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; mutants: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; killed: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; survived: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }, { timeout: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; noCoverage: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; equivalent: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }>[]>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Record<never, never>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-opened">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; cause: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"budget-spent" | "failed" | "probe-failed" | "stale">; reason: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; evidence: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{}, { traceId: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; path: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; openedBy: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"system">; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent">; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"role">; role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, {}> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-linked">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; problem: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ number: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<number>; }, { repo: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-opened">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; nonconformance: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; action: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; test: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Record<never, never>>>; correctiveRevision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; openedBy: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"system">; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent">; name: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"role">; role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { author: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-verified">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; traceId: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; revision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"capa-closed">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; decision: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; person: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { role: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }>>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"nonconformance-closed">; id: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; capa: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"statement">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent" | "person">; who: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { note: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"review">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; by: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"agent" | "person">; who: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, { sample: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<boolean>; }> | import("/home/runner/work/.github/.github/commons/core/src/decode").ObjectOf<{ kind: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"probe">; requirement: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/core/src/brand").Brand<string, "RequirementId">>; outcome: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<"fail" | "pass">; source: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<string>; day: import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<import("/home/runner/work/.github/.github/commons/quality/src/pure/time").Day>; }, Readonly<Record<string, import("/home/runner/work/.github/.github/commons/core/src/decode").Decoder<unknown>>>>)[], options?: AppendOptions): Promise<Result<LedgerRead, LedgerHostError>>

Appends events to the ledger, each as a new file in a commit of its own on the quality branch (created by the first commit where there is none). An event that does not follow the ledger (a CAPA closed before it was verified, a nonconformance closed by editing) is refused and nothing is written; a branch that moved while it was written is refused and the ledger is unchanged.

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

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