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" Limits
It plans T0 to T6 and runs nothing; the caller decides which tiers run where. A change it cannot classify is outside, and a change it cannot explain (Git that does not say) plans everything.
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.ChangedFiletype no 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.ClassifiedFiletype no 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.Usetype no test imports it type Use = { readonly provider : LibraryName ; readonly usage : Usage };What one library imports from another.
logical.LibraryNodetype no 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.LibrarySurfacetype no 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.ProofInputtype no 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.Whytype no 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.PlannedProoftype no 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.SkippedProoftype no 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.ProofPlantype no 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.PlanSteptype no 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.classifyFilefunction no 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.classesOffunction no test imports it function classesOf (files : readonly ClassifiedFile []): readonly ChangeClass []The classes of the files, in the order of the table, each once.
logical.libraryOfPathfunction no 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.everythingfunction no 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.whySentencefunction no test imports it function whySentence (w : Why ): string The sentence that says why a proof is in the plan.
logical.skipSentencefunction no test imports it function skipSentence (s : SkippedProof ): string The sentence that says why leaving a proof out is safe.
logical.proofLabelfunction no test imports it function proofLabel (p : Proof ): string A name of the proof for a person.
logical.planProoffunction no test imports it function planProof (input : ProofInput ): PlanStep The plan of a change, or the libraries whose surface it needs to be given first.
ChangedFiletype no 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).
ClassifiedFiletype no 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.
Usetype no test imports it type Use = { readonly provider : LibraryName ; readonly usage : Usage };What one library imports from another.
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
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
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
Whytype no 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.
PlannedProoftype no test imports it type PlannedProof = { readonly proof : Proof ; readonly tier : ProofTier ; readonly why : Why };A proof of the plan with its tier and why.
SkippedProoftype no 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.
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
PlanSteptype no 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.
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
classesOffunction no test imports it function classesOf (files : readonly ClassifiedFile []): readonly ChangeClass []The classes of the files, in the order of the table, each once.
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
everythingfunction no 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.
whySentencefunction no test imports it function whySentence (w : Why ): string The sentence that says why a proof is in the plan.
skipSentencefunction no test imports it function skipSentence (s : SkippedProof ): string The sentence that says why leaving a proof out is safe.
proofLabelfunction no test imports it function proofLabel (p : Proof ): string A name of the proof for a person.
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