IF Commons GitHub

changes/declaration

A harness's declaration for the changes check (commons 0020-ifccm FR-010 to FR-013, FR-019, FR-020): the regulated domains it claims (ifccm:RegulatedDomain) and the day it declares production, the phase that follows (warn before the day, gate from it), the Decisions that authorize departures, and the judgement that a declaration was relaxed in Git history.

Pure: the day it is judged on, the earlier versions of the declaration and the Decisions are arguments. The record a harness writes is a TypeScript file of object literals (export const declaration = { ... }, export const decisions = [ ... ], export const roles = { ... }) read as data and never run, so that an earlier version from Git reads the same way as the present one (kernel/ts-literal.ts). The names of the regulated domains are the keys of ifccm:RegulatedDomain; a test holds the two lists equal.

import { decodeDeclaration, phaseOf } from "./declaration.ts";
const d = decodeDeclaration({ regulatedDomains: ["DeviceQuality"], productionDeclaredOn: "2027-01-01" });
if (d.kind === "ok") phaseOf(d.value, "2027-01-01"); // "gate"

Source: commons/mizan/src/changes/declaration.ts

14 of 54 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.coversfunctionno test imports it
function covers(decision: DecisionRecord, thing: string): boolean

Whether a Decision covers a thing (a requirement, gate-relaxed <revision> or no-issue <revision>): a covered revision may be named by a prefix of at least 7 characters.

changes.dayOffunctionno test imports it
function dayOf(text: string): Day | undefined

Text as a day, or undefined where it is not a real calendar day written YYYY-MM-DD.

changes.decodeDecisionsfunctionno test imports it
function decodeDecisions(input: unknown): Result<readonly DecisionRecord[], DecodeError>

The Decisions decoded from data.

changes.decodeDeclarationfunctionno test imports it
function decodeDeclaration(input: unknown): Result<Declaration, DecodeError>

A declaration decoded from data read from a file.

changes.decodeHarnessRecordfunctionno test imports it
function decodeHarnessRecord(source: string): Result<HarnessRecord, RecordError>

The record of a harness read from the text of its file (export const declaration = ..., and optionally decisions and roles). A file with no declaration is a harness that declares nothing (not regulated, not in production), which is not an error (0020-ifccm FR-010).

changes.declarationProblemfunctionno test imports it
function declarationProblem(declaration: Declaration | undefined): string | undefined

What is wrong with a declaration by itself (0020-ifccm FR-010): a regulated domain claimed with no production day.

changes.formatRecordErrorfunctionno test imports it
function formatRecordError(e: RecordError): string

A record error as a sentence.

changes.isRegulatedfunctionno test imports it
function isRegulated(declaration: Declaration | undefined): boolean

Whether a declaration claims a regulated domain.

changes.NO_ISSUEconstno test imports it
const NO_ISSUE: "no-issue"

The word a covers entry starts with when the owner exempts one commit from naming a change request: no-issue <revision> (0020-ifccm FR-046).

changes.noIssueEntriesfunctionno test imports it
function noIssueEntries(decision: DecisionRecord): readonly { readonly entry: string; readonly revision: string | undefined; }[]

The entries of a Decision that exempt a commit (no-issue ...): each with its revision where it is well formed (no-issue and 7 to 64 lowercase hexadecimal characters), none where it is not.

changes.noIssueProblemsfunctionno test imports it
function noIssueProblems(decision: DecisionRecord, roles: Readonly<Record<string, string>>): readonly string[]

What is wrong with a Decision that exempts a commit (0020-ifccm FR-046), as sentences; none for a Decision that covers no no-issue entry or one whose entries, person, day and reason are all sound. The person is approvedBy: it MUST name someone, and MUST NOT be a role of roles, because a role is not a person.

changes.phaseOffunctionno test imports it
function phaseOf(declaration: Declaration | undefined, today: string): Phase

The phase a harness is in on today: gate from the day it declared production (that day included), else warn (0020-ifccm FR-011).

changes.REGULATED_DOMAINSconstno test imports it
const REGULATED_DOMAINS: readonly ["FederalSecurity", "DeviceQuality", "ElectronicRecords", "DeviceSoftware", "TrustServices"]

The names of the regulated domains a harness may claim: the keys of ifccm:RegulatedDomain (a test holds the two lists equal).

changes.relaxationsfunctionno test imports it
function relaxations(history: readonly DeclarationVersion[]): readonly Relaxation[]

The relaxations in a history of a declaration, oldest version first (0020-ifccm FR-012): a production day that had passed on the day of the change and was moved later or removed, and a regulated domain dropped.

changes.rungsRequiredfunctionno test imports it
function rungsRequired(declaration: Declaration | undefined, today: string): readonly number[]

The rungs of the ladder that a declaration requires on today beyond the rungs every harness has (0020-ifccm FR-013, 0016-ladder FR-011): rungs 9 and 10 from the day a harness that claims a regulated domain declares production, and none before it or for a harness that claims none.

changes.Daytypeno test imports it
type Day = Brand<string, "Day">;

A calendar day, YYYY-MM-DD, made only by dayOf; the days compare as text.

changes.DecisionRecordtypeno test imports it
type DecisionRecord = { readonly id: string; /** The role that approved it (0020-ifccm FR-019). */ readonly approv… (747 characters)
type DecisionRecord = {
  readonly id: string;
  /** The role that approved it (0020-ifccm FR-019). */
  readonly approvedBy: string;
  /** What it authorizes: requirements as `NNNN-slug FR-nnn` for a departure, `gate-relaxed <revision>` for a relaxed declaration, or `no-issue <revision>` for the one commit the owner exempts from naming a change request. */
  readonly covers: readonly string[];
  /** Why it was made; a Decision that covers `no-issue <revision>` MUST state it. */
  readonly reason?: string;
  /** The day it was made, `YYYY-MM-DD`; a Decision that covers `no-issue <revision>` MUST state it. */
  readonly decidedOn?: string;
  /** The change request that records it (`mz:record`), by number. */
  readonly record?: number;
};

A Decision (mz:Decision) as the check reads it: who approved it, what it authorizes, and the issue that records it where there is one.

changes.Declarationtypeno test imports it
type Declaration = { readonly regulatedDomains: readonly RegulatedDomainName[]; /** The day it declares production; … (568 characters)
type Declaration = {
  readonly regulatedDomains: readonly RegulatedDomainName[];
  /** The day it declares production; absent where it declares none. */
  readonly productionDeclaredOn?: Day;
  /** How long the harness keeps its evidence on the `quality` branch, in days (0021-ifqs FR-047); absent where it states none. */
  readonly retentionDays?: RetentionDays;
  /** The evidence tier the harness releases on, the least tier a regulated harness may release at (0026-works-versioning FR-026); absent where it names none. */
  readonly releaseTier?: ReleaseTier;
};

A harness's declaration (ifccm:HarnessDeclaration).

changes.DeclarationVersiontypeno test imports it
type DeclarationVersion = { readonly revision: string; readonly day: Day; readonly declaration: Declaration | undefined };

One version of a declaration file in Git: the revision that wrote it, the day of that commit, and the declaration then (undefined where the file was absent or declared nothing).

changes.HarnessRecordtypeno test imports it
type HarnessRecord = {
  readonly declaration: Declaration | undefined;
  readonly decisions: readonly DecisionRecord[];
  readonly roles: Readonly<Record<string, string>>;
};

Everything a harness states for the check: its declaration, its Decisions and the role of each author by email.

changes.Phasetypeno test imports it
type Phase = "warn" | "gate";

What an enforcement phase is (ifccm:EnforcementPhase): warn is held by a baseline that only shrinks, gate fails whatever the baseline holds.

changes.RecordErrortypeno test imports it
type RecordError =
  { readonly kind: "decode"; readonly message: string } | { readonly kind: "literal"; readonly name: string; readonly expected: string };

Why a record could not be read.

changes.RegulatedDomainNametypeno test imports it
type RegulatedDomainName = (typeof REGULATED_DOMAINS)[number];

A regulated domain a harness claims.

changes.Relaxationtypeno test imports it
type Relaxation = {
  readonly revision: string;
  readonly how: "day-moved-later" | "day-removed" | "domain-dropped";
  readonly detail: string;
};

A relaxation: the revision that made it and how.

coversfunction
function covers(decision: DecisionRecord, thing: string): boolean

Whether a Decision covers a thing (a requirement, gate-relaxed <revision> or no-issue <revision>): a covered revision may be named by a prefix of at least 7 characters.

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

dayOffunction
function dayOf(text: string): Day | undefined

Text as a day, or undefined where it is not a real calendar day written YYYY-MM-DD.

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

decodeDecisionsfunctionno test imports it
function decodeDecisions(input: unknown): Result<readonly DecisionRecord[], DecodeError>

The Decisions decoded from data.

decodeDeclarationfunction
function decodeDeclaration(input: unknown): Result<Declaration, DecodeError>

A declaration decoded from data read from a file.

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

decodeHarnessRecordfunction
function decodeHarnessRecord(source: string): Result<HarnessRecord, RecordError>

The record of a harness read from the text of its file (export const declaration = ..., and optionally decisions and roles). A file with no declaration is a harness that declares nothing (not regulated, not in production), which is not an error (0020-ifccm FR-010).

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

declarationProblemfunction
function declarationProblem(declaration: Declaration | undefined): string | undefined

What is wrong with a declaration by itself (0020-ifccm FR-010): a regulated domain claimed with no production day.

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

formatRecordErrorfunctionno test imports it
function formatRecordError(e: RecordError): string

A record error as a sentence.

isRegulatedfunctionno test imports it
function isRegulated(declaration: Declaration | undefined): boolean

Whether a declaration claims a regulated domain.

NO_ISSUEconstno test imports it
const NO_ISSUE: "no-issue"

The word a covers entry starts with when the owner exempts one commit from naming a change request: no-issue <revision> (0020-ifccm FR-046).

noIssueEntriesfunctionno test imports it
function noIssueEntries(decision: DecisionRecord): readonly { readonly entry: string; readonly revision: string | undefined; }[]

The entries of a Decision that exempt a commit (no-issue ...): each with its revision where it is well formed (no-issue and 7 to 64 lowercase hexadecimal characters), none where it is not.

noIssueProblemsfunction
function noIssueProblems(decision: DecisionRecord, roles: Readonly<Record<string, string>>): readonly string[]

What is wrong with a Decision that exempts a commit (0020-ifccm FR-046), as sentences; none for a Decision that covers no no-issue entry or one whose entries, person, day and reason are all sound. The person is approvedBy: it MUST name someone, and MUST NOT be a role of roles, because a role is not a person.

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

phaseOffunction
function phaseOf(declaration: Declaration | undefined, today: string): Phase

The phase a harness is in on today: gate from the day it declared production (that day included), else warn (0020-ifccm FR-011).

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

REGULATED_DOMAINSconst
const REGULATED_DOMAINS: readonly ["FederalSecurity", "DeviceQuality", "ElectronicRecords", "DeviceSoftware", "TrustServices"]

The names of the regulated domains a harness may claim: the keys of ifccm:RegulatedDomain (a test holds the two lists equal).

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

relaxationsfunction
function relaxations(history: readonly DeclarationVersion[]): readonly Relaxation[]

The relaxations in a history of a declaration, oldest version first (0020-ifccm FR-012): a production day that had passed on the day of the change and was moved later or removed, and a regulated domain dropped.

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

rungsRequiredfunction
function rungsRequired(declaration: Declaration | undefined, today: string): readonly number[]

The rungs of the ladder that a declaration requires on today beyond the rungs every harness has (0020-ifccm FR-013, 0016-ladder FR-011): rungs 9 and 10 from the day a harness that claims a regulated domain declares production, and none before it or for a harness that claims none.

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

Daytypeno test imports it
type Day = Brand<string, "Day">;

A calendar day, YYYY-MM-DD, made only by dayOf; the days compare as text.

DecisionRecordtype
type DecisionRecord = { readonly id: string; /** The role that approved it (0020-ifccm FR-019). */ readonly approv… (747 characters)
type DecisionRecord = {
  readonly id: string;
  /** The role that approved it (0020-ifccm FR-019). */
  readonly approvedBy: string;
  /** What it authorizes: requirements as `NNNN-slug FR-nnn` for a departure, `gate-relaxed <revision>` for a relaxed declaration, or `no-issue <revision>` for the one commit the owner exempts from naming a change request. */
  readonly covers: readonly string[];
  /** Why it was made; a Decision that covers `no-issue <revision>` MUST state it. */
  readonly reason?: string;
  /** The day it was made, `YYYY-MM-DD`; a Decision that covers `no-issue <revision>` MUST state it. */
  readonly decidedOn?: string;
  /** The change request that records it (`mz:record`), by number. */
  readonly record?: number;
};

A Decision (mz:Decision) as the check reads it: who approved it, what it authorizes, and the issue that records it where there is one.

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

Declarationtype
type Declaration = { readonly regulatedDomains: readonly RegulatedDomainName[]; /** The day it declares production; … (568 characters)
type Declaration = {
  readonly regulatedDomains: readonly RegulatedDomainName[];
  /** The day it declares production; absent where it declares none. */
  readonly productionDeclaredOn?: Day;
  /** How long the harness keeps its evidence on the `quality` branch, in days (0021-ifqs FR-047); absent where it states none. */
  readonly retentionDays?: RetentionDays;
  /** The evidence tier the harness releases on, the least tier a regulated harness may release at (0026-works-versioning FR-026); absent where it names none. */
  readonly releaseTier?: ReleaseTier;
};

A harness's declaration (ifccm:HarnessDeclaration).

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

DeclarationVersiontype
type DeclarationVersion = { readonly revision: string; readonly day: Day; readonly declaration: Declaration | undefined };

One version of a declaration file in Git: the revision that wrote it, the day of that commit, and the declaration then (undefined where the file was absent or declared nothing).

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

HarnessRecordtypeno test imports it
type HarnessRecord = {
  readonly declaration: Declaration | undefined;
  readonly decisions: readonly DecisionRecord[];
  readonly roles: Readonly<Record<string, string>>;
};

Everything a harness states for the check: its declaration, its Decisions and the role of each author by email.

Phasetypeno test imports it
type Phase = "warn" | "gate";

What an enforcement phase is (ifccm:EnforcementPhase): warn is held by a baseline that only shrinks, gate fails whatever the baseline holds.

RecordErrortypeno test imports it
type RecordError =
  { readonly kind: "decode"; readonly message: string } | { readonly kind: "literal"; readonly name: string; readonly expected: string };

Why a record could not be read.

RegulatedDomainNametypeno test imports it
type RegulatedDomainName = (typeof REGULATED_DOMAINS)[number];

A regulated domain a harness claims.

Relaxationtypeno test imports it
type Relaxation = {
  readonly revision: string;
  readonly how: "day-moved-later" | "day-removed" | "domain-dropped";
  readonly detail: string;
};

A relaxation: the revision that made it and how.

RetentionDaystypeno test imports it
type RetentionDays = Brand<number, "RetentionDays">;

A number of days a harness keeps its evidence for: a whole number of at least one, made only by the decoder.

RELEASE_TIERSconst
const RELEASE_TIERS: readonly ["Tier0", "Tier1", "Tier2"]

The evidence tiers a harness may name as the tier it releases on: the keys of ifqs:QualityTier (0021-ifqs FR-036; a test holds the two lists equal).

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

ReleaseTiertypeno test imports it
type ReleaseTier = (typeof RELEASE_TIERS)[number];

An evidence tier (0021-ifqs).

SIGNING_WAIVERconstno test imports it
const SIGNING_WAIVER: "signing-waiver"

The word a Decision's covers entry starts with when it waives the signed-commit rule for a bot account that signs through the host: signing-waiver <account> <key> (ergonex 0002-workspace-model FR-049, which reads the entries this module decodes).

SigningWaivertypeno test imports it
type SigningWaiver = { /** The Decision that names the account and the key. */ readonly decision: string; /** The … (460 characters)
type SigningWaiver = {
  /** The Decision that names the account and the key. */
  readonly decision: string;
  /** The role that approved it (0020-ifccm FR-019). */
  readonly approvedBy: string;
  /** The account that signs, as its commits' committer address is written: `noreply@github.com` for GitHub's own. */
  readonly account: string;
  /** The key, by its fingerprint or its key id, as Git reports it for a signed commit. */
  readonly key: string;
};

A waiver of the signed-commit rule for one account and one key, with the Decision that authorizes it.

signingWaiversfunctionno test imports it
function signingWaivers(decisions: readonly DecisionRecord[]): readonly SigningWaiver[]

The waivers of the signed-commit rule that the Decisions of a harness record make (ergonex 0002-workspace-model FR-049, which reads the entries this module decodes): each entry of a Decision's covers written signing-waiver <account> <key>. An entry that names no account or no key waives nothing, and a Decision that says only signing-waiver or names the account alone waives no one.

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