@wtf/release-docs 9.1.0 → 10.0.0

package/api/@wtf/release/README.md

@@ -0,0 +1,55 @@
+[**Release trains**](../../README.md)
+
+***
+
+[Release trains](../../README.md) / @wtf/release
+
+# @wtf/release
+
+What a release runs by, of no release tool and of no train: the platform its caller gives it, a
+`Pick` of `@wtf/platform`, and the folder of the repo, `root`, a handle of the File System
+standard (`@wtf/platform-fs-node`'s on disk, `@wtf/platform-fs-memory`'s in memory, a
+browser's). A library names no Node: it reaches the runtime by these alone. Each function takes
+only what it uses:
+
+- reading the files of the repo takes `root` alone;
+- running git and the other programs of the repo takes a [RepoPlatform](type-aliases/RepoPlatform.md), whose working
+  folder, `dirs.cwd`, is the folder of the repo, the one `root` is the handle of;
+- a release that fetches and stages files outside the repo takes a [ReleasePlatform](type-aliases/ReleasePlatform.md).
+
+The code is at the subpaths:
+
+- `./files`: the files of a folder, by their paths from it;
+- `./process`: a program run in the folder of the repo, to its end;
+- `./posix`: paths as POSIX writes them;
+- `./paths`: whether a file is of a set of paths and globs, and a path as they are compared;
+- `./git`: git of a repo, its tracked files, the files of each commit, and the commits since a
+  ref;
+- `./ecosystem`: what an ecosystem is, the packages of one kind of manifest of the repo, and the
+  ecosystems a config names, loaded;
+- `./order`: the order to publish the packages of an ecosystem in;
+- `./generated`: the folders a build generates, listed by the build and staged for the release
+  commit;
+- `./forge`: forges, and the link of each package of a release from the release of its tag;
+- `./contract`: the contract of a release, what a driver gives an ecosystem, what a release is
+  of, and the steps an ecosystem implements;
+- `./driver`: a step of every ecosystem of a release, over its plan;
+- `./validator`: validators of options, each a Standard Schema and a Standard JSON Schema, and the
+  errors of their issues;
+- `./errors`: `ReleaseError`, of a stable code and details of how to fix it, which the errors of
+  every package over this one extend.
+
+```ts
+import type { RepoContext } from '@wtf/release'
+
+export const folderOf = ({ platform }: RepoContext): string => platform.dirs.cwd
+```
+
+## Interfaces
+
+- [RepoContext](interfaces/RepoContext.md)
+
+## Type Aliases
+
+- [ReleasePlatform](type-aliases/ReleasePlatform.md)
+- [RepoPlatform](type-aliases/RepoPlatform.md)

package/api/@wtf/release/contract/README.md

@@ -0,0 +1,60 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release/contract
+
+# @wtf/release/contract
+
+The contract of a release: what a driver gives an ecosystem ([Release](interfaces/Release.md)), what a release is
+of ([Plan](interfaces/Plan.md)), what an ecosystem that releases does in each step of it
+([ReleasingEcosystem](type-aliases/ReleasingEcosystem.md)), and what it published ([Released](../forge/interfaces/Released.md) of `./forge`). A driver is
+any caller: a plugin of a release tool, a CLI, a test. It works out the plan, by trains or of the
+whole repo, and runs the steps it is asked, each over every ecosystem, by `runStep` of
+`./driver`. An ecosystem knows its own manifests, registries and rules of versions, and no
+driver.
+
+| Step      | What the ecosystem does                                                     | Required |
+| --------- | --------------------------------------------------------------------------- | -------- |
+| `verify`  | checks its options, the version and the credentials, and writes nothing     | no       |
+| `prepare` | writes the versions into its manifests, and gives the files it wrote         | no       |
+| `smoke`   | tries what it will publish, as a package packed, installed and imported      | no       |
+| `publish` | publishes the packages, each the registry has already skipped               | yes      |
+| `move`    | points the moving names, as npm's dist-tags or OCI tags, at a version, and   | no       |
+|           | gives what it moved                                                         |          |
+
+A driver runs `verify` once the version of the release is known, as a release tool decides it,
+so an ecosystem checks the version by its own rules there, and never of a placeholder.
+
+```ts
+import type { ReleasingEcosystem } from '@wtf/release/contract'
+
+// An ecosystem whose packages publish nowhere, each said in the log.
+export const said: ReleasingEcosystem<{ prefix: string }> = {
+  name: 'said',
+  packages: async () => [],
+  resolve: (_range, version) => version,
+  satisfies: (range, version) => range === version,
+  async publish(release, plan, { prefix }) {
+    for (const { name } of plan.own) release.log(`${prefix}${name}@${release.version}`)
+    return plan.own.map(({ name }) => ({ ecosystem: 'said', name, version: release.version }))
+  }
+}
+```
+
+## Interfaces
+
+- [Plan](interfaces/Plan.md)
+- [Release](interfaces/Release.md)
+- [ReleaseSteps](interfaces/ReleaseSteps.md)
+
+## Type Aliases
+
+- [OptionalStep](type-aliases/OptionalStep.md)
+- [ReleasingEcosystem](type-aliases/ReleasingEcosystem.md)
+
+## References
+
+### Released
+
+Re-exports [Released](../forge/interfaces/Released.md)

package/api/@wtf/release/contract/interfaces/Plan.md

@@ -0,0 +1,46 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/contract](../README.md) / Plan
+
+# Interface: Plan\<P\>
+
+Defined in: [packages/release/src/contract.ts:80](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L80)
+
+What a release of one ecosystem is of, as its driver works it out: of a train, of the whole repo,
+or by hand.
+
+## Extended by
+
+- [`TrainPlan`](../../../release-trains/plan/interfaces/TrainPlan.md)
+- [`NpmPlan`](../../../release-npm/release/interfaces/NpmPlan.md)
+
+## Type Parameters
+
+### P
+
+`P` *extends* [`Package`](../../ecosystem/interfaces/Package.md) = [`Package`](../../ecosystem/interfaces/Package.md)
+
+A package, as the ecosystem gives it, or one of more of its own.
+
+## Properties
+
+### own
+
+> `readonly` **own**: readonly `P`[]
+
+Defined in: [packages/release/src/contract.ts:82](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L82)
+
+The packages the release publishes, in the order to publish them in.
+
+***
+
+### versions
+
+> `readonly` **versions**: `ReadonlyMap`\<`string`, `string`\>
+
+Defined in: [packages/release/src/contract.ts:87](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L87)
+
+The version of each package of the repo of the ecosystem, by its name: the release's of each
+of `own`, the last release of its own of each other, which a range of it is written of.

package/api/@wtf/release/contract/interfaces/Release.md

@@ -0,0 +1,96 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/contract](../README.md) / Release
+
+# Interface: Release
+
+Defined in: [packages/release/src/contract.ts:50](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L50)
+
+A release, as a driver gives it to each ecosystem: plain values, of no release tool and no train.
+
+## Properties
+
+### dryRun
+
+> `readonly` **dryRun**: `boolean`
+
+Defined in: [packages/release/src/contract.ts:58](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L58)
+
+Whether the release only says what it would do, and writes and publishes nothing.
+
+***
+
+### log
+
+> `readonly` **log**: (`line`) => `void`
+
+Defined in: [packages/release/src/contract.ts:64](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L64)
+
+Where each line of what a step does goes.
+
+#### Parameters
+
+##### line
+
+`string`
+
+The line, of no newline.
+
+#### Returns
+
+`void`
+
+***
+
+### platform
+
+> `readonly` **platform**: [`ReleasePlatform`](../../type-aliases/ReleasePlatform.md)
+
+Defined in: [packages/release/src/contract.ts:56](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L56)
+
+The platform, of the folder of the repo as its working folder.
+
+***
+
+### root
+
+> `readonly` **root**: `FileSystemDirectoryHandle`
+
+Defined in: [packages/release/src/contract.ts:54](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L54)
+
+The folder of the repo, a handle of the File System standard.
+
+***
+
+### version
+
+> `readonly` **version**: `string`
+
+Defined in: [packages/release/src/contract.ts:52](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L52)
+
+The version of the packages, as each ecosystem checks it by its own rules.
+
+***
+
+### warn
+
+> `readonly` **warn**: (`line`) => `void`
+
+Defined in: [packages/release/src/contract.ts:71](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L71)
+
+Where each line of a warning goes: of what the release goes on without, as a credential a dry
+run needs none of.
+
+#### Parameters
+
+##### line
+
+`string`
+
+The line, of no newline.
+
+#### Returns
+
+`void`

package/api/@wtf/release/contract/interfaces/ReleaseSteps.md

@@ -0,0 +1,203 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/contract](../README.md) / ReleaseSteps
+
+# Interface: ReleaseSteps\<O, P\>
+
+Defined in: [packages/release/src/contract.ts:100](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L100)
+
+The steps of a release, each over the plan of the ecosystem, of its options: what a
+[ReleasingEcosystem](../type-aliases/ReleasingEcosystem.md) has of them, `publish` always.
+
+## Type Parameters
+
+### O
+
+`O` = `unknown`
+
+Its options, its own, as npm's dist-tags or a registry.
+
+### P
+
+`P` *extends* [`Package`](../../ecosystem/interfaces/Package.md) = [`Package`](../../ecosystem/interfaces/Package.md)
+
+Its packages, as it gives them.
+
+## Methods
+
+### move()
+
+> **move**(`release`, `plan`, `options`): `Promise`\<readonly [`Released`](../../forge/interfaces/Released.md)[]\>
+
+Defined in: [packages/release/src/contract.ts:144](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L144)
+
+Points the moving names, as npm's dist-tags or OCI tags, at the version of the release.
+
+#### Parameters
+
+##### release
+
+[`Release`](Release.md)
+
+The release.
+
+##### plan
+
+[`Plan`](Plan.md)\<`P`\>
+
+What the release of the ecosystem is of.
+
+##### options
+
+`O`
+
+Its options.
+
+#### Returns
+
+`Promise`\<readonly [`Released`](../../forge/interfaces/Released.md)[]\>
+
+Each package it moved, or found moved, at the version of the release.
+
+***
+
+### prepare()
+
+> **prepare**(`release`, `plan`, `options`): `Promise`\<readonly `string`[]\>
+
+Defined in: [packages/release/src/contract.ts:117](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L117)
+
+Writes the versions into the manifests.
+
+#### Parameters
+
+##### release
+
+[`Release`](Release.md)
+
+The release.
+
+##### plan
+
+[`Plan`](Plan.md)\<`P`\>
+
+What the release of the ecosystem is of.
+
+##### options
+
+`O`
+
+Its options.
+
+#### Returns
+
+`Promise`\<readonly `string`[]\>
+
+The files it wrote, from the root of the repo, which the commit of the release holds.
+
+***
+
+### publish()
+
+> **publish**(`release`, `plan`, `options`): `Promise`\<readonly [`Released`](../../forge/interfaces/Released.md)[]\>
+
+Defined in: [packages/release/src/contract.ts:135](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L135)
+
+Publishes the packages; one the registry has already is skipped, so a retry finishes.
+
+#### Parameters
+
+##### release
+
+[`Release`](Release.md)
+
+The release.
+
+##### plan
+
+[`Plan`](Plan.md)\<`P`\>
+
+What the release of the ecosystem is of.
+
+##### options
+
+`O`
+
+Its options.
+
+#### Returns
+
+`Promise`\<readonly [`Released`](../../forge/interfaces/Released.md)[]\>
+
+What it published, or found published, and where.
+
+***
+
+### smoke()
+
+> **smoke**(`release`, `plan`, `options`): `Promise`\<`void`\>
+
+Defined in: [packages/release/src/contract.ts:126](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L126)
+
+Tries what it will publish, before it is published, as a package packed, installed and
+imported, or an image that is in the registry.
+
+#### Parameters
+
+##### release
+
+[`Release`](Release.md)
+
+The release.
+
+##### plan
+
+[`Plan`](Plan.md)\<`P`\>
+
+What the release of the ecosystem is of.
+
+##### options
+
+`O`
+
+Its options.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### verify()
+
+> **verify**(`release`, `plan`, `options`): `Promise`\<`void`\>
+
+Defined in: [packages/release/src/contract.ts:108](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L108)
+
+Checks the options, the version and the credentials, before anything is written.
+
+#### Parameters
+
+##### release
+
+[`Release`](Release.md)
+
+The release.
+
+##### plan
+
+[`Plan`](Plan.md)\<`P`\>
+
+What the release of the ecosystem is of.
+
+##### options
+
+`O`
+
+Its options.
+
+#### Returns
+
+`Promise`\<`void`\>

package/api/@wtf/release/contract/type-aliases/OptionalStep.md

@@ -0,0 +1,13 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/contract](../README.md) / OptionalStep
+
+# Type Alias: OptionalStep
+
+> **OptionalStep** = `"verify"` \| `"prepare"` \| `"smoke"` \| `"move"`
+
+Defined in: [packages/release/src/contract.ts:91](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L91)
+
+A step of the contract that an ecosystem may leave out: each but `publish`.

package/api/@wtf/release/contract/type-aliases/ReleasingEcosystem.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/contract](../README.md) / ReleasingEcosystem
+
+# Type Alias: ReleasingEcosystem\<O, P, S\>
+
+> **ReleasingEcosystem**\<`O`, `P`, `S`\> = [`Ecosystem`](../../ecosystem/interfaces/Ecosystem.md)\<`P`\> & `Pick`\<[`ReleaseSteps`](../interfaces/ReleaseSteps.md)\<`O`, `P`\>, `"publish"` \| `S`\> & `Partial`\<`Pick`\<[`ReleaseSteps`](../interfaces/ReleaseSteps.md)\<`O`, `P`\>, `Exclude`\<[`OptionalStep`](OptionalStep.md), `S`\>\>\>
+
+Defined in: [packages/release/src/contract.ts:165](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/contract.ts#L165)
+
+An ecosystem that releases: the read side of `./ecosystem`, of its packages, and the steps of a
+release ([ReleaseSteps](../interfaces/ReleaseSteps.md)), each over its plan. Each step but `publish` is optional, and a
+driver skips one an ecosystem has not; the steps of `S` it has, so its type holds them, and a
+caller calls each of them as it is, of no check.
+
+```ts
+import type { ReleasingEcosystem } from '@wtf/release/contract'
+import type { Package } from '@wtf/release/ecosystem'
+
+declare const images: ReleasingEcosystem<{ moving: readonly string[] }, Package, 'verify' | 'move'>
+export const verify = images.verify // there, of its type
+```
+
+## Type Parameters
+
+### O
+
+`O` = `unknown`
+
+Its options, its own, as npm's dist-tags or a registry.
+
+### P
+
+`P` *extends* [`Package`](../../ecosystem/interfaces/Package.md) = [`Package`](../../ecosystem/interfaces/Package.md)
+
+Its packages, as it gives them.
+
+### S
+
+`S` *extends* [`OptionalStep`](OptionalStep.md) = `never`
+
+The optional steps it has: none by default, each then maybe there.

package/api/@wtf/release/driver/README.md

@@ -0,0 +1,43 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release/driver
+
+# @wtf/release/driver
+
+The driver of a release: [runStep](functions/runStep.md) runs one step of the contract of `./contract` over the
+ecosystems of a release, in the order given, each over its plan. It knows no train and no release
+tool: its caller works out the plans and decides which steps a run has, as one run that verifies,
+prepares and tags, and another of the tag that publishes.
+
+```ts
+import type { Plan, Release, ReleasingEcosystem } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+
+declare const release: Release
+declare const npm: ReleasingEcosystem<{ moving: readonly [string, ...string[]] }>
+declare const plan: Plan
+
+const plans = new Map([['npm', plan]])
+const ecosystems = [[npm, { moving: ['latest'] }]] as const
+await runStep(release, plans, ecosystems, 'verify')
+const { released } = await runStep(release, plans, ecosystems, 'publish')
+```
+
+## Interfaces
+
+- [StepOutcome](interfaces/StepOutcome.md)
+
+## Type Aliases
+
+- [EcosystemsOf](type-aliases/EcosystemsOf.md)
+- [Step](type-aliases/Step.md)
+
+## Variables
+
+- [STEPS](variables/STEPS.md)
+
+## Functions
+
+- [runStep](functions/runStep.md)

package/api/@wtf/release/driver/functions/runStep.md

@@ -0,0 +1,50 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/driver](../README.md) / runStep
+
+# Function: runStep()
+
+> **runStep**(`release`, `plans`, `ecosystems`, `step`): `Promise`\<[`StepOutcome`](../interfaces/StepOutcome.md)\>
+
+Defined in: [packages/release/src/driver.ts:68](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L68)
+
+Runs `step` of each ecosystem of `ecosystems`, in their order, over its plan, the plan of its name
+in `plans`. An ecosystem of no plan, or of a plan of no package, is skipped, and so is one that
+has not the step, each said in the log. `verify` runs every ecosystem, and throws what each threw
+together; any other step stops at the first ecosystem that fails, which a retry finishes, as each
+step skips what it has done. It throws the errors as the ecosystems threw them: the one alone,
+several in an `AggregateError`.
+
+## Parameters
+
+### release
+
+[`Release`](../../contract/interfaces/Release.md)
+
+The release.
+
+### plans
+
+`ReadonlyMap`\<`string`, [`Plan`](../../contract/interfaces/Plan.md)\<[`Package`](../../ecosystem/interfaces/Package.md)\>\>
+
+The plan of each ecosystem, by its name.
+
+### ecosystems
+
+[`EcosystemsOf`](../type-aliases/EcosystemsOf.md)
+
+The ecosystems, in the order their steps run, each with its options.
+
+### step
+
+keyof [`ReleaseSteps`](../../contract/interfaces/ReleaseSteps.md)\<`unknown`, [`Package`](../../ecosystem/interfaces/Package.md)\>
+
+The step to run.
+
+## Returns
+
+`Promise`\<[`StepOutcome`](../interfaces/StepOutcome.md)\>
+
+What `publish` published or `move` moved, and the files `prepare` wrote.

package/api/@wtf/release/driver/interfaces/StepOutcome.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/driver](../README.md) / StepOutcome
+
+# Interface: StepOutcome
+
+Defined in: [packages/release/src/driver.ts:41](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L41)
+
+What a step gave, of every ecosystem.
+
+## Properties
+
+### files
+
+> `readonly` **files**: readonly `string`[]
+
+Defined in: [packages/release/src/driver.ts:47](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L47)
+
+The files `prepare` wrote, of each ecosystem in order, each once: none of another step.
+
+***
+
+### released
+
+> `readonly` **released**: readonly [`Released`](../../forge/interfaces/Released.md)[]
+
+Defined in: [packages/release/src/driver.ts:45](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L45)
+
+What `publish` published, or `move` moved, of each ecosystem in order: none of another step.

package/api/@wtf/release/driver/type-aliases/EcosystemsOf.md

@@ -0,0 +1,14 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/driver](../README.md) / EcosystemsOf
+
+# Type Alias: EcosystemsOf
+
+> **EcosystemsOf** = readonly (readonly \[[`ReleasingEcosystem`](../../contract/type-aliases/ReleasingEcosystem.md)\<`any`, `any`\>, `unknown`\])[]
+
+Defined in: [packages/release/src/driver.ts:38](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L38)
+
+The ecosystems of a release, in the order their steps run, each with its options: of a release
+tool, the order of its plugins.

package/api/@wtf/release/driver/type-aliases/Step.md

@@ -0,0 +1,13 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release/driver](../README.md) / Step
+
+# Type Alias: Step
+
+> **Step** = keyof [`ReleaseSteps`](../../contract/interfaces/ReleaseSteps.md)
+
+Defined in: [packages/release/src/driver.ts:28](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/driver.ts#L28)
+
+A step of the contract, in the order a release runs them.