Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
import test from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import {
isMainEntry,
parseEnvExampleVars,
parseEnvDocVars,
runEnvDocSync,
} from "../../scripts/check/check-env-doc-sync.mjs";
test("parseEnvExampleVars: extracts uncommented assignments", () => {
const text = `
JWT_SECRET=abc123
FOO_BAR=baz
# SKIPPED_VAR=leading whitespace before hash is rejected
`;
const vars = parseEnvExampleVars(text);
assert.ok(vars.has("JWT_SECRET"));
assert.ok(vars.has("FOO_BAR"));
// The regex anchors `^#?` so leading whitespace before `#` prevents a match.
assert.equal(vars.has("SKIPPED_VAR"), false);
});
test("parseEnvExampleVars: extracts commented examples", () => {
const text = `
#OPTIONAL_KEY=value
# OPTIONAL_OTHER=value-with-space
ACTIVE=1
`;
const vars = parseEnvExampleVars(text);
assert.ok(vars.has("OPTIONAL_KEY"));
assert.ok(vars.has("OPTIONAL_OTHER"));
assert.ok(vars.has("ACTIVE"));
});
test("parseEnvExampleVars: ignores prose", () => {
const text = `
# This file documents env vars. Don't put values here.
Some narrative paragraph mentions PORT and DATA_DIR in passing.
PORT=20128
`;
const vars = parseEnvExampleVars(text);
assert.deepEqual([...vars].sort(), ["PORT"]);
});
test("parseEnvDocVars: extracts SHOUTY_NAMES from inline backticks", () => {
const md = "Set `FOO_BAR` to enable the thing. Defaults to `BAR_BAZ_QUX`.";
const vars = parseEnvDocVars(md);
assert.deepEqual([...vars].sort(), ["BAR_BAZ_QUX", "FOO_BAR"]);
});
test("parseEnvDocVars: ignores values like `7s` or two-letter codes", () => {
const md = "TTL is `60s` and the type is `JSON`. Real var: `OMNIROUTE_TTL_MS`.";
const vars = parseEnvDocVars(md);
assert.deepEqual([...vars].sort(), ["JSON", "OMNIROUTE_TTL_MS"]);
});
test("runEnvDocSync: matched fixture passes", () => {
const envExampleText = `
JWT_SECRET=secret
#OPTIONAL_VAR=value
ANOTHER_VAR=1
`;
const envDocText = `
# Reference
| Variable | Default | Description |
| --- | --- | --- |
| \`JWT_SECRET\` | _(none)_ | required |
| \`OPTIONAL_VAR\` | _(unset)_ | optional |
| \`ANOTHER_VAR\` | 1 | enabled by default |
`;
const codeVars = new Set(["JWT_SECRET", "OPTIONAL_VAR", "ANOTHER_VAR"]);
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars,
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, true);
assert.deepEqual(result.problems.codeMissingEnv, []);
assert.deepEqual(result.problems.envMissingDoc, []);
assert.deepEqual(result.problems.docMissingEnv, []);
});
test("runEnvDocSync: drift in code is flagged", () => {
const envExampleText = `JWT_SECRET=secret\n`;
const envDocText = "| `JWT_SECRET` | _(none)_ | required |";
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET", "NEW_VAR"]),
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, false);
assert.deepEqual(result.problems.codeMissingEnv, ["NEW_VAR"]);
});
test("runEnvDocSync: drift in doc is flagged", () => {
const envExampleText = `JWT_SECRET=secret\nNEW_VAR=value\n`;
const envDocText = "| `JWT_SECRET` | _(none)_ | required |";
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET", "NEW_VAR"]),
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, false);
assert.deepEqual(result.problems.envMissingDoc, ["NEW_VAR"]);
});
test("runEnvDocSync: drift in env (doc-only var) is flagged", () => {
const envExampleText = `JWT_SECRET=secret\n`;
const envDocText = `
| \`JWT_SECRET\` | _(none)_ | required |
| \`OBSOLETE_VAR\` | _(unset)_ | docs-only legacy |
`;
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET"]),
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, false);
assert.deepEqual(result.problems.docMissingEnv, ["OBSOLETE_VAR"]);
});
test("runEnvDocSync: docOnlyAllowlist absolves doc-only entries", () => {
const envExampleText = `JWT_SECRET=secret\n`;
const envDocText = `
| \`JWT_SECRET\` | _(none)_ | required |
| \`LEGACY_ALIAS\` | _(unset)_ | documented but not in env.example |
`;
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET"]),
ignore: new Set(),
docOnlyAllowlist: new Set(["LEGACY_ALIAS"]),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, true);
assert.deepEqual(result.problems.docMissingEnv, []);
});
test("runEnvDocSync: envOnlyAllowlist absolves env-only entries", () => {
const envExampleText = `JWT_SECRET=secret\nFOO_BAR=bar\n`;
const envDocText = "| `JWT_SECRET` | _(none)_ | required |";
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET", "FOO_BAR"]),
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(["FOO_BAR"]),
});
assert.equal(result.ok, true);
assert.deepEqual(result.problems.envMissingDoc, []);
});
test("runEnvDocSync: ignore set skips a code-referenced var", () => {
const envExampleText = `JWT_SECRET=secret\n`;
const envDocText = "| `JWT_SECRET` | _(none)_ | required |";
const result = runEnvDocSync({
envExampleText,
envDocText,
codeVars: new Set(["JWT_SECRET", "PATH", "HOME"]),
ignore: new Set(["PATH", "HOME"]),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(result.ok, true);
});
test("runEnvDocSync: shipped allowlist ignores ad-hoc BOT_TOKEN and BOT_URL", () => {
const envExampleText = `JWT_SECRET=secret\n`;
const envDocText = "| `JWT_SECRET` | _(none)_ | required |";
const codeVars = new Set(["JWT_SECRET", "BOT_TOKEN", "BOT_URL"]);
const unignored = runEnvDocSync({
envExampleText,
envDocText,
codeVars,
ignore: new Set(),
docOnlyAllowlist: new Set(),
envOnlyAllowlist: new Set(),
});
assert.equal(unignored.ok, false);
assert.deepEqual(unignored.problems.codeMissingEnv, ["BOT_TOKEN", "BOT_URL"]);
// Omit `ignore` so the checker uses IGNORE_FROM_CODE from check-env-doc-sync.mjs.
const shipped = runEnvDocSync({
envExampleText,
envDocText,
codeVars,
});
assert.equal(shipped.ok, true);
assert.deepEqual(shipped.problems.codeMissingEnv, []);
});
test("repository contract is in sync (live data)", () => {
// Uses the real .env.example, docs/ENVIRONMENT.md, and the bundled
// allowlists. This is the same check that runs in pre-commit / CI.
const result = runEnvDocSync();
if (!result.ok) {
const summary = JSON.stringify(result.problems, null, 2);
assert.fail(`Env/docs contract drift detected:\n${summary}`);
}
assert.equal(result.ok, true);
});
// ─── CLI entry guard ────────────────────────────────────────────────────────
test("isMainEntry: absolute argv[1] matches the module URL (normal CLI invocation)", () => {
const moduleUrl =
"file:///home/runner/work/OmniRoute/OmniRoute/scripts/check/check-env-doc-sync.mjs";
const argv1 = "/home/runner/work/OmniRoute/OmniRoute/scripts/check/check-env-doc-sync.mjs";
assert.equal(isMainEntry(argv1, moduleUrl), true);
});
test("isMainEntry: path with characters that import.meta.url percent-encodes still matches", () => {
// A checkout path containing a space is the common macOS case; the module
// URL carries %20 while process.argv[1] carries the raw character.
const moduleUrl =
"file:///Users/dev/My%20Projects/OmniRoute/scripts/check/check-env-doc-sync.mjs";
const argv1 = "/Users/dev/My Projects/OmniRoute/scripts/check/check-env-doc-sync.mjs";
assert.equal(isMainEntry(argv1, moduleUrl), true);
});
test("isMainEntry: different entry target or missing argv[1] does not trigger the CLI", () => {
const moduleUrl =
"file:///home/runner/work/OmniRoute/OmniRoute/scripts/check/check-env-doc-sync.mjs";
assert.equal(
isMainEntry("/home/runner/work/OmniRoute/OmniRoute/tests/unit/x.test.ts", moduleUrl),
false
);
assert.equal(isMainEntry(undefined, moduleUrl), false);
assert.equal(isMainEntry("", moduleUrl), false);
});
test("CLI entry actually runs the gate when spawned directly", () => {
const scriptPath = fileURLToPath(
new URL("../../scripts/check/check-env-doc-sync.mjs", import.meta.url)
);
const res = spawnSync(process.execPath, [scriptPath], { encoding: "utf8" });
// The gate may legitimately exit 1 when the live contract is out of sync;
// what matters here is that main() ran and printed its report.
assert.ok(
res.stdout.includes("Env var contract sync report"),
`expected the sync report banner in stdout, got: ${JSON.stringify(res.stdout.slice(0, 200))}`
);
});