IF Commons GitHub

logical/envelope

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-headless-output FR-006, 0003-headless-output FR-007

The machine's view of a run (commons headless 0003-headless-output FR-006, FR-007): one JSON document, with a fixed shape and order of keys, that says how the run ended, what it found and what it returned; and the same findings as SARIF 2.1.0 for the tools that read it. Nothing here is coloured, marked or cut to a width: a document is not drawn.

import { envelopeOf, jsonText } from "./envelope.ts";
import { outcomeOf } from "./outcome.ts";
jsonText(envelopeOf({ program: "tool", command: "status", outcome: outcomeOf({ n: 1 }), code: 0 })).startsWith("{"); // true

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

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

logical.ENVELOPE_SCHEMAconstno test imports it
const ENVELOPE_SCHEMA: "headless.envelope/1"

The name and version of the document's shape: a reader checks it.

logical.Jsontypeno test imports it
type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };

A JSON value.

logical.toJsonfunctionno test imports it
function toJson(value: unknown): Json

A value as JSON: what JSON cannot say is made what it can (undefined properties are left out, a bigint is its digits as a string, a Date its ISO text, a number that is not finite null, a function or symbol left out), so that writing it never throws.

logical.Envelopetypeno test imports it
type Envelope = { readonly schema: typeof ENVELOPE_SCHEMA; readonly program: string; readonly version?: string; … (441 characters)
type Envelope = {
  readonly schema: typeof ENVELOPE_SCHEMA;
  readonly program: string;
  readonly version?: string;
  readonly command: string;
  readonly ok: boolean;
  readonly exit: { readonly code: number; readonly name: string };
  readonly counts: Counts;
  readonly problems: readonly Problem[];
  readonly outcomes: readonly string[];
  readonly hints: readonly Hint[];
  readonly next: readonly string[];
  readonly data: Json;
};

The document a run ends with.

logical.EnvelopeInputtypeno test imports it
type EnvelopeInput = {
  readonly program: string;
  readonly version?: string;
  /** The words of the command as typed (`work build`); empty for the program itself. */
  readonly command: string;
  readonly outcome: Outcome;
  /** The status the run ends with. */
  readonly code: number;
};

What an envelope is made from.

logical.envelopeOffunctionno test imports it
function envelopeOf(i: EnvelopeInput): Envelope

The envelope of a run. ok is whether nothing failed; exit.name is the table's name of the status, or other.

logical.jsonTextfunctionno test imports it
function jsonText(e: Envelope): string

The envelope as the one document a run writes: indented, ending in a newline.

logical.SarifInputtypeno test imports it
type SarifInput = { readonly program: string; readonly version?: string; readonly outcome: Outcome };

What SARIF takes of a run.

logical.sarifOffunctionno test imports it
function sarifOf(i: SarifInput): Json

A SARIF 2.1.0 log of a run's findings (those it returned, else those its failures and warnings make).

logical.sarifTextfunctionno test imports it
function sarifText(i: SarifInput): string

SARIF as the one document a run writes.

ENVELOPE_SCHEMAconst
const ENVELOPE_SCHEMA: "headless.envelope/1"

The name and version of the document's shape: a reader checks it.

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

Jsontype
type Json = null | boolean | number | string | readonly Json[] | { readonly [key: string]: Json };

A JSON value.

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

toJsonfunction
function toJson(value: unknown): Json

A value as JSON: what JSON cannot say is made what it can (undefined properties are left out, a bigint is its digits as a string, a Date its ISO text, a number that is not finite null, a function or symbol left out), so that writing it never throws.

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

Envelopetypeno test imports it
type Envelope = { readonly schema: typeof ENVELOPE_SCHEMA; readonly program: string; readonly version?: string; … (441 characters)
type Envelope = {
  readonly schema: typeof ENVELOPE_SCHEMA;
  readonly program: string;
  readonly version?: string;
  readonly command: string;
  readonly ok: boolean;
  readonly exit: { readonly code: number; readonly name: string };
  readonly counts: Counts;
  readonly problems: readonly Problem[];
  readonly outcomes: readonly string[];
  readonly hints: readonly Hint[];
  readonly next: readonly string[];
  readonly data: Json;
};

The document a run ends with.

EnvelopeInputtypeno test imports it
type EnvelopeInput = {
  readonly program: string;
  readonly version?: string;
  /** The words of the command as typed (`work build`); empty for the program itself. */
  readonly command: string;
  readonly outcome: Outcome;
  /** The status the run ends with. */
  readonly code: number;
};

What an envelope is made from.

envelopeOffunction
function envelopeOf(i: EnvelopeInput): Envelope

The envelope of a run. ok is whether nothing failed; exit.name is the table's name of the status, or other.

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

jsonTextfunction
function jsonText(e: Envelope): string

The envelope as the one document a run writes: indented, ending in a newline.

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

SarifInputtypeno test imports it
type SarifInput = { readonly program: string; readonly version?: string; readonly outcome: Outcome };

What SARIF takes of a run.

sarifOffunction
function sarifOf(i: SarifInput): Json

A SARIF 2.1.0 log of a run's findings (those it returned, else those its failures and warnings make).

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

sarifTextfunction
function sarifText(i: SarifInput): string

SARIF as the one document a run writes.

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

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