@noldova/tools.pipelines 0.0.6 → 0.0.8

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`, `tag`, `toolchain`, `line-endings`, `unchanged`, `reproducible` and `dependents`.
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`, `dependents` and `pins`.
5
5
 
6
6
  ## Install
7
7
 
@@ -74,14 +74,19 @@ It succeeds only when:
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
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
+ - 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
+ - each archive holds every file the build copies into its package, as a file with the same bytes as its source, and neither the copy nor its source is a symbolic link or under one.
79
+
80
+ The step asks the build for those copies with `npm run build --silent -- --list-copies`, in the folder the `Npm` it's given works in, the checkout's root.
81
+ The build script prints one line for each copy, with tabs between its source's path from the checkout's root, the package's name, and its path inside the package, such as `LICENSE`, `@noldova/tools.pipelines` and `LICENSE`, with `/` between a path's parts, then `end of copies` as its last line, also when it copies nothing; it builds nothing.
82
+ Every build the step checks must answer `--list-copies` so before the build's release or CI moves to this version of the step: a build that doesn't fails the step.
78
83
 
79
84
  ```ts
80
- import { ArchiveStep, CommandLine, Git, ProcessRunner, SourceStep, Tar } from "@noldova/tools.pipelines";
85
+ import { ArchiveStep, CommandLine, Git, Npm, ProcessRunner, SourceStep, Tar } from "@noldova/tools.pipelines";
81
86
 
82
87
  const processRunner = new ProcessRunner();
83
88
  const git = new Git(processRunner, process.cwd());
84
- const commandLine = new CommandLine("pipelines", [new SourceStep(git), new ArchiveStep(git, new Tar(processRunner))], {
89
+ const commandLine = new CommandLine("pipelines", [new SourceStep(git), new ArchiveStep(git, new Tar(processRunner), new Npm(processRunner, process.cwd()))], {
85
90
  writeSuccess: message => console.log(message),
86
91
  writeFailure: message => console.error(message)
87
92
  });
@@ -92,6 +97,7 @@ process.exitCode = await commandLine.runAsync(["archive", "archives", "0.0.4", "
92
97
  A wrong value, a checkout at another commit or a missing folder fails with that one message.
93
98
  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
99
  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.
100
+ When the archives pass, the step checks the copies, extracting each archive with `tar` into a new temporary folder that it removes after, and adds one line, such as `Each of the 2 files the build copies in matches its source.`; it fails with npm's exit code and message when the build can't list its copies, and when its output doesn't end with `end of copies`; otherwise with one line for each copy the build lists that isn't three fields, has a path that isn't inside its folder or a package without an archive, a source that is a symbolic link or under one or isn't a file, an archive `tar` can't extract, and a copy an archive lacks, holds as a symbolic link, under one or as a folder, or holds with other bytes.
95
101
  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
102
 
97
103
  ### The publish step
@@ -105,7 +111,7 @@ The step passes no token: `npm` takes its credentials from its own configuration
105
111
  import { ArchiveStep, CommandLine, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
106
112
 
107
113
  const processRunner = new ProcessRunner();
108
- const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
114
+ const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
109
115
  const commandLine = new CommandLine("pipelines", [archiveStep, new PublishStep(archiveStep, new Npm(processRunner, process.cwd()))], {
110
116
  writeSuccess: message => console.log(message),
111
117
  writeFailure: message => console.error(message)
@@ -116,7 +122,7 @@ process.exitCode = await commandLine.runAsync(["publish", "archives", "0.0.4", "
116
122
 
117
123
  The step:
118
124
 
119
- 1. runs the archive step's checks, and fails with their message when they fail;
125
+ 1. runs the archive step's checks, except the build's copies, and fails with their message when they fail;
120
126
  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
127
  3. publishes the rest in turn, and stops at the first publish that fails;
122
128
  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.
@@ -134,7 +140,8 @@ import { ArchiveStep, CommandLine, Git, NightlyStep, Npm, ProcessRunner, Tar } f
134
140
 
135
141
  const processRunner = new ProcessRunner();
136
142
  const git = new Git(processRunner, process.cwd());
137
- const nightlyStep = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
143
+ const npm = new Npm(processRunner, process.cwd());
144
+ const nightlyStep = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner), npm), npm);
138
145
  const commandLine = new CommandLine("pipelines", [nightlyStep], {
139
146
  writeSuccess: message => console.log(message),
140
147
  writeFailure: message => console.error(message)
@@ -150,10 +157,10 @@ It fails with one line naming the packages when only some have a nightly version
150
157
 
151
158
  `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, and every version a repository's lock file still holds, so that repository's `npm ci` keeps working.
152
159
  It lists and deletes versions, and reads the lock files, 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.
160
+ Since the step deletes, a pipeline runs it only in a release whose publish an environment's reviewers approve.
154
161
 
155
162
  ```ts
156
- import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
163
+ import { ArchiveStep, Git, type IRegistryHost, Npm, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
157
164
 
158
165
  const processRunner = new ProcessRunner();
159
166
  const git = new Git(processRunner, process.cwd());
@@ -164,7 +171,7 @@ const host: IRegistryHost = {
164
171
  deleteVersionAsync: async (packageName, version) => versions.delete(version),
165
172
  readLockFilesAsync: async () => new Map([["app/package-lock.json", JSON.stringify({ packages: { "node_modules/@noldova/a": { version: "0.0.3" } } })]])
166
173
  };
167
- const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
174
+ const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner), new Npm(processRunner, process.cwd())), host);
168
175
  const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://npm.pkg.github.com/", "1"]);
169
176
  result.message; // "@noldova/a@0.0.3 kept, since app/package-lock.json locks it.\n@noldova/a@0.0.2 deleted." when the commit holds only @noldova/a
170
177
  ```
@@ -273,7 +280,7 @@ import { ArchiveStep, DependentsStep, Git, type IUpdateHost, Npm, ProcessRunner,
273
280
 
274
281
  declare const host: IUpdateHost;
275
282
  const processRunner = new ProcessRunner();
276
- const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
283
+ const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
277
284
  const step = new DependentsStep(archiveStep, host, processRunner, new Npm(processRunner, process.cwd()));
278
285
  const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
279
286
  result.message; // "Looked for exact pins of @noldova/a, @noldova/b older than 0.0.4 in 2 repositories: …"
@@ -291,6 +298,28 @@ result.message; // "Looked for exact pins of @noldova/a, @noldova/b older than 0
291
298
  - Given an output, it writes each repository's line there instead, as a success or a failure, as soon as that repository is done, so a run stopped partway still shows the repositories it finished; its result's message is then only the summary.
292
299
  - It removes its temporary folder whether it succeeds or fails, and makes it in the root its constructor is given, or in `os.tmpdir()`.
293
300
 
301
+ ### The pins step
302
+
303
+ `pins <version> <commit>` runs after a shared repository of workflows tags `v<version>` at the commit, in a clone that holds the commit, and proposes the tag to every repository that pins its workflows at an older version.
304
+ It works through the host's `IUpdateHost`, as the dependents step does.
305
+
306
+ ```ts
307
+ import { Git, type IUpdateHost, PinsStep, ProcessRunner } from "@noldova/tools.pipelines";
308
+
309
+ declare const host: IUpdateHost;
310
+ const processRunner = new ProcessRunner();
311
+ const step = new PinsStep(new Git(processRunner, process.cwd()), host, processRunner);
312
+ const result = await step.runAsync(["1.2.0", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
313
+ result.message; // "Looked for pins on .github's workflows older than v1.2.0 in 2 repositories: …"
314
+ ```
315
+
316
+ - It fails, before asking the host, unless the version is a release version and the commit is its full id.
317
+ - It reads the outside actions the commit's `.github/workflows` pin as `uses: <action>@<commit> # v<version>`, keeping the highest version of each.
318
+ - In each repository's tracked `.github/workflows/*.yml` and `*.yaml`, it moves each `uses: <owner>/<source>/<path>@<commit>`, with that repository's owner, to the new commit and `# v<version>` when its version comment is older within the same major version, or is missing and its commit is in the tagged commit's history; a pin a major version behind, or with no version and a commit the tag doesn't hold, stays, and the repository's line and the proposal name it.
319
+ - A pin with no version is checked against the clone the step runs in, so that clone needs the shared repository's whole history, such as `fetch-depth: 0`; a commit the clone doesn't hold stays.
320
+ - It moves each outside action pinned at an older version than the shared repository's to the shared one's commit and version, and the proposal lists apart those that move to a new major version, except in a repository with a tracked `.github/dependabot.yml` or `.github/dependabot.yaml`, whose outside actions Dependabot moves.
321
+ - When it moved any, it commits, pushes the branch `pipelines/pins-<source>` and proposes it with the moved and the left pins and the release's notes; the branch, the lines, the output and the temporary folder work as in the dependents step.
322
+
294
323
  The declaration file `api/index.d.ts` documents every member with its contract and examples.
295
324
 
296
325
  ## License
package/api/index.d.ts CHANGED
@@ -1141,7 +1141,8 @@ export declare class Git {
1141
1141
  }
1142
1142
 
1143
1143
  /**
1144
- * Reads and lists files in `.tgz` archives through the `tar` program.
1144
+ * Reads, lists and extracts files in `.tgz` archives through the `tar`
1145
+ * program.
1145
1146
  */
1146
1147
  export declare class Tar {
1147
1148
  /**
@@ -1199,6 +1200,26 @@ export declare class Tar {
1199
1200
  * ```
1200
1201
  */
1201
1202
  public listFilesAsync(archivePath: string): Promise<ProcessResult>;
1203
+
1204
+ /**
1205
+ * Extracts every file of an archive into the archive's folder; an npm
1206
+ * archive's files land under its `package/` folder.
1207
+ *
1208
+ * @param archivePath The archive's path, such as
1209
+ * `archives/noldova-tools.pipelines-0.0.4.tgz`.
1210
+ * @returns A promise of how `tar` ended; when the archive is not a `.tgz`,
1211
+ * it failed, with `tar`'s message. It rejects with
1212
+ * {@link ProcessException} if `tar` cannot start, such as when it is not
1213
+ * installed or the archive's folder does not exist.
1214
+ * @example
1215
+ * ```ts
1216
+ * import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
1217
+ *
1218
+ * const result = await new Tar(new ProcessRunner()).extractAsync("archives/noldova-tools.pipelines-0.0.4.tgz");
1219
+ * result.isSuccessful; // true when archives/package holds the archive's files
1220
+ * ```
1221
+ */
1222
+ public extractAsync(archivePath: string): Promise<ProcessResult>;
1202
1223
  }
1203
1224
 
1204
1225
  /**
@@ -1225,6 +1246,11 @@ export declare class Npm {
1225
1246
  */
1226
1247
  public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string);
1227
1248
 
1249
+ /**
1250
+ * The directory `npm` runs in, as the constructor got it.
1251
+ */
1252
+ public readonly workingDirectory: string;
1253
+
1228
1254
  /**
1229
1255
  * Reads a field of a package or a version from the registry, asking the
1230
1256
  * registry rather than `npm`'s cache.
@@ -1312,6 +1338,27 @@ export declare class Npm {
1312
1338
  */
1313
1339
  public buildAsync(directory: string): Promise<ProcessResult>;
1314
1340
 
1341
+ /**
1342
+ * Asks the build script of the package in the working directory which
1343
+ * files it copies into the packages, with
1344
+ * `npm run build --silent -- --list-copies`, or on Windows the same through
1345
+ * `cmd.exe /d /s /c`, a fixed command. The script prints one line for each
1346
+ * copy: the source's path from the repository's root, the package's name
1347
+ * and the copy's path inside the package, separated by tabs, with `/`
1348
+ * between a path's parts, then the line `end of copies`, its last, also
1349
+ * when it copies nothing; it builds nothing.
1350
+ *
1351
+ * @returns A promise of npm's exit code and of what it wrote. It rejects
1352
+ * with {@link ProcessException} if the program cannot start.
1353
+ * @example
1354
+ * ```ts
1355
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
1356
+ *
1357
+ * (await new Npm(new ProcessRunner(), process.cwd()).listCopiesAsync()).output; // "LICENSE\t@noldova/context.text\tLICENSE\nend of copies\n"
1358
+ * ```
1359
+ */
1360
+ public listCopiesAsync(): Promise<ProcessResult>;
1361
+
1315
1362
  /**
1316
1363
  * Refreshes a directory's `package-lock.json` from its `package.json`
1317
1364
  * files, with `npm install --package-lock-only --ignore-scripts --no-audit
@@ -1441,7 +1488,11 @@ export declare class SourceStep implements IStep {
1441
1488
  * file of a kind that holds credentials: `.npmrc`, `.netrc`, `.env` or
1442
1489
  * `.env.<name>`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, or a name
1443
1490
  * ending in `.pem`, `.key`, `.p12` or `.pfx`, such as `.key` itself, in any
1444
- * folder and whatever its case.
1491
+ * folder and whatever its case. When those checks pass, the step asks the
1492
+ * build which files it copies into the packages, with
1493
+ * {@link Npm.listCopiesAsync}, and each archive must hold every copy into its
1494
+ * package as a file with the same bytes as its source, neither of them a
1495
+ * symbolic link or under one.
1445
1496
  */
1446
1497
  export declare class ArchiveStep implements IStep {
1447
1498
  /**
@@ -1455,21 +1506,23 @@ export declare class ArchiveStep implements IStep {
1455
1506
  public readonly usage: string;
1456
1507
 
1457
1508
  /**
1458
- * Creates the step over a clone and an archive reader.
1509
+ * Creates the step over a clone, an archive reader and the build.
1459
1510
  *
1460
1511
  * @param git The reader of the clone whose checkout the archives were
1461
1512
  * packed from.
1462
1513
  * @param tar The reader of the archives.
1514
+ * @param npm The runner of the build that packed the archives, working in
1515
+ * the clone's root.
1463
1516
  * @example
1464
1517
  * ```ts
1465
- * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1518
+ * import { ArchiveStep, Git, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1466
1519
  *
1467
1520
  * const processRunner = new ProcessRunner();
1468
- * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1521
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1469
1522
  * step.name; // "archive"
1470
1523
  * ```
1471
1524
  */
1472
- public constructor(git: Git, tar: Tar);
1525
+ public constructor(git: Git, tar: Tar, npm: Npm);
1473
1526
 
1474
1527
  /**
1475
1528
  * Checks the release's archives.
@@ -1492,7 +1545,19 @@ export declare class ArchiveStep implements IStep {
1492
1545
  * or an empty one, or an expected package under `dependencies`
1493
1546
  * at anything but exactly the version, an archive `tar` cannot list the
1494
1547
  * files of, with `tar`'s exit code and message, a file of a kind that holds
1495
- * credentials, and no `package/LICENSE`. It rejects with `JsonException`,
1548
+ * credentials, and no `package/LICENSE`. When the archives pass, it asks
1549
+ * the build for its copies and adds a line, such as
1550
+ * `Each of the 2 files the build copies in matches its source.`, or
1551
+ * `The build copies no file into a package.`; it fails when the build
1552
+ * cannot list them, with npm's exit code and message, or when its output
1553
+ * does not end with the line `end of copies`, or with one line for each
1554
+ * line before it that is not three fields, a path that is absolute, holds
1555
+ * `\`, or an empty, `.` or `..` part, or a package without an archive;
1556
+ * otherwise with one line for each source that is a symbolic link or under
1557
+ * one, or not a file, archive `tar` cannot extract, with `tar`'s exit code
1558
+ * and message, and copy the archive lacks, that is a symbolic link or under
1559
+ * one, that is not a file, or whose bytes differ. It rejects with
1560
+ * `JsonException`,
1496
1561
  * from `@noldova/context.json`, if a `package.json` the step reads is not
1497
1562
  * a JSON object, lacks a `name` or `version` text where it needs one, has
1498
1563
  * a `gitHead` or a `license` that is not a text, or
@@ -1501,10 +1566,10 @@ export declare class ArchiveStep implements IStep {
1501
1566
  * `tar` cannot start or git fails otherwise.
1502
1567
  * @example
1503
1568
  * ```ts
1504
- * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1569
+ * import { ArchiveStep, Git, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1505
1570
  *
1506
1571
  * const processRunner = new ProcessRunner();
1507
- * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1572
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1508
1573
  * const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
1509
1574
  * result.isSuccessful; // true when the folder holds exactly the packages at 0.0.4
1510
1575
  * (await step.runAsync(["archives"])).message; // "The archive step takes <folder> <version> <commit> <scope>."
@@ -1513,9 +1578,9 @@ export declare class ArchiveStep implements IStep {
1513
1578
  public runAsync(values: readonly string[]): Promise<StepResult>;
1514
1579
 
1515
1580
  /**
1516
- * Checks the release's archives as {@link ArchiveStep.runAsync} does, and
1517
- * gives the archives it checked with the result, for a step that goes on
1518
- * to use them.
1581
+ * Checks the release's archives as {@link ArchiveStep.runAsync} does,
1582
+ * except for the build's copies, and gives the archives it checked with the
1583
+ * result, for a step that goes on to use them.
1519
1584
  *
1520
1585
  * @param values The same values as {@link ArchiveStep.runAsync}.
1521
1586
  * @returns A promise of the check: the result, and when it succeeded, each
@@ -1523,10 +1588,10 @@ export declare class ArchiveStep implements IStep {
1523
1588
  * {@link ArchiveStep.runAsync} does.
1524
1589
  * @example
1525
1590
  * ```ts
1526
- * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1591
+ * import { ArchiveStep, Git, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1527
1592
  *
1528
1593
  * const processRunner = new ProcessRunner();
1529
- * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1594
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1530
1595
  * const check = await step.checkAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
1531
1596
  * check.archives.map(t => t.packageName); // ["@noldova/tools.pipelines"] when the check succeeded
1532
1597
  * ```
@@ -1544,10 +1609,10 @@ export declare class ArchiveStep implements IStep {
1544
1609
  * {@link ArchiveStep.runAsync} does.
1545
1610
  * @example
1546
1611
  * ```ts
1547
- * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1612
+ * import { ArchiveStep, Git, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1548
1613
  *
1549
1614
  * const processRunner = new ProcessRunner();
1550
- * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1615
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1551
1616
  * const names = await step.readPackageNamesAsync("225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8");
1552
1617
  * names; // ["@noldova/tools.pipelines"]
1553
1618
  * ```
@@ -1564,10 +1629,10 @@ export declare class ArchiveStep implements IStep {
1564
1629
  * and {@link ProcessException} as {@link ArchiveStep.runAsync} does.
1565
1630
  * @example
1566
1631
  * ```ts
1567
- * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1632
+ * import { ArchiveStep, Git, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1568
1633
  *
1569
1634
  * const processRunner = new ProcessRunner();
1570
- * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1635
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1571
1636
  * const manifests = await step.readPackageManifestsAsync("225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8");
1572
1637
  * manifests.map(t => t.readString("name")); // ["@noldova/tools.pipelines"]
1573
1638
  * ```
@@ -1578,9 +1643,9 @@ export declare class ArchiveStep implements IStep {
1578
1643
  /**
1579
1644
  * The step that publishes a release's archives:
1580
1645
  * `publish <folder> <version> <commit> <scope> <registry> <access>`. It runs
1581
- * {@link ArchiveStep}'s checks first, then publishes each package whose
1582
- * version the registry doesn't have and waits until the registry serves each
1583
- * version it published with the same archive.
1646
+ * {@link ArchiveStep}'s checks first, except the build's copies, then
1647
+ * publishes each package whose version the registry doesn't have and waits
1648
+ * until the registry serves each version it published with the same archive.
1584
1649
  */
1585
1650
  export declare class PublishStep implements IStep {
1586
1651
  /**
@@ -1609,7 +1674,7 @@ export declare class PublishStep implements IStep {
1609
1674
  * import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
1610
1675
  *
1611
1676
  * const processRunner = new ProcessRunner();
1612
- * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1677
+ * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1613
1678
  * const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
1614
1679
  * step.name; // "publish"
1615
1680
  * ```
@@ -1646,7 +1711,7 @@ export declare class PublishStep implements IStep {
1646
1711
  * import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
1647
1712
  *
1648
1713
  * const processRunner = new ProcessRunner();
1649
- * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1714
+ * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
1650
1715
  * const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
1651
1716
  * const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://registry.npmjs.org/", "public"]);
1652
1717
  * result.isSuccessful; // true when every package's 0.0.4 is published and served
@@ -1686,7 +1751,8 @@ export declare class NightlyStep implements IStep {
1686
1751
  *
1687
1752
  * const processRunner = new ProcessRunner();
1688
1753
  * const git = new Git(processRunner, process.cwd());
1689
- * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
1754
+ * const npm = new Npm(processRunner, process.cwd());
1755
+ * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner), npm), npm);
1690
1756
  * step.name; // "nightly"
1691
1757
  * ```
1692
1758
  */
@@ -1721,7 +1787,8 @@ export declare class NightlyStep implements IStep {
1721
1787
  *
1722
1788
  * const processRunner = new ProcessRunner();
1723
1789
  * const git = new Git(processRunner, process.cwd());
1724
- * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
1790
+ * const npm = new Npm(processRunner, process.cwd());
1791
+ * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner), npm), npm);
1725
1792
  * const result = await step.runAsync(["225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "https://registry.npmjs.org/"]);
1726
1793
  * result.message; // "0.0.5-nightly.20261102", or "" when nothing changed
1727
1794
  * ```
@@ -1759,7 +1826,7 @@ export declare class PruneStep implements IStep {
1759
1826
  * registry, and reads the lock files whose versions it keeps.
1760
1827
  * @example
1761
1828
  * ```ts
1762
- * import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1829
+ * import { ArchiveStep, Git, type IRegistryHost, Npm, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1763
1830
  *
1764
1831
  * const processRunner = new ProcessRunner();
1765
1832
  * const git = new Git(processRunner, process.cwd());
@@ -1769,7 +1836,7 @@ export declare class PruneStep implements IStep {
1769
1836
  * deleteVersionAsync: async () => true,
1770
1837
  * readLockFilesAsync: async () => new Map()
1771
1838
  * };
1772
- * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
1839
+ * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner), new Npm(processRunner, process.cwd())), host);
1773
1840
  * step.name; // "prune"
1774
1841
  * ```
1775
1842
  */
@@ -1815,7 +1882,7 @@ export declare class PruneStep implements IStep {
1815
1882
  * with anything but an `Error`.
1816
1883
  * @example
1817
1884
  * ```ts
1818
- * import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1885
+ * import { ArchiveStep, Git, type IRegistryHost, Npm, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1819
1886
  *
1820
1887
  * const processRunner = new ProcessRunner();
1821
1888
  * const git = new Git(processRunner, process.cwd());
@@ -1826,7 +1893,7 @@ export declare class PruneStep implements IStep {
1826
1893
  * deleteVersionAsync: async (packageName, version) => versions.delete(version),
1827
1894
  * readLockFilesAsync: async () => new Map()
1828
1895
  * };
1829
- * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
1896
+ * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner), new Npm(processRunner, process.cwd())), host);
1830
1897
  * const result = await step.runAsync(["0.0.3", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://npm.pkg.github.com/", "2"]);
1831
1898
  * result.message; // "@noldova/a@0.0.1 deleted." when the commit holds only @noldova/a
1832
1899
  * ```
@@ -2193,7 +2260,7 @@ export declare class DependentsStep implements IStep {
2193
2260
  *
2194
2261
  * declare const host: IUpdateHost;
2195
2262
  * const processRunner = new ProcessRunner();
2196
- * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
2263
+ * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
2197
2264
  * const step = new DependentsStep(archiveStep, host, processRunner, new Npm(processRunner, process.cwd()));
2198
2265
  * step.name; // "dependents"
2199
2266
  * ```
@@ -2226,3 +2293,92 @@ export declare class DependentsStep implements IStep {
2226
2293
  */
2227
2294
  public runAsync(values: readonly string[]): Promise<StepResult>;
2228
2295
  }
2296
+
2297
+ /**
2298
+ * The step that moves the repositories that pin a shared repository's
2299
+ * workflows: `pins <version> <commit>`. Run from a clone of the shared
2300
+ * repository after it tags `v<version>` at the commit, it reads the outside
2301
+ * actions the commit's `.github/workflows` pin, as
2302
+ * `uses: <action>@<commit> # v<version>`, keeping the highest version of each,
2303
+ * and checks out each repository the {@link IUpdateHost} lists. In each
2304
+ * one's tracked workflows, it moves each pin on a
2305
+ * workflow of the shared repository under the repository's own owner, such
2306
+ * as `uses: <owner>/<source>/.github/workflows/check.yml@<commit> # v1.2.0`,
2307
+ * to the commit and tag when the pin's version is older within the same major
2308
+ * version, or has none and its commit is in the tagged commit's history; a
2309
+ * pin a major version behind, or with no version and a commit the tag doesn't
2310
+ * hold, is left as it is and named, since it may need changes in its caller
2311
+ * or be newer than the tag. It moves each outside action older than the
2312
+ * shared repository's to the shared one's commit and tag, naming apart those
2313
+ * that move to a new major version, except in a repository with a tracked
2314
+ * `.github/dependabot.yml` or `.github/dependabot.yaml`, whose outside actions
2315
+ * Dependabot moves. Then it commits, pushes the branch `pipelines/pins-<source>`
2316
+ * and proposes it, with the moved and the left pins and the release's notes
2317
+ * in its description. When the branch exists, it replaces it only when the
2318
+ * branch is at a commit of its own, made by the same committer with its
2319
+ * title, and otherwise fails that repository, so nobody's commits are lost.
2320
+ * A repository with nothing to move is left as it is.
2321
+ */
2322
+ export declare class PinsStep implements IStep {
2323
+ /**
2324
+ * The step's name, `"pins"`.
2325
+ */
2326
+ public readonly name: string;
2327
+
2328
+ /**
2329
+ * The values the step takes, `"<version> <commit>"`.
2330
+ */
2331
+ public readonly usage: string;
2332
+
2333
+ /**
2334
+ * Creates the step.
2335
+ *
2336
+ * @param git The reader of the shared repository's clone.
2337
+ * @param updateHost What lists, checks out, pushes to and proposes in the
2338
+ * repositories.
2339
+ * @param processRunner What runs git in each repository's clone.
2340
+ * @param temporaryRoot The folder the step makes its temporary folder in,
2341
+ * such as one the pipeline host empties after each job. Omitted or empty,
2342
+ * it is `os.tmpdir()`.
2343
+ * @param output Where each repository's line is written as soon as that
2344
+ * repository is done, as a success or a failure, so a run stopped partway
2345
+ * still shows the repositories it finished; the result's message then holds
2346
+ * only the summary. Omitted, the lines are in the result's message.
2347
+ * @example
2348
+ * ```ts
2349
+ * import { Git, type IUpdateHost, PinsStep, ProcessRunner } from "@noldova/tools.pipelines";
2350
+ *
2351
+ * declare const host: IUpdateHost;
2352
+ * const processRunner = new ProcessRunner();
2353
+ * const step = new PinsStep(new Git(processRunner, process.cwd()), host, processRunner);
2354
+ * step.name; // "pins"
2355
+ * ```
2356
+ */
2357
+ public constructor(git: Git, updateHost: IUpdateHost, processRunner: ProcessRunner, temporaryRoot?: string, output?: IStepOutput);
2358
+
2359
+ /**
2360
+ * Moves the pins in every repository that has older ones.
2361
+ *
2362
+ * @param values The version, a release version such as `1.2.0`, and the
2363
+ * full id of the commit its tag names.
2364
+ * @returns A promise of the result, with a line for each repository, or,
2365
+ * given an output, only the summary: the proposal's address and how many
2366
+ * pins moved, that it pins nothing older, the pins left a major version
2367
+ * behind, or why it failed. It fails for any
2368
+ * number of values but two, a version that isn't one or is a nightly, a
2369
+ * commit that isn't a full id, what the host can't answer, and when any
2370
+ * repository fails, after trying every other; an error in one repository,
2371
+ * such as git failing, is that repository's line. It removes its temporary
2372
+ * folder whether it succeeds or fails, and rejects with
2373
+ * {@link ProcessException} if git cannot start or fails while it reads the
2374
+ * commit's workflows.
2375
+ * @example
2376
+ * ```ts
2377
+ * (await step.runAsync(["1.2.0", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message;
2378
+ * // Looked for pins on .github's workflows older than v1.2.0 in 2 repositories:
2379
+ * // noldova-com/example: moved 3 pins in https://github.com/noldova-com/example/pull/7
2380
+ * // noldova-com/sample: pins nothing older than v1.2.0.
2381
+ * ```
2382
+ */
2383
+ public runAsync(values: readonly string[]): Promise<StepResult>;
2384
+ }
package/api/index.js CHANGED
@@ -21,6 +21,7 @@ export { Git } from "../services/git.js";
21
21
  export { LineEndingsStep } from "../services/line-endings-step.js";
22
22
  export { NightlyStep } from "../services/nightly-step.js";
23
23
  export { Npm } from "../services/npm.js";
24
+ export { PinsStep } from "../services/pins-step.js";
24
25
  export { ProcessRunner } from "../services/process-runner.js";
25
26
  export { PruneStep } from "../services/prune-step.js";
26
27
  export { PublishStep } from "../services/publish-step.js";
package/api/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/noldova.tools.pipelines/src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAMtE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/noldova.tools.pipelines/src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAMtE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@noldova/tools.pipelines",
3
- "version": "0.0.6",
3
+ "version": "0.0.8",
4
4
  "type": "module",
5
5
  "main": "api/index.js",
6
6
  "types": "api/index.d.ts",
@@ -22,5 +22,5 @@
22
22
  "@noldova/context.exceptions": "0.0.3",
23
23
  "@noldova/context.json": "0.0.3"
24
24
  },
25
- "gitHead": "84452da7421d10220c9abfde5c684c9f29d4e928"
25
+ "gitHead": "35217254d5c6fe25ce9bc38f0a637b1fecfdff2d"
26
26
  }