Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0008-repoctl-prove FR-007
The public type surface of a library as values (commons repoctl 0008-repoctl-prove FR-006 to FR-008 ): the declarations a compiler emitted for its sources, read statement by statement, each exported one with the declarations local to its file that it can mention; the fingerprint of the surface (a hash of each declaration, by name); the names that changed between two fingerprints; and what a source imports from a package, by name. The functions are pure: the Physical layer emits the declarations and hashes the texts, and these decide what changed and who uses it.
A declaration file is regular enough to be cut by depth: a statement ends at a semicolon outside every bracket, or at the brace that closes a block declaration (interface, class, namespace, enum) when a new statement follows. Comments are removed by the compiler; the scanner also skips them and strings, so a comment that holds a brace changes nothing.
import { declarationsOf, importsOf } from "./surface.ts" ;
declarationsOf ("a.d.ts" , "export declare function f(x: number): string; \n " ).map ((d ) => d.name); // ["f"]
importsOf ('import { a, type B } from "@x/y/z";' , "@x/y" ); // { all: false, names: ["a", "B"] } Limits
A name is the key of a declaration, so two declarations of one name in two files of a library are one entry with both texts; an overload is one entry. A change that only moves a declaration to another file leaves its entry as it was.
Source: commons/repoctl/src/logical/surface.ts
6 of 34 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.Declarationtype no test imports it type Declaration = { readonly file : string ; readonly name : string ; readonly text : string };One exported declaration: the file it is in, its name, and its text with the declarations local to the file that it can mention.
logical.Usagetype no test imports it type Usage = { readonly all : boolean ; readonly names : readonly string [] };What a source imports from a package: every name (a namespace import, a re-export of everything, a dynamic import) or these names.
logical.Fingerprinttype no test imports it type Fingerprint = ReadonlyMap <string , string >;The fingerprint of a surface: each exported name with the hash of its declarations.
logical.SurfaceDeltatype no test imports it type SurfaceDelta = { readonly kind : "same" } | { readonly kind : "changed" ; readonly symbols : readonly string [] } | { readonly kind : "unknown" ; readonly why : string };How a library's surface differs between two states: not at all, in these names, or in a way that cannot be told.
logical.codeOffunction no test imports it function codeOf (text : string ): string The code of a text with its comments removed and its white space made one space: two texts that differ only in comments or layout are the same.
logical.statementsOffunction no test imports it function statementsOf (text : string ): readonly string []The statements of a declaration file, each as its text.
logical.exportedNamesfunction no test imports it function exportedNames (statement : string ): readonly string []The names a statement exports; none where it exports nothing.
logical.declarationsOffunction no test imports it function declarationsOf (file : string , text : string ): readonly Declaration []The exported declarations of one declaration file, each with the file's local declarations that it can mention.
logical.fingerprintOffunction no test imports it function fingerprintOf (declarations : readonly Declaration [], hash : (text : string ) => string ): Fingerprint The fingerprint of declarations: each name with the hash of its texts, sorted and joined, so that moving a declaration to another file changes nothing and the order of files changes nothing.
logical.surfaceDeltafunction no test imports it function surfaceDelta (base : Fingerprint , now : Fingerprint ): SurfaceDelta The names whose hash differs, that appeared or that went away between two fingerprints, sorted.
logical.Mentiontype no test imports it type Mention = { readonly name : string ; readonly mentions : readonly string [] };An exported name and the identifiers its declaration mentions (with the declarations local to its file).
logical.mentionsOffunction no test imports it function mentionsOf (declarations : readonly Declaration []): readonly Mention []For each exported name, the identifiers its declarations mention: what a changed name could reach through a library's own surface.
logical.packageOffunction no test imports it function packageOf (specifier : string ): string | undefined The package a specifier names: @scope/name or name, without the subpath; none for a relative path.
logical.usagesOffunction no test imports it function usagesOf (text : string ): ReadonlyMap <string , Usage >What a source imports from each package it imports (the subpaths of one package together): the names, or all of them where the import cannot say which.
logical.importsOffunction no test imports it function importsOf (text : string , pkg : string ): Usage What a source imports from a package (the package name, or any subpath of it).
logical.joinUsagefunction no test imports it function joinUsage (a : Usage , b : Usage ): Usage Declarationtype no test imports it type Declaration = { readonly file : string ; readonly name : string ; readonly text : string };One exported declaration: the file it is in, its name, and its text with the declarations local to the file that it can mention.
Usagetype no test imports it type Usage = { readonly all : boolean ; readonly names : readonly string [] };What a source imports from a package: every name (a namespace import, a re-export of everything, a dynamic import) or these names.
Fingerprinttype no test imports it type Fingerprint = ReadonlyMap <string , string >;The fingerprint of a surface: each exported name with the hash of its declarations.
SurfaceDeltatype no test imports it type SurfaceDelta = { readonly kind : "same" } | { readonly kind : "changed" ; readonly symbols : readonly string [] } | { readonly kind : "unknown" ; readonly why : string };How a library's surface differs between two states: not at all, in these names, or in a way that cannot be told.
function codeOf (text : string ): string The code of a text with its comments removed and its white space made one space: two texts that differ only in comments or layout are the same.
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
statementsOffunction no test imports it function statementsOf (text : string ): readonly string []The statements of a declaration file, each as its text.
exportedNamesfunction no test imports it function exportedNames (statement : string ): readonly string []The names a statement exports; none where it exports nothing.
function declarationsOf (file : string , text : string ): readonly Declaration []The exported declarations of one declaration file, each with the file's local declarations that it can mention.
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
function fingerprintOf (declarations : readonly Declaration [], hash : (text : string ) => string ): Fingerprint The fingerprint of declarations: each name with the hash of its texts, sorted and joined, so that moving a declaration to another file changes nothing and the order of files changes nothing.
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
function surfaceDelta (base : Fingerprint , now : Fingerprint ): SurfaceDelta The names whose hash differs, that appeared or that went away between two fingerprints, sorted.
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
Mentiontype no test imports it type Mention = { readonly name : string ; readonly mentions : readonly string [] };An exported name and the identifiers its declaration mentions (with the declarations local to its file).
mentionsOffunction no test imports it function mentionsOf (declarations : readonly Declaration []): readonly Mention []For each exported name, the identifiers its declarations mention: what a changed name could reach through a library's own surface.
packageOffunction no test imports it function packageOf (specifier : string ): string | undefined The package a specifier names: @scope/name or name, without the subpath; none for a relative path.
function usagesOf (text : string ): ReadonlyMap <string , Usage >What a source imports from each package it imports (the subpaths of one package together): the names, or all of them where the import cannot say which.
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
function importsOf (text : string , pkg : string ): Usage What a source imports from a package (the package name, or any subpath of it).
Imported by 11 tests of the run (11 passed, 0 failed): the library's results
joinUsagefunction no test imports it function joinUsage (a : Usage , b : Usage ): Usage