vouchington-tooling 0.78.2 → 0.80.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/README.md +58 -3
- package/dist/agent-blackboard/feedback-journal-sandbox.d.mts +1 -1
- package/dist/agent-blackboard/feedback-journal-sandbox.mjs +11 -2
- package/dist/audit-journal/audit-block.d.mts +8 -2
- package/dist/audit-journal/audit-block.mjs +35 -5
- package/dist/audit-journal/ci-failures.mjs +11 -1
- package/dist/cli/index.mjs +3 -0
- package/dist/cli/parse-forwarded-commands.d.mts +1 -1
- package/dist/cli/parse-forwarded-commands.mjs +1 -0
- package/dist/cli/parse.d.mts +3 -0
- package/dist/cli/usage-text.d.mts +1 -1
- package/dist/cli/usage-text.mjs +2 -0
- package/dist/mcp-server/dispatch.d.mts +3 -0
- package/dist/mcp-server/dispatch.mjs +7 -1
- package/dist/mcp-server/install-info.d.mts +11 -0
- package/dist/mcp-server/install-info.mjs +45 -0
- package/dist/mcp-server/retrospective-facts-input.d.mts +2 -0
- package/dist/mcp-server/retrospective-facts-input.mjs +8 -2
- package/dist/mcp-server/retrospective-input.mjs +6 -2
- package/dist/mcp-server/run.mjs +2 -0
- package/dist/retrospective-transcript/codex-segment.d.mts +7 -0
- package/dist/retrospective-transcript/codex-segment.mjs +14 -10
- package/dist/retrospective-transcript/index.mjs +16 -11
- package/dist/runner-policy/cli.d.mts +6 -0
- package/dist/runner-policy/cli.mjs +45 -0
- package/dist/runner-policy/config.d.mts +3 -0
- package/dist/runner-policy/config.mjs +97 -0
- package/dist/runner-policy/discover.d.mts +9 -0
- package/dist/runner-policy/discover.mjs +34 -0
- package/dist/runner-policy/evaluate.d.mts +7 -0
- package/dist/runner-policy/evaluate.mjs +61 -0
- package/dist/runner-policy/index.d.mts +6 -0
- package/dist/runner-policy/index.mjs +4 -0
- package/dist/runner-policy/matrix.d.mts +13 -0
- package/dist/runner-policy/matrix.mjs +45 -0
- package/dist/runner-policy/rules.d.mts +6 -0
- package/dist/runner-policy/rules.mjs +87 -0
- package/dist/runner-policy/types.d.mts +38 -0
- package/dist/runner-policy/types.mjs +1 -0
- package/dist/runner-policy/workflow.d.mts +24 -0
- package/dist/runner-policy/workflow.mjs +37 -0
- package/dist/sql-ast/no-mistakes-peer.d.mts +54 -49
- package/package.json +7 -2
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
|
@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
|
|
|
3
3
|
import { homedir } from 'node:os';
|
|
4
4
|
import { basename, dirname, join } from 'node:path';
|
|
5
5
|
import { codexChildren, codexIdentity, computeCodex } from "./codex.mjs";
|
|
6
|
-
import {
|
|
6
|
+
import { explainCodexSegment } from "./codex-segment.mjs";
|
|
7
7
|
import { computeClaude } from "./claude.mjs";
|
|
8
8
|
import { formatTranscriptFacts, formatUnavailable } from "./format.mjs";
|
|
9
9
|
import { globFrom, resolveTranscriptFile, SESSION_ID, } from "./resolve-transcript-file.mjs";
|
|
@@ -68,7 +68,7 @@ function matchesChildIdentity(lines, threadId, agentPath) {
|
|
|
68
68
|
const threadMatches = identity.threadId?.toLowerCase() === threadId.toLowerCase();
|
|
69
69
|
return threadMatches && identity.agentPath.replace(/\/$/, '') === agentPath;
|
|
70
70
|
}
|
|
71
|
-
async function codexSubagents(lines, sessionsDir, ownerPath, visited
|
|
71
|
+
async function codexSubagents(lines, sessionsDir, ownerPath, visited, failure) {
|
|
72
72
|
const result = [];
|
|
73
73
|
for (const edge of codexChildren(lines, ownerPath)) {
|
|
74
74
|
if (visited.has(edge.threadId))
|
|
@@ -83,11 +83,13 @@ async function codexSubagents(lines, sessionsDir, ownerPath, visited = new Set()
|
|
|
83
83
|
hasMalformedInteriorRecord(child) ||
|
|
84
84
|
!matchesChildIdentity(child, edge.threadId, edge.agentPath))
|
|
85
85
|
return undefined;
|
|
86
|
-
const
|
|
87
|
-
if (
|
|
86
|
+
const outcome = explainCodexSegment(child);
|
|
87
|
+
if ('reason' in outcome) {
|
|
88
|
+
failure.reason = outcome.reason;
|
|
88
89
|
return undefined;
|
|
89
|
-
|
|
90
|
-
|
|
90
|
+
}
|
|
91
|
+
result.push({ ...outcome.segment, partial: partialCapture(child) });
|
|
92
|
+
const nested = await codexSubagents(outcome.segment.lines, sessionsDir, edge.agentPath, visited, failure);
|
|
91
93
|
if (!nested)
|
|
92
94
|
return undefined;
|
|
93
95
|
result.push(...nested);
|
|
@@ -121,15 +123,18 @@ export async function runRetrospectiveTranscriptReport(options) {
|
|
|
121
123
|
};
|
|
122
124
|
}
|
|
123
125
|
const identity = codexIdentity(lines);
|
|
124
|
-
const
|
|
125
|
-
if (
|
|
126
|
-
return unavailable(
|
|
126
|
+
const rootOutcome = explainCodexSegment(lines);
|
|
127
|
+
if ('reason' in rootOutcome)
|
|
128
|
+
return unavailable(`could not segment Codex transcript: ${rootOutcome.reason}`);
|
|
129
|
+
const root = rootOutcome.segment;
|
|
127
130
|
const codexHome = (options.env ?? process.env).CODEX_HOME;
|
|
131
|
+
const unresolved = 'could not resolve a referenced Codex child transcript';
|
|
132
|
+
const failure = {};
|
|
128
133
|
const subagents = await codexSubagents(root.lines, options.codexSessionsDir ??
|
|
129
134
|
(options.jsonlPath ? dirname(resolved.path) : undefined) ??
|
|
130
|
-
join(codexHome || join(homedir(), '.codex'), 'sessions'), identity.agentPath, new Set([identity.threadId ?? resolved.sessionId].filter((
|
|
135
|
+
join(codexHome || join(homedir(), '.codex'), 'sessions'), identity.agentPath, new Set([identity.threadId ?? resolved.sessionId].filter((id) => SESSION_ID.test(id))), failure);
|
|
131
136
|
if (!subagents)
|
|
132
|
-
return unavailable(
|
|
137
|
+
return unavailable(failure.reason ? `${unresolved}: could not segment it (${failure.reason})` : unresolved);
|
|
133
138
|
return {
|
|
134
139
|
markdown: formatTranscriptFacts(resolved.sessionId, computeCodex(root.lines, subagents, root.baseline)),
|
|
135
140
|
coverage: partialCapture(lines) || subagents.some((segment) => segment.partial)
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export declare const USAGE = "Usage: vouchington runner-policy [--config <file>] [--root <directory>]";
|
|
2
|
+
export interface RunnerPolicyCliOptions {
|
|
3
|
+
output?: Pick<Console, 'error' | 'log'>;
|
|
4
|
+
}
|
|
5
|
+
/** Exit codes: 0 clean, 1 violations or fail-closed input error, 2 usage error. */
|
|
6
|
+
export declare function runRunnerPolicyCli(argv: readonly string[], options?: RunnerPolicyCliOptions): Promise<number>;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { parseArgs } from 'node:util';
|
|
2
|
+
import { DEFAULT_CONFIG_PATH, DEFAULT_WORKFLOW_ROOT, discoverWorkflows, loadRunnerPolicyConfig, } from "./discover.mjs";
|
|
3
|
+
import { evaluateRunnerPolicy, formatRunnerPolicyViolation } from "./evaluate.mjs";
|
|
4
|
+
export const USAGE = 'Usage: vouchington runner-policy [--config <file>] [--root <directory>]';
|
|
5
|
+
/** Exit codes: 0 clean, 1 violations or fail-closed input error, 2 usage error. */
|
|
6
|
+
export async function runRunnerPolicyCli(argv, options = {}) {
|
|
7
|
+
const { output = console } = options;
|
|
8
|
+
let values;
|
|
9
|
+
try {
|
|
10
|
+
;
|
|
11
|
+
({ values } = parseArgs({
|
|
12
|
+
args: [...argv],
|
|
13
|
+
options: {
|
|
14
|
+
config: { type: 'string', default: DEFAULT_CONFIG_PATH },
|
|
15
|
+
root: { type: 'string', default: DEFAULT_WORKFLOW_ROOT },
|
|
16
|
+
},
|
|
17
|
+
strict: true,
|
|
18
|
+
}));
|
|
19
|
+
}
|
|
20
|
+
catch (error) {
|
|
21
|
+
output.error(`${USAGE}\n${error.message}`);
|
|
22
|
+
return 2;
|
|
23
|
+
}
|
|
24
|
+
const empty = ['config', 'root'].find((key) => values[key].trim() === '');
|
|
25
|
+
if (empty !== undefined) {
|
|
26
|
+
output.error(`${USAGE}\n--${empty} requires a non-empty value`);
|
|
27
|
+
return 2;
|
|
28
|
+
}
|
|
29
|
+
try {
|
|
30
|
+
const config = await loadRunnerPolicyConfig(values.config);
|
|
31
|
+
const inputs = await discoverWorkflows(values.root);
|
|
32
|
+
const violations = evaluateRunnerPolicy(inputs, config);
|
|
33
|
+
if (violations.length === 0) {
|
|
34
|
+
output.log(`runner-policy: ${String(inputs.length)} workflow file(s) conform`);
|
|
35
|
+
return 0;
|
|
36
|
+
}
|
|
37
|
+
output.error(`runner-policy: ${String(violations.length)} violation(s)\n` +
|
|
38
|
+
violations.map((violation) => ` - ${formatRunnerPolicyViolation(violation)}`).join('\n'));
|
|
39
|
+
return 1;
|
|
40
|
+
}
|
|
41
|
+
catch (error) {
|
|
42
|
+
output.error(`runner-policy failed: ${error.message}`);
|
|
43
|
+
return 1;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
2
|
+
function checkKeys(value, allowed, where, problems) {
|
|
3
|
+
for (const key of Object.keys(value)) {
|
|
4
|
+
if (!allowed.includes(key))
|
|
5
|
+
problems.push(`${where}: unknown key "${key}"`);
|
|
6
|
+
}
|
|
7
|
+
}
|
|
8
|
+
function stringList(value, where, problems, minimum = 0) {
|
|
9
|
+
const ok = Array.isArray(value) &&
|
|
10
|
+
value.length >= minimum &&
|
|
11
|
+
value.every((item) => typeof item === 'string' && item.trim() !== '');
|
|
12
|
+
if (!ok) {
|
|
13
|
+
problems.push(`${where}: must be ${minimum > 0 ? 'a non-empty' : 'an'} array of non-empty strings`);
|
|
14
|
+
}
|
|
15
|
+
return ok ? value : [];
|
|
16
|
+
}
|
|
17
|
+
function nonEmptyString(value, key, where, problems) {
|
|
18
|
+
const field = value[key];
|
|
19
|
+
if (typeof field === 'string' && field.trim() !== '')
|
|
20
|
+
return field;
|
|
21
|
+
problems.push(`${where}.${key}: must be a non-empty string`);
|
|
22
|
+
return '';
|
|
23
|
+
}
|
|
24
|
+
const jobReference = /^[^#\s]+#[^#\s]+$/;
|
|
25
|
+
function parseRequired(raw, where, problems) {
|
|
26
|
+
checkKeys(raw, ['workflow', 'job', 'runsOn'], where, problems);
|
|
27
|
+
return {
|
|
28
|
+
workflow: nonEmptyString(raw, 'workflow', where, problems),
|
|
29
|
+
job: nonEmptyString(raw, 'job', where, problems),
|
|
30
|
+
runsOn: nonEmptyString(raw, 'runsOn', where, problems),
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
function parseExact(raw, where, problems) {
|
|
34
|
+
checkKeys(raw, ['label', 'jobs'], where, problems);
|
|
35
|
+
const jobs = stringList(raw.jobs, `${where}.jobs`, problems);
|
|
36
|
+
for (const job of jobs) {
|
|
37
|
+
if (!jobReference.test(job))
|
|
38
|
+
problems.push(`${where}.jobs: "${job}" must look like workflow#job`);
|
|
39
|
+
}
|
|
40
|
+
if (new Set(jobs).size !== jobs.length)
|
|
41
|
+
problems.push(`${where}.jobs: entries must be unique`);
|
|
42
|
+
return { label: nonEmptyString(raw, 'label', where, problems), jobs };
|
|
43
|
+
}
|
|
44
|
+
function parseActions(raw, where, problems) {
|
|
45
|
+
if (raw !== undefined && !isRecord(raw)) {
|
|
46
|
+
problems.push(`${where}: must be an object`);
|
|
47
|
+
return { prefixes: [], contains: [], exact: [] };
|
|
48
|
+
}
|
|
49
|
+
const record = raw ?? {};
|
|
50
|
+
checkKeys(record, ['prefixes', 'contains', 'exact'], where, problems);
|
|
51
|
+
const list = (key) => record[key] === undefined ? [] : stringList(record[key], `${where}.${key}`, problems);
|
|
52
|
+
return { prefixes: list('prefixes'), contains: list('contains'), exact: list('exact') };
|
|
53
|
+
}
|
|
54
|
+
function parseRestricted(raw, where, problems) {
|
|
55
|
+
checkKeys(raw, ['label', 'forbidServices', 'forbiddenActions'], where, problems);
|
|
56
|
+
if (raw.forbidServices !== undefined && typeof raw.forbidServices !== 'boolean') {
|
|
57
|
+
problems.push(`${where}.forbidServices: must be a boolean`);
|
|
58
|
+
}
|
|
59
|
+
return {
|
|
60
|
+
label: nonEmptyString(raw, 'label', where, problems),
|
|
61
|
+
forbidServices: raw.forbidServices !== false,
|
|
62
|
+
forbiddenActions: parseActions(raw.forbiddenActions, `${where}.forbiddenActions`, problems),
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
function entries(raw, key, problems, parse) {
|
|
66
|
+
const value = raw[key];
|
|
67
|
+
if (value === undefined)
|
|
68
|
+
return [];
|
|
69
|
+
if (!Array.isArray(value)) {
|
|
70
|
+
problems.push(`${key}: must be an array`);
|
|
71
|
+
return [];
|
|
72
|
+
}
|
|
73
|
+
return value.flatMap((item, index) => {
|
|
74
|
+
const where = `${key}[${String(index)}]`;
|
|
75
|
+
if (isRecord(item))
|
|
76
|
+
return [parse(item, where, problems)];
|
|
77
|
+
problems.push(`${where}: must be an object`);
|
|
78
|
+
return [];
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
/** Validates an untrusted parsed-JSON config; throws one error listing every problem. */
|
|
82
|
+
export function parseRunnerPolicyConfig(raw) {
|
|
83
|
+
if (!isRecord(raw))
|
|
84
|
+
throw new Error('runner-policy config must be a JSON object');
|
|
85
|
+
const problems = [];
|
|
86
|
+
checkKeys(raw, ['allowedLabels', 'requiredJobs', 'exactLabelJobs', 'restrictedLabels'], 'config', problems);
|
|
87
|
+
const config = {
|
|
88
|
+
allowedLabels: stringList(raw.allowedLabels, 'allowedLabels', problems, 1),
|
|
89
|
+
requiredJobs: entries(raw, 'requiredJobs', problems, parseRequired),
|
|
90
|
+
exactLabelJobs: entries(raw, 'exactLabelJobs', problems, parseExact),
|
|
91
|
+
restrictedLabels: entries(raw, 'restrictedLabels', problems, parseRestricted),
|
|
92
|
+
};
|
|
93
|
+
if (problems.length > 0) {
|
|
94
|
+
throw new Error(`invalid runner-policy config:\n${problems.map((p) => ` - ${p}`).join('\n')}`);
|
|
95
|
+
}
|
|
96
|
+
return config;
|
|
97
|
+
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { RunnerPolicyConfig, WorkflowInput } from './types.mts';
|
|
2
|
+
export declare const DEFAULT_WORKFLOW_ROOT = ".github/workflows";
|
|
3
|
+
export declare const DEFAULT_CONFIG_PATH = ".github/runner-policy.json";
|
|
4
|
+
/**
|
|
5
|
+
* Reads every `*.yml` / `*.yaml` file directly under `root` (workflow directories are flat).
|
|
6
|
+
* Throws when the root is missing or not a directory, or when any file cannot be read.
|
|
7
|
+
*/
|
|
8
|
+
export declare function discoverWorkflows(root: string): Promise<WorkflowInput[]>;
|
|
9
|
+
export declare function loadRunnerPolicyConfig(file: string): Promise<RunnerPolicyConfig>;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { readdir, readFile, stat } from 'node:fs/promises';
|
|
2
|
+
import { join, resolve } from 'node:path';
|
|
3
|
+
import { parseRunnerPolicyConfig } from "./config.mjs";
|
|
4
|
+
export const DEFAULT_WORKFLOW_ROOT = '.github/workflows';
|
|
5
|
+
export const DEFAULT_CONFIG_PATH = '.github/runner-policy.json';
|
|
6
|
+
/**
|
|
7
|
+
* Reads every `*.yml` / `*.yaml` file directly under `root` (workflow directories are flat).
|
|
8
|
+
* Throws when the root is missing or not a directory, or when any file cannot be read.
|
|
9
|
+
*/
|
|
10
|
+
export async function discoverWorkflows(root) {
|
|
11
|
+
const directory = resolve(root);
|
|
12
|
+
const info = await stat(directory).catch(() => undefined);
|
|
13
|
+
if (info === undefined || !info.isDirectory()) {
|
|
14
|
+
throw new Error(`workflow root "${root}" does not exist or is not a directory`);
|
|
15
|
+
}
|
|
16
|
+
const entries = await readdir(directory, { withFileTypes: true });
|
|
17
|
+
const names = entries
|
|
18
|
+
.filter((entry) => entry.isFile() && /\.ya?ml$/.test(entry.name))
|
|
19
|
+
.map((entry) => entry.name)
|
|
20
|
+
.sort();
|
|
21
|
+
return Promise.all(names.map(async (path) => ({ path, text: await readFile(join(directory, path), 'utf8') })));
|
|
22
|
+
}
|
|
23
|
+
export async function loadRunnerPolicyConfig(file) {
|
|
24
|
+
let raw;
|
|
25
|
+
try {
|
|
26
|
+
raw = JSON.parse(await readFile(resolve(file), 'utf8'));
|
|
27
|
+
}
|
|
28
|
+
catch (error) {
|
|
29
|
+
throw new Error(`cannot read runner-policy config "${file}": ${error.message}`, {
|
|
30
|
+
cause: error,
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
return parseRunnerPolicyConfig(raw);
|
|
34
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { RunnerPolicyConfig, RunnerPolicyViolation, WorkflowInput } from './types.mts';
|
|
2
|
+
/**
|
|
3
|
+
* Evaluates every configured runner policy over supplied workflow files. Fails closed: empty
|
|
4
|
+
* input, unparseable workflows and config entries naming undiscovered workflows are violations.
|
|
5
|
+
*/
|
|
6
|
+
export declare function evaluateRunnerPolicy(inputs: readonly WorkflowInput[], config: RunnerPolicyConfig): RunnerPolicyViolation[];
|
|
7
|
+
export declare function formatRunnerPolicyViolation(violation: RunnerPolicyViolation): string;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { resolveRunsOn } from "./matrix.mjs";
|
|
2
|
+
import { exactSetViolations, requiredJobViolations, restrictedViolations, } from "./rules.mjs";
|
|
3
|
+
import { parseWorkflowInput } from "./workflow.mjs";
|
|
4
|
+
function allowedLabelViolations(workflows, allowed) {
|
|
5
|
+
const out = [];
|
|
6
|
+
for (const [workflow, parsed] of workflows) {
|
|
7
|
+
for (const [job, body] of parsed.jobs) {
|
|
8
|
+
const base = { workflow, job };
|
|
9
|
+
if (body.uses !== undefined) {
|
|
10
|
+
if (body['runs-on'] !== undefined) {
|
|
11
|
+
out.push({
|
|
12
|
+
...base,
|
|
13
|
+
policy: 'reusable-delegate',
|
|
14
|
+
message: 'reusable-workflow delegate must not set runs-on',
|
|
15
|
+
});
|
|
16
|
+
}
|
|
17
|
+
continue;
|
|
18
|
+
}
|
|
19
|
+
const resolved = resolveRunsOn(body);
|
|
20
|
+
const policy = 'allowed-labels';
|
|
21
|
+
if (resolved.kind === 'invalid') {
|
|
22
|
+
out.push({ ...base, policy, message: resolved.reason });
|
|
23
|
+
continue;
|
|
24
|
+
}
|
|
25
|
+
const labels = resolved.kind === 'literal' ? [resolved.label] : resolved.candidates;
|
|
26
|
+
for (const label of labels.filter((candidate) => !allowed.includes(candidate))) {
|
|
27
|
+
out.push({ ...base, policy, message: `runs-on label "${label}" is not allowed` });
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
return out;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Evaluates every configured runner policy over supplied workflow files. Fails closed: empty
|
|
35
|
+
* input, unparseable workflows and config entries naming undiscovered workflows are violations.
|
|
36
|
+
*/
|
|
37
|
+
export function evaluateRunnerPolicy(inputs, config) {
|
|
38
|
+
if (inputs.length === 0) {
|
|
39
|
+
return [{ policy: 'discovery', message: 'no workflow files were discovered' }];
|
|
40
|
+
}
|
|
41
|
+
const violations = [];
|
|
42
|
+
const workflows = new Map();
|
|
43
|
+
for (const input of inputs) {
|
|
44
|
+
const parsed = parseWorkflowInput(input);
|
|
45
|
+
if (parsed.ok)
|
|
46
|
+
workflows.set(input.path, parsed.workflow);
|
|
47
|
+
else
|
|
48
|
+
violations.push({ policy: 'parse', workflow: input.path, message: parsed.message });
|
|
49
|
+
}
|
|
50
|
+
return [
|
|
51
|
+
...violations,
|
|
52
|
+
...allowedLabelViolations(workflows, config.allowedLabels),
|
|
53
|
+
...requiredJobViolations(config.requiredJobs, workflows),
|
|
54
|
+
...exactSetViolations(config.exactLabelJobs, workflows),
|
|
55
|
+
...restrictedViolations(config.restrictedLabels, workflows),
|
|
56
|
+
];
|
|
57
|
+
}
|
|
58
|
+
export function formatRunnerPolicyViolation(violation) {
|
|
59
|
+
const where = [violation.workflow, violation.job].filter(Boolean).join('#');
|
|
60
|
+
return `${where === '' ? '' : `${where}: `}${violation.message} [${violation.policy}]`;
|
|
61
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { runRunnerPolicyCli, USAGE } from './cli.mts';
|
|
2
|
+
export type { RunnerPolicyCliOptions } from './cli.mts';
|
|
3
|
+
export { parseRunnerPolicyConfig } from './config.mts';
|
|
4
|
+
export { DEFAULT_CONFIG_PATH, DEFAULT_WORKFLOW_ROOT, discoverWorkflows, loadRunnerPolicyConfig, } from './discover.mts';
|
|
5
|
+
export { evaluateRunnerPolicy, formatRunnerPolicyViolation } from './evaluate.mts';
|
|
6
|
+
export type { ExactLabelJobs, ForbiddenActions, RequiredJob, RestrictedLabel, RunnerPolicyConfig, RunnerPolicyName, RunnerPolicyViolation, WorkflowInput, } from './types.mts';
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { runRunnerPolicyCli, USAGE } from "./cli.mjs";
|
|
2
|
+
export { parseRunnerPolicyConfig } from "./config.mjs";
|
|
3
|
+
export { DEFAULT_CONFIG_PATH, DEFAULT_WORKFLOW_ROOT, discoverWorkflows, loadRunnerPolicyConfig, } from "./discover.mjs";
|
|
4
|
+
export { evaluateRunnerPolicy, formatRunnerPolicyViolation } from "./evaluate.mjs";
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type WorkflowJob } from './workflow.mts';
|
|
2
|
+
export type RunsOnResolution = {
|
|
3
|
+
kind: 'literal';
|
|
4
|
+
label: string;
|
|
5
|
+
} | {
|
|
6
|
+
kind: 'matrix';
|
|
7
|
+
candidates: string[];
|
|
8
|
+
} | {
|
|
9
|
+
kind: 'invalid';
|
|
10
|
+
reason: string;
|
|
11
|
+
};
|
|
12
|
+
/** Resolves a non-delegate job's `runs-on` to literal label(s), or explains why it cannot. */
|
|
13
|
+
export declare function resolveRunsOn(job: WorkflowJob): RunsOnResolution;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { isRecord } from "./workflow.mjs";
|
|
2
|
+
const matrixExpression = /^\$\{\{\s*matrix\.([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}$/;
|
|
3
|
+
const invalid = (reason) => ({ kind: 'invalid', reason });
|
|
4
|
+
const candidateText = (value) => typeof value === 'string' ? value : JSON.stringify(value);
|
|
5
|
+
function matrixCandidates(job, field) {
|
|
6
|
+
const matrix = isRecord(job.strategy) ? job.strategy.matrix : undefined;
|
|
7
|
+
if (!isRecord(matrix)) {
|
|
8
|
+
return invalid(`matrix.${field} cannot be resolved: strategy.matrix is not a mapping`);
|
|
9
|
+
}
|
|
10
|
+
const candidates = [];
|
|
11
|
+
const declared = matrix[field];
|
|
12
|
+
if (declared !== undefined) {
|
|
13
|
+
if (!Array.isArray(declared))
|
|
14
|
+
return invalid(`matrix.${field} is not an array of labels`);
|
|
15
|
+
candidates.push(...declared);
|
|
16
|
+
}
|
|
17
|
+
if (matrix.include !== undefined) {
|
|
18
|
+
if (!Array.isArray(matrix.include))
|
|
19
|
+
return invalid('matrix.include is not an array');
|
|
20
|
+
for (const entry of matrix.include) {
|
|
21
|
+
if (isRecord(entry) && entry[field] !== undefined)
|
|
22
|
+
candidates.push(entry[field]);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
if (candidates.length === 0)
|
|
26
|
+
return invalid(`matrix.${field} resolves to no candidates`);
|
|
27
|
+
return { kind: 'matrix', candidates: candidates.map(candidateText) };
|
|
28
|
+
}
|
|
29
|
+
/** Resolves a non-delegate job's `runs-on` to literal label(s), or explains why it cannot. */
|
|
30
|
+
export function resolveRunsOn(job) {
|
|
31
|
+
const runsOn = job['runs-on'];
|
|
32
|
+
if (runsOn === undefined || runsOn === null)
|
|
33
|
+
return invalid('runs-on is missing');
|
|
34
|
+
if (Array.isArray(runsOn))
|
|
35
|
+
return invalid('runs-on must not be an array of labels');
|
|
36
|
+
if (typeof runsOn !== 'string') {
|
|
37
|
+
return invalid(`runs-on must be a literal string, got ${typeof runsOn} form`);
|
|
38
|
+
}
|
|
39
|
+
const field = matrixExpression.exec(runsOn)?.[1];
|
|
40
|
+
if (field !== undefined)
|
|
41
|
+
return matrixCandidates(job, field);
|
|
42
|
+
if (runsOn.includes('${{'))
|
|
43
|
+
return invalid(`runs-on is a computed expression: ${runsOn}`);
|
|
44
|
+
return { kind: 'literal', label: runsOn };
|
|
45
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { ExactLabelJobs, RequiredJob, RestrictedLabel, RunnerPolicyViolation } from './types.mts';
|
|
2
|
+
import { type ParsedWorkflow } from './workflow.mts';
|
|
3
|
+
export type Workflows = ReadonlyMap<string, ParsedWorkflow>;
|
|
4
|
+
export declare function requiredJobViolations(required: readonly RequiredJob[], workflows: Workflows): RunnerPolicyViolation[];
|
|
5
|
+
export declare function exactSetViolations(rules: readonly ExactLabelJobs[], workflows: Workflows): RunnerPolicyViolation[];
|
|
6
|
+
export declare function restrictedViolations(rules: readonly RestrictedLabel[], workflows: Workflows): RunnerPolicyViolation[];
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { resolveRunsOn } from "./matrix.mjs";
|
|
2
|
+
import { hasNonEmptyServices, stepUses } from "./workflow.mjs";
|
|
3
|
+
const missingWorkflow = (policy, workflow) => ({
|
|
4
|
+
policy,
|
|
5
|
+
workflow,
|
|
6
|
+
message: `configured workflow "${workflow}" was not discovered`,
|
|
7
|
+
});
|
|
8
|
+
export function requiredJobViolations(required, workflows) {
|
|
9
|
+
return required.flatMap(({ workflow, job, runsOn }) => {
|
|
10
|
+
const parsed = workflows.get(workflow);
|
|
11
|
+
if (parsed === undefined)
|
|
12
|
+
return [missingWorkflow('required-jobs', workflow)];
|
|
13
|
+
const found = parsed.jobs.get(job);
|
|
14
|
+
const base = { policy: 'required-jobs', workflow, job };
|
|
15
|
+
if (found === undefined)
|
|
16
|
+
return [{ ...base, message: 'required job is missing' }];
|
|
17
|
+
const resolved = resolveRunsOn(found);
|
|
18
|
+
if (resolved.kind === 'literal' && resolved.label === runsOn)
|
|
19
|
+
return [];
|
|
20
|
+
return [{ ...base, message: `required job must use literal runs-on "${runsOn}"` }];
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
/** Labels a job runs on: a literal label, every resolvable matrix candidate, or none. */
|
|
24
|
+
function jobLabels(job) {
|
|
25
|
+
const resolved = resolveRunsOn(job);
|
|
26
|
+
if (resolved.kind === 'literal')
|
|
27
|
+
return [resolved.label];
|
|
28
|
+
return resolved.kind === 'matrix' ? resolved.candidates : [];
|
|
29
|
+
}
|
|
30
|
+
export function exactSetViolations(rules, workflows) {
|
|
31
|
+
return rules.flatMap(({ label, jobs }) => {
|
|
32
|
+
const out = [];
|
|
33
|
+
for (const workflow of new Set(jobs.map((entry) => entry.slice(0, entry.indexOf('#'))))) {
|
|
34
|
+
if (!workflows.has(workflow))
|
|
35
|
+
out.push(missingWorkflow('exact-label-jobs', workflow));
|
|
36
|
+
}
|
|
37
|
+
const actual = new Set();
|
|
38
|
+
for (const [workflow, parsed] of workflows) {
|
|
39
|
+
for (const [id, job] of parsed.jobs) {
|
|
40
|
+
if (job.uses === undefined && jobLabels(job).includes(label))
|
|
41
|
+
actual.add(`${workflow}#${id}`);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
const expected = new Set(jobs);
|
|
45
|
+
const entry = (policyJob, message) => {
|
|
46
|
+
const split = policyJob.indexOf('#');
|
|
47
|
+
const workflow = policyJob.slice(0, split);
|
|
48
|
+
const job = policyJob.slice(split + 1);
|
|
49
|
+
return { policy: 'exact-label-jobs', workflow, job, message };
|
|
50
|
+
};
|
|
51
|
+
for (const job of expected) {
|
|
52
|
+
if (!actual.has(job))
|
|
53
|
+
out.push(entry(job, `expected to run on "${label}" but does not`));
|
|
54
|
+
}
|
|
55
|
+
for (const job of actual) {
|
|
56
|
+
if (!expected.has(job))
|
|
57
|
+
out.push(entry(job, `runs on "${label}" but is not in the exact set`));
|
|
58
|
+
}
|
|
59
|
+
return out;
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
export function restrictedViolations(rules, workflows) {
|
|
63
|
+
const out = [];
|
|
64
|
+
for (const { label, forbidServices, forbiddenActions } of rules) {
|
|
65
|
+
for (const [workflow, parsed] of workflows) {
|
|
66
|
+
for (const [id, job] of parsed.jobs) {
|
|
67
|
+
const resolved = resolveRunsOn(job);
|
|
68
|
+
if (job.uses !== undefined || resolved.kind !== 'literal' || resolved.label !== label) {
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
const base = { policy: 'restricted-label', workflow, job: id };
|
|
72
|
+
if (forbidServices && hasNonEmptyServices(job)) {
|
|
73
|
+
out.push({ ...base, message: `"${label}" jobs must not declare services` });
|
|
74
|
+
}
|
|
75
|
+
for (const action of stepUses(job)) {
|
|
76
|
+
const matched = forbiddenActions.prefixes.some((prefix) => action.startsWith(prefix)) ||
|
|
77
|
+
forbiddenActions.contains.some((part) => action.includes(part)) ||
|
|
78
|
+
forbiddenActions.exact.includes(action);
|
|
79
|
+
if (matched) {
|
|
80
|
+
out.push({ ...base, message: `"${label}" jobs must not use action "${action}"` });
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return out;
|
|
87
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/** One workflow file supplied to the evaluator; `path` is relative to the discovery root. */
|
|
2
|
+
export interface WorkflowInput {
|
|
3
|
+
path: string;
|
|
4
|
+
text: string;
|
|
5
|
+
}
|
|
6
|
+
export interface RequiredJob {
|
|
7
|
+
workflow: string;
|
|
8
|
+
job: string;
|
|
9
|
+
runsOn: string;
|
|
10
|
+
}
|
|
11
|
+
export interface ForbiddenActions {
|
|
12
|
+
prefixes: readonly string[];
|
|
13
|
+
contains: readonly string[];
|
|
14
|
+
exact: readonly string[];
|
|
15
|
+
}
|
|
16
|
+
export interface RestrictedLabel {
|
|
17
|
+
label: string;
|
|
18
|
+
forbidServices: boolean;
|
|
19
|
+
forbiddenActions: ForbiddenActions;
|
|
20
|
+
}
|
|
21
|
+
export interface ExactLabelJobs {
|
|
22
|
+
label: string;
|
|
23
|
+
/** `workflow#job` entries. */
|
|
24
|
+
jobs: readonly string[];
|
|
25
|
+
}
|
|
26
|
+
export interface RunnerPolicyConfig {
|
|
27
|
+
allowedLabels: readonly string[];
|
|
28
|
+
requiredJobs: readonly RequiredJob[];
|
|
29
|
+
exactLabelJobs: readonly ExactLabelJobs[];
|
|
30
|
+
restrictedLabels: readonly RestrictedLabel[];
|
|
31
|
+
}
|
|
32
|
+
export type RunnerPolicyName = 'discovery' | 'parse' | 'allowed-labels' | 'reusable-delegate' | 'required-jobs' | 'exact-label-jobs' | 'restricted-label';
|
|
33
|
+
export interface RunnerPolicyViolation {
|
|
34
|
+
policy: RunnerPolicyName;
|
|
35
|
+
workflow?: string;
|
|
36
|
+
job?: string;
|
|
37
|
+
message: string;
|
|
38
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { WorkflowInput } from './types.mts';
|
|
2
|
+
export interface WorkflowJob {
|
|
3
|
+
uses?: unknown;
|
|
4
|
+
'runs-on'?: unknown;
|
|
5
|
+
services?: unknown;
|
|
6
|
+
strategy?: unknown;
|
|
7
|
+
steps?: unknown;
|
|
8
|
+
}
|
|
9
|
+
export interface ParsedWorkflow {
|
|
10
|
+
path: string;
|
|
11
|
+
jobs: Map<string, WorkflowJob>;
|
|
12
|
+
}
|
|
13
|
+
export type ParseResult = {
|
|
14
|
+
ok: true;
|
|
15
|
+
workflow: ParsedWorkflow;
|
|
16
|
+
} | {
|
|
17
|
+
ok: false;
|
|
18
|
+
message: string;
|
|
19
|
+
};
|
|
20
|
+
export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
|
|
21
|
+
export declare function parseWorkflowInput(input: WorkflowInput): ParseResult;
|
|
22
|
+
/** `uses` values of a job's steps; non-string values are ignored. */
|
|
23
|
+
export declare function stepUses(job: WorkflowJob): string[];
|
|
24
|
+
export declare function hasNonEmptyServices(job: WorkflowJob): boolean;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { parse } from 'yaml';
|
|
2
|
+
export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
3
|
+
export function parseWorkflowInput(input) {
|
|
4
|
+
let document;
|
|
5
|
+
try {
|
|
6
|
+
document = parse(input.text);
|
|
7
|
+
}
|
|
8
|
+
catch (error) {
|
|
9
|
+
return { ok: false, message: `cannot parse YAML: ${error.message.split('\n')[0]}` };
|
|
10
|
+
}
|
|
11
|
+
if (!isRecord(document) || !isRecord(document.jobs)) {
|
|
12
|
+
return { ok: false, message: 'workflow has no jobs mapping' };
|
|
13
|
+
}
|
|
14
|
+
const jobs = new Map();
|
|
15
|
+
for (const [id, job] of Object.entries(document.jobs)) {
|
|
16
|
+
if (!isRecord(job))
|
|
17
|
+
return { ok: false, message: `job "${id}" is not a mapping` };
|
|
18
|
+
jobs.set(id, job);
|
|
19
|
+
}
|
|
20
|
+
return { ok: true, workflow: { path: input.path, jobs } };
|
|
21
|
+
}
|
|
22
|
+
/** `uses` values of a job's steps; non-string values are ignored. */
|
|
23
|
+
export function stepUses(job) {
|
|
24
|
+
if (!Array.isArray(job.steps))
|
|
25
|
+
return [];
|
|
26
|
+
return job.steps.flatMap((step) => isRecord(step) && typeof step.uses === 'string' ? [step.uses] : []);
|
|
27
|
+
}
|
|
28
|
+
export function hasNonEmptyServices(job) {
|
|
29
|
+
const { services } = job;
|
|
30
|
+
if (services === undefined || services === null || services === '')
|
|
31
|
+
return false;
|
|
32
|
+
if (Array.isArray(services))
|
|
33
|
+
return services.length > 0;
|
|
34
|
+
if (isRecord(services))
|
|
35
|
+
return Object.keys(services).length > 0;
|
|
36
|
+
return true;
|
|
37
|
+
}
|