spec-controller 0.1.259 → 0.1.261
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 +12 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -28,24 +28,24 @@ Point it at your scenarios and nothing else:
|
|
|
28
28
|
spec-controller balance --features ./features
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
Every scenario gets a row, whether or not any evidence exists for it. You have supplied no reports, so every scenario that names evidence reads **missing** and the run is out-of-balance. That is by design, not a fault in your repository
|
|
31
|
+
Every scenario gets a row, whether or not any evidence exists for it. You have supplied no reports, so every scenario that names evidence reads **missing** and the run is out-of-balance. That is by design, not a fault in your repository. The tool starts from what you specified, not from what a tool happened to find, and no input makes saying nothing the right answer.
|
|
32
32
|
|
|
33
|
-
**`balance` fails your build by default.** An out-of-balance run exits `1`, so the run above
|
|
33
|
+
**`balance` fails your build by default.** An out-of-balance run exits `1`, so the run above fails any pipeline you put it in. Two tools it sits beside do the opposite: Stryker's `thresholds.break` defaults to `null` (*"never let your build fail"*), and the Sonar scanner exits `0` whatever its quality gate says unless you set `sonar.qualitygate.wait`. Both make you opt in to gating. `balance` makes you opt out.
|
|
34
34
|
|
|
35
35
|
### Report first, gate later
|
|
36
36
|
|
|
37
|
-
To add it to an existing pipeline without
|
|
37
|
+
To add it to an existing pipeline without failing that pipeline on day one, add `--exit-zero`:
|
|
38
38
|
|
|
39
39
|
```
|
|
40
40
|
spec-controller balance --features ./features --vitest ./vitest-report.json --exit-zero
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
Apart from the timestamp each run stamps for itself, the report is byte for byte the one a run without the flag prints: the same rows, the same out-of-balance count, and the same headline naming the code that run would give. Only the exit status changes:
|
|
44
44
|
|
|
45
45
|
- Out-of-balance and claim code errors (`1`), and pending under `--strict` (`3`), exit `0`.
|
|
46
46
|
- Usage (`2`), unsound (`4`), nothing to reconcile (`5`) and an unexpected error before the verdict (`6`) still fail. Each means the run could not reach a verdict, and a flag that suppresses verdicts does not suppress that.
|
|
47
47
|
|
|
48
|
-
Work the out-of-balance rows
|
|
48
|
+
Work through the out-of-balance rows, then delete `--exit-zero`. The gate is then on. Do not wrap the step in `continue-on-error` or `|| true` instead. Those swallow the codes that mean the run could not be trusted, and leave nothing in the command to show the gate is off.
|
|
49
49
|
|
|
50
50
|
### Give it the evidence
|
|
51
51
|
|
|
@@ -63,18 +63,18 @@ A scenario tagged `@unit` names an obligation: a unit test must exist and pass.
|
|
|
63
63
|
| Exit | What it says |
|
|
64
64
|
| --- | --- |
|
|
65
65
|
| `0` | balanced — every obligation has evidence, and it holds |
|
|
66
|
-
| `1` | out-of-balance — the
|
|
66
|
+
| `1` | out-of-balance — the scenarios and the evidence disagree, and the report says where; or a claim code is misfiled, listed under `### Claim code errors` |
|
|
67
67
|
| `2` | usage — the invocation was wrong |
|
|
68
68
|
| `3` | balanced, but carrying Pending Items, and you asked for `--strict` |
|
|
69
|
-
| `4` | unsound — a proving suite failed to collect, so the ledger
|
|
70
|
-
| `5` | nothing to reconcile — no scenario
|
|
71
|
-
| `6` | unexpected error — the run
|
|
69
|
+
| `4` | unsound — a proving suite failed to collect, so the ledger cannot be trusted to show a disagreement |
|
|
70
|
+
| `5` | nothing to reconcile — no scenario is carried and no evidence is produced, so the run has no basis for a verdict |
|
|
71
|
+
| `6` | unexpected error — the run stops on an error no refusal names, and gives no verdict; one line on stderr names it. `--exit-zero` never moves it |
|
|
72
72
|
|
|
73
73
|
The whole report is written before the exit code is set, so a failing run still tells you why.
|
|
74
74
|
|
|
75
|
-
**Design your pipeline for new codes.** The list is open at the top: a state that is none of the above gets a **new** code, not the nearest existing one. The highest is `6`. **Treat an unrecognised non-zero code as a failure you have not seen before**, not as a synonym for `1`.
|
|
75
|
+
**Design your pipeline for new codes.** The list is open at the top: a state that is none of the above gets a **new** code, not the nearest existing one. The highest is `6`. **Treat an unrecognised non-zero code as a failure you have not seen before**, not as a synonym for `1`. A pipeline that matches `1` exactly is not affected when a code is added. A pipeline that treats any non-zero code as a failed build is correct, only less precise about why.
|
|
76
76
|
|
|
77
|
-
**Node's default exit code is never one of these.** A run that cannot reconcile ends on one of
|
|
77
|
+
**Node's default exit code is never one of these.** A run that cannot reconcile ends on one of the codes above, never by crashing out of the process. A crash that exits `1` would look, by status, exactly like an honest disagreement.
|
|
78
78
|
|
|
79
79
|
**An input it cannot read is a usage error (`2`)**, never a verdict about your code. This covers:
|
|
80
80
|
|
|
@@ -102,7 +102,7 @@ spec-controller balance --features ./features \
|
|
|
102
102
|
--format json:reconciliation.json
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
`--format` can be repeated and takes an optional `:<path>`. On GitHub Actions, writing Markdown to `$GITHUB_STEP_SUMMARY` puts the reconciliation on the run's summary page, the channel GitHub provides for a table.
|
|
105
|
+
`--format` can be repeated and takes an optional `:<path>`. On GitHub Actions, writing Markdown to `$GITHUB_STEP_SUMMARY` puts the reconciliation on the run's summary page, the channel GitHub provides for a table. This needs no action, no plugin and no permission.
|
|
106
106
|
|
|
107
107
|
`spec-controller balance --help` lists every flag, one line each.
|
|
108
108
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-controller",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.261",
|
|
4
4
|
"description": "Reconcile the behaviour your scenarios name against the evidence that actually ran — the deterministic `balance` CLI.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"reconciliation",
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"fast-xml-parser": "^5.11.2",
|
|
27
27
|
"ts-json-schema-generator": "^2.9.0",
|
|
28
28
|
"yaml": "^2.9.0",
|
|
29
|
-
"@3f-consulting/spec-controller-core": "0.1.
|
|
29
|
+
"@3f-consulting/spec-controller-core": "0.1.261"
|
|
30
30
|
},
|
|
31
31
|
"publishConfig": {
|
|
32
32
|
"access": "public"
|