versions.addDurationfunctionno test imports itfunction addDuration(day: string, duration: string): string | undefinedA day plus an ISO 8601 duration of years, months, weeks and days, clamped to the end of a short month.
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)versions.addDurationfunctionno test imports itfunction addDuration(day: string, duration: string): string | undefinedA day plus an ISO 8601 duration of years, months, weeks and days, clamped to the end of a short month.
versions.lastReleasefunctionno test imports itfunction lastRelease(entries: readonly LedgerEntry[], work: Release, reachable?: ReadonlySet<string> | undefined): LedgerEntry | undefinedThe 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 itfunction ledgerJson(entries: readonly LedgerEntry[]): stringThe ledger as a deterministic JSON document: { "releases": [...] }, two spaces, a newline at the end.
versions.ledgerTextfunctionno test imports itfunction ledgerText(entries: readonly LedgerEntry[]): stringThe 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 itfunction readEarlier(text: string): Result<readonly EarlierEntry[], string>An earlier ledger read from the JSON versions ledger --json wrote (FR-020).
versions.readLedgerfunctionno test imports itfunction 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 itfunction splitTag(name: string, slugs: readonly string[]): { readonly slug: string; readonly version: string; } | undefinedThe 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 itfunction tagNameOf(slug: string, version: string): stringThe tag a version of a work has.
versions.EarlierEntrytypeno test imports ittype 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 ittype 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 ittype 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 ittype 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.
addDurationfunctionfunction addDuration(day: string, duration: string): string | undefinedA day plus an ISO 8601 duration of years, months, weeks and days, clamped to the end of a short month.
lastReleasefunctionfunction lastRelease(entries: readonly LedgerEntry[], work: Release, reachable?: ReadonlySet<string> | undefined): LedgerEntry | undefinedThe 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).
ledgerJsonfunctionfunction ledgerJson(entries: readonly LedgerEntry[]): stringThe ledger as a deterministic JSON document: { "releases": [...] }, two spaces, a newline at the end.
ledgerTextfunctionfunction ledgerText(entries: readonly LedgerEntry[]): stringThe 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.
readEarlierfunctionfunction readEarlier(text: string): Result<readonly EarlierEntry[], string>An earlier ledger read from the JSON versions ledger --json wrote (FR-020).
readLedgerfunctionfunction 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.
splitTagfunctionfunction splitTag(name: string, slugs: readonly string[]): { readonly slug: string; readonly version: string; } | undefinedThe work and the version a tag name carries, by the slugs known: the work with the longest slug the name starts with.
tagNameOffunctionno test imports itfunction tagNameOf(slug: string, version: string): stringThe tag a version of a work has.
EarlierEntrytypeno test imports ittype 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 ittype 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 ittype 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.
TagFacttypetype 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.