@futurelastic/colab-handbook 1.13.0-rc.25 → 1.13.0-rc.27
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/audit/audit.mjs +40 -14
- package/package.json +1 -1
- package/templates/ci-laravel.yml +34 -0
- package/templates/ci-node.yml +34 -0
- package/templates/ci-python.yml +34 -0
- package/tools/colab +266 -11
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +4 -1
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/thresholds.js +98 -0
package/audit/audit.mjs
CHANGED
|
@@ -98,6 +98,8 @@ const installRoute = require("../tools/lib/install-route.js");
|
|
|
98
98
|
const releaseRunner = require("../tools/lib/release-runner.js"); // #453
|
|
99
99
|
const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
|
|
100
100
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
101
|
+
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
102
|
+
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
101
103
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
102
104
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
103
105
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -218,7 +220,7 @@ function parseScalarValue(raw) {
|
|
|
218
220
|
return val;
|
|
219
221
|
}
|
|
220
222
|
|
|
221
|
-
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate"]); // owner: #394 · gate: #410
|
|
223
|
+
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds"]); // owner: #394 · gate: #410 · thresholds: #560
|
|
222
224
|
|
|
223
225
|
function parseFlatYaml(text) {
|
|
224
226
|
const out = {};
|
|
@@ -1053,7 +1055,7 @@ function yamlRawValue(text, key) {
|
|
|
1053
1055
|
return m[1].replace(/\s+#.*$/, "").trim();
|
|
1054
1056
|
}
|
|
1055
1057
|
|
|
1056
|
-
const DURATION_MIN_DAYS =
|
|
1058
|
+
const DURATION_MIN_DAYS = thresholdsLib.DEFAULTS["transitional-days"]; // 180, the DEFAULT (#560: a repo may declare thresholds.transitional-days); below this, silence — see audit-exposure.test.js's pinned
|
|
1057
1059
|
// "transitional descriptor is clean" case, which this
|
|
1058
1060
|
// threshold exists to keep passing untouched: a descriptor
|
|
1059
1061
|
// committed moments ago must never earn a duration line.
|
|
@@ -1091,9 +1093,9 @@ function declaredStateAge(src, key) {
|
|
|
1091
1093
|
|
|
1092
1094
|
// Prose for a declaredStateAge() result, or null when it is too recent to be worth saying
|
|
1093
1095
|
// (the DURATION_MIN_DAYS gate — the caller must check this before calling warn()).
|
|
1094
|
-
function renderDuration(age) {
|
|
1096
|
+
function renderDuration(age, minDays = DURATION_MIN_DAYS) {
|
|
1095
1097
|
const days = Math.floor((Date.now() / 1000 - age.epoch) / DURATION_DAY_SECONDS);
|
|
1096
|
-
if (days <
|
|
1098
|
+
if (days < minDays) return null;
|
|
1097
1099
|
const months = Math.floor(days / 30); // coarse on purpose — a report, not a countdown
|
|
1098
1100
|
return `${age.lowerBound ? "at least " : ""}${months} month${months === 1 ? "" : "s"}`;
|
|
1099
1101
|
}
|
|
@@ -1122,12 +1124,15 @@ function auditRepo(target, ctx) {
|
|
|
1122
1124
|
// ---- .github/project.yml -------------------------------------------------
|
|
1123
1125
|
const rawCfg = src.readFile(".github/project.yml");
|
|
1124
1126
|
let cfg = null;
|
|
1127
|
+
// #560: the advisory thresholds this run applies — defaults until the descriptor declares otherwise.
|
|
1128
|
+
let th = thresholdsLib.parseThresholds(null);
|
|
1125
1129
|
if (rawCfg === null) {
|
|
1126
1130
|
fail("no .github/project.yml — repo is undescribed (tier/trunk/deploy unknown)");
|
|
1127
1131
|
} else {
|
|
1128
1132
|
const { data, problems } = parseFlatYaml(rawCfg);
|
|
1129
1133
|
problems.forEach((p) => fail(`project.yml: ${p}`));
|
|
1130
1134
|
cfg = data;
|
|
1135
|
+
th = thresholdsLib.parseThresholds(cfg);
|
|
1131
1136
|
// `tier` is deliberately NOT in this list as of #144: it used to be the sole axis of
|
|
1132
1137
|
// record and therefore unconditionally required, but a descriptor may now answer the
|
|
1133
1138
|
// gate-count question with `exposure` instead — see the "axis of record" check below,
|
|
@@ -1315,6 +1320,22 @@ function auditRepo(target, ctx) {
|
|
|
1315
1320
|
else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
|
|
1316
1321
|
}
|
|
1317
1322
|
|
|
1323
|
+
// ---- ci-wait-factor (#559) ----------------------------------------------------
|
|
1324
|
+
// The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
|
|
1325
|
+
// (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
|
|
1326
|
+
// value fails here; the tools fall back to the documented default (2) and say so — never to a
|
|
1327
|
+
// different behaviour. No ceiling: how patient a repo is, is the repo's choice.
|
|
1328
|
+
if (ciProfile.FACTOR_KEY in (cfg || {}) && cfg[ciProfile.FACTOR_KEY] !== null) {
|
|
1329
|
+
const f = ciProfile.parseFactor(cfg);
|
|
1330
|
+
if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
|
|
1331
|
+
}
|
|
1332
|
+
|
|
1333
|
+
// ---- thresholds (#560) --------------------------------------------------------
|
|
1334
|
+
// Repo-declared values for the advisory thresholds (tools/lib/thresholds.js, the one reading
|
|
1335
|
+
// `colab thresholds` and every consumer use). A malformed entry fails here and in the CI
|
|
1336
|
+
// templates' descriptor check (the #416 pattern); every consumer falls back to the default.
|
|
1337
|
+
thresholdsLib.parseThresholds(cfg).problems.forEach((p) => fail(`${p} — see project.schema.md, thresholds`));
|
|
1338
|
+
|
|
1318
1339
|
// ---- migrations (#383) ----------------------------------------------------
|
|
1319
1340
|
// Where the repo's migrations live, beyond the two defaults (database/migrations/,
|
|
1320
1341
|
// prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
|
|
@@ -1467,7 +1488,7 @@ function auditRepo(target, ctx) {
|
|
|
1467
1488
|
);
|
|
1468
1489
|
}
|
|
1469
1490
|
const exposureAge = declaredStateAge(src, "exposure");
|
|
1470
|
-
const durationLine = exposureAge && renderDuration(exposureAge);
|
|
1491
|
+
const durationLine = exposureAge && renderDuration(exposureAge, th.values["transitional-days"]);
|
|
1471
1492
|
if (durationLine) {
|
|
1472
1493
|
warn(`exposure: none has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
|
|
1473
1494
|
}
|
|
@@ -1557,7 +1578,7 @@ function auditRepo(target, ctx) {
|
|
|
1557
1578
|
);
|
|
1558
1579
|
}
|
|
1559
1580
|
const channelsAge = declaredStateAge(src, "channels");
|
|
1560
|
-
const durationLine = channelsAge && renderDuration(channelsAge);
|
|
1581
|
+
const durationLine = channelsAge && renderDuration(channelsAge, th.values["transitional-days"]);
|
|
1561
1582
|
if (durationLine) {
|
|
1562
1583
|
warn(`channels: [none] has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
|
|
1563
1584
|
}
|
|
@@ -1702,7 +1723,7 @@ function auditRepo(target, ctx) {
|
|
|
1702
1723
|
// ---- CLAUDE.md is a router, not an archive (#64) -------------------------
|
|
1703
1724
|
// Unconditional: this is a repo-doc concern, not a tier/deploy one, and it applies to
|
|
1704
1725
|
// the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
|
|
1705
|
-
checkClaudeMdSize(src, warn);
|
|
1726
|
+
checkClaudeMdSize(src, warn, th.values);
|
|
1706
1727
|
// #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
|
|
1707
1728
|
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
|
|
1708
1729
|
checkInstructionFileBlocks(src, warn);
|
|
@@ -2204,9 +2225,10 @@ function checkReleaseBranch(cfg, trunk, branches, fail, warn, deploy) {
|
|
|
2204
2225
|
// a starting point rather than a recommendation", wanting calibration across adopting repos
|
|
2205
2226
|
// before anything here becomes a hard gate — the goal is a finding with the measured number
|
|
2206
2227
|
// ("state the condition"), not a build-breaking assertion of a still-uncalibrated one.
|
|
2207
|
-
const CLAUDE_MD_MAX_BYTES =
|
|
2208
|
-
|
|
2209
|
-
|
|
2228
|
+
const CLAUDE_MD_MAX_BYTES = thresholdsLib.DEFAULTS["claude-md-kb"] * 1024; // 40 KB by default (#560) — near the handbook's own cited worst case (39 KB / 452 lines)
|
|
2229
|
+
// The per-line multiple ("some small multiple of the [file's] median row", default 6) and its
|
|
2230
|
+
// absolute floor (default 2048 bytes — below it, flagging on the multiple alone is noise: tiny
|
|
2231
|
+
// medians make everything look huge) live in tools/lib/thresholds.js with the ceiling (#560).
|
|
2210
2232
|
|
|
2211
2233
|
// #117: the byte ceiling above was built to catch hand-written accretion, but it counts
|
|
2212
2234
|
// TOTAL file bytes — which also charges a repo for content it cannot shorten by the rule's
|
|
@@ -2439,7 +2461,11 @@ function checkAnchorLinks(src, fail) {
|
|
|
2439
2461
|
}
|
|
2440
2462
|
}
|
|
2441
2463
|
|
|
2442
|
-
function checkClaudeMdSize(src, warn) {
|
|
2464
|
+
function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
|
|
2465
|
+
// #560: the three numbers below are the defaults; a repo may declare its own under `thresholds:`.
|
|
2466
|
+
const maxBytes = limits["claude-md-kb"] * 1024;
|
|
2467
|
+
const lineMultiple = limits["claude-md-line-multiple"];
|
|
2468
|
+
const lineFloor = limits["claude-md-line-floor-bytes"];
|
|
2443
2469
|
// #417: measure what is LOADED, not one file. A thin-shell CLAUDE.md (`@AGENTS.md` plus the
|
|
2444
2470
|
// by-name tool blocks) is tiny by construction, so measuring it alone would neuter this guard
|
|
2445
2471
|
// while a bloated AGENTS.md rides in behind it on every turn. The loaded set is CLAUDE.md plus
|
|
@@ -2462,7 +2488,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2462
2488
|
}
|
|
2463
2489
|
const derivedBytes = Math.max(0, bytes - authoredBytes);
|
|
2464
2490
|
|
|
2465
|
-
if (authoredBytes >
|
|
2491
|
+
if (authoredBytes > maxBytes) {
|
|
2466
2492
|
const totalNote = derivedBytes > 0
|
|
2467
2493
|
? ` (of ${bytes} bytes total; ${derivedBytes} bytes are marked colab:derived and excluded — #117)`
|
|
2468
2494
|
: "";
|
|
@@ -2471,7 +2497,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2471
2497
|
: `CLAUDE.md plus its @-imports (${files.slice(1).map((f) => f.path).join(", ")}) is`;
|
|
2472
2498
|
warn(
|
|
2473
2499
|
`${subject} ${authoredBytes} bytes (~${(authoredBytes / 1024).toFixed(1)} KB)${totalNote} — over the ` +
|
|
2474
|
-
`${
|
|
2500
|
+
`${maxBytes / 1024} KB advisory ceiling (#64${maxBytes === CLAUDE_MD_MAX_BYTES ? "" : ", declared in thresholds.claude-md-kb"}). It is loaded in full into every session before ` +
|
|
2475
2501
|
`any work starts; if the knowledge belongs in docs/, the ${files.length === 1 ? "CLAUDE.md" : "instruction-file"} change is a pointer, not a copy (code-wrap A2)`,
|
|
2476
2502
|
);
|
|
2477
2503
|
}
|
|
@@ -2486,7 +2512,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2486
2512
|
if (lens.length < 2) continue; // no meaningful median from 0 or 1 lines
|
|
2487
2513
|
const median = lens[Math.floor(lens.length / 2)];
|
|
2488
2514
|
const worst = lens[lens.length - 1];
|
|
2489
|
-
if (median > 0 && worst >
|
|
2515
|
+
if (median > 0 && worst > lineFloor && worst > median * lineMultiple) {
|
|
2490
2516
|
const pct = ((worst / f.authoredBytes) * 100).toFixed(1);
|
|
2491
2517
|
warn(
|
|
2492
2518
|
`${f.path} has a single line of ${worst} bytes — ${(worst / median).toFixed(1)}x the file's median line ` +
|
package/package.json
CHANGED
package/templates/ci-laravel.yml
CHANGED
|
@@ -296,6 +296,40 @@ jobs:
|
|
|
296
296
|
exit 1
|
|
297
297
|
fi ;;
|
|
298
298
|
esac
|
|
299
|
+
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
300
|
+
# floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
|
|
301
|
+
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
302
|
+
bad=0
|
|
303
|
+
while IFS= read -r t; do
|
|
304
|
+
case "$t" in =*)
|
|
305
|
+
echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
|
|
306
|
+
bad=1; continue ;;
|
|
307
|
+
esac
|
|
308
|
+
k="${t%%:*}"
|
|
309
|
+
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
310
|
+
case "$k" in
|
|
311
|
+
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
312
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
313
|
+
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
314
|
+
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
315
|
+
bad=1; continue ;;
|
|
316
|
+
esac
|
|
317
|
+
case "$n" in ''|'~'|null) continue ;; esac
|
|
318
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
319
|
+
echo "thresholds.$k: $n — ok"
|
|
320
|
+
else
|
|
321
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
|
|
322
|
+
bad=1
|
|
323
|
+
fi
|
|
324
|
+
done < <(awk '
|
|
325
|
+
/^thresholds[[:space:]]*:/ { b = 1; v = $0
|
|
326
|
+
sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
|
|
327
|
+
if (v != "" && v != "~" && v != "null") print "=" v
|
|
328
|
+
next }
|
|
329
|
+
b && /^[[:space:]]*(#|$)/ { next }
|
|
330
|
+
b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
|
|
331
|
+
{ b = 0 }' .github/project.yml)
|
|
332
|
+
[ "$bad" = 0 ] || exit 1
|
|
299
333
|
|
|
300
334
|
# ---------------------------------------------------------------------------
|
|
301
335
|
# Toolchain resolution. Precedence, highest first:
|
package/templates/ci-node.yml
CHANGED
|
@@ -291,6 +291,40 @@ jobs:
|
|
|
291
291
|
exit 1
|
|
292
292
|
fi ;;
|
|
293
293
|
esac
|
|
294
|
+
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
295
|
+
# floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
|
|
296
|
+
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
297
|
+
bad=0
|
|
298
|
+
while IFS= read -r t; do
|
|
299
|
+
case "$t" in =*)
|
|
300
|
+
echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
|
|
301
|
+
bad=1; continue ;;
|
|
302
|
+
esac
|
|
303
|
+
k="${t%%:*}"
|
|
304
|
+
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
305
|
+
case "$k" in
|
|
306
|
+
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
307
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
308
|
+
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
309
|
+
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
310
|
+
bad=1; continue ;;
|
|
311
|
+
esac
|
|
312
|
+
case "$n" in ''|'~'|null) continue ;; esac
|
|
313
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
314
|
+
echo "thresholds.$k: $n — ok"
|
|
315
|
+
else
|
|
316
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
|
|
317
|
+
bad=1
|
|
318
|
+
fi
|
|
319
|
+
done < <(awk '
|
|
320
|
+
/^thresholds[[:space:]]*:/ { b = 1; v = $0
|
|
321
|
+
sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
|
|
322
|
+
if (v != "" && v != "~" && v != "null") print "=" v
|
|
323
|
+
next }
|
|
324
|
+
b && /^[[:space:]]*(#|$)/ { next }
|
|
325
|
+
b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
|
|
326
|
+
{ b = 0 }' .github/project.yml)
|
|
327
|
+
[ "$bad" = 0 ] || exit 1
|
|
294
328
|
|
|
295
329
|
# ---------------------------------------------------------------------------
|
|
296
330
|
# Toolchain resolution. Precedence, highest first:
|
package/templates/ci-python.yml
CHANGED
|
@@ -282,6 +282,40 @@ jobs:
|
|
|
282
282
|
exit 1
|
|
283
283
|
fi ;;
|
|
284
284
|
esac
|
|
285
|
+
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
286
|
+
# floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
|
|
287
|
+
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
288
|
+
bad=0
|
|
289
|
+
while IFS= read -r t; do
|
|
290
|
+
case "$t" in =*)
|
|
291
|
+
echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
|
|
292
|
+
bad=1; continue ;;
|
|
293
|
+
esac
|
|
294
|
+
k="${t%%:*}"
|
|
295
|
+
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
296
|
+
case "$k" in
|
|
297
|
+
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
298
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
299
|
+
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
300
|
+
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
301
|
+
bad=1; continue ;;
|
|
302
|
+
esac
|
|
303
|
+
case "$n" in ''|'~'|null) continue ;; esac
|
|
304
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
305
|
+
echo "thresholds.$k: $n — ok"
|
|
306
|
+
else
|
|
307
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
|
|
308
|
+
bad=1
|
|
309
|
+
fi
|
|
310
|
+
done < <(awk '
|
|
311
|
+
/^thresholds[[:space:]]*:/ { b = 1; v = $0
|
|
312
|
+
sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
|
|
313
|
+
if (v != "" && v != "~" && v != "null") print "=" v
|
|
314
|
+
next }
|
|
315
|
+
b && /^[[:space:]]*(#|$)/ { next }
|
|
316
|
+
b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
|
|
317
|
+
{ b = 0 }' .github/project.yml)
|
|
318
|
+
[ "$bad" = 0 ] || exit 1
|
|
285
319
|
|
|
286
320
|
# ---------------------------------------------------------------------------
|
|
287
321
|
# Toolchain resolution. Precedence, highest first:
|
package/tools/colab
CHANGED
|
@@ -49,6 +49,8 @@ const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
|
49
49
|
const treeGreen = require('./lib/tree-green');
|
|
50
50
|
const verifyRuns = require('./lib/verify-runs');
|
|
51
51
|
const ciWait = require('./lib/ci-wait'); // #495
|
|
52
|
+
const ciProfile = require('./lib/ci-profile'); // #559
|
|
53
|
+
const thresholdsLib = require('./lib/thresholds'); // #560
|
|
52
54
|
const staleBase = require('./lib/stale-base');
|
|
53
55
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
54
56
|
const scratchDirs = require('./lib/scratch-dirs');
|
|
@@ -10885,10 +10887,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10885
10887
|
// (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
|
|
10886
10888
|
// never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
|
|
10887
10889
|
if (run.status === 'none' && target === trunk) {
|
|
10888
|
-
|
|
10890
|
+
// #559: the grace is the repo's measured push→run lag when there is one — read from cache, never fetched here.
|
|
10891
|
+
const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
|
|
10889
10892
|
if (fresh.fresh) {
|
|
10890
10893
|
verdict = { ok: false, class: SELF_CLEARING,
|
|
10891
|
-
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${
|
|
10894
|
+
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${Math.round(fresh.graceMinutes * 10) / 10}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
|
|
10892
10895
|
}
|
|
10893
10896
|
}
|
|
10894
10897
|
// #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
|
|
@@ -11001,7 +11004,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
|
|
|
11001
11004
|
// Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
|
|
11002
11005
|
// shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
|
|
11003
11006
|
const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
|
|
11004
|
-
|
|
11007
|
+
// #559: wedge age and zero-jobs floor follow the repo's measured CI (cached profile; bootstrap = 6h / 2m).
|
|
11008
|
+
const th = ciProfileFor(repoAbs).th;
|
|
11009
|
+
const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount }, { wedgeAgeSec: th.wedgeAgeSec, zeroJobsFloorSec: th.zeroJobsFloorSec });
|
|
11005
11010
|
if (wedge.wedged) {
|
|
11006
11011
|
return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
|
|
11007
11012
|
}
|
|
@@ -14491,6 +14496,110 @@ function trunkCiCache(repoAbs) {
|
|
|
14491
14496
|
};
|
|
14492
14497
|
}
|
|
14493
14498
|
|
|
14499
|
+
// ---- ci-profile (#559) ------------------------------------------------------------------------
|
|
14500
|
+
// Every CI wait bound derives from the repo's own measured CI duration (tools/lib/ci-profile.js).
|
|
14501
|
+
// The profile is cached per checkout in `<git common dir>/colab-ci-profile.json` for a day; the
|
|
14502
|
+
// thresholds are NOT cached — they are recomputed from the cached profile and the CURRENT
|
|
14503
|
+
// `ci-wait-factor`, so editing the factor applies at once with no refetch.
|
|
14504
|
+
const CI_PROFILE_TTL_DEFAULT_SEC = 24 * 3600;
|
|
14505
|
+
const CI_PROFILE_CACHE_V = 1;
|
|
14506
|
+
|
|
14507
|
+
function ciProfileTtlSec() {
|
|
14508
|
+
const env = process.env.COLAB_CI_PROFILE_TTL;
|
|
14509
|
+
return env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : CI_PROFILE_TTL_DEFAULT_SEC;
|
|
14510
|
+
}
|
|
14511
|
+
|
|
14512
|
+
function ciProfileCacheFile(repoAbs) {
|
|
14513
|
+
const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
|
|
14514
|
+
return dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-ci-profile.json') : null;
|
|
14515
|
+
}
|
|
14516
|
+
|
|
14517
|
+
/**
|
|
14518
|
+
* The repo's completed CI runs in the profile window — up to 3 pages of the whole list plus one page
|
|
14519
|
+
* of trunk pushes, so a branch-heavy repo still yields trunk samples. Returns `{ rows, runsRead }`,
|
|
14520
|
+
* or `{ error }` when the list cannot be read (the caller falls back, never fails a wait on it).
|
|
14521
|
+
*/
|
|
14522
|
+
function fetchCiProfileRows(repoAbs, trunk, sinceIso) {
|
|
14523
|
+
const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .name, .status, .conclusion, .run_attempt, .created_at, .updated_at, .head_commit.timestamp] | @json';
|
|
14524
|
+
const day = sinceIso.slice(0, 10);
|
|
14525
|
+
const paths = [1, 2, 3].map((n) => `repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&page=${n}`);
|
|
14526
|
+
paths.push(`repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&branch=${encodeURIComponent(trunk)}&event=push`);
|
|
14527
|
+
const seen = new Map();
|
|
14528
|
+
for (let i = 0; i < paths.length; i++) {
|
|
14529
|
+
const r = git.ghApi(repoAbs, [paths[i], '--jq', jq]);
|
|
14530
|
+
if (!r.ok) return { error: git.gitFailureLine(r.stderr) || 'gh api failed' };
|
|
14531
|
+
let n = 0;
|
|
14532
|
+
for (const line of String(r.stdout || '').split('\n')) {
|
|
14533
|
+
if (!line.trim()) continue;
|
|
14534
|
+
let a; try { a = JSON.parse(line); } catch (_) { continue; }
|
|
14535
|
+
n++;
|
|
14536
|
+
seen.set(a[0], {
|
|
14537
|
+
id: a[0], branch: a[1], sha: a[2], event: a[3], workflowName: a[4], status: a[5], conclusion: a[6],
|
|
14538
|
+
attempt: a[7], createdMs: Date.parse(a[8]), updatedMs: Date.parse(a[9]), headCommitMs: a[10] ? Date.parse(a[10]) : null,
|
|
14539
|
+
});
|
|
14540
|
+
}
|
|
14541
|
+
if (i < 3 && n < 100) i = 2; // a short page ends the paged list; the trunk page still runs
|
|
14542
|
+
}
|
|
14543
|
+
return { rows: [...seen.values()], runsRead: seen.size };
|
|
14544
|
+
}
|
|
14545
|
+
|
|
14546
|
+
const ciProfileMemo = new Map();
|
|
14547
|
+
|
|
14548
|
+
/**
|
|
14549
|
+
* The one reader: `{ profile, th, factor, kindTrunk, cache: { state, ageSec, fetchedAt }, notes }`.
|
|
14550
|
+
* `fetch`: 'never' (ship's hot path — never blocks a verdict on a history read) · 'if-stale' ·
|
|
14551
|
+
* 'always'. A stale cache is still used when a refetch fails: old measured data beats bootstrap.
|
|
14552
|
+
* TTL 0 (`COLAB_CI_PROFILE_TTL=0`) means no cache and no fetch — the bootstrap everywhere.
|
|
14553
|
+
*/
|
|
14554
|
+
function ciProfileFor(repoAbs, { fetch = 'never' } = {}) {
|
|
14555
|
+
const memoKey = `${repoAbs}\u0000${fetch}`;
|
|
14556
|
+
if (ciProfileMemo.has(memoKey)) return ciProfileMemo.get(memoKey);
|
|
14557
|
+
const doc = projectDoc(repoAbs);
|
|
14558
|
+
const factor = ciProfile.parseFactor(doc);
|
|
14559
|
+
const trunk = resolveTrunk(repoAbs, doc);
|
|
14560
|
+
const notes = [];
|
|
14561
|
+
if (!factor.valid) notes.push(factor.reason);
|
|
14562
|
+
const ttl = ciProfileTtlSec();
|
|
14563
|
+
const file = ttl > 0 ? ciProfileCacheFile(repoAbs) : null;
|
|
14564
|
+
let entry = null;
|
|
14565
|
+
if (file) {
|
|
14566
|
+
try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { entry = null; }
|
|
14567
|
+
if (entry && (entry.v !== CI_PROFILE_CACHE_V || entry.trunk !== trunk || !entry.profile)) entry = null;
|
|
14568
|
+
}
|
|
14569
|
+
const ageSec = entry ? Math.max(0, Math.floor((Date.now() - entry.fetchedAt) / 1000)) : null;
|
|
14570
|
+
let state = entry ? (ageSec < ttl ? 'fresh' : 'stale') : 'none';
|
|
14571
|
+
const want = file && trunk && (fetch === 'always' || (fetch === 'if-stale' && state !== 'fresh'));
|
|
14572
|
+
if (want) {
|
|
14573
|
+
if (!isGhUsable(repoAbs)) notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — CI history not read`);
|
|
14574
|
+
else {
|
|
14575
|
+
const nowMs = Date.now();
|
|
14576
|
+
const sinceMs = nowMs - ciProfile.WINDOW_DAYS * 86_400_000;
|
|
14577
|
+
const got = fetchCiProfileRows(repoAbs, trunk, new Date(sinceMs).toISOString());
|
|
14578
|
+
if (got.error) notes.push(`could not read CI history (${got.error}) — ${entry ? 'using the stale cached profile' : 'using the bootstrap bounds'}`);
|
|
14579
|
+
else {
|
|
14580
|
+
const policy = verifyRuns.parsePolicy(doc);
|
|
14581
|
+
const prof = ciProfile.profile(ciProfile.shaDurations(got.rows, { trunk, policy }), { sinceMs });
|
|
14582
|
+
entry = { v: CI_PROFILE_CACHE_V, trunk, fetchedAt: nowMs, since: new Date(sinceMs).toISOString(), runsRead: got.runsRead, profile: prof };
|
|
14583
|
+
state = 'fetched';
|
|
14584
|
+
try {
|
|
14585
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
14586
|
+
fs.writeFileSync(tmp, JSON.stringify(entry));
|
|
14587
|
+
fs.renameSync(tmp, file);
|
|
14588
|
+
} catch (_) { /* no cache, not an error */ }
|
|
14589
|
+
}
|
|
14590
|
+
}
|
|
14591
|
+
}
|
|
14592
|
+
const profile = entry ? entry.profile : null;
|
|
14593
|
+
const out = {
|
|
14594
|
+
trunk, factor, profile, th: ciProfile.thresholds(profile, factor.value),
|
|
14595
|
+
cache: { state, ageSec: state === 'fetched' ? 0 : ageSec, fetchedAt: entry ? new Date(entry.fetchedAt).toISOString() : null,
|
|
14596
|
+
since: entry ? entry.since : null, runsRead: entry ? entry.runsRead : null },
|
|
14597
|
+
notes,
|
|
14598
|
+
};
|
|
14599
|
+
ciProfileMemo.set(memoKey, out);
|
|
14600
|
+
return out;
|
|
14601
|
+
}
|
|
14602
|
+
|
|
14494
14603
|
// ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
|
|
14495
14604
|
// of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
|
|
14496
14605
|
// requests, a deadline, and a distinct exit code for every way a wait can end.
|
|
@@ -14506,9 +14615,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
|
|
|
14506
14615
|
with no run yet counts as pending until the deadline. An abbreviated sha is
|
|
14507
14616
|
resolved in the repo first, and refused (exit 2) when it does not resolve — #529
|
|
14508
14617
|
--branch <b> narrow --sha to runs on that branch
|
|
14509
|
-
--timeout <d> deadline:
|
|
14618
|
+
--timeout <d> deadline: 90s, 15m, 1h, or seconds. Default: this repo's CI wait bound, derived
|
|
14619
|
+
from its measured CI duration (\`colab ci-profile\`, #559) — the trunk bound
|
|
14620
|
+
when the target is trunk, the branch bound for any other branch, the larger
|
|
14621
|
+
for a bare run id; 15m while the repo has no CI history. Skills omit it.
|
|
14510
14622
|
|
|
14511
|
-
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline
|
|
14623
|
+
Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline (a repo whose CI bound is past 15m
|
|
14624
|
+
gets the same schedule stretched in proportion — never a faster one). Every poll after the first is a
|
|
14512
14625
|
conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
|
|
14513
14626
|
304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
|
|
14514
14627
|
can cost one paid call, never the whole wait (#505). A 15-minute run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
|
|
@@ -14523,7 +14636,8 @@ Exit codes — branch on these, never on the text:
|
|
|
14523
14636
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
14524
14637
|
|
|
14525
14638
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
14526
|
-
--json { outcome, exit, target, polls, notModified, forced, waitedSec,
|
|
14639
|
+
--json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
|
|
14640
|
+
detail, status, conclusion, url }`;
|
|
14527
14641
|
|
|
14528
14642
|
function cmdCiWait(argv) {
|
|
14529
14643
|
const opts = parseArgs(argv, {
|
|
@@ -14536,8 +14650,10 @@ function cmdCiWait(argv) {
|
|
|
14536
14650
|
warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
|
|
14537
14651
|
return ciWait.EXIT.USAGE;
|
|
14538
14652
|
}
|
|
14539
|
-
|
|
14540
|
-
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try
|
|
14653
|
+
let deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
|
|
14654
|
+
if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 15m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
|
|
14655
|
+
let deadlineBasis = opts.timeout !== undefined ? '--timeout' : 'bootstrap';
|
|
14656
|
+
let schedule = ciWait.DEFAULT_SCHEDULE_SEC;
|
|
14541
14657
|
const repoAbs = resolveRepo(opts);
|
|
14542
14658
|
if (opts.sha) {
|
|
14543
14659
|
// #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
|
|
@@ -14564,6 +14680,23 @@ function cmdCiWait(argv) {
|
|
|
14564
14680
|
return ciWait.EXIT.ALREADY_WAITING;
|
|
14565
14681
|
}
|
|
14566
14682
|
|
|
14683
|
+
// #559: no --timeout → the repo's own bound, one source with every skill (they omit the flag). Read
|
|
14684
|
+
// after the lock, so a refused second waiter never spends a history fetch; a failed read is a note.
|
|
14685
|
+
if (opts.timeout === undefined) {
|
|
14686
|
+
const cp = ciProfileFor(repoAbs, { fetch: 'if-stale' });
|
|
14687
|
+
let onTrunk = null;
|
|
14688
|
+
if (!runId && !opts.branch && cp.trunk) {
|
|
14689
|
+
const remote = git.remoteFor(repoAbs);
|
|
14690
|
+
onTrunk = git.git(['merge-base', '--is-ancestor', opts.sha, `${remote}/${cp.trunk}`], repoAbs).ok;
|
|
14691
|
+
}
|
|
14692
|
+
const kind = ciProfile.kindFor({ branch: opts.branch || null, trunk: cp.trunk, onTrunk });
|
|
14693
|
+
deadlineSec = cp.th.ciWaitDefaultSec[kind];
|
|
14694
|
+
schedule = cp.th.scheduleSec[kind];
|
|
14695
|
+
const b = kind === 'any' ? (cp.th.basis.branchWait === 'measured' || cp.th.basis.trunkWait === 'measured' ? 'measured' : 'bootstrap') : cp.th.basis[`${kind}Wait`];
|
|
14696
|
+
deadlineBasis = `${kind === 'any' ? 'larger' : kind} bound, ${b}`;
|
|
14697
|
+
if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
|
|
14698
|
+
}
|
|
14699
|
+
|
|
14567
14700
|
const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
|
|
14568
14701
|
const poll = (etag) => {
|
|
14569
14702
|
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
@@ -14583,11 +14716,11 @@ function cmdCiWait(argv) {
|
|
|
14583
14716
|
return { ...r, summary, state: ciWait.runState(summary) };
|
|
14584
14717
|
};
|
|
14585
14718
|
|
|
14586
|
-
if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s,
|
|
14719
|
+
if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}, ${deadlineBasis}; polls at +0s, +${schedule[0]}s, +${schedule[1]}s, then every ${schedule[2]}s)\n`);
|
|
14587
14720
|
let res;
|
|
14588
14721
|
try {
|
|
14589
14722
|
res = ciWait.waitLoop({
|
|
14590
|
-
poll, sleep: ciWait.sleepSync, deadlineSec,
|
|
14723
|
+
poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
|
|
14591
14724
|
onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}${p.forced ? ' (unconditional re-read — #505)' : ''}\n`); },
|
|
14592
14725
|
});
|
|
14593
14726
|
} finally {
|
|
@@ -14597,7 +14730,7 @@ function cmdCiWait(argv) {
|
|
|
14597
14730
|
const code = ciWait.EXIT[res.outcome];
|
|
14598
14731
|
const out = {
|
|
14599
14732
|
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
|
|
14600
|
-
waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
|
|
14733
|
+
waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
|
|
14601
14734
|
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
14602
14735
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
14603
14736
|
};
|
|
@@ -14793,6 +14926,122 @@ function cmdBatchStats(argv) {
|
|
|
14793
14926
|
return 0;
|
|
14794
14927
|
}
|
|
14795
14928
|
|
|
14929
|
+
// ci-profile (#559) — the repo's measured CI duration and every wait bound derived from it.
|
|
14930
|
+
const HELP_CI_PROFILE = `colab ci-profile [--repo <path>] [--json] [--refresh]
|
|
14931
|
+
|
|
14932
|
+
This repo's measured CI duration, and every CI wait bound derived from it (#559). One source:
|
|
14933
|
+
\`colab ci-wait\` with no --timeout, and \`colab ship\`'s wedged-run and empty-read verdicts, read
|
|
14934
|
+
these same numbers — no skill hard-codes a wait.
|
|
14935
|
+
|
|
14936
|
+
Measured: per sha, the wall time from the first verifying run's creation to the last one's
|
|
14937
|
+
finish, over clean first-attempt green shas in the last ${ciProfile.WINDOW_DAYS} days — split into branch runs and trunk
|
|
14938
|
+
runs — plus the push → run lag on trunk. A kind with fewer than ${ciProfile.MIN_SAMPLES} samples stays on its
|
|
14939
|
+
bootstrap value, which is today's fleet value exactly (15m waits, 6h wedge, 10m grace, 2m floor).
|
|
14940
|
+
|
|
14941
|
+
Declared: only \`ci-wait-factor: <number ≥ 1>\` in .github/project.yml (default ${ciProfile.DEFAULT_FACTOR}) — how many times
|
|
14942
|
+
the measured p95 a repo will wait. Every bound:
|
|
14943
|
+
branch / trunk wait 2m + factor × p95 of that kind, rounded up to the minute
|
|
14944
|
+
wedged-run age factor × the longer wait, never above 6h
|
|
14945
|
+
empty-read grace factor × push→run p95, never below 2m
|
|
14946
|
+
zero-jobs floor 2m (not measurable from the run list)
|
|
14947
|
+
poll backoff 30/60/120s, stretched in proportion to a wait past 15m — never faster
|
|
14948
|
+
|
|
14949
|
+
The profile is cached per checkout for a day (<git common dir>/colab-ci-profile.json;
|
|
14950
|
+
COLAB_CI_PROFILE_TTL seconds overrides, 0 = no cache and no read: the bootstrap). The bounds are
|
|
14951
|
+
recomputed from it on every read, so a changed ci-wait-factor applies at once.
|
|
14952
|
+
|
|
14953
|
+
--refresh re-read the CI history now, whatever the cache's age
|
|
14954
|
+
--json { repo, trunk, source, factor, cache, measured: { branch, trunk, lag }, thresholds, notes }`;
|
|
14955
|
+
|
|
14956
|
+
function cmdCiProfile(argv) {
|
|
14957
|
+
const opts = parseArgs(argv, {
|
|
14958
|
+
values: { '--repo': 'repo' },
|
|
14959
|
+
flags: { '--json': 'json', '--refresh': 'refresh', '-h': 'help', '--help': 'help' },
|
|
14960
|
+
});
|
|
14961
|
+
if (opts.help) return print(HELP_CI_PROFILE);
|
|
14962
|
+
const repoAbs = resolveRepo(opts);
|
|
14963
|
+
if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone, then run \`colab ci-profile\` again`);
|
|
14964
|
+
const cp = ciProfileFor(repoAbs, { fetch: opts.refresh ? 'always' : 'if-stale' });
|
|
14965
|
+
if (!cp.trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab ci-profile` again');
|
|
14966
|
+
const p = cp.profile || ciProfile.profile([]);
|
|
14967
|
+
const th = cp.th;
|
|
14968
|
+
const source = cp.profile ? cp.profile.source : 'bootstrap';
|
|
14969
|
+
if (opts.json) {
|
|
14970
|
+
print(JSON.stringify({
|
|
14971
|
+
repo: shortRepo(repoAbs), trunk: cp.trunk, source, factor: cp.factor, cache: cp.cache,
|
|
14972
|
+
measured: { branch: p.branch, trunk: p.trunk, lag: p.lag }, thresholds: th, notes: cp.notes,
|
|
14973
|
+
}, null, 2));
|
|
14974
|
+
return 0;
|
|
14975
|
+
}
|
|
14976
|
+
const dur = (s) => (s === null || s === undefined ? '—' : ciWait.fmtDuration(s * 1000));
|
|
14977
|
+
const cacheTxt = cp.cache.state === 'fetched' ? 'read now'
|
|
14978
|
+
: cp.cache.state === 'none' ? 'no history read' : `read ${dur(cp.cache.ageSec)} ago (cache${cp.cache.state === 'stale' ? ', stale' : ''})`;
|
|
14979
|
+
print(`ci-profile ${shortRepo(repoAbs)} → ${cp.trunk} ${source.toUpperCase()} · ${cacheTxt} · ${cp.factor.valid ? cp.factor.reason : `${ciProfile.FACTOR_KEY}: ${ciProfile.DEFAULT_FACTOR} (declared value invalid)`}`);
|
|
14980
|
+
if (source !== 'measured') print(` ${source === 'bootstrap' ? 'every bound is' : 'unmeasured bounds are'} the bootstrap — fewer than ${ciProfile.MIN_SAMPLES} clean green shas per kind in ${ciProfile.WINDOW_DAYS}d`);
|
|
14981
|
+
const k = (name, x) => print(` ${name.padEnd(11)} ${x.source} · ${x.samples} sha(s)${x.samples ? ` · p50 ${dur(x.p50Sec)} · p95 ${dur(x.p95Sec)} · max ${dur(x.maxSec)}` : ''}`);
|
|
14982
|
+
k('branch', p.branch);
|
|
14983
|
+
k('trunk', p.trunk);
|
|
14984
|
+
print(` ${'push→run'.padEnd(11)} ${p.lag.source} · ${p.lag.samples} sample(s)${p.lag.samples ? ` · p95 ${dur(p.lag.p95Sec)}` : ''}`);
|
|
14985
|
+
const row = (name, sec, basis, how, boot) => print(` ${name.padEnd(11)} ${dur(sec).padEnd(7)} ${basis === 'measured' ? how : basis === 'default' ? how : 'bootstrap'}${basis === 'measured' && boot ? ` (bootstrap ${boot})` : ''}`);
|
|
14986
|
+
row('branch wait', th.branchWaitSec, th.basis.branchWait, `2m + ${th.factor} × p95`, '15m');
|
|
14987
|
+
row('trunk wait', th.trunkWaitSec, th.basis.trunkWait, `2m + ${th.factor} × p95`, '15m');
|
|
14988
|
+
print(` ${'ci-wait'.padEnd(11)} ${dur(th.ciWaitDefaultSec.branch)} branch · ${dur(th.ciWaitDefaultSec.trunk)} trunk · ${dur(th.ciWaitDefaultSec.any)} run id (its default with no --timeout)`);
|
|
14989
|
+
row('wedged age', th.wedgeAgeSec, th.basis.wedgeAge, `${th.factor} × the longer wait, ≤ 6h`, '6h');
|
|
14990
|
+
row('empty read', th.emptyReadGraceSec, th.basis.emptyReadGrace, `${th.factor} × push→run p95, ≥ 2m`, '10m');
|
|
14991
|
+
row('zero jobs', th.zeroJobsFloorSec, th.basis.zeroJobsFloor, 'default — not measurable from the run list');
|
|
14992
|
+
print(` ${'backoff'.padEnd(11)} branch ${th.scheduleSec.branch.map((x) => `${x}s`).join('/')} · trunk ${th.scheduleSec.trunk.map((x) => `${x}s`).join('/')}`);
|
|
14993
|
+
for (const n of cp.notes) print(` ! ${n}`);
|
|
14994
|
+
return 0;
|
|
14995
|
+
}
|
|
14996
|
+
|
|
14997
|
+
// thresholds (#560) — the advisory thresholds this repo applies: its declared values, else the defaults.
|
|
14998
|
+
const HELP_THRESHOLDS = `colab thresholds [--repo <path>] [--json] [<name>]
|
|
14999
|
+
|
|
15000
|
+
The advisory thresholds this repo applies (#560): the value of each, and whether it is this
|
|
15001
|
+
repo's declared value or the handbook default. A repo overrides one in .github/project.yml:
|
|
15002
|
+
|
|
15003
|
+
thresholds:
|
|
15004
|
+
hot-file-count: 4
|
|
15005
|
+
|
|
15006
|
+
Nothing changes for a repo that declares nothing. Skills cite these by name — code-triage's
|
|
15007
|
+
hot-file count and dependents band, code-wrap's gate.smoke target — and read them here, so no
|
|
15008
|
+
skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
|
|
15009
|
+
and is listed under problems; the audit and the CI templates' descriptor check fail it.
|
|
15010
|
+
|
|
15011
|
+
<name> print only that threshold's value (a bare number, for a script or a skill)
|
|
15012
|
+
--json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
|
|
15013
|
+
|
|
15014
|
+
function cmdThresholds(argv) {
|
|
15015
|
+
const opts = parseArgs(argv, {
|
|
15016
|
+
values: { '--repo': 'repo' },
|
|
15017
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
15018
|
+
});
|
|
15019
|
+
if (opts.help) return print(HELP_THRESHOLDS);
|
|
15020
|
+
const repoAbs = resolveRepo(opts);
|
|
15021
|
+
const r = thresholdsLib.parseThresholds(projectDoc(repoAbs));
|
|
15022
|
+
const name = opts._ && opts._[0];
|
|
15023
|
+
if (name !== undefined) {
|
|
15024
|
+
if (!thresholdsLib.SPEC[name]) throw new UserError(`unknown threshold ${name} — expected one of: ${Object.keys(thresholdsLib.SPEC).join(', ')} (run \`colab thresholds\` to list them)`);
|
|
15025
|
+
for (const p of r.problems) process.stderr.write(`! ${p}\n`);
|
|
15026
|
+
print(String(r.values[name]));
|
|
15027
|
+
return 0;
|
|
15028
|
+
}
|
|
15029
|
+
const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
|
|
15030
|
+
value: r.values[k], default: s.def, declared: !!r.declared[k], what: s.what, where: s.where,
|
|
15031
|
+
}]));
|
|
15032
|
+
if (opts.json) {
|
|
15033
|
+
print(JSON.stringify({ repo: shortRepo(repoAbs), thresholds: rows, problems: r.problems }, null, 2));
|
|
15034
|
+
return 0;
|
|
15035
|
+
}
|
|
15036
|
+
print(`thresholds ${shortRepo(repoAbs)}`);
|
|
15037
|
+
const w = Math.max(...Object.keys(rows).map((k) => k.length));
|
|
15038
|
+
for (const [k, row] of Object.entries(rows)) {
|
|
15039
|
+
print(` ${k.padEnd(w)} ${String(row.value).padStart(5)} ${row.declared ? `declared (default ${row.default})` : 'default'.padEnd(20)} ${row.what}`);
|
|
15040
|
+
}
|
|
15041
|
+
for (const p of r.problems) print(` ! ${p}`);
|
|
15042
|
+
return 0;
|
|
15043
|
+
}
|
|
15044
|
+
|
|
14796
15045
|
function cmdLanded(argv) {
|
|
14797
15046
|
const opts = parseArgs(argv, {
|
|
14798
15047
|
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
|
|
@@ -15580,6 +15829,10 @@ Commands:
|
|
|
15580
15829
|
batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
|
|
15581
15830
|
fill, first-attempt green, drops, missed partners, queue
|
|
15582
15831
|
wait; how a repo tunes ship-batch / ship-batch-wait (#554)
|
|
15832
|
+
ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
|
|
15833
|
+
derived from it — ci-wait's default deadline (#559)
|
|
15834
|
+
thresholds [<name>] [--json] the advisory thresholds this repo applies — declared in
|
|
15835
|
+
project.yml thresholds:, else the default (#560)
|
|
15583
15836
|
holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
|
|
15584
15837
|
have not landed on the base (filters the raw git-log
|
|
15585
15838
|
one-liner through \`landed\`'s content classification)
|
|
@@ -15665,6 +15918,8 @@ function main(argv) {
|
|
|
15665
15918
|
case 'ship': return cmdShip(rest);
|
|
15666
15919
|
case 'landed': return cmdLanded(rest);
|
|
15667
15920
|
case 'batch-stats': return cmdBatchStats(rest);
|
|
15921
|
+
case 'ci-profile': return cmdCiProfile(rest);
|
|
15922
|
+
case 'thresholds': return cmdThresholds(rest);
|
|
15668
15923
|
case 'trunk-ci': return cmdTrunkCi(rest);
|
|
15669
15924
|
case 'ci-wait': return cmdCiWait(rest);
|
|
15670
15925
|
case 'holders': return cmdHolders(rest);
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/ci-profile.js — a repo's measured CI duration, and every CI wait bound derived from it (#559).
|
|
4
|
+
*
|
|
5
|
+
* Before this module every CI wait was a fleet-wide constant, and two of them disagreed: the skills
|
|
6
|
+
* passed `--timeout 15m` to `colab ci-wait` everywhere while its own default was 45 minutes, so a
|
|
7
|
+
* caller that omitted the flag silently waited three times as long. Repos' CI ranges from a few
|
|
8
|
+
* minutes to nearly half an hour, so one number was too long for a fast repo and too short for a
|
|
9
|
+
* slow one.
|
|
10
|
+
*
|
|
11
|
+
* The rule (epic #558): a threshold that depends on a repo's nature comes from THAT repo. Here the
|
|
12
|
+
* duration is MEASURED from the repo's own CI history; the only DECLARED part is the multiple of it
|
|
13
|
+
* a repo is willing to wait (`ci-wait-factor`, default 2). Where nothing has been measured yet, each
|
|
14
|
+
* bound is today's value exactly — documented as the bootstrap, never a different behaviour.
|
|
15
|
+
*
|
|
16
|
+
* Pure: run rows in, a profile and thresholds out — no git, no gh, no clock. `tools/colab` fetches
|
|
17
|
+
* (`fetchCiProfileRows`), caches (`ciProfileFor`) and prints (`cmdCiProfile`).
|
|
18
|
+
*
|
|
19
|
+
* What is measured, per sha: the wall time from the first run's creation to the last run's last
|
|
20
|
+
* update, across every run that verifies the code at that sha (verify-runs.js, the same set
|
|
21
|
+
* `ci-wait --sha` waits on). That is exactly the wait a session sits through: "every run at the sha
|
|
22
|
+
* has finished". Only clean first-attempt green shas count — a re-run measures an incident, a red
|
|
23
|
+
* run measures how fast it failed.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
const ciWait = require('./ci-wait');
|
|
27
|
+
const ciVerdict = require('./ci-verdict');
|
|
28
|
+
const verifyRuns = require('./verify-runs');
|
|
29
|
+
const { quantile } = require('./batch-stats');
|
|
30
|
+
|
|
31
|
+
const FACTOR_KEY = 'ci-wait-factor';
|
|
32
|
+
const DEFAULT_FACTOR = 2;
|
|
33
|
+
/** A kind with fewer clean green shas than this in the window stays on its bootstrap value. */
|
|
34
|
+
const MIN_SAMPLES = 10;
|
|
35
|
+
const WINDOW_DAYS = 30;
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* The one platform constant: how long GitHub may take to start a run and materialize its job list
|
|
39
|
+
* (ci-verdict's zero-jobs floor). It floors every derived bound — a 20-second CI must not produce a
|
|
40
|
+
* wait shorter than the time a run can take to appear at all. Not repo-measurable at run-list cost:
|
|
41
|
+
* `run_started_at` equals `created_at` on every row we read, so the list carries no queue signal.
|
|
42
|
+
*/
|
|
43
|
+
const PLATFORM_FLOOR_SEC = ciVerdict.ZERO_JOBS_AGE_FLOOR_MINUTES * 60;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Today's values, exactly — what a repo with no history gets, built from the constants that hold
|
|
47
|
+
* them rather than restated. The 6 h wedge age is also a CAP: it is the hosted-runner job limit, so
|
|
48
|
+
* measurement may only lower it (a safety limit a repo may only tighten, epic #558). Likewise the
|
|
49
|
+
* 30/60/120 s poll schedule is a REST-quota floor — measurement may only stretch it.
|
|
50
|
+
*/
|
|
51
|
+
const BOOTSTRAP = Object.freeze({
|
|
52
|
+
branchWaitSec: 15 * 60,
|
|
53
|
+
trunkWaitSec: 15 * 60,
|
|
54
|
+
wedgeAgeSec: ciVerdict.WEDGE_AGE_HOURS * 3600,
|
|
55
|
+
emptyReadGraceSec: ciVerdict.EMPTY_READ_GRACE_MINUTES * 60,
|
|
56
|
+
zeroJobsFloorSec: PLATFORM_FLOOR_SEC,
|
|
57
|
+
scheduleSec: ciWait.DEFAULT_SCHEDULE_SEC,
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* `ci-wait-factor: <number ≥ 1>` — absent → 2. A malformed value falls back to the documented
|
|
62
|
+
* default (never to a different behaviour) and is reported; the audit fails it.
|
|
63
|
+
*/
|
|
64
|
+
function parseFactor(doc) {
|
|
65
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, FACTOR_KEY) && doc[FACTOR_KEY] !== null && doc[FACTOR_KEY] !== undefined;
|
|
66
|
+
if (!has) return { value: DEFAULT_FACTOR, declared: false, valid: true, reason: `${FACTOR_KEY}: ${DEFAULT_FACTOR} (default)` };
|
|
67
|
+
const raw = doc[FACTOR_KEY];
|
|
68
|
+
const n = typeof raw === 'number' ? raw : (typeof raw === 'string' && /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : NaN);
|
|
69
|
+
if (!Number.isFinite(n) || n < 1) {
|
|
70
|
+
return { value: DEFAULT_FACTOR, declared: true, valid: false,
|
|
71
|
+
reason: `${FACTOR_KEY} must be a number ≥ 1 (a multiple of the measured CI duration), got ${JSON.stringify(raw)} — using ${DEFAULT_FACTOR}` };
|
|
72
|
+
}
|
|
73
|
+
return { value: n, declared: true, valid: true, reason: `${FACTOR_KEY}: ${n}` };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Rows → one wall time per clean green sha. A row: `{ sha, branch, event, workflowName, status,
|
|
78
|
+
* conclusion, attempt, createdMs, updatedMs, headCommitMs }`.
|
|
79
|
+
*
|
|
80
|
+
* A branch group at a sha that is also a trunk sha is dropped: a branch cut moments ago re-runs
|
|
81
|
+
* trunk's content, and those near-instant runs would drag the branch duration down.
|
|
82
|
+
*/
|
|
83
|
+
function shaDurations(rows, { trunk, policy = null } = {}) {
|
|
84
|
+
const groups = new Map();
|
|
85
|
+
for (const r of rows || []) {
|
|
86
|
+
if (!r || !r.sha || r.event === 'dynamic') continue;
|
|
87
|
+
const key = `${r.branch || ''}\u0000${r.sha}`;
|
|
88
|
+
if (!groups.has(key)) groups.set(key, []);
|
|
89
|
+
groups.get(key).push(r);
|
|
90
|
+
}
|
|
91
|
+
const trunkShas = new Set([...groups.values()].filter((g) => g[0].branch === trunk).map((g) => g[0].sha));
|
|
92
|
+
const out = [];
|
|
93
|
+
for (const g of groups.values()) {
|
|
94
|
+
const split = verifyRuns.splitVerifying(g, policy);
|
|
95
|
+
const counted = split ? split.counted : g;
|
|
96
|
+
if (!counted.length) continue;
|
|
97
|
+
if (!counted.every((r) => r.status === 'completed')) continue;
|
|
98
|
+
if (!counted.every((r) => ['success', 'skipped', 'neutral'].includes(r.conclusion))) continue;
|
|
99
|
+
if (!counted.some((r) => r.conclusion === 'success')) continue;
|
|
100
|
+
if (counted.some((r) => Number(r.attempt) > 1)) continue;
|
|
101
|
+
const created = Math.min(...counted.map((r) => r.createdMs));
|
|
102
|
+
const ended = Math.max(...counted.map((r) => r.updatedMs));
|
|
103
|
+
if (!Number.isFinite(created) || !Number.isFinite(ended) || ended < created) continue;
|
|
104
|
+
const kind = g[0].branch === trunk ? 'trunk' : 'branch';
|
|
105
|
+
if (kind === 'branch' && trunkShas.has(g[0].sha)) continue;
|
|
106
|
+
let lagSec = null;
|
|
107
|
+
if (kind === 'trunk') {
|
|
108
|
+
const c = Math.min(...counted.map((r) => r.headCommitMs).filter(Number.isFinite));
|
|
109
|
+
if (Number.isFinite(c) && created >= c) lagSec = Math.round((created - c) / 1000);
|
|
110
|
+
}
|
|
111
|
+
out.push({ sha: g[0].sha, kind, sec: Math.round((ended - created) / 1000), lagSec, endMs: ended });
|
|
112
|
+
}
|
|
113
|
+
return out;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function stats(values) {
|
|
117
|
+
const v = values.filter(Number.isFinite);
|
|
118
|
+
return {
|
|
119
|
+
source: v.length >= MIN_SAMPLES ? 'measured' : 'bootstrap',
|
|
120
|
+
samples: v.length,
|
|
121
|
+
p50Sec: quantile(v, 0.5),
|
|
122
|
+
p95Sec: quantile(v, 0.95),
|
|
123
|
+
maxSec: v.length ? Math.max(...v) : null,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Durations → `{ branch, trunk, lag, source }`; only samples ending at or after `sinceMs` count. */
|
|
128
|
+
function profile(durations, { sinceMs = null } = {}) {
|
|
129
|
+
const d = (durations || []).filter((x) => sinceMs === null || x.endMs >= sinceMs);
|
|
130
|
+
const branch = stats(d.filter((x) => x.kind === 'branch').map((x) => x.sec));
|
|
131
|
+
const trunk = stats(d.filter((x) => x.kind === 'trunk').map((x) => x.sec));
|
|
132
|
+
const lagV = d.filter((x) => x.kind === 'trunk' && x.lagSec !== null).map((x) => x.lagSec);
|
|
133
|
+
const lag = { source: lagV.length >= MIN_SAMPLES ? 'measured' : 'bootstrap', samples: lagV.length, p95Sec: quantile(lagV, 0.95) };
|
|
134
|
+
const n = [branch, trunk].filter((k) => k.source === 'measured').length;
|
|
135
|
+
return { branch, trunk, lag, source: n === 2 ? 'measured' : n === 0 ? 'bootstrap' : 'partial' };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const ceilMinute = (sec) => Math.ceil(sec / 60) * 60;
|
|
139
|
+
|
|
140
|
+
/** A kind's wait bound: GitHub must start the run, then `factor` times what it takes at p95. */
|
|
141
|
+
function boundFor(k, factor, bootstrapSec) {
|
|
142
|
+
if (!k || k.source !== 'measured' || !Number.isFinite(k.p95Sec)) return { sec: bootstrapSec, basis: 'bootstrap' };
|
|
143
|
+
return { sec: ceilMinute(PLATFORM_FLOOR_SEC + factor * k.p95Sec), basis: 'measured' };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** The schedule for a bound: 30/60/120 s stretched in proportion to a bound past 15 min, never shrunk. */
|
|
147
|
+
function scheduleFor(boundSec) {
|
|
148
|
+
const k = Math.max(1, boundSec / BOOTSTRAP.branchWaitSec);
|
|
149
|
+
return BOOTSTRAP.scheduleSec.map((s) => Math.round(s * k));
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Profile + factor → every threshold, each with the basis it came from. A null profile (nothing
|
|
154
|
+
* read, no cache) is the bootstrap in full.
|
|
155
|
+
*/
|
|
156
|
+
function thresholds(prof, factor = DEFAULT_FACTOR) {
|
|
157
|
+
const f = Number.isFinite(factor) && factor >= 1 ? factor : DEFAULT_FACTOR;
|
|
158
|
+
const p = prof || {};
|
|
159
|
+
const branch = boundFor(p.branch, f, BOOTSTRAP.branchWaitSec);
|
|
160
|
+
const trunk = boundFor(p.trunk, f, BOOTSTRAP.trunkWaitSec);
|
|
161
|
+
const anyMeasured = branch.basis === 'measured' || trunk.basis === 'measured';
|
|
162
|
+
const wedgeAgeSec = anyMeasured ? Math.min(BOOTSTRAP.wedgeAgeSec, ceilMinute(f * Math.max(branch.sec, trunk.sec))) : BOOTSTRAP.wedgeAgeSec;
|
|
163
|
+
const lagMeasured = p.lag && p.lag.source === 'measured' && Number.isFinite(p.lag.p95Sec);
|
|
164
|
+
const emptyReadGraceSec = lagMeasured ? Math.max(PLATFORM_FLOOR_SEC, ceilMinute(f * p.lag.p95Sec)) : BOOTSTRAP.emptyReadGraceSec;
|
|
165
|
+
return {
|
|
166
|
+
factor: f,
|
|
167
|
+
branchWaitSec: branch.sec,
|
|
168
|
+
trunkWaitSec: trunk.sec,
|
|
169
|
+
ciWaitDefaultSec: { branch: branch.sec, trunk: trunk.sec, any: Math.max(branch.sec, trunk.sec) },
|
|
170
|
+
wedgeAgeSec,
|
|
171
|
+
emptyReadGraceSec,
|
|
172
|
+
zeroJobsFloorSec: BOOTSTRAP.zeroJobsFloorSec,
|
|
173
|
+
scheduleSec: { branch: scheduleFor(branch.sec), trunk: scheduleFor(trunk.sec), any: scheduleFor(Math.max(branch.sec, trunk.sec)) },
|
|
174
|
+
basis: {
|
|
175
|
+
branchWait: branch.basis,
|
|
176
|
+
trunkWait: trunk.basis,
|
|
177
|
+
wedgeAge: anyMeasured ? 'measured' : 'bootstrap',
|
|
178
|
+
emptyReadGrace: lagMeasured ? 'measured' : 'bootstrap',
|
|
179
|
+
zeroJobsFloor: 'default',
|
|
180
|
+
},
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** Which bound a wait uses: trunk when the target is trunk, branch for any other branch, else `any`. */
|
|
185
|
+
function kindFor({ branch = null, trunk = null, onTrunk = null } = {}) {
|
|
186
|
+
if (branch) return branch === trunk ? 'trunk' : 'branch';
|
|
187
|
+
if (onTrunk === true) return 'trunk';
|
|
188
|
+
if (onTrunk === false) return 'branch';
|
|
189
|
+
return 'any';
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
module.exports = {
|
|
193
|
+
FACTOR_KEY, DEFAULT_FACTOR, MIN_SAMPLES, WINDOW_DAYS, PLATFORM_FLOOR_SEC, BOOTSTRAP,
|
|
194
|
+
parseFactor, shaDurations, profile, thresholds, scheduleFor, kindFor,
|
|
195
|
+
};
|
package/tools/lib/ci-verdict.js
CHANGED
|
@@ -72,24 +72,30 @@ function hoursSince(iso, nowMs) {
|
|
|
72
72
|
function wedgedVerdict(run, opts = {}) {
|
|
73
73
|
if (!run || run.status === 'completed' || run.status === 'none') return { wedged: false, reason: null };
|
|
74
74
|
const age = hoursSince(run.createdAt, opts.nowMs);
|
|
75
|
+
// #559: both bounds may come from the repo's measured CI (tools/lib/ci-profile.js); absent → today's.
|
|
76
|
+
const floorMin = Number.isFinite(opts.zeroJobsFloorSec) ? opts.zeroJobsFloorSec / 60 : ZERO_JOBS_AGE_FLOOR_MINUTES;
|
|
77
|
+
const wedgeHours = Number.isFinite(opts.wedgeAgeSec) ? opts.wedgeAgeSec / 3600 : WEDGE_AGE_HOURS;
|
|
75
78
|
if (run.jobCount === 0) {
|
|
76
79
|
// #171: no createdAt (age unknown) never manufactures a positive here, same posture as the age
|
|
77
80
|
// backstop below when createdAt is missing/unparseable — a missing signal must not wedge on its own.
|
|
78
|
-
const floorHours =
|
|
81
|
+
const floorHours = floorMin / 60;
|
|
79
82
|
if (age !== null && age >= floorHours) {
|
|
80
83
|
return {
|
|
81
84
|
wedged: true,
|
|
82
|
-
reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${
|
|
85
|
+
reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${fmtMin(floorMin)} floor)`,
|
|
83
86
|
};
|
|
84
87
|
}
|
|
85
88
|
return { wedged: false, reason: null };
|
|
86
89
|
}
|
|
87
|
-
if (age !== null && age >=
|
|
88
|
-
return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${
|
|
90
|
+
if (age !== null && age >= wedgeHours) {
|
|
91
|
+
return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${fmtHours(wedgeHours)} backstop)` };
|
|
89
92
|
}
|
|
90
93
|
return { wedged: false, reason: null };
|
|
91
94
|
}
|
|
92
95
|
|
|
96
|
+
const fmtMin = (m) => `${Number.isInteger(m) ? m : m.toFixed(1)}m`;
|
|
97
|
+
const fmtHours = (h) => (Number.isInteger(h) ? `${h}h` : `${Math.round(h * 60)}m`);
|
|
98
|
+
|
|
93
99
|
// #413: how long after a trunk commit "no run at this sha" is still the ordinary state. GitHub
|
|
94
100
|
// creates a push run seconds after the push, but a ship reading trunk right after another ship
|
|
95
101
|
// landed it can get there first. Ten minutes covers queueing on a busy account; past it, an empty
|
|
@@ -107,7 +113,9 @@ function emptyReadVerdict(committedAtMs, opts = {}) {
|
|
|
107
113
|
if (committedAtMs == null || !Number.isFinite(committedAtMs)) return { fresh: false, minutes: null };
|
|
108
114
|
const now = opts.nowMs != null ? opts.nowMs : Date.now();
|
|
109
115
|
const minutes = (now - committedAtMs) / 60000;
|
|
110
|
-
|
|
116
|
+
// #559: the grace may be the repo's measured push→run lag (tools/lib/ci-profile.js); absent → 10 min.
|
|
117
|
+
const graceMinutes = Number.isFinite(opts.graceSec) ? opts.graceSec / 60 : EMPTY_READ_GRACE_MINUTES;
|
|
118
|
+
return { fresh: minutes >= 0 && minutes < graceMinutes, minutes, graceMinutes };
|
|
111
119
|
}
|
|
112
120
|
|
|
113
121
|
module.exports = { WEDGE_AGE_HOURS, ZERO_JOBS_AGE_FLOOR_MINUTES, EMPTY_READ_GRACE_MINUTES, wedgedVerdict, emptyReadVerdict };
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -38,7 +38,10 @@ const EXIT = Object.freeze({
|
|
|
38
38
|
});
|
|
39
39
|
|
|
40
40
|
const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
|
|
41
|
-
|
|
41
|
+
// #559: the bootstrap deadline — the same 15 minutes every skill passed as `--timeout 15m`, so a caller
|
|
42
|
+
// that omits the flag no longer silently waits three times as long (it was 45 min). Once a repo has CI
|
|
43
|
+
// history, `colab ci-wait` derives its deadline from it instead (tools/lib/ci-profile.js).
|
|
44
|
+
const DEFAULT_DEADLINE_SEC = 15 * 60;
|
|
42
45
|
|
|
43
46
|
/** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
|
|
44
47
|
function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
|
package/tools/lib/disposition.js
CHANGED
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
|
|
56
56
|
const { axisOfRecord } = require('./axis-authority');
|
|
57
57
|
const { parseWakeLine } = require('./wake');
|
|
58
|
+
const { thresholdValue, parseThresholds } = require('./thresholds');
|
|
58
59
|
|
|
59
60
|
// ---------------------------------------------------------------------------------------------
|
|
60
61
|
// Vocabulary
|
|
@@ -115,10 +116,10 @@ const EVIDENCE_FIELDS = Object.freeze(['what', 'command', 'result', 'remains']);
|
|
|
115
116
|
/**
|
|
116
117
|
* PROPOSAL, not a measured threshold (CONVENTIONS.md §5 says so in the same words). A hold whose
|
|
117
118
|
* wake condition has sat this long without movement wants a human to confirm it is still wanted.
|
|
118
|
-
*
|
|
119
|
-
*
|
|
119
|
+
* This is the DEFAULT: a repo may declare its own as `thresholds.hold-stale-days` (#560), read
|
|
120
|
+
* from the `project` fact through tools/lib/thresholds.js. Exported for consumers and tests.
|
|
120
121
|
*/
|
|
121
|
-
const HOLD_STALE_DAYS =
|
|
122
|
+
const HOLD_STALE_DAYS = thresholdValue({}, 'hold-stale-days');
|
|
122
123
|
|
|
123
124
|
/**
|
|
124
125
|
* One marker per line, `proposed=<token>`, the shape `colab:grade verdict=<token>` already uses.
|
|
@@ -320,11 +321,13 @@ function classify(facts) {
|
|
|
320
321
|
'a park with no wake condition is not a hold — it is a silent wontfix, and should be said plainly',
|
|
321
322
|
['no review-by:<date>, no blockedBy edge, and no wake: condition from the closed vocabulary']);
|
|
322
323
|
}
|
|
323
|
-
const
|
|
324
|
+
const declared = parseThresholds(f.project); // #560: the repo's value, else the default 30
|
|
325
|
+
const staleDays = declared.values['hold-stale-days'];
|
|
326
|
+
const stale = Number.isFinite(w.ageDays) && w.ageDays > staleDays && w.movedSince !== true;
|
|
324
327
|
return stale
|
|
325
328
|
? verdict(kind, HUMAN, true,
|
|
326
|
-
`the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${
|
|
327
|
-
[`wake older than ${
|
|
329
|
+
`the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${staleDays} d is ${declared.declared['hold-stale-days'] ? 'this repo\'s thresholds.hold-stale-days' : 'a PROPOSAL, unmeasured'})`,
|
|
330
|
+
[`wake older than ${staleDays} days with no movement`])
|
|
328
331
|
: verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
|
|
329
332
|
}
|
|
330
333
|
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/thresholds.js — repo-declared values for the ADVISORY thresholds (#560, epic #558).
|
|
4
|
+
*
|
|
5
|
+
* Before this module each of these numbers was one fleet-wide constant, written into a skill's
|
|
6
|
+
* prose or a tool's source. The ruling on #560: today's value stays as the documented default, and
|
|
7
|
+
* a repo may override it in `.github/project.yml`:
|
|
8
|
+
*
|
|
9
|
+
* thresholds:
|
|
10
|
+
* hot-file-count: 4
|
|
11
|
+
* hold-stale-days: 45
|
|
12
|
+
*
|
|
13
|
+
* Nothing changes for a repo that declares nothing. Only ADVISORY thresholds live here — a number
|
|
14
|
+
* that decides what gets flagged, ranked or warned about. Safety limits (a cap a repo may only
|
|
15
|
+
* tighten) and protocol counts are out of scope (epic #558) and keep their own fields.
|
|
16
|
+
*
|
|
17
|
+
* Every value is a whole number with a per-key floor, and the unit is in the key's name. That keeps
|
|
18
|
+
* the CI templates' shell copy of this rule (the descriptor check, #416) small enough to be held to
|
|
19
|
+
* this table by tools/lib/ci-template-descriptor-check.test.js.
|
|
20
|
+
*
|
|
21
|
+
* A malformed value — a typo'd key, a non-number, a number under the floor — falls back to the
|
|
22
|
+
* default and is reported; the audit and the descriptor check fail it. A typo'd key is a problem,
|
|
23
|
+
* not an ignored extra: silently reverting to the default is exactly the failure #416 measured.
|
|
24
|
+
*
|
|
25
|
+
* Pure: a parsed descriptor in, values out. Both YAML readers feed it — the CLI's (numbers come
|
|
26
|
+
* through as numbers) and the audit's (they come through as digit strings) — so it accepts both.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
const KEY = 'thresholds';
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* key → { def, min, what, where }. `where` names the one place that reads the value.
|
|
33
|
+
* Order is the order `colab thresholds` prints.
|
|
34
|
+
*/
|
|
35
|
+
const SPEC = Object.freeze({
|
|
36
|
+
'hot-file-count': { def: 3, min: 2, what: 'waiting issues on one path before triage files HOT FILE', where: 'skills/code-triage/3-hot-file.md' },
|
|
37
|
+
'dependents-count': { def: 3, min: 1, what: 'open issues blocked_by one issue before triage ranks it as leverage', where: 'skills/code-triage/4-order.md' },
|
|
38
|
+
'hold-stale-days': { def: 30, min: 1, what: 'days a hold\'s wake condition may stand unmoved before a human confirms it', where: 'tools/lib/disposition.js' },
|
|
39
|
+
'smoke-minutes': { def: 3, min: 1, what: 'target run time of gate.smoke', where: 'skills/code-wrap/SKILL.md' },
|
|
40
|
+
'claude-md-kb': { def: 40, min: 1, what: 'authored KB of CLAUDE.md plus its @-imports before the audit warns', where: 'audit/audit.mjs' },
|
|
41
|
+
'claude-md-line-multiple': { def: 6, min: 2, what: 'longest line as a multiple of the file\'s median line before the audit warns', where: 'audit/audit.mjs' },
|
|
42
|
+
'claude-md-line-floor-bytes': { def: 2048, min: 0, what: 'a line under this many bytes is never flagged on the multiple alone', where: 'audit/audit.mjs' },
|
|
43
|
+
'transitional-days': { def: 180, min: 1, what: 'days a transitional descriptor value holds before the audit says how long', where: 'audit/audit.mjs' },
|
|
44
|
+
'doc-budget-slack': { def: 100, min: 0, what: 'lines under a doc budget before check-doc-budget asks to lower it', where: 'scripts/check-doc-budget.mjs' },
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
const DEFAULTS = Object.freeze(Object.fromEntries(Object.entries(SPEC).map(([k, s]) => [k, s.def])));
|
|
48
|
+
|
|
49
|
+
/** At most nine digits — the CI templates' shell check compares with `[ -ge ]`, which must not overflow. */
|
|
50
|
+
const MAX_VALUE = 999999999;
|
|
51
|
+
|
|
52
|
+
function wholeNumber(raw) {
|
|
53
|
+
if (typeof raw === 'number') return Number.isInteger(raw) && raw <= MAX_VALUE ? raw : NaN;
|
|
54
|
+
if (typeof raw === 'string' && /^\s*[0-9]{1,9}\s*$/.test(raw)) return Number(raw);
|
|
55
|
+
return NaN;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* `doc` → `{ values, declared, problems }`. `values` always carries every key (the default where
|
|
60
|
+
* nothing valid was declared); `declared` names the keys whose declared value is in force;
|
|
61
|
+
* `problems` is one sentence per malformed entry, each ending with the default it fell back to.
|
|
62
|
+
*/
|
|
63
|
+
function parseThresholds(doc) {
|
|
64
|
+
const values = Object.assign({}, DEFAULTS);
|
|
65
|
+
const declared = {};
|
|
66
|
+
const problems = [];
|
|
67
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
|
|
68
|
+
const raw = has ? doc[KEY] : undefined;
|
|
69
|
+
if (raw === undefined || raw === null || raw === '') return { values, declared, problems };
|
|
70
|
+
if (typeof raw !== 'object' || Array.isArray(raw)) {
|
|
71
|
+
problems.push(`${KEY} must be a map of "name: whole number" pairs, got ${JSON.stringify(raw)} — every threshold keeps its default`);
|
|
72
|
+
return { values, declared, problems };
|
|
73
|
+
}
|
|
74
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
75
|
+
const spec = SPEC[k];
|
|
76
|
+
if (!spec) {
|
|
77
|
+
problems.push(`${KEY}.${k} is not a known threshold (known: ${Object.keys(SPEC).join(', ')}) — ignored`);
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
if (v === null || v === undefined || v === '') continue; // an empty entry declares nothing
|
|
81
|
+
const n = wholeNumber(v);
|
|
82
|
+
if (!Number.isFinite(n) || n < spec.min) {
|
|
83
|
+
problems.push(`${KEY}.${k} must be a whole number ≥ ${spec.min}, got ${JSON.stringify(v)} — using the default ${spec.def}`);
|
|
84
|
+
continue;
|
|
85
|
+
}
|
|
86
|
+
values[k] = n;
|
|
87
|
+
declared[k] = true;
|
|
88
|
+
}
|
|
89
|
+
return { values, declared, problems };
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The resolved value of one key — the convenience a single consumer wants. */
|
|
93
|
+
function thresholdValue(doc, key) {
|
|
94
|
+
if (!SPEC[key]) throw new Error(`unknown threshold ${key}`);
|
|
95
|
+
return parseThresholds(doc).values[key];
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
module.exports = { KEY, SPEC, DEFAULTS, MAX_VALUE, parseThresholds, thresholdValue };
|