@vaultcompass/conductor 0.10.0 → 0.11.0
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 +39 -19
- package/dist/intent-prepare.d.ts +33 -1
- package/dist/intent-prepare.js +137 -33
- package/dist/intent-spec.d.ts +108 -22
- package/dist/intent-spec.js +226 -55
- package/dist/output-sarif.js +54 -1
- package/dist/output-text.d.ts +11 -0
- package/dist/output-text.js +118 -8
- package/dist/run.d.ts +9 -1
- package/dist/run.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -166,7 +166,7 @@ required.
|
|
|
166
166
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
167
167
|
|
|
168
168
|
```
|
|
169
|
-
conductor 0.
|
|
169
|
+
conductor 0.11.0
|
|
170
170
|
verdict-token: blocked (1)
|
|
171
171
|
conductor run: 2 gate(s), 1 finding(s)
|
|
172
172
|
|
|
@@ -721,7 +721,12 @@ code and the `enforce` flags the run already had.
|
|
|
721
721
|
vulnerabilities already on the base branch, reported and not blocking;
|
|
722
722
|
the report's third line then says `present-on-base: N reported, not
|
|
723
723
|
blocking`, the verdict sentence says the same, and the Action copies that
|
|
724
|
-
line to the job summary under the token.
|
|
724
|
+
line to the job summary under the token. When the intent gate's spec was
|
|
725
|
+
chosen weakly, differently than before 0.11.0, or not at all because of a
|
|
726
|
+
tie or a branch 0.10.0 bound, the line after the token (after the
|
|
727
|
+
present-on-base line, when there is one) is one of four fixed
|
|
728
|
+
`intent-spec:` lines naming no branch or file, and the Action copies that
|
|
729
|
+
one too.
|
|
725
730
|
- `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
|
|
726
731
|
all (none is enabled, or every enabled one was deferred to a later stage,
|
|
727
732
|
had nothing to judge, or was skipped), or every gate that ran examined
|
|
@@ -1180,12 +1185,24 @@ itself and needs an administrator to merge it.
|
|
|
1180
1185
|
token is exact and lowercase, a frozen contract at rule 2 still wins over
|
|
1181
1186
|
it, and `--spec` at rule 1 still overrides it.
|
|
1182
1187
|
4. A markdown file **directly under** `docs/superpowers/specs` whose name
|
|
1183
|
-
|
|
1184
|
-
segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1185
|
-
`YYYY-MM-DD-` prefix and a trailing `-design
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1188
|
+
matches the branch on **whole words**. The branch slug is the branch name
|
|
1189
|
+
with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1190
|
+
stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
|
|
1191
|
+
ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
|
|
1192
|
+
spaces. A spec is a candidate when one name's words appear, in order and
|
|
1193
|
+
together, inside the other's, and at least one shared word is three or
|
|
1194
|
+
more characters, contains a letter, and is not a common branch word
|
|
1195
|
+
(`fix`, `feat`, `wip`, `docs`, and the rest of the list in
|
|
1196
|
+
`src/intent-spec.ts`). Candidates are ranked by an equal name first, then
|
|
1197
|
+
the most shared words, then the longest shared word, then the lexically
|
|
1198
|
+
greatest filename among files with the same name (the newest date when
|
|
1199
|
+
every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
|
|
1200
|
+
Two different specs that tie are **not** guessed between: the gate is
|
|
1201
|
+
skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
|
|
1202
|
+
one shared word, or on word length alone, is used and the report says the
|
|
1203
|
+
match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
|
|
1204
|
+
the choice matters, say it: a `Spec:` line in the pull request body, or a
|
|
1205
|
+
branch named after the spec.
|
|
1189
1206
|
|
|
1190
1207
|
**A branch with neither** is a third state beside deferred and could-not-run:
|
|
1191
1208
|
the gate is switched on, it ran, and it had nothing to check. It gets one
|
|
@@ -1197,7 +1214,9 @@ repository. A waived pull request lands in the same state and is reported
|
|
|
1197
1214
|
under its own `intent-guard/contract-waived` id, with its own wording on the
|
|
1198
1215
|
skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
1199
1216
|
reader can tell "nobody has written one" from "somebody decided against one"
|
|
1200
|
-
wherever they meet it.
|
|
1217
|
+
wherever they meet it. An ambiguous branch, one two specs match equally,
|
|
1218
|
+
lands in the same advisory state under its own `intent-guard/spec-ambiguous`
|
|
1219
|
+
id, and never reaches the exit code either.
|
|
1201
1220
|
|
|
1202
1221
|
**A repository with no contract yet is not a repository this gate can act
|
|
1203
1222
|
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
@@ -1222,7 +1241,8 @@ gate does not run at all on that pull request, and budget breaches are the
|
|
|
1222
1241
|
thing this gate blocks on. The one thing a waiver cannot override is a frozen
|
|
1223
1242
|
native contract, under either of the two paths above, which is checked first:
|
|
1224
1243
|
a repository that wants the gate to be non-waivable freezes a native contract
|
|
1225
|
-
and keeps it committed.
|
|
1244
|
+
and keeps it committed. The branch-name convention is not a control either:
|
|
1245
|
+
whoever names the branch chooses among the base's specs.
|
|
1226
1246
|
|
|
1227
1247
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
1228
1248
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
@@ -1358,7 +1378,7 @@ request being judged, and the version-pin protection described above
|
|
|
1358
1378
|
"protects nothing" against a tree that controls its own judge (the
|
|
1359
1379
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1360
1380
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1361
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1381
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.11.0.
|
|
1362
1382
|
|
|
1363
1383
|
```yaml
|
|
1364
1384
|
name: guardrails
|
|
@@ -1380,7 +1400,7 @@ jobs:
|
|
|
1380
1400
|
with:
|
|
1381
1401
|
node-version: '22.11.0'
|
|
1382
1402
|
- id: conductor
|
|
1383
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1403
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1384
1404
|
with:
|
|
1385
1405
|
output: conductor.sarif
|
|
1386
1406
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1455,7 +1475,7 @@ jobs:
|
|
|
1455
1475
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1456
1476
|
# umbrella is the default in the pinned action.yml.
|
|
1457
1477
|
- id: conductor
|
|
1458
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1478
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1459
1479
|
with:
|
|
1460
1480
|
output: conductor.sarif
|
|
1461
1481
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1466,9 +1486,9 @@ jobs:
|
|
|
1466
1486
|
# request of their own. On a pull request the action refuses a pin
|
|
1467
1487
|
# below what the pinned action.yml ships, and the three lines can
|
|
1468
1488
|
# be left out entirely to take that action's own versions.
|
|
1469
|
-
dep-guard-version: 0.
|
|
1489
|
+
dep-guard-version: 0.14.0
|
|
1470
1490
|
vault-guard-version: 1.11.0
|
|
1471
|
-
intent-guard-version: 1.
|
|
1491
|
+
intent-guard-version: 1.10.0
|
|
1472
1492
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1473
1493
|
# Always: the log is most worth having on the run that failed.
|
|
1474
1494
|
if: always()
|
|
@@ -1661,7 +1681,7 @@ jobs:
|
|
|
1661
1681
|
node-version: '22.11.0'
|
|
1662
1682
|
- id: conductor
|
|
1663
1683
|
timeout-minutes: 5
|
|
1664
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1684
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1665
1685
|
with:
|
|
1666
1686
|
pr-comment: true
|
|
1667
1687
|
advisory: true
|
|
@@ -1797,7 +1817,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1797
1817
|
# the pull request runs before the action in this job: no install, build
|
|
1798
1818
|
# or test step here; those belong in a separate job. ...
|
|
1799
1819
|
- id: conductor
|
|
1800
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1820
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1801
1821
|
with:
|
|
1802
1822
|
output: conductor.sarif
|
|
1803
1823
|
pr-comment: true
|
|
@@ -1876,12 +1896,12 @@ per pull request.
|
|
|
1876
1896
|
|
|
1877
1897
|
```yaml
|
|
1878
1898
|
- id: conductor-package-a
|
|
1879
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1899
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1880
1900
|
with:
|
|
1881
1901
|
pr-comment: true
|
|
1882
1902
|
pr-comment-marker: 'package-a'
|
|
1883
1903
|
- id: conductor-package-b
|
|
1884
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1904
|
+
uses: vaultcompasshq/conductor@v0.11.0
|
|
1885
1905
|
with:
|
|
1886
1906
|
pr-comment: true
|
|
1887
1907
|
pr-comment-marker: 'package-b'
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { ConventionMatch, SelectionMiss } from './intent-spec.js';
|
|
1
2
|
import type { ResolvedBinary } from './resolve.js';
|
|
2
3
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
3
4
|
export declare const TEMP_PREFIX = "conductor-intent-";
|
|
@@ -51,9 +52,32 @@ export type ContractSource =
|
|
|
51
52
|
spec: string;
|
|
52
53
|
plan: string | null;
|
|
53
54
|
ref?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Set only when the branch-name convention chose the spec. Its presence
|
|
57
|
+
* is how every renderer knows the branch name chose it; nothing
|
|
58
|
+
* recomputes that from the policy or the path.
|
|
59
|
+
*/
|
|
60
|
+
match?: ReportedMatch;
|
|
54
61
|
} | {
|
|
55
62
|
kind: 'none';
|
|
56
63
|
};
|
|
64
|
+
/**
|
|
65
|
+
* A convention match as the report carries it: how the spec was chosen, plus
|
|
66
|
+
* which remedy the weak-match line names. `pr-body` on a run with a pull
|
|
67
|
+
* request event (a "Spec:" line), `spec-flag` locally (--spec).
|
|
68
|
+
*/
|
|
69
|
+
export type ReportedMatch = ConventionMatch & {
|
|
70
|
+
remedy: 'pr-body' | 'spec-flag';
|
|
71
|
+
};
|
|
72
|
+
/** How many tied specs a report sentence names before "and N more". */
|
|
73
|
+
export declare const TIED_SHOWN = 5;
|
|
74
|
+
/**
|
|
75
|
+
* The legacy clause for a branch 0.10.0 bound and this release does not.
|
|
76
|
+
* Reporting only, for one minor release.
|
|
77
|
+
*/
|
|
78
|
+
export declare function legacyNoneSentence(legacy: string): string;
|
|
79
|
+
/** The legacy clause for a branch whose chosen spec changed this release. */
|
|
80
|
+
export declare function legacyChangedSentence(legacy: string): string;
|
|
57
81
|
export interface IntentPreparation {
|
|
58
82
|
contractSource: ContractSource;
|
|
59
83
|
/** The ref the change set was measured against, or null for a staged run. */
|
|
@@ -112,10 +136,18 @@ export type IntentPrepareResult = {
|
|
|
112
136
|
*/
|
|
113
137
|
| {
|
|
114
138
|
kind: 'skip';
|
|
115
|
-
|
|
139
|
+
/**
|
|
140
|
+
* `spec-ambiguous`: two or more specs matched the branch name equally,
|
|
141
|
+
* so none was chosen. Its own reason because its remedy differs (a
|
|
142
|
+
* spec exists; choose one) and because a tie that 0.10.0 silently
|
|
143
|
+
* broke must not file itself under "nobody wrote one".
|
|
144
|
+
*/
|
|
145
|
+
reason: 'no-contract' | 'contract-waived' | 'spec-ambiguous';
|
|
116
146
|
detail: string;
|
|
117
147
|
/** As on IntentPreparation: what this pull request proposes. */
|
|
118
148
|
proposals?: string[];
|
|
149
|
+
/** What the branch-name convention said, for the details bag. */
|
|
150
|
+
selection?: SelectionMiss;
|
|
119
151
|
} | {
|
|
120
152
|
kind: 'failed';
|
|
121
153
|
step: PrepareStep;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -37,7 +37,7 @@ import { parse as parseYaml } from 'yaml';
|
|
|
37
37
|
import { gitComplaint, runGit } from './git.js';
|
|
38
38
|
import { changedPathsSince, currentBranch, orderForPathsFlag, pathsFlagRefusal, resolveBaseRefInRepo, } from './intent-base.js';
|
|
39
39
|
import { summariseStderr } from './normalize.js';
|
|
40
|
-
import { PLAN_DIR, SPEC_DIR, SPEC_WAIVER_TOKEN,
|
|
40
|
+
import { PLAN_DIR, SPEC_DIR, SPEC_WAIVER_TOKEN, discoverSpec, matchOf, normalizeStem, prBodyFromEvent, selectByBranch, specFromPrBody, } from './intent-spec.js';
|
|
41
41
|
import { readFileAtRef, unreadableBaseRemedy } from './trust-base.js';
|
|
42
42
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
43
43
|
export const TEMP_PREFIX = 'conductor-intent-';
|
|
@@ -80,6 +80,82 @@ export const NATIVE_CONTRACT_PATHS = [
|
|
|
80
80
|
export function isLegacyContractPath(contractPath) {
|
|
81
81
|
return contractPath === LEGACY_NATIVE_CONTRACT_PATH;
|
|
82
82
|
}
|
|
83
|
+
/** How many tied specs a report sentence names before "and N more". */
|
|
84
|
+
export const TIED_SHOWN = 5;
|
|
85
|
+
/** The tied specs, as repository paths, capped for a report sentence. */
|
|
86
|
+
function tiedList(tied) {
|
|
87
|
+
const shown = tied.slice(0, TIED_SHOWN).map((name) => `${SPEC_DIR}/${name}`);
|
|
88
|
+
const more = tied.length - shown.length;
|
|
89
|
+
return more > 0 ? `${shown.join(', ')}, and ${more} more` : shown.join(', ');
|
|
90
|
+
}
|
|
91
|
+
/** The skip detail when two or more specs match the branch equally (5.2). */
|
|
92
|
+
function ambiguousDetail(branch, tied, ref) {
|
|
93
|
+
return (`No spec was chosen: the branch name "${branch}" matches ${tied.length} specs equally` +
|
|
94
|
+
`${ref === undefined ? '' : ` on "${ref}"`} (${tiedList(tied)}), and conductor does not ` +
|
|
95
|
+
'guess between them. Add a "Spec: <path>" line to the pull request body or pass --spec, ' +
|
|
96
|
+
"or rename the branch to one spec's name.");
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* The legacy clause for a branch 0.10.0 bound and this release does not.
|
|
100
|
+
* Reporting only, for one minor release.
|
|
101
|
+
*/
|
|
102
|
+
export function legacyNoneSentence(legacy) {
|
|
103
|
+
return (`Before conductor 0.11.0 this branch name chose ${SPEC_DIR}/${legacy} by a partial-word ` +
|
|
104
|
+
'match; it no longer does.');
|
|
105
|
+
}
|
|
106
|
+
/** The legacy clause for a branch whose chosen spec changed this release. */
|
|
107
|
+
export function legacyChangedSentence(legacy) {
|
|
108
|
+
return (`Before conductor 0.11.0 this branch name chose ${SPEC_DIR}/${legacy}; it now chooses this ` +
|
|
109
|
+
'spec, which matches it on whole words.');
|
|
110
|
+
}
|
|
111
|
+
/** The sentences a no-contract skip gains from the convention's answer. */
|
|
112
|
+
function selectionSuffix(branch, selection) {
|
|
113
|
+
if (selection === undefined) {
|
|
114
|
+
return '';
|
|
115
|
+
}
|
|
116
|
+
const sentences = [];
|
|
117
|
+
if (selection.why === 'no-usable-token' && branch !== null) {
|
|
118
|
+
sentences.push(`The branch name "${branch}" has no word of three or more letters that is not a common ` +
|
|
119
|
+
'branch word (fix, feat, wip, ...), so it cannot choose a spec.');
|
|
120
|
+
}
|
|
121
|
+
if (selection.legacy !== null) {
|
|
122
|
+
sentences.push(legacyNoneSentence(selection.legacy));
|
|
123
|
+
}
|
|
124
|
+
return sentences.map((sentence) => ` ${sentence}`).join('');
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The selection a skip carries for its details bag, or undefined when it
|
|
128
|
+
* says nothing the ordinary adoption-ramp skip does not: a usable branch name
|
|
129
|
+
* that matched no spec, under either rule, keeps its 0.10.0 shape exactly.
|
|
130
|
+
*/
|
|
131
|
+
function reportedSelection(selection) {
|
|
132
|
+
if (selection === undefined || (selection.why === 'no-candidate' && selection.legacy === null)) {
|
|
133
|
+
return undefined;
|
|
134
|
+
}
|
|
135
|
+
return selection;
|
|
136
|
+
}
|
|
137
|
+
/** The skip for a convention that found nothing, on either path. */
|
|
138
|
+
function noSpecChosen(branch, selection, noContractDetail, proposals, ref) {
|
|
139
|
+
const reported = reportedSelection(selection);
|
|
140
|
+
const withProposals = proposals.length === 0 ? {} : { proposals };
|
|
141
|
+
if (selection !== undefined && selection.why === 'ambiguous' && branch !== null) {
|
|
142
|
+
return {
|
|
143
|
+
kind: 'skip',
|
|
144
|
+
reason: 'spec-ambiguous',
|
|
145
|
+
detail: ambiguousDetail(branch, selection.tied, ref) +
|
|
146
|
+
(selection.legacy === null ? '' : ` ${legacyNoneSentence(selection.legacy)}`),
|
|
147
|
+
selection,
|
|
148
|
+
...withProposals,
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
return {
|
|
152
|
+
kind: 'skip',
|
|
153
|
+
reason: 'no-contract',
|
|
154
|
+
detail: noContractDetail + selectionSuffix(branch, selection),
|
|
155
|
+
...(reported === undefined ? {} : { selection: reported }),
|
|
156
|
+
...withProposals,
|
|
157
|
+
};
|
|
158
|
+
}
|
|
83
159
|
/**
|
|
84
160
|
* Whether a contract on disk has been approved.
|
|
85
161
|
*
|
|
@@ -393,17 +469,21 @@ export function prepareIntent(options) {
|
|
|
393
469
|
else if (discovery.kind === 'none') {
|
|
394
470
|
source = { kind: 'none' };
|
|
395
471
|
}
|
|
472
|
+
else if (discovery.kind === 'convention') {
|
|
473
|
+
source = {
|
|
474
|
+
kind: 'imported',
|
|
475
|
+
spec: discovery.spec,
|
|
476
|
+
plan: discovery.plan,
|
|
477
|
+
match: { ...discovery.match, remedy: eventPath === undefined ? 'spec-flag' : 'pr-body' },
|
|
478
|
+
};
|
|
479
|
+
}
|
|
396
480
|
else {
|
|
397
481
|
source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
|
|
398
482
|
}
|
|
399
483
|
if (source.kind === 'none') {
|
|
400
|
-
return {
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
detail: `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
|
|
404
|
-
`${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
|
|
405
|
-
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
406
|
-
};
|
|
484
|
+
return noSpecChosen(branch, discovery.kind === 'none' ? discovery.selection : undefined, `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
|
|
485
|
+
`${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
|
|
486
|
+
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.', []);
|
|
407
487
|
}
|
|
408
488
|
return finishPreparation(options, source, null, []);
|
|
409
489
|
}
|
|
@@ -785,12 +865,19 @@ function planAtRef(repoRoot, ref, spec) {
|
|
|
785
865
|
* failure, never "no spec".
|
|
786
866
|
*/
|
|
787
867
|
function discoverSpecAtRef(repoRoot, ref, inputs) {
|
|
788
|
-
const found = (spec, specText) => {
|
|
868
|
+
const found = (spec, specText, match) => {
|
|
789
869
|
const plan = planAtRef(repoRoot, ref, spec);
|
|
790
870
|
if (!plan.ok) {
|
|
791
871
|
return { kind: 'failed', detail: plan.detail };
|
|
792
872
|
}
|
|
793
|
-
return {
|
|
873
|
+
return {
|
|
874
|
+
kind: 'found',
|
|
875
|
+
spec,
|
|
876
|
+
specText,
|
|
877
|
+
plan: plan.plan,
|
|
878
|
+
planText: plan.planText,
|
|
879
|
+
...(match === undefined ? {} : { match }),
|
|
880
|
+
};
|
|
794
881
|
};
|
|
795
882
|
if (inputs.spec !== undefined) {
|
|
796
883
|
const relative = toRepoRelative(repoRoot, inputs.spec);
|
|
@@ -837,18 +924,25 @@ function discoverSpecAtRef(repoRoot, ref, inputs) {
|
|
|
837
924
|
if (!listed.ok) {
|
|
838
925
|
return { kind: 'failed', detail: listed.detail };
|
|
839
926
|
}
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
927
|
+
// The same selector as the working tree, over the names listed AT THE
|
|
928
|
+
// BASE: a head branch name only ever chooses among the base's specs.
|
|
929
|
+
const selection = selectByBranch(listed.names, inputs.branch);
|
|
930
|
+
if (selection.kind === 'none') {
|
|
931
|
+
return {
|
|
932
|
+
kind: 'none',
|
|
933
|
+
flagOnHead: null,
|
|
934
|
+
selection: { why: selection.why, tied: selection.tied, legacy: selection.legacy },
|
|
935
|
+
};
|
|
936
|
+
}
|
|
937
|
+
const relative = `${SPEC_DIR}/${selection.name}`;
|
|
938
|
+
const read = readFileAtRef(repoRoot, ref, relative);
|
|
939
|
+
if (read.kind !== 'file') {
|
|
940
|
+
return {
|
|
941
|
+
kind: 'failed',
|
|
942
|
+
detail: read.kind === 'error' ? read.detail : `${relative} was listed at "${ref}" but not found`,
|
|
943
|
+
};
|
|
851
944
|
}
|
|
945
|
+
return found(relative, read.text, matchOf(selection));
|
|
852
946
|
}
|
|
853
947
|
return { kind: 'none', flagOnHead: null };
|
|
854
948
|
}
|
|
@@ -943,7 +1037,22 @@ function prepareAgainstTrustBase(options, trustBase) {
|
|
|
943
1037
|
files.push({ path: atBase.plan, baseText: atBase.planText });
|
|
944
1038
|
}
|
|
945
1039
|
proposals.push(...importedFileProposals(repoRoot, trustBase, files));
|
|
946
|
-
return finishPreparation(options, {
|
|
1040
|
+
return finishPreparation(options, {
|
|
1041
|
+
kind: 'imported',
|
|
1042
|
+
spec: atBase.spec,
|
|
1043
|
+
plan: atBase.plan,
|
|
1044
|
+
ref: trustBase,
|
|
1045
|
+
...(atBase.match === undefined
|
|
1046
|
+
? {}
|
|
1047
|
+
: { match: { ...atBase.match, remedy: eventPath === undefined ? 'spec-flag' : 'pr-body' } }),
|
|
1048
|
+
}, { ref: trustBase, specText: atBase.specText, planText: atBase.planText }, proposals);
|
|
1049
|
+
}
|
|
1050
|
+
// The base carries SEVERAL specs the branch name matches equally. Saying
|
|
1051
|
+
// the base has no spec for the branch would be false, so this returns
|
|
1052
|
+
// before the head-spec proposal below: no spec is proposed when the base
|
|
1053
|
+
// already has candidates. The proposals already collected are kept.
|
|
1054
|
+
if (atBase.selection?.why === 'ambiguous') {
|
|
1055
|
+
return noSpecChosen(branch, atBase.selection, '', proposals, trustBase);
|
|
947
1056
|
}
|
|
948
1057
|
// Nothing on the base. A spec the head carries is a proposal, and a --spec
|
|
949
1058
|
// that names a file neither side has is still reported as missing.
|
|
@@ -969,15 +1078,10 @@ function prepareAgainstTrustBase(options, trustBase) {
|
|
|
969
1078
|
proposals.push(`${headSpec} is a spec in this pull request but not on "${trustBase}": it is a proposal, ` +
|
|
970
1079
|
'and pull requests are judged against it once it is on the base branch.');
|
|
971
1080
|
}
|
|
972
|
-
return {
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
'intent contract comes from the base ref only, so nothing in this pull request can ' +
|
|
979
|
-
'become it; once a contract or spec is on the base branch, the next pull request is ' +
|
|
980
|
-
'judged against it.',
|
|
981
|
-
...(proposals.length === 0 ? {} : { proposals }),
|
|
982
|
-
};
|
|
1081
|
+
return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" carries no frozen ` +
|
|
1082
|
+
`${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
|
|
1083
|
+
`${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
|
|
1084
|
+
'intent contract comes from the base ref only, so nothing in this pull request can ' +
|
|
1085
|
+
'become it; once a contract or spec is on the base branch, the next pull request is ' +
|
|
1086
|
+
'judged against it.', proposals, trustBase);
|
|
983
1087
|
}
|
package/dist/intent-spec.d.ts
CHANGED
|
@@ -3,10 +3,17 @@ export declare const PLAN_DIR = "docs/superpowers/plans";
|
|
|
3
3
|
export type SpecDiscovery =
|
|
4
4
|
/** Found, with the source that won. Paths are repository-relative. */
|
|
5
5
|
{
|
|
6
|
-
kind: 'flag' | 'pr-body'
|
|
6
|
+
kind: 'flag' | 'pr-body';
|
|
7
7
|
spec: string;
|
|
8
8
|
plan: string | null;
|
|
9
9
|
}
|
|
10
|
+
/** Found by the branch-name convention, with how it was chosen. */
|
|
11
|
+
| {
|
|
12
|
+
kind: 'convention';
|
|
13
|
+
spec: string;
|
|
14
|
+
plan: string | null;
|
|
15
|
+
match: ConventionMatch;
|
|
16
|
+
}
|
|
10
17
|
/** `--spec` named a file that is not there. Never silently replaced. */
|
|
11
18
|
| {
|
|
12
19
|
kind: 'missing-flag';
|
|
@@ -25,8 +32,11 @@ export type SpecDiscovery =
|
|
|
25
32
|
| {
|
|
26
33
|
kind: 'escaped';
|
|
27
34
|
path: string;
|
|
28
|
-
}
|
|
35
|
+
}
|
|
36
|
+
/** Nothing found. `selection` is present when a branch was available. */
|
|
37
|
+
| {
|
|
29
38
|
kind: 'none';
|
|
39
|
+
selection?: SelectionMiss;
|
|
30
40
|
};
|
|
31
41
|
/**
|
|
32
42
|
* The token that turns a `Spec:` line into a waiver.
|
|
@@ -64,8 +74,98 @@ export declare function branchSlug(branch: string): string;
|
|
|
64
74
|
* importer pairs them.
|
|
65
75
|
*/
|
|
66
76
|
export declare function normalizeStem(fileName: string): string;
|
|
67
|
-
/**
|
|
68
|
-
|
|
77
|
+
/**
|
|
78
|
+
* The shortest token that can be evidence for a binding.
|
|
79
|
+
*
|
|
80
|
+
* Two-letter tokens (pr, ci, ui, db, v2) are the shape of the dogfood failure
|
|
81
|
+
* this rule exists to close, and they recur across unrelated work. Three
|
|
82
|
+
* keeps the short domain words a team actually names features after (api,
|
|
83
|
+
* cli, osv).
|
|
84
|
+
*/
|
|
85
|
+
export declare const MIN_TOKEN_LENGTH = 3;
|
|
86
|
+
/**
|
|
87
|
+
* Words that appear in branch and spec names because of the naming
|
|
88
|
+
* convention, not because of the feature. Closed and pinned exactly by a
|
|
89
|
+
* test. A stop word is ignored as EVIDENCE, never deleted from a sequence: it
|
|
90
|
+
* still occupies its position for the contiguity test.
|
|
91
|
+
*/
|
|
92
|
+
export declare const STOP_WORDS: readonly string[];
|
|
93
|
+
/**
|
|
94
|
+
* A branch slug or a spec stem as a sequence of whole words.
|
|
95
|
+
*
|
|
96
|
+
* ASCII letters only are folded, never toLowerCase(): that maps U+212A
|
|
97
|
+
* KELVIN SIGN to an ASCII k, so a branch spelled with one would fold into an
|
|
98
|
+
* ASCII word and could bind a spec. The delimiters are ASCII only for the
|
|
99
|
+
* same reason, never \s, which also matches Unicode whitespace git allows in
|
|
100
|
+
* a ref name (U+00A0 and the rest). A non-ASCII character therefore survives
|
|
101
|
+
* unchanged inside its token, and the charset rule in isSignificant keeps
|
|
102
|
+
* that token from ever counting. A dot is not a delimiter: 1.2.1 is one token.
|
|
103
|
+
*/
|
|
104
|
+
export declare function tokens(text: string): string[];
|
|
105
|
+
/**
|
|
106
|
+
* Whether a token can be evidence for a binding: three or more characters,
|
|
107
|
+
* letters digits and dots only, at least one letter, and not a stop word.
|
|
108
|
+
* The charset rule is also what keeps every word the report prints as
|
|
109
|
+
* "shared" free of markup, whatever the head branch was called.
|
|
110
|
+
*/
|
|
111
|
+
export declare function isSignificant(token: string): boolean;
|
|
112
|
+
/**
|
|
113
|
+
* Whether a spec stem is a candidate for a branch slug, and on what words.
|
|
114
|
+
*
|
|
115
|
+
* The shorter token sequence must appear as ONE CONTIGUOUS RUN of the longer,
|
|
116
|
+
* compared token by token, in either direction, and that run must hold a
|
|
117
|
+
* significant token. This is the old substring test moved from characters to
|
|
118
|
+
* whole tokens and nothing looser: on tokens(x).join("-") of both sides,
|
|
119
|
+
* every candidate here is one the substring rule also accepts.
|
|
120
|
+
*/
|
|
121
|
+
export declare function candidateRun(slug: string, stem: string): {
|
|
122
|
+
exact: boolean;
|
|
123
|
+
shared: string[];
|
|
124
|
+
} | null;
|
|
125
|
+
/** How a convention selection was made, carried to every report surface. */
|
|
126
|
+
export interface ConventionMatch {
|
|
127
|
+
strength: 'exact' | 'strong' | 'weak';
|
|
128
|
+
weakBecause: Array<'single-token' | 'length-tiebreak'>;
|
|
129
|
+
/** The significant tokens of the shared run, charset-restricted. */
|
|
130
|
+
shared: string[];
|
|
131
|
+
/** The next stem group's member, if any. */
|
|
132
|
+
runnerUp: string | null;
|
|
133
|
+
/** The runner-up's shared significant tokens, for the length-tiebreak wording. */
|
|
134
|
+
runnerUpShared: string[];
|
|
135
|
+
/**
|
|
136
|
+
* What 0.10.0's substring rule would have chosen, when that differs from
|
|
137
|
+
* this choice; null when it is the same file. Reporting only.
|
|
138
|
+
*/
|
|
139
|
+
legacy: string | null;
|
|
140
|
+
}
|
|
141
|
+
/** Why the convention chose nothing, when a branch was available. */
|
|
142
|
+
export interface SelectionMiss {
|
|
143
|
+
why: 'no-usable-token' | 'no-candidate' | 'ambiguous';
|
|
144
|
+
/** Ambiguous only: every tied group's member, sorted lexically, in full. */
|
|
145
|
+
tied: string[];
|
|
146
|
+
/** What 0.10.0's substring rule would have chosen. Reporting only. */
|
|
147
|
+
legacy: string | null;
|
|
148
|
+
}
|
|
149
|
+
export type BranchSelection = ({
|
|
150
|
+
kind: 'selected';
|
|
151
|
+
name: string;
|
|
152
|
+
} & ConventionMatch) | ({
|
|
153
|
+
kind: 'none';
|
|
154
|
+
} & SelectionMiss);
|
|
155
|
+
/**
|
|
156
|
+
* The branch-name convention's choice among `names` (spec filenames), the one
|
|
157
|
+
* function both selection paths call, on the working tree and at the trust
|
|
158
|
+
* base.
|
|
159
|
+
*
|
|
160
|
+
* Candidates are grouped by their folded stem sequence; a group's member is
|
|
161
|
+
* its lexically greatest filename. Groups are ranked by an exact sequence,
|
|
162
|
+
* then the number of significant shared tokens, then the length of the
|
|
163
|
+
* longest one. A tie on all three between the top two groups chooses
|
|
164
|
+
* NOTHING: every key the old code used after the first was a guess about
|
|
165
|
+
* which feature the branch meant, and a tie on everything this measures is
|
|
166
|
+
* the code saying it does not know.
|
|
167
|
+
*/
|
|
168
|
+
export declare function selectByBranch(names: string[], branch: string): BranchSelection;
|
|
69
169
|
/**
|
|
70
170
|
* The path named by a `Spec:` line in a pull request body.
|
|
71
171
|
*
|
|
@@ -82,22 +182,8 @@ export declare function stemMatches(stem: string, slug: string): boolean;
|
|
|
82
182
|
export declare function specFromPrBody(body: string): string | null;
|
|
83
183
|
/** `pull_request.body` out of a GitHub event payload, or null. */
|
|
84
184
|
export declare function prBodyFromEvent(eventPath: string): string | null;
|
|
85
|
-
/**
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
* two are different questions. Ranking on the lexically newest filename alone
|
|
90
|
-
* was answering the second with the first: a loose candidate carrying a later
|
|
91
|
-
* date beat the spec whose stem was the branch slug exactly, and an undated
|
|
92
|
-
* name beat everything because it sorts after every date. A pull request was
|
|
93
|
-
* then measured against a different feature's requirements, with nothing in
|
|
94
|
-
* the report saying so, since naming the spec it used is exactly what the
|
|
95
|
-
* report does.
|
|
96
|
-
*
|
|
97
|
-
* So: an exact stem first, then the most specific stem, and only then the
|
|
98
|
-
* newest name. Specificity is stem LENGTH, which is crude but is the property
|
|
99
|
-
* the failure actually had: "superpowers" beat
|
|
100
|
-
* "1.2.1-base-and-superpowers" by being shorter and vaguer.
|
|
101
|
-
*/
|
|
102
|
-
export declare function bestMatch(names: string[], target: string): string | undefined;
|
|
185
|
+
/** The match record of a selection, without its discriminant and name. */
|
|
186
|
+
export declare function matchOf(selection: Extract<BranchSelection, {
|
|
187
|
+
kind: 'selected';
|
|
188
|
+
}>): ConventionMatch;
|
|
103
189
|
export declare function discoverSpec(options: SpecDiscoveryOptions): SpecDiscovery;
|
package/dist/intent-spec.js
CHANGED
|
@@ -29,9 +29,10 @@
|
|
|
29
29
|
// explicit statement beats the inferred convention below.
|
|
30
30
|
//
|
|
31
31
|
// 3. The convention: a markdown file directly under docs/superpowers/specs
|
|
32
|
-
// whose name
|
|
33
|
-
// that is the layout intent-guard's
|
|
34
|
-
// archive subdirectory is not a candidate
|
|
32
|
+
// whose name matches the branch on WHOLE WORDS (selectByBranch below).
|
|
33
|
+
// Directly under, not nested, because that is the layout intent-guard's
|
|
34
|
+
// own importer discovers and an archive subdirectory is not a candidate
|
|
35
|
+
// for this branch's contract.
|
|
35
36
|
import { readFileSync, readdirSync, realpathSync } from 'node:fs';
|
|
36
37
|
import path from 'node:path';
|
|
37
38
|
export const SPEC_DIR = 'docs/superpowers/specs';
|
|
@@ -69,12 +70,197 @@ export function normalizeStem(fileName) {
|
|
|
69
70
|
const stem = fileName.replace(/\.md$/i, '');
|
|
70
71
|
return stem.replace(/^\d{4}-\d{2}-\d{2}-/, '').replace(/-design$/, '');
|
|
71
72
|
}
|
|
72
|
-
/**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
73
|
+
/**
|
|
74
|
+
* The shortest token that can be evidence for a binding.
|
|
75
|
+
*
|
|
76
|
+
* Two-letter tokens (pr, ci, ui, db, v2) are the shape of the dogfood failure
|
|
77
|
+
* this rule exists to close, and they recur across unrelated work. Three
|
|
78
|
+
* keeps the short domain words a team actually names features after (api,
|
|
79
|
+
* cli, osv).
|
|
80
|
+
*/
|
|
81
|
+
export const MIN_TOKEN_LENGTH = 3;
|
|
82
|
+
/**
|
|
83
|
+
* Words that appear in branch and spec names because of the naming
|
|
84
|
+
* convention, not because of the feature. Closed and pinned exactly by a
|
|
85
|
+
* test. A stop word is ignored as EVIDENCE, never deleted from a sequence: it
|
|
86
|
+
* still occupies its position for the contiguity test.
|
|
87
|
+
*/
|
|
88
|
+
export const STOP_WORDS = Object.freeze([
|
|
89
|
+
// Change-type words
|
|
90
|
+
'feat', 'feature', 'fix', 'bugfix', 'hotfix', 'chore', 'docs',
|
|
91
|
+
'refactor', 'test', 'tests', 'wip', 'release', 'build', 'perf',
|
|
92
|
+
'style', 'revert', 'deps', 'bump',
|
|
93
|
+
// Convention words
|
|
94
|
+
'design', 'spec', 'specs', 'plan', 'draft', 'review', 'followup',
|
|
95
|
+
'temp', 'tmp',
|
|
96
|
+
// Function words
|
|
97
|
+
'and', 'the', 'for', 'with', 'from', 'into', 'onto', 'per', 'via', 'not',
|
|
98
|
+
'add', 'use', 'new', 'more', 'misc',
|
|
99
|
+
]);
|
|
100
|
+
const STOP_WORD_SET = new Set(STOP_WORDS);
|
|
101
|
+
/**
|
|
102
|
+
* A branch slug or a spec stem as a sequence of whole words.
|
|
103
|
+
*
|
|
104
|
+
* ASCII letters only are folded, never toLowerCase(): that maps U+212A
|
|
105
|
+
* KELVIN SIGN to an ASCII k, so a branch spelled with one would fold into an
|
|
106
|
+
* ASCII word and could bind a spec. The delimiters are ASCII only for the
|
|
107
|
+
* same reason, never \s, which also matches Unicode whitespace git allows in
|
|
108
|
+
* a ref name (U+00A0 and the rest). A non-ASCII character therefore survives
|
|
109
|
+
* unchanged inside its token, and the charset rule in isSignificant keeps
|
|
110
|
+
* that token from ever counting. A dot is not a delimiter: 1.2.1 is one token.
|
|
111
|
+
*/
|
|
112
|
+
export function tokens(text) {
|
|
113
|
+
return text
|
|
114
|
+
.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32))
|
|
115
|
+
.split(/[-_/ \t\n\r\f\v]+/)
|
|
116
|
+
.filter((token) => token !== '');
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Whether a token can be evidence for a binding: three or more characters,
|
|
120
|
+
* letters digits and dots only, at least one letter, and not a stop word.
|
|
121
|
+
* The charset rule is also what keeps every word the report prints as
|
|
122
|
+
* "shared" free of markup, whatever the head branch was called.
|
|
123
|
+
*/
|
|
124
|
+
export function isSignificant(token) {
|
|
125
|
+
return (token.length >= MIN_TOKEN_LENGTH &&
|
|
126
|
+
/^[a-z0-9.]+$/.test(token) &&
|
|
127
|
+
/[a-z]/.test(token) &&
|
|
128
|
+
!STOP_WORD_SET.has(token));
|
|
129
|
+
}
|
|
130
|
+
/** Where `needle` sits as one contiguous run of `haystack`, or -1. */
|
|
131
|
+
function runAt(haystack, needle) {
|
|
132
|
+
for (let start = 0; start + needle.length <= haystack.length; start++) {
|
|
133
|
+
if (needle.every((token, offset) => haystack[start + offset] === token)) {
|
|
134
|
+
return start;
|
|
135
|
+
}
|
|
76
136
|
}
|
|
77
|
-
return
|
|
137
|
+
return -1;
|
|
138
|
+
}
|
|
139
|
+
function candidateOnTokens(slug, stem) {
|
|
140
|
+
if (slug.length === 0 || stem.length === 0) {
|
|
141
|
+
return null;
|
|
142
|
+
}
|
|
143
|
+
const [longer, shorter] = slug.length >= stem.length ? [slug, stem] : [stem, slug];
|
|
144
|
+
if (runAt(longer, shorter) === -1) {
|
|
145
|
+
return null;
|
|
146
|
+
}
|
|
147
|
+
const shared = shorter.filter(isSignificant);
|
|
148
|
+
if (shared.length === 0) {
|
|
149
|
+
return null;
|
|
150
|
+
}
|
|
151
|
+
return { exact: slug.length === stem.length, shared };
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Whether a spec stem is a candidate for a branch slug, and on what words.
|
|
155
|
+
*
|
|
156
|
+
* The shorter token sequence must appear as ONE CONTIGUOUS RUN of the longer,
|
|
157
|
+
* compared token by token, in either direction, and that run must hold a
|
|
158
|
+
* significant token. This is the old substring test moved from characters to
|
|
159
|
+
* whole tokens and nothing looser: on tokens(x).join("-") of both sides,
|
|
160
|
+
* every candidate here is one the substring rule also accepts.
|
|
161
|
+
*/
|
|
162
|
+
export function candidateRun(slug, stem) {
|
|
163
|
+
return candidateOnTokens(tokens(slug), tokens(stem));
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* 0.10.0's convention rule, verbatim: a character substring test in either
|
|
167
|
+
* direction, then an exact stem, the longer stem, the lexically greatest
|
|
168
|
+
* filename. Kept for one minor release for the legacy sentence in the report
|
|
169
|
+
* and for nothing else; it never selects.
|
|
170
|
+
*/
|
|
171
|
+
function legacySelection(names, slug) {
|
|
172
|
+
const contains = (stem) => stem !== '' && slug !== '' && (stem.includes(slug) || slug.includes(stem));
|
|
173
|
+
const ranked = names
|
|
174
|
+
.filter((name) => contains(normalizeStem(name)))
|
|
175
|
+
.sort((a, b) => {
|
|
176
|
+
const stemA = normalizeStem(a);
|
|
177
|
+
const stemB = normalizeStem(b);
|
|
178
|
+
const exactA = stemA === slug ? 0 : 1;
|
|
179
|
+
const exactB = stemB === slug ? 0 : 1;
|
|
180
|
+
if (exactA !== exactB) {
|
|
181
|
+
return exactA - exactB;
|
|
182
|
+
}
|
|
183
|
+
if (stemA.length !== stemB.length) {
|
|
184
|
+
return stemB.length - stemA.length;
|
|
185
|
+
}
|
|
186
|
+
return a < b ? 1 : a > b ? -1 : 0;
|
|
187
|
+
});
|
|
188
|
+
return ranked[0] ?? null;
|
|
189
|
+
}
|
|
190
|
+
function compareScore(a, b) {
|
|
191
|
+
if (a.exact !== b.exact) {
|
|
192
|
+
return a.exact ? -1 : 1;
|
|
193
|
+
}
|
|
194
|
+
if (a.shared.length !== b.shared.length) {
|
|
195
|
+
return b.shared.length - a.shared.length;
|
|
196
|
+
}
|
|
197
|
+
return b.longest - a.longest;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* The branch-name convention's choice among `names` (spec filenames), the one
|
|
201
|
+
* function both selection paths call, on the working tree and at the trust
|
|
202
|
+
* base.
|
|
203
|
+
*
|
|
204
|
+
* Candidates are grouped by their folded stem sequence; a group's member is
|
|
205
|
+
* its lexically greatest filename. Groups are ranked by an exact sequence,
|
|
206
|
+
* then the number of significant shared tokens, then the length of the
|
|
207
|
+
* longest one. A tie on all three between the top two groups chooses
|
|
208
|
+
* NOTHING: every key the old code used after the first was a guess about
|
|
209
|
+
* which feature the branch meant, and a tie on everything this measures is
|
|
210
|
+
* the code saying it does not know.
|
|
211
|
+
*/
|
|
212
|
+
export function selectByBranch(names, branch) {
|
|
213
|
+
const rawSlug = branchSlug(branch);
|
|
214
|
+
const slug = tokens(rawSlug);
|
|
215
|
+
const oldAnswer = legacySelection(names, rawSlug);
|
|
216
|
+
if (!slug.some(isSignificant)) {
|
|
217
|
+
return { kind: 'none', why: 'no-usable-token', tied: [], legacy: oldAnswer };
|
|
218
|
+
}
|
|
219
|
+
const groups = new Map();
|
|
220
|
+
for (const name of [...names].sort()) {
|
|
221
|
+
const stem = tokens(normalizeStem(name));
|
|
222
|
+
const run = candidateOnTokens(slug, stem);
|
|
223
|
+
if (run === null) {
|
|
224
|
+
continue;
|
|
225
|
+
}
|
|
226
|
+
// Sorted ascending, so a later name in the same group replaces an
|
|
227
|
+
// earlier one: the member is the lexically greatest filename.
|
|
228
|
+
groups.set(JSON.stringify(stem), {
|
|
229
|
+
member: name,
|
|
230
|
+
exact: run.exact,
|
|
231
|
+
shared: run.shared,
|
|
232
|
+
longest: Math.max(...run.shared.map((token) => token.length)),
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
const ranked = [...groups.values()].sort((a, b) => compareScore(a, b) || (a.member < b.member ? -1 : a.member > b.member ? 1 : 0));
|
|
236
|
+
const top = ranked[0];
|
|
237
|
+
if (top === undefined) {
|
|
238
|
+
return { kind: 'none', why: 'no-candidate', tied: [], legacy: oldAnswer };
|
|
239
|
+
}
|
|
240
|
+
const second = ranked[1];
|
|
241
|
+
if (second !== undefined && compareScore(top, second) === 0) {
|
|
242
|
+
const tied = ranked.filter((group) => compareScore(top, group) === 0).map((group) => group.member);
|
|
243
|
+
return { kind: 'none', why: 'ambiguous', tied: tied.sort(), legacy: oldAnswer };
|
|
244
|
+
}
|
|
245
|
+
const weakBecause = [];
|
|
246
|
+
if (!top.exact) {
|
|
247
|
+
if (top.shared.length === 1) {
|
|
248
|
+
weakBecause.push('single-token');
|
|
249
|
+
}
|
|
250
|
+
if (second !== undefined && second.exact === top.exact && second.shared.length === top.shared.length) {
|
|
251
|
+
weakBecause.push('length-tiebreak');
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
return {
|
|
255
|
+
kind: 'selected',
|
|
256
|
+
name: top.member,
|
|
257
|
+
strength: top.exact ? 'exact' : weakBecause.length > 0 ? 'weak' : 'strong',
|
|
258
|
+
weakBecause,
|
|
259
|
+
shared: top.shared,
|
|
260
|
+
runnerUp: second?.member ?? null,
|
|
261
|
+
runnerUpShared: second?.shared ?? [],
|
|
262
|
+
legacy: oldAnswer === top.member ? null : oldAnswer,
|
|
263
|
+
};
|
|
78
264
|
}
|
|
79
265
|
/**
|
|
80
266
|
* The path named by a `Spec:` line in a pull request body.
|
|
@@ -137,43 +323,6 @@ function exists(repoRoot, relative) {
|
|
|
137
323
|
return false;
|
|
138
324
|
}
|
|
139
325
|
}
|
|
140
|
-
/**
|
|
141
|
-
* The best of the candidates whose stem relates to `target`, or undefined.
|
|
142
|
-
*
|
|
143
|
-
* `stemMatches` decides who is a CANDIDATE; this decides who wins, and the
|
|
144
|
-
* two are different questions. Ranking on the lexically newest filename alone
|
|
145
|
-
* was answering the second with the first: a loose candidate carrying a later
|
|
146
|
-
* date beat the spec whose stem was the branch slug exactly, and an undated
|
|
147
|
-
* name beat everything because it sorts after every date. A pull request was
|
|
148
|
-
* then measured against a different feature's requirements, with nothing in
|
|
149
|
-
* the report saying so, since naming the spec it used is exactly what the
|
|
150
|
-
* report does.
|
|
151
|
-
*
|
|
152
|
-
* So: an exact stem first, then the most specific stem, and only then the
|
|
153
|
-
* newest name. Specificity is stem LENGTH, which is crude but is the property
|
|
154
|
-
* the failure actually had: "superpowers" beat
|
|
155
|
-
* "1.2.1-base-and-superpowers" by being shorter and vaguer.
|
|
156
|
-
*/
|
|
157
|
-
export function bestMatch(names, target) {
|
|
158
|
-
return names
|
|
159
|
-
.filter((name) => stemMatches(normalizeStem(name), target))
|
|
160
|
-
.sort((a, b) => {
|
|
161
|
-
const stemA = normalizeStem(a);
|
|
162
|
-
const stemB = normalizeStem(b);
|
|
163
|
-
const exactA = stemA === target ? 0 : 1;
|
|
164
|
-
const exactB = stemB === target ? 0 : 1;
|
|
165
|
-
if (exactA !== exactB) {
|
|
166
|
-
return exactA - exactB;
|
|
167
|
-
}
|
|
168
|
-
if (stemA.length !== stemB.length) {
|
|
169
|
-
return stemB.length - stemA.length;
|
|
170
|
-
}
|
|
171
|
-
// Newest name last in lexical order, so descending puts it first. The
|
|
172
|
-
// names carry an ISO date prefix, so this is date order among equally
|
|
173
|
-
// good candidates and nothing more.
|
|
174
|
-
return a < b ? 1 : a > b ? -1 : 0;
|
|
175
|
-
})[0];
|
|
176
|
-
}
|
|
177
326
|
/**
|
|
178
327
|
* The plan belonging to a spec.
|
|
179
328
|
*
|
|
@@ -205,6 +354,24 @@ function withPlan(repoRoot, kind, spec) {
|
|
|
205
354
|
const found = planFor(repoRoot, spec);
|
|
206
355
|
return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
|
|
207
356
|
}
|
|
357
|
+
/** The same, for a convention spec, which carries how it was chosen. */
|
|
358
|
+
function conventionWithPlan(repoRoot, spec, match) {
|
|
359
|
+
const found = planFor(repoRoot, spec);
|
|
360
|
+
return 'escaped' in found
|
|
361
|
+
? { kind: 'escaped', path: found.escaped }
|
|
362
|
+
: { kind: 'convention', spec, plan: found.plan, match };
|
|
363
|
+
}
|
|
364
|
+
/** The match record of a selection, without its discriminant and name. */
|
|
365
|
+
export function matchOf(selection) {
|
|
366
|
+
return {
|
|
367
|
+
strength: selection.strength,
|
|
368
|
+
weakBecause: selection.weakBecause,
|
|
369
|
+
shared: selection.shared,
|
|
370
|
+
runnerUp: selection.runnerUp,
|
|
371
|
+
runnerUpShared: selection.runnerUpShared,
|
|
372
|
+
legacy: selection.legacy,
|
|
373
|
+
};
|
|
374
|
+
}
|
|
208
375
|
/** Normalizes a user-supplied path to a repository-relative one. */
|
|
209
376
|
function relativeToRoot(repoRoot, candidate) {
|
|
210
377
|
const relative = path.isAbsolute(candidate)
|
|
@@ -290,17 +457,21 @@ export function discoverSpec(options) {
|
|
|
290
457
|
}
|
|
291
458
|
}
|
|
292
459
|
if (options.branch !== undefined) {
|
|
293
|
-
const
|
|
294
|
-
if (
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
460
|
+
const selection = selectByBranch(markdownFilesIn(repoRoot, SPEC_DIR), options.branch);
|
|
461
|
+
if (selection.kind === 'none') {
|
|
462
|
+
return {
|
|
463
|
+
kind: 'none',
|
|
464
|
+
selection: { why: selection.why, tied: selection.tied, legacy: selection.legacy },
|
|
465
|
+
};
|
|
466
|
+
}
|
|
467
|
+
const relative = `${SPEC_DIR}/${selection.name}`;
|
|
468
|
+
// The convention spec is held to the repository too: a specs directory
|
|
469
|
+
// linked out of the checkout is refused, never imported. Only --spec is
|
|
470
|
+
// exempt, as a path a person typed.
|
|
471
|
+
if (!resolvesInsideRoot(repoRoot, relative)) {
|
|
472
|
+
return { kind: 'escaped', path: relative };
|
|
303
473
|
}
|
|
474
|
+
return conventionWithPlan(repoRoot, relative, matchOf(selection));
|
|
304
475
|
}
|
|
305
476
|
return { kind: 'none' };
|
|
306
477
|
}
|
package/dist/output-sarif.js
CHANGED
|
@@ -582,9 +582,54 @@ function skippedNotifications(result) {
|
|
|
582
582
|
// body on purpose, so it is a notification and never a result.
|
|
583
583
|
id: `${gate.product}/${gate.reason}`,
|
|
584
584
|
message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
|
|
585
|
-
details: {
|
|
585
|
+
details: {
|
|
586
|
+
role: gate.role,
|
|
587
|
+
product: gate.product,
|
|
588
|
+
reason: gate.reason,
|
|
589
|
+
// The full tied list here; the message caps it for reading.
|
|
590
|
+
...(gate.selection?.why === 'ambiguous'
|
|
591
|
+
? { tied: gate.selection.tied, tiedCount: gate.selection.tied.length }
|
|
592
|
+
: {}),
|
|
593
|
+
...(gate.selection === undefined || gate.selection.legacy === null
|
|
594
|
+
? {}
|
|
595
|
+
: { legacySelection: gate.selection.legacy }),
|
|
596
|
+
},
|
|
586
597
|
}));
|
|
587
598
|
}
|
|
599
|
+
/**
|
|
600
|
+
* A spec the branch-name convention chose on thin evidence, as a NOTE.
|
|
601
|
+
*
|
|
602
|
+
* A notification by the rule above: it says how much this run's verdict can
|
|
603
|
+
* be trusted to be about the right contract, which is a statement about the
|
|
604
|
+
* run's coverage, true on every run of this branch until somebody pins the
|
|
605
|
+
* spec. The verdict and enforcement are unchanged by it.
|
|
606
|
+
*/
|
|
607
|
+
function weakMatchNotifications(result) {
|
|
608
|
+
return result.gates.flatMap((gate) => {
|
|
609
|
+
const source = gate.intent?.contractSource;
|
|
610
|
+
if (source === undefined || source.kind !== 'imported' || source.match?.strength !== 'weak') {
|
|
611
|
+
return [];
|
|
612
|
+
}
|
|
613
|
+
const match = source.match;
|
|
614
|
+
return [
|
|
615
|
+
{
|
|
616
|
+
id: `${gate.product}/spec-weak-match`,
|
|
617
|
+
message: `The ${gate.role} gate (${gate.product}) used ${source.spec}, chosen by the branch name on ` +
|
|
618
|
+
`a weak match (${match.weakBecause.join(', ')}). Name the spec with a "Spec: <path>" line ` +
|
|
619
|
+
'or --spec, or rename the branch to the spec name, to be sure it is the right contract.',
|
|
620
|
+
details: {
|
|
621
|
+
role: gate.role,
|
|
622
|
+
product: gate.product,
|
|
623
|
+
spec: source.spec,
|
|
624
|
+
shared: match.shared,
|
|
625
|
+
weakBecause: match.weakBecause,
|
|
626
|
+
runnerUp: match.runnerUp,
|
|
627
|
+
...(match.legacy === null ? {} : { legacySelection: match.legacy }),
|
|
628
|
+
},
|
|
629
|
+
},
|
|
630
|
+
];
|
|
631
|
+
});
|
|
632
|
+
}
|
|
588
633
|
/**
|
|
589
634
|
* intent-guard 1.7.0's own advance-notice warnings, as notifications.
|
|
590
635
|
*
|
|
@@ -917,6 +962,13 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
917
962
|
...(gate.intent === undefined
|
|
918
963
|
? {}
|
|
919
964
|
: { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
|
|
965
|
+
// What 0.10.0 would have chosen, when the branch-name convention now
|
|
966
|
+
// chooses a different spec. Reporting only, for one minor release.
|
|
967
|
+
...(gate.intent?.contractSource.kind === 'imported' &&
|
|
968
|
+
gate.intent.contractSource.match !== undefined &&
|
|
969
|
+
gate.intent.contractSource.match.legacy !== null
|
|
970
|
+
? { legacySelection: gate.intent.contractSource.match.legacy }
|
|
971
|
+
: {}),
|
|
920
972
|
// The gate's own run facts (issue #72: the lockfiles the umbrella
|
|
921
973
|
// handed osv-scanner, and dep-guard's online-lookup reporting), the
|
|
922
974
|
// same bag the text report renders as scalars. Carried verbatim and
|
|
@@ -945,6 +997,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
945
997
|
...skippedNotifications(result),
|
|
946
998
|
...unenforcedNotifications(result),
|
|
947
999
|
...legacyStateDirNotifications(result),
|
|
1000
|
+
...weakMatchNotifications(result),
|
|
948
1001
|
...trustBaseRefusedNotifications(result),
|
|
949
1002
|
...programRefusedNotifications(result),
|
|
950
1003
|
...proposalNotifications(result),
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { type GateOutcome } from './gate-runner.js';
|
|
2
|
+
import type { ReportedMatch } from './intent-prepare.js';
|
|
1
3
|
import type { RunResult } from './run.js';
|
|
2
4
|
/**
|
|
3
5
|
* How many entries a section prints before it rolls the rest up into one
|
|
@@ -8,6 +10,8 @@ import type { RunResult } from './run.js';
|
|
|
8
10
|
* SARIF log, --verbose prints them, and the exit code never reads this.
|
|
9
11
|
*/
|
|
10
12
|
export declare const FINDINGS_SHOWN_PER_GATE = 20;
|
|
13
|
+
/** The convention match behind a gate's contract, when the branch name chose it. */
|
|
14
|
+
export declare function conventionMatch(gate: GateOutcome): ReportedMatch | null;
|
|
11
15
|
/**
|
|
12
16
|
* The one sentence the whole of pull-request mode has to fit into.
|
|
13
17
|
*
|
|
@@ -183,6 +187,13 @@ export interface TextOptions {
|
|
|
183
187
|
*/
|
|
184
188
|
terminal?: boolean;
|
|
185
189
|
}
|
|
190
|
+
/**
|
|
191
|
+
* The intent-spec header line: a CLOSED SET of four strings, in precedence
|
|
192
|
+
* order, naming no branch, no file and no token. The Action copies one to the
|
|
193
|
+
* step summary only on a whole-line match, so nothing the repository or the
|
|
194
|
+
* head branch carries can reach that summary through it.
|
|
195
|
+
*/
|
|
196
|
+
export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two or more specs matched the branch equally", "intent-spec: none chosen, this branch chose a spec before conductor 0.11.0", "intent-spec: a different spec chosen than before conductor 0.11.0, see the report", "intent-spec: weak match, see the intent gate in the report"];
|
|
186
197
|
/**
|
|
187
198
|
* dep-guard's own diagnostic code for an online budget that ran out before
|
|
188
199
|
* every lookup was made (dep-guard core, online/deadline.ts,
|
package/dist/output-text.js
CHANGED
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
26
|
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
|
|
27
|
-
import { isLegacyContractPath } from './intent-prepare.js';
|
|
27
|
+
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
|
+
import { SPEC_DIR } from './intent-spec.js';
|
|
28
29
|
function subjectLabel(finding) {
|
|
29
30
|
const subject = finding.subject;
|
|
30
31
|
switch (subject.kind) {
|
|
@@ -254,6 +255,52 @@ function contractLine(gate) {
|
|
|
254
255
|
const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
|
|
255
256
|
return ` contract: ${where} ${base}`;
|
|
256
257
|
}
|
|
258
|
+
/** The convention match behind a gate's contract, when the branch name chose it. */
|
|
259
|
+
export function conventionMatch(gate) {
|
|
260
|
+
const source = gate.intent?.contractSource;
|
|
261
|
+
return source?.kind === 'imported' && source.match !== undefined ? source.match : null;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* The weak-match line, printed under the contract line in every report.
|
|
265
|
+
*
|
|
266
|
+
* The shared words are charset-restricted tokens (isSignificant in
|
|
267
|
+
* intent-spec.ts), so nothing the branch was called beyond them reaches this
|
|
268
|
+
* line, and the runner-up is a filename the specs directory listed.
|
|
269
|
+
*/
|
|
270
|
+
function weakMatchLine(match) {
|
|
271
|
+
const words = (list) => list.map((word) => `"${word}"`).join(', ');
|
|
272
|
+
const why = match.weakBecause.includes('length-tiebreak') && match.runnerUp !== null
|
|
273
|
+
? `the branch name shares ${words(match.shared)} with this spec and ` +
|
|
274
|
+
`${words(match.runnerUpShared)} with ${SPEC_DIR}/${match.runnerUp}; the longer word decided it.`
|
|
275
|
+
: `the branch name shares only ${words(match.shared)} with this spec's name.`;
|
|
276
|
+
const remedy = match.remedy === 'pr-body'
|
|
277
|
+
? 'To be sure this is the right contract, add a "Spec: <path>" line to the pull request body ' +
|
|
278
|
+
"or rename the branch to the spec's name."
|
|
279
|
+
: "To be sure this is the right contract, pass --spec <path> or rename the branch to the spec's name.";
|
|
280
|
+
return ` match: weak, ${why} ${remedy}`;
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* The lines a convention match adds to the gate block: the weak line and the
|
|
284
|
+
* changed-winner note, printed in every report, and the chosen-by line,
|
|
285
|
+
* printed for every strength under --verbose so a strong or exact choice is
|
|
286
|
+
* visible too.
|
|
287
|
+
*/
|
|
288
|
+
function conventionLines(gate) {
|
|
289
|
+
const match = conventionMatch(gate);
|
|
290
|
+
if (match === null) {
|
|
291
|
+
return { under: [], chosenBy: null };
|
|
292
|
+
}
|
|
293
|
+
const under = [];
|
|
294
|
+
if (match.strength === 'weak') {
|
|
295
|
+
under.push(weakMatchLine(match));
|
|
296
|
+
}
|
|
297
|
+
if (match.legacy !== null) {
|
|
298
|
+
under.push(` note: ${legacyChangedSentence(match.legacy)}`);
|
|
299
|
+
}
|
|
300
|
+
const chosenBy = ` chosen by: branch name, ${match.strength}, shared: ${match.shared.join(' ')}` +
|
|
301
|
+
(match.runnerUp === null ? '' : `, runner-up ${SPEC_DIR}/${match.runnerUp}`);
|
|
302
|
+
return { under, chosenBy };
|
|
303
|
+
}
|
|
257
304
|
function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
258
305
|
// A gate the refused trust base stopped, on a terminal: the refusal is at
|
|
259
306
|
// the top of the report once, so the section is one line and no more.
|
|
@@ -272,9 +319,16 @@ function gateSection(gate, verbose, refusedOnTerminal = false) {
|
|
|
272
319
|
const contract = contractLine(gate);
|
|
273
320
|
if (contract !== null) {
|
|
274
321
|
lines.push(contract);
|
|
322
|
+
// The weak line and the changed-winner note sit directly under the
|
|
323
|
+
// contract line; the chosen-by line, --verbose only, after any other note.
|
|
324
|
+
const convention = conventionLines(gate);
|
|
325
|
+
lines.push(...convention.under);
|
|
275
326
|
if (gate.intent?.note !== undefined) {
|
|
276
327
|
lines.push(` note: ${gate.intent.note}`);
|
|
277
328
|
}
|
|
329
|
+
if (verbose && convention.chosenBy !== null) {
|
|
330
|
+
lines.push(convention.chosenBy);
|
|
331
|
+
}
|
|
278
332
|
}
|
|
279
333
|
if (gate.couldNotRun !== null) {
|
|
280
334
|
lines.push(` ${gate.couldNotRun.detail}`);
|
|
@@ -375,17 +429,27 @@ function skippedLines(result) {
|
|
|
375
429
|
return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} ${skipWording(gate.reason).line}: ${gate.detail}`);
|
|
376
430
|
}
|
|
377
431
|
function skipWording(reason) {
|
|
378
|
-
|
|
379
|
-
|
|
432
|
+
if (reason === 'contract-waived') {
|
|
433
|
+
return {
|
|
380
434
|
line: 'spec waived',
|
|
381
435
|
verdict: 'had its spec waived by the pull request body',
|
|
382
436
|
summary: 'Spec waived by the pull request body',
|
|
383
|
-
}
|
|
384
|
-
: {
|
|
385
|
-
line: 'no contract',
|
|
386
|
-
verdict: 'had no contract to check against',
|
|
387
|
-
summary: 'Nothing to check against',
|
|
388
437
|
};
|
|
438
|
+
}
|
|
439
|
+
if (reason === 'spec-ambiguous') {
|
|
440
|
+
// A spec exists; two or more matched equally. Never "nothing to check
|
|
441
|
+
// against", which tells a reader to go and write one.
|
|
442
|
+
return {
|
|
443
|
+
line: 'spec ambiguous',
|
|
444
|
+
verdict: 'matched two or more specs equally, so none was chosen',
|
|
445
|
+
summary: 'No spec chosen, two or more matched the branch equally',
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
return {
|
|
449
|
+
line: 'no contract',
|
|
450
|
+
verdict: 'had no contract to check against',
|
|
451
|
+
summary: 'Nothing to check against',
|
|
452
|
+
};
|
|
389
453
|
}
|
|
390
454
|
/**
|
|
391
455
|
* One line per gate the --gate flag left out.
|
|
@@ -1017,14 +1081,55 @@ function isFullyClean(result) {
|
|
|
1017
1081
|
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
|
|
1018
1082
|
return false;
|
|
1019
1083
|
}
|
|
1084
|
+
// A tie the convention refused to guess, or a skip whose branch 0.10.0
|
|
1085
|
+
// bound to a spec, carries a sentence the one-line summary would drop.
|
|
1086
|
+
if (result.skipped.some((gate) => gate.reason === 'spec-ambiguous' || (gate.selection?.legacy ?? null) !== null)) {
|
|
1087
|
+
return false;
|
|
1088
|
+
}
|
|
1020
1089
|
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
1021
1090
|
(gate.exitCode ?? 0) === 0 &&
|
|
1022
1091
|
gate.diagnostics.length === 0 &&
|
|
1023
1092
|
// A note about an input this run did not use is never folded into the
|
|
1024
1093
|
// one-line summary, where nobody would see it.
|
|
1025
1094
|
gate.intent?.note === undefined &&
|
|
1095
|
+
// Nor a weak convention match, or a winner that changed this release.
|
|
1096
|
+
conventionMatch(gate)?.strength !== 'weak' &&
|
|
1097
|
+
(conventionMatch(gate)?.legacy ?? null) === null &&
|
|
1026
1098
|
!gate.findings.some((finding) => finding.blocking));
|
|
1027
1099
|
}
|
|
1100
|
+
/**
|
|
1101
|
+
* The intent-spec header line: a CLOSED SET of four strings, in precedence
|
|
1102
|
+
* order, naming no branch, no file and no token. The Action copies one to the
|
|
1103
|
+
* step summary only on a whole-line match, so nothing the repository or the
|
|
1104
|
+
* head branch carries can reach that summary through it.
|
|
1105
|
+
*/
|
|
1106
|
+
export const INTENT_SPEC_LINES = [
|
|
1107
|
+
'intent-spec: none chosen, two or more specs matched the branch equally',
|
|
1108
|
+
'intent-spec: none chosen, this branch chose a spec before conductor 0.11.0',
|
|
1109
|
+
'intent-spec: a different spec chosen than before conductor 0.11.0, see the report',
|
|
1110
|
+
'intent-spec: weak match, see the intent gate in the report',
|
|
1111
|
+
];
|
|
1112
|
+
/** The first of the four lines that applies to this run, or null. */
|
|
1113
|
+
function intentSpecLine(result) {
|
|
1114
|
+
const misses = result.skipped.flatMap((gate) => (gate.selection === undefined ? [] : [gate.selection]));
|
|
1115
|
+
const matches = result.gates.flatMap((gate) => {
|
|
1116
|
+
const match = conventionMatch(gate);
|
|
1117
|
+
return match === null ? [] : [match];
|
|
1118
|
+
});
|
|
1119
|
+
if (misses.some((miss) => miss.why === 'ambiguous')) {
|
|
1120
|
+
return INTENT_SPEC_LINES[0];
|
|
1121
|
+
}
|
|
1122
|
+
if (misses.some((miss) => miss.legacy !== null)) {
|
|
1123
|
+
return INTENT_SPEC_LINES[1];
|
|
1124
|
+
}
|
|
1125
|
+
if (matches.some((match) => match.legacy !== null)) {
|
|
1126
|
+
return INTENT_SPEC_LINES[2];
|
|
1127
|
+
}
|
|
1128
|
+
if (matches.some((match) => match.strength === 'weak')) {
|
|
1129
|
+
return INTENT_SPEC_LINES[3];
|
|
1130
|
+
}
|
|
1131
|
+
return null;
|
|
1132
|
+
}
|
|
1028
1133
|
/**
|
|
1029
1134
|
* dep-guard's own diagnostic code for an online budget that ran out before
|
|
1030
1135
|
* every lookup was made (dep-guard core, online/deadline.ts,
|
|
@@ -1258,9 +1363,14 @@ export function renderText(result, options = {}) {
|
|
|
1258
1363
|
// job summary when, and only when, line 3 is exactly this shape, so a pass
|
|
1259
1364
|
// that carries them does not read as spotless there either.
|
|
1260
1365
|
const reported = presentOnBaseReported(result);
|
|
1366
|
+
// The intent-spec line follows it, so the present-on-base line, when
|
|
1367
|
+
// present, stays line 3 and every report without an intent-spec line keeps
|
|
1368
|
+
// the shape the Action already reads.
|
|
1369
|
+
const specLine = intentSpecLine(result);
|
|
1261
1370
|
const lines = [
|
|
1262
1371
|
...headerLines(result, options),
|
|
1263
1372
|
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
1373
|
+
...(specLine === null ? [] : [specLine]),
|
|
1264
1374
|
...refusal,
|
|
1265
1375
|
...(refusal.length === 0 ? [] : ['']),
|
|
1266
1376
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
package/dist/run.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type Finding } from './envelope.js';
|
|
2
2
|
import { type GateOutcome } from './gate-runner.js';
|
|
3
|
+
import type { SelectionMiss } from './intent-spec.js';
|
|
3
4
|
import type { GateRole, GateStage, Policy, Product } from './policy.js';
|
|
4
5
|
/**
|
|
5
6
|
* An enabled gate the stage filter held back.
|
|
@@ -69,8 +70,15 @@ export interface TreeUnchangedGate {
|
|
|
69
70
|
export interface SkippedGate {
|
|
70
71
|
role: GateRole;
|
|
71
72
|
product: Product;
|
|
72
|
-
|
|
73
|
+
/**
|
|
74
|
+
* `spec-ambiguous` is the third: two or more specs matched the branch name
|
|
75
|
+
* equally, so the convention chose none. Advisory exactly like the other
|
|
76
|
+
* two, and for the same reason.
|
|
77
|
+
*/
|
|
78
|
+
reason: 'no-contract' | 'contract-waived' | 'spec-ambiguous';
|
|
73
79
|
detail: string;
|
|
80
|
+
/** What the branch-name convention said, for the SARIF details bag. */
|
|
81
|
+
selection?: SelectionMiss;
|
|
74
82
|
}
|
|
75
83
|
/**
|
|
76
84
|
* One control input this pull request proposes to change.
|
package/dist/run.js
CHANGED