IF Commons GitHub

versions/scheme

The version schemes of works (commons 0026-works-versioning FR-005, FR-006, FR-010 to FR-014): the kinds of work, the one scheme each kind uses, how a version of each scheme is read, compared and raised. Semantic Versioning 2.0.0 for software, libraries, command-line interfaces, ontologies and schemas; the commit-date edition YYYY.MM.DD-<commit8> for published prose; the snapshot date YYYY-MM-DD for data; an integer revision for a controlled document; and no version for a specification.

Pure: no clock, no Git. The lists are those of commons/ontology/ifr (a test holds them equal), so that the tool needs not load the ontology. The kind of a work decides its scheme and a pattern never does: 2026.11.17-1a2b3c4d is also a Semantic Version, and is an edition where the work is prose (FR-006). Two editions of one day are ordered by the history, which the caller knows and this module does not: it is given the order as a function.

import { compareVersions, parseVersion, schemeOf } from "./scheme.ts";
const a = parseVersion(schemeOf("Library"), "1.2.0");
const b = parseVersion(schemeOf("Library"), "1.10.0");
if (a.kind === "ok" && b.kind === "ok") compareVersions(a.value, b.value); // -1

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

9 of 40 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.commit8Offunctionno test imports it
function commit8Of(commit: string): string

The first eight characters of a commit's object name, as an edition carries them.

versions.companionOffunctionno test imports it
function companionOf(kind: "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"): "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate" | undefined

The scheme of the schema a kind of work also carries: SemVer for data, none for the others (FR-005).

versions.compareVersionsfunctionno test imports it
function compareVersions(a: ParsedVersion, b: ParsedVersion, order?: EditionOrder): number | undefined

Negative where a comes before b, positive where after, zero where they are the same version (FR-010 to FR-013): a Semantic Version by its precedence (build ignored), an edition by its day and then by order (the history), a snapshot by its day and a revision by its number. Versions of two schemes are never compared (FR-037): the result is undefined.

versions.editionAtfunctionno test imports it
function editionAt(commit: string, committedAtSeconds: number): string

The edition made at a commit: its UTC day (from the commit's committer time, never the clock) and the first eight characters of its object name (FR-011).

versions.formatVersionfunctionno test imports it
function formatVersion(v: ParsedVersion): string

The text of a version in its scheme.

versions.greaterImpactfunctionno test imports it
function greaterImpact(a: "major" | "minor" | "patch", b: "major" | "minor" | "patch"): "major" | "minor" | "patch"

The greater of two impacts.

versions.IMPACTSconstno test imports it
const IMPACTS: readonly ["patch", "minor", "major"]

The impacts a capability declares (ifr:Impact), least first.

versions.isSchemefunctionno test imports it
function isScheme(text: string): text is "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate"

Whether a text names a scheme.

versions.isWorkKindfunctionno test imports it
function isWorkKind(text: string): text is "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"

Whether a text names a kind of work.

versions.nextSemVerfunctionno test imports it
function nextSemVer(version: string, impact: "major" | "minor" | "patch"): Result<string, string>

The next Semantic Version after version at an impact (FR-021): major raises the first number and zeroes the others, minor raises the second and zeroes the third, patch raises the third.

versions.parseVersionfunctionno test imports it
function parseVersion(scheme: "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate", text: string): Result<ParsedVersion, string>

A version read by a scheme (FR-006), or why it does not match. A Semantic Version in a record, a tag or a comparison has no build metadata (+<commit12>, FR-010) and no leading v.

versions.SCHEMESconstno test imports it
const SCHEMES: readonly ["SemVer", "CommitDateEdition", "SnapshotDate", "IntegerRevision", "NoVersion"]

The schemes of version (ifr:VersionScheme).

versions.schemeOffunctionno test imports it
function schemeOf(kind: "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"): "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate"

The one scheme a kind of work uses (FR-005).

versions.utcDayfunctionno test imports it
function utcDay(seconds: number): string

The UTC day of a time given in seconds since the epoch.

versions.WORK_KINDSconstno test imports it
const WORK_KINDS: readonly ["Software", "Library", "CommandLineInterface", "Ontology", "Schema", "Prose", "Data", "ControlledDocument", "Specification"]

The kinds of work (ifr:WorkKind; a test holds the two lists equal).

versions.EditionOrdertypeno test imports it
type EditionOrder = (a: string, b: string) => number;

The order of two editions of one day: negative where a is the earlier in the history, positive where later, zero where the history does not say.

versions.Impacttypeno test imports it
type Impact = (typeof IMPACTS)[number];

An impact.

versions.ParsedVersiontypeno test imports it
type ParsedVersion =
  | { readonly scheme: "SemVer"; readonly semver: SemVer }
  | { readonly scheme: "CommitDateEdition"; readonly day: string; readonly commit8: string }
  | { readonly scheme: "SnapshotDate"; readonly day: string }
  | { readonly scheme: "IntegerRevision"; readonly revision: number };

A version as it is read: a Semantic Version, an edition (its day and the first eight characters of its commit), a snapshot day or an integer revision.

versions.Schemetypeno test imports it
type Scheme = (typeof SCHEMES)[number];

A scheme of version.

versions.WorkKindtypeno test imports it
type WorkKind = (typeof WORK_KINDS)[number];

A kind of work.

commit8Offunctionno test imports it
function commit8Of(commit: string): string

The first eight characters of a commit's object name, as an edition carries them.

companionOffunction
function companionOf(kind: "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"): "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate" | undefined

The scheme of the schema a kind of work also carries: SemVer for data, none for the others (FR-005).

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

compareVersionsfunction
function compareVersions(a: ParsedVersion, b: ParsedVersion, order?: EditionOrder): number | undefined

Negative where a comes before b, positive where after, zero where they are the same version (FR-010 to FR-013): a Semantic Version by its precedence (build ignored), an edition by its day and then by order (the history), a snapshot by its day and a revision by its number. Versions of two schemes are never compared (FR-037): the result is undefined.

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

editionAtfunction
function editionAt(commit: string, committedAtSeconds: number): string

The edition made at a commit: its UTC day (from the commit's committer time, never the clock) and the first eight characters of its object name (FR-011).

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

formatVersionfunctionno test imports it
function formatVersion(v: ParsedVersion): string

The text of a version in its scheme.

greaterImpactfunctionno test imports it
function greaterImpact(a: "major" | "minor" | "patch", b: "major" | "minor" | "patch"): "major" | "minor" | "patch"

The greater of two impacts.

IMPACTSconst
const IMPACTS: readonly ["patch", "minor", "major"]

The impacts a capability declares (ifr:Impact), least first.

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

isSchemefunctionno test imports it
function isScheme(text: string): text is "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate"

Whether a text names a scheme.

isWorkKindfunctionno test imports it
function isWorkKind(text: string): text is "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"

Whether a text names a kind of work.

nextSemVerfunction
function nextSemVer(version: string, impact: "major" | "minor" | "patch"): Result<string, string>

The next Semantic Version after version at an impact (FR-021): major raises the first number and zeroes the others, minor raises the second and zeroes the third, patch raises the third.

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

parseVersionfunction
function parseVersion(scheme: "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate", text: string): Result<ParsedVersion, string>

A version read by a scheme (FR-006), or why it does not match. A Semantic Version in a record, a tag or a comparison has no build metadata (+<commit12>, FR-010) and no leading v.

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

SCHEMESconst
const SCHEMES: readonly ["SemVer", "CommitDateEdition", "SnapshotDate", "IntegerRevision", "NoVersion"]

The schemes of version (ifr:VersionScheme).

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

schemeOffunction
function schemeOf(kind: "CommandLineInterface" | "ControlledDocument" | "Data" | "Library" | "Ontology" | "Prose" | "Schema" | "Software" | "Specification"): "CommitDateEdition" | "IntegerRevision" | "NoVersion" | "SemVer" | "SnapshotDate"

The one scheme a kind of work uses (FR-005).

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

utcDayfunctionno test imports it
function utcDay(seconds: number): string

The UTC day of a time given in seconds since the epoch.

WORK_KINDSconst
const WORK_KINDS: readonly ["Software", "Library", "CommandLineInterface", "Ontology", "Schema", "Prose", "Data", "ControlledDocument", "Specification"]

The kinds of work (ifr:WorkKind; a test holds the two lists equal).

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

EditionOrdertypeno test imports it
type EditionOrder = (a: string, b: string) => number;

The order of two editions of one day: negative where a is the earlier in the history, positive where later, zero where the history does not say.

Impacttypeno test imports it
type Impact = (typeof IMPACTS)[number];

An impact.

ParsedVersiontypeno test imports it
type ParsedVersion =
  | { readonly scheme: "SemVer"; readonly semver: SemVer }
  | { readonly scheme: "CommitDateEdition"; readonly day: string; readonly commit8: string }
  | { readonly scheme: "SnapshotDate"; readonly day: string }
  | { readonly scheme: "IntegerRevision"; readonly revision: number };

A version as it is read: a Semantic Version, an edition (its day and the first eight characters of its commit), a snapshot day or an integer revision.

Schemetypeno test imports it
type Scheme = (typeof SCHEMES)[number];

A scheme of version.

WorkKindtypeno test imports it
type WorkKind = (typeof WORK_KINDS)[number];

A kind of work.

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