@feigi/fleet-ctl 3.49.4 → 3.50.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/package.json +1 -1
- package/scripts/report-schema.mjs +240 -0
package/package.json
CHANGED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// The shape of a member's report: one JSON Schema per member family, and the
|
|
3
|
+
// check that a report file has that shape.
|
|
4
|
+
//
|
|
5
|
+
// report-schema.mjs print <family>
|
|
6
|
+
// report-schema.mjs validate <family> <file>
|
|
7
|
+
//
|
|
8
|
+
// Reached through the Resolver: `~/.fleet/bin/fleet-run report-schema.mjs ...`.
|
|
9
|
+
// <family> is one of `impl`, `fix-pr`, `finisher`, `merge-bot`. The review
|
|
10
|
+
// runner is not a family here: its report already has a shape of its own.
|
|
11
|
+
//
|
|
12
|
+
// `print` writes the family's schema to stdout as JSON, the text a brief
|
|
13
|
+
// quotes or a `task` call carries as its `outputSchema`. `validate` reads
|
|
14
|
+
// <file> as JSON and checks it against the family's schema.
|
|
15
|
+
//
|
|
16
|
+
// Exit vocabulary:
|
|
17
|
+
//
|
|
18
|
+
// 0 print: the schema is on stdout. validate: `valid` on stdout
|
|
19
|
+
// 1 validate: `invalid: <violation>` on stdout, naming the FIRST violation;
|
|
20
|
+
// a file that is not JSON is invalid too, as `$: not JSON (...)`
|
|
21
|
+
// 2 usage: no or unknown subcommand, a wrong argument count, an unknown
|
|
22
|
+
// family, any flag; or <file> could not be read; or print could not
|
|
23
|
+
// write the schema to stdout. Refused on stderr, nothing on stdout
|
|
24
|
+
//
|
|
25
|
+
// A validate verdict line that stdout would not take changes nothing: the
|
|
26
|
+
// exit code, 0 or 1, is the verdict.
|
|
27
|
+
//
|
|
28
|
+
// Every field a family lists is required, a nullable one included: a report
|
|
29
|
+
// says `null`, it never leaves the field out. Only the top level is closed
|
|
30
|
+
// (`additionalProperties: false`); objects inside it may carry more than
|
|
31
|
+
// their schema names.
|
|
32
|
+
//
|
|
33
|
+
// The validator below is hand-written and covers exactly the keywords these
|
|
34
|
+
// schemas use: `type` (one or a list; `integer` is a whole number), `enum`,
|
|
35
|
+
// `required`, `properties`, `additionalProperties: false`, `items` and
|
|
36
|
+
// `pattern`. A keyword it does not know is not checked, so a schema here
|
|
37
|
+
// that starts using one needs the validator to learn it first. It walks in a
|
|
38
|
+
// fixed order, which is what makes "the first violation" one answer: at
|
|
39
|
+
// each value `type`, then `enum`, then `pattern`; in an object every
|
|
40
|
+
// `required` field in the schema's order, then any unexpected field in the
|
|
41
|
+
// report's order, then each property in the schema's order; in an array each
|
|
42
|
+
// item in turn. A violation is named by its path from the report's root, `$`,
|
|
43
|
+
// as `$.merged[1].sha`.
|
|
44
|
+
//
|
|
45
|
+
// Strict mode. A `task` call can carry this schema as `outputSchema` with
|
|
46
|
+
// `schemaMode: "strict"`. Measured 2026-10-14 under omp/18.10.3, and only on
|
|
47
|
+
// the path a member session can reach: the session's `task` tool takes items
|
|
48
|
+
// of { agent, name, solutionSpace, task, tools } and no `outputSchema` or
|
|
49
|
+
// `schemaMode`, so the same schema was handed to `eval`'s `agent(prompt,
|
|
50
|
+
// { schema, schemaMode })`, with a child told to submit `{}` and never
|
|
51
|
+
// anything else, against a schema requiring a field `x`. Each of its first
|
|
52
|
+
// three submissions got a notice from the child's `yield` tool:
|
|
53
|
+
//
|
|
54
|
+
// Output does not match schema: x: is required. Call yield again with the
|
|
55
|
+
// corrected shape — 2 retry attempt(s) remain before the schema constraint
|
|
56
|
+
// is dropped.
|
|
57
|
+
//
|
|
58
|
+
// then `1 retry attempt(s) remain`, then `this is the final retry`, and the
|
|
59
|
+
// fourth submission was taken: `Result submitted (schema validation
|
|
60
|
+
// overridden after 4 failed attempt(s)).` What the caller then saw depended
|
|
61
|
+
// on the mode:
|
|
62
|
+
//
|
|
63
|
+
// strict job status `failed`; the handle's wait() rejected with
|
|
64
|
+
// `schema_violation: missing required fields: x`; its output
|
|
65
|
+
// text was {"error":"schema_violation","message":"x: is
|
|
66
|
+
// required","missingRequired":["x"],"data":"{}"}
|
|
67
|
+
// permissive job status `completed`; the invalid `{}` came back as the
|
|
68
|
+
// result
|
|
69
|
+
//
|
|
70
|
+
// A child that corrected itself after the first notice, in strict mode,
|
|
71
|
+
// resolved with its corrected data. Not measured: a `task` dispatch that
|
|
72
|
+
// carries both fields, which this session's tool cannot express. So a caller
|
|
73
|
+
// reading a report validates the file itself, whatever the dispatch's
|
|
74
|
+
// schema mode.
|
|
75
|
+
|
|
76
|
+
import { readFileSync } from "node:fs";
|
|
77
|
+
import { makeDie, defineFlags, writeAll } from "./arg.mjs";
|
|
78
|
+
import { isCLI } from "./is-cli.mjs";
|
|
79
|
+
import { HALT_CAUSES } from "./ledger-grammar.mjs";
|
|
80
|
+
|
|
81
|
+
const NAME = "report-schema";
|
|
82
|
+
const die = makeDie(NAME);
|
|
83
|
+
|
|
84
|
+
const USAGE = "usage: report-schema.mjs print <family> | validate <family> <file>";
|
|
85
|
+
|
|
86
|
+
const HEX = "^[0-9a-f]{40}$";
|
|
87
|
+
const str = { type: "string" };
|
|
88
|
+
const int = { type: "integer" };
|
|
89
|
+
const sha = { type: "string", pattern: HEX };
|
|
90
|
+
const strings = { type: "array", items: str };
|
|
91
|
+
|
|
92
|
+
// An object node whose every named property is required.
|
|
93
|
+
const obj = (properties, type = "object") => ({ type, required: Object.keys(properties), properties });
|
|
94
|
+
const listOf = (properties) => ({ type: "array", items: obj(properties) });
|
|
95
|
+
|
|
96
|
+
// A family's top level: every field required, nothing else allowed.
|
|
97
|
+
const report = (properties) => ({ ...obj(properties), additionalProperties: false });
|
|
98
|
+
|
|
99
|
+
const issues = listOf({ issue: int, subject: str });
|
|
100
|
+
|
|
101
|
+
export const SCHEMAS = {
|
|
102
|
+
impl: report({
|
|
103
|
+
member: str,
|
|
104
|
+
outcome: { type: "string", enum: ["pr", "bailed"] },
|
|
105
|
+
pr: { type: ["integer", "null"] },
|
|
106
|
+
head: { type: ["string", "null"], pattern: HEX },
|
|
107
|
+
branch: str,
|
|
108
|
+
sizing: obj(
|
|
109
|
+
{ verdict: { type: "string", enum: ["light", "heavy"] }, signal: str, ranBeforePr: { type: "boolean" } },
|
|
110
|
+
["object", "null"],
|
|
111
|
+
),
|
|
112
|
+
bailCause: { type: ["string", "null"], enum: ["undecided", "fork", "hands", null] },
|
|
113
|
+
bailDetail: { type: ["string", "null"] },
|
|
114
|
+
confirmation: strings,
|
|
115
|
+
}),
|
|
116
|
+
"fix-pr": report({
|
|
117
|
+
member: str,
|
|
118
|
+
outcome: { type: "string", enum: ["applied", "no-op", "failed"] },
|
|
119
|
+
head: sha,
|
|
120
|
+
branch: str,
|
|
121
|
+
applied: listOf({ bucket: str, index: int }),
|
|
122
|
+
deferred: listOf({ bucket: str, index: int, issue: int }),
|
|
123
|
+
filed: issues,
|
|
124
|
+
unrecorded: issues,
|
|
125
|
+
dispositionsRecord: { type: "string", pattern: "^/" },
|
|
126
|
+
testRun: obj({ cmd: str, exit: int, tests: int, cancelled: int }),
|
|
127
|
+
confirmation: strings,
|
|
128
|
+
}),
|
|
129
|
+
finisher: report({
|
|
130
|
+
member: str,
|
|
131
|
+
outcome: { type: "string", enum: ["labelled", "halted", "failed"] },
|
|
132
|
+
// The ledger's own `halted:<cause>` vocabulary, so a cause added there is accepted here.
|
|
133
|
+
cause: { type: ["string", "null"], enum: [...HALT_CAUSES, null] },
|
|
134
|
+
evidence: { type: ["string", "null"] },
|
|
135
|
+
pin: sha,
|
|
136
|
+
labelsReadBack: strings,
|
|
137
|
+
kill: obj({ red: str, baseline: str }, ["object", "null"]),
|
|
138
|
+
filed: issues,
|
|
139
|
+
unrecorded: issues,
|
|
140
|
+
confirmation: strings,
|
|
141
|
+
}),
|
|
142
|
+
"merge-bot": report({
|
|
143
|
+
member: str,
|
|
144
|
+
merged: listOf({ pr: int, sha }),
|
|
145
|
+
held: listOf({ pr: int, behind: int }),
|
|
146
|
+
conflictHold: { type: "array", items: int },
|
|
147
|
+
refused: listOf({ pr: int, reason: str }),
|
|
148
|
+
branchKept: listOf({ pr: int, by: int }),
|
|
149
|
+
}),
|
|
150
|
+
};
|
|
151
|
+
|
|
152
|
+
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
153
|
+
|
|
154
|
+
function typeOf(v) {
|
|
155
|
+
if (v === null) return "null";
|
|
156
|
+
if (Array.isArray(v)) return "array";
|
|
157
|
+
if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number";
|
|
158
|
+
return typeof v;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
const show = (v) => JSON.stringify(v);
|
|
162
|
+
|
|
163
|
+
// The first violation of `schema` by `value`, as `<path>: <what>`, or null.
|
|
164
|
+
export function validate(schema, value, path = "$") {
|
|
165
|
+
if (schema.type !== undefined) {
|
|
166
|
+
const types = [].concat(schema.type);
|
|
167
|
+
if (!types.includes(typeOf(value))) return `${path}: expected ${types.join(" or ")}, got ${typeOf(value)}`;
|
|
168
|
+
}
|
|
169
|
+
if (schema.enum !== undefined && !schema.enum.includes(value)) {
|
|
170
|
+
return `${path}: ${show(value)} is not one of ${schema.enum.map(show).join(", ")}`;
|
|
171
|
+
}
|
|
172
|
+
if (typeof value === "string" && schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
|
|
173
|
+
return `${path}: ${show(value)} does not match ${schema.pattern}`;
|
|
174
|
+
}
|
|
175
|
+
if (isObject(value)) {
|
|
176
|
+
for (const key of schema.required ?? []) {
|
|
177
|
+
if (!Object.hasOwn(value, key)) return `${path}: missing required field ${show(key)}`;
|
|
178
|
+
}
|
|
179
|
+
const props = schema.properties ?? {};
|
|
180
|
+
if (schema.additionalProperties === false) {
|
|
181
|
+
const extra = Object.keys(value).find((key) => !Object.hasOwn(props, key));
|
|
182
|
+
if (extra !== undefined) return `${path}: unexpected field ${show(extra)}`;
|
|
183
|
+
}
|
|
184
|
+
for (const [key, sub] of Object.entries(props)) {
|
|
185
|
+
if (!Object.hasOwn(value, key)) continue;
|
|
186
|
+
const found = validate(sub, value[key], `${path}.${key}`);
|
|
187
|
+
if (found !== null) return found;
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
if (Array.isArray(value) && schema.items !== undefined) {
|
|
191
|
+
for (let i = 0; i < value.length; i++) {
|
|
192
|
+
const found = validate(schema.items, value[i], `${path}[${i}]`);
|
|
193
|
+
if (found !== null) return found;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
return null;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
function familyOf(name) {
|
|
200
|
+
if (!Object.hasOwn(SCHEMAS, name)) die(`unknown family '${name}' — known: ${Object.keys(SCHEMAS).join(", ")}`);
|
|
201
|
+
return SCHEMAS[name];
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
function main() {
|
|
205
|
+
// No flags at all: the sweep refuses every `--` token by name. The
|
|
206
|
+
// positionals are read by count below, not by stray(), whose grammar holds
|
|
207
|
+
// one positional slot and this command line has up to three.
|
|
208
|
+
defineFlags(die, { flags: {} }).sweep();
|
|
209
|
+
const [cmd, family, path, ...rest] = process.argv.slice(2);
|
|
210
|
+
if (rest.length > 0 || family === undefined) die(USAGE);
|
|
211
|
+
|
|
212
|
+
if (cmd === "print" && path === undefined) {
|
|
213
|
+
if (!writeAll(1, `${JSON.stringify(familyOf(family), null, 2)}\n`)) die("the schema could not be written to stdout");
|
|
214
|
+
return;
|
|
215
|
+
}
|
|
216
|
+
if (cmd !== "validate" || path === undefined) die(USAGE);
|
|
217
|
+
|
|
218
|
+
const schema = familyOf(family);
|
|
219
|
+
let text;
|
|
220
|
+
try {
|
|
221
|
+
text = readFileSync(path, "utf8");
|
|
222
|
+
} catch (e) {
|
|
223
|
+
die(`cannot read ${path}: ${e.code ?? e.message}`);
|
|
224
|
+
}
|
|
225
|
+
let value;
|
|
226
|
+
try {
|
|
227
|
+
value = JSON.parse(text);
|
|
228
|
+
} catch (e) {
|
|
229
|
+
writeAll(1, `invalid: $: not JSON (${e.message})\n`);
|
|
230
|
+
process.exit(1);
|
|
231
|
+
}
|
|
232
|
+
const violation = validate(schema, value);
|
|
233
|
+
if (violation !== null) {
|
|
234
|
+
writeAll(1, `invalid: ${violation}\n`);
|
|
235
|
+
process.exit(1);
|
|
236
|
+
}
|
|
237
|
+
writeAll(1, "valid\n");
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
if (isCLI(import.meta.url)) main();
|