IF Commons GitHub

logical/explain

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

The mechanism of explain and translate (commons headless 0003-headless-output FR-008): a problem shown with a stable code says how to read more about it, and a raw error of another tool (ssh, apt, git) that people meet often is recognized and given its plain cause and fix. The catalogue of codes, the patterns of raw errors and the guides are the program's own data; this module holds the rules for using them.

import { explainText, translator } from "./explain.ts";
const catalogue = { "E001-DNS": { title: "A name did not resolve", what: "It did not.", why: "The network is down.", fix: "ping 1.1.1.1" } };
const translate = translator(catalogue, [[/Could not resolve host/, "E001-DNS"]]);
translate("curl: Could not resolve host: x")?.code; // "E001-DNS"
explainText(catalogue, { program: "tool" }, "e001-dns").includes("Likely cause"); // true

Source: commons/headless/src/logical/explain.ts

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

logical.Explanationtypeno test imports it
type Explanation = {
  readonly title: string;
  /** What happened, in plain words. */
  readonly what: string;
  /** The likely cause. */
  readonly why: string;
  /** The fix: what to do, with the exact command where there is one. */
  readonly fix: string;
  /** The guide that explains more, by its name: the program says where it is shown. */
  readonly doc?: string;
};

One problem's explanation: what, why, the fix, and the guide.

logical.Cataloguetypeno test imports it
type Catalogue = Readonly<Record<string, Explanation>>;

Every explanation, by code.

logical.RawPatterntypeno test imports it
type RawPattern = readonly [RegExp, string];

A pattern of a raw error and the code it is given.

logical.Translationtypeno test imports it
type Translation = { readonly code: string; readonly fix: string };

What a pattern gives: the code and the fix of its explanation.

logical.catalogueProblemsfunctionno test imports it
function catalogueProblems(catalogue: Readonly<Record<string, Explanation>>, patterns?: readonly RawPattern[]): readonly string[]

Everything wrong with a catalogue and its patterns: a code that is not a code, an explanation with a blank field, a pattern that names a code the catalogue lacks.

logical.translatorfunctionno test imports it
function translator(catalogue: Readonly<Record<string, Explanation>>, patterns: readonly RawPattern[]): (raw: string) => Translation | undefined

A function that gives a known raw error its code and fix, or undefined where the error is not known (it is then shown as it is). The first pattern that matches wins.

logical.GuideLinkstypeno test imports it
type GuideLinks = (doc: string) => { readonly ref: string; readonly url: string };

How a program says where more is to be read: the command that shows a guide, here and offline, and where it is online.

logical.ExplainContexttypeno test imports it
type ExplainContext = { readonly program: string; readonly guide?: GuideLinks };

What explainText is given about the program.

logical.explainTextfunctionno test imports it
function explainText(catalogue: Readonly<Record<string, Explanation>>, ctx: ExplainContext, code?: string | undefined): string

The explanation of a code (a code is written in either case), the list of every code, or a sentence that says there is none and names the nearest.

Explanationtypeno test imports it
type Explanation = {
  readonly title: string;
  /** What happened, in plain words. */
  readonly what: string;
  /** The likely cause. */
  readonly why: string;
  /** The fix: what to do, with the exact command where there is one. */
  readonly fix: string;
  /** The guide that explains more, by its name: the program says where it is shown. */
  readonly doc?: string;
};

One problem's explanation: what, why, the fix, and the guide.

Cataloguetype
type Catalogue = Readonly<Record<string, Explanation>>;

Every explanation, by code.

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

RawPatterntype
type RawPattern = readonly [RegExp, string];

A pattern of a raw error and the code it is given.

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

Translationtypeno test imports it
type Translation = { readonly code: string; readonly fix: string };

What a pattern gives: the code and the fix of its explanation.

catalogueProblemsfunction
function catalogueProblems(catalogue: Readonly<Record<string, Explanation>>, patterns?: readonly RawPattern[]): readonly string[]

Everything wrong with a catalogue and its patterns: a code that is not a code, an explanation with a blank field, a pattern that names a code the catalogue lacks.

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

translatorfunction
function translator(catalogue: Readonly<Record<string, Explanation>>, patterns: readonly RawPattern[]): (raw: string) => Translation | undefined

A function that gives a known raw error its code and fix, or undefined where the error is not known (it is then shown as it is). The first pattern that matches wins.

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

GuideLinkstypeno test imports it
type GuideLinks = (doc: string) => { readonly ref: string; readonly url: string };

How a program says where more is to be read: the command that shows a guide, here and offline, and where it is online.

ExplainContexttypeno test imports it
type ExplainContext = { readonly program: string; readonly guide?: GuideLinks };

What explainText is given about the program.

explainTextfunction
function explainText(catalogue: Readonly<Record<string, Explanation>>, ctx: ExplainContext, code?: string | undefined): string

The explanation of a code (a code is written in either case), the list of every code, or a sentence that says there is none and names the nearest.

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

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