IF Commons GitHub

governance/problems

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-headless-governance FR-008

What a run found, as the one contract every headless program shares (commons headless 0002-headless-governance FR-008): a problem has one of four levels, a stable code that can be searched for and written down, a message, and the one step that fixes it. A failure and a warning are problems; pending is something not set up yet that is expected until someone does it; action is a step that is the person's to take. Neither of the last two is wrong, so neither is a failure.

import { countsOf, isProblemCode, problem } from "./problems.ts";
const p = problem("fail", "the disk is full", { code: "E105-DISK", fix: "df -h" });
isProblemCode(p.code); // true
countsOf([p]); // { fail: 1, warn: 0, pending: 0, action: 0 }

Source: commons/headless/src/governance/problems.ts

10 of 24 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.ProblemLeveltypeno test imports it
type ProblemLevel = "fail" | "warn" | "pending" | "action";

How serious a problem is: fail and warn are problems; pending waits on time or someone else; action is the person's to take.

governance.PROBLEM_LEVELSconstno test imports it
const PROBLEM_LEVELS: readonly ProblemLevel[]

Every level, in the order a closing block shows them.

governance.Problemtypeno test imports it
type Problem = { readonly level: ProblemLevel; /** What happened, in a plain sentence. */ readonly message: string… (693 characters)
type Problem = {
  readonly level: ProblemLevel;
  /** What happened, in a plain sentence. */
  readonly message: string;
  /** The phase it happened in, where the run has phases. */
  readonly phase?: string;
  /** How to fix it (for `pending` and `action`: the next step): one command, or a sentence that holds one. */
  readonly fix?: string;
  /** A stable code: `E` for a problem, `P` for something pending, then letters and digits and dashes. */
  readonly code?: string;
  /** The raw text of a system error, when `message` is its plain sentence: shown with `--verbose`. */
  readonly raw?: string;
  /** Its line in the run's log, where there is one. */
  readonly logLine?: number;
};

A problem a run found.

governance.ProblemFieldstypeno test imports it
type ProblemFields = {
  readonly phase?: string;
  readonly fix?: string;
  readonly code?: string;
  readonly raw?: string;
  readonly logLine?: number;
};

A problem's optional fields, given by name.

governance.problemfunctionno test imports it
function problem(level: ProblemLevel, message: string, fields?: ProblemFields): Problem

A problem, made with only the fields that are given (a field never holds undefined).

governance.isProblemCodefunctionno test imports it
function isProblemCode(text: unknown): text is string

Whether a value is a stable problem code.

governance.isPendingCodefunctionno test imports it
function isPendingCode(code: string): boolean

Whether a code is the code of a pending thing (P...), which is never a failure.

governance.GenericCodestypeno test imports it
type GenericCodes = Readonly<Record<ProblemLevel, string>>;

The codes a problem carries when its raiser gave none: one per level, a program's own to configure.

governance.DEFAULT_GENERIC_CODESconstno test imports it
const DEFAULT_GENERIC_CODES: Readonly<Record<ProblemLevel, string>>

The generic codes of a program that has no numbers of its own.

governance.withCodefunctionno test imports it
function withCode(p: Problem, generic?: Readonly<Record<ProblemLevel, string>>): Problem

The problem with the code of its level where it has none.

governance.countsOffunctionno test imports it
function countsOf(problems: readonly Problem[]): Counts

How many problems of each level.

governance.ofLevelfunctionno test imports it
function ofLevel(problems: readonly Problem[], level: ProblemLevel): readonly Problem[]

The problems of a level, in the order found.

ProblemLeveltype
type ProblemLevel = "fail" | "warn" | "pending" | "action";

How serious a problem is: fail and warn are problems; pending waits on time or someone else; action is the person's to take.

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

PROBLEM_LEVELSconst
const PROBLEM_LEVELS: readonly ProblemLevel[]

Every level, in the order a closing block shows them.

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

Problemtype
type Problem = { readonly level: ProblemLevel; /** What happened, in a plain sentence. */ readonly message: string… (693 characters)
type Problem = {
  readonly level: ProblemLevel;
  /** What happened, in a plain sentence. */
  readonly message: string;
  /** The phase it happened in, where the run has phases. */
  readonly phase?: string;
  /** How to fix it (for `pending` and `action`: the next step): one command, or a sentence that holds one. */
  readonly fix?: string;
  /** A stable code: `E` for a problem, `P` for something pending, then letters and digits and dashes. */
  readonly code?: string;
  /** The raw text of a system error, when `message` is its plain sentence: shown with `--verbose`. */
  readonly raw?: string;
  /** Its line in the run's log, where there is one. */
  readonly logLine?: number;
};

A problem a run found.

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

ProblemFieldstypeno test imports it
type ProblemFields = {
  readonly phase?: string;
  readonly fix?: string;
  readonly code?: string;
  readonly raw?: string;
  readonly logLine?: number;
};

A problem's optional fields, given by name.

problemfunction
function problem(level: ProblemLevel, message: string, fields?: ProblemFields): Problem

A problem, made with only the fields that are given (a field never holds undefined).

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

isProblemCodefunction
function isProblemCode(text: unknown): text is string

Whether a value is a stable problem code.

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

isPendingCodefunction
function isPendingCode(code: string): boolean

Whether a code is the code of a pending thing (P...), which is never a failure.

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

GenericCodestypeno test imports it
type GenericCodes = Readonly<Record<ProblemLevel, string>>;

The codes a problem carries when its raiser gave none: one per level, a program's own to configure.

DEFAULT_GENERIC_CODESconst
const DEFAULT_GENERIC_CODES: Readonly<Record<ProblemLevel, string>>

The generic codes of a program that has no numbers of its own.

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

withCodefunction
function withCode(p: Problem, generic?: Readonly<Record<ProblemLevel, string>>): Problem

The problem with the code of its level where it has none.

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

countsOffunction
function countsOf(problems: readonly Problem[]): Counts

How many problems of each level.

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

ofLevelfunction
function ofLevel(problems: readonly Problem[], level: ProblemLevel): readonly Problem[]

The problems of a level, in the order found.

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

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