spec-controller 0.1.117 → 0.1.119
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 +7 -7
- package/dist/cli.js +37 -33
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
**One command, `balance`, that checks the behaviour your scenarios name against the evidence that actually ran.**
|
|
4
4
|
|
|
5
|
-
You give it your Gherkin scenarios and the reports your tools already write: a Vitest report, a Cucumber report, and your CI run's own record of what its steps did. It prints one table
|
|
5
|
+
You give it your Gherkin scenarios and the reports your tools already write: a Vitest report, a Cucumber report, and your CI run's own record of what its steps did. It prints one table showing which scenarios have living evidence, which do not, and which evidence ran that no scenario asked for.
|
|
6
6
|
|
|
7
|
-
It runs nothing itself
|
|
7
|
+
It runs nothing itself; it only reads what your pipeline wrote.
|
|
8
8
|
|
|
9
9
|
Requires Node ≥ 22. ESM only.
|
|
10
10
|
|
|
@@ -28,7 +28,7 @@ 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.
|
|
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 silence the right answer.
|
|
32
32
|
|
|
33
33
|
**`balance` fails your build by default.** An out-of-balance run exits `1`, so the run above reds 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
|
|
|
@@ -43,9 +43,9 @@ spec-controller balance --features ./features --vitest ./vitest-report.json --ex
|
|
|
43
43
|
The report is byte for byte the one the gate prints: the same rows, the same out-of-balance count, and the same headline naming the code the gate would give. Only the exit status changes:
|
|
44
44
|
|
|
45
45
|
- Out-of-balance and scenario code errors (`1`), and pending under `--strict` (`3`), exit `0`.
|
|
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
|
|
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 down, then delete `--exit-zero`, and the gate is 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
|
|
48
|
+
Work the out-of-balance rows down, then delete `--exit-zero`, and the gate is 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
|
|
|
@@ -72,7 +72,7 @@ A scenario tagged `@unit` names an obligation: a unit test must exist and pass.
|
|
|
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
|
|
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`. Matching `1` exactly is not affected when a code is added. Treating any non-zero code as a red build is correct, only less precise about why.
|
|
76
76
|
|
|
77
77
|
**Node's default exit code is never one of these.** A run that cannot reconcile ends on one of its own codes, never by falling out of the process: a crash that exits `1` would look, by status, exactly like an honest disagreement.
|
|
78
78
|
|
|
@@ -107,7 +107,7 @@ spec-controller balance --features ./features \
|
|
|
107
107
|
--format json:reconciliation.json
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
`--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
|
|
110
|
+
`--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. No action, no plugin, no permission.
|
|
111
111
|
|
|
112
112
|
`spec-controller balance --help` lists every flag, one line each.
|
|
113
113
|
|
package/dist/cli.js
CHANGED
|
@@ -11942,8 +11942,27 @@ function reconcileEvidenceObligation(scnId, obligation, evidenceObservations) {
|
|
|
11942
11942
|
function fitnessFunctionNameOf(observation) {
|
|
11943
11943
|
return isFitnessObservation(observation) ? observation.fitnessFunction : void 0;
|
|
11944
11944
|
}
|
|
11945
|
+
function remarkOf(o) {
|
|
11946
|
+
return {
|
|
11947
|
+
...o.locator !== void 0 ? { locator: o.locator } : {},
|
|
11948
|
+
...o.message !== void 0 ? { message: o.message } : {},
|
|
11949
|
+
...o.notes !== void 0 ? { notes: o.notes } : {}
|
|
11950
|
+
};
|
|
11951
|
+
}
|
|
11952
|
+
function brokenReconciliationOf(o) {
|
|
11953
|
+
return makeQualityCheckReconciliation({
|
|
11954
|
+
qualityCheck: o.qualityCheck,
|
|
11955
|
+
...fitnessFunctionNameOf(o) !== void 0 ? { fitnessFunction: fitnessFunctionNameOf(o) } : {},
|
|
11956
|
+
outcome: "broken",
|
|
11957
|
+
evidenceObservation: o,
|
|
11958
|
+
...remarkOf(o)
|
|
11959
|
+
});
|
|
11960
|
+
}
|
|
11961
|
+
function brokenReconciliationsOf(postedObservations) {
|
|
11962
|
+
return postedObservations.filter((o) => o.broken === true).map(brokenReconciliationOf);
|
|
11963
|
+
}
|
|
11945
11964
|
function noEvidenceObligationReconciliationsOf(scnId, postedObservations, evidenceObligationPairs) {
|
|
11946
|
-
return postedObservations.filter((o) => !evidenceObligationPairs.has(evidenceObligationPairKey(scnId, o.qualityCheck))).map((o) => makeQualityCheckReconciliation({
|
|
11965
|
+
return postedObservations.filter((o) => o.broken === true || !evidenceObligationPairs.has(evidenceObligationPairKey(scnId, o.qualityCheck))).map((o) => o.broken === true ? brokenReconciliationOf(o) : makeQualityCheckReconciliation({
|
|
11947
11966
|
qualityCheck: o.qualityCheck,
|
|
11948
11967
|
outcome: "no-evidence-obligation",
|
|
11949
11968
|
...fitnessFunctionNameOf(o) !== void 0 ? { fitnessFunction: fitnessFunctionNameOf(o) } : {},
|
|
@@ -11952,7 +11971,7 @@ function noEvidenceObligationReconciliationsOf(scnId, postedObservations, eviden
|
|
|
11952
11971
|
}));
|
|
11953
11972
|
}
|
|
11954
11973
|
function citesUnknownScenarioReconciliationsOf(observations) {
|
|
11955
|
-
return observations.map((o) => makeQualityCheckReconciliation({
|
|
11974
|
+
return observations.map((o) => o.broken === true ? brokenReconciliationOf(o) : makeQualityCheckReconciliation({
|
|
11956
11975
|
qualityCheck: o.qualityCheck,
|
|
11957
11976
|
...isFitnessObservation(o) ? { fitnessFunction: o.fitnessFunction } : {},
|
|
11958
11977
|
outcome: "cites-unknown-scenario",
|
|
@@ -11962,20 +11981,12 @@ function citesUnknownScenarioReconciliationsOf(observations) {
|
|
|
11962
11981
|
}
|
|
11963
11982
|
function unnamedClaimReconciliationsOf(brokenEvidence, uncited, uncitedFitnessFunctions) {
|
|
11964
11983
|
return [
|
|
11965
|
-
...brokenEvidence.map(
|
|
11966
|
-
qualityCheck: o.qualityCheck,
|
|
11967
|
-
outcome: "broken",
|
|
11968
|
-
...o.locator !== void 0 ? { locator: o.locator } : {},
|
|
11969
|
-
...o.message !== void 0 ? { message: o.message } : {},
|
|
11970
|
-
..."notes" in o && o.notes !== void 0 ? { notes: o.notes } : {}
|
|
11971
|
-
})),
|
|
11984
|
+
...brokenEvidence.map(brokenReconciliationOf),
|
|
11972
11985
|
...uncited.map((o) => makeQualityCheckReconciliation({
|
|
11973
11986
|
qualityCheck: o.qualityCheck,
|
|
11974
11987
|
outcome: "cites-no-scenario",
|
|
11975
11988
|
evidenceObservation: o,
|
|
11976
|
-
...o
|
|
11977
|
-
...o.message !== void 0 ? { message: o.message } : {},
|
|
11978
|
-
...o.notes !== void 0 ? { notes: o.notes } : {}
|
|
11989
|
+
...remarkOf(o)
|
|
11979
11990
|
})),
|
|
11980
11991
|
...uncitedFitnessFunctions.map((o) => makeQualityCheckReconciliation({
|
|
11981
11992
|
qualityCheck: "fitness",
|
|
@@ -12020,7 +12031,7 @@ var init_qualityCheckReconciliation = __esm({
|
|
|
12020
12031
|
"cites-unknown-scenario": { obligation: "None", observation: "Exists" },
|
|
12021
12032
|
"cites-no-scenario": { obligation: "None", observation: "Exists" },
|
|
12022
12033
|
"no-evidence-obligation": { obligation: "None", observation: "Exists" },
|
|
12023
|
-
broken: { obligation: "None", observation: "
|
|
12034
|
+
broken: { obligation: "None", observation: "Exists" },
|
|
12024
12035
|
"both-missing": { obligation: "None", observation: "None" }
|
|
12025
12036
|
};
|
|
12026
12037
|
OUT_OF_BALANCE_OUTCOMES = Object.keys(OUTCOME_SIDE_PROFILE).filter((outcome) => outcome !== "satisfied");
|
|
@@ -12226,28 +12237,15 @@ var init_ledger = __esm({
|
|
|
12226
12237
|
|
|
12227
12238
|
// ../core/dist/domain/posting.js
|
|
12228
12239
|
function postingOf(observation, scenarioIds) {
|
|
12229
|
-
|
|
12230
|
-
|
|
12231
|
-
|
|
12232
|
-
}
|
|
12233
|
-
if (observation.scnId !== void 0) {
|
|
12234
|
-
return scenarioIds.has(observation.scnId) ? { kind: "scenario", scnId: observation.scnId } : { kind: "phantom-claim", scnId: observation.scnId };
|
|
12235
|
-
}
|
|
12236
|
-
return { kind: "unnamed-claim", posted: "cites-nothing" };
|
|
12240
|
+
const scnId = observation.scnId ?? null;
|
|
12241
|
+
if (scnId === null) {
|
|
12242
|
+
return { kind: "unnamed-claim", posted: observation.broken === true ? "broken" : "cites-nothing" };
|
|
12237
12243
|
}
|
|
12238
|
-
|
|
12239
|
-
return { kind: "unnamed-claim", posted: "broken" };
|
|
12240
|
-
if (observation.scnId === null)
|
|
12241
|
-
return { kind: "unnamed-claim", posted: "cites-nothing" };
|
|
12242
|
-
if (!scenarioIds.has(observation.scnId)) {
|
|
12243
|
-
return { kind: "phantom-claim", scnId: observation.scnId };
|
|
12244
|
-
}
|
|
12245
|
-
return { kind: "scenario", scnId: observation.scnId };
|
|
12244
|
+
return scenarioIds.has(scnId) ? { kind: "scenario", scnId } : { kind: "phantom-claim", scnId };
|
|
12246
12245
|
}
|
|
12247
12246
|
var init_posting = __esm({
|
|
12248
12247
|
"../core/dist/domain/posting.js"() {
|
|
12249
12248
|
"use strict";
|
|
12250
|
-
init_journal();
|
|
12251
12249
|
}
|
|
12252
12250
|
});
|
|
12253
12251
|
|
|
@@ -12342,7 +12340,10 @@ function accountsByCode(scenarios) {
|
|
|
12342
12340
|
function duplicateScnCodeRow(sharers, citations) {
|
|
12343
12341
|
const scnId = sharers[0].scnId;
|
|
12344
12342
|
const evidenceObligations2 = sharers.flatMap((s) => s.evidenceObligations);
|
|
12345
|
-
const items =
|
|
12343
|
+
const items = [
|
|
12344
|
+
...duplicateScnCodeReconciliationsOf(evidenceObligations2),
|
|
12345
|
+
...brokenReconciliationsOf(citations.observationsFor(scnId))
|
|
12346
|
+
];
|
|
12346
12347
|
return {
|
|
12347
12348
|
scnId,
|
|
12348
12349
|
kind: "scenario",
|
|
@@ -29017,8 +29018,11 @@ var init_remarkWords = __esm({
|
|
|
29017
29018
|
});
|
|
29018
29019
|
|
|
29019
29020
|
// ../core/dist/domain/unnamedClaimGroups.js
|
|
29021
|
+
function citesNoScenario(item) {
|
|
29022
|
+
return item.outcome === "cites-no-scenario";
|
|
29023
|
+
}
|
|
29020
29024
|
function isFileGrouped(item) {
|
|
29021
|
-
return item.evidenceObservation !== void 0 && !isFitnessObservation(item.evidenceObservation);
|
|
29025
|
+
return citesNoScenario(item) && item.evidenceObservation !== void 0 && !isFitnessObservation(item.evidenceObservation);
|
|
29022
29026
|
}
|
|
29023
29027
|
function keyOf(item) {
|
|
29024
29028
|
return JSON.stringify([item.evidenceObservation.qualityCheck, item.locator ?? null]);
|
|
@@ -29040,7 +29044,7 @@ function groupOf(items) {
|
|
|
29040
29044
|
};
|
|
29041
29045
|
}
|
|
29042
29046
|
function stepsGroupOf(items) {
|
|
29043
|
-
const names = items.flatMap(({ evidenceObservation: o }) => o !== void 0 && isFitnessObservation(o) ? [o.fitnessFunction] : []);
|
|
29047
|
+
const names = items.filter(citesNoScenario).flatMap(({ evidenceObservation: o }) => o !== void 0 && isFitnessObservation(o) ? [o.fitnessFunction] : []);
|
|
29044
29048
|
return names.length === 0 ? [] : [{ names }];
|
|
29045
29049
|
}
|
|
29046
29050
|
function unnamedClaimGroupsOf(items) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spec-controller",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.119",
|
|
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",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"esbuild": "0.28.1",
|
|
26
26
|
"fast-xml-parser": "^5.11.2",
|
|
27
27
|
"yaml": "^2.9.0",
|
|
28
|
-
"@3f-consulting/spec-controller-core": "0.1.
|
|
28
|
+
"@3f-consulting/spec-controller-core": "0.1.119"
|
|
29
29
|
},
|
|
30
30
|
"publishConfig": {
|
|
31
31
|
"access": "public"
|