@vaultcompass/conductor 0.2.1 → 0.2.3
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 +98 -6
- package/dist/cli.js +49 -6
- package/dist/gate-runner.js +16 -5
- package/dist/init.d.ts +18 -2
- package/dist/init.js +241 -13
- package/dist/intent-prepare.d.ts +68 -4
- package/dist/intent-prepare.js +253 -19
- package/dist/intent-spec.d.ts +13 -0
- package/dist/intent-spec.js +21 -0
- package/dist/normalize.d.ts +31 -3
- package/dist/normalize.js +63 -5
- package/dist/output-sarif.js +65 -1
- package/dist/output-text.js +44 -8
- package/dist/run.d.ts +21 -7
- package/dist/run.js +1 -0
- package/package.json +1 -1
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -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
|
-
|
|
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,15 +63,32 @@ 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'
|
|
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;
|
|
37
78
|
}
|
|
38
|
-
/**
|
|
79
|
+
/**
|
|
80
|
+
* Nothing to check against: an advisory, never an exit code.
|
|
81
|
+
*
|
|
82
|
+
* Two reasons, and they are different facts about the same run.
|
|
83
|
+
* `no-contract` is the ordinary state of a branch nobody has written a
|
|
84
|
+
* spec for; `contract-waived` is somebody saying in the pull request body
|
|
85
|
+
* that there is deliberately no spec for this one. Reporting the second as
|
|
86
|
+
* the first tells a reviewer to go and write a spec that was already
|
|
87
|
+
* decided against.
|
|
88
|
+
*/
|
|
39
89
|
| {
|
|
40
90
|
kind: 'skip';
|
|
41
|
-
reason: 'no-contract';
|
|
91
|
+
reason: 'no-contract' | 'contract-waived';
|
|
42
92
|
detail: string;
|
|
43
93
|
} | {
|
|
44
94
|
kind: 'failed';
|
|
@@ -53,5 +103,19 @@ export interface IntentPrepareOptions {
|
|
|
53
103
|
base?: string;
|
|
54
104
|
spec?: string;
|
|
55
105
|
timeoutMs?: number;
|
|
106
|
+
/**
|
|
107
|
+
* The directory the per-run temporary project is created under.
|
|
108
|
+
*
|
|
109
|
+
* Injected exactly like `env` and `pathValue` are, and for the same kind
|
|
110
|
+
* of reason: the two tests that prove nothing is leaked count the
|
|
111
|
+
* `conductor-intent-` directories either side of a run, and counting them
|
|
112
|
+
* in the shared temporary directory made each of those tests depend on
|
|
113
|
+
* what the other jest worker happened to be doing at that moment. Nothing
|
|
114
|
+
* in production passes it, so a real run still uses the system temporary
|
|
115
|
+
* directory. It cannot be steered with TMPDIR from a test either: node
|
|
116
|
+
* reads that from the real process environment, and a jest test's
|
|
117
|
+
* `process.env` is a copy that never reaches it.
|
|
118
|
+
*/
|
|
119
|
+
tempRoot?: string;
|
|
56
120
|
}
|
|
57
121
|
export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -11,11 +11,12 @@
|
|
|
11
11
|
//
|
|
12
12
|
// Two rules keep that from being a lie:
|
|
13
13
|
//
|
|
14
|
-
// - NOTHING IS EVER WRITTEN UNDER
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
// it, and the second failure is
|
|
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
|
-
|
|
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
|
|
95
|
+
function contractIsFrozenAt(absolutePath) {
|
|
56
96
|
let parsed;
|
|
57
97
|
try {
|
|
58
|
-
parsed = parseYaml(readFileSync(
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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,46 @@ 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 (
|
|
143
|
-
source = { kind: 'native', path:
|
|
336
|
+
else if (nativeContract !== null) {
|
|
337
|
+
source = { kind: 'native', path: nativeContract };
|
|
338
|
+
}
|
|
339
|
+
else if (discovery.kind === 'waived') {
|
|
340
|
+
// BELOW the native check, and the order is the whole meaning of the
|
|
341
|
+
// token: "Spec: none" says there is no spec to import, not that this
|
|
342
|
+
// repository's own frozen contract should be ignored. Above the
|
|
343
|
+
// convention, though, which discoverSpec has already settled: an
|
|
344
|
+
// explicit statement beats an inferred one.
|
|
345
|
+
return {
|
|
346
|
+
kind: 'skip',
|
|
347
|
+
reason: 'contract-waived',
|
|
348
|
+
detail: 'The pull request body waived the spec with a "Spec: none" line, so there was ' +
|
|
349
|
+
`nothing to import and no frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} to fall ` +
|
|
350
|
+
'back on.',
|
|
351
|
+
};
|
|
144
352
|
}
|
|
145
353
|
else if (discovery.kind === 'none') {
|
|
146
354
|
source = { kind: 'none' };
|
|
@@ -152,7 +360,7 @@ export function prepareIntent(options) {
|
|
|
152
360
|
return {
|
|
153
361
|
kind: 'skip',
|
|
154
362
|
reason: 'no-contract',
|
|
155
|
-
detail: `No frozen ${
|
|
363
|
+
detail: `No frozen ${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} matching ` +
|
|
156
364
|
`${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
|
|
157
365
|
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
158
366
|
};
|
|
@@ -247,13 +455,22 @@ export function prepareIntent(options) {
|
|
|
247
455
|
detail: 'import-spec printed something that is not JSON, so no draft could be read.',
|
|
248
456
|
};
|
|
249
457
|
}
|
|
250
|
-
const projectDir = mkdtempSync(path.join(os.tmpdir(), TEMP_PREFIX));
|
|
458
|
+
const projectDir = mkdtempSync(path.join(options.tempRoot ?? os.tmpdir(), TEMP_PREFIX));
|
|
251
459
|
const cleanup = () => {
|
|
252
460
|
rmSync(projectDir, { recursive: true, force: true });
|
|
253
461
|
};
|
|
254
462
|
try {
|
|
255
|
-
|
|
256
|
-
|
|
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);
|
|
257
474
|
}
|
|
258
475
|
catch (err) {
|
|
259
476
|
cleanup();
|
|
@@ -290,6 +507,23 @@ export function prepareIntent(options) {
|
|
|
290
507
|
`freeze exited ${freezeResult.status ?? -1}: ${complaint(freezeResult)}`,
|
|
291
508
|
};
|
|
292
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
|
+
}
|
|
293
527
|
return {
|
|
294
528
|
kind: 'ready',
|
|
295
529
|
preparation: { ...common, contractSource: source, projectDir, cleanup },
|
package/dist/intent-spec.d.ts
CHANGED
|
@@ -11,9 +11,22 @@ export type SpecDiscovery =
|
|
|
11
11
|
| {
|
|
12
12
|
kind: 'missing-flag';
|
|
13
13
|
spec: string;
|
|
14
|
+
}
|
|
15
|
+
/** The pull request body said `Spec: none`: there is nothing to import. */
|
|
16
|
+
| {
|
|
17
|
+
kind: 'waived';
|
|
14
18
|
} | {
|
|
15
19
|
kind: 'none';
|
|
16
20
|
};
|
|
21
|
+
/**
|
|
22
|
+
* The token that turns a `Spec:` line into a waiver.
|
|
23
|
+
*
|
|
24
|
+
* Exact and lowercase. "None" with a capital is somebody writing prose, and
|
|
25
|
+
* a sentence must not be able to switch a gate off; an unusable value that
|
|
26
|
+
* is not this token keeps falling through to the convention, silently, the
|
|
27
|
+
* way every other unusable value does.
|
|
28
|
+
*/
|
|
29
|
+
export declare const SPEC_WAIVER_TOKEN = "none";
|
|
17
30
|
export interface SpecDiscoveryOptions {
|
|
18
31
|
repoRoot: string;
|
|
19
32
|
/** `--spec` on the umbrella's command line, repository-relative or absolute. */
|
package/dist/intent-spec.js
CHANGED
|
@@ -24,6 +24,9 @@
|
|
|
24
24
|
// pull request, which is a weaker claim than a command line typed now,
|
|
25
25
|
// and a path here that does not exist FALLS THROUGH to the convention. A
|
|
26
26
|
// typo in a pull request description must not be able to fail a build.
|
|
27
|
+
// The one value that does not fall through is the exact token `none`,
|
|
28
|
+
// which WAIVES the import: it is a statement rather than a path, and an
|
|
29
|
+
// explicit statement beats the inferred convention below.
|
|
27
30
|
//
|
|
28
31
|
// 3. The convention: a markdown file directly under docs/superpowers/specs
|
|
29
32
|
// whose name relates to the branch. Directly under, not nested, because
|
|
@@ -33,6 +36,15 @@ import { readFileSync, readdirSync, realpathSync } from 'node:fs';
|
|
|
33
36
|
import path from 'node:path';
|
|
34
37
|
export const SPEC_DIR = 'docs/superpowers/specs';
|
|
35
38
|
export const PLAN_DIR = 'docs/superpowers/plans';
|
|
39
|
+
/**
|
|
40
|
+
* The token that turns a `Spec:` line into a waiver.
|
|
41
|
+
*
|
|
42
|
+
* Exact and lowercase. "None" with a capital is somebody writing prose, and
|
|
43
|
+
* a sentence must not be able to switch a gate off; an unusable value that
|
|
44
|
+
* is not this token keeps falling through to the convention, silently, the
|
|
45
|
+
* way every other unusable value does.
|
|
46
|
+
*/
|
|
47
|
+
export const SPEC_WAIVER_TOKEN = 'none';
|
|
36
48
|
/**
|
|
37
49
|
* The branch name with its prefix removed.
|
|
38
50
|
*
|
|
@@ -245,6 +257,15 @@ export function discoverSpec(options) {
|
|
|
245
257
|
}
|
|
246
258
|
if (options.prBody !== undefined) {
|
|
247
259
|
const named = specFromPrBody(options.prBody);
|
|
260
|
+
if (named === SPEC_WAIVER_TOKEN) {
|
|
261
|
+
// Before the convention, because an explicit statement beats an
|
|
262
|
+
// inferred one: whoever opened the pull request said there is no spec
|
|
263
|
+
// to import, and the branch happening to share a name with a file
|
|
264
|
+
// under docs/superpowers/specs does not overrule that. It is NOT
|
|
265
|
+
// before a frozen native contract, which prepareIntent still checks
|
|
266
|
+
// first: a waiver says "nothing to import", not "check nothing".
|
|
267
|
+
return { kind: 'waived' };
|
|
268
|
+
}
|
|
248
269
|
if (named !== null) {
|
|
249
270
|
const relative = relativeToRoot(repoRoot, named);
|
|
250
271
|
// A path out of the tree is treated exactly as a path that is not
|
package/dist/normalize.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
58
|
-
|
|
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.'
|
|
582
|
+
'Nothing was verified by this gate.' +
|
|
583
|
+
(said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
|
|
578
584
|
}
|
|
579
|
-
/**
|
|
580
|
-
|
|
581
|
-
|
|
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
|
}
|