@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 +113 -7
- package/dist/cli.js +6 -1
- 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 +28 -0
- package/dist/output-text.js +21 -0
- 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.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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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, {
|
|
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;
|