IF Commons GitHub

logical/prove

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

The proof plan as a pure function (commons repoctl 0008-repoctl-prove FR-003 to FR-009): each changed file is classified by its path and its content at the base and now; the classes give the proofs of the tiers; a change inside a library asks the fingerprint of its public surface (and of the surfaces of the importers it reaches) to decide who must be proved again; every proof left out says why. Nothing here reads a file or runs a program: the Physical layer gives the changed files, the import graph and the surfaces, and asks again where the planner says it needs a surface it was not given.

planProof answers either with the plan or with the libraries whose surface it still needs, so that the compiler is asked only for the libraries the reach touches. The same input gives the same plan, in the same order.

import { classifyFile } from "./prove.ts";
classifyFile({ path: "README.md", before: "a", after: "b" }, () => undefined).class; // "prose"

Source: commons/repoctl/src/logical/prove.ts

7 of 38 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.ChangedFiletypeno test imports it
type ChangedFile = { readonly path: string; readonly before: string | undefined; readonly after: string | undefined };

A file that changed: its path and its text at the base and now (none where it was not there).

logical.ClassifiedFiletypeno test imports it
type ClassifiedFile = { readonly path: string; readonly class: ChangeClass; readonly library: LibraryName | undefined };

A changed file with its class and the library whose folder holds it, where one does.

logical.Usetypeno test imports it
type Use = { readonly provider: LibraryName; readonly usage: Usage };

What one library imports from another.

logical.LibraryNodetypeno test imports it
type LibraryNode = {
  readonly name: LibraryName;
  readonly package: string;
  readonly folder: string;
  readonly foundation: boolean;
  readonly uses: readonly Use[];
  readonly systems: readonly ("windows" | "macos")[];
};

A library as the planner reads it: its place, what it imports from other libraries, whether it is foundation, and the systems it has code of its own for.

logical.LibrarySurfacetypeno test imports it
type LibrarySurface = { readonly delta: SurfaceDelta; readonly mentions: readonly Mention[] };

The surface of one library as the planner needs it: how it differs from the base, and for each exported name the identifiers its declaration mentions.

logical.ProofInputtypeno test imports it
type ProofInput = { readonly base: string; /** Whether Git said what changed; where it did not, the plan is everythi… (490 characters)
type ProofInput = {
  readonly base: string;
  /** Whether Git said what changed; where it did not, the plan is everything. */
  readonly gitKnown: boolean;
  /** Plan everything (`--all`). */
  readonly all: boolean;
  readonly changed: readonly ChangedFile[];
  readonly libraries: readonly LibraryNode[];
  readonly surfaces: ReadonlyMap<LibraryName, LibrarySurface>;
  /** The libraries that read the files that no library holds. */
  readonly outsideReaders: readonly LibraryName[];
};

Everything the planner reads.

logical.Whytypeno test imports it
type Why = | { readonly kind: "class"; readonly class: ChangeClass; readonly files: number } | { readonly kind: "sur… (421 characters)
type Why =
  | { readonly kind: "class"; readonly class: ChangeClass; readonly files: number }
  | { readonly kind: "surface"; readonly provider: LibraryName; readonly symbols: readonly string[] }
  | { readonly kind: "surface-unknown"; readonly provider: LibraryName; readonly why: string }
  | { readonly kind: "foundation"; readonly library: LibraryName }
  | { readonly kind: "everything"; readonly because: string };

Why a proof is in the plan.

logical.PlannedProoftypeno test imports it
type PlannedProof = { readonly proof: Proof; readonly tier: ProofTier; readonly why: Why };

A proof of the plan with its tier and why.

logical.SkippedProoftypeno test imports it
type SkippedProof = { readonly tier: ProofTier; readonly subject: string; readonly reason: SkipReason; readonly because: string };

A proof left out, the tier it would have been in, what it would have proved, the reason and the sentence that says why leaving it out is safe.

logical.ProofPlantypeno test imports it
type ProofPlan = {
  readonly base: string;
  readonly files: readonly ClassifiedFile[];
  readonly classes: readonly ChangeClass[];
  readonly proofs: readonly PlannedProof[];
  readonly skipped: readonly SkippedProof[];
  readonly libraries: { readonly total: number; readonly proven: readonly LibraryName[] };
};

The proof plan of a change.

logical.PlanSteptypeno test imports it
type PlanStep = { readonly kind: "plan"; readonly plan: ProofPlan } | { readonly kind: "needs"; readonly libraries: readonly LibraryName[] };

The planner's answer: the plan, or the libraries whose surface it needs first.

logical.classifyFilefunctionno test imports it
function classifyFile(change: ChangedFile, libraryOf: (path: string) => LibraryName | undefined): ClassifiedFile

The class of a changed file, by its path and its content at the base and now; libraryOf says which library's folder holds a path.

logical.classesOffunctionno test imports it
function classesOf(files: readonly ClassifiedFile[]): readonly ChangeClass[]

The classes of the files, in the order of the table, each once.

logical.libraryOfPathfunctionno test imports it
function libraryOfPath(libraries: readonly { readonly name: LibraryName; readonly folder: string; }[]): (path: string) => LibraryName | undefined

The library whose folder holds a path of the repository, among these.

logical.everythingfunctionno test imports it
function everything(libraries: readonly LibraryNode[], why: Why): readonly PlannedProof[]

The proofs of every tier for these libraries: what a change to the planner, --all and the release plan.

logical.whySentencefunctionno test imports it
function whySentence(w: Why): string

The sentence that says why a proof is in the plan.

logical.skipSentencefunctionno test imports it
function skipSentence(s: SkippedProof): string

The sentence that says why leaving a proof out is safe.

logical.proofLabelfunctionno test imports it
function proofLabel(p: Proof): string

A name of the proof for a person.

logical.planProoffunctionno test imports it
function planProof(input: ProofInput): PlanStep

The plan of a change, or the libraries whose surface it needs to be given first.

ChangedFiletypeno test imports it
type ChangedFile = { readonly path: string; readonly before: string | undefined; readonly after: string | undefined };

A file that changed: its path and its text at the base and now (none where it was not there).

ClassifiedFiletypeno test imports it
type ClassifiedFile = { readonly path: string; readonly class: ChangeClass; readonly library: LibraryName | undefined };

A changed file with its class and the library whose folder holds it, where one does.

Usetypeno test imports it
type Use = { readonly provider: LibraryName; readonly usage: Usage };

What one library imports from another.

LibraryNodetype
type LibraryNode = {
  readonly name: LibraryName;
  readonly package: string;
  readonly folder: string;
  readonly foundation: boolean;
  readonly uses: readonly Use[];
  readonly systems: readonly ("windows" | "macos")[];
};

A library as the planner reads it: its place, what it imports from other libraries, whether it is foundation, and the systems it has code of its own for.

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

LibrarySurfacetype
type LibrarySurface = { readonly delta: SurfaceDelta; readonly mentions: readonly Mention[] };

The surface of one library as the planner needs it: how it differs from the base, and for each exported name the identifiers its declaration mentions.

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

ProofInputtype
type ProofInput = { readonly base: string; /** Whether Git said what changed; where it did not, the plan is everythi… (490 characters)
type ProofInput = {
  readonly base: string;
  /** Whether Git said what changed; where it did not, the plan is everything. */
  readonly gitKnown: boolean;
  /** Plan everything (`--all`). */
  readonly all: boolean;
  readonly changed: readonly ChangedFile[];
  readonly libraries: readonly LibraryNode[];
  readonly surfaces: ReadonlyMap<LibraryName, LibrarySurface>;
  /** The libraries that read the files that no library holds. */
  readonly outsideReaders: readonly LibraryName[];
};

Everything the planner reads.

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

Whytypeno test imports it
type Why = | { readonly kind: "class"; readonly class: ChangeClass; readonly files: number } | { readonly kind: "sur… (421 characters)
type Why =
  | { readonly kind: "class"; readonly class: ChangeClass; readonly files: number }
  | { readonly kind: "surface"; readonly provider: LibraryName; readonly symbols: readonly string[] }
  | { readonly kind: "surface-unknown"; readonly provider: LibraryName; readonly why: string }
  | { readonly kind: "foundation"; readonly library: LibraryName }
  | { readonly kind: "everything"; readonly because: string };

Why a proof is in the plan.

PlannedProoftypeno test imports it
type PlannedProof = { readonly proof: Proof; readonly tier: ProofTier; readonly why: Why };

A proof of the plan with its tier and why.

SkippedProoftypeno test imports it
type SkippedProof = { readonly tier: ProofTier; readonly subject: string; readonly reason: SkipReason; readonly because: string };

A proof left out, the tier it would have been in, what it would have proved, the reason and the sentence that says why leaving it out is safe.

ProofPlantype
type ProofPlan = {
  readonly base: string;
  readonly files: readonly ClassifiedFile[];
  readonly classes: readonly ChangeClass[];
  readonly proofs: readonly PlannedProof[];
  readonly skipped: readonly SkippedProof[];
  readonly libraries: { readonly total: number; readonly proven: readonly LibraryName[] };
};

The proof plan of a change.

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

PlanSteptypeno test imports it
type PlanStep = { readonly kind: "plan"; readonly plan: ProofPlan } | { readonly kind: "needs"; readonly libraries: readonly LibraryName[] };

The planner's answer: the plan, or the libraries whose surface it needs first.

classifyFilefunction
function classifyFile(change: ChangedFile, libraryOf: (path: string) => LibraryName | undefined): ClassifiedFile

The class of a changed file, by its path and its content at the base and now; libraryOf says which library's folder holds a path.

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

classesOffunctionno test imports it
function classesOf(files: readonly ClassifiedFile[]): readonly ChangeClass[]

The classes of the files, in the order of the table, each once.

libraryOfPathfunction
function libraryOfPath(libraries: readonly { readonly name: LibraryName; readonly folder: string; }[]): (path: string) => LibraryName | undefined

The library whose folder holds a path of the repository, among these.

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

everythingfunctionno test imports it
function everything(libraries: readonly LibraryNode[], why: Why): readonly PlannedProof[]

The proofs of every tier for these libraries: what a change to the planner, --all and the release plan.

whySentencefunctionno test imports it
function whySentence(w: Why): string

The sentence that says why a proof is in the plan.

skipSentencefunctionno test imports it
function skipSentence(s: SkippedProof): string

The sentence that says why leaving a proof out is safe.

proofLabelfunctionno test imports it
function proofLabel(p: Proof): string

A name of the proof for a person.

planProoffunction
function planProof(input: ProofInput): PlanStep

The plan of a change, or the libraries whose surface it needs to be given first.

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

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