@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 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.10.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
- relates to the branch. The branch slug is the branch name with its first
1184
- segment (`feat/`, `fix/`) removed; a filename is reduced by stripping a
1185
- `YYYY-MM-DD-` prefix and a trailing `-design`; the two are candidates when
1186
- either contains the other. Several candidates are ranked: a stem **equal**
1187
- to the slug first, then the **longest** stem, and only then the newest
1188
- name, which is a lexical tie-break, so **date every spec**.
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.10.0.
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.10.0
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.10.0
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.13.0
1489
+ dep-guard-version: 0.14.0
1470
1490
  vault-guard-version: 1.11.0
1471
- intent-guard-version: 1.8.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.10.0
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.10.0
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.10.0
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.10.0
1904
+ uses: vaultcompasshq/conductor@v0.11.0
1885
1905
  with:
1886
1906
  pr-comment: true
1887
1907
  pr-comment-marker: 'package-b'
@@ -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
- reason: 'no-contract' | 'contract-waived';
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;
@@ -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, bestMatch, branchSlug, discoverSpec, normalizeStem, prBodyFromEvent, specFromPrBody, } from './intent-spec.js';
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
- kind: 'skip',
402
- reason: 'no-contract',
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 { kind: 'found', spec, specText, plan: plan.plan, planText: plan.planText };
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
- const best = bestMatch(listed.names, branchSlug(inputs.branch));
841
- if (best !== undefined) {
842
- const relative = `${SPEC_DIR}/${best}`;
843
- const read = readFileAtRef(repoRoot, ref, relative);
844
- if (read.kind !== 'file') {
845
- return {
846
- kind: 'failed',
847
- detail: read.kind === 'error' ? read.detail : `${relative} was listed at "${ref}" but not found`,
848
- };
849
- }
850
- return found(relative, read.text);
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, { kind: 'imported', spec: atBase.spec, plan: atBase.plan, ref: trustBase }, { ref: trustBase, specText: atBase.specText, planText: atBase.planText }, proposals);
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
- kind: 'skip',
974
- reason: 'no-contract',
975
- detail: `No contract on the base: "${trustBase}" carries no frozen ` +
976
- `${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
977
- `${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
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
  }
@@ -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' | 'convention';
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
- /** Whether a normalized stem and a slug name the same work. */
68
- export declare function stemMatches(stem: string, slug: string): boolean;
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
- * The best of the candidates whose stem relates to `target`, or undefined.
87
- *
88
- * `stemMatches` decides who is a CANDIDATE; this decides who wins, and the
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;
@@ -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 relates to the branch. Directly under, not nested, because
33
- // that is the layout intent-guard's own importer discovers and an
34
- // archive subdirectory is not a candidate for this branch's contract.
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
- /** Whether a normalized stem and a slug name the same work. */
73
- export function stemMatches(stem, slug) {
74
- if (stem === '' || slug === '') {
75
- return false;
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 stem.includes(slug) || slug.includes(stem);
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 best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
294
- if (best !== undefined) {
295
- const relative = `${SPEC_DIR}/${best}`;
296
- // The convention spec is held to the repository too: a specs directory
297
- // linked out of the checkout is refused, never imported. Only --spec is
298
- // exempt, as a path a person typed.
299
- if (!resolvesInsideRoot(repoRoot, relative)) {
300
- return { kind: 'escaped', path: relative };
301
- }
302
- return withPlan(repoRoot, 'convention', relative);
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
  }
@@ -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: { role: gate.role, product: gate.product, reason: gate.reason },
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),
@@ -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,
@@ -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
- return reason === 'contract-waived'
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
- reason: 'no-contract' | 'contract-waived';
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
@@ -309,6 +309,7 @@ export function runAll(policy, options) {
309
309
  product: gate.product,
310
310
  reason: prepared.reason,
311
311
  detail: prepared.detail,
312
+ ...(prepared.selection === undefined ? {} : { selection: prepared.selection }),
312
313
  });
313
314
  continue;
314
315
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [