@vaultcompass/conductor 0.17.0 → 0.18.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/README.md CHANGED
@@ -60,7 +60,7 @@ jobs:
60
60
  gates:
61
61
  runs-on: ubuntu-latest
62
62
  steps:
63
- - uses: actions/checkout@v7
63
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
64
64
  with:
65
65
  fetch-depth: 0
66
66
  - name: Install gitleaks and osv-scanner
@@ -76,8 +76,8 @@ jobs:
76
76
  echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
77
  chmod +x "$bin/osv-scanner"
78
78
  echo "$bin" >> "$GITHUB_PATH"
79
- - uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
80
- - uses: github/codeql-action/upload-sarif@v4
79
+ - uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
80
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
81
81
  if: always()
82
82
  with:
83
83
  sarif_file: conductor.sarif
@@ -151,7 +151,7 @@ required.
151
151
  product: osv-scanner
152
152
  ```
153
153
 
154
- **Globally, and that is the guidance for CI too.** A devDependency is
154
+ **Install globally; that is the guidance for CI too.** A devDependency is
155
155
  fine beside it for your own pre-commit hook, and nothing about a local
156
156
  run changed, but under the Action keep it at the Action's pin or a push
157
157
  run is could-not-run (see "The Action" below). It is not what gates
@@ -229,7 +229,7 @@ required.
229
229
 
230
230
  Your terminal also shows one status line per gate, written to stderr so a
231
231
  CI job log has a per-gate record even when the report goes to a file,
232
- such as `conductor: gate dependencies (dep-guard 0.18.1): ok, exit 0` or
232
+ such as `conductor: gate dependencies (dep-guard 0.20.0): ok, exit 0` or
233
233
  a `skipped (deferred to stage ci)` line for a deferred gate. They carry
234
234
  nothing the summary does not; to see only the summary, redirect stderr
235
235
  (`conductor run --staged --stage commit 2>/dev/null` in the hook).
@@ -237,15 +237,15 @@ required.
237
237
  A commit with a staged credential in it prints the full report and exits 1:
238
238
 
239
239
  ```
240
- conductor 0.17.0
240
+ conductor 0.18.1
241
241
  verdict-token: blocked (1)
242
242
  conductor run: 2 gate(s), 1 finding(s)
243
243
 
244
- dependencies dep-guard 0.18.1 exit 0 153ms via dep-guard on path
244
+ dependencies dep-guard 0.20.0 exit 0 153ms via dep-guard on path
245
245
  threshold medium suppressed 0 ignored 0
246
246
  mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
247
247
 
248
- secrets vault-guard 1.13.1 exit 1 105ms via vault-guard on path
248
+ secrets vault-guard 1.13.3 exit 1 105ms via vault-guard on path
249
249
  BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
250
250
  Possible secret of type 'anthropic'
251
251
  threshold medium suppressed 0 ignored not reported
@@ -287,8 +287,8 @@ required.
287
287
 
288
288
  2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
289
289
  and the workflow together, with `advisory: true` and `pr-comment: true`
290
- on the conductor step -- the recipe under "Running the gates as an
291
- advisory check" below is a complete copy-paste job -- and leave the check
290
+ on the conductor step (the recipe under "Running the gates as an
291
+ advisory check" below is a complete copy-paste job), and leave the check
292
292
  out of branch protection for this one pull request. The step still exits
293
293
  2 on this pull request even with `advisory: true`: the base branch has no
294
294
  policy yet, so the run has no rules, and `advisory` never touches that
@@ -305,7 +305,7 @@ required.
305
305
 
306
306
  4. **Go required.** Once a few ordinary pull requests have shown the report
307
307
  reads the way you expect, remove `advisory: true` from the conductor step
308
- and require the job's own check context in branch protection -- `gates`
308
+ and require the job's own check context in branch protection: `gates`
309
309
  in the recipes below, the job name, never the context the SARIF-upload
310
310
  step reports under. That is the whole of turning this from an advisory
311
311
  job into the one required check.
@@ -382,8 +382,11 @@ it is what makes a team switch a hook off.
382
382
  It is not a sixth gate. It finds no bugs of its own and scans nothing.
383
383
  Every finding about your code came from one of the five gates and is
384
384
  labelled with which one. The only findings it adds are about the gates
385
- themselves, and they are labelled `conductor`: a gate that is switched on
386
- and could not run, and a gate whose output it could not read. Those exist
385
+ themselves, and they are labelled `conductor`. Three can fail a run; the rest
386
+ are non-blocking notes, all listed under "What is in and what is out" below.
387
+ The main ones are a gate that is switched on and could not run, and a gate
388
+ whose output it could not read.
389
+ Those exist
387
390
  because a report that reads clean when nothing looked is the failure this
388
391
  whole family exists to prevent.
389
392
 
@@ -505,7 +508,14 @@ its configuration from the base branch and the pull request cannot change the
505
508
  rules it is judged by; a change to the rules shows as a proposal line and
506
509
  takes effect after merge. See
507
510
  [The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
508
- other event it passes nothing and behaviour is unchanged. The `trust-base`
511
+ other event it passes nothing and behaviour is unchanged. One shape passes a
512
+ different commit: when the base branch has moved to a commit with the exact
513
+ tree of the run's merge ref, as when a pull request lands while its job is
514
+ queued, that commit cannot judge the run, so the step moves the private ref to
515
+ the commit the merge ref was built from and prints a notice naming both. That
516
+ needs a full clone (`fetch-depth: 0`) and every control file listed in
517
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md) the same
518
+ at both commits; otherwise the run stays could-not-run, exit 2. The `trust-base`
509
519
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
510
520
  set. **On a `pull_request` or `pull_request_target` event this input is
511
521
  refused outright, in the validate step** (issue #58). On `pull_request` the
@@ -532,8 +542,8 @@ request being judged, and the version-pin protection described above
532
542
  "protects nothing" against a tree that controls its own judge (the
533
543
  validate step's own comment in `action.yml` says so in those words). A tag
534
544
  moves when someone pushes it. Name this action by owner and the full commit
535
- SHA instead. The recipes in this README name v0.16.0 that way, as
536
- `vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0`.
545
+ SHA instead. The recipes in this README name v0.18.0 that way, as
546
+ `vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0`.
537
547
 
538
548
  ```yaml
539
549
  name: guardrails
@@ -546,7 +556,7 @@ jobs:
546
556
  contents: read
547
557
  security-events: write
548
558
  steps:
549
- - uses: actions/checkout@v7
559
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
550
560
  with:
551
561
  # From 0.8.0 a shallow checkout on a pull-request run is
552
562
  # could-not-run for the history gate.
@@ -555,10 +565,10 @@ jobs:
555
565
  with:
556
566
  node-version: '22.23.4'
557
567
  - id: conductor
558
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
568
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
559
569
  with:
560
570
  output: conductor.sarif
561
- - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
571
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
562
572
  if: always()
563
573
  continue-on-error: true
564
574
  with:
@@ -599,8 +609,8 @@ refuses a pin below them, and that bump's own pull request goes red with
599
609
  nothing wrong in it. The fix is in the same pull request: raise each pinned
600
610
  line to the new tag's default (the CHANGELOG entry for the tag lists them,
601
611
  and so does the table in [Upgrading](docs/upgrading.md)), or delete it. The
602
- spelled-out example below names them when a workflow wants that
603
- transparency, and carries that cost.
612
+ example below leaves them out for that reason; add an exact forward pin when
613
+ a workflow needs one, and accept that it then has to be raised by hand.
604
614
 
605
615
  **The gates the Action installs are as new as the tag** (issue 146). A
606
616
  tag's defaults can reach npm the same day the tag does, so they can be
@@ -625,7 +635,7 @@ jobs:
625
635
  contents: read
626
636
  security-events: write
627
637
  steps:
628
- - uses: actions/checkout@v7
638
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
629
639
  with:
630
640
  # Required. From 0.8.0 a shallow checkout on a pull-request run is
631
641
  # could-not-run for the history gate. Without a full history there
@@ -654,21 +664,18 @@ jobs:
654
664
  # installs those itself, globally. Leave conductor-version unset so the
655
665
  # umbrella is the default in the pinned action.yml.
656
666
  - id: conductor
657
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
667
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
658
668
  with:
659
669
  output: conductor.sarif
660
- # Exact versions, never a range and never "latest". These three
661
- # lines decide which gate programs judge a pull request, so a pull
662
- # request's own lockfile no longer does. They are only as protected
663
- # as this file is: require review on .github/workflows in your
664
- # branch protection. Bump them like any other pin, in a pull
665
- # request of their own. On a pull request the action refuses a pin
666
- # below what the pinned action.yml ships, and the three lines can
667
- # be left out entirely to take that action's own versions.
668
- dep-guard-version: 0.18.1
669
- vault-guard-version: 1.13.1
670
- intent-guard-version: 1.10.4
671
- - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
670
+ # The gate versions are left out on purpose: the defaults travel
671
+ # with the tag above, so a bump of that line moves the gates with it.
672
+ # To pin a gate forward, add an exact version such as
673
+ # `dep-guard-version: x.y.z`, never a range and never "latest". A
674
+ # pin decides which gate program judges a pull request, so it is
675
+ # only as protected as this file is: require review on
676
+ # .github/workflows in your branch protection. On a pull request the
677
+ # action refuses a pin below what the pinned action.yml ships.
678
+ - uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
672
679
  # Always: the log is most worth having on the run that failed.
673
680
  if: always()
674
681
  # The sarif path is published BEFORE the gates run, so on the exit 2
@@ -687,7 +694,7 @@ jobs:
687
694
  build:
688
695
  runs-on: ubuntu-latest
689
696
  steps:
690
- - uses: actions/checkout@v7
697
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
691
698
  - uses: pnpm/action-setup@v4
692
699
  - uses: actions/setup-node@v7
693
700
  with:
@@ -710,8 +717,12 @@ keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
710
717
  (`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
711
718
  `.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
712
719
  credential helpers, `core.sshCommand`), git hooks such as
713
- `reference-transaction`, and replace refs or grafts. Say it plainly:
714
- package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
720
+ `reference-transaction`, and replace refs or grafts. (The action's fetch, gates
721
+ and fallback render steps set `GIT_NO_REPLACE_OBJECTS=1` for themselves and
722
+ for the gates they run, which narrows replace refs. The fetch step alone also
723
+ reads through a graft file, for its decision to move the trust base; the gates
724
+ and the CLI still see one.)
725
+ Say it plainly: package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
715
726
  `prepare`) run by an install bypass "require review on `.github/workflows`",
716
727
  because the pull request supplies them, not the workflow file. Branch
717
728
  protection on the workflow directory does not stop them, so the gates must
@@ -862,7 +873,7 @@ jobs:
862
873
  contents: read
863
874
  pull-requests: write
864
875
  steps:
865
- - uses: actions/checkout@v7
876
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
866
877
  with:
867
878
  # From 0.8.0 a shallow checkout on a pull-request run is
868
879
  # could-not-run for the history gate.
@@ -876,7 +887,7 @@ jobs:
876
887
  # seconds) plus 300 seconds for the preview, rounded up. A step
877
888
  # timeout below that can kill a full gitleaks scan and leave no verdict.
878
889
  timeout-minutes: 30
879
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
890
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
880
891
  with:
881
892
  pr-comment: true
882
893
  advisory: true
@@ -1012,7 +1023,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1012
1023
  # the pull request runs before the action in this job: no install, build
1013
1024
  # or test step here; those belong in a separate job. ...
1014
1025
  - id: conductor
1015
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1026
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1016
1027
  with:
1017
1028
  output: conductor.sarif
1018
1029
  pr-comment: true
@@ -1091,12 +1102,12 @@ per pull request.
1091
1102
 
1092
1103
  ```yaml
1093
1104
  - id: conductor-package-a
1094
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1105
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1095
1106
  with:
1096
1107
  pr-comment: true
1097
1108
  pr-comment-marker: 'package-a'
1098
1109
  - id: conductor-package-b
1099
- uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1110
+ uses: vaultcompasshq/conductor@717e6f5ff6acc934344c2ab49643ece615d5c9ff # v0.18.0
1100
1111
  with:
1101
1112
  pr-comment: true
1102
1113
  pr-comment-marker: 'package-b'
@@ -1214,12 +1225,14 @@ binary (the adopter installs gitleaks and osv-scanner), and any finding of
1214
1225
  the umbrella's own about
1215
1226
  anybody's CODE. The findings it does raise are all about the gates
1216
1227
  themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
1217
- and `conductor/gate-failed`, plus the two diagnostics
1218
- `conductor/blocking-count-mismatch` and
1219
- `conductor/blocking-threshold-unknown`.
1228
+ and `conductor/gate-failed`, which count toward the exit code, and diagnostics
1229
+ that never do: `conductor/blocking-count-mismatch` and
1230
+ `conductor/blocking-threshold-unknown`, plus the `conductor/` notes on what the
1231
+ vulnerabilities gate was handed and how it was run, such as
1232
+ `conductor/lockfiles-empty`.
1220
1233
 
1221
1234
  Also out: intent at the cohesion level, which is what a merge or a
1222
- promotion would want and which the audits do by hand today; and anything that
1235
+ promotion would want; and anything that
1223
1236
  runs inside an agent session or on save, which intent-guard's own optional
1224
1237
  session hooks already cover.
1225
1238
 
package/dist/cli.js CHANGED
@@ -18,7 +18,7 @@ import { gateLogLines, jobLogSummary, previewLogLines, proposalLogLines, renderT
18
18
  import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
19
19
  import { diffPolicies, previewPolicy, previewRoles } from './policy-diff.js';
20
20
  import { refusedTrustBase, runAll } from './run.js';
21
- import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
21
+ import { headTreeEqualsBase, withMovedBaseTip, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
22
22
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
23
23
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
24
24
  /**
@@ -631,10 +631,10 @@ export function buildProgram() {
631
631
  .option('--preview', 'pull-request mode only: when the pull request changes a gate\'s enabled or stage, run those gates once more under the proposed values, as a preview that never changes the exit code or the verdict. Every other policy key still comes from the base ref, and so do the gitleaks and osv-scanner configs; dep-guard and vault-guard read their own config files from the head. Not on --staged.')
632
632
  .option('--format <format>', 'output format: text or sarif')
633
633
  .option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
634
- .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
635
- .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
634
+ .option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base the action resolved (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
635
+ .option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event, or the commit the merge ref was built from when the fetched tip has the merge ref\'s exact tree.')
636
636
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
637
- .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, or had no contract), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
637
+ .option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, had no contract, or was handed an empty change set), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
638
638
  .option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention. On a pull-request run (--trust-base) the spec is read from the base ref, and a frozen contract on the base takes precedence over it')
639
639
  .option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
640
640
  .option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
@@ -697,7 +697,7 @@ export function buildProgram() {
697
697
  ...(stage === undefined ? {} : { stage }),
698
698
  ...(options.base === undefined ? {} : { base: options.base }),
699
699
  ...(options.spec === undefined ? {} : { spec: options.spec }),
700
- ...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
700
+ ...(source.trustBase === undefined ? {} : { trustBase: withMovedBaseTip(root, source.trustBase, process.env.CONDUCTOR_BASE_TIP) }),
701
701
  // Only on request, never on --staged, and only with a trust
702
702
  // base and a preview policy: a head that parsed and changed
703
703
  // at least one role's enabled or stage.
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Every character outside printable ASCII as a \uXXXX escape (an astral
3
+ * character as its two surrogate escapes), so head-chosen text cannot smuggle
4
+ * a bidi override or a zero-width character into the report. Used for a head
5
+ * policy value (renderValue, src/policy-diff.ts), and for every preview line
6
+ * (cleanPreviewLine, src/gate-runner.ts), whose gate text the head's own
7
+ * control files can choose (audit 2026-10-27, N3).
8
+ */
9
+ export declare function escapeNonAscii(text: string): string;
package/dist/escape.js ADDED
@@ -0,0 +1,14 @@
1
+ // Pure text sanitizers with no dependency on any other module here, so a
2
+ // renderer or the gate runner can import them without importing the policy
3
+ // diff or anything heavier.
4
+ /**
5
+ * Every character outside printable ASCII as a \uXXXX escape (an astral
6
+ * character as its two surrogate escapes), so head-chosen text cannot smuggle
7
+ * a bidi override or a zero-width character into the report. Used for a head
8
+ * policy value (renderValue, src/policy-diff.ts), and for every preview line
9
+ * (cleanPreviewLine, src/gate-runner.ts), whose gate text the head's own
10
+ * control files can choose (audit 2026-10-27, N3).
11
+ */
12
+ export function escapeNonAscii(text) {
13
+ return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
14
+ }
@@ -351,6 +351,7 @@ export interface GateOutcome {
351
351
  contractSource: ContractSource;
352
352
  baseRef: string | null;
353
353
  note?: string;
354
+ changedPaths?: number;
354
355
  };
355
356
  /**
356
357
  * Present only on a pull-request run. Whether this gate was put into
@@ -1217,7 +1217,7 @@ export function runGate(gate, options) {
1217
1217
  intent: {
1218
1218
  contractSource: options.intent.contractSource,
1219
1219
  baseRef: options.intent.baseRef,
1220
- ...(options.intent.note === undefined ? {} : { note: options.intent.note }),
1220
+ ...(options.intent.note === undefined ? {} : { note: options.intent.note }), ...(options.intent.paths === null ? {} : { changedPaths: options.intent.paths.length }),
1221
1221
  },
1222
1222
  }
1223
1223
  : options.intentContract === undefined
@@ -1078,10 +1078,7 @@ function prepareAgainstTrustBase(options, trustBase) {
1078
1078
  proposals.push(`${headSpec} is a spec in this pull request but not on "${trustBase}": it is a proposal, ` +
1079
1079
  'and pull requests are judged against it once it is on the base branch.');
1080
1080
  }
1081
- return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" carries no frozen ` +
1082
- `${NATIVE_CONTRACT_PATHS.join(' or ')} and no spec under ${SPEC_DIR} for ` +
1083
- `${branch === null ? 'this branch' : `branch "${branch}"`}. On a pull-request run the ` +
1084
- 'intent contract comes from the base ref only, so nothing in this pull request can ' +
1085
- 'become it; once a contract or spec is on the base branch, the next pull request is ' +
1086
- 'judged against it.', proposals, trustBase);
1081
+ return noSpecChosen(branch, atBase.selection, `No contract on the base: "${trustBase}" has no frozen contract or spec for ` +
1082
+ `${branch === null ? 'this branch' : `branch "${branch}"`}. See ` +
1083
+ 'https://github.com/vaultcompasshq/conductor/blob/main/docs/intent-at-a-pull-request.md', proposals, trustBase);
1087
1084
  }
@@ -9,6 +9,7 @@ import path from 'node:path';
9
9
  import { runGit } from './git.js';
10
10
  import { osvLockfileKind } from './products.js';
11
11
  import { checkRequirementsPins, describePinProblem, } from './requirements-pin.js';
12
+ import { LOCKFILE_NO_LONGER_SCANNED, REQUIREMENTS_DIRECT_ONLY, REQUIREMENTS_NOT_PINNED, REQUIREMENTS_NOT_SCANNED, } from './rule-ids.js';
12
13
  import { readFileAtRefBytes } from './trust-base.js';
13
14
  /**
14
15
  * A reader over the head: a TRACKED regular file on disk. On disk because
@@ -102,7 +103,7 @@ export function selectOsvInputs(args) {
102
103
  suffix = ' Newly pinned in this pull request.';
103
104
  }
104
105
  }
105
- notes.push({ code: 'conductor/requirements-direct-only', message: `${file}: ${DIRECT_ONLY}${suffix}` });
106
+ notes.push({ code: REQUIREMENTS_DIRECT_ONLY, message: `${file}: ${DIRECT_ONLY}${suffix}` });
106
107
  continue;
107
108
  }
108
109
  if (base !== null) {
@@ -116,18 +117,18 @@ export function selectOsvInputs(args) {
116
117
  ? 'Its copy on the base is pinned, so the file stays scanned under the ratchet; the lines named are read as written.'
117
118
  : 'Its copy on the base could not be read, so the file stays scanned; the lines named are read as written.';
118
119
  diagnostics.push({
119
- code: 'conductor/requirements-not-pinned',
120
+ code: REQUIREMENTS_NOT_PINNED,
120
121
  message: `${file} is scanned although ${lines}. ${why}`,
121
122
  });
122
123
  notes.push({
123
- code: 'conductor/requirements-direct-only',
124
+ code: REQUIREMENTS_DIRECT_ONLY,
124
125
  message: `${file}: ${DIRECT_ONLY} ${baseCheck.pinned ? 'Pinned on the base; scanned under the ratchet.' : 'Base copy unreadable; scanned under the ratchet.'}`,
125
126
  });
126
127
  continue;
127
128
  }
128
129
  }
129
130
  notScanned.push(file);
130
- diagnostics.push({ code: 'conductor/requirements-not-scanned', message: notScannedMessage(file, headCheck) });
131
+ diagnostics.push({ code: REQUIREMENTS_NOT_SCANNED, message: notScannedMessage(file, headCheck) });
131
132
  }
132
133
  return { handed: handed.sort(), notScanned, diagnostics, notes, closures };
133
134
  }
@@ -142,7 +143,7 @@ export function selectOsvInputs(args) {
142
143
  */
143
144
  export function noLongerScanned(repoRoot, ref, tracked) {
144
145
  return (noLongerScannedFiles(repoRoot, ref, tracked) ?? []).map((file) => ({
145
- code: 'conductor/lockfile-no-longer-scanned',
146
+ code: LOCKFILE_NO_LONGER_SCANNED,
146
147
  message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
147
148
  '(by either run). Its removal is visible in the diff.',
148
149
  }));
@@ -121,7 +121,7 @@ import { gateExitBlocks } from './exit-codes.js';
121
121
  import { cleanPreviewLine } from './gate-runner.js';
122
122
  import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
123
123
  import { INTENT_WARNING } from './normalize.js';
124
- import { gateOutcomeWords, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
124
+ import { baseMovedSentences, gateOutcomeWords, intentEmptyChangeSet, intentNothingWording, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
125
125
  import { POLICY_FILE_NAME } from './policy.js';
126
126
  import { policyChangeLine } from './policy-diff.js';
127
127
  import { guardPreview } from './run.js';
@@ -426,7 +426,7 @@ fallbackUri, properties, invocation) {
426
426
  * summary or an exit code.
427
427
  */
428
428
  function diagnosticFindings(result) {
429
- return result.gates.flatMap((gate) => gate.diagnostics.map((diagnostic) => ({
429
+ return result.gates.flatMap((gate) => gate.diagnostics.filter((diagnostic) => diagnostic.code !== NOTHING_TO_SCAN).map((diagnostic) => ({
430
430
  schemaVersion: 1,
431
431
  product: UMBRELLA_DRIVER_NAME,
432
432
  productVersion: null,
@@ -1089,7 +1089,7 @@ export function renderSarif(result, umbrellaVersion) {
1089
1089
  ...deferredNotifications(result),
1090
1090
  ...excludedNotifications(result),
1091
1091
  ...treeUnchangedNotifications(result),
1092
- ...skippedNotifications(result),
1092
+ ...skippedNotifications(result), ...emptyChangeSetNotifications(result), ...nothingToScanNotifications(result), ...baseMovedNotifications(result),
1093
1093
  ...unenforcedNotifications(result),
1094
1094
  ...legacyStateDirNotifications(result),
1095
1095
  ...weakMatchNotifications(result),
@@ -1146,3 +1146,48 @@ export function renderSarif(result, umbrellaVersion) {
1146
1146
  }
1147
1147
  return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
1148
1148
  }
1149
+ /**
1150
+ * The base branch moved past the merge ref, as a notification: what this run
1151
+ * was judged against is a statement about the run. The same sentence as the
1152
+ * text report.
1153
+ */
1154
+ function baseMovedNotifications(result) {
1155
+ return baseMovedSentences(result).map((message) => ({
1156
+ id: 'conductor/base-moved',
1157
+ message,
1158
+ details: { ref: result.trustBase?.ref ?? null, baseTip: result.trustBase?.baseTip ?? null },
1159
+ }));
1160
+ }
1161
+ /**
1162
+ * An intent gate that ran with a contract on no changed paths, as a notification:
1163
+ * how much a run covered, by the rule at skippedNotifications. In the gate's own
1164
+ * namespace, like its no-contract skip, with the words of the verdict sentence. A
1165
+ * gate with no contract is left to that skip, which already says it checked nothing.
1166
+ */
1167
+ function emptyChangeSetNotifications(result) {
1168
+ return result.gates
1169
+ .filter((gate) => intentEmptyChangeSet(gate) && !intentCheckedNothing(gate))
1170
+ .map((gate) => ({
1171
+ id: `${gate.product}/empty-change-set`,
1172
+ message: `${intentNothingWording(gate)}.`,
1173
+ details: { role: gate.role, product: gate.product, reason: 'empty-change-set' },
1174
+ }));
1175
+ }
1176
+ /** The gate diagnostic the log carries as a notification, never a result. */
1177
+ const NOTHING_TO_SCAN = 'conductor/nothing-to-scan';
1178
+ /**
1179
+ * A gate with nothing to scan, as a notification.
1180
+ *
1181
+ * True on every run until somebody adds a lockfile, so by the rule at
1182
+ * skippedNotifications it says how much a run covered and is not a result. The
1183
+ * sentence is the gate's diagnostic, unchanged, which the text report prints too.
1184
+ */
1185
+ function nothingToScanNotifications(result) {
1186
+ return result.gates.flatMap((gate) => gate.diagnostics
1187
+ .filter((diagnostic) => diagnostic.code === NOTHING_TO_SCAN)
1188
+ .map((diagnostic) => ({
1189
+ id: diagnostic.code,
1190
+ message: diagnostic.message,
1191
+ details: { role: gate.role, product: gate.product },
1192
+ })));
1193
+ }
@@ -148,8 +148,8 @@ export declare function versionSkewSummaryLines(result: RunResult): string[];
148
148
  * nothing-checked exit 0, but nothing was checked: no gate ran at
149
149
  * all (none enabled, or every one deferred,
150
150
  * tree-unchanged or skipped), or every gate that
151
- * ran checked nothing (nothing to scan, or no
152
- * contract; audit finding F4)
151
+ * ran checked nothing (nothing to scan, no contract,
152
+ * or an empty change set; audit finding F4)
153
153
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
154
154
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
155
155
  * could not run
@@ -267,4 +267,22 @@ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two
267
267
  */
268
268
  export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
269
269
  export declare function renderText(result: RunResult, options?: TextOptions): string;
270
+ /**
271
+ * An intent gate that ran with a contract on a change set of no paths: a branch
272
+ * the base it was measured against already carries, or a net-empty one. The
273
+ * gate says it is clean and it is, about nothing. Never for a gate that could
274
+ * not run or that blocked: every could-not-run outcome carries a blocking finding,
275
+ * so the one clause covers both. It does its work in the SARIF notification, which
276
+ * reads this directly; the text report sorts those gates out before it gets here.
277
+ */
278
+ export declare function intentEmptyChangeSet(gate: GateOutcome): boolean;
279
+ /** How the verdict sentence names an intent gate that ran and checked nothing. */
280
+ export declare function intentNothingWording(gate: GateOutcome): string;
281
+ /**
282
+ * Why the rules commit is not the base branch's tip, on a run the Action moved
283
+ * past it, as a list of one, or of none. Says what happened and never that
284
+ * anything merged: the same shape occurs on an open pull request. The text
285
+ * report and the SARIF log read this one sentence, so they cannot disagree.
286
+ */
287
+ export declare function baseMovedSentences(result: RunResult): string[];
270
288
  export {};
@@ -605,7 +605,7 @@ function trustBaseLines(result) {
605
605
  for (const { gate, reason } of withheldTrustBase(result)) {
606
606
  lines.push(` NOT in pull-request mode ${gate.role} ${gate.product} ${reason}`);
607
607
  }
608
- lines.push(...nodeModulesSkippedLine(result));
608
+ lines.push(...baseMovedSentences(result).map((moved) => ` ${moved}`), ...nodeModulesSkippedLine(result));
609
609
  return lines;
610
610
  }
611
611
  /**
@@ -722,7 +722,7 @@ export function gateOutcomeWords(gate) {
722
722
  }
723
723
  const total = gate.findings.length;
724
724
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
725
- let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
725
+ let outcome = total === 0 && (gate.exitCode ?? 0) === 0 ? intentCleanWords(gate) : `findings (${total}, ${blocking} blocking)`;
726
726
  // Only when the gate said so; the outcome word above is unchanged.
727
727
  const coverage = deadlineCoverage(gate);
728
728
  if (coverage !== null) {
@@ -956,8 +956,8 @@ function blockingCount(gate) {
956
956
  * nothing-checked exit 0, but nothing was checked: no gate ran at
957
957
  * all (none enabled, or every one deferred,
958
958
  * tree-unchanged or skipped), or every gate that
959
- * ran checked nothing (nothing to scan, or no
960
- * contract; audit finding F4)
959
+ * ran checked nothing (nothing to scan, no contract,
960
+ * or an empty change set; audit finding F4)
961
961
  * advisory-blocked (N) exit 1 that --advisory turned into exit 0
962
962
  * unenforced-findings (N) exit 0, but enforce: false gates blocked or
963
963
  * could not run
@@ -1021,8 +1021,8 @@ export function verdictToken(result, advisory) {
1021
1021
  * A gate that ran and examined nothing: osv-scanner with nothing to scan,
1022
1022
  * osv-scanner whose every handed lockfile parsed to no packages (exit 128,
1023
1023
  * marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
1024
- * same news as no lockfile), or an intent gate that found no contract to
1025
- * check against. The one predicate behind both the verdict token and the
1024
+ * same news as no lockfile), or an intent gate with no contract to check
1025
+ * against or no changed path. The one predicate behind both the verdict token and the
1026
1026
  * verdict sentence's list of what was not checked.
1027
1027
  *
1028
1028
  * NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
@@ -1039,7 +1039,7 @@ function gateCheckedNothing(gate) {
1039
1039
  }
1040
1040
  return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
1041
1041
  readNoPackages(gate) ||
1042
- intentCheckedNothing(gate));
1042
+ intentCheckedNothing(gate) || intentEmptyChangeSet(gate));
1043
1043
  }
1044
1044
  /**
1045
1045
  * The gate's own skipReason (intent-guard 1.10.4, issue 103), or null. Put
@@ -1067,7 +1067,7 @@ export function intentCheckedNothing(gate) {
1067
1067
  /** How the verdict sentence names a gate that ran and checked nothing. */
1068
1068
  function checkedNothingWording(gate) {
1069
1069
  if (gate.role === 'intent') {
1070
- return `${gate.role} ran but found no contract to check against`;
1070
+ return intentNothingWording(gate);
1071
1071
  }
1072
1072
  return readNoPackages(gate)
1073
1073
  ? `${gate.role} read no packages from its lockfiles`
@@ -1271,7 +1271,7 @@ function verdictForRun(result, advisory) {
1271
1271
  function isFullyClean(result) {
1272
1272
  // Every gate that ran checked nothing is the nothing-checked token's state
1273
1273
  // (audit finding F4), and a line opening "clean" would contradict it.
1274
- if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
1274
+ if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing) || result.gates.some(intentEmptyChangeSet)) {
1275
1275
  return false;
1276
1276
  }
1277
1277
  // A tie the convention refused to guess, or a skip whose branch 0.10.0
@@ -1501,7 +1501,7 @@ function summaryLine(result) {
1501
1501
  // produces a clean report, and without this clause the only trace of the
1502
1502
  // attempt would be in a file nobody re-reads.
1503
1503
  if (result.trustBase !== null) {
1504
- parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`);
1504
+ parts.push(`Rules from ${result.trustBase.ref}. ${proposalCount(result)}.`, ...baseMovedSentences(result));
1505
1505
  const withheld = withheldTrustBase(result);
1506
1506
  if (withheld.length > 0) {
1507
1507
  const names = withheld.map(({ gate }) => `${gate.role} (${gate.product})`).join(', ');
@@ -1613,3 +1613,48 @@ export function renderText(result, options = {}) {
1613
1613
  lines.push('', verdict(result, Boolean(options.advisory)));
1614
1614
  return withPreview(`${lines.join('\n')}\n`);
1615
1615
  }
1616
+ /**
1617
+ * An intent gate that ran with a contract on a change set of no paths: a branch
1618
+ * the base it was measured against already carries, or a net-empty one. The
1619
+ * gate says it is clean and it is, about nothing. Never for a gate that could
1620
+ * not run or that blocked: every could-not-run outcome carries a blocking finding,
1621
+ * so the one clause covers both. It does its work in the SARIF notification, which
1622
+ * reads this directly; the text report sorts those gates out before it gets here.
1623
+ */
1624
+ export function intentEmptyChangeSet(gate) {
1625
+ return (gate.role === 'intent' &&
1626
+ !gate.findings.some((finding) => finding.blocking) &&
1627
+ gate.intent?.changedPaths === 0);
1628
+ }
1629
+ /** How the verdict sentence names an intent gate that ran and checked nothing. */
1630
+ export function intentNothingWording(gate) {
1631
+ return intentCheckedNothing(gate)
1632
+ ? `${gate.role} ran but found no contract to check against`
1633
+ : `${gate.role} ran on an empty change set, so no path was judged against its contract`;
1634
+ }
1635
+ /**
1636
+ * The outcome word on a gate's log line when it found nothing and exited 0. An
1637
+ * intent gate with no contract gets the words of the pull-request path's skipped
1638
+ * line for the same state, though it did run and so has an exit code to give.
1639
+ */
1640
+ function intentCleanWords(gate) {
1641
+ if (intentCheckedNothing(gate)) {
1642
+ return `skipped (${skipWording('no-contract').line})`;
1643
+ }
1644
+ return intentEmptyChangeSet(gate) ? 'ok, empty change set' : 'ok';
1645
+ }
1646
+ /**
1647
+ * Why the rules commit is not the base branch's tip, on a run the Action moved
1648
+ * past it, as a list of one, or of none. Says what happened and never that
1649
+ * anything merged: the same shape occurs on an open pull request. The text
1650
+ * report and the SARIF log read this one sentence, so they cannot disagree.
1651
+ */
1652
+ export function baseMovedSentences(result) {
1653
+ const trust = result.trustBase;
1654
+ return trust === null || trust.baseTip === undefined
1655
+ ? []
1656
+ : [
1657
+ `The base branch moved past the merge ref this run is on, to ${trust.baseTip}, which has ` +
1658
+ `the same tree, so the rules are from ${trust.ref}, the commit the merge ref was built from.`,
1659
+ ];
1660
+ }
@@ -1,3 +1,4 @@
1
+ import { escapeNonAscii } from './escape.js';
1
2
  import type { GateRole, Policy } from './policy.js';
2
3
  export interface PolicyKeyChange {
3
4
  /** The gate role the key belongs to, or null for a key outside any gate. */
@@ -14,15 +15,7 @@ export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
14
15
  * file's. A null head (absent or unparseable) is one change that says so.
15
16
  */
16
17
  export declare function diffPolicies(base: Policy, head: Policy | null): PolicyKeyChange[];
17
- /**
18
- * Every character outside printable ASCII as a \uXXXX escape (an astral
19
- * character as its two surrogate escapes), so head-chosen text cannot smuggle
20
- * a bidi override or a zero-width character into the report. Used for a head
21
- * policy value here, and for every preview line (cleanPreviewLine,
22
- * src/gate-runner.ts), whose gate text the head's own control files can
23
- * choose (audit 2026-10-27, N3).
24
- */
25
- export declare function escapeNonAscii(text: string): string;
18
+ export { escapeNonAscii };
26
19
  /** One proposal line for one changed key. */
27
20
  export declare function policyChangeLine(change: PolicyKeyChange): string;
28
21
  /**
@@ -8,6 +8,7 @@
8
8
  // verdict. The one place a head value goes further is `previewPolicy`, which
9
9
  // takes only `enabled`, `stage` and `enforce` from it for the preview under
10
10
  // the proposed rules, a run that decides nothing.
11
+ import { escapeNonAscii } from './escape.js';
11
12
  import { GATE_ROLES, PRODUCT_FOR_ROLE, parsePolicy } from './policy.js';
12
13
  export const HEAD_POLICY_KEY = '.guardrails.yaml';
13
14
  const MAX_VALUE_LENGTH = 80;
@@ -92,17 +93,9 @@ export function diffPolicies(base, head) {
92
93
  }
93
94
  return changes;
94
95
  }
95
- /**
96
- * Every character outside printable ASCII as a \uXXXX escape (an astral
97
- * character as its two surrogate escapes), so head-chosen text cannot smuggle
98
- * a bidi override or a zero-width character into the report. Used for a head
99
- * policy value here, and for every preview line (cleanPreviewLine,
100
- * src/gate-runner.ts), whose gate text the head's own control files can
101
- * choose (audit 2026-10-27, N3).
102
- */
103
- export function escapeNonAscii(text) {
104
- return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
105
- }
96
+ // escapeNonAscii lives in src/escape.ts, a dependency-free leaf; it is
97
+ // re-exported here so existing importers keep working unchanged.
98
+ export { escapeNonAscii };
106
99
  function renderValue(value) {
107
100
  if (value === undefined)
108
101
  return '(absent)';
@@ -0,0 +1,41 @@
1
+ export type RuleIdClass = 'finding' | 'diagnostic' | 'notification';
2
+ export declare const GATE_MISSING = "conductor/gate-missing";
3
+ export declare const GATE_FAILED = "conductor/gate-failed";
4
+ export declare const GATE_OUTPUT_UNPARSEABLE = "conductor/gate-output-unparseable";
5
+ export declare const INTENT_GATE_BLOCKED = "intent-guard/gate-blocked";
6
+ export declare const BLOCKING_COUNT_MISMATCH = "conductor/blocking-count-mismatch";
7
+ export declare const BLOCKING_THRESHOLD_UNKNOWN = "conductor/blocking-threshold-unknown";
8
+ export declare const NOTHING_TO_SCAN = "conductor/nothing-to-scan";
9
+ export declare const LOCKFILES_EMPTY = "conductor/lockfiles-empty";
10
+ export declare const LOCKFILE_NO_LONGER_SCANNED = "conductor/lockfile-no-longer-scanned";
11
+ export declare const MANIFESTS_NOT_HANDED = "conductor/manifests-not-handed";
12
+ export declare const OPTION_OVERRIDDEN = "conductor/option-overridden";
13
+ export declare const BASE_COMPARISON_UNAVAILABLE = "conductor/base-comparison-unavailable";
14
+ export declare const REQUIREMENTS_DIRECT_ONLY = "conductor/requirements-direct-only";
15
+ export declare const REQUIREMENTS_NOT_PINNED = "conductor/requirements-not-pinned";
16
+ export declare const REQUIREMENTS_NOT_SCANNED = "conductor/requirements-not-scanned";
17
+ export declare const INTENT_WARNING = "intent-guard/warning";
18
+ export declare const GATE_DEFERRED = "conductor/gate-deferred";
19
+ export declare const GATE_EXCLUDED = "conductor/gate-excluded";
20
+ export declare const GATE_NOT_ENFORCED = "conductor/gate-not-enforced";
21
+ export declare const TREE_UNCHANGED = "conductor/tree-unchanged";
22
+ export declare const BASE_MOVED = "conductor/base-moved";
23
+ export declare const CONTROL_CHANGE_PROPOSED = "conductor/control-change-proposed";
24
+ export declare const PREVIEW_UNDER_PROPOSED_RULES = "conductor/preview-under-proposed-rules";
25
+ export declare const TRUST_BASE_REFUSED = "conductor/trust-base-refused";
26
+ export declare const TRUST_BASE_NOT_PASSED = "conductor/trust-base-not-passed";
27
+ export declare const GATE_PROGRAM_REFUSED = "conductor/gate-program-refused";
28
+ export declare const NODE_MODULES_SKIPPED = "conductor/node-modules-skipped";
29
+ export declare const VERSION_SKEW = "conductor/version-skew";
30
+ export declare const OPTION_IS_GATE_OWN = "conductor/option-is-gate-own";
31
+ export declare const INTENT_LEGACY_STATE_DIR = "intent-guard/legacy-state-dir";
32
+ export declare const INTENT_NO_CONTRACT = "intent-guard/no-contract";
33
+ export declare const INTENT_CONTRACT_WAIVED = "intent-guard/contract-waived";
34
+ export declare const INTENT_SPEC_AMBIGUOUS = "intent-guard/spec-ambiguous";
35
+ export declare const INTENT_SPEC_WEAK_MATCH = "intent-guard/spec-weak-match";
36
+ export declare const INTENT_EMPTY_CHANGE_SET = "intent-guard/empty-change-set";
37
+ /** Every id above, with its class. */
38
+ export declare const RULE_IDS: ReadonlyArray<{
39
+ id: string;
40
+ class: RuleIdClass;
41
+ }>;
@@ -0,0 +1,98 @@
1
+ // Every rule id the umbrella writes, as a named constant with its class.
2
+ // tests/rule-ids.test.ts holds this to every id literal under src in any
3
+ // quote style, every template id of the form product/suffix, and every
4
+ // skip reason that becomes the second half of an id.
5
+ //
6
+ // These strings are frozen public surface: they are SARIF rule and
7
+ // notification ids, and the codes of the umbrella's diagnostics, and a
8
+ // consumer matches on them. A value here never changes; a new id is added,
9
+ // never renamed in place.
10
+ //
11
+ // The class says what kind of record carries the id when the umbrella
12
+ // writes it, not where a renderer later files it:
13
+ // - finding: a Finding the umbrella raises itself (src/normalize.ts).
14
+ // - diagnostic: a Diagnostic record, an umbrella diagnostic or a run note,
15
+ // which never counts toward the exit code.
16
+ // - notification: a SARIF tool-execution notification on the umbrella's run.
17
+ //
18
+ // Call sites are moving to these constants one file at a time; a site that
19
+ // still writes the literal must write exactly the value here.
20
+ // Findings.
21
+ export const GATE_MISSING = 'conductor/gate-missing';
22
+ export const GATE_FAILED = 'conductor/gate-failed';
23
+ export const GATE_OUTPUT_UNPARSEABLE = 'conductor/gate-output-unparseable';
24
+ export const INTENT_GATE_BLOCKED = 'intent-guard/gate-blocked';
25
+ // Diagnostics.
26
+ export const BLOCKING_COUNT_MISMATCH = 'conductor/blocking-count-mismatch';
27
+ export const BLOCKING_THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
28
+ export const NOTHING_TO_SCAN = 'conductor/nothing-to-scan';
29
+ export const LOCKFILES_EMPTY = 'conductor/lockfiles-empty';
30
+ export const LOCKFILE_NO_LONGER_SCANNED = 'conductor/lockfile-no-longer-scanned';
31
+ export const MANIFESTS_NOT_HANDED = 'conductor/manifests-not-handed';
32
+ export const OPTION_OVERRIDDEN = 'conductor/option-overridden';
33
+ export const BASE_COMPARISON_UNAVAILABLE = 'conductor/base-comparison-unavailable';
34
+ export const REQUIREMENTS_DIRECT_ONLY = 'conductor/requirements-direct-only';
35
+ export const REQUIREMENTS_NOT_PINNED = 'conductor/requirements-not-pinned';
36
+ export const REQUIREMENTS_NOT_SCANNED = 'conductor/requirements-not-scanned';
37
+ export const INTENT_WARNING = 'intent-guard/warning';
38
+ // Notifications.
39
+ export const GATE_DEFERRED = 'conductor/gate-deferred';
40
+ export const GATE_EXCLUDED = 'conductor/gate-excluded';
41
+ export const GATE_NOT_ENFORCED = 'conductor/gate-not-enforced';
42
+ export const TREE_UNCHANGED = 'conductor/tree-unchanged';
43
+ export const BASE_MOVED = 'conductor/base-moved';
44
+ export const CONTROL_CHANGE_PROPOSED = 'conductor/control-change-proposed';
45
+ export const PREVIEW_UNDER_PROPOSED_RULES = 'conductor/preview-under-proposed-rules';
46
+ export const TRUST_BASE_REFUSED = 'conductor/trust-base-refused';
47
+ export const TRUST_BASE_NOT_PASSED = 'conductor/trust-base-not-passed';
48
+ export const GATE_PROGRAM_REFUSED = 'conductor/gate-program-refused';
49
+ export const NODE_MODULES_SKIPPED = 'conductor/node-modules-skipped';
50
+ export const VERSION_SKEW = 'conductor/version-skew';
51
+ export const OPTION_IS_GATE_OWN = 'conductor/option-is-gate-own';
52
+ export const INTENT_LEGACY_STATE_DIR = 'intent-guard/legacy-state-dir';
53
+ // These five are written in src/output-sarif.ts as a template on the gate's
54
+ // product, which only an intent gate reaches, so the value written is the
55
+ // one here. The skip reasons are SkippedGate.reason in src/run.ts.
56
+ export const INTENT_NO_CONTRACT = 'intent-guard/no-contract';
57
+ export const INTENT_CONTRACT_WAIVED = 'intent-guard/contract-waived';
58
+ export const INTENT_SPEC_AMBIGUOUS = 'intent-guard/spec-ambiguous';
59
+ export const INTENT_SPEC_WEAK_MATCH = 'intent-guard/spec-weak-match';
60
+ export const INTENT_EMPTY_CHANGE_SET = 'intent-guard/empty-change-set';
61
+ /** Every id above, with its class. */
62
+ export const RULE_IDS = [
63
+ { id: GATE_MISSING, class: 'finding' },
64
+ { id: GATE_FAILED, class: 'finding' },
65
+ { id: GATE_OUTPUT_UNPARSEABLE, class: 'finding' },
66
+ { id: INTENT_GATE_BLOCKED, class: 'finding' },
67
+ { id: BLOCKING_COUNT_MISMATCH, class: 'diagnostic' },
68
+ { id: BLOCKING_THRESHOLD_UNKNOWN, class: 'diagnostic' },
69
+ { id: NOTHING_TO_SCAN, class: 'diagnostic' },
70
+ { id: LOCKFILES_EMPTY, class: 'diagnostic' },
71
+ { id: LOCKFILE_NO_LONGER_SCANNED, class: 'diagnostic' },
72
+ { id: MANIFESTS_NOT_HANDED, class: 'diagnostic' },
73
+ { id: OPTION_OVERRIDDEN, class: 'diagnostic' },
74
+ { id: BASE_COMPARISON_UNAVAILABLE, class: 'diagnostic' },
75
+ { id: REQUIREMENTS_DIRECT_ONLY, class: 'diagnostic' },
76
+ { id: REQUIREMENTS_NOT_PINNED, class: 'diagnostic' },
77
+ { id: REQUIREMENTS_NOT_SCANNED, class: 'diagnostic' },
78
+ { id: INTENT_WARNING, class: 'diagnostic' },
79
+ { id: GATE_DEFERRED, class: 'notification' },
80
+ { id: GATE_EXCLUDED, class: 'notification' },
81
+ { id: GATE_NOT_ENFORCED, class: 'notification' },
82
+ { id: TREE_UNCHANGED, class: 'notification' },
83
+ { id: BASE_MOVED, class: 'notification' },
84
+ { id: CONTROL_CHANGE_PROPOSED, class: 'notification' },
85
+ { id: PREVIEW_UNDER_PROPOSED_RULES, class: 'notification' },
86
+ { id: TRUST_BASE_REFUSED, class: 'notification' },
87
+ { id: TRUST_BASE_NOT_PASSED, class: 'notification' },
88
+ { id: GATE_PROGRAM_REFUSED, class: 'notification' },
89
+ { id: NODE_MODULES_SKIPPED, class: 'notification' },
90
+ { id: VERSION_SKEW, class: 'notification' },
91
+ { id: OPTION_IS_GATE_OWN, class: 'notification' },
92
+ { id: INTENT_LEGACY_STATE_DIR, class: 'notification' },
93
+ { id: INTENT_NO_CONTRACT, class: 'notification' },
94
+ { id: INTENT_CONTRACT_WAIVED, class: 'notification' },
95
+ { id: INTENT_SPEC_AMBIGUOUS, class: 'notification' },
96
+ { id: INTENT_SPEC_WEAK_MATCH, class: 'notification' },
97
+ { id: INTENT_EMPTY_CHANGE_SET, class: 'notification' },
98
+ ];
package/dist/run.d.ts CHANGED
@@ -109,7 +109,7 @@ export interface ControlProposal {
109
109
  * the policy file at the base ref with the one at the head commit. It is
110
110
  * reported and never acted on: the base ref's policy is the one that ran.
111
111
  */
112
- export interface RunTrustBase {
112
+ export interface RunTrustBase extends BaseTipForDisplay {
113
113
  /** The ref the umbrella took its own policy from. */
114
114
  ref: string;
115
115
  /** Whether the head commit's own policy file differs from that one. */
@@ -340,3 +340,13 @@ export declare function guardPreview<T>(work: () => T, fallback: (message: strin
340
340
  */
341
341
  export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
342
342
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;
343
+ /** The part of a trust base only the reports read. */
344
+ interface BaseTipForDisplay {
345
+ /**
346
+ * The base branch's tip, when the Action moved this trust base past it
347
+ * (`withMovedBaseTip`, trust-base.ts). Printed by the reports and read by
348
+ * nothing else.
349
+ */
350
+ baseTip?: string;
351
+ }
352
+ export {};
@@ -1,9 +1,9 @@
1
1
  /**
2
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.
3
+ * into, or moves to the merge ref's first parent on issue 159's one shape
4
+ * (action.yml, fetch-base step). Nothing else writes it and no short name can
5
+ * shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
6
+ * so a tag pushed by anyone able to push tags would choose the rules' commit.
7
7
  */
8
8
  export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
9
9
  /** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
@@ -120,8 +120,8 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
120
120
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
121
121
  * a platform that never sets it. When it is set, the given ref is accepted
122
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),
123
+ * base" step published, the tip or on one shape its first parent (it must equal
124
+ * refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
125
125
  * or is that private ref itself, or -- for an explicit trust base -- resolves
126
126
  * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
127
127
  * pull-request run through the action returns null here, before
@@ -446,3 +446,21 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
446
446
  entry?: string;
447
447
  from?: 'options';
448
448
  }): string | null;
449
+ /**
450
+ * The trust base with the base branch's tip to name in the report, when the
451
+ * Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
452
+ * anything reads `baseTip`. The value comes from the environment, so it is
453
+ * honored only when the repository bears it out: a full id of a commit that is
454
+ * neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
455
+ * first parent. Anything else is ignored without a word: the sentence is the only
456
+ * thing it could change, and leaving it out is true.
457
+ *
458
+ * The CLI cannot work this out alone. It sees the private ref at HEAD's first
459
+ * parent, which is also what every ordinary pull-request run looks like, and it
460
+ * never sees the tip the Action moved away from. It can only check what it is told.
461
+ */
462
+ export declare function withMovedBaseTip<T extends {
463
+ ref: string;
464
+ }>(repoRoot: string, trustBase: T, value: string | undefined): T & {
465
+ baseTip?: string;
466
+ };
@@ -77,10 +77,10 @@ import { parse as parseYaml } from 'yaml';
77
77
  import { gitComplaint, runGit, runGitBytes } from './git.js';
78
78
  /**
79
79
  * The private, fully spelled ref the composite action fetches the base branch
80
- * into (action.yml, gates step). Nothing else writes it and no short name can
81
- * shadow it: git resolves a short name like origin/main through refs/tags/
82
- * BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
83
- * otherwise choose the commit the rules are read from.
80
+ * into, or moves to the merge ref's first parent on issue 159's one shape
81
+ * (action.yml, fetch-base step). Nothing else writes it and no short name can
82
+ * shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
83
+ * so a tag pushed by anyone able to push tags would choose the rules' commit.
84
84
  */
85
85
  export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
86
86
  /**
@@ -332,9 +332,9 @@ export function refuseTrustBaseRef(repoRoot, ref) {
332
332
  `identical tree (${headTree}), so the policy would come from the tree being judged and ` +
333
333
  'there would be nothing for pull-request mode to compare. Likely cause: the base already ' +
334
334
  'carries this tree, which usually means the pull request was merged while this job was ' +
335
- 'queued; if so, nothing here needs fixing, and a later push re-runs the check. Otherwise ' +
336
- 'the trust base names the head or merge commit: pass the base branch (for example ' +
337
- 'origin/main) instead. Nothing was checked.');
335
+ 'queued. ' +
336
+ `${EQUAL_TREE_ADVICE} ` +
337
+ 'Nothing was checked.');
338
338
  }
339
339
  return null;
340
340
  }
@@ -360,8 +360,8 @@ export function refuseTrustBaseRef(repoRoot, ref) {
360
360
  * else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
361
361
  * a platform that never sets it. When it is set, the given ref is accepted
362
362
  * only when it is the FULL COMMIT ID the composite action's "Fetch the trust
363
- * base" step published (which must equal refs/conductor/trust-base, the
364
- * authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
363
+ * base" step published, the tip or on one shape its first parent (it must equal
364
+ * refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
365
365
  * or is that private ref itself, or -- for an explicit trust base -- resolves
366
366
  * to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
367
367
  * pull-request run through the action returns null here, before
@@ -1370,3 +1370,35 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
1370
1370
  }
1371
1371
  return null;
1372
1372
  }
1373
+ /** What a run refused for carrying HEAD's tree tells the reader to do. */
1374
+ const EQUAL_TREE_ADVICE = 'A pull request that landed gets no later push, so nothing re-runs this check: this run stays ' +
1375
+ 'red and its changes went unchecked here. One still open re-runs on its next push. The Action judges this shape against the commit the merge ref was ' +
1376
+ 'built from only on a full clone (fetch-depth: 0) with the same control files at both commits. ' +
1377
+ 'If neither case applies, the trust base names the head or merge commit: pass the base branch ' +
1378
+ '(for example origin/main) instead.';
1379
+ /**
1380
+ * The trust base with the base branch's tip to name in the report, when the
1381
+ * Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
1382
+ * anything reads `baseTip`. The value comes from the environment, so it is
1383
+ * honored only when the repository bears it out: a full id of a commit that is
1384
+ * neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
1385
+ * first parent. Anything else is ignored without a word: the sentence is the only
1386
+ * thing it could change, and leaving it out is true.
1387
+ *
1388
+ * The CLI cannot work this out alone. It sees the private ref at HEAD's first
1389
+ * parent, which is also what every ordinary pull-request run looks like, and it
1390
+ * never sees the tip the Action moved away from. It can only check what it is told.
1391
+ */
1392
+ export function withMovedBaseTip(repoRoot, trustBase, value) {
1393
+ if (value === undefined || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value)) {
1394
+ return trustBase;
1395
+ }
1396
+ const base = resolveRev(repoRoot, trustBase.ref, 'commit');
1397
+ const borneOut = base !== null &&
1398
+ value !== base &&
1399
+ resolveRev(repoRoot, value, 'commit') === value &&
1400
+ value !== resolveRev(repoRoot, 'HEAD', 'commit') &&
1401
+ headTreeEqualsBase(repoRoot, value) &&
1402
+ headParents(repoRoot)[0] === base;
1403
+ return borneOut ? { ...trustBase, baseTip: value } : trustBase;
1404
+ }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Tracked manifest-like files that were not handed to `product`, sorted, as
2
+ * Tracked dependency files that were not handed to `product`, sorted, as
3
3
  * one sentence fragment, or null when there are none.
4
4
  *
5
5
  * `handed` are the repository-relative paths the gate was actually handed,
@@ -5,6 +5,7 @@
5
5
  // given. A repository whose only manifests are a pyproject.toml, a Dockerfile
6
6
  // and a workflow gets a green vulnerabilities gate that looked at none of
7
7
  // them, and "treated as clean" on its own reads as a statement about the code.
8
+ import { OSV_LOCKFILE_ECOSYSTEMS } from './products.js';
8
9
  const EXACT_NAMES = new Set([
9
10
  'pyproject.toml',
10
11
  'Pipfile',
@@ -46,7 +47,28 @@ function isManifest(file) {
46
47
  (file.startsWith('.github/workflows/') && /\.ya?ml$/.test(base)));
47
48
  }
48
49
  /**
49
- * Tracked manifest-like files that were not handed to `product`, sorted, as
50
+ * A package.json no JavaScript lockfile the gate was handed could have resolved:
51
+ * none sits in its directory or an ancestor. Under one it is what that lockfile
52
+ * resolved, a workspace member under a root lockfile included, and naming it
53
+ * would put a note on every such run. Any other ecosystem's lockfile says
54
+ * nothing about it.
55
+ */
56
+ function isUnresolvedPackageJson(file, handed) {
57
+ if (file.slice(file.lastIndexOf('/') + 1) !== 'package.json') {
58
+ return false;
59
+ }
60
+ const directory = file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : '';
61
+ return ![...handed].some((lockfile) => {
62
+ const base = lockfile.slice(lockfile.lastIndexOf('/') + 1);
63
+ if (OSV_LOCKFILE_ECOSYSTEMS[base] !== 'javascript') {
64
+ return false;
65
+ }
66
+ const lockDirectory = lockfile.includes('/') ? lockfile.slice(0, lockfile.lastIndexOf('/')) : '';
67
+ return lockDirectory === '' || directory === lockDirectory || directory.startsWith(`${lockDirectory}/`);
68
+ });
69
+ }
70
+ /**
71
+ * Tracked dependency files that were not handed to `product`, sorted, as
50
72
  * one sentence fragment, or null when there are none.
51
73
  *
52
74
  * `handed` are the repository-relative paths the gate was actually handed,
@@ -62,12 +84,12 @@ export function unreadManifestsNote(tracked, handed, product) {
62
84
  const unread = tracked
63
85
  .filter((file) => !file.split('/').some((segment) => SKIPPED_DIRS.has(segment)))
64
86
  .filter((file) => !handed.has(file))
65
- .filter(isManifest)
87
+ .filter((file) => isManifest(file) || isUnresolvedPackageJson(file, handed))
66
88
  .sort();
67
89
  if (unread.length === 0) {
68
90
  return null;
69
91
  }
70
92
  const listed = unread.slice(0, MAX_LISTED).join(', ');
71
93
  const more = unread.length > MAX_LISTED ? `, and ${unread.length - MAX_LISTED} more` : '';
72
- return `Tracked manifests not handed to ${product}: ${listed}${more}.`;
94
+ return `Tracked dependency files not handed to ${product}: ${listed}${more}.`;
73
95
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.17.0",
3
+ "version": "0.18.1",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [