@noldova/tools.pipelines 0.0.0-stage → 0.0.2

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.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +202 -2
  3. package/api/index.d.ts +1490 -0
  4. package/api/index.js +27 -0
  5. package/api/index.js.map +1 -0
  6. package/exceptions/pipeline.exception.js +14 -0
  7. package/exceptions/pipeline.exception.js.map +1 -0
  8. package/exceptions/process.exception.js +17 -0
  9. package/exceptions/process.exception.js.map +1 -0
  10. package/exceptions/version.exception.js +15 -0
  11. package/exceptions/version.exception.js.map +1 -0
  12. package/interfaces/i-registry-host.js +9 -0
  13. package/interfaces/i-registry-host.js.map +1 -0
  14. package/interfaces/i-step-output.js +9 -0
  15. package/interfaces/i-step-output.js.map +1 -0
  16. package/interfaces/i-step.js +9 -0
  17. package/interfaces/i-step.js.map +1 -0
  18. package/interfaces/i-tag-host.js +9 -0
  19. package/interfaces/i-tag-host.js.map +1 -0
  20. package/models/archive-check.js +16 -0
  21. package/models/archive-check.js.map +1 -0
  22. package/models/package-archive.js +16 -0
  23. package/models/package-archive.js.map +1 -0
  24. package/models/process-result.js +22 -0
  25. package/models/process-result.js.map +1 -0
  26. package/models/step-result.js +22 -0
  27. package/models/step-result.js.map +1 -0
  28. package/models/version.js +85 -0
  29. package/models/version.js.map +1 -0
  30. package/package.json +24 -4
  31. package/resources.js +310 -0
  32. package/resources.js.map +1 -0
  33. package/services/archive-step.js +130 -0
  34. package/services/archive-step.js.map +1 -0
  35. package/services/command-line.js +34 -0
  36. package/services/command-line.js.map +1 -0
  37. package/services/git.js +60 -0
  38. package/services/git.js.map +1 -0
  39. package/services/nightly-step.js +82 -0
  40. package/services/nightly-step.js.map +1 -0
  41. package/services/npm.js +43 -0
  42. package/services/npm.js.map +1 -0
  43. package/services/process-runner.js +34 -0
  44. package/services/process-runner.js.map +1 -0
  45. package/services/prune-step.js +102 -0
  46. package/services/prune-step.js.map +1 -0
  47. package/services/publish-step.js +117 -0
  48. package/services/publish-step.js.map +1 -0
  49. package/services/source-step.js +43 -0
  50. package/services/source-step.js.map +1 -0
  51. package/services/tag-step.js +48 -0
  52. package/services/tag-step.js.map +1 -0
  53. package/services/tar.js +23 -0
  54. package/services/tar.js.map +1 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Noldova
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,203 @@
1
- # Temporary Holding Version
1
+ # @noldova/tools.pipelines
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
+ The steps of a build and release pipeline that work the same on any host.
4
+ This version holds the version model the steps share, the command-line base a host builds its command line on, and the steps: `source`, `archive`, `publish`, `nightly`, `prune` and `tag`.
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ npm install @noldova/tools.pipelines
10
+ ```
11
+
12
+ ## Use
13
+
14
+ ### Versions
15
+
16
+ `Version` reads, compares and writes releases of the form `major.minor.patch` and nightly versions of the form `major.minor.patch-nightly.YYYYMMDD`.
17
+
18
+ ```ts
19
+ import { Version } from "@noldova/tools.pipelines";
20
+
21
+ const current = Version.parse("0.0.3");
22
+ const next = new Version(current.major, current.minor, current.patch + 1);
23
+
24
+ next.toString(); // "0.0.4"
25
+ next.compareTo(current); // 1
26
+
27
+ const nightly = new Version(next.major, next.minor, next.patch, "20261101");
28
+
29
+ nightly.toString(); // "0.0.4-nightly.20261101"
30
+ nightly.compareTo(next); // -1, a nightly version comes before its release
31
+
32
+ Version.validate("0.0.4x"); // "\"0.0.4x\" is not a version: …", for a text from outside the program
33
+ ```
34
+
35
+ `Version.parse` and the constructor throw `VersionException` for a text or a part that isn't a version.
36
+
37
+ ### Steps and the command line
38
+
39
+ A step returns a `StepResult`: it succeeded, or it failed, each with the message a pipeline's log shows.
40
+ A failed check is a result, never an exception; the package throws only when something else goes wrong, such as git failing to start, and its exceptions extend `PipelineException`.
41
+
42
+ `CommandLine` runs the step its first value names, writes the step's message through the host's `IStepOutput`, and gives the exit code: `0` when the step succeeded, `1` when it failed or no step has that name.
43
+
44
+ ```ts
45
+ import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
46
+
47
+ const git = new Git(new ProcessRunner(), process.cwd());
48
+ const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
49
+ writeSuccess: message => console.log(message),
50
+ writeFailure: message => console.error(message)
51
+ });
52
+
53
+ process.exitCode = await commandLine.runAsync(process.argv.slice(2));
54
+ ```
55
+
56
+ ### The source step
57
+
58
+ `source <version> <commit>` succeeds only when:
59
+
60
+ - the version is a version and the commit is its full id, 40 lowercase hexadecimal digits;
61
+ - the clone holds the commit, and the commit is on `origin/main`, which the clone has fetched with its history;
62
+ - the commit holds `version.json` at its root, and its `version` is that version, such as `{ "version": "0.0.4" }`.
63
+
64
+ Otherwise it fails with the first thing that is wrong, such as `Commit 225059f… is not on origin/main.` or `version.json at commit 225059f… holds 0.0.3, not 0.0.4.`
65
+ A `version.json` that isn't a JSON object with a `version` text makes the step throw `JsonException`, from `@noldova/context.json`.
66
+
67
+ ### The archive step
68
+
69
+ `archive <folder> <version> <commit> <scope>` checks the archives a build packed with `npm pack`, before anything is published.
70
+ The packages it expects are the commit's `package.json` files under `src/`, outside `tests/` folders, that aren't `"private": true`.
71
+ It succeeds only when:
72
+
73
+ - the version is a version, the commit is its full id, and the scope is `@` and a lowercase name, such as `@noldova`;
74
+ - the checkout is at the commit;
75
+ - the folder holds one archive for each package at the version, named as `npm pack` names it, such as `noldova-tools.pipelines-0.0.4.tgz`, and nothing else;
76
+ - each archive's `package/package.json` has the package's name, inside the scope, the version, and the commit as its `gitHead`, isn't `"private": true`, has a `license`, and lists any other expected package under `dependencies` at exactly the version;
77
+ - each archive holds `package/LICENSE`, and no file of a kind that holds credentials: `.npmrc`, `.netrc`, `.env` or `.env.<name>`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, or a name ending in `.pem`, `.key`, `.p12` or `.pfx`, such as `.key` itself, in any folder and whatever its case.
78
+
79
+ ```ts
80
+ import { ArchiveStep, CommandLine, Git, ProcessRunner, SourceStep, Tar } from "@noldova/tools.pipelines";
81
+
82
+ const processRunner = new ProcessRunner();
83
+ const git = new Git(processRunner, process.cwd());
84
+ const commandLine = new CommandLine("pipelines", [new SourceStep(git), new ArchiveStep(git, new Tar(processRunner))], {
85
+ writeSuccess: message => console.log(message),
86
+ writeFailure: message => console.error(message)
87
+ });
88
+
89
+ process.exitCode = await commandLine.runAsync(["archive", "archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
90
+ ```
91
+
92
+ A wrong value, a checkout at another commit or a missing folder fails with that one message.
93
+ Otherwise the step fails with one line for each problem it finds with the archives, such as `archives has no noldova-tools.pipelines-0.0.4.tgz.` or `noldova-tools.pipelines-0.0.4.tgz: its version is 0.0.3, not 0.0.4.`
94
+ It reads each manifest and lists each archive's files with the `tar` program, which must be on the `PATH`; an archive `tar` can't read or list is one of those lines, with `tar`'s exit code and message.
95
+ A `package.json`, in an archive or under `src/`, makes the step throw `JsonException` if it isn't a JSON object, lacks a `name` or `version` text where the step needs one, has a `gitHead` or a `license` that isn't a text, or has a `private` that isn't `true` or `false` or `dependencies` that aren't an object of texts.
96
+
97
+ ### The publish step
98
+
99
+ `publish <folder> <version> <commit> <scope> <registry> <access>` publishes the archives the archive step checks, with the `npm` program, which must be on the `PATH` as an executable, as it is on Linux and macOS.
100
+ The registry is an `https` URL without credentials, a query or a fragment, such as `https://registry.npmjs.org/`, and the access is `public` or `restricted`.
101
+ A release is published under the `latest` dist-tag, and a nightly version under `nightly`; a nightly version must be newer than both.
102
+ The step passes no token: `npm` takes its credentials from its own configuration, such as the environment a pipeline sets up.
103
+
104
+ ```ts
105
+ import { ArchiveStep, CommandLine, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
106
+
107
+ const processRunner = new ProcessRunner();
108
+ const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
109
+ const commandLine = new CommandLine("pipelines", [archiveStep, new PublishStep(archiveStep, new Npm(processRunner, process.cwd()))], {
110
+ writeSuccess: message => console.log(message),
111
+ writeFailure: message => console.error(message)
112
+ });
113
+
114
+ process.exitCode = await commandLine.runAsync(["publish", "archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://registry.npmjs.org/", "public"]);
115
+ ```
116
+
117
+ The step:
118
+
119
+ 1. runs the archive step's checks, and fails with their message when they fail;
120
+ 2. asks the registry about each package, and fails, publishing nothing, with one line for each version it already has from another archive and each version that isn't newer than the version a tag it must pass points to; a version it already has from the same archive is skipped;
121
+ 3. publishes the rest in turn, and stops at the first publish that fails;
122
+ 4. waits until the registry serves each version it published with the same archive, up to 10 minutes, asking every 10 seconds, also after a failed publish, so a rerun skips the versions already published.
123
+
124
+ It succeeds with one line for each package, such as `@noldova/tools.pipelines@0.0.4 published.`, and otherwise fails with one line for each problem.
125
+ A failed `npm` call is one of those lines, with `npm`'s exit code and message, and without the credentials, query or fragment of any URL in it; `npm` failing to start throws `ProcessException`.
126
+
127
+ ### The nightly step
128
+
129
+ `nightly <commit> <registry>` works out a nightly build's version, which the later steps take, and prints it alone, such as `0.0.5-nightly.20261102`: the release in `version.json` at the commit with one more patch, and the UTC date.
130
+ The commit must be on `origin/main`, and the registry is as the publish step takes it.
131
+
132
+ ```ts
133
+ import { ArchiveStep, CommandLine, Git, NightlyStep, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
134
+
135
+ const processRunner = new ProcessRunner();
136
+ const git = new Git(processRunner, process.cwd());
137
+ const nightlyStep = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
138
+ const commandLine = new CommandLine("pipelines", [nightlyStep], {
139
+ writeSuccess: message => console.log(message),
140
+ writeFailure: message => console.error(message)
141
+ });
142
+
143
+ process.exitCode = await commandLine.runAsync(["nightly", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "https://registry.npmjs.org/"]);
144
+ ```
145
+
146
+ The step prints nothing when the last nightly version of every package the archive step expects has the commit as its `gitHead`, or is from the same UTC date, so a pipeline skips the build when the output is empty.
147
+ It fails with one line naming the packages when only some have a nightly version from that date, and with `npm`'s exit code and message for a read of the registry that fails.
148
+
149
+ ### The prune step
150
+
151
+ `prune <version> <commit> <scope> <registry> <keep-versions>` runs after a release on a registry that keeps only its newest versions: it deletes each package's older release versions, keeping the newest `<keep-versions>`, a whole number above 0.
152
+ It lists and deletes versions through the host's `IRegistryHost`, which a host's package implements for its own registry, and runs only on that registry; it refuses npm's public registry whatever the host names, so a version published there stays.
153
+ Since the step deletes, a pipeline runs it only from a release job that an environment's reviewers approve.
154
+
155
+ ```ts
156
+ import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
157
+
158
+ const processRunner = new ProcessRunner();
159
+ const git = new Git(processRunner, process.cwd());
160
+ const versions = new Set(["0.0.2", "0.0.3", "0.0.4"]);
161
+ const host: IRegistryHost = {
162
+ registry: "https://npm.pkg.github.com/",
163
+ readVersionsAsync: async () => [...versions],
164
+ deleteVersionAsync: async (packageName, version) => versions.delete(version)
165
+ };
166
+ const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
167
+ const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://npm.pkg.github.com/", "2"]);
168
+ result.message; // "@noldova/a@0.0.2 deleted." when the commit holds only @noldova/a
169
+ ```
170
+
171
+ - It fails, asking the registry nothing, unless the version is a release version, the commit is its full id and in the clone, the scope holds every package the archive step expects at the commit, the registry is the host's and not npm's, and the number to keep is one.
172
+ - It lists every package's versions before it deletes any, and fails, deleting nothing, with one line for each package whose versions the host can't list and each whose newest release version isn't the version.
173
+ - It deletes each package's release versions after the newest it keeps, with one line for each, and succeeds with one line saying nothing is deleted when no package has more; a version another run deleted first is reported, not a failure.
174
+ - It stops at the first delete that fails, with the lines before it and the host's answer, or a line naming the version with the error's message when the delete rejects, such as for a lost connection.
175
+ - It counts and deletes only release versions: a nightly version, or any other version, stays.
176
+
177
+ ### The tag step
178
+
179
+ `tag <version> <commit>` ends a release: it tags the released commit `v<version>`, such as `v0.0.4`.
180
+ It reads and creates the tag through the host's `ITagHost`, which a host's package implements, such as through the host's API.
181
+
182
+ ```ts
183
+ import { type ITagHost, TagStep } from "@noldova/tools.pipelines";
184
+
185
+ const tags = new Map<string, string>();
186
+ const host: ITagHost = {
187
+ readTagAsync: async tag => tags.get(tag) ?? "",
188
+ createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
189
+ };
190
+ const result = await new TagStep(host).runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
191
+ result.message; // "Tagged commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8 as v0.0.4."
192
+ ```
193
+
194
+ - It fails, before asking the host, unless the version is a release version and the commit is its full id; a nightly version gets no tag.
195
+ - It creates the tag when the host has none, and succeeds, such as `Tagged commit 225059f… as v0.0.4.`
196
+ - When the tag is already there, such as from a rerun or from another run that made it first, it succeeds if the tag points to the commit, and otherwise fails, naming both commits; it never moves or deletes a tag.
197
+ - A failed answer of the host is the step's result.
198
+
199
+ The declaration file `api/index.d.ts` documents every member with its contract and examples.
200
+
201
+ ## License
202
+
203
+ MIT; see `LICENSE`.