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
Merge FASE 2: env audit
diegosouzapw6991024935ee
diff --cc scripts/check/check-env-doc-sync.mjsindex 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:urlimport { 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.tsindex 0000000000,3fc4ba637f..2db6a62c87mode 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);+ });