@wtf/release-docs 9.0.2 → 10.0.0

package/api/@wtf/release-validate/validate/functions/validateConfig.md

@@ -8,7 +8,7 @@
 
 > **validateConfig**(`schema`, `config`): `Promise`\<[`ConfigIssue`](../../interfaces/ConfigIssue.md)[]\>
 
-Defined in: [packages/release-validate/src/validate.ts:80](https://gitlab.com/wetryfun/release/release/-/blob/3b0e2c3c91b521977d05b801e2297d0df9e52834/packages/release-validate/src/validate.ts#L80)
+Defined in: [packages/release-validate/src/validate.ts:80](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-validate/src/validate.ts#L80)
 
 The issues of `config` by `schema`, a Standard Schema, whose validation is sync or async: none
 of a config it finds valid. Throws `ESCHEMA` of a schema that is none.

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

@@ -0,0 +1,36 @@
+[**Release trains**](../../README.md)
+
+***
+
+[Release trains](../../README.md) / @wtf/semantic-release
+
+# @wtf/semantic-release
+
+What every plugin of semantic-release over the libraries of a release shares: [runOf](functions/runOf.md), the
+platform and the folder of a run, on Node, of the folder and the environment semantic-release
+gives a step; and [realPathOf](functions/realPathOf.md), the folder Node resolves the packages of a folder from. A
+library takes the platform and the folder it is given, and names no Node; a plugin makes them by
+this package, once a step. The mark semantic-release prints an error by is `./errors`', and the
+validator of a plugin's entries of a config `./schema`'s.
+
+```ts
+import { runOf } from '@wtf/semantic-release'
+import { trackedFiles } from '@wtf/release/git'
+
+export async function verifyConditions(
+  _options: unknown,
+  context: { cwd: string; env: Record<string, string | undefined> }
+) {
+  const { platform } = await runOf(context)
+  await trackedFiles({ platform })
+}
+```
+
+## Interfaces
+
+- [RunContext](interfaces/RunContext.md)
+
+## Functions
+
+- [realPathOf](functions/realPathOf.md)
+- [runOf](functions/runOf.md)

package/api/@wtf/semantic-release/errors/README.md

@@ -0,0 +1,32 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/semantic-release/errors
+
+# @wtf/semantic-release/errors
+
+The mark semantic-release prints an error of a plugin by: [marked](functions/marked.md) marks the errors of a
+release as they leave a step, and [markedStep](functions/markedStep.md) makes a step that marks each it throws. The
+libraries throw plain `ReleaseError`s of `@wtf/release/errors`, of a code, a message and details;
+semantic-release prints one of its `semanticRelease` mark by its code, its message and its
+details, and each of an `AggregateError` one by one, so a plugin marks them once, at the edge of
+each of its steps.
+
+```ts
+import { markedStep } from '@wtf/semantic-release/errors'
+import { ReleaseError } from '@wtf/release/errors'
+
+export const verifyConditions = markedStep(async () => {
+  throw new ReleaseError('EDEPLOY', 'It cannot deploy.', 'Give it a target.')
+})
+```
+
+## Variables
+
+- [SEMANTIC\_RELEASE\_ERROR](variables/SEMANTIC_RELEASE_ERROR.md)
+
+## Functions
+
+- [marked](functions/marked.md)
+- [markedStep](functions/markedStep.md)

package/api/@wtf/semantic-release/errors/functions/marked.md

@@ -0,0 +1,29 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/errors](../README.md) / marked
+
+# Function: marked()
+
+> **marked**(`error`): `unknown`
+
+Defined in: [packages/semantic-release/src/errors.ts:34](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/errors.ts#L34)
+
+`error`, of semantic-release's mark: a `ReleaseError` marked `semanticRelease` and named
+`SemanticReleaseError`, as semantic-release prints one, and each `ReleaseError` of an
+`AggregateError` so; any other error as it is.
+
+## Parameters
+
+### error
+
+`unknown`
+
+What a step threw.
+
+## Returns
+
+`unknown`
+
+The same error, marked where it is a release's.

package/api/@wtf/semantic-release/errors/functions/markedStep.md

@@ -0,0 +1,36 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/errors](../README.md) / markedStep
+
+# Function: markedStep()
+
+> **markedStep**\<`F`\>(`step`): `F`
+
+Defined in: [packages/semantic-release/src/errors.ts:56](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/errors.ts#L56)
+
+A step of a plugin that throws what `step` throws, marked ([marked](marked.md)): of the type of `step`
+itself, its parameters and what it gives as they are.
+
+## Type Parameters
+
+### F
+
+`F` *extends* (...`args`) => `Promise`\<`unknown`\>
+
+The step, as a plugin writes it: of its options and semantic-release's context.
+
+## Parameters
+
+### step
+
+`F`
+
+The step.
+
+## Returns
+
+`F`
+
+The step, of its errors marked.

package/api/@wtf/semantic-release/errors/variables/SEMANTIC_RELEASE_ERROR.md

@@ -0,0 +1,13 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/errors](../README.md) / SEMANTIC\_RELEASE\_ERROR
+
+# Variable: SEMANTIC\_RELEASE\_ERROR
+
+> `const` **SEMANTIC\_RELEASE\_ERROR**: `"SemanticReleaseError"` = `'SemanticReleaseError'`
+
+Defined in: [packages/semantic-release/src/errors.ts:24](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/errors.ts#L24)
+
+The name semantic-release gives an error of its mark.

package/api/@wtf/{release-system/node → semantic-release}/functions/realPathOf.md

@@ -1,14 +1,14 @@
-[**Release trains**](../../../../README.md)
+[**Release trains**](../../../README.md)
 
 ***
 
-[Release trains](../../../../README.md) / [@wtf/release-system/node](../README.md) / realPathOf
+[Release trains](../../../README.md) / [@wtf/semantic-release](../README.md) / realPathOf
 
 # Function: realPathOf()
 
 > **realPathOf**(`dir`): `string`
 
-Defined in: [packages/release-system/src/node.ts:142](https://gitlab.com/wetryfun/release/release/-/blob/3b0e2c3c91b521977d05b801e2297d0df9e52834/packages/release-system/src/node.ts#L142)
+Defined in: [packages/semantic-release/src/index.ts:74](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/index.ts#L74)
 
 The real path of the folder `dir`, of no link, which Node resolves the packages of a module of
 that folder from, as semantic-release's own `resolve-from` does: `dir` as it is of one that is not

package/api/@wtf/semantic-release/functions/runOf.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / [@wtf/semantic-release](../README.md) / runOf
+
+# Function: runOf()
+
+> **runOf**(`context`): `Promise`\<[`RepoContext`](../../release/interfaces/RepoContext.md)\<[`ReleasePlatform`](../../release/type-aliases/ReleasePlatform.md)\>\>
+
+Defined in: [packages/semantic-release/src/index.ts:52](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/index.ts#L52)
+
+The platform of a run, Node's, and the folder of its repo: the platform's working folder,
+`dirs.cwd`, and the folder `root` is the handle of, are the run's `cwd`; its environment, which
+each program it runs is given, the run's `env`; its `fetch` Node's own. A plugin runs on Node, and
+gives each library it calls this platform: a library takes the platform it is given, and assumes
+none. The folder of the repo is of the platform's storage, at its `dirs.cwd`.
+
+## Parameters
+
+### context
+
+[`RunContext`](../interfaces/RunContext.md)
+
+The folder and the environment of the run.
+
+## Returns
+
+`Promise`\<[`RepoContext`](../../release/interfaces/RepoContext.md)\<[`ReleasePlatform`](../../release/type-aliases/ReleasePlatform.md)\>\>
+
+The platform and the folder of the repo.

package/api/@wtf/semantic-release/interfaces/RunContext.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / [@wtf/semantic-release](../README.md) / RunContext
+
+# Interface: RunContext
+
+Defined in: [packages/semantic-release/src/index.ts:35](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/index.ts#L35)
+
+The folder and the environment of a run, as semantic-release gives them to each step.
+
+## Properties
+
+### cwd
+
+> `readonly` **cwd**: `string`
+
+Defined in: [packages/semantic-release/src/index.ts:37](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/index.ts#L37)
+
+The folder of the repo.
+
+***
+
+### env
+
+> `readonly` **env**: `Readonly`\<`Record`\<`string`, `string` \| `undefined`\>\>
+
+Defined in: [packages/semantic-release/src/index.ts:39](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/index.ts#L39)
+
+The environment of the run.

package/api/@wtf/semantic-release/links/README.md

@@ -0,0 +1,38 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/semantic-release/links
+
+# @wtf/semantic-release/links
+
+The record of what a release published, of each run: each plugin that publishes the packages of
+an ecosystem says what it published and where, by [recordReleased](functions/recordReleased.md), in its `publish` step, a
+`Released` of `@wtf/release/forge` of each; the plugin that makes the release of the forge reads
+them back of the same run, by [releasedOf](functions/releasedOf.md), and links each, as `releaseLinks` of
+`@wtf/release-trains/links` does on GitLab.
+
+```ts
+import { recordReleased, releasedOf } from '@wtf/semantic-release/links'
+
+const run = { cwd: '/repo', train: 'core', version: '1.2.0' }
+recordReleased(run, 'npm', [
+  {
+    ecosystem: 'npm',
+    name: '@acme/core',
+    version: '1.2.0',
+    page: 'https://www.npmjs.com/package/@acme/core/v/1.2.0'
+  }
+])
+console.log(releasedOf(run).map(({ name }) => name)) // ['@acme/core']
+```
+
+## Interfaces
+
+- [ReleaseRun](interfaces/ReleaseRun.md)
+
+## Functions
+
+- [forgetReleased](functions/forgetReleased.md)
+- [recordReleased](functions/recordReleased.md)
+- [releasedOf](functions/releasedOf.md)

package/api/@wtf/{release-trains → semantic-release}/links/functions/forgetReleased.md

@@ -2,13 +2,13 @@
 
 ***
 
-[Release trains](../../../../README.md) / [@wtf/release-trains/links](../README.md) / forgetReleased
+[Release trains](../../../../README.md) / [@wtf/semantic-release/links](../README.md) / forgetReleased
 
 # Function: forgetReleased()
 
 > **forgetReleased**(`run`): `void`
 
-Defined in: [packages/release-trains/src/links.ts:149](https://gitlab.com/wetryfun/release/release/-/blob/3b0e2c3c91b521977d05b801e2297d0df9e52834/packages/release-trains/src/links.ts#L149)
+Defined in: [packages/semantic-release/src/links.ts:96](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L96)
 
 Forgets what the release of `run` recorded, as once its links are made.
 

package/api/@wtf/{release-trains → semantic-release}/links/functions/recordReleased.md

@@ -2,13 +2,13 @@
 
 ***
 
-[Release trains](../../../../README.md) / [@wtf/release-trains/links](../README.md) / recordReleased
+[Release trains](../../../../README.md) / [@wtf/semantic-release/links](../README.md) / recordReleased
 
 # Function: recordReleased()
 
 > **recordReleased**(`run`, `ecosystem`, `packages`): `void`
 
-Defined in: [packages/release-trains/src/links.ts:122](https://gitlab.com/wetryfun/release/release/-/blob/3b0e2c3c91b521977d05b801e2297d0df9e52834/packages/release-trains/src/links.ts#L122)
+Defined in: [packages/semantic-release/src/links.ts:69](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L69)
 
 Records the packages of `ecosystem` that the release of `run` published, or found published, in
 place of what was recorded of the ecosystem in the run before, as of a release run again: none of
@@ -30,7 +30,7 @@ The ecosystem of the packages, as `npm`.
 
 ### packages
 
-readonly [`ReleasedPackage`](../interfaces/ReleasedPackage.md)[]
+readonly [`Released`](../../../release/forge/interfaces/Released.md)[]
 
 Each package, and where it is.
 

package/api/@wtf/semantic-release/links/functions/releasedOf.md

@@ -0,0 +1,28 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/links](../README.md) / releasedOf
+
+# Function: releasedOf()
+
+> **releasedOf**(`run`): [`Released`](../../../release/forge/interfaces/Released.md)[]
+
+Defined in: [packages/semantic-release/src/links.ts:87](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L87)
+
+The packages the release of `run` recorded, of every ecosystem, in the order the plugins
+recorded them: none of a run of none.
+
+## Parameters
+
+### run
+
+[`ReleaseRun`](../interfaces/ReleaseRun.md)
+
+The folder of the repo, the train and the version of the release.
+
+## Returns
+
+[`Released`](../../../release/forge/interfaces/Released.md)[]
+
+The packages.

package/api/@wtf/semantic-release/links/interfaces/ReleaseRun.md

@@ -0,0 +1,41 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/links](../README.md) / ReleaseRun
+
+# Interface: ReleaseRun
+
+Defined in: [packages/semantic-release/src/links.ts:29](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L29)
+
+The run of a release: the folder of its repo, its train and its version.
+
+## Properties
+
+### cwd
+
+> `readonly` **cwd**: `string`
+
+Defined in: [packages/semantic-release/src/links.ts:31](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L31)
+
+The folder of the repo.
+
+***
+
+### train
+
+> `readonly` **train**: `string`
+
+Defined in: [packages/semantic-release/src/links.ts:33](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L33)
+
+The name of the train.
+
+***
+
+### version
+
+> `readonly` **version**: `string`
+
+Defined in: [packages/semantic-release/src/links.ts:35](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/links.ts#L35)
+
+The version of the release.

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

@@ -0,0 +1,47 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/semantic-release/release
+
+# @wtf/semantic-release/release
+
+The release of a step of a plugin of a train, on the contract of `@wtf/release/contract`:
+[stepRelease](functions/stepRelease.md) gives the `Release` of the version semantic-release decided, of its dry run
+and its logger, each line of it named by the train of the run, as `[train core] …`; and
+[inTrain](functions/inTrain.md) names the train in the message of each error of a release a step throws. The
+libraries know no train, so what they say names none: a plugin names it, once, here, and what
+semantic-release prints of each plugin says the train again.
+
+```ts
+import { runOf } from '@wtf/semantic-release'
+import { inTrain, stepRelease } from '@wtf/semantic-release/release'
+
+export const verifyRelease = (
+  _options: unknown,
+  context: {
+    cwd: string
+    env: Record<string, string | undefined>
+    logger: { log(line: string): void; warn(line: string): void }
+    options: { dryRun?: boolean }
+    nextRelease: { version: string }
+  }
+) =>
+  inTrain('core', async () => {
+    const { version } = context.nextRelease
+    const release = stepRelease(context, { ...(await runOf(context)), train: 'core', version })
+    release.log(`Verifies ${release.version}.`) // [train core] Verifies 1.2.0.
+  })
+```
+
+## Interfaces
+
+- [StepContext](interfaces/StepContext.md)
+- [StepOf](interfaces/StepOf.md)
+
+## Functions
+
+- [inTrain](functions/inTrain.md)
+- [stepRelease](functions/stepRelease.md)
+- [trainNamed](functions/trainNamed.md)
+- [trainPrefix](functions/trainPrefix.md)

package/api/@wtf/semantic-release/release/functions/inTrain.md

@@ -0,0 +1,42 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/release](../README.md) / inTrain
+
+# Function: inTrain()
+
+> **inTrain**\<`T`\>(`train`, `run`): `Promise`\<`T`\>
+
+Defined in: [packages/semantic-release/src/release.ts:112](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L112)
+
+What `run` gives, each error of a release it throws named by `train` ([trainNamed](trainNamed.md)): the
+part of a step after it knows its train.
+
+## Type Parameters
+
+### T
+
+`T`
+
+What `run` gives.
+
+## Parameters
+
+### train
+
+`string`
+
+The train of the run.
+
+### run
+
+() => `Promise`\<`T`\>
+
+The part of the step.
+
+## Returns
+
+`Promise`\<`T`\>
+
+What `run` gives.

package/api/@wtf/semantic-release/release/functions/stepRelease.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/release](../README.md) / stepRelease
+
+# Function: stepRelease()
+
+> **stepRelease**(`context`, `of`): [`Release`](../../../release/contract/interfaces/Release.md)
+
+Defined in: [packages/semantic-release/src/release.ts:73](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L73)
+
+The release of a step, on the contract: of the version, the folder and the platform of `of`, the
+dry run of `context`, and its logger, each line named by the train of `of`, a warning by the
+logger's `warn`.
+
+## Parameters
+
+### context
+
+[`StepContext`](../interfaces/StepContext.md)
+
+The logger and the options of the step.
+
+### of
+
+[`StepOf`](../interfaces/StepOf.md)
+
+The version, the train, and the folder and the platform of the run.
+
+## Returns
+
+[`Release`](../../../release/contract/interfaces/Release.md)
+
+The release.

package/api/@wtf/semantic-release/release/functions/trainNamed.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/release](../README.md) / trainNamed
+
+# Function: trainNamed()
+
+> **trainNamed**(`train`, `error`): `unknown`
+
+Defined in: [packages/semantic-release/src/release.ts:95](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L95)
+
+`error`, the message of each error of a release of it named by `train`: of a `ReleaseError`, and
+of each `ReleaseError` of an `AggregateError`, once; any other as it is.
+
+## Parameters
+
+### train
+
+`string`
+
+The train of the run.
+
+### error
+
+`unknown`
+
+What a step threw.
+
+## Returns
+
+`unknown`
+
+The same error.

package/api/@wtf/semantic-release/release/functions/trainPrefix.md

@@ -0,0 +1,27 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/release](../README.md) / trainPrefix
+
+# Function: trainPrefix()
+
+> **trainPrefix**(`train`): `string`
+
+Defined in: [packages/semantic-release/src/release.ts:62](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L62)
+
+What each line and each message of a release of `train` begins with.
+
+## Parameters
+
+### train
+
+`string`
+
+The train of the run, as `core`.
+
+## Returns
+
+`string`
+
+The prefix, as `[train core] `.

package/api/@wtf/semantic-release/release/interfaces/StepContext.md

@@ -0,0 +1,63 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/semantic-release/release](../README.md) / StepContext
+
+# Interface: StepContext
+
+Defined in: [packages/semantic-release/src/release.ts:38](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L38)
+
+What a step of semantic-release gives a plugin that its release reads: its logger and options.
+
+## Properties
+
+### logger
+
+> `readonly` **logger**: `object`
+
+Defined in: [packages/semantic-release/src/release.ts:40](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L40)
+
+The logger of the run: `warn` of a warning, `log` where it has none.
+
+#### log()
+
+> **log**(`line`): `void`
+
+##### Parameters
+
+###### line
+
+`string`
+
+##### Returns
+
+`void`
+
+#### warn()?
+
+> `optional` **warn**(`line`): `void`
+
+##### Parameters
+
+###### line
+
+`string`
+
+##### Returns
+
+`void`
+
+***
+
+### options?
+
+> `readonly` `optional` **options?**: `object`
+
+Defined in: [packages/semantic-release/src/release.ts:45](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/semantic-release/src/release.ts#L45)
+
+The options of the run: `dryRun` of a run that publishes nothing.
+
+#### dryRun?
+
+> `readonly` `optional` **dryRun?**: `boolean`