dotenv-diff 2.6.1 → 2.6.3

package/docs/expiration_warnings.md

@@ -0,0 +1,111 @@
+# Expiration Warnings
+
+Expiration warnings help you track time-limited environment variables such as temporary API keys, tokens, and credentials.
+
+By annotating a key with an expiration date, `dotenv-diff` can:
+
+- warn when a key is expired
+- warn when a key is close to expiration
+- fail the process in `--strict` mode
+
+## Syntax
+
+Add an expiration annotation directly above the variable:
+
+```env
+# @expire 2026-12-31
+TEMP_API_TOKEN=abc123
+```
+
+Supported annotation styles:
+
+```env
+# @expire 2026-12-31
+TOKEN_A=...
+
+// @expire 2026-12-31
+TOKEN_B=...
+
+@expire 2026-12-31
+TOKEN_C=...
+
+# expire 2026-12-31
+TOKEN_D=...
+```
+
+### Rules
+
+- Date format must be `YYYY-MM-DD`
+- `@` is optional (`expire 2026-12-31` also works)
+- The annotation applies to the **next env key only**
+- If no key follows, no warning is created
+
+## Warning output
+
+When expiration annotations are found, CLI output includes an `Expiration warnings` section.
+
+Severity is shown from `daysLeft`:
+
+- `< 0`: expired (`EXPIRED ... days ago`)
+- `0`: `EXPIRES TODAY`
+- `1`: `expires tomorrow`
+- `2-3`: urgent warning
+- `4-7`: warning
+- `> 7`: still shown as informational warning
+
+## Strict mode
+
+In strict mode, expiration warnings are treated as blocking warnings and return exit code `1`.
+
+```bash
+dotenv-diff --strict
+```
+
+If expiration warnings exist, strict mode includes them in the strict error summary.
+
+## Enable / disable
+
+Expiration warnings are enabled by default.
+
+Disable via CLI:
+
+```bash
+dotenv-diff --no-expire-warnings
+```
+
+Or disable in `dotenv-diff.config.json`:
+
+```json
+{
+	"expireWarnings": false
+}
+```
+
+You can also force-enable explicitly:
+
+```bash
+dotenv-diff --expire-warnings
+```
+
+## JSON output
+
+With `--json`, expiration warnings are returned in the `expireWarnings` field:
+
+```json
+{
+	"expireWarnings": [
+		{
+			"key": "TEMP_API_TOKEN",
+			"date": "2026-12-31",
+			"daysLeft": 30
+		}
+	]
+}
+```
+
+## Best practices
+
+- Use `YYYY-MM-DD` consistently
+- Keep expiration comments immediately above the key they belong to
+- Add a short comment describing why the key expires
+- Combine with `--strict` in CI/CD to catch expired credentials early

package/docs/frameworks/index.md

@@ -0,0 +1,24 @@
+# Framework-Specific Warnings
+
+This section explains which framework-specific environment variable are currently supported and how it works.
+
+---
+
+## Supported frameworks
+
+- [SvelteKit warnings](./sveltekit_warnings.md)
+- [Next.js warnings](./nextjs_warnings.md)
+
+---
+
+## Framework detection
+
+dotenv-diff detects framework rules automatically from `package.json` in your current working directory.
+
+E.g.
+
+- If `@sveltejs/kit` is present, SvelteKit rules are enabled.
+- If `next` is present, Next.js rules are enabled.
+- If neither is detected, framework-specific warnings are skipped.
+
+---

package/docs/frameworks/nextjs_warnings.md

@@ -0,0 +1,56 @@
+# Next.js warnings
+
+`dotenv-diff` includes Next.js-specific rules to catch unsafe or invalid environment variable usage.
+
+This page reflects the currently implemented rule behavior.
+
+## 1 Client code must use `NEXT_PUBLIC_` variables only
+
+When a file is treated as client code (`"use client"` or Pages Router client files), non-`NEXT_PUBLIC_` variables trigger a warning.
+
+```tsx
+"use client";
+console.log(process.env.SECRET_TOKEN);
+```
+
+Warning:
+
+`Server-only variable accessed from client code`
+
+## 2 `import.meta.env` is not supported in Next.js
+
+```ts
+console.log(import.meta.env.PRIVATE_KEY);
+```
+
+Warning:
+
+`Next.js uses process.env, not import.meta.env (Vite syntax)`
+
+## 3 Sensitive-looking `NEXT_PUBLIC_` names trigger exposure warnings
+
+If a `NEXT_PUBLIC_` variable contains `SECRET`, `PRIVATE`, or `PASSWORD`, a warning is produced.
+
+```ts
+console.log(process.env.NEXT_PUBLIC_SECRET_PASSWORD);
+```
+
+Warning:
+
+`Potential sensitive environment variable exposed to the browser`
+
+## What is allowed
+
+Server files (for example API routes and other server-only code) can use private environment variables without framework warnings.
+
+## Summary of rules
+
+- Client code → only `NEXT_PUBLIC_*`
+- `import.meta.env` → not valid in Next.js
+- Sensitive names in `NEXT_PUBLIC_*` → warning
+
+## Best practices
+
+- Use `NEXT_PUBLIC_*` only for browser-safe values
+- Keep secrets in server-only code paths
+- Do not use `import.meta.env` in Next.js projects

package/docs/frameworks/sveltekit_warnings.md

@@ -0,0 +1,130 @@
+# SvelteKit warnings
+
+`dotenv-diff` includes SvelteKit-specific rules for invalid or unsafe environment variable usage.
+
+This page documents the exact warning behavior currently implemented.
+
+## 1 `import.meta.env` must use `VITE_` prefix
+
+```ts
+import.meta.env.PUBLIC_URL
+```
+
+Warning:
+
+`Variables accessed through import.meta.env must start with "VITE_"`
+
+Correct usage:
+
+```ts
+import.meta.env.VITE_PUBLIC_URL
+```
+
+## 2 `process.env` should only be used in server files
+
+```ts
+process.env.VITE_SECRET
+```
+
+Warning:
+
+`process.env should only be used in server files`
+
+## 3 `$env/dynamic/private` cannot be used in client-side code
+
+```svelte
+<script lang="ts">
+  import { env } from '$env/dynamic/private';
+  console.log(env.SECRET_KEY);
+</script>
+```
+
+Warning:
+
+`$env/dynamic/private cannot be used in client-side code`
+
+## 4 `$env/dynamic/private` variables must not start with `PUBLIC_`
+
+```ts
+import { env } from '$env/dynamic/private';
+console.log(env.PUBLIC_API_URL);
+```
+
+Warning:
+
+`$env/dynamic/private variables must not start with "PUBLIC_"`
+
+## 5 `$env/dynamic/public` variables must start with `PUBLIC_`
+
+```ts
+import { env } from '$env/dynamic/public';
+console.log(env.API_URL);
+```
+
+Warning:
+
+`$env/dynamic/public variables must start with "PUBLIC_"`
+
+## 6 `$env/static/private` variables must not start with `PUBLIC_`
+
+```ts
+import { PUBLIC_KEY } from '$env/static/private';
+```
+
+Warning:
+
+`$env/static/private variables must not start with "PUBLIC_"`
+
+## 7 `$env/static/private` cannot be used in client-side code
+
+```svelte
+<script lang="ts">
+  import { SECRET_KEY } from '$env/static/private';
+</script>
+```
+
+Warning:
+
+`$env/static/private variables cannot be used in client-side code`
+
+## 8 `$env/static/public` variables must start with `PUBLIC_`
+
+```ts
+import { API_URL } from '$env/static/public';
+```
+
+Warning:
+
+`$env/static/public variables must start with "PUBLIC_"`
+
+## 9 Sensitive-looking `PUBLIC_` / `VITE_` names trigger exposure warnings
+
+If a client-exposed name contains `SECRET`, `PRIVATE`, or `PASSWORD`, a warning is produced.
+
+```svelte
+<script lang="ts">
+  import { env } from '$env/dynamic/public';
+  console.log(env.PUBLIC_SECRET_PASSWORD);
+</script>
+```
+
+Warning:
+
+`Potential sensitive environment variable exposed to the browser`
+
+## Summary of rules
+
+- `import.meta.env` → must use `VITE_*`
+- `process.env` → server files only
+- `$env/dynamic/private` → server-only, never `PUBLIC_*`
+- `$env/dynamic/public` → must use `PUBLIC_*`
+- `$env/static/private` → server-only, never `PUBLIC_*`
+- `$env/static/public` → must use `PUBLIC_*`
+- Sensitive client-exposed names (`PUBLIC_*`/`VITE_*`) → warning
+
+## Best practices
+
+- Use `PUBLIC_*` only for values intended for the browser
+- Use `VITE_*` only via `import.meta.env`
+- Keep private variables in server-only code
+- Never expose secrets via `PUBLIC_*` or `VITE_*`

package/docs/git_hooks_ci.md

@@ -0,0 +1,51 @@
+# Git Hooks and CI/CD
+
+`dotenv-diff` is a CLI-first tool and does not manage git hooks or CI workflows by itself.
+
+Instead, it is built to integrate cleanly with your existing tooling, such as Husky pre-commit hooks and GitHub Actions.
+
+## Using dotenv-diff as a pre-commit hook
+
+Running `dotenv-diff` before each commit helps catch missing, unused, and misused environment variables early.
+
+A common setup is Husky + lint-staged, where `dotenv-diff` runs automatically on commit.
+
+## Running dotenv-diff in GitHub Actions
+
+Use `dotenv-diff` in CI to validate environment variable consistency on pull requests.
+
+This is especially useful to keep `.env.example` in sync with real usage in code.
+
+### Example GitHub Action
+
+`.github/workflows/dotenv-diff.yml`
+
+```yaml
+name: dotenv-diff
+
+on: [pull_request]
+
+jobs:
+  env-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+      - run: npm ci
+      - run: npx dotenv-diff --example .env.example --strict
+```
+
+## Why use this in hooks and CI
+
+- Prevent commits that introduce undocumented environment variables
+- Catch framework-specific env usage issues early
+- Keep `.env.example` accurate across contributors and pull requests
+
+## Best practices
+
+- Use `--example` to validate against your reference file
+- Use `--strict` in CI for fail-fast behavior on warnings
+- Keep hook checks fast and predictable
+- Pair with monorepo patterns (`--include-files`) where relevant
+
+---

package/docs/ignore_comments.md

@@ -0,0 +1,82 @@
+# Ignore Comments
+
+dotenv-diff can skip certain lines or code sections from being flagged during scanning. This is helpful when you know a specific warning is safe in your source code.
+
+Ignore comments work for both secret detection and environment variable usage scanning, allowing you to suppress false positives while maintaining security in the rest of your codebase.
+
+## Table of Contents
+
+- [Single Line Ignore](#single-line-ignore)
+- [Block Ignore](#block-ignore)
+- [When to Use](#when-to-use)
+
+## Single Line Ignore
+
+You can ignore a single line by adding an inline comment with `dotenv-diff-ignore`.
+
+### JavaScript/TypeScript
+
+```typescript
+const apiKey = 'safe_secret_123123123'; // dotenv-diff-ignore
+```
+
+This will suppress potential secret warnings for this specific line but still allow dotenv-diff to report other issues elsewhere in the file.
+
+### JavaScript Block Comments
+
+```javascript
+const url = 'https://safe.example.com'; /* dotenv-diff-ignore */
+```
+
+### HTML
+
+```html
+<a href="https://safe.example.com">Link</a> <!-- dotenv-diff-ignore -->
+```
+
+### JSX/TSX Files
+
+```ts
+<p>Database: {process.env.DATABASE_URL}</p> {/* <!-- dotenv-diff-ignore --> */}
+```
+
+## Block Ignore
+
+You can ignore entire sections of code using start and end markers. All lines between the markers will be skipped during scanning.
+
+### HTML/JSX/TSX
+
+```html
+<!-- dotenv-diff-ignore-start -->
+<p>Hardcoded data, images or links that are safe to ignore</p>
+<img src="https://cdn.safe-service.com/image.png" />
+<a href="https://legacy-system.com/api">Legacy API</a>
+<!-- dotenv-diff-ignore-end -->
+```
+
+```ts
+// dotenv-diff-ignore-start
+const legacyApiKey = 'legacy_secret_456456456';
+const safeKey = process.env.SAFE_KEY;
+// dotenv-diff-ignore-end
+```
+
+This is particularly useful for:
+
+- Legacy code sections that can't be easily refactored
+- Generated HTML or markup with safe hardcoded values
+- Documentation or example code embedded in your source
+- Third-party integrations with known safe URLs
+
+Ignore markers are case-insensitive.
+
+## Alternative Configuration
+
+If you need to ignore entire files, folders, or key patterns globally, consider using configuration options instead:
+
+- `--exclude-files <patterns>` - Skip entire files or directories from scanning
+- `--ignore <keys>` - Ignore specific environment variable keys
+- `--ignore-regex <patterns>` - Ignore keys matching regex patterns
+- `--ignore-urls <list>` - Ignore specific URLs during secret detection
+
+See the [Configuration and Flags](./configuration_and_flags.md) documentation for more details.

package/docs/index.md

@@ -0,0 +1,87 @@
+# dotenv-diff Documentation
+
+Welcome to the official documentation for `dotenv-diff`.
+
+`dotenv-diff` scans your codebase for environment variable usage and compares it against your `.env` and/or `.env.example` files.
+
+It helps you:
+
+- Detect missing environment variables
+- Detect unused variables in your `.env` files
+- Prevent runtime crashes caused by undefined `process.env` usage
+- Enforce consistent environment configuration across teams
+- Apply framework-specific validation rules (SvelteKit, Next.js, etc.)
+
+The tool is designed to be fast, CI-friendly, and safe to run in large projects and monorepos.
+
+---
+
+## Quick Start
+
+Install:
+
+```bash
+npm install dotenv-diff
+```
+
+Run:
+
+```bash
+npx dotenv-diff
+```
+
+---
+
+The extension recognises the following patterns:
+
+```typescript
+// Node.js – dot and bracket notation
+process.env.MY_KEY
+process.env["MY_KEY"]
+process.env['MY_KEY']
+
+// Node.js – destructuring
+const { MY_KEY } = process.env
+const { MY_KEY: alias, OTHER_KEY = "fallback" } = process.env
+
+// Vite / import.meta
+import.meta.env.MY_KEY
+import.meta.env["MY_KEY"]
+import.meta.env['MY_KEY']
+
+// SvelteKit – dynamic (env object)
+import { env } from '$env/dynamic/private';
+import { env } from '$env/dynamic/public';
+env.MY_KEY
+
+// SvelteKit – static (named imports)
+import { MY_KEY } from '$env/static/private';
+import { MY_KEY } from '$env/static/public';
+MY_KEY
+```
+
+Only `UPPER_CASE` key names are matched, which is the standard convention for environment variables.
+
+Default scanned file types: .ts, .js, jsx, tsx, vue, .mjs, .cjs, .svelte
+
+---
+
+## Table of Contents
+
+| Document | Description |
+|---|---|
+| [Configuration and Flags](./configuration_and_flags.md) | Full CLI/config reference for options and behavior |
+| [Expiration Warnings](./expiration_warnings.md) | How `@expire` annotations work and strict mode integration |
+| [Ignore Comments](./ignore_comments.md) | Suppress false positives with inline/block ignore markers |
+| [Monorepo Support](./monorepo_support.md) | Scan shared packages and cross-folder usage in monorepos |
+| [Git Hooks and CI/CD](./git_hooks_ci.md) | Integrate dotenv-diff with Husky, lint-staged, and GitHub Actions |
+| [Framework Warnings (Index)](./frameworks/index.md) | Framework detection and links to supported framework rules |
+| [SvelteKit warnings](./frameworks/sveltekit_warnings.md) | SvelteKit-specific env validation rules |
+| [Next.js warnings](./frameworks/nextjs_warnings.md) | Next.js-specific env validation rules |
+
+---
+
+## Quick links
+
+- [Issue Tracker](https://github.com/Chrilleweb/dotenv-diff/issues)
+- [CHANGELOG](../CHANGELOG.md)

package/docs/monorepo_support.md

@@ -0,0 +1,63 @@
+# Monorepo Support
+
+In monorepos with multiple apps and shared packages, environment variables are often referenced across folder boundaries.
+
+`dotenv-diff` supports this by scanning from your current app and letting you extend the scan scope to shared folders.
+
+## Scanning shared packages
+
+By default, `dotenv-diff` scans from the current working directory.
+
+In a monorepo, use `--include-files` to add shared package paths:
+
+```json
+{
+  "scripts": {
+    "dotenv-diff": "dotenv-diff --example .env.example --include-files '../../packages/**/*'"
+  }
+}
+```
+
+### What this does
+
+- Scans the current application
+- Compares your environment variables against `.env.example`
+- Includes shared packages from the monorepo (for example `../../packages/**/*`)
+- Detects env usage across app + shared code
+
+## Using a configuration file
+
+For larger monorepos, move file patterns and ignores to `dotenv-diff.config.json`:
+
+```json
+{
+  "example": ".env.example",
+  "includeFiles": ["../../packages/**/*"],
+}
+```
+
+Then run:
+
+```bash
+dotenv-diff
+```
+
+## `--include-files` vs `--files`
+
+- `--include-files` **extends** default scan patterns
+- `--files` **replaces** default scan patterns completely
+
+For monorepos, `--include-files` is usually the best default because you keep built-in scanning and only add shared paths.
+
+## Why this matters in monorepos
+
+- Undocumented variables are harder to detect when usage is spread across apps/packages
+- Keeping `.env.example` accurate becomes harder as shared code grows
+- One app-local scan can still include cross-folder usage and reduce drift
+
+## Best practices
+
+- Run `dotenv-diff` from the app folder that owns the `.env` / `.env.example` pair
+- Add shared package globs with `--include-files` (or `includeFiles` in config)
+- Keep `ignore` small and explicit
+- Use `--strict` in CI to fail fast on warnings and missing variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-diff",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "type": "module",
   "description": "Detects environment variable issues, usage, and potential security risks.",
   "bin": {
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -68,19 +69,20 @@
   },
   "dependencies": {
     "chalk": "5.6.2",
-    "commander": "^14.0.2",
+    "commander": "^14.0.3",
     "prompts": "^2.4.2"
   },
   "devDependencies": {
-    "@release-it/conventional-changelog": "^10.0.4",
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
+    "@release-it/conventional-changelog": "^10.0.5",
+    "@types/node": "^25.3.0",
+    "@types/prompts": "^2.4.9",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "4.0.18",
-    "eslint": "^9.39.2",
-    "prettier": "^3.8.0",
+    "eslint": "^9.39.3",
+    "prettier": "^3.8.1",
     "release-it": "^19.2.4",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   }
 }

package/dist/src/ui/prompts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/ui/prompts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GACjE,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/src/ui/prompts.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/ui/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,EAAE,QAAQ,EAAE,SAAS,EAA6C;IAElE,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACxB,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,IAAI;QACV,OAAO;QACP,OAAO,EAAE;YACP,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE;YAC7B,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE;SAC9B;QACD,OAAO,EAAE,CAAC;KACX,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}