@vaultcompass/conductor 0.8.0 → 0.9.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 +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +4 -0
package/dist/intent-base.js
CHANGED
|
@@ -7,16 +7,17 @@
|
|
|
7
7
|
// branch after this branch forked to this branch, so somebody else's merge
|
|
8
8
|
// breaches this pull request's change budget.
|
|
9
9
|
//
|
|
10
|
-
// The umbrella computes the path set ITSELF
|
|
11
|
-
//
|
|
12
|
-
//
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
//
|
|
17
|
-
//
|
|
18
|
-
|
|
19
|
-
import {
|
|
10
|
+
// The umbrella computes the path set ITSELF, and how it reaches the gate
|
|
11
|
+
// depends on the contract. An imported contract lives in a temporary
|
|
12
|
+
// directory (see intent-prepare.ts), where the gate's own `--base` would
|
|
13
|
+
// resolve git relative to a `--project` with no repository in it, so that
|
|
14
|
+
// gate is always handed `--paths`. A native contract on an intent-guard new
|
|
15
|
+
// enough to read the change set from git itself is handed the gate's own
|
|
16
|
+
// `--base` instead (`intentChangeChannel` in gate-runner.ts), and `--paths`
|
|
17
|
+
// otherwise. The flags below are copied from intent-guard so the two agree
|
|
18
|
+
// on what "changed" means rather than agreeing by coincidence.
|
|
19
|
+
import { runGit } from './git.js';
|
|
20
|
+
import { PRIVATE_TRUST_BASE_REF, exactRefLookup, exactRefObject, refuseAmbiguousRef, resolveRev, } from './trust-base.js';
|
|
20
21
|
/**
|
|
21
22
|
* The ref to diff against, or null for a run that is not a pull request.
|
|
22
23
|
*
|
|
@@ -49,6 +50,8 @@ export function resolveBaseRef(options) {
|
|
|
49
50
|
* both in full. The private ref wins and is not compared against the
|
|
50
51
|
* remote-tracking ref. If neither exists the spelled remote ref is returned and the
|
|
51
52
|
* diff fails closed, naming fetch-depth: 0.
|
|
53
|
+
* - Otherwise, on a run with a trust base: the commit the trust base
|
|
54
|
+
* resolves to.
|
|
52
55
|
* - Null outside a pull request.
|
|
53
56
|
*
|
|
54
57
|
* Nothing is deepened here: a depth-1 private ref has no merge base and the
|
|
@@ -59,7 +62,7 @@ export function resolveBaseRefInRepo(repoRoot, options) {
|
|
|
59
62
|
// A base that starts with a dash is an OPTION to git, not a ref:
|
|
60
63
|
// "--output=/x" made "git diff --output=/x...HEAD" write that file and
|
|
61
64
|
// print nothing, an empty change set the intent gate then judged as clean.
|
|
62
|
-
// Refused here, and changedPathsSince
|
|
65
|
+
// Refused here, and changedPathsSince refuses it again itself.
|
|
63
66
|
if (options.base.startsWith('-')) {
|
|
64
67
|
return {
|
|
65
68
|
ok: false,
|
|
@@ -84,7 +87,25 @@ export function resolveBaseRefInRepo(repoRoot, options) {
|
|
|
84
87
|
}
|
|
85
88
|
const fromGithub = options.env.GITHUB_BASE_REF;
|
|
86
89
|
if (fromGithub === undefined || fromGithub === '') {
|
|
87
|
-
|
|
90
|
+
if (options.trustBase === undefined) {
|
|
91
|
+
return { ok: true, base: null };
|
|
92
|
+
}
|
|
93
|
+
// No other base was named, so the change set is measured from the trust
|
|
94
|
+
// base: the commit the rules were read from is the one the pull request
|
|
95
|
+
// is judged against. Handed on as the commit id it resolves to, read the
|
|
96
|
+
// same way the trust base itself was (resolveRev never sends a refs/
|
|
97
|
+
// name through git's name resolution).
|
|
98
|
+
const commit = resolveRev(repoRoot, options.trustBase, 'commit');
|
|
99
|
+
if (commit === null) {
|
|
100
|
+
return {
|
|
101
|
+
ok: false,
|
|
102
|
+
detail: `the trust base does not resolve to a commit: "${options.trustBase}" names no commit in ` +
|
|
103
|
+
'this repository, so there is no base to measure the intent gate against and nothing ' +
|
|
104
|
+
'was checked. Fix: pass a trust base that is a commit in this checkout (in CI, check out ' +
|
|
105
|
+
'with fetch-depth: 0).',
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
return { ok: true, base: { ref: commit, source: 'trust-base' } };
|
|
88
109
|
}
|
|
89
110
|
const remoteRef = `refs/remotes/origin/${fromGithub}`;
|
|
90
111
|
// The private ref is the authority when it exists; refs/remotes/origin/<base>
|
|
@@ -93,16 +114,28 @@ export function resolveBaseRefInRepo(repoRoot, options) {
|
|
|
93
114
|
// refusal). It is the base only when the private ref is absent. Both are
|
|
94
115
|
// read with show-ref (the EXACT ref, never git's name resolution, which
|
|
95
116
|
// would take a tag of that name) and the base handed on is the commit id.
|
|
96
|
-
|
|
97
|
-
|
|
117
|
+
// A private ref git could not read is a refusal, never taken for an absent
|
|
118
|
+
// one; the remote-tracking ref is used only when the private ref is absent.
|
|
119
|
+
const privLookup = exactRefLookup(repoRoot, PRIVATE_TRUST_BASE_REF);
|
|
120
|
+
if (privLookup.kind === 'error') {
|
|
121
|
+
return {
|
|
122
|
+
ok: false,
|
|
123
|
+
detail: `the base branch could not be read: ${privLookup.detail}, so there is no base to measure ` +
|
|
124
|
+
'the intent gate against and nothing was checked. Fix: check that git can read the ' +
|
|
125
|
+
`repository and that the action's fetch of the base branch into ${PRIVATE_TRUST_BASE_REF} ` +
|
|
126
|
+
'succeeded, then run again.',
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
const priv = privLookup.kind === 'ref' ? privLookup.oid : null;
|
|
130
|
+
const remote = priv === null ? exactRefObject(repoRoot, remoteRef) : null;
|
|
98
131
|
const chosen = priv ?? remote;
|
|
99
132
|
if (chosen === null) {
|
|
100
133
|
return {
|
|
101
134
|
ok: false,
|
|
102
|
-
detail: `
|
|
103
|
-
|
|
104
|
-
'against
|
|
105
|
-
'ref before the run.',
|
|
135
|
+
detail: `the base branch is not in this repository: neither ${PRIVATE_TRUST_BASE_REF} (the ` +
|
|
136
|
+
`composite action's fetch of the base branch) nor ${remoteRef} exists, so there is no base ` +
|
|
137
|
+
'to measure the intent gate against and nothing was checked. Fix: in CI, check out with ' +
|
|
138
|
+
'fetch-depth: 0, or fetch the base ref before the run.',
|
|
106
139
|
};
|
|
107
140
|
}
|
|
108
141
|
return { ok: true, base: { ref: chosen, source: 'github' } };
|
|
@@ -120,11 +153,8 @@ export function currentBranch(repoRoot, env) {
|
|
|
120
153
|
if (fromGithub !== undefined && fromGithub !== '') {
|
|
121
154
|
return fromGithub;
|
|
122
155
|
}
|
|
123
|
-
const child =
|
|
124
|
-
|
|
125
|
-
encoding: 'utf8',
|
|
126
|
-
});
|
|
127
|
-
const value = (child.stdout ?? '').trim();
|
|
156
|
+
const child = runGit(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
|
|
157
|
+
const value = child.stdout.trim();
|
|
128
158
|
if (child.status !== 0 || value === '' || value === 'HEAD') {
|
|
129
159
|
return null;
|
|
130
160
|
}
|
|
@@ -150,7 +180,16 @@ export function currentBranch(repoRoot, env) {
|
|
|
150
180
|
* git error, because an empty path set is indistinguishable from a clean run.
|
|
151
181
|
*/
|
|
152
182
|
export function changedPathsSince(repoRoot, base) {
|
|
153
|
-
|
|
183
|
+
// Refused here, inside the function that calls git, so no caller can skip
|
|
184
|
+
// it: "--output=/x...HEAD" is an option to git diff, not a range.
|
|
185
|
+
if (base.startsWith('-')) {
|
|
186
|
+
return {
|
|
187
|
+
ok: false,
|
|
188
|
+
detail: `refusing "${base}" as the intent gate base: it starts with a dash, so git would read it ` +
|
|
189
|
+
'as an option rather than a ref. Nothing was checked.',
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
const child = runGit(repoRoot, [
|
|
154
193
|
'-c',
|
|
155
194
|
'core.quotePath=false',
|
|
156
195
|
'diff',
|
|
@@ -160,12 +199,14 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
160
199
|
// names no file and which intent-guard refuses outright (backslash).
|
|
161
200
|
'-z',
|
|
162
201
|
'--no-renames',
|
|
163
|
-
//
|
|
164
|
-
//
|
|
165
|
-
//
|
|
166
|
-
'--
|
|
202
|
+
// A moved submodule pointer is a change, and is listed whatever
|
|
203
|
+
// .gitmodules or git config says about ignoring submodules: the command
|
|
204
|
+
// line value overrides both.
|
|
205
|
+
'--ignore-submodules=none',
|
|
167
206
|
`${base}...HEAD`,
|
|
168
|
-
|
|
207
|
+
// Ends the revisions, so the range is always read as a range.
|
|
208
|
+
'--',
|
|
209
|
+
], { maxBuffer: 64 * 1024 * 1024 });
|
|
169
210
|
if (child.error !== undefined) {
|
|
170
211
|
return { ok: false, detail: `git could not be run: ${child.error.message}` };
|
|
171
212
|
}
|
|
@@ -173,57 +214,76 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
173
214
|
// git's own first line usually ends in a full stop, and this message
|
|
174
215
|
// continues after it. Two in a row reads as a typo in a message somebody
|
|
175
216
|
// is already reading because something went wrong.
|
|
176
|
-
const stderr = (
|
|
217
|
+
const stderr = (child.stderr.trim().split('\n')[0] ?? '').replace(/\.+$/, '');
|
|
177
218
|
return {
|
|
178
219
|
ok: false,
|
|
179
220
|
detail: `git could not resolve "${base}...HEAD" (exit ${child.status ?? -1})` +
|
|
180
221
|
`${stderr === '' ? '' : `: ${stderr}`}. ` +
|
|
181
|
-
'In Actions this is usually a shallow checkout with no merge base
|
|
182
|
-
'check out with fetch-depth: 0, or fetch the base ref before the run.',
|
|
222
|
+
'In Actions this is usually a shallow checkout with no merge base. ' +
|
|
223
|
+
'Fix: check out with fetch-depth: 0, or fetch the base ref before the run.',
|
|
183
224
|
};
|
|
184
225
|
}
|
|
185
226
|
// Split on NUL and NOTHING else. Trimming each entry was corrupting a
|
|
186
227
|
// filename with leading or trailing whitespace into a different filename,
|
|
187
228
|
// which is worse than refusing it: the gate would then check a path that
|
|
188
229
|
// does not exist and never check the one that changed.
|
|
189
|
-
const paths =
|
|
230
|
+
const paths = child.stdout.split('\0').filter((line) => line.length > 0);
|
|
231
|
+
return { ok: true, paths };
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* Why this change set cannot be handed to intent-guard as one `--paths`
|
|
235
|
+
* value, or null when it can.
|
|
236
|
+
*
|
|
237
|
+
* Asked only where `--paths` is the channel: a contract imported from a spec
|
|
238
|
+
* (its project is a temporary directory with no repository, so the gate
|
|
239
|
+
* cannot read the change set from git itself) or an intent-guard older than
|
|
240
|
+
* the release whose own `--base` reads the change set from git. Where the
|
|
241
|
+
* gate reads git itself, none of this applies and the change is judged.
|
|
242
|
+
*
|
|
243
|
+
* - A comma: `--paths` is comma-joined, so a comma in a filename arrives as
|
|
244
|
+
* two paths, a phantom that can be reported as outside allowed_paths and a
|
|
245
|
+
* real path that quietly stops being measured against a protected one.
|
|
246
|
+
* - A backslash: intent-guard refuses an explicit path list entry with one.
|
|
247
|
+
* - Leading or trailing whitespace: it cannot survive the list intact.
|
|
248
|
+
* - EVERY path starting with "-": intent-guard reads a `--paths` value that
|
|
249
|
+
* starts with "-" as a missing value, and there is no `--paths=value` form
|
|
250
|
+
* (verified against intent-guard 1.8.0: it is an unknown option). One path
|
|
251
|
+
* starting with "-" is fine once another leads the list
|
|
252
|
+
* (`orderForPathsFlag`), so this is refused only when every path does.
|
|
253
|
+
*
|
|
254
|
+
* A space or any other byte inside a path passes through unchanged.
|
|
255
|
+
*/
|
|
256
|
+
export function pathsFlagRefusal(paths) {
|
|
190
257
|
for (const entry of paths) {
|
|
191
|
-
// Fail closed rather than hand over a path the encoding cannot carry.
|
|
192
|
-
// `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
|
|
193
|
-
// accepts, so a comma in a filename arrives as two paths: a phantom that
|
|
194
|
-
// can be reported as outside allowed_paths, and a real path that quietly
|
|
195
|
-
// stops being measured against a protected one. It invents a breach and
|
|
196
|
-
// hides one, and neither half is visible in the report.
|
|
197
258
|
if (entry.includes(',')) {
|
|
198
|
-
return {
|
|
199
|
-
|
|
200
|
-
detail: `the changed path "${entry}" contains a comma, and the intent gate takes its ` +
|
|
201
|
-
'path list comma-joined, so it cannot be passed without splitting into two paths. ' +
|
|
202
|
-
'Nothing was checked, rather than checking a path that does not exist.',
|
|
203
|
-
};
|
|
259
|
+
return (`the changed path "${entry}" contains a comma, and intent-guard takes an explicit path ` +
|
|
260
|
+
'list comma-joined, so it cannot be passed without splitting into two paths.');
|
|
204
261
|
}
|
|
205
|
-
// intent-guard refuses ANY explicit --paths entry containing a backslash
|
|
206
|
-
// (skill/src/changed-paths.ts, explicitPathIssue: "it contains a
|
|
207
|
-
// backslash"), and exits 2 with a message that names the flag rather than
|
|
208
|
-
// the file. Said here instead, naming the file. A newline, tab or quote
|
|
209
|
-
// inside a path is accepted by intent-guard (it splits on commas only) and
|
|
210
|
-
// passes through intact.
|
|
211
262
|
if (entry.includes('\\')) {
|
|
212
|
-
return {
|
|
213
|
-
|
|
214
|
-
detail: `the changed path "${entry}" contains a backslash, and intent-guard refuses an explicit ` +
|
|
215
|
-
'path list entry with one (--paths), so it cannot judge this change. Nothing was ' +
|
|
216
|
-
'checked. Rename the file, or run the intent gate against the index instead.',
|
|
217
|
-
};
|
|
263
|
+
return (`the changed path "${entry}" contains a backslash, and intent-guard refuses an explicit ` +
|
|
264
|
+
'path list entry with one.');
|
|
218
265
|
}
|
|
219
266
|
if (entry !== entry.trim()) {
|
|
220
|
-
return {
|
|
221
|
-
|
|
222
|
-
detail: `the changed path "${entry}" has leading or trailing whitespace, which cannot ` +
|
|
223
|
-
'survive the gate path list intact. Nothing was checked, rather than checking a ' +
|
|
224
|
-
'path that does not exist. A space inside a path is fine.',
|
|
225
|
-
};
|
|
267
|
+
return (`the changed path "${entry}" has leading or trailing whitespace, which cannot survive ` +
|
|
268
|
+
'the path list intact. A space inside a path is fine.');
|
|
226
269
|
}
|
|
227
270
|
}
|
|
228
|
-
|
|
271
|
+
if (paths.length > 0 && paths.every((entry) => entry.startsWith('-'))) {
|
|
272
|
+
return (`every changed path starts with "-" (the first is "${paths[0]}"), and intent-guard reads ` +
|
|
273
|
+
'a path list that starts with "-" as a missing value.');
|
|
274
|
+
}
|
|
275
|
+
return null;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* The change set in the order it is joined for `--paths`: unchanged, except
|
|
279
|
+
* that when the first path starts with "-" the first path that does not is
|
|
280
|
+
* moved to the front, so the joined value does not start with "-". Order
|
|
281
|
+
* carries no meaning to the gate.
|
|
282
|
+
*/
|
|
283
|
+
export function orderForPathsFlag(paths) {
|
|
284
|
+
const lead = paths.findIndex((entry) => !entry.startsWith('-'));
|
|
285
|
+
if (paths.length === 0 || !paths[0].startsWith('-') || lead === -1) {
|
|
286
|
+
return [...paths];
|
|
287
|
+
}
|
|
288
|
+
return [paths[lead], ...paths.slice(0, lead), ...paths.slice(lead + 1)];
|
|
229
289
|
}
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -41,11 +41,16 @@ export type ContractSource =
|
|
|
41
41
|
kind: 'native';
|
|
42
42
|
path: string;
|
|
43
43
|
}
|
|
44
|
-
/**
|
|
44
|
+
/**
|
|
45
|
+
* A spec imported and frozen for this run only. Repository-relative paths.
|
|
46
|
+
* `ref` is set on a run with a trust base: the spec and plan were read from
|
|
47
|
+
* that ref, never from the tree being judged.
|
|
48
|
+
*/
|
|
45
49
|
| {
|
|
46
50
|
kind: 'imported';
|
|
47
51
|
spec: string;
|
|
48
52
|
plan: string | null;
|
|
53
|
+
ref?: string;
|
|
49
54
|
} | {
|
|
50
55
|
kind: 'none';
|
|
51
56
|
};
|
|
@@ -54,13 +59,32 @@ export interface IntentPreparation {
|
|
|
54
59
|
/** The ref the change set was measured against, or null for a staged run. */
|
|
55
60
|
baseRef: string | null;
|
|
56
61
|
/** Whether that ref was asked for or inferred from the CI environment. */
|
|
57
|
-
baseSource: 'flag' | 'github' | null;
|
|
62
|
+
baseSource: 'flag' | 'github' | 'trust-base' | null;
|
|
58
63
|
/** What to hand the gate as --project: "." or an absolute temporary path. */
|
|
59
64
|
projectDir: string;
|
|
60
65
|
/** The changed paths, or null to leave v0.1's staged behaviour alone. */
|
|
61
66
|
paths: string[] | null;
|
|
62
67
|
/** Removes anything written outside the repository. Safe to call twice. */
|
|
63
68
|
cleanup: () => void;
|
|
69
|
+
/**
|
|
70
|
+
* On a run with a trust base: intent control files this pull request adds
|
|
71
|
+
* or changes that did not decide this run, one line each. Reported as
|
|
72
|
+
* proposals, never acted on.
|
|
73
|
+
*/
|
|
74
|
+
proposals?: string[];
|
|
75
|
+
/**
|
|
76
|
+
* One plain sentence the report prints under the contract line, for an
|
|
77
|
+
* input the person gave that this run did not use: --spec, when the base's
|
|
78
|
+
* frozen contract outranks it.
|
|
79
|
+
*/
|
|
80
|
+
note?: string;
|
|
81
|
+
/**
|
|
82
|
+
* Why `paths` cannot be handed over as one --paths value (pathsFlagRefusal
|
|
83
|
+
* in intent-base.ts), on a native contract. The runner then uses the
|
|
84
|
+
* gate's own --base where the gate has it, and refuses with this reason
|
|
85
|
+
* where it does not.
|
|
86
|
+
*/
|
|
87
|
+
pathsRefusal?: string;
|
|
64
88
|
}
|
|
65
89
|
/** Which link of the chain broke. Carried into the report verbatim. */
|
|
66
90
|
export type PrepareStep = 'spec' | 'base'
|
|
@@ -90,6 +114,8 @@ export type IntentPrepareResult = {
|
|
|
90
114
|
kind: 'skip';
|
|
91
115
|
reason: 'no-contract' | 'contract-waived';
|
|
92
116
|
detail: string;
|
|
117
|
+
/** As on IntentPreparation: what this pull request proposes. */
|
|
118
|
+
proposals?: string[];
|
|
93
119
|
} | {
|
|
94
120
|
kind: 'failed';
|
|
95
121
|
step: PrepareStep;
|
|
@@ -102,6 +128,11 @@ export interface IntentPrepareOptions {
|
|
|
102
128
|
env: NodeJS.ProcessEnv;
|
|
103
129
|
base?: string;
|
|
104
130
|
spec?: string;
|
|
131
|
+
/**
|
|
132
|
+
* The trust base, on a pull-request run. The change set is measured from
|
|
133
|
+
* it when no --base and no GITHUB_BASE_REF names another base.
|
|
134
|
+
*/
|
|
135
|
+
trustBase?: string;
|
|
105
136
|
timeoutMs?: number;
|
|
106
137
|
/**
|
|
107
138
|
* The directory the per-run temporary project is created under.
|