@futurelastic/colab-handbook 1.13.0-rc.26 → 1.13.0-rc.28
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 +29 -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 +187 -12
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/thresholds.js +98 -0
package/audit/audit.mjs
CHANGED
|
@@ -99,6 +99,7 @@ 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
101
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
102
|
+
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
102
103
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
103
104
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
104
105
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -219,7 +220,7 @@ function parseScalarValue(raw) {
|
|
|
219
220
|
return val;
|
|
220
221
|
}
|
|
221
222
|
|
|
222
|
-
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
|
|
223
224
|
|
|
224
225
|
function parseFlatYaml(text) {
|
|
225
226
|
const out = {};
|
|
@@ -1054,7 +1055,7 @@ function yamlRawValue(text, key) {
|
|
|
1054
1055
|
return m[1].replace(/\s+#.*$/, "").trim();
|
|
1055
1056
|
}
|
|
1056
1057
|
|
|
1057
|
-
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
|
|
1058
1059
|
// "transitional descriptor is clean" case, which this
|
|
1059
1060
|
// threshold exists to keep passing untouched: a descriptor
|
|
1060
1061
|
// committed moments ago must never earn a duration line.
|
|
@@ -1092,9 +1093,9 @@ function declaredStateAge(src, key) {
|
|
|
1092
1093
|
|
|
1093
1094
|
// Prose for a declaredStateAge() result, or null when it is too recent to be worth saying
|
|
1094
1095
|
// (the DURATION_MIN_DAYS gate — the caller must check this before calling warn()).
|
|
1095
|
-
function renderDuration(age) {
|
|
1096
|
+
function renderDuration(age, minDays = DURATION_MIN_DAYS) {
|
|
1096
1097
|
const days = Math.floor((Date.now() / 1000 - age.epoch) / DURATION_DAY_SECONDS);
|
|
1097
|
-
if (days <
|
|
1098
|
+
if (days < minDays) return null;
|
|
1098
1099
|
const months = Math.floor(days / 30); // coarse on purpose — a report, not a countdown
|
|
1099
1100
|
return `${age.lowerBound ? "at least " : ""}${months} month${months === 1 ? "" : "s"}`;
|
|
1100
1101
|
}
|
|
@@ -1123,12 +1124,15 @@ function auditRepo(target, ctx) {
|
|
|
1123
1124
|
// ---- .github/project.yml -------------------------------------------------
|
|
1124
1125
|
const rawCfg = src.readFile(".github/project.yml");
|
|
1125
1126
|
let cfg = null;
|
|
1127
|
+
// #560: the advisory thresholds this run applies — defaults until the descriptor declares otherwise.
|
|
1128
|
+
let th = thresholdsLib.parseThresholds(null);
|
|
1126
1129
|
if (rawCfg === null) {
|
|
1127
1130
|
fail("no .github/project.yml — repo is undescribed (tier/trunk/deploy unknown)");
|
|
1128
1131
|
} else {
|
|
1129
1132
|
const { data, problems } = parseFlatYaml(rawCfg);
|
|
1130
1133
|
problems.forEach((p) => fail(`project.yml: ${p}`));
|
|
1131
1134
|
cfg = data;
|
|
1135
|
+
th = thresholdsLib.parseThresholds(cfg);
|
|
1132
1136
|
// `tier` is deliberately NOT in this list as of #144: it used to be the sole axis of
|
|
1133
1137
|
// record and therefore unconditionally required, but a descriptor may now answer the
|
|
1134
1138
|
// gate-count question with `exposure` instead — see the "axis of record" check below,
|
|
@@ -1326,6 +1330,12 @@ function auditRepo(target, ctx) {
|
|
|
1326
1330
|
if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
|
|
1327
1331
|
}
|
|
1328
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
|
+
|
|
1329
1339
|
// ---- migrations (#383) ----------------------------------------------------
|
|
1330
1340
|
// Where the repo's migrations live, beyond the two defaults (database/migrations/,
|
|
1331
1341
|
// prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
|
|
@@ -1478,7 +1488,7 @@ function auditRepo(target, ctx) {
|
|
|
1478
1488
|
);
|
|
1479
1489
|
}
|
|
1480
1490
|
const exposureAge = declaredStateAge(src, "exposure");
|
|
1481
|
-
const durationLine = exposureAge && renderDuration(exposureAge);
|
|
1491
|
+
const durationLine = exposureAge && renderDuration(exposureAge, th.values["transitional-days"]);
|
|
1482
1492
|
if (durationLine) {
|
|
1483
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`);
|
|
1484
1494
|
}
|
|
@@ -1568,7 +1578,7 @@ function auditRepo(target, ctx) {
|
|
|
1568
1578
|
);
|
|
1569
1579
|
}
|
|
1570
1580
|
const channelsAge = declaredStateAge(src, "channels");
|
|
1571
|
-
const durationLine = channelsAge && renderDuration(channelsAge);
|
|
1581
|
+
const durationLine = channelsAge && renderDuration(channelsAge, th.values["transitional-days"]);
|
|
1572
1582
|
if (durationLine) {
|
|
1573
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`);
|
|
1574
1584
|
}
|
|
@@ -1713,7 +1723,7 @@ function auditRepo(target, ctx) {
|
|
|
1713
1723
|
// ---- CLAUDE.md is a router, not an archive (#64) -------------------------
|
|
1714
1724
|
// Unconditional: this is a repo-doc concern, not a tier/deploy one, and it applies to
|
|
1715
1725
|
// the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
|
|
1716
|
-
checkClaudeMdSize(src, warn);
|
|
1726
|
+
checkClaudeMdSize(src, warn, th.values);
|
|
1717
1727
|
// #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
|
|
1718
1728
|
// file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
|
|
1719
1729
|
checkInstructionFileBlocks(src, warn);
|
|
@@ -2215,9 +2225,10 @@ function checkReleaseBranch(cfg, trunk, branches, fail, warn, deploy) {
|
|
|
2215
2225
|
// a starting point rather than a recommendation", wanting calibration across adopting repos
|
|
2216
2226
|
// before anything here becomes a hard gate — the goal is a finding with the measured number
|
|
2217
2227
|
// ("state the condition"), not a build-breaking assertion of a still-uncalibrated one.
|
|
2218
|
-
const CLAUDE_MD_MAX_BYTES =
|
|
2219
|
-
|
|
2220
|
-
|
|
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).
|
|
2221
2232
|
|
|
2222
2233
|
// #117: the byte ceiling above was built to catch hand-written accretion, but it counts
|
|
2223
2234
|
// TOTAL file bytes — which also charges a repo for content it cannot shorten by the rule's
|
|
@@ -2450,7 +2461,11 @@ function checkAnchorLinks(src, fail) {
|
|
|
2450
2461
|
}
|
|
2451
2462
|
}
|
|
2452
2463
|
|
|
2453
|
-
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"];
|
|
2454
2469
|
// #417: measure what is LOADED, not one file. A thin-shell CLAUDE.md (`@AGENTS.md` plus the
|
|
2455
2470
|
// by-name tool blocks) is tiny by construction, so measuring it alone would neuter this guard
|
|
2456
2471
|
// while a bloated AGENTS.md rides in behind it on every turn. The loaded set is CLAUDE.md plus
|
|
@@ -2473,7 +2488,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2473
2488
|
}
|
|
2474
2489
|
const derivedBytes = Math.max(0, bytes - authoredBytes);
|
|
2475
2490
|
|
|
2476
|
-
if (authoredBytes >
|
|
2491
|
+
if (authoredBytes > maxBytes) {
|
|
2477
2492
|
const totalNote = derivedBytes > 0
|
|
2478
2493
|
? ` (of ${bytes} bytes total; ${derivedBytes} bytes are marked colab:derived and excluded — #117)`
|
|
2479
2494
|
: "";
|
|
@@ -2482,7 +2497,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2482
2497
|
: `CLAUDE.md plus its @-imports (${files.slice(1).map((f) => f.path).join(", ")}) is`;
|
|
2483
2498
|
warn(
|
|
2484
2499
|
`${subject} ${authoredBytes} bytes (~${(authoredBytes / 1024).toFixed(1)} KB)${totalNote} — over the ` +
|
|
2485
|
-
`${
|
|
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 ` +
|
|
2486
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)`,
|
|
2487
2502
|
);
|
|
2488
2503
|
}
|
|
@@ -2497,7 +2512,7 @@ function checkClaudeMdSize(src, warn) {
|
|
|
2497
2512
|
if (lens.length < 2) continue; // no meaningful median from 0 or 1 lines
|
|
2498
2513
|
const median = lens[Math.floor(lens.length / 2)];
|
|
2499
2514
|
const worst = lens[lens.length - 1];
|
|
2500
|
-
if (median > 0 && worst >
|
|
2515
|
+
if (median > 0 && worst > lineFloor && worst > median * lineMultiple) {
|
|
2501
2516
|
const pct = ((worst / f.authoredBytes) * 100).toFixed(1);
|
|
2502
2517
|
warn(
|
|
2503
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
|
@@ -50,6 +50,7 @@ const treeGreen = require('./lib/tree-green');
|
|
|
50
50
|
const verifyRuns = require('./lib/verify-runs');
|
|
51
51
|
const ciWait = require('./lib/ci-wait'); // #495
|
|
52
52
|
const ciProfile = require('./lib/ci-profile'); // #559
|
|
53
|
+
const thresholdsLib = require('./lib/thresholds'); // #560
|
|
53
54
|
const staleBase = require('./lib/stale-base');
|
|
54
55
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
55
56
|
const scratchDirs = require('./lib/scratch-dirs');
|
|
@@ -67,6 +68,7 @@ const shipBatch = require('./lib/ship-batch');
|
|
|
67
68
|
const batchStats = require('./lib/batch-stats');
|
|
68
69
|
const conflictMarkers = require('./lib/conflict-markers');
|
|
69
70
|
const docsOnly = require('./lib/docs-only');
|
|
71
|
+
const configSet = require('./lib/config-set'); // #561
|
|
70
72
|
const cureDiff = require('./lib/cure-diff');
|
|
71
73
|
const codeowners = require('./lib/codeowners');
|
|
72
74
|
const releasePolicy = require('./lib/release-policy');
|
|
@@ -7656,6 +7658,10 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
|
|
|
7656
7658
|
rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
|
|
7657
7659
|
set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
|
|
7658
7660
|
claimIdentity
|
|
7661
|
+
set <tuning-key> <value> --evidence "<why>"
|
|
7662
|
+
a kebab-case key is this REPO's .github/project.yml, not this machine (#561):
|
|
7663
|
+
one tuning value, committed on a short branch, shippable with no issue —
|
|
7664
|
+
see: colab config set ship-batch --help
|
|
7659
7665
|
|
|
7660
7666
|
notifyUrl is OPTIONAL and off by default: unset, colab makes no network call of its own. Set it to
|
|
7661
7667
|
an http(s) endpoint and claim / release / ship / worktree new / worktree rm each push one small
|
|
@@ -7683,6 +7689,91 @@ changes on resume makes that session's own earlier claim comment read as a diffe
|
|
|
7683
7689
|
it will yield to itself. Unset it again with: colab config set claimIdentity ""
|
|
7684
7690
|
`;
|
|
7685
7691
|
|
|
7692
|
+
// config set <tuning-key> (#561) — one TUNING value of this repo's .github/project.yml, committed on
|
|
7693
|
+
// a short branch without touching any checkout, shippable by `colab ship` with no issue.
|
|
7694
|
+
const HELP_CONFIG_SET_DESCRIPTOR = `colab config set <tuning-key> <value> --evidence "<why>" [--repo <path>] [--no-push] [--dry]
|
|
7695
|
+
|
|
7696
|
+
Change ONE tuning value of this repo's .github/project.yml (#561). Tuning keys:
|
|
7697
|
+
${configSet.TUNING_KEYS.filter((k) => k !== 'thresholds').join(', ')}, thresholds.<name>
|
|
7698
|
+
|
|
7699
|
+
The value is validated by the parser every reader of that key uses (the same verdict \`colab ship\`
|
|
7700
|
+
computes), then committed on top of a freshly fetched <remote>/<trunk> as branch
|
|
7701
|
+
chore/tune-<key> — with no checkout touched and no issue. The subject is
|
|
7702
|
+
\`chore(project): <key> <old> → <new>\`; --evidence (required) goes in the body, which the squash
|
|
7703
|
+
carries, so the reason for the number lives in trunk's history.
|
|
7704
|
+
|
|
7705
|
+
Then: wait for the branch's CI (\`colab ci-wait --sha <sha> --branch <branch>\`) and
|
|
7706
|
+
\`colab ship --branch <branch>\`. Ship computes the TUNING-ONLY class from the diff — it is never
|
|
7707
|
+
asserted — and, like docs-only (#345), it opens the autonomy gate on a repo without auto-trunk.
|
|
7708
|
+
Every other precondition still applies.
|
|
7709
|
+
|
|
7710
|
+
Never on this path (they grant authority or change what deploys): ${configSet.AUTHORITY_KEYS.join(', ')}.
|
|
7711
|
+
|
|
7712
|
+
--evidence <text> the measurement behind the number (required)
|
|
7713
|
+
--no-push create the branch locally only
|
|
7714
|
+
--dry print the edit and the verdict; create nothing`;
|
|
7715
|
+
|
|
7716
|
+
function cmdConfigSetDescriptor(argv) {
|
|
7717
|
+
const opts = parseArgs(argv, {
|
|
7718
|
+
values: { '--repo': 'repo', '--evidence': 'evidence' },
|
|
7719
|
+
flags: { '--no-push': 'noPush', '--dry': 'dry', '-h': 'help', '--help': 'help' },
|
|
7720
|
+
});
|
|
7721
|
+
if (opts.help) return print(HELP_CONFIG_SET_DESCRIPTOR);
|
|
7722
|
+
const [key, value] = opts._ || [];
|
|
7723
|
+
if (!key || value === undefined) throw new UserError('config set needs <tuning-key> <value> — see: colab config set ship-batch --help');
|
|
7724
|
+
const kp = configSet.parseKeyPath(key);
|
|
7725
|
+
if (kp.problem) throw new UserError(kp.problem);
|
|
7726
|
+
if (!opts.dry && !String(opts.evidence || '').trim()) {
|
|
7727
|
+
throw new UserError('--evidence "<why>" is required — the measurement behind the number goes in the commit body (#561); re-run with --evidence "<what you measured>"');
|
|
7728
|
+
}
|
|
7729
|
+
const repoAbs = resolveRepo(opts);
|
|
7730
|
+
const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
|
|
7731
|
+
if (!trunk) throw new UserError('could not determine trunk — add `trunk:` to .github/project.yml (or run `colab adopt`), then re-run');
|
|
7732
|
+
const remote = git.remoteFor(repoAbs);
|
|
7733
|
+
const f = git.git(['fetch', remote, trunk], repoAbs);
|
|
7734
|
+
if (!f.ok) throw new UserError(`could not fetch ${remote}/${trunk} — nothing created (${f.stderr.split('\n')[0]}); re-run once \`git fetch ${remote} ${trunk}\` succeeds`);
|
|
7735
|
+
const baseRef = `${remote}/${trunk}`;
|
|
7736
|
+
const baseSha = (git.git(['rev-parse', `refs/remotes/${baseRef}`], repoAbs).stdout || '').trim();
|
|
7737
|
+
if (!baseSha) throw new UserError(`${baseRef} does not resolve after the fetch — check \`git ls-remote ${remote} ${trunk}\` and re-run`);
|
|
7738
|
+
const text = configSet.descriptorAt(repoAbs, baseSha);
|
|
7739
|
+
if (text === null) throw new UserError(`could not read ${configSet.DESCRIPTOR} at ${baseRef} — see why with \`git show ${baseRef}:${configSet.DESCRIPTOR}\``);
|
|
7740
|
+
if (text === '') throw new UserError(`${baseRef} has no ${configSet.DESCRIPTOR} — adopt the handbook first: \`colab adopt\``);
|
|
7741
|
+
const edit = configSet.editText(text, kp, value);
|
|
7742
|
+
if (edit.problem) throw new UserError(edit.problem);
|
|
7743
|
+
const name = [kp.top, kp.sub].filter(Boolean).join('.');
|
|
7744
|
+
if (edit.text === text) { print(`${name} is already ${value} on ${baseRef} — nothing to change`); return 0; }
|
|
7745
|
+
// The SAME verdict ship will compute on this diff — so a value ship would refuse is refused here.
|
|
7746
|
+
const verdict = configSet.classify({
|
|
7747
|
+
entries: [{ path: configSet.DESCRIPTOR, oldMode: '100644', newMode: '100644', binary: false }],
|
|
7748
|
+
baseText: text, headText: edit.text,
|
|
7749
|
+
});
|
|
7750
|
+
if (!verdict.tuning) throw new UserError(`refused: ${verdict.reason} — pick a valid value (\`colab config set ${name} --help\`)`);
|
|
7751
|
+
const branch = configSet.branchName(kp);
|
|
7752
|
+
if (git.branchExists(repoAbs, branch, remote)) {
|
|
7753
|
+
throw new UserError(`branch ${branch} already exists — ship it with \`colab ship --branch ${branch}\`, or delete it with \`git push ${remote} --delete ${branch}\` and \`git branch -D ${branch}\``);
|
|
7754
|
+
}
|
|
7755
|
+
const message = configSet.commitMessage(kp, edit.old, value, opts.evidence || '(dry run)');
|
|
7756
|
+
print(`config set ${shortRepo(repoAbs)} · ${name}: ${edit.old === null ? '(unset)' : edit.old} → ${value}`);
|
|
7757
|
+
print(` verdict: ${verdict.reason}`);
|
|
7758
|
+
print(` branch: ${branch} (base ${baseRef} @ ${shortSha(baseSha)})`);
|
|
7759
|
+
if (opts.dry) { print(' [DRY RUN] nothing created.'); return 0; }
|
|
7760
|
+
const c = configSet.commitOnBranch(repoAbs, { baseSha, text: edit.text, message, branch });
|
|
7761
|
+
if (!c.ok) throw new UserError(`could not create the commit: ${c.error} — nothing was created; a human must read the git error above before re-running`);
|
|
7762
|
+
print(` commit: ${shortSha(c.sha)} ${message.split('\n')[0]}`);
|
|
7763
|
+
if (opts.noPush) {
|
|
7764
|
+
print(` not pushed (--no-push). Push it, wait for CI, then: colab ship --branch ${branch}`);
|
|
7765
|
+
return 0;
|
|
7766
|
+
}
|
|
7767
|
+
const p = git.git(['push', remote, `refs/heads/${branch}:refs/heads/${branch}`], repoAbs);
|
|
7768
|
+
if (!p.ok) {
|
|
7769
|
+
warn(`push failed — the branch exists locally only: ${p.stderr.split('\n')[0]}`);
|
|
7770
|
+
return 1;
|
|
7771
|
+
}
|
|
7772
|
+
print(` pushed: ${remote}/${branch}`);
|
|
7773
|
+
print(`Next: colab ci-wait --sha ${c.sha} --branch ${branch} && colab ship --branch ${branch}`);
|
|
7774
|
+
return 0;
|
|
7775
|
+
}
|
|
7776
|
+
|
|
7686
7777
|
function cmdConfig(argv) {
|
|
7687
7778
|
const sub = argv[0];
|
|
7688
7779
|
const cfg = state.loadConfig();
|
|
@@ -7740,6 +7831,7 @@ function cmdConfig(argv) {
|
|
|
7740
7831
|
print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
|
|
7741
7832
|
return 0;
|
|
7742
7833
|
}
|
|
7834
|
+
if (sub === 'set' && argv[1] && configSet.isDescriptorKey(argv[1])) return cmdConfigSetDescriptor(argv.slice(1)); // #561
|
|
7743
7835
|
if (sub === 'set') {
|
|
7744
7836
|
const [k, v] = [argv[1], argv[2]];
|
|
7745
7837
|
if (!k || v === undefined) throw new UserError('set needs <key> <value>');
|
|
@@ -10121,6 +10213,7 @@ promotes is an integration event of the same weight as a promotion, and stays hu
|
|
|
10121
10213
|
|
|
10122
10214
|
Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
|
|
10123
10215
|
a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
|
|
10216
|
+
or tuning-only (#561)
|
|
10124
10217
|
— or a person runs ship through the human door (#525): a confirmed interactive
|
|
10125
10218
|
terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
|
|
10126
10219
|
b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
|
|
@@ -10297,6 +10390,14 @@ auto-trunk). The row reads "docs-only (N files) — autonomy exception", and --d
|
|
|
10297
10390
|
\`autonomyGate: { via, docsOnly }\`. After B0 sync the diff is measured again before the squash.
|
|
10298
10391
|
Every other precondition is unchanged. No flag, env var or project.yml field widens the list.
|
|
10299
10392
|
|
|
10393
|
+
TUNING-ONLY — the second computed exception (#561). Ship also proceeds without the grant when the
|
|
10394
|
+
diff changes .github/project.yml ALONE, every changed line inside a tuning key (ship-batch,
|
|
10395
|
+
ship-batch-wait, ci-wait-factor, thresholds) and every moved value valid; never with an authority
|
|
10396
|
+
key (autonomy, promotion, migration-grant, ci-grant, trust-humans, exposure, tier, trunk, deploy,
|
|
10397
|
+
release, production). It needs no issue. \`colab config set <key> <value> --evidence "<why>"\`
|
|
10398
|
+
writes such a branch. The row reads "tuning-only (<keys>) — autonomy exception (#561)"; --dry --json
|
|
10399
|
+
adds \`autonomyGate.tuning\`. Re-measured after B0 sync like docs-only.
|
|
10400
|
+
|
|
10300
10401
|
TRUNK-DIRECT — \`colab ship --direct\` (#302). A unit committed straight to trunk has no branch and
|
|
10301
10402
|
no worktree, so neither door above can find it, and evidence-close's own detection cannot fire
|
|
10302
10403
|
(\`landed\` is \`unknown\` when base === branch). --direct is its close path: the claims are this
|
|
@@ -11774,7 +11875,8 @@ function cmdShipDryJson(opts) {
|
|
|
11774
11875
|
|
|
11775
11876
|
// ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
|
|
11776
11877
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
11777
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
11878
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
11879
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
11778
11880
|
autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
|
|
11779
11881
|
checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
|
|
11780
11882
|
|
|
@@ -12655,23 +12757,33 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
|
|
|
12655
12757
|
* caller asserts nothing. `readDocsOnly` is a thunk, so an auto-trunk repo never pays for the
|
|
12656
12758
|
* diff read. Every other precondition is untouched — this relaxes the autonomy gate, not the checks.
|
|
12657
12759
|
*
|
|
12658
|
-
*
|
|
12760
|
+
* #561 adds the TUNING-ONLY class beside it: a diff `lib/config-set.js` classifies as one or more
|
|
12761
|
+
* tuning keys of .github/project.yml with valid values, and nothing else. `readTuning` is a thunk
|
|
12762
|
+
* too, consulted only when the change is not docs-only; a branchless (trunk-direct) door passes none.
|
|
12763
|
+
*
|
|
12764
|
+
* Returns `{ ok, via: 'auto-trunk'|'docs-only'|'tuning'|'human'|null, declared, docsOnly: verdict|null,
|
|
12765
|
+
* tuning: verdict|null, detail }`.
|
|
12659
12766
|
*/
|
|
12660
|
-
function shipAutonomyGate(doc, readDocsOnly, door = null) {
|
|
12767
|
+
function shipAutonomyGate(doc, readDocsOnly, door = null, readTuning = null) {
|
|
12661
12768
|
const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
|
|
12662
|
-
if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, human: null, detail: 'auto-trunk' };
|
|
12769
|
+
if (declared === 'auto-trunk') return { ok: true, via: 'auto-trunk', declared, docsOnly: null, tuning: null, human: null, detail: 'auto-trunk' };
|
|
12663
12770
|
const verdict = readDocsOnly();
|
|
12664
12771
|
if (verdict.docsOnly) {
|
|
12665
|
-
return { ok: true, via: 'docs-only', declared, docsOnly: verdict, human: null, detail: `${verdict.reason} — autonomy exception` };
|
|
12772
|
+
return { ok: true, via: 'docs-only', declared, docsOnly: verdict, tuning: null, human: null, detail: `${verdict.reason} — autonomy exception` };
|
|
12773
|
+
}
|
|
12774
|
+
const tuning = readTuning ? readTuning() : null;
|
|
12775
|
+
if (tuning && tuning.tuning) {
|
|
12776
|
+
return { ok: true, via: 'tuning', declared, docsOnly: verdict, tuning, human: null, detail: `${tuning.reason} — autonomy exception (#561)` };
|
|
12666
12777
|
}
|
|
12667
12778
|
// #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
|
|
12668
|
-
// after docs-only, so
|
|
12779
|
+
// after docs-only and tuning, so either keeps its own (agent-usable) door and record.
|
|
12669
12780
|
if (door && door.open) {
|
|
12670
|
-
return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
|
|
12781
|
+
return { ok: true, via: 'human', declared, docsOnly: verdict, tuning, human: door,
|
|
12671
12782
|
detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
|
|
12672
12783
|
}
|
|
12673
|
-
return { ok: false, via: null, declared, docsOnly: verdict, human: door,
|
|
12674
|
-
detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason};
|
|
12784
|
+
return { ok: false, via: null, declared, docsOnly: verdict, tuning, human: door,
|
|
12785
|
+
detail: `project.yml autonomy: ${declared} — a human must trigger Phase B (not docs-only: ${verdict.reason}; ` +
|
|
12786
|
+
`${tuning ? `not tuning-only: ${tuning.reason}; ` : ''}human door closed: ${door ? door.why : 'not offered'})` };
|
|
12675
12787
|
}
|
|
12676
12788
|
|
|
12677
12789
|
/** #525: the human-door refusal lines — what a person runs, never just "a human must". */
|
|
@@ -12730,8 +12842,10 @@ function shipHumanDoorGo(gate, opts, what) {
|
|
|
12730
12842
|
function autonomyGatePayload(gate) {
|
|
12731
12843
|
// #525: `human` is additive and present only when the human door was consulted, so an
|
|
12732
12844
|
// auto-trunk / docs-only payload stays byte-identical to before.
|
|
12733
|
-
|
|
12734
|
-
|
|
12845
|
+
// #561: `tuning` likewise — present only when the tuning class was consulted.
|
|
12846
|
+
const base = { via: gate.via, docsOnly: gate.docsOnly };
|
|
12847
|
+
if (gate.tuning) base.tuning = gate.tuning;
|
|
12848
|
+
return gate.human ? { ...base, human: { open: gate.human.open, how: gate.human.how, why: gate.human.why } } : base;
|
|
12735
12849
|
}
|
|
12736
12850
|
|
|
12737
12851
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
@@ -12818,11 +12932,13 @@ function cmdShip(argv) {
|
|
|
12818
12932
|
// ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
|
|
12819
12933
|
// #345: …or the branch's diff is documentation only, computed here from git — never asserted.
|
|
12820
12934
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
12821
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
12935
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
12936
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
12822
12937
|
if (!autonomyGate.ok) {
|
|
12823
12938
|
process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
|
|
12824
12939
|
process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
|
|
12825
12940
|
process.stderr.write(` The docs-only exception (#345) does not apply either: ${autonomyGate.docsOnly.reason}.\n`);
|
|
12941
|
+
if (autonomyGate.tuning) process.stderr.write(` Nor the tuning-only class (#561): ${autonomyGate.tuning.reason}.\n`);
|
|
12826
12942
|
process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
|
|
12827
12943
|
return 1;
|
|
12828
12944
|
}
|
|
@@ -13315,6 +13431,14 @@ function cmdShip(argv) {
|
|
|
13315
13431
|
return 1;
|
|
13316
13432
|
}
|
|
13317
13433
|
}
|
|
13434
|
+
if (autonomyGate.via === 'tuning') {
|
|
13435
|
+
const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
|
|
13436
|
+
if (!again.tuning) {
|
|
13437
|
+
cleanupEphemeral();
|
|
13438
|
+
process.stderr.write(`✗ B1: the tuning-only class (#561) no longer holds after B0 sync — ${again.reason}. A human must trigger Phase B. Nothing pushed.\n`);
|
|
13439
|
+
return 1;
|
|
13440
|
+
}
|
|
13441
|
+
}
|
|
13318
13442
|
|
|
13319
13443
|
// #350: B0 may have brought in paths (a pre-ship hook's regenerated files). The approval covered
|
|
13320
13444
|
// the core paths the table listed; a core path it did not list was never reviewed.
|
|
@@ -14993,6 +15117,54 @@ function cmdCiProfile(argv) {
|
|
|
14993
15117
|
return 0;
|
|
14994
15118
|
}
|
|
14995
15119
|
|
|
15120
|
+
// thresholds (#560) — the advisory thresholds this repo applies: its declared values, else the defaults.
|
|
15121
|
+
const HELP_THRESHOLDS = `colab thresholds [--repo <path>] [--json] [<name>]
|
|
15122
|
+
|
|
15123
|
+
The advisory thresholds this repo applies (#560): the value of each, and whether it is this
|
|
15124
|
+
repo's declared value or the handbook default. A repo overrides one in .github/project.yml:
|
|
15125
|
+
|
|
15126
|
+
thresholds:
|
|
15127
|
+
hot-file-count: 4
|
|
15128
|
+
|
|
15129
|
+
Nothing changes for a repo that declares nothing. Skills cite these by name — code-triage's
|
|
15130
|
+
hot-file count and dependents band, code-wrap's gate.smoke target — and read them here, so no
|
|
15131
|
+
skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
|
|
15132
|
+
and is listed under problems; the audit and the CI templates' descriptor check fail it.
|
|
15133
|
+
|
|
15134
|
+
<name> print only that threshold's value (a bare number, for a script or a skill)
|
|
15135
|
+
--json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
|
|
15136
|
+
|
|
15137
|
+
function cmdThresholds(argv) {
|
|
15138
|
+
const opts = parseArgs(argv, {
|
|
15139
|
+
values: { '--repo': 'repo' },
|
|
15140
|
+
flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
|
|
15141
|
+
});
|
|
15142
|
+
if (opts.help) return print(HELP_THRESHOLDS);
|
|
15143
|
+
const repoAbs = resolveRepo(opts);
|
|
15144
|
+
const r = thresholdsLib.parseThresholds(projectDoc(repoAbs));
|
|
15145
|
+
const name = opts._ && opts._[0];
|
|
15146
|
+
if (name !== undefined) {
|
|
15147
|
+
if (!thresholdsLib.SPEC[name]) throw new UserError(`unknown threshold ${name} — expected one of: ${Object.keys(thresholdsLib.SPEC).join(', ')} (run \`colab thresholds\` to list them)`);
|
|
15148
|
+
for (const p of r.problems) process.stderr.write(`! ${p}\n`);
|
|
15149
|
+
print(String(r.values[name]));
|
|
15150
|
+
return 0;
|
|
15151
|
+
}
|
|
15152
|
+
const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
|
|
15153
|
+
value: r.values[k], default: s.def, declared: !!r.declared[k], what: s.what, where: s.where,
|
|
15154
|
+
}]));
|
|
15155
|
+
if (opts.json) {
|
|
15156
|
+
print(JSON.stringify({ repo: shortRepo(repoAbs), thresholds: rows, problems: r.problems }, null, 2));
|
|
15157
|
+
return 0;
|
|
15158
|
+
}
|
|
15159
|
+
print(`thresholds ${shortRepo(repoAbs)}`);
|
|
15160
|
+
const w = Math.max(...Object.keys(rows).map((k) => k.length));
|
|
15161
|
+
for (const [k, row] of Object.entries(rows)) {
|
|
15162
|
+
print(` ${k.padEnd(w)} ${String(row.value).padStart(5)} ${row.declared ? `declared (default ${row.default})` : 'default'.padEnd(20)} ${row.what}`);
|
|
15163
|
+
}
|
|
15164
|
+
for (const p of r.problems) print(` ! ${p}`);
|
|
15165
|
+
return 0;
|
|
15166
|
+
}
|
|
15167
|
+
|
|
14996
15168
|
function cmdLanded(argv) {
|
|
14997
15169
|
const opts = parseArgs(argv, {
|
|
14998
15170
|
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
|
|
@@ -15782,6 +15954,8 @@ Commands:
|
|
|
15782
15954
|
wait; how a repo tunes ship-batch / ship-batch-wait (#554)
|
|
15783
15955
|
ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
|
|
15784
15956
|
derived from it — ci-wait's default deadline (#559)
|
|
15957
|
+
thresholds [<name>] [--json] the advisory thresholds this repo applies — declared in
|
|
15958
|
+
project.yml thresholds:, else the default (#560)
|
|
15785
15959
|
holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
|
|
15786
15960
|
have not landed on the base (filters the raw git-log
|
|
15787
15961
|
one-liner through \`landed\`'s content classification)
|
|
@@ -15868,6 +16042,7 @@ function main(argv) {
|
|
|
15868
16042
|
case 'landed': return cmdLanded(rest);
|
|
15869
16043
|
case 'batch-stats': return cmdBatchStats(rest);
|
|
15870
16044
|
case 'ci-profile': return cmdCiProfile(rest);
|
|
16045
|
+
case 'thresholds': return cmdThresholds(rest);
|
|
15871
16046
|
case 'trunk-ci': return cmdTrunkCi(rest);
|
|
15872
16047
|
case 'ci-wait': return cmdCiWait(rest);
|
|
15873
16048
|
case 'holders': return cmdHolders(rest);
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/config-set.js — a TUNING change to `.github/project.yml`, made and shipped cheaply (#561).
|
|
4
|
+
*
|
|
5
|
+
* Before this module, changing one repo-owned value (`ship-batch: 2`, a threshold) cost an issue, a
|
|
6
|
+
* code session, a wrap and a ship — the same ceremony as a feature. Repos that pay that much per
|
|
7
|
+
* tuning step do not tune. The descriptor stays committed (CI templates read it from the commit,
|
|
8
|
+
* worktrees are cut from git, and authority-granting fields need their review trail), so the cost is
|
|
9
|
+
* cut on two sides instead:
|
|
10
|
+
*
|
|
11
|
+
* 1. `colab config set <key> <value>` writes ONE tuning key, validated by the same parser every
|
|
12
|
+
* reader of that key uses, and commits it on a short branch — no checkout is touched.
|
|
13
|
+
* 2. `colab ship` computes a TUNING-ONLY class from the diff, modelled on the docs-only door
|
|
14
|
+
* (tools/lib/docs-only.js): no issue, no `Closes #N`, the evidence in the commit body, every
|
|
15
|
+
* other precondition unchanged.
|
|
16
|
+
*
|
|
17
|
+
* The allowlist and the authority list below are constants, so widening either is a handbook change
|
|
18
|
+
* reviewed in a commit — never a project.yml field, a flag or an env var. Every doubt resolves to
|
|
19
|
+
* "not tuning": a second file, a comment line, an authority key, a malformed value, a git read that
|
|
20
|
+
* failed. A false "no" costs a human click; a false "yes" lands an unreviewed change.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const yaml = require('./yaml');
|
|
24
|
+
const shipBatch = require('./ship-batch');
|
|
25
|
+
const ciProfile = require('./ci-profile');
|
|
26
|
+
const thresholds = require('./thresholds');
|
|
27
|
+
|
|
28
|
+
const DESCRIPTOR = '.github/project.yml';
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The tuning allowlist: key → the one validator every reader of that key already uses. Each returns
|
|
32
|
+
* a problem sentence, or null when the parsed descriptor's value is valid (absent counts as valid —
|
|
33
|
+
* removing a tuning key restores the documented default).
|
|
34
|
+
*/
|
|
35
|
+
const TUNING = Object.freeze({
|
|
36
|
+
'ship-batch': (doc) => { const r = shipBatch.parseShipBatch(doc); return r.valid ? null : r.reason; },
|
|
37
|
+
'ship-batch-wait': (doc) => { const r = shipBatch.parseShipBatchWait(doc); return r.valid ? null : r.reason; },
|
|
38
|
+
'ci-wait-factor': (doc) => { const r = ciProfile.parseFactor(doc); return r.valid ? null : r.reason; },
|
|
39
|
+
[thresholds.KEY]: (doc) => { const r = thresholds.parseThresholds(doc); return r.problems.length ? r.problems.join('; ') : null; },
|
|
40
|
+
});
|
|
41
|
+
const TUNING_KEYS = Object.freeze(Object.keys(TUNING));
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Never on this path: these grant authority or change what deploys (#561 §4). Listed so `config set`
|
|
45
|
+
* can say WHY it refuses them; any key outside TUNING is refused all the same.
|
|
46
|
+
*/
|
|
47
|
+
const AUTHORITY_KEYS = Object.freeze([
|
|
48
|
+
'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'trust-humans',
|
|
49
|
+
'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
|
|
50
|
+
]);
|
|
51
|
+
|
|
52
|
+
/** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`). */
|
|
53
|
+
const VALUE_RE = /^[A-Za-z0-9._-]+$/;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* `ship-batch` → `{ top: 'ship-batch', sub: null }`; `thresholds.hot-file-count` → `{ top:
|
|
57
|
+
* 'thresholds', sub: 'hot-file-count' }`. Returns `{ problem }` for anything outside the allowlist.
|
|
58
|
+
*/
|
|
59
|
+
function parseKeyPath(arg) {
|
|
60
|
+
const s = String(arg || '').trim();
|
|
61
|
+
const dot = s.indexOf('.');
|
|
62
|
+
const top = dot < 0 ? s : s.slice(0, dot);
|
|
63
|
+
const sub = dot < 0 ? null : s.slice(dot + 1);
|
|
64
|
+
if (AUTHORITY_KEYS.includes(top)) {
|
|
65
|
+
return { problem: `${top} grants authority or changes what deploys — it is never a tuning change; edit it on a branch with an issue and ship it the full way (#561)` };
|
|
66
|
+
}
|
|
67
|
+
if (!TUNING[top]) return { problem: `${s} is not a tuning key (tuning keys: ${TUNING_KEYS.join(', ')}, thresholds.<name>)` };
|
|
68
|
+
if (top === thresholds.KEY) {
|
|
69
|
+
if (!sub) return { problem: `${top} is a map — set one entry: ${top}.<name> (names: ${Object.keys(thresholds.SPEC).join(', ')})` };
|
|
70
|
+
if (!thresholds.SPEC[sub]) return { problem: `${top}.${sub} is not a known threshold (known: ${Object.keys(thresholds.SPEC).join(', ')})` };
|
|
71
|
+
} else if (sub !== null) {
|
|
72
|
+
return { problem: `${top} is a scalar — set it as ${top}, not ${s}` };
|
|
73
|
+
}
|
|
74
|
+
return { top, sub };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const isTopKeyLine = (line) => /^[^\s#][^:]*:/.test(line);
|
|
78
|
+
const topKeyOf = (line) => (isTopKeyLine(line) ? line.slice(0, line.indexOf(':')).trim() : null);
|
|
79
|
+
|
|
80
|
+
/** Replace a `key: value # comment` line's value, keeping the indent and the trailing comment. */
|
|
81
|
+
function replaceValue(line, value) {
|
|
82
|
+
const m = /^(\s*[^:#]+:)([ \t]*)([^#]*?)([ \t]*#.*)?$/.exec(line);
|
|
83
|
+
if (!m) return null;
|
|
84
|
+
return `${m[1]} ${value}${m[4] || ''}`;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Edit ONE tuning key in the descriptor's text, leaving every other byte alone. Returns `{ text,
|
|
89
|
+
* old }` (`old` is the previous raw value, or null when the key was absent), or `{ problem }`.
|
|
90
|
+
*/
|
|
91
|
+
function editText(text, keyPath, value) {
|
|
92
|
+
if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ -)` };
|
|
93
|
+
const src = String(text);
|
|
94
|
+
const eol = src.endsWith('\n') ? '' : '\n';
|
|
95
|
+
const lines = src.split('\n');
|
|
96
|
+
if (lines[lines.length - 1] === '') lines.pop();
|
|
97
|
+
const topIdx = lines.findIndex((l) => topKeyOf(l) === keyPath.top);
|
|
98
|
+
const blockEnd = (start) => { let j = start + 1; while (j < lines.length && !isTopKeyLine(lines[j]) && !/^#/.test(lines[j])) j++; return j; };
|
|
99
|
+
const restOf = (l) => l.slice(l.indexOf(':') + 1).replace(/[ \t]#.*$/, '').trim();
|
|
100
|
+
|
|
101
|
+
if (!keyPath.sub) {
|
|
102
|
+
if (topIdx < 0) return { text: `${src}${eol}${keyPath.top}: ${value}\n`, old: null };
|
|
103
|
+
const rest = restOf(lines[topIdx]);
|
|
104
|
+
if (rest === '' && blockEnd(topIdx) > topIdx + 1 && lines.slice(topIdx + 1, blockEnd(topIdx)).some((l) => l.trim() && !l.trim().startsWith('#'))) {
|
|
105
|
+
return { problem: `${keyPath.top} is written as a block in ${DESCRIPTOR} — edit it by hand` };
|
|
106
|
+
}
|
|
107
|
+
lines[topIdx] = replaceValue(lines[topIdx], value);
|
|
108
|
+
return { text: lines.join('\n') + '\n', old: rest === '' ? null : rest };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
if (topIdx < 0) return { text: `${src}${eol}${keyPath.top}:\n ${keyPath.sub}: ${value}\n`, old: null };
|
|
112
|
+
if (restOf(lines[topIdx]) !== '') return { problem: `${keyPath.top} is written inline in ${DESCRIPTOR} — edit it by hand` };
|
|
113
|
+
const end = blockEnd(topIdx);
|
|
114
|
+
let lastChild = topIdx, indent = ' ';
|
|
115
|
+
for (let j = topIdx + 1; j < end; j++) {
|
|
116
|
+
const l = lines[j];
|
|
117
|
+
if (!l.trim() || l.trim().startsWith('#')) continue;
|
|
118
|
+
const m = /^(\s+)([^:#]+):/.exec(l);
|
|
119
|
+
if (!m) return { problem: `${keyPath.top} has a line this command cannot read (${JSON.stringify(l)}) — edit it by hand` };
|
|
120
|
+
lastChild = j; indent = m[1];
|
|
121
|
+
if (m[2].trim() === keyPath.sub) {
|
|
122
|
+
const old = restOf(l);
|
|
123
|
+
lines[j] = replaceValue(l, value);
|
|
124
|
+
return { text: lines.join('\n') + '\n', old: old === '' ? null : old };
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
lines.splice(lastChild + 1, 0, `${indent}${keyPath.sub}: ${value}`);
|
|
128
|
+
return { text: lines.join('\n') + '\n', old: null };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** The value a key path resolves to in a parsed doc (undefined when absent). */
|
|
132
|
+
function valueAt(doc, keyPath) {
|
|
133
|
+
const top = doc ? doc[keyPath.top] : undefined;
|
|
134
|
+
if (!keyPath.sub) return top;
|
|
135
|
+
return top && typeof top === 'object' ? top[keyPath.sub] : undefined;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Line diff → the 0-based indices of changed lines on each side. A plain LCS: a descriptor is a few
|
|
140
|
+
* hundred lines at most, and a dependency-free diff keeps this module pure and testable.
|
|
141
|
+
*/
|
|
142
|
+
function changedLines(aText, bText) {
|
|
143
|
+
const a = String(aText).split('\n'), b = String(bText).split('\n');
|
|
144
|
+
const n = a.length, m = b.length;
|
|
145
|
+
const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
|
|
146
|
+
for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) {
|
|
147
|
+
dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
|
|
148
|
+
}
|
|
149
|
+
const del = [], add = [];
|
|
150
|
+
let i = 0, j = 0;
|
|
151
|
+
while (i < n && j < m) {
|
|
152
|
+
if (a[i] === b[j]) { i++; j++; } else if (dp[i + 1][j] >= dp[i][j + 1]) del.push(i++); else add.push(j++);
|
|
153
|
+
}
|
|
154
|
+
while (i < n) del.push(i++);
|
|
155
|
+
while (j < m) add.push(j++);
|
|
156
|
+
return { a, b, del, add };
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* The top-level key whose block holds line `idx`, or null for a top-level comment / a line before
|
|
161
|
+
* any key. A blank line is reported as `''` (harmless wherever it sits).
|
|
162
|
+
*/
|
|
163
|
+
function ownerOf(lines, idx) {
|
|
164
|
+
const l = lines[idx];
|
|
165
|
+
if (!l.trim()) return '';
|
|
166
|
+
if (/^#/.test(l)) return null;
|
|
167
|
+
for (let k = idx; k >= 0; k--) {
|
|
168
|
+
if (/^#/.test(lines[k])) return null; // a top-level comment ends the block above it
|
|
169
|
+
const key = topKeyOf(lines[k]);
|
|
170
|
+
if (key !== null) return key;
|
|
171
|
+
}
|
|
172
|
+
return null;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Is the change from `baseText` to `headText` (both the descriptor's full text) TUNING ONLY?
|
|
177
|
+
* `paths` are the changed entries for the whole diff — `[{ path, oldMode, newMode, binary }]`, the
|
|
178
|
+
* shape docs-only.js reads — so a second file anywhere refuses the class.
|
|
179
|
+
*
|
|
180
|
+
* Tuning only means: exactly one file changed, the descriptor, as a regular text file; every changed
|
|
181
|
+
* non-blank line sits inside a tuning key's block; every other key parses identical on both sides;
|
|
182
|
+
* and every tuning key that moved holds a valid value (or is absent) at head.
|
|
183
|
+
*
|
|
184
|
+
* Returns `{ tuning, keys, reason }` — `reason` is one line for a human, set on both outcomes.
|
|
185
|
+
*/
|
|
186
|
+
function classify({ entries, baseText, headText }) {
|
|
187
|
+
const no = (reason, keys = []) => ({ tuning: false, keys, reason });
|
|
188
|
+
const files = [...new Set((entries || []).map((e) => e.path))];
|
|
189
|
+
if (!files.length) return no('empty diff — nothing to call tuning');
|
|
190
|
+
if (files.length !== 1 || files[0] !== DESCRIPTOR) {
|
|
191
|
+
const other = files.filter((f) => f !== DESCRIPTOR);
|
|
192
|
+
return no(`changes ${other.length ? other.slice(0, 3).join(', ') + (other.length > 3 ? ` +${other.length - 3} more` : '') : files.join(', ')} — a tuning change touches ${DESCRIPTOR} alone`);
|
|
193
|
+
}
|
|
194
|
+
for (const e of entries) {
|
|
195
|
+
if (e.binary) return no(`${DESCRIPTOR} reads as binary`);
|
|
196
|
+
if ((e.oldMode && e.oldMode !== '100644' && e.oldMode !== '000000') || (e.newMode && e.newMode !== '100644')) {
|
|
197
|
+
return no(`${DESCRIPTOR} mode change (${e.oldMode} → ${e.newMode})`);
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
if (typeof baseText !== 'string' || typeof headText !== 'string') return no(`could not read ${DESCRIPTOR} on both sides`);
|
|
201
|
+
|
|
202
|
+
const d = changedLines(baseText, headText);
|
|
203
|
+
const owners = new Set();
|
|
204
|
+
for (const [lines, idxs] of [[d.a, d.del], [d.b, d.add]]) {
|
|
205
|
+
for (const idx of idxs) {
|
|
206
|
+
const o = ownerOf(lines, idx);
|
|
207
|
+
if (o === '') continue;
|
|
208
|
+
if (o === null) return no(`line ${JSON.stringify(lines[idx].slice(0, 60))} is a top-level comment or sits outside any key`);
|
|
209
|
+
owners.add(o);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
if (!owners.size) return no('only blank lines changed — nothing to call tuning');
|
|
213
|
+
const offending = [...owners].filter((k) => !TUNING[k]);
|
|
214
|
+
if (offending.length) {
|
|
215
|
+
const auth = offending.filter((k) => AUTHORITY_KEYS.includes(k));
|
|
216
|
+
return no(`${offending.join(', ')} ${offending.length > 1 ? 'are' : 'is'} not a tuning key${auth.length ? ` (${auth.join(', ')} grant${auth.length > 1 ? '' : 's'} authority)` : ''}`, [...owners]);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
let base, head;
|
|
220
|
+
try { base = yaml.parse(baseText) || {}; head = yaml.parse(headText) || {}; } catch (e) { return no(`${DESCRIPTOR} does not parse: ${e.message}`); }
|
|
221
|
+
const keys = [...new Set([...Object.keys(base), ...Object.keys(head)])];
|
|
222
|
+
const moved = keys.filter((k) => JSON.stringify(base[k]) !== JSON.stringify(head[k]));
|
|
223
|
+
const nonTuning = moved.filter((k) => !TUNING[k]);
|
|
224
|
+
if (nonTuning.length) return no(`${nonTuning.join(', ')} changed value — not a tuning key`, moved);
|
|
225
|
+
if (!moved.length) return no('no value changed — formatting alone is not a tuning change');
|
|
226
|
+
const bad = moved.map((k) => TUNING[k](head)).filter(Boolean);
|
|
227
|
+
if (bad.length) return no(`malformed tuning value: ${bad.join('; ')}`, moved);
|
|
228
|
+
return { tuning: true, keys: moved, reason: `tuning-only (${moved.join(', ')})` };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* The branch shape, with I/O: what `branch` changes relative to its merge base with `base` — the
|
|
233
|
+
* same three-dot diff the squash would land, read through docs-only.js's entry reader so both doors
|
|
234
|
+
* judge one diff. `git` is tools/lib/git.js (or a fake with its `git()` shape).
|
|
235
|
+
*/
|
|
236
|
+
function branchTuning(git, repo, base, branch) {
|
|
237
|
+
const docsOnly = require('./docs-only');
|
|
238
|
+
const entries = docsOnly.readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
|
|
239
|
+
if (!entries) return { tuning: false, keys: [], reason: `could not read the diff ${base}...${branch}` };
|
|
240
|
+
const mb = git.git(['merge-base', base, branch], repo);
|
|
241
|
+
if (!mb.ok) return { tuning: false, keys: [], reason: `no merge base between ${base} and ${branch}` };
|
|
242
|
+
const show = (ref) => { const r = git.git(['show', `${ref}:${DESCRIPTOR}`], repo); return r.ok ? r.stdout : (/does not exist|exists on disk, but not in/.test(r.stderr || '') ? '' : null); };
|
|
243
|
+
return classify({ entries, baseText: show(mb.stdout.trim()), headText: show(branch) });
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Commit `text` as the descriptor on top of `baseSha`, as branch `branch`, WITHOUT touching any
|
|
248
|
+
* working tree or the repo's own index: a scratch index (GIT_INDEX_FILE) holds the tree. The main
|
|
249
|
+
* checkout stays on trunk at rest, which a `git checkout -b` here would break (CONVENTIONS.md §4).
|
|
250
|
+
* The ref is created only if absent (`update-ref <ref> <sha> ""`), so a concurrent run cannot
|
|
251
|
+
* overwrite a branch someone else just made. Returns `{ ok, sha, error }`.
|
|
252
|
+
*/
|
|
253
|
+
function commitOnBranch(repo, { baseSha, text, message, branch }) {
|
|
254
|
+
const { spawnSync } = require('child_process');
|
|
255
|
+
const fs = require('fs');
|
|
256
|
+
const os = require('os');
|
|
257
|
+
const path = require('path');
|
|
258
|
+
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-config-set-'));
|
|
259
|
+
const env = { ...process.env, GIT_INDEX_FILE: path.join(tmp, 'index') };
|
|
260
|
+
const run = (args, input) => {
|
|
261
|
+
const r = spawnSync('git', args, { cwd: repo, env, encoding: 'utf8', ...(input !== undefined ? { input } : {}) });
|
|
262
|
+
return { ok: r.status === 0, out: String(r.stdout || '').trim(), err: String(r.stderr || '').trim() };
|
|
263
|
+
};
|
|
264
|
+
try {
|
|
265
|
+
const rt = run(['read-tree', baseSha]);
|
|
266
|
+
if (!rt.ok) return { ok: false, error: `read-tree ${baseSha}: ${rt.err}` };
|
|
267
|
+
const blob = run(['hash-object', '-w', '--stdin'], text);
|
|
268
|
+
if (!blob.ok) return { ok: false, error: `hash-object: ${blob.err}` };
|
|
269
|
+
const up = run(['update-index', '--add', '--cacheinfo', `100644,${blob.out},${DESCRIPTOR}`]);
|
|
270
|
+
if (!up.ok) return { ok: false, error: `update-index: ${up.err}` };
|
|
271
|
+
const tree = run(['write-tree']);
|
|
272
|
+
if (!tree.ok) return { ok: false, error: `write-tree: ${tree.err}` };
|
|
273
|
+
const commit = run(['commit-tree', tree.out, '-p', baseSha, '-F', '-'], message);
|
|
274
|
+
if (!commit.ok) return { ok: false, error: `commit-tree: ${commit.err}` };
|
|
275
|
+
const ref = run(['update-ref', `refs/heads/${branch}`, commit.out, '']);
|
|
276
|
+
if (!ref.ok) return { ok: false, error: `update-ref refs/heads/${branch}: ${ref.err}` };
|
|
277
|
+
return { ok: true, sha: commit.out };
|
|
278
|
+
} finally {
|
|
279
|
+
fs.rmSync(tmp, { recursive: true, force: true });
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/** The descriptor's exact text at `ref` (no trimming — it becomes a blob), '' when absent, null on a git error. */
|
|
284
|
+
function descriptorAt(repo, ref) {
|
|
285
|
+
const { spawnSync } = require('child_process');
|
|
286
|
+
const r = spawnSync('git', ['show', `${ref}:${DESCRIPTOR}`], { cwd: repo, encoding: 'utf8' });
|
|
287
|
+
if (r.status === 0) return String(r.stdout);
|
|
288
|
+
return /does not exist|exists on disk, but not in/.test(String(r.stderr || '')) ? '' : null;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Does `colab config set <key>` mean THIS repo's descriptor (#561) rather than the machine-local
|
|
293
|
+
* config? Machine keys are camelCase (`claimTTLHours`); descriptor keys are kebab-case. An authority
|
|
294
|
+
* key routes here too, so its refusal names the reason instead of "unknown config key".
|
|
295
|
+
*/
|
|
296
|
+
function isDescriptorKey(arg) {
|
|
297
|
+
const s = String(arg || '');
|
|
298
|
+
const top = s.split('.')[0];
|
|
299
|
+
return !!TUNING[top] || AUTHORITY_KEYS.includes(top) || /[-.]/.test(s);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/** `chore/tune-<key>` — never ending in a digit group, which `colab ship` would read as an issue number. */
|
|
303
|
+
function branchName(keyPath) {
|
|
304
|
+
const slug = [keyPath.top, keyPath.sub].filter(Boolean).join('-').toLowerCase().replace(/[^a-z0-9-]+/g, '-');
|
|
305
|
+
return `chore/tune-${slug}`;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** The commit message: a conventional subject, the evidence in the body (#561). */
|
|
309
|
+
function commitMessage(keyPath, oldValue, value, evidence) {
|
|
310
|
+
const name = [keyPath.top, keyPath.sub].filter(Boolean).join('.');
|
|
311
|
+
return `chore(project): ${name} ${oldValue === null || oldValue === undefined ? '(unset)' : oldValue} → ${value}\n\n` +
|
|
312
|
+
`Tuning-only change to ${DESCRIPTOR}, written by \`colab config set\` (#561).\n\n` +
|
|
313
|
+
`Evidence: ${String(evidence).trim()}\n`;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
module.exports = {
|
|
317
|
+
DESCRIPTOR, TUNING, TUNING_KEYS, AUTHORITY_KEYS,
|
|
318
|
+
parseKeyPath, editText, valueAt, changedLines, ownerOf, classify, branchTuning, commitOnBranch, descriptorAt, isDescriptorKey, branchName, commitMessage,
|
|
319
|
+
};
|
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
|
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -166,5 +166,5 @@ function directChanges(git, repo, trunk, since) {
|
|
|
166
166
|
|
|
167
167
|
module.exports = {
|
|
168
168
|
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
169
|
-
pathReason, classify, parseRaw, parseBinary, branchChanges, directChanges,
|
|
169
|
+
pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
|
|
170
170
|
};
|
|
@@ -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 };
|