@vaultcompass/conductor 0.4.5 → 0.4.7
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 +153 -14
- package/dist/cli.js +36 -3
- package/dist/init-hook-detect.d.ts +195 -0
- package/dist/init-hook-detect.js +315 -0
- package/dist/init-manifest.d.ts +64 -0
- package/dist/init-manifest.js +127 -0
- package/dist/init-policy.d.ts +12 -0
- package/dist/init-policy.js +103 -0
- package/dist/init.d.ts +7 -42
- package/dist/init.js +17 -539
- package/dist/output-text.d.ts +43 -0
- package/dist/output-text.js +56 -8
- package/package.json +1 -1
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.7
|
|
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,10 +271,25 @@ 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.
|
|
276
283
|
It never reaches the exit code.
|
|
284
|
+
- `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
|
|
285
|
+
finding no longer fails. A gate that could not run is unaffected and still
|
|
286
|
+
exits 2, so a crashed install or a missing policy still shows red rather
|
|
287
|
+
than a silent green: this flag changes what a **finding** does, never what
|
|
288
|
+
a **broken gate** does. The report is unchanged, a blocking finding still
|
|
289
|
+
prints with its `BLOCKING` marker, and only the process exit and the
|
|
290
|
+
verdict line's own wording (it says findings were advisory and did not
|
|
291
|
+
block) change. Text output only; the SARIF log has no verdict line to
|
|
292
|
+
change and its `properties.blocking` on each result is unaffected.
|
|
277
293
|
|
|
278
294
|
### Exit codes
|
|
279
295
|
|
|
@@ -284,6 +300,11 @@ proceeds normally without mentioning them.
|
|
|
284
300
|
stdout, which is what a rejected config file looks like from two of the
|
|
285
301
|
three.
|
|
286
302
|
|
|
303
|
+
`run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
|
|
304
|
+
could not run is a different failure from a blocking finding, and advisory
|
|
305
|
+
mode exists to leave that one alone. See "Running the gates as an advisory
|
|
306
|
+
check" below.
|
|
307
|
+
|
|
287
308
|
## The pull-request trust boundary
|
|
288
309
|
|
|
289
310
|
Every gate reads its own rules out of the repository it is judging. On a pull
|
|
@@ -424,6 +445,12 @@ judged while still reporting pull-request mode as on. Pass the base
|
|
|
424
445
|
commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
|
|
425
446
|
the run has no rules and exits 2 rather than using the pull request's; the
|
|
426
447
|
file the pull request adds decides what runs once it is on the base branch.
|
|
448
|
+
That is why adopting conductor takes one merge before the gates can judge
|
|
449
|
+
anything, and it is not an oversight: the policy file can name a program to
|
|
450
|
+
run, so a run that read it from the pull request would let the pull request
|
|
451
|
+
choose its own judge on exactly the repositories that have no rules yet. See
|
|
452
|
+
"Adopting conductor" below for the sequence and for how to see what your
|
|
453
|
+
policy will do before you merge it.
|
|
427
454
|
|
|
428
455
|
**Which gates are covered.** All three: dep-guard from **0.6.0**,
|
|
429
456
|
intent-guard from **1.4.0**, vault-guard from **1.7.0**.
|
|
@@ -648,7 +675,7 @@ jobs:
|
|
|
648
675
|
with:
|
|
649
676
|
node-version: '22.11.0'
|
|
650
677
|
- id: conductor
|
|
651
|
-
uses: vaultcompasshq/conductor@v0.4.
|
|
678
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
652
679
|
with:
|
|
653
680
|
output: conductor.sarif
|
|
654
681
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -697,7 +724,7 @@ jobs:
|
|
|
697
724
|
# pinned below.
|
|
698
725
|
- run: pnpm install --frozen-lockfile
|
|
699
726
|
- id: conductor
|
|
700
|
-
uses: vaultcompasshq/conductor@v0.4.
|
|
727
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
701
728
|
with:
|
|
702
729
|
output: conductor.sarif
|
|
703
730
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -708,7 +735,7 @@ jobs:
|
|
|
708
735
|
# request of their own. Forward only on a pull request: the action
|
|
709
736
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
710
737
|
# left out entirely to take that tag's own versions.
|
|
711
|
-
conductor-version: 0.4.
|
|
738
|
+
conductor-version: 0.4.7
|
|
712
739
|
dep-guard-version: 0.7.0
|
|
713
740
|
vault-guard-version: 1.8.0
|
|
714
741
|
intent-guard-version: 1.5.2
|
|
@@ -732,6 +759,106 @@ runs whatever its author pushes to it next. Pin every third-party action by
|
|
|
732
759
|
commit digest in a workflow you actually run, the way this repository's own
|
|
733
760
|
workflows do.
|
|
734
761
|
|
|
762
|
+
### Running the gates as an advisory check
|
|
763
|
+
|
|
764
|
+
To run the gates without blocking a merge, set `advisory: true` on the
|
|
765
|
+
`conductor` step and leave the check not required in branch protection.
|
|
766
|
+
`advisory: true` maps a blocking finding to exit 0, so it never fails this
|
|
767
|
+
run; a gate that **could not run** is unaffected and still exits 2, so a
|
|
768
|
+
crashed install or a missing policy on the base ref still shows red rather
|
|
769
|
+
than a silent green. That distinction is why the recipe below carries no
|
|
770
|
+
`continue-on-error` anywhere: an earlier version of this recipe put
|
|
771
|
+
`continue-on-error: true` on every step, including the umbrella's own, and a
|
|
772
|
+
transient `npm audit signatures` failure then read as nothing wrong for two
|
|
773
|
+
days (issue #36) because the step's exit code was swallowed regardless of
|
|
774
|
+
which of the two reasons produced it. `advisory` fixes the failure that
|
|
775
|
+
caused that; `continue-on-error` is the thing that let it happen, so the two
|
|
776
|
+
do not belong in the same recipe. Set a step `timeout-minutes` as well: the
|
|
777
|
+
Action already caps each gate's own subprocess at 120 seconds and reports one
|
|
778
|
+
that exceeds it as could-not-run, so the timeout is an outer bound around the
|
|
779
|
+
whole run rather than the primary control.
|
|
780
|
+
|
|
781
|
+
A complete copy-paste job, rather than the one step above in isolation:
|
|
782
|
+
|
|
783
|
+
```yaml
|
|
784
|
+
name: guardrails-advisory
|
|
785
|
+
on: pull_request
|
|
786
|
+
|
|
787
|
+
jobs:
|
|
788
|
+
gates:
|
|
789
|
+
runs-on: ubuntu-latest
|
|
790
|
+
permissions:
|
|
791
|
+
contents: read
|
|
792
|
+
pull-requests: write
|
|
793
|
+
steps:
|
|
794
|
+
- uses: actions/checkout@v4
|
|
795
|
+
with:
|
|
796
|
+
fetch-depth: 0
|
|
797
|
+
- uses: actions/setup-node@v4
|
|
798
|
+
with:
|
|
799
|
+
node-version: '22.11.0'
|
|
800
|
+
- id: conductor
|
|
801
|
+
timeout-minutes: 5
|
|
802
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
803
|
+
with:
|
|
804
|
+
pr-comment: true
|
|
805
|
+
advisory: true
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
`action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
|
|
809
|
+
the checkout does not already carry it (see the changelog entry for that
|
|
810
|
+
version), so this recipe needs no separate "fetch the base ref" step. None of
|
|
811
|
+
the three steps above swallows its own exit code: a checkout or setup-node
|
|
812
|
+
failure is an infrastructure problem this recipe should still surface, and
|
|
813
|
+
the `conductor` step's own advisory behaviour comes from `advisory: true`
|
|
814
|
+
rather than from hiding a failing step, for the reason above. `pr-comment:
|
|
815
|
+
true` is what makes the advisory finding visible at all: a `pull_request`
|
|
816
|
+
check that is not required posts nothing anywhere else a developer would
|
|
817
|
+
look, so without it the run's only trace is a step that exited 0 and nobody
|
|
818
|
+
opens. See "The report as a pull request comment" below for what that input
|
|
819
|
+
needs and what it does on a fork.
|
|
820
|
+
|
|
821
|
+
`advisory` changes the umbrella's own process exit code only: it does not
|
|
822
|
+
reach the SARIF log, so a GitHub Code Scanning tab shows the same results and
|
|
823
|
+
the same alerts either way, and Code Scanning's own merge protection can
|
|
824
|
+
still block on them regardless of what this step's exit code says. `advisory`
|
|
825
|
+
is also an input on the `conductor` step, which means it is read from the
|
|
826
|
+
pull request's own workflow file on a same-repo `pull_request` event, the
|
|
827
|
+
same as every other input this Action takes; that gives a pull request
|
|
828
|
+
author nothing they could not already do by editing the workflow to add
|
|
829
|
+
`continue-on-error` themselves, and the control for that, as for any workflow
|
|
830
|
+
edit, is branch protection requiring review on `.github/workflows`, not
|
|
831
|
+
anything in `action.yml`.
|
|
832
|
+
|
|
833
|
+
### Adopting conductor
|
|
834
|
+
|
|
835
|
+
The first pull request cannot be judged by the policy it adds. Plan for two
|
|
836
|
+
steps rather than being surprised by one:
|
|
837
|
+
|
|
838
|
+
1. On a branch, run `conductor init`, then run `conductor run --verbose` on
|
|
839
|
+
your own checkout. That is the full report your policy will produce, with
|
|
840
|
+
no `--trust-base` involved: a direct run on your own checkout is already
|
|
841
|
+
inside the trust boundary, so it reads the policy you just wrote. This is
|
|
842
|
+
where you tune thresholds, not on a pull request.
|
|
843
|
+
2. Open the pull request with `.guardrails.yaml` and the workflow together,
|
|
844
|
+
and set `advisory: true` on the conductor step, the same as the advisory
|
|
845
|
+
recipe above, and leave the check not required in branch protection for
|
|
846
|
+
this one pull request. The step still exits 2 on this pull request even
|
|
847
|
+
with `advisory: true`: the base branch has no policy yet, so the run has
|
|
848
|
+
no rules, and `advisory` never touches that exit code, only a blocking
|
|
849
|
+
finding's. Leaving the check unrequired is what keeps that expected exit 2
|
|
850
|
+
from blocking the merge; the step posts a comment saying so with the
|
|
851
|
+
remedy on it, which is the honest report of an unfinished adoption, not a
|
|
852
|
+
broken tool.
|
|
853
|
+
3. Merge. Every pull request after that is judged by the policy on the base
|
|
854
|
+
branch, and a change to that policy shows up as a proposal line and takes
|
|
855
|
+
effect after its own merge.
|
|
856
|
+
|
|
857
|
+
There is deliberately no mode in which the pull request's own policy file
|
|
858
|
+
decides the run, not even as a preview: the preview in step 1 gives you the
|
|
859
|
+
same report without putting a file the pull request controls behind a
|
|
860
|
+
verdict on the pull request page.
|
|
861
|
+
|
|
735
862
|
### The report as a pull request comment
|
|
736
863
|
|
|
737
864
|
**Built in, opt-in.** This matters most for an advisory job: a `pull_request`
|
|
@@ -748,7 +875,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
748
875
|
steps:
|
|
749
876
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
750
877
|
- id: conductor
|
|
751
|
-
uses: vaultcompasshq/conductor@v0.4.
|
|
878
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
752
879
|
with:
|
|
753
880
|
output: conductor.sarif
|
|
754
881
|
pr-comment: true
|
|
@@ -761,7 +888,13 @@ a re-run find and update that same comment, so a push does not pile up a new
|
|
|
761
888
|
comment every time, the way the manual recipe below does. It runs on a
|
|
762
889
|
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
763
890
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
764
|
-
check most needs a developer to actually see.
|
|
891
|
+
check most needs a developer to actually see. The first line of every
|
|
892
|
+
comment carries the version of conductor that produced it, and when the
|
|
893
|
+
trust base was refused and no gate ran at all, the comment shrinks to the
|
|
894
|
+
version, the verdict, and the refusal reason (with its remedy, when one
|
|
895
|
+
applies) rather than the full per-gate report, so an adopter with no policy
|
|
896
|
+
on the base ref yet does not get a full sticky comment whose only content is
|
|
897
|
+
"refused, nothing checked" on every push.
|
|
765
898
|
|
|
766
899
|
**It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
|
|
767
900
|
there is read-only regardless of the `pull-requests: write` permission you
|
|
@@ -794,12 +927,12 @@ per pull request.
|
|
|
794
927
|
|
|
795
928
|
```yaml
|
|
796
929
|
- id: conductor-package-a
|
|
797
|
-
uses: vaultcompasshq/conductor@v0.4.
|
|
930
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
798
931
|
with:
|
|
799
932
|
pr-comment: true
|
|
800
933
|
pr-comment-marker: 'package-a'
|
|
801
934
|
- id: conductor-package-b
|
|
802
|
-
uses: vaultcompasshq/conductor@v0.4.
|
|
935
|
+
uses: vaultcompasshq/conductor@v0.4.7
|
|
803
936
|
with:
|
|
804
937
|
pr-comment: true
|
|
805
938
|
pr-comment-marker: 'package-b'
|
|
@@ -872,13 +1005,17 @@ came from, so a pull request that plants one gets a clean comment beside a
|
|
|
872
1005
|
SARIF log that refused it.
|
|
873
1006
|
|
|
874
1007
|
**Mirror whatever you gave the Action**, or the two runs can report different
|
|
875
|
-
contracts. The step above matches the example, which
|
|
876
|
-
`base-ref`, `trust-base` nor `
|
|
877
|
-
the `Spec:` line out of the job environment
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
1008
|
+
contracts, or different verdicts. The step above matches the example, which
|
|
1009
|
+
passes neither `base-ref`, `trust-base`, `spec` nor `advisory`, so both runs
|
|
1010
|
+
read `GITHUB_BASE_REF` and the `Spec:` line out of the job environment
|
|
1011
|
+
themselves and land on the same contract and the same ref, and neither one
|
|
1012
|
+
maps a blocking finding to exit 0. If you set any of those inputs on the
|
|
1013
|
+
gates step, pass the same values here: `--base`, `--trust-base` and `--spec`
|
|
1014
|
+
for the first three, and `--advisory` if you set `advisory: true`. Missing
|
|
1015
|
+
one of the first three means the comment is a report of a contract source,
|
|
1016
|
+
or of a boundary, the uploaded log never used; missing `--advisory` means the
|
|
1017
|
+
comment's own verdict line reads "exit 1" underneath a gates step that just
|
|
1018
|
+
exited 0, which is confusing in the opposite direction from silence.
|
|
882
1019
|
|
|
883
1020
|
**On a pull request from a fork the token is read-only**, so `gh pr comment`
|
|
884
1021
|
fails, `continue-on-error` swallows the failure, and no comment appears on
|
|
@@ -929,6 +1066,8 @@ SARIF result, how the exit code is composed, and the mechanism behind the
|
|
|
929
1066
|
intent gate at a pull request. Several of them were learned from running this
|
|
930
1067
|
tool against real repositories rather than reasoned out in advance.
|
|
931
1068
|
|
|
1069
|
+
Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repository is in [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
1070
|
+
|
|
932
1071
|
## License
|
|
933
1072
|
|
|
934
1073
|
MIT, [Vault & Compass](https://vaultcompass.io)
|
package/dist/cli.js
CHANGED
|
@@ -10,7 +10,7 @@ import { execFileSync } from 'node:child_process';
|
|
|
10
10
|
import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
|
-
import { EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
13
|
+
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
14
14
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
15
|
import { renderSarif } from './output-sarif.js';
|
|
16
16
|
import { renderText } from './output-text.js';
|
|
@@ -65,6 +65,27 @@ function repoRoot(cwd) {
|
|
|
65
65
|
throw new Error(`git could not be run to find the repository root: ${err.message}`);
|
|
66
66
|
}
|
|
67
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* The process exit code for a run, with --advisory applied.
|
|
70
|
+
*
|
|
71
|
+
* ONE PLACE, so the mapping cannot drift from what the verdict line claims:
|
|
72
|
+
* this reads the same `result.exitCode` that `renderText`'s own `advisory`
|
|
73
|
+
* option reads, and the two are always passed the same boolean from the same
|
|
74
|
+
* call site below.
|
|
75
|
+
*
|
|
76
|
+
* ONLY EXIT_BLOCKED (1) IS EVER REMAPPED, and only to EXIT_OK (0). A gate
|
|
77
|
+
* that could not run (2) is left exactly alone: "advisory" means a finding
|
|
78
|
+
* does not block, never that the umbrella cannot fail. Swallowing a
|
|
79
|
+
* could-not-run exit is the precise failure this flag exists to close (a
|
|
80
|
+
* crashed `npm audit signatures` read as nothing wrong for two days,
|
|
81
|
+
* issue #36, because every step carried `continue-on-error` instead of a
|
|
82
|
+
* flag that only ever touches a FINDING's verdict). Any other code -- there
|
|
83
|
+
* is none today besides 0, 1 and 2, but a future one would land here too --
|
|
84
|
+
* passes through unchanged for the same reason.
|
|
85
|
+
*/
|
|
86
|
+
function applyAdvisory(exitCode, advisory) {
|
|
87
|
+
return advisory && exitCode === EXIT_BLOCKED ? EXIT_OK : exitCode;
|
|
88
|
+
}
|
|
68
89
|
/**
|
|
69
90
|
* Reads the policy for one run, from the base ref in pull-request mode.
|
|
70
91
|
*
|
|
@@ -284,7 +305,9 @@ export function buildProgram() {
|
|
|
284
305
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
285
306
|
.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
307
|
.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.')
|
|
308
|
+
.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
309
|
.option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
|
|
310
|
+
.option('--advisory', 'maps exit 1 (every enabled gate ran and at least one blocked) to exit 0, so a blocking finding never fails this run. A gate that could not run is unaffected and still exits 2: advisory changes what a FINDING does, never what a broken gate does. The report is unchanged and a blocking finding still prints as BLOCKING; only the process exit code and the verdict line, which says findings were advisory, are different.')
|
|
288
311
|
.exitOverride()
|
|
289
312
|
.action((options) => {
|
|
290
313
|
const cwd = process.cwd();
|
|
@@ -316,9 +339,19 @@ export function buildProgram() {
|
|
|
316
339
|
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
317
340
|
...(source.trustBase === undefined ? {} : { trustBase: source.trustBase }),
|
|
318
341
|
});
|
|
342
|
+
const advisory = Boolean(options.advisory);
|
|
343
|
+
// SARIF carries no verdict line, so --advisory has nothing to say
|
|
344
|
+
// there: each finding's `properties.blocking` is the gate's own
|
|
345
|
+
// decision (see output-sarif.ts) and is unaffected by this flag,
|
|
346
|
+
// exactly as the text report's per-finding BLOCKING marker is.
|
|
319
347
|
const rendered = format === 'sarif'
|
|
320
348
|
? `${renderSarif(result, pkg.version)}\n`
|
|
321
|
-
: renderText(result, {
|
|
349
|
+
: renderText(result, {
|
|
350
|
+
verbose: Boolean(options.verbose),
|
|
351
|
+
version: pkg.version,
|
|
352
|
+
compact: Boolean(options.compactOnRefusal),
|
|
353
|
+
advisory,
|
|
354
|
+
});
|
|
322
355
|
if (options.output === undefined) {
|
|
323
356
|
process.stdout.write(rendered);
|
|
324
357
|
}
|
|
@@ -334,7 +367,7 @@ export function buildProgram() {
|
|
|
334
367
|
process.stdout.write(`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s); ` +
|
|
335
368
|
`${format} report written to ${options.output}\n`);
|
|
336
369
|
}
|
|
337
|
-
process.exitCode = result.exitCode;
|
|
370
|
+
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
338
371
|
}
|
|
339
372
|
catch (err) {
|
|
340
373
|
// One line, never a stack. runGate is total, so nothing from a gate
|
|
@@ -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;
|