IF Commons GitHub

logical/nested

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

A run inside another run (commons headless 0003-headless-output FR-010): a command that runs another command of the same program as one of its steps. The child does not draw a closing block of its own; it writes what it found as a summary (to the file its parent names in the environment) and the parent merges it, so that every problem appears once, in the parent's block. The names of the variables come from the program's prefix, and the summary is read back by a decoder, never trusted.

import { nestedNames, summaryOf, parseSummary, encodeSummary } from "./nested.ts";
import { outcomeOf } from "./outcome.ts";
nestedNames("tool").nested; // "TOOL_NESTED"
parseSummary(encodeSummary(summaryOf(outcomeOf(null)))); // ok({ fails: 0, ... })

Source: commons/headless/src/logical/nested.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.NestedNamestypeno test imports it
type NestedNames = {
  /** Set in a child's environment: this run is a step of another. */
  readonly nested: string;
  /** Names the file the child writes its summary to. */
  readonly summary: string;
};

The names of the environment variables a program uses to nest its runs.

logical.nestedNamesfunctionno test imports it
function nestedNames(prefix: string): NestedNames

The variable names of a program, from its prefix (tool or TOOL: TOOL_NESTED and TOOL_SUMMARY).

logical.RunSummarytypeno test imports it
type RunSummary = {
  readonly fails: number;
  readonly warns: number;
  readonly pending: number;
  readonly actions: number;
  readonly problems: readonly Problem[];
  readonly outcomes: readonly string[];
};

What a child run found, as its parent wants it: the counts, every problem in order, and the lines the run wanted seen.

logical.summaryOffunctionno test imports it
function summaryOf(o: Outcome): RunSummary

The summary of an outcome.

logical.problemDecoderconstno test imports it
const problemDecoder: Decoder<ObjectOf<{ level: Decoder<"action" | "fail" | "pending" | "warn">; message: Decoder<string>; }, { phase: Decoder<string>; fix: Decoder<string>; code: Decoder<string>; raw: Decoder<string>; logLine: Decoder<number>; }>>

Reads a problem as a program gives it, from unknown to a typed value.

logical.encodeSummaryfunctionno test imports it
function encodeSummary(s: RunSummary): string

The summary as the text a child writes.

logical.parseSummaryfunctionno test imports it
function parseSummary(text: string): Result<RunSummary, string>

A summary read from the text a child wrote, or why it is not one.

logical.mergeSummaryfunctionno test imports it
function mergeSummary<D>(parent: Outcome<D>, child: RunSummary): Outcome<D>

The parent's outcome with what its child found added after its own: the child's problems and lines, once.

logical.isNestedfunctionno test imports it
function isNested(names: NestedNames, env: (name: string) => string | undefined): boolean

Whether an environment says this run is a step of another.

logical.childEnvfunctionno test imports it
function childEnv(names: NestedNames, summaryFile: string): Readonly<Record<string, string>>

The variables to give a child run: that it is nested, and where to write its summary.

NestedNamestypeno test imports it
type NestedNames = {
  /** Set in a child's environment: this run is a step of another. */
  readonly nested: string;
  /** Names the file the child writes its summary to. */
  readonly summary: string;
};

The names of the environment variables a program uses to nest its runs.

nestedNamesfunction
function nestedNames(prefix: string): NestedNames

The variable names of a program, from its prefix (tool or TOOL: TOOL_NESTED and TOOL_SUMMARY).

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

RunSummarytypeno test imports it
type RunSummary = {
  readonly fails: number;
  readonly warns: number;
  readonly pending: number;
  readonly actions: number;
  readonly problems: readonly Problem[];
  readonly outcomes: readonly string[];
};

What a child run found, as its parent wants it: the counts, every problem in order, and the lines the run wanted seen.

summaryOffunction
function summaryOf(o: Outcome): RunSummary

The summary of an outcome.

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

problemDecoderconstno test imports it
const problemDecoder: Decoder<ObjectOf<{ level: Decoder<"action" | "fail" | "pending" | "warn">; message: Decoder<string>; }, { phase: Decoder<string>; fix: Decoder<string>; code: Decoder<string>; raw: Decoder<string>; logLine: Decoder<number>; }>>

Reads a problem as a program gives it, from unknown to a typed value.

encodeSummaryfunction
function encodeSummary(s: RunSummary): string

The summary as the text a child writes.

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

parseSummaryfunction
function parseSummary(text: string): Result<RunSummary, string>

A summary read from the text a child wrote, or why it is not one.

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

mergeSummaryfunction
function mergeSummary<D>(parent: Outcome<D>, child: RunSummary): Outcome<D>

The parent's outcome with what its child found added after its own: the child's problems and lines, once.

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

isNestedfunction
function isNested(names: NestedNames, env: (name: string) => string | undefined): boolean

Whether an environment says this run is a step of another.

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

childEnvfunction
function childEnv(names: NestedNames, summaryFile: string): Readonly<Record<string, string>>

The variables to give a child run: that it is nested, and where to write its summary.

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

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