@noldova/tools.pipelines 0.0.9 → 0.0.11
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 +62 -1
- package/api/index.d.ts +531 -1
- 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 +154 -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 +75 -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
|
* };
|
|
@@ -525,6 +742,7 @@ export declare interface IStepOutput {
|
|
|
525
742
|
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
526
743
|
*
|
|
527
744
|
* const output: IStepOutput = {
|
|
745
|
+
* writeProgress: message => console.log(message),
|
|
528
746
|
* writeSuccess: message => console.log(message),
|
|
529
747
|
* writeFailure: message => console.error(message)
|
|
530
748
|
* };
|
|
@@ -791,6 +1009,7 @@ export declare class CommandLine {
|
|
|
791
1009
|
*
|
|
792
1010
|
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
793
1011
|
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
1012
|
+
* writeProgress: message => console.log(message),
|
|
794
1013
|
* writeSuccess: message => console.log(message),
|
|
795
1014
|
* writeFailure: message => console.error(message)
|
|
796
1015
|
* });
|
|
@@ -816,6 +1035,7 @@ export declare class CommandLine {
|
|
|
816
1035
|
*
|
|
817
1036
|
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
818
1037
|
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
1038
|
+
* writeProgress: message => console.log(message),
|
|
819
1039
|
* writeSuccess: message => console.log(message),
|
|
820
1040
|
* writeFailure: message => console.error(message)
|
|
821
1041
|
* });
|
|
@@ -860,6 +1080,28 @@ export declare class ProcessRunner {
|
|
|
860
1080
|
* ```
|
|
861
1081
|
*/
|
|
862
1082
|
public runAsync(program: string, values: readonly string[], workingDirectory: string, environment?: Readonly<Record<string, string | undefined>>, timeoutMilliseconds?: number): Promise<ProcessResult>;
|
|
1083
|
+
|
|
1084
|
+
/**
|
|
1085
|
+
* Runs a program to its end with this process's input and output, so what
|
|
1086
|
+
* it writes shows as it runs, such as a test run's progress.
|
|
1087
|
+
*
|
|
1088
|
+
* @param program The program, found on the `PATH` or a path to it.
|
|
1089
|
+
* @param values The values passed to the program, each as one argument,
|
|
1090
|
+
* never read by a shell.
|
|
1091
|
+
* @param workingDirectory The directory the program runs in.
|
|
1092
|
+
* @param environment Variables the program gets on top of this process's
|
|
1093
|
+
* own.
|
|
1094
|
+
* @returns A promise of the program's exit code, or `null` when a signal
|
|
1095
|
+
* ended it. It rejects with {@link ProcessException} only when the program
|
|
1096
|
+
* cannot start.
|
|
1097
|
+
* @example
|
|
1098
|
+
* ```ts
|
|
1099
|
+
* import { ProcessRunner } from "@noldova/tools.pipelines";
|
|
1100
|
+
*
|
|
1101
|
+
* await new ProcessRunner().runVisibleAsync("git", ["--version"], process.cwd(), {}); // 0, after git printed its version
|
|
1102
|
+
* ```
|
|
1103
|
+
*/
|
|
1104
|
+
public runVisibleAsync(program: string, values: readonly string[], workingDirectory: string, environment: Readonly<Record<string, string>>): Promise<number | null>;
|
|
863
1105
|
}
|
|
864
1106
|
|
|
865
1107
|
/**
|
|
@@ -1110,6 +1352,22 @@ export declare class Git {
|
|
|
1110
1352
|
*/
|
|
1111
1353
|
public readHeadAsync(): Promise<string>;
|
|
1112
1354
|
|
|
1355
|
+
/**
|
|
1356
|
+
* Reads where the working directory is inside the clone.
|
|
1357
|
+
*
|
|
1358
|
+
* @returns A promise of the path from the clone's root, ending with `/`,
|
|
1359
|
+
* such as `src/`, or empty at the root. It rejects with
|
|
1360
|
+
* {@link ProcessException} if git cannot start or fails, such as outside a
|
|
1361
|
+
* clone.
|
|
1362
|
+
* @example
|
|
1363
|
+
* ```ts
|
|
1364
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1365
|
+
*
|
|
1366
|
+
* await new Git(new ProcessRunner(), process.cwd()).readPrefixAsync(); // "" at the clone's root
|
|
1367
|
+
* ```
|
|
1368
|
+
*/
|
|
1369
|
+
public readPrefixAsync(): Promise<string>;
|
|
1370
|
+
|
|
1113
1371
|
/**
|
|
1114
1372
|
* Reads the email address of a commit's committer.
|
|
1115
1373
|
*
|
|
@@ -1240,6 +1498,9 @@ export declare class Npm {
|
|
|
1240
1498
|
* @param platform The platform npm runs on, as `process.platform` names it;
|
|
1241
1499
|
* on `win32`, where npm is a command script, it reads npm's version
|
|
1242
1500
|
* through `cmd.exe`. Omitted, it is `process.platform`.
|
|
1501
|
+
* @param environment The variables that name npm's command line, as an npm
|
|
1502
|
+
* script sets `npm_execpath`, which packing and installing the built
|
|
1503
|
+
* packages run with Node.js. Omitted, it is `process.env`.
|
|
1243
1504
|
* @example
|
|
1244
1505
|
* ```ts
|
|
1245
1506
|
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
@@ -1247,7 +1508,7 @@ export declare class Npm {
|
|
|
1247
1508
|
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
1248
1509
|
* ```
|
|
1249
1510
|
*/
|
|
1250
|
-
public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string);
|
|
1511
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string, platform?: string, environment?: Readonly<Record<string, string | undefined>>);
|
|
1251
1512
|
|
|
1252
1513
|
/**
|
|
1253
1514
|
* The directory `npm` runs in, as the constructor got it.
|
|
@@ -1400,6 +1661,44 @@ export declare class Npm {
|
|
|
1400
1661
|
*/
|
|
1401
1662
|
public readVersionAsync(): Promise<string>;
|
|
1402
1663
|
|
|
1664
|
+
/**
|
|
1665
|
+
* Packs a built package with `npm pack --silent --pack-destination`, run
|
|
1666
|
+
* by Node.js from `npm_execpath`.
|
|
1667
|
+
*
|
|
1668
|
+
* @param directory The built package's folder.
|
|
1669
|
+
* @param destination The folder the archive is written to.
|
|
1670
|
+
* @returns A promise of how `npm pack` ended. It throws
|
|
1671
|
+
* {@link BuildException} when `npm_execpath` is not set, as outside an npm
|
|
1672
|
+
* script, and rejects with {@link ProcessException} if Node.js cannot
|
|
1673
|
+
* start.
|
|
1674
|
+
* @example
|
|
1675
|
+
* ```ts
|
|
1676
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1677
|
+
*
|
|
1678
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).packAsync("_build/packages/noldova.example", "_packages")).isSuccessful; // true
|
|
1679
|
+
* ```
|
|
1680
|
+
*/
|
|
1681
|
+
public packAsync(directory: string, destination: string): Promise<ProcessResult>;
|
|
1682
|
+
|
|
1683
|
+
/**
|
|
1684
|
+
* Installs built archives in the working directory without saving them,
|
|
1685
|
+
* with `npm install --no-save --ignore-scripts`, run by Node.js from
|
|
1686
|
+
* `npm_execpath`.
|
|
1687
|
+
*
|
|
1688
|
+
* @param archivePaths The archives, such as
|
|
1689
|
+
* `./_packages/noldova-example-0.0.5.tgz`.
|
|
1690
|
+
* @returns A promise of how `npm install` ended. It throws
|
|
1691
|
+
* {@link BuildException} when `npm_execpath` is not set, and rejects with
|
|
1692
|
+
* {@link ProcessException} if Node.js cannot start.
|
|
1693
|
+
* @example
|
|
1694
|
+
* ```ts
|
|
1695
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
1696
|
+
*
|
|
1697
|
+
* (await new Npm(new ProcessRunner(), process.cwd()).installArchivesAsync(["./_packages/noldova-example-0.0.5.tgz"])).isSuccessful; // true
|
|
1698
|
+
* ```
|
|
1699
|
+
*/
|
|
1700
|
+
public installArchivesAsync(archivePaths: readonly string[]): Promise<ProcessResult>;
|
|
1701
|
+
|
|
1403
1702
|
/**
|
|
1404
1703
|
* Tells whether a text is a registry the steps take: an `https` URL
|
|
1405
1704
|
* without credentials, a query or a fragment.
|
|
@@ -1417,6 +1716,49 @@ export declare class Npm {
|
|
|
1417
1716
|
public static isRegistry(text: string): boolean;
|
|
1418
1717
|
}
|
|
1419
1718
|
|
|
1719
|
+
/**
|
|
1720
|
+
* Runs the TypeScript compiler a repository installs, so a build compiles
|
|
1721
|
+
* with the version the repository pins.
|
|
1722
|
+
*/
|
|
1723
|
+
export declare class TypeScript {
|
|
1724
|
+
/**
|
|
1725
|
+
* The repository's root, as the constructor got it.
|
|
1726
|
+
*/
|
|
1727
|
+
public readonly workingDirectory: string;
|
|
1728
|
+
|
|
1729
|
+
/**
|
|
1730
|
+
* Creates the runner.
|
|
1731
|
+
*
|
|
1732
|
+
* @param processRunner What runs the compiler.
|
|
1733
|
+
* @param workingDirectory The repository's root, where `typescript` is
|
|
1734
|
+
* installed.
|
|
1735
|
+
* @example
|
|
1736
|
+
* ```ts
|
|
1737
|
+
* import { ProcessRunner, TypeScript } from "@noldova/tools.pipelines";
|
|
1738
|
+
*
|
|
1739
|
+
* const typeScript = new TypeScript(new ProcessRunner(), process.cwd());
|
|
1740
|
+
* ```
|
|
1741
|
+
*/
|
|
1742
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
1743
|
+
|
|
1744
|
+
/**
|
|
1745
|
+
* Compiles a TypeScript project with `tsc --pretty --project`.
|
|
1746
|
+
*
|
|
1747
|
+
* @param projectPath The project's `tsconfig.json`, from the repository's
|
|
1748
|
+
* root.
|
|
1749
|
+
* @returns A promise of how the compiler ended, with what it wrote. It
|
|
1750
|
+
* throws {@link BuildException} when `typescript` is not installed, and
|
|
1751
|
+
* rejects with {@link ProcessException} if Node.js cannot start.
|
|
1752
|
+
* @example
|
|
1753
|
+
* ```ts
|
|
1754
|
+
* import { ProcessRunner, TypeScript } from "@noldova/tools.pipelines";
|
|
1755
|
+
*
|
|
1756
|
+
* (await new TypeScript(new ProcessRunner(), process.cwd()).compileAsync("src/noldova.example/src/tsconfig.json")).isSuccessful; // true
|
|
1757
|
+
* ```
|
|
1758
|
+
*/
|
|
1759
|
+
public compileAsync(projectPath: string): Promise<ProcessResult>;
|
|
1760
|
+
}
|
|
1761
|
+
|
|
1420
1762
|
/**
|
|
1421
1763
|
* The step that checks a release's source before anything is built or
|
|
1422
1764
|
* published: `source <version> <commit>`. It succeeds only when the version
|
|
@@ -2385,3 +2727,191 @@ export declare class PinsStep implements IStep {
|
|
|
2385
2727
|
*/
|
|
2386
2728
|
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2387
2729
|
}
|
|
2730
|
+
|
|
2731
|
+
/**
|
|
2732
|
+
* The step that checks a checkout's installed packages: `installed`. It
|
|
2733
|
+
* succeeds, writing nothing, only when `node_modules` holds what
|
|
2734
|
+
* `package-lock.json` locks: every locked package but an optional one for
|
|
2735
|
+
* another platform, at its version, address and integrity, and no other.
|
|
2736
|
+
* The packages the checkout builds are left out, since the build installs
|
|
2737
|
+
* them itself. A repository's npm script runs
|
|
2738
|
+
* `pipelines installed || npm ci --ignore-scripts && pipelines build`, so it
|
|
2739
|
+
* installs only when something changed.
|
|
2740
|
+
*/
|
|
2741
|
+
export declare class InstalledStep implements IStep {
|
|
2742
|
+
/**
|
|
2743
|
+
* The step's name, `"installed"`.
|
|
2744
|
+
*/
|
|
2745
|
+
public readonly name: string;
|
|
2746
|
+
|
|
2747
|
+
/**
|
|
2748
|
+
* The values the step takes, none: `""`.
|
|
2749
|
+
*/
|
|
2750
|
+
public readonly usage: string;
|
|
2751
|
+
|
|
2752
|
+
/**
|
|
2753
|
+
* Creates the step.
|
|
2754
|
+
*
|
|
2755
|
+
* @param workingDirectory The checkout's root.
|
|
2756
|
+
* @example
|
|
2757
|
+
* ```ts
|
|
2758
|
+
* import { InstalledStep } from "@noldova/tools.pipelines";
|
|
2759
|
+
*
|
|
2760
|
+
* const step = new InstalledStep(process.cwd());
|
|
2761
|
+
* step.name; // "installed"
|
|
2762
|
+
* ```
|
|
2763
|
+
*/
|
|
2764
|
+
public constructor(workingDirectory: string);
|
|
2765
|
+
|
|
2766
|
+
/**
|
|
2767
|
+
* Checks the installed packages.
|
|
2768
|
+
*
|
|
2769
|
+
* @param values None.
|
|
2770
|
+
* @returns A promise of the result: succeeded with an empty message, or
|
|
2771
|
+
* failed for any value, a `build.json` that is not valid, a missing
|
|
2772
|
+
* `package-lock.json`, `node_modules` without npm's record of what it
|
|
2773
|
+
* installed, or the first packages that differ, with the command that
|
|
2774
|
+
* installs them. It rejects with `JsonException` from
|
|
2775
|
+
* `@noldova/context.json` for a lock file that is not valid JSON.
|
|
2776
|
+
* @example
|
|
2777
|
+
* ```ts
|
|
2778
|
+
* import { InstalledStep } from "@noldova/tools.pipelines";
|
|
2779
|
+
*
|
|
2780
|
+
* (await new InstalledStep(process.cwd()).runAsync([])).message;
|
|
2781
|
+
* // "The installed packages differ from package-lock.json at node_modules/typescript; run npm ci --ignore-scripts."
|
|
2782
|
+
* ```
|
|
2783
|
+
*/
|
|
2784
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2785
|
+
}
|
|
2786
|
+
|
|
2787
|
+
/**
|
|
2788
|
+
* The step that builds a checkout's packages:
|
|
2789
|
+
* `build [--version <version>] [<package>...]`, or `build --list-copies`. For each
|
|
2790
|
+
* package `build.json` names, in order, it writes the package's
|
|
2791
|
+
* `package.json` with the version for `__VERSION__` and the head commit as
|
|
2792
|
+
* `gitHead`, copies the `LICENSE`, the `README.md`, the
|
|
2793
|
+
* `src/api/index.d.ts` and the `THIRD-PARTY-NOTICES.txt` it has, runs its
|
|
2794
|
+
* `pre` script, compiles it or runs its `compile` script, runs its `post`
|
|
2795
|
+
* script, packs it into `_packages/` and installs every built archive, so
|
|
2796
|
+
* the next package builds against it. With `--list-copies`, it lists the
|
|
2797
|
+
* files it copies as the archive step reads them.
|
|
2798
|
+
*/
|
|
2799
|
+
export declare class BuildStep implements IStep {
|
|
2800
|
+
/**
|
|
2801
|
+
* The step's name, `"build"`.
|
|
2802
|
+
*/
|
|
2803
|
+
public readonly name: string;
|
|
2804
|
+
|
|
2805
|
+
/**
|
|
2806
|
+
* The values the step takes,
|
|
2807
|
+
* `"[--version <version>] [<package>...], or --list-copies"`.
|
|
2808
|
+
*/
|
|
2809
|
+
public readonly usage: string;
|
|
2810
|
+
|
|
2811
|
+
/**
|
|
2812
|
+
* Creates the step.
|
|
2813
|
+
*
|
|
2814
|
+
* @param git What reads the head commit, in the checkout's root.
|
|
2815
|
+
* @param npm What packs and installs the built packages.
|
|
2816
|
+
* @param typeScript What compiles a package.
|
|
2817
|
+
* @param processRunner What runs a package's scripts.
|
|
2818
|
+
* @param output Where the step writes the package it builds.
|
|
2819
|
+
* @example
|
|
2820
|
+
* ```ts
|
|
2821
|
+
* import { BuildStep, Git, Npm, ProcessRunner, TypeScript, type IStepOutput } from "@noldova/tools.pipelines";
|
|
2822
|
+
*
|
|
2823
|
+
* declare const output: IStepOutput;
|
|
2824
|
+
* const processRunner = new ProcessRunner();
|
|
2825
|
+
* const step = new BuildStep(new Git(processRunner, process.cwd()), new Npm(processRunner, process.cwd()), new TypeScript(processRunner, process.cwd()), processRunner, output);
|
|
2826
|
+
* step.name; // "build"
|
|
2827
|
+
* ```
|
|
2828
|
+
*/
|
|
2829
|
+
public constructor(git: Git, npm: Npm, typeScript: TypeScript, processRunner: ProcessRunner, output: IStepOutput);
|
|
2830
|
+
|
|
2831
|
+
/**
|
|
2832
|
+
* Builds the packages, or lists the files the build copies.
|
|
2833
|
+
*
|
|
2834
|
+
* @param values `--version` and a version to build instead of
|
|
2835
|
+
* `version.json`'s, such as a nightly `0.0.5-nightly.20261102`, and the
|
|
2836
|
+
* folder names of the packages to build, all of them when none is named;
|
|
2837
|
+
* or `--list-copies` alone.
|
|
2838
|
+
* @returns A promise of the result: succeeded, such as
|
|
2839
|
+
* `Built 2 packages at version 0.0.5.`, or, with `--list-copies`, a line
|
|
2840
|
+
* `<source>\t<package>\t<file>` for each copy and `end of copies`; or
|
|
2841
|
+
* failed for an unknown option, a version that is not one, a package
|
|
2842
|
+
* named twice or that `build.json` doesn't name, a directory that is not
|
|
2843
|
+
* the checkout's root, or the first package that fails, with what the
|
|
2844
|
+
* compiler, script or npm wrote. It rejects with
|
|
2845
|
+
* {@link ProcessException} if a program cannot start, and with
|
|
2846
|
+
* `JsonException` from `@noldova/context.json` for a `build.json`,
|
|
2847
|
+
* `version.json` or package's `package.json` that is not valid JSON.
|
|
2848
|
+
* @example
|
|
2849
|
+
* ```ts
|
|
2850
|
+
* (await step.runAsync(["--version", "0.0.5-nightly.20261102"])).message; // "Built 2 packages at version 0.0.5-nightly.20261102."
|
|
2851
|
+
* ```
|
|
2852
|
+
*/
|
|
2853
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2854
|
+
}
|
|
2855
|
+
|
|
2856
|
+
/**
|
|
2857
|
+
* The step that tests a checkout's packages:
|
|
2858
|
+
* `test [--skip-test-details] [--skip-coverage-details] [<filter>...]`. It
|
|
2859
|
+
* compiles each package's `tests/tsconfig.json` into `_build/tests/<name>`,
|
|
2860
|
+
* runs them through the checkout's `@noldova/context.testing` with V8
|
|
2861
|
+
* coverage, and requires complete coverage of the packages' source; a run
|
|
2862
|
+
* with filters skips the coverage gate. The tests and the coverage report
|
|
2863
|
+
* each run in a Node.js process of their own, so the checkout's packages
|
|
2864
|
+
* never load beside the step's. Run the build first: the tests use the
|
|
2865
|
+
* installed packages.
|
|
2866
|
+
*/
|
|
2867
|
+
export declare class TestStep implements IStep {
|
|
2868
|
+
/**
|
|
2869
|
+
* The step's name, `"test"`.
|
|
2870
|
+
*/
|
|
2871
|
+
public readonly name: string;
|
|
2872
|
+
|
|
2873
|
+
/**
|
|
2874
|
+
* The values the step takes,
|
|
2875
|
+
* `"[--skip-test-details] [--skip-coverage-details] [<filter>...]"`.
|
|
2876
|
+
*/
|
|
2877
|
+
public readonly usage: string;
|
|
2878
|
+
|
|
2879
|
+
/**
|
|
2880
|
+
* Creates the step.
|
|
2881
|
+
*
|
|
2882
|
+
* @param typeScript What compiles the tests, in the checkout's root.
|
|
2883
|
+
* @param processRunner What runs the tests.
|
|
2884
|
+
* @param output Where the step writes its progress.
|
|
2885
|
+
* @example
|
|
2886
|
+
* ```ts
|
|
2887
|
+
* import { ProcessRunner, TestStep, TypeScript, type IStepOutput } from "@noldova/tools.pipelines";
|
|
2888
|
+
*
|
|
2889
|
+
* declare const output: IStepOutput;
|
|
2890
|
+
* const processRunner = new ProcessRunner();
|
|
2891
|
+
* const step = new TestStep(new TypeScript(processRunner, process.cwd()), processRunner, output);
|
|
2892
|
+
* step.name; // "test"
|
|
2893
|
+
* ```
|
|
2894
|
+
*/
|
|
2895
|
+
public constructor(typeScript: TypeScript, processRunner: ProcessRunner, output: IStepOutput);
|
|
2896
|
+
|
|
2897
|
+
/**
|
|
2898
|
+
* Tests the packages.
|
|
2899
|
+
*
|
|
2900
|
+
* @param values The options, `--skip-test-details` to hide the passing
|
|
2901
|
+
* tests' lines and `--skip-coverage-details` to hide the fully covered
|
|
2902
|
+
* files' rows, and the filters: a package, file, class,
|
|
2903
|
+
* `ClassName.methodName` substring or exact `category:name` identity.
|
|
2904
|
+
* @returns A promise of the result: succeeded, such as
|
|
2905
|
+
* `The tests passed, and coverage is complete.`, or failed for an unknown
|
|
2906
|
+
* option, a `build.json` that is not valid, no package with tests, a
|
|
2907
|
+
* compile that fails, failed tests, incomplete coverage, or a coverage
|
|
2908
|
+
* report that cannot run, such as without `@noldova/context.testing`
|
|
2909
|
+
* installed. It rejects with {@link ProcessException} if a program cannot
|
|
2910
|
+
* start.
|
|
2911
|
+
* @example
|
|
2912
|
+
* ```ts
|
|
2913
|
+
* (await step.runAsync(["--skip-test-details"])).message; // "The tests passed, and coverage is complete."
|
|
2914
|
+
* ```
|
|
2915
|
+
*/
|
|
2916
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
2917
|
+
}
|
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"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) Noldova.
|
|
4
|
+
*
|
|
5
|
+
* This source code is licensed under the license found in the
|
|
6
|
+
* LICENSE file in the root directory of this source tree.
|
|
7
|
+
*/
|
|
8
|
+
import { PipelineException } from "./pipeline.exception.js";
|
|
9
|
+
export class BuildException extends PipelineException {
|
|
10
|
+
constructor(message, options) {
|
|
11
|
+
super(message, options);
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
//# sourceMappingURL=build.exception.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"build.exception.js","sourceRoot":"","sources":["../../../../src/noldova.tools.pipelines/src/exceptions/build.exception.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,MAAM,OAAO,cAAe,SAAQ,iBAAiB;IACnD,YAAmB,OAAe,EAAE,OAA0B;QAC5D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF"}
|