IF Commons GitHub

logical/select

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0008-repoctl-prove FR-011

Which tests a change must run, and which it may leave out (commons repoctl 0008-repoctl-prove FR-011, FR-012, FR-014): a test runs when anything it transitively imports changed (the selector by imports), when a requirement named by a changed file's // Spec: line is proved by it (the selector by the trace register), or, for a seam, when its library imports a changed symbol of the provider; a test of a suite that reads the tree is never left out (a seam is about symbols, so it runs the tests that import them); a quarantined test is reported and not run until its expiry; and the key of a result in the cache is a hash of everything that decides it.

The functions are pure: the Physical layer reads the files, resolves the imports and runs the tests, and these decide. A test leaves out only what it cannot reach, so the selectors only ever add a test to the run.

import { specIdsOf } from "./select.ts";
specIdsOf("// Spec: 0003-repoctl-sync FR-002, FR-003\n"); // ["0003-repoctl-sync FR-002", "0003-repoctl-sync FR-003"]

Source: commons/repoctl/src/logical/select.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.

logical.TestReachtypeno test imports it
type TestReach = { readonly library: LibraryName; /** The path from the repository's root. */ readonly path: strin… (683 characters)
type TestReach = {
  readonly library: LibraryName;
  /** The path from the repository's root. */
  readonly path: string;
  /** What it transitively imports: files, and folders (ending with `/`) where an import could not be resolved to a file. */
  readonly depends: readonly string[];
  /** Whether it reads the checkout, so that no change can be shown not to reach it. */
  readonly environmental: boolean;
  /** The requirements it proves, as `<spec> FR-nnn`. */
  readonly proves: readonly string[];
  /** What the files of its own library that it reaches import of each other library. */
  readonly uses: readonly { readonly provider: LibraryName; readonly usage: Usage }[];
};

A test file as the selectors read it: where it is, what it reaches, whether it reads the tree, which requirements it proves and what its library imports of other libraries through it.

logical.Selectortypeno test imports it
type Selector = "import" | "trace" | "symbol" | "environmental" | "everything";

Why a test is in the run.

logical.Selectiontypeno test imports it
type Selection = {
  readonly run: readonly { readonly test: TestReach; readonly by: Selector }[];
  readonly left: readonly TestReach[];
};

The tests that run, each with why, and those left out.

logical.specIdsOffunctionno test imports it
function specIdsOf(text: string): readonly string[]

The requirements a text names on its Spec: lines, as <spec> FR-nnn, the list after a spec expanded.

logical.provesOffunctionno test imports it
function provesOf(text: string): readonly string[]

The requirements a test proves: the identifiers in its proves([...]) calls.

logical.specOfPathfunctionno test imports it
function specOfPath(path: string): string | undefined

The specification a path of a specification's own folder names (.../specs/0008-repoctl-prove/spec.md), where it is one.

logical.readsTheTreefunctionno test imports it
function readsTheTree(text: string): boolean

Whether a text reads the checkout: the tests that do are never left out.

logical.selectTestsfunctionno test imports it
function selectTests(tests: readonly TestReach[], changed: readonly { readonly path: string; readonly text: string; }[], everything: boolean): Selection

The tests of a suite that a change must run: by imports, by the trace register, and the ones that read the tree; the others are left out. everything runs them all (the plan is every proof).

logical.selectSeamfunctionno test imports it
function selectSeam(tests: readonly TestReach[], provider: LibraryName, delta: SurfaceDelta): Selection

The tests of a consumer that a change of the symbols of a provider must run: those whose library files import one of them (or everything from the provider).

logical.applyQuarantinefunctionno test imports it
function applyQuarantine<T extends { readonly test: TestReach; }>(selected: readonly T[], entries: readonly QuarantineEntry[], today: string): { readonly run: readonly T[]; readonly held: readonly { readonly item: T; readonly entry: QuarantineEntry; }[]; readonly expired: readonly QuarantineEntry[]; }

The tests of a run split by the quarantine record on a day (YYYY-MM-DD): those that run, those held back with their entry, and the entries that have expired (their tests run again).

logical.seedsOffunctionno test imports it
function seedsOf(output: string): readonly string[]

The seeds and counterexamples a failing property test printed, so that a failure says how to reproduce it.

logical.cacheKeyOffunctionno test imports it
function cacheKeyOf(parts: { readonly runtime: string; readonly library: LibraryName; readonly test: string; readonly hashes: readonly (readonly [string, string])[]; }): string

The key of a result: the same text for the same test, the same sources it imports and the same runtime, so that a cache holds a result by it. The hashes are given: one for the test, one for each source it imports.

TestReachtype
type TestReach = { readonly library: LibraryName; /** The path from the repository's root. */ readonly path: strin… (683 characters)
type TestReach = {
  readonly library: LibraryName;
  /** The path from the repository's root. */
  readonly path: string;
  /** What it transitively imports: files, and folders (ending with `/`) where an import could not be resolved to a file. */
  readonly depends: readonly string[];
  /** Whether it reads the checkout, so that no change can be shown not to reach it. */
  readonly environmental: boolean;
  /** The requirements it proves, as `<spec> FR-nnn`. */
  readonly proves: readonly string[];
  /** What the files of its own library that it reaches import of each other library. */
  readonly uses: readonly { readonly provider: LibraryName; readonly usage: Usage }[];
};

A test file as the selectors read it: where it is, what it reaches, whether it reads the tree, which requirements it proves and what its library imports of other libraries through it.

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

Selectortypeno test imports it
type Selector = "import" | "trace" | "symbol" | "environmental" | "everything";

Why a test is in the run.

Selectiontypeno test imports it
type Selection = {
  readonly run: readonly { readonly test: TestReach; readonly by: Selector }[];
  readonly left: readonly TestReach[];
};

The tests that run, each with why, and those left out.

specIdsOffunction
function specIdsOf(text: string): readonly string[]

The requirements a text names on its Spec: lines, as <spec> FR-nnn, the list after a spec expanded.

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

provesOffunction
function provesOf(text: string): readonly string[]

The requirements a test proves: the identifiers in its proves([...]) calls.

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

specOfPathfunction
function specOfPath(path: string): string | undefined

The specification a path of a specification's own folder names (.../specs/0008-repoctl-prove/spec.md), where it is one.

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

readsTheTreefunction
function readsTheTree(text: string): boolean

Whether a text reads the checkout: the tests that do are never left out.

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

selectTestsfunction
function selectTests(tests: readonly TestReach[], changed: readonly { readonly path: string; readonly text: string; }[], everything: boolean): Selection

The tests of a suite that a change must run: by imports, by the trace register, and the ones that read the tree; the others are left out. everything runs them all (the plan is every proof).

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

selectSeamfunction
function selectSeam(tests: readonly TestReach[], provider: LibraryName, delta: SurfaceDelta): Selection

The tests of a consumer that a change of the symbols of a provider must run: those whose library files import one of them (or everything from the provider).

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

applyQuarantinefunction
function applyQuarantine<T extends { readonly test: TestReach; }>(selected: readonly T[], entries: readonly QuarantineEntry[], today: string): { readonly run: readonly T[]; readonly held: readonly { readonly item: T; readonly entry: QuarantineEntry; }[]; readonly expired: readonly QuarantineEntry[]; }

The tests of a run split by the quarantine record on a day (YYYY-MM-DD): those that run, those held back with their entry, and the entries that have expired (their tests run again).

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

seedsOffunction
function seedsOf(output: string): readonly string[]

The seeds and counterexamples a failing property test printed, so that a failure says how to reproduce it.

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

cacheKeyOffunction
function cacheKeyOf(parts: { readonly runtime: string; readonly library: LibraryName; readonly test: string; readonly hashes: readonly (readonly [string, string])[]; }): string

The key of a result: the same text for the same test, the same sources it imports and the same runtime, so that a cache holds a result by it. The hashes are given: one for the test, one for each source it imports.

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

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