@wtf/release-oci 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mikael Karon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,137 @@
1
- # Temporary Holding Version
1
+ # @wtf/release-oci
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Releases the OCI images of a repo in trains, with no release tool and no rebuild. A pipeline builds
4
+ and tests an image; a release copies that tested image, by its digest, to the tags of its version
5
+ in the registry, so the bytes released are the bytes tested. This library reads the images of a
6
+ repo for the trains, finds the tested image of each, and copies it to the tags of a release by
7
+ [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md). It is the
8
+ library of [`@wtf/semantic-release-oci`](../semantic-release-oci/README.md), with no dependency on
9
+ semantic-release; each function runs `git` and `crane` by the `System` of
10
+ [`@wtf/release-system/system`](../release-system/README.md) its caller gives it.
11
+
12
+ ## The ecosystem
13
+
14
+ Its default export is the ecosystem of OCI images, `ociEcosystem` of `./ecosystem`, an `Ecosystem`
15
+ of [`@wtf/release-trains/ecosystem`](../release-trains/README.md), which a config names in
16
+ `ecosystems` as `'@wtf/release-oci'`. The trains then read the images of the repo as they read npm
17
+ packages and crates: which train holds each, the order of the trains, and the checks of a release
18
+ ([Ecosystems](../docs/guides/ecosystems.md)).
19
+
20
+ - `packages` gives a package for each folder of a file an image is built of that git tracks: a
21
+ `Dockerfile` or a `Containerfile`, or a `.devcontainer/devcontainer.json`, which the devcontainer
22
+ CLI builds. A folder of more than one of them is one image. Its name is its repository in the
23
+ registry: the registry image of the project, `CI_REGISTRY_IMAGE` of a pipeline, for an image at
24
+ the root, and that and its folder for another, as GitLab names the images of a project; its
25
+ folder where the environment names no registry image. Every image is published, and none depends
26
+ on another: a `FROM` or a base pins a tag of a registry, not a package of the repo. It reads the
27
+ working tree by default, or a commit by `git ls-tree`.
28
+ - `resolve` gives the tag a release publishes, the version itself: `1.4.0` for `1.4.0`.
29
+ - `satisfies` takes a tag of the one version it names.
30
+
31
+ ```ts
32
+ import oci from '@wtf/release-oci'
33
+ import type { System } from '@wtf/release-system/system'
34
+
35
+ oci.resolve('0.0.0', '1.4.0') // '1.4.0'
36
+ oci.satisfies('1.4.0', '1.4.0') // true
37
+
38
+ /** The images of the repo at the tag of a release, as the trains read them. */
39
+ export const imagesAt = (system: System, tag: string) => oci.packages({ system, ref: tag })
40
+ ```
41
+
42
+ ## What a release of images is
43
+
44
+ No version is written into git: the tags of the registry are the versions. A release of a train
45
+ does this:
46
+
47
+ - `readImages` (`./images`) reads the images of the files git tracks; `imagesAt` reads them at a
48
+ commit.
49
+ - `ownersOf` of `@wtf/release-trains/packages` gives each image its train.
50
+ - `smokeImages` (`./publish`) finds the tested image of each, its source, by its digest
51
+ (`crane digest`), and the platforms of its index (`crane manifest`). A source the registry has
52
+ not, or of fewer platforms than the release asks, fails (`EOCISMOKE`).
53
+ - `publishImages` copies the digest of each source to the tags the release gives
54
+ (`crane copy <source>@<digest> <image>:<tag>`), which mounts each blob of the source's repository
55
+ rather than moving it. The tag of the version is copied once: a registry that has it at the same
56
+ digest is skipped, so a release that stopped part way is finished by running it again, and at
57
+ another digest is refused (`EOCIRETAG`), as a released version never moves.
58
+ - `registryPageOf` (`./registry`) gives the page of each image in the container registry of GitLab,
59
+ which the GitLab release of the tag links it by.
60
+
61
+ ## The tags of a release
62
+
63
+ `tagsOfRelease` (`./tags`) gives the version, and of a release, the minor and the major, which move
64
+ to each release of their line, so a consumer that pins `1` takes each fix and feature of 1.x:
65
+
66
+ | Version | Tags |
67
+ | -------------- | ------------------- |
68
+ | `1.4.2` | `1.4.2`, `1.4`, `1` |
69
+ | `0.3.1` | `0.3.1`, `0.3` |
70
+ | `8.0.0-next.1` | `8.0.0-next.1` |
71
+
72
+ A minor of the major `0` breaks what the one before gave, so a release of `0.x` moves its minor
73
+ alone; a prerelease moves no tag.
74
+
75
+ `publishImages` takes the tags of a release as they are given: `version`, the tag that is copied
76
+ once and never moved, and `moving`, each tag copied on every run, `[]` of none. It derives none:
77
+ `releaseTagsOf` gives those of a semver version, as the plugin passes them, and a release of a
78
+ version that is no semver, as `12.12-wtf.1` of an image of Debian 12.12, names its own. Each is a tag
79
+ an image can have, `[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}`, none given twice, as `checkReleaseTags`
80
+ checks before anything is asked of the registry.
81
+
82
+ ```ts
83
+ import { publishImages } from '@wtf/release-oci/publish'
84
+ import type { System } from '@wtf/release-system/system'
85
+
86
+ /** The base image of Debian 12.12, its first build of ours, as `12.12-wtf.1`, `12.12` and `latest`. */
87
+ export const release = (system: System, source: string) =>
88
+ publishImages({
89
+ context: { system },
90
+ images: [
91
+ {
92
+ repository: 'registry.gitlab.com/acme/images/base',
93
+ source: { repository: 'registry.gitlab.com/acme/images/base', tag: source }
94
+ }
95
+ ],
96
+ version: '12.12-wtf.1',
97
+ moving: ['12.12', 'latest']
98
+ })
99
+ ```
100
+
101
+ ```ts
102
+ import { tagsOfRelease } from '@wtf/release-oci/tags'
103
+
104
+ export const tags = tagsOfRelease('1.4.2') // ['1.4.2', '1.4', '1']
105
+ ```
106
+
107
+ ## The version in an image
108
+
109
+ A release stamps nothing: the image a pipeline tested is the image it publishes. A pipeline that
110
+ labels an image of the version it will be, as `org.opencontainers.image.version`, reads the next
111
+ version of its train of the dotenv `semantic-release-info` of
112
+ [`@wtf/semantic-release-trains`](../semantic-release-trains/README.md) writes, and passes it to the
113
+ build as an argument of its own.
114
+
115
+ ## Subpaths
116
+
117
+ | Subpath | What it is |
118
+ | ------------- | ---------------------------------------------------------------------------------- |
119
+ | `.` | `OciImage`, and the ecosystem as the default export |
120
+ | `./ecosystem` | `ociEcosystem`, `packagesOfImages`, `packagesOfRepo`, `resolveTag`, `satisfiesTag` |
121
+ | `./images` | `readImages`, `imagesAt`, `imagesOf`, `imageDirOf`, `repositoryOf` |
122
+ | `./tags` | `tagsOfRelease`, `releaseTagsOf`, `checkReleaseTags` |
123
+ | `./publish` | `smokeImages`, `publishImages`, `digestOf`, `platformsOf` |
124
+ | `./registry` | `registryPageOf` |
125
+ | `./errors` | `OciError`, `OCI_ERRORS` |
126
+
127
+ ## Errors
128
+
129
+ | Code | Means |
130
+ | --------------- | ----------------------------------------------------------------------------- |
131
+ | `EOCIECOSYSTEM` | `ecosystems` lists neither `@wtf/semantic-release-oci/ecosystem` nor this |
132
+ | `EOCIIMAGE` | An image has no repository: neither `image` nor `CI_REGISTRY_IMAGE` names one |
133
+ | `EOCISOURCE` | The tested image has no tag: neither `sourceTag` nor `CI_COMMIT_REF_SLUG` |
134
+ | `EOCISMOKE` | The registry has not the tested image, or crane cannot ask it |
135
+ | `EOCIRETAG` | The registry has the version already, at another digest |
136
+ | `EOCITAG` | crane cannot copy the tested image to a tag |
137
+ | `EOCILINK` | GitLab cannot give the page of an image in its container registry |
@@ -0,0 +1,74 @@
1
+ /**
2
+ * The ecosystem of OCI images ({@link ociEcosystem}), as the trains read it, and the default export
3
+ * of the package, which a config names in `ecosystems` as `'@wtf/release-oci'`: the images of the
4
+ * repo, each folder of a file an image is built of that git tracks ({@link packagesOfRepo}), of the
5
+ * working tree or of a commit; a repo of none has none. An image names no other image of the repo
6
+ * as a dependency the trains could read: a `FROM` or a base pins a tag of a registry, not a package
7
+ * of the repo. A range of an image is a tag: a release publishes the version itself
8
+ * ({@link resolveTag}), which takes that version alone ({@link satisfiesTag}).
9
+ *
10
+ * ```js
11
+ * // release.config.mjs
12
+ * export default {
13
+ * trains: {
14
+ * base: { paths: ['images/base'] },
15
+ * release: { paths: ['images/release'] }
16
+ * },
17
+ * ecosystems: ['@wtf/release-oci']
18
+ * }
19
+ * ```
20
+ *
21
+ * @packageDocumentation
22
+ * @module @wtf/release-oci/ecosystem
23
+ */
24
+ import type { Ecosystem, EcosystemContext, Package } from '@wtf/release-trains/ecosystem';
25
+ import type { OciImage } from './index.ts';
26
+ /** An image as the trains read it: a package of the trains, and the image it is of. */
27
+ export interface OciPackage extends Package {
28
+ /** The image, as `readImages` of `./images` gives it. */
29
+ readonly image: OciImage;
30
+ }
31
+ /**
32
+ * The images of the repo as the trains read them: each a package named by its repository, or by its
33
+ * folder where the environment names no registry image; of its folder and the file it is built of;
34
+ * published, as every image a pipeline builds is; and of no dependency.
35
+ *
36
+ * @param images - The images of the repo, as `readImages` of `./images` gives them.
37
+ * @returns The packages, one of each image, in the order of `images`.
38
+ */
39
+ export declare function packagesOfImages(images: readonly OciImage[]): OciPackage[];
40
+ /**
41
+ * The tag a release publishes of an image of `version`, the release of its train: the version
42
+ * itself, as `1.4.0`. No image of the repo names another as a dependency, so a range is never read
43
+ * of a manifest.
44
+ *
45
+ * @param _range - The tag before the release, as a manifest would write it.
46
+ * @param version - The release of the image, as `1.4.0`.
47
+ * @returns The tag, as `1.4.0`.
48
+ */
49
+ export declare const resolveTag: (_range: string, version: string) => string;
50
+ /**
51
+ * Whether `version` is the one `tag` names: a tag of an image names one version, and a moving tag,
52
+ * as `1`, is no range the trains read.
53
+ *
54
+ * @param tag - A tag, as `1.4.0`.
55
+ * @param version - A version, as `1.4.0`.
56
+ * @returns Whether they are the same version.
57
+ */
58
+ export declare const satisfiesTag: (tag: string, version: string) => boolean;
59
+ /**
60
+ * The images of the repo of `context` as the trains read them, of the commit `ref` where it names
61
+ * one, else of the working tree.
62
+ *
63
+ * @param context - The folder of the repo, its environment, the system, and the commit.
64
+ * @returns The packages, one of each image.
65
+ * @throws `EGIT` of a commit git has not.
66
+ */
67
+ export declare function packagesOfRepo(context: EcosystemContext): Promise<OciPackage[]>;
68
+ /**
69
+ * The ecosystem of OCI images: its packages, the images of the repo, of the working tree or of a
70
+ * commit ({@link packagesOfRepo}); a tag published as the version ({@link resolveTag}); and a tag
71
+ * of one version ({@link satisfiesTag}).
72
+ */
73
+ export declare const ociEcosystem: Ecosystem;
74
+ //# sourceMappingURL=ecosystem.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ecosystem.d.ts","sourceRoot":"","sources":["../src/ecosystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAA;AAEzF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1C,uFAAuF;AACvF,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,UAAU,EAAE,CAS1E;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAAiB,CAAA;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,OACP,CAAA;AAErD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAIrF;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAK1B,CAAA"}
@@ -0,0 +1,61 @@
1
+ import { imagesAt, readImages } from "./images.js";
2
+ /**
3
+ * The images of the repo as the trains read them: each a package named by its repository, or by its
4
+ * folder where the environment names no registry image; of its folder and the file it is built of;
5
+ * published, as every image a pipeline builds is; and of no dependency.
6
+ *
7
+ * @param images - The images of the repo, as `readImages` of `./images` gives them.
8
+ * @returns The packages, one of each image, in the order of `images`.
9
+ */
10
+ export function packagesOfImages(images) {
11
+ return images.map((image) => ({
12
+ name: image.repository ?? image.dir,
13
+ dir: image.dir,
14
+ manifest: image.manifest,
15
+ published: true,
16
+ dependencies: [],
17
+ image
18
+ }));
19
+ }
20
+ /**
21
+ * The tag a release publishes of an image of `version`, the release of its train: the version
22
+ * itself, as `1.4.0`. No image of the repo names another as a dependency, so a range is never read
23
+ * of a manifest.
24
+ *
25
+ * @param _range - The tag before the release, as a manifest would write it.
26
+ * @param version - The release of the image, as `1.4.0`.
27
+ * @returns The tag, as `1.4.0`.
28
+ */
29
+ export const resolveTag = (_range, version) => version;
30
+ /**
31
+ * Whether `version` is the one `tag` names: a tag of an image names one version, and a moving tag,
32
+ * as `1`, is no range the trains read.
33
+ *
34
+ * @param tag - A tag, as `1.4.0`.
35
+ * @param version - A version, as `1.4.0`.
36
+ * @returns Whether they are the same version.
37
+ */
38
+ export const satisfiesTag = (tag, version) => tag.replace(/^v/, '') === version.replace(/^v/, '');
39
+ /**
40
+ * The images of the repo of `context` as the trains read them, of the commit `ref` where it names
41
+ * one, else of the working tree.
42
+ *
43
+ * @param context - The folder of the repo, its environment, the system, and the commit.
44
+ * @returns The packages, one of each image.
45
+ * @throws `EGIT` of a commit git has not.
46
+ */
47
+ export async function packagesOfRepo(context) {
48
+ return packagesOfImages(context.ref === undefined ? await readImages(context) : await imagesAt(context.ref, context));
49
+ }
50
+ /**
51
+ * The ecosystem of OCI images: its packages, the images of the repo, of the working tree or of a
52
+ * commit ({@link packagesOfRepo}); a tag published as the version ({@link resolveTag}); and a tag
53
+ * of one version ({@link satisfiesTag}).
54
+ */
55
+ export const ociEcosystem = {
56
+ name: 'oci',
57
+ packages: packagesOfRepo,
58
+ resolve: resolveTag,
59
+ satisfies: satisfiesTag
60
+ };
61
+ //# sourceMappingURL=ecosystem.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ecosystem.js","sourceRoot":"","sources":["../src/ecosystem.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAQlD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA2B;IAC1D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,IAAI,EAAE,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,GAAG;QACnC,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,IAAI;QACf,YAAY,EAAE,EAAE;QAChB,KAAK;KACN,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAc,EAAE,OAAe,EAAU,EAAE,CAAC,OAAO,CAAA;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAE,OAAe,EAAW,EAAE,CACpE,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAyB;IAC5D,OAAO,gBAAgB,CACrB,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAC7F,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,KAAK;IACX,QAAQ,EAAE,cAAc;IACxB,OAAO,EAAE,UAAU;IACnB,SAAS,EAAE,YAAY;CACxB,CAAA"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * What the release of OCI images throws: {@link OciError}, a `ReleaseError` of
3
+ * `@wtf/release-system/errors` of the codes of {@link OCI_ERRORS}, which semantic-release prints by
4
+ * its mark, beside the codes of the options of a plugin, its `SYSTEM_ERRORS` (`EOPTIONS`). What is
5
+ * the same of every ecosystem, as a package of two trains, is the trains' own, `TRAINS_ERRORS` of
6
+ * `@wtf/release-trains/errors`.
7
+ *
8
+ * @packageDocumentation
9
+ * @module @wtf/release-oci/errors
10
+ */
11
+ import { ReleaseError } from '@wtf/release-system/errors';
12
+ /** The codes of the errors of the OCI images, each with what it means. */
13
+ export declare const OCI_ERRORS: {
14
+ readonly EOCIECOSYSTEM: "The `ecosystems` of the config lists neither `@wtf/semantic-release-oci/ecosystem` nor `@wtf/release-oci`, so the trains read no image.";
15
+ readonly EOCIIMAGE: "The repository of an image cannot be named: neither the option `image` nor `CI_REGISTRY_IMAGE` of the environment gives one.";
16
+ 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.";
17
+ 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.";
18
+ readonly EOCIRETAG: "The registry has the full version of a release already, at another digest: a released version is never moved.";
19
+ readonly EOCITAG: "crane cannot copy the tested image to a tag of the release.";
20
+ readonly EOCILINK: "The container registry of GitLab cannot be asked the page of an image, or lists none.";
21
+ };
22
+ /** A code of {@link OCI_ERRORS}. */
23
+ export type OciErrorCode = keyof typeof OCI_ERRORS;
24
+ /**
25
+ * An error of the OCI images, or of the options of the plugin over them: a stable `code`, of
26
+ * {@link OCI_ERRORS} or of `SYSTEM_ERRORS` of `@wtf/release-system/errors`, its `message` what is
27
+ * wrong, and its `details` how to fix it.
28
+ */
29
+ export declare class OciError extends ReleaseError {
30
+ }
31
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAEzD,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;CAab,CAAA;AAEV,oCAAoC;AACpC,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,UAAU,CAAA;AAElD;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,YAAY;CAAG"}
package/dist/errors.js ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * What the release of OCI images throws: {@link OciError}, a `ReleaseError` of
3
+ * `@wtf/release-system/errors` of the codes of {@link OCI_ERRORS}, which semantic-release prints by
4
+ * its mark, beside the codes of the options of a plugin, its `SYSTEM_ERRORS` (`EOPTIONS`). What is
5
+ * the same of every ecosystem, as a package of two trains, is the trains' own, `TRAINS_ERRORS` of
6
+ * `@wtf/release-trains/errors`.
7
+ *
8
+ * @packageDocumentation
9
+ * @module @wtf/release-oci/errors
10
+ */
11
+ import { ReleaseError } from '@wtf/release-system/errors';
12
+ /** The codes of the errors of the OCI images, each with what it means. */
13
+ export const OCI_ERRORS = {
14
+ EOCIECOSYSTEM: 'The `ecosystems` of the config lists neither `@wtf/semantic-release-oci/ecosystem` nor `@wtf/release-oci`, so the trains read no image.',
15
+ EOCIIMAGE: 'The repository of an image cannot be named: neither the option `image` nor `CI_REGISTRY_IMAGE` of the environment gives one.',
16
+ 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.',
17
+ 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.',
18
+ EOCIRETAG: 'The registry has the full version of a release already, at another digest: a released version is never moved.',
19
+ EOCITAG: 'crane cannot copy the tested image to a tag of the release.',
20
+ EOCILINK: 'The container registry of GitLab cannot be asked the page of an image, or lists none.'
21
+ };
22
+ /**
23
+ * An error of the OCI images, or of the options of the plugin over them: a stable `code`, of
24
+ * {@link OCI_ERRORS} or of `SYSTEM_ERRORS` of `@wtf/release-system/errors`, its `message` what is
25
+ * wrong, and its `details` how to fix it.
26
+ */
27
+ export class OciError extends ReleaseError {
28
+ }
29
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAEzD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,aAAa,EACX,yIAAyI;IAC3I,SAAS,EACP,8HAA8H;IAChI,UAAU,EACR,0IAA0I;IAC5I,SAAS,EACP,kIAAkI;IACpI,SAAS,EACP,+GAA+G;IACjH,OAAO,EAAE,6DAA6D;IACtE,QAAQ,EAAE,uFAAuF;CACzF,CAAA;AAKV;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;CAAG"}
@@ -0,0 +1,87 @@
1
+ /**
2
+ * The OCI images of a repo: {@link readImages} reads each image of the working tree, and
3
+ * {@link imagesAt} each of a commit, of the files git tracks. An image is a folder that holds what
4
+ * it is built of ({@link isImageManifest}): a `Dockerfile` or a `Containerfile`, or a
5
+ * `.devcontainer/devcontainer.json`, which the devcontainer CLI builds; a folder of both is one image.
6
+ * Its repository in the registry is the registry image of the project, `CI_REGISTRY_IMAGE` of a
7
+ * pipeline, of the root, and that and its folder of another ({@link repositoryOf}), as GitLab names
8
+ * the images of a project.
9
+ *
10
+ * ```ts
11
+ * import { readImages } from '@wtf/release-oci/images'
12
+ * import type { System } from '@wtf/release-system'
13
+ *
14
+ * // The folders of the images of the repo.
15
+ * export async function folders(system: System): Promise<string[]> {
16
+ * return (await readImages({ system })).map(({ dir }) => dir)
17
+ * }
18
+ * ```
19
+ *
20
+ * @packageDocumentation
21
+ * @module @wtf/release-oci/images
22
+ */
23
+ import { type GitContext } from '@wtf/release-system/git';
24
+ import type { OciImage } from './index.ts';
25
+ /**
26
+ * The folder of the image `file` is built of: of a `Dockerfile` or a `Containerfile`, its folder; of
27
+ * a `.devcontainer/devcontainer.json`, the folder above `.devcontainer`; of any other file, none.
28
+ *
29
+ * @param file - A file of the repo, from its root.
30
+ * @returns The folder of its image, `.` of the root; none of a file no image is built of.
31
+ */
32
+ export declare function imageDirOf(file: string): string | undefined;
33
+ /**
34
+ * Whether `file`, a file of the repo, is what an image is built of (see {@link imageDirOf}).
35
+ *
36
+ * @param file - The file, from the root of the repo.
37
+ * @returns Whether it is.
38
+ */
39
+ export declare const isImageManifest: (file: string) => boolean;
40
+ /**
41
+ * The repository of the image of `dir` in the registry of `registryImage`, the registry image of
42
+ * the project: that of the root, and that and the folder of another.
43
+ *
44
+ * @param registryImage - The registry image of the project, as `registry.gitlab.com/acme/images`,
45
+ * or none.
46
+ * @param dir - The folder of the image, `.` of the root.
47
+ * @returns The repository, as `registry.gitlab.com/acme/images/base`; none of no registry image.
48
+ */
49
+ export declare function repositoryOf(registryImage: string | undefined, dir: string): string | undefined;
50
+ /**
51
+ * The images of `files`, the files of the repo: one of each folder that holds what an image is
52
+ * built of, of the first such file of it, in the order of their folders.
53
+ *
54
+ * @param files - The files of the repo, from its root.
55
+ * @param registryImage - The registry image of the project, which names the repository of each.
56
+ * @returns The images, by their folders.
57
+ */
58
+ export declare function imagesOf(files: readonly string[], registryImage: string | undefined): OciImage[];
59
+ /**
60
+ * The registry image of the project of `context`, as GitLab gives a pipeline it:
61
+ * `CI_REGISTRY_IMAGE` of the environment; none of none.
62
+ *
63
+ * @param context - The environment of the run, of its system.
64
+ * @returns The registry image, or none.
65
+ */
66
+ export declare function registryImageOf(context: GitContext): string | undefined;
67
+ /**
68
+ * The images of the repo of `context`: each folder of the working tree that git tracks a file an
69
+ * image is built of in.
70
+ *
71
+ * @param context - The folder of the repo, its environment, and the system git runs by.
72
+ * @param registryImage - The registry image of the project: {@link registryImageOf} by default.
73
+ * @returns The images, by their folders.
74
+ */
75
+ export declare function readImages(context: GitContext, registryImage?: string | undefined): Promise<OciImage[]>;
76
+ /**
77
+ * The images of the repo of `context` at the commit `ref`: each folder of its tree that holds a file
78
+ * an image is built of, by `git ls-tree`.
79
+ *
80
+ * @param ref - The commit, as `HEAD` or the tag of a release.
81
+ * @param context - The folder of the repo, its environment, and the system git runs by.
82
+ * @param registryImage - The registry image of the project: {@link registryImageOf} by default.
83
+ * @returns The images, by their folders.
84
+ * @throws `EGIT` of a commit git has not.
85
+ */
86
+ export declare function imagesAt(ref: string, context: GitContext, registryImage?: string | undefined): Promise<OciImage[]>;
87
+ //# sourceMappingURL=images.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"images.d.ts","sourceRoot":"","sources":["../src/images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAO,KAAK,UAAU,EAAuB,MAAM,yBAAyB,CAAA;AAGnF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAQ1C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAAyC,CAAA;AAExF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/F;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,EAAE,CAShG;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,UAAU,EACnB,aAAa,GAAE,MAAM,GAAG,SAAoC,GAC3D,OAAO,CAAC,QAAQ,EAAE,CAAC,CAErB;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,UAAU,EACnB,aAAa,GAAE,MAAM,GAAG,SAAoC,GAC3D,OAAO,CAAC,QAAQ,EAAE,CAAC,CAKrB"}
package/dist/images.js ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * The OCI images of a repo: {@link readImages} reads each image of the working tree, and
3
+ * {@link imagesAt} each of a commit, of the files git tracks. An image is a folder that holds what
4
+ * it is built of ({@link isImageManifest}): a `Dockerfile` or a `Containerfile`, or a
5
+ * `.devcontainer/devcontainer.json`, which the devcontainer CLI builds; a folder of both is one image.
6
+ * Its repository in the registry is the registry image of the project, `CI_REGISTRY_IMAGE` of a
7
+ * pipeline, of the root, and that and its folder of another ({@link repositoryOf}), as GitLab names
8
+ * the images of a project.
9
+ *
10
+ * ```ts
11
+ * import { readImages } from '@wtf/release-oci/images'
12
+ * import type { System } from '@wtf/release-system'
13
+ *
14
+ * // The folders of the images of the repo.
15
+ * export async function folders(system: System): Promise<string[]> {
16
+ * return (await readImages({ system })).map(({ dir }) => dir)
17
+ * }
18
+ * ```
19
+ *
20
+ * @packageDocumentation
21
+ * @module @wtf/release-oci/images
22
+ */
23
+ import { git, gitOf, trackedFiles } from '@wtf/release-system/git';
24
+ import { basenameOf, dirnameOf } from '@wtf/release-system/posix';
25
+ /** The names of the files an image is built of, at the root of its folder. */
26
+ const BUILD_FILES = new Set(['Dockerfile', 'Containerfile']);
27
+ /** The file of a devcontainer the devcontainer CLI builds, from the folder of its image. */
28
+ const DEVCONTAINER = '.devcontainer/devcontainer.json';
29
+ /**
30
+ * The folder of the image `file` is built of: of a `Dockerfile` or a `Containerfile`, its folder; of
31
+ * a `.devcontainer/devcontainer.json`, the folder above `.devcontainer`; of any other file, none.
32
+ *
33
+ * @param file - A file of the repo, from its root.
34
+ * @returns The folder of its image, `.` of the root; none of a file no image is built of.
35
+ */
36
+ export function imageDirOf(file) {
37
+ if (BUILD_FILES.has(basenameOf(file)))
38
+ return dirnameOf(file);
39
+ if (file === DEVCONTAINER)
40
+ return '.';
41
+ if (file.endsWith(`/${DEVCONTAINER}`))
42
+ return file.slice(0, -DEVCONTAINER.length - 1);
43
+ return undefined;
44
+ }
45
+ /**
46
+ * Whether `file`, a file of the repo, is what an image is built of (see {@link imageDirOf}).
47
+ *
48
+ * @param file - The file, from the root of the repo.
49
+ * @returns Whether it is.
50
+ */
51
+ export const isImageManifest = (file) => imageDirOf(file) !== undefined;
52
+ /**
53
+ * The repository of the image of `dir` in the registry of `registryImage`, the registry image of
54
+ * the project: that of the root, and that and the folder of another.
55
+ *
56
+ * @param registryImage - The registry image of the project, as `registry.gitlab.com/acme/images`,
57
+ * or none.
58
+ * @param dir - The folder of the image, `.` of the root.
59
+ * @returns The repository, as `registry.gitlab.com/acme/images/base`; none of no registry image.
60
+ */
61
+ export function repositoryOf(registryImage, dir) {
62
+ if (registryImage === undefined || registryImage === '')
63
+ return undefined;
64
+ const base = registryImage.replace(/\/+$/, '');
65
+ return dir === '.' ? base : `${base}/${dir}`;
66
+ }
67
+ /**
68
+ * The images of `files`, the files of the repo: one of each folder that holds what an image is
69
+ * built of, of the first such file of it, in the order of their folders.
70
+ *
71
+ * @param files - The files of the repo, from its root.
72
+ * @param registryImage - The registry image of the project, which names the repository of each.
73
+ * @returns The images, by their folders.
74
+ */
75
+ export function imagesOf(files, registryImage) {
76
+ const manifests = new Map();
77
+ for (const file of [...files].toSorted()) {
78
+ const dir = imageDirOf(file);
79
+ if (dir !== undefined && !manifests.has(dir))
80
+ manifests.set(dir, file);
81
+ }
82
+ return [...manifests]
83
+ .toSorted(([a], [b]) => a.localeCompare(b))
84
+ .map(([dir, manifest]) => ({ dir, manifest, repository: repositoryOf(registryImage, dir) }));
85
+ }
86
+ /**
87
+ * The registry image of the project of `context`, as GitLab gives a pipeline it:
88
+ * `CI_REGISTRY_IMAGE` of the environment; none of none.
89
+ *
90
+ * @param context - The environment of the run, of its system.
91
+ * @returns The registry image, or none.
92
+ */
93
+ export function registryImageOf(context) {
94
+ const value = gitOf(context).env['CI_REGISTRY_IMAGE'];
95
+ return value === undefined || value === '' ? undefined : value;
96
+ }
97
+ /**
98
+ * The images of the repo of `context`: each folder of the working tree that git tracks a file an
99
+ * image is built of in.
100
+ *
101
+ * @param context - The folder of the repo, its environment, and the system git runs by.
102
+ * @param registryImage - The registry image of the project: {@link registryImageOf} by default.
103
+ * @returns The images, by their folders.
104
+ */
105
+ export async function readImages(context, registryImage = registryImageOf(context)) {
106
+ return imagesOf(await trackedFiles(context), registryImage);
107
+ }
108
+ /**
109
+ * The images of the repo of `context` at the commit `ref`: each folder of its tree that holds a file
110
+ * an image is built of, by `git ls-tree`.
111
+ *
112
+ * @param ref - The commit, as `HEAD` or the tag of a release.
113
+ * @param context - The folder of the repo, its environment, and the system git runs by.
114
+ * @param registryImage - The registry image of the project: {@link registryImageOf} by default.
115
+ * @returns The images, by their folders.
116
+ * @throws `EGIT` of a commit git has not.
117
+ */
118
+ export async function imagesAt(ref, context, registryImage = registryImageOf(context)) {
119
+ const files = (await git(['ls-tree', '-r', '-z', '--name-only', ref], context))
120
+ .split('\0')
121
+ .filter((file) => file !== '');
122
+ return imagesOf(files, registryImage);
123
+ }
124
+ //# sourceMappingURL=images.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"images.js","sourceRoot":"","sources":["../src/images.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The OCI images of a repo released in trains, of no release tool and no rebuild. Its default export
3
+ * is the ecosystem of OCI images, `ociEcosystem` of `./ecosystem`, which a config of the trains
4
+ * names in `ecosystems` as `'@wtf/release-oci'`, so the trains read the images of the repo by it;
5
+ * and this module holds the type of an image, which the modules of this package do with: the
6
+ * images of the repo, each folder of a Dockerfile, a Containerfile or a
7
+ * `.devcontainer/devcontainer.json` (`./images`), the tags of a release (`./tags`), the tested image
8
+ * of each copied to them by crane (`./publish`), and the page of each in the container registry of
9
+ * GitLab (`./registry`). An image is built and tested by its own pipeline; a release copies the
10
+ * image it tested, by its digest, to the tags of its version, so the bytes released are the bytes
11
+ * tested. Each function takes the `System` it runs by, and runs `git` and `crane` through it.
12
+ *
13
+ * ```ts
14
+ * import type { OciImage } from '@wtf/release-oci'
15
+ *
16
+ * // The repositories of the images, as a release lists them.
17
+ * export const repositoriesOf = (images: readonly OciImage[]): (string | undefined)[] =>
18
+ * images.map(({ repository }) => repository)
19
+ * ```
20
+ *
21
+ * @packageDocumentation
22
+ * @module @wtf/release-oci
23
+ */
24
+ import { ociEcosystem } from './ecosystem.ts';
25
+ /** An OCI image of the repo: one folder, built of one manifest. */
26
+ export interface OciImage {
27
+ /** Its folder, from the root of the repo, as `images/base`; `.` of the root. */
28
+ readonly dir: string;
29
+ /**
30
+ * What it is built of, from the root of the repo: its `Dockerfile` or `Containerfile`, or its
31
+ * `.devcontainer/devcontainer.json`, as `images/base/Dockerfile`.
32
+ */
33
+ readonly manifest: string;
34
+ /**
35
+ * The repository of the image in its registry, as `registry.gitlab.com/acme/images/base`: the
36
+ * registry image of the project, `CI_REGISTRY_IMAGE` of a pipeline, of the root, and that and
37
+ * the folder of an image of a folder; none where the environment names no registry image.
38
+ */
39
+ readonly repository: string | undefined;
40
+ }
41
+ /** The ecosystem of OCI images, which a config of the trains names as `'@wtf/release-oci'`. */
42
+ export default ociEcosystem;
43
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACvB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,+FAA+F;AAC/F,eAAe,YAAY,CAAA"}