@noldova/tools.pipelines 0.0.10 → 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 CHANGED
@@ -1,7 +1,7 @@
1
1
  # @noldova/tools.pipelines
2
2
 
3
3
  The steps of a build and release pipeline that work the same on any host.
4
- This version holds the version model the steps share, the command-line base a host builds its command line on, and the steps: `source`, `archive`, `publish`, `nightly`, `prune`, `tag`, `toolchain`, `line-endings`, `unchanged`, `reproducible`, `dependents` and `pins`.
4
+ This version holds the version model the steps share, the command-line base a host builds its command line on, and the steps: `source`, `archive`, `publish`, `nightly`, `prune`, `tag`, `toolchain`, `line-endings`, `unchanged`, `reproducible`, `dependents`, `pins`, and `installed`, `build` and `test`, which build and test a repository's packages.
5
5
 
6
6
  ## Install
7
7
 
@@ -46,6 +46,7 @@ import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipe
46
46
 
47
47
  const git = new Git(new ProcessRunner(), process.cwd());
48
48
  const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
49
+ writeProgress: message => console.log(message),
49
50
  writeSuccess: message => console.log(message),
50
51
  writeFailure: message => console.error(message)
51
52
  });
@@ -87,6 +88,7 @@ import { ArchiveStep, CommandLine, Git, Npm, ProcessRunner, SourceStep, Tar } fr
87
88
  const processRunner = new ProcessRunner();
88
89
  const git = new Git(processRunner, process.cwd());
89
90
  const commandLine = new CommandLine("pipelines", [new SourceStep(git), new ArchiveStep(git, new Tar(processRunner), new Npm(processRunner, process.cwd()))], {
91
+ writeProgress: message => console.log(message),
90
92
  writeSuccess: message => console.log(message),
91
93
  writeFailure: message => console.error(message)
92
94
  });
@@ -113,6 +115,7 @@ import { ArchiveStep, CommandLine, Git, Npm, ProcessRunner, PublishStep, Tar } f
113
115
  const processRunner = new ProcessRunner();
114
116
  const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner), new Npm(processRunner, process.cwd()));
115
117
  const commandLine = new CommandLine("pipelines", [archiveStep, new PublishStep(archiveStep, new Npm(processRunner, process.cwd()))], {
118
+ writeProgress: message => console.log(message),
116
119
  writeSuccess: message => console.log(message),
117
120
  writeFailure: message => console.error(message)
118
121
  });
@@ -143,6 +146,7 @@ const git = new Git(processRunner, process.cwd());
143
146
  const npm = new Npm(processRunner, process.cwd());
144
147
  const nightlyStep = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner), npm), npm);
145
148
  const commandLine = new CommandLine("pipelines", [nightlyStep], {
149
+ writeProgress: message => console.log(message),
146
150
  writeSuccess: message => console.log(message),
147
151
  writeFailure: message => console.error(message)
148
152
  });
@@ -322,6 +326,63 @@ result.message; // "Looked for pins on .github's workflows older than v1.2.0 in
322
326
 
323
327
  The declaration file `api/index.d.ts` documents every member with its contract and examples.
324
328
 
329
+ ### Building and testing a repository
330
+
331
+ The `installed`, `build` and `test` steps build, pack and test the packages of a repository, so every repository runs the same build.
332
+ A repository lists its packages, in the order they build, in `build.json` at its root:
333
+
334
+ ```json
335
+ {
336
+ "scope": "@noldova",
337
+ "packages": [
338
+ { "name": "noldova.example" },
339
+ { "name": "noldova.example.parsers", "path": "parsers/noldova.example.parsers", "pre": "src/parsers/noldova.example.parsers/scripts/verify.ts" }
340
+ ]
341
+ }
342
+ ```
343
+
344
+ - `scope` is the npm scope the packages publish under, `@noldova` when omitted.
345
+ - `name` is the package's folder name: `noldova.` and lowercase segments joined by dots; the package's npm name is the scope, `/` and the name after `noldova.`, such as `@noldova/example`.
346
+ - `path` is the package's folder under `src/`, whose last segment is the name; it is the name when omitted.
347
+ - `pre`, `compile` and `post` are optional scripts, paths inside the checkout that Node.js runs with the package's source folder and build folder as its values: `pre` before the compile, `compile` instead of the TypeScript compile, and `post` after it.
348
+
349
+ Each package's folder holds `package.json`, with `__VERSION__` wherever the version goes, `README.md`, and, for the TypeScript compile, `src/tsconfig.json`, whose output is `_build/packages/<name>`; it may hold `src/api/index.d.ts`, the package's declarations, `THIRD-PARTY-NOTICES.txt`, and `tests/tsconfig.json`, whose output is `_build/tests/<name>`.
350
+
351
+ A repository's `package.json` runs the steps through the package's `pipelines` command:
352
+
353
+ ```json
354
+ "scripts": {
355
+ "build": "pipelines installed || npm ci --ignore-scripts && pipelines build",
356
+ "test": "pipelines test"
357
+ }
358
+ ```
359
+
360
+ #### The installed step
361
+
362
+ `installed` takes no values and succeeds, writing nothing, when `node_modules` holds what `package-lock.json` locks: every locked package at its version, address and integrity, but an optional one for another platform, and no other.
363
+ The repository's own packages are left out, since the build installs them.
364
+ It fails when `node_modules` is missing or differs, so the script above runs `npm ci --ignore-scripts` only after a clone or a change to the lock file.
365
+
366
+ #### The build step
367
+
368
+ `build [--version <version>] [<package>...]` builds the packages, or the ones named, in `build.json`'s order.
369
+ For each, it writes `_build/packages/<name>` afresh: `package.json`, with the version for `__VERSION__` and the head commit as `gitHead`, the repository's `LICENSE`, and the package's `README.md`, `src/api/index.d.ts` as `api/index.d.ts` and `THIRD-PARTY-NOTICES.txt` it has; then it runs `pre`, compiles `src/tsconfig.json` or runs `compile`, runs `post`, packs the package into `_packages/`, and installs every package built so far, so the next one builds against it.
370
+
371
+ - The version is `version.json`'s, or the one `--version` gives, such as a nightly `0.0.5-nightly.20261102`.
372
+ - It runs at the checkout's root, through an npm script, which sets the `npm_execpath` it packs and installs with.
373
+ - It fails with the first thing that is wrong, such as a missing `README.md` or what the compiler, a script or npm wrote.
374
+
375
+ `build --list-copies` lists each file the build copies into a package as `<source>\t<package>\t<file>` and ends with `end of copies`, which the archive step reads to check that each copy is the same as its source.
376
+
377
+ #### The test step
378
+
379
+ `test [--skip-test-details] [--skip-coverage-details] [<filter>...]` compiles each package's `tests/tsconfig.json`, runs the tests through the repository's `@noldova/context.testing` with V8 coverage in `_build/coverage`, and requires complete coverage of the packages' `src/` folders.
380
+
381
+ - Run the build first: the tests use the installed packages.
382
+ - A filter runs the tests that match a package, file, class, `ClassName.methodName` substring or exact `category:name` identity, and skips the coverage gate.
383
+ - `--skip-test-details` hides the passing tests' lines and `--skip-coverage-details` the fully covered files' rows; failures and totals always show.
384
+ - The tests and the coverage report each run in a Node.js process of their own, so the repository's packages never load beside the step's.
385
+
325
386
  ## License
326
387
 
327
388
  MIT; see `LICENSE`.