@feigi/fleet-ctl 3.109.1 → 3.110.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.109.1",
3
+ "version": "3.110.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -56,7 +56,19 @@
56
56
  // whose model changed is judged afresh once its new generation reaches MIN_N
57
57
  // merged PRs. Each older generation prints on its own line beside the newest,
58
58
  // with no verdict and no interval.
59
+ //
60
+ // THE GUARD FILE keeps each cell's whole entry as the report computed it —
61
+ // `n` (its `n_merged`, which readers key on) beside every figure above and its
62
+ // older generations nested under `older`, never as extra `cells[]` entries,
63
+ // since a reader keys entries by cell — and, per generation, three counts
64
+ // that never enter its figures: `by_hand`, the counted merged Pulls whose
65
+ // Ruling's note is not one `tier-outcomes.mjs append` derives (`isDerivedNote`);
66
+ // `no_ruling`, the Pulls whose PR merged on GitHub with no Ruling, which stay
67
+ // not merged; and `pending`, the Pulls whose PR is still open or not in the
68
+ // list. Beside `min_n` it records `trip_points`, the floor's margin, and
69
+ // `tsv_blobs`: the git blob id of each TSV it read, by the path it read it at.
59
70
 
71
+ import { createHash } from "node:crypto";
60
72
  import { execFileSync } from "node:child_process";
61
73
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
62
74
  import { dirname, join } from "node:path";
@@ -66,7 +78,7 @@ import { gitEnv } from "./git-env.mjs";
66
78
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
67
79
  import { isCLI } from "./is-cli.mjs";
68
80
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
69
- import { AttributionError, attribute, bootUnit, bootstrapDiffCI, parseFeatures, tally, underFloor } from "./pull-attribution.mjs";
81
+ import { AttributionError, TRIP_POINTS, attribute, bootUnit, bootstrapDiffCI, parseFeatures, tally, underFloor } from "./pull-attribution.mjs";
70
82
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
71
83
 
72
84
  const NAME = "pr-cost";
@@ -117,6 +129,9 @@ export function computeReport({ members, tiers, features, prs, routerTable = nul
117
129
  fail_rate: g.claims ? round(g.failed / g.claims) : null,
118
130
  mean_usd: round(meanUsd(g), 2),
119
131
  median_usd: round(median(g.pulls.filter((u) => u.merged).map((u) => u.spend)), 2),
132
+ by_hand: g.by_hand,
133
+ no_ruling: g.no_ruling,
134
+ pending: g.pending,
120
135
  router_usd: round(g.pulls.reduce((s, u) => s + routerUsd(u.pull), 0), 4),
121
136
  usd_diff_ci95: !newest || cell === BASELINE_CELL || !base ? null : bootstrapDiffCI(bootUnits(g), bootUnits(base)),
122
137
  left_out: g.left_out,
@@ -245,18 +260,27 @@ export function formatReport(report) {
245
260
  return lines.join("\n") + "\n";
246
261
  }
247
262
 
248
- export function guardFile(report, computedAt) {
263
+ // The git blob id of `bytes` — what `git hash-object` prints for a file of them.
264
+ export const blobId = (bytes) => createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
265
+
266
+ // `tsvBlobs` is the blob id of each TSV the guard read, keyed by path.
267
+ export function guardFile(report, computedAt, tsvBlobs = {}) {
249
268
  return {
250
269
  computed_at: computedAt,
251
270
  window_start: report.window_start,
252
271
  baseline: report.baseline,
253
- cells: report.cells.map((f) => ({ cell: f.cell, generation: f.generation, n: f.n_merged, mean_usd: f.mean_usd, fail_rate: f.fail_rate, untimed: f.untimed })),
272
+ cells: report.cells.map((f) => {
273
+ const { cell, generation, ...rest } = f;
274
+ return { cell, generation, n: f.n_merged, ...rest };
275
+ }),
254
276
  tripped: report.tripped,
255
277
  verdict: report.verdict,
256
278
  retire: report.retire,
257
- // The n the baseline and every judged cell need, so a reader prints it
258
- // rather than restating it.
279
+ // The n the baseline and every judged cell need, and the margin the fail
280
+ // leg applies, so a reader prints them rather than restating them.
259
281
  min_n: MIN_N,
282
+ trip_points: TRIP_POINTS,
283
+ tsv_blobs: Object.fromEntries(Object.entries(tsvBlobs).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
260
284
  };
261
285
  }
262
286
 
@@ -288,8 +312,14 @@ function main() {
288
312
  });
289
313
  sweep();
290
314
  stray();
291
- const read = (path, ifMissing = "") => {
292
- try { return readFileSync(path, "utf8"); }
315
+ const tsvBlobs = {};
316
+ // `blobbed` records the file's git blob id, off the bytes as read.
317
+ const read = (path, ifMissing = "", blobbed = false) => {
318
+ try {
319
+ const bytes = readFileSync(path);
320
+ if (blobbed) tsvBlobs[path] = blobId(bytes);
321
+ return bytes.toString("utf8");
322
+ }
293
323
  catch (e) { die(`cannot read ${path}: ${e.code ?? e.message}${e.code === "ENOENT" ? ifMissing : ""}`); }
294
324
  };
295
325
  const parse = (what, fn) => {
@@ -301,9 +331,9 @@ function main() {
301
331
  const featuresPath = arg("ticket-features") ?? "docs/metrics/ticket-features.tsv";
302
332
  const pricingArg = arg("pricing");
303
333
  const pricingPath = pricingArg ?? "docs/metrics/pricing.json";
304
- const members = parse(membersPath, () => parseMemberTsv(read(membersPath)));
305
- const tiers = parse(tiersPath, () => parseTierOutcomes(read(tiersPath)));
306
- const features = parse(featuresPath, () => parseFeatures(read(featuresPath, " — the router script writes it at dispatch, so there is nothing to price before it has dispatched")));
334
+ const members = parse(membersPath, () => parseMemberTsv(read(membersPath, "", true)));
335
+ const tiers = parse(tiersPath, () => parseTierOutcomes(read(tiersPath, "", true)));
336
+ const features = parse(featuresPath, () => parseFeatures(read(featuresPath, " — the router script writes it at dispatch, so there is nothing to price before it has dispatched", true)));
307
337
  // The default pricing.json is optional; one named on the command line is not.
308
338
  const pricing = pricingArg === null && !existsSync(pricingPath) ? null : parse(pricingPath, () => JSON.parse(read(pricingPath)));
309
339
  const tablePath = join(SCRIPT_DIR, "router-table.json");
@@ -338,7 +368,7 @@ function main() {
338
368
  const file = arg("out") ?? defaultGuardPath();
339
369
  try {
340
370
  mkdirSync(dirname(file), { recursive: true });
341
- writeFileSync(`${file}.tmp`, JSON.stringify(guardFile(report, new Date().toISOString()), null, 2) + "\n");
371
+ writeFileSync(`${file}.tmp`, JSON.stringify(guardFile(report, new Date().toISOString(), tsvBlobs), null, 2) + "\n");
342
372
  renameSync(`${file}.tmp`, file);
343
373
  } catch (e) {
344
374
  die(`cannot write ${file}: ${e.code ?? e.message}`);
@@ -36,6 +36,9 @@
36
36
  // MERGED: the Pull holds a Ruling and, when PR states are given, its PR is
37
37
  // MERGED. With PR states, a ruled PR that is OPEN or not in the list, or an
38
38
  // unruled Pull whose implementer opened a PR still OPEN, is pending.
39
+ // A Pull with no Ruling whose implementer's PR is MERGED, and whose PR no
40
+ // other Pull holds the Ruling of, is `noRuling`: still not merged, its status
41
+ // unchanged — a count beside the figures, not a state.
39
42
  //
40
43
  // STATUS, first that applies:
41
44
  // excluded no Admissible row among the Pull's implementer rows;
@@ -84,7 +87,7 @@ import { isDigits } from "./arg.mjs";
84
87
  import { CELL } from "./ledger-grammar.mjs";
85
88
  import { parseMemberName } from "./member-record.mjs";
86
89
  import { isImplementer } from "./member-outcomes.mjs";
87
- import { DATE, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
90
+ import { DATE, isDerivedNote, rulingFor, rulingsByTicket } from "./tier-outcomes.mjs";
88
91
 
89
92
  // The ticket-features row, one per Pull, in this order. `objective` came last
90
93
  // and is optional on read: a file whose header lacks it reads it blank.
@@ -277,7 +280,7 @@ function numberOf(row, field, column = field) {
277
280
  /**
278
281
  * One unit per ticket-features row dated on or after `windowStart` (every dated
279
282
  * row when null), in file order: `{ pull, cell, stratum, generation, status,
280
- * merged, pr, ruling, pendingPr, claims, falseClaims, rows, spend, workS }`,
283
+ * merged, pr, ruling, pendingPr, noRuling, claims, falseClaims, rows, spend, workS }`,
281
284
  * `generation` null exactly when the Pull is excluded. `spend` is null when a
282
285
  * booked `cost` is blank, and `workS`, its work time in seconds, when a booked
283
286
  * `work_s` of a row naming no parent is. `prs` is `gh pr list`'s
@@ -342,6 +345,8 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
342
345
  const ruling = cands.reduce((a, c) => (fileOrder.get(c.ruling) > fileOrder.get(a) ? c.ruling : a), cands[0].ruling);
343
346
  ruled.set(cands.at(-1).pull, { pr, ruling, carried: false });
344
347
  }
348
+ // Every PR some Pull holds the Ruling of, carried or taken by date.
349
+ const held = new Set([...ruled.values()].map((r) => r.pr));
345
350
 
346
351
  const state = prs && new Map(prs.map((p) => [String(p.number), p.state]));
347
352
  return inWindow.map((pull) => {
@@ -350,12 +355,16 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
350
355
  const r = ruled.get(pull) ?? null;
351
356
  let merged = r !== null;
352
357
  let pendingPr = null;
358
+ let noRuling = false;
353
359
  if (state) {
354
360
  if (r) {
355
361
  const s = state.get(r.pr);
356
362
  if (s === undefined || s === "OPEN") pendingPr = r.pr;
357
363
  merged = s === "MERGED";
358
- } else pendingPr = own.find((m) => m.pr && state.get(m.pr) === "OPEN")?.pr ?? null;
364
+ } else {
365
+ pendingPr = own.find((m) => m.pr && state.get(m.pr) === "OPEN")?.pr ?? null;
366
+ noRuling = own.some((m) => m.pr && state.get(m.pr) === "MERGED" && !held.has(m.pr));
367
+ }
359
368
  }
360
369
  let claims = 0, falseClaims = 0;
361
370
  if (merged) {
@@ -384,7 +393,7 @@ export function attribute({ features, members, tiers, prs = null, windowStart =
384
393
  else if (blank || (r && !r.carried)) status = "unpriced";
385
394
  else if (untimed) status = "untimed";
386
395
  return {
387
- pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null,
396
+ pull, cell: pull.chosen_cell, stratum: stratum(pull), generation, status, merged, pr: r?.pr ?? null, ruling: r?.ruling ?? null, noRuling,
388
397
  pendingPr, claims, falseClaims, rows: booked, spend: blank ? null : spend, workS: untimed ? null : workS,
389
398
  };
390
399
  });
@@ -410,13 +419,16 @@ export function generations(units) {
410
419
 
411
420
  /**
412
421
  * Per cell, in cell-name order: `{ cell, generation, n, merged, claims, failed,
413
- * spend, workS, pulls, excluded, left_out, unpriced, untimed, pending, older }`.
422
+ * spend, workS, pulls, excluded, left_out, unpriced, untimed, pending,
423
+ * by_hand, no_ruling, older }`.
414
424
  * `generation` is the cell's newest (null when no Pull of it has one), and the
415
425
  * figures beside it are that generation's alone: `n`, `merged`, `claims`,
416
426
  * `failed`, `spend` and `workS` (work time, in seconds) over its counted
417
427
  * Pulls, `pulls` those counted units themselves in the order of `units`, then
418
- * its left-out, unpriced, untimed and pending Pull counts.
419
- * `excluded` counts the cell's excluded Pulls, which have no generation.
428
+ * its left-out, unpriced, untimed and pending Pull counts. `by_hand` counts
429
+ * those counted merged Pulls whose Ruling's note is not one `append` derives
430
+ * (`isDerivedNote`); `no_ruling` counts the generation's Pulls of any status
431
+ * whose unit is `noRuling`.
420
432
  * `older` is an array, newest first, of every other generation's figures in
421
433
  * the same shape, each carrying its `generation`. `order` is `generations()`
422
434
  * of the units that place each cell's generations; by default these same
@@ -427,7 +439,7 @@ export function tally(units, order = generations(units)) {
427
439
  // `n` is read off `pulls`, so the count and the list cannot drift apart.
428
440
  const figures = (generation) => ({
429
441
  generation, get n() { return this.pulls.length; }, merged: 0, claims: 0, failed: 0, spend: 0, workS: 0, pulls: [],
430
- left_out: 0, unpriced: 0, untimed: 0, pending: 0,
442
+ left_out: 0, unpriced: 0, untimed: 0, pending: 0, by_hand: 0, no_ruling: 0,
431
443
  });
432
444
  const cells = new Map();
433
445
  for (const u of units) {
@@ -438,8 +450,12 @@ export function tally(units, order = generations(units)) {
438
450
  }
439
451
  const g = u.generation ?? null;
440
452
  const f = c.gens.get(g) ?? c.gens.set(g, figures(g)).get(g);
453
+ if (u.noRuling) f.no_ruling++;
441
454
  if (u.status === "counted") {
442
- if (u.merged) f.merged++;
455
+ if (u.merged) {
456
+ f.merged++;
457
+ if (u.ruling && !isDerivedNote(u.ruling.note)) f.by_hand++;
458
+ }
443
459
  f.claims += u.claims;
444
460
  f.failed += u.falseClaims;
445
461
  f.spend += u.spend;
@@ -308,7 +308,8 @@ function fitPulls({ features, members, verdicts, window }) {
308
308
 
309
309
  // Per stratum and `*`, per cell, its newest generation's figures: `n` counted
310
310
  // Pulls, `merged`, $ per merged PR, minutes of work time per merged PR, false
311
- // claims over claims, fix rounds per merged PR, and its left-out, unpriced and
311
+ // claims over claims, fix rounds per merged PR, `by_hand` (the counted merged Pulls whose
312
+ // Ruling was given by hand), and its left-out, unpriced and
312
313
  // untimed Pull counts. Both per merged PR figures take every counted Pull,
313
314
  // merged or not, over the merged ones. Beside them the cell's
314
315
  // excluded Pull count, `generation` naming the newest generation's model, and
@@ -329,6 +330,7 @@ function estimate(units, order) {
329
330
  return {
330
331
  n: g.n,
331
332
  merged: g.merged,
333
+ by_hand: g.by_hand,
332
334
  claims: g.claims,
333
335
  failed: g.failed,
334
336
  usd_per_merged: g.merged ? round4(g.spend / g.merged) : null,
@@ -747,6 +747,15 @@ export function deriveRuling({ run, head, review, record }) {
747
747
  };
748
748
  }
749
749
 
750
+ // Is `note` one `append` derives — deriveRuling's opening, `review <run> at
751
+ // <head7>`, then `, record <file>: …` or `, no record: …`, with ` — <--note>`
752
+ // after it when `--note` was given — rather than typed by hand with the
753
+ // verdicts? Pure: the note alone is read, never the verdicts. A blank or
754
+ // missing note is by hand.
755
+ export function isDerivedNote(note) {
756
+ return /^review \S+ at [0-9a-fA-F]{7}, (?:no record: |record \S+: )/.test(String(note ?? ""));
757
+ }
758
+
750
759
  // PR `pr`'s first review read from scratch and tied to the ledger, then ruled
751
760
  // by deriveRuling: its Ruling plus `review`, the review's run, or `{missing}`
752
761
  // saying what is not there to read. `scratch` is `{root}` or `{unresolvable}`.