@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/api/index.d.ts CHANGED
@@ -351,6 +351,46 @@ export declare class StepResult {
351
351
  public static failed(message: string): StepResult;
352
352
  }
353
353
 
354
+ /**
355
+ * A file a checkout tracks, as {@link Git.listTrackedFilesAsync} lists it.
356
+ */
357
+ export declare class TrackedFile {
358
+ /**
359
+ * The file's path from the working directory, with `/` between folders.
360
+ */
361
+ public readonly filePath: string;
362
+
363
+ /**
364
+ * The line endings of the file's committed content, as git names them:
365
+ * `"lf"`, `"crlf"`, `"mixed"`, `"none"` for text without a line ending,
366
+ * `"-text"` for content git sees as binary, or `""` for an entry without
367
+ * content of its own, such as a submodule.
368
+ */
369
+ public readonly lineEndings: string;
370
+
371
+ /**
372
+ * Whether the file is text: not a symbolic link, not an entry without
373
+ * content of its own, not binary as git sees its content, and not marked
374
+ * `-text`, or `binary`, in `.gitattributes`.
375
+ */
376
+ public readonly isText: boolean;
377
+
378
+ /**
379
+ * Creates a tracked file.
380
+ *
381
+ * @param filePath The file's path from the working directory.
382
+ * @param lineEndings The line endings of its committed content.
383
+ * @param isText Whether the file is text.
384
+ * @example
385
+ * ```ts
386
+ * import { TrackedFile } from "@noldova/tools.pipelines";
387
+ *
388
+ * new TrackedFile("README.md", "lf", true).isText; // true
389
+ * ```
390
+ */
391
+ public constructor(filePath: string, lineEndings: string, isText: boolean);
392
+ }
393
+
354
394
  /**
355
395
  * A package and the path of its archive, as {@link ArchiveStep} checked it.
356
396
  */
@@ -424,7 +464,7 @@ export declare interface IStep {
424
464
 
425
465
  /**
426
466
  * The values the step takes, as a usage line shows them, such as
427
- * `"<version> <commit>"`.
467
+ * `"<version> <commit>"`; `""` for a step that takes none.
428
468
  */
429
469
  readonly usage: string;
430
470
 
@@ -545,6 +585,68 @@ export declare interface ITagHost {
545
585
  createTagAsync(tag: string, commit: string): Promise<boolean | StepResult>;
546
586
  }
547
587
 
588
+ /**
589
+ * How the {@link PruneStep} lists and deletes a package's versions on a
590
+ * registry, which the registry's host implements, such as through the
591
+ * host's API.
592
+ */
593
+ export declare interface IRegistryHost {
594
+ /**
595
+ * The registry the host lists and deletes versions on, an `https` URL such
596
+ * as `https://npm.pkg.github.com/`; the prune step runs only for it, and
597
+ * never for npm's registry, `https://registry.npmjs.org/`.
598
+ */
599
+ readonly registry: string;
600
+
601
+ /**
602
+ * Lists every version of a package the registry has.
603
+ *
604
+ * @param packageName The package's name, inside its scope, such as
605
+ * `@noldova/tools.pipelines`.
606
+ * @returns A promise of the versions' texts, in any order, including any
607
+ * that are not release versions, or a failed {@link StepResult} that says
608
+ * why the host could not list them.
609
+ * @example
610
+ * ```ts
611
+ * import type { IRegistryHost } from "@noldova/tools.pipelines";
612
+ *
613
+ * const versions = new Map([["@noldova/a", ["0.0.3", "0.0.4"]]]);
614
+ * const host: IRegistryHost = {
615
+ * registry: "https://npm.pkg.github.com/",
616
+ * readVersionsAsync: async packageName => versions.get(packageName) ?? [],
617
+ * deleteVersionAsync: async () => true
618
+ * };
619
+ * await host.readVersionsAsync("@noldova/a"); // ["0.0.3", "0.0.4"]
620
+ * ```
621
+ */
622
+ readVersionsAsync(packageName: string): Promise<readonly string[] | StepResult>;
623
+
624
+ /**
625
+ * Deletes one version of a package from the registry.
626
+ *
627
+ * @param packageName The package's name, inside its scope.
628
+ * @param version The version's text, as {@link IRegistryHost.readVersionsAsync}
629
+ * listed it.
630
+ * @returns A promise of `true` when it deleted the version, `false` when
631
+ * the registry no longer has it, such as after another run deleted it, or
632
+ * a failed {@link StepResult} that says why the host could not delete it.
633
+ * @example
634
+ * ```ts
635
+ * import type { IRegistryHost } from "@noldova/tools.pipelines";
636
+ *
637
+ * const versions = new Set(["0.0.3", "0.0.4"]);
638
+ * const host: IRegistryHost = {
639
+ * registry: "https://npm.pkg.github.com/",
640
+ * readVersionsAsync: async () => [...versions],
641
+ * deleteVersionAsync: async (packageName, version) => versions.delete(version)
642
+ * };
643
+ * await host.deleteVersionAsync("@noldova/a", "0.0.3"); // true
644
+ * await host.deleteVersionAsync("@noldova/a", "0.0.3"); // false
645
+ * ```
646
+ */
647
+ deleteVersionAsync(packageName: string, version: string): Promise<boolean | StepResult>;
648
+ }
649
+
548
650
  /**
549
651
  * The command-line base a pipeline host builds its command line on: it runs
550
652
  * the step its first value names with the values after it, writes the step's
@@ -631,6 +733,11 @@ export declare class ProcessRunner {
631
733
  * `git` program.
632
734
  */
633
735
  export declare class Git {
736
+ /**
737
+ * The directory git runs in, as the constructor was given it.
738
+ */
739
+ public readonly workingDirectory: string;
740
+
634
741
  /**
635
742
  * Creates a reader of one clone.
636
743
  *
@@ -646,6 +753,41 @@ export declare class Git {
646
753
  */
647
754
  public constructor(processRunner: ProcessRunner, workingDirectory: string);
648
755
 
756
+ /**
757
+ * Adds a worktree of the clone at a commit, detached from any branch.
758
+ *
759
+ * @param directory The worktree's directory: a new or empty one.
760
+ * @param commit The commit, which the clone holds.
761
+ * @returns A promise that resolves once the worktree is checked out. It
762
+ * rejects with {@link ProcessException} if git cannot start or fails, such
763
+ * as when the directory holds files.
764
+ * @example
765
+ * ```ts
766
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
767
+ *
768
+ * const git = new Git(new ProcessRunner(), process.cwd());
769
+ * await git.addWorktreeAsync("/tmp/second-build", await git.readHeadAsync());
770
+ * ```
771
+ */
772
+ public addWorktreeAsync(directory: string, commit: string): Promise<void>;
773
+
774
+ /**
775
+ * Removes a worktree and its directory, with the files a build wrote in
776
+ * it.
777
+ *
778
+ * @param directory The worktree's directory.
779
+ * @returns A promise that resolves once the worktree is removed. It rejects
780
+ * with {@link ProcessException} if git cannot start or fails, such as when
781
+ * the directory is not a worktree of the clone.
782
+ * @example
783
+ * ```ts
784
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
785
+ *
786
+ * await new Git(new ProcessRunner(), process.cwd()).removeWorktreeAsync("/tmp/second-build");
787
+ * ```
788
+ */
789
+ public removeWorktreeAsync(directory: string): Promise<void>;
790
+
649
791
  /**
650
792
  * Tells whether a revision names a commit in the clone.
651
793
  *
@@ -724,6 +866,64 @@ export declare class Git {
724
866
  */
725
867
  public listFilesAsync(commit: string, folderPath: string): Promise<readonly string[]>;
726
868
 
869
+ /**
870
+ * Lists what `git status --porcelain` lists: the checkout's changed,
871
+ * staged and untracked paths, outside the ignored ones.
872
+ *
873
+ * @returns A promise of each line git writes, such as ` M README.md` or
874
+ * `?? notes.txt`, with paths from the repository's root as git quotes
875
+ * them; none for a checkout as committed. It rejects with
876
+ * {@link ProcessException} if git cannot start or fails otherwise, such as
877
+ * outside a clone.
878
+ * @example
879
+ * ```ts
880
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
881
+ *
882
+ * const git = new Git(new ProcessRunner(), process.cwd());
883
+ * await git.listChangesAsync(); // [] in a checkout as committed
884
+ * ```
885
+ */
886
+ public listChangesAsync(): Promise<readonly string[]>;
887
+
888
+ /**
889
+ * Lists the files the index tracks in the working directory and the
890
+ * folders inside it.
891
+ *
892
+ * @returns A promise of each file, in git's order, with its line endings
893
+ * and whether it is text; none when the index tracks no file there. It
894
+ * rejects with {@link ProcessException} if git cannot start or fails
895
+ * otherwise, such as outside a clone.
896
+ * @example
897
+ * ```ts
898
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
899
+ *
900
+ * const git = new Git(new ProcessRunner(), process.cwd());
901
+ * (await git.listTrackedFilesAsync()).filter(t => t.isText).length; // the number of tracked text files
902
+ * ```
903
+ */
904
+ public listTrackedFilesAsync(): Promise<readonly TrackedFile[]>;
905
+
906
+ /**
907
+ * Reads the last bytes of a file as the checkout holds it, which can
908
+ * differ from the committed content when the file was changed after the
909
+ * checkout.
910
+ *
911
+ * @param filePath The file's path from the working directory.
912
+ * @param byteCount How many bytes to read from the file's end.
913
+ * @returns A promise of the file's last `byteCount` bytes, or all of them
914
+ * for a shorter file; `null` when the checkout has no file at the path,
915
+ * such as after the file was deleted. It rejects with the file system's
916
+ * error if the file cannot be read otherwise.
917
+ * @example
918
+ * ```ts
919
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
920
+ *
921
+ * const git = new Git(new ProcessRunner(), process.cwd());
922
+ * (await git.readCheckoutFileEndAsync("README.md", 2))?.toString("utf8"); // ".\n"
923
+ * ```
924
+ */
925
+ public readCheckoutFileEndAsync(filePath: string, byteCount: number): Promise<Buffer | null>;
926
+
727
927
  /**
728
928
  * Reads a file as a commit holds it.
729
929
  *
@@ -761,7 +961,7 @@ export declare class Git {
761
961
  }
762
962
 
763
963
  /**
764
- * Reads files from `.tgz` archives through the `tar` program.
964
+ * Reads and lists files in `.tgz` archives through the `tar` program.
765
965
  */
766
966
  export declare class Tar {
767
967
  /**
@@ -798,6 +998,27 @@ export declare class Tar {
798
998
  * ```
799
999
  */
800
1000
  public readFileAsync(archivePath: string, filePath: string): Promise<ProcessResult>;
1001
+
1002
+ /**
1003
+ * Lists the paths an archive holds.
1004
+ *
1005
+ * @param archivePath The archive's path, such as
1006
+ * `archives/noldova-tools.pipelines-0.0.4.tgz`.
1007
+ * @returns A promise of how `tar` ended: on success, its output has one
1008
+ * path inside the archive on each line, such as `package/package.json`,
1009
+ * with a folder's path ending in `/` when the archive lists it; when the
1010
+ * archive is not a `.tgz`, it failed, with `tar`'s message. It rejects with
1011
+ * {@link ProcessException} if `tar` cannot start, such as when it is not
1012
+ * installed or the archive's folder does not exist.
1013
+ * @example
1014
+ * ```ts
1015
+ * import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
1016
+ *
1017
+ * const result = await new Tar(new ProcessRunner()).listFilesAsync("archives/noldova-tools.pipelines-0.0.4.tgz");
1018
+ * result.output.split(/\r?\n/).includes("package/LICENSE"); // true when the archive holds its license
1019
+ * ```
1020
+ */
1021
+ public listFilesAsync(archivePath: string): Promise<ProcessResult>;
801
1022
  }
802
1023
 
803
1024
  /**
@@ -812,6 +1033,9 @@ export declare class Npm {
812
1033
  * @param processRunner The runner that starts `npm`.
813
1034
  * @param workingDirectory The directory `npm` runs in, whose configuration
814
1035
  * it reads.
1036
+ * @param platform The platform npm runs on, as `process.platform` names it;
1037
+ * on `win32`, where npm is a command script, it reads npm's version
1038
+ * through `cmd.exe`. Omitted, it is `process.platform`.
815
1039
  * @example
816
1040
  * ```ts
817
1041
  * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
@@ -819,7 +1043,7 @@ export declare class Npm {
819
1043
  * const npm = new Npm(new ProcessRunner(), process.cwd());
820
1044
  * ```
821
1045
  */
822
- public constructor(processRunner: ProcessRunner, workingDirectory: string);
1046
+ public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string);
823
1047
 
824
1048
  /**
825
1049
  * Reads a field of a package or a version from the registry, asking the
@@ -889,6 +1113,40 @@ export declare class Npm {
889
1113
  */
890
1114
  public publishAsync(archivePath: string, tag: string, access: string, registry: string): Promise<ProcessResult>;
891
1115
 
1116
+ /**
1117
+ * Runs the build script of the package in a directory, with
1118
+ * `npm run build`, or on Windows `cmd.exe /d /s /c "npm.cmd run build"`, a
1119
+ * fixed command.
1120
+ *
1121
+ * @param directory The directory whose `package.json` names the build
1122
+ * script.
1123
+ * @returns A promise of npm's exit code and of what it wrote; a build that
1124
+ * fails still resolves. It rejects with {@link ProcessException} if the
1125
+ * program cannot start.
1126
+ * @example
1127
+ * ```ts
1128
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
1129
+ *
1130
+ * (await new Npm(new ProcessRunner(), process.cwd()).buildAsync("/tmp/second-build")).isSuccessful; // true when the build passes
1131
+ * ```
1132
+ */
1133
+ public buildAsync(directory: string): Promise<ProcessResult>;
1134
+
1135
+ /**
1136
+ * Reads the version of the npm that runs, with `npm --version`, or on
1137
+ * Windows `cmd.exe /d /s /c "npm.cmd --version"`, a fixed command.
1138
+ *
1139
+ * @returns A promise of the version, such as `11.19.0`. It rejects with
1140
+ * {@link ProcessException} if npm cannot start or fails.
1141
+ * @example
1142
+ * ```ts
1143
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
1144
+ *
1145
+ * await new Npm(new ProcessRunner(), process.cwd()).readVersionAsync(); // "11.19.0"
1146
+ * ```
1147
+ */
1148
+ public readVersionAsync(): Promise<string>;
1149
+
892
1150
  /**
893
1151
  * Tells whether a text is a registry the steps take: an `https` URL
894
1152
  * without credentials, a query or a fragment.
@@ -975,8 +1233,12 @@ export declare class SourceStep implements IStep {
975
1233
  * the commit, and the folder holds exactly one archive for each package at
976
1234
  * the version, named as `npm pack` names it, whose `package/package.json`
977
1235
  * has the package's name, inside the scope, the version, and the commit as
978
- * its `gitHead`, is not `"private": true`, and lists any expected package under `dependencies` at
979
- * exactly the version.
1236
+ * its `gitHead`, is not `"private": true`, has a `license`, and lists any expected package under `dependencies` at
1237
+ * exactly the version. Each archive must also hold `package/LICENSE`, and no
1238
+ * file of a kind that holds credentials: `.npmrc`, `.netrc`, `.env` or
1239
+ * `.env.<name>`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, or a name
1240
+ * ending in `.pem`, `.key`, `.p12` or `.pfx`, such as `.key` itself, in any
1241
+ * folder and whatever its case.
980
1242
  */
981
1243
  export declare class ArchiveStep implements IStep {
982
1244
  /**
@@ -1023,11 +1285,14 @@ export declare class ArchiveStep implements IStep {
1023
1285
  * archive missing, a file that is not an expected archive, an archive
1024
1286
  * `tar` cannot read the manifest of, with `tar`'s exit code and message,
1025
1287
  * and a manifest with another name, a name outside the scope, another
1026
- * version, no `gitHead` or another one, `"private": true`, or an expected package under `dependencies`
1027
- * at anything but exactly the version. It rejects with `JsonException`,
1288
+ * version, no `gitHead` or another one, `"private": true`, no `license`
1289
+ * or an empty one, or an expected package under `dependencies`
1290
+ * at anything but exactly the version, an archive `tar` cannot list the
1291
+ * files of, with `tar`'s exit code and message, a file of a kind that holds
1292
+ * credentials, and no `package/LICENSE`. It rejects with `JsonException`,
1028
1293
  * from `@noldova/context.json`, if a `package.json` the step reads is not
1029
1294
  * a JSON object, lacks a `name` or `version` text where it needs one, has
1030
- * a `gitHead` that is not a text, or
1295
+ * a `gitHead` or a `license` that is not a text, or
1031
1296
  * has a `private` that is not `true` or `false` or `dependencies` that are
1032
1297
  * not an object of texts, and with {@link ProcessException} if git or
1033
1298
  * `tar` cannot start or git fails otherwise.
@@ -1241,6 +1506,99 @@ export declare class NightlyStep implements IStep {
1241
1506
  public runAsync(values: readonly string[]): Promise<StepResult>;
1242
1507
  }
1243
1508
 
1509
+ /**
1510
+ * The step that keeps a registry's newest versions after a release:
1511
+ * `prune <version> <commit> <scope> <registry> <keep-versions>`. Through
1512
+ * the host's {@link IRegistryHost}, it deletes each package's older release
1513
+ * versions, keeping the newest; it runs only on the host's registry, never
1514
+ * on npm's, and deletes nothing unless the release is every package's
1515
+ * newest.
1516
+ */
1517
+ export declare class PruneStep implements IStep {
1518
+ /**
1519
+ * The step's name, `"prune"`.
1520
+ */
1521
+ public readonly name: string;
1522
+
1523
+ /**
1524
+ * The values the step takes,
1525
+ * `"<version> <commit> <scope> <registry> <keep-versions>"`.
1526
+ */
1527
+ public readonly usage: string;
1528
+
1529
+ /**
1530
+ * Creates the step.
1531
+ *
1532
+ * @param git The reader of the clone that holds the commit.
1533
+ * @param archiveStep The step whose expected packages the step prunes.
1534
+ * @param registryHost How the step lists and deletes versions on the
1535
+ * registry.
1536
+ * @example
1537
+ * ```ts
1538
+ * import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1539
+ *
1540
+ * const processRunner = new ProcessRunner();
1541
+ * const git = new Git(processRunner, process.cwd());
1542
+ * const host: IRegistryHost = {
1543
+ * registry: "https://npm.pkg.github.com/",
1544
+ * readVersionsAsync: async () => [],
1545
+ * deleteVersionAsync: async () => true
1546
+ * };
1547
+ * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
1548
+ * step.name; // "prune"
1549
+ * ```
1550
+ */
1551
+ public constructor(git: Git, archiveStep: ArchiveStep, registryHost: IRegistryHost);
1552
+
1553
+ /**
1554
+ * Deletes the older release versions of the packages a commit holds.
1555
+ *
1556
+ * @param values The release version just published, such as `0.0.4`; the
1557
+ * commit's full id, 40 lowercase hexadecimal digits; the scope, such as
1558
+ * `@noldova`; the registry, an `https` URL without credentials, a query or
1559
+ * a fragment, which must be the host's and not npm's; and how many release
1560
+ * versions to keep, a whole number above 0 without a leading zero, such as
1561
+ * `5`.
1562
+ * @returns A promise of the result. It fails with the first of these that
1563
+ * is wrong, asking the registry nothing: not five values, a version that
1564
+ * is not a version, a nightly version, a commit that is not a full id, a
1565
+ * scope that is not `@` and a lowercase name, a registry that is not one,
1566
+ * is npm's or is not the host's, a number to keep that is not one, a commit
1567
+ * the clone does not hold, a commit without a package to publish, and a
1568
+ * package outside the scope. Otherwise it lists every package's versions
1569
+ * first, and fails, deleting nothing, with one line for each package whose
1570
+ * versions the host could not list and each whose newest release version
1571
+ * is not the version. Then it deletes each package's release versions
1572
+ * after the newest it keeps, and succeeds with one line for each, such as
1573
+ * `@noldova/tools.pipelines@0.0.1 deleted.` or
1574
+ * `@noldova/tools.pipelines@0.0.1 was already deleted.`, or with one line
1575
+ * saying nothing is deleted when no package has more. It stops at the
1576
+ * first delete that fails, with the lines before it and the host's
1577
+ * answer, or, when the delete rejects with an `Error`, a line naming the
1578
+ * version with the error's message. Versions that are not release
1579
+ * versions, such as nightly ones, are neither counted nor deleted. It
1580
+ * rejects as {@link ArchiveStep.readPackageNamesAsync} and the host's
1581
+ * list do, and as a delete does that rejects with anything but an `Error`.
1582
+ * @example
1583
+ * ```ts
1584
+ * import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
1585
+ *
1586
+ * const processRunner = new ProcessRunner();
1587
+ * const git = new Git(processRunner, process.cwd());
1588
+ * const versions = new Set(["0.0.1", "0.0.2", "0.0.3"]);
1589
+ * const host: IRegistryHost = {
1590
+ * registry: "https://npm.pkg.github.com/",
1591
+ * readVersionsAsync: async () => [...versions],
1592
+ * deleteVersionAsync: async (packageName, version) => versions.delete(version)
1593
+ * };
1594
+ * const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
1595
+ * const result = await step.runAsync(["0.0.3", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://npm.pkg.github.com/", "2"]);
1596
+ * result.message; // "@noldova/a@0.0.1 deleted." when the commit holds only @noldova/a
1597
+ * ```
1598
+ */
1599
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1600
+ }
1601
+
1244
1602
  /**
1245
1603
  * The step a release ends with: it tags the released commit `v<version>`,
1246
1604
  * through the host's {@link ITagHost}, and never moves a tag.
@@ -1305,3 +1663,239 @@ export declare class TagStep implements IStep {
1305
1663
  */
1306
1664
  public runAsync(values: readonly string[]): Promise<StepResult>;
1307
1665
  }
1666
+
1667
+ /**
1668
+ * The step that checks the line endings of the files a checkout tracks:
1669
+ * `line-endings`, which takes no values. It succeeds only when
1670
+ * `.gitattributes` at the checkout's root holds the line
1671
+ * `* text=auto eol=lf`, and every tracked text file uses LF line endings and
1672
+ * ends with exactly one newline. It skips the files that are not text, as
1673
+ * {@link TrackedFile.isText} tells.
1674
+ */
1675
+ export declare class LineEndingsStep implements IStep {
1676
+ /**
1677
+ * The step's name, `"line-endings"`.
1678
+ */
1679
+ public readonly name: string;
1680
+
1681
+ /**
1682
+ * The values the step takes: none, `""`.
1683
+ */
1684
+ public readonly usage: string;
1685
+
1686
+ /**
1687
+ * Creates the step over a checkout.
1688
+ *
1689
+ * @param git The reader of the clone, whose working directory is the
1690
+ * checkout's root, or the folder whose files the step checks.
1691
+ * @example
1692
+ * ```ts
1693
+ * import { Git, LineEndingsStep, ProcessRunner } from "@noldova/tools.pipelines";
1694
+ *
1695
+ * const step = new LineEndingsStep(new Git(new ProcessRunner(), process.cwd()));
1696
+ * step.name; // "line-endings"
1697
+ * ```
1698
+ */
1699
+ public constructor(git: Git);
1700
+
1701
+ /**
1702
+ * Checks the line endings.
1703
+ *
1704
+ * @param values None.
1705
+ * @returns A promise of the result: succeeded, such as
1706
+ * `.gitattributes holds "* text=auto eol=lf", and the 12 tracked text
1707
+ * files use LF line endings and end with exactly one newline.`, or failed
1708
+ * when values are given, when git lists no tracked file, or with one line
1709
+ * for each thing that is wrong, naming the file and the fix: a
1710
+ * `.gitattributes` without the line, a file whose committed content has
1711
+ * CRLF or mixed line endings, a file the checkout does not hold, a file
1712
+ * that does not end with a newline, and a file that ends with a blank
1713
+ * line. The line endings come from the committed content, and the files'
1714
+ * ends from the checkout, so a pipeline runs the step on a checkout as
1715
+ * committed, before anything changes it. It rejects with
1716
+ * {@link ProcessException} if git cannot start or fails otherwise, such as
1717
+ * outside a clone.
1718
+ * @example
1719
+ * ```ts
1720
+ * import { Git, LineEndingsStep, ProcessRunner } from "@noldova/tools.pipelines";
1721
+ *
1722
+ * const step = new LineEndingsStep(new Git(new ProcessRunner(), process.cwd()));
1723
+ * const result = await step.runAsync([]);
1724
+ * result.message; // "\"README.md\" does not end with a newline; add one." when it does not
1725
+ * (await step.runAsync(["src"])).message; // "The line-endings step takes no values."
1726
+ * ```
1727
+ */
1728
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1729
+ }
1730
+
1731
+ /**
1732
+ * The step that checks that a checkout is as committed: `unchanged`, which
1733
+ * takes no values. Run after a build and its tests, it finds the tracked
1734
+ * files they changed and the files they wrote outside the ignored paths.
1735
+ */
1736
+ export declare class UnchangedStep implements IStep {
1737
+ /**
1738
+ * The step's name, `"unchanged"`.
1739
+ */
1740
+ public readonly name: string;
1741
+
1742
+ /**
1743
+ * The values the step takes: none, `""`.
1744
+ */
1745
+ public readonly usage: string;
1746
+
1747
+ /**
1748
+ * Creates the step over a checkout.
1749
+ *
1750
+ * @param git The reader of the clone.
1751
+ * @example
1752
+ * ```ts
1753
+ * import { Git, ProcessRunner, UnchangedStep } from "@noldova/tools.pipelines";
1754
+ *
1755
+ * const step = new UnchangedStep(new Git(new ProcessRunner(), process.cwd()));
1756
+ * step.name; // "unchanged"
1757
+ * ```
1758
+ */
1759
+ public constructor(git: Git);
1760
+
1761
+ /**
1762
+ * Checks that the checkout has no changed or untracked file.
1763
+ *
1764
+ * @param values None.
1765
+ * @returns A promise of the result: succeeded,
1766
+ * `The checkout has no changed or untracked file.`, when `git status
1767
+ * --porcelain` lists nothing, or failed when values are given, or with
1768
+ * each path git lists, as it lists them, and how to fix it. It rejects with
1769
+ * {@link ProcessException} if git cannot start or fails otherwise, such as
1770
+ * outside a clone.
1771
+ * @example
1772
+ * ```ts
1773
+ * import { Git, ProcessRunner, UnchangedStep } from "@noldova/tools.pipelines";
1774
+ *
1775
+ * const step = new UnchangedStep(new Git(new ProcessRunner(), process.cwd()));
1776
+ * (await step.runAsync([])).isSuccessful; // true in a checkout as committed
1777
+ * ```
1778
+ */
1779
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1780
+ }
1781
+
1782
+ /**
1783
+ * The step that checks the toolchain a job runs:
1784
+ * `toolchain <node-version> [<npm-version>]`. It succeeds only when the
1785
+ * Node.js that runs it is that version and, when an npm version is given,
1786
+ * `npm --version` prints it.
1787
+ */
1788
+ export declare class ToolchainStep implements IStep {
1789
+ /**
1790
+ * The step's name, `"toolchain"`.
1791
+ */
1792
+ public readonly name: string;
1793
+
1794
+ /**
1795
+ * The values the step takes, `"<node-version> [<npm-version>]"`.
1796
+ */
1797
+ public readonly usage: string;
1798
+
1799
+ /**
1800
+ * Creates the step.
1801
+ *
1802
+ * @param npm What reads npm's version.
1803
+ * @param nodeVersion The version of the Node.js that runs the step, as
1804
+ * `process.version` gives it, such as `v24.21.0`.
1805
+ * @example
1806
+ * ```ts
1807
+ * import { Npm, ProcessRunner, ToolchainStep } from "@noldova/tools.pipelines";
1808
+ *
1809
+ * const step = new ToolchainStep(new Npm(new ProcessRunner(), process.cwd()), process.version);
1810
+ * step.name; // "toolchain"
1811
+ * ```
1812
+ */
1813
+ public constructor(npm: Npm, nodeVersion: string);
1814
+
1815
+ /**
1816
+ * Checks the toolchain.
1817
+ *
1818
+ * @param values The Node.js version, such as `24.21.0`, and optionally
1819
+ * the npm version, such as `11.19.0`; each exact, `major.minor.patch`.
1820
+ * An empty npm version is the same as none, so a workflow can pass a
1821
+ * setting that names none.
1822
+ * @returns A promise of the result: succeeded, such as
1823
+ * `Node.js v24.21.0 and npm 11.19.0 run this step.`, or failed for no
1824
+ * values or more than two, for a version that is not exact, or with one
1825
+ * line for each version that differs, naming the version found, the one
1826
+ * expected and the fix. It reads npm's version only when one is given, and
1827
+ * rejects with {@link ProcessException} if npm cannot start or fails.
1828
+ * @example
1829
+ * ```ts
1830
+ * import { Npm, ProcessRunner, ToolchainStep } from "@noldova/tools.pipelines";
1831
+ *
1832
+ * const step = new ToolchainStep(new Npm(new ProcessRunner(), process.cwd()), "v24.20.0");
1833
+ * (await step.runAsync(["24.21.0"])).message; // "Node.js v24.20.0 runs this step, not v24.21.0; set up Node.js 24.21.0 before it."
1834
+ * ```
1835
+ */
1836
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1837
+ }
1838
+
1839
+ /**
1840
+ * The step that checks a build is reproducible: `reproducible <folder>`.
1841
+ * Run after the build in a checkout, it builds the checkout's commit again in
1842
+ * a worktree in a new temporary folder, with `npm run build`, and succeeds
1843
+ * only when both builds' `<folder>` hold the same `.tgz` archives, byte for
1844
+ * byte, so that rerunning a release publishes nothing new.
1845
+ */
1846
+ export declare class ReproducibleStep implements IStep {
1847
+ /**
1848
+ * The step's name, `"reproducible"`.
1849
+ */
1850
+ public readonly name: string;
1851
+
1852
+ /**
1853
+ * The values the step takes, `"<folder>"`.
1854
+ */
1855
+ public readonly usage: string;
1856
+
1857
+ /**
1858
+ * Creates the step over a checkout.
1859
+ *
1860
+ * @param git The reader of the clone, whose working directory is the
1861
+ * checkout's root.
1862
+ * @param npm What runs the second build.
1863
+ * @param temporaryRoot The folder the step makes its temporary folder in,
1864
+ * such as one the pipeline host empties after each job, so a run that is
1865
+ * cancelled leaves nothing behind. Omitted or empty, it is `os.tmpdir()`.
1866
+ * @example
1867
+ * ```ts
1868
+ * import { Git, Npm, ProcessRunner, ReproducibleStep } from "@noldova/tools.pipelines";
1869
+ *
1870
+ * const processRunner = new ProcessRunner();
1871
+ * const step = new ReproducibleStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()));
1872
+ * step.name; // "reproducible"
1873
+ * ```
1874
+ */
1875
+ public constructor(git: Git, npm: Npm, temporaryRoot?: string);
1876
+
1877
+ /**
1878
+ * Builds the commit again and compares the archives.
1879
+ *
1880
+ * @param values The folder the build packs its archives into, as a path
1881
+ * from the checkout's root, such as `_packages`.
1882
+ * @returns A promise of the result: succeeded, listing each archive with
1883
+ * its SHA-512, or failed for any number of values but one, for a folder
1884
+ * that is absolute, outside the checkout or the checkout itself, a missing
1885
+ * folder or one without archives, a second build that
1886
+ * fails, with npm's exit code and error output, or with one line for each
1887
+ * archive that differs or is in only one build. It removes the worktree and
1888
+ * its folder whether it succeeds or fails, and rejects with
1889
+ * {@link ProcessException} if git or npm cannot start, or git fails, such
1890
+ * as outside a clone.
1891
+ * @example
1892
+ * ```ts
1893
+ * import { Git, Npm, ProcessRunner, ReproducibleStep } from "@noldova/tools.pipelines";
1894
+ *
1895
+ * const processRunner = new ProcessRunner();
1896
+ * const step = new ReproducibleStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()));
1897
+ * (await step.runAsync(["_packages"])).isSuccessful; // true when the second build packs the same archives
1898
+ * ```
1899
+ */
1900
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1901
+ }