@noldova/tools.pipelines 0.0.1 → 0.0.3

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/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @noldova/tools.pipelines
2
2
 
3
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` and `tag`.
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`, `tag`, `toolchain`, `line-endings`, `unchanged` and `reproducible`.
5
5
 
6
6
  ## Install
7
7
 
@@ -73,7 +73,8 @@ It succeeds only when:
73
73
  - the version is a version, the commit is its full id, and the scope is `@` and a lowercase name, such as `@noldova`;
74
74
  - the checkout is at the commit;
75
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`, and lists any other expected package under `dependencies` at exactly the version.
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.
77
78
 
78
79
  ```ts
79
80
  import { ArchiveStep, CommandLine, Git, ProcessRunner, SourceStep, Tar } from "@noldova/tools.pipelines";
@@ -90,8 +91,8 @@ process.exitCode = await commandLine.runAsync(["archive", "archives", "0.0.4", "
90
91
 
91
92
  A wrong value, a checkout at another commit or a missing folder fails with that one message.
92
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.`
93
- It reads each manifest with the `tar` program, which must be on the `PATH`; an archive `tar` can't read is one of those lines, with `tar`'s exit code and message.
94
- 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` that isn't a text, or has a `private` that isn't `true` or `false` or `dependencies` that aren't an object of texts.
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.
95
96
 
96
97
  ### The publish step
97
98
 
@@ -145,6 +146,34 @@ process.exitCode = await commandLine.runAsync(["nightly", "225059f4c1e6a3b2d8f7e
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.
146
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.
147
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
+
148
177
  ### The tag step
149
178
 
150
179
  `tag <version> <commit>` ends a release: it tags the released commit `v<version>`, such as `v0.0.4`.
@@ -167,6 +196,70 @@ result.message; // "Tagged commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8 as v0
167
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.
168
197
  - A failed answer of the host is the step's result.
169
198
 
199
+ ### The toolchain step
200
+
201
+ `toolchain <node-version> [<npm-version>]` checks that the Node.js running it is `<node-version>` and, when given, that `npm --version` prints `<npm-version>`; an empty npm version checks none.
202
+
203
+ ```ts
204
+ import { Npm, ProcessRunner, ToolchainStep } from "@noldova/tools.pipelines";
205
+
206
+ const step = new ToolchainStep(new Npm(new ProcessRunner(), process.cwd()), process.version);
207
+ const result = await step.runAsync(["24.21.0", "11.19.0"]);
208
+ result.message; // "Node.js v24.21.0 and npm 11.19.0 run this step."
209
+ ```
210
+
211
+ - Each version is exact, `major.minor.patch`; anything else, such as `24` or `v24.21.0`, fails before anything is read.
212
+ - It fails with one line for each version that differs, naming the version found, the one expected and the fix.
213
+
214
+ ### The line-endings step
215
+
216
+ `line-endings` takes no values and checks the files the checkout tracks, in the working directory and the folders inside it.
217
+
218
+ ```ts
219
+ import { Git, LineEndingsStep, ProcessRunner } from "@noldova/tools.pipelines";
220
+
221
+ const result = await new LineEndingsStep(new Git(new ProcessRunner(), process.cwd())).runAsync([]);
222
+ result.message; // ".gitattributes holds \"* text=auto eol=lf\", and the 12 tracked text files use LF line endings and end with exactly one newline."
223
+ ```
224
+
225
+ - `.gitattributes` at the checkout's root holds the line `* text=auto eol=lf`.
226
+ - Every tracked text file's committed content uses LF line endings, and the file in the checkout ends with exactly one newline; a tracked file the checkout doesn't hold is a failure.
227
+ - It reads the files' ends from the checkout, so a pipeline runs it on a checkout as committed, before the build.
228
+ - It skips symbolic links, submodules, files git sees as binary and files `.gitattributes` marks `-text` or `binary`.
229
+ - It fails with one line for each thing that is wrong, naming the file and the fix, and fails when git lists no tracked file.
230
+
231
+ ### The unchanged step
232
+
233
+ `unchanged` takes no values and checks that the checkout is as committed, such as after a build and its tests: `git status --porcelain` lists nothing.
234
+ It fails with each path git lists, changed, staged or untracked outside the ignored paths, and says to undo the change or ignore the output in `.gitignore`.
235
+
236
+ ```ts
237
+ import { Git, ProcessRunner, UnchangedStep } from "@noldova/tools.pipelines";
238
+
239
+ const result = await new UnchangedStep(new Git(new ProcessRunner(), process.cwd())).runAsync([]);
240
+ result.message; // "The checkout has no changed or untracked file."
241
+ ```
242
+
243
+ ### The reproducible step
244
+
245
+ `reproducible <folder>` runs after the build, in the checkout, and checks that a second build of the same commit packs the same archives, so that rerunning a release publishes nothing new.
246
+
247
+ ```ts
248
+ import { Git, Npm, ProcessRunner, ReproducibleStep } from "@noldova/tools.pipelines";
249
+
250
+ const processRunner = new ProcessRunner();
251
+ const step = new ReproducibleStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()));
252
+ const result = await step.runAsync(["_packages"]);
253
+ result.message; // "A second build of commit 225059f…, in another folder, packed the same 2 archives byte for byte: …"
254
+ ```
255
+
256
+ - It adds a worktree of the checkout's commit in a new temporary folder, runs `npm run build` there, and compares the `.tgz` archives in `<folder>`, a path from the checkout's root, with those in the worktree's.
257
+ - It succeeds listing each archive with its SHA-512, and fails with one line for each archive that differs or is in only one build.
258
+ - It fails when `<folder>` is missing or holds no archive, and when the second build fails, with npm's exit code and error output.
259
+ - It removes the worktree and its folder whether it succeeds or fails.
260
+ - It makes its temporary folder in the root its constructor is given, or in `os.tmpdir()`; give a root the pipeline host empties after each job, so a cancelled run leaves nothing behind.
261
+ - `<folder>` must be inside the checkout: an absolute path, `..` or the checkout itself fails.
262
+
170
263
  The declaration file `api/index.d.ts` documents every member with its contract and examples.
171
264
 
172
265
  ## License