@vaultcompass/conductor 0.8.0 → 0.8.1

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/dist/run.js CHANGED
@@ -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;
@@ -124,7 +130,12 @@ export function refusedTrustBase(policy, ref, detail, options) {
124
130
  // thing that could not be read. False rather than a third state, because
125
131
  // no proposal is reported on a run where nothing was judged. The refusal
126
132
  // itself is carried, and it is what both renderers lead with.
127
- trustBase: { ref, policyChanged: false, refusal: detail },
133
+ trustBase: {
134
+ ref,
135
+ policyChanged: false,
136
+ refusal: detail,
137
+ ...(options.notGiven === true ? { notGiven: true } : {}),
138
+ },
128
139
  proposals: [],
129
140
  summary: {
130
141
  blocking: findings.filter((finding) => finding.blocking).length,
@@ -142,11 +153,19 @@ export function refusedTrustBase(policy, ref, detail, options) {
142
153
  * proposing to change which gates run at all, and reading that after a gate's
143
154
  * own contract line would bury it.
144
155
  */
145
- function collectProposals(outcomes, trustBase) {
156
+ function collectProposals(outcomes, trustBase,
157
+ /**
158
+ * The intent gate's own control files this pull request adds or changes,
159
+ * observed while preparing it from the base ref (a contract or spec the
160
+ * base does not carry yet, an edit to the imported spec). They arrive here
161
+ * whether the gate then ran or was skipped.
162
+ */
163
+ preparation = []) {
146
164
  const proposals = [];
147
165
  if (trustBase?.policyChanged === true) {
148
166
  proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
149
167
  }
168
+ proposals.push(...preparation);
150
169
  for (const outcome of outcomes) {
151
170
  for (const line of outcome.trustBase?.proposals ?? []) {
152
171
  proposals.push({ product: outcome.product, role: outcome.role, line });
@@ -198,11 +217,32 @@ function splitOnTreeUnchanged(gates, trustBase) {
198
217
  }
199
218
  return { toRun, treeUnchanged };
200
219
  }
220
+ /**
221
+ * The environment variables the Action sets to say which version of each
222
+ * family gate it pinned, read only to warn when a gate resolved from PATH
223
+ * reports a different one. Not a control input: nothing about resolution or
224
+ * the verdict reads them, so a run that sets them wrongly gets a wrong warning
225
+ * and nothing else.
226
+ */
227
+ const EXPECTED_VERSION_ENV = {
228
+ 'dep-guard': 'CONDUCTOR_EXPECTED_DEP_GUARD_VERSION',
229
+ 'vault-guard': 'CONDUCTOR_EXPECTED_VAULT_GUARD_VERSION',
230
+ 'intent-guard': 'CONDUCTOR_EXPECTED_INTENT_GUARD_VERSION',
231
+ };
232
+ /** The `expectedVersion` option for one gate, or nothing. Exact versions only. */
233
+ function expectedVersionOption(product, env) {
234
+ const name = EXPECTED_VERSION_ENV[product];
235
+ const value = name === undefined ? undefined : env[name];
236
+ return value !== undefined && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(value)
237
+ ? { expectedVersion: value }
238
+ : {};
239
+ }
201
240
  export function runAll(policy, options) {
202
241
  const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
203
242
  const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
204
243
  const env = options.env ?? {};
205
244
  const skipped = [];
245
+ const preparationProposals = [];
206
246
  const cleanups = [];
207
247
  // Sequential, not concurrent. Three Node process starts is real overhead
208
248
  // in a pre-commit hook and running them at once would hide most of it,
@@ -243,7 +283,16 @@ export function runAll(policy, options) {
243
283
  ...(options.spec === undefined ? {} : { spec: options.spec }),
244
284
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
245
285
  ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
286
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
246
287
  });
288
+ const proposed = prepared.kind === 'skip'
289
+ ? prepared.proposals
290
+ : prepared.kind === 'ready'
291
+ ? prepared.preparation.proposals
292
+ : undefined;
293
+ for (const line of proposed ?? []) {
294
+ preparationProposals.push({ product: gate.product, role: gate.role, line });
295
+ }
247
296
  if (prepared.kind === 'skip') {
248
297
  skipped.push({
249
298
  role: gate.role,
@@ -275,15 +324,16 @@ export function runAll(policy, options) {
275
324
  pathValue: options.pathValue,
276
325
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
277
326
  ...(intent === undefined ? {} : { intent }),
327
+ ...expectedVersionOption(gate.product, env),
278
328
  // For a run with no preparation: which contract the child will read
279
329
  // out of the repository itself. Looked up only for the gate it is
280
330
  // about, so no other gate pays for the two stat calls.
281
331
  ...(intent !== undefined || gate.role !== 'intent'
282
332
  ? {}
283
333
  : 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.
334
+ // Offered to every child. runGate decides which ones take it: a
335
+ // gate below its pull-request-mode minimum is could-not-run, and a
336
+ // gate it is withheld from carries the reason on the outcome.
287
337
  ...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
288
338
  // Where an external gate's working directory goes (its report file,
289
339
  // its config from the base ref). The runner removes what it makes.
@@ -324,7 +374,7 @@ export function runAll(policy, options) {
324
374
  treeUnchanged,
325
375
  findings,
326
376
  trustBase: options.trustBase ?? null,
327
- proposals: collectProposals(outcomes, options.trustBase),
377
+ proposals: collectProposals(outcomes, options.trustBase, preparationProposals),
328
378
  summary: {
329
379
  blocking: findings.filter((finding) => finding.blocking).length,
330
380
  byProduct,
@@ -6,19 +6,38 @@
6
6
  * otherwise choose the commit the rules are read from.
7
7
  */
8
8
  export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
9
+ /** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
10
+ export type RefLookup = {
11
+ kind: 'absent';
12
+ } | {
13
+ kind: 'ref';
14
+ oid: string;
15
+ } | {
16
+ kind: 'error';
17
+ detail: string;
18
+ };
19
+ /**
20
+ * The object a fully spelled ref EXACTLY names, keeping "no such ref" apart
21
+ * from "git could not answer". `show-ref --verify` looks at that ref and
22
+ * nothing else: it does not run git's name-resolution rules, so a tag stored
23
+ * as refs/tags/refs/conductor/trust-base is never taken for
24
+ * refs/conductor/trust-base. With --quiet it exits 1 for a ref that is not
25
+ * there and something else for a failure, which is the split this needs.
26
+ */
27
+ export declare function exactRefLookup(repoRoot: string, fullRef: string): RefLookup;
9
28
  /**
10
29
  * The object id a fully spelled ref EXACTLY names, or null when there is no
11
- * such ref. `show-ref --verify` looks at that ref and nothing else: it does
12
- * not run git's name-resolution rules, so a tag stored as
13
- * refs/tags/refs/conductor/trust-base is never taken for
14
- * refs/conductor/trust-base.
30
+ * such ref or it cannot be read. For callers where both mean "cannot use
31
+ * it"; a caller that would fall back to something else on absence uses
32
+ * `exactRefLookup` instead, so an unreadable ref never takes that fallback.
15
33
  */
16
34
  export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
17
35
  /**
18
36
  * A caller-given trust base that starts with "-", or null. Git allows a tag
19
37
  * named refs/tags/--output=x, and such a name handed to git as an argument is
20
- * read as an option, not a revision. Refused before any git call sees it; the
21
- * git calls below also pass --end-of-options as a second line of defence.
38
+ * read as an option, not a revision. Refused before any git call sees it; each
39
+ * git-calling function below refuses one again itself, so no caller can skip
40
+ * the check.
22
41
  */
23
42
  export declare function refuseDashLeadingRef(ref: string): string | null;
24
43
  /** A full 40- or 64-hex object id: never subject to ref name resolution. */
@@ -129,15 +148,43 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
129
148
  */
130
149
  export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
131
150
  /**
132
- * The policy file's contents at a ref, or null when that ref carries none.
151
+ * How a control file that cannot be read at the base is cleared, as one
152
+ * sentence for every refusal that names one. The pull request that fixes the
153
+ * file is judged against the same base, so it cannot pass this check itself.
154
+ */
155
+ export declare function unreadableBaseRemedy(relativePath: string): string;
156
+ /** One file at a ref: not there, its text, or a read this run could not make. */
157
+ export type FileAtRef = {
158
+ kind: 'absent';
159
+ } | {
160
+ kind: 'file';
161
+ text: string;
162
+ } | {
163
+ kind: 'error';
164
+ detail: string;
165
+ };
166
+ /**
167
+ * One file's contents at a ref, with absent, present and unreadable kept
168
+ * apart. THE ONE READER for every file the umbrella takes from a ref.
133
169
  *
134
- * `git show`, never a checkout switch and never a read from the working
135
- * tree. The `./` is load-bearing for the same reason it is in intent-guard:
136
- * it makes git resolve the path relative to the working directory, which is
137
- * the repository root here, rather than to wherever the repository root would
138
- * be from somewhere else.
170
+ * Two steps. `git ls-tree <ref> -- ./<path>` looks the path up in the ref's
171
+ * tree: a listing that succeeds and names nothing is ABSENT, and a listing
172
+ * that fails is an ERROR. The entry must be a regular file; a symlink, a
173
+ * directory or a submodule at the path, or at any directory above it, is an
174
+ * ERROR, never read as its link target or as nothing. Then
175
+ * `git cat-file blob <id>` reads the blob by the id the listing named, and a
176
+ * failure there is an ERROR too. The path is only ever a path and the
177
+ * revision only ever a revision, so a file name can never be read as part of
178
+ * a revision, and absent, present and unreadable are three separate answers.
179
+ *
180
+ * No caller turns an ERROR into empty text or into a default. An error is
181
+ * could-not-run: the trusted file exists, or may, and nothing was judged
182
+ * against it.
183
+ *
184
+ * The `./` makes git resolve the path relative to the working directory,
185
+ * which is the repository root here.
139
186
  */
140
- export declare function readPolicyAtRef(repoRoot: string, ref: string): string | null;
187
+ export declare function readFileAtRef(repoRoot: string, ref: string, relativePath: string): FileAtRef;
141
188
  /**
142
189
  * Whether two policy files differ in what they SAY.
143
190
  *
@@ -148,7 +195,7 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
148
195
  * compared instead, which is the fail-closed direction: an unparseable head
149
196
  * policy is reported as a change rather than quietly matching.
150
197
  *
151
- * BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
198
+ * BOTH SIDES COME FROM `readFileAtRef`, base and head alike, and that is not an
152
199
  * accident of implementation. intent-guard read its head side from the
153
200
  * working tree with a call that follows symlinks, so a pull request that
154
201
  * replaced a control file with a link compared equal to the base and was
@@ -159,19 +206,34 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
159
206
  export declare function policyDiffers(base: string | null, head: string | null): boolean;
160
207
  /** The one line the report prints when the head proposes a different policy. */
161
208
  export declare const POLICY_PROPOSAL_LINE = "policy changed in this pull request";
209
+ /** One path's tree entry at a ref: not there, the entry, or a listing that failed. */
210
+ export type TreeEntry = {
211
+ kind: 'absent';
212
+ } | {
213
+ kind: 'entry';
214
+ mode: string;
215
+ type: string;
216
+ sha: string;
217
+ } | {
218
+ kind: 'error';
219
+ detail: string;
220
+ };
162
221
  /**
163
- * One path's tree entry at a ref, or null when the ref has no such path.
222
+ * One path's tree entry at a ref, keeping "the ref has no such path" apart
223
+ * from "git could not list it".
164
224
  *
165
225
  * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
166
226
  * compared and `show` prints contents without telling you what kind of entry
167
227
  * produced them. The mode comes with it, so a regular file can be told from a
168
228
  * symlink, a submodule or a directory in the same read.
229
+ *
230
+ * Only a listing that SUCCEEDS and names nothing is absent. ls-tree exiting
231
+ * non-zero (a ref that will not resolve, a tree it cannot read) is a read
232
+ * this run cannot make, and so is a path with a symlink or a submodule at
233
+ * any directory above it in the ref's tree: what the path means there is
234
+ * decided outside the tree, so it is an error, never absent.
169
235
  */
170
- export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): {
171
- mode: string;
172
- type: string;
173
- sha: string;
174
- } | null;
236
+ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
175
237
  /**
176
238
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
177
239
  *