@vaultcompass/conductor 0.9.0 → 0.10.0

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.
@@ -72,8 +72,8 @@ export function breakWorkflowMarkers(text) {
72
72
  }
73
73
  /**
74
74
  * The could-not-run reasons that are conductor's OWN decision, made before
75
- * the gate was spawned (or instead of spawning it), as opposed to something
76
- * the gate itself said or did.
75
+ * the gate was spawned (or instead of spawning it), or the umbrella stopping
76
+ * it, as opposed to something the gate itself said or did.
77
77
  */
78
78
  export const CONDUCTOR_OWN_REASONS = new Set([
79
79
  'preparation-failed',
@@ -81,7 +81,101 @@ export const CONDUCTOR_OWN_REASONS = new Set([
81
81
  'gate-program-refused',
82
82
  'gate-version-unsupported',
83
83
  'history-shallow',
84
+ 'timed-out',
84
85
  ]);
86
+ /**
87
+ * A gate's time limit, and where it came from. THE ONE PLACE the precedence
88
+ * is written: the test hook (`RunGateOptions.timeoutMs`, which no CLI path
89
+ * sets), then the policy's `timeout-seconds`, then the product's default.
90
+ * runGate and the intent gate's preparation in run.ts both call this, so the
91
+ * two cannot disagree about a gate's limit.
92
+ */
93
+ export function resolveTimeLimit(gate, override) {
94
+ if (override !== undefined) {
95
+ return { ms: override, source: 'override' };
96
+ }
97
+ if (gate.timeoutSeconds !== undefined) {
98
+ return { ms: gate.timeoutSeconds * 1000, source: 'policy' };
99
+ }
100
+ return { ms: profileFor(gate.product).timeoutMs, source: 'default' };
101
+ }
102
+ /**
103
+ * Classifies a spawnSync result that carries an error. PURE, so it is tested
104
+ * on hand-built results.
105
+ *
106
+ * THE ERROR CODE ALONE decides it. ETIMEDOUT is timed-out and nothing else
107
+ * is. No status or signal condition belongs here: a child that traps SIGTERM,
108
+ * or ignores it and exits on its own, comes back with status 0 (or its
109
+ * blocked code) and signal null, and ENOBUFS arrives with the same SIGTERM a
110
+ * timeout does. The signal is recorded for the report and never classifies.
111
+ */
112
+ export function spawnFailure(child) {
113
+ if (child.error === undefined) {
114
+ return null;
115
+ }
116
+ if (child.error.code === 'ETIMEDOUT') {
117
+ return { reason: 'timed-out', signal: child.signal ?? null };
118
+ }
119
+ return { reason: 'spawn-failed', message: child.error.message };
120
+ }
121
+ /** "(the default for this gate)", or where the policy value came from. */
122
+ function limitSourcePhrase(gate, source, trustBase) {
123
+ if (source === 'policy') {
124
+ return trustBase === undefined
125
+ ? `gates.${gate.role}.timeout-seconds`
126
+ : `gates.${gate.role}.timeout-seconds on ${trustBase}`;
127
+ }
128
+ return source === 'default' ? 'the default for this gate' : 'set by the caller';
129
+ }
130
+ /**
131
+ * The note for `options.timeout` on the secrets-history gate, which is
132
+ * gitleaks' own --timeout and not conductor's limit. Null when the key is not
133
+ * set or the gate is not gitleaks.
134
+ */
135
+ function gateOwnTimeoutNote(gate, limit, trustBase) {
136
+ if (gate.product !== 'gitleaks' || gate.options.timeout === undefined) {
137
+ return null;
138
+ }
139
+ return (`options.timeout is gitleaks' own --timeout (${String(gate.options.timeout)} s); conductor stops the ` +
140
+ `gate at ${Math.round(limit.ms / 1000)} s (${limitSourcePhrase(gate, limit.source, trustBase)}).`);
141
+ }
142
+ /** The could-not-run detail for a gate stopped at its limit, by step. */
143
+ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
144
+ const limitSeconds = Math.round(limit.ms / 1000);
145
+ const elapsedSeconds = Math.round(elapsedMs / 1000);
146
+ const where = limitSourcePhrase(gate, limit.source, trustBase);
147
+ const own = gateOwnTimeoutNote(gate, limit, trustBase);
148
+ const remedies = profileFor(gate.product).timeoutRemedies(gate.role);
149
+ if (step === 'version-probe') {
150
+ return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
151
+ 'was not run and nothing was checked by it.');
152
+ }
153
+ const what = step === 'scan'
154
+ ? `${gate.product} was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s limit (${where}), ` +
155
+ 'so nothing was checked by it.'
156
+ : `the intent gate's ${step} step was stopped after ${elapsedSeconds} s, at its ${limitSeconds} s ` +
157
+ `limit (${where}), so the gate was not run and nothing was checked by it.`;
158
+ return `${what} ${remedies}${own === null ? '' : ` ${own}`}`;
159
+ }
160
+ function timedOutRecord(step, limit, elapsedMs, signal) {
161
+ return {
162
+ step,
163
+ limitSeconds: Math.round(limit.ms / 1000),
164
+ elapsedSeconds: Math.round(elapsedMs / 1000),
165
+ limitSource: limit.source,
166
+ signal,
167
+ };
168
+ }
169
+ /** The `conductor/gate-failed` finding for a timed-out gate, with the timing in its details. */
170
+ function timedOutFinding(gate, detail, timedOut, stderr) {
171
+ return normalizeFailedGate(gate.role, gate.product, detail, stderr, {
172
+ timedOut: {
173
+ limitSeconds: timedOut.limitSeconds,
174
+ elapsedSeconds: timedOut.elapsedSeconds,
175
+ limitSource: timedOut.limitSource,
176
+ },
177
+ });
178
+ }
85
179
  /**
86
180
  * conductor's own reason for a could-not-run, as a job-log excerpt: cleaned,
87
181
  * one line, capped and with double quotes replaced, exactly like a gate's
@@ -98,25 +192,89 @@ export function conductorStatedReason(detail) {
98
192
  export function cleanOutputLine(raw) {
99
193
  return breakWorkflowMarkers(raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
100
194
  }
195
+ /** A zerolog line at one level: gitleaks' "<time> ERR ..." shape. */
196
+ const ZEROLOG_ERR = /^\S+\s+ERR\s/;
197
+ const ZEROLOG_WRN = /^\S+\s+WRN\s/;
198
+ function plainLine(raw) {
199
+ return raw.replace(/[^\x20-\x7e]/g, ' ').replace(/\s+/g, ' ').trim();
200
+ }
201
+ /**
202
+ * The stderr half of the stated-reason rule: the line a gate marks as its
203
+ * failure, else the first line that is not informational, else nothing.
204
+ *
205
+ * 1. Lines are split after stripAnsi. Whitespace tests (blank, indented)
206
+ * are made there, before sanitizing, because a colour code can come
207
+ * before the indentation; markers are matched on the sanitized text, so
208
+ * a leading emoji or colour code does not hide one.
209
+ * 2. Informational lines are never chosen: a `note:` line and every
210
+ * following indented line (a BLANK line ends the note block, so an
211
+ * indented reason after it is not swallowed), and gitleaks' two
212
+ * rename-detection warnings.
213
+ * 3. A marker wins: the first remaining INCOMPLETE: or zerolog ERR line,
214
+ * joined with the indented lines after it, skipping blank lines, up to
215
+ * the first non-blank line that is not indented.
216
+ * 4. No marker: the first remaining line.
217
+ */
218
+ function statedReasonFromStderr(stderr) {
219
+ const lines = stripAnsi(stderr)
220
+ .split('\n')
221
+ .map((raw) => {
222
+ const blank = raw.trim() === '';
223
+ return { blank, indented: !blank && /^\s/.test(raw), text: plainLine(raw), informational: false };
224
+ });
225
+ for (let i = 0; i < lines.length; i++) {
226
+ const line = lines[i];
227
+ if (/^note:/i.test(line.text)) {
228
+ line.informational = true;
229
+ for (let j = i + 1; j < lines.length && lines[j].indented; j++) {
230
+ lines[j].informational = true;
231
+ }
232
+ }
233
+ else if (ZEROLOG_WRN.test(line.text) &&
234
+ (line.text.includes('rename detection was skipped') || line.text.includes('diff.renameLimit'))) {
235
+ line.informational = true;
236
+ }
237
+ }
238
+ const candidate = (line) => !line.blank && !line.informational && line.text !== '';
239
+ const markerAt = lines.findIndex((line) => candidate(line) && (line.text.startsWith('INCOMPLETE:') || ZEROLOG_ERR.test(line.text)));
240
+ if (markerAt >= 0) {
241
+ const block = [lines[markerAt].text];
242
+ for (let k = markerAt + 1; k < lines.length; k++) {
243
+ const next = lines[k];
244
+ if (next.blank) {
245
+ continue;
246
+ }
247
+ if (!next.indented) {
248
+ break;
249
+ }
250
+ if (next.text !== '') {
251
+ block.push(next.text);
252
+ }
253
+ }
254
+ return sanitizeGateSaid(block.join(' '));
255
+ }
256
+ const first = lines.find(candidate);
257
+ return first === undefined ? null : sanitizeGateSaid(first.text);
258
+ }
101
259
  /**
102
260
  * What a gate that exited with a non-verdict code said about why.
103
261
  *
104
262
  * TOTAL, and never a decision: the caller has already settled that this is a
105
- * could-not-run, and nothing here can change that. The first non-empty stderr
106
- * line is preferred, since that is where every gate in the family prints its
107
- * reason on exit 2 (dep-guard, intent-guard and vault-guard all do). Failing
108
- * that, stdout is parsed only for a gate whose output is JSON on stdout, and
109
- * only a string `reason` field (top level, or on `run`) is read; anything else,
110
- * including output that does not parse, is simply no excerpt.
263
+ * could-not-run, and nothing here can change that. stderr is preferred, since
264
+ * that is where every gate in the family prints its reason on exit 2
265
+ * (dep-guard, intent-guard and vault-guard all do), read by the rule in
266
+ * `statedReasonFromStderr`: the line the gate marks as the failure, never an
267
+ * informational line. Failing that, stdout is parsed only for a gate whose
268
+ * output is JSON on stdout, and only a string `reason` field (top level, or
269
+ * on `run`) is read; anything else, including output that does not parse, is
270
+ * simply no excerpt. An absent excerpt is better than quoting a warning as
271
+ * the cause; the full stderr is still printed in the text report.
111
272
  */
112
273
  export function gateStatedReason(stderr, stdout, stdoutIsJson) {
113
274
  try {
114
- const firstLine = stripAnsi(stderr)
115
- .split('\n')
116
- .map((line) => sanitizeGateSaid(line))
117
- .find((line) => line !== null);
118
- if (firstLine !== undefined && firstLine !== null) {
119
- return firstLine;
275
+ const fromStderr = statedReasonFromStderr(stderr);
276
+ if (fromStderr !== null) {
277
+ return fromStderr;
120
278
  }
121
279
  if (!stdoutIsJson || typeof stdout !== 'string' || !stdout.trimStart().startsWith('{')) {
122
280
  return null;
@@ -321,6 +479,33 @@ export function preparationFailed(gate, detail) {
321
479
  diagnostics: [],
322
480
  };
323
481
  }
482
+ /**
483
+ * The intent gate whose preparation step (import-spec or freeze) was stopped
484
+ * at the gate's time limit. Shaped like `preparationFailed`, with the
485
+ * timed-out reason, so it composes the same way; the caller decides
486
+ * `enforce` under the same rule it applies to a failed preparation.
487
+ */
488
+ export function preparationTimedOut(gate, stopped) {
489
+ const detail = timedOutDetail(gate, stopped.step, stopped.limit, stopped.elapsedMs, stopped.trustBase);
490
+ const timedOut = timedOutRecord(stopped.step, stopped.limit, stopped.elapsedMs, stopped.signal);
491
+ return {
492
+ role: gate.role,
493
+ product: gate.product,
494
+ stage: gate.stage,
495
+ enforce: gate.enforce,
496
+ productVersion: null,
497
+ argv: [],
498
+ binary: null,
499
+ exitCode: null,
500
+ durationMs: stopped.elapsedMs,
501
+ stderr: '',
502
+ timeLimit: stopped.limit,
503
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
504
+ findings: [timedOutFinding(gate, detail, timedOut)],
505
+ run: EMPTY_RUN,
506
+ diagnostics: [],
507
+ };
508
+ }
324
509
  const EMPTY_RUN = {
325
510
  failOn: null,
326
511
  suppressed: 0,
@@ -597,25 +782,25 @@ intentBase) {
597
782
  }
598
783
  }
599
784
  }
600
- /**
601
- * Asks a binary for its version.
602
- *
603
- * Never called for a binary the candidate table marks unsafe to ask: the
604
- * per-command binaries ignore --version and run the gate instead, so a
605
- * probe there would have side effects on the user's repository.
606
- */
607
785
  function probeVersion(binary, product, repoRoot, timeoutMs) {
608
786
  const spec = profileFor(product).versionProbe;
609
787
  if (binary.versionProbe === null || spec === null) {
610
- return null;
788
+ return { kind: 'unreadable' };
611
789
  }
790
+ const probeStarted = Date.now();
612
791
  const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
613
792
  cwd: repoRoot,
614
793
  encoding: 'utf8',
615
794
  timeout: timeoutMs,
616
795
  });
796
+ // FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
797
+ // version on stdout, and it was still stopped at the limit.
798
+ const failure = spawnFailure(probe);
799
+ if (failure !== null && failure.reason === 'timed-out') {
800
+ return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
801
+ }
617
802
  if (probe.status !== 0 || typeof probe.stdout !== 'string') {
618
- return null;
803
+ return { kind: 'unreadable' };
619
804
  }
620
805
  // Take the first line and accept it only if the product's pattern matches,
621
806
  // so a future help banner does not end up in a SARIF driver's version
@@ -624,7 +809,7 @@ function probeVersion(binary, product, repoRoot, timeoutMs) {
624
809
  // a capture group that takes the number alone.
625
810
  const first = probe.stdout.trim().split('\n')[0]?.trim() ?? '';
626
811
  const match = spec.pattern.exec(first);
627
- return match === null ? null : (match[1] ?? match[0]).replace(/^v/, '');
812
+ return match === null ? { kind: 'unreadable' } : { kind: 'version', value: (match[1] ?? match[0]).replace(/^v/, '') };
628
813
  }
629
814
  /**
630
815
  * `context.blocked` is whether the gate's exit said it blocked. The npm gates
@@ -648,7 +833,7 @@ function normalizeFor(product, parsed, version, context) {
648
833
  case 'gitleaks':
649
834
  return normalizeGitleaks(parsed, version, context.blocked);
650
835
  case 'osv-scanner':
651
- return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles);
836
+ return normalizeOsvScanner(parsed, version, context.blocked, context.roots, context.lockfiles, context.stderr);
652
837
  }
653
838
  }
654
839
  /**
@@ -805,7 +990,19 @@ function isShallowRepository(repoRoot) {
805
990
  return probe.status === 0 && probe.stdout.trim() === 'true';
806
991
  }
807
992
  function runGateInner(gate, options, started, progress) {
808
- const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
993
+ // Every spawn of this gate gets the FULL limit, not a share of it: the
994
+ // version probe, the scan and, on a compared pull request, osv-scanner's
995
+ // base run. Onto `progress` so every outcome from here on carries it.
996
+ const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
997
+ const timeoutMs = timeLimit.ms;
998
+ Object.assign(progress, { timeLimit });
999
+ const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
1000
+ if (ownOption !== null) {
1001
+ // Before any spawn, the way nodeModulesSkipped is, so every return path
1002
+ // from here on carries it, the gate-error of gitleaks' own deadline
1003
+ // included.
1004
+ Object.assign(progress, { gateOwnOption: ownOption });
1005
+ }
809
1006
  // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
810
1007
  // trust base. resolve.ts knows nothing about refs, so it is told rather than
811
1008
  // asked.
@@ -938,7 +1135,29 @@ function runGateInner(gate, options, started, progress) {
938
1135
  diagnostics: [],
939
1136
  };
940
1137
  }
941
- const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1138
+ const probed = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
1139
+ if (probed.kind === 'timed-out') {
1140
+ // Stopped here, before the version floor and before decideTrustBase: a
1141
+ // timed-out probe is not an unreadable version (which on a pull request
1142
+ // would read as trust-base-unverified, a packaging problem that does not
1143
+ // exist), and a local run does not go on to scan with the version
1144
+ // unknown. Enforced under a trust base, like trust-base-unverified: the
1145
+ // gate could not be placed inside the boundary.
1146
+ const detail = timedOutDetail(gate, 'version-probe', timeLimit, probed.elapsedMs, options.trustBase);
1147
+ const timedOut = timedOutRecord('version-probe', timeLimit, probed.elapsedMs, probed.signal);
1148
+ return {
1149
+ ...base,
1150
+ binary,
1151
+ enforce: options.trustBase !== undefined ? true : gate.enforce,
1152
+ durationMs: Date.now() - started,
1153
+ exitCode: null,
1154
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1155
+ findings: [timedOutFinding(gate, detail, timedOut)],
1156
+ run: EMPTY_RUN,
1157
+ diagnostics: [],
1158
+ };
1159
+ }
1160
+ const version = probed.kind === 'version' ? probed.value : null;
942
1161
  // A PATH binary at a different version than the run was told to expect: a
943
1162
  // fact for a warning and nothing else. It sits on `progress` (which `base`
944
1163
  // is) so every outcome from here on carries it, and no branch below reads it.
@@ -1046,7 +1265,7 @@ function runGateInner(gate, options, started, progress) {
1046
1265
  version,
1047
1266
  trustBase,
1048
1267
  profile,
1049
- timeoutMs,
1268
+ timeLimit,
1050
1269
  workDir,
1051
1270
  });
1052
1271
  }
@@ -1062,7 +1281,8 @@ function stripAnsi(text) {
1062
1281
  }
1063
1282
  /** Builds the command line, runs the gate, and reads what it said. */
1064
1283
  function spawnAndRead(ctx) {
1065
- const { gate, options, started, progress, base, binary, version, trustBase, profile, timeoutMs, workDir } = ctx;
1284
+ const { gate, options, started, progress, base, binary, version, trustBase, profile, timeLimit, workDir } = ctx;
1285
+ const timeoutMs = timeLimit.ms;
1066
1286
  const external = {};
1067
1287
  if (profile.output.kind === 'report-file' && workDir !== null) {
1068
1288
  external.reportPath = path.join(workDir, `${gate.product}-report${profile.output.extension}`);
@@ -1263,6 +1483,9 @@ function spawnAndRead(ctx) {
1263
1483
  ...binary.argvPrefix,
1264
1484
  ...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
1265
1485
  ];
1486
+ // Taken just before the call, so a timed-out message's elapsed time is the
1487
+ // scan's own and not resolution plus the version probe.
1488
+ const spawnStarted = Date.now();
1266
1489
  const child = spawnSync(binary.command, argv, {
1267
1490
  cwd: spawnCwd,
1268
1491
  encoding: 'utf8',
@@ -1294,14 +1517,34 @@ function spawnAndRead(ctx) {
1294
1517
  // Keep the backstop's view current, so an unexpected throw below still
1295
1518
  // reports which binary ran and what it printed.
1296
1519
  Object.assign(progress, withRun);
1297
- if (child.error !== undefined) {
1520
+ // THE FIRST THING READ after spawnSync returns, ahead of every status,
1521
+ // signal, report and stdout check, and it returns for every error. A child
1522
+ // stopped at the limit that handled SIGTERM can come back with status 0, or
1523
+ // its blocked code, and a complete clean report or clean JSON on stdout;
1524
+ // only this order keeps that from reading as a verdict. The outcome's
1525
+ // exitCode is null whatever child.status says: a status from a child that
1526
+ // was told to stop is not a verdict. Nothing on this path reads the report
1527
+ // file, parses stdout or calls a normalizer.
1528
+ const failure = spawnFailure(child);
1529
+ if (failure !== null) {
1530
+ if (failure.reason === 'timed-out') {
1531
+ const elapsedMs = Date.now() - spawnStarted;
1532
+ const detail = timedOutDetail(gate, 'scan', timeLimit, elapsedMs, options.trustBase);
1533
+ const timedOut = timedOutRecord('scan', timeLimit, elapsedMs, failure.signal);
1534
+ return {
1535
+ ...withRun,
1536
+ exitCode: null,
1537
+ couldNotRun: { reason: 'timed-out', detail, timedOut },
1538
+ findings: [timedOutFinding(gate, detail, timedOut, withRun.stderr)],
1539
+ run: EMPTY_RUN,
1540
+ diagnostics: [],
1541
+ };
1542
+ }
1298
1543
  return {
1299
1544
  ...withRun,
1300
1545
  exitCode: null,
1301
- couldNotRun: { reason: 'spawn-failed', detail: child.error.message },
1302
- findings: [
1303
- normalizeFailedGate(gate.role, gate.product, child.error.message, withRun.stderr),
1304
- ],
1546
+ couldNotRun: { reason: 'spawn-failed', detail: failure.message },
1547
+ findings: [normalizeFailedGate(gate.role, gate.product, failure.message, withRun.stderr)],
1305
1548
  run: EMPTY_RUN,
1306
1549
  diagnostics: [],
1307
1550
  };
@@ -1354,12 +1597,13 @@ function spawnAndRead(ctx) {
1354
1597
  // The profile says which exits are verdicts. For the npm gates that is 0
1355
1598
  // and 1, exactly as before profiles existed: dep-guard's 2 means "could not
1356
1599
  // run the checks at all" and it prints no JSON. gitleaks is handed
1357
- // --exit-code 3, so its 1 is left meaning an error. A signal-killed child
1358
- // or a timeout lands here too, and none of those are a clean result.
1600
+ // --exit-code 3, so its 1 is left meaning an error. A child killed by
1601
+ // something other than the umbrella lands here too (a timeout returned
1602
+ // above), and none of those are a clean result.
1359
1603
  const blocked = exitCode !== null && profile.exit.blocked.includes(exitCode);
1360
1604
  if (exitCode === null || (!blocked && !profile.exit.clean.includes(exitCode))) {
1361
1605
  const detail = exitCode === null
1362
- ? 'the gate did not exit normally (killed, or timed out).'
1606
+ ? `the gate was killed by signal ${child.signal ?? 'unknown'} before it exited.`
1363
1607
  : `the gate exited ${exitCode}, which it uses for "could not run".`;
1364
1608
  // WHY, in the gate's own words, when it said. Read here and nowhere
1365
1609
  // earlier: the exit code has already been judged above, and this only
@@ -1459,6 +1703,7 @@ function spawnAndRead(ctx) {
1459
1703
  // not off gate.options: the argv is what dep-guard was actually told.
1460
1704
  online: argv.includes('--online'),
1461
1705
  lockfiles: external.lockfiles ?? [],
1706
+ stderr: withRun.stderr,
1462
1707
  });
1463
1708
  // The base comparison (osv design, section 3.1): only on a decided trust
1464
1709
  // base, only when the head run exited blocked and produced a finding. A
@@ -168,6 +168,7 @@ export interface ManagedDeclaration {
168
168
  detectedIn: ManagedDetection;
169
169
  }
170
170
  export declare function declaredManagedHooks(root: string): ManagedDeclaration | null;
171
+ export declare function declaredHusky(root: string): string | null;
171
172
  /**
172
173
  * What init says when it finds one of those two, and why it says nothing
173
174
  * else.
@@ -203,6 +203,51 @@ export function declaredManagedHooks(root) {
203
203
  }
204
204
  return null;
205
205
  }
206
+ /**
207
+ * Where this repository's package.json declares husky, or null: a husky
208
+ * dependency or devDependency, or a prepare script that runs husky. The
209
+ * signal that exists on a fresh clone, before husky's own install has set
210
+ * core.hooksPath. Unreadable or unparseable is the same as undeclared, as for
211
+ * declaredManagedHooks above.
212
+ */
213
+ /**
214
+ * husky as a COMMAND in a script: at the start or after a shell separator
215
+ * (&&, ||, ;, |), optionally behind a package runner, and followed by an
216
+ * argument or the end. So "husky", "husky install", "is-ci || husky" and
217
+ * "npx husky" match, and "no-husky" or "echo skip husky" do not.
218
+ */
219
+ const HUSKY_COMMAND = /(?:^|&&|\|\||;|\|)\s*(?:(?:npx|pnpx|bunx)\s+|(?:pnpm|yarn|npm)\s+(?:exec\s+)?)?husky(?:\s|$)/;
220
+ export function declaredHusky(root) {
221
+ const raw = readIfExists(path.join(root, 'package.json'));
222
+ if (raw === undefined) {
223
+ return null;
224
+ }
225
+ let parsed;
226
+ try {
227
+ parsed = JSON.parse(raw);
228
+ }
229
+ catch {
230
+ return null;
231
+ }
232
+ if (!isPlainObject(parsed)) {
233
+ return null;
234
+ }
235
+ const manifest = parsed;
236
+ for (const key of ['devDependencies', 'dependencies']) {
237
+ const deps = manifest[key];
238
+ if (isPlainObject(deps) && deps.husky !== undefined) {
239
+ return `package.json (${key})`;
240
+ }
241
+ }
242
+ const scripts = manifest.scripts;
243
+ if (isPlainObject(scripts)) {
244
+ const prepare = scripts.prepare;
245
+ if (typeof prepare === 'string' && HUSKY_COMMAND.test(prepare)) {
246
+ return 'package.json (the prepare script)';
247
+ }
248
+ }
249
+ return null;
250
+ }
206
251
  function isPlainObject(value) {
207
252
  return typeof value === 'object' && value !== null && !Array.isArray(value);
208
253
  }
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
4
4
  import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
5
5
  import { installName } from './normalize.js';
6
+ import { profileFor } from './products.js';
6
7
  import { CANDIDATES } from './resolve.js';
7
8
  export { POLICY_FILE_NAME };
8
9
  /** Names of the gates whose binary resolves right now. */
@@ -102,6 +103,14 @@ export function renderPolicy(detected, frozenContractPath) {
102
103
  lines.push(` ${role}:`);
103
104
  lines.push(` product: ${product}`);
104
105
  lines.push(` enabled: ${enabled ? 'true' : 'false'}`);
106
+ // An external tool is enabled only because THIS machine has it, and
107
+ // nothing installs it anywhere else: say so where the next reader of the
108
+ // file will look, not only in init's own output, which nobody re-reads.
109
+ if (enabled && !profileFor(product).managed) {
110
+ lines.push(` # Enabled because ${product} was found on the machine that ran init. CI must`);
111
+ lines.push(` # install ${product} itself (conductor does not); without it this gate`);
112
+ lines.push(' # reports conductor/gate-missing and the run exits 2.');
113
+ }
105
114
  lines.push(` stage: ${DEFAULT_STAGE_FOR_ROLE[role]}`);
106
115
  // The intent gate is the one with ceremony, and the ramp is what makes
107
116
  // that ceremony adoptable: with no frozen contract yet, it reports for a
@@ -147,6 +156,10 @@ export function renderPolicy(detected, frozenContractPath) {
147
156
  if (role === 'secrets-history') {
148
157
  lines.push(' # gitleaks has no severity floor. Tune its rules in .gitleaks.toml and');
149
158
  lines.push(' # accept an old finding in .gitleaksignore, not here.');
159
+ // No timeout-seconds line: an absent key is the default, and writing
160
+ // 600 would freeze today's default into every new policy.
161
+ lines.push(' # A full-history scan can outlive the 600 s default on a large repository.');
162
+ lines.push(' # Set timeout-seconds beside enforce to change it; see the README.');
150
163
  }
151
164
  else if (role === 'vulnerabilities') {
152
165
  lines.push(' # osv-scanner has no severity floor. Tune what it reports in');
package/dist/init.d.ts CHANGED
@@ -91,6 +91,12 @@ export interface InitResult {
91
91
  content: string;
92
92
  kind: 'hook' | 'policy';
93
93
  }>;
94
+ /**
95
+ * The .gitignore that GITIGNORE_LINE is appended to on apply, when the
96
+ * manifest is not already ignored and appending is safe. Absent otherwise.
97
+ * Never in the manifest: --revert does not touch .gitignore.
98
+ */
99
+ gitignoreAppend?: string;
94
100
  }
95
101
  export interface InitOptions {
96
102
  cwd: string;
@@ -117,6 +123,8 @@ export interface InitOptions {
117
123
  force?: boolean;
118
124
  }
119
125
  export declare function planInit(options: InitOptions): InitResult;
126
+ /** The line init adds to .gitignore for the per-machine manifest. */
127
+ export declare const GITIGNORE_LINE = ".guardrails/";
120
128
  export declare function applyInit(plan: InitResult, options: InitOptions): InitResult;
121
129
  export interface RevertResult {
122
130
  ok: boolean;