@vaultcompass/conductor 0.2.0 → 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 +66 -3
- package/dist/cli.js +49 -6
- package/dist/init.d.ts +1 -1
- package/dist/init.js +37 -11
- package/dist/intent-prepare.d.ts +25 -2
- package/dist/intent-prepare.js +14 -1
- package/dist/intent-spec.d.ts +13 -0
- package/dist/intent-spec.js +21 -0
- package/dist/output-sarif.js +7 -1
- package/dist/output-text.js +39 -7
- package/dist/run.d.ts +21 -7
- package/dist/run.js +1 -0
- package/package.json +10 -11
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,
|
|
@@ -393,8 +456,8 @@ promotion would want and which the audits do by hand today; and anything that
|
|
|
393
456
|
runs inside an agent session or on save, which intent-guard's own optional
|
|
394
457
|
session hooks already cover.
|
|
395
458
|
|
|
396
|
-
|
|
397
|
-
|
|
459
|
+
This is a young tool rather than a finished one. The gates are still the
|
|
460
|
+
product; this is the convenience layer over them.
|
|
398
461
|
|
|
399
462
|
## Design notes
|
|
400
463
|
|
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
|
-
|
|
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)}`);
|
package/dist/init.d.ts
CHANGED
|
@@ -24,7 +24,7 @@ export declare const INTENT_GUARD_HOOK_MARKER = "conductor-managed-pre-commit";
|
|
|
24
24
|
* once in a repository somebody else already wired up.
|
|
25
25
|
*/
|
|
26
26
|
export type HookManager = 'native' | 'husky' | 'lefthook' | 'precommit';
|
|
27
|
-
export type ConflictReason = 'not-a-git-repository' | 'foreign-hook' | 'gate-hook' | 'generated-hook' | 'hooks-path-outside-repository' | 'no-manifest' | 'changed-since-init' | 'write-failed';
|
|
27
|
+
export type ConflictReason = 'not-a-git-repository' | 'foreign-hook' | 'gate-hook' | 'generated-hook' | 'hooks-path-outside-repository' | 'no-manifest' | 'manifest-unreadable' | 'changed-since-init' | 'write-failed';
|
|
28
28
|
export interface InitConflict {
|
|
29
29
|
path: string;
|
|
30
30
|
reason: ConflictReason;
|
package/dist/init.js
CHANGED
|
@@ -52,7 +52,7 @@
|
|
|
52
52
|
// directory, which is the state this whole property exists to survive.
|
|
53
53
|
import { createHash } from 'node:crypto';
|
|
54
54
|
import { execFileSync } from 'node:child_process';
|
|
55
|
-
import { chmodSync, mkdirSync, readFileSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
|
|
55
|
+
import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, statSync, writeFileSync, } from 'node:fs';
|
|
56
56
|
import path from 'node:path';
|
|
57
57
|
import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
58
58
|
import { CANDIDATES } from './resolve.js';
|
|
@@ -820,7 +820,28 @@ export function revertInit(options) {
|
|
|
820
820
|
});
|
|
821
821
|
return { ok: false, actions, conflicts };
|
|
822
822
|
}
|
|
823
|
-
|
|
823
|
+
// Not routed through readManifest, which answers null for both a missing
|
|
824
|
+
// file and an unparseable one. Revert has to tell those apart: a missing
|
|
825
|
+
// manifest means there is no record to act on, an unreadable one means the
|
|
826
|
+
// record exists and cannot be trusted, and the second is a file somebody
|
|
827
|
+
// has to look at by hand.
|
|
828
|
+
let manifest;
|
|
829
|
+
try {
|
|
830
|
+
manifest = JSON.parse(raw);
|
|
831
|
+
}
|
|
832
|
+
catch {
|
|
833
|
+
conflicts.push({
|
|
834
|
+
path: MANIFEST_RELATIVE_PATH,
|
|
835
|
+
reason: 'manifest-unreadable',
|
|
836
|
+
guidance: `${MANIFEST_RELATIVE_PATH} will not parse, so there is no usable record of what init ` +
|
|
837
|
+
'wrote. Nothing was removed and nothing was guessed. Repair the file by hand if you ' +
|
|
838
|
+
'know what belongs in it. If init ran with --adopt, this file holds the only copy of ' +
|
|
839
|
+
'the hook that --adopt replaced, so recover that content from it before deleting ' +
|
|
840
|
+
'anything. Only then delete it and remove the hook and the policy file yourself, and ' +
|
|
841
|
+
're-run init.',
|
|
842
|
+
});
|
|
843
|
+
return { ok: false, actions, conflicts };
|
|
844
|
+
}
|
|
824
845
|
const relative = (file) => path.relative(root, file).split(path.sep).join('/');
|
|
825
846
|
const planned = manifest.files.map((file) => {
|
|
826
847
|
const current = readIfExists(file.path);
|
|
@@ -848,14 +869,10 @@ export function revertInit(options) {
|
|
|
848
869
|
return { ok: false, actions, conflicts };
|
|
849
870
|
}
|
|
850
871
|
const remaining = [];
|
|
851
|
-
let hookRemoved = false;
|
|
852
872
|
for (const { file, state } of planned) {
|
|
853
873
|
const rel = relative(file.path);
|
|
854
874
|
if (state === 'gone') {
|
|
855
875
|
actions.push({ kind: 'skip', path: rel, detail: 'already gone' });
|
|
856
|
-
if (file.kind === 'hook') {
|
|
857
|
-
hookRemoved = true;
|
|
858
|
-
}
|
|
859
876
|
continue;
|
|
860
877
|
}
|
|
861
878
|
if (state === 'changed' && !force) {
|
|
@@ -874,15 +891,24 @@ export function revertInit(options) {
|
|
|
874
891
|
path: rel,
|
|
875
892
|
detail: state === 'changed' ? 'removed (--force, it had changed)' : 'removed',
|
|
876
893
|
});
|
|
877
|
-
if (file.kind === 'hook') {
|
|
878
|
-
hookRemoved = true;
|
|
879
|
-
}
|
|
880
894
|
}
|
|
881
895
|
// Only restore an adopted hook once the umbrella hook that replaced it is
|
|
882
896
|
// actually gone. Putting the old hook back next to a hook the user has
|
|
883
|
-
// since edited would give them two
|
|
897
|
+
// since edited would give them two at one path, and the edit they asked to
|
|
898
|
+
// keep is the one that gets written over.
|
|
899
|
+
//
|
|
900
|
+
// Read off the world rather than off a flag raised while removing. This
|
|
901
|
+
// used to be a `hookRemoved` boolean, and every path that reached here with
|
|
902
|
+
// a hook in the manifest had already set it, because a hook that changed
|
|
903
|
+
// with no --force returns at the changed-hook check far above. So the flag
|
|
904
|
+
// said what this pass INTENDED and the early return was what actually held
|
|
905
|
+
// the rule, which meant a refactor that flattened that return would satisfy
|
|
906
|
+
// the flag and restore a hook next to a surviving one. existsSync says what
|
|
907
|
+
// is there, which is the thing the rule is about.
|
|
908
|
+
const recordedHooks = planned.filter((entry) => entry.file.kind === 'hook');
|
|
909
|
+
const umbrellaHookGone = recordedHooks.length > 0 && recordedHooks.every((entry) => !existsSync(entry.file.path));
|
|
884
910
|
let adopted = manifest.adopted;
|
|
885
|
-
if (adopted !== null &&
|
|
911
|
+
if (adopted !== null && umbrellaHookGone) {
|
|
886
912
|
mkdirSync(path.dirname(adopted.path), { recursive: true });
|
|
887
913
|
writeFileSync(adopted.path, adopted.content, 'utf8');
|
|
888
914
|
chmodSync(adopted.path, 0o755);
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -35,10 +35,19 @@ export type IntentPrepareResult = {
|
|
|
35
35
|
kind: 'ready';
|
|
36
36
|
preparation: IntentPreparation;
|
|
37
37
|
}
|
|
38
|
-
/**
|
|
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;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -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
|
};
|
package/dist/intent-spec.d.ts
CHANGED
|
@@ -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. */
|
package/dist/intent-spec.js
CHANGED
|
@@ -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
|
package/dist/output-sarif.js
CHANGED
|
@@ -432,7 +432,13 @@ function excludedNotifications(result) {
|
|
|
432
432
|
*/
|
|
433
433
|
function skippedNotifications(result) {
|
|
434
434
|
return result.skipped.map((gate) => ({
|
|
435
|
-
id
|
|
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
|
}));
|
package/dist/output-text.js
CHANGED
|
@@ -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}
|
|
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.
|
|
251
|
-
|
|
252
|
-
|
|
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
|
-
|
|
377
|
-
|
|
378
|
-
|
|
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
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
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.
|
|
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",
|
|
@@ -8,7 +8,6 @@
|
|
|
8
8
|
"type": "git",
|
|
9
9
|
"url": "git+https://github.com/vaultcompasshq/conductor.git"
|
|
10
10
|
},
|
|
11
|
-
"packageManager": "pnpm@9.15.9",
|
|
12
11
|
"engines": {
|
|
13
12
|
"node": ">=22"
|
|
14
13
|
},
|
|
@@ -19,14 +18,6 @@
|
|
|
19
18
|
"dist",
|
|
20
19
|
"schema"
|
|
21
20
|
],
|
|
22
|
-
"scripts": {
|
|
23
|
-
"build": "tsc -b && chmod +x dist/cli.js",
|
|
24
|
-
"pretest": "pnpm build",
|
|
25
|
-
"test": "NODE_OPTIONS=--experimental-vm-modules jest",
|
|
26
|
-
"typecheck": "tsc -b && tsc --noEmit -p tsconfig.test.json",
|
|
27
|
-
"lint": "pnpm check:public-hygiene",
|
|
28
|
-
"check:public-hygiene": "node scripts/check-public-hygiene.mjs"
|
|
29
|
-
},
|
|
30
21
|
"dependencies": {
|
|
31
22
|
"ajv": "^8.17.1",
|
|
32
23
|
"commander": "^12.1.0",
|
|
@@ -39,5 +30,13 @@
|
|
|
39
30
|
"jest": "^30.4.2",
|
|
40
31
|
"ts-jest": "^29.4.12",
|
|
41
32
|
"typescript": "^5.9.3"
|
|
33
|
+
},
|
|
34
|
+
"scripts": {
|
|
35
|
+
"build": "tsc -b && chmod +x dist/cli.js",
|
|
36
|
+
"pretest": "pnpm build",
|
|
37
|
+
"test": "NODE_OPTIONS=--experimental-vm-modules jest",
|
|
38
|
+
"typecheck": "tsc -b && tsc --noEmit -p tsconfig.test.json",
|
|
39
|
+
"lint": "pnpm check:public-hygiene",
|
|
40
|
+
"check:public-hygiene": "node scripts/check-public-hygiene.mjs"
|
|
42
41
|
}
|
|
43
|
-
}
|
|
42
|
+
}
|