Skip to content

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

Merge FASE 2: env audit

diegosouzapw6991024935ee
diff --cc scripts/check/check-env-doc-sync.mjs
index eeb9db8114,f4e61d841b..f68fea2eb7
--- a/scripts/check/check-env-doc-sync.mjs
+++ b/scripts/check/check-env-doc-sync.mjs
@@@ -1,10 -1,27 +1,27 @@@
#!/usr/bin/env node
- // Validates that env vars referenced in code appear in .env.example AND in docs/ENVIRONMENT.md.
- // Exits 0 on success, 1 on missing entries. Designed for use in pre-commit / CI.
- //
- // Run: node scripts/check/check-env-doc-sync.mjs
- // Strict mode: node scripts/check/check-env-doc-sync.mjs --strict
- // In strict mode, missing entries cause failure. In default mode, only summary is printed.
+ /**
+ * Strict environment variable contract checker.
+ *
+ * Enforces that every env var referenced in OmniRoute source code appears in
+ * both `.env.example` and `docs/ENVIRONMENT.md`, and that the two files agree
+ * on the documented var set. Falls back to a small allowlist for variables
+ * that are intentionally documented but not literally referenced (legacy
+ * aliases, future-supported hooks) or vice versa.
+ *
+ * Usage:
- * node scripts/check-env-doc-sync.mjs # strict (CI mode)
- * node scripts/check-env-doc-sync.mjs --lenient # legacy report-only mode
++ * node scripts/check/check-env-doc-sync.mjs # strict (CI mode)
++ * node scripts/check/check-env-doc-sync.mjs --lenient # legacy report-only mode
+ *
+ * Strict mode exits non-zero if any of these are non-empty:
+ * - vars in code but missing from .env.example
+ * - vars in .env.example but missing from ENVIRONMENT.md
+ * - vars in ENVIRONMENT.md but missing from .env.example
+ *
+ * Programmatic API:
+ * Other Node tests can `import { runEnvDocSync } from "./check-env-doc-sync.mjs"`
+ * and pass `{ root, envExample, envDoc, codeVars, ignore, docOnlyAllowlist,
+ * envOnlyAllowlist }` to drive the checker against fixtures.
+ */
import fs from "node:fs";
import path from "node:path";
@@@ -12,14 -29,12 +29,12 @@@ import { fileURLToPath } from "node:url
import { execSync } from "node:child_process";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
- const ROOT = path.resolve(__dirname, "..", "..");
- const ENV_EXAMPLE = path.join(ROOT, ".env.example");
- const ENV_DOC = path.join(ROOT, "docs", "ENVIRONMENT.md");
-const REPO_ROOT = path.resolve(__dirname, "..");
++const REPO_ROOT = path.resolve(__dirname, "..", "..");
- const STRICT = process.argv.includes("--strict");
-
- // Vars that are intentionally not documented or detected in code via dynamic patterns.
- const IGNORE = new Set([
+ // ─── Allowlists ────────────────────────────────────────────────────────────
+ // Env vars referenced in code that should NOT trigger documentation drift.
+ // These are usually system/process vars or harness-only knobs.
+ const IGNORE_FROM_CODE = new Set([
"NODE_ENV",
"PATH",
"HOME",
@@@ -88,44 -177,101 +177,101 @@@ function diff(set, against)
return [...set].filter((v) => !against.has(v)).sort();
}
+ // ─── Programmatic entry point ──────────────────────────────────────────────
+
+ /**
+ * Run the contract checker. All inputs are overridable for tests.
+ *
+ * Returns `{ ok: boolean, summary, problems: { codeMissingEnv, envMissingDoc,
+ * docMissingEnv } }`.
+ */
+ export function runEnvDocSync(options = {}) {
+ const ignore = options.ignore ?? IGNORE_FROM_CODE;
+ const docOnly = options.docOnlyAllowlist ?? DOC_ONLY_ALLOWLIST;
+ const envOnly = options.envOnlyAllowlist ?? ENV_ONLY_ALLOWLIST;
+
+ const envExampleText =
+ options.envExampleText ??
+ (options.envExamplePath
+ ? fs.readFileSync(options.envExamplePath, "utf8")
+ : fs.readFileSync(path.join(REPO_ROOT, ".env.example"), "utf8"));
+ const envDocText =
+ options.envDocText ??
+ (options.envDocPath
+ ? fs.readFileSync(options.envDocPath, "utf8")
+ : fs.readFileSync(path.join(REPO_ROOT, "docs", "ENVIRONMENT.md"), "utf8"));
+
+ const envVars = parseEnvExampleVars(envExampleText);
+ const docVars = parseEnvDocVars(envDocText);
+
+ const codeVars = new Set(
+ [...(options.codeVars ?? scanCodeVars({ cwd: options.root }))].filter((v) => !ignore.has(v))
+ );
+
+ const codeMissingEnv = diff(codeVars, envVars);
+ const envMissingDoc = diff(envVars, docVars).filter((v) => !envOnly.has(v));
+ const docMissingEnv = diff(docVars, envVars).filter((v) => !docOnly.has(v));
+
+ const ok =
+ codeMissingEnv.length === 0 && envMissingDoc.length === 0 && docMissingEnv.length === 0;
+
+ return {
+ ok,
+ summary: {
+ code: codeVars.size,
+ envExample: envVars.size,
+ doc: docVars.size,
+ },
+ problems: {
+ codeMissingEnv,
+ envMissingDoc,
+ docMissingEnv,
+ },
+ };
+ }
+
+ // ─── CLI ───────────────────────────────────────────────────────────────────
+
+ function printList(label, list, marker) {
+ if (list.length === 0) {
+ console.log(` ${marker || "✓"} ${label}: none`);
+ return;
+ }
+ console.log(` ✗ ${label}: ${list.length}`);
+ for (const v of list.slice(0, 50)) console.log(` - ${v}`);
+ if (list.length > 50) console.log(` ... and ${list.length - 50} more`);
+ }
+
function main() {
- const codeVars = readCodeVars();
- const exampleVars = readEnvExampleVars();
- const docVars = readEnvDocVars();
-
- const inCodeMissingExample = diff(codeVars, exampleVars);
- const inCodeMissingDoc = diff(codeVars, docVars);
- const inExampleMissingDoc = diff(exampleVars, docVars);
- const inExampleMissingCode = diff(exampleVars, codeVars);
-
- console.log("Env var sync report");
- console.log("===================");
- console.log(`Code references: ${codeVars.size} unique vars`);
- console.log(`In .env.example: ${exampleVars.size} unique vars`);
- console.log(`In docs/ENVIRONMENT.md: ${docVars.size} unique vars (heuristic)`);
+ const lenient = process.argv.includes("--lenient");
+ const result = runEnvDocSync();
+
+ console.log("Env var contract sync report");
+ console.log("============================");
+ console.log(`Code references: ${result.summary.code} unique vars`);
+ console.log(`In .env.example: ${result.summary.envExample} unique vars`);
+ console.log(`In docs/ENVIRONMENT.md: ${result.summary.doc} unique vars`);
console.log();
- function printList(label, list) {
- if (list.length === 0) {
- console.log(` ✓ ${label}: none`);
- } else {
- console.log(` ⚠ ${label}: ${list.length}`);
- for (const v of list.slice(0, 30)) console.log(` - ${v}`);
- if (list.length > 30) console.log(` ... and ${list.length - 30} more`);
- }
- }
+ printList("In code but missing from .env.example", result.problems.codeMissingEnv);
+ printList("In .env.example but missing from ENVIRONMENT.md", result.problems.envMissingDoc);
+ printList("In ENVIRONMENT.md but missing from .env.example", result.problems.docMissingEnv);
- printList("In code but missing from .env.example", inCodeMissingExample);
- printList("In code but missing from ENVIRONMENT.md", inCodeMissingDoc);
- printList("In .env.example but missing from ENVIRONMENT.md", inExampleMissingDoc);
- printList("In .env.example but not referenced in code (dead?)", inExampleMissingCode);
+ if (result.ok) {
+ console.log("\n✓ Env / docs contract is in sync.");
+ process.exit(0);
+ }
- const errors = inCodeMissingExample.length + inExampleMissingDoc.length;
- if (STRICT && errors > 0) {
- console.error(`\n✗ ${errors} drift(s) detected (strict mode)`);
- process.exit(1);
+ if (lenient) {
+ console.log("\n⚠ Drift detected (lenient mode — exit 0).");
+ process.exit(0);
}
- console.log(`\n${errors === 0 ? "✓" : "⚠"} Done.`);
+
+ console.log("\n✗ Env / docs contract is out of sync. Update .env.example, docs/ENVIRONMENT.md,");
- console.log(" or the allowlists in scripts/check-env-doc-sync.mjs and try again.");
++ console.log(" or the allowlists in scripts/check/check-env-doc-sync.mjs and try again.");
+ process.exit(1);
}
- main();
+ if (import.meta.url === `file://${process.argv[1]}`) {
+ main();
+ }
diff --cc tests/unit/check-env-doc-sync.test.ts
index 0000000000,3fc4ba637f..2db6a62c87
mode 000000,100644..100644
--- a/tests/unit/check-env-doc-sync.test.ts
+++ b/tests/unit/check-env-doc-sync.test.ts
@@@ -1,0 -1,191 +1,191 @@@
+ import test from "node:test";
+ import assert from "node:assert/strict";
+
+ import {
+ parseEnvExampleVars,
+ parseEnvDocVars,
+ runEnvDocSync,
-} from "../../scripts/check-env-doc-sync.mjs";
++} 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("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);
+ });