@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 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.5
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.5
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.5
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.5
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.5
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.5
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 passes neither
876
- `base-ref`, `trust-base` nor `spec`, so both runs read `GITHUB_BASE_REF` and
877
- the `Spec:` line out of the job environment themselves and land on the same
878
- contract and the same ref. If you set any of those inputs on the gates step,
879
- pass the same values here as `--base`, `--trust-base` and `--spec`; if you do
880
- not, the comment is a report of a contract source, or of a boundary, the
881
- uploaded log never used.
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, { verbose: Boolean(options.verbose) });
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;