@wtf/release-docs 9.0.2 → 10.0.0

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

@@ -0,0 +1,38 @@
+[**Release trains**](../../README.md)
+
+***
+
+[Release trains](../../README.md) / @wtf/release-oci
+
+# @wtf/release-oci
+
+The OCI images of a repo released, of no release tool and no rebuild. Its default export is the
+ecosystem of OCI images, `ociEcosystem` of `./ecosystem`, a `ReleasingEcosystem` of
+`@wtf/release/contract`, which a config names in `ecosystems` as `'@wtf/release-oci'`, and a driver
+runs the steps of; and this module holds the type of an image, which the modules of this package
+do with: the images of the repo, each folder of a Dockerfile, a Containerfile or a
+`.devcontainer/devcontainer.json` (`./images`), the tags of a release checked (`./tags`), the
+tested image of each copied to the tag of its version, and the tags that move pointed at it, by
+crane (`./publish`), and the page of each in the container registry of GitLab (`./registry`). An
+image is built and tested by its own pipeline; a release copies the image it tested, by its
+digest, to the tags of its version, so the bytes released are the bytes tested. Each function
+takes the platform it runs by, of the folder of the repo as its working folder, and runs `git`
+and `crane` by it.
+
+```ts
+import type { OciImage } from '@wtf/release-oci'
+
+// The repositories of the images, as a release lists them.
+export const repositoriesOf = (images: readonly OciImage[]): (string | undefined)[] =>
+  images.map(({ repository }) => repository)
+```
+
+## Interfaces
+
+- [OciImage](interfaces/OciImage.md)
+
+## References
+
+### default
+
+Renames and re-exports [ociEcosystem](ecosystem/variables/ociEcosystem.md)

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

@@ -0,0 +1,56 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-oci/ecosystem
+
+# @wtf/release-oci/ecosystem
+
+The ecosystem of OCI images ([ociEcosystem](variables/ociEcosystem.md)), a `ReleasingEcosystem` of
+`@wtf/release/contract`, and the default export of the package, which a config names in
+`ecosystems` as `'@wtf/release-oci'`. Its read side: the images of the repo, each folder of a file
+an image is built of that git tracks ([packagesOfRepo](functions/packagesOfRepo.md)), of the working tree or of a commit;
+a repo of none has none. An image names no other image of the repo as a dependency: a `FROM` or a
+base pins a tag of a registry, not a package of the repo. A range of an image is a tag: a release
+publishes the version itself ([resolveTag](functions/resolveTag.md)), which takes that version alone
+([satisfiesTag](functions/satisfiesTag.md)).
+
+Its steps, each over the images of the plan it is given, of its options ([OciOptions](interfaces/OciOptions.md)):
+
+| Step      | What it does                                                               |
+| --------- | -------------------------------------------------------------------------- |
+| `verify`  | checks the version and the tags that move, and the repository of each      |
+| `smoke`   | finds the tested image of each by its digest, of the platforms asked       |
+| `publish` | copies the tested image of each, by its digest, to the tag of the version  |
+| `move`    | points the tags that move at the digest of the version                     |
+
+It writes nothing into git, so it has no `prepare`: the tags of the registry are the versions.
+
+```js
+// release.config.mjs
+export default {
+  trains: {
+    base: { paths: ['images/base'] },
+    release: { paths: ['images/release'] }
+  },
+  ecosystems: ['@wtf/release-oci']
+}
+```
+
+## Interfaces
+
+- [OciOptions](interfaces/OciOptions.md)
+- [OciPackage](interfaces/OciPackage.md)
+- [OciSourceOptions](interfaces/OciSourceOptions.md)
+
+## Variables
+
+- [ociEcosystem](variables/ociEcosystem.md)
+
+## Functions
+
+- [packagesOfImages](functions/packagesOfImages.md)
+- [packagesOfRepo](functions/packagesOfRepo.md)
+- [repositoriesOf](functions/repositoriesOf.md)
+- [resolveTag](functions/resolveTag.md)
+- [satisfiesTag](functions/satisfiesTag.md)

package/api/@wtf/release-oci/ecosystem/functions/packagesOfImages.md

@@ -0,0 +1,29 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / packagesOfImages
+
+# Function: packagesOfImages()
+
+> **packagesOfImages**(`images`): [`OciPackage`](../interfaces/OciPackage.md)[]
+
+Defined in: [packages/release-oci/src/ecosystem.ts:67](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L67)
+
+The images of the repo as a release reads them: each a package named by its repository, or by its
+folder where the environment names no registry image; of its folder and the file it is built of;
+published, as every image a pipeline builds is; and of no dependency.
+
+## Parameters
+
+### images
+
+readonly [`OciImage`](../../interfaces/OciImage.md)[]
+
+The images of the repo, as `readImages` of `./images` gives them.
+
+## Returns
+
+[`OciPackage`](../interfaces/OciPackage.md)[]
+
+The packages, one of each image, in the order of `images`.

package/api/@wtf/release-oci/ecosystem/functions/packagesOfRepo.md

@@ -0,0 +1,32 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / packagesOfRepo
+
+# Function: packagesOfRepo()
+
+> **packagesOfRepo**(`context`): `Promise`\<[`OciPackage`](../interfaces/OciPackage.md)[]\>
+
+Defined in: [packages/release-oci/src/ecosystem.ts:108](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L108)
+
+The images of the repo of `context` as a release reads them, of the commit `ref` where it names
+one, else of the working tree.
+
+## Parameters
+
+### context
+
+[`EcosystemContext`](../../../release/ecosystem/interfaces/EcosystemContext.md)
+
+The folder of the repo, the platform git runs by, and the commit.
+
+## Returns
+
+`Promise`\<[`OciPackage`](../interfaces/OciPackage.md)[]\>
+
+The packages, one of each image.
+
+## Throws
+
+`EGIT` of a commit git has not.

package/api/@wtf/release-oci/ecosystem/functions/repositoriesOf.md

@@ -0,0 +1,27 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / repositoriesOf
+
+# Function: repositoriesOf()
+
+> **repositoriesOf**(`packages`): `string`[]
+
+Defined in: [packages/release-oci/src/ecosystem.ts:152](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L152)
+
+The repository of each image of `packages`. Throws `EOCIIMAGE`, together, of each image of none.
+
+## Parameters
+
+### packages
+
+readonly [`OciPackage`](../interfaces/OciPackage.md)[]
+
+The images, as the ecosystem gives them.
+
+## Returns
+
+`string`[]
+
+The repository of each, in their order.

package/api/@wtf/release-oci/ecosystem/functions/resolveTag.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / resolveTag
+
+# Function: resolveTag()
+
+> **resolveTag**(`_range`, `version`): `string`
+
+Defined in: [packages/release-oci/src/ecosystem.ts:87](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L87)
+
+The tag a release publishes of an image of `version`, the version of the release: the version
+itself, as `1.4.0`. No image of the repo names another as a dependency, so a range is never read
+of a manifest.
+
+## Parameters
+
+### \_range
+
+`string`
+
+The tag before the release, as a manifest would write it.
+
+### version
+
+`string`
+
+The release of the image, as `1.4.0`.
+
+## Returns
+
+`string`
+
+The tag, as `1.4.0`.

package/api/@wtf/release-oci/ecosystem/functions/satisfiesTag.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / satisfiesTag
+
+# Function: satisfiesTag()
+
+> **satisfiesTag**(`tag`, `version`): `boolean`
+
+Defined in: [packages/release-oci/src/ecosystem.ts:97](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L97)
+
+Whether `version` is the one `tag` names: a tag of an image names one version, and a moving tag,
+as `1`, is no range a release reads.
+
+## Parameters
+
+### tag
+
+`string`
+
+A tag, as `1.4.0`.
+
+### version
+
+`string`
+
+A version, as `1.4.0`.
+
+## Returns
+
+`boolean`
+
+Whether they are the same version.

package/api/@wtf/release-oci/ecosystem/interfaces/OciOptions.md

@@ -0,0 +1,64 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / OciOptions
+
+# Interface: OciOptions
+
+Defined in: [packages/release-oci/src/ecosystem.ts:126](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L126)
+
+The options of the ecosystem of OCI images, which a driver gives each step.
+
+## Properties
+
+### crane?
+
+> `readonly` `optional` **crane?**: `string`
+
+Defined in: [packages/release-oci/src/ecosystem.ts:138](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L138)
+
+The command of crane, by its name on the path or its path: `crane` by default.
+
+***
+
+### moving
+
+> `readonly` **moving**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/ecosystem.ts:132](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L132)
+
+The tags that move to the version of the release, as `['1.4', '1']` of `1.4.2`, or
+`['12.12', 'latest']` of `12.12-wtf.1`: `[]` of none. The ecosystem derives none: its caller
+names them by its own rules.
+
+***
+
+### platforms?
+
+> `readonly` `optional` **platforms?**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/ecosystem.ts:136](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L136)
+
+The platforms each tested image must be of, as `linux/amd64`: any by default.
+
+***
+
+### registry?
+
+> `readonly` `optional` **registry?**: [`ContainerRegistry`](../../registry/interfaces/ContainerRegistry.md)
+
+Defined in: [packages/release-oci/src/ecosystem.ts:143](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L143)
+
+The container registry of GitLab that `publish` asks the page of each image of: none by
+default, of an image of no page, which the forge of the release is asked of.
+
+***
+
+### source?
+
+> `readonly` `optional` **source?**: [`OciSourceOptions`](OciSourceOptions.md)
+
+Defined in: [packages/release-oci/src/ecosystem.ts:134](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L134)
+
+The tested image of each image, which `smoke` finds and `publish` copies.

package/api/@wtf/release-oci/ecosystem/interfaces/OciPackage.md

@@ -0,0 +1,97 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / OciPackage
+
+# Interface: OciPackage
+
+Defined in: [packages/release-oci/src/ecosystem.ts:54](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L54)
+
+An image as a release reads it: a package of the ecosystem, and the image it is of.
+
+## Extends
+
+- [`Package`](../../../release/ecosystem/interfaces/Package.md)
+
+## Properties
+
+### dependencies
+
+> `readonly` **dependencies**: readonly [`Dependency`](../../../release/ecosystem/interfaces/Dependency.md)[]
+
+Defined in: [packages/release/src/ecosystem.ts:74](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/ecosystem.ts#L74)
+
+Its dependencies on the other packages of its ecosystem in the repo.
+
+#### Inherited from
+
+[`Package`](../../../release/ecosystem/interfaces/Package.md).[`dependencies`](../../../release/ecosystem/interfaces/Package.md#dependencies)
+
+***
+
+### dir
+
+> `readonly` **dir**: `string`
+
+Defined in: [packages/release/src/ecosystem.ts:65](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/ecosystem.ts#L65)
+
+Its folder, from the root of the repo, as `packages/core`; `.` of the root. A part of the repo,
+as a train, holds it when its paths hold this folder.
+
+#### Inherited from
+
+[`Package`](../../../release/ecosystem/interfaces/Package.md).[`dir`](../../../release/ecosystem/interfaces/Package.md#dir)
+
+***
+
+### image
+
+> `readonly` **image**: [`OciImage`](../../interfaces/OciImage.md)
+
+Defined in: [packages/release-oci/src/ecosystem.ts:56](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L56)
+
+The image, as `readImages` of `./images` gives it.
+
+***
+
+### manifest
+
+> `readonly` **manifest**: `string`
+
+Defined in: [packages/release/src/ecosystem.ts:67](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/ecosystem.ts#L67)
+
+Its manifest, from the root of the repo, as `packages/core/package.json`.
+
+#### Inherited from
+
+[`Package`](../../../release/ecosystem/interfaces/Package.md).[`manifest`](../../../release/ecosystem/interfaces/Package.md#manifest)
+
+***
+
+### name
+
+> `readonly` **name**: `string`
+
+Defined in: [packages/release/src/ecosystem.ts:60](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/ecosystem.ts#L60)
+
+Its name, the one its ecosystem's registry knows it by: unique of the ecosystem in the repo.
+
+#### Inherited from
+
+[`Package`](../../../release/ecosystem/interfaces/Package.md).[`name`](../../../release/ecosystem/interfaces/Package.md#name)
+
+***
+
+### published
+
+> `readonly` **published**: `boolean`
+
+Defined in: [packages/release/src/ecosystem.ts:72](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release/src/ecosystem.ts#L72)
+
+Whether a release publishes it: not of an npm package that is private, nor of a crate of
+`publish = false`.
+
+#### Inherited from
+
+[`Package`](../../../release/ecosystem/interfaces/Package.md).[`published`](../../../release/ecosystem/interfaces/Package.md#published)

package/api/@wtf/release-oci/ecosystem/interfaces/OciSourceOptions.md

@@ -0,0 +1,32 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / OciSourceOptions
+
+# Interface: OciSourceOptions
+
+Defined in: [packages/release-oci/src/ecosystem.ts:115](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L115)
+
+The tested image of each image of a release: where the pipeline that tested it pushed it.
+
+## Properties
+
+### repository
+
+> `readonly` **repository**: `string`
+
+Defined in: [packages/release-oci/src/ecosystem.ts:120](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L120)
+
+The repository of the tested image of each image, `{image}` its repository, as
+`{image}/snapshot`.
+
+***
+
+### tag
+
+> `readonly` **tag**: `string`
+
+Defined in: [packages/release-oci/src/ecosystem.ts:122](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L122)
+
+Its tag, as `base-v1-4-2`, the snapshot of the pipeline of the tag of the release.

package/api/@wtf/release-oci/ecosystem/variables/ociEcosystem.md

@@ -0,0 +1,29 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/ecosystem](../README.md) / ociEcosystem
+
+# Variable: ociEcosystem
+
+> `const` **ociEcosystem**: [`ReleasingEcosystem`](../../../release/contract/type-aliases/ReleasingEcosystem.md)\<[`OciOptions`](../interfaces/OciOptions.md), [`OciPackage`](../interfaces/OciPackage.md), `"verify"` \| `"smoke"` \| `"move"`\>
+
+Defined in: [packages/release-oci/src/ecosystem.ts:232](https://gitlab.com/wetryfun/release/release/-/blob/27c0c9bead8eea4a721e18a0cbd2724080f82e69/packages/release-oci/src/ecosystem.ts#L232)
+
+The ecosystem of OCI images: its packages, the images of the repo, of the working tree or of a
+commit ([packagesOfRepo](../functions/packagesOfRepo.md)); a tag published as the version ([resolveTag](../functions/resolveTag.md)); a tag of
+one version ([satisfiesTag](../functions/satisfiesTag.md)); and the steps of a release of its images, each there:
+
+- `verify` checks that the version and each tag that moves is a tag of an image, none given twice
+  (`EOCIVERSION`), and that each image has a repository (`EOCIIMAGE`), together; it asks the
+  registry nothing;
+- `smoke` finds the tested image of each image by its digest, of the platforms of `platforms`
+  (`EOCISMOKE`), as `smokeImages` of `./publish` does;
+- `publish` copies the tested image of each image, by its digest, to the tag of the version,
+  skipped of a registry that has it at the same digest and refused at another (`EOCIRETAG`), as
+  `publishImages` of `./publish` does; then asks the page of each of the container registry of
+  `registry` (`EOCILINK`), and gives each image, by its repository; a dry run asks the registry,
+  and copies and asks GitLab nothing;
+- `move` points the tags of `moving` of each image at the digest the registry has of the version,
+  as `moveImages` of `./publish` does (`EOCIMOVE`), and gives each image it moved; a dry run asks
+  the registry, and copies nothing.

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

@@ -0,0 +1,24 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-oci/errors
+
+# @wtf/release-oci/errors
+
+What the release of OCI images throws: [OciError](classes/OciError.md), a `ReleaseError` of `@wtf/release/errors`
+of the codes of [OCI\_ERRORS](variables/OCI_ERRORS.md), beside the codes of the options of a plugin, its
+`RELEASE_ERRORS` (`EOPTIONS`). What is the same of every ecosystem, as the plan of a release, is
+its driver's own.
+
+## Classes
+
+- [OciError](classes/OciError.md)
+
+## Type Aliases
+
+- [OciErrorCode](type-aliases/OciErrorCode.md)
+
+## Variables
+
+- [OCI\_ERRORS](variables/OCI_ERRORS.md)