@vaultcompass/conductor 0.2.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.
- package/LICENSE +21 -0
- package/README.md +412 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +231 -0
- package/dist/envelope.d.ts +105 -0
- package/dist/envelope.js +75 -0
- package/dist/exit-codes.d.ts +30 -0
- package/dist/exit-codes.js +67 -0
- package/dist/gate-runner.d.ts +97 -0
- package/dist/gate-runner.js +354 -0
- package/dist/init.d.ts +138 -0
- package/dist/init.js +973 -0
- package/dist/intent-base.d.ts +54 -0
- package/dist/intent-base.js +135 -0
- package/dist/intent-prepare.d.ts +57 -0
- package/dist/intent-prepare.js +297 -0
- package/dist/intent-spec.d.ts +62 -0
- package/dist/intent-spec.js +268 -0
- package/dist/normalize.d.ts +58 -0
- package/dist/normalize.js +582 -0
- package/dist/output-sarif.d.ts +34 -0
- package/dist/output-sarif.js +564 -0
- package/dist/output-text.d.ts +12 -0
- package/dist/output-text.js +448 -0
- package/dist/policy.d.ts +126 -0
- package/dist/policy.js +328 -0
- package/dist/resolve.d.ts +52 -0
- package/dist/resolve.js +207 -0
- package/dist/run.d.ts +100 -0
- package/dist/run.js +147 -0
- package/package.json +43 -0
- package/schema/guardrails.schema.json +88 -0
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
export interface BaseResolution {
|
|
2
|
+
ref: string;
|
|
3
|
+
/** Which input named it, so the report can say. */
|
|
4
|
+
source: 'flag' | 'github';
|
|
5
|
+
}
|
|
6
|
+
export type ChangedPaths = {
|
|
7
|
+
ok: true;
|
|
8
|
+
paths: string[];
|
|
9
|
+
} | {
|
|
10
|
+
ok: false;
|
|
11
|
+
detail: string;
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* The ref to diff against, or null for a run that is not a pull request.
|
|
15
|
+
*
|
|
16
|
+
* `GITHUB_BASE_REF` is a BRANCH NAME, not a ref anything local can resolve:
|
|
17
|
+
* a CI checkout has no local branch for it, so it is prefixed with `origin/`.
|
|
18
|
+
* Actions defines the variable and leaves it EMPTY outside a pull request, so
|
|
19
|
+
* an empty value has to mean "no pull request" rather than "origin/", which
|
|
20
|
+
* would fail every push build closed.
|
|
21
|
+
*/
|
|
22
|
+
export declare function resolveBaseRef(options: {
|
|
23
|
+
base?: string;
|
|
24
|
+
env: NodeJS.ProcessEnv;
|
|
25
|
+
}): BaseResolution | null;
|
|
26
|
+
/**
|
|
27
|
+
* The branch this run is about.
|
|
28
|
+
*
|
|
29
|
+
* `GITHUB_HEAD_REF` first, and it is not an optimization: `actions/checkout`
|
|
30
|
+
* leaves a pull request build on a DETACHED HEAD, so asking git for the
|
|
31
|
+
* branch name there answers "HEAD" and matches no spec at all. Outside CI the
|
|
32
|
+
* variable is absent and git is the only answer.
|
|
33
|
+
*/
|
|
34
|
+
export declare function currentBranch(repoRoot: string, env: NodeJS.ProcessEnv): string | null;
|
|
35
|
+
/**
|
|
36
|
+
* The paths the branch changed since it forked from `base`.
|
|
37
|
+
*
|
|
38
|
+
* Three flags, each of which is a decision:
|
|
39
|
+
*
|
|
40
|
+
* - `-c core.quotePath=false`, or git escapes any byte outside ASCII and
|
|
41
|
+
* wraps the line in quotes, and the gate is handed a path that matches no
|
|
42
|
+
* glob and no file on disk.
|
|
43
|
+
* - `--no-renames`, so a rename lists BOTH its old and its new path. Moving
|
|
44
|
+
* a file out of a protected directory still has to block, which it cannot
|
|
45
|
+
* if only the destination is listed. The cost is that a rename counts as
|
|
46
|
+
* two paths against a max_files budget, which is the same cost
|
|
47
|
+
* intent-guard's own `--base` pays.
|
|
48
|
+
* - the three-dot range, which asks what the branch changed since it forked
|
|
49
|
+
* rather than how it differs from the base branch right now.
|
|
50
|
+
*
|
|
51
|
+
* Fails closed. There is deliberately no fallback to an empty path set on a
|
|
52
|
+
* git error, because an empty path set is indistinguishable from a clean run.
|
|
53
|
+
*/
|
|
54
|
+
export declare function changedPathsSince(repoRoot: string, base: string): ChangedPaths;
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// What the branch changed, and what to measure it against.
|
|
2
|
+
//
|
|
3
|
+
// The intent gate's pre-commit view is the index. Its pull-request view is
|
|
4
|
+
// the set of paths the branch changed since it forked, which is a different
|
|
5
|
+
// question with a different answer, and getting it wrong is not a small
|
|
6
|
+
// error: a two-dot diff attributes every commit that landed on the base
|
|
7
|
+
// branch after this branch forked to this branch, so somebody else's merge
|
|
8
|
+
// breaches this pull request's change budget.
|
|
9
|
+
//
|
|
10
|
+
// The umbrella computes the path set ITSELF rather than handing intent-guard
|
|
11
|
+
// its own `--base`, and that is a deliberate cost. The contract for a run may
|
|
12
|
+
// live in a temporary directory (see intent-prepare.ts), and `--base` inside
|
|
13
|
+
// the gate resolves git relative to `--project`, where there is no
|
|
14
|
+
// repository. Computing the set here and passing `--paths` is the one
|
|
15
|
+
// arrangement that works for both the native and the imported contract, and
|
|
16
|
+
// the flags below are copied from intent-guard 1.2.1 so the two agree on what
|
|
17
|
+
// "changed" means rather than agreeing by coincidence.
|
|
18
|
+
import { spawnSync } from 'node:child_process';
|
|
19
|
+
/**
|
|
20
|
+
* The ref to diff against, or null for a run that is not a pull request.
|
|
21
|
+
*
|
|
22
|
+
* `GITHUB_BASE_REF` is a BRANCH NAME, not a ref anything local can resolve:
|
|
23
|
+
* a CI checkout has no local branch for it, so it is prefixed with `origin/`.
|
|
24
|
+
* Actions defines the variable and leaves it EMPTY outside a pull request, so
|
|
25
|
+
* an empty value has to mean "no pull request" rather than "origin/", which
|
|
26
|
+
* would fail every push build closed.
|
|
27
|
+
*/
|
|
28
|
+
export function resolveBaseRef(options) {
|
|
29
|
+
if (options.base !== undefined && options.base !== '') {
|
|
30
|
+
return { ref: options.base, source: 'flag' };
|
|
31
|
+
}
|
|
32
|
+
const fromGithub = options.env.GITHUB_BASE_REF;
|
|
33
|
+
if (fromGithub !== undefined && fromGithub !== '') {
|
|
34
|
+
return { ref: `origin/${fromGithub}`, source: 'github' };
|
|
35
|
+
}
|
|
36
|
+
return null;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The branch this run is about.
|
|
40
|
+
*
|
|
41
|
+
* `GITHUB_HEAD_REF` first, and it is not an optimization: `actions/checkout`
|
|
42
|
+
* leaves a pull request build on a DETACHED HEAD, so asking git for the
|
|
43
|
+
* branch name there answers "HEAD" and matches no spec at all. Outside CI the
|
|
44
|
+
* variable is absent and git is the only answer.
|
|
45
|
+
*/
|
|
46
|
+
export function currentBranch(repoRoot, env) {
|
|
47
|
+
const fromGithub = env.GITHUB_HEAD_REF;
|
|
48
|
+
if (fromGithub !== undefined && fromGithub !== '') {
|
|
49
|
+
return fromGithub;
|
|
50
|
+
}
|
|
51
|
+
const child = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
|
|
52
|
+
cwd: repoRoot,
|
|
53
|
+
encoding: 'utf8',
|
|
54
|
+
});
|
|
55
|
+
const value = (child.stdout ?? '').trim();
|
|
56
|
+
if (child.status !== 0 || value === '' || value === 'HEAD') {
|
|
57
|
+
return null;
|
|
58
|
+
}
|
|
59
|
+
return value;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* The paths the branch changed since it forked from `base`.
|
|
63
|
+
*
|
|
64
|
+
* Three flags, each of which is a decision:
|
|
65
|
+
*
|
|
66
|
+
* - `-c core.quotePath=false`, or git escapes any byte outside ASCII and
|
|
67
|
+
* wraps the line in quotes, and the gate is handed a path that matches no
|
|
68
|
+
* glob and no file on disk.
|
|
69
|
+
* - `--no-renames`, so a rename lists BOTH its old and its new path. Moving
|
|
70
|
+
* a file out of a protected directory still has to block, which it cannot
|
|
71
|
+
* if only the destination is listed. The cost is that a rename counts as
|
|
72
|
+
* two paths against a max_files budget, which is the same cost
|
|
73
|
+
* intent-guard's own `--base` pays.
|
|
74
|
+
* - the three-dot range, which asks what the branch changed since it forked
|
|
75
|
+
* rather than how it differs from the base branch right now.
|
|
76
|
+
*
|
|
77
|
+
* Fails closed. There is deliberately no fallback to an empty path set on a
|
|
78
|
+
* git error, because an empty path set is indistinguishable from a clean run.
|
|
79
|
+
*/
|
|
80
|
+
export function changedPathsSince(repoRoot, base) {
|
|
81
|
+
const child = spawnSync('git', [
|
|
82
|
+
'-c',
|
|
83
|
+
'core.quotePath=false',
|
|
84
|
+
'diff',
|
|
85
|
+
'--name-only',
|
|
86
|
+
'--no-renames',
|
|
87
|
+
`${base}...HEAD`,
|
|
88
|
+
], { cwd: repoRoot, encoding: 'utf8' });
|
|
89
|
+
if (child.error !== undefined) {
|
|
90
|
+
return { ok: false, detail: `git could not be run: ${child.error.message}` };
|
|
91
|
+
}
|
|
92
|
+
if (child.status !== 0) {
|
|
93
|
+
// git's own first line usually ends in a full stop, and this message
|
|
94
|
+
// continues after it. Two in a row reads as a typo in a message somebody
|
|
95
|
+
// is already reading because something went wrong.
|
|
96
|
+
const stderr = ((child.stderr ?? '').trim().split('\n')[0] ?? '').replace(/\.+$/, '');
|
|
97
|
+
return {
|
|
98
|
+
ok: false,
|
|
99
|
+
detail: `git could not resolve "${base}...HEAD" (exit ${child.status ?? -1})` +
|
|
100
|
+
`${stderr === '' ? '' : `: ${stderr}`}. ` +
|
|
101
|
+
'In Actions this is usually a shallow checkout with no merge base; ' +
|
|
102
|
+
'check out with fetch-depth: 0, or fetch the base ref before the run.',
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
// Split on newlines and NOTHING else. Trimming each line was corrupting a
|
|
106
|
+
// filename with leading or trailing whitespace into a different filename,
|
|
107
|
+
// which is worse than refusing it: the gate would then check a path that
|
|
108
|
+
// does not exist and never check the one that changed.
|
|
109
|
+
const paths = (child.stdout ?? '').split('\n').filter((line) => line.length > 0);
|
|
110
|
+
for (const entry of paths) {
|
|
111
|
+
// Fail closed rather than hand over a path the encoding cannot carry.
|
|
112
|
+
// `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
|
|
113
|
+
// accepts, so a comma in a filename arrives as two paths: a phantom that
|
|
114
|
+
// can be reported as outside allowed_paths, and a real path that quietly
|
|
115
|
+
// stops being measured against a protected one. It invents a breach and
|
|
116
|
+
// hides one, and neither half is visible in the report.
|
|
117
|
+
if (entry.includes(',')) {
|
|
118
|
+
return {
|
|
119
|
+
ok: false,
|
|
120
|
+
detail: `the changed path "${entry}" contains a comma, and the intent gate takes its ` +
|
|
121
|
+
'path list comma-joined, so it cannot be passed without splitting into two paths. ' +
|
|
122
|
+
'Nothing was checked, rather than checking a path that does not exist.',
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
if (entry !== entry.trim()) {
|
|
126
|
+
return {
|
|
127
|
+
ok: false,
|
|
128
|
+
detail: `the changed path "${entry}" has leading or trailing whitespace, which cannot ` +
|
|
129
|
+
'survive the gate path list intact. Nothing was checked, rather than checking a ' +
|
|
130
|
+
'path that does not exist. A space inside a path is fine.',
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
return { ok: true, paths };
|
|
135
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import type { ResolvedBinary } from './resolve.js';
|
|
2
|
+
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
3
|
+
export declare const TEMP_PREFIX = "conductor-intent-";
|
|
4
|
+
export declare const NATIVE_CONTRACT_PATH = ".conductor/intent-contract.yaml";
|
|
5
|
+
export type ContractSource =
|
|
6
|
+
/** The repository's own frozen contract, used untouched. */
|
|
7
|
+
{
|
|
8
|
+
kind: 'native';
|
|
9
|
+
path: string;
|
|
10
|
+
}
|
|
11
|
+
/** A spec imported and frozen for this run only. Repository-relative paths. */
|
|
12
|
+
| {
|
|
13
|
+
kind: 'imported';
|
|
14
|
+
spec: string;
|
|
15
|
+
plan: string | null;
|
|
16
|
+
} | {
|
|
17
|
+
kind: 'none';
|
|
18
|
+
};
|
|
19
|
+
export interface IntentPreparation {
|
|
20
|
+
contractSource: ContractSource;
|
|
21
|
+
/** The ref the change set was measured against, or null for a staged run. */
|
|
22
|
+
baseRef: string | null;
|
|
23
|
+
/** Whether that ref was asked for or inferred from the CI environment. */
|
|
24
|
+
baseSource: 'flag' | 'github' | null;
|
|
25
|
+
/** What to hand the gate as --project: "." or an absolute temporary path. */
|
|
26
|
+
projectDir: string;
|
|
27
|
+
/** The changed paths, or null to leave v0.1's staged behaviour alone. */
|
|
28
|
+
paths: string[] | null;
|
|
29
|
+
/** Removes anything written outside the repository. Safe to call twice. */
|
|
30
|
+
cleanup: () => void;
|
|
31
|
+
}
|
|
32
|
+
/** Which link of the chain broke. Carried into the report verbatim. */
|
|
33
|
+
export type PrepareStep = 'spec' | 'base' | 'import-spec' | 'write-contract' | 'freeze';
|
|
34
|
+
export type IntentPrepareResult = {
|
|
35
|
+
kind: 'ready';
|
|
36
|
+
preparation: IntentPreparation;
|
|
37
|
+
}
|
|
38
|
+
/** No contract and no spec: an advisory, never an exit code. */
|
|
39
|
+
| {
|
|
40
|
+
kind: 'skip';
|
|
41
|
+
reason: 'no-contract';
|
|
42
|
+
detail: string;
|
|
43
|
+
} | {
|
|
44
|
+
kind: 'failed';
|
|
45
|
+
step: PrepareStep;
|
|
46
|
+
detail: string;
|
|
47
|
+
};
|
|
48
|
+
export interface IntentPrepareOptions {
|
|
49
|
+
repoRoot: string;
|
|
50
|
+
/** The resolved intent-guard binary, or null when none is installed. */
|
|
51
|
+
binary: ResolvedBinary | null;
|
|
52
|
+
env: NodeJS.ProcessEnv;
|
|
53
|
+
base?: string;
|
|
54
|
+
spec?: string;
|
|
55
|
+
timeoutMs?: number;
|
|
56
|
+
}
|
|
57
|
+
export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
// Giving the intent gate a frozen contract for one run, without writing one
|
|
2
|
+
// into the repository.
|
|
3
|
+
//
|
|
4
|
+
// The gate refuses to check anything against a contract nobody approved, and
|
|
5
|
+
// approving one is a per-task human step. That step is the ceremony the
|
|
6
|
+
// stopping-points design exists to keep out of a pull request, so this file
|
|
7
|
+
// stands in for it: it takes the document the work was actually approved
|
|
8
|
+
// from, hands it to intent-guard's own importer, freezes the draft in a
|
|
9
|
+
// TEMPORARY directory, and points the gate at that directory for the length
|
|
10
|
+
// of one run.
|
|
11
|
+
//
|
|
12
|
+
// Two rules keep that from being a lie:
|
|
13
|
+
//
|
|
14
|
+
// - NOTHING IS EVER WRITTEN UNDER <repo>/.conductor. A contract is a
|
|
15
|
+
// committed artifact with an approver's name on it. A pull-request run
|
|
16
|
+
// that dropped one into the working tree would either be committed by
|
|
17
|
+
// accident or picked up by the next run as though a person had approved
|
|
18
|
+
// it, and the second failure is silent.
|
|
19
|
+
//
|
|
20
|
+
// - THE REPOSITORY'S OWN FROZEN CONTRACT ALWAYS WINS. Where a team has done
|
|
21
|
+
// the native flow, the native flow is what runs; the import is the
|
|
22
|
+
// fallback for a repository that has not, not a replacement for one that
|
|
23
|
+
// has. "Exists" is not the test, though: an unfrozen contract is a draft
|
|
24
|
+
// somebody left behind, and running the gate against it fails every pull
|
|
25
|
+
// request on "not frozen by user" without checking anything.
|
|
26
|
+
//
|
|
27
|
+
// Every step can fail, and every failure NAMES ITS STEP. The gate is
|
|
28
|
+
// could-not-run for the whole run either way, so the only thing that
|
|
29
|
+
// distinguishes a shallow checkout from a spec the importer choked on is the
|
|
30
|
+
// sentence in the report.
|
|
31
|
+
import { spawnSync } from 'node:child_process';
|
|
32
|
+
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
33
|
+
import os from 'node:os';
|
|
34
|
+
import path from 'node:path';
|
|
35
|
+
import { parse as parseYaml } from 'yaml';
|
|
36
|
+
import { changedPathsSince, currentBranch, resolveBaseRef } from './intent-base.js';
|
|
37
|
+
import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
|
|
38
|
+
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
39
|
+
export const TEMP_PREFIX = 'conductor-intent-';
|
|
40
|
+
export const NATIVE_CONTRACT_PATH = '.conductor/intent-contract.yaml';
|
|
41
|
+
/**
|
|
42
|
+
* Whether a contract on disk has been approved.
|
|
43
|
+
*
|
|
44
|
+
* `frozen_by: user` and nothing else, because that is the marker THE GATE
|
|
45
|
+
* ITSELF reads. Accepting an `approval` block as an alternative was a guess
|
|
46
|
+
* dressed up as tolerance: a real 1.2.1 freeze writes both, so the only
|
|
47
|
+
* contracts the second test admitted were hand-edited or half-written ones,
|
|
48
|
+
* and admitting those skipped the import and then let the gate block every
|
|
49
|
+
* pull request with "exists but is not frozen by user" -- the exact failure
|
|
50
|
+
* this function exists to prevent.
|
|
51
|
+
*
|
|
52
|
+
* A file that cannot be parsed is treated as not frozen, which sends the run
|
|
53
|
+
* down the import path rather than handing the gate something it will reject.
|
|
54
|
+
*/
|
|
55
|
+
function nativeContractIsFrozen(repoRoot) {
|
|
56
|
+
let parsed;
|
|
57
|
+
try {
|
|
58
|
+
parsed = parseYaml(readFileSync(path.join(repoRoot, NATIVE_CONTRACT_PATH), 'utf8'));
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
return false;
|
|
62
|
+
}
|
|
63
|
+
if (parsed === null || typeof parsed !== 'object') {
|
|
64
|
+
return false;
|
|
65
|
+
}
|
|
66
|
+
return parsed.frozen_by === 'user';
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The command line for one intent-guard subcommand.
|
|
70
|
+
*
|
|
71
|
+
* The resolved binary already carries `check` as its argument prefix, since
|
|
72
|
+
* running the gate is what every other caller wants. The chain needs two
|
|
73
|
+
* other subcommands off the same binary, so the trailing `check` is replaced.
|
|
74
|
+
* A binary whose prefix does not end in `check` is one the candidate table
|
|
75
|
+
* did not choose (the per-command `intent-guard-check`, or a `command:`
|
|
76
|
+
* override with its own `args:`), and neither can run `import-spec` at all.
|
|
77
|
+
*/
|
|
78
|
+
function subcommand(binary, name) {
|
|
79
|
+
const prefix = binary.argvPrefix;
|
|
80
|
+
if (prefix[prefix.length - 1] !== 'check') {
|
|
81
|
+
return null;
|
|
82
|
+
}
|
|
83
|
+
return { command: binary.command, argv: [...prefix.slice(0, -1), name] };
|
|
84
|
+
}
|
|
85
|
+
function run(command, argv, cwd, timeoutMs) {
|
|
86
|
+
const child = spawnSync(command, argv, {
|
|
87
|
+
cwd,
|
|
88
|
+
encoding: 'utf8',
|
|
89
|
+
timeout: timeoutMs,
|
|
90
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
91
|
+
});
|
|
92
|
+
return {
|
|
93
|
+
status: child.status,
|
|
94
|
+
stdout: child.stdout ?? '',
|
|
95
|
+
stderr: child.stderr ?? '',
|
|
96
|
+
errorMessage: child.error === undefined ? null : child.error.message,
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
/** The first line of whatever the child complained with, for a one-line report. */
|
|
100
|
+
function complaint(result) {
|
|
101
|
+
const text = (result.stderr.trim() === '' ? result.stdout : result.stderr).trim();
|
|
102
|
+
return text.split('\n')[0] ?? '';
|
|
103
|
+
}
|
|
104
|
+
/** The short commit the contract is attributed to, or a placeholder. */
|
|
105
|
+
function shortHead(repoRoot) {
|
|
106
|
+
const child = spawnSync('git', ['rev-parse', '--short', 'HEAD'], {
|
|
107
|
+
cwd: repoRoot,
|
|
108
|
+
encoding: 'utf8',
|
|
109
|
+
});
|
|
110
|
+
const value = (child.stdout ?? '').trim();
|
|
111
|
+
return child.status === 0 && value !== '' ? value : 'an unknown commit';
|
|
112
|
+
}
|
|
113
|
+
export function prepareIntent(options) {
|
|
114
|
+
const { repoRoot, env } = options;
|
|
115
|
+
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
116
|
+
// The contract source is decided FIRST, before git is touched. A repository
|
|
117
|
+
// with no spec is never blocked by this gate, and that promise has to hold
|
|
118
|
+
// on a shallow checkout too: resolving the base ref first would turn a
|
|
119
|
+
// fetch-depth of 1 into exit 2 on a repository the gate was never going to
|
|
120
|
+
// check anything in.
|
|
121
|
+
const eventPath = env.GITHUB_EVENT_PATH;
|
|
122
|
+
const prBody = eventPath === undefined ? null : prBodyFromEvent(eventPath);
|
|
123
|
+
const branch = currentBranch(repoRoot, env);
|
|
124
|
+
const discovery = discoverSpec({
|
|
125
|
+
repoRoot,
|
|
126
|
+
...(options.spec === undefined ? {} : { spec: options.spec }),
|
|
127
|
+
...(prBody === null ? {} : { prBody }),
|
|
128
|
+
...(branch === null ? {} : { branch }),
|
|
129
|
+
});
|
|
130
|
+
if (discovery.kind === 'missing-flag') {
|
|
131
|
+
return {
|
|
132
|
+
kind: 'failed',
|
|
133
|
+
step: 'spec',
|
|
134
|
+
detail: `--spec named "${discovery.spec}", which is not in this repository. ` +
|
|
135
|
+
'A spec asked for by name is never replaced by a discovered one.',
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
let source;
|
|
139
|
+
if (discovery.kind === 'flag') {
|
|
140
|
+
source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
|
|
141
|
+
}
|
|
142
|
+
else if (nativeContractIsFrozen(repoRoot)) {
|
|
143
|
+
source = { kind: 'native', path: NATIVE_CONTRACT_PATH };
|
|
144
|
+
}
|
|
145
|
+
else if (discovery.kind === 'none') {
|
|
146
|
+
source = { kind: 'none' };
|
|
147
|
+
}
|
|
148
|
+
else {
|
|
149
|
+
source = { kind: 'imported', spec: discovery.spec, plan: discovery.plan };
|
|
150
|
+
}
|
|
151
|
+
if (source.kind === 'none') {
|
|
152
|
+
return {
|
|
153
|
+
kind: 'skip',
|
|
154
|
+
reason: 'no-contract',
|
|
155
|
+
detail: `No frozen ${NATIVE_CONTRACT_PATH} and no spec under ${SPEC_DIR} matching ` +
|
|
156
|
+
`${branch === null ? 'this branch' : `branch "${branch}"`}. ` +
|
|
157
|
+
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
const base = resolveBaseRef({
|
|
161
|
+
...(options.base === undefined ? {} : { base: options.base }),
|
|
162
|
+
env,
|
|
163
|
+
});
|
|
164
|
+
let paths = null;
|
|
165
|
+
if (base !== null) {
|
|
166
|
+
const changed = changedPathsSince(repoRoot, base.ref);
|
|
167
|
+
if (!changed.ok) {
|
|
168
|
+
return { kind: 'failed', step: 'base', detail: changed.detail };
|
|
169
|
+
}
|
|
170
|
+
paths = changed.paths;
|
|
171
|
+
}
|
|
172
|
+
const common = {
|
|
173
|
+
baseRef: base === null ? null : base.ref,
|
|
174
|
+
baseSource: base === null ? null : base.source,
|
|
175
|
+
paths,
|
|
176
|
+
};
|
|
177
|
+
if (source.kind === 'native') {
|
|
178
|
+
return {
|
|
179
|
+
kind: 'ready',
|
|
180
|
+
preparation: {
|
|
181
|
+
...common,
|
|
182
|
+
contractSource: source,
|
|
183
|
+
// The repository itself, spelled the way every other gate is spelled:
|
|
184
|
+
// the child already runs with the repository root as its working
|
|
185
|
+
// directory.
|
|
186
|
+
projectDir: '.',
|
|
187
|
+
cleanup: () => undefined,
|
|
188
|
+
},
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
if (options.binary === null) {
|
|
192
|
+
// Nothing to run the chain with. The caller reports the missing binary
|
|
193
|
+
// through the ordinary gate-missing path, so this never becomes a second
|
|
194
|
+
// way of saying the same thing.
|
|
195
|
+
return {
|
|
196
|
+
kind: 'failed',
|
|
197
|
+
step: 'import-spec',
|
|
198
|
+
detail: 'no intent-guard binary was resolved, so the spec could not be imported.',
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
const importCommand = subcommand(options.binary, 'import-spec');
|
|
202
|
+
if (importCommand === null) {
|
|
203
|
+
return {
|
|
204
|
+
kind: 'failed',
|
|
205
|
+
step: 'import-spec',
|
|
206
|
+
detail: `the resolved binary is ${options.binary.candidate}, which has no import-spec ` +
|
|
207
|
+
'subcommand. Importing a spec needs the unified intent-guard binary.',
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
const importResult = run(importCommand.command, [
|
|
211
|
+
...importCommand.argv,
|
|
212
|
+
'--project',
|
|
213
|
+
'.',
|
|
214
|
+
'--from',
|
|
215
|
+
'superpowers',
|
|
216
|
+
'--spec',
|
|
217
|
+
path.join(repoRoot, source.spec),
|
|
218
|
+
...(source.plan === null ? [] : ['--plan', path.join(repoRoot, source.plan)]),
|
|
219
|
+
'--dry-run',
|
|
220
|
+
], repoRoot, timeoutMs);
|
|
221
|
+
if (importResult.errorMessage !== null) {
|
|
222
|
+
return { kind: 'failed', step: 'import-spec', detail: importResult.errorMessage };
|
|
223
|
+
}
|
|
224
|
+
if (importResult.status !== 0) {
|
|
225
|
+
return {
|
|
226
|
+
kind: 'failed',
|
|
227
|
+
step: 'import-spec',
|
|
228
|
+
detail: `import-spec exited ${importResult.status ?? -1}: ${complaint(importResult)}`,
|
|
229
|
+
};
|
|
230
|
+
}
|
|
231
|
+
let contractYaml;
|
|
232
|
+
try {
|
|
233
|
+
const parsed = JSON.parse(importResult.stdout);
|
|
234
|
+
if (typeof parsed.contract_yaml !== 'string' || parsed.contract_yaml === '') {
|
|
235
|
+
return {
|
|
236
|
+
kind: 'failed',
|
|
237
|
+
step: 'import-spec',
|
|
238
|
+
detail: 'import-spec printed no contract_yaml, so there is nothing to freeze.',
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
contractYaml = parsed.contract_yaml;
|
|
242
|
+
}
|
|
243
|
+
catch {
|
|
244
|
+
return {
|
|
245
|
+
kind: 'failed',
|
|
246
|
+
step: 'import-spec',
|
|
247
|
+
detail: 'import-spec printed something that is not JSON, so no draft could be read.',
|
|
248
|
+
};
|
|
249
|
+
}
|
|
250
|
+
const projectDir = mkdtempSync(path.join(os.tmpdir(), TEMP_PREFIX));
|
|
251
|
+
const cleanup = () => {
|
|
252
|
+
rmSync(projectDir, { recursive: true, force: true });
|
|
253
|
+
};
|
|
254
|
+
try {
|
|
255
|
+
mkdirSync(path.join(projectDir, '.conductor'), { recursive: true });
|
|
256
|
+
writeFileSync(path.join(projectDir, NATIVE_CONTRACT_PATH), contractYaml);
|
|
257
|
+
}
|
|
258
|
+
catch (err) {
|
|
259
|
+
cleanup();
|
|
260
|
+
return {
|
|
261
|
+
kind: 'failed',
|
|
262
|
+
step: 'write-contract',
|
|
263
|
+
detail: `the drafted contract could not be written: ${err.message}`,
|
|
264
|
+
};
|
|
265
|
+
}
|
|
266
|
+
const freezeCommand = subcommand(options.binary, 'freeze');
|
|
267
|
+
if (freezeCommand === null) {
|
|
268
|
+
cleanup();
|
|
269
|
+
return { kind: 'failed', step: 'freeze', detail: 'no freeze subcommand on this binary.' };
|
|
270
|
+
}
|
|
271
|
+
const freezeResult = run(freezeCommand.command, [
|
|
272
|
+
...freezeCommand.argv,
|
|
273
|
+
'--project',
|
|
274
|
+
projectDir,
|
|
275
|
+
'--approved-by',
|
|
276
|
+
// Says what approved it and against which commit, so the approval is
|
|
277
|
+
// never mistaken for a person's. The spec path is repository-relative,
|
|
278
|
+
// because this string ends up in a contract and a machine path in a
|
|
279
|
+
// contract is exactly what intent-guard's own docs warn about.
|
|
280
|
+
`conductor: ${source.spec} at ${shortHead(repoRoot)}`,
|
|
281
|
+
'--yes',
|
|
282
|
+
'--json',
|
|
283
|
+
], repoRoot, timeoutMs);
|
|
284
|
+
if (freezeResult.errorMessage !== null || freezeResult.status !== 0) {
|
|
285
|
+
cleanup();
|
|
286
|
+
return {
|
|
287
|
+
kind: 'failed',
|
|
288
|
+
step: 'freeze',
|
|
289
|
+
detail: freezeResult.errorMessage ??
|
|
290
|
+
`freeze exited ${freezeResult.status ?? -1}: ${complaint(freezeResult)}`,
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
return {
|
|
294
|
+
kind: 'ready',
|
|
295
|
+
preparation: { ...common, contractSource: source, projectDir, cleanup },
|
|
296
|
+
};
|
|
297
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
export declare const SPEC_DIR = "docs/superpowers/specs";
|
|
2
|
+
export declare const PLAN_DIR = "docs/superpowers/plans";
|
|
3
|
+
export type SpecDiscovery =
|
|
4
|
+
/** Found, with the source that won. Paths are repository-relative. */
|
|
5
|
+
{
|
|
6
|
+
kind: 'flag' | 'pr-body' | 'convention';
|
|
7
|
+
spec: string;
|
|
8
|
+
plan: string | null;
|
|
9
|
+
}
|
|
10
|
+
/** `--spec` named a file that is not there. Never silently replaced. */
|
|
11
|
+
| {
|
|
12
|
+
kind: 'missing-flag';
|
|
13
|
+
spec: string;
|
|
14
|
+
} | {
|
|
15
|
+
kind: 'none';
|
|
16
|
+
};
|
|
17
|
+
export interface SpecDiscoveryOptions {
|
|
18
|
+
repoRoot: string;
|
|
19
|
+
/** `--spec` on the umbrella's command line, repository-relative or absolute. */
|
|
20
|
+
spec?: string;
|
|
21
|
+
/** The pull request body, when this run has one. */
|
|
22
|
+
prBody?: string;
|
|
23
|
+
/** The branch name the slug is derived from. */
|
|
24
|
+
branch?: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The branch name with its prefix removed.
|
|
28
|
+
*
|
|
29
|
+
* Only the FIRST segment goes. Dropping everything but the last would turn
|
|
30
|
+
* `feat/online/widget-cache` into `widget-cache` and match a spec about a
|
|
31
|
+
* different feature, and the prefix convention (`feat/`, `fix/`) is exactly
|
|
32
|
+
* one segment deep.
|
|
33
|
+
*/
|
|
34
|
+
export declare function branchSlug(branch: string): string;
|
|
35
|
+
/**
|
|
36
|
+
* A spec or plan filename reduced to the part that identifies the feature.
|
|
37
|
+
*
|
|
38
|
+
* The date prefix and the `-design` suffix are the two pieces of the
|
|
39
|
+
* superpowers naming convention that carry no identity: the same feature's
|
|
40
|
+
* spec and plan differ by exactly those, which is how intent-guard's own
|
|
41
|
+
* importer pairs them.
|
|
42
|
+
*/
|
|
43
|
+
export declare function normalizeStem(fileName: string): string;
|
|
44
|
+
/** Whether a normalized stem and a slug name the same work. */
|
|
45
|
+
export declare function stemMatches(stem: string, slug: string): boolean;
|
|
46
|
+
/**
|
|
47
|
+
* The path named by a `Spec:` line in a pull request body.
|
|
48
|
+
*
|
|
49
|
+
* Anchored to the start of a line on purpose: a sentence that happens to
|
|
50
|
+
* contain "the Spec: value" in prose is not somebody naming a file, and
|
|
51
|
+
* treating it as one would silently swap the contract a pull request is
|
|
52
|
+
* checked against.
|
|
53
|
+
*
|
|
54
|
+
* The FIRST such line wins when a body carries two. Not a deep decision, but
|
|
55
|
+
* it has to be a decision rather than whatever the regex happened to do: a
|
|
56
|
+
* pull request edited to add a second line above the first would otherwise
|
|
57
|
+
* change contract without the diff showing it.
|
|
58
|
+
*/
|
|
59
|
+
export declare function specFromPrBody(body: string): string | null;
|
|
60
|
+
/** `pull_request.body` out of a GitHub event payload, or null. */
|
|
61
|
+
export declare function prBodyFromEvent(eventPath: string): string | null;
|
|
62
|
+
export declare function discoverSpec(options: SpecDiscoveryOptions): SpecDiscovery;
|