@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/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"}