IF Commons GitHub

governance/model

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-policy-gate FR-001, 0002-policy-gate FR-002, 0002-policy-gate FR-003

The vocabulary of a policy gate (0002-policy-gate FR-001 to FR-003): the subjects of a change (an asset, a cloud resource, an endpoint, a file) with their attributes as plain values; a rule, which is a function from a subject to the problems it has, with an id, a title, a severity and what it applies to; a waiver, which a person grants for a rule and a subject, for a reason and until an instant; and the verdict.

import { SEVERITIES } from "./model.ts";
SEVERITIES; // ["block", "warn"]

Source: commons/gate/src/governance/model.ts

3 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.

governance.Valuetypeno test imports it
type Value = string | number | boolean | readonly string[];

An attribute value: a plain value or a list of text.

governance.Subjecttypeno test imports it
type Subject = { readonly id: string; readonly kind: string; readonly attributes: Readonly<Record<string, Value>> };

A thing a change touches.

governance.Changetypeno test imports it
type Change = { readonly before: readonly Subject[]; readonly after: readonly Subject[] };

A change: the subjects as they were and as they will be (a subject only in after is added, only in before removed).

governance.SEVERITIESconstno test imports it
const SEVERITIES: readonly ["block", "warn"]

Whether a rule stops a change or only says so.

governance.Severitytypeno test imports it
type Severity = (typeof SEVERITIES)[number];

A severity.

governance.Problemtypeno test imports it
type Problem = { readonly message: string; readonly attribute?: string };

One problem a rule finds in a subject.

governance.Ruletypeno test imports it
type Rule = {
  readonly id: string;
  readonly title: string;
  readonly severity: Severity;
  /** The kinds of subject it applies to (every kind where absent). */
  readonly kinds?: readonly string[];
  /** The controls (of any framework, by their identifiers) the rule gives evidence for. */
  readonly controls?: readonly string[];
  readonly check: (subject: Subject) => readonly Problem[];
};

A rule of a policy.

governance.Waivertypeno test imports it
type Waiver = { readonly rule: string; readonly subject: string; readonly reason: string; readonly by: string; readonly until: string };

A waiver: a person lets a subject break a rule, for a reason, until an instant.

governance.Violationtypeno test imports it
type Violation = { readonly rule: string; readonly title: string; readonly severity: Severity; readonly subject: string; readonly message: string; readonly controls: readonly string[]; readonly waived?: Waiver };

A violation: a rule broken by a subject.

governance.Verdicttypeno test imports it
type Verdict = { /** Whether the change may go on: no violation that blocks and is not waived. */ readonly pass: boo… (420 characters)
type Verdict = {
  /** Whether the change may go on: no violation that blocks and is not waived. */
  readonly pass: boolean;
  readonly blocking: readonly Violation[];
  readonly warnings: readonly Violation[];
  readonly waived: readonly Violation[];
  /** Waivers that were not used because they have expired, or that no violation needed. */
  readonly unusedWaivers: readonly Waiver[];
  readonly checked: number;
};

The verdict of a gate.

Valuetypeno test imports it
type Value = string | number | boolean | readonly string[];

An attribute value: a plain value or a list of text.

Subjecttype
type Subject = { readonly id: string; readonly kind: string; readonly attributes: Readonly<Record<string, Value>> };

A thing a change touches.

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

Changetypeno test imports it
type Change = { readonly before: readonly Subject[]; readonly after: readonly Subject[] };

A change: the subjects as they were and as they will be (a subject only in after is added, only in before removed).

SEVERITIESconstno test imports it
const SEVERITIES: readonly ["block", "warn"]

Whether a rule stops a change or only says so.

Severitytypeno test imports it
type Severity = (typeof SEVERITIES)[number];

A severity.

Problemtypeno test imports it
type Problem = { readonly message: string; readonly attribute?: string };

One problem a rule finds in a subject.

Ruletype
type Rule = {
  readonly id: string;
  readonly title: string;
  readonly severity: Severity;
  /** The kinds of subject it applies to (every kind where absent). */
  readonly kinds?: readonly string[];
  /** The controls (of any framework, by their identifiers) the rule gives evidence for. */
  readonly controls?: readonly string[];
  readonly check: (subject: Subject) => readonly Problem[];
};

A rule of a policy.

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

Waivertype
type Waiver = { readonly rule: string; readonly subject: string; readonly reason: string; readonly by: string; readonly until: string };

A waiver: a person lets a subject break a rule, for a reason, until an instant.

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

Violationtypeno test imports it
type Violation = { readonly rule: string; readonly title: string; readonly severity: Severity; readonly subject: string; readonly message: string; readonly controls: readonly string[]; readonly waived?: Waiver };

A violation: a rule broken by a subject.

Verdicttypeno test imports it
type Verdict = { /** Whether the change may go on: no violation that blocks and is not waived. */ readonly pass: boo… (420 characters)
type Verdict = {
  /** Whether the change may go on: no violation that blocks and is not waived. */
  readonly pass: boolean;
  readonly blocking: readonly Violation[];
  readonly warnings: readonly Violation[];
  readonly waived: readonly Violation[];
  /** Waivers that were not used because they have expired, or that no violation needed. */
  readonly unusedWaivers: readonly Waiver[];
  readonly checked: number;
};

The verdict of a gate.

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