IF Commons GitHub

logical/ports

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-repoctl-layers FR-006

The ports of Repoctl (commons repoctl 0001-repoctl-layers FR-006): everything a verb needs of the world, as records of functions that the Physical layer fills and a test fills with its own. A program is run through Process (the same shape as Headless' executor, with the output as text), a file is read and written through Files, the registry of npm is asked through Registry, and a credential is taken through Credentials and never through the environment of a verb. Nothing in Governance or Logical reads a file, runs a program or reaches the network except through these.

import type { Process } from "@intellectual-frontiers/repoctl/logical";
const none: Process = { run: () => Promise.resolve({ code: 0, stdout: "", stderr: "" }) };

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

4 of 20 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.Runtypeno test imports it
type Run = { readonly code: number; readonly stdout: string; readonly stderr: string };

How a program ended, with its output as text.

logical.RunOptionstypeno test imports it
type RunOptions = { readonly cwd?: string; readonly env?: Readonly<Record<string, string>> };

How to run a program: where, and with which variables added to its environment.

logical.Processtypeno test imports it
type Process = { readonly run: (argv: readonly string[], options?: RunOptions) => Promise<Run> };

The port that runs a program by its argument vector, with no shell between.

logical.Filestypeno test imports it
type Files = { /** The text of a file, or undefined where it is not there. */ readonly read: (path: string) => Promi… (1084 characters)
type Files = {
  /** The text of a file, or undefined where it is not there. */
  readonly read: (path: string) => Promise<string | undefined>;
  /** Writes a text (making the folder), with the mode where one is given. */
  readonly write: (path: string, text: string, mode?: number) => Promise<void>;
  /** Removes a file; nothing where it is not there. */
  readonly remove: (path: string) => Promise<void>;
  /** Whether a file or a folder is there. */
  readonly exists: (path: string) => Promise<boolean>;
  /** The names in a folder, files and folders, sorted; none where it is not there. */
  readonly list: (dir: string) => Promise<readonly string[]>;
  /** Every file under a folder, as paths from the folder, sorted, leaving out `node_modules`; none where it is not there. */
  readonly walk: (dir: string) => Promise<readonly string[]>;
  /** Makes a private folder outside the repository and gives its path. */
  readonly makeTemp: (prefix: string) => Promise<string>;
  /** Removes a folder and what is in it. */
  readonly removeTree: (path: string) => Promise<void>;
};

The port of files. Paths are absolute; a folder's entries are names.

logical.NpmViewtypeno test imports it
type NpmView = { readonly latest: string | undefined; readonly versions: readonly string[] };

What npm shows of a package.

logical.Registrytypeno test imports it
type Registry = { readonly view: (name: string) => Promise<Result<NpmView | "absent", string>> };

The port of the registry of npm: what it shows of a package, or absent where it has none, or why it could not be asked.

logical.Credentialstypeno test imports it
type Credentials = { readonly npmToken: () => Secret | undefined };

The port of credentials: the token for npm is held by whoever publishes and is read from where the host keeps it, never from a verb's own options.

logical.LibraryInfotypeno test imports it
type LibraryInfo = { readonly name: string; /** The package it publishes: its scope and name, or the one its manifes… (627 characters)
type LibraryInfo = {
  readonly name: string;
  /** The package it publishes: its scope and name, or the one its manifest names in `publishes`. */
  readonly package: string;
  /** Its folder from the repository's root. */
  readonly folder: string;
  readonly version: string;
  readonly level: string;
  /** Its spec kit from its folder, where it has one. */
  readonly specKit: string | undefined;
  readonly npm: boolean;
  /** Why the library is held out of the release, where it is: it has no tag, no registry and no set. */
  readonly held: string | undefined;
  readonly versionConstants: readonly VersionConstant[];
};

What a library says of itself, read from its manifest.

logical.Librariestypeno test imports it
type Libraries = { readonly list: () => Promise<Result<readonly LibraryInfo[], string>> };

The port of the manifests: every library of the repository, or why they cannot be read.

logical.Worldtypeno test imports it
type World = {
  /** The absolute path of the repository's root. */
  readonly repo: string;
  readonly process: Process;
  readonly files: Files;
  readonly registry: Registry;
  readonly credentials: Credentials;
  readonly libraries: Libraries;
  /** The documentation generator, loaded from the repository's own dependencies. */
  readonly docs: DocsPort;
};

The world a verb runs in: the repository's root and every port.

Runtypeno test imports it
type Run = { readonly code: number; readonly stdout: string; readonly stderr: string };

How a program ended, with its output as text.

RunOptionstypeno test imports it
type RunOptions = { readonly cwd?: string; readonly env?: Readonly<Record<string, string>> };

How to run a program: where, and with which variables added to its environment.

Processtype
type Process = { readonly run: (argv: readonly string[], options?: RunOptions) => Promise<Run> };

The port that runs a program by its argument vector, with no shell between.

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

Filestypeno test imports it
type Files = { /** The text of a file, or undefined where it is not there. */ readonly read: (path: string) => Promi… (1084 characters)
type Files = {
  /** The text of a file, or undefined where it is not there. */
  readonly read: (path: string) => Promise<string | undefined>;
  /** Writes a text (making the folder), with the mode where one is given. */
  readonly write: (path: string, text: string, mode?: number) => Promise<void>;
  /** Removes a file; nothing where it is not there. */
  readonly remove: (path: string) => Promise<void>;
  /** Whether a file or a folder is there. */
  readonly exists: (path: string) => Promise<boolean>;
  /** The names in a folder, files and folders, sorted; none where it is not there. */
  readonly list: (dir: string) => Promise<readonly string[]>;
  /** Every file under a folder, as paths from the folder, sorted, leaving out `node_modules`; none where it is not there. */
  readonly walk: (dir: string) => Promise<readonly string[]>;
  /** Makes a private folder outside the repository and gives its path. */
  readonly makeTemp: (prefix: string) => Promise<string>;
  /** Removes a folder and what is in it. */
  readonly removeTree: (path: string) => Promise<void>;
};

The port of files. Paths are absolute; a folder's entries are names.

NpmViewtypeno test imports it
type NpmView = { readonly latest: string | undefined; readonly versions: readonly string[] };

What npm shows of a package.

Registrytype
type Registry = { readonly view: (name: string) => Promise<Result<NpmView | "absent", string>> };

The port of the registry of npm: what it shows of a package, or absent where it has none, or why it could not be asked.

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

Credentialstypeno test imports it
type Credentials = { readonly npmToken: () => Secret | undefined };

The port of credentials: the token for npm is held by whoever publishes and is read from where the host keeps it, never from a verb's own options.

LibraryInfotype
type LibraryInfo = { readonly name: string; /** The package it publishes: its scope and name, or the one its manifes… (627 characters)
type LibraryInfo = {
  readonly name: string;
  /** The package it publishes: its scope and name, or the one its manifest names in `publishes`. */
  readonly package: string;
  /** Its folder from the repository's root. */
  readonly folder: string;
  readonly version: string;
  readonly level: string;
  /** Its spec kit from its folder, where it has one. */
  readonly specKit: string | undefined;
  readonly npm: boolean;
  /** Why the library is held out of the release, where it is: it has no tag, no registry and no set. */
  readonly held: string | undefined;
  readonly versionConstants: readonly VersionConstant[];
};

What a library says of itself, read from its manifest.

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

Librariestypeno test imports it
type Libraries = { readonly list: () => Promise<Result<readonly LibraryInfo[], string>> };

The port of the manifests: every library of the repository, or why they cannot be read.

Worldtype
type World = {
  /** The absolute path of the repository's root. */
  readonly repo: string;
  readonly process: Process;
  readonly files: Files;
  readonly registry: Registry;
  readonly credentials: Credentials;
  readonly libraries: Libraries;
  /** The documentation generator, loaded from the repository's own dependencies. */
  readonly docs: DocsPort;
};

The world a verb runs in: the repository's root and every port.

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

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