@noldova/tools.pipelines 0.0.10 → 0.0.12
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 +66 -1
- package/api/index.d.ts +543 -2
- package/api/index.js +7 -0
- package/api/index.js.map +1 -1
- package/exceptions/build.exception.js +14 -0
- package/exceptions/build.exception.js.map +1 -0
- package/interfaces/i-testing-module.js +9 -0
- package/interfaces/i-testing-module.js.map +1 -0
- package/models/build-config.js +66 -0
- package/models/build-config.js.map +1 -0
- package/models/build-package.js +37 -0
- package/models/build-package.js.map +1 -0
- package/package.json +2 -2
- package/resources.js +164 -0
- package/resources.js.map +1 -1
- package/services/build-step.js +172 -0
- package/services/build-step.js.map +1 -0
- package/services/coverage-entry-point.js +30 -0
- package/services/coverage-entry-point.js.map +1 -0
- package/services/git.js +3 -0
- package/services/git.js.map +1 -1
- package/services/installed-step.js +87 -0
- package/services/installed-step.js.map +1 -0
- package/services/npm.js +16 -1
- package/services/npm.js.map +1 -1
- package/services/process-runner.js +7 -0
- package/services/process-runner.js.map +1 -1
- package/services/test-step.js +89 -0
- package/services/test-step.js.map +1 -0
- package/services/type-script.js +33 -0
- package/services/type-script.js.map +1 -0
package/api/index.d.ts
CHANGED
|
@@ -74,6 +74,32 @@ export declare class ProcessException extends PipelineException {
|
|
|
74
74
|
public constructor(program: string, message?: string, options?: ExceptionOptions);
|
|
75
75
|
}
|
|
76
76
|
|
|
77
|
+
/**
|
|
78
|
+
* The exception that is thrown when a repository's build cannot go on, such
|
|
79
|
+
* as for a `build.json` that is not valid, a file a package needs that is
|
|
80
|
+
* missing, or a compile, script, pack or install that fails; the build,
|
|
81
|
+
* test and installed steps report its message as their failure.
|
|
82
|
+
*/
|
|
83
|
+
export declare class BuildException extends PipelineException {
|
|
84
|
+
/**
|
|
85
|
+
* Creates the exception with the explanation it reports.
|
|
86
|
+
*
|
|
87
|
+
* @param message The complete explanation, kept as given, such as which
|
|
88
|
+
* file is missing or what the compiler wrote.
|
|
89
|
+
* @param options The failure that caused this one, as its `cause`.
|
|
90
|
+
* Omitted, the exception has no cause.
|
|
91
|
+
* @example
|
|
92
|
+
* ```ts
|
|
93
|
+
* import { BuildException, PipelineException } from "@noldova/tools.pipelines";
|
|
94
|
+
*
|
|
95
|
+
* const exception = new BuildException("The checkout has no build.json, which names the packages to build.");
|
|
96
|
+
* exception.name; // "BuildException"
|
|
97
|
+
* exception instanceof PipelineException; // true
|
|
98
|
+
* ```
|
|
99
|
+
*/
|
|
100
|
+
public constructor(message: string, options?: ExceptionOptions);
|
|
101
|
+
}
|
|
102
|
+
|
|
77
103
|
/**
|
|
78
104
|
* The exception that is thrown when a text is not a version, when a
|
|
79
105
|
* version's part is not a whole number from 0 to `Number.MAX_SAFE_INTEGER`,
|
|
@@ -453,6 +479,177 @@ export declare class ArchiveCheck {
|
|
|
453
479
|
public constructor(result: StepResult, archives: readonly PackageArchive[]);
|
|
454
480
|
}
|
|
455
481
|
|
|
482
|
+
/**
|
|
483
|
+
* One package a repository builds, as its `build.json` names it: its folder
|
|
484
|
+
* under `src/`, and the scripts that run before, instead of and after the
|
|
485
|
+
* TypeScript compile.
|
|
486
|
+
*/
|
|
487
|
+
export declare class BuildPackage {
|
|
488
|
+
/**
|
|
489
|
+
* The package's folder name, such as `noldova.tools.pipelines`.
|
|
490
|
+
*/
|
|
491
|
+
public readonly name: string;
|
|
492
|
+
|
|
493
|
+
/**
|
|
494
|
+
* The package's folder under `src/`, such as
|
|
495
|
+
* `parsers/noldova.example.parsers`; its last segment is the name.
|
|
496
|
+
*/
|
|
497
|
+
public readonly path: string;
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* The package's npm name, the scope, `/` and the folder name after
|
|
501
|
+
* `noldova.`, such as `@noldova/tools.pipelines`.
|
|
502
|
+
*/
|
|
503
|
+
public readonly packageName: string;
|
|
504
|
+
|
|
505
|
+
/**
|
|
506
|
+
* The script that runs before the compile, a path in the checkout, or
|
|
507
|
+
* `null`.
|
|
508
|
+
*/
|
|
509
|
+
public readonly pre: string | null;
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* The script that runs instead of the TypeScript compile, a path in the
|
|
513
|
+
* checkout, or `null` for the compile of `src/<path>/src/tsconfig.json`.
|
|
514
|
+
*/
|
|
515
|
+
public readonly compile: string | null;
|
|
516
|
+
|
|
517
|
+
/**
|
|
518
|
+
* The script that runs after the compile, a path in the checkout, or
|
|
519
|
+
* `null`.
|
|
520
|
+
*/
|
|
521
|
+
public readonly post: string | null;
|
|
522
|
+
|
|
523
|
+
/**
|
|
524
|
+
* Creates the package.
|
|
525
|
+
*
|
|
526
|
+
* @param name The folder name, such as `noldova.tools.pipelines`.
|
|
527
|
+
* @param path The folder under `src/`. Omitted, it is the name.
|
|
528
|
+
* @param pre The script before the compile. Omitted, there is none.
|
|
529
|
+
* @param compile The script instead of the compile. Omitted, the package
|
|
530
|
+
* compiles with TypeScript.
|
|
531
|
+
* @param post The script after the compile. Omitted, there is none.
|
|
532
|
+
* @param scope The npm scope the package publishes under. Omitted, it is
|
|
533
|
+
* `@noldova`.
|
|
534
|
+
* @example
|
|
535
|
+
* ```ts
|
|
536
|
+
* import { BuildPackage } from "@noldova/tools.pipelines";
|
|
537
|
+
*
|
|
538
|
+
* const buildPackage = new BuildPackage("noldova.tools.pipelines");
|
|
539
|
+
* buildPackage.packageName; // "@noldova/tools.pipelines"
|
|
540
|
+
* buildPackage.buildFolder; // "_build/packages/noldova.tools.pipelines"
|
|
541
|
+
* ```
|
|
542
|
+
*/
|
|
543
|
+
public constructor(name: string, path?: string, pre?: string | null, compile?: string | null, post?: string | null, scope?: string);
|
|
544
|
+
|
|
545
|
+
/**
|
|
546
|
+
* The package's source folder in the checkout, `src/<path>`.
|
|
547
|
+
*/
|
|
548
|
+
public get sourceFolder(): string;
|
|
549
|
+
|
|
550
|
+
/**
|
|
551
|
+
* The folder the package is built into, `_build/packages/<name>`.
|
|
552
|
+
*/
|
|
553
|
+
public get buildFolder(): string;
|
|
554
|
+
|
|
555
|
+
/**
|
|
556
|
+
* The folder the package's tests compile into, `_build/tests/<name>`.
|
|
557
|
+
*/
|
|
558
|
+
public get testsFolder(): string;
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* Names the archive `npm pack` makes of a version of the package.
|
|
562
|
+
*
|
|
563
|
+
* @param version The version, such as `0.0.5`.
|
|
564
|
+
* @returns The file name, such as `noldova-tools.pipelines-0.0.5.tgz`.
|
|
565
|
+
* @example
|
|
566
|
+
* ```ts
|
|
567
|
+
* import { BuildPackage } from "@noldova/tools.pipelines";
|
|
568
|
+
*
|
|
569
|
+
* new BuildPackage("noldova.tools.pipelines").archiveName("0.0.5"); // "noldova-tools.pipelines-0.0.5.tgz"
|
|
570
|
+
* ```
|
|
571
|
+
*/
|
|
572
|
+
public archiveName(version: string): string;
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* The packages a repository builds, in the order it builds them, as its
|
|
577
|
+
* `build.json` names them:
|
|
578
|
+
* `{ "scope": "<npm scope>", "packages": [{ "name": "<folder>", "path": "<folder under src/>", "pre": "<script>", "compile": "<script>", "post": "<script>" }] }`,
|
|
579
|
+
* where only the packages and their names are required, and the scope,
|
|
580
|
+
* such as `@noldova`, the default, names every package. A package's folder name is `noldova.` and
|
|
581
|
+
* lowercase segments joined by dots, its path is a relative folder whose
|
|
582
|
+
* last segment is the name, and each script is a relative path inside the
|
|
583
|
+
* checkout that Node.js runs with the package's source folder and build
|
|
584
|
+
* folder as its values.
|
|
585
|
+
*/
|
|
586
|
+
export declare class BuildConfig {
|
|
587
|
+
/**
|
|
588
|
+
* The npm scope the packages publish under, such as `@noldova`.
|
|
589
|
+
*/
|
|
590
|
+
public readonly scope: string;
|
|
591
|
+
|
|
592
|
+
/**
|
|
593
|
+
* The packages, in the order `build.json` names them.
|
|
594
|
+
*/
|
|
595
|
+
public readonly packages: readonly BuildPackage[];
|
|
596
|
+
|
|
597
|
+
/**
|
|
598
|
+
* Creates the configuration.
|
|
599
|
+
*
|
|
600
|
+
* @param scope The npm scope the packages publish under.
|
|
601
|
+
* @param packages The packages, in build order.
|
|
602
|
+
* @example
|
|
603
|
+
* ```ts
|
|
604
|
+
* import { BuildConfig, BuildPackage } from "@noldova/tools.pipelines";
|
|
605
|
+
*
|
|
606
|
+
* const config = new BuildConfig("@noldova", [new BuildPackage("noldova.tools.pipelines")]);
|
|
607
|
+
* ```
|
|
608
|
+
*/
|
|
609
|
+
public constructor(scope: string, packages: readonly BuildPackage[]);
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* The packages' npm names, such as `@noldova/tools.pipelines`.
|
|
613
|
+
*/
|
|
614
|
+
public get packageNames(): readonly string[];
|
|
615
|
+
|
|
616
|
+
/**
|
|
617
|
+
* Reads a checkout's `build.json`.
|
|
618
|
+
*
|
|
619
|
+
* @param directory The checkout's root.
|
|
620
|
+
* @returns The configuration.
|
|
621
|
+
* @throws {@link BuildException} when the file is missing or names a scope
|
|
622
|
+
* that is not an npm scope, no package, a package twice, a name that is not a package folder name, or a
|
|
623
|
+
* path or a script outside the checkout; `JsonException` from
|
|
624
|
+
* `@noldova/context.json` when it is not JSON or lacks a field.
|
|
625
|
+
* @example
|
|
626
|
+
* ```ts
|
|
627
|
+
* import { BuildConfig } from "@noldova/tools.pipelines";
|
|
628
|
+
*
|
|
629
|
+
* BuildConfig.read(process.cwd()).packageNames; // ["@noldova/tools.pipelines", "@noldova/tools.pipelines.github"]
|
|
630
|
+
* ```
|
|
631
|
+
*/
|
|
632
|
+
public static read(directory: string): BuildConfig;
|
|
633
|
+
|
|
634
|
+
/**
|
|
635
|
+
* Reads the text of a `build.json`.
|
|
636
|
+
*
|
|
637
|
+
* @param text The file's text.
|
|
638
|
+
* @returns The configuration.
|
|
639
|
+
* @throws {@link BuildException} when the text names a scope that is not
|
|
640
|
+
* an npm scope, no package, a package twice, a name that is not a package folder name, or a path or a
|
|
641
|
+
* script outside the checkout; `JsonException` from
|
|
642
|
+
* `@noldova/context.json` when it is not JSON or lacks a field.
|
|
643
|
+
* @example
|
|
644
|
+
* ```ts
|
|
645
|
+
* import { BuildConfig } from "@noldova/tools.pipelines";
|
|
646
|
+
*
|
|
647
|
+
* BuildConfig.parse("{\"packages\":[{\"name\":\"noldova.example\"}]}").packages[0]?.packageName; // "@noldova/example"
|
|
648
|
+
* ```
|
|
649
|
+
*/
|
|
650
|
+
public static parse(text: string): BuildConfig;
|
|
651
|
+
}
|
|
652
|
+
|
|
456
653
|
/**
|
|
457
654
|
* A step of a pipeline that a {@link CommandLine} runs by its name, such as
|
|
458
655
|
* {@link SourceStep}.
|
|
@@ -498,6 +695,25 @@ export declare interface IStep {
|
|
|
498
695
|
* implements it, such as by writing a failure as the host's error annotation.
|
|
499
696
|
*/
|
|
500
697
|
export declare interface IStepOutput {
|
|
698
|
+
/**
|
|
699
|
+
* Writes a line of a step's progress while it runs, such as the package it
|
|
700
|
+
* builds or a line of a coverage report.
|
|
701
|
+
*
|
|
702
|
+
* @param message The line.
|
|
703
|
+
* @example
|
|
704
|
+
* ```ts
|
|
705
|
+
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
706
|
+
*
|
|
707
|
+
* const output: IStepOutput = {
|
|
708
|
+
* writeProgress: message => console.log(message),
|
|
709
|
+
* writeSuccess: message => console.log(message),
|
|
710
|
+
* writeFailure: message => console.error(message)
|
|
711
|
+
* };
|
|
712
|
+
* output.writeProgress("Building @noldova/tools.pipelines...");
|
|
713
|
+
* ```
|
|
714
|
+
*/
|
|
715
|
+
writeProgress(message: string): void;
|
|
716
|
+
|
|
501
717
|
/**
|
|
502
718
|
* Writes the message of a step that succeeded.
|
|
503
719
|
*
|
|
@@ -507,6 +723,7 @@ export declare interface IStepOutput {
|
|
|
507
723
|
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
508
724
|
*
|
|
509
725
|
* const output: IStepOutput = {
|
|
726
|
+
* writeProgress: message => console.log(message),
|
|
510
727
|
* writeSuccess: message => console.log(message),
|
|
511
728
|
* writeFailure: message => console.error(message)
|
|
512
729
|
* };
|
|
@@ -517,7 +734,8 @@ export declare interface IStepOutput {
|
|
|
517
734
|
|
|
518
735
|
/**
|
|
519
736
|
* Writes the message of a step that failed, or the usage line when the
|
|
520
|
-
* command line names no step it has.
|
|
737
|
+
* command line names no step it has. An empty message, from a step that
|
|
738
|
+
* wrote why it failed as progress, writes nothing.
|
|
521
739
|
*
|
|
522
740
|
* @param message What is wrong.
|
|
523
741
|
* @example
|
|
@@ -525,6 +743,7 @@ export declare interface IStepOutput {
|
|
|
525
743
|
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
526
744
|
*
|
|
527
745
|
* const output: IStepOutput = {
|
|
746
|
+
* writeProgress: message => console.log(message),
|
|
528
747
|
* writeSuccess: message => console.log(message),
|
|
529
748
|
* writeFailure: message => console.error(message)
|
|
530
749
|
* };
|
|
@@ -791,6 +1010,7 @@ export declare class CommandLine {
|
|
|
791
1010
|
*
|
|
792
1011
|
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
793
1012
|
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
1013
|
+
* writeProgress: message => console.log(message),
|
|
794
1014
|
* writeSuccess: message => console.log(message),
|
|
795
1015
|
* writeFailure: message => console.error(message)
|
|
796
1016
|
* });
|
|
@@ -816,6 +1036,7 @@ export declare class CommandLine {
|
|
|
816
1036
|
*
|
|
817
1037
|
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
818
1038
|
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
1039
|
+
* writeProgress: message => console.log(message),
|
|
819
1040
|
* writeSuccess: message => console.log(message),
|
|
820
1041
|
* writeFailure: message => console.error(message)
|
|
821
1042
|
* });
|
|
@@ -860,6 +1081,28 @@ export declare class ProcessRunner {
|
|
|
860
1081
|
* ```
|
|
861
1082
|
*/
|
|
862
1083
|
public runAsync(program: string, values: readonly string[], workingDirectory: string, environment?: Readonly<Record<string, string | undefined>>, timeoutMilliseconds?: number): Promise<ProcessResult>;
|
|
1084
|
+
|
|
1085
|
+
/**
|
|
1086
|
+
* Runs a program to its end with this process's input and output, so what
|
|
1087
|
+
* it writes shows as it runs, such as a test run's progress.
|
|
1088
|
+
*
|
|
1089
|
+
* @param program The program, found on the `PATH` or a path to it.
|
|
1090
|
+
* @param values The values passed to the program, each as one argument,
|
|
1091
|
+
* never read by a shell.
|
|
1092
|
+
* @param workingDirectory The directory the program runs in.
|
|
1093
|
+
* @param environment Variables the program gets on top of this process's
|
|
1094
|
+
* own.
|
|
1095
|
+
* @returns A promise of the program's exit code, or `null` when a signal
|
|
1096
|
+
* ended it. It rejects with {@link ProcessException} only when the program
|
|
1097
|
+
* cannot start.
|
|
1098
|
+
* @example
|
|
1099
|
+
* ```ts
|
|
1100
|
+
* import { ProcessRunner } from "@noldova/tools.pipelines";
|
|
1101
|
+
*
|
|
1102
|
+
* await new ProcessRunner().runVisibleAsync("git", ["--version"], process.cwd(), {}); // 0, after git printed its version
|
|
1103
|
+
* ```
|
|
1104
|
+
*/
|
|
1105
|
+
public runVisibleAsync(program: string, values: readonly string[], workingDirectory: string, environment: Readonly<Record<string, string>>): Promise<number | null>;
|
|
863
1106
|
}
|
|
864
1107
|
|
|
865
1108
|
/**
|
|
@@ -1110,6 +1353,22 @@ export declare class Git {
|
|
|
1110
1353
|
*/
|
|
1111
1354
|
public readHeadAsync(): Promise<string>;
|
|
1112
1355
|
|
|
1356
|
+
/**
|
|
1357
|
+
* Reads where the working directory is inside the clone.
|
|
1358
|
+
*
|
|
1359
|
+
* @returns A promise of the path from the clone's root, ending with `/`,
|
|
1360
|
+
* such as `src/`, or empty at the root. It rejects with
|
|
1361
|
+
* {@link ProcessException} if git cannot start or fails, such as outside a
|
|
1362
|
+
* clone.
|
|
1363
|
+
* @example
|
|
1364
|
+
* ```ts
|
|
1365
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1366
|
+
*
|
|
1367
|
+
* await new Git(new ProcessRunner(), process.cwd()).readPrefixAsync(); // "" at the clone's root
|
|
1368
|
+
* ```
|
|
1369
|
+
*/
|
|
1370
|
+
public readPrefixAsync(): Promise<string>;
|
|
1371
|
+
|
|
1113
1372
|
/**
|
|
1114
1373
|
* Reads the email address of a commit's committer.
|
|
1115
1374
|
*
|
|
@@ -1240,6 +1499,9 @@ export declare class Npm {
|
|
|
1240
1499
|
* @param platform The platform npm runs on, as `process.platform` names it;
|
|
1241
1500
|
* on `win32`, where npm is a command script, it reads npm's version
|
|
1242
1501
|
* through `cmd.exe`. Omitted, it is `process.platform`.
|
|
1502
|
+
* @param environment The variables that name npm's command line, as an npm
|
|
1503
|
+
* script sets `npm_execpath`, which packing and installing the built
|
|
1504
|
+
* packages run with Node.js. Omitted, it is `process.env`.
|
|
1243
1505
|
* @example
|
|
1244
1506
|
* ```ts
|
|
1245
1507
|
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
@@ -1247,7 +1509,7 @@ export declare class Npm {
|
|
|
1247
1509
|
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
1248
1510
|
* ```
|
|
1249
1511
|
*/
|
|
1250
|
-
public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string);
|
|
1512
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string, environment?: Readonly<Record<string, string | undefined>>);
|
|
1251
1513
|
|
|
1252
1514
|
/**
|
|
1253
1515
|
* The directory `npm` runs in, as the constructor got it.
|
|
@@ -1400,6 +1662,44 @@ export declare class Npm {
|
|
|
1400
1662
|
*/
|
|
1401
1663
|
public readVersionAsync(): Promise<string>;
|
|
1402
1664
|
|
|
1665
|
+
/**
|
|
1666
|
+
* Packs a built package with `npm pack --silent --pack-destination`, run
|
|
1667
|
+
* by Node.js from `npm_execpath`.
|
|
1668
|
+
*
|
|
1669
|
+
* @param directory The built package's folder.
|
|
1670
|
+
* @param destination The folder the archive is written to.
|
|
1671
|
+
* @returns A promise of how `npm pack` ended. It throws
|
|
1672
|
+
* {@link BuildException} when `npm_execpath` is not set, as outside an npm
|
|
1673
|
+
* script, and rejects with {@link ProcessException} if Node.js cannot
|
|
1674
|
+
* start.
|
|
1675
|
+
* @example
|
|
1676
|
+
* ```ts
|
|
1677
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1678
|
+
*
|
|
1679
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).packAsync("_build/packages/noldova.example", "_packages")).isSuccessful; // true
|
|
1680
|
+
* ```
|
|
1681
|
+
*/
|
|
1682
|
+
public packAsync(directory: string, destination: string): Promise<ProcessResult>;
|
|
1683
|
+
|
|
1684
|
+
/**
|
|
1685
|
+
* Installs built archives in the working directory without saving them,
|
|
1686
|
+
* with `npm install --no-save --ignore-scripts`, run by Node.js from
|
|
1687
|
+
* `npm_execpath`.
|
|
1688
|
+
*
|
|
1689
|
+
* @param archivePaths The archives, such as
|
|
1690
|
+
* `./_packages/noldova-example-0.0.5.tgz`.
|
|
1691
|
+
* @returns A promise of how `npm install` ended. It throws
|
|
1692
|
+
* {@link BuildException} when `npm_execpath` is not set, and rejects with
|
|
1693
|
+
* {@link ProcessException} if Node.js cannot start.
|
|
1694
|
+
* @example
|
|
1695
|
+
* ```ts
|
|
1696
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1697
|
+
*
|
|
1698
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).installArchivesAsync(["./_packages/noldova-example-0.0.5.tgz"])).isSuccessful; // true
|
|
1699
|
+
* ```
|
|
1700
|
+
*/
|
|
1701
|
+
public installArchivesAsync(archivePaths: readonly string[]): Promise<ProcessResult>;
|
|
1702
|
+
|
|
1403
1703
|
/**
|
|
1404
1704
|
* Tells whether a text is a registry the steps take: an `https` URL
|
|
1405
1705
|
* without credentials, a query or a fragment.
|
|
@@ -1417,6 +1717,49 @@ export declare class Npm {
|
|
|
1417
1717
|
public static isRegistry(text: string): boolean;
|
|
1418
1718
|
}
|
|
1419
1719
|
|
|
1720
|
+
/**
|
|
1721
|
+
* Runs the TypeScript compiler a repository installs, so a build compiles
|
|
1722
|
+
* with the version the repository pins.
|
|
1723
|
+
*/
|
|
1724
|
+
export declare class TypeScript {
|
|
1725
|
+
/**
|
|
1726
|
+
* The repository's root, as the constructor got it.
|
|
1727
|
+
*/
|
|
1728
|
+
public readonly workingDirectory: string;
|
|
1729
|
+
|
|
1730
|
+
/**
|
|
1731
|
+
* Creates the runner.
|
|
1732
|
+
*
|
|
1733
|
+
* @param processRunner What runs the compiler.
|
|
1734
|
+
* @param workingDirectory The repository's root, where `typescript` is
|
|
1735
|
+
* installed.
|
|
1736
|
+
* @example
|
|
1737
|
+
* ```ts
|
|
1738
|
+
* import { ProcessRunner, TypeScript } from "@noldova/tools.pipelines";
|
|
1739
|
+
*
|
|
1740
|
+
* const typeScript = new TypeScript(new ProcessRunner(), process.cwd());
|
|
1741
|
+
* ```
|
|
1742
|
+
*/
|
|
1743
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
1744
|
+
|
|
1745
|
+
/**
|
|
1746
|
+
* Compiles a TypeScript project with `tsc --pretty --project`.
|
|
1747
|
+
*
|
|
1748
|
+
* @param projectPath The project's `tsconfig.json`, from the repository's
|
|
1749
|
+
* root.
|
|
1750
|
+
* @returns A promise of how the compiler ended, with what it wrote. It
|
|
1751
|
+
* throws {@link BuildException} when `typescript` is not installed, and
|
|
1752
|
+
* rejects with {@link ProcessException} if Node.js cannot start.
|
|
1753
|
+
* @example
|
|
1754
|
+
* ```ts
|
|
1755
|
+
* import { ProcessRunner, TypeScript } from "@noldova/tools.pipelines";
|
|
1756
|
+
*
|
|
1757
|
+
* (await new TypeScript(new ProcessRunner(), process.cwd()).compileAsync("src/noldova.example/src/tsconfig.json")).isSuccessful; // true
|
|
1758
|
+
* ```
|
|
1759
|
+
*/
|
|
1760
|
+
public compileAsync(projectPath: string): Promise<ProcessResult>;
|
|
1761
|
+
}
|
|
1762
|
+
|
|
1420
1763
|
/**
|
|
1421
1764
|
* The step that checks a release's source before anything is built or
|
|
1422
1765
|
* published: `source <version> <commit>`. It succeeds only when the version
|
|
@@ -2385,3 +2728,201 @@ export declare class PinsStep implements IStep {
|
|
|
2385
2728
|
*/
|
|
2386
2729
|
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2387
2730
|
}
|
|
2731
|
+
|
|
2732
|
+
/**
|
|
2733
|
+
* The step that checks a folder's installed packages: `installed`. It
|
|
2734
|
+
* succeeds, writing nothing, only when the folder's `node_modules` holds what
|
|
2735
|
+
* its `package-lock.json` locks: every locked package but an optional one for
|
|
2736
|
+
* another platform, at its version, address and integrity, and no other.
|
|
2737
|
+
* The packages a `build.json` in the folder names are left out, since the
|
|
2738
|
+
* build installs them itself. A difference is no error but the answer the
|
|
2739
|
+
* check exists for, so the step writes it as progress and fails with an empty
|
|
2740
|
+
* message, and a host writes no error for it. A repository's npm script runs
|
|
2741
|
+
* `(pipelines installed || npm ci --ignore-scripts) && pipelines build`, so
|
|
2742
|
+
* it installs only when something changed.
|
|
2743
|
+
*/
|
|
2744
|
+
export declare class InstalledStep implements IStep {
|
|
2745
|
+
/**
|
|
2746
|
+
* The step's name, `"installed"`.
|
|
2747
|
+
*/
|
|
2748
|
+
public readonly name: string;
|
|
2749
|
+
|
|
2750
|
+
/**
|
|
2751
|
+
* The values the step takes: `"[<folder>]"`.
|
|
2752
|
+
*/
|
|
2753
|
+
public readonly usage: string;
|
|
2754
|
+
|
|
2755
|
+
/**
|
|
2756
|
+
* Creates the step.
|
|
2757
|
+
*
|
|
2758
|
+
* @param workingDirectory The folder that a folder value is relative to,
|
|
2759
|
+
* and the one the step checks without one: the checkout's root.
|
|
2760
|
+
* @param output Where the step writes why the packages differ.
|
|
2761
|
+
* @example
|
|
2762
|
+
* ```ts
|
|
2763
|
+
* import { InstalledStep } from "@noldova/tools.pipelines";
|
|
2764
|
+
* import { GitHubStepOutput } from "@noldova/tools.pipelines.github";
|
|
2765
|
+
*
|
|
2766
|
+
* const step = new InstalledStep(process.cwd(), new GitHubStepOutput(process.stdout, process.stderr));
|
|
2767
|
+
* step.name; // "installed"
|
|
2768
|
+
* ```
|
|
2769
|
+
*/
|
|
2770
|
+
public constructor(workingDirectory: string, output: IStepOutput);
|
|
2771
|
+
|
|
2772
|
+
/**
|
|
2773
|
+
* Checks the installed packages.
|
|
2774
|
+
*
|
|
2775
|
+
* @param values Nothing, to check the working directory, or the path of
|
|
2776
|
+
* another folder with its own lock, from the working directory.
|
|
2777
|
+
* @returns A promise of the result: succeeded with an empty message;
|
|
2778
|
+
* failed with an empty message after writing, as progress, that the
|
|
2779
|
+
* folder's `node_modules` has no record of what npm installed, or the first
|
|
2780
|
+
* packages that differ, with the command that installs them; or failed with
|
|
2781
|
+
* a message for more than one value, an empty folder, an option, a folder
|
|
2782
|
+
* without `package-lock.json`, or a `build.json` that is not valid. It rejects with
|
|
2783
|
+
* `JsonException` from `@noldova/context.json` for a lock file that is not
|
|
2784
|
+
* valid JSON.
|
|
2785
|
+
* @example
|
|
2786
|
+
* ```ts
|
|
2787
|
+
* import { InstalledStep } from "@noldova/tools.pipelines";
|
|
2788
|
+
* import { GitHubStepOutput } from "@noldova/tools.pipelines.github";
|
|
2789
|
+
*
|
|
2790
|
+
* await new InstalledStep(process.cwd(), new GitHubStepOutput(process.stdout, process.stderr)).runAsync([".pipelines"]);
|
|
2791
|
+
* // writes "The installed packages differ from .pipelines/package-lock.json at node_modules/typescript; run npm ci --ignore-scripts --prefix .pipelines.
|
|
2792
|
+
"
|
|
2793
|
+
* ```
|
|
2794
|
+
*/
|
|
2795
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2796
|
+
}
|
|
2797
|
+
|
|
2798
|
+
/**
|
|
2799
|
+
* The step that builds a checkout's packages:
|
|
2800
|
+
* `build [--version <version>] [<package>...]`, or `build --list-copies`. For each
|
|
2801
|
+
* package `build.json` names, in order, it writes the package's
|
|
2802
|
+
* `package.json` with the version for `__VERSION__` and the head commit as
|
|
2803
|
+
* `gitHead`, copies the `LICENSE`, the `README.md`, the
|
|
2804
|
+
* `src/api/index.d.ts` and the `THIRD-PARTY-NOTICES.txt` it has, runs its
|
|
2805
|
+
* `pre` script, compiles it or runs its `compile` script, runs its `post`
|
|
2806
|
+
* script, packs it into `_packages/` and installs every built archive, so
|
|
2807
|
+
* the next package builds against it. With `--list-copies`, it lists the
|
|
2808
|
+
* files it copies as the archive step reads them.
|
|
2809
|
+
*/
|
|
2810
|
+
export declare class BuildStep implements IStep {
|
|
2811
|
+
/**
|
|
2812
|
+
* The step's name, `"build"`.
|
|
2813
|
+
*/
|
|
2814
|
+
public readonly name: string;
|
|
2815
|
+
|
|
2816
|
+
/**
|
|
2817
|
+
* The values the step takes,
|
|
2818
|
+
* `"[--version <version>] [<package>...], or --list-copies"`.
|
|
2819
|
+
*/
|
|
2820
|
+
public readonly usage: string;
|
|
2821
|
+
|
|
2822
|
+
/**
|
|
2823
|
+
* Creates the step.
|
|
2824
|
+
*
|
|
2825
|
+
* @param git What reads the head commit, in the checkout's root.
|
|
2826
|
+
* @param npm What packs and installs the built packages.
|
|
2827
|
+
* @param typeScript What compiles a package.
|
|
2828
|
+
* @param processRunner What runs a package's scripts.
|
|
2829
|
+
* @param output Where the step writes the package it builds.
|
|
2830
|
+
* @example
|
|
2831
|
+
* ```ts
|
|
2832
|
+
* import { BuildStep, Git, Npm, ProcessRunner, TypeScript, type IStepOutput } from "@noldova/tools.pipelines";
|
|
2833
|
+
*
|
|
2834
|
+
* declare const output: IStepOutput;
|
|
2835
|
+
* const processRunner = new ProcessRunner();
|
|
2836
|
+
* const step = new BuildStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()), new TypeScript(processRunner, process.cwd()), processRunner, output);
|
|
2837
|
+
* step.name; // "build"
|
|
2838
|
+
* ```
|
|
2839
|
+
*/
|
|
2840
|
+
public constructor(git: Git, npm: Npm, typeScript: TypeScript, processRunner: ProcessRunner, output: IStepOutput);
|
|
2841
|
+
|
|
2842
|
+
/**
|
|
2843
|
+
* Builds the packages, or lists the files the build copies.
|
|
2844
|
+
*
|
|
2845
|
+
* @param values `--version` and a version to build instead of
|
|
2846
|
+
* `version.json`'s, such as a nightly `0.0.5-nightly.20261102`, and the
|
|
2847
|
+
* folder names of the packages to build, all of them when none is named;
|
|
2848
|
+
* or `--list-copies` alone.
|
|
2849
|
+
* @returns A promise of the result: succeeded, such as
|
|
2850
|
+
* `Built 2 packages at version 0.0.5.`, or, with `--list-copies`, a line
|
|
2851
|
+
* `<source>\t<package>\t<file>` for each copy and `end of copies`; or
|
|
2852
|
+
* failed for an unknown option, a version that is not one, a package
|
|
2853
|
+
* named twice or that `build.json` doesn't name, a directory that is not
|
|
2854
|
+
* the checkout's root, or the first package that fails, with what the
|
|
2855
|
+
* compiler, script or npm wrote. It rejects with
|
|
2856
|
+
* {@link ProcessException} if a program cannot start, and with
|
|
2857
|
+
* `JsonException` from `@noldova/context.json` for a `build.json`,
|
|
2858
|
+
* `version.json` or package's `package.json` that is not valid JSON.
|
|
2859
|
+
* @example
|
|
2860
|
+
* ```ts
|
|
2861
|
+
* (await step.runAsync(["--version", "0.0.5-nightly.20261102"])).message; // "Built 2 packages at version 0.0.5-nightly.20261102."
|
|
2862
|
+
* ```
|
|
2863
|
+
*/
|
|
2864
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2865
|
+
}
|
|
2866
|
+
|
|
2867
|
+
/**
|
|
2868
|
+
* The step that tests a checkout's packages:
|
|
2869
|
+
* `test [--skip-test-details] [--skip-coverage-details] [<filter>...]`. It
|
|
2870
|
+
* compiles each package's `tests/tsconfig.json` into `_build/tests/<name>`,
|
|
2871
|
+
* runs them through the checkout's `@noldova/context.testing` with V8
|
|
2872
|
+
* coverage, and requires complete coverage of the packages' source; a run
|
|
2873
|
+
* with filters skips the coverage gate. The tests and the coverage report
|
|
2874
|
+
* each run in a Node.js process of their own, so the checkout's packages
|
|
2875
|
+
* never load beside the step's. Run the build first: the tests use the
|
|
2876
|
+
* installed packages.
|
|
2877
|
+
*/
|
|
2878
|
+
export declare class TestStep implements IStep {
|
|
2879
|
+
/**
|
|
2880
|
+
* The step's name, `"test"`.
|
|
2881
|
+
*/
|
|
2882
|
+
public readonly name: string;
|
|
2883
|
+
|
|
2884
|
+
/**
|
|
2885
|
+
* The values the step takes,
|
|
2886
|
+
* `"[--skip-test-details] [--skip-coverage-details] [<filter>...]"`.
|
|
2887
|
+
*/
|
|
2888
|
+
public readonly usage: string;
|
|
2889
|
+
|
|
2890
|
+
/**
|
|
2891
|
+
* Creates the step.
|
|
2892
|
+
*
|
|
2893
|
+
* @param typeScript What compiles the tests, in the checkout's root.
|
|
2894
|
+
* @param processRunner What runs the tests.
|
|
2895
|
+
* @param output Where the step writes its progress.
|
|
2896
|
+
* @example
|
|
2897
|
+
* ```ts
|
|
2898
|
+
* import { ProcessRunner, TestStep, TypeScript, type IStepOutput } from "@noldova/tools.pipelines";
|
|
2899
|
+
*
|
|
2900
|
+
* declare const output: IStepOutput;
|
|
2901
|
+
* const processRunner = new ProcessRunner();
|
|
2902
|
+
* const step = new TestStep(new TypeScript(processRunner, process.cwd()), processRunner, output);
|
|
2903
|
+
* step.name; // "test"
|
|
2904
|
+
* ```
|
|
2905
|
+
*/
|
|
2906
|
+
public constructor(typeScript: TypeScript, processRunner: ProcessRunner, output: IStepOutput);
|
|
2907
|
+
|
|
2908
|
+
/**
|
|
2909
|
+
* Tests the packages.
|
|
2910
|
+
*
|
|
2911
|
+
* @param values The options, `--skip-test-details` to hide the passing
|
|
2912
|
+
* tests' lines and `--skip-coverage-details` to hide the fully covered
|
|
2913
|
+
* files' rows, and the filters: a package, file, class,
|
|
2914
|
+
* `ClassName.methodName` substring or exact `category:name` identity.
|
|
2915
|
+
* @returns A promise of the result: succeeded, such as
|
|
2916
|
+
* `The tests passed, and coverage is complete.`, or failed for an unknown
|
|
2917
|
+
* option, a `build.json` that is not valid, no package with tests, a
|
|
2918
|
+
* compile that fails, failed tests, incomplete coverage, or a coverage
|
|
2919
|
+
* report that cannot run, such as without `@noldova/context.testing`
|
|
2920
|
+
* installed. It rejects with {@link ProcessException} if a program cannot
|
|
2921
|
+
* start.
|
|
2922
|
+
* @example
|
|
2923
|
+
* ```ts
|
|
2924
|
+
* (await step.runAsync(["--skip-test-details"])).message; // "The tests passed, and coverage is complete."
|
|
2925
|
+
* ```
|
|
2926
|
+
*/
|
|
2927
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2928
|
+
}
|
package/api/index.js
CHANGED
|
@@ -5,19 +5,24 @@
|
|
|
5
5
|
* This source code is licensed under the license found in the
|
|
6
6
|
* LICENSE file in the root directory of this source tree.
|
|
7
7
|
*/
|
|
8
|
+
export { BuildException } from "../exceptions/build.exception.js";
|
|
8
9
|
export { PipelineException } from "../exceptions/pipeline.exception.js";
|
|
9
10
|
export { ProcessException } from "../exceptions/process.exception.js";
|
|
10
11
|
export { VersionException } from "../exceptions/version.exception.js";
|
|
11
12
|
export { ArchiveCheck } from "../models/archive-check.js";
|
|
13
|
+
export { BuildConfig } from "../models/build-config.js";
|
|
14
|
+
export { BuildPackage } from "../models/build-package.js";
|
|
12
15
|
export { PackageArchive } from "../models/package-archive.js";
|
|
13
16
|
export { ProcessResult } from "../models/process-result.js";
|
|
14
17
|
export { StepResult } from "../models/step-result.js";
|
|
15
18
|
export { TrackedFile } from "../models/tracked-file.js";
|
|
16
19
|
export { Version } from "../models/version.js";
|
|
17
20
|
export { ArchiveStep } from "../services/archive-step.js";
|
|
21
|
+
export { BuildStep } from "../services/build-step.js";
|
|
18
22
|
export { CommandLine } from "../services/command-line.js";
|
|
19
23
|
export { DependentsStep } from "../services/dependents-step.js";
|
|
20
24
|
export { Git } from "../services/git.js";
|
|
25
|
+
export { InstalledStep } from "../services/installed-step.js";
|
|
21
26
|
export { LineEndingsStep } from "../services/line-endings-step.js";
|
|
22
27
|
export { NightlyStep } from "../services/nightly-step.js";
|
|
23
28
|
export { Npm } from "../services/npm.js";
|
|
@@ -29,6 +34,8 @@ export { ReproducibleStep } from "../services/reproducible-step.js";
|
|
|
29
34
|
export { SourceStep } from "../services/source-step.js";
|
|
30
35
|
export { TagStep } from "../services/tag-step.js";
|
|
31
36
|
export { Tar } from "../services/tar.js";
|
|
37
|
+
export { TestStep } from "../services/test-step.js";
|
|
32
38
|
export { ToolchainStep } from "../services/toolchain-step.js";
|
|
39
|
+
export { TypeScript } from "../services/type-script.js";
|
|
33
40
|
export { UnchangedStep } from "../services/unchanged-step.js";
|
|
34
41
|
//# sourceMappingURL=index.js.map
|
package/api/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/noldova.tools.pipelines/src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAMtE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/noldova.tools.pipelines/src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAMtE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}
|