IF Commons GitHub

changes/capability-view

The view of the capabilities that touch each rung (commons 0020-ifccm FR-016, FR-017), generated between the markers <!-- capabilities:begin --> and <!-- capabilities:end --> of a harness's document, and the check that the document still holds it (--check). The view is an axis across the ladder and no rung of it.

Pure text in, text out. A capability states its rungs (ifccm:touchesRung) and its last revision; a rung states the commands that prove it (mz:provedBy). A capability is shown as proved on a rung when every one of the rung's commands has a passing run at the capability's last revision, and as open on it otherwise (0016-ladder FR-003); a rung that names no command cannot be proved, so a capability that touches it is open there. The view lists only the rungs some capability touches, in the order the rungs are given, and the capabilities of a rung by number.

import { viewOf } from "./capability-view.ts";
viewOf([{ id: "rung-5", label: "Checks", provedBy: ["bun test"] }], [{ id: 10, title: "The check", touchesRung: ["rung-5"], lastRevision: "abc1234" }], []);
// "### Checks (rung-5)\n\n- #10 The check: open, `bun test` has no passing run at abc1234\n"

Source: commons/mizan/src/changes/capability-view.ts

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

changes.BEGINconstno test imports it
const BEGIN: "<!-- capabilities:begin -->"

The marker that opens the generated view.

changes.decodeViewRecordfunctionno test imports it
function decodeViewRecord(source: string, capabilitiesRequired?: boolean): Result<ViewRecord, string>

The record of a harness's capabilities read from its file's text (export const rungs, export const capabilities and, where it has them, export const runs), as data and never run. The offline view derives its capabilities from the commits (0020-ifccm FR-035), and then the file needs no capabilities (capabilitiesRequired false). The runs are stated here until the quality records of 0021-ifqs are read in their place.

changes.ENDconstno test imports it
const END: "<!-- capabilities:end -->"

The marker that closes it.

changes.formatViewErrorfunctionno test imports it
function formatViewError(e: ViewError): string

A view error as a sentence.

changes.isProvedfunctionno test imports it
function isProved(rung: RungRecord, revision: string, runs: readonly CommandRun[]): boolean

Whether every command of a rung has a passing run at the revision; a rung with no command is not proved.

changes.spliceViewfunctionno test imports it
function spliceView(document: string, view: string): Result<string, ViewError>

The document with the view between its markers.

changes.viewIsCurrentfunctionno test imports it
function viewIsCurrent(document: string, view: string): Result<boolean, ViewError>

Whether the document holds the view as it would be generated (--check): ok(true) where it does, ok(false) where it differs.

changes.viewOffunctionno test imports it
function viewOf(rungs: readonly RungRecord[], capabilities: readonly CapabilityRecord[], runs: readonly CommandRun[]): string

The view: for each rung some capability touches, in the order of rungs, the capabilities that touch it and whether each is proved or open there.

changes.CapabilityRecordtypeno test imports it
type CapabilityRecord = {
  readonly id: number;
  readonly title: string;
  readonly touchesRung: readonly string[];
  readonly lastRevision: string;
};

A capability as the view reads it: its change request's number, its title, the rungs it touches and the last revision of its work.

changes.CommandRuntypeno test imports it
type CommandRun = { readonly command: string; readonly revision: string; readonly passed: boolean };

A run of a rung's command at a revision.

changes.RungRecordtypeno test imports it
type RungRecord = {
  readonly id: string;
  readonly label: string;
  readonly provedBy: readonly string[];
  readonly homes?: readonly string[];
};

A rung as the view reads it: its identifier, its label, the commands that prove it and, where the offline trace places files on it, its homes (0020-ifccm FR-035).

changes.ViewErrortypeno test imports it
type ViewError = { readonly kind: "no-markers" } | { readonly kind: "misplaced-markers" };

Why a document cannot hold the view.

changes.ViewRecordtypeno test imports it
type ViewRecord = {
  readonly rungs: readonly RungRecord[];
  readonly capabilities: readonly CapabilityRecord[];
  readonly runs: readonly CommandRun[];
};

What a harness states for the view: its rungs, its capabilities and the runs of the rungs' commands.

BEGINconst
const BEGIN: "<!-- capabilities:begin -->"

The marker that opens the generated view.

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

decodeViewRecordfunction
function decodeViewRecord(source: string, capabilitiesRequired?: boolean): Result<ViewRecord, string>

The record of a harness's capabilities read from its file's text (export const rungs, export const capabilities and, where it has them, export const runs), as data and never run. The offline view derives its capabilities from the commits (0020-ifccm FR-035), and then the file needs no capabilities (capabilitiesRequired false). The runs are stated here until the quality records of 0021-ifqs are read in their place.

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

ENDconst
const END: "<!-- capabilities:end -->"

The marker that closes it.

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

formatViewErrorfunctionno test imports it
function formatViewError(e: ViewError): string

A view error as a sentence.

isProvedfunction
function isProved(rung: RungRecord, revision: string, runs: readonly CommandRun[]): boolean

Whether every command of a rung has a passing run at the revision; a rung with no command is not proved.

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

spliceViewfunction
function spliceView(document: string, view: string): Result<string, ViewError>

The document with the view between its markers.

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

viewIsCurrentfunction
function viewIsCurrent(document: string, view: string): Result<boolean, ViewError>

Whether the document holds the view as it would be generated (--check): ok(true) where it does, ok(false) where it differs.

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

viewOffunction
function viewOf(rungs: readonly RungRecord[], capabilities: readonly CapabilityRecord[], runs: readonly CommandRun[]): string

The view: for each rung some capability touches, in the order of rungs, the capabilities that touch it and whether each is proved or open there.

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

CapabilityRecordtypeno test imports it
type CapabilityRecord = {
  readonly id: number;
  readonly title: string;
  readonly touchesRung: readonly string[];
  readonly lastRevision: string;
};

A capability as the view reads it: its change request's number, its title, the rungs it touches and the last revision of its work.

CommandRuntypeno test imports it
type CommandRun = { readonly command: string; readonly revision: string; readonly passed: boolean };

A run of a rung's command at a revision.

RungRecordtypeno test imports it
type RungRecord = {
  readonly id: string;
  readonly label: string;
  readonly provedBy: readonly string[];
  readonly homes?: readonly string[];
};

A rung as the view reads it: its identifier, its label, the commands that prove it and, where the offline trace places files on it, its homes (0020-ifccm FR-035).

ViewErrortypeno test imports it
type ViewError = { readonly kind: "no-markers" } | { readonly kind: "misplaced-markers" };

Why a document cannot hold the view.

ViewRecordtypeno test imports it
type ViewRecord = {
  readonly rungs: readonly RungRecord[];
  readonly capabilities: readonly CapabilityRecord[];
  readonly runs: readonly CommandRun[];
};

What a harness states for the view: its rungs, its capabilities and the runs of the rungs' commands.

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