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

8.9 KB
Raw Blame
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))}`
  );
});