@futurelastic/colab-handbook 1.13.0-rc.27 → 1.13.0-rc.29
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/README.vi.md +1 -1
- package/audit/audit.mjs +65 -1
- package/package.json +1 -1
- package/templates/ci-laravel.yml +7 -4
- package/templates/ci-node.yml +7 -4
- package/templates/ci-python.yml +7 -4
- package/tools/colab +145 -15
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +5 -1
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/thresholds.js +20 -8
package/README.md
CHANGED
|
@@ -244,7 +244,7 @@ migration hold with or without it.
|
|
|
244
244
|
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
245
245
|
| [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. Nothing is called remotely — copy it, edit it, own it. |
|
|
246
246
|
| [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Command reference: [`tools/README.md`](tools/README.md). |
|
|
247
|
-
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
|
|
247
|
+
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. What each check means: [`audit/README.md`](audit/README.md). |
|
|
248
248
|
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Plain `SKILL.md` folders; `install.sh` links them into each coding agent you choose. |
|
|
249
249
|
| [`engines/`](engines/) | One small data file per coding agent: where its user-level skills go, how a skill is invoked, what it supports. Adding an engine is adding a file — [`engines/README.md`](engines/README.md). |
|
|
250
250
|
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
|
package/README.vi.md
CHANGED
|
@@ -243,7 +243,7 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
243
243
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
244
244
|
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
|
|
245
245
|
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
|
|
246
|
-
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
246
|
+
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
247
247
|
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). Là các thư mục `SKILL.md` thuần; `install.sh` link chúng vào từng coding agent bạn chọn. |
|
|
248
248
|
| [`engines/`](engines/) | Mỗi coding agent một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm engine là thêm một file — [`engines/README.md`](engines/README.md). |
|
|
249
249
|
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
|
package/audit/audit.mjs
CHANGED
|
@@ -37,6 +37,8 @@
|
|
|
37
37
|
// node audit.mjs --identity # also scan PUBLIC repository METADATA (description,
|
|
38
38
|
// # topics, homepage, name) against the operator's
|
|
39
39
|
// # private identity vocabulary — see "Identity" below
|
|
40
|
+
// node audit.mjs --batch-history # also read each local repo's batch landing history
|
|
41
|
+
// # (colab batch-stats --json) — see "Batch history" below
|
|
40
42
|
//
|
|
41
43
|
// Identity (--identity): metadata never passes through git, so the pre-commit identity scan
|
|
42
44
|
// (templates/pre-commit-identity) structurally cannot see it, and it is the first thing a
|
|
@@ -45,6 +47,13 @@
|
|
|
45
47
|
// vocabulary — and is never shipped, printed, or written into a report. Off unless asked
|
|
46
48
|
// for: it needs the network, and a fleet sweep must stay runnable offline.
|
|
47
49
|
//
|
|
50
|
+
// Batch history (--batch-history, #556): per LOCAL repo, the measured batch picture from
|
|
51
|
+
// `colab batch-stats --json` — overlap of serial landings with a partner inside their trunk-CI
|
|
52
|
+
// cycle, batch fill, first-attempt green rate, eviction rate. Shown, never judged on its own:
|
|
53
|
+
// an advisory is raised ONLY against a `batch-*` value the repo declares under `thresholds:`
|
|
54
|
+
// in project.yml, and none of those has a default. Off unless asked for, like --identity: it
|
|
55
|
+
// reads the CI history over the network (one API listing per day of the window).
|
|
56
|
+
//
|
|
48
57
|
// Exit code: 0 when every repo passes, 1 when any repo has a finding, 2 on a usage
|
|
49
58
|
// error. Findings never crash the run — a repo missing project.yml is a result, not
|
|
50
59
|
// an exception.
|
|
@@ -100,6 +109,7 @@ const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFir
|
|
|
100
109
|
const shipBatch = require("../tools/lib/ship-batch.js");
|
|
101
110
|
const ciProfile = require("../tools/lib/ci-profile.js"); // #559
|
|
102
111
|
const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
|
|
112
|
+
const batchHistory = require("../tools/lib/batch-history.js"); // #556
|
|
103
113
|
// #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
|
|
104
114
|
// validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
|
|
105
115
|
const migrationPaths = require("../tools/lib/migration-paths.js");
|
|
@@ -140,12 +150,13 @@ const COLAB_HOME = process.env.COLAB_HOME || join(homedir(), ".colab");
|
|
|
140
150
|
|
|
141
151
|
function parseArgs(argv) {
|
|
142
152
|
// config === null means "resolve from the precedence chain"; a string means explicit.
|
|
143
|
-
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false };
|
|
153
|
+
const opts = { config: null, locals: [], slugs: [], json: false, quiet: false, help: false, identity: false, batchHistory: false };
|
|
144
154
|
for (let i = 0; i < argv.length; i++) {
|
|
145
155
|
const a = argv[i];
|
|
146
156
|
if (a === "--json") opts.json = true;
|
|
147
157
|
else if (a === "--quiet" || a === "-q") opts.quiet = true;
|
|
148
158
|
else if (a === "--identity") opts.identity = true;
|
|
159
|
+
else if (a === "--batch-history") opts.batchHistory = true;
|
|
149
160
|
else if (a === "--local") {
|
|
150
161
|
const p = argv[++i];
|
|
151
162
|
if (!p) die("--local needs a path");
|
|
@@ -1997,6 +2008,9 @@ function auditRepo(target, ctx) {
|
|
|
1997
2008
|
// read by every visitor, and it is subject to the rule it publishes.
|
|
1998
2009
|
if (ctx.identity) checkIdentityMetadata(src, ctx.identity, info, fail);
|
|
1999
2010
|
|
|
2011
|
+
// ---- batch history (#556) ------------------------------------------------------
|
|
2012
|
+
checkBatchHistory(src, target, cfg, ctx, info, warn);
|
|
2013
|
+
|
|
2000
2014
|
function finish() {
|
|
2001
2015
|
info.findings = findings;
|
|
2002
2016
|
info.ok = !findings.some((f) => f.level === "fail");
|
|
@@ -2006,6 +2020,43 @@ function auditRepo(target, ctx) {
|
|
|
2006
2020
|
return finish();
|
|
2007
2021
|
}
|
|
2008
2022
|
|
|
2023
|
+
/**
|
|
2024
|
+
* #556 — the repo's measured batch picture, from `colab batch-stats --json` (this handbook's own
|
|
2025
|
+
* CLI, so the audit and the command read history the same way). Writes `info.batchHistory` on every
|
|
2026
|
+
* path. The picture is never a finding; an advisory is raised only for a `batch-*` threshold the
|
|
2027
|
+
* repo declares (tools/lib/batch-history.js judge — no defaults, by the owner's ruling). A run that
|
|
2028
|
+
* was asked for and could not read the history warns: a quiet row must not read as "checked".
|
|
2029
|
+
*/
|
|
2030
|
+
function checkBatchHistory(src, target, cfg, ctx, info, warn) {
|
|
2031
|
+
const declared = batchHistory.declaredBatchKeys(cfg);
|
|
2032
|
+
if (!ctx.batchHistory) {
|
|
2033
|
+
info.batchHistory = { status: "not-requested", declared };
|
|
2034
|
+
return;
|
|
2035
|
+
}
|
|
2036
|
+
if (src.kind !== "local") {
|
|
2037
|
+
info.batchHistory = { status: "not-applicable", reason: "batch-stats reads a clone's trunk log — audit a local path", declared };
|
|
2038
|
+
return;
|
|
2039
|
+
}
|
|
2040
|
+
let rep;
|
|
2041
|
+
try {
|
|
2042
|
+
const out = execFileSync(process.execPath, [join(HANDBOOK_ROOT, "tools", "colab"), "batch-stats", "--repo", resolve(target.path), "--json"],
|
|
2043
|
+
{ encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 600_000, maxBuffer: 64 * 1024 * 1024 });
|
|
2044
|
+
rep = JSON.parse(out);
|
|
2045
|
+
} catch (err) {
|
|
2046
|
+
const why = String((err.stderr || err.message || "")).trim().split("\n").pop() || "no output";
|
|
2047
|
+
info.batchHistory = { status: "unreadable", reason: why, declared };
|
|
2048
|
+
warn(`batch history: colab batch-stats could not read it (${why}) — nothing was measured or judged`);
|
|
2049
|
+
return;
|
|
2050
|
+
}
|
|
2051
|
+
const measured = batchHistory.measure(rep);
|
|
2052
|
+
const verdict = batchHistory.judge(rep, cfg, measured);
|
|
2053
|
+
info.batchHistory = {
|
|
2054
|
+
status: "read", since: rep.since, until: rep.until, landings: rep.landings, measured,
|
|
2055
|
+
picture: batchHistory.picture(rep, measured), declared, judged: verdict.judged, unjudged: verdict.unjudged, notes: rep.notes || [],
|
|
2056
|
+
};
|
|
2057
|
+
verdict.advisories.forEach(warn);
|
|
2058
|
+
}
|
|
2059
|
+
|
|
2009
2060
|
/**
|
|
2010
2061
|
* #228 part 4 — the identity scan of REPOSITORY METADATA: name, description, homepage and
|
|
2011
2062
|
* topics. None of it passes through git, so the pre-commit scan cannot see any of it, and it
|
|
@@ -3110,6 +3161,7 @@ function report(results, opts, ctx) {
|
|
|
3110
3161
|
identity: ctx.identity
|
|
3111
3162
|
? { scanned: true, vocabulary: ctx.identity.path, source: ctx.identity.source, terms: ctx.identity.count }
|
|
3112
3163
|
: { scanned: false, reason: "not requested (--identity)" },
|
|
3164
|
+
batchHistory: ctx.batchHistory ? { read: true } : { read: false, reason: "not requested (--batch-history)" },
|
|
3113
3165
|
results,
|
|
3114
3166
|
}, null, 2));
|
|
3115
3167
|
return;
|
|
@@ -3126,6 +3178,11 @@ function report(results, opts, ctx) {
|
|
|
3126
3178
|
console.log(ctx.identity
|
|
3127
3179
|
? `identity: ${ctx.identity.count} term(s) from ${ctx.identity.path} (${ctx.identity.source}) — public repository metadata scanned`
|
|
3128
3180
|
: "identity: repository metadata NOT scanned (pass --identity)");
|
|
3181
|
+
// #556: same once-per-run statement for batch history — a per-repo line on every offline run
|
|
3182
|
+
// would make every row non-clean for a read nobody asked for.
|
|
3183
|
+
console.log(ctx.batchHistory
|
|
3184
|
+
? "batch: batch landing history read per local repo (colab batch-stats); advisories only against declared thresholds"
|
|
3185
|
+
: "batch: batch landing history NOT read (pass --batch-history)");
|
|
3129
3186
|
console.log("");
|
|
3130
3187
|
|
|
3131
3188
|
const shown = opts.quiet ? results.filter((r) => !r.clean) : results;
|
|
@@ -3145,6 +3202,12 @@ function report(results, opts, ctx) {
|
|
|
3145
3202
|
else if (r.adoption === "local") lines.push(`⌂ adopted locally, not committed — descriptor hidden by .git/info/exclude; a repo the fleet does not own (CONVENTIONS.md §9)${r.clean ? " ✓" : ""}`);
|
|
3146
3203
|
else if (r.clean) lines.push("✓");
|
|
3147
3204
|
r.findings.forEach((f) => lines.push(`${f.level === "fail" ? "⚠" : "·"} ${f.text}`));
|
|
3205
|
+
// #556: the measured picture — information, not a finding, so it never changes clean/ok.
|
|
3206
|
+
if (r.batchHistory?.status === "read") {
|
|
3207
|
+
r.batchHistory.picture.forEach((l) => lines.push(`▸ ${l}`));
|
|
3208
|
+
if (!r.batchHistory.declared.length) lines.push("▸ no batch-* thresholds declared — shown, not judged");
|
|
3209
|
+
r.batchHistory.unjudged.forEach((u) => lines.push(`▸ thresholds.${u.key} not judged: ${u.why}`));
|
|
3210
|
+
} else if (r.batchHistory?.status === "not-applicable") lines.push(`▸ batch history: ${r.batchHistory.reason}`);
|
|
3148
3211
|
|
|
3149
3212
|
// Repeat the name on every line so the output stays greppable.
|
|
3150
3213
|
lines.forEach((l, i) => console.log(`${i === 0 ? head : cont} ${l}`));
|
|
@@ -3203,6 +3266,7 @@ function runAudit(opts) {
|
|
|
3203
3266
|
|
|
3204
3267
|
const ctx = { handbook: handbookInfo(HANDBOOK_ROOT), templateNames: templateNames(HANDBOOK_ROOT) };
|
|
3205
3268
|
ctx.identity = opts.identity ? loadIdentityVocabulary() : null;
|
|
3269
|
+
ctx.batchHistory = !!opts.batchHistory;
|
|
3206
3270
|
|
|
3207
3271
|
const results = [];
|
|
3208
3272
|
for (const t of targets) {
|
package/package.json
CHANGED
package/templates/ci-laravel.yml
CHANGED
|
@@ -297,7 +297,8 @@ jobs:
|
|
|
297
297
|
fi ;;
|
|
298
298
|
esac
|
|
299
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),
|
|
300
|
+
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
301
|
+
# which a test holds this list to.
|
|
301
302
|
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
302
303
|
bad=0
|
|
303
304
|
while IFS= read -r t; do
|
|
@@ -307,18 +308,20 @@ jobs:
|
|
|
307
308
|
esac
|
|
308
309
|
k="${t%%:*}"
|
|
309
310
|
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
311
|
+
max=999999999
|
|
310
312
|
case "$k" in
|
|
311
313
|
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
312
|
-
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
314
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
|
|
313
315
|
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
316
|
+
batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
|
|
314
317
|
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
315
318
|
bad=1; continue ;;
|
|
316
319
|
esac
|
|
317
320
|
case "$n" in ''|'~'|null) continue ;; esac
|
|
318
|
-
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
321
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
|
|
319
322
|
echo "thresholds.$k: $n — ok"
|
|
320
323
|
else
|
|
321
|
-
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number
|
|
324
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number from $min to $max. Every reader ignores it (a batch-* key is then not judged; any other uses its default). See project.schema.md, thresholds."
|
|
322
325
|
bad=1
|
|
323
326
|
fi
|
|
324
327
|
done < <(awk '
|
package/templates/ci-node.yml
CHANGED
|
@@ -292,7 +292,8 @@ jobs:
|
|
|
292
292
|
fi ;;
|
|
293
293
|
esac
|
|
294
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),
|
|
295
|
+
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
296
|
+
# which a test holds this list to.
|
|
296
297
|
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
297
298
|
bad=0
|
|
298
299
|
while IFS= read -r t; do
|
|
@@ -302,18 +303,20 @@ jobs:
|
|
|
302
303
|
esac
|
|
303
304
|
k="${t%%:*}"
|
|
304
305
|
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
306
|
+
max=999999999
|
|
305
307
|
case "$k" in
|
|
306
308
|
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
307
|
-
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
309
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
|
|
308
310
|
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
311
|
+
batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
|
|
309
312
|
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
310
313
|
bad=1; continue ;;
|
|
311
314
|
esac
|
|
312
315
|
case "$n" in ''|'~'|null) continue ;; esac
|
|
313
|
-
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
316
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
|
|
314
317
|
echo "thresholds.$k: $n — ok"
|
|
315
318
|
else
|
|
316
|
-
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number
|
|
319
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number from $min to $max. Every reader ignores it (a batch-* key is then not judged; any other uses its default). See project.schema.md, thresholds."
|
|
317
320
|
bad=1
|
|
318
321
|
fi
|
|
319
322
|
done < <(awk '
|
package/templates/ci-python.yml
CHANGED
|
@@ -283,7 +283,8 @@ jobs:
|
|
|
283
283
|
fi ;;
|
|
284
284
|
esac
|
|
285
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),
|
|
286
|
+
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
287
|
+
# which a test holds this list to.
|
|
287
288
|
# A bad entry falls back to the default everywhere, silently, so it fails here.
|
|
288
289
|
bad=0
|
|
289
290
|
while IFS= read -r t; do
|
|
@@ -293,18 +294,20 @@ jobs:
|
|
|
293
294
|
esac
|
|
294
295
|
k="${t%%:*}"
|
|
295
296
|
n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
297
|
+
max=999999999
|
|
296
298
|
case "$k" in
|
|
297
299
|
hot-file-count|claude-md-line-multiple) min=2 ;;
|
|
298
|
-
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
|
|
300
|
+
dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days|batch-min-samples) min=1 ;;
|
|
299
301
|
claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
|
|
302
|
+
batch-first-green-pct-min|batch-eviction-pct-max|batch-overlap-pct) min=0 max=100 ;;
|
|
300
303
|
*) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
|
|
301
304
|
bad=1; continue ;;
|
|
302
305
|
esac
|
|
303
306
|
case "$n" in ''|'~'|null) continue ;; esac
|
|
304
|
-
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
|
|
307
|
+
if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ] && [ "$n" -le "$max" ]; then
|
|
305
308
|
echo "thresholds.$k: $n — ok"
|
|
306
309
|
else
|
|
307
|
-
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number
|
|
310
|
+
echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number from $min to $max. Every reader ignores it (a batch-* key is then not judged; any other uses its default). See project.schema.md, thresholds."
|
|
308
311
|
bad=1
|
|
309
312
|
fi
|
|
310
313
|
done < <(awk '
|
package/tools/colab
CHANGED
|
@@ -68,6 +68,7 @@ const shipBatch = require('./lib/ship-batch');
|
|
|
68
68
|
const batchStats = require('./lib/batch-stats');
|
|
69
69
|
const conflictMarkers = require('./lib/conflict-markers');
|
|
70
70
|
const docsOnly = require('./lib/docs-only');
|
|
71
|
+
const configSet = require('./lib/config-set'); // #561
|
|
71
72
|
const cureDiff = require('./lib/cure-diff');
|
|
72
73
|
const codeowners = require('./lib/codeowners');
|
|
73
74
|
const releasePolicy = require('./lib/release-policy');
|
|
@@ -7657,6 +7658,10 @@ const HELP_CONFIG = `colab config [show|add-repo <path>|rm-repo <path>|add-reser
|
|
|
7657
7658
|
rm-notify-url <url> remove one receiver from notifyUrl; removing the last unsets the key
|
|
7658
7659
|
set <key> <value> set claimTTLHours | plannerClaimTTLMinutes | portRange | worktreeSubdir | notifyUrl | journal |
|
|
7659
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
|
|
7660
7665
|
|
|
7661
7666
|
notifyUrl is OPTIONAL and off by default: unset, colab makes no network call of its own. Set it to
|
|
7662
7667
|
an http(s) endpoint and claim / release / ship / worktree new / worktree rm each push one small
|
|
@@ -7684,6 +7689,91 @@ changes on resume makes that session's own earlier claim comment read as a diffe
|
|
|
7684
7689
|
it will yield to itself. Unset it again with: colab config set claimIdentity ""
|
|
7685
7690
|
`;
|
|
7686
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
|
+
|
|
7687
7777
|
function cmdConfig(argv) {
|
|
7688
7778
|
const sub = argv[0];
|
|
7689
7779
|
const cfg = state.loadConfig();
|
|
@@ -7741,6 +7831,7 @@ function cmdConfig(argv) {
|
|
|
7741
7831
|
print(`notifyUrl = ${urls.length ? urls.join(', ') : '(unset)'}`);
|
|
7742
7832
|
return 0;
|
|
7743
7833
|
}
|
|
7834
|
+
if (sub === 'set' && argv[1] && configSet.isDescriptorKey(argv[1])) return cmdConfigSetDescriptor(argv.slice(1)); // #561
|
|
7744
7835
|
if (sub === 'set') {
|
|
7745
7836
|
const [k, v] = [argv[1], argv[2]];
|
|
7746
7837
|
if (!k || v === undefined) throw new UserError('set needs <key> <value>');
|
|
@@ -10122,6 +10213,7 @@ promotes is an integration event of the same weight as a promotion, and stays hu
|
|
|
10122
10213
|
|
|
10123
10214
|
Sequence (each step gated; any failure aborts before the push — the target is never half-shipped):
|
|
10124
10215
|
a. autonomy gate repo must grant auto-trunk (no --force override) — or the diff is docs-only (#345)
|
|
10216
|
+
or tuning-only (#561)
|
|
10125
10217
|
— or a person runs ship through the human door (#525): a confirmed interactive
|
|
10126
10218
|
terminal, or COLAB_HUMAN=1 + --answered-by <name>. An agent shell is no terminal.
|
|
10127
10219
|
b. preconditions target CI alive+green (UNLESS the branch proves the CURE RULE, #281 — no
|
|
@@ -10298,6 +10390,14 @@ auto-trunk). The row reads "docs-only (N files) — autonomy exception", and --d
|
|
|
10298
10390
|
\`autonomyGate: { via, docsOnly }\`. After B0 sync the diff is measured again before the squash.
|
|
10299
10391
|
Every other precondition is unchanged. No flag, env var or project.yml field widens the list.
|
|
10300
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
|
+
|
|
10301
10401
|
TRUNK-DIRECT — \`colab ship --direct\` (#302). A unit committed straight to trunk has no branch and
|
|
10302
10402
|
no worktree, so neither door above can find it, and evidence-close's own detection cannot fire
|
|
10303
10403
|
(\`landed\` is \`unknown\` when base === branch). --direct is its close path: the claims are this
|
|
@@ -11775,7 +11875,8 @@ function cmdShipDryJson(opts) {
|
|
|
11775
11875
|
|
|
11776
11876
|
// ---- (a) AUTONOMY GATE — does NOT short-circuit here; an unattended caller wants the whole table ----
|
|
11777
11877
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
11778
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
11878
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
11879
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
11779
11880
|
autonomyGatePayloadVal = autonomyGatePayload(autonomyGate);
|
|
11780
11881
|
checks.push({ name: 'autonomy granted', ok: autonomyGate.ok, class: autonomyGate.ok ? null : HUMAN_GATED, detail: autonomyGate.detail });
|
|
11781
11882
|
|
|
@@ -12656,23 +12757,33 @@ function shipOpenCorePr(repoAbs, cr, { target, branch, title, body }) {
|
|
|
12656
12757
|
* caller asserts nothing. `readDocsOnly` is a thunk, so an auto-trunk repo never pays for the
|
|
12657
12758
|
* diff read. Every other precondition is untouched — this relaxes the autonomy gate, not the checks.
|
|
12658
12759
|
*
|
|
12659
|
-
*
|
|
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 }`.
|
|
12660
12766
|
*/
|
|
12661
|
-
function shipAutonomyGate(doc, readDocsOnly, door = null) {
|
|
12767
|
+
function shipAutonomyGate(doc, readDocsOnly, door = null, readTuning = null) {
|
|
12662
12768
|
const declared = doc.autonomy ? String(doc.autonomy) : 'absent';
|
|
12663
|
-
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' };
|
|
12664
12770
|
const verdict = readDocsOnly();
|
|
12665
12771
|
if (verdict.docsOnly) {
|
|
12666
|
-
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)` };
|
|
12667
12777
|
}
|
|
12668
12778
|
// #525: the human door — the person running ship IS the go (ruling on #525, option 1). Checked
|
|
12669
|
-
// after docs-only, so
|
|
12779
|
+
// after docs-only and tuning, so either keeps its own (agent-usable) door and record.
|
|
12670
12780
|
if (door && door.open) {
|
|
12671
|
-
return { ok: true, via: 'human', declared, docsOnly: verdict, human: door,
|
|
12781
|
+
return { ok: true, via: 'human', declared, docsOnly: verdict, tuning, human: door,
|
|
12672
12782
|
detail: `human door (#525): ${door.why} — project.yml autonomy: ${declared}` };
|
|
12673
12783
|
}
|
|
12674
|
-
return { ok: false, via: null, declared, docsOnly: verdict, human: door,
|
|
12675
|
-
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'})` };
|
|
12676
12787
|
}
|
|
12677
12788
|
|
|
12678
12789
|
/** #525: the human-door refusal lines — what a person runs, never just "a human must". */
|
|
@@ -12731,8 +12842,10 @@ function shipHumanDoorGo(gate, opts, what) {
|
|
|
12731
12842
|
function autonomyGatePayload(gate) {
|
|
12732
12843
|
// #525: `human` is additive and present only when the human door was consulted, so an
|
|
12733
12844
|
// auto-trunk / docs-only payload stays byte-identical to before.
|
|
12734
|
-
|
|
12735
|
-
|
|
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;
|
|
12736
12849
|
}
|
|
12737
12850
|
|
|
12738
12851
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
@@ -12819,11 +12932,13 @@ function cmdShip(argv) {
|
|
|
12819
12932
|
// ---- (a) AUTONOMY GATE — granted by the repo file, never by the caller ----
|
|
12820
12933
|
// #345: …or the branch's diff is documentation only, computed here from git — never asserted.
|
|
12821
12934
|
const autonomyGate = shipAutonomyGate(doc, () => docsOnly.branchChanges(git, repoAbs, target, shipRefFor(repoAbs, sess.branch)),
|
|
12822
|
-
humanDoor.humanDoorFromProcess(process, opts.answeredBy)
|
|
12935
|
+
humanDoor.humanDoorFromProcess(process, opts.answeredBy), // #525
|
|
12936
|
+
() => configSet.branchTuning(git, repoAbs, target, shipRefFor(repoAbs, sess.branch))); // #561
|
|
12823
12937
|
if (!autonomyGate.ok) {
|
|
12824
12938
|
process.stderr.write(`✗ ${shortRepo(repoAbs)} does not grant auto-trunk (project.yml autonomy: ${autonomyGate.declared}).\n`);
|
|
12825
12939
|
process.stderr.write(' A human must trigger Phase B. (Autonomy is granted by the repo, not by a flag — --force cannot override.)\n');
|
|
12826
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`);
|
|
12827
12942
|
process.stderr.write(shipHumanDoorRefusal(autonomyGate, shipSelector(opts, sess)));
|
|
12828
12943
|
return 1;
|
|
12829
12944
|
}
|
|
@@ -13316,6 +13431,14 @@ function cmdShip(argv) {
|
|
|
13316
13431
|
return 1;
|
|
13317
13432
|
}
|
|
13318
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
|
+
}
|
|
13319
13442
|
|
|
13320
13443
|
// #350: B0 may have brought in paths (a pre-ship hook's regenerated files). The approval covered
|
|
13321
13444
|
// the core paths the table listed; a core path it did not list was never reviewed.
|
|
@@ -15008,7 +15131,11 @@ hot-file count and dependents band, code-wrap's gate.smoke target — and read t
|
|
|
15008
15131
|
skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
|
|
15009
15132
|
and is listed under problems; the audit and the CI templates' descriptor check fail it.
|
|
15010
15133
|
|
|
15011
|
-
|
|
15134
|
+
The batch-* names (#556) have NO default: undeclared, they read "—" and the audit's
|
|
15135
|
+
--batch-history shows the measurement without judging it. Percents are bounded at 100.
|
|
15136
|
+
|
|
15137
|
+
<name> print only that threshold's value (a bare number, for a script or a skill;
|
|
15138
|
+
an empty line for an undeclared no-default name)
|
|
15012
15139
|
--json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
|
|
15013
15140
|
|
|
15014
15141
|
function cmdThresholds(argv) {
|
|
@@ -15023,7 +15150,7 @@ function cmdThresholds(argv) {
|
|
|
15023
15150
|
if (name !== undefined) {
|
|
15024
15151
|
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
15152
|
for (const p of r.problems) process.stderr.write(`! ${p}\n`);
|
|
15026
|
-
print(String(r.values[name]));
|
|
15153
|
+
print(r.values[name] === null ? '' : String(r.values[name])); // #556: empty = undeclared, no default
|
|
15027
15154
|
return 0;
|
|
15028
15155
|
}
|
|
15029
15156
|
const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
|
|
@@ -15036,7 +15163,10 @@ function cmdThresholds(argv) {
|
|
|
15036
15163
|
print(`thresholds ${shortRepo(repoAbs)}`);
|
|
15037
15164
|
const w = Math.max(...Object.keys(rows).map((k) => k.length));
|
|
15038
15165
|
for (const [k, row] of Object.entries(rows)) {
|
|
15039
|
-
|
|
15166
|
+
// #556: a no-default key (batch-*) shows `—` and "not declared" — nothing judges it until it is.
|
|
15167
|
+
const shown = row.value === null ? '—' : String(row.value);
|
|
15168
|
+
const src = row.declared ? `declared (default ${row.default === null ? 'none' : row.default})` : (row.default === null ? 'not declared' : 'default');
|
|
15169
|
+
print(` ${k.padEnd(w)} ${shown.padStart(5)} ${src.padEnd(20)} ${row.what}`);
|
|
15040
15170
|
}
|
|
15041
15171
|
for (const p of r.problems) print(` ! ${p}`);
|
|
15042
15172
|
return 0;
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/batch-history.js — the audit's reading of `colab batch-stats --json` (#556).
|
|
4
|
+
*
|
|
5
|
+
* Two halves, deliberately separate:
|
|
6
|
+
* measure the repo's batch picture as four rates — overlap of serial landings with a partner
|
|
7
|
+
* inside their trunk-CI cycle, batch fill, first-attempt green rate of combined runs,
|
|
8
|
+
* eviction rate of members at build. Always shown; never a finding by itself.
|
|
9
|
+
* judge an advisory ONLY against a threshold the repo declares in `thresholds:` (the four
|
|
10
|
+
* `batch-*` keys in tools/lib/thresholds.js, none of which has a default). The owner's
|
|
11
|
+
* ruling on #556 — "should not set any hard code number" — is why: nothing declared ⇒
|
|
12
|
+
* the numbers are shown and nothing is flagged. Replaces #506's proposed fixed
|
|
13
|
+
* "suggest ship-batch: 3".
|
|
14
|
+
*
|
|
15
|
+
* A rate with no samples is unmeasured (null), and an unmeasured rate is never judged — the same
|
|
16
|
+
* rule as `batch-min-samples`, which a repo may declare to demand more than one sample.
|
|
17
|
+
*
|
|
18
|
+
* Pure: a batch-stats report + the parsed descriptor in, `{ measured, picture, advisories }` out.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const thresholds = require('./thresholds');
|
|
22
|
+
const shipBatch = require('./ship-batch');
|
|
23
|
+
|
|
24
|
+
const pctOf = (num, den) => (den > 0 ? Math.round((num / den) * 100) : null);
|
|
25
|
+
const pctRate = (r) => (r === null || r === undefined ? null : Math.round(r * 100));
|
|
26
|
+
|
|
27
|
+
/** The four rates and their sample counts, from a batch-stats report. */
|
|
28
|
+
function measure(rep) {
|
|
29
|
+
const s = rep.serial || {};
|
|
30
|
+
const b = rep.batches || {};
|
|
31
|
+
const d = rep.dropped || {};
|
|
32
|
+
const finished = (b.builds || 0) - (b.pending || 0);
|
|
33
|
+
return {
|
|
34
|
+
overlap: { pct: pctOf(s.overlapped || 0, s.cyclesRead || 0), samples: s.cyclesRead || 0, overlapped: s.overlapped || 0 },
|
|
35
|
+
fill: { batches: b.landed || 0, byMembers: b.fill || {} },
|
|
36
|
+
firstGreen: { pct: pctRate(b.firstAttemptGreenRate), samples: finished, green: b.firstAttemptGreen || 0 },
|
|
37
|
+
eviction: { pct: pctRate(d.rate), samples: d.attempted || 0, dropped: d.count || 0 },
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** One line per rate, for the human report. `—` is unmeasured, never zero. */
|
|
42
|
+
function picture(rep, m = measure(rep)) {
|
|
43
|
+
const p = (x) => (x.pct === null ? '—' : `${x.pct}%`);
|
|
44
|
+
const fill = Object.keys(m.fill.byMembers).sort().map((k) => `${m.fill.byMembers[k]}×${k}`).join(' · ') || '—';
|
|
45
|
+
const head = `batch history ${String(rep.since || '').slice(0, 10)} … ${String(rep.until || '').slice(0, 10)}: ${(rep.landings || {}).total || 0} landing(s), ${(rep.landings || {}).batch || 0} batch · ${(rep.landings || {}).serial || 0} serial (ship-batch: ${(rep.config || {}).n || 1})`;
|
|
46
|
+
return [
|
|
47
|
+
head,
|
|
48
|
+
`overlap ${p(m.overlap)} of ${m.overlap.samples} serial landing(s) had a partner green inside their trunk-CI cycle · fill ${fill} · first-attempt green ${p(m.firstGreen)} of ${m.firstGreen.samples} combined run(s) · eviction ${p(m.eviction)} of ${m.eviction.samples} member(s)`,
|
|
49
|
+
];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Advisories for the rates that cross a DECLARED threshold. `doc` is the parsed descriptor.
|
|
54
|
+
* Returns `{ advisories: [text], judged: [key], unjudged: [{ key, why }] }` — a declared key that
|
|
55
|
+
* could not be judged (no samples, under batch-min-samples, not applicable) says why, so a quiet
|
|
56
|
+
* report never reads as "checked and fine" when it was not checked.
|
|
57
|
+
*/
|
|
58
|
+
function judge(rep, doc, m = measure(rep)) {
|
|
59
|
+
const t = thresholds.parseThresholds(doc).values;
|
|
60
|
+
const n = shipBatch.parseShipBatch(doc || {}).n || 1;
|
|
61
|
+
const minN = t['batch-min-samples'] === null ? 1 : t['batch-min-samples'];
|
|
62
|
+
const advisories = [];
|
|
63
|
+
const judged = [];
|
|
64
|
+
const unjudged = [];
|
|
65
|
+
const enough = (key, rate) => {
|
|
66
|
+
if (rate.pct === null || rate.samples < minN) {
|
|
67
|
+
unjudged.push({ key, why: `${rate.samples} sample(s)${minN > 1 ? `, batch-min-samples is ${minN}` : ''}` });
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
judged.push(key);
|
|
71
|
+
return true;
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const ov = t['batch-overlap-pct'];
|
|
75
|
+
if (ov !== null) {
|
|
76
|
+
if (n > 1) unjudged.push({ key: 'batch-overlap-pct', why: `already opted in (ship-batch: ${n})` });
|
|
77
|
+
else if (enough('batch-overlap-pct', m.overlap) && m.overlap.pct >= ov) {
|
|
78
|
+
advisories.push(`batch history: ${m.overlap.pct}% of ${m.overlap.samples} serial landings overlapped a partner's green inside their trunk-CI cycle (thresholds.batch-overlap-pct: ${ov}) — consider opting in to ship-batch; colab batch-stats has the pairs`);
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
const fg = t['batch-first-green-pct-min'];
|
|
82
|
+
if (fg !== null) {
|
|
83
|
+
if (n <= 1 && !m.firstGreen.samples) unjudged.push({ key: 'batch-first-green-pct-min', why: 'not batching (ship-batch absent or 1)' });
|
|
84
|
+
else if (enough('batch-first-green-pct-min', m.firstGreen) && m.firstGreen.pct < fg) {
|
|
85
|
+
advisories.push(`batch history: ${m.firstGreen.pct}% of ${m.firstGreen.samples} combined runs went green on the first attempt (thresholds.batch-first-green-pct-min: ${fg}) — consider lowering ship-batch${n > 1 ? ` below ${n}` : ''}`);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
const ev = t['batch-eviction-pct-max'];
|
|
89
|
+
if (ev !== null) {
|
|
90
|
+
if (n <= 1 && !m.eviction.samples) unjudged.push({ key: 'batch-eviction-pct-max', why: 'not batching (ship-batch absent or 1)' });
|
|
91
|
+
else if (enough('batch-eviction-pct-max', m.eviction) && m.eviction.pct > ev) {
|
|
92
|
+
advisories.push(`batch history: ${m.eviction.pct}% of ${m.eviction.samples} batch members were dropped at build (thresholds.batch-eviction-pct-max: ${ev}) — colab batch-stats lists them by class`);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return { advisories, judged, unjudged };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** The batch-* threshold names a descriptor declares — what makes a no-flag audit run worth a note. */
|
|
99
|
+
function declaredBatchKeys(doc) {
|
|
100
|
+
const d = thresholds.parseThresholds(doc).declared;
|
|
101
|
+
return Object.keys(d).filter((k) => k.startsWith('batch-'));
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { measure, picture, judge, declaredBatchKeys };
|
package/tools/lib/batch-stats.js
CHANGED
|
@@ -207,7 +207,7 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
207
207
|
|
|
208
208
|
// ---- missed partners: serial landings that landed alone while a partner was (nearly) ready ----
|
|
209
209
|
const pairs = [];
|
|
210
|
-
let withMissed = 0, withNear = 0, cyclesUnread = 0;
|
|
210
|
+
let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
|
|
211
211
|
// A partner is judged by ITS state at this landing's moment, never by the head it finally landed
|
|
212
212
|
// with: a serial ship syncs the other branches, so their final heads all post-date it. The cycle
|
|
213
213
|
// ends when this landing's trunk run finishes — or at the next landing, whichever is first (a
|
|
@@ -238,6 +238,7 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
238
238
|
}
|
|
239
239
|
if (missed) withMissed++;
|
|
240
240
|
else if (near) withNear++;
|
|
241
|
+
if (end !== null && (missed || near)) overlapped++;
|
|
241
242
|
}
|
|
242
243
|
if (cyclesUnread) notes.push(`${cyclesUnread} serial landing(s) with no finished trunk run in the window — near misses not judged for them`);
|
|
243
244
|
const unknownGreen = changes.filter((c) => c.greenMs === null).length;
|
|
@@ -262,6 +263,9 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
262
263
|
dropped: { count: dropped.length, attempted: builtMembers + dropped.length, rate: rate(dropped.length, builtMembers + dropped.length), byClass, members: dropped },
|
|
263
264
|
serial: {
|
|
264
265
|
landings: serialChanges.length, withMissedPartner: withMissed, withNearMiss: withNear,
|
|
266
|
+
// #556: the overlap rate's honest denominator — only a landing whose trunk-CI cycle was read
|
|
267
|
+
// could have been judged for a partner inside it; `overlapped` counts those that had one.
|
|
268
|
+
cyclesRead: serialChanges.length - cyclesUnread, overlapped,
|
|
265
269
|
nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
|
|
266
270
|
pairs,
|
|
267
271
|
},
|
|
@@ -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/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
|
};
|
package/tools/lib/thresholds.js
CHANGED
|
@@ -14,9 +14,13 @@
|
|
|
14
14
|
* that decides what gets flagged, ranked or warned about. Safety limits (a cap a repo may only
|
|
15
15
|
* tighten) and protocol counts are out of scope (epic #558) and keep their own fields.
|
|
16
16
|
*
|
|
17
|
-
* Every value is a whole number with a per-key floor
|
|
18
|
-
* the CI templates' shell copy of this rule (the descriptor
|
|
19
|
-
* this table by tools/lib/ci-template-descriptor-check.test.js.
|
|
17
|
+
* Every value is a whole number with a per-key floor (and, for a percent, a ceiling of 100), and the
|
|
18
|
+
* unit is in the key's name. That keeps the CI templates' shell copy of this rule (the descriptor
|
|
19
|
+
* check, #416) small enough to be held to this table by tools/lib/ci-template-descriptor-check.test.js.
|
|
20
|
+
*
|
|
21
|
+
* NO-DEFAULT keys (#556): `def: null`. The batch-history judgement has no fleet-wide number to fall
|
|
22
|
+
* back on — the owner's ruling is that none be hard-coded — so an undeclared one means "do not judge":
|
|
23
|
+
* its value is null, and its reader shows the measurement without an advisory.
|
|
20
24
|
*
|
|
21
25
|
* A malformed value — a typo'd key, a non-number, a number under the floor — falls back to the
|
|
22
26
|
* default and is reported; the audit and the descriptor check fail it. A typo'd key is a problem,
|
|
@@ -29,7 +33,8 @@
|
|
|
29
33
|
const KEY = 'thresholds';
|
|
30
34
|
|
|
31
35
|
/**
|
|
32
|
-
* key → { def, min, what, where }. `where` names the one place that reads the value.
|
|
36
|
+
* key → { def, min, max?, what, where }. `where` names the one place that reads the value. `def: null`
|
|
37
|
+
* = no default (#556): undeclared means its reader does not judge. `max` absent = MAX_VALUE.
|
|
33
38
|
* Order is the order `colab thresholds` prints.
|
|
34
39
|
*/
|
|
35
40
|
const SPEC = Object.freeze({
|
|
@@ -42,6 +47,11 @@ const SPEC = Object.freeze({
|
|
|
42
47
|
'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
48
|
'transitional-days': { def: 180, min: 1, what: 'days a transitional descriptor value holds before the audit says how long', where: 'audit/audit.mjs' },
|
|
44
49
|
'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' },
|
|
50
|
+
// #556 — the audit's batch-history advisories (tools/lib/batch-history.js). No defaults, by ruling.
|
|
51
|
+
'batch-min-samples': { def: null, min: 1, what: 'measured events a batch rate needs before the audit judges it (undeclared: any)', where: 'audit/audit.mjs --batch-history' },
|
|
52
|
+
'batch-first-green-pct-min': { def: null, min: 0, max: 100, what: 'first-attempt green % of combined runs below which the audit suggests lowering ship-batch', where: 'audit/audit.mjs --batch-history' },
|
|
53
|
+
'batch-eviction-pct-max': { def: null, min: 0, max: 100, what: '% of batch members dropped at build above which the audit flags eviction', where: 'audit/audit.mjs --batch-history' },
|
|
54
|
+
'batch-overlap-pct': { def: null, min: 0, max: 100, what: '% of serial landings with a missed or near-miss partner at which the audit suggests opting in to ship-batch', where: 'audit/audit.mjs --batch-history' },
|
|
45
55
|
});
|
|
46
56
|
|
|
47
57
|
const DEFAULTS = Object.freeze(Object.fromEntries(Object.entries(SPEC).map(([k, s]) => [k, s.def])));
|
|
@@ -57,7 +67,7 @@ function wholeNumber(raw) {
|
|
|
57
67
|
|
|
58
68
|
/**
|
|
59
69
|
* `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;
|
|
70
|
+
* nothing valid was declared — null for a no-default key); `declared` names the keys whose declared value is in force;
|
|
61
71
|
* `problems` is one sentence per malformed entry, each ending with the default it fell back to.
|
|
62
72
|
*/
|
|
63
73
|
function parseThresholds(doc) {
|
|
@@ -79,8 +89,10 @@ function parseThresholds(doc) {
|
|
|
79
89
|
}
|
|
80
90
|
if (v === null || v === undefined || v === '') continue; // an empty entry declares nothing
|
|
81
91
|
const n = wholeNumber(v);
|
|
82
|
-
|
|
83
|
-
|
|
92
|
+
const max = spec.max === undefined ? MAX_VALUE : spec.max;
|
|
93
|
+
if (!Number.isFinite(n) || n < spec.min || n > max) {
|
|
94
|
+
const range = spec.max === undefined ? `≥ ${spec.min}` : `${spec.min}–${spec.max}`;
|
|
95
|
+
problems.push(`${KEY}.${k} must be a whole number ${range}, got ${JSON.stringify(v)} — ${spec.def === null ? 'not declared, so not judged' : `using the default ${spec.def}`}`);
|
|
84
96
|
continue;
|
|
85
97
|
}
|
|
86
98
|
values[k] = n;
|
|
@@ -89,7 +101,7 @@ function parseThresholds(doc) {
|
|
|
89
101
|
return { values, declared, problems };
|
|
90
102
|
}
|
|
91
103
|
|
|
92
|
-
/** The resolved value of one key — the convenience a single consumer wants. */
|
|
104
|
+
/** The resolved value of one key — the convenience a single consumer wants. Null = undeclared, no default. */
|
|
93
105
|
function thresholdValue(doc, key) {
|
|
94
106
|
if (!SPEC[key]) throw new Error(`unknown threshold ${key}`);
|
|
95
107
|
return parseThresholds(doc).values[key];
|