@wtf/release-docs 8.1.0 → 8.2.0

package/api/@wtf/release-go/modules/functions/modulesAt.md

@@ -0,0 +1,39 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/modules](../README.md) / modulesAt
+
+# Function: modulesAt()
+
+> **modulesAt**(`ref`, `context`): `Promise`\<[`GoModule`](../../interfaces/GoModule.md)[]\>
+
+Defined in: [packages/release-go/src/modules.ts:117](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L117)
+
+The modules of the repo of `context` at the commit `ref`: each go.mod of its tree, as
+[isGoMod](isGoMod.md) says, read by `git show`.
+
+## Parameters
+
+### ref
+
+`string`
+
+The commit, as `HEAD` or the tag of a release.
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo, its environment, and the system git runs by.
+
+## Returns
+
+`Promise`\<[`GoModule`](../../interfaces/GoModule.md)[]\>
+
+The modules, in the order of `git ls-tree`.
+
+## Throws
+
+`EGIT` of a commit git has not, `EGOMOD` of a go.mod of no module, and of two of one
+path.

package/api/@wtf/release-go/modules/functions/modulesOf.md

@@ -0,0 +1,29 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/modules](../README.md) / modulesOf
+
+# Function: modulesOf()
+
+> **modulesOf**(`manifests`): [`GoModule`](../../interfaces/GoModule.md)[]
+
+Defined in: [packages/release-go/src/modules.ts:52](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L52)
+
+The modules of go.mod files, each of its file and its text: each of the path of its `module`
+line, its folder, its requires and its replaces. Throws `EGOMOD` of a go.mod of no `module` line,
+and of two of one path, together.
+
+## Parameters
+
+### manifests
+
+readonly `object`[]
+
+Each go.mod, of its path from the root of the repo and its text.
+
+## Returns
+
+[`GoModule`](../../interfaces/GoModule.md)[]
+
+The modules, in the order of `manifests`.

package/api/@wtf/release-go/modules/functions/readModules.md

@@ -0,0 +1,33 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/modules](../README.md) / readModules
+
+# Function: readModules()
+
+> **readModules**(`context`): `Promise`\<[`GoModule`](../../interfaces/GoModule.md)[]\>
+
+Defined in: [packages/release-go/src/modules.ts:97](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L97)
+
+The modules of the working tree of the repo of `context`: each go.mod git tracks, as
+[isGoMod](isGoMod.md) says, read by the system.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo, its environment, and the system git runs and the files
+are read by.
+
+## Returns
+
+`Promise`\<[`GoModule`](../../interfaces/GoModule.md)[]\>
+
+The modules, in the order of `git ls-files`.
+
+## Throws
+
+`EGOMOD` of a go.mod of no module, and of two of one path.

package/api/@wtf/release-go/modules/functions/selectModules.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/modules](../README.md) / selectModules
+
+# Function: selectModules()
+
+> **selectModules**(`modules`, `selection`): [`GoModule`](../../interfaces/GoModule.md)[]
+
+Defined in: [packages/release-go/src/modules.ts:166](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L166)
+
+The modules a release tags: those of its train that can be fetched ([isFetchable](isFetchable.md)), of
+`include` where it names some, but those of `exclude`, in the order of their paths. A module of an
+option that the repo has not, or that is of another train, or that cannot be fetched, is a fault,
+as a release that skips it by a typo tags less than it says. A module of the release that requires
+a module of the repo that cannot be fetched fails too, as no user of it could build it.
+
+## Parameters
+
+### modules
+
+readonly [`GoModule`](../../interfaces/GoModule.md)[]
+
+The modules of the repo, as [readModules](readModules.md) gives them.
+
+### selection
+
+[`Selection`](../interfaces/Selection.md)
+
+The modules of the train, and the paths to include and to exclude.
+
+## Returns
+
+[`GoModule`](../../interfaces/GoModule.md)[]
+
+The modules of the release, in the order of their paths: none of a train of no module to
+tag.
+
+## Throws
+
+`EGOMODULES` of a path no module has, or of a module of another train or that cannot be
+fetched that `include` names; `EGOPRIVATE` of a require of a module of the
+repo that cannot be fetched.

package/api/@wtf/release-go/modules/interfaces/Selection.md

@@ -0,0 +1,43 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/modules](../README.md) / Selection
+
+# Interface: Selection
+
+Defined in: [packages/release-go/src/modules.ts:138](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L138)
+
+The names a selection of modules is made of.
+
+## Properties
+
+### exclude?
+
+> `readonly` `optional` **exclude?**: readonly `string`[]
+
+Defined in: [packages/release-go/src/modules.ts:148](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L148)
+
+The modules not to tag, by path, of the ones `include` or the train gives.
+
+***
+
+### include?
+
+> `readonly` `optional` **include?**: readonly `string`[]
+
+Defined in: [packages/release-go/src/modules.ts:146](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L146)
+
+The modules to tag, by path: every module of the train that can be fetched by default.
+
+***
+
+### train
+
+> `readonly` **train**: `ReadonlySet`\<`string`\>
+
+Defined in: [packages/release-go/src/modules.ts:144](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/modules.ts#L144)
+
+The modules of the train of the release, by path, as `ownersOf` of
+`@wtf/release-trains/packages` gives them of the packages of `goEcosystem` of `./ecosystem`: the
+release tags of these alone.

package/api/@wtf/release-go/stamp/README.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-go/stamp
+
+# @wtf/release-go/stamp
+
+The versions of the trains written into the go.mod files of a repo, by the line reader of
+`./gomod`, and no parser that writes the file again: the comments, the layout, the quoting and
+the line endings of a go.mod that people edit stay as they are. Each module takes the version of
+its train: of the train of the release, the release's; of another train, its last release
+(`releasedVersions` of `@wtf/release-trains/packages`); of no train, none. What it writes, in every
+go.mod of the repo:
+
+- the version of each `require` of a module that takes one, of a line of its own or of a block,
+  `// indirect` too, as `v1.4.0`;
+- the version a `replace` of such a module replaces, where it names one, as
+  `replace example.com/lib v0.0.0 => ../lib`, so the replace still applies to the version the
+  require names.
+
+Nothing else changes: no go.sum, no `go mod tidy`, and a require of a module of no version to
+take is left. [checkVersions](functions/checkVersions.md) then holds the files read again to the versions.
+
+```ts
+import { stampGoMod } from '@wtf/release-go/stamp'
+
+const { text } = stampGoMod(
+  'module example.com/app\n\nrequire example.com/lib v0.0.0 // kept\n',
+  new Map([['example.com/lib', '1.2.3']])
+)
+console.log(text)
+```
+
+## Interfaces
+
+- [Stamped](interfaces/Stamped.md)
+- [StampedModules](interfaces/StampedModules.md)
+
+## Functions
+
+- [checkVersions](functions/checkVersions.md)
+- [stampGoMod](functions/stampGoMod.md)
+- [stampModules](functions/stampModules.md)

package/api/@wtf/release-go/stamp/functions/checkVersions.md

@@ -0,0 +1,38 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/stamp](../README.md) / checkVersions
+
+# Function: checkVersions()
+
+> **checkVersions**(`modules`, `versions`): `void`
+
+Defined in: [packages/release-go/src/stamp.ts:149](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L149)
+
+Checks that each `require` of a module of `versions`, of the go.mod files read again after the
+stamp, names the version that module takes: what a stamp left wrong, as a require of a form the
+line reader does not read.
+
+## Parameters
+
+### modules
+
+readonly [`GoModule`](../../interfaces/GoModule.md)[]
+
+Every module of the repo, as `readModules` of `./modules` gives them after the
+stamp.
+
+### versions
+
+`ReadonlyMap`\<`string`, `string`\>
+
+The version each module takes, by its path: a module of none is not checked.
+
+## Returns
+
+`void`
+
+## Throws
+
+`EGOVERSION` of each require of another version, together.

package/api/@wtf/release-go/stamp/functions/stampGoMod.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/stamp](../README.md) / stampGoMod
+
+# Function: stampGoMod()
+
+> **stampGoMod**(`text`, `versions`): [`Stamped`](../interfaces/Stamped.md)
+
+Defined in: [packages/release-go/src/stamp.ts:74](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L74)
+
+The go.mod `text` with the versions written, as the module says: each `require` of a module of
+`versions`, and the version a `replace` of it replaces. Idempotent: stamped twice, the second
+changes nothing.
+
+## Parameters
+
+### text
+
+`string`
+
+The go.mod.
+
+### versions
+
+`ReadonlyMap`\<`string`, `string`\>
+
+The version each module takes, by its path, as `1.2.3`, of no `v`.
+
+## Returns
+
+[`Stamped`](../interfaces/Stamped.md)
+
+The go.mod stamped, and the count of values it wrote.

package/api/@wtf/release-go/stamp/functions/stampModules.md

@@ -0,0 +1,42 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/stamp](../README.md) / stampModules
+
+# Function: stampModules()
+
+> **stampModules**(`context`, `modules`, `versions`): `Promise`\<[`StampedModules`](../interfaces/StampedModules.md)\>
+
+Defined in: [packages/release-go/src/stamp.ts:117](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L117)
+
+Writes `versions` into the go.mod of each of `modules`, as the module says. A file of no change
+is not written.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo and the system the files are read and written by.
+
+### modules
+
+readonly [`GoModule`](../../interfaces/GoModule.md)[]
+
+Every module of the repo, as `readModules` of `./modules` gives them.
+
+### versions
+
+`ReadonlyMap`\<`string`, `string`\>
+
+The version each module takes, by its path: of the modules of the train of the
+release, the release's, and of each other train's, its last release (`releasedVersions` of
+`@wtf/release-trains/packages`).
+
+## Returns
+
+`Promise`\<[`StampedModules`](../interfaces/StampedModules.md)\>
+
+The go.mod files written, and how many values.

package/api/@wtf/release-go/stamp/interfaces/Stamped.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/stamp](../README.md) / Stamped
+
+# Interface: Stamped
+
+Defined in: [packages/release-go/src/stamp.ts:39](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L39)
+
+A go.mod stamped, and how many values it wrote.
+
+## Properties
+
+### changes
+
+> `readonly` **changes**: `number`
+
+Defined in: [packages/release-go/src/stamp.ts:43](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L43)
+
+The values that were another, and are of the versions now.
+
+***
+
+### text
+
+> `readonly` **text**: `string`
+
+Defined in: [packages/release-go/src/stamp.ts:41](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L41)
+
+The go.mod, the versions written.

package/api/@wtf/release-go/stamp/interfaces/StampedModules.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/stamp](../README.md) / StampedModules
+
+# Interface: StampedModules
+
+Defined in: [packages/release-go/src/stamp.ts:99](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L99)
+
+The result of stamping the modules of a repo: the go.mod files written, and the values.
+
+## Properties
+
+### changes
+
+> `readonly` **changes**: `number`
+
+Defined in: [packages/release-go/src/stamp.ts:103](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L103)
+
+The values written.
+
+***
+
+### files
+
+> `readonly` **files**: readonly `string`[]
+
+Defined in: [packages/release-go/src/stamp.ts:101](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/stamp.ts#L101)
+
+The go.mod files whose text changed, from the root of the repo.

package/api/@wtf/release-go/tags/README.md

@@ -0,0 +1,48 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-go/tags
+
+# @wtf/release-go/tags
+
+The tags of a release of Go modules: Go has no registry, and a version of a module is a tag of its
+repo, `<folder>/v<version>`, or `v<version>` of a module at the root ([tagOfModule](functions/tagOfModule.md)). Go
+reads the go.mod of a module at the commit its tag names, so that commit must require the modules
+of the repo at their releases; and no version is written into git on the branch, whose go.mod
+files hold placeholders. So [releaseCommit](functions/releaseCommit.md) makes a commit of the stamped go.mod files on top
+of `HEAD`, on no branch, by a temporary index, without touching `HEAD`, the index or the working
+tree; [tagModules](functions/tagModules.md) asks the remote which tags it has, tags that commit with each it lacks,
+and pushes them in one atomic push, so a release that stopped part way is finished by running it
+again; and [askProxy](functions/askProxy.md) asks the Go proxy for each module at its version, so it is fetched
+once and listed.
+
+```ts
+import { tagOfModule } from '@wtf/release-go/tags'
+
+const module = { path: 'example.com/repo/lib/v2', dir: 'lib/v2', manifest: 'lib/v2/go.mod' }
+console.log(tagOfModule({ ...module, requires: [], replaces: [] }, '2.1.0')) // lib/v2.1.0
+```
+
+## Interfaces
+
+- [TaggedModule](interfaces/TaggedModule.md)
+- [TagModulesOptions](interfaces/TagModulesOptions.md)
+
+## Type Aliases
+
+- [ModuleStatus](type-aliases/ModuleStatus.md)
+
+## Variables
+
+- [RELEASE\_AUTHOR](variables/RELEASE_AUTHOR.md)
+
+## Functions
+
+- [askProxy](functions/askProxy.md)
+- [maskCredentials](functions/maskCredentials.md)
+- [releaseCommit](functions/releaseCommit.md)
+- [remoteTags](functions/remoteTags.md)
+- [tagModules](functions/tagModules.md)
+- [tagOfModule](functions/tagOfModule.md)
+- [tagPrefix](functions/tagPrefix.md)

package/api/@wtf/release-go/tags/functions/askProxy.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/tags](../README.md) / askProxy
+
+# Function: askProxy()
+
+> **askProxy**(`context`, `modules`, `version`): `Promise`\<`void`\>
+
+Defined in: [packages/release-go/src/tags.ts:293](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/tags.ts#L293)
+
+Asks the Go proxy for each of `modules` at `version`, by `go list -m -json <path>@v<version>`
+in the system's temporary folder, of no workspace (`GOWORK=off`, `GOFLAGS=-mod=mod`), and
+`GOPROXY` of the environment, Go's own by default: the proxy fetches it once, and lists it. Each
+that fails is an error, together.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The environment, and the system `go` runs by.
+
+### modules
+
+readonly `Pick`\<[`GoModule`](../../interfaces/GoModule.md), `"path"`\>[]
+
+The modules, of their paths.
+
+### version
+
+`string`
+
+The version, as `1.2.3`.
+
+## Returns
+
+`Promise`\<`void`\>
+
+## Throws
+
+`EGOPROXY` of a `go` that cannot be run, or of a module the proxy cannot give.

package/api/@wtf/release-go/tags/functions/maskCredentials.md

@@ -0,0 +1,28 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/tags](../README.md) / maskCredentials
+
+# Function: maskCredentials()
+
+> **maskCredentials**(`text`): `string`
+
+Defined in: [packages/release-go/src/tags.ts:73](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/tags.ts#L73)
+
+A text of no credentials of a URL: `https://user:token@host` as `https://[secure]@host`, as a
+remote of a CI holds its token.
+
+## Parameters
+
+### text
+
+`string`
+
+A text, as a URL or what git says of one.
+
+## Returns
+
+`string`
+
+The text, each user and password of a URL masked.

package/api/@wtf/release-go/tags/functions/releaseCommit.md

@@ -0,0 +1,48 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/tags](../README.md) / releaseCommit
+
+# Function: releaseCommit()
+
+> **releaseCommit**(`context`, `files`, `message`): `Promise`\<`string`\>
+
+Defined in: [packages/release-go/src/tags.ts:114](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/tags.ts#L114)
+
+A commit of `files`, the go.mod files stamped in the working tree, on top of `HEAD`, on no branch,
+as `git commit` would make it but by a temporary index of the system's temporary files: `HEAD`,
+the index and the working tree are left as they are. Its author and committer are those of
+`GIT_AUTHOR_*` and `GIT_COMMITTER_*` of the environment, else [RELEASE\_AUTHOR](../variables/RELEASE_AUTHOR.md). A tree the
+same as `HEAD`'s, as of go.mod files that require no module of the repo, is no commit: it gives
+`HEAD` itself.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo, its environment, and the system git runs by.
+
+### files
+
+readonly `string`[]
+
+The go.mod files, from the root of the repo.
+
+### message
+
+`string`
+
+The message of the commit.
+
+## Returns
+
+`Promise`\<`string`\>
+
+The hash of the commit, or of `HEAD`.
+
+## Throws
+
+`EGOTAG` of a git that fails.

package/api/@wtf/release-go/tags/functions/remoteTags.md

@@ -0,0 +1,43 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/tags](../README.md) / remoteTags
+
+# Function: remoteTags()
+
+> **remoteTags**(`context`, `remote`, `tags`): `Promise`\<`Set`\<`string`\>\>
+
+Defined in: [packages/release-go/src/tags.ts:173](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/tags.ts#L173)
+
+The tags of `tags` the remote has, of one `git ls-remote`.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo, its environment, and the system git runs by.
+
+### remote
+
+`string`
+
+The remote, by its name or its URL.
+
+### tags
+
+readonly `string`[]
+
+The tags, as `lib/v1.2.3`.
+
+## Returns
+
+`Promise`\<`Set`\<`string`\>\>
+
+The tags of `tags` the remote has.
+
+## Throws
+
+`EGOTAG` of a remote that cannot be asked.

package/api/@wtf/release-go/tags/functions/tagModules.md

@@ -0,0 +1,36 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-go/tags](../README.md) / tagModules
+
+# Function: tagModules()
+
+> **tagModules**(`options`): `Promise`\<[`TaggedModule`](../interfaces/TaggedModule.md)[]\>
+
+Defined in: [packages/release-go/src/tags.ts:247](https://gitlab.com/wetryfun/release/release/-/blob/a387d2dfc7054e3ce27012a942d72d35e4f4b45f/packages/release-go/src/tags.ts#L247)
+
+Tags the modules of a release and pushes the tags: asks the remote which tags it has first, so a
+remote that cannot be asked stops before anything is made; skips each it has; makes the commit of
+the stamped go.mod files ([releaseCommit](releaseCommit.md)) of the rest, tags it with each (`git tag -f`, as a
+tag the remote lacks is this release's own), and pushes them in one `git push --atomic`, all or
+none.
+
+## Parameters
+
+### options
+
+[`TagModulesOptions`](../interfaces/TagModulesOptions.md)
+
+The repo, the remote, the modules and the version, the files of the commit and
+its message, and the log.
+
+## Returns
+
+`Promise`\<[`TaggedModule`](../interfaces/TaggedModule.md)[]\>
+
+Each module, its tag, and whether it was tagged or skipped, in the order of `modules`.
+
+## Throws
+
+`EGOTAG` of a remote that cannot be asked, or a commit, a tag or a push that fails.