@noldova/tools.pipelines 0.0.10 → 0.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -1
- package/api/index.d.ts +543 -2
- package/api/index.js +7 -0
- package/api/index.js.map +1 -1
- package/exceptions/build.exception.js +14 -0
- package/exceptions/build.exception.js.map +1 -0
- package/interfaces/i-testing-module.js +9 -0
- package/interfaces/i-testing-module.js.map +1 -0
- package/models/build-config.js +66 -0
- package/models/build-config.js.map +1 -0
- package/models/build-package.js +37 -0
- package/models/build-package.js.map +1 -0
- package/package.json +2 -2
- package/resources.js +164 -0
- package/resources.js.map +1 -1
- package/services/build-step.js +172 -0
- package/services/build-step.js.map +1 -0
- package/services/coverage-entry-point.js +30 -0
- package/services/coverage-entry-point.js.map +1 -0
- package/services/git.js +3 -0
- package/services/git.js.map +1 -1
- package/services/installed-step.js +87 -0
- package/services/installed-step.js.map +1 -0
- package/services/npm.js +16 -1
- package/services/npm.js.map +1 -1
- package/services/process-runner.js +7 -0
- package/services/process-runner.js.map +1 -1
- package/services/test-step.js +89 -0
- package/services/test-step.js.map +1 -0
- package/services/type-script.js +33 -0
- package/services/type-script.js.map +1 -0
package/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 `
|
|
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,67 @@ 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 [<folder>]` 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
|
+
It checks the working directory, or the folder given, a path from it with its own `package-lock.json`, such as one that pins a build tool apart from the repository's packages.
|
|
364
|
+
The packages a `build.json` in that folder names are left out, since the build installs them.
|
|
365
|
+
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.
|
|
366
|
+
That failure is the answer the check exists for, not an error: it writes the difference and the command that installs as a plain line, and the host writes no error for it.
|
|
367
|
+
A folder without `package-lock.json` is an error, since no install can fix it.
|
|
368
|
+
The parentheses make the script run the same in a POSIX shell and in Windows' `cmd`, which reads `a || b && c` as `a || (b && c)`.
|
|
369
|
+
|
|
370
|
+
#### The build step
|
|
371
|
+
|
|
372
|
+
`build [--version <version>] [<package>...]` builds the packages, or the ones named, in `build.json`'s order.
|
|
373
|
+
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.
|
|
374
|
+
|
|
375
|
+
- The version is `version.json`'s, or the one `--version` gives, such as a nightly `0.0.5-nightly.20261102`.
|
|
376
|
+
- It runs at the checkout's root, through an npm script, which sets the `npm_execpath` it packs and installs with.
|
|
377
|
+
- It fails with the first thing that is wrong, such as a missing `README.md` or what the compiler, a script or npm wrote.
|
|
378
|
+
|
|
379
|
+
`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.
|
|
380
|
+
|
|
381
|
+
#### The test step
|
|
382
|
+
|
|
383
|
+
`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.
|
|
384
|
+
|
|
385
|
+
- Run the build first: the tests use the installed packages.
|
|
386
|
+
- A filter runs the tests that match a package, file, class, `ClassName.methodName` substring or exact `category:name` identity, and skips the coverage gate.
|
|
387
|
+
- `--skip-test-details` hides the passing tests' lines and `--skip-coverage-details` the fully covered files' rows; failures and totals always show.
|
|
388
|
+
- 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.
|
|
389
|
+
|
|
325
390
|
## License
|
|
326
391
|
|
|
327
392
|
MIT; see `LICENSE`.
|