IF Commons GitHub

versions/judge

The version check (commons 0026-works-versioning FR-007, FR-009 to FR-014, FR-022, FR-037): for each work, whether its record decodes, whether its version matches the pattern of its kind's scheme, whether its identity is the one it had at the base, and, where files of the work changed since the base, whether its version grew by its scheme.

Pure: it is given the tracked paths and the records of two trees (the head and the base), the paths Git says changed between them, and, for the editions of prose, what Git said of the commits the editions name (their day and which is the ancestor of which). A work is told from another by its slug, so a work that moved to another folder is the same work; a work whose folder holds a record of another slug is a new work only where its record names the one it replaces (replaces), and a change of slug, IRI or position otherwise is versions/identity-changed. A version grows by the scheme of its kind: Semantic Version precedence (build ignored), an edition by its day and then the history, a snapshot by a later day and another digest (and a schema version that grew where the schema's files changed), a revision by a greater number.

import { judgeWorks } from "./judge.ts";
// judgeWorks({ head, base, changed: ["lib/src/a.ts"], editions }) -> [{ rule: "versions/not-grown", ... }] where lib/release.ts did not change

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

5 of 20 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.editionsNeededfunctionno test imports it
function editionsNeeded(head: TreeFacts, base: TreeFacts): readonly string[]

The first eight characters of the commits that the editions of Prose works name, at the head and the base: what the host asks Git about.

versions.isAncestorInfunctionno test imports it
function isAncestorIn(facts: EditionFacts, a: string, b: string): boolean

Whether a is b or an ancestor of it, by the facts given.

versions.judgeWorksfunctionno test imports it
function judgeWorks(input: CheckInput): readonly VersionsFinding[]

The version check over the works of the head against the base (FR-022): the findings of each record by itself, a change of identity (FR-007), and for each work whose files changed since the base a version that did not grow by its scheme (FR-010 to FR-014).

versions.recordFindingsfunctionno test imports it
function recordFindings(folder: string, text: string | undefined): { readonly found: readonly VersionsFinding[]; readonly record?: ReadRecord | undefined; }

The findings a record has by itself, which a folder can judge offline (FR-032), and the record where it decoded: that it decodes, that its version matches the pattern of its kind's scheme, and that the revision of a controlled document has its approval (FR-013).

versions.versionProblemsfunctionno test imports it
function versionProblems(r: Release): readonly string[]

What is wrong with the versions a record carries, by the scheme of its kind (FR-006, FR-010): the version, the schema version of data, the first version of a migration.

versions.workFilesfunctionno test imports it
function workFiles(tree: TreeFacts, folder: string, exclude: readonly string[], paths?: readonly string[]): readonly string[]

The files of a work at a tree, for the commands that list them.

versions.CheckInputtypeno test imports it
type CheckInput = {
  readonly head: TreeFacts;
  readonly base: TreeFacts;
  readonly changed: readonly string[];
  readonly editions: EditionFacts;
};

Everything the check takes: the two trees, the paths that changed between them and the facts about editions.

versions.EditionFactstypeno test imports it
type EditionFacts = {
  /** The commits the editions of the head and the base name, by the first eight characters of their object names. */
  readonly commits: ReadonlyMap<string, { readonly commit: string; readonly day: string }>;
  /** Pairs `<ancestor> <descendant>` of full object names. */
  readonly ancestry: ReadonlySet<string>;
  /** The head commit. */
  readonly head: string;
};

What Git said of the commits that editions name: each by its first eight characters, and which commit is an ancestor of which.

versions.ReadRecordtypeno test imports it
type ReadRecord = { readonly folder: string; readonly file: string; readonly release: Release };

A record read, with the file it is in.

versions.TreeFactstypeno test imports it
type TreeFacts = { readonly paths: readonly string[]; readonly records: ReadonlyMap<string, string> };

A tree as the check reads it: its tracked paths and the text of each record by the folder of its work.

editionsNeededfunction
function editionsNeeded(head: TreeFacts, base: TreeFacts): readonly string[]

The first eight characters of the commits that the editions of Prose works name, at the head and the base: what the host asks Git about.

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

isAncestorInfunctionno test imports it
function isAncestorIn(facts: EditionFacts, a: string, b: string): boolean

Whether a is b or an ancestor of it, by the facts given.

judgeWorksfunction
function judgeWorks(input: CheckInput): readonly VersionsFinding[]

The version check over the works of the head against the base (FR-022): the findings of each record by itself, a change of identity (FR-007), and for each work whose files changed since the base a version that did not grow by its scheme (FR-010 to FR-014).

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

recordFindingsfunction
function recordFindings(folder: string, text: string | undefined): { readonly found: readonly VersionsFinding[]; readonly record?: ReadRecord | undefined; }

The findings a record has by itself, which a folder can judge offline (FR-032), and the record where it decoded: that it decodes, that its version matches the pattern of its kind's scheme, and that the revision of a controlled document has its approval (FR-013).

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

versionProblemsfunctionno test imports it
function versionProblems(r: Release): readonly string[]

What is wrong with the versions a record carries, by the scheme of its kind (FR-006, FR-010): the version, the schema version of data, the first version of a migration.

workFilesfunctionno test imports it
function workFiles(tree: TreeFacts, folder: string, exclude: readonly string[], paths?: readonly string[]): readonly string[]

The files of a work at a tree, for the commands that list them.

CheckInputtypeno test imports it
type CheckInput = {
  readonly head: TreeFacts;
  readonly base: TreeFacts;
  readonly changed: readonly string[];
  readonly editions: EditionFacts;
};

Everything the check takes: the two trees, the paths that changed between them and the facts about editions.

EditionFactstype
type EditionFacts = {
  /** The commits the editions of the head and the base name, by the first eight characters of their object names. */
  readonly commits: ReadonlyMap<string, { readonly commit: string; readonly day: string }>;
  /** Pairs `<ancestor> <descendant>` of full object names. */
  readonly ancestry: ReadonlySet<string>;
  /** The head commit. */
  readonly head: string;
};

What Git said of the commits that editions name: each by its first eight characters, and which commit is an ancestor of which.

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

ReadRecordtypeno test imports it
type ReadRecord = { readonly folder: string; readonly file: string; readonly release: Release };

A record read, with the file it is in.

TreeFactstype
type TreeFacts = { readonly paths: readonly string[]; readonly records: ReadonlyMap<string, string> };

A tree as the check reads it: its tracked paths and the text of each record by the folder of its work.

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

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