@vaultcompass/conductor 0.4.5 → 0.4.6

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
@@ -89,6 +89,7 @@ conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secr
89
89
  A commit with a staged credential in it prints the full report and exits 1:
90
90
 
91
91
  ```
92
+ conductor 0.4.6
92
93
  conductor run: 2 gate(s), 1 finding(s)
93
94
 
94
95
  dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
@@ -270,6 +271,12 @@ proceeds normally without mentioning them.
270
271
  report nobody can read.
271
272
  - `--verbose` prints the full per-gate report even when the run is clean.
272
273
  Text output only; the SARIF log never changes shape with it.
274
+ - `--compact-on-refusal` shrinks the report to the version, the verdict and
275
+ the refusal reason when the trust base was refused and no gate ran,
276
+ instead of the full per-gate report. Built for the pull-request-comment
277
+ step. It has no effect on a run that was not refused, whatever `--verbose`
278
+ says. Text output only; it has no effect on the SARIF log and never
279
+ changes the exit code.
273
280
  - `--gate <role>`, repeatable. A gate the policy file enables and this flag
274
281
  leaves out is named as excluded, on one line in the text report and as a
275
282
  `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
@@ -424,6 +431,12 @@ judged while still reporting pull-request mode as on. Pass the base
424
431
  commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
425
432
  the run has no rules and exits 2 rather than using the pull request's; the
426
433
  file the pull request adds decides what runs once it is on the base branch.
434
+ That is why adopting conductor takes one merge before the gates can judge
435
+ anything, and it is not an oversight: the policy file can name a program to
436
+ run, so a run that read it from the pull request would let the pull request
437
+ choose its own judge on exactly the repositories that have no rules yet. See
438
+ "Adopting conductor" below for the sequence and for how to see what your
439
+ policy will do before you merge it.
427
440
 
428
441
  **Which gates are covered.** All three: dep-guard from **0.6.0**,
429
442
  intent-guard from **1.4.0**, vault-guard from **1.7.0**.
@@ -648,7 +661,7 @@ jobs:
648
661
  with:
649
662
  node-version: '22.11.0'
650
663
  - id: conductor
651
- uses: vaultcompasshq/conductor@v0.4.5
664
+ uses: vaultcompasshq/conductor@v0.4.6
652
665
  with:
653
666
  output: conductor.sarif
654
667
  - uses: github/codeql-action/upload-sarif@v3
@@ -697,7 +710,7 @@ jobs:
697
710
  # pinned below.
698
711
  - run: pnpm install --frozen-lockfile
699
712
  - id: conductor
700
- uses: vaultcompasshq/conductor@v0.4.5
713
+ uses: vaultcompasshq/conductor@v0.4.6
701
714
  with:
702
715
  output: conductor.sarif
703
716
  # Exact versions, never a range and never "latest". These four
@@ -708,7 +721,7 @@ jobs:
708
721
  # request of their own. Forward only on a pull request: the action
709
722
  # refuses a pin below what its tag ships, and the four lines can be
710
723
  # left out entirely to take that tag's own versions.
711
- conductor-version: 0.4.5
724
+ conductor-version: 0.4.6
712
725
  dep-guard-version: 0.7.0
713
726
  vault-guard-version: 1.8.0
714
727
  intent-guard-version: 1.5.2
@@ -732,6 +745,91 @@ runs whatever its author pushes to it next. Pin every third-party action by
732
745
  commit digest in a workflow you actually run, the way this repository's own
733
746
  workflows do.
734
747
 
748
+ ### Running the gates as an advisory check
749
+
750
+ To run the gates without blocking a merge, set `continue-on-error: true` on the
751
+ `conductor` step and leave the check not required in branch protection. Set a
752
+ step `timeout-minutes` as well. `continue-on-error` swallows a failing exit
753
+ code, but it does not bound a step that hangs: on a required job a stuck run
754
+ still drags the job to its own job-level limit and blocks the very merge the
755
+ advisory setting was meant to leave alone. The Action already caps each gate's
756
+ own subprocess at 120 seconds and reports a gate that exceeds it as
757
+ could-not-run, so a step `timeout-minutes` is an outer bound around the whole
758
+ run rather than the primary control.
759
+
760
+ A complete copy-paste job, rather than the one step above in isolation:
761
+
762
+ ```yaml
763
+ name: guardrails-advisory
764
+ on: pull_request
765
+
766
+ jobs:
767
+ gates:
768
+ runs-on: ubuntu-latest
769
+ permissions:
770
+ contents: read
771
+ pull-requests: write
772
+ steps:
773
+ - uses: actions/checkout@v4
774
+ continue-on-error: true
775
+ with:
776
+ fetch-depth: 0
777
+ - uses: actions/setup-node@v4
778
+ continue-on-error: true
779
+ with:
780
+ node-version: '22.11.0'
781
+ - name: Fetch the base ref
782
+ continue-on-error: true
783
+ run: git fetch origin "$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"
784
+ env:
785
+ GITHUB_BASE_REF: ${{ github.base_ref }}
786
+ - id: conductor
787
+ continue-on-error: true
788
+ timeout-minutes: 5
789
+ uses: vaultcompasshq/conductor@v0.4.6
790
+ with:
791
+ pr-comment: true
792
+ ```
793
+
794
+ Every fallible step above, the checkout, the node setup, the explicit fetch,
795
+ and the conductor step itself, carries `continue-on-error: true`, because a
796
+ required job must never go red over an advisory step that hung or failed.
797
+ `action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
798
+ the checkout does not already carry it (see the changelog entry for that
799
+ version), so the explicit "Fetch the base ref" step above is belt and
800
+ braces, not a requirement; it is here so the recipe still resolves the base
801
+ ref on an action version that predates that self-fetch. `pr-comment: true`
802
+ is what makes the advisory finding visible at all: a `pull_request` check
803
+ that is not required posts nothing anywhere else a developer would look, so
804
+ without it the run's only trace is a green-looking step nobody opens. See
805
+ "The report as a pull request comment" below for what that input needs and
806
+ what it does on a fork.
807
+
808
+ ### Adopting conductor
809
+
810
+ The first pull request cannot be judged by the policy it adds. Plan for two
811
+ steps rather than being surprised by one:
812
+
813
+ 1. On a branch, run `conductor init`, then run `conductor run --verbose` on
814
+ your own checkout. That is the full report your policy will produce, with
815
+ no `--trust-base` involved: a direct run on your own checkout is already
816
+ inside the trust boundary, so it reads the policy you just wrote. This is
817
+ where you tune thresholds, not on a pull request.
818
+ 2. Open the pull request with `.guardrails.yaml` and the workflow together,
819
+ and set `continue-on-error: true` on the conductor step for it. The step
820
+ is inert on this pull request: the base branch has no policy yet, so the
821
+ run has no rules, exits 2, and posts a comment saying so with the remedy
822
+ on it. That is the honest report of an unfinished adoption, not a broken
823
+ tool.
824
+ 3. Merge. Every pull request after that is judged by the policy on the base
825
+ branch, and a change to that policy shows up as a proposal line and takes
826
+ effect after its own merge.
827
+
828
+ There is deliberately no mode in which the pull request's own policy file
829
+ decides the run, not even as a preview: the preview in step 1 gives you the
830
+ same report without putting a file the pull request controls behind a
831
+ verdict on the pull request page.
832
+
735
833
  ### The report as a pull request comment
736
834
 
737
835
  **Built in, opt-in.** This matters most for an advisory job: a `pull_request`
@@ -748,7 +846,7 @@ step and add `pull-requests: write` to the job's `permissions`:
748
846
  steps:
749
847
  # ... checkout, pnpm, setup-node, install, as in the example above ...
750
848
  - id: conductor
751
- uses: vaultcompasshq/conductor@v0.4.5
849
+ uses: vaultcompasshq/conductor@v0.4.6
752
850
  with:
753
851
  output: conductor.sarif
754
852
  pr-comment: true
@@ -761,7 +859,13 @@ a re-run find and update that same comment, so a push does not pile up a new
761
859
  comment every time, the way the manual recipe below does. It runs on a
762
860
  `pull_request` or `pull_request_target` event only, and it runs whether the
763
861
  gates step passed or failed, since a blocking run is the one an advisory
764
- check most needs a developer to actually see.
862
+ check most needs a developer to actually see. The first line of every
863
+ comment carries the version of conductor that produced it, and when the
864
+ trust base was refused and no gate ran at all, the comment shrinks to the
865
+ version, the verdict, and the refusal reason (with its remedy, when one
866
+ applies) rather than the full per-gate report, so an adopter with no policy
867
+ on the base ref yet does not get a full sticky comment whose only content is
868
+ "refused, nothing checked" on every push.
765
869
 
766
870
  **It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
767
871
  there is read-only regardless of the `pull-requests: write` permission you
@@ -794,12 +898,12 @@ per pull request.
794
898
 
795
899
  ```yaml
796
900
  - id: conductor-package-a
797
- uses: vaultcompasshq/conductor@v0.4.5
901
+ uses: vaultcompasshq/conductor@v0.4.6
798
902
  with:
799
903
  pr-comment: true
800
904
  pr-comment-marker: 'package-a'
801
905
  - id: conductor-package-b
802
- uses: vaultcompasshq/conductor@v0.4.5
906
+ uses: vaultcompasshq/conductor@v0.4.6
803
907
  with:
804
908
  pr-comment: true
805
909
  pr-comment-marker: 'package-b'
@@ -929,6 +1033,8 @@ SARIF result, how the exit code is composed, and the mechanism behind the
929
1033
  intent gate at a pull request. Several of them were learned from running this
930
1034
  tool against real repositories rather than reasoned out in advance.
931
1035
 
1036
+ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repository is in [CONTRIBUTING.md](CONTRIBUTING.md).
1037
+
932
1038
  ## License
933
1039
 
934
1040
  MIT, [Vault & Compass](https://vaultcompass.io)
package/dist/cli.js CHANGED
@@ -284,6 +284,7 @@ export function buildProgram() {
284
284
  .option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
285
285
  .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')
286
286
  .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.')
287
+ .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.')
287
288
  .option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
288
289
  .exitOverride()
289
290
  .action((options) => {
@@ -318,7 +319,11 @@ export function buildProgram() {
318
319
  });
319
320
  const rendered = format === 'sarif'
320
321
  ? `${renderSarif(result, pkg.version)}\n`
321
- : renderText(result, { verbose: Boolean(options.verbose) });
322
+ : renderText(result, {
323
+ verbose: Boolean(options.verbose),
324
+ version: pkg.version,
325
+ compact: Boolean(options.compactOnRefusal),
326
+ });
322
327
  if (options.output === undefined) {
323
328
  process.stdout.write(rendered);
324
329
  }
@@ -0,0 +1,195 @@
1
+ import type { Product } from './policy.js';
2
+ /** The one string that says "conductor init wrote this". */
3
+ export declare const MANAGED_HOOK_MARKER = "guardrails-managed-hook: v1";
4
+ /**
5
+ * Markers each gate's own installer writes, so a collision is recognised
6
+ * rather than clobbered. Two of these are literal marker comments the other
7
+ * tools write on purpose; the third has no marker at all and is matched on
8
+ * the two strings its hook always contains, which is exactly how that
9
+ * tool's own installer recognises its own hook.
10
+ */
11
+ export declare const DEP_GUARD_HOOK_MARKER = "dep-guard-managed-hook: v1";
12
+ export declare const INTENT_GUARD_HOOK_MARKER = "conductor-managed-pre-commit";
13
+ /**
14
+ * Hook managers whose installed pre-commit file is GENERATED rather than
15
+ * written by a human. Every one of these rewrites that file on install, so
16
+ * it is never the file the umbrella may write into.
17
+ *
18
+ * The same four names dep-guard's and vault-guard's inits use, so the
19
+ * family says one thing. The difference is that those take the manager as
20
+ * a flag, and this one detects it: the umbrella's whole job is to be run
21
+ * once in a repository somebody else already wired up.
22
+ */
23
+ export type HookManager = 'native' | 'husky' | 'lefthook' | 'precommit' | 'simple-git-hooks' | 'yorkie';
24
+ /**
25
+ * The two managers whose pre-commit TEXT lives in package.json rather than
26
+ * in a config file of their own or in the hook file.
27
+ *
28
+ * They are kept apart from lefthook and the pre-commit framework because
29
+ * the refusal is different: there is no manager-owned config file to point
30
+ * somebody at, only a key in the file conductor deliberately never writes.
31
+ */
32
+ export type ManagedHookManager = 'simple-git-hooks' | 'yorkie';
33
+ /**
34
+ * The `.husky` directory whose generated subdirectory git has been pointed
35
+ * at, or null when this is not that arrangement.
36
+ *
37
+ * The rule is STRUCTURAL and nothing else: the hooks directory is named
38
+ * `_`, and its parent is named `.husky`. Only husky creates that path, so
39
+ * the shape alone identifies it, and both halves are required.
40
+ *
41
+ * Two things are deliberately NOT part of the rule, each for a reason that
42
+ * cost a bug:
43
+ *
44
+ * - THE CONTENT of the pre-commit file git executes. The line that sources
45
+ * husky's shim appears in two completely different places:
46
+ *
47
+ * husky 9 core.hooksPath = .husky/_ .husky/_/pre-commit sources
48
+ * _/h and IS a dispatcher; the tracked hook is one up.
49
+ * husky 8 core.hooksPath = .husky .husky/pre-commit sources
50
+ * _/husky.sh as a PREAMBLE and IS the tracked hook already.
51
+ *
52
+ * Reading content therefore fired against husky 8's tracked hook, and
53
+ * "one directory up" then pointed at the parent of `.husky`, which is
54
+ * the repository root. Init wrote a hook there, never read the real one
55
+ * so never saw the gate hook in it, reported success, and left every
56
+ * commit ungated. The structural rule excludes husky 8 on its own,
57
+ * because there the hooks directory is `.husky` and not `_`.
58
+ *
59
+ * - THE PRESENCE OF THE SHIM (`h`, or husky 8's `husky.sh`). Requiring it
60
+ * looks like useful confirmation and quietly reintroduces the original
61
+ * trap. husky gitignores `.husky/_`, so `git clean -xdf` deletes the
62
+ * whole directory while `core.hooksPath=.husky/_` sits in `.git/config`
63
+ * and survives. In that state there is no shim, no dispatcher, and
64
+ * nothing whatever to confirm, so a shim requirement sends init down the
65
+ * ordinary path to write `.husky/_/pre-commit` -- which is exactly the
66
+ * file husky's next prepare step wipes. The shim is evidence that husky
67
+ * ran recently, not evidence about whose directory this is, so it is
68
+ * reported and never tested against.
69
+ *
70
+ * The tracked target is this `.husky` directory's own hook, never a
71
+ * computed parent of whatever directory git happens to point at.
72
+ */
73
+ export declare function huskyDirectoryFor(hooksDir: string): string | null;
74
+ /** Whether husky's shim is in place, which is worth SAYING but never testing. */
75
+ export declare function huskyShimPresent(hooksDir: string): boolean;
76
+ /**
77
+ * What each of these two managers actually writes into the hook it
78
+ * generates, checked against a real install rather than against anybody's
79
+ * memory of one. The captured files are in tests/fixtures/hooks.
80
+ *
81
+ * lefthook is recognised by `call_lefthook`, the shell function its
82
+ * generated hook defines and then calls on the last line. Verified against
83
+ * lefthook 2.1.12 and 1.7.18, which both write it twice.
84
+ *
85
+ * `lefthook_version:` is a second alternative and IS NOT VERIFIED. Neither
86
+ * of those versions writes it, and the string does not appear anywhere in
87
+ * the 2.1.12 binary either, so it recognises nothing lefthook produces
88
+ * today. It stays because a spare alternative in an OR cannot cause a false
89
+ * negative and may still catch a much older install. What could not stay is
90
+ * the comment that used to be here, which called both halves the
91
+ * installer's own mark: a hand-written fixture in the suite carried the
92
+ * invented line, so the fixture and the code agreed with each other and
93
+ * neither had ever been held up against lefthook. Recognising lefthook on
94
+ * that string alone misclassifies both real hooks as native, which is how
95
+ * init ends up writing into a file lefthook regenerates.
96
+ *
97
+ * The pre-commit framework stamps its own URL, and that one is exact:
98
+ * verified against pre-commit 4.6.2, whose marker line is character for
99
+ * character the string below.
100
+ */
101
+ export declare function detectGeneratedHook(content: string): Exclude<HookManager, 'native' | 'husky' | ManagedHookManager> | null;
102
+ export declare function generatedHookGuidance(manager: 'lefthook' | 'precommit', relPath: string): string;
103
+ /**
104
+ * The manager that generated this hook, for the two whose hook text comes
105
+ * out of package.json. Checked against real installs, captured in
106
+ * tests/fixtures/hooks.
107
+ *
108
+ * simple-git-hooks is recognised by `SKIP_SIMPLE_GIT_HOOKS`, the opt-out
109
+ * variable its generated hook tests on its first line. Verified against
110
+ * 2.14.0 and 2.11.1.
111
+ *
112
+ * IT IS NOT IN EVERY VERSION, and that is the whole reason the package.json
113
+ * key below exists rather than being belt and braces. simple-git-hooks 2.8.0
114
+ * writes the shebang and the user's own command and nothing else: there is
115
+ * no string in that file belonging to simple-git-hooks, so no content rule
116
+ * can recognise it, at any price. A repository on that version is
117
+ * unrecognisable from its hook alone and would have had the umbrella hook
118
+ * written into a file the next install rewrites.
119
+ *
120
+ * yorkie is recognised by `yorkie/src/runner.js`, the script its generated
121
+ * hook invokes. Verified against 2.0.0, which writes it relative, and 1.0.2,
122
+ * which writes the same suffix under an absolute path, so the suffix is what
123
+ * both have in common. The `#yorkie ` version stamp on the second line is a
124
+ * second alternative and is present in both captures too; it is second
125
+ * because it is a comment, and a comment is the part of a generated file
126
+ * most likely to be reworded.
127
+ */
128
+ export declare function detectManagedHook(content: string): ManagedHookManager | null;
129
+ /**
130
+ * The manager this repository's package.json DECLARES, or null.
131
+ *
132
+ * This is the signal that matters, and it is not a corroboration of the
133
+ * content rule above: it is the only one that fires on a fresh clone, where
134
+ * the manager has never run, `.git/hooks/pre-commit` does not exist, and the
135
+ * next `npm install` will create it. That is the state a repository is in
136
+ * when somebody adds the umbrella to it.
137
+ *
138
+ * Presence of the key is the whole test; it is deliberately NOT narrowed to
139
+ * a declared `pre-commit` entry. yorkie's installer writes every hook file
140
+ * whatever the key contains (its generated hook decides at run time whether
141
+ * a script exists), and simple-git-hooks removes hooks it previously managed
142
+ * as well as writing the declared ones. Narrowing would trade a refusal that
143
+ * costs somebody one paragraph of guidance for a hook that is silently
144
+ * deleted, and those are not the same size of mistake.
145
+ *
146
+ * An unreadable or unparseable package.json is the same answer as no
147
+ * package.json: this asks whether something was declared, and "the file
148
+ * cannot be read" is not evidence that it was.
149
+ */
150
+ /**
151
+ * Where a managed-hooks declaration was found.
152
+ *
153
+ * The config file is carried rather than collapsed into a boolean because
154
+ * the guidance has to NAME it: simple-git-hooks reads package.json last, so
155
+ * telling somebody to edit package.json while one of these exists sends them
156
+ * to the file that will be ignored.
157
+ */
158
+ export type ManagedDetection = {
159
+ kind: 'hook';
160
+ } | {
161
+ kind: 'package.json';
162
+ } | {
163
+ kind: 'config-file';
164
+ file: string;
165
+ };
166
+ export interface ManagedDeclaration {
167
+ manager: ManagedHookManager;
168
+ detectedIn: ManagedDetection;
169
+ }
170
+ export declare function declaredManagedHooks(root: string): ManagedDeclaration | null;
171
+ /**
172
+ * What init says when it finds one of those two, and why it says nothing
173
+ * else.
174
+ *
175
+ * The honest answer here is a refusal, not an offer. These managers have no
176
+ * tracked hook file to redirect into and no config file of their own to name:
177
+ * the only place the umbrella's command could go is a key in package.json,
178
+ * and init does not write package.json. That is not squeamishness. Init
179
+ * writes a hook, a policy file and a manifest, and the manifest is what
180
+ * makes --revert honest; an edit merged into somebody's package.json has no
181
+ * revert story that is not a guess about which of their later edits were
182
+ * theirs. So the guidance says exactly what to add and leaves the adding to
183
+ * the person whose file it is.
184
+ *
185
+ * The exit-code sentence differs between the two, and both halves are held
186
+ * against the captured fixtures rather than against anybody's memory:
187
+ * simple-git-hooks runs the entry as the last command of a plain `sh`
188
+ * script, so the umbrella's status is the hook's status, while yorkie wraps
189
+ * its runner in `|| { ...; exit 1; }` and turns every non-zero exit into 1.
190
+ */
191
+ export declare function managedHooksGuidance(manager: ManagedHookManager, relPath: string, detectedIn: ManagedDetection): string;
192
+ export declare function detectGateHook(content: string): Product | null;
193
+ export declare function foreignGuidance(relPath: string): string;
194
+ export declare function editedManagedGuidance(relPath: string): string;
195
+ export declare function gateHookGuidance(product: Product, relPath: string): string;