@vaultcompass/conductor 0.6.0 → 0.8.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.
@@ -36,7 +36,15 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
36
36
  * verdict to is not there. Only a tool whose output is a report file can
37
37
  * land here.
38
38
  */
39
- | 'report-missing';
39
+ | 'report-missing'
40
+ /**
41
+ * The gate reads git history and the checkout is shallow, so the history it
42
+ * would read is truncated (at depth 1 the pull request's merge commit is
43
+ * grafted, and base..HEAD holds one commit: a secret added and removed
44
+ * inside the pull request is never seen). Never unshallowed automatically:
45
+ * the remedy is a checkout setting, fetch-depth: 0.
46
+ */
47
+ | 'history-shallow';
40
48
  export interface CouldNotRun {
41
49
  reason: CouldNotRunReason;
42
50
  detail: string;
@@ -274,9 +274,10 @@ external = {}) {
274
274
  // with cwd at the repository root anyway. Passing one would also risk
275
275
  // a passthrough value being read as the positional.
276
276
  //
277
- // `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
278
- // line on stderr and NO document at all, which the could-not-run path
279
- // above already handles before JSON.parse is reached.
277
+ // `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
278
+ // stderr and may also write a JSON document (it can on a staged run);
279
+ // conductor never parses stdout on exit 2, so the could-not-run path
280
+ // above handles both before JSON.parse is reached.
280
281
  return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
281
282
  case 'intent-guard': {
282
283
  if (intent === undefined) {
@@ -484,7 +485,10 @@ function missingGateRemedy(product, skipNodeModules, skipped) {
484
485
  return ` ${profile.remedy(skipNodeModules)}`;
485
486
  }
486
487
  if (!skipNodeModules) {
487
- return '';
488
+ // Named on a local run too: the scoped package is the only correct
489
+ // install target, and the finding's own sentence must not be the only
490
+ // place a reader could take a bare name from.
491
+ return ` ${profile.remedy(false)}`;
488
492
  }
489
493
  return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
490
494
  'is chosen by the head own manifest and lockfile, so no ref approves it.' +
@@ -559,6 +563,18 @@ export function runGate(gate, options) {
559
563
  };
560
564
  }
561
565
  }
566
+ /**
567
+ * Whether git says the repository at `repoRoot` is shallow. Anything other
568
+ * than a clear "true" (no git, an old git that does not know the flag) is
569
+ * not shallow: those runs have their own failure paths.
570
+ */
571
+ function isShallowRepository(repoRoot) {
572
+ const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
573
+ cwd: repoRoot,
574
+ encoding: 'utf8',
575
+ });
576
+ return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
577
+ }
562
578
  function runGateInner(gate, options, started, progress) {
563
579
  const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
564
580
  // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
@@ -611,7 +627,9 @@ function runGateInner(gate, options, started, progress) {
611
627
  // not a location this run has.
612
628
  detail: (skipNodeModules
613
629
  ? `no ${gate.product} binary on PATH`
614
- : `no ${gate.product} binary in node_modules/.bin or on PATH`) + remedy,
630
+ : `no ${gate.product} binary in node_modules/.bin or on PATH`) +
631
+ (remedy === '' ? '' : '.') +
632
+ remedy,
615
633
  },
616
634
  // A missing enabled gate is a finding of the umbrella's own, never a
617
635
  // silent skip. Skipping is how a gate ends up switched on in the
@@ -642,6 +660,27 @@ function runGateInner(gate, options, started, progress) {
642
660
  };
643
661
  }
644
662
  }
663
+ // A history gate cannot vouch for history it was not given. Checked before
664
+ // the version probe so nothing is executed for a run that cannot be honest.
665
+ if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
666
+ const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
667
+ 'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
668
+ 'single grafted commit, and a secret added and then removed inside the pull request ' +
669
+ 'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
670
+ 'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
671
+ return {
672
+ ...base,
673
+ // Under a trust base this is enforced whatever the policy says: the
674
+ // gate produced nothing for `enforce: false` to be a decision about.
675
+ // A local run keeps the policy's own value.
676
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
677
+ durationMs: Date.now() - started,
678
+ couldNotRun: { reason: 'history-shallow', detail },
679
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
680
+ run: EMPTY_RUN,
681
+ diagnostics: [],
682
+ };
683
+ }
645
684
  const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
646
685
  // The command-line floor. Only the external tools have one: the umbrella
647
686
  // writes flags they grew at a known release (gitleaks' git subcommand,
@@ -895,6 +934,11 @@ function spawnAndRead(ctx) {
895
934
  encoding: 'utf8',
896
935
  timeout: timeoutMs,
897
936
  maxBuffer: 64 * 1024 * 1024,
937
+ // A history gate reads git history, and replace refs or grafts can cut
938
+ // that history without making the repository shallow. Ignoring replace
939
+ // objects makes it read the real commits. Other gates keep the
940
+ // inherited environment untouched.
941
+ ...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
898
942
  });
899
943
  const withRun = {
900
944
  ...base,
@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
4
4
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
5
+ import { installName } from './normalize.js';
5
6
  import { CANDIDATES } from './resolve.js';
6
7
  export { POLICY_FILE_NAME };
7
8
  /** Names of the gates whose binary resolves right now. */
@@ -96,7 +97,7 @@ export function renderPolicy(detected, frozenContractPath) {
96
97
  const enabled = detected.has(role);
97
98
  lines.push(` # ${ROLE_DESCRIPTION[role]}`);
98
99
  if (!enabled) {
99
- lines.push(` # not found in node_modules/.bin or on PATH. Install ${product}, then set enabled: true.`);
100
+ lines.push(` # not found in node_modules/.bin or on PATH. Install ${installName(product)}, then set enabled: true.`);
100
101
  }
101
102
  lines.push(` ${role}:`);
102
103
  lines.push(` product: ${product}`);
@@ -23,6 +23,35 @@ export declare function resolveBaseRef(options: {
23
23
  base?: string;
24
24
  env: NodeJS.ProcessEnv;
25
25
  }): BaseResolution | null;
26
+ export type ResolvedBase = {
27
+ ok: true;
28
+ base: BaseResolution | null;
29
+ } | {
30
+ ok: false;
31
+ detail: string;
32
+ };
33
+ /**
34
+ * The base to diff against, resolved against the repository and always
35
+ * spelled so a tag cannot shadow it (the same class as the trust base: git
36
+ * resolves a short origin/<base> through refs/tags/ first, so a tag at
37
+ * HEAD~1 would narrow the change set to the last commit).
38
+ *
39
+ * - An explicit --base keeps its meaning, but a short name that matches
40
+ * more than one kind of ref is refused (refuseAmbiguousRef).
41
+ * - Otherwise, on a pull request: refs/conductor/trust-base (the composite
42
+ * action's private fetch) when it exists, else refs/remotes/origin/<base>,
43
+ * both in full. The private ref wins and is not compared against the
44
+ * remote-tracking ref. If neither exists the spelled remote ref is returned and the
45
+ * diff fails closed, naming fetch-depth: 0.
46
+ * - Null outside a pull request.
47
+ *
48
+ * Nothing is deepened here: a depth-1 private ref has no merge base and the
49
+ * diff fails closed, the same outcome as a depth-1 origin/<base> always had.
50
+ */
51
+ export declare function resolveBaseRefInRepo(repoRoot: string, options: {
52
+ base?: string;
53
+ env: NodeJS.ProcessEnv;
54
+ }): ResolvedBase;
26
55
  /**
27
56
  * The branch this run is about.
28
57
  *
@@ -16,6 +16,7 @@
16
16
  // the flags below are copied from intent-guard 1.2.1 so the two agree on what
17
17
  // "changed" means rather than agreeing by coincidence.
18
18
  import { spawnSync } from 'node:child_process';
19
+ import { PRIVATE_TRUST_BASE_REF, exactRefObject, refuseAmbiguousRef } from './trust-base.js';
19
20
  /**
20
21
  * The ref to diff against, or null for a run that is not a pull request.
21
22
  *
@@ -35,6 +36,77 @@ export function resolveBaseRef(options) {
35
36
  }
36
37
  return null;
37
38
  }
39
+ /**
40
+ * The base to diff against, resolved against the repository and always
41
+ * spelled so a tag cannot shadow it (the same class as the trust base: git
42
+ * resolves a short origin/<base> through refs/tags/ first, so a tag at
43
+ * HEAD~1 would narrow the change set to the last commit).
44
+ *
45
+ * - An explicit --base keeps its meaning, but a short name that matches
46
+ * more than one kind of ref is refused (refuseAmbiguousRef).
47
+ * - Otherwise, on a pull request: refs/conductor/trust-base (the composite
48
+ * action's private fetch) when it exists, else refs/remotes/origin/<base>,
49
+ * both in full. The private ref wins and is not compared against the
50
+ * remote-tracking ref. If neither exists the spelled remote ref is returned and the
51
+ * diff fails closed, naming fetch-depth: 0.
52
+ * - Null outside a pull request.
53
+ *
54
+ * Nothing is deepened here: a depth-1 private ref has no merge base and the
55
+ * diff fails closed, the same outcome as a depth-1 origin/<base> always had.
56
+ */
57
+ export function resolveBaseRefInRepo(repoRoot, options) {
58
+ if (options.base !== undefined && options.base !== '') {
59
+ // A base that starts with a dash is an OPTION to git, not a ref:
60
+ // "--output=/x" made "git diff --output=/x...HEAD" write that file and
61
+ // print nothing, an empty change set the intent gate then judged as clean.
62
+ // Refused here, and changedPathsSince passes --end-of-options as well.
63
+ if (options.base.startsWith('-')) {
64
+ return {
65
+ ok: false,
66
+ detail: `refusing "${options.base}" as the intent gate base: it starts with a dash, so git would ` +
67
+ 'read it as an option rather than a ref. Nothing was checked.',
68
+ };
69
+ }
70
+ const ambiguous = refuseAmbiguousRef(repoRoot, options.base, 'the intent gate base');
71
+ if (ambiguous !== null) {
72
+ return { ok: false, detail: ambiguous };
73
+ }
74
+ // A refs/ name is checked with show-ref: git's name resolution would
75
+ // otherwise fall back to refs/tags/<that name> when the ref is absent.
76
+ if (options.base.startsWith('refs/') && exactRefObject(repoRoot, options.base) === null) {
77
+ return {
78
+ ok: false,
79
+ detail: `refusing "${options.base}" as the intent gate base: no such ref exists in this ` +
80
+ 'repository (a tag of that name does not count). Nothing was checked.',
81
+ };
82
+ }
83
+ return { ok: true, base: { ref: options.base, source: 'flag' } };
84
+ }
85
+ const fromGithub = options.env.GITHUB_BASE_REF;
86
+ if (fromGithub === undefined || fromGithub === '') {
87
+ return { ok: true, base: null };
88
+ }
89
+ const remoteRef = `refs/remotes/origin/${fromGithub}`;
90
+ // The private ref is the authority when it exists; refs/remotes/origin/<base>
91
+ // is fixed at checkout time, is the side pull-request code can move, and is
92
+ // not compared against it (a merge to the base in between would be a false
93
+ // refusal). It is the base only when the private ref is absent. Both are
94
+ // read with show-ref (the EXACT ref, never git's name resolution, which
95
+ // would take a tag of that name) and the base handed on is the commit id.
96
+ const priv = exactRefObject(repoRoot, PRIVATE_TRUST_BASE_REF);
97
+ const remote = exactRefObject(repoRoot, remoteRef);
98
+ const chosen = priv ?? remote;
99
+ if (chosen === null) {
100
+ return {
101
+ ok: false,
102
+ detail: `neither ${PRIVATE_TRUST_BASE_REF} (the composite action's fetch of the base branch) nor ` +
103
+ `${remoteRef} exists in this repository, so there is no base to measure the intent gate ` +
104
+ 'against. Nothing was checked. In CI, check out with fetch-depth: 0, or fetch the base ' +
105
+ 'ref before the run.',
106
+ };
107
+ }
108
+ return { ok: true, base: { ref: chosen, source: 'github' } };
109
+ }
38
110
  /**
39
111
  * The branch this run is about.
40
112
  *
@@ -83,7 +155,15 @@ export function changedPathsSince(repoRoot, base) {
83
155
  'core.quotePath=false',
84
156
  'diff',
85
157
  '--name-only',
158
+ // NUL-terminated, so a name with a quote, a backslash, a tab or a
159
+ // newline arrives byte for byte instead of C-quoted ("a\"b.txt"), which
160
+ // names no file and which intent-guard refuses outright (backslash).
161
+ '-z',
86
162
  '--no-renames',
163
+ // Everything after this is a revision, never an option, whatever the
164
+ // caller-given base looks like (the second line of defence behind the
165
+ // dash refusal in resolveBaseRefInRepo).
166
+ '--end-of-options',
87
167
  `${base}...HEAD`,
88
168
  ], { cwd: repoRoot, encoding: 'utf8' });
89
169
  if (child.error !== undefined) {
@@ -102,11 +182,11 @@ export function changedPathsSince(repoRoot, base) {
102
182
  'check out with fetch-depth: 0, or fetch the base ref before the run.',
103
183
  };
104
184
  }
105
- // Split on newlines and NOTHING else. Trimming each line was corrupting a
185
+ // Split on NUL and NOTHING else. Trimming each entry was corrupting a
106
186
  // filename with leading or trailing whitespace into a different filename,
107
187
  // which is worse than refusing it: the gate would then check a path that
108
188
  // does not exist and never check the one that changed.
109
- const paths = (child.stdout ?? '').split('\n').filter((line) => line.length > 0);
189
+ const paths = (child.stdout ?? '').split('\0').filter((line) => line.length > 0);
110
190
  for (const entry of paths) {
111
191
  // Fail closed rather than hand over a path the encoding cannot carry.
112
192
  // `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
@@ -122,6 +202,20 @@ export function changedPathsSince(repoRoot, base) {
122
202
  'Nothing was checked, rather than checking a path that does not exist.',
123
203
  };
124
204
  }
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
+ if (entry.includes('\\')) {
212
+ return {
213
+ ok: false,
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
+ };
218
+ }
125
219
  if (entry !== entry.trim()) {
126
220
  return {
127
221
  ok: false,
@@ -34,7 +34,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, st
34
34
  import os from 'node:os';
35
35
  import path from 'node:path';
36
36
  import { parse as parseYaml } from 'yaml';
37
- import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
37
+ import { changedPathsSince, currentBranch, resolveBaseRefInRepo } from './intent-base.js';
38
38
  import { summariseStderr } from './normalize.js';
39
39
  import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
40
40
  /** Prefix of the per-run directory, exported so a test can count leaks. */
@@ -383,10 +383,14 @@ export function prepareIntent(options) {
383
383
  'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
384
384
  };
385
385
  }
386
- const base = resolveBaseRef({
386
+ const resolvedBase = resolveBaseRefInRepo(repoRoot, {
387
387
  ...(options.base === undefined ? {} : { base: options.base }),
388
388
  env,
389
389
  });
390
+ if (!resolvedBase.ok) {
391
+ return { kind: 'failed', step: 'base', detail: resolvedBase.detail };
392
+ }
393
+ const base = resolvedBase.base;
390
394
  let paths = null;
391
395
  if (base !== null) {
392
396
  const changed = changedPathsSince(repoRoot, base.ref);
@@ -54,6 +54,15 @@ roots?: readonly string[],
54
54
  /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
55
55
  lockfiles?: readonly string[]): NormalizedGateOutput;
56
56
  export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
57
+ /**
58
+ * What to install for a product, spelled so it cannot be mistaken for
59
+ * another package. The three npm gates are published under the
60
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
61
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
62
+ * could install a squatted package. The external tools are not npm packages
63
+ * of this family and keep their own names.
64
+ */
65
+ export declare function installName(product: Product): string;
57
66
  /**
58
67
  * The finding raised when an ENABLED gate's binary cannot be found.
59
68
  *
package/dist/normalize.js CHANGED
@@ -14,6 +14,7 @@
14
14
  // own reported count says otherwise.
15
15
  import { createHash } from 'node:crypto';
16
16
  import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
17
+ import { profileFor } from './products.js';
17
18
  const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
18
19
  const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
19
20
  function isRecord(value) {
@@ -1045,6 +1046,17 @@ function gateProblem(ruleId, role, product, message, details) {
1045
1046
  details: { role, product, ...details },
1046
1047
  };
1047
1048
  }
1049
+ /**
1050
+ * What to install for a product, spelled so it cannot be mistaken for
1051
+ * another package. The three npm gates are published under the
1052
+ * @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
1053
+ * unclaimed on npm, so a reader (or an agent) told to install the bare name
1054
+ * could install a squatted package. The external tools are not npm packages
1055
+ * of this family and keep their own names.
1056
+ */
1057
+ export function installName(product) {
1058
+ return profileFor(product).managed ? `@vaultcompass/${product}` : product;
1059
+ }
1048
1060
  /**
1049
1061
  * The finding raised when an ENABLED gate's binary cannot be found.
1050
1062
  *
@@ -1066,7 +1078,7 @@ export function normalizeMissingGate(role, product, candidates,
1066
1078
  */
1067
1079
  remedy = '') {
1068
1080
  return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
1069
- `Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
1081
+ `Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
1070
1082
  `absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
1071
1083
  }
1072
1084
  /**
@@ -25,6 +25,41 @@ import type { RunResult } from './run.js';
25
25
  * not change.
26
26
  */
27
27
  export declare function jobLogSummary(result: RunResult): string;
28
+ /**
29
+ * The verdict token: a label for the umbrella's OWN exit decision, in a
30
+ * closed set, so a person or a script reading a report or a job summary gets
31
+ * the state without parsing the verdict sentence.
32
+ *
33
+ * pass exit 0 and nothing was hidden by it
34
+ * nothing-checked exit 0, but no gate ran at all (none enabled,
35
+ * or every one deferred, tree-unchanged or skipped)
36
+ * advisory-blocked (N) exit 1 that --advisory turned into exit 0
37
+ * unenforced-findings (N) exit 0, but enforce: false gates blocked or
38
+ * could not run
39
+ * blocked (N) exit 1
40
+ * could-not-run exit 2, a refused trust base included
41
+ *
42
+ * PRECEDENCE, when several apply: could-not-run, then blocked or
43
+ * advisory-blocked, then unenforced-findings, then pass. So an advisory run
44
+ * whose only blocking findings sit on an unenforced gate is
45
+ * unenforced-findings and never advisory-blocked: --advisory did nothing
46
+ * there, and saying it did would be a false statement of what was hidden.
47
+ *
48
+ * This decides nothing. Every branch reads the exit code composeExitCode
49
+ * already produced (result.exitCode) and the enforce flags already on the
50
+ * gates; the only counting is over what those gates said. It never
51
+ * overrules a gate. It is also the same `advisory` boolean cli.ts hands to
52
+ * applyAdvisory, so the label and the process exit code cannot disagree.
53
+ *
54
+ * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
55
+ * than result.gates, is neither a blocking finding nor a could-not-run, and
56
+ * so does not by itself move the token off pass when another gate ran. When
57
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
58
+ *
59
+ * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
60
+ * not a pass.
61
+ */
62
+ export declare function verdictToken(result: RunResult, advisory: boolean): string;
28
63
  export interface TextOptions {
29
64
  /**
30
65
  * Print the full report even when the run is fully clean.
@@ -382,6 +382,81 @@ export function jobLogSummary(result) {
382
382
  }
383
383
  return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
384
384
  }
385
+ /**
386
+ * How many blocking findings one gate that RAN is carrying, for the token.
387
+ *
388
+ * A gate that exited non-zero with nothing on screen marked blocking (the
389
+ * mismatch shape the verdict sentence already has its own wording for) counts
390
+ * as one, so a state that is not a pass never prints a count of zero. A gate
391
+ * that could not run is not counted here at all: its findings list carries
392
+ * the umbrella's own blocking gate-missing finding, and counting that as well
393
+ * would report one broken gate as two things.
394
+ */
395
+ function blockingCount(gate) {
396
+ if (gate.couldNotRun !== null) {
397
+ return 0;
398
+ }
399
+ const blocking = gate.findings.filter((finding) => finding.blocking).length;
400
+ return blocking === 0 && (gate.exitCode ?? 0) !== 0 ? 1 : blocking;
401
+ }
402
+ /**
403
+ * The verdict token: a label for the umbrella's OWN exit decision, in a
404
+ * closed set, so a person or a script reading a report or a job summary gets
405
+ * the state without parsing the verdict sentence.
406
+ *
407
+ * pass exit 0 and nothing was hidden by it
408
+ * nothing-checked exit 0, but no gate ran at all (none enabled,
409
+ * or every one deferred, tree-unchanged or skipped)
410
+ * advisory-blocked (N) exit 1 that --advisory turned into exit 0
411
+ * unenforced-findings (N) exit 0, but enforce: false gates blocked or
412
+ * could not run
413
+ * blocked (N) exit 1
414
+ * could-not-run exit 2, a refused trust base included
415
+ *
416
+ * PRECEDENCE, when several apply: could-not-run, then blocked or
417
+ * advisory-blocked, then unenforced-findings, then pass. So an advisory run
418
+ * whose only blocking findings sit on an unenforced gate is
419
+ * unenforced-findings and never advisory-blocked: --advisory did nothing
420
+ * there, and saying it did would be a false statement of what was hidden.
421
+ *
422
+ * This decides nothing. Every branch reads the exit code composeExitCode
423
+ * already produced (result.exitCode) and the enforce flags already on the
424
+ * gates; the only counting is over what those gates said. It never
425
+ * overrules a gate. It is also the same `advisory` boolean cli.ts hands to
426
+ * applyAdvisory, so the label and the process exit code cannot disagree.
427
+ *
428
+ * A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
429
+ * than result.gates, is neither a blocking finding nor a could-not-run, and
430
+ * so does not by itself move the token off pass when another gate ran. When
431
+ * NO gate ran, the token is nothing-checked, matching the verdict sentence.
432
+ *
433
+ * Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
434
+ * not a pass.
435
+ */
436
+ export function verdictToken(result, advisory) {
437
+ const refusal = result.trustBase?.refusal;
438
+ const refused = refusal !== undefined && refusal !== null;
439
+ if (refused || (result.exitCode !== 0 && result.exitCode !== EXIT_BLOCKED)) {
440
+ return 'could-not-run';
441
+ }
442
+ if (result.exitCode === EXIT_BLOCKED) {
443
+ const count = result.gates
444
+ .filter((gate) => gate.enforce)
445
+ .reduce((total, gate) => total + blockingCount(gate), 0);
446
+ return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
447
+ }
448
+ // Exit 0 with no gate having run at all (none enabled, every one deferred,
449
+ // tree-unchanged or skipped): the exit code stays 0, since nothing failed,
450
+ // but the label must not say pass. It is the same condition the verdict
451
+ // sentence words as "nothing was checked".
452
+ if (result.gates.length === 0) {
453
+ return 'nothing-checked';
454
+ }
455
+ const unenforced = result.gates
456
+ .filter((gate) => !gate.enforce)
457
+ .reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
458
+ return unenforced > 0 ? `unenforced-findings (${unenforced})` : 'pass';
459
+ }
385
460
  function verdict(result, advisory) {
386
461
  const refusal = result.trustBase?.refusal;
387
462
  if (refusal !== undefined && refusal !== null) {
@@ -698,6 +773,18 @@ function summaryLine(result) {
698
773
  function versionLine(version) {
699
774
  return version === undefined ? [] : [`conductor ${version}`];
700
775
  }
776
+ /**
777
+ * The version line, then the verdict-token line directly under it: the first
778
+ * two lines of every report that carries a token. Without a version the
779
+ * token is the first line. The closing verdict sentence is a separate thing
780
+ * and stays where it was.
781
+ */
782
+ function headerLines(result, options) {
783
+ return [
784
+ ...versionLine(options.version),
785
+ `verdict-token: ${verdictToken(result, Boolean(options.advisory))}`,
786
+ ];
787
+ }
701
788
  export function renderText(result, options = {}) {
702
789
  const refusal = refusalLines(result);
703
790
  if (options.compact === true && refusal.length > 0) {
@@ -708,7 +795,7 @@ export function renderText(result, options = {}) {
708
795
  // proposal) as part of the same sentence. Nothing here points at a step
709
796
  // log: the reason has to be readable on the comment itself.
710
797
  const lines = [
711
- ...versionLine(options.version),
798
+ ...headerLines(result, options),
712
799
  verdict(result, Boolean(options.advisory)),
713
800
  ...refusal,
714
801
  ];
@@ -726,7 +813,7 @@ export function renderText(result, options = {}) {
726
813
  // different questions, so two numbers, and the section headers and the
727
814
  // "not enforced" lines are what connect them.
728
815
  const lines = [
729
- ...versionLine(options.version),
816
+ ...headerLines(result, options),
730
817
  ...refusal,
731
818
  ...(refusal.length === 0 ? [] : ['']),
732
819
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
package/dist/products.js CHANGED
@@ -39,7 +39,7 @@ function managedRemedy(product) {
39
39
  ? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
40
40
  `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
41
41
  'that pin lives in the workflow file on the base branch.'
42
- : `Install it with npm install -g @vaultcompass/${product}, or add it to the repository's devDependencies.`;
42
+ : `The package is @vaultcompass/${product}, never the unscoped name: install it with npm install -g @vaultcompass/${product}, or add @vaultcompass/${product} to the repository's devDependencies.`;
43
43
  }
44
44
  function managedProfile(product) {
45
45
  return {
@@ -1,3 +1,49 @@
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
+ /**
10
+ * 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.
15
+ */
16
+ export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
17
+ /**
18
+ * A caller-given trust base that starts with "-", or null. Git allows a tag
19
+ * 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.
22
+ */
23
+ export declare function refuseDashLeadingRef(ref: string): string | null;
24
+ /** A full 40- or 64-hex object id: never subject to ref name resolution. */
25
+ export declare function isFullObjectId(value: string): boolean;
26
+ /**
27
+ * Why a SHORT ref name cannot be trusted as spelled, or null.
28
+ *
29
+ * A name that matches more than one kind of ref (a tag and a remote-tracking
30
+ * ref or a branch) is resolved by git in its own precedence order, tags
31
+ * first, with no warning under --quiet. That is a choice made by whoever can
32
+ * create the tag, so it is refused rather than resolved. A ref already spelled
33
+ * from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
34
+ * not names and are left to the callers' own checks.
35
+ */
36
+ export declare function refuseAmbiguousRef(repoRoot: string, ref: string,
37
+ /** What the ref is used as, for the message: "the trust base", "the intent base". */
38
+ noun?: string): string | null;
39
+ /**
40
+ * What a rev resolves to at this repository, or null when it does not.
41
+ *
42
+ * `--quiet` suppresses git's own explanation, so there is nothing worth
43
+ * forwarding on failure: the caller writes a sentence a reader can act on
44
+ * rather than repeating the command line that failed.
45
+ */
46
+ export declare function resolveRev(repoRoot: string, rev: string, kind: 'commit' | 'tree'): string | null;
1
47
  /**
2
48
  * Whether HEAD's tree is byte-identical to the trust base's tree.
3
49
  *
@@ -54,11 +100,12 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
54
100
  * NAME on a pull_request or pull_request_target event, and empty everywhere
55
101
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
56
102
  * 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
103
+ * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
104
+ * base" step published (which must equal refs/conductor/trust-base, the
105
+ * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
106
+ * or is that private ref itself, or -- for an explicit trust base -- resolves
107
+ * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
108
+ * pull-request run through the action returns null here, before
62
109
  * refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
63
110
  * issue #69/#73 -- ever run: this check is narrower than those and says
64
111
  * nothing about HEAD or about tree equality, only about whether the given ref
@@ -66,11 +113,11 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
66
113
  * request's own branch, or anything else that disagrees, is refused with both
67
114
  * refs and both commits named.
68
115
  *
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.
116
+ * FAILS CLOSED when neither the private ref nor refs/remotes/origin/
117
+ * <githubBaseRef> exists, naming them: reachable through the CLI on the
118
+ * default actions/checkout (fetch-depth: 1), which does not carry the base
119
+ * branch at all. The README already asks for fetch-depth: 0, and a checkout
120
+ * that does not carry the base branch is not a reason to skip the comparison.
74
121
  *
75
122
  * When the GIVEN ref does not resolve at all, this returns null rather than
76
123
  * refusing: refuseTrustBaseRef is the function with its own sentence for an