@noldova/tools.pipelines 0.0.2 → 0.0.4

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`, `prune` 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`, `reproducible` and `dependents`.
5
5
 
6
6
  ## Install
7
7
 
@@ -196,6 +196,94 @@ result.message; // "Tagged commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8 as v0
196
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
197
  - A failed answer of the host is the step's result.
198
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
+
263
+ ### The dependents step
264
+
265
+ `dependents <version> <commit>` runs after a release, in a checkout of the released commit, and proposes the release to every repository that pins its packages exactly at an older version.
266
+ It lists, checks out, pushes to and proposes in the repositories through the host's `IUpdateHost`, which a host's package implements, such as through the host's API.
267
+
268
+ ```ts
269
+ import { ArchiveStep, DependentsStep, Git, type IUpdateHost, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
270
+
271
+ declare const host: IUpdateHost;
272
+ const processRunner = new ProcessRunner();
273
+ const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
274
+ const step = new DependentsStep(archiveStep, host, processRunner, new Npm(processRunner, process.cwd()));
275
+ const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
276
+ result.message; // "Looked for exact pins of @noldova/a, @noldova/b older than 0.0.4 in 2 repositories: …"
277
+ ```
278
+
279
+ - It fails, before asking the host, unless the version is a release version and the commit is its full id; a nightly version moves nothing.
280
+ - It reads the packages the commit releases as the archive step does, and checks out each repository the host lists into a new temporary folder.
281
+ - In each tracked `package.json`, it moves every value that names one of those packages at an exact version older than the release, such as `"0.0.3"`; a range, such as `"^0.0.3"`, and a newer or equal version stay.
282
+ - When it moved any, it refreshes every tracked `package-lock.json` with `npm install --package-lock-only --ignore-scripts`, without the host's credential variables, commits, pushes the branch `pipelines/update-<source>` and proposes it with the moved pins and the release's notes; a repository that pins none is left as it is.
283
+ - When the branch exists, it replaces it only while the branch is at a commit of its own, with its title and the same committer; a branch with anyone else's commit is left as it is, and that repository fails, so nobody's work is lost.
284
+ - It succeeds with one line for each repository, and fails, after trying every other repository, with the line of each that failed; an error in one repository, such as git failing, is that repository's line.
285
+ - It removes its temporary folder whether it succeeds or fails, and makes it in the root its constructor is given, or in `os.tmpdir()`.
286
+
199
287
  The declaration file `api/index.d.ts` documents every member with its contract and examples.
200
288
 
201
289
  ## License