@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 +97 -4
- package/api/index.d.ts +602 -8
- package/api/index.js +6 -0
- package/api/index.js.map +1 -1
- package/interfaces/i-registry-host.js +9 -0
- package/interfaces/i-registry-host.js.map +1 -0
- package/models/tracked-file.js +18 -0
- package/models/tracked-file.js.map +1 -0
- package/package.json +2 -2
- package/resources.js +164 -2
- package/resources.js.map +1 -1
- package/services/archive-step.js +16 -0
- package/services/archive-step.js.map +1 -1
- package/services/git.js +41 -0
- package/services/git.js.map +1 -1
- package/services/line-endings-step.js +57 -0
- package/services/line-endings-step.js.map +1 -0
- package/services/npm.js +17 -1
- package/services/npm.js.map +1 -1
- package/services/prune-step.js +102 -0
- package/services/prune-step.js.map +1 -0
- package/services/reproducible-step.js +84 -0
- package/services/reproducible-step.js.map +1 -0
- package/services/tar.js +3 -0
- package/services/tar.js.map +1 -1
- package/services/toolchain-step.js +38 -0
- package/services/toolchain-step.js.map +1 -0
- package/services/unchanged-step.js +26 -0
- package/services/unchanged-step.js.map +1 -0
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
|
|
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`,
|
|
1027
|
-
*
|
|
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
|
+
}
|