@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.
Files changed (44) hide show
  1. package/README.md +263 -77
  2. package/dist/cli.js +152 -30
  3. package/dist/envelope.d.ts +8 -0
  4. package/dist/exit-codes.d.ts +52 -2
  5. package/dist/exit-codes.js +64 -14
  6. package/dist/external-config.d.ts +2 -1
  7. package/dist/external-config.js +33 -18
  8. package/dist/gate-runner.d.ts +141 -17
  9. package/dist/gate-runner.js +537 -83
  10. package/dist/git.d.ts +95 -0
  11. package/dist/git.js +244 -0
  12. package/dist/init-policy.js +38 -2
  13. package/dist/init.js +40 -3
  14. package/dist/intent-base.d.ts +35 -1
  15. package/dist/intent-base.js +124 -64
  16. package/dist/intent-prepare.d.ts +33 -2
  17. package/dist/intent-prepare.js +443 -34
  18. package/dist/intent-spec.d.ts +28 -0
  19. package/dist/intent-spec.js +22 -5
  20. package/dist/normalize.d.ts +11 -0
  21. package/dist/normalize.js +60 -6
  22. package/dist/osv-baseline.d.ts +84 -0
  23. package/dist/osv-baseline.js +325 -0
  24. package/dist/osv-coverage.d.ts +80 -0
  25. package/dist/osv-coverage.js +223 -0
  26. package/dist/output-sarif.js +55 -15
  27. package/dist/output-text.d.ts +53 -2
  28. package/dist/output-text.js +287 -27
  29. package/dist/policy.d.ts +10 -0
  30. package/dist/policy.js +21 -7
  31. package/dist/products.d.ts +32 -10
  32. package/dist/products.js +73 -9
  33. package/dist/requirements-pin.d.ts +47 -0
  34. package/dist/requirements-pin.js +256 -0
  35. package/dist/resolve.d.ts +1 -0
  36. package/dist/resolve.js +1 -1
  37. package/dist/run.d.ts +21 -0
  38. package/dist/run.js +74 -15
  39. package/dist/trust-base.d.ts +101 -20
  40. package/dist/trust-base.js +219 -73
  41. package/dist/unread-manifests.d.ts +14 -0
  42. package/dist/unread-manifests.js +69 -0
  43. package/package.json +1 -1
  44. package/schema/guardrails.schema.json +4 -0
package/dist/products.js CHANGED
@@ -8,17 +8,27 @@
8
8
  // did before profiles existed; changing one of them changes a gate that
9
9
  // adopters already run.
10
10
  /**
11
- * The lockfiles osv-scanner is handed, matched by base name at any depth
12
- * among the repository's TRACKED files (`git ls-files`).
11
+ * The lockfiles osv-scanner is handed as a bare path, matched by base name at
12
+ * any depth among the repository's TRACKED files (`git ls-files`).
13
13
  *
14
14
  * By name, not by walking the tree, for three reasons: osv-scanner's own walk
15
15
  * skips anything .gitignore matches, tracked or not, so a pull request could
16
16
  * hide a committed lockfile from it with one ignore line; the walk can reach
17
17
  * into node_modules; and an untracked lockfile is not part of what is being
18
- * judged. Only the npm family is listed, because that is the ecosystem this
19
- * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
20
- * supports more, and a repository whose only lockfile is another ecosystem's
21
- * gets nothing-to-scan until a name is added here.
18
+ * judged.
19
+ *
20
+ * Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
21
+ * (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
22
+ * rejects it ("could not determine extractor", exit 127), which would make
23
+ * every Go pull request could-not-run, and go.mod is what it reads for Go.
24
+ *
25
+ * The second group was added on 2026-10-13 (audit finding F3: a tracked
26
+ * mix.lock was neither scanned nor named), each measured the same way
27
+ * against 2.4.0 and read with one or more packages. Measured and NOT added,
28
+ * because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
29
+ * named by the unread-manifests note instead). gradle's
30
+ * verification-metadata.xml is read only inside a `gradle` directory and is
31
+ * matched by `osvLockfileKind` rather than listed here.
22
32
  */
23
33
  export const OSV_LOCKFILE_NAMES = [
24
34
  'package-lock.json',
@@ -26,7 +36,61 @@ export const OSV_LOCKFILE_NAMES = [
26
36
  'pnpm-lock.yaml',
27
37
  'yarn.lock',
28
38
  'bun.lock',
39
+ 'go.mod',
40
+ 'poetry.lock',
41
+ 'Pipfile.lock',
42
+ 'uv.lock',
43
+ 'pdm.lock',
44
+ 'Cargo.lock',
45
+ 'Gemfile.lock',
46
+ 'composer.lock',
47
+ 'gradle.lockfile',
48
+ 'packages.lock.json',
49
+ 'mix.lock',
50
+ 'pubspec.lock',
51
+ 'Package.resolved',
52
+ 'conan.lock',
53
+ 'renv.lock',
54
+ 'packages.config',
55
+ 'buildscript-gradle.lockfile',
56
+ 'gems.locked',
57
+ 'pylock.toml',
58
+ 'cabal.project.freeze',
59
+ 'stack.yaml.lock',
60
+ ];
61
+ /** gradle's dependency verification file, which 2.4.0 reads only under a `gradle` directory. */
62
+ const GRADLE_VERIFICATION_METADATA = 'verification-metadata.xml';
63
+ /**
64
+ * pip requirements files, by base name: requirements.txt itself,
65
+ * requirements-dev.txt and its _ and . spellings, and dev-requirements.txt.
66
+ * Not requirements.in (pip-tools input, unpinned by design), not constraints
67
+ * files, and not a file under a requirements/ directory whose own name does
68
+ * not match. A requirements file is handed over only when every requirement
69
+ * in it, and in every file it includes, is pinned with == (the pin check).
70
+ */
71
+ const REQUIREMENTS_PATTERNS = [
72
+ /^requirements\.txt$/,
73
+ /^requirements[-_.][A-Za-z0-9._-]+\.txt$/,
74
+ /^[A-Za-z0-9._-]+[-_]requirements\.txt$/,
29
75
  ];
76
+ /**
77
+ * What osv-scanner is handed for a tracked file, or null. Takes the
78
+ * repository-relative path (a bare base name works for every name but one):
79
+ * gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
80
+ * its parent directory is `gradle`, and anywhere else it exits 127, so the
81
+ * parent is part of the match for that one file.
82
+ */
83
+ export function osvLockfileKind(file) {
84
+ const segments = file.split('/');
85
+ const basename = segments[segments.length - 1] ?? '';
86
+ if (basename === GRADLE_VERIFICATION_METADATA) {
87
+ return segments[segments.length - 2] === 'gradle' ? 'bare' : null;
88
+ }
89
+ if (OSV_LOCKFILE_NAMES.includes(basename)) {
90
+ return 'bare';
91
+ }
92
+ return REQUIREMENTS_PATTERNS.some((pattern) => pattern.test(basename)) ? 'requirements' : null;
93
+ }
30
94
  /**
31
95
  * The npm gates print a bare version. No capture group on purpose: the runner
32
96
  * has always reported the whole first line minus a leading v, prerelease
@@ -55,7 +119,7 @@ function managedProfile(product) {
55
119
  ignoreFile: null,
56
120
  remedy: managedRemedy(product),
57
121
  stderrError: null,
58
- lockfileNames: null,
122
+ lockfileMatcher: null,
59
123
  followsConfigExtend: false,
60
124
  readsHistory: false,
61
125
  };
@@ -93,7 +157,7 @@ const PROFILES = {
93
157
  // gitleaks 8.30.1 swallows a git failure: it logs "<time> ERR [git]
94
158
  // fatal: ..." and exits 0 with an empty report (tests/fixtures/README.md).
95
159
  stderrError: /^\S+\s+ERR\s/,
96
- lockfileNames: null,
160
+ lockfileMatcher: null,
97
161
  followsConfigExtend: true,
98
162
  // gitleaks reads git history (--log-opts), never the tree, which is
99
163
  // exactly what makes it the one gate an equal-tree pull request does not
@@ -120,7 +184,7 @@ const PROFILES = {
120
184
  // osv-scanner's exit codes separate an error (127) from a verdict, and
121
185
  // its stderr is progress chatter, so the exit is taken at its word.
122
186
  stderrError: null,
123
- lockfileNames: OSV_LOCKFILE_NAMES,
187
+ lockfileMatcher: osvLockfileKind,
124
188
  followsConfigExtend: false,
125
189
  // osv-scanner reads the tracked lockfiles it is handed, which are the
126
190
  // tree being judged, not history.
@@ -0,0 +1,47 @@
1
+ /** One file the check asked for: its text, or why there is none. */
2
+ export type IncludeRead = {
3
+ kind: 'file';
4
+ text: string;
5
+ } | {
6
+ kind: 'missing';
7
+ why: string;
8
+ };
9
+ export interface PinProblem {
10
+ /** The file the problem is in, repository-relative. */
11
+ file: string;
12
+ /** The physical line a logical line starts on; null for a problem with an include itself. */
13
+ line: number | null;
14
+ /** The logical line as written, cleaned for printing; for an include, the path as written. */
15
+ text: string;
16
+ kind: 'unpinned' | 'arbitrary-equality' | 'unrecognised' | 'include';
17
+ /** For an include: why it cannot be read ("which is outside the repository"). */
18
+ why?: string;
19
+ }
20
+ export interface PinCheck {
21
+ pinned: boolean;
22
+ /** Every file read, the top file first, repository-relative. */
23
+ files: string[];
24
+ /** Direct references (-e, paths, URLs, name @ url) left out of the check. */
25
+ excluded: number;
26
+ problems: PinProblem[];
27
+ /** Why the top file itself could not be read, or null when it was. */
28
+ topMissing: string | null;
29
+ }
30
+ /** The deepest include chain followed. A deeper one leaves the top file unscanned. */
31
+ export declare const MAX_INCLUDE_DEPTH = 8;
32
+ /**
33
+ * Checks one requirements file and everything it includes.
34
+ *
35
+ * `read` is asked for each file by repository-relative path and decides what
36
+ * "there" means: on the head, a tracked regular file on disk; on the base,
37
+ * the blob at the trust base. Every problem is collected, not only the first,
38
+ * so the ratchet's diagnostic can name each unpinned line; `pinned` is true
39
+ * only when there are none.
40
+ */
41
+ export declare function checkRequirementsPins(top: string, read: (file: string) => IncludeRead): PinCheck;
42
+ /**
43
+ * One problem as the reason clause of a diagnostic about `top`, with no
44
+ * trailing full stop: `line 4 "flask>=2.0" is not pinned with ==, so any
45
+ * version osv-scanner reported would be a guess`.
46
+ */
47
+ export declare function describePinProblem(top: string, problem: PinProblem): string;
@@ -0,0 +1,256 @@
1
+ // The pin check for pip requirements files.
2
+ //
3
+ // osv-scanner reads a requirements file as a list of packages at the versions
4
+ // written in it. A line pinned with == names one version, and an advisory
5
+ // against that version is a statement about what this repository installs.
6
+ // Any other line (>=, ~=, a range, no version at all) names a set of versions,
7
+ // and whatever osv-scanner reports for it is a guess: with its default
8
+ // resolution it is the registry's latest, with --no-resolve it is the lower
9
+ // bound. So a requirements file is handed over only when every requirement in
10
+ // it, and in every file it includes with -r, is pinned with ==.
11
+ //
12
+ // This SELECTS what the tool is handed, like the basename list beside it in
13
+ // src/products.ts, and raises no finding of its own: a file left out is named
14
+ // on the coverage line with the line that stopped it (src/gate-runner.ts).
15
+ //
16
+ // Includes are followed here rather than left to osv-scanner, because
17
+ // osv-scanner 2.4.0 follows -r and swallows a missing include (one stderr
18
+ // line, the rest scanned, exit decided by what it did read): a top file whose
19
+ // include is absent would be scanned and silently under-read. It resolves an
20
+ // include relative to the including file's directory and survives a cycle,
21
+ // and so does this.
22
+ import path from 'node:path';
23
+ /** The deepest include chain followed. A deeper one leaves the top file unscanned. */
24
+ export const MAX_INCLUDE_DEPTH = 8;
25
+ /** Options that take a value and say nothing about which packages are installed. */
26
+ const IGNORED_WITH_VALUE = [
27
+ '-c',
28
+ '--constraint',
29
+ '-i',
30
+ '--index-url',
31
+ '--extra-index-url',
32
+ '-f',
33
+ '--find-links',
34
+ '--trusted-host',
35
+ '--only-binary',
36
+ '--no-binary',
37
+ '--use-feature',
38
+ ];
39
+ /** Flags with no value that say nothing about which packages are installed. */
40
+ const IGNORED_FLAGS = ['--pre', '--prefer-binary', '--require-hashes'];
41
+ const NAME = '[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?';
42
+ const EXTRAS = '\\[[^\\]]*\\]';
43
+ const REQUIREMENT = new RegExp(`^(${NAME})\\s*(${EXTRAS})?\\s*(.*)$`);
44
+ const NAME_AT_URL = new RegExp(`^${NAME}\\s*(${EXTRAS})?\\s*@\\s*\\S`);
45
+ const URL = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
46
+ const HASH_OPTION = /\s+--hash(?:=|\s+)\S+/g;
47
+ function logicalLines(text) {
48
+ const physical = text.split(/\r?\n/);
49
+ const out = [];
50
+ let buffer = null;
51
+ let start = 0;
52
+ const flush = () => {
53
+ if (buffer === null) {
54
+ return;
55
+ }
56
+ // A # that starts the line or follows whitespace starts a comment; one
57
+ // inside a token (a URL fragment, #egg=) does not.
58
+ const stripped = buffer.replace(/(^|\s)#.*$/, '').trim();
59
+ if (stripped !== '') {
60
+ out.push({ line: start, text: stripped });
61
+ }
62
+ buffer = null;
63
+ };
64
+ for (const [index, raw] of physical.entries()) {
65
+ if (buffer === null) {
66
+ buffer = '';
67
+ start = index + 1;
68
+ }
69
+ if (raw.endsWith('\\')) {
70
+ buffer += `${raw.slice(0, -1)} `;
71
+ continue;
72
+ }
73
+ buffer += raw;
74
+ flush();
75
+ }
76
+ flush();
77
+ return out;
78
+ }
79
+ /** Splits a leading option into its name and value: "-rfoo", "-r foo", "--x=foo", "--x foo". */
80
+ function option(text) {
81
+ const long = /^(--[A-Za-z0-9-]+)(?:=|\s+|$)(.*)$/.exec(text);
82
+ if (long !== null) {
83
+ return { name: long[1], value: long[2].trim() };
84
+ }
85
+ const short = /^(-[A-Za-z])\s*(.*)$/.exec(text);
86
+ if (short !== null) {
87
+ return { name: short[1], value: short[2].trim() };
88
+ }
89
+ return null;
90
+ }
91
+ /** Printable, one line, no double quotes, capped: the line goes into a report. */
92
+ function printable(text) {
93
+ const flat = text.replace(/[^\x20-\x7e]/g, '?').replace(/"/g, "'");
94
+ return flat.length > 120 ? `${flat.slice(0, 117)}...` : flat;
95
+ }
96
+ function isDirectReference(text) {
97
+ if (URL.test(text) || NAME_AT_URL.test(text)) {
98
+ return true;
99
+ }
100
+ // A local path: anything that starts like one or has a path separator in
101
+ // the part before a version specifier, or names an archive.
102
+ const head = text.split(/[\s;=<>!~]/)[0] ?? '';
103
+ return (head.startsWith('.') ||
104
+ head.startsWith('/') ||
105
+ head.startsWith('~') ||
106
+ head.includes('/') ||
107
+ head.includes('\\') ||
108
+ /\.(whl|zip|tar\.gz|tgz|tar\.bz2)$/i.test(head));
109
+ }
110
+ function classify(text) {
111
+ if (text.startsWith('-')) {
112
+ const opt = option(text);
113
+ if (opt === null) {
114
+ return { kind: 'unrecognised' };
115
+ }
116
+ if (opt.name === '-r' || opt.name === '--requirement') {
117
+ return opt.value === '' ? { kind: 'unrecognised' } : { kind: 'include', target: opt.value };
118
+ }
119
+ if (opt.name === '-e' || opt.name === '--editable') {
120
+ return { kind: 'excluded' };
121
+ }
122
+ if (IGNORED_WITH_VALUE.includes(opt.name) && opt.value !== '') {
123
+ return { kind: 'ignored' };
124
+ }
125
+ if (IGNORED_FLAGS.includes(opt.name) && opt.value === '') {
126
+ return { kind: 'ignored' };
127
+ }
128
+ return { kind: 'unrecognised' };
129
+ }
130
+ if (isDirectReference(text)) {
131
+ return { kind: 'excluded' };
132
+ }
133
+ // Hash options may follow a requirement; nothing else may.
134
+ const withoutHashes = text.replace(HASH_OPTION, '');
135
+ const [spec = '', ...marker] = withoutHashes.split(';');
136
+ if (marker.join(';').includes(' --') || /\s--?[A-Za-z]/.test(spec)) {
137
+ return { kind: 'unrecognised' };
138
+ }
139
+ const match = REQUIREMENT.exec(spec.trim());
140
+ if (match === null) {
141
+ return { kind: 'unrecognised' };
142
+ }
143
+ const specifier = match[3].trim();
144
+ if (specifier.startsWith('===')) {
145
+ return { kind: 'arbitrary-equality' };
146
+ }
147
+ if (/^==\s*[^\s,=<>!~*$;]+$/.test(specifier)) {
148
+ return { kind: 'pinned' };
149
+ }
150
+ if (specifier === '' || /^[=<>!~]/.test(specifier)) {
151
+ return { kind: 'unpinned' };
152
+ }
153
+ return { kind: 'unrecognised' };
154
+ }
155
+ /**
156
+ * Checks one requirements file and everything it includes.
157
+ *
158
+ * `read` is asked for each file by repository-relative path and decides what
159
+ * "there" means: on the head, a tracked regular file on disk; on the base,
160
+ * the blob at the trust base. Every problem is collected, not only the first,
161
+ * so the ratchet's diagnostic can name each unpinned line; `pinned` is true
162
+ * only when there are none.
163
+ */
164
+ export function checkRequirementsPins(top, read) {
165
+ const files = [];
166
+ const problems = [];
167
+ let excluded = 0;
168
+ let topMissing = null;
169
+ const visited = new Set();
170
+ const visit = (file, depth, from, written) => {
171
+ if (visited.has(file)) {
172
+ return;
173
+ }
174
+ if (depth > MAX_INCLUDE_DEPTH) {
175
+ problems.push({
176
+ file: from ?? file,
177
+ line: null,
178
+ text: written,
179
+ kind: 'include',
180
+ why: `more than ${MAX_INCLUDE_DEPTH} includes deep`,
181
+ });
182
+ return;
183
+ }
184
+ visited.add(file);
185
+ const got = read(file);
186
+ if (got.kind === 'missing') {
187
+ // For the top file itself the sentence would read "includes
188
+ // requirements.txt, which ...", which no caller prints: the head copy
189
+ // is a tracked file, and callers of a base check read topMissing.
190
+ if (from === null) {
191
+ topMissing = got.why;
192
+ }
193
+ problems.push({ file: from ?? file, line: null, text: written, kind: 'include', why: `which ${got.why}` });
194
+ return;
195
+ }
196
+ files.push(file);
197
+ for (const logical of logicalLines(got.text)) {
198
+ const verdict = classify(logical.text);
199
+ switch (verdict.kind) {
200
+ case 'pinned':
201
+ case 'ignored':
202
+ break;
203
+ case 'excluded':
204
+ excluded += 1;
205
+ break;
206
+ case 'include': {
207
+ const target = verdict.target;
208
+ const fail = (why) => {
209
+ problems.push({ file, line: null, text: printable(target), kind: 'include', why });
210
+ };
211
+ if (URL.test(target)) {
212
+ fail('which is a URL');
213
+ break;
214
+ }
215
+ if (path.posix.isAbsolute(target) || path.win32.isAbsolute(target)) {
216
+ fail('which is an absolute path');
217
+ break;
218
+ }
219
+ const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), target));
220
+ if (resolved === '..' || resolved.startsWith('../')) {
221
+ fail('which is outside the repository');
222
+ break;
223
+ }
224
+ visit(resolved, depth + 1, file, printable(target));
225
+ break;
226
+ }
227
+ default:
228
+ problems.push({ file, line: logical.line, text: printable(logical.text), kind: verdict.kind });
229
+ }
230
+ }
231
+ };
232
+ visit(top, 0, null, top);
233
+ return { pinned: problems.length === 0, files, excluded, problems, topMissing };
234
+ }
235
+ /**
236
+ * One problem as the reason clause of a diagnostic about `top`, with no
237
+ * trailing full stop: `line 4 "flask>=2.0" is not pinned with ==, so any
238
+ * version osv-scanner reported would be a guess`.
239
+ */
240
+ export function describePinProblem(top, problem) {
241
+ const guess = 'so any version osv-scanner reported would be a guess';
242
+ const where = problem.file === top ? '' : ` of ${problem.file}`;
243
+ switch (problem.kind) {
244
+ case 'unpinned':
245
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is not pinned with ==, ${guess}`;
246
+ case 'arbitrary-equality':
247
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is pinned with ===, not ==, ${guess}`;
248
+ case 'unrecognised':
249
+ return (`line ${problem.line ?? '?'}${where} "${problem.text}" is not a line conductor recognises, ` +
250
+ 'so it cannot tell what osv-scanner would read there');
251
+ case 'include': {
252
+ const from = problem.file === top ? '' : ` (from ${problem.file})`;
253
+ return `includes ${problem.text}${from}, ${problem.why ?? 'which could not be read'}`;
254
+ }
255
+ }
256
+ }
package/dist/resolve.d.ts CHANGED
@@ -55,6 +55,7 @@ export interface ResolveOptions {
55
55
  export declare class ResolveError extends Error {
56
56
  constructor(message: string);
57
57
  }
58
+ export declare function findOnPath(name: string, pathValue: string): string | null;
58
59
  /**
59
60
  * The node_modules/.bin candidate a pull-request run declined to take.
60
61
  *
package/dist/resolve.js CHANGED
@@ -106,7 +106,7 @@ function existsAsFile(candidate) {
106
106
  return false;
107
107
  }
108
108
  }
109
- function findOnPath(name, pathValue) {
109
+ export function findOnPath(name, pathValue) {
110
110
  for (const dir of pathValue.split(path.delimiter)) {
111
111
  if (dir.length === 0) {
112
112
  continue;
package/dist/run.d.ts CHANGED
@@ -137,11 +137,31 @@ export interface RunTrustBase {
137
137
  * instead of being spawned.
138
138
  */
139
139
  treeUnchanged?: boolean;
140
+ /**
141
+ * True on the refusal for a pull-request job that gave no trust base at
142
+ * all (GITHUB_ACTIONS and GITHUB_BASE_REF set, no --trust-base). `ref` is
143
+ * then empty, and the reports say no trust base was given and no rules
144
+ * were read, rather than naming a ref.
145
+ */
146
+ notGiven?: boolean;
147
+ }
148
+ /**
149
+ * A gate the policy file declares with `enabled: false`. Listed so an adopter
150
+ * sees what is off; it is not a GateOutcome, nothing was looked for or run.
151
+ */
152
+ export interface DisabledGate {
153
+ role: GateRole;
154
+ product: Product;
140
155
  }
141
156
  export interface RunResult {
142
157
  schemaVersion: 1;
143
158
  generatedAt: string;
144
159
  gates: GateOutcome[];
160
+ /**
161
+ * Gates the policy file declares with `enabled: false`. A gate the --gate
162
+ * flag left out is in `excluded` instead. Absent counts as none.
163
+ */
164
+ disabled?: DisabledGate[];
145
165
  /** Enabled gates the requested stage held back. Empty with no --stage. */
146
166
  deferred: DeferredGate[];
147
167
  /** Enabled gates that ran at this stage and found nothing to check. */
@@ -242,5 +262,6 @@ export interface RunOptions {
242
262
  export declare function refusedTrustBase(policy: Policy, ref: string, detail: string, options: {
243
263
  stage?: GateStage;
244
264
  now?: () => Date;
265
+ notGiven?: boolean;
245
266
  }): RunResult;
246
267
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;
package/dist/run.js CHANGED
@@ -1,6 +1,6 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
- import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
3
+ import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
4
  import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
@@ -11,15 +11,21 @@ import { POLICY_PROPOSAL_LINE } from './trust-base.js';
11
11
  /**
12
12
  * Whether this run is the pull-request shaped one.
13
13
  *
14
- * The whole intent-at-pull-request flow engages on a resolved base ref or an
15
- * explicit `--spec`, and on nothing else. Without one of those, the intent
16
- * gate keeps exactly the command line v0.1 gave it: a developer running
17
- * `conductor run` on their own machine has not asked for a contract to be
18
- * imported, and importing one anyway would change what a local run means
19
- * without anybody having written that down.
14
+ * The whole intent-at-pull-request flow engages on a trust base, a resolved
15
+ * base ref or an explicit `--spec`, and on nothing else. Without one of
16
+ * those, the intent gate keeps exactly the command line v0.1 gave it: a
17
+ * developer running `conductor run` on their own machine has not asked for a
18
+ * contract to be imported, and importing one anyway would change what a
19
+ * local run means without anybody having written that down.
20
+ *
21
+ * A TRUST BASE ALWAYS MAKES THE RUN PULL-REQUEST SHAPED, with or without a
22
+ * base ref or GITHUB_BASE_REF (merge_group, workflow_dispatch and any CLI
23
+ * run that passes --trust-base alone). A run with a trust base is always
24
+ * judged as a pull request against that base: the change set is measured
25
+ * from it.
20
26
  */
21
27
  function isPullRequestShaped(options, env) {
22
- if (options.spec !== undefined) {
28
+ if (options.spec !== undefined || options.trustBase !== undefined) {
23
29
  return true;
24
30
  }
25
31
  return resolveBaseRef({ ...(options.base === undefined ? {} : { base: options.base }), env }) !== null;
@@ -76,6 +82,12 @@ function partitionGates(policy, requested) {
76
82
  .map((gate) => ({ role: gate.role, product: gate.product }));
77
83
  return { gates, deferred, excluded };
78
84
  }
85
+ /** Declared in the policy file with enabled: false, in role order. */
86
+ function disabledGates(policy) {
87
+ return GATE_ROLES.map((role) => policy.gates[role])
88
+ .filter((gate) => gate !== undefined && !gate.enabled && !gate.excludedByCli)
89
+ .map((gate) => ({ role: gate.role, product: gate.product }));
90
+ }
79
91
  /**
80
92
  * The run that never happened, because the trust base could not be judged
81
93
  * against.
@@ -124,7 +136,12 @@ export function refusedTrustBase(policy, ref, detail, options) {
124
136
  // thing that could not be read. False rather than a third state, because
125
137
  // no proposal is reported on a run where nothing was judged. The refusal
126
138
  // itself is carried, and it is what both renderers lead with.
127
- trustBase: { ref, policyChanged: false, refusal: detail },
139
+ trustBase: {
140
+ ref,
141
+ policyChanged: false,
142
+ refusal: detail,
143
+ ...(options.notGiven === true ? { notGiven: true } : {}),
144
+ },
128
145
  proposals: [],
129
146
  summary: {
130
147
  blocking: findings.filter((finding) => finding.blocking).length,
@@ -142,11 +159,19 @@ export function refusedTrustBase(policy, ref, detail, options) {
142
159
  * proposing to change which gates run at all, and reading that after a gate's
143
160
  * own contract line would bury it.
144
161
  */
145
- function collectProposals(outcomes, trustBase) {
162
+ function collectProposals(outcomes, trustBase,
163
+ /**
164
+ * The intent gate's own control files this pull request adds or changes,
165
+ * observed while preparing it from the base ref (a contract or spec the
166
+ * base does not carry yet, an edit to the imported spec). They arrive here
167
+ * whether the gate then ran or was skipped.
168
+ */
169
+ preparation = []) {
146
170
  const proposals = [];
147
171
  if (trustBase?.policyChanged === true) {
148
172
  proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
149
173
  }
174
+ proposals.push(...preparation);
150
175
  for (const outcome of outcomes) {
151
176
  for (const line of outcome.trustBase?.proposals ?? []) {
152
177
  proposals.push({ product: outcome.product, role: outcome.role, line });
@@ -198,11 +223,32 @@ function splitOnTreeUnchanged(gates, trustBase) {
198
223
  }
199
224
  return { toRun, treeUnchanged };
200
225
  }
226
+ /**
227
+ * The environment variables the Action sets to say which version of each
228
+ * family gate it pinned, read only to warn when a gate resolved from PATH
229
+ * reports a different one. Not a control input: nothing about resolution or
230
+ * the verdict reads them, so a run that sets them wrongly gets a wrong warning
231
+ * and nothing else.
232
+ */
233
+ const EXPECTED_VERSION_ENV = {
234
+ 'dep-guard': 'CONDUCTOR_EXPECTED_DEP_GUARD_VERSION',
235
+ 'vault-guard': 'CONDUCTOR_EXPECTED_VAULT_GUARD_VERSION',
236
+ 'intent-guard': 'CONDUCTOR_EXPECTED_INTENT_GUARD_VERSION',
237
+ };
238
+ /** The `expectedVersion` option for one gate, or nothing. Exact versions only. */
239
+ function expectedVersionOption(product, env) {
240
+ const name = EXPECTED_VERSION_ENV[product];
241
+ const value = name === undefined ? undefined : env[name];
242
+ return value !== undefined && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(value)
243
+ ? { expectedVersion: value }
244
+ : {};
245
+ }
201
246
  export function runAll(policy, options) {
202
247
  const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
203
248
  const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
204
249
  const env = options.env ?? {};
205
250
  const skipped = [];
251
+ const preparationProposals = [];
206
252
  const cleanups = [];
207
253
  // Sequential, not concurrent. Three Node process starts is real overhead
208
254
  // in a pre-commit hook and running them at once would hide most of it,
@@ -243,7 +289,16 @@ export function runAll(policy, options) {
243
289
  ...(options.spec === undefined ? {} : { spec: options.spec }),
244
290
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
245
291
  ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
292
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
246
293
  });
294
+ const proposed = prepared.kind === 'skip'
295
+ ? prepared.proposals
296
+ : prepared.kind === 'ready'
297
+ ? prepared.preparation.proposals
298
+ : undefined;
299
+ for (const line of proposed ?? []) {
300
+ preparationProposals.push({ product: gate.product, role: gate.role, line });
301
+ }
247
302
  if (prepared.kind === 'skip') {
248
303
  skipped.push({
249
304
  role: gate.role,
@@ -275,15 +330,16 @@ export function runAll(policy, options) {
275
330
  pathValue: options.pathValue,
276
331
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
277
332
  ...(intent === undefined ? {} : { intent }),
333
+ ...expectedVersionOption(gate.product, env),
278
334
  // For a run with no preparation: which contract the child will read
279
335
  // out of the repository itself. Looked up only for the gate it is
280
336
  // about, so no other gate pays for the two stat calls.
281
337
  ...(intent !== undefined || gate.role !== 'intent'
282
338
  ? {}
283
339
  : nativeContractOption(options.repoRoot)),
284
- // Offered to every child. runGate decides which ones can take it,
285
- // so a gate with no pull-request mode yet is not handed a flag it
286
- // would reject, and the reason it was withheld is on the outcome.
340
+ // Offered to every child. runGate decides which ones take it: a
341
+ // gate below its pull-request-mode minimum is could-not-run, and a
342
+ // gate it is withheld from carries the reason on the outcome.
287
343
  ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
288
344
  // Where an external gate's working directory goes (its report file,
289
345
  // its config from the base ref). The runner removes what it makes.
@@ -310,7 +366,7 @@ export function runAll(policy, options) {
310
366
  }
311
367
  const exitCode = composeExitCode(outcomes.map((outcome) => ({
312
368
  couldNotRun: outcome.couldNotRun,
313
- exitCode: outcome.exitCode,
369
+ exitBlocks: gateExitBlocks(outcome),
314
370
  hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
315
371
  enforce: outcome.enforce,
316
372
  })));
@@ -318,13 +374,16 @@ export function runAll(policy, options) {
318
374
  schemaVersion: 1,
319
375
  generatedAt: (options.now?.() ?? new Date()).toISOString(),
320
376
  gates: outcomes,
377
+ // Absent rather than empty when nothing is disabled, so a run with every
378
+ // gate on serialises exactly as it did before this field existed.
379
+ ...(disabledGates(policy).length === 0 ? {} : { disabled: disabledGates(policy) }),
321
380
  deferred,
322
381
  skipped,
323
382
  excluded,
324
383
  treeUnchanged,
325
384
  findings,
326
385
  trustBase: options.trustBase ?? null,
327
- proposals: collectProposals(outcomes, options.trustBase),
386
+ proposals: collectProposals(outcomes, options.trustBase, preparationProposals),
328
387
  summary: {
329
388
  blocking: findings.filter((finding) => finding.blocking).length,
330
389
  byProduct,