IF Commons GitHub

state-record

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-host FR-009

The state record (commons 0003-host FR-009 to FR-011): <home>/.ergonex/state.auto.json, which holds the path, the SHA-256 and the generator of each generated file as it was written, the hash of the last plan, the version of Ergonex and the day each tool or module outside the catalog was first seen. ergonex verify compares the disk with it and it with what the templates give now; render and apply never overwrite a file whose bytes differ from it.

Pure: it decodes and encodes text and judges what verify compares; reading and writing the file is the host layer's. The text is deterministic (keys in order, two spaces, LF, one final newline), so that the record's own hash, which the evidence of a run names, is the same for the same record. The record is data, never trusted: a hash that is not 64 hexadecimal digits is refused.

Source: commons/ergonex/src/state-record.ts

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

decodeStateRecordfunction
function decodeStateRecord(text: string): Result<StateRecord, string>

The record from its text, or why it cannot be read: a hand-edited or damaged record is told, never guessed.

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

EMPTY_RECORDconst
const EMPTY_RECORD: StateRecord

A record with nothing in it, as before the first apply.

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

encodeStateRecordfunction
function encodeStateRecord(r: StateRecord): string

The record as text: deterministic, with the header of a generated file as _generated.

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

FileFactstype
type FileFacts = {
  readonly path: string;
  /** The SHA-256 of the bytes on disk; absent where there is no file. */
  readonly onDisk?: Sha256 | undefined;
  /** The SHA-256 the record holds; absent where it holds none. */
  readonly recorded?: Sha256 | undefined;
  /** The SHA-256 of what the templates give now; absent where they give no such file. */
  readonly wanted?: Sha256 | undefined;
};

What verify found of one path.

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

ERGONEX_VERSIONconst
const ERGONEX_VERSION: "0.5.7"

The version of Ergonex the record names.

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

RecordedFiletypeno test imports it
type RecordedFile = {
  readonly sha256: Sha256;
  readonly generator: string;
};

One generated file as it was written.

STATE_RECORD_PATHconstno test imports it
const STATE_RECORD_PATH: ".ergonex/state.auto.json"

Where the state record is, below the root.

StateRecordtypeno test imports it
type StateRecord = { readonly ergonex: string; /** The SHA-256 of the last plan, as `planDigest` gives it; absent be… (452 characters)
type StateRecord = {
  readonly ergonex: string;
  /** The SHA-256 of the last plan, as `planDigest` gives it; absent before the first apply. */
  readonly plan?: Sha256;
  /** The generated files as written, by path. */
  readonly files: Readonly<Record<string, RecordedFile>>;
  /** The day each tool or module outside the catalog was first seen, by name (never restarted by a later run). */
  readonly firstSeen: Readonly<Record<string, string>>;
};

The state record (ergonex:StateRecord).

verifyFindingsfunction
function verifyFindings(facts: readonly FileFacts[], today: string): readonly Finding[]

What ergonex verify reports (0003-host FR-010): a generated file whose bytes differ from the record is an error (a hand edit); a recorded file that is missing, an .auto. file the record does not hold and a file the templates would now write differently (a drift) are each a warning. Nothing is changed. today is the day the findings are first seen.

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

withFilefunction
function withFile(r: StateRecord, file: GeneratedFile, digest: Sha256): StateRecord

The record after a file was written: its path, hash and generator.

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

withoutFilefunction
function withoutFile(r: StateRecord, path: string): StateRecord

The record after a generated file was removed.

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

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