IF Commons GitHub

pure/record

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-quality-evidence FR-018

The canonical record of a run (commons 0001-quality-evidence FR-018 to FR-020, FR-025): the record of 0008-test-evidence (one OTLP/JSON document, a test span and a log record for each case) extended with what the quality system adds, and read back through the same decoders.

  • canonicalize takes the document a run assembled (assembleRecord) and returns the file to keep: the body of each case's log record is a CTRF test object (FR-018), a case that never started is a log record with the outcome not_run and its reason (FR-013, FR-019), each case carries its grade (FR-014), every resource carries ifc.quality.previous.sha256 (FR-022), and every text is redacted and names no person (FR-025).
  • readQuality reads a file back into a QualityRecord: the model of 0008 (TestRun, five outcomes) and, beside it, every case with its outcome, not_run included, its grade and, for a check's case, its rule and line.
  • checkRun makes the record of a check of Mizan (FR-020): each rule a case, each finding a failed case with its rule id, file and line.
import { readQuality } from "./record.ts";
// const q = readQuality(await readTextFile("quality/evidence/2026/11/17/4bf92f3577b34da6a3ce929d0e0e4736.otlp.json"));
// if (q.kind === "ok") console.log(q.value.counts.notRun, q.value.grade);

Source: commons/quality/src/pure/record.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.

QualityCasetypeno test imports it
type QualityCase = { readonly id: string; /** Its file, relative to the working folder, with `/`. */ readonly file… (926 characters)
type QualityCase = {
  readonly id: string;
  /** Its file, relative to the working folder, with `/`. */
  readonly file: string;
  readonly name: string;
  readonly requirements: readonly string[];
  readonly risk: Risk;
  readonly characteristic?: string;
  readonly outcome: QualityOutcome;
  /** A skip's, a todo's or a cancellation's reason, and why a case did not run (FR-019). */
  readonly reason?: string;
  readonly message?: string;
  readonly expected?: string;
  readonly actual?: string;
  readonly attempt: number;
  readonly start: bigint;
  readonly end: bigint;
  /** The runtime it ran on; `none` for a case that did not run. */
  readonly runtime: string;
  /** What the case is worth (FR-014, FR-026). */
  readonly grade: Grade;
  /** The rule of a check that the case reports (FR-020). */
  readonly rule?: string;
  /** The line of its file a finding points to (FR-020). */
  readonly line?: number;
};

One case of a run, whatever became of it: a test of 0008-test-evidence, a case that did not run, or a check's rule or finding.

QualityCountstypeno test imports it
type QualityCounts = Counts & { readonly notRun: number };

The counts of a run: those of 0008-test-evidence for what ran, and the cases that did not (FR-013).

QualityRecordtype
type QualityRecord = { readonly traceId: string; /** The model of 0008-test-evidence over the same file: the cases t… (567 characters)
type QualityRecord = {
  readonly traceId: string;
  /** The model of 0008-test-evidence over the same file: the cases that ran. */
  readonly run: TestRun;
  /** Every case, in a stable order: what ran as the model orders it, then what did not run by file and name. */
  readonly cases: readonly QualityCase[];
  readonly counts: QualityCounts;
  /** The grade the file claims for itself (FR-014). */
  readonly grade: Grade;
  /** The SHA-256 of the evidence file before this one (FR-022); none where the file is not yet chained. */
  readonly previous?: Sha256;
};

A run's record as the quality system reads it.

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

QualityErrortypeno test imports it
type QualityError =
  | { readonly kind: "record"; readonly error: RecordError }
  | { readonly kind: "otlp"; readonly error: DecodeError }
  | { readonly kind: "case"; readonly spanId: string; readonly reason: string }
  | { readonly kind: "previous"; readonly reason: string }
  | { readonly kind: "person"; readonly key: string };

Why a record could not be made or read.

formatQualityErrorfunctionno test imports it
function formatQualityError(e: QualityError): string

A quality error as one sentence.

qualityCountsfunction
function qualityCounts(cases: readonly { readonly outcome: QualityOutcome; }[]): QualityCounts

The counts of cases.

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

ctrfStatusfunctionno test imports it
function ctrfStatus(o: QualityOutcome): "failed" | "other" | "passed" | "pending" | "skipped"

The status CTRF gives an outcome (other for cancelled and for not_run, FR-019).

ctrfTestfunctionno test imports it
function ctrfTest(c: QualityCase): AnyMap

A case as a CTRF test object (FR-018): name, status and duration, and the other CTRF fields the case has; what CTRF has no field for is under extra.

redactEvidencefunctionno test imports it
function redactEvidence(text: string): string

A text with its secrets (0006-signals FR-006) and its e-mail addresses (0008-test-evidence FR-003) replaced by REDACTED.

NotRuntypeno test imports it
type NotRun = {
  /** The requirements it would have proved. */
  readonly requirements: readonly string[];
  /** The case's name, or the requirement's id where only a requirement was planned. */
  readonly name: string;
  /** Its file, or `plan` where there is none. */
  readonly file?: string;
  readonly reason: string;
  readonly risk?: Risk;
  readonly rule?: string;
};

A case, check or requirement that was planned and did not run, with the reason (FR-013).

readQualityfunction
function readQuality(input: unknown): Result<QualityRecord, QualityError>

A record read into the model of the quality system (FR-018): through the decoders of 0006-signals and the model of 0008-test-evidence (input is the file's text, or its JSON parsed), then the cases that did not run, each case's grade, rule and line, the grade of the file, and its link in the chain.

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

CanonicalInputtypeno test imports it
type CanonicalInput = { /** The run's document as 0008-test-evidence assembles it (`assembleRecord`), or its text. */ … (589 characters)
type CanonicalInput = {
  /** The run's document as 0008-test-evidence assembles it (`assembleRecord`), or its text. */
  readonly record: unknown;
  /** The SHA-256 of the evidence file before this one, or none for the first (FR-022). */
  readonly previous?: Sha256;
  /** What was planned and did not run (FR-013). */
  readonly notRun?: readonly NotRun[];
  /** Facts about the run that every resource of the record carries besides the installation (a command and its options, a plan's hash): the check of another system names its own. */
  readonly resourceAttributes?: Attributes;
};

What canonicalize is given.

Canonicaltypeno test imports it
type Canonical = { readonly text: string; readonly record: QualityRecord };

A record made canonical: the text to keep, and the record it reads back as.

canonicalizefunction
function canonicalize(input: CanonicalInput): Promise<Result<Canonical, QualityError>>

The file to keep for a run (FR-018, FR-022, FR-025): the same OTLP/JSON document with each case's log record bodied as a CTRF test object and carrying its grade, a log record for each case that did not run, ifc.quality.previous.sha256 on every resource, every text redacted of secrets and e-mail addresses, and nothing that names a person (a refusal). Reading the text gives back the record.

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

FIRST_PREVIOUSconstno test imports it
const FIRST_PREVIOUS: Sha256

The first link of the chain (FR-022): 64 zeros.

CheckRuletypeno test imports it
type CheckRule = { readonly id: string; readonly findings: readonly CheckFinding[]; readonly notRun?: string };

One rule of a check and what it found.

CheckFindingtypeno test imports it
type CheckFinding = { readonly file: string; readonly line?: number; readonly message: string };

One finding of a rule: where it is and what it says.

CheckInputtypeno test imports it
type CheckInput = { /** The check's name (`mizan`, `changes`). */ readonly tool: string; readonly rules: readonly … (813 characters)
type CheckInput = {
  /** The check's name (`mizan`, `changes`). */
  readonly tool: string;
  readonly rules: readonly CheckRule[];
  readonly traceId: TraceId;
  readonly spanId: SpanId;
  /** A span id for each case, in order: one per rule that ran clean and one per finding; the caller supplies them (a host makes them). */
  readonly caseIds: readonly SpanId[];
  readonly start: bigint;
  readonly end: bigint;
  readonly runner: Installation;
  /** The requirements the check proves, which each case names. */
  readonly requirements?: readonly string[];
  /** Facts about the run that the resource of the record carries besides the installation (a command and its options, a plan's hash, the version of each tool): a check of another system names its own. */
  readonly resourceAttributes?: Attributes;
};

What checkRun is given: the check, its rules and the run's ids, times and installation.

checkRunfunction
function checkRun(input: CheckInput): Promise<Result<Canonical, QualityError>>

The record of a check of Mizan (0001-quality-evidence FR-020): each rule a case, each finding a failed case with its rule id, file and line, so that its findings render as SARIF results. A rule that ran and found nothing is a pass; each finding is a fail; a rule that could not run (a plain Git host cannot answer the strict rules of the changes check) is a case that is not_run with its reason, never a pass.

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

dayOffunctionno test imports it
function dayOf(nanos: bigint): string

A day as YYYY/MM/DD in UTC, from nanoseconds since the Unix epoch.

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