@vaultcompass/conductor 0.2.2 → 0.2.4

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.
@@ -1,7 +1,40 @@
1
1
  import type { ResolvedBinary } from './resolve.js';
2
2
  /** Prefix of the per-run directory, exported so a test can count leaks. */
3
3
  export declare const TEMP_PREFIX = "conductor-intent-";
4
- export declare const NATIVE_CONTRACT_PATH = ".conductor/intent-contract.yaml";
4
+ /**
5
+ * Where intent-guard keeps a project's frozen contract, canonical first.
6
+ *
7
+ * intent-guard 1.3.0 renamed its per-project state directory from
8
+ * `.conductor` to `.intent-guard`, because `.conductor` had become the name
9
+ * of a DIFFERENT product in the same family: a repository adopting both
10
+ * showed `.conductor/` and `.guardrails/` side by side with nothing to say
11
+ * which tool owned which. The umbrella has to read both, because the two
12
+ * versions will be installed side by side across repositories for as long as
13
+ * anybody is slow to upgrade, and a gate whose contract the umbrella cannot
14
+ * find is a pull request blocked on nothing.
15
+ *
16
+ * THE ORDER IS THE RULE, and it is the same order intent-guard itself uses:
17
+ * canonical wins outright, and the legacy path is consulted only when the
18
+ * canonical one holds nothing. Reversing it would make a migrated repository
19
+ * keep reading the directory the migration left behind.
20
+ */
21
+ export declare const STATE_DIR = ".intent-guard";
22
+ /** The pre-1.3.0 directory. Read as a fallback, never written to. */
23
+ export declare const LEGACY_STATE_DIR = ".conductor";
24
+ export declare const NATIVE_CONTRACT_PATH = ".intent-guard/intent-contract.yaml";
25
+ /** The pre-1.3.0 path. Read as a fallback, never written to. */
26
+ export declare const LEGACY_NATIVE_CONTRACT_PATH = ".conductor/intent-contract.yaml";
27
+ /** Both, canonical first, so no caller has to spell the order itself. */
28
+ export declare const NATIVE_CONTRACT_PATHS: readonly [".intent-guard/intent-contract.yaml", ".conductor/intent-contract.yaml"];
29
+ /**
30
+ * Whether a contract source path is the pre-1.3.0 one.
31
+ *
32
+ * A PREDICATE over the path rather than a flag carried beside it. The path is
33
+ * already the fact, and a boolean travelling next to it is a second copy that
34
+ * can disagree with the first -- the failure this repository has written down
35
+ * about recomputing a gate's decision in a renderer, in the same shape.
36
+ */
37
+ export declare function isLegacyContractPath(contractPath: string): boolean;
5
38
  export type ContractSource =
6
39
  /** The repository's own frozen contract, used untouched. */
7
40
  {
@@ -30,7 +63,15 @@ export interface IntentPreparation {
30
63
  cleanup: () => void;
31
64
  }
32
65
  /** Which link of the chain broke. Carried into the report verbatim. */
33
- export type PrepareStep = 'spec' | 'base' | 'import-spec' | 'write-contract' | 'freeze';
66
+ export type PrepareStep = 'spec' | 'base'
67
+ /**
68
+ * The repository holds a frozen contract at BOTH the canonical and the
69
+ * legacy path, so which one the gate is about cannot be answered. Its own
70
+ * step because it happens before anything is spawned and before a spec is
71
+ * even looked for, and because the fix is in the repository rather than in
72
+ * anything conductor did.
73
+ */
74
+ | 'contract-source' | 'import-spec' | 'write-contract' | 'freeze';
34
75
  export type IntentPrepareResult = {
35
76
  kind: 'ready';
36
77
  preparation: IntentPreparation;
@@ -11,11 +11,12 @@
11
11
  //
12
12
  // Two rules keep that from being a lie:
13
13
  //
14
- // - NOTHING IS EVER WRITTEN UNDER <repo>/.conductor. A contract is a
15
- // committed artifact with an approver's name on it. A pull-request run
16
- // that dropped one into the working tree would either be committed by
17
- // accident or picked up by the next run as though a person had approved
18
- // it, and the second failure is silent.
14
+ // - NOTHING IS EVER WRITTEN UNDER THE REPOSITORY'S OWN STATE DIRECTORY,
15
+ // under either of its two names. A contract is a committed artifact with
16
+ // an approver's name on it. A pull-request run that dropped one into the
17
+ // working tree would either be committed by accident or picked up by the
18
+ // next run as though a person had approved it, and the second failure is
19
+ // silent.
19
20
  //
20
21
  // - THE REPOSITORY'S OWN FROZEN CONTRACT ALWAYS WINS. Where a team has done
21
22
  // the native flow, the native flow is what runs; the import is the
@@ -29,15 +30,54 @@
29
30
  // distinguishes a shallow checkout from a spec the importer choked on is the
30
31
  // sentence in the report.
31
32
  import { spawnSync } from 'node:child_process';
32
- import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
33
+ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
33
34
  import os from 'node:os';
34
35
  import path from 'node:path';
35
36
  import { parse as parseYaml } from 'yaml';
36
37
  import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
38
+ import { summariseStderr } from './normalize.js';
37
39
  import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
38
40
  /** Prefix of the per-run directory, exported so a test can count leaks. */
39
41
  export const TEMP_PREFIX = 'conductor-intent-';
40
- export const NATIVE_CONTRACT_PATH = '.conductor/intent-contract.yaml';
42
+ /**
43
+ * Where intent-guard keeps a project's frozen contract, canonical first.
44
+ *
45
+ * intent-guard 1.3.0 renamed its per-project state directory from
46
+ * `.conductor` to `.intent-guard`, because `.conductor` had become the name
47
+ * of a DIFFERENT product in the same family: a repository adopting both
48
+ * showed `.conductor/` and `.guardrails/` side by side with nothing to say
49
+ * which tool owned which. The umbrella has to read both, because the two
50
+ * versions will be installed side by side across repositories for as long as
51
+ * anybody is slow to upgrade, and a gate whose contract the umbrella cannot
52
+ * find is a pull request blocked on nothing.
53
+ *
54
+ * THE ORDER IS THE RULE, and it is the same order intent-guard itself uses:
55
+ * canonical wins outright, and the legacy path is consulted only when the
56
+ * canonical one holds nothing. Reversing it would make a migrated repository
57
+ * keep reading the directory the migration left behind.
58
+ */
59
+ export const STATE_DIR = '.intent-guard';
60
+ /** The pre-1.3.0 directory. Read as a fallback, never written to. */
61
+ export const LEGACY_STATE_DIR = '.conductor';
62
+ export const NATIVE_CONTRACT_PATH = `${STATE_DIR}/intent-contract.yaml`;
63
+ /** The pre-1.3.0 path. Read as a fallback, never written to. */
64
+ export const LEGACY_NATIVE_CONTRACT_PATH = `${LEGACY_STATE_DIR}/intent-contract.yaml`;
65
+ /** Both, canonical first, so no caller has to spell the order itself. */
66
+ export const NATIVE_CONTRACT_PATHS = [
67
+ NATIVE_CONTRACT_PATH,
68
+ LEGACY_NATIVE_CONTRACT_PATH,
69
+ ];
70
+ /**
71
+ * Whether a contract source path is the pre-1.3.0 one.
72
+ *
73
+ * A PREDICATE over the path rather than a flag carried beside it. The path is
74
+ * already the fact, and a boolean travelling next to it is a second copy that
75
+ * can disagree with the first -- the failure this repository has written down
76
+ * about recomputing a gate's decision in a renderer, in the same shape.
77
+ */
78
+ export function isLegacyContractPath(contractPath) {
79
+ return contractPath === LEGACY_NATIVE_CONTRACT_PATH;
80
+ }
41
81
  /**
42
82
  * Whether a contract on disk has been approved.
43
83
  *
@@ -52,10 +92,10 @@ export const NATIVE_CONTRACT_PATH = '.conductor/intent-contract.yaml';
52
92
  * A file that cannot be parsed is treated as not frozen, which sends the run
53
93
  * down the import path rather than handing the gate something it will reject.
54
94
  */
55
- function nativeContractIsFrozen(repoRoot) {
95
+ function contractIsFrozenAt(absolutePath) {
56
96
  let parsed;
57
97
  try {
58
- parsed = parseYaml(readFileSync(path.join(repoRoot, NATIVE_CONTRACT_PATH), 'utf8'));
98
+ parsed = parseYaml(readFileSync(absolutePath, 'utf8'));
59
99
  }
60
100
  catch {
61
101
  return false;
@@ -63,7 +103,127 @@ function nativeContractIsFrozen(repoRoot) {
63
103
  if (parsed === null || typeof parsed !== 'object') {
64
104
  return false;
65
105
  }
66
- return parsed.frozen_by === 'user';
106
+ // BOTH halves, because both halves are the gate's own test
107
+ // (`isContractFrozen`: frozen_by === "user" && approval != null), and its
108
+ // comment says frozen_by alone, hand-set in YAML, is not enough. This
109
+ // function reconstructs that judgment from the file rather than asking the
110
+ // gate, so reconstructing only half of it means calling a contract frozen
111
+ // that the gate will call unfrozen -- which skips the import and then
112
+ // blocks the pull request on "exists but is not frozen by user" without
113
+ // checking anything, the exact failure the surrounding rule exists to
114
+ // prevent. A real freeze on either version writes both, so requiring both
115
+ // excludes no contract either tool produced.
116
+ const contract = parsed;
117
+ return (contract.frozen_by === 'user' && contract.approval !== undefined && contract.approval !== null);
118
+ }
119
+ /**
120
+ * Every state directory in this repository holding a FROZEN contract,
121
+ * canonical first.
122
+ *
123
+ * Zero is the ordinary case for a repository that has not done the native
124
+ * flow, one is the answer this exists to give, and two cannot reach here:
125
+ * `stateDirsConflict` below has already refused that repository, on a rule
126
+ * wider than this one.
127
+ *
128
+ * FROZEN is the test rather than EXISTS for the reason the single-path
129
+ * version of this already recorded: an unfrozen contract is a draft somebody
130
+ * left behind, and handing the gate one fails every pull request on "not
131
+ * frozen by user" without checking anything.
132
+ */
133
+ function frozenNativeContracts(repoRoot) {
134
+ return NATIVE_CONTRACT_PATHS.filter((relative) => contractIsFrozenAt(path.join(repoRoot, relative)));
135
+ }
136
+ /**
137
+ * The files only intent-guard writes into its state directory.
138
+ *
139
+ * Copied from the gate's own `holdsIntentGuardState`, because the rule below
140
+ * has to be the gate's rule and not an approximation of it. A `.conductor`
141
+ * holding none of these belongs to something else, and neither tool touches
142
+ * it.
143
+ */
144
+ const STATE_MARKERS = [
145
+ 'config.yaml',
146
+ 'intent-contract.yaml',
147
+ 'index.md',
148
+ 'drift-log.jsonl',
149
+ 'contracts',
150
+ ];
151
+ function isDirectory(candidate) {
152
+ try {
153
+ return statSync(candidate).isDirectory();
154
+ }
155
+ catch {
156
+ return false;
157
+ }
158
+ }
159
+ /**
160
+ * A real directory, not a symlink to one.
161
+ *
162
+ * `ln -s .intent-guard .conductor` is the obvious workaround for a script
163
+ * that still names the old path, and following it makes ONE directory look
164
+ * like two: the legacy path would hold state, the canonical path would
165
+ * exist, and the run would fail closed on a conflict that is not one. lstat
166
+ * does not follow the link, so a symlink is simply not a legacy state
167
+ * directory.
168
+ *
169
+ * THE ASYMMETRY WITH `isDirectory` ABOVE IS DELIBERATE AND IS THE GATE'S
170
+ * OWN: the canonical side follows symlinks and the legacy side does not.
171
+ * Making both sides lstat would be tidier and wrong, because a canonical
172
+ * directory reached through a symlink is still a canonical directory that
173
+ * intent-guard will read and write.
174
+ */
175
+ function isRealDirectory(candidate) {
176
+ try {
177
+ return lstatSync(candidate).isDirectory();
178
+ }
179
+ catch {
180
+ return false;
181
+ }
182
+ }
183
+ function holdsIntentGuardState(dir) {
184
+ if (!isRealDirectory(dir)) {
185
+ return false;
186
+ }
187
+ return STATE_MARKERS.some((marker) => existsSync(path.join(dir, marker)));
188
+ }
189
+ /**
190
+ * Whether this repository is in the state intent-guard 1.3.0 refuses to run
191
+ * ANY command in.
192
+ *
193
+ * THIS MIRRORS THE GATE'S OWN CONFLICT RULE, deliberately and exactly
194
+ * (`inspectStateDir` in the gate's state-dir.ts): the canonical directory
195
+ * merely EXISTING, even empty, beside a legacy directory holding any state
196
+ * marker, frozen or not. Both halves are wider than they look and both
197
+ * matter.
198
+ *
199
+ * An earlier version of this file used a narrower rule -- both directories
200
+ * holding a FROZEN contract -- on the reasoning that a stale unfrozen draft
201
+ * beside a real contract has an obvious right answer and refusing would fail
202
+ * pull requests over a file nobody had looked at in months. That reasoning
203
+ * was about the wrong tool. The gate does not share it: in that exact state
204
+ * `stateDir` throws and every intent-guard command exits 1. So the narrower
205
+ * rule did not save those pull requests, it just moved where they broke --
206
+ * conductor handed the gate a repository the gate refuses to run in, the
207
+ * child exited non-zero with no JSON, and the run surfaced as
208
+ * gate-output-unparseable with a message about the umbrella being out of
209
+ * date. A guess about somebody else's tool is worth what the run that
210
+ * checked it is worth, and this one had not been checked.
211
+ */
212
+ function stateDirsConflict(repoRoot) {
213
+ return (isDirectory(path.join(repoRoot, STATE_DIR)) &&
214
+ holdsIntentGuardState(path.join(repoRoot, LEGACY_STATE_DIR)));
215
+ }
216
+ /**
217
+ * The contract file inside a prepared temporary project, canonical first, or
218
+ * null when neither path holds one.
219
+ *
220
+ * EXISTS rather than FROZEN, unlike the repository-side lookup above, and the
221
+ * difference is deliberate: this asks whether the freeze step left a file
222
+ * where the gate will look for it, and reading `frozen_by` here would be the
223
+ * umbrella double-checking a decision it just asked intent-guard to make.
224
+ */
225
+ function frozenContractIn(projectDir) {
226
+ return (NATIVE_CONTRACT_PATHS.find((relative) => existsSync(path.join(projectDir, relative))) ?? null);
67
227
  }
68
228
  /**
69
229
  * The command line for one intent-guard subcommand.
@@ -96,10 +256,24 @@ function run(command, argv, cwd, timeoutMs) {
96
256
  errorMessage: child.error === undefined ? null : child.error.message,
97
257
  };
98
258
  }
99
- /** The first line of whatever the child complained with, for a one-line report. */
259
+ /**
260
+ * Everything the child complained with, trimmed and capped.
261
+ *
262
+ * THIS USED TO BE THE FIRST LINE, and that was a real defect rather than a
263
+ * stylistic choice. The draft is written under the legacy directory name, so
264
+ * intent-guard 1.3.0 prints "reading project state from .conductor/, renamed
265
+ * to .intent-guard/ in 1.3.0" as line one of stderr on EVERY import-spec and
266
+ * EVERY freeze in a prepared project. Taking line one therefore reported the
267
+ * rename notice as the reason the step failed and discarded the sentence
268
+ * saying what was actually wrong, on every failure, on the version this
269
+ * release exists to support.
270
+ *
271
+ * The cap is the same one the gate-failed carry uses, and for the same
272
+ * reason: this string ends up in an uploaded report, and a child that dumps
273
+ * a stack must not grow it without a bound.
274
+ */
100
275
  function complaint(result) {
101
- const text = (result.stderr.trim() === '' ? result.stdout : result.stderr).trim();
102
- return text.split('\n')[0] ?? '';
276
+ return summariseStderr(result.stderr.trim() === '' ? result.stdout : result.stderr) ?? '';
103
277
  }
104
278
  /** The short commit the contract is attributed to, or a placeholder. */
105
279
  function shortHead(repoRoot) {
@@ -135,12 +309,32 @@ export function prepareIntent(options) {
135
309
  'A spec asked for by name is never replaced by a discovered one.',
136
310
  };
137
311
  }
312
+ // A repository holding both state directories stops the run before
313
+ // anything else is decided, INCLUDING before --spec is honoured. The flag
314
+ // would otherwise take the import path, which runs "import-spec --project ."
315
+ // in this same repository, where intent-guard 1.3.0 fails closed on the
316
+ // same conflict and reports it as an opaque non-zero exit from a
317
+ // subcommand. One sentence naming both directories beats that, and it is
318
+ // the same answer either way.
319
+ if (stateDirsConflict(repoRoot)) {
320
+ return {
321
+ kind: 'failed',
322
+ step: 'contract-source',
323
+ detail: `this repository has both ${STATE_DIR}/ and a ${LEGACY_STATE_DIR}/ holding ` +
324
+ `intent-guard state. ${LEGACY_STATE_DIR}/ is the pre-1.3 name for ${STATE_DIR}/, and ` +
325
+ 'intent-guard reads one state directory and never merges two, so it refuses every ' +
326
+ `command here rather than guessing. Move ${LEGACY_STATE_DIR}/ aside, or move what ` +
327
+ `is still needed out of it into ${STATE_DIR}/, and re-run. Nothing was checked by ` +
328
+ 'this gate.',
329
+ };
330
+ }
331
+ const nativeContract = frozenNativeContracts(repoRoot)[0] ?? null;
138
332
  let source;
139
333
  if (discovery.kind === 'flag') {
140
334
  source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
141
335
  }
142
- else if (nativeContractIsFrozen(repoRoot)) {
143
- source = { kind: 'native', path: NATIVE_CONTRACT_PATH };
336
+ else if (nativeContract !== null) {
337
+ source = { kind: 'native', path: nativeContract };
144
338
  }
145
339
  else if (discovery.kind === 'waived') {
146
340
  // BELOW the native check, and the order is the whole meaning of the
@@ -152,7 +346,8 @@ export function prepareIntent(options) {
152
346
  kind: 'skip',
153
347
  reason: 'contract-waived',
154
348
  detail: 'The pull request body waived the spec with a "Spec: none" line, so there was ' +
155
- `nothing to import and no frozen ${NATIVE_CONTRACT_PATH} to fall back on.`,
349
+ `nothing to import and no frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} to fall ` +
350
+ 'back on.',
156
351
  };
157
352
  }
158
353
  else if (discovery.kind === 'none') {
@@ -165,7 +360,7 @@ export function prepareIntent(options) {
165
360
  return {
166
361
  kind: 'skip',
167
362
  reason: 'no-contract',
168
- detail: `No frozen ${NATIVE_CONTRACT_PATH} and no spec under ${SPEC_DIR} matching ` +
363
+ detail: `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
169
364
  `${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
170
365
  'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
171
366
  };
@@ -265,8 +460,17 @@ export function prepareIntent(options) {
265
460
  rmSync(projectDir, { recursive: true, force: true });
266
461
  };
267
462
  try {
268
- mkdirSync(path.join(projectDir, '.conductor'), { recursive: true });
269
- writeFileSync(path.join(projectDir, NATIVE_CONTRACT_PATH), contractYaml);
463
+ // The DRAFT goes to the legacy path, which is the one both versions can
464
+ // find. A 1.2.x intent-guard reads only that directory; a 1.3.0 one reads
465
+ // it as the legacy fallback and renames it to the canonical name on its
466
+ // first write, which the freeze below is. Writing the canonical name
467
+ // instead would work on 1.3.0 and leave 1.2.x freezing an empty project.
468
+ // This is a temporary directory the umbrella made two lines ago, so
469
+ // writing the old name here is not a migration anybody has to live with.
470
+ mkdirSync(path.join(projectDir, path.dirname(LEGACY_NATIVE_CONTRACT_PATH)), {
471
+ recursive: true,
472
+ });
473
+ writeFileSync(path.join(projectDir, LEGACY_NATIVE_CONTRACT_PATH), contractYaml);
270
474
  }
271
475
  catch (err) {
272
476
  cleanup();
@@ -303,6 +507,23 @@ export function prepareIntent(options) {
303
507
  `freeze exited ${freezeResult.status ?? -1}: ${complaint(freezeResult)}`,
304
508
  };
305
509
  }
510
+ // Exit 0 is not proof there is a contract to hand the gate. freeze writes
511
+ // through intent-guard's own state directory, so a 1.3.0 build has just
512
+ // renamed the directory this function created and a 1.2.x one has not, and
513
+ // the whole point of this release is that the umbrella cannot assume which.
514
+ // Looking for the file, canonical first, turns "the gate found no contract
515
+ // in a directory conductor prepared" into a named preparation failure here
516
+ // rather than a confusing verdict from the gate three steps later.
517
+ if (frozenContractIn(projectDir) === null) {
518
+ cleanup();
519
+ return {
520
+ kind: 'failed',
521
+ step: 'freeze',
522
+ detail: 'freeze reported success but left no contract in the prepared project: neither ' +
523
+ `${NATIVE_CONTRACT_PATHS.join(' nor ')} is there. That is a version of ` +
524
+ 'intent-guard writing its state somewhere this umbrella does not know about.',
525
+ };
526
+ }
306
527
  return {
307
528
  kind: 'ready',
308
529
  preparation: { ...common, contractSource: source, projectDir, cleanup },
@@ -53,6 +53,34 @@ export declare function normalizeMisconfiguredGate(role: GateRole, product: Prod
53
53
  * filesystem path into a report that gets uploaded, and it would tell the
54
54
  * user nothing they can act on.
55
55
  */
56
- export declare function normalizeUnparseableGate(role: GateRole, product: Product, detail: string): Finding;
57
- /** The finding raised when a gate could not be run or did not complete. */
58
- export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string): Finding;
56
+ export declare function normalizeUnparseableGate(role: GateRole, product: Product, detail: string, stderr?: string | null): Finding;
57
+ /**
58
+ * The gate's own last words, trimmed and capped, or null when it said
59
+ * nothing.
60
+ *
61
+ * The truncation is ANNOUNCED rather than silent, and says how much there
62
+ * was. A message that stops mid-sentence with no note reads as the gate's
63
+ * final word, which sends a reader looking for meaning in a cut.
64
+ */
65
+ export declare function summariseStderr(stderr: string | null | undefined): string | null;
66
+ /**
67
+ * The finding raised when a gate could not be run or did not complete.
68
+ *
69
+ * `stderr` is what the child printed, and it is carried here because this
70
+ * finding is the ONLY place a published log can say why. A gate that could
71
+ * not run gets no SARIF run of its own, so without this the log held
72
+ * "the gate exited 2, which it uses for could not run" and nothing else,
73
+ * while the text report beside it printed the gate's own line naming the
74
+ * file and the reason. Found by running the umbrella against a repository
75
+ * with an unparseable lockfile.
76
+ *
77
+ * It is APPENDED to the umbrella's own sentence rather than replacing it.
78
+ * The generic half says which exit code was seen and what that gate uses it
79
+ * for, which the child's line does not, and a gate that exits 2 silently is
80
+ * a real case that has to keep reading sensibly.
81
+ *
82
+ * The fingerprint is unaffected: it is computed over the rule, the role and
83
+ * the product and never over the message, so a gate that reworded its error
84
+ * is the same alert rather than a new one every run.
85
+ */
86
+ export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null): Finding;
package/dist/normalize.js CHANGED
@@ -571,12 +571,70 @@ export function normalizeMisconfiguredGate(role, product, command, detail) {
571
571
  * filesystem path into a report that gets uploaded, and it would tell the
572
572
  * user nothing they can act on.
573
573
  */
574
- export function normalizeUnparseableGate(role, product, detail) {
574
+ export function normalizeUnparseableGate(role, product, detail, stderr) {
575
+ // Carried for the same reason gate-failed carries it, and the case that
576
+ // found the gap is a good one: a gate refusing to run at all exits 1 with
577
+ // no JSON and says why on stderr, and this result is the only place a
578
+ // published log can repeat it.
579
+ const said = summariseStderr(stderr);
575
580
  return gateProblem('conductor/gate-output-unparseable', role, product, `The "${role}" gate ran but the umbrella could not read its output: ${detail} ` +
576
581
  'This is the umbrella being out of date with that gate, not a problem in your code. ' +
577
- 'Nothing was verified by this gate.', { detail });
582
+ 'Nothing was verified by this gate.' +
583
+ (said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
578
584
  }
579
- /** The finding raised when a gate could not be run or did not complete. */
580
- export function normalizeFailedGate(role, product, detail) {
581
- return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.`, { detail });
585
+ /**
586
+ * How much of a failing gate's stderr goes into a published report.
587
+ *
588
+ * A gate that could not run may print a stack, a whole rejected config, or a
589
+ * file it could not parse, and this finding is uploaded to code scanning.
590
+ * The cap is generous enough for the shape that matters -- a line or two
591
+ * naming the file and the reason -- and small enough that nothing here can
592
+ * grow an alert without a bound.
593
+ */
594
+ const STDERR_CAP = 2000;
595
+ /**
596
+ * The gate's own last words, trimmed and capped, or null when it said
597
+ * nothing.
598
+ *
599
+ * The truncation is ANNOUNCED rather than silent, and says how much there
600
+ * was. A message that stops mid-sentence with no note reads as the gate's
601
+ * final word, which sends a reader looking for meaning in a cut.
602
+ */
603
+ export function summariseStderr(stderr) {
604
+ if (stderr === null || stderr === undefined) {
605
+ return null;
606
+ }
607
+ const trimmed = stderr.trim();
608
+ if (trimmed.length === 0) {
609
+ return null;
610
+ }
611
+ if (trimmed.length <= STDERR_CAP) {
612
+ return trimmed;
613
+ }
614
+ return `${trimmed.slice(0, STDERR_CAP)} [truncated, ${trimmed.length} characters in total]`;
615
+ }
616
+ /**
617
+ * The finding raised when a gate could not be run or did not complete.
618
+ *
619
+ * `stderr` is what the child printed, and it is carried here because this
620
+ * finding is the ONLY place a published log can say why. A gate that could
621
+ * not run gets no SARIF run of its own, so without this the log held
622
+ * "the gate exited 2, which it uses for could not run" and nothing else,
623
+ * while the text report beside it printed the gate's own line naming the
624
+ * file and the reason. Found by running the umbrella against a repository
625
+ * with an unparseable lockfile.
626
+ *
627
+ * It is APPENDED to the umbrella's own sentence rather than replacing it.
628
+ * The generic half says which exit code was seen and what that gate uses it
629
+ * for, which the child's line does not, and a gate that exits 2 silently is
630
+ * a real case that has to keep reading sensibly.
631
+ *
632
+ * The fingerprint is unaffected: it is computed over the rule, the role and
633
+ * the product and never over the message, so a gate that reworded its error
634
+ * is the same alert rather than a new one every run.
635
+ */
636
+ export function normalizeFailedGate(role, product, detail, stderr) {
637
+ const said = summariseStderr(stderr);
638
+ return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.` +
639
+ (said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
582
640
  }
@@ -21,6 +21,20 @@
21
21
  // umbrella, which is the only honest owner of a statement about a tool
22
22
  // that is not installed.
23
23
  //
24
+ // The rule is written for a gate that never ran, and it currently also
25
+ // covers a gate that RAN AND FAILED, which is a different thing: the
26
+ // SARIF-native shape for that one is its own run carrying
27
+ // invocations[0].executionSuccessful: false. That is deliberately not
28
+ // done here yet, because it changes the run list of every log with a
29
+ // failing gate in it and this release is a fix rather than a format
30
+ // change. The consequence is that conductor/gate-failed in the
31
+ // umbrella's run is the ONLY place such a log can say anything at all
32
+ // about the failure, which is why that finding carries the child's own
33
+ // stderr (normalizeFailedGate in normalize.ts). A dogfood run found the
34
+ // gap the other way round: the text report printed dep-guard naming an
35
+ // unparseable lockfile and the log beside it said only that the gate had
36
+ // exited 2.
37
+ //
24
38
  // - A STATEMENT ABOUT COVERAGE OR CONFIGURATION IS A NOTIFICATION, NOT A
25
39
  // FINDING. A gate deferred to a later stage, a gate the policy told not
26
40
  // to decide anything, and a branch with no contract to check against are
@@ -84,6 +98,7 @@
84
98
  // product, which puts an end column in its own SARIF; see the note in
85
99
  // normalize.ts, which is where the omission would stop mattering if the
86
100
  // field were ever carried.
101
+ import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
87
102
  const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
88
103
  export const UMBRELLA_DRIVER_NAME = 'conductor';
89
104
  /**
@@ -372,6 +387,48 @@ function deferredNotifications(result) {
372
387
  details: { role: gate.role, product: gate.product, stage: gate.stage },
373
388
  }));
374
389
  }
390
+ /**
391
+ * The intent gate reading its contract from the pre-1.3 state directory.
392
+ *
393
+ * intent-guard 1.3.0 renamed `.conductor` to `.intent-guard`, and the
394
+ * umbrella reads both so a repository on either version is checked rather
395
+ * than blocked. That fallback is silent otherwise, and a silent fallback is
396
+ * how a repository ends up on the old layout for a year: the log should say
397
+ * which directory the verdict was actually about.
398
+ *
399
+ * A NOTIFICATION by the discriminator below, and it is worth saying why,
400
+ * because it is the closest call of the five. Nothing went wrong. The gate
401
+ * ran, the contract was read, the verdict is exactly what it would have been
402
+ * after the migration, and the run is complete. What this says is which of
403
+ * two layouts the run covered, it stays true on every run until somebody
404
+ * upgrades the gate, and as a result it would be a fingerprint-less alert
405
+ * reappearing on every pull request for as long as that takes -- the precise
406
+ * shape of permanent alert the notification rule exists to keep out.
407
+ */
408
+ function legacyStateDirNotifications(result) {
409
+ return result.gates.flatMap((gate) => {
410
+ const source = gate.intent?.contractSource;
411
+ if (source === undefined || source.kind !== 'native' || !isLegacyContractPath(source.path)) {
412
+ return [];
413
+ }
414
+ return [
415
+ {
416
+ id: 'intent-guard/legacy-state-dir',
417
+ message: `The ${gate.role} gate (${gate.product}) read its frozen contract from ` +
418
+ `${source.path}, the state directory intent-guard used before 1.3.0. This run's ` +
419
+ `verdict is unaffected. 1.3.0 renamed that directory, reads the old one while it ` +
420
+ `is the only one there, and migrates it on its first write, after which the ` +
421
+ `contract is at ${NATIVE_CONTRACT_PATH}.`,
422
+ details: {
423
+ role: gate.role,
424
+ product: gate.product,
425
+ contractPath: source.path,
426
+ canonicalPath: NATIVE_CONTRACT_PATH,
427
+ },
428
+ },
429
+ ];
430
+ });
431
+ }
375
432
  /**
376
433
  * The gates the --gate flag left out, as notifications.
377
434
  *
@@ -551,6 +608,7 @@ export function renderSarif(result, umbrellaVersion) {
551
608
  ...excludedNotifications(result),
552
609
  ...skippedNotifications(result),
553
610
  ...unenforcedNotifications(result),
611
+ ...legacyStateDirNotifications(result),
554
612
  ];
555
613
  // Notifications earn the run on their own. Before this, the umbrella run
556
614
  // existed only when it had findings and a deferred gate was one; without