@rinorhatashi/envguard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rinor Hatashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,350 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/envguard-logo-dark.svg" />
+    <img src="assets/envguard-logo-light.svg" alt="EnvGuard" width="440" />
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Know that every environment variable your code needs is configured in every environment — before you deploy.</strong>
+</p>
+
+<p align="center">
+  EnvGuard statically analyzes your codebase to inventory every environment variable it reads, then cross-references that list against what each of your environments actually provides — surfacing <em>missing</em> variables, staging/production <em>parity drift</em>, and <em>dead</em> configuration no code uses anymore.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@rinorhatashi/envguard"><img src="https://img.shields.io/npm/v/@rinorhatashi/envguard" alt="npm version" /></a>
+  <a href="https://github.com/rinorhatashi/EnvGuard/actions/workflows/ci.yml"><img src="https://github.com/rinorhatashi/EnvGuard/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@rinorhatashi/envguard" alt="license" /></a>
+  <img src="https://img.shields.io/node/v/@rinorhatashi/envguard" alt="node version" />
+</p>
+
+<p align="center">
+  <a href="#what-it-does">What it does</a> •
+  <a href="#how-it-works">How it works</a> •
+  <a href="#runs-entirely-on-your-machine">Local &amp; private</a> •
+  <a href="#install">Install</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#github-action">GitHub Action</a>
+</p>
+
+---
+
+## The problem
+
+"It works on staging but breaks in production" is one of the most common — and most avoidable — deployment failures, and environment misconfiguration is a leading cause. The problem is structural:
+
+- Your **code** declares what it needs: `process.env.STRIPE_WEBHOOK_SECRET`, `os.environ["DATABASE_URL"]`.
+- Your **infrastructure** declares what it has: secrets in AWS, Vercel, Doppler, a `.env` file.
+- **Nothing checks that the two lists agree.**
+
+So variables drift out of sync. One gets added to production at 3am during an incident and never backfilled to staging. One gets deleted from the code but lingers in every secrets manager for years. A new service ships to production missing a variable nobody knew to add.
+
+Existing tools don't close this gap. Dotenv linters (`dotenv-linter`, `dotenv-safe`) only compare a single local `.env` against `.env.example`. Infrastructure drift tools (`driftctl`, Terragrunt) only compare cloud resources against Terraform state — not application-level variable usage. **EnvGuard is the missing link between what the code reads and what every environment provides.**
+
+## What it does
+
+EnvGuard reduces the entire question — *"is every environment configured correctly for this code?"* — to one command, `envguard scan`, and one report with four verdicts:
+
+| Status | Meaning | The failure it prevents |
+| :--- | :--- | :--- |
+| 🔴 **`MISSING`** | The code reads it, but **no** environment provides it. | A guaranteed crash the moment that code path runs. |
+| 🟡 **`PARITY`** | Present in **some** environments but not others. | The classic "works on staging, breaks in production" drift. |
+| ⚪ **`DEAD`** | Configured in an environment but **no** code reads it. | Secret sprawl and config rot — stale values that mislead. |
+| 🟢 `OK` | Read by the code and present everywhere. | Nothing to do. |
+
+Run it locally before a deploy, or wire up the [GitHub Action](#github-action) to post the report on every pull request and fail the build when something is missing or drifting.
+
+## How it works
+
+EnvGuard is a three-stage pipeline. It performs **pure static analysis** — your code is never executed, so the scan is fast and safe to run anywhere, including untrusted CI.
+
+```mermaid
+flowchart LR
+    src["Source code"] --> scan["Scanner<br/>language-aware patterns"]
+    scan --> expected["Expected vars<br/>what the code reads"]
+    envs["Environments<br/>.env files · secrets managers"] --> resolve["Resolver<br/>source adapters"]
+    resolve --> provided["Provided vars<br/>what each env has"]
+    expected --> compare{"Compare"}
+    provided --> compare
+    compare --> report["Report<br/>MISSING · PARITY · DEAD · OK"]
+```
+
+**1. Scan — build the manifest of what the code expects.**
+EnvGuard walks your source tree and applies a set of language-aware patterns to every supported file, extracting each environment-variable reference together with its file and line number. There's no build step and nothing is run; it simply reads source. The output is the *expected* manifest — the complete set of variables your code depends on.
+
+**2. Resolve — find out what each environment provides.**
+For every environment you configure, a **source adapter** reports the set of variable *names* that environment supplies. The built-in `dotenv` adapter reads the keys from a `.env` file; planned adapters query secrets managers like AWS SSM, Vercel, and Doppler. EnvGuard only ever reads variable **names — never secret values**. With no configuration at all, it auto-discovers local `.env.*` files and treats each as an environment.
+
+**3. Compare — cross-reference and classify.**
+EnvGuard builds a matrix of *what the code needs* against *what each environment has* and assigns every variable a status. `ignore` rules in your config demote intentional cases (an environment-specific flag, an allowed legacy var) to `OK`, and the `failOn` setting decides which statuses cause a non-zero exit so CI can gate on them.
+
+Each variable lands in exactly one bucket:
+
+```mermaid
+flowchart TD
+    start["Each variable"] --> incode{"Read by<br/>any code?"}
+    incode -- no --> dead["DEAD<br/>configured but unused"]
+    incode -- yes --> provided{"Provided by<br/>environments?"}
+    provided -- "none of them" --> missing["MISSING<br/>code needs it, nothing has it"]
+    provided -- "some, not all" --> parity["PARITY<br/>drift across environments"]
+    provided -- "all of them" --> ok["OK"]
+```
+
+The report is then rendered three ways — a colored terminal table for humans, JSON for tooling, and Markdown for pull-request comments.
+
+## Runs entirely on your machine
+
+EnvGuard is local-first: **no hosted service, no account, no telemetry.** The `envguard` CLI makes **no network calls** — it reads your source and `.env` files from disk, analyzes them in-process, and writes a report. Nothing about your code or configuration is uploaded anywhere, because there's no reason for it to be.
+
+```mermaid
+flowchart LR
+    subgraph local["Your machine / CI runner — everything happens here"]
+        direction LR
+        code["Source files"] --> eg["envguard CLI"]
+        cfg[".env files and envguard.yml"] --> eg
+        eg --> report["Report:<br/>terminal · JSON · Markdown"]
+    end
+    eg x--x net(["External servers · telemetry"])
+```
+
+- **Only names, never values.** EnvGuard compares variable *names*. It never reads, stores, or prints the secret values inside your `.env` files.
+- **Future cloud sources stay direct.** Planned adapters (AWS SSM, Vercel, Doppler, …) will talk **directly** to your own provider with your own credentials to list variable names — still no third-party server in the middle, and still names only.
+
+## Install
+
+```bash
+npm install -g @rinorhatashi/envguard
+```
+
+…or run it without installing:
+
+```bash
+npx @rinorhatashi/envguard scan
+```
+
+Requires **Node.js 18 or newer**.
+
+## Quick start
+
+From a project that has `.env.staging` and `.env.production` files, EnvGuard works with **zero configuration** — it discovers them automatically:
+
+```bash
+envguard scan
+```
+
+Point it at a specific directory and/or config file:
+
+```bash
+envguard scan ./services/api --config envguard.yml
+```
+
+### Try the bundled demo
+
+The repository ships a demo with source files in all five supported languages and two diverging environments:
+
+```bash
+git clone https://github.com/rinorhatashi/EnvGuard
+cd EnvGuard
+npm install && npm run build
+node dist/index.js scan examples/demo
+```
+
+## Example output
+
+```text
+EnvGuard  ·  scanned 5 files  ·  2 environments (staging, production)
+
+VARIABLE               CODE  staging  production  STATUS
+STRIPE_WEBHOOK_SECRET   ✓       ✗         ✗       MISSING
+API_KEY                 ✓       ✓         ✗       PARITY
+DEBUG                   –       ✓         ✗       DEAD
+LEGACY_TOKEN            –       ✓         ✓       DEAD
+DATABASE_URL            ✓       ✓         ✓       OK
+REDIS_URL               ✓       ✓         ✓       OK
+SENDGRID_API_KEY        ✓       ✓         ✓       OK
+
+  1 missing · 1 parity · 2 dead · 3 ok
+
+  MISSING  STRIPE_WEBHOOK_SECRET — read at src/billing.ts:3, not set in any environment
+  PARITY   API_KEY — set in staging; missing in production (read at app/server.py:5)
+  DEAD     DEBUG — set in staging but not read by any scanned file
+  DEAD     LEGACY_TOKEN — set in staging, production but not read by any scanned file
+```
+
+The same report, as machine-readable JSON or as a Markdown PR comment:
+
+```bash
+envguard scan --format json
+envguard scan --format markdown
+```
+
+## Supported languages
+
+Each language is matched with its own idiomatic access patterns. Adding a language is a small, self-contained change to [`src/scan/patterns.ts`](src/scan/patterns.ts).
+
+| Language | Extensions | Detected forms |
+| :--- | :--- | :--- |
+| Node.js / TypeScript | `.js` `.jsx` `.mjs` `.cjs` `.ts` `.tsx` `.mts` `.cts` | `process.env.X`, `process.env['X']`, `import.meta.env.X` |
+| Python | `.py` | `os.environ['X']`, `os.environ.get('X')`, `os.getenv('X')` |
+| Ruby | `.rb` `.erb` `.rake` | `ENV['X']`, `ENV.fetch('X')` |
+| Go | `.go` | `os.Getenv("X")`, `os.LookupEnv("X")` |
+| Rust | `.rs` | `std::env::var("X")`, `env::var("X")`, `std::env::var_os("X")` |
+
+## Configuration
+
+EnvGuard runs with zero config, but an `envguard.yml` at your project root unlocks declared environments, ignore rules, and CI behavior. **Every field is optional.**
+
+```yaml
+# Which environments to compare, and where to read each one's variable names.
+environments:
+  staging:
+    source: dotenv
+    path: .env.staging
+  production:
+    source: dotenv
+    path: .env.production
+
+# Statuses that make `envguard scan` exit non-zero. Defaults to MISSING + PARITY.
+failOn:
+  - MISSING
+  - PARITY
+
+# Silence intentional findings by listing variable names.
+ignore:
+  parity:
+    - DEBUG          # intentionally environment-specific — don't flag drift
+  dead:
+    - LEGACY_TOKEN   # allowed legacy var during a cleanup sprint
+  missing:
+    - OPTIONAL_VAR   # read by code but not required in any environment
+
+# Narrow what gets scanned. Defaults to every supported file under the root.
+scan:
+  include:
+    - "src/**"
+    - "app/**"
+  exclude:
+    - "**/*.test.ts"
+```
+
+If `environments` is omitted, EnvGuard auto-discovers them from local `.env.*` files (`.env` → `local`, `.env.staging` → `staging`, …), skipping `.example`, `.sample`, and `.local` files.
+
+## Sources
+
+A **source** answers a single question: *"which variables does this environment provide?"* Adapters implement one small interface ([`src/sources/types.ts`](src/sources/types.ts)) and only ever read variable **names**, never secret values — so coverage grows without touching the core.
+
+| Source | Status | Configuration |
+| :--- | :--- | :--- |
+| `dotenv` — local `.env` files | ✅ Available | `path: .env.<environment>` |
+| AWS SSM Parameter Store | 🔜 Planned | — |
+| GitHub Actions secrets | 🔜 Planned | — |
+| Vercel | 🔜 Planned | — |
+| Doppler | 🔜 Planned | — |
+| Railway / Render | 🔜 Planned | — |
+
+## CLI reference
+
+```
+envguard scan [path]
+
+Arguments:
+  path                    directory to scan (default: ".")
+
+Options:
+  -c, --config <file>     path to an envguard.yml config file
+  -f, --format <format>   output format: table | json | markdown (default: table)
+  -o, --output <file>     write the report to a file instead of stdout
+  --fail-on <list>        statuses that cause a non-zero exit:
+                          missing, parity, dead, none (default: missing,parity)
+  --no-color              disable colored output
+  -v, --version           print the EnvGuard version
+  -h, --help              show help
+```
+
+### Exit codes
+
+EnvGuard is built to gate a pipeline:
+
+| Code | Meaning |
+| :---: | :--- |
+| `0` | No findings in the `fail-on` set. |
+| `1` | At least one finding in the `fail-on` set (e.g. a `MISSING` or `PARITY` variable). |
+| `2` | EnvGuard errored (bad config, unreadable path, …). |
+
+## GitHub Action
+
+Run EnvGuard on every pull request. It posts the report as a comment that updates in place on each push:
+
+```mermaid
+sequenceDiagram
+    participant PR as Pull request
+    participant CI as GitHub Actions
+    participant EG as envguard CLI
+    PR->>CI: push / open PR
+    CI->>EG: envguard scan
+    EG-->>CI: report + exit code
+    CI->>PR: create or update the report comment
+    CI-->>CI: fail the check if MISSING / PARITY
+```
+
+Copy [`examples/github-workflow.yml`](examples/github-workflow.yml) to `.github/workflows/envguard.yml`:
+
+```yaml
+name: EnvGuard
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  envguard:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write # required to post the report comment
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rinorhatashi/EnvGuard@v1
+        with:
+          working-directory: .
+          # config: envguard.yml
+          # fail-on: missing,parity
+```
+
+When a `fail-on` status is present, the job fails — turning environment drift into a red check instead of a 3am page.
+
+| Input | Description | Default |
+| :--- | :--- | :--- |
+| `working-directory` | Directory to scan. | `.` |
+| `config` | Path to an `envguard.yml`. | _(auto)_ |
+| `fail-on` | Statuses that fail the job. | _(from config / defaults)_ |
+| `comment` | Post/update the PR comment. | `true` |
+| `version` | `envguard` npm version to run. | `latest` |
+| `github-token` | Token used to post the comment. | `${{ github.token }}` |
+
+## Roadmap
+
+- Source adapters for AWS SSM, GitHub Actions secrets, Vercel, Doppler, Railway, and Render.
+- Destructuring (`const { FOO } = process.env`) and comment-aware scanning.
+- SARIF output for GitHub code scanning, and a `--baseline` file to accept existing findings.
+- More languages (Java, PHP, .NET, Elixir).
+
+## Contributing
+
+EnvGuard is designed to be extended in small, isolated pieces:
+
+- **Add a language** — append a pattern set to [`src/scan/patterns.ts`](src/scan/patterns.ts) and a test to [`test/extract.test.ts`](test/extract.test.ts).
+- **Add a source** — implement the `SourceAdapter` interface and register it in [`src/sources/index.ts`](src/sources/index.ts).
+
+```bash
+npm install
+npm test                            # run the test suite
+npm run build                       # compile to dist/
+npm run dev -- scan examples/demo   # run straight from source
+```
+
+## License
+
+[MIT](./LICENSE) © Rinor Hatashi

package/dist/index.js

@@ -0,0 +1,659 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { readFileSync } from "fs";
+import { Command } from "commander";
+
+// src/commands/scan.ts
+import path4 from "path";
+import { writeFile } from "fs/promises";
+import { createColors } from "picocolors";
+
+// src/scan/index.ts
+import { readFile } from "fs/promises";
+import path from "path";
+
+// src/scan/walk.ts
+import fg from "fast-glob";
+
+// src/scan/patterns.ts
+var IDENT = "[A-Za-z_][A-Za-z0-9_]*";
+var KEY = `[^'"]+`;
+var LANGUAGE_PATTERNS = [
+  {
+    language: "javascript",
+    extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts"],
+    patterns: [
+      // Dot access:    process.env.FOO
+      new RegExp(`process\\.env\\.(${IDENT})`, "g"),
+      // Bracket access: process.env['FOO'] / process.env["FOO"]
+      new RegExp(`process\\.env\\[\\s*['"](${KEY})['"]\\s*\\]`, "g"),
+      // Vite-style:    import.meta.env.FOO
+      new RegExp(`import\\.meta\\.env\\.(${IDENT})`, "g")
+    ]
+  },
+  {
+    language: "python",
+    extensions: [".py"],
+    patterns: [
+      // os.environ['FOO'] / environ["FOO"]
+      new RegExp(`(?:os\\.)?environ\\[\\s*['"](${KEY})['"]\\s*\\]`, "g"),
+      // os.environ.get('FOO') / environ.get("FOO")
+      new RegExp(`(?:os\\.)?environ\\.get\\(\\s*['"](${KEY})['"]`, "g"),
+      // os.getenv('FOO') / getenv("FOO")
+      new RegExp(`(?:os\\.)?getenv\\(\\s*['"](${KEY})['"]`, "g")
+    ]
+  },
+  {
+    language: "ruby",
+    extensions: [".rb", ".erb", ".rake"],
+    patterns: [
+      // ENV['FOO'] / ENV["FOO"]
+      new RegExp(`ENV\\[\\s*['"](${KEY})['"]\\s*\\]`, "g"),
+      // ENV.fetch('FOO') / ENV.fetch("FOO")
+      new RegExp(`ENV\\.fetch\\(\\s*['"](${KEY})['"]`, "g")
+    ]
+  },
+  {
+    language: "go",
+    extensions: [".go"],
+    patterns: [
+      // os.Getenv("FOO")
+      new RegExp(`os\\.Getenv\\(\\s*"(${KEY})"\\s*\\)`, "g"),
+      // os.LookupEnv("FOO")
+      new RegExp(`os\\.LookupEnv\\(\\s*"(${KEY})"\\s*\\)`, "g")
+    ]
+  },
+  {
+    language: "rust",
+    extensions: [".rs"],
+    patterns: [
+      // std::env::var("FOO") / env::var("FOO") / std::env::var_os("FOO")
+      new RegExp(`(?:std::)?env::var(?:_os)?\\(\\s*"(${KEY})"\\s*\\)`, "g")
+    ]
+  }
+];
+var ALL_EXTENSIONS = [
+  ...new Set(LANGUAGE_PATTERNS.flatMap((p) => p.extensions))
+];
+function patternsForExtension(ext) {
+  const out = [];
+  for (const lp of LANGUAGE_PATTERNS) {
+    if (lp.extensions.includes(ext)) out.push(...lp.patterns);
+  }
+  return out;
+}
+
+// src/scan/walk.ts
+var DEFAULT_EXCLUDE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/coverage/**",
+  "**/vendor/**",
+  "**/target/**",
+  // Rust build output
+  "**/.venv/**",
+  "**/venv/**",
+  "**/__pycache__/**"
+];
+async function walkSourceFiles(root, opts = {}) {
+  const include = opts.include && opts.include.length > 0 ? opts.include : ALL_EXTENSIONS.map((ext) => `**/*${ext}`);
+  const ignore = [...DEFAULT_EXCLUDE, ...opts.exclude ?? []];
+  return fg(include, {
+    cwd: root,
+    ignore,
+    onlyFiles: true,
+    dot: false,
+    absolute: false,
+    followSymbolicLinks: false,
+    suppressErrors: true
+  });
+}
+
+// src/scan/extract.ts
+function extractFromContent(content, ext, relPath) {
+  const found = /* @__PURE__ */ new Map();
+  const patterns = patternsForExtension(ext);
+  if (patterns.length === 0) return found;
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    for (const re of patterns) {
+      for (const match of line.matchAll(re)) {
+        const name = match[1];
+        if (!name) continue;
+        const refs = found.get(name) ?? [];
+        refs.push({ file: relPath, line: i + 1 });
+        found.set(name, refs);
+      }
+    }
+  }
+  return found;
+}
+
+// src/scan/index.ts
+async function scanCode(root, opts = {}) {
+  const files = (await walkSourceFiles(root, opts)).filter(
+    (f) => ALL_EXTENSIONS.includes(path.extname(f))
+  );
+  const vars = /* @__PURE__ */ new Map();
+  let filesScanned = 0;
+  for (const rel of files) {
+    let content;
+    try {
+      content = await readFile(path.join(root, rel), "utf8");
+    } catch {
+      continue;
+    }
+    filesScanned++;
+    const fileVars = extractFromContent(content, path.extname(rel), rel);
+    for (const [name, refs] of fileVars) {
+      const existing = vars.get(name) ?? [];
+      existing.push(...refs);
+      vars.set(name, existing);
+    }
+  }
+  return { vars, filesScanned };
+}
+
+// src/config/load.ts
+import { readFile as readFile2, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import path2 from "path";
+import { parse as parseYaml } from "yaml";
+var CONFIG_NAMES = ["envguard.yml", "envguard.yaml"];
+async function loadConfig(root, explicitPath) {
+  let configPath;
+  if (explicitPath) {
+    configPath = path2.isAbsolute(explicitPath) ? explicitPath : path2.join(root, explicitPath);
+    if (!existsSync(configPath)) {
+      throw new Error(`config file not found: ${explicitPath}`);
+    }
+  } else {
+    for (const name of CONFIG_NAMES) {
+      const candidate = path2.join(root, name);
+      if (existsSync(candidate)) {
+        configPath = candidate;
+        break;
+      }
+    }
+  }
+  if (configPath) {
+    const raw = await readFile2(configPath, "utf8");
+    const config = parseYaml(raw) ?? {};
+    if (!config.environments || Object.keys(config.environments).length === 0) {
+      config.environments = await discoverDotenvEnvironments(root);
+      return { config, configPath, autoDiscovered: true };
+    }
+    return { config, configPath, autoDiscovered: false };
+  }
+  const environments = await discoverDotenvEnvironments(root);
+  return { config: { environments }, autoDiscovered: true };
+}
+async function discoverDotenvEnvironments(root) {
+  let entries;
+  try {
+    entries = await readdir(root);
+  } catch {
+    return {};
+  }
+  const environments = {};
+  for (const file of entries.sort()) {
+    if (!file.startsWith(".env")) continue;
+    if (/\.(example|sample|local)$/.test(file)) continue;
+    let name;
+    if (file === ".env") name = "local";
+    else if (file.startsWith(".env.")) name = file.slice(".env.".length);
+    else continue;
+    if (!name) continue;
+    environments[name] = { source: "dotenv", path: file };
+  }
+  return environments;
+}
+
+// src/sources/dotenv.ts
+import { readFile as readFile3 } from "fs/promises";
+import path3 from "path";
+import dotenv from "dotenv";
+var dotenvAdapter = {
+  id: "dotenv",
+  async load(envName, config, root) {
+    const rel = config.path ?? `.env.${envName}`;
+    const abs = path3.isAbsolute(rel) ? rel : path3.join(root, rel);
+    try {
+      const content = await readFile3(abs, "utf8");
+      const parsed = dotenv.parse(content);
+      return {
+        name: envName,
+        source: "dotenv",
+        origin: rel,
+        vars: new Set(Object.keys(parsed)),
+        available: true
+      };
+    } catch {
+      return {
+        name: envName,
+        source: "dotenv",
+        origin: rel,
+        vars: /* @__PURE__ */ new Set(),
+        available: false
+      };
+    }
+  }
+};
+
+// src/sources/index.ts
+var ADAPTERS = {
+  [dotenvAdapter.id]: dotenvAdapter
+};
+async function resolveEnvironments(config, root) {
+  const warnings = [];
+  const environments = [];
+  for (const [name, envCfg] of Object.entries(config.environments ?? {})) {
+    const sourceId = envCfg.source ?? "dotenv";
+    const adapter = ADAPTERS[sourceId];
+    if (!adapter) {
+      warnings.push(
+        `environment "${name}": unknown source "${sourceId}" \u2014 skipping`
+      );
+      continue;
+    }
+    const env = await adapter.load(name, envCfg, root);
+    if (!env.available) {
+      warnings.push(
+        `environment "${name}": could not read ${env.origin} \u2014 skipping`
+      );
+      continue;
+    }
+    environments.push(env);
+  }
+  return { environments, warnings };
+}
+
+// src/compare/index.ts
+var STATUS_ORDER = {
+  MISSING: 0,
+  PARITY: 1,
+  DEAD: 2,
+  OK: 3
+};
+function buildReport(code, environments, config, root, generatedAt, warnings = []) {
+  const ignoreParity = new Set(config.ignore?.parity ?? []);
+  const ignoreDead = new Set(config.ignore?.dead ?? []);
+  const ignoreMissing = new Set(config.ignore?.missing ?? []);
+  const totalEnvs = environments.length;
+  const allVars = /* @__PURE__ */ new Set();
+  for (const name of code.vars.keys()) allVars.add(name);
+  for (const env of environments) for (const name of env.vars) allVars.add(name);
+  const findings = [];
+  for (const name of allVars) {
+    const inCode = code.vars.has(name);
+    const presence = {};
+    let presentCount = 0;
+    for (const env of environments) {
+      const has = env.vars.has(name);
+      presence[env.name] = has;
+      if (has) presentCount++;
+    }
+    let status;
+    if (!inCode) {
+      status = ignoreDead.has(name) ? "OK" : "DEAD";
+    } else if (totalEnvs > 0 && presentCount === 0) {
+      status = ignoreMissing.has(name) ? "OK" : "MISSING";
+    } else if (totalEnvs > 0 && presentCount < totalEnvs) {
+      status = ignoreParity.has(name) ? "OK" : "PARITY";
+    } else {
+      status = "OK";
+    }
+    findings.push({
+      name,
+      status,
+      inCode,
+      references: code.vars.get(name) ?? [],
+      presence
+    });
+  }
+  findings.sort(
+    (a, b) => STATUS_ORDER[a.status] - STATUS_ORDER[b.status] || a.name.localeCompare(b.name)
+  );
+  const summary = {
+    MISSING: 0,
+    PARITY: 0,
+    DEAD: 0,
+    OK: 0
+  };
+  for (const f of findings) summary[f.status]++;
+  return {
+    generatedAt,
+    root,
+    environments: environments.map((e) => e.name),
+    summary,
+    findings,
+    warnings
+  };
+}
+
+// src/report/table.ts
+var cell = (text, render) => ({
+  text,
+  render: render ?? text
+});
+function renderTable(report, opts) {
+  const c = opts.colors;
+  const lines = [];
+  const envCount = report.environments.length;
+  const envList = envCount > 0 ? report.environments.join(", ") : "none";
+  const fileWord = opts.filesScanned === 1 ? "file" : "files";
+  const envWord = envCount === 1 ? "environment" : "environments";
+  lines.push(
+    c.bold("EnvGuard") + c.dim(
+      `  \xB7  scanned ${opts.filesScanned} ${fileWord}  \xB7  ${envCount} ${envWord} (${envList})`
+    )
+  );
+  lines.push("");
+  if (report.findings.length === 0) {
+    lines.push(
+      c.dim("No environment variables found in code or environments.")
+    );
+    return lines.join("\n");
+  }
+  if (envCount === 0) {
+    lines.push(
+      c.yellow("No environments configured.") + c.dim(
+        " Add .env.<environment> files or an envguard.yml to compare against."
+      )
+    );
+    lines.push("");
+    lines.push(c.dim(`Variables referenced in code (${report.findings.length}):`));
+    for (const f of report.findings) {
+      const ref = f.references[0];
+      const loc = ref ? c.dim(`  ${ref.file}:${ref.line}`) : "";
+      lines.push(`  ${f.name}${loc}`);
+    }
+    return lines.join("\n");
+  }
+  const header = [
+    cell("VARIABLE"),
+    cell("CODE"),
+    ...report.environments.map((e) => cell(e)),
+    cell("STATUS")
+  ];
+  const aligns = [
+    "left",
+    "center",
+    ...report.environments.map(() => "center"),
+    "left"
+  ];
+  const rows = [header];
+  for (const f of report.findings) {
+    const nameCell = f.status === "OK" ? cell(f.name, c.dim(f.name)) : cell(f.name);
+    const codeCell = f.inCode ? cell("\u2713", c.cyan("\u2713")) : cell("\u2013", c.dim("\u2013"));
+    const envCells = report.environments.map(
+      (e) => f.presence[e] ? cell("\u2713", c.green("\u2713")) : cell("\u2717", c.red("\u2717"))
+    );
+    rows.push([nameCell, codeCell, ...envCells, statusCell(f.status, c)]);
+  }
+  const widths = header.map(
+    (_, col) => Math.max(...rows.map((r) => r[col].text.length))
+  );
+  const headerRow = rows[0].map((cl) => cell(cl.text, c.dim(cl.text)));
+  lines.push(renderRow(headerRow, widths, aligns));
+  for (let i = 1; i < rows.length; i++) {
+    lines.push(renderRow(rows[i], widths, aligns));
+  }
+  lines.push("");
+  lines.push(summaryLine(report, c));
+  const details = renderDetails(report, c);
+  if (details.length > 0) {
+    lines.push("");
+    lines.push(...details);
+  }
+  if (report.warnings.length > 0) {
+    lines.push("");
+    for (const w of report.warnings) {
+      lines.push(c.yellow("warning: ") + w);
+    }
+  }
+  return lines.join("\n");
+}
+function renderRow(cells, widths, aligns) {
+  return cells.map((cl, i) => pad(cl, widths[i] ?? cl.text.length, aligns[i] ?? "left")).join("  ").replace(/\s+$/, "");
+}
+function pad(cl, width, align) {
+  const space = Math.max(0, width - cl.text.length);
+  if (align === "center") {
+    const left = Math.floor(space / 2);
+    return " ".repeat(left) + cl.render + " ".repeat(space - left);
+  }
+  return cl.render + " ".repeat(space);
+}
+function statusCell(status, c) {
+  switch (status) {
+    case "MISSING":
+      return cell("MISSING", c.bold(c.red("MISSING")));
+    case "PARITY":
+      return cell("PARITY", c.yellow("PARITY"));
+    case "DEAD":
+      return cell("DEAD", c.dim("DEAD"));
+    case "OK":
+      return cell("OK", c.green("OK"));
+  }
+}
+function summaryLine(report, c) {
+  const s = report.summary;
+  const parts = [
+    s.MISSING > 0 ? c.red(`${s.MISSING} missing`) : c.dim(`${s.MISSING} missing`),
+    s.PARITY > 0 ? c.yellow(`${s.PARITY} parity`) : c.dim(`${s.PARITY} parity`),
+    c.dim(`${s.DEAD} dead`),
+    c.green(`${s.OK} ok`)
+  ];
+  return "  " + parts.join(c.dim(" \xB7 "));
+}
+function renderDetails(report, c) {
+  const out = [];
+  for (const f of report.findings) {
+    if (f.status === "OK") continue;
+    const first = f.references[0];
+    const more = f.references.length > 1 ? c.dim(` (+${f.references.length - 1} more)`) : "";
+    const where = first ? c.dim(`${first.file}:${first.line}`) + more : c.dim("\u2014");
+    if (f.status === "MISSING") {
+      out.push(
+        `  ${c.bold(c.red("MISSING"))}  ${c.bold(f.name)} \u2014 read at ${where}, not set in any environment`
+      );
+    } else if (f.status === "PARITY") {
+      const has = report.environments.filter((e) => f.presence[e]);
+      const missing = report.environments.filter((e) => !f.presence[e]);
+      out.push(
+        `  ${c.yellow("PARITY")}   ${c.bold(f.name)} \u2014 set in ${has.join(", ")}; missing in ${c.red(missing.join(", "))} (read at ${where})`
+      );
+    } else if (f.status === "DEAD") {
+      const has = report.environments.filter((e) => f.presence[e]);
+      out.push(
+        `  ${c.dim("DEAD")}     ${c.bold(f.name)} \u2014 set in ${has.join(", ")} but not read by any scanned file`
+      );
+    }
+  }
+  return out;
+}
+
+// src/report/markdown.ts
+var MARKDOWN_MARKER = "<!-- envguard-report -->";
+function renderMarkdown(report) {
+  const s = report.summary;
+  const out = [];
+  out.push(MARKDOWN_MARKER);
+  out.push("## EnvGuard \u2014 environment variable report");
+  out.push("");
+  const envText = report.environments.length ? "`" + report.environments.join("`, `") + "`" : "_no environments configured_";
+  out.push(
+    `**${s.MISSING} missing \xB7 ${s.PARITY} parity drift \xB7 ${s.DEAD} dead \xB7 ${s.OK} ok** across ${envText}.`
+  );
+  out.push("");
+  const missing = report.findings.filter((f) => f.status === "MISSING");
+  const parity = report.findings.filter((f) => f.status === "PARITY");
+  const dead = report.findings.filter((f) => f.status === "DEAD");
+  if (missing.length > 0) {
+    out.push("### \u274C Missing \u2014 code reads it, no environment provides it");
+    out.push("");
+    out.push("| Variable | Read at |");
+    out.push("| --- | --- |");
+    for (const f of missing) out.push(`| \`${f.name}\` | ${refList(f)} |`);
+    out.push("");
+  }
+  if (parity.length > 0) {
+    out.push(
+      "### \u26A0\uFE0F Parity drift \u2014 present in some environments, missing in others"
+    );
+    out.push("");
+    out.push(`| Variable | ${report.environments.join(" | ")} | Read at |`);
+    out.push(
+      `| --- |${report.environments.map(() => " --- |").join("")} --- |`
+    );
+    for (const f of parity) {
+      const cells = report.environments.map((e) => f.presence[e] ? "\u2705" : "\u274C").join(" | ");
+      out.push(`| \`${f.name}\` | ${cells} | ${refList(f)} |`);
+    }
+    out.push("");
+  }
+  if (dead.length > 0) {
+    out.push("### \u{1F9F9} Dead \u2014 configured but no code reads it");
+    out.push("");
+    out.push("| Variable | Configured in |");
+    out.push("| --- | --- |");
+    for (const f of dead) {
+      const has = report.environments.filter((e) => f.presence[e]).join(", ");
+      out.push(`| \`${f.name}\` | ${has} |`);
+    }
+    out.push("");
+  }
+  if (missing.length === 0 && parity.length === 0 && dead.length === 0) {
+    out.push(
+      "\u2705 Every variable the code reads is present in all configured environments, and nothing is configured that the code doesn't read."
+    );
+    out.push("");
+  }
+  if (report.warnings.length > 0) {
+    out.push("> **Warnings**");
+    for (const w of report.warnings) out.push(`> - ${w}`);
+    out.push("");
+  }
+  out.push(
+    "<sub>EnvGuard \xB7 run <code>envguard scan</code> locally to reproduce.</sub>"
+  );
+  return out.join("\n");
+}
+function refList(f) {
+  if (f.references.length === 0) return "\u2014";
+  const shown = f.references.slice(0, 3).map((r) => `\`${r.file}:${r.line}\``).join(", ");
+  const extra = f.references.length > 3 ? ` +${f.references.length - 3} more` : "";
+  return shown + extra;
+}
+
+// src/commands/scan.ts
+var FORMATS = ["table", "json", "markdown"];
+var FAILABLE = ["MISSING", "PARITY", "DEAD"];
+async function runScan(targetPath, options) {
+  const root = path4.resolve(process.cwd(), targetPath || ".");
+  const format = (options.format ?? "table").toLowerCase();
+  if (!FORMATS.includes(format)) {
+    throw new Error(
+      `unknown format "${options.format}" (expected: ${FORMATS.join(", ")})`
+    );
+  }
+  const { config } = await loadConfig(root, options.config);
+  const code = await scanCode(root, {
+    include: config.scan?.include,
+    exclude: config.scan?.exclude
+  });
+  const { environments, warnings } = await resolveEnvironments(config, root);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const report = buildReport(
+    code,
+    environments,
+    config,
+    root,
+    generatedAt,
+    warnings
+  );
+  if (format === "json") {
+    const payload = { version: 1, ...report, filesScanned: code.filesScanned };
+    await emit(JSON.stringify(payload, null, 2) + "\n", options.output);
+  } else if (format === "markdown") {
+    await emit(renderMarkdown(report) + "\n", options.output);
+  } else {
+    const enabled = options.color !== false && Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+    const colors = createColors(enabled);
+    const text = renderTable(report, {
+      colors,
+      filesScanned: code.filesScanned
+    });
+    await emit(text + "\n", options.output);
+    for (const w of warnings) {
+      process.stderr.write(colors.yellow("warning: ") + w + "\n");
+    }
+  }
+  const failOn = resolveFailOn(options.failOn, config.failOn);
+  const failed = failOn.some((s) => report.summary[s] > 0);
+  return failed ? 1 : 0;
+}
+async function emit(content, output) {
+  if (output) {
+    const dest = path4.isAbsolute(output) ? output : path4.resolve(process.cwd(), output);
+    await writeFile(dest, content);
+  } else {
+    process.stdout.write(content);
+  }
+}
+function resolveFailOn(flag, configFailOn) {
+  if (flag !== void 0) return parseStatusList(flag);
+  if (configFailOn && configFailOn.length > 0) {
+    return configFailOn.map((s) => String(s).toUpperCase()).filter((s) => FAILABLE.includes(s));
+  }
+  return ["MISSING", "PARITY"];
+}
+function parseStatusList(raw) {
+  const tokens = raw.split(",").map((t) => t.trim().toUpperCase()).filter(Boolean);
+  if (tokens.includes("NONE")) return [];
+  const out = [];
+  for (const t of tokens) {
+    if (FAILABLE.includes(t)) out.push(t);
+    else
+      throw new Error(
+        `invalid --fail-on value "${t}" (expected any of: missing, parity, dead, none)`
+      );
+  }
+  return out;
+}
+
+// src/index.ts
+var pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+var program = new Command();
+program.name("envguard").description(
+  "Inventory the environment variables your code expects and check them against every environment."
+).version(pkg.version, "-v, --version", "print the EnvGuard version");
+program.command("scan", { isDefault: true }).description(
+  "Scan source for env var usage and compare it against every configured environment."
+).argument("[path]", "directory to scan", ".").option("-c, --config <file>", "path to an envguard.yml config file").option("-f, --format <format>", "output format: table | json | markdown", "table").option("-o, --output <file>", "write the report to a file instead of stdout").option(
+  "--fail-on <list>",
+  "comma-separated statuses that cause a non-zero exit: missing, parity, dead, none"
+).option("--no-color", "disable colored output").action(async (pathArg, opts) => {
+  try {
+    process.exitCode = await runScan(pathArg, {
+      config: opts.config,
+      format: opts.format,
+      output: opts.output,
+      failOn: opts.failOn,
+      color: opts.color
+    });
+  } catch (err) {
+    process.stderr.write(`envguard: ${err.message}
+`);
+    process.exitCode = 2;
+  }
+});
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@rinorhatashi/envguard",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Inventory the environment variables your code expects and check them against every environment — surfacing missing vars, staging/production parity drift, and dead configuration.",
+  "keywords": [
+    "env",
+    "environment-variables",
+    "dotenv",
+    "configuration",
+    "parity",
+    "drift",
+    "secrets",
+    "cli",
+    "github-action",
+    "devops"
+  ],
+  "license": "MIT",
+  "author": "Rinor Hatashi",
+  "homepage": "https://github.com/rinorhatashi/EnvGuard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rinorhatashi/EnvGuard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rinorhatashi/EnvGuard/issues"
+  },
+  "type": "module",
+  "bin": {
+    "envguard": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "envguard": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "fast-glob": "^3.3.2",
+    "picocolors": "^1.1.0",
+    "yaml": "^2.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}