@wtf/release-docs 9.0.1 → 9.1.0

package/api/@wtf/release-oci/errors/classes/OciError.md

@@ -0,0 +1,268 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/errors](../README.md) / OciError
+
+# Class: OciError
+
+Defined in: [packages/release-oci/src/errors.ts:38](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/errors.ts#L38)
+
+An error of the OCI images, or of the options of the plugin over them: a stable `code`, of
+[OCI\_ERRORS](../variables/OCI_ERRORS.md) or of `SYSTEM_ERRORS` of `@wtf/release-system/errors`, its `message` what is
+wrong, and its `details` how to fix it.
+
+## Extends
+
+- [`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md)
+
+## Constructors
+
+### Constructor
+
+> **new OciError**(`code`, `message`, `details`): `OciError`
+
+Defined in: [packages/release-system/src/errors.ts:54](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/errors.ts#L54)
+
+An error of `code`, of its `message` and its `details`, named `SemanticReleaseError`, as
+semantic-release prints one.
+
+#### Parameters
+
+##### code
+
+`string`
+
+The stable code of the error, as `EGIT`.
+
+##### message
+
+`string`
+
+What is wrong, as a reader is told it.
+
+##### details
+
+`string`
+
+How to fix it, of the steps a reader takes.
+
+#### Returns
+
+`OciError`
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`constructor`](../../../release-system/errors/classes/ReleaseError.md#constructor)
+
+## Properties
+
+### cause?
+
+> `optional` **cause?**: `unknown`
+
+Defined in: node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`cause`](../../../release-system/errors/classes/ReleaseError.md#cause)
+
+***
+
+### code
+
+> `readonly` **code**: `string`
+
+Defined in: [packages/release-system/src/errors.ts:40](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/errors.ts#L40)
+
+The stable code of the error, as `EGIT`.
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`code`](../../../release-system/errors/classes/ReleaseError.md#code)
+
+***
+
+### details
+
+> `readonly` **details**: `string`
+
+Defined in: [packages/release-system/src/errors.ts:42](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/errors.ts#L42)
+
+How to fix it.
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`details`](../../../release-system/errors/classes/ReleaseError.md#details)
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`message`](../../../release-system/errors/classes/ReleaseError.md#message)
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`name`](../../../release-system/errors/classes/ReleaseError.md#name)
+
+***
+
+### semanticRelease
+
+> `readonly` **semanticRelease**: `true`
+
+Defined in: [packages/release-system/src/errors.ts:44](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/errors.ts#L44)
+
+The mark semantic-release prints an error of a plugin by.
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`semanticRelease`](../../../release-system/errors/classes/ReleaseError.md#semanticrelease)
+
+***
+
+### stack?
+
+> `optional` **stack?**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`stack`](../../../release-system/errors/classes/ReleaseError.md#stack)
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+Defined in: node\_modules/.pnpm/@types+node@24.19.2/node\_modules/@types/node/globals.d.ts:68
+
+The `Error.stackTraceLimit` property specifies the number of stack frames
+collected by a stack trace (whether generated by `new Error().stack` or
+`Error.captureStackTrace(obj)`).
+
+The default value is `10` but may be set to any valid JavaScript number. Changes
+will affect any stack trace captured _after_ the value has been changed.
+
+If set to a non-number value, or set to a negative number, stack traces will
+not capture any frames.
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`stackTraceLimit`](../../../release-system/errors/classes/ReleaseError.md#stacktracelimit)
+
+## Methods
+
+### captureStackTrace()
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
+
+Defined in: node\_modules/.pnpm/@types+node@24.19.2/node\_modules/@types/node/globals.d.ts:52
+
+Creates a `.stack` property on `targetObject`, which when accessed returns
+a string representing the location in the code at which
+`Error.captureStackTrace()` was called.
+
+```js
+const myObject = {};
+Error.captureStackTrace(myObject);
+myObject.stack;  // Similar to `new Error().stack`
+```
+
+The first line of the trace will be prefixed with
+`${myObject.name}: ${myObject.message}`.
+
+The optional `constructorOpt` argument accepts a function. If given, all frames
+above `constructorOpt`, including `constructorOpt`, will be omitted from the
+generated stack trace.
+
+The `constructorOpt` argument is useful for hiding implementation
+details of error generation from the user. For instance:
+
+```js
+function a() {
+  b();
+}
+
+function b() {
+  c();
+}
+
+function c() {
+  // Create an error without stack trace to avoid calculating the stack trace twice.
+  const { stackTraceLimit } = Error;
+  Error.stackTraceLimit = 0;
+  const error = new Error();
+  Error.stackTraceLimit = stackTraceLimit;
+
+  // Capture the stack trace above function b
+  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
+  throw error;
+}
+
+a();
+```
+
+#### Parameters
+
+##### targetObject
+
+`object`
+
+##### constructorOpt?
+
+`Function`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`captureStackTrace`](../../../release-system/errors/classes/ReleaseError.md#capturestacktrace)
+
+***
+
+### prepareStackTrace()
+
+> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
+
+Defined in: node\_modules/.pnpm/@types+node@24.19.2/node\_modules/@types/node/globals.d.ts:56
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`ReleaseError`](../../../release-system/errors/classes/ReleaseError.md).[`prepareStackTrace`](../../../release-system/errors/classes/ReleaseError.md#preparestacktrace)

package/api/@wtf/release-oci/errors/type-aliases/OciErrorCode.md

@@ -0,0 +1,13 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/errors](../README.md) / OciErrorCode
+
+# Type Alias: OciErrorCode
+
+> **OciErrorCode** = keyof *typeof* [`OCI_ERRORS`](../variables/OCI_ERRORS.md)
+
+Defined in: [packages/release-oci/src/errors.ts:31](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/errors.ts#L31)
+
+A code of [OCI\_ERRORS](../variables/OCI_ERRORS.md).

package/api/@wtf/release-oci/errors/variables/OCI_ERRORS.md

@@ -0,0 +1,43 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/errors](../README.md) / OCI\_ERRORS
+
+# Variable: OCI\_ERRORS
+
+> `const` **OCI\_ERRORS**: `object`
+
+Defined in: [packages/release-oci/src/errors.ts:15](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/errors.ts#L15)
+
+The codes of the errors of the OCI images, each with what it means.
+
+## Type Declaration
+
+### EOCIECOSYSTEM
+
+> `readonly` **EOCIECOSYSTEM**: `` "The `ecosystems` of the config lists neither `@wtf/semantic-release-oci/ecosystem` nor `@wtf/release-oci`, so the trains read no image." `` = `` 'The `ecosystems` of the config lists neither `@wtf/semantic-release-oci/ecosystem` nor `@wtf/release-oci`, so the trains read no image.' ``
+
+### EOCIIMAGE
+
+> `readonly` **EOCIIMAGE**: `` "The repository of an image cannot be named: neither the option `image` nor `CI_REGISTRY_IMAGE` of the environment gives one." `` = `` 'The repository of an image cannot be named: neither the option `image` nor `CI_REGISTRY_IMAGE` of the environment gives one.' ``
+
+### EOCILINK
+
+> `readonly` **EOCILINK**: `"The container registry of GitLab cannot be asked the page of an image, or lists none."` = `'The container registry of GitLab cannot be asked the page of an image, or lists none.'`
+
+### EOCIRETAG
+
+> `readonly` **EOCIRETAG**: `"The registry has the full version of a release already, at another digest: a released version is never moved."` = `'The registry has the full version of a release already, at another digest: a released version is never moved.'`
+
+### EOCISMOKE
+
+> `readonly` **EOCISMOKE**: `"The registry has not the tested image of a release, or crane cannot ask it: there is nothing to copy to the tags of the release."` = `'The registry has not the tested image of a release, or crane cannot ask it: there is nothing to copy to the tags of the release.'`
+
+### EOCISOURCE
+
+> `readonly` **EOCISOURCE**: `` "The tested image of a release cannot be named: neither the option `sourceTag` nor `CI_COMMIT_REF_SLUG` of the environment gives its tag." `` = `` 'The tested image of a release cannot be named: neither the option `sourceTag` nor `CI_COMMIT_REF_SLUG` of the environment gives its tag.' ``
+
+### EOCITAG
+
+> `readonly` **EOCITAG**: `"crane cannot copy the tested image to a tag of the release."` = `'crane cannot copy the tested image to a tag of the release.'`

package/api/@wtf/release-oci/images/README.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-oci/images
+
+# @wtf/release-oci/images
+
+The OCI images of a repo: [readImages](functions/readImages.md) reads each image of the working tree, and
+[imagesAt](functions/imagesAt.md) each of a commit, of the files git tracks. An image is a folder that holds what
+it is built of ([isImageManifest](functions/isImageManifest.md)): a `Dockerfile` or a `Containerfile`, or a
+`.devcontainer/devcontainer.json`, which the devcontainer CLI builds; a folder of both is one image.
+Its repository in the registry is the registry image of the project, `CI_REGISTRY_IMAGE` of a
+pipeline, of the root, and that and its folder of another ([repositoryOf](functions/repositoryOf.md)), as GitLab names
+the images of a project.
+
+```ts
+import { readImages } from '@wtf/release-oci/images'
+import type { System } from '@wtf/release-system'
+
+// The folders of the images of the repo.
+export async function folders(system: System): Promise<string[]> {
+  return (await readImages({ system })).map(({ dir }) => dir)
+}
+```
+
+## Functions
+
+- [imageDirOf](functions/imageDirOf.md)
+- [imagesAt](functions/imagesAt.md)
+- [imagesOf](functions/imagesOf.md)
+- [isImageManifest](functions/isImageManifest.md)
+- [readImages](functions/readImages.md)
+- [registryImageOf](functions/registryImageOf.md)
+- [repositoryOf](functions/repositoryOf.md)

package/api/@wtf/release-oci/images/functions/imageDirOf.md

@@ -0,0 +1,28 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / imageDirOf
+
+# Function: imageDirOf()
+
+> **imageDirOf**(`file`): `string` \| `undefined`
+
+Defined in: [packages/release-oci/src/images.ts:41](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L41)
+
+The folder of the image `file` is built of: of a `Dockerfile` or a `Containerfile`, its folder; of
+a `.devcontainer/devcontainer.json`, the folder above `.devcontainer`; of any other file, none.
+
+## Parameters
+
+### file
+
+`string`
+
+A file of the repo, from its root.
+
+## Returns
+
+`string` \| `undefined`
+
+The folder of its image, `.` of the root; none of a file no image is built of.

package/api/@wtf/release-oci/images/functions/imagesAt.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / imagesAt
+
+# Function: imagesAt()
+
+> **imagesAt**(`ref`, `context`, `registryImage?`): `Promise`\<[`OciImage`](../../interfaces/OciImage.md)[]\>
+
+Defined in: [packages/release-oci/src/images.ts:127](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L127)
+
+The images of the repo of `context` at the commit `ref`: each folder of its tree that holds a file
+an image is built of, by `git ls-tree`.
+
+## 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.
+
+### registryImage?
+
+`string` \| `undefined` = `...`
+
+The registry image of the project: [registryImageOf](registryImageOf.md) by default.
+
+## Returns
+
+`Promise`\<[`OciImage`](../../interfaces/OciImage.md)[]\>
+
+The images, by their folders.
+
+## Throws
+
+`EGIT` of a commit git has not.

package/api/@wtf/release-oci/images/functions/imagesOf.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / imagesOf
+
+# Function: imagesOf()
+
+> **imagesOf**(`files`, `registryImage`): [`OciImage`](../../interfaces/OciImage.md)[]
+
+Defined in: [packages/release-oci/src/images.ts:79](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L79)
+
+The images of `files`, the files of the repo: one of each folder that holds what an image is
+built of, of the first such file of it, in the order of their folders.
+
+## Parameters
+
+### files
+
+readonly `string`[]
+
+The files of the repo, from its root.
+
+### registryImage
+
+`string` \| `undefined`
+
+The registry image of the project, which names the repository of each.
+
+## Returns
+
+[`OciImage`](../../interfaces/OciImage.md)[]
+
+The images, by their folders.

package/api/@wtf/release-oci/images/functions/isImageManifest.md

@@ -0,0 +1,27 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / isImageManifest
+
+# Function: isImageManifest()
+
+> **isImageManifest**(`file`): `boolean`
+
+Defined in: [packages/release-oci/src/images.ts:54](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L54)
+
+Whether `file`, a file of the repo, is what an image is built of (see [imageDirOf](imageDirOf.md)).
+
+## Parameters
+
+### file
+
+`string`
+
+The file, from the root of the repo.
+
+## Returns
+
+`boolean`
+
+Whether it is.

package/api/@wtf/release-oci/images/functions/readImages.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / readImages
+
+# Function: readImages()
+
+> **readImages**(`context`, `registryImage?`): `Promise`\<[`OciImage`](../../interfaces/OciImage.md)[]\>
+
+Defined in: [packages/release-oci/src/images.ts:110](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L110)
+
+The images of the repo of `context`: each folder of the working tree that git tracks a file an
+image is built of in.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The folder of the repo, its environment, and the system git runs by.
+
+### registryImage?
+
+`string` \| `undefined` = `...`
+
+The registry image of the project: [registryImageOf](registryImageOf.md) by default.
+
+## Returns
+
+`Promise`\<[`OciImage`](../../interfaces/OciImage.md)[]\>
+
+The images, by their folders.

package/api/@wtf/release-oci/images/functions/registryImageOf.md

@@ -0,0 +1,28 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / registryImageOf
+
+# Function: registryImageOf()
+
+> **registryImageOf**(`context`): `string` \| `undefined`
+
+Defined in: [packages/release-oci/src/images.ts:97](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L97)
+
+The registry image of the project of `context`, as GitLab gives a pipeline it:
+`CI_REGISTRY_IMAGE` of the environment; none of none.
+
+## Parameters
+
+### context
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+The environment of the run, of its system.
+
+## Returns
+
+`string` \| `undefined`
+
+The registry image, or none.

package/api/@wtf/release-oci/images/functions/repositoryOf.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/images](../README.md) / repositoryOf
+
+# Function: repositoryOf()
+
+> **repositoryOf**(`registryImage`, `dir`): `string` \| `undefined`
+
+Defined in: [packages/release-oci/src/images.ts:65](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/images.ts#L65)
+
+The repository of the image of `dir` in the registry of `registryImage`, the registry image of
+the project: that of the root, and that and the folder of another.
+
+## Parameters
+
+### registryImage
+
+`string` \| `undefined`
+
+The registry image of the project, as `registry.gitlab.com/acme/images`,
+or none.
+
+### dir
+
+`string`
+
+The folder of the image, `.` of the root.
+
+## Returns
+
+`string` \| `undefined`
+
+The repository, as `registry.gitlab.com/acme/images/base`; none of no registry image.

package/api/@wtf/release-oci/interfaces/OciImage.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / [@wtf/release-oci](../README.md) / OciImage
+
+# Interface: OciImage
+
+Defined in: [packages/release-oci/src/index.ts:27](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/index.ts#L27)
+
+An OCI image of the repo: one folder, built of one manifest.
+
+## Properties
+
+### dir
+
+> `readonly` **dir**: `string`
+
+Defined in: [packages/release-oci/src/index.ts:29](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/index.ts#L29)
+
+Its folder, from the root of the repo, as `images/base`; `.` of the root.
+
+***
+
+### manifest
+
+> `readonly` **manifest**: `string`
+
+Defined in: [packages/release-oci/src/index.ts:34](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/index.ts#L34)
+
+What it is built of, from the root of the repo: its `Dockerfile` or `Containerfile`, or its
+`.devcontainer/devcontainer.json`, as `images/base/Dockerfile`.
+
+***
+
+### repository
+
+> `readonly` **repository**: `string` \| `undefined`
+
+Defined in: [packages/release-oci/src/index.ts:40](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/index.ts#L40)
+
+The repository of the image in its registry, as `registry.gitlab.com/acme/images/base`: the
+registry image of the project, `CI_REGISTRY_IMAGE` of a pipeline, of the root, and that and
+the folder of an image of a folder; none where the environment names no registry image.