IF Commons GitHub

logical/surface

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"] }

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.Declarationtypeno 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.Usagetypeno 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.Fingerprinttypeno test imports it
type Fingerprint = ReadonlyMap<string, string>;

The fingerprint of a surface: each exported name with the hash of its declarations.

logical.SurfaceDeltatypeno 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.stripCommentsfunctionno test imports it
function stripComments(text: string): string

The text of TypeScript or JavaScript without its comments, the strings, templates and regular expressions kept as they are.

logical.codeOffunctionno 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.statementsOffunctionno test imports it
function statementsOf(text: string): readonly string[]

The statements of a declaration file, each as its text.

logical.exportedNamesfunctionno test imports it
function exportedNames(statement: string): readonly string[]

The names a statement exports; none where it exports nothing.

logical.declarationsOffunctionno 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.fingerprintOffunctionno 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.surfaceDeltafunctionno 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.Mentiontypeno 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.mentionsOffunctionno 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.packageOffunctionno 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.usagesOffunctionno 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.importsOffunctionno 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.joinUsagefunctionno test imports it
function joinUsage(a: Usage, b: Usage): Usage

The union of usages.

Declarationtypeno 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.

Usagetypeno 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.

Fingerprinttypeno test imports it
type Fingerprint = ReadonlyMap<string, string>;

The fingerprint of a surface: each exported name with the hash of its declarations.

SurfaceDeltatypeno 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.

stripCommentsfunctionno test imports it
function stripComments(text: string): string

The text of TypeScript or JavaScript without its comments, the strings, templates and regular expressions kept as they are.

codeOffunction
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

statementsOffunctionno test imports it
function statementsOf(text: string): readonly string[]

The statements of a declaration file, each as its text.

exportedNamesfunctionno test imports it
function exportedNames(statement: string): readonly string[]

The names a statement exports; none where it exports nothing.

declarationsOffunction
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

fingerprintOffunction
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

surfaceDeltafunction
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

Mentiontypeno 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).

mentionsOffunctionno 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.

packageOffunctionno 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.

usagesOffunction
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

importsOffunction
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

joinUsagefunctionno test imports it
function joinUsage(a: Usage, b: Usage): Usage

The union of usages.

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