@noldova/tools.pipelines 0.0.2 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -1
- package/api/index.d.ts +662 -3
- package/api/index.js +6 -0
- package/api/index.js.map +1 -1
- package/interfaces/i-update-host.js +9 -0
- package/interfaces/i-update-host.js.map +1 -0
- package/models/dependents-update.js +22 -0
- package/models/dependents-update.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 +169 -2
- package/resources.js.map +1 -1
- package/services/dependents-step.js +136 -0
- package/services/dependents-step.js.map +1 -0
- package/services/git.js +50 -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 +23 -1
- package/services/npm.js.map +1 -1
- package/services/process-runner.js +3 -2
- package/services/process-runner.js.map +1 -1
- package/services/reproducible-step.js +84 -0
- package/services/reproducible-step.js.map +1 -0
- 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,102 @@ export declare interface ITagHost {
|
|
|
545
585
|
createTagAsync(tag: string, commit: string): Promise<boolean | StepResult>;
|
|
546
586
|
}
|
|
547
587
|
|
|
588
|
+
/**
|
|
589
|
+
* How the {@link DependentsStep} reaches the repositories that may pin a
|
|
590
|
+
* release's packages, on the pipeline's host, which implements it, such as
|
|
591
|
+
* through the host's API and git.
|
|
592
|
+
*/
|
|
593
|
+
export declare interface IUpdateHost {
|
|
594
|
+
/**
|
|
595
|
+
* The environment variables that hold the host's credentials, such as
|
|
596
|
+
* `GITHUB_TOKEN`; the step keeps them from npm when it refreshes a
|
|
597
|
+
* repository's lock files.
|
|
598
|
+
*/
|
|
599
|
+
readonly credentialVariables: readonly string[];
|
|
600
|
+
|
|
601
|
+
/**
|
|
602
|
+
* Reads the name of the repository that released, which names the branch
|
|
603
|
+
* of each update.
|
|
604
|
+
*
|
|
605
|
+
* @returns The name, such as `tools`, or a failed
|
|
606
|
+
* {@link StepResult} that says what the host lacks to name it.
|
|
607
|
+
*/
|
|
608
|
+
readSourceName(): string | StepResult;
|
|
609
|
+
|
|
610
|
+
/**
|
|
611
|
+
* Lists the repositories the host may update, leaving out the one that
|
|
612
|
+
* released.
|
|
613
|
+
*
|
|
614
|
+
* @returns A promise of the repositories' full names, such as
|
|
615
|
+
* `noldova-com/example`, or a failed {@link StepResult} that says why
|
|
616
|
+
* the host could not answer.
|
|
617
|
+
*/
|
|
618
|
+
listRepositoriesAsync(): Promise<readonly string[] | StepResult>;
|
|
619
|
+
|
|
620
|
+
/**
|
|
621
|
+
* Reads the release notes of a version, from the change that merged its
|
|
622
|
+
* commit.
|
|
623
|
+
*
|
|
624
|
+
* @param version The version, such as `0.0.4`.
|
|
625
|
+
* @param commit The commit the version was released from.
|
|
626
|
+
* @returns A promise of the notes' section, starting with its heading, `""`
|
|
627
|
+
* when no change merged the commit or the one that did has none, or a failed {@link StepResult} that says why
|
|
628
|
+
* the host could not answer.
|
|
629
|
+
*/
|
|
630
|
+
readReleaseNotesAsync(version: string, commit: string): Promise<string | StepResult>;
|
|
631
|
+
|
|
632
|
+
/**
|
|
633
|
+
* Checks out a repository's default branch into a new directory, as a git
|
|
634
|
+
* clone the step can commit in.
|
|
635
|
+
*
|
|
636
|
+
* @param repository The repository's full name.
|
|
637
|
+
* @param directory The directory, which doesn't exist yet.
|
|
638
|
+
* @returns A promise of `null` once it is checked out, or a failed
|
|
639
|
+
* {@link StepResult} that says why not.
|
|
640
|
+
*/
|
|
641
|
+
checkOutAsync(repository: string, directory: string): Promise<StepResult | null>;
|
|
642
|
+
|
|
643
|
+
/**
|
|
644
|
+
* Fetches the commit a branch of the repository is at into the clone, so
|
|
645
|
+
* the step can read who made it.
|
|
646
|
+
*
|
|
647
|
+
* @param repository The repository's full name.
|
|
648
|
+
* @param directory The clone's directory.
|
|
649
|
+
* @param branch The branch, such as `pipelines/update-tools`.
|
|
650
|
+
* @returns A promise of the commit's full id, `null` when the repository
|
|
651
|
+
* has no such branch, or a failed {@link StepResult} that says why not.
|
|
652
|
+
*/
|
|
653
|
+
fetchBranchAsync(repository: string, directory: string, branch: string): Promise<string | null | StepResult>;
|
|
654
|
+
|
|
655
|
+
/**
|
|
656
|
+
* Pushes the clone's checked-out commit to a branch of the repository.
|
|
657
|
+
*
|
|
658
|
+
* @param repository The repository's full name.
|
|
659
|
+
* @param directory The clone's directory.
|
|
660
|
+
* @param branch The branch, such as `pipelines/update-tools`.
|
|
661
|
+
* @param replaced `null` to create the branch, which fails if it exists,
|
|
662
|
+
* or the commit {@link fetchBranchAsync} found it at, to replace it only
|
|
663
|
+
* while it is still at that commit.
|
|
664
|
+
* @returns A promise of `null` once it is pushed, or a failed
|
|
665
|
+
* {@link StepResult} that says why not.
|
|
666
|
+
*/
|
|
667
|
+
pushAsync(repository: string, directory: string, branch: string, replaced: string | null): Promise<StepResult | null>;
|
|
668
|
+
|
|
669
|
+
/**
|
|
670
|
+
* Proposes a pushed branch for merging into the default branch: opens the
|
|
671
|
+
* change and what links it, or, when one is open for the branch already,
|
|
672
|
+
* replaces its title and description.
|
|
673
|
+
*
|
|
674
|
+
* @param repository The repository's full name.
|
|
675
|
+
* @param branch The pushed branch.
|
|
676
|
+
* @param title The change's title.
|
|
677
|
+
* @param body The change's description, in Markdown.
|
|
678
|
+
* @returns A promise of the change's address, or a failed
|
|
679
|
+
* {@link StepResult} that says why not.
|
|
680
|
+
*/
|
|
681
|
+
proposeAsync(repository: string, branch: string, title: string, body: string): Promise<string | StepResult>;
|
|
682
|
+
}
|
|
683
|
+
|
|
548
684
|
/**
|
|
549
685
|
* How the {@link PruneStep} lists and deletes a package's versions on a
|
|
550
686
|
* registry, which the registry's host implements, such as through the
|
|
@@ -673,6 +809,10 @@ export declare class ProcessRunner {
|
|
|
673
809
|
* @param values The values passed to the program, each as one argument,
|
|
674
810
|
* never read by a shell.
|
|
675
811
|
* @param workingDirectory The directory the program runs in.
|
|
812
|
+
* @param environment Variables the program gets on top of this process's
|
|
813
|
+
* own, such as a credential only it may read, where a variable set to
|
|
814
|
+
* `undefined` is kept from it; omitted, it gets this process's variables
|
|
815
|
+
* alone.
|
|
676
816
|
* @returns A promise of the program's exit code and of what it wrote. A
|
|
677
817
|
* program that fails still resolves, with its exit code; the promise
|
|
678
818
|
* rejects with {@link ProcessException} only when the program cannot
|
|
@@ -685,7 +825,7 @@ export declare class ProcessRunner {
|
|
|
685
825
|
* result.isSuccessful; // true where git is installed
|
|
686
826
|
* ```
|
|
687
827
|
*/
|
|
688
|
-
public runAsync(program: string, values: readonly string[], workingDirectory: string): Promise<ProcessResult>;
|
|
828
|
+
public runAsync(program: string, values: readonly string[], workingDirectory: string, environment?: Readonly<Record<string, string | undefined>>): Promise<ProcessResult>;
|
|
689
829
|
}
|
|
690
830
|
|
|
691
831
|
/**
|
|
@@ -693,6 +833,11 @@ export declare class ProcessRunner {
|
|
|
693
833
|
* `git` program.
|
|
694
834
|
*/
|
|
695
835
|
export declare class Git {
|
|
836
|
+
/**
|
|
837
|
+
* The directory git runs in, as the constructor was given it.
|
|
838
|
+
*/
|
|
839
|
+
public readonly workingDirectory: string;
|
|
840
|
+
|
|
696
841
|
/**
|
|
697
842
|
* Creates a reader of one clone.
|
|
698
843
|
*
|
|
@@ -708,6 +853,58 @@ export declare class Git {
|
|
|
708
853
|
*/
|
|
709
854
|
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
710
855
|
|
|
856
|
+
/**
|
|
857
|
+
* Adds a worktree of the clone at a commit, detached from any branch.
|
|
858
|
+
*
|
|
859
|
+
* @param directory The worktree's directory: a new or empty one.
|
|
860
|
+
* @param commit The commit, which the clone holds.
|
|
861
|
+
* @returns A promise that resolves once the worktree is checked out. It
|
|
862
|
+
* rejects with {@link ProcessException} if git cannot start or fails, such
|
|
863
|
+
* as when the directory holds files.
|
|
864
|
+
* @example
|
|
865
|
+
* ```ts
|
|
866
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
867
|
+
*
|
|
868
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
869
|
+
* await git.addWorktreeAsync("/tmp/second-build", await git.readHeadAsync());
|
|
870
|
+
* ```
|
|
871
|
+
*/
|
|
872
|
+
public addWorktreeAsync(directory: string, commit: string): Promise<void>;
|
|
873
|
+
|
|
874
|
+
/**
|
|
875
|
+
* Commits every change to a tracked file, without running the clone's
|
|
876
|
+
* hooks, as the author and committer git's settings or environment name.
|
|
877
|
+
*
|
|
878
|
+
* @param message The commit's message.
|
|
879
|
+
* @returns A promise that resolves once the commit is made. It rejects with
|
|
880
|
+
* {@link ProcessException} if git cannot start or fails, such as when
|
|
881
|
+
* nothing changed.
|
|
882
|
+
* @example
|
|
883
|
+
* ```ts
|
|
884
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
885
|
+
*
|
|
886
|
+
* await new Git(new ProcessRunner(), "/tmp/example").commitAllAsync("Move the pins of tools's packages to 0.0.4");
|
|
887
|
+
* ```
|
|
888
|
+
*/
|
|
889
|
+
public commitAllAsync(message: string): Promise<void>;
|
|
890
|
+
|
|
891
|
+
/**
|
|
892
|
+
* Removes a worktree and its directory, with the files a build wrote in
|
|
893
|
+
* it.
|
|
894
|
+
*
|
|
895
|
+
* @param directory The worktree's directory.
|
|
896
|
+
* @returns A promise that resolves once the worktree is removed. It rejects
|
|
897
|
+
* with {@link ProcessException} if git cannot start or fails, such as when
|
|
898
|
+
* the directory is not a worktree of the clone.
|
|
899
|
+
* @example
|
|
900
|
+
* ```ts
|
|
901
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
902
|
+
*
|
|
903
|
+
* await new Git(new ProcessRunner(), process.cwd()).removeWorktreeAsync("/tmp/second-build");
|
|
904
|
+
* ```
|
|
905
|
+
*/
|
|
906
|
+
public removeWorktreeAsync(directory: string): Promise<void>;
|
|
907
|
+
|
|
711
908
|
/**
|
|
712
909
|
* Tells whether a revision names a commit in the clone.
|
|
713
910
|
*
|
|
@@ -786,6 +983,64 @@ export declare class Git {
|
|
|
786
983
|
*/
|
|
787
984
|
public listFilesAsync(commit: string, folderPath: string): Promise<readonly string[]>;
|
|
788
985
|
|
|
986
|
+
/**
|
|
987
|
+
* Lists what `git status --porcelain` lists: the checkout's changed,
|
|
988
|
+
* staged and untracked paths, outside the ignored ones.
|
|
989
|
+
*
|
|
990
|
+
* @returns A promise of each line git writes, such as ` M README.md` or
|
|
991
|
+
* `?? notes.txt`, with paths from the repository's root as git quotes
|
|
992
|
+
* them; none for a checkout as committed. It rejects with
|
|
993
|
+
* {@link ProcessException} if git cannot start or fails otherwise, such as
|
|
994
|
+
* outside a clone.
|
|
995
|
+
* @example
|
|
996
|
+
* ```ts
|
|
997
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
998
|
+
*
|
|
999
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
1000
|
+
* await git.listChangesAsync(); // [] in a checkout as committed
|
|
1001
|
+
* ```
|
|
1002
|
+
*/
|
|
1003
|
+
public listChangesAsync(): Promise<readonly string[]>;
|
|
1004
|
+
|
|
1005
|
+
/**
|
|
1006
|
+
* Lists the files the index tracks in the working directory and the
|
|
1007
|
+
* folders inside it.
|
|
1008
|
+
*
|
|
1009
|
+
* @returns A promise of each file, in git's order, with its line endings
|
|
1010
|
+
* and whether it is text; none when the index tracks no file there. It
|
|
1011
|
+
* rejects with {@link ProcessException} if git cannot start or fails
|
|
1012
|
+
* otherwise, such as outside a clone.
|
|
1013
|
+
* @example
|
|
1014
|
+
* ```ts
|
|
1015
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1016
|
+
*
|
|
1017
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
1018
|
+
* (await git.listTrackedFilesAsync()).filter(t => t.isText).length; // the number of tracked text files
|
|
1019
|
+
* ```
|
|
1020
|
+
*/
|
|
1021
|
+
public listTrackedFilesAsync(): Promise<readonly TrackedFile[]>;
|
|
1022
|
+
|
|
1023
|
+
/**
|
|
1024
|
+
* Reads the last bytes of a file as the checkout holds it, which can
|
|
1025
|
+
* differ from the committed content when the file was changed after the
|
|
1026
|
+
* checkout.
|
|
1027
|
+
*
|
|
1028
|
+
* @param filePath The file's path from the working directory.
|
|
1029
|
+
* @param byteCount How many bytes to read from the file's end.
|
|
1030
|
+
* @returns A promise of the file's last `byteCount` bytes, or all of them
|
|
1031
|
+
* for a shorter file; `null` when the checkout has no file at the path,
|
|
1032
|
+
* such as after the file was deleted. It rejects with the file system's
|
|
1033
|
+
* error if the file cannot be read otherwise.
|
|
1034
|
+
* @example
|
|
1035
|
+
* ```ts
|
|
1036
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1037
|
+
*
|
|
1038
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
1039
|
+
* (await git.readCheckoutFileEndAsync("README.md", 2))?.toString("utf8"); // ".\n"
|
|
1040
|
+
* ```
|
|
1041
|
+
*/
|
|
1042
|
+
public readCheckoutFileEndAsync(filePath: string, byteCount: number): Promise<Buffer | null>;
|
|
1043
|
+
|
|
789
1044
|
/**
|
|
790
1045
|
* Reads a file as a commit holds it.
|
|
791
1046
|
*
|
|
@@ -820,6 +1075,38 @@ export declare class Git {
|
|
|
820
1075
|
* ```
|
|
821
1076
|
*/
|
|
822
1077
|
public readHeadAsync(): Promise<string>;
|
|
1078
|
+
|
|
1079
|
+
/**
|
|
1080
|
+
* Reads the email address of a commit's committer.
|
|
1081
|
+
*
|
|
1082
|
+
* @param revision The commit, such as its id or `HEAD`.
|
|
1083
|
+
* @returns A promise of the address. It rejects with
|
|
1084
|
+
* {@link ProcessException} if git cannot start or fails, such as for a
|
|
1085
|
+
* revision the clone doesn't hold.
|
|
1086
|
+
* @example
|
|
1087
|
+
* ```ts
|
|
1088
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1089
|
+
*
|
|
1090
|
+
* await new Git(new ProcessRunner(), process.cwd()).readCommitterAsync("HEAD"); // "noreply@github.com"
|
|
1091
|
+
* ```
|
|
1092
|
+
*/
|
|
1093
|
+
public readCommitterAsync(revision: string): Promise<string>;
|
|
1094
|
+
|
|
1095
|
+
/**
|
|
1096
|
+
* Reads a commit's subject, the first line of its message.
|
|
1097
|
+
*
|
|
1098
|
+
* @param revision The commit, such as its id or `HEAD`.
|
|
1099
|
+
* @returns A promise of the subject. It rejects with
|
|
1100
|
+
* {@link ProcessException} if git cannot start or fails, such as for a
|
|
1101
|
+
* revision the clone doesn't hold.
|
|
1102
|
+
* @example
|
|
1103
|
+
* ```ts
|
|
1104
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1105
|
+
*
|
|
1106
|
+
* await new Git(new ProcessRunner(), process.cwd()).readSubjectAsync("HEAD"); // "Move the pins of tools's packages to 0.0.4"
|
|
1107
|
+
* ```
|
|
1108
|
+
*/
|
|
1109
|
+
public readSubjectAsync(revision: string): Promise<string>;
|
|
823
1110
|
}
|
|
824
1111
|
|
|
825
1112
|
/**
|
|
@@ -895,6 +1182,9 @@ export declare class Npm {
|
|
|
895
1182
|
* @param processRunner The runner that starts `npm`.
|
|
896
1183
|
* @param workingDirectory The directory `npm` runs in, whose configuration
|
|
897
1184
|
* it reads.
|
|
1185
|
+
* @param platform The platform npm runs on, as `process.platform` names it;
|
|
1186
|
+
* on `win32`, where npm is a command script, it reads npm's version
|
|
1187
|
+
* through `cmd.exe`. Omitted, it is `process.platform`.
|
|
898
1188
|
* @example
|
|
899
1189
|
* ```ts
|
|
900
1190
|
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
@@ -902,7 +1192,7 @@ export declare class Npm {
|
|
|
902
1192
|
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
903
1193
|
* ```
|
|
904
1194
|
*/
|
|
905
|
-
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
1195
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string);
|
|
906
1196
|
|
|
907
1197
|
/**
|
|
908
1198
|
* Reads a field of a package or a version from the registry, asking the
|
|
@@ -972,6 +1262,61 @@ export declare class Npm {
|
|
|
972
1262
|
*/
|
|
973
1263
|
public publishAsync(archivePath: string, tag: string, access: string, registry: string): Promise<ProcessResult>;
|
|
974
1264
|
|
|
1265
|
+
/**
|
|
1266
|
+
* Runs the build script of the package in a directory, with
|
|
1267
|
+
* `npm run build`, or on Windows `cmd.exe /d /s /c "npm.cmd run build"`, a
|
|
1268
|
+
* fixed command.
|
|
1269
|
+
*
|
|
1270
|
+
* @param directory The directory whose `package.json` names the build
|
|
1271
|
+
* script.
|
|
1272
|
+
* @returns A promise of npm's exit code and of what it wrote; a build that
|
|
1273
|
+
* fails still resolves. It rejects with {@link ProcessException} if the
|
|
1274
|
+
* program cannot start.
|
|
1275
|
+
* @example
|
|
1276
|
+
* ```ts
|
|
1277
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1278
|
+
*
|
|
1279
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).buildAsync("/tmp/second-build")).isSuccessful; // true when the build passes
|
|
1280
|
+
* ```
|
|
1281
|
+
*/
|
|
1282
|
+
public buildAsync(directory: string): Promise<ProcessResult>;
|
|
1283
|
+
|
|
1284
|
+
/**
|
|
1285
|
+
* Refreshes a directory's `package-lock.json` from its `package.json`
|
|
1286
|
+
* files, with `npm install --package-lock-only --ignore-scripts --no-audit
|
|
1287
|
+
* --no-fund`, or on Windows the same through `cmd.exe /d /s /c`, a fixed
|
|
1288
|
+
* command; it installs nothing and runs no script.
|
|
1289
|
+
*
|
|
1290
|
+
* @param directory The directory that holds the `package-lock.json`.
|
|
1291
|
+
* @param hiddenVariables The environment variables npm doesn't get, such
|
|
1292
|
+
* as a credential meant for something else; omitted, it gets them all.
|
|
1293
|
+
* @returns A promise of npm's exit code and of what it wrote; a refresh
|
|
1294
|
+
* that fails still resolves. It rejects with {@link ProcessException} if
|
|
1295
|
+
* the program cannot start.
|
|
1296
|
+
* @example
|
|
1297
|
+
* ```ts
|
|
1298
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1299
|
+
*
|
|
1300
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).lockAsync("/tmp/example")).isSuccessful; // true when the lock file is refreshed
|
|
1301
|
+
* ```
|
|
1302
|
+
*/
|
|
1303
|
+
public lockAsync(directory: string, hiddenVariables?: readonly string[]): Promise<ProcessResult>;
|
|
1304
|
+
|
|
1305
|
+
/**
|
|
1306
|
+
* Reads the version of the npm that runs, with `npm --version`, or on
|
|
1307
|
+
* Windows `cmd.exe /d /s /c "npm.cmd --version"`, a fixed command.
|
|
1308
|
+
*
|
|
1309
|
+
* @returns A promise of the version, such as `11.19.0`. It rejects with
|
|
1310
|
+
* {@link ProcessException} if npm cannot start or fails.
|
|
1311
|
+
* @example
|
|
1312
|
+
* ```ts
|
|
1313
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1314
|
+
*
|
|
1315
|
+
* await new Npm(new ProcessRunner(), process.cwd()).readVersionAsync(); // "11.19.0"
|
|
1316
|
+
* ```
|
|
1317
|
+
*/
|
|
1318
|
+
public readVersionAsync(): Promise<string>;
|
|
1319
|
+
|
|
975
1320
|
/**
|
|
976
1321
|
* Tells whether a text is a registry the steps take: an `https` URL
|
|
977
1322
|
* without credentials, a query or a fragment.
|
|
@@ -1488,3 +1833,317 @@ export declare class TagStep implements IStep {
|
|
|
1488
1833
|
*/
|
|
1489
1834
|
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1490
1835
|
}
|
|
1836
|
+
|
|
1837
|
+
/**
|
|
1838
|
+
* The step that checks the line endings of the files a checkout tracks:
|
|
1839
|
+
* `line-endings`, which takes no values. It succeeds only when
|
|
1840
|
+
* `.gitattributes` at the checkout's root holds the line
|
|
1841
|
+
* `* text=auto eol=lf`, and every tracked text file uses LF line endings and
|
|
1842
|
+
* ends with exactly one newline. It skips the files that are not text, as
|
|
1843
|
+
* {@link TrackedFile.isText} tells.
|
|
1844
|
+
*/
|
|
1845
|
+
export declare class LineEndingsStep implements IStep {
|
|
1846
|
+
/**
|
|
1847
|
+
* The step's name, `"line-endings"`.
|
|
1848
|
+
*/
|
|
1849
|
+
public readonly name: string;
|
|
1850
|
+
|
|
1851
|
+
/**
|
|
1852
|
+
* The values the step takes: none, `""`.
|
|
1853
|
+
*/
|
|
1854
|
+
public readonly usage: string;
|
|
1855
|
+
|
|
1856
|
+
/**
|
|
1857
|
+
* Creates the step over a checkout.
|
|
1858
|
+
*
|
|
1859
|
+
* @param git The reader of the clone, whose working directory is the
|
|
1860
|
+
* checkout's root, or the folder whose files the step checks.
|
|
1861
|
+
* @example
|
|
1862
|
+
* ```ts
|
|
1863
|
+
* import { Git, LineEndingsStep, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1864
|
+
*
|
|
1865
|
+
* const step = new LineEndingsStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1866
|
+
* step.name; // "line-endings"
|
|
1867
|
+
* ```
|
|
1868
|
+
*/
|
|
1869
|
+
public constructor(git: Git);
|
|
1870
|
+
|
|
1871
|
+
/**
|
|
1872
|
+
* Checks the line endings.
|
|
1873
|
+
*
|
|
1874
|
+
* @param values None.
|
|
1875
|
+
* @returns A promise of the result: succeeded, such as
|
|
1876
|
+
* `.gitattributes holds "* text=auto eol=lf", and the 12 tracked text
|
|
1877
|
+
* files use LF line endings and end with exactly one newline.`, or failed
|
|
1878
|
+
* when values are given, when git lists no tracked file, or with one line
|
|
1879
|
+
* for each thing that is wrong, naming the file and the fix: a
|
|
1880
|
+
* `.gitattributes` without the line, a file whose committed content has
|
|
1881
|
+
* CRLF or mixed line endings, a file the checkout does not hold, a file
|
|
1882
|
+
* that does not end with a newline, and a file that ends with a blank
|
|
1883
|
+
* line. The line endings come from the committed content, and the files'
|
|
1884
|
+
* ends from the checkout, so a pipeline runs the step on a checkout as
|
|
1885
|
+
* committed, before anything changes it. It rejects with
|
|
1886
|
+
* {@link ProcessException} if git cannot start or fails otherwise, such as
|
|
1887
|
+
* outside a clone.
|
|
1888
|
+
* @example
|
|
1889
|
+
* ```ts
|
|
1890
|
+
* import { Git, LineEndingsStep, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1891
|
+
*
|
|
1892
|
+
* const step = new LineEndingsStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1893
|
+
* const result = await step.runAsync([]);
|
|
1894
|
+
* result.message; // "\"README.md\" does not end with a newline; add one." when it does not
|
|
1895
|
+
* (await step.runAsync(["src"])).message; // "The line-endings step takes no values."
|
|
1896
|
+
* ```
|
|
1897
|
+
*/
|
|
1898
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1899
|
+
}
|
|
1900
|
+
|
|
1901
|
+
/**
|
|
1902
|
+
* The step that checks that a checkout is as committed: `unchanged`, which
|
|
1903
|
+
* takes no values. Run after a build and its tests, it finds the tracked
|
|
1904
|
+
* files they changed and the files they wrote outside the ignored paths.
|
|
1905
|
+
*/
|
|
1906
|
+
export declare class UnchangedStep implements IStep {
|
|
1907
|
+
/**
|
|
1908
|
+
* The step's name, `"unchanged"`.
|
|
1909
|
+
*/
|
|
1910
|
+
public readonly name: string;
|
|
1911
|
+
|
|
1912
|
+
/**
|
|
1913
|
+
* The values the step takes: none, `""`.
|
|
1914
|
+
*/
|
|
1915
|
+
public readonly usage: string;
|
|
1916
|
+
|
|
1917
|
+
/**
|
|
1918
|
+
* Creates the step over a checkout.
|
|
1919
|
+
*
|
|
1920
|
+
* @param git The reader of the clone.
|
|
1921
|
+
* @example
|
|
1922
|
+
* ```ts
|
|
1923
|
+
* import { Git, ProcessRunner, UnchangedStep } from "@noldova/tools.pipelines";
|
|
1924
|
+
*
|
|
1925
|
+
* const step = new UnchangedStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1926
|
+
* step.name; // "unchanged"
|
|
1927
|
+
* ```
|
|
1928
|
+
*/
|
|
1929
|
+
public constructor(git: Git);
|
|
1930
|
+
|
|
1931
|
+
/**
|
|
1932
|
+
* Checks that the checkout has no changed or untracked file.
|
|
1933
|
+
*
|
|
1934
|
+
* @param values None.
|
|
1935
|
+
* @returns A promise of the result: succeeded,
|
|
1936
|
+
* `The checkout has no changed or untracked file.`, when `git status
|
|
1937
|
+
* --porcelain` lists nothing, or failed when values are given, or with
|
|
1938
|
+
* each path git lists, as it lists them, and how to fix it. It rejects with
|
|
1939
|
+
* {@link ProcessException} if git cannot start or fails otherwise, such as
|
|
1940
|
+
* outside a clone.
|
|
1941
|
+
* @example
|
|
1942
|
+
* ```ts
|
|
1943
|
+
* import { Git, ProcessRunner, UnchangedStep } from "@noldova/tools.pipelines";
|
|
1944
|
+
*
|
|
1945
|
+
* const step = new UnchangedStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1946
|
+
* (await step.runAsync([])).isSuccessful; // true in a checkout as committed
|
|
1947
|
+
* ```
|
|
1948
|
+
*/
|
|
1949
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1950
|
+
}
|
|
1951
|
+
|
|
1952
|
+
/**
|
|
1953
|
+
* The step that checks the toolchain a job runs:
|
|
1954
|
+
* `toolchain <node-version> [<npm-version>]`. It succeeds only when the
|
|
1955
|
+
* Node.js that runs it is that version and, when an npm version is given,
|
|
1956
|
+
* `npm --version` prints it.
|
|
1957
|
+
*/
|
|
1958
|
+
export declare class ToolchainStep implements IStep {
|
|
1959
|
+
/**
|
|
1960
|
+
* The step's name, `"toolchain"`.
|
|
1961
|
+
*/
|
|
1962
|
+
public readonly name: string;
|
|
1963
|
+
|
|
1964
|
+
/**
|
|
1965
|
+
* The values the step takes, `"<node-version> [<npm-version>]"`.
|
|
1966
|
+
*/
|
|
1967
|
+
public readonly usage: string;
|
|
1968
|
+
|
|
1969
|
+
/**
|
|
1970
|
+
* Creates the step.
|
|
1971
|
+
*
|
|
1972
|
+
* @param npm What reads npm's version.
|
|
1973
|
+
* @param nodeVersion The version of the Node.js that runs the step, as
|
|
1974
|
+
* `process.version` gives it, such as `v24.21.0`.
|
|
1975
|
+
* @example
|
|
1976
|
+
* ```ts
|
|
1977
|
+
* import { Npm, ProcessRunner, ToolchainStep } from "@noldova/tools.pipelines";
|
|
1978
|
+
*
|
|
1979
|
+
* const step = new ToolchainStep(new Npm(new ProcessRunner(), process.cwd()), process.version);
|
|
1980
|
+
* step.name; // "toolchain"
|
|
1981
|
+
* ```
|
|
1982
|
+
*/
|
|
1983
|
+
public constructor(npm: Npm, nodeVersion: string);
|
|
1984
|
+
|
|
1985
|
+
/**
|
|
1986
|
+
* Checks the toolchain.
|
|
1987
|
+
*
|
|
1988
|
+
* @param values The Node.js version, such as `24.21.0`, and optionally
|
|
1989
|
+
* the npm version, such as `11.19.0`; each exact, `major.minor.patch`.
|
|
1990
|
+
* An empty npm version is the same as none, so a workflow can pass a
|
|
1991
|
+
* setting that names none.
|
|
1992
|
+
* @returns A promise of the result: succeeded, such as
|
|
1993
|
+
* `Node.js v24.21.0 and npm 11.19.0 run this step.`, or failed for no
|
|
1994
|
+
* values or more than two, for a version that is not exact, or with one
|
|
1995
|
+
* line for each version that differs, naming the version found, the one
|
|
1996
|
+
* expected and the fix. It reads npm's version only when one is given, and
|
|
1997
|
+
* rejects with {@link ProcessException} if npm cannot start or fails.
|
|
1998
|
+
* @example
|
|
1999
|
+
* ```ts
|
|
2000
|
+
* import { Npm, ProcessRunner, ToolchainStep } from "@noldova/tools.pipelines";
|
|
2001
|
+
*
|
|
2002
|
+
* const step = new ToolchainStep(new Npm(new ProcessRunner(), process.cwd()), "v24.20.0");
|
|
2003
|
+
* (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."
|
|
2004
|
+
* ```
|
|
2005
|
+
*/
|
|
2006
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2007
|
+
}
|
|
2008
|
+
|
|
2009
|
+
/**
|
|
2010
|
+
* The step that checks a build is reproducible: `reproducible <folder>`.
|
|
2011
|
+
* Run after the build in a checkout, it builds the checkout's commit again in
|
|
2012
|
+
* a worktree in a new temporary folder, with `npm run build`, and succeeds
|
|
2013
|
+
* only when both builds' `<folder>` hold the same `.tgz` archives, byte for
|
|
2014
|
+
* byte, so that rerunning a release publishes nothing new.
|
|
2015
|
+
*/
|
|
2016
|
+
export declare class ReproducibleStep implements IStep {
|
|
2017
|
+
/**
|
|
2018
|
+
* The step's name, `"reproducible"`.
|
|
2019
|
+
*/
|
|
2020
|
+
public readonly name: string;
|
|
2021
|
+
|
|
2022
|
+
/**
|
|
2023
|
+
* The values the step takes, `"<folder>"`.
|
|
2024
|
+
*/
|
|
2025
|
+
public readonly usage: string;
|
|
2026
|
+
|
|
2027
|
+
/**
|
|
2028
|
+
* Creates the step over a checkout.
|
|
2029
|
+
*
|
|
2030
|
+
* @param git The reader of the clone, whose working directory is the
|
|
2031
|
+
* checkout's root.
|
|
2032
|
+
* @param npm What runs the second build.
|
|
2033
|
+
* @param temporaryRoot The folder the step makes its temporary folder in,
|
|
2034
|
+
* such as one the pipeline host empties after each job, so a run that is
|
|
2035
|
+
* cancelled leaves nothing behind. Omitted or empty, it is `os.tmpdir()`.
|
|
2036
|
+
* @example
|
|
2037
|
+
* ```ts
|
|
2038
|
+
* import { Git, Npm, ProcessRunner, ReproducibleStep } from "@noldova/tools.pipelines";
|
|
2039
|
+
*
|
|
2040
|
+
* const processRunner = new ProcessRunner();
|
|
2041
|
+
* const step = new ReproducibleStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()));
|
|
2042
|
+
* step.name; // "reproducible"
|
|
2043
|
+
* ```
|
|
2044
|
+
*/
|
|
2045
|
+
public constructor(git: Git, npm: Npm, temporaryRoot?: string);
|
|
2046
|
+
|
|
2047
|
+
/**
|
|
2048
|
+
* Builds the commit again and compares the archives.
|
|
2049
|
+
*
|
|
2050
|
+
* @param values The folder the build packs its archives into, as a path
|
|
2051
|
+
* from the checkout's root, such as `_packages`.
|
|
2052
|
+
* @returns A promise of the result: succeeded, listing each archive with
|
|
2053
|
+
* its SHA-512, or failed for any number of values but one, for a folder
|
|
2054
|
+
* that is absolute, outside the checkout or the checkout itself, a missing
|
|
2055
|
+
* folder or one without archives, a second build that
|
|
2056
|
+
* fails, with npm's exit code and error output, or with one line for each
|
|
2057
|
+
* archive that differs or is in only one build. It removes the worktree and
|
|
2058
|
+
* its folder whether it succeeds or fails, and rejects with
|
|
2059
|
+
* {@link ProcessException} if git or npm cannot start, or git fails, such
|
|
2060
|
+
* as outside a clone.
|
|
2061
|
+
* @example
|
|
2062
|
+
* ```ts
|
|
2063
|
+
* import { Git, Npm, ProcessRunner, ReproducibleStep } from "@noldova/tools.pipelines";
|
|
2064
|
+
*
|
|
2065
|
+
* const processRunner = new ProcessRunner();
|
|
2066
|
+
* const step = new ReproducibleStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()));
|
|
2067
|
+
* (await step.runAsync(["_packages"])).isSuccessful; // true when the second build packs the same archives
|
|
2068
|
+
* ```
|
|
2069
|
+
*/
|
|
2070
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2071
|
+
}
|
|
2072
|
+
|
|
2073
|
+
/**
|
|
2074
|
+
* The step that moves the repositories that pin a release's packages:
|
|
2075
|
+
* `dependents <version> <commit>`. Run from a checkout of the released
|
|
2076
|
+
* commit after the release publishes, it reads the packages the commit
|
|
2077
|
+
* releases, as the {@link ArchiveStep} does, and checks out each repository
|
|
2078
|
+
* the {@link IUpdateHost} lists. In a repository whose tracked `package.json`
|
|
2079
|
+
* files pin any of those packages exactly at an older version, it moves each
|
|
2080
|
+
* such pin to the version, refreshes every tracked `package-lock.json` with
|
|
2081
|
+
* {@link Npm.lockAsync}, without the host's credential variables, commits,
|
|
2082
|
+
* pushes the branch `pipelines/update-<source>` and proposes it, with the
|
|
2083
|
+
* moved pins and the release's notes in its description. When the branch
|
|
2084
|
+
* exists, it replaces it only when the branch is at a commit of its own, made
|
|
2085
|
+
* by the same committer with its title, and otherwise fails that repository,
|
|
2086
|
+
* so nobody's commits are lost. A repository that pins none of them is left
|
|
2087
|
+
* as it is.
|
|
2088
|
+
*/
|
|
2089
|
+
export declare class DependentsStep implements IStep {
|
|
2090
|
+
/**
|
|
2091
|
+
* The step's name, `"dependents"`.
|
|
2092
|
+
*/
|
|
2093
|
+
public readonly name: string;
|
|
2094
|
+
|
|
2095
|
+
/**
|
|
2096
|
+
* The values the step takes, `"<version> <commit>"`.
|
|
2097
|
+
*/
|
|
2098
|
+
public readonly usage: string;
|
|
2099
|
+
|
|
2100
|
+
/**
|
|
2101
|
+
* Creates the step.
|
|
2102
|
+
*
|
|
2103
|
+
* @param archiveStep What reads the packages the commit releases, over the
|
|
2104
|
+
* checkout of that commit.
|
|
2105
|
+
* @param updateHost What lists, checks out, pushes to and proposes in the
|
|
2106
|
+
* repositories.
|
|
2107
|
+
* @param processRunner What runs git in each repository's clone.
|
|
2108
|
+
* @param npm What refreshes the lock files.
|
|
2109
|
+
* @param temporaryRoot The folder the step makes its temporary folder in,
|
|
2110
|
+
* such as one the pipeline host empties after each job. Omitted or empty,
|
|
2111
|
+
* it is `os.tmpdir()`.
|
|
2112
|
+
* @example
|
|
2113
|
+
* ```ts
|
|
2114
|
+
* import { ArchiveStep, DependentsStep, Git, type IUpdateHost, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
2115
|
+
*
|
|
2116
|
+
* declare const host: IUpdateHost;
|
|
2117
|
+
* const processRunner = new ProcessRunner();
|
|
2118
|
+
* const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
2119
|
+
* const step = new DependentsStep(archiveStep, host, processRunner, new Npm(processRunner, process.cwd()));
|
|
2120
|
+
* step.name; // "dependents"
|
|
2121
|
+
* ```
|
|
2122
|
+
*/
|
|
2123
|
+
public constructor(archiveStep: ArchiveStep, updateHost: IUpdateHost, processRunner: ProcessRunner, npm: Npm, temporaryRoot?: string);
|
|
2124
|
+
|
|
2125
|
+
/**
|
|
2126
|
+
* Moves the pins in every repository that has them.
|
|
2127
|
+
*
|
|
2128
|
+
* @param values The version, a release version such as `0.0.4`, and the
|
|
2129
|
+
* full id of the commit it was released from.
|
|
2130
|
+
* @returns A promise of the result, with a line for each repository: the
|
|
2131
|
+
* proposal's address and how many pins moved, that it pins none, or why it
|
|
2132
|
+
* failed. It fails for any number of values but two, a version that isn't
|
|
2133
|
+
* one or is a nightly, a commit that isn't a full id, a commit that
|
|
2134
|
+
* releases no package, what the host can't answer, and when any
|
|
2135
|
+
* repository fails, after trying every other; an error in one repository,
|
|
2136
|
+
* such as git failing, is that repository's line. It removes its temporary
|
|
2137
|
+
* folder whether it succeeds or fails, and rejects with
|
|
2138
|
+
* {@link ProcessException} if git cannot start or fails while it reads the
|
|
2139
|
+
* released commit.
|
|
2140
|
+
* @example
|
|
2141
|
+
* ```ts
|
|
2142
|
+
* (await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message;
|
|
2143
|
+
* // Looked for exact pins of @noldova/tools.pipelines, @noldova/tools.pipelines.github older than 0.0.4 in 2 repositories:
|
|
2144
|
+
* // noldova-com/example: moved 2 pins in https://github.com/noldova-com/example/pull/7
|
|
2145
|
+
* // noldova-com/sample: pins none of them below 0.0.4.
|
|
2146
|
+
* ```
|
|
2147
|
+
*/
|
|
2148
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2149
|
+
}
|