IF Commons GitHub

governance/tool

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-toolchain-governance FR-002, 0002-toolchain-governance FR-003, 0002-toolchain-governance FR-004, 0002-toolchain-governance FR-005, 0002-toolchain-governance FR-006, 0002-toolchain-governance FR-008

A tool: a program a computer needs, declared once. It has a pin policy, what it provides and needs, the phase of work that first needs it, the scope it lives in and the bindings that say how a dialect obtains it: a reference to a pin of the packaging ontology (which holds the version and the checksums, so that a declaration never copies a version or a hash), or the names a package manager of the ontology knows. defineTool is the one way to make one, and it refuses with every reason what is not one. A download, as a pin gives it for a platform, is checked by defineDownload.

import { defineTool } from "./tool.ts";
const r = defineTool({
  name: "jq",
  summary: "A command line JSON processor.",
  pin: "exact",
  program: "jq",
  versionArgs: ["--version"],
  phases: ["core"],
  scope: "user",
  bindings: [{ kind: "pin", pin: "jq" }, { kind: "package", manager: "manager-brew", packages: ["jq"] }],
});
r.kind; // "ok"

Source: commons/toolchain/src/governance/tool.ts

7 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Platformtype
type Platform = "linux-x64" | "linux-arm64" | "macos-x64" | "macos-arm64" | "windows-x64";

A platform a pin can have a download for.

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

PLATFORMSconstno test imports it
const PLATFORMS: readonly Platform[]

Every platform.

Phasetypeno test imports it
type Phase = "core" | "dev" | "test" | "stage" | "publish";

The phase of work that first needs a tool.

PHASESconstno test imports it
const PHASES: readonly Phase[]

Every phase, from the first needed to the last.

Scopetypeno test imports it
type Scope = "user" | "system";

Where a tool lives: in a user's folder, or in the system's.

PinPolicytypeno test imports it
type PinPolicy = "exact" | "release-line" | "rolling";

How strictly a tool is pinned.

PIN_POLICIESconstno test imports it
const PIN_POLICIES: readonly PinPolicy[]

Every pin policy, from the least strict to the most.

ArtifactFormattypeno test imports it
type ArtifactFormat = "zip" | "tar" | "file";

The format of what a download address gives.

Downloadtype
type Download = {
  readonly version: Version;
  readonly downloadUrl: string;
  readonly sha256: Sha256;
  readonly archiveFormat: ArtifactFormat;
  readonly binPath: string;
};

What a pin gives for one platform: the version, the address, the SHA-256 of what is there, its format and the folder of its programs inside it.

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

Bindingtypeno test imports it
type Binding =
  | { readonly kind: "pin"; readonly pin: PinId }
  | { readonly kind: "package"; readonly manager: ManagerId; readonly packages: readonly string[]; readonly version?: Version };

How a dialect obtains a tool: the download a pin of the ontology gives, or the names of the packages a package manager of the ontology knows (at a version, where one is named).

Tooltype
type Tool = { readonly name: ToolName; readonly summary: string; readonly pin: PinPolicy; /** The least version … (942 characters)
type Tool = {
  readonly name: ToolName;
  readonly summary: string;
  readonly pin: PinPolicy;
  /** The least version of a copy found on the computer that may be taken. */
  readonly minimum?: Version;
  /** The program, or the file, whose presence proves it. */
  readonly program: string;
  /** How the program is asked its version; none where it cannot be asked. */
  readonly versionArgs: readonly string[];
  readonly needs: readonly ToolName[];
  /** The variables it sets for the programs that run it. */
  readonly env: Readonly<Record<string, string>>;
  /** The other programs it provides. */
  readonly provides: readonly string[];
  /** The other names a copy of its program may go by on a computer (Chromium is also `chrome` and `google-chrome`), tried after the program's own. */
  readonly alsoNamed: readonly string[];
  readonly phases: readonly Phase[];
  readonly scope: Scope;
  readonly bindings: readonly Binding[];
};

A tool. It holds no version and no hash of a pin: it references the pin.

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

DownloadInputtype
type DownloadInput = { readonly version: string; readonly downloadUrl: string; readonly sha256: string; readonly archiveFormat: string; readonly binPath: string };

A download as a source of pins gives it.

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

BindingInputtypeno test imports it
type BindingInput =
  | { readonly kind: "pin"; readonly pin: string }
  | { readonly kind: "package"; readonly manager: string; readonly packages: readonly string[]; readonly version?: string };

A binding as written.

ToolInputtype
type ToolInput = { readonly name: string; readonly summary: string; readonly pin: string; readonly minimum?: str… (480 characters)
type ToolInput = {
  readonly name: string;
  readonly summary: string;
  readonly pin: string;
  readonly minimum?: string;
  readonly program: string;
  readonly versionArgs: readonly string[];
  readonly needs?: readonly string[];
  readonly env?: Readonly<Record<string, string>>;
  readonly provides?: readonly string[];
  readonly alsoNamed?: readonly string[];
  readonly phases: readonly string[];
  readonly scope: string;
  readonly bindings: readonly BindingInput[];
};

What defineTool takes.

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

defineDownloadfunction
function defineDownload(input: DownloadInput): Result<Download, readonly string[]>

A download from what a source of pins gave, or every reason it is not one: an https address with no user name or password, a SHA-256, a format and a folder inside the unpacked folder.

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

defineToolfunction
function defineTool(input: ToolInput): Result<Tool, readonly string[]>

A tool, or every reason the input is not one.

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

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