IF Commons GitHub

logical/outcome

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

The typed outcome of a command (commons headless 0003-headless-output FR-002): what a verb returns instead of printing. A report's data and its text, the problems the run found, the lines it wants seen, the optional features it noticed are off (hints), the steps it spells out for the person, and the findings a SARIF reader would list. No surface is named here: the command line draws it, a tool server returns it as JSON.

import { outcomeOf, withProblem } from "./outcome.ts";
import { problem } from "@intellectual-frontiers/headless/governance";
const o = withProblem(outcomeOf({ files: 3 }), problem("warn", "one file is large"));
o.problems.length; // 1

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

7 of 22 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.Hinttypeno test imports it
type Hint = {
  /** Its stable id: it is shown at most once in a while. */
  readonly id: string;
  /** What is off, and what it would give. */
  readonly message: string;
  /** The command that turns it on, where there is one. */
  readonly command?: string;
};

An optional feature that is merely off: a hint, not a problem.

logical.FindingLeveltypeno test imports it
type FindingLevel = "error" | "warning" | "note";

How serious a finding is, in the words SARIF uses.

logical.Findingtypeno test imports it
type Finding = {
  readonly ruleId: string;
  readonly level: FindingLevel;
  readonly message: string;
  readonly file?: string;
  readonly line?: number;
};

One finding of a check, for a reader of SARIF.

logical.Outcometypeno test imports it
type Outcome<D = unknown> = { /** The report's data: what `--json` carries under `data`. */ readonly data: D; /** … (1207 characters)
type Outcome<D = unknown> = {
  /** The report's data: what `--json` carries under `data`. */
  readonly data: D;
  /** The report's text, for a person; what the command writes to its output. */
  readonly text: string | undefined;
  /** Every problem found, in the order found. */
  readonly problems: readonly Problem[];
  /** Lines the run wants the person to see ("Sent: every server applies it within 15 minutes"). */
  readonly outcomes: readonly string[];
  /** Optional features that are off. */
  readonly hints: readonly Hint[];
  /** Steps the command spells out: `next: <command>` is a candidate for the closing next line, any other line is shown as a step (`then: ...`). */
  readonly next: readonly string[];
  /** Findings, for SARIF. */
  readonly findings: readonly Finding[];
  /** The verdict's title when all is well ("Up to date"). */
  readonly title: string | undefined;
  /** Whether the run was stopped by the person before it ended. */
  readonly cancelled: boolean;
  /** The exit the command names for its run (0008-exit-style-consent FR-001): `usage` or `environment` where its problem is of that kind; none where the problems say it. */
  readonly exit: RunExit | undefined;
};

What a command returns.

logical.OutcomeFieldstypeno test imports it
type OutcomeFields = {
  readonly text?: string;
  readonly problems?: readonly Problem[];
  readonly outcomes?: readonly string[];
  readonly hints?: readonly Hint[];
  readonly next?: readonly string[];
  readonly findings?: readonly Finding[];
  readonly title?: string;
  readonly cancelled?: boolean;
  readonly exit?: RunExit;
};

What outcomeOf takes besides the data.

logical.outcomeOffunctionno test imports it
function outcomeOf<D>(data: D, fields?: OutcomeFields): Outcome<D>

An outcome with the data and the fields given; the rest is empty.

logical.NOTHINGconstno test imports it
const NOTHING: Outcome<null>

The outcome of a run that found nothing and has nothing to say.

logical.withExitfunctionno test imports it
function withExit<D>(o: Outcome<D>, exit: RunExit): Outcome<D>

The outcome with the exit its command names.

logical.withProblemfunctionno test imports it
function withProblem<D>(o: Outcome<D>, p: Problem): Outcome<D>

The outcome with one more problem at the end.

logical.mergeOutcomesfunctionno test imports it
function mergeOutcomes<D>(first: Outcome<D>, second: Outcome<unknown>): Outcome<D>

Two outcomes as one: the data and text of the first (the second is what was found beside it), and everything else of the first and then the second, in order. It is associative, and NOTHING is its identity for everything but the data.

logical.findingsOfProblemsfunctionno test imports it
function findingsOfProblems(problems: readonly Problem[]): readonly Finding[]

The findings a SARIF reader sees for a run that has none of its own: each failure an error, each warning a warning, with the problem's code as the rule.

Hinttypeno test imports it
type Hint = {
  /** Its stable id: it is shown at most once in a while. */
  readonly id: string;
  /** What is off, and what it would give. */
  readonly message: string;
  /** The command that turns it on, where there is one. */
  readonly command?: string;
};

An optional feature that is merely off: a hint, not a problem.

FindingLeveltypeno test imports it
type FindingLevel = "error" | "warning" | "note";

How serious a finding is, in the words SARIF uses.

Findingtypeno test imports it
type Finding = {
  readonly ruleId: string;
  readonly level: FindingLevel;
  readonly message: string;
  readonly file?: string;
  readonly line?: number;
};

One finding of a check, for a reader of SARIF.

Outcometype
type Outcome<D = unknown> = { /** The report's data: what `--json` carries under `data`. */ readonly data: D; /** … (1207 characters)
type Outcome<D = unknown> = {
  /** The report's data: what `--json` carries under `data`. */
  readonly data: D;
  /** The report's text, for a person; what the command writes to its output. */
  readonly text: string | undefined;
  /** Every problem found, in the order found. */
  readonly problems: readonly Problem[];
  /** Lines the run wants the person to see ("Sent: every server applies it within 15 minutes"). */
  readonly outcomes: readonly string[];
  /** Optional features that are off. */
  readonly hints: readonly Hint[];
  /** Steps the command spells out: `next: <command>` is a candidate for the closing next line, any other line is shown as a step (`then: ...`). */
  readonly next: readonly string[];
  /** Findings, for SARIF. */
  readonly findings: readonly Finding[];
  /** The verdict's title when all is well ("Up to date"). */
  readonly title: string | undefined;
  /** Whether the run was stopped by the person before it ended. */
  readonly cancelled: boolean;
  /** The exit the command names for its run (0008-exit-style-consent FR-001): `usage` or `environment` where its problem is of that kind; none where the problems say it. */
  readonly exit: RunExit | undefined;
};

What a command returns.

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

OutcomeFieldstypeno test imports it
type OutcomeFields = {
  readonly text?: string;
  readonly problems?: readonly Problem[];
  readonly outcomes?: readonly string[];
  readonly hints?: readonly Hint[];
  readonly next?: readonly string[];
  readonly findings?: readonly Finding[];
  readonly title?: string;
  readonly cancelled?: boolean;
  readonly exit?: RunExit;
};

What outcomeOf takes besides the data.

outcomeOffunction
function outcomeOf<D>(data: D, fields?: OutcomeFields): Outcome<D>

An outcome with the data and the fields given; the rest is empty.

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

NOTHINGconst
const NOTHING: Outcome<null>

The outcome of a run that found nothing and has nothing to say.

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

withExitfunction
function withExit<D>(o: Outcome<D>, exit: RunExit): Outcome<D>

The outcome with the exit its command names.

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

withProblemfunction
function withProblem<D>(o: Outcome<D>, p: Problem): Outcome<D>

The outcome with one more problem at the end.

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

mergeOutcomesfunction
function mergeOutcomes<D>(first: Outcome<D>, second: Outcome<unknown>): Outcome<D>

Two outcomes as one: the data and text of the first (the second is what was found beside it), and everything else of the first and then the second, in order. It is associative, and NOTHING is its identity for everything but the data.

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

findingsOfProblemsfunction
function findingsOfProblems(problems: readonly Problem[]): readonly Finding[]

The findings a SARIF reader sees for a run that has none of its own: each failure an error, each warning a warning, with the problem's code as the rule.

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

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