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