@vaultcompass/conductor 0.7.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,
@@ -1,3 +1,68 @@
1
+ /**
2
+ * The private, fully spelled ref the composite action fetches the base branch
3
+ * into (action.yml, gates step). Nothing else writes it and no short name can
4
+ * shadow it: git resolves a short name like origin/main through refs/tags/
5
+ * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
6
+ * otherwise choose the commit the rules are read from.
7
+ */
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;
28
+ /**
29
+ * The object id a fully spelled ref EXACTLY names, or null when there is no
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.
33
+ */
34
+ export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
35
+ /**
36
+ * A caller-given trust base that starts with "-", or null. Git allows a tag
37
+ * named refs/tags/--output=x, and such a name handed to git as an argument is
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.
41
+ */
42
+ export declare function refuseDashLeadingRef(ref: string): string | null;
43
+ /** A full 40- or 64-hex object id: never subject to ref name resolution. */
44
+ export declare function isFullObjectId(value: string): boolean;
45
+ /**
46
+ * Why a SHORT ref name cannot be trusted as spelled, or null.
47
+ *
48
+ * A name that matches more than one kind of ref (a tag and a remote-tracking
49
+ * ref or a branch) is resolved by git in its own precedence order, tags
50
+ * first, with no warning under --quiet. That is a choice made by whoever can
51
+ * create the tag, so it is refused rather than resolved. A ref already spelled
52
+ * from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
53
+ * not names and are left to the callers' own checks.
54
+ */
55
+ export declare function refuseAmbiguousRef(repoRoot: string, ref: string,
56
+ /** What the ref is used as, for the message: "the trust base", "the intent base". */
57
+ noun?: string): string | null;
58
+ /**
59
+ * What a rev resolves to at this repository, or null when it does not.
60
+ *
61
+ * `--quiet` suppresses git's own explanation, so there is nothing worth
62
+ * forwarding on failure: the caller writes a sentence a reader can act on
63
+ * rather than repeating the command line that failed.
64
+ */
65
+ export declare function resolveRev(repoRoot: string, rev: string, kind: 'commit' | 'tree'): string | null;
1
66
  /**
2
67
  * Whether HEAD's tree is byte-identical to the trust base's tree.
3
68
  *
@@ -54,11 +119,12 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
54
119
  * NAME on a pull_request or pull_request_target event, and empty everywhere
55
120
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
56
121
  * a platform that never sets it. When it is set, the given ref is accepted
57
- * only when it resolves to the SAME COMMIT as origin/<githubBaseRef>, which
58
- * is exactly what the composite action itself always passes
59
- * (`--trust-base "origin/$GITHUB_BASE_REF"` in action.yml's gates step). So
60
- * an ordinary pull-request run sees the given ref and the expected ref as the
61
- * identical spelling and this returns null immediately, before
122
+ * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
123
+ * base" step published (which must equal refs/conductor/trust-base, the
124
+ * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
125
+ * or is that private ref itself, or -- for an explicit trust base -- resolves
126
+ * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
127
+ * pull-request run through the action returns null here, before
62
128
  * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
63
129
  * issue #69/#73 -- ever run: this check is narrower than those and says
64
130
  * nothing about HEAD or about tree equality, only about whether the given ref
@@ -66,11 +132,11 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
66
132
  * request's own branch, or anything else that disagrees, is refused with both
67
133
  * refs and both commits named.
68
134
  *
69
- * FAILS CLOSED when origin/<githubBaseRef> itself does not resolve, naming
70
- * it: reachable on the default actions/checkout (fetch-depth: 1), which does
71
- * not carry the base branch at all. The README already asks for
72
- * fetch-depth: 0, and a checkout that does not carry the base branch is not a
73
- * reason to skip the comparison.
135
+ * FAILS CLOSED when neither the private ref nor refs/remotes/origin/
136
+ * <githubBaseRef> exists, naming them: reachable through the CLI on the
137
+ * default actions/checkout (fetch-depth: 1), which does not carry the base
138
+ * branch at all. The README already asks for fetch-depth: 0, and a checkout
139
+ * that does not carry the base branch is not a reason to skip the comparison.
74
140
  *
75
141
  * When the GIVEN ref does not resolve at all, this returns null rather than
76
142
  * refusing: refuseTrustBaseRef is the function with its own sentence for an
@@ -82,15 +148,43 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
82
148
  */
83
149
  export declare function refuseTrustBaseForPullRequest(repoRoot: string, ref: string, githubBaseRef: string | undefined): string | null;
84
150
  /**
85
- * 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.
86
169
  *
87
- * `git show`, never a checkout switch and never a read from the working
88
- * tree. The `./` is load-bearing for the same reason it is in intent-guard:
89
- * it makes git resolve the path relative to the working directory, which is
90
- * the repository root here, rather than to wherever the repository root would
91
- * 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.
92
186
  */
93
- export declare function readPolicyAtRef(repoRoot: string, ref: string): string | null;
187
+ export declare function readFileAtRef(repoRoot: string, ref: string, relativePath: string): FileAtRef;
94
188
  /**
95
189
  * Whether two policy files differ in what they SAY.
96
190
  *
@@ -101,7 +195,7 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
101
195
  * compared instead, which is the fail-closed direction: an unparseable head
102
196
  * policy is reported as a change rather than quietly matching.
103
197
  *
104
- * 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
105
199
  * accident of implementation. intent-guard read its head side from the
106
200
  * working tree with a call that follows symlinks, so a pull request that
107
201
  * replaced a control file with a link compared equal to the base and was
@@ -112,19 +206,34 @@ export declare function readPolicyAtRef(repoRoot: string, ref: string): string |
112
206
  export declare function policyDiffers(base: string | null, head: string | null): boolean;
113
207
  /** The one line the report prints when the head proposes a different policy. */
114
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
+ };
115
221
  /**
116
- * 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".
117
224
  *
118
225
  * `ls-tree` rather than `git show`, because the BLOB ID is the thing being
119
226
  * compared and `show` prints contents without telling you what kind of entry
120
227
  * produced them. The mode comes with it, so a regular file can be told from a
121
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.
122
235
  */
123
- export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): {
124
- mode: string;
125
- type: string;
126
- sha: string;
127
- } | null;
236
+ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
128
237
  /**
129
238
  * Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
130
239
  *