test(env): cover ratchet growth and boundary; document surface budgets

steipete · steipete · commit 58b9a1c631a6 · 2026-07-20T06:29:35.000-07:00
diff --git a/docs/ci.md b/docs/ci.md
@@ -207,6 +207,22 @@ The changed-target PR plan reduces the common Node test burst from 14 Blacksmith
 
 Canonical-repo CI keeps Blacksmith as the default runner path for normal push and pull-request runs. `workflow_dispatch` and non-canonical repository runs use GitHub-hosted runners, but normal canonical runs do not currently probe Blacksmith queue health or automatically fall back to GitHub-hosted labels when Blacksmith is unavailable.
 
+## Surface ratchets
+
+Two shrink-only budgets guard the configuration surface. Both fail CI on growth
+until the budget file is consciously updated in the same PR, and both demand a
+ratchet-down when cleanup lowers the real count.
+
+- `config/env-var-count-budget.txt` caps the number of distinct `OPENCLAW_*`
+  names in production source under `src/`, `packages/`, and `extensions/`
+  (tests and QA Lab excluded). Checked by `node scripts/check-env-var-count.mjs`.
+  Removing env vars: lower the number in the same PR. Adding one is a
+  config-surface decision — justify it in the PR body.
+- `docs/.generated/config-baseline.counts.json` caps the per-kind
+  (core/channel/plugin) `openclaw.json` schema entry counts. Checked by
+  `pnpm config:docs:check`; regenerate with `pnpm config:docs:gen` after any
+  schema change.
+
 ## Local equivalents
 
 ```bash
diff --git a/test/scripts/check-env-var-count.test.ts b/test/scripts/check-env-var-count.test.ts
@@ -73,6 +73,45 @@ describe("check-env-var-count", () => {
     expect(() => main(["--base", "missing"], root)).toThrow(/Could not resolve/u);
   });
 
+  it("rejects growth above the budget", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-env-count-grow-"));
+    tempDirs.push(root);
+    fs.mkdirSync(path.join(root, "config"), { recursive: true });
+    fs.mkdirSync(path.join(root, "src"), { recursive: true });
+    fs.writeFileSync(path.join(root, "config/env-var-count-budget.txt"), "1\n");
+    fs.writeFileSync(
+      path.join(root, "src/runtime.ts"),
+      "process.env.OPENCLAW_ONE; process.env.OPENCLAW_TWO;\n",
+    );
+    execFileSync("git", ["init"], { cwd: root, stdio: "ignore" });
+    execFileSync("git", ["add", "."], { cwd: root, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["-c", "user.name=OpenClaw", "-c", "user.email=test@openclaw.local", "commit", "-m", "base"],
+      { cwd: root, stdio: "ignore" },
+    );
+
+    expect(() => main(["--base", "HEAD"], root)).toThrow(/exceeds budget|over budget/u);
+  });
+
+  it("passes when the count exactly matches the budget", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-env-count-exact-"));
+    tempDirs.push(root);
+    fs.mkdirSync(path.join(root, "config"), { recursive: true });
+    fs.mkdirSync(path.join(root, "src"), { recursive: true });
+    fs.writeFileSync(path.join(root, "config/env-var-count-budget.txt"), "1\n");
+    fs.writeFileSync(path.join(root, "src/runtime.ts"), "process.env.OPENCLAW_ONLY;\n");
+    execFileSync("git", ["init"], { cwd: root, stdio: "ignore" });
+    execFileSync("git", ["add", "."], { cwd: root, stdio: "ignore" });
+    execFileSync(
+      "git",
+      ["-c", "user.name=OpenClaw", "-c", "user.email=test@openclaw.local", "commit", "-m", "base"],
+      { cwd: root, stdio: "ignore" },
+    );
+
+    expect(() => main(["--base", "HEAD"], root)).not.toThrow();
+  });
+
   it("rejects stale headroom after the count shrinks", () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-env-count-tight-"));
     tempDirs.push(root);
