commit aaf4258a99b76432ffc6624a203336d6347c61fc
parent 64ba30619b3c2a3e300429ee3fb069c747e395c6
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Mon, 28 Sep 2026 02:42:17 -0400
common: the declared-but-unmentioned env-var test can fail (review S1)
Its corpus included common/lib/envVars.ts, where every declared name is
spelled, so it could never fail: a declared var nothing read passed (the
reviewer's bite), and the record's bite for it was the stale-ENVIRONMENT.md
test. envVars.ts is now left out. The test is "still NAMED outside the
list" and the header, ENVIRONMENT.md's intro and the record say that (a
mention, not a proven read). New: every ARCHILYZER_* name in docker/, the
Dockerfiles and the compose files must be declared (review L5).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Diffstat:
3 files changed, 32 insertions(+), 10 deletions(-)
diff --git a/ENVIRONMENT.md b/ENVIRONMENT.md
@@ -2,7 +2,7 @@
<!-- GENERATED by common/bin/env-docs.ts from common/lib/envVars.ts — do not edit by hand. -->
-Every environment variable the repo's code reads, by who it is for. The list is code (`common/lib/envVars.ts`), and a test fails when the code reads a variable the list does not declare, or the list declares one nothing reads. umtool's own knobs are documented in [umtool/docs](umtool/docs/README.md).
+Every environment variable the repo's code reads, by who it is for. The list is code (`common/lib/envVars.ts`), and a test fails when the code reads a variable the list does not declare, or the list declares one that nothing outside the list names any more. umtool's own knobs are documented in [umtool/docs](umtool/docs/README.md).
Regenerate this file with `pnpm archilyzer docs env`. `pnpm archilyzer doctor` prints which of the paths overrides are set on this machine.
diff --git a/common/lib/envVars.test.ts b/common/lib/envVars.test.ts
@@ -87,15 +87,33 @@ test("every variable the code reads is declared", () => {
assert.deepEqual(missing, [], "declare these in common/lib/envVars.ts");
});
-test("every declared variable is still mentioned by the code, a script or a compose file", () => {
- const corpus = [
- ...codeFiles().map((f) => readFileSync(f, "utf8")),
+// docker/'s files, the Dockerfiles and the compose files: where the
+// container's own ARCHILYZER_* set is read.
+function dockerTexts(): string[] {
+ return [
...readdirSync(path.join(REPO, "docker"))
.filter((n) => statSync(path.join(REPO, "docker", n)).isFile())
.map((n) => readFileSync(path.join(REPO, "docker", n), "utf8")),
...readdirSync(REPO)
.filter((n) => /^docker-compose.*\.yml$|^Dockerfile/.test(n))
.map((n) => readFileSync(path.join(REPO, n), "utf8")),
+ ];
+}
+
+test("every ARCHILYZER_* name in docker/, the Dockerfiles and the compose files is declared", () => {
+ const declared = new Set(ENV_VARS.map((v) => v.name));
+ const names = new Set(dockerTexts().flatMap((t) => [...t.matchAll(/\bARCHILYZER_[A-Z0-9_]+\b/g)].map((m) => m[0])));
+ assert.deepEqual([...names].filter((n) => !declared.has(n)).sort(), [], "declare these in common/lib/envVars.ts");
+});
+
+test("every declared variable is still named outside the list: the code, docker/, a Dockerfile, a compose file or a script", () => {
+ // envVars.ts itself is left out: every declared name is spelled there, so
+ // with it in the corpus this test could never fail.
+ const corpus = [
+ ...codeFiles()
+ .filter((f) => !f.endsWith(path.join("common", "lib", "envVars.ts")))
+ .map((f) => readFileSync(f, "utf8")),
+ ...dockerTexts(),
...["", "editor", "export", "homepage"].map((d) =>
readFileSync(path.join(REPO, d, "package.json"), "utf8"),
),
diff --git a/common/lib/envVars.ts b/common/lib/envVars.ts
@@ -1,11 +1,15 @@
// EVERY ENVIRONMENT VARIABLE THE REPO READS — the one declared list.
//
// ENVIRONMENT.md is generated from this (common/bin/env-docs.ts, `--check` in
-// the common tests), and `envVars.test.ts` holds the list to the code: every
-// variable read by common/, editor/, export/, homepage/, mcp/src and scripts/ is
-// declared here, and every entry here is still read somewhere. A variable that
-// is added without an entry, or deleted with its entry left behind, fails the
-// build. umtool's own knobs are NOT here — its song and report scripts read
+// the common tests), and `envVars.test.ts` holds the list to the code in both
+// directions: every variable read by common/, editor/, export/, homepage/,
+// mcp/src and scripts/ (and every `ARCHILYZER_*` name in docker/, the
+// Dockerfiles and the compose files) is declared here, and every entry here is
+// still NAMED somewhere outside this file — the code, docker/, a Dockerfile, a
+// compose file or a package.json script. A variable added without an entry, or
+// whose last mention is deleted while its entry stays, fails the build. (The
+// second check is a mention, not a proven read: a name left only in a comment
+// passes it.) umtool's own knobs are NOT here — its song and report scripts read
// dozens, documented in umtool/docs, and fold into the core in one-core Phase 5.
//
// THE AUDIENCES, which are the point of the table:
@@ -208,7 +212,7 @@ export function renderEnvironmentMarkdown(): string {
"",
"<!-- GENERATED by common/bin/env-docs.ts from common/lib/envVars.ts — do not edit by hand. -->",
"",
- "Every environment variable the repo's code reads, by who it is for. The list is code (`common/lib/envVars.ts`), and a test fails when the code reads a variable the list does not declare, or the list declares one nothing reads. umtool's own knobs are documented in [umtool/docs](umtool/docs/README.md).",
+ "Every environment variable the repo's code reads, by who it is for. The list is code (`common/lib/envVars.ts`), and a test fails when the code reads a variable the list does not declare, or the list declares one that nothing outside the list names any more. umtool's own knobs are documented in [umtool/docs](umtool/docs/README.md).",
"",
"Regenerate this file with `pnpm archilyzer docs env`. `pnpm archilyzer doctor` prints which of the paths overrides are set on this machine.",
"",
