@vaultcompass/conductor 0.2.1 → 0.2.2

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
@@ -289,6 +289,11 @@ gate looks like. In Actions this is almost always a shallow checkout, so
289
289
  3. The **first** `Spec: <path>` line in the pull request body, read from the
290
290
  event payload at `GITHUB_EVENT_PATH`. A path here that is not on disk, or
291
291
  one that leaves the repository, falls through to the next rule.
292
+ `Spec: none` is a **waiver**: it says this pull request deliberately has
293
+ no spec, so rule 4 is not tried and the gate reports itself skipped with
294
+ `intent-guard/contract-waived` instead of `intent-guard/no-contract`. The
295
+ token is exact and lowercase, a frozen contract at rule 2 still wins over
296
+ it, and `--spec` at rule 1 still overrides it.
292
297
  4. A markdown file **directly under** `docs/superpowers/specs` whose name
293
298
  relates to the branch. The branch slug is the branch name with its first
294
299
  segment (`feat/`, `fix/`) removed; a filename is reduced by stripping a
@@ -303,7 +308,20 @@ line in the text report and one `intent-guard/no-contract` notification
303
308
  in the `conductor` run, and it **never** reaches the exit code, enforced or
304
309
  not. A branch with no spec is a branch this gate has no opinion about, and
305
310
  turning that into a failed build is how a gate gets switched off across a
306
- repository.
311
+ repository. A waived pull request lands in the same state and is reported
312
+ under its own `intent-guard/contract-waived` id, with its own wording on the
313
+ skipped line, in the verdict and on the one-line summary of a clean run, so a
314
+ reader can tell "nobody has written one" from "somebody decided against one"
315
+ wherever they meet it.
316
+
317
+ **A waiver is a decision, recorded by whoever wrote the pull request body,
318
+ and that includes a contributor from a fork.** On the ordinary path, where a
319
+ repository has no frozen contract of its own, `Spec: none` means the intent
320
+ gate does not run at all on that pull request, and budget breaches are the
321
+ thing this gate blocks on. The one thing a waiver cannot override is a frozen
322
+ `.conductor/intent-contract.yaml`, which is checked first: a repository that
323
+ wants the gate to be non-waivable freezes a native contract and keeps it
324
+ committed.
307
325
 
308
326
  **What blocks is unchanged.** Blocking stays where intent-guard puts it:
309
327
  budget breaches block, subject to `enforce`. Drift on its own is reported and
@@ -370,6 +388,51 @@ runs whatever its author pushes to it next. Pin every third-party action by
370
388
  commit digest in a workflow you actually run, the way this repository's own
371
389
  workflows do.
372
390
 
391
+ ### The report as a pull request comment
392
+
393
+ The SARIF upload produces no alerts on a private repository without GitHub
394
+ Code Security, which is why that step carries `continue-on-error`. A comment
395
+ is free there. Add `pull-requests: write` to the job's `permissions` and this
396
+ step after the gates. It **runs the gates a second time**, because the Action
397
+ writes SARIF and nothing else, so the job costs roughly twice the gate time;
398
+ `--verbose` because a clean run otherwise collapses to one line.
399
+
400
+ ```yaml
401
+ - name: Comment the report on the pull request
402
+ # always: the report is most worth reading on the run that failed,
403
+ # and the gates step has already failed the job by then.
404
+ if: always()
405
+ continue-on-error: true
406
+ env:
407
+ GH_TOKEN: ${{ github.token }}
408
+ PR: ${{ github.event.pull_request.number }}
409
+ # || true: a blocking finding is a non-zero exit, and that verdict
410
+ # belongs to the gates step rather than to this one.
411
+ run: |
412
+ node_modules/.bin/conductor run --stage ci --format text --verbose --output conductor.txt || true
413
+ gh pr comment "$PR" --body-file conductor.txt
414
+ ```
415
+
416
+ **Mirror whatever you gave the Action**, or the two runs can report different
417
+ contracts. The step above matches the example, which passes neither
418
+ `base-ref` nor `spec`, so both runs read `GITHUB_BASE_REF` and the `Spec:`
419
+ line out of the job environment themselves and land on the same contract. If
420
+ you set either input on the gates step, pass the same values here as `--base`
421
+ and `--spec`; if you do not, the comment is a report of a contract source the
422
+ uploaded log never used.
423
+
424
+ **On a pull request from a fork the token is read-only**, so `gh pr comment`
425
+ fails, `continue-on-error` swallows the failure, and no comment appears on
426
+ exactly the pull requests a reviewer knows least about. Nothing here fixes
427
+ that: `pull_request_target` runs with a writable token and the base
428
+ repository's own workflow, which is a different security decision to take on
429
+ purpose rather than a flag to add.
430
+
431
+ This is a substitute for code-scanning alerts, not the same thing. A comment
432
+ is one snapshot of one run: no per-finding state, nothing to dismiss, no
433
+ history between runs, and a new comment every time rather than an alert that
434
+ closes when the finding goes away.
435
+
373
436
  ## What is in and what is out
374
437
 
375
438
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,
package/dist/cli.js CHANGED
@@ -18,10 +18,27 @@ import { GATE_ROLES, GATE_STAGES, PolicyError, applyCliOverrides, loadPolicy } f
18
18
  import { runAll } from './run.js';
19
19
  const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
20
20
  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
21
+ /**
22
+ * The working-tree root, or a thrown one-line diagnosis of why there is none.
23
+ *
24
+ * The policy file, the hook, and every child's working directory are all
25
+ * anchored at the working-tree root, so a run from a subdirectory behaves
26
+ * exactly like a run from the top.
27
+ *
28
+ * This used to catch everything and return the working directory. Two quite
29
+ * different failures hid in that: git is not on PATH, and this directory is
30
+ * not inside a repository. Both then produced "no .guardrails.yaml here, run
31
+ * conductor init" from a subdirectory of a repository that has one, which is
32
+ * a confident answer to a question nobody asked. The generated hook has
33
+ * always named a missing git in its own words (src/init.ts), for the same
34
+ * reason.
35
+ *
36
+ * Errors rather than a fallback root, because the alternative is silently
37
+ * gating a commit against the wrong tree. `run`'s own catch turns these into
38
+ * one line on stderr with no stack and the could-not-run exit code, so
39
+ * nothing here has to know about either.
40
+ */
21
41
  function repoRoot(cwd) {
22
- // The policy file, the hook, and every child's working directory are all
23
- // anchored at the working-tree root, so a run from a subdirectory behaves
24
- // exactly like a run from the top.
25
42
  try {
26
43
  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
27
44
  cwd,
@@ -29,8 +46,22 @@ function repoRoot(cwd) {
29
46
  stdio: ['ignore', 'pipe', 'ignore'],
30
47
  }).trim();
31
48
  }
32
- catch {
33
- return cwd;
49
+ catch (err) {
50
+ if (err.code === 'ENOENT') {
51
+ throw new Error('git is not on PATH, so the repository root could not be found. Install git, or ' +
52
+ 'run conductor from a shell that has it.');
53
+ }
54
+ if (typeof err.status === 'number') {
55
+ // git ran and refused. The directory is named because it is the one
56
+ // thing the reader has to check, and it is the directory they typed
57
+ // the command in rather than anything internal to this tool.
58
+ throw new Error(`not a git repository: ${cwd}. conductor anchors every gate at the working-tree ` +
59
+ 'root, so run it inside a checkout.');
60
+ }
61
+ // git is there and never got as far as an exit code: a permissions
62
+ // problem, or a machine out of processes. Neither of the two sentences
63
+ // above would be true, so this says what actually happened.
64
+ throw new Error(`git could not be run to find the repository root: ${err.message}`);
34
65
  }
35
66
  }
36
67
  function parseFormat(value) {
@@ -143,8 +174,11 @@ export function buildProgram() {
143
174
  .exitOverride()
144
175
  .action((options) => {
145
176
  const cwd = process.cwd();
146
- const root = repoRoot(cwd);
147
177
  try {
178
+ // Inside the try, because repoRoot now reports rather than guesses,
179
+ // and the catch below is what turns any of its three sentences into
180
+ // one line on stderr and the could-not-run exit code.
181
+ const root = repoRoot(cwd);
148
182
  const policy = applyCliOverrides(loadPolicy(root), {
149
183
  ...(parseRoles(options.gate) === undefined
150
184
  ? {}
@@ -186,6 +220,15 @@ export function buildProgram() {
186
220
  // reaches here; anything that does is the umbrella's own problem and
187
221
  // still must not put a local filesystem path in front of a user who
188
222
  // cannot act on it, or into a pre-commit hook's output.
223
+ //
224
+ // The working directory in repoRoot's "not a git repository" sentence
225
+ // is the deliberate exception, and it is the shape of the rule rather
226
+ // than a hole in it: the user typed the command in that directory, it
227
+ // is the one thing they have to check, and a message that withheld it
228
+ // would be telling somebody their directory is wrong without saying
229
+ // which one. What the rule is really about is a path this tool knows
230
+ // and the reader does not, in a stack frame or a message they cannot
231
+ // act on.
189
232
  process.exitCode = fail(err instanceof PolicyError
190
233
  ? err.message
191
234
  : `conductor: ${err instanceof Error ? err.message : String(err)}`);
@@ -35,10 +35,19 @@ export type IntentPrepareResult = {
35
35
  kind: 'ready';
36
36
  preparation: IntentPreparation;
37
37
  }
38
- /** No contract and no spec: an advisory, never an exit code. */
38
+ /**
39
+ * Nothing to check against: an advisory, never an exit code.
40
+ *
41
+ * Two reasons, and they are different facts about the same run.
42
+ * `no-contract` is the ordinary state of a branch nobody has written a
43
+ * spec for; `contract-waived` is somebody saying in the pull request body
44
+ * that there is deliberately no spec for this one. Reporting the second as
45
+ * the first tells a reviewer to go and write a spec that was already
46
+ * decided against.
47
+ */
39
48
  | {
40
49
  kind: 'skip';
41
- reason: 'no-contract';
50
+ reason: 'no-contract' | 'contract-waived';
42
51
  detail: string;
43
52
  } | {
44
53
  kind: 'failed';
@@ -53,5 +62,19 @@ export interface IntentPrepareOptions {
53
62
  base?: string;
54
63
  spec?: string;
55
64
  timeoutMs?: number;
65
+ /**
66
+ * The directory the per-run temporary project is created under.
67
+ *
68
+ * Injected exactly like `env` and `pathValue` are, and for the same kind
69
+ * of reason: the two tests that prove nothing is leaked count the
70
+ * `conductor-intent-` directories either side of a run, and counting them
71
+ * in the shared temporary directory made each of those tests depend on
72
+ * what the other jest worker happened to be doing at that moment. Nothing
73
+ * in production passes it, so a real run still uses the system temporary
74
+ * directory. It cannot be steered with TMPDIR from a test either: node
75
+ * reads that from the real process environment, and a jest test's
76
+ * `process.env` is a copy that never reaches it.
77
+ */
78
+ tempRoot?: string;
56
79
  }
57
80
  export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
@@ -142,6 +142,19 @@ export function prepareIntent(options) {
142
142
  else if (nativeContractIsFrozen(repoRoot)) {
143
143
  source = { kind: 'native', path: NATIVE_CONTRACT_PATH };
144
144
  }
145
+ else if (discovery.kind === 'waived') {
146
+ // BELOW the native check, and the order is the whole meaning of the
147
+ // token: "Spec: none" says there is no spec to import, not that this
148
+ // repository's own frozen contract should be ignored. Above the
149
+ // convention, though, which discoverSpec has already settled: an
150
+ // explicit statement beats an inferred one.
151
+ return {
152
+ kind: 'skip',
153
+ reason: 'contract-waived',
154
+ detail: 'The pull request body waived the spec with a "Spec: none" line, so there was ' +
155
+ `nothing to import and no frozen ${NATIVE_CONTRACT_PATH} to fall back on.`,
156
+ };
157
+ }
145
158
  else if (discovery.kind === 'none') {
146
159
  source = { kind: 'none' };
147
160
  }
@@ -247,7 +260,7 @@ export function prepareIntent(options) {
247
260
  detail: 'import-spec printed something that is not JSON, so no draft could be read.',
248
261
  };
249
262
  }
250
- const projectDir = mkdtempSync(path.join(os.tmpdir(), TEMP_PREFIX));
263
+ const projectDir = mkdtempSync(path.join(options.tempRoot ?? os.tmpdir(), TEMP_PREFIX));
251
264
  const cleanup = () => {
252
265
  rmSync(projectDir, { recursive: true, force: true });
253
266
  };
@@ -11,9 +11,22 @@ export type SpecDiscovery =
11
11
  | {
12
12
  kind: 'missing-flag';
13
13
  spec: string;
14
+ }
15
+ /** The pull request body said `Spec: none`: there is nothing to import. */
16
+ | {
17
+ kind: 'waived';
14
18
  } | {
15
19
  kind: 'none';
16
20
  };
21
+ /**
22
+ * The token that turns a `Spec:` line into a waiver.
23
+ *
24
+ * Exact and lowercase. "None" with a capital is somebody writing prose, and
25
+ * a sentence must not be able to switch a gate off; an unusable value that
26
+ * is not this token keeps falling through to the convention, silently, the
27
+ * way every other unusable value does.
28
+ */
29
+ export declare const SPEC_WAIVER_TOKEN = "none";
17
30
  export interface SpecDiscoveryOptions {
18
31
  repoRoot: string;
19
32
  /** `--spec` on the umbrella's command line, repository-relative or absolute. */
@@ -24,6 +24,9 @@
24
24
  // pull request, which is a weaker claim than a command line typed now,
25
25
  // and a path here that does not exist FALLS THROUGH to the convention. A
26
26
  // typo in a pull request description must not be able to fail a build.
27
+ // The one value that does not fall through is the exact token `none`,
28
+ // which WAIVES the import: it is a statement rather than a path, and an
29
+ // explicit statement beats the inferred convention below.
27
30
  //
28
31
  // 3. The convention: a markdown file directly under docs/superpowers/specs
29
32
  // whose name relates to the branch. Directly under, not nested, because
@@ -33,6 +36,15 @@ import { readFileSync, readdirSync, realpathSync } from 'node:fs';
33
36
  import path from 'node:path';
34
37
  export const SPEC_DIR = 'docs/superpowers/specs';
35
38
  export const PLAN_DIR = 'docs/superpowers/plans';
39
+ /**
40
+ * The token that turns a `Spec:` line into a waiver.
41
+ *
42
+ * Exact and lowercase. "None" with a capital is somebody writing prose, and
43
+ * a sentence must not be able to switch a gate off; an unusable value that
44
+ * is not this token keeps falling through to the convention, silently, the
45
+ * way every other unusable value does.
46
+ */
47
+ export const SPEC_WAIVER_TOKEN = 'none';
36
48
  /**
37
49
  * The branch name with its prefix removed.
38
50
  *
@@ -245,6 +257,15 @@ export function discoverSpec(options) {
245
257
  }
246
258
  if (options.prBody !== undefined) {
247
259
  const named = specFromPrBody(options.prBody);
260
+ if (named === SPEC_WAIVER_TOKEN) {
261
+ // Before the convention, because an explicit statement beats an
262
+ // inferred one: whoever opened the pull request said there is no spec
263
+ // to import, and the branch happening to share a name with a file
264
+ // under docs/superpowers/specs does not overrule that. It is NOT
265
+ // before a frozen native contract, which prepareIntent still checks
266
+ // first: a waiver says "nothing to import", not "check nothing".
267
+ return { kind: 'waived' };
268
+ }
248
269
  if (named !== null) {
249
270
  const relative = relativeToRoot(repoRoot, named);
250
271
  // A path out of the tree is treated exactly as a path that is not
@@ -432,7 +432,13 @@ function excludedNotifications(result) {
432
432
  */
433
433
  function skippedNotifications(result) {
434
434
  return result.skipped.map((gate) => ({
435
- id: `${gate.product}/no-contract`,
435
+ // The reason IS the second half of the id, which keeps
436
+ // intent-guard/no-contract exactly where consumers already have it and
437
+ // gives the waiver its own id rather than filing two different facts
438
+ // under one. A waiver is a statement about configuration in the purest
439
+ // form the rule above describes: a person wrote it in the pull request
440
+ // body on purpose, so it is a notification and never a result.
441
+ id: `${gate.product}/${gate.reason}`,
436
442
  message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
437
443
  details: { role: gate.role, product: gate.product, reason: gate.reason },
438
444
  }));
@@ -188,7 +188,20 @@ function deferredLines(result) {
188
188
  * the flow yet.
189
189
  */
190
190
  function skippedLines(result) {
191
- return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} no contract: ${gate.detail}`);
191
+ return result.skipped.map((gate) => ` skipped ${gate.role} ${gate.product} ${skipWording(gate.reason).line}: ${gate.detail}`);
192
+ }
193
+ function skipWording(reason) {
194
+ return reason === 'contract-waived'
195
+ ? {
196
+ line: 'spec waived',
197
+ verdict: 'had its spec waived by the pull request body',
198
+ summary: 'Spec waived by the pull request body',
199
+ }
200
+ : {
201
+ line: 'no contract',
202
+ verdict: 'had no contract to check against',
203
+ summary: 'Nothing to check against',
204
+ };
192
205
  }
193
206
  /**
194
207
  * One line per gate the --gate flag left out.
@@ -247,9 +260,14 @@ function verdict(result) {
247
260
  if (result.gates.length === 0 && result.skipped.length > 0) {
248
261
  // A third distinct state, and telling somebody to switch a gate on is
249
262
  // wrong advice here too: the gate IS on, it ran, and it had nothing to
250
- // check. The fix is a spec, which the skipped line above names.
251
- const names = result.skipped.map((gate) => gate.role).join(', ');
252
- return `verdict: exit 0, nothing was checked: ${names} had no contract to check against.`;
263
+ // check. What to do about that is NOT the same in both cases, which is
264
+ // why the clause comes from the skip reason rather than being written
265
+ // here: for a missing spec the fix is to write one, and for a waiver
266
+ // there is nothing to fix, because a person decided it.
267
+ const clauses = result.skipped
268
+ .map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`)
269
+ .join(', ');
270
+ return `verdict: exit 0, nothing was checked: ${clauses}.`;
253
271
  }
254
272
  if (result.gates.length === 0) {
255
273
  // Exit 0 with an empty report is indistinguishable from a clean run at a
@@ -373,9 +391,23 @@ function summaryLine(result) {
373
391
  // Same reasoning as the deferred clause. A gate that ran and had nothing to
374
392
  // check covered none of this commit, and silence there makes a branch with
375
393
  // no spec read as a branch that passed the intent gate.
376
- if (result.skipped.length > 0) {
377
- const names = result.skipped.map((gate) => `${gate.role} (${gate.product})`).join(', ');
378
- parts.push(`Nothing to check against: ${names}.`);
394
+ //
395
+ // One clause per REASON, not one clause for all of them. This line is the
396
+ // whole report on a clean run, which is what a pre-commit hook and a pull
397
+ // request comment print, so a shared "nothing to check against" would hide
398
+ // the difference between nobody having written a spec and somebody having
399
+ // decided there is none exactly where most readers stop reading. Grouped in
400
+ // first-seen order so the sentence does not reorder itself between runs.
401
+ const skippedByWording = new Map();
402
+ for (const gate of result.skipped) {
403
+ const lead = skipWording(gate.reason).summary;
404
+ skippedByWording.set(lead, [
405
+ ...(skippedByWording.get(lead) ?? []),
406
+ `${gate.role} (${gate.product})`,
407
+ ]);
408
+ }
409
+ for (const [lead, names] of skippedByWording) {
410
+ parts.push(`${lead}: ${names.join(', ')}.`);
379
411
  }
380
412
  // Same reasoning again, for the gates the command line left out. This one
381
413
  // is the easiest of the three to lose: a --gate run is usually somebody
package/dist/run.d.ts CHANGED
@@ -34,17 +34,24 @@ export interface ExcludedGate {
34
34
  /**
35
35
  * An enabled gate that had nothing to check.
36
36
  *
37
- * Exactly one thing produces this today: an intent gate on a branch with no
38
- * frozen contract and no spec to import. It is not a deferred gate (nobody
39
- * asked for a different stage), it is not a could-not-run (nothing broke),
40
- * and it must never reach the exit code, enforced or not. A branch that has
41
- * no spec is a branch this gate has no opinion about, and turning that into
42
- * a failed build is how a gate gets switched off repository-wide.
37
+ * Two things produce this today, both of them an intent gate with no frozen
38
+ * contract: a branch with no spec to import (`no-contract`), and a pull
39
+ * request body that waived the spec with a `Spec: none` line
40
+ * (`contract-waived`). Neither is a deferred gate (nobody asked for a
41
+ * different stage), neither is a could-not-run (nothing broke), and neither
42
+ * must ever reach the exit code, enforced or not. A branch that has no spec
43
+ * is a branch this gate has no opinion about, and turning that into a failed
44
+ * build is how a gate gets switched off repository-wide.
45
+ *
46
+ * The reason is carried rather than flattened because the two ask different
47
+ * things of a reader: one wants a spec written, the other says a person
48
+ * already decided there is none. It is also the second half of the
49
+ * notification id in the SARIF log.
43
50
  */
44
51
  export interface SkippedGate {
45
52
  role: GateRole;
46
53
  product: Product;
47
- reason: 'no-contract';
54
+ reason: 'no-contract' | 'contract-waived';
48
55
  detail: string;
49
56
  }
50
57
  export interface RunResult {
@@ -96,5 +103,12 @@ export interface RunOptions {
96
103
  env?: NodeJS.ProcessEnv;
97
104
  /** Injected in tests so a run's output is comparable between runs. */
98
105
  now?: () => Date;
106
+ /**
107
+ * Where the intent gate's per-run temporary project is created. Injected
108
+ * in tests so the one that counts leaked directories counts its own and
109
+ * not another jest worker's; nothing in production passes it. See
110
+ * IntentPrepareOptions.tempRoot.
111
+ */
112
+ tempRoot?: string;
99
113
  }
100
114
  export declare function runAll(policy: Policy, options: RunOptions): RunResult;
package/dist/run.js CHANGED
@@ -79,6 +79,7 @@ export function runAll(policy, options) {
79
79
  ...(options.base === undefined ? {} : { base: options.base }),
80
80
  ...(options.spec === undefined ? {} : { spec: options.spec }),
81
81
  ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
82
+ ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
82
83
  });
83
84
  if (prepared.kind === 'skip') {
84
85
  skipped.push({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "license": "MIT",