@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.
@@ -15,9 +15,9 @@
15
15
  // head's file on its own. A head-side difference is not an error: it is
16
16
  // reported as a proposal, which takes effect once it merges and the base
17
17
  // carries it.
18
- import { spawnSync } from 'node:child_process';
19
18
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
20
19
  import path from 'node:path';
20
+ import { readFileAtRef, unreadableBaseRemedy } from './trust-base.js';
21
21
  /** The base ref's config cannot be materialised; the gate cannot run safely. */
22
22
  export class ExternalConfigError extends Error {
23
23
  constructor(message) {
@@ -60,26 +60,38 @@ export function extendPath(config) {
60
60
  }
61
61
  return null;
62
62
  }
63
- /** A file's contents at a ref, or null when the ref does not have it. */
64
- function showAtRef(repoRoot, ref, file) {
65
- if (ref.startsWith('-')) {
66
- return null;
63
+ /**
64
+ * A file's contents at the base ref, or null when the base does not carry
65
+ * it. A read git could not make THROWS: it is never null, because null
66
+ * selects the neutral config, and a trusted file that exists but could not
67
+ * be read must not be replaced by a default (src/trust-base.ts,
68
+ * readFileAtRef).
69
+ */
70
+ function baseCopy(repoRoot, ref, file) {
71
+ const read = readFileAtRef(repoRoot, ref, file);
72
+ if (read.kind === 'error') {
73
+ throw new ExternalConfigError(`${file} could not be read from the base ref: ${read.detail}. Nothing was checked by this ` +
74
+ `gate. ${unreadableBaseRemedy(file)}`);
67
75
  }
68
- const child = spawnSync('git', ['show', '--end-of-options', `${ref}:${file}`], {
69
- cwd: repoRoot,
70
- encoding: 'utf8',
71
- });
72
- return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
76
+ return read.kind === 'file' ? read.text : null;
73
77
  }
74
78
  function headCopy(repoRoot, file) {
75
79
  const full = path.join(repoRoot, file);
76
80
  return existsSync(full) ? readFileSync(full, 'utf8') : null;
77
81
  }
78
- function differs(file, base, head) {
82
+ /**
83
+ * The proposal line for a head-side difference, or null. It says which copy
84
+ * was actually used: the base's own, or, when the base carries none, the
85
+ * stand-in the umbrella wrote. Saying "the base's copy" for a stand-in would
86
+ * claim a file the base does not have.
87
+ */
88
+ function differs(file, base, head, standIn = "conductor's neutral stand-in") {
79
89
  if (head === null || head === base) {
80
90
  return null;
81
91
  }
82
- return `${file} differs from the base ref; the base's copy was used and this change takes effect after merge.`;
92
+ return base === null
93
+ ? `${file} is not on the base ref; ${standIn} was used and this file takes effect after merge.`
94
+ : `${file} differs from the base ref; the base's copy was used and this change takes effect after merge.`;
83
95
  }
84
96
  /**
85
97
  * Copies one relative file from the base ref into the run directory, at the
@@ -93,7 +105,7 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
93
105
  throw new ExternalConfigError(`${what} ${file} is not a path inside the repository, so conductor cannot read it from ` +
94
106
  'the base ref; name it relative to the repository root.');
95
107
  }
96
- const base = showAtRef(repoRoot, trustBase, path.relative(cwd, target).split(path.sep).join('/'));
108
+ const base = baseCopy(repoRoot, trustBase, path.relative(cwd, target).split(path.sep).join('/'));
97
109
  if (base === null) {
98
110
  throw new ExternalConfigError(`${what} ${file} does not exist on the base ref ${trustBase}, so there is no approved copy ` +
99
111
  'to read; commit it to the base branch or remove the reference.');
@@ -110,12 +122,13 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
110
122
  * a nested file added or edited by the pull request has no effect on the run
111
123
  * (measured against 2.6.0: a nested file ignoring lodash passes without
112
124
  * --config and blocks with it). It is still a change to how the tool behaves
113
- * once merged, so it is reported the way the root config is.
125
+ * once merged, so it is reported the way the root config is. A base copy git
126
+ * could not read throws ExternalConfigError, like every other base read here.
114
127
  */
115
128
  export function nestedConfigProposals(repoRoot, trustBase, trackedFiles, configFile) {
116
129
  return trackedFiles
117
130
  .filter((file) => file !== configFile && path.posix.basename(file) === configFile)
118
- .map((file) => differs(file, showAtRef(repoRoot, trustBase, file), headCopy(repoRoot, file)))
131
+ .map((file) => differs(file, baseCopy(repoRoot, trustBase, file), headCopy(repoRoot, file), 'the root config'))
119
132
  .filter((proposal) => proposal !== null);
120
133
  }
121
134
  export function materializeExternalConfig(args) {
@@ -123,7 +136,9 @@ export function materializeExternalConfig(args) {
123
136
  if (profile.configFile === null) {
124
137
  return null;
125
138
  }
126
- const base = showAtRef(repoRoot, trustBase, profile.configFile);
139
+ // Only an ABSENT base config selects the neutral one. An unreadable one has
140
+ // already thrown, so the tool never runs under a default in its place.
141
+ const base = baseCopy(repoRoot, trustBase, profile.configFile);
127
142
  const ext = path.extname(profile.configFile) || '.toml';
128
143
  const out = path.join(tempRoot, `${profile.product}-config${ext}`);
129
144
  writeFileSync(out, base ?? profile.neutralConfig ?? '');
@@ -158,13 +173,13 @@ export function materializeExternalConfig(args) {
158
173
  let ignore = null;
159
174
  if (profile.ignoreFile !== null) {
160
175
  const name = profile.ignoreFile.name;
161
- const baseIgnore = showAtRef(repoRoot, trustBase, name);
176
+ const baseIgnore = baseCopy(repoRoot, trustBase, name);
162
177
  const dir = path.join(tempRoot, `${profile.product}-ignore`);
163
178
  mkdirSync(dir, { recursive: true });
164
179
  // An empty file when the base has none, for the reason the neutral
165
180
  // config exists: pointing the tool anywhere else lets it find the head's.
166
181
  writeFileSync(path.join(dir, name), baseIgnore ?? '');
167
- ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name)) };
182
+ ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name), 'an empty one') };
168
183
  }
169
184
  return {
170
185
  path: out,
@@ -27,8 +27,12 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
27
27
  | 'gate-program-refused'
28
28
  /**
29
29
  * The installed build is older than the oldest version whose command line
30
- * the umbrella speaks (`minVersion` in src/products.ts). Only the external
31
- * tools have a floor; nothing was run beyond the version probe.
30
+ * the umbrella speaks (`minVersion` in src/products.ts, which only the
31
+ * external tools have), or, on a run with a trust base, older than the
32
+ * first version that takes its rules from the base ref
33
+ * (`TRUST_BASE_MIN_VERSION`). The gate's check was not run. For an intent
34
+ * gate with an imported contract the preparation that stages that contract
35
+ * from the base ref has already run by then.
32
36
  */
33
37
  | 'gate-version-unsupported'
34
38
  /**
@@ -48,7 +52,55 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
48
52
  export interface CouldNotRun {
49
53
  reason: CouldNotRunReason;
50
54
  detail: string;
55
+ /**
56
+ * What the gate itself said about why it could not run: a short, bounded,
57
+ * sanitised excerpt of its own stderr (first line) or, failing that, of a
58
+ * `reason` field in its JSON output. Present only when the gate exited with
59
+ * a code the umbrella does not read as a verdict and said something. It is
60
+ * information for the reader and never an input to a decision: the exit
61
+ * code and `reason` above are decided before this is looked at.
62
+ */
63
+ gateSaid?: string;
51
64
  }
65
+ /** The longest excerpt of a gate's own reason that is carried. */
66
+ export declare const GATE_SAID_MAX_CHARS = 160;
67
+ /**
68
+ * Breaks up the two character sequences a CI log reader treats as a command
69
+ * ("##[" and "::") by putting a space inside them, so gate-printed text stays
70
+ * inert in a job log. Repeated until stable, so runs such as ":::" and "###["
71
+ * are covered too.
72
+ */
73
+ export declare function breakWorkflowMarkers(text: string): string;
74
+ /**
75
+ * The could-not-run reasons that are conductor's OWN decision, made before
76
+ * the gate was spawned (or instead of spawning it), as opposed to something
77
+ * the gate itself said or did.
78
+ */
79
+ export declare const CONDUCTOR_OWN_REASONS: ReadonlySet<CouldNotRunReason>;
80
+ /**
81
+ * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
82
+ * one line, capped and with double quotes replaced, exactly like a gate's
83
+ * stated reason. Null when there is nothing to print.
84
+ */
85
+ export declare function conductorStatedReason(detail: string): string | null;
86
+ /**
87
+ * One line of raw gate output, made safe to print: control characters (escape
88
+ * included) become spaces and workflow-command markers are broken up. The
89
+ * content is otherwise left as it was.
90
+ */
91
+ export declare function cleanOutputLine(raw: string): string;
92
+ /**
93
+ * What a gate that exited with a non-verdict code said about why.
94
+ *
95
+ * TOTAL, and never a decision: the caller has already settled that this is a
96
+ * could-not-run, and nothing here can change that. The first non-empty stderr
97
+ * line is preferred, since that is where every gate in the family prints its
98
+ * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
99
+ * that, stdout is parsed only for a gate whose output is JSON on stdout, and
100
+ * only a string `reason` field (top level, or on `run`) is read; anything else,
101
+ * including output that does not parse, is simply no excerpt.
102
+ */
103
+ export declare function gateStatedReason(stderr: string, stdout: string | null | undefined, stdoutIsJson: boolean): string | null;
52
104
  /**
53
105
  * The first version of each gate that understands `--trust-base`.
54
106
  *
@@ -57,10 +109,11 @@ export interface CouldNotRun {
57
109
  * against every combination in the meantime. A product missing from this
58
110
  * table has no pull-request mode yet and is never handed the flag; a product
59
111
  * in it is handed the flag only when the installed build says it is at least
60
- * this version. Both directions matter: handing an older build a flag it does
61
- * not parse makes it exit non-zero with no JSON, which the umbrella correctly
62
- * reports as could-not-run, so a wrong guess here turns a working repository's
63
- * pull requests red rather than merely leaving a gate un-hardened.
112
+ * this version, and on a run with a trust base a build below it is
113
+ * could-not-run rather than run without the flag, since without the flag it
114
+ * would take its rules from the tree being judged. The entries are the
115
+ * minimum the umbrella requires on a pull-request run, which can be later
116
+ * than the release the flag first appeared in.
64
117
  *
65
118
  * The umbrella is deliberately NOT the place a version pin lives otherwise
66
119
  * (nothing here imports any gate's package), and this is the one exception:
@@ -68,6 +121,22 @@ export interface CouldNotRun {
68
121
  * this package has to those tools.
69
122
  */
70
123
  export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
124
+ /**
125
+ * The first intent-guard whose own `--base` can carry any change set: it
126
+ * reads the paths from git NUL-separated (1.8.0) and lists a moved submodule
127
+ * pointer with --ignore-submodules=none and ends the range with "--" (the
128
+ * release after 1.8.0). For a native contract on this version or later the
129
+ * runner hands the gate `--base` instead of `--paths`, so a changed path
130
+ * that `--paths` cannot carry (a comma, a backslash, edge whitespace, a
131
+ * leading "-") is judged rather than refused.
132
+ *
133
+ * It equals the intent-guard entry in `TRUST_BASE_MIN_VERSION`, so on a run
134
+ * with a trust base every intent gate that runs is new enough, and the
135
+ * `--paths` refusal for a native contract is reached only on a run without
136
+ * one (an explicit `--base`). Kept as its own constant because the two
137
+ * answer different questions and the floor may move without it.
138
+ */
139
+ export declare const INTENT_BASE_CHANNEL_MIN_VERSION = "1.8.1";
71
140
  /**
72
141
  * Pull-request mode as it applied to ONE gate.
73
142
  *
@@ -76,24 +145,27 @@ export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
76
145
  * from the other: whether this gate was actually put into pull-request mode,
77
146
  * and what it said about the control inputs the head proposes to change.
78
147
  *
79
- * `withheld` is the half that must never be silent. A gate the umbrella could
80
- * not put into pull-request mode read its own control inputs out of the tree
81
- * under judgment, which is the whole hole this release exists to close, and a
82
- * run where that happened must not look like a run where it did not.
148
+ * `withheld` is the half that must never be silent. A gate the umbrella did
149
+ * not put into pull-request mode was not handed the base ref, and a run where
150
+ * that happened must not look like a run where it did not.
83
151
  */
84
152
  export interface GateTrustBase {
85
153
  /** The ref the umbrella took its own policy from, and offered to this gate. */
86
154
  ref: string;
87
155
  /**
88
- * Null when the flag was passed; otherwise the reason it was not, for a
89
- * gate that was never going to be inside the boundary in the first place.
90
- * The run continues: that gate read its own control inputs from the tree
91
- * being judged, and the report says so.
156
+ * Null when the flag was passed; otherwise the reason it was not. Only two
157
+ * cases withhold: a product with no pull-request mode at all (none today,
158
+ * every product is in `TRUST_BASE_MIN_VERSION`), and an intent gate judging
159
+ * a contract imported for this run, whose project is a temporary directory
160
+ * with no repository in it (the contract itself was read from the base).
161
+ * A gate below its minimum is never withheld; it is `refused`.
92
162
  */
93
163
  withheld: string | null;
94
164
  /**
95
165
  * Set when the umbrella could not ESTABLISH that this gate would be in
96
- * pull-request mode, which is could-not-run rather than a downgrade.
166
+ * pull-request mode (its version did not read), or established that it
167
+ * would not be (its version is below the minimum), which is could-not-run
168
+ * rather than a downgrade.
97
169
  *
98
170
  * The distinction is the whole point and it is not symmetry with
99
171
  * `withheld`. A gate outside the table was never going to get the flag, so
@@ -155,6 +227,7 @@ export interface GateOutcome {
155
227
  intent?: {
156
228
  contractSource: ContractSource;
157
229
  baseRef: string | null;
230
+ note?: string;
158
231
  };
159
232
  /**
160
233
  * Present only on a pull-request run. Whether this gate was put into
@@ -172,8 +245,26 @@ export interface GateOutcome {
172
245
  * nowhere. Repository-relative because it reaches a published log.
173
246
  */
174
247
  nodeModulesSkipped?: string;
248
+ /**
249
+ * Present only when this gate was resolved from PATH, the version it
250
+ * reported differs from the one the run was told to expect (the Action's
251
+ * pin, handed over as an environment variable), and both are known. A
252
+ * statement for a warning, never an input to a decision: resolution,
253
+ * trust-base handling and the exit code are all settled without it.
254
+ */
255
+ versionSkew?: {
256
+ expected: string;
257
+ found: string;
258
+ path: string;
259
+ };
175
260
  }
176
261
  export interface RunGateOptions {
262
+ /**
263
+ * The version this run expects of the gate, when something says so (the
264
+ * Action passes its pin). Compared with what the PATH binary reports, for a
265
+ * warning only. Absent means no expectation, which is every local run.
266
+ */
267
+ expectedVersion?: string;
177
268
  repoRoot: string;
178
269
  staged: boolean;
179
270
  /** PATH to search. Injected so tests never depend on the machine. */
@@ -289,7 +380,12 @@ export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: Inte
289
380
  */
290
381
  trustBase?: string,
291
382
  /** Paths the runner owns for an external tool; the npm gates ignore them. */
292
- external?: ExternalArgs): string[];
383
+ external?: ExternalArgs,
384
+ /**
385
+ * For the intent gate on a prepared run: hand it this base with its own
386
+ * `--base` in place of `--paths`. Decided by `intentChangeChannel`.
387
+ */
388
+ intentBase?: string): string[];
293
389
  /**
294
390
  * Runs one gate. TOTAL: this never throws.
295
391
  *
@@ -301,3 +397,10 @@ external?: ExternalArgs): string[];
301
397
  * a finding of the umbrella's own saying so.
302
398
  */
303
399
  export declare function runGate(gate: GatePolicy, options: RunGateOptions): GateOutcome;
400
+ /**
401
+ * Whether git says the repository at `repoRoot` is shallow. Anything other
402
+ * than a clear "true" (no git, an old git that does not know the flag) is
403
+ * not shallow: those runs have their own failure paths.
404
+ */
405
+ /** The oldest git a history gate runs under on a pull-request run. */
406
+ export declare const HISTORY_GIT_FLOOR = "2.31.0";