IF Commons GitHub

releasing

The release (commons 0001-libraries FR-013 to FR-015, 0026-works-versioning FR-022): versions grow here, at the release, and not on every push. One command plans what a release does and makes it, and writes the record that the one release workflow reads.

bun commons/libraries/src/releasing.ts plan what a release would do, from the tags and the working tree; writes nothing (the default command) bun commons/libraries/src/releasing.ts apply raise the versions the plan says, refresh the lockfile of each library released, make the generated files once and synchronize them, run the tests that pack, install and type-check every library, write the record bun commons/libraries/src/releasing.ts matrix --github-output F what the release workflow builds and publishes, from the record, leaving out what is tagged (written as the outputs of a step) other flags: --repo DIR, and for apply --no-tests (leave out the tests that pack: for trying the command, never for a release)

A library is released unless its manifest carries a typed held reason not to (tests-only, unfinished, owner-blocked); plan names each such library and its reason. A library is released at the version its manifest has, and its version is raised here and nowhere else: a library whose files changed since its last tag (its folder, and the paths its record adds) is raised by the greater of the Impact: of the commits since that tag (a patch where none states one) and the floor of its exports (a key removed or renamed since the version npm holds is breaking, a key added a feature; a breaking change raises the minor while the major version is 0), and a library that imports a library that is raised is raised by at least a patch, and so on up the imports. A library whose version is not tagged yet is released as it is, whatever the tags say of earlier versions: a library that has never been tagged (the first release of it, or a backlog that was never tagged), or whose manifest is ahead of its last tag (a version raised by hand). A library whose version is tagged and whose files did not change is left alone. The order of the release is the order of the imports, a library after the libraries it imports. The record, commons/generated/release.auto.json, lists what the release workflow publishes and tags, in that order; it says nothing of a day or a person, so the same state gives the same bytes. Nothing here publishes, tags or commits: the workflow publishes and tags, and a person commits what apply made.

import { planRelease } from "./release.ts";
// a library whose version is tagged and whose files changed is raised; one that imports it is raised by a patch

Spec: 0001-libraries FR-013

Source: commons/libraries/src/releasing.ts

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

RECORD_PATHconst
const RECORD_PATH: "commons/generated/release.auto.json"

The record of the release, from the repository's root.

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

ExportsChangetypeno test imports it
type ExportsChange = { readonly removed: readonly string[]; readonly added: readonly string[] };

The keys of exports a library lost and gained against the version npm holds.

Floortypeno test imports it
type Floor = { readonly impact: Impact; readonly reason: string };

The least impact the keys of exports alone ask for, and why (0001-libraries FR-027): a key removed or renamed is breaking (major), a key added is a feature (minor).

floorOffunction
function floorOf(change: ExportsChange | undefined): Floor | undefined

The floor of a change of exports: none where no key was removed or added. Types, signatures and behaviour behind an unchanged key are not seen.

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

exportsChangeOffunction
function exportsChangeOf(published: readonly string[], local: readonly string[]): ExportsChange

The change of the keys of exports from the keys npm holds to the library's, each list sorted.

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

appliedImpactfunction
function appliedImpact(version: string, impact: "major" | "minor" | "patch"): "major" | "minor" | "patch"

The impact that raises a version: while the major version is 0 the first number never changes by a release (SemVer 2.0.0 item 4: major version zero is for initial development and anything may change), so a breaking change (major) raises the minor, and a feature (minor) raises the minor too; from 1.0.0 the impact is as stated (0026-works-versioning FR-041).

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

Drifttypeno test imports it
type Drift = "absent" | "same" | "differs" | "unknown";

What npm holds of a version, against the files of the library: not there, there and the same, there and different, or not known (offline, or the registry did not say).

Whytypeno test imports it
type Why = "changed" | "differs-from-npm" | "changed-since-version" | "manual";

Why a library is raised.

Decisiontypeno test imports it
type Decision =
  | { readonly kind: "unchanged" }
  | { readonly kind: "as-is"; readonly why: "no-tag" | "ahead-of-tag"; readonly npm: Drift }
  | { readonly kind: "raised"; readonly to: string; readonly impact: Impact; readonly why: Why; readonly floor: Floor | undefined }
  | { readonly kind: "dependent"; readonly to: string; readonly because: readonly Slug[] };

What the release does to one library.

Steptypeno test imports it
type Step = {
  readonly slug: Slug;
  readonly folder: string;
  readonly package: string;
  readonly from: string;
  readonly to: string;
  readonly tag: string;
  readonly publish: boolean;
  readonly registries?: readonly PublishTarget[];
  readonly decision: Exclude<Decision, { readonly kind: "unchanged" }>;
};

One step of a release: a library, its version before and after, and what is done to it.

HeldLibrarytypeno test imports it
type HeldLibrary = { readonly name: string; readonly hold: Hold };

A library that is not released, and the typed reason (0001-libraries FR-024).

Plantypeno test imports it
type Plan = { readonly steps: readonly Step[]; readonly unchanged: readonly Slug[]; readonly held: readonly HeldLibrary[] };

The plan: every step in the order of the imports, the libraries that are left alone, and the libraries that are not released with their reasons.

describefunctionno test imports it
function describe(d: Decision, from: string): string

The text of a decision, in a sentence.

planReleasefunction
function planRelease(facts: readonly Facts[], raise?: ReadonlyMap<string, "major" | "minor" | "patch" | undefined>, held?: readonly HeldLibrary[]): Result<Plan, string>

The plan of a release from the facts of the libraries (FR-013): a library with no tag, or ahead of its last tag, is released as it is; one that is tagged at its version and changed is raised by its impact; one that is tagged, unchanged and imports a library that is raised, directly or through another, is raised by a patch; the rest are left alone. A library whose version is below its last tag is an error, and so is a cycle of imports.

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

recordTextfunction
function recordText(plan: Plan): string

The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order.

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

sendsToconstno test imports it
const sendsTo: (e: Entry, target: "github" | "npm") => boolean

Whether a release sends an entry to a registry: an entry names its registries, and one that names none goes to both.

readRecordfunction
function readRecord(text: string): Result<readonly Entry[], string>

The entries of a record's text, or why it is not one.

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

matrixOutputsfunction
function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string

What the workflow builds and publishes: the entries whose tag is not there yet, as the cells of a matrix and the sequence to publish in, as the outputs of a step.

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

writeVersionfunction
function writeVersion(repo: string, step: Step): Result<readonly string[], string>

Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not.

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

writeConstantfunctionno test imports it
function writeConstant(repo: string, step: Step, c: VersionConstant): Result<string, string>

Writes the new version into a constant of the library's sources that holds it (export const NAME = "1.2.3"); the file's path from the root, or the problem where the file or the constant is not there.

Tarballtypeno test imports it
type Tarball = { readonly hashes: ReadonlyMap<string, string>; readonly packageJson: string };

What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder package/), and the text of its package.json.

tarballOffunction
function tarballOf(gz: Uint8Array<ArrayBufferLike>): Tarball

The files of a gzipped tar, as a registry serves it: each regular file's path and SHA-256. A header it cannot read ends the list there.

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

driftOffunction
function driftOf(published: Tarball, local: { readonly hash: (path: string) => string | undefined; readonly packageJson: string; }): "differs" | "same"

Whether the files of a library are those of the version npm holds (FR-013): the sources the package carries (src/, each by its SHA-256 against the library's own file) and the keys of its exports (the packer rewrites the rest of package.json, and the compiled files are the compiler's). A source that is missing here, or other, or an entry of exports that was added or removed, is a difference.

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

realRegistryfunctionno test imports it
function realRegistry(repo: string): Registry

The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under repo; anything that goes wrong is unknown, never a guess.

driftOfSinglefunctionno test imports it
function driftOfSingle(published: Tarball, local: { readonly source: (path: string) => string | undefined; readonly keys: readonly string[]; }): "differs" | "same"

Whether the files of the one package are those of the version npm holds (0036-distribution FR-027): the sources it carries (each .ts file by its SHA-256 against the library's own file with its specifiers written as the package's) and the keys of its exports. A source that is missing here, or other, or a key that was added or removed, is a difference.

RegistryAttypeno test imports it
type RegistryAt = { readonly base: string; readonly token: string };

The registry that holds the one package: its address and the token that may read it (none for npm, the token of the environment for the GitHub package registry).

registryAtfunctionno test imports it
function registryAt(targets?: readonly ("github" | "npm")[]): RegistryAt

The registry the one package is sent to first: npm where SINGLE_TARGETS has it, the GitHub package registry otherwise, read with GITHUB_TOKEN, GH_TOKEN or NODE_AUTH_TOKEN where the environment has one (without one the registry cannot be asked, which is unknown).

realRegistrySinglefunctionno test imports it
function realRegistrySingle(repo: string, registry?: RegistryAt): Registry

The registry of npm for the one package: the metadata of the version, its tarball, and the sources of every library under repo; anything that goes wrong is unknown, never a guess.

PublishedExportstypeno test imports it
type PublishedExports = (pkg: string, version: string) => Promise<readonly string[] | undefined>;

The keys of exports of a version npm holds, or undefined where it cannot be read (not there, offline, no answer): never a guess.

realPublishedExportsfunction
function realPublishedExports(base?: string, token?: string): PublishedExports

The registry of npm (or the one at base, for a test's own server) asked for the manifest of a version, whose exports keys are those the package was published with.

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

offlinePublishedExportsconst
const offlinePublishedExports: PublishedExports

The registry that is not asked for exports (--offline).

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

exportKeysfunctionno test imports it
function exportKeys(packageJson: string): readonly string[]

The keys of the exports of a package.json's text.

heldLibrariesfunctionno test imports it
function heldLibraries(repo: string): readonly HeldLibrary[]

The libraries that are not released, each with its typed reason, in the order of their names (0001-libraries FR-024).

releasePlanfunction
function releasePlan(repo: string, options?: { readonly raise?: ReadonlyMap<string, "major" | "minor" | "patch" | undefined> | undefined; readonly registry?: Registry | undefined; readonly published?: PublishedExports | undefined; readonly mode?: "per-library" | "single" | undefined; }): Promise<Result<Plan, string>>

The plan of a repository: the facts of the libraries that are released, the libraries that are held, and the rules of the plan.

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

singleFactsOffunctionno test imports it
function singleFactsOf(repo: string, registry?: Registry, published?: PublishedExports): Promise<Result<Facts, string>>

What the host gives the plan of single mode: the facts of the one package, from the tags commons-v<version> and the tree. The package changed where a file of any library it holds changed since its last tag, and the impact is the greatest of the Impact: of the commits that touched any of them (a patch where none states one); the floor of its keys of exports is read against the version npm holds.

GENERATORSconst
const GENERATORS: readonly (readonly string[])[]

The commands that make the generated files, in the order they are made: the section of the libraries first, the register last. Each is run once, by apply.

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

PACKAGE_TESTSconstno test imports it
const PACKAGE_TESTS: readonly string[]

The tests that pack every library, install it into a consumer and type-check against it (the heavy proof a release of per-library mode asks for and a push does not).

SINGLE_PACKAGE_TESTSconstno test imports it
const SINGLE_PACKAGE_TESTS: readonly string[]

The test that packs the one package, installs it with npm and with Bun, imports every entry of every library on Node and on Bun and type-checks a consumer (the proof a release of single mode asks for).

testsOfconstno test imports it
const testsOf: (mode: "per-library" | "single") => readonly string[]

The tests a release of a mode runs: the mode that is not active is proved on demand with IFC_DISTRIBUTION.

Hosttype
type Host = { /** Refreshes the lockfile of the library in `folder` (from the root of the repository): an install that… (547 characters)
type Host = {
  /** Refreshes the lockfile of the library in `folder` (from the root of the repository): an install that may change it. */
  readonly lock: (repo: string, folder: string) => Promise<Result<void, string>>;
  readonly generate: (repo: string, command: readonly string[]) => Promise<Result<void, string>>;
  /** Makes every generated file of the repository, in dependency order (`repoctl sync`). */
  readonly sync: (repo: string) => Promise<Result<void, string>>;
  readonly prove: (repo: string) => Promise<Result<void, string>>;
};

What apply runs besides the planner: the refresh of a lockfile, the generators, the synchronization of every generated file and the tests, which a test of this module replaces.

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

REALconst
const REAL: Host

The real host: each command run with Bun from the repository's root.

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

Appliedtypeno test imports it
type Applied = { readonly plan: Plan; readonly written: readonly string[] };

What apply did: the files written, in order.

applyReleasefunction
function applyRelease(repo: string, host: Host, options: { readonly tests: boolean; readonly raise?: ReadonlyMap<string, "major" | "minor" | "patch" | undefined> | undefined; readonly registry?: Registry | undefined; readonly published?: PublishedExports | undefined; readonly mode?: "per-library" | "single" | undefined; }): Promise<Result<Applied, string>>

Makes the release (FR-014), in this order: the versions of the plan are written, the lockfile of every library the plan releases is refreshed (an install that may change it), the generated files are made once and then synchronized, the tests that pack run unless asked not to, and the record is written. The lockfiles are refreshed before the tests because those install each library from its lockfile and refuse a stale one.

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

planLinesfunction
function planLines(look: Look, plan: Plan): readonly string[]

The lines the plan prints: one for each library that is released, and the libraries left alone.

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

Toolstype
type Tools = { /** Whether the version is on npm (asked again after a pause where it is not, because a version put the… (696 characters)
type Tools = {
  /** Whether the version is on npm (asked again after a pause where it is not, because a version put there by hand may take a while to show). */
  readonly onNpm: (name: string, version: string) => Promise<boolean>;
  /** Sends the package to npm; the reason where it cannot (no trusted publisher and no token, or npm refused). */
  readonly npm: (e: Entry) => Promise<Result<void, string>>;
  /** Sends the package to the GitHub package registry, unless it is there. */
  readonly github: (e: Entry) => Promise<Result<void, string>>;
  /** Makes the tag at the commit that runs, or finds it there. */
  readonly tag: (tag: string) => Promise<Result<"made" | "there", string>>;
};

What the publication needs from the world, so that its order and its rules are a pure function of what these say.

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

publishAllfunction
function publishAll(entries: readonly Entry[], tools: Tools): Promise<readonly Outcome[]>

Publishes and tags the releases in order (FR-015), each by itself: a version that is on npm is not sent again and is tagged; one that is not is sent, and where nothing can send it (no trusted publisher, no token) it is reported and its tag withheld, and the others go on; a release that is only tagged (a library that names no npm) is tagged. A tag that is there is kept. The failures are in the outcomes, never thrown.

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

outcomeLinesfunction
function outcomeLines(outcomes: readonly Outcome[]): { readonly lines: readonly string[]; readonly failed: boolean; }

The lines that say how each release went, and whether the run is a failure: one failure anywhere fails it, after every release was tried.

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

realToolsfunctionno test imports it
function realTools(dir: string): Tools

The tools of a run of the release workflow: npm and the GitHub CLI, the tarballs under dir (one folder for each library, package-<slug>), and the environment's credentials.

raiseOffunction
function raiseOf(words: readonly string[]): Result<ReadonlyMap<string, "major" | "minor" | "patch" | undefined>, string>

What --raise says: each library by its name, with the impact after an = where one is given.

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

offlineRegistryconst
const offlineRegistry: Registry

The registry that is not asked (--offline).

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

registryOfconstno test imports it
const registryOf: (mode: "per-library" | "single", repo: string) => Registry

The registry that is asked: npm for the files of the library, or for those of the one package.

publishedOfconstno test imports it
const publishedOf: (mode: "per-library" | "single") => PublishedExports

The registry whose exports keys the floor reads.

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