IF Commons GitHub

versions/ledger

The ledger of releases (commons 0026-works-versioning FR-017 to FR-020, FR-027, FR-028, FR-037): derived from the tags of a repository and never written by hand. Each tag <slug>-v<version> of a work is one release, with the commit and tree it names, whether it carries a signature and the day of its commit; the tags are ordered by the work's scheme, a tag that is not greater than an earlier one of its own history, a tag that moved and a tag that is gone are findings, and a retired version, its replacement and its tombstone are read from the record.

Pure: the tags (read by git.ts), the records of the works and the ancestry of the tags' commits are arguments. A work's slug is the prefix of its tags, and a tag belongs to the work with the longest slug it starts with, since a slug and a version may both hold hyphens; a tag that starts with no work's slug is not a release and is left alone. Versions are compared only within one scheme (FR-037): where a record names migratedFrom, the tags up to the one that carries the first version of the new scheme are of the old scheme and the others of the new, and each is read by its own scheme. A tag that is not annotated is read too and says so (annotated: false), since commons' first tags are lightweight.

import { ledgerJson, readLedger } from "./ledger.ts";
// const { entries, findings } = readLedger({ tags, works, isAncestor }); ledgerJson(entries)

Source: commons/mizan/src/versions/ledger.ts

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

versions.addDurationfunctionno test imports it
function addDuration(day: string, duration: string): string | undefined

A day plus an ISO 8601 duration of years, months, weeks and days, clamped to the end of a short month.

versions.lastReleasefunctionno test imports it
function lastRelease(entries: readonly LedgerEntry[], work: Release, reachable?: ReadonlySet<string> | undefined): LedgerEntry | undefined

The releases of one work in the scheme it uses now, the last of them first-class for the commands that need "the last tag" (those of reachable where given).

versions.ledgerJsonfunctionno test imports it
function ledgerJson(entries: readonly LedgerEntry[]): string

The ledger as a deterministic JSON document: { "releases": [...] }, two spaces, a newline at the end.

versions.ledgerTextfunctionno test imports it
function ledgerText(entries: readonly LedgerEntry[]): string

The ledger as text, a line for each release: work, version, commit, tree, signed or unsigned, day, and where it is so a note on retirement.

versions.readEarlierfunctionno test imports it
function readEarlier(text: string): Result<readonly EarlierEntry[], string>

An earlier ledger read from the JSON versions ledger --json wrote (FR-020).

versions.readLedgerfunctionno test imports it
function readLedger(input: LedgerInput): { readonly entries: readonly LedgerEntry[]; readonly findings: readonly VersionsFinding[]; }

The ledger of a repository: its releases in order, and what is wrong with them.

versions.splitTagfunctionno test imports it
function splitTag(name: string, slugs: readonly string[]): { readonly slug: string; readonly version: string; } | undefined

The work and the version a tag name carries, by the slugs known: the work with the longest slug the name starts with.

versions.tagNameOffunctionno test imports it
function tagNameOf(slug: string, version: string): string

The tag a version of a work has.

versions.EarlierEntrytypeno test imports it
type EarlierEntry = {
  readonly work: string;
  readonly version: string;
  readonly tag: string;
  readonly commit: string;
  readonly tree: string;
};

What the ledger keeps of an earlier ledger.

versions.LedgerEntrytypeno test imports it
type LedgerEntry = { readonly work: string; readonly version: string; readonly scheme: Scheme; readonly tag: str… (598 characters)
type LedgerEntry = {
  readonly work: string;
  readonly version: string;
  readonly scheme: Scheme;
  readonly tag: string;
  readonly commit: string;
  readonly tree: string;
  readonly signed: boolean;
  readonly annotated: boolean;
  readonly day: string;
  /** The record's entry for the version where it was retired (FR-028). */
  readonly retired?: { readonly on: string; readonly replacedBy?: string; readonly archivedOn?: string };
  /** The day the bytes of the version were removed, where they were: the version then resolves to a tombstone (FR-027). */
  readonly tombstone?: string;
};

One release of the ledger.

versions.LedgerInputtypeno test imports it
type LedgerInput = {
  readonly tags: readonly TagFact[];
  readonly works: readonly Release[];
  /** Whether the commit `a` is a proper ancestor of the commit `b`. */
  readonly isAncestor: (a: string, b: string) => boolean;
  /** An earlier ledger (`--against`): a tag of it that moved or is gone is a finding. */
  readonly earlier?: readonly EarlierEntry[];
};

What readLedger takes.

versions.TagFacttypeno test imports it
type TagFact = { readonly name: string; /** Whether it is an annotated tag (a lightweight tag is a name for a commit… (422 characters)
type TagFact = {
  readonly name: string;
  /** Whether it is an annotated tag (a lightweight tag is a name for a commit and nothing more). */
  readonly annotated: boolean;
  /** Whether the tag carries a signature (it is not verified). */
  readonly signed: boolean;
  readonly commit: string;
  readonly tree: string;
  /** The committer time of the commit, in seconds since the epoch. */
  readonly seconds: number;
};

A tag of the repository as Git reports it.

addDurationfunction
function addDuration(day: string, duration: string): string | undefined

A day plus an ISO 8601 duration of years, months, weeks and days, clamped to the end of a short month.

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

lastReleasefunction
function lastRelease(entries: readonly LedgerEntry[], work: Release, reachable?: ReadonlySet<string> | undefined): LedgerEntry | undefined

The releases of one work in the scheme it uses now, the last of them first-class for the commands that need "the last tag" (those of reachable where given).

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

ledgerJsonfunction
function ledgerJson(entries: readonly LedgerEntry[]): string

The ledger as a deterministic JSON document: { "releases": [...] }, two spaces, a newline at the end.

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

ledgerTextfunction
function ledgerText(entries: readonly LedgerEntry[]): string

The ledger as text, a line for each release: work, version, commit, tree, signed or unsigned, day, and where it is so a note on retirement.

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

readEarlierfunction
function readEarlier(text: string): Result<readonly EarlierEntry[], string>

An earlier ledger read from the JSON versions ledger --json wrote (FR-020).

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

readLedgerfunction
function readLedger(input: LedgerInput): { readonly entries: readonly LedgerEntry[]; readonly findings: readonly VersionsFinding[]; }

The ledger of a repository: its releases in order, and what is wrong with them.

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

splitTagfunction
function splitTag(name: string, slugs: readonly string[]): { readonly slug: string; readonly version: string; } | undefined

The work and the version a tag name carries, by the slugs known: the work with the longest slug the name starts with.

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

tagNameOffunctionno test imports it
function tagNameOf(slug: string, version: string): string

The tag a version of a work has.

EarlierEntrytypeno test imports it
type EarlierEntry = {
  readonly work: string;
  readonly version: string;
  readonly tag: string;
  readonly commit: string;
  readonly tree: string;
};

What the ledger keeps of an earlier ledger.

LedgerEntrytypeno test imports it
type LedgerEntry = { readonly work: string; readonly version: string; readonly scheme: Scheme; readonly tag: str… (598 characters)
type LedgerEntry = {
  readonly work: string;
  readonly version: string;
  readonly scheme: Scheme;
  readonly tag: string;
  readonly commit: string;
  readonly tree: string;
  readonly signed: boolean;
  readonly annotated: boolean;
  readonly day: string;
  /** The record's entry for the version where it was retired (FR-028). */
  readonly retired?: { readonly on: string; readonly replacedBy?: string; readonly archivedOn?: string };
  /** The day the bytes of the version were removed, where they were: the version then resolves to a tombstone (FR-027). */
  readonly tombstone?: string;
};

One release of the ledger.

LedgerInputtypeno test imports it
type LedgerInput = {
  readonly tags: readonly TagFact[];
  readonly works: readonly Release[];
  /** Whether the commit `a` is a proper ancestor of the commit `b`. */
  readonly isAncestor: (a: string, b: string) => boolean;
  /** An earlier ledger (`--against`): a tag of it that moved or is gone is a finding. */
  readonly earlier?: readonly EarlierEntry[];
};

What readLedger takes.

TagFacttype
type TagFact = { readonly name: string; /** Whether it is an annotated tag (a lightweight tag is a name for a commit… (422 characters)
type TagFact = {
  readonly name: string;
  /** Whether it is an annotated tag (a lightweight tag is a name for a commit and nothing more). */
  readonly annotated: boolean;
  /** Whether the tag carries a signature (it is not verified). */
  readonly signed: boolean;
  readonly commit: string;
  readonly tree: string;
  /** The committer time of the commit, in seconds since the epoch. */
  readonly seconds: number;
};

A tag of the repository as Git reports it.

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

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