fix: flagging config loader variables as unused (#482)

Author: Chrilleweb

.changeset/config-loader-unused.md

@@ -0,0 +1,5 @@
+---
+'dotenv-diff': patch
+---
+
+Stop flagging config loader variables as unused.

packages/cli/src/config/types.ts

@@ -267,6 +267,12 @@ export interface ScanResult {
   used: EnvUsage[];
   missing: string[];
   unused: string[];
+  /**
+   * Keys declared by a central config loader (e.g. a Zod/envalid schema over the
+   * whole `process.env`). Used only to suppress false "unused" findings — they do
+   * not count as usages for missing detection, stats, or the health score.
+   */
+  declaredKeys?: string[];
   stats: ScanStats;
   secrets: SecretFinding[];
   duplicates: {

packages/cli/src/core/scan/compareScan.ts

@@ -53,7 +53,13 @@ export function compareWithEnvFiles(
     return files.some((file) => !isCovered(variable, file));
   });
   const missing = filterIgnoredKeys(missingUnfiltered, ignore, ignoreRegex);
-  const unused = [...envKeys].filter((v) => !usedVariables.has(v));
+
+  // Keys declared by a central config loader (e.g. a Zod schema over the whole
+  // process.env) are read indirectly, so they must not be reported as unused.
+  const declaredKeys = new Set(scanResult.declaredKeys ?? []);
+  const unused = [...envKeys].filter(
+    (v) => !usedVariables.has(v) && !declaredKeys.has(v),
+  );
 
   // Cross-reference missing (used but undefined) keys against the defined keys
   // to surface likely typos, e.g. code uses DATABASE_URL but .env has DATABAS_URL.

packages/cli/src/core/scan/detectConfigSchemaKeys.ts

@@ -0,0 +1,48 @@
+/**
+ * Signals that a file consumes the entire `process.env` object rather than a
+ * single `process.env.X` key — the hallmark of a central config loader
+ * (Zod/envalid schemas, direct assignment, spread). When one of these is present
+ * we treat the file's UPPER_SNAKE_CASE object keys as env declarations.
+ */
+const WHOLESALE_ENV_SIGNALS: RegExp[] = [
+  /\.(?:safeParse|parse)\s*\(\s*process\.env\b/, // zod: schema.parse(process.env)
+  /\bcleanEnv\s*\(\s*process\.env\b/, // envalid: cleanEnv(process.env, {...})
+  /=\s*process\.env(?!\s*[.[])/, // const env = process.env
+  /\{\s*\.\.\.process\.env\b/, // { ...process.env }
+];
+
+/**
+ * Matches UPPER_SNAKE_CASE object-literal keys, e.g. `CLIENT_SECRET_GITHUB:` or
+ * `"CLIENT_SECRET_GITHUB":`, in a key position (start of line, or after `{`, `,`,
+ * `(`, or whitespace).
+ */
+const OBJECT_KEY_PATTERN = /(?:^|[\s{,(])["']?([A-Z_][A-Z0-9_]*)["']?\s*:/gm;
+
+/**
+ * Extracts env-variable keys that a central config loader declares as object
+ * keys while consuming the whole `process.env` object.
+ *
+ * This surfaces variables that are read indirectly — e.g. a Zod schema
+ * `z.object({ CLIENT_SECRET_GITHUB: ... }).parse(process.env)` whose values are
+ * later accessed as `appCfg.CLIENT_SECRET_GITHUB` — which the literal
+ * `process.env.X` scanner never sees. The returned keys are used only to
+ * suppress false "unused" findings; they do not count as usages for missing
+ * detection, stats, or the health score.
+ *
+ * @param content - The full source of a file.
+ * @returns UPPER_SNAKE_CASE keys declared in the file, or an empty array when the
+ *   file does not consume the whole `process.env` object.
+ */
+export function detectConfigSchemaKeys(content: string): string[] {
+  const consumesWholeEnv = WHOLESALE_ENV_SIGNALS.some((rx) => rx.test(content));
+  if (!consumesWholeEnv) return [];
+
+  const keys = new Set<string>();
+  OBJECT_KEY_PATTERN.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = OBJECT_KEY_PATTERN.exec(content)) !== null) {
+    keys.add(match[1]!);
+  }
+
+  return [...keys];
+}

packages/cli/src/services/scanCodebase.ts

@@ -8,6 +8,7 @@ import {
 } from '../core/security/secretDetectors.js';
 import { DEFAULT_EXCLUDE_PATTERNS } from '../core/scan/patterns.js';
 import { scanFile } from '../core/scan/scanFile.js';
+import { detectConfigSchemaKeys } from '../core/scan/detectConfigSchemaKeys.js';
 import { createConcurrencyLimit } from '../core/helpers/concurrencyLimit.js';
 import { findFiles } from './fileWalker.js';
 import { normalizePath } from '../core/helpers/normalizePath.js';
@@ -36,8 +37,9 @@ export async function scanCodebase(opts: ScanOptions): Promise<ScanResult> {
     const relativePath = normalizePath(path.relative(opts.cwd, filePath));
     const fileUsages = scanFile(filePath, content, opts);
     const secrets = safeDetectSecrets(relativePath, content, opts);
+    const declaredKeys = detectConfigSchemaKeys(content);
 
-    return { fileUsages, relativePath, content, secrets };
+    return { fileUsages, relativePath, content, secrets, declaredKeys };
   };
 
   const results = await Promise.all(
@@ -46,15 +48,17 @@ export async function scanCodebase(opts: ScanOptions): Promise<ScanResult> {
 
   const allUsages: EnvUsage[] = [];
   const allSecrets: SecretFinding[] = [];
+  const allDeclaredKeys = new Set<string>();
   const fileContentMap = new Map<string, string>();
   let filesScanned = 0;
 
   for (const result of results) {
     if (!result) continue;
-    const { fileUsages, relativePath, content, secrets } = result;
+    const { fileUsages, relativePath, content, secrets, declaredKeys } = result;
     allUsages.push(...fileUsages);
     fileContentMap.set(relativePath, content);
     if (secrets.length) allSecrets.push(...secrets);
+    for (const key of declaredKeys) allDeclaredKeys.add(key);
     filesScanned++;
   }
 
@@ -72,6 +76,7 @@ export async function scanCodebase(opts: ScanOptions): Promise<ScanResult> {
     used: filteredUsages,
     missing: [],
     unused: [],
+    declaredKeys: [...allDeclaredKeys],
     secrets: allSecrets,
     stats: {
       filesScanned,

packages/cli/test/unit/core/scan/compareScan.test.ts

@@ -65,6 +65,25 @@ describe('compareWithEnvFiles', () => {
     expect(result.unused).toEqual(['B']);
   });
 
+  it('does not report a config-schema declared key as unused', () => {
+    const result = compareWithEnvFiles(
+      makeScanResult({ declaredKeys: ['CLIENT_SECRET_GITHUB'] }),
+      { CLIENT_SECRET_GITHUB: 'x', REALLY_UNUSED: 'y' },
+    );
+
+    // Declared via a loader schema → not unused; the truly unreferenced key stays.
+    expect(result.unused).toEqual(['REALLY_UNUSED']);
+  });
+
+  it('ignores declared keys that are not present in the env file', () => {
+    const result = compareWithEnvFiles(
+      makeScanResult({ declaredKeys: ['NOT_IN_ENV'] }),
+      { REALLY_UNUSED: 'y' },
+    );
+
+    expect(result.unused).toEqual(['REALLY_UNUSED']);
+  });
+
   it('preserves other ScanResult fields', () => {
     const scanResult = makeScanResult({
       stats: {

packages/cli/test/unit/core/scan/detectConfigSchemaKeys.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { detectConfigSchemaKeys } from '../../../../src/core/scan/detectConfigSchemaKeys.js';
+
+describe('detectConfigSchemaKeys', () => {
+  it('extracts schema keys from a Zod .parse(process.env) loader', () => {
+    const content = `const envVars = z.object({
+      CLIENT_ID_GITHUB: z.string(),
+      CLIENT_SECRET_GITHUB: z.string().optional(),
+    }).parse(process.env);`;
+
+    expect(detectConfigSchemaKeys(content).sort()).toEqual([
+      'CLIENT_ID_GITHUB',
+      'CLIENT_SECRET_GITHUB',
+    ]);
+  });
+
+  it('supports .safeParse(process.env)', () => {
+    const content =
+      'schema.safeParse(process.env);\nconst obj = { DATABASE_URL: 1 };';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['DATABASE_URL']);
+  });
+
+  it('supports envalid cleanEnv(process.env, {...})', () => {
+    const content =
+      'const env = cleanEnv(process.env, { PORT: port(), API_KEY: str() });';
+
+    expect(detectConfigSchemaKeys(content).sort()).toEqual(['API_KEY', 'PORT']);
+  });
+
+  it('supports direct whole-object assignment (= process.env)', () => {
+    const content =
+      'const env = process.env;\nconst cfg = { SECRET_TOKEN: env.SECRET_TOKEN };';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['SECRET_TOKEN']);
+  });
+
+  it('supports spread of the whole env object ({ ...process.env })', () => {
+    const content = 'const cfg = { ...process.env, EXTRA_FLAG: true };';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['EXTRA_FLAG']);
+  });
+
+  it('recognises quoted keys', () => {
+    const content =
+      'z.object({ "CLIENT_SECRET_GITHUB": z.string() }).parse(process.env);';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['CLIENT_SECRET_GITHUB']);
+  });
+
+  it('deduplicates repeated keys', () => {
+    const content =
+      'schema.parse(process.env);\nconst a = { API_KEY: 1 };\nconst b = { API_KEY: 2 };';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['API_KEY']);
+  });
+
+  it('ignores non-UPPER_SNAKE keys', () => {
+    const content =
+      'z.object({ clientId: z.string(), someKey: z.string() }).parse(process.env);';
+
+    expect(detectConfigSchemaKeys(content)).toEqual([]);
+  });
+
+  it('returns [] when the file only reads a single process.env.X key', () => {
+    const content =
+      'const key = process.env.API_KEY;\nconst obj = { OTHER_KEY: 1 };';
+
+    // `process.env.API_KEY` must NOT count as whole-object consumption.
+    expect(detectConfigSchemaKeys(content)).toEqual([]);
+  });
+
+  it('returns [] when the file does not touch process.env at all', () => {
+    const content = 'const config = { DATABASE_URL: 1, API_KEY: 2 };';
+
+    expect(detectConfigSchemaKeys(content)).toEqual([]);
+  });
+
+  it('returns [] for a whole-env loader with no UPPER_SNAKE object keys', () => {
+    const content = 'const env = process.env;\nexport default env;';
+
+    expect(detectConfigSchemaKeys(content)).toEqual([]);
+  });
+
+  it('detects the loader across newlines between .parse( and process.env', () => {
+    const content =
+      'const cfg = z\n  .object({ API_KEY: z.string() })\n  .parse(\n    process.env,\n  );';
+
+    expect(detectConfigSchemaKeys(content)).toEqual(['API_KEY']);
+  });
+
+  it('extracts only object keys, not the accessor key, in a mixed file', () => {
+    // The file both reads a single process.env.NODE_ENV and defines a schema.
+    const content =
+      'const runtime = process.env.NODE_ENV;\nconst cfg = schema.parse(process.env);\nconst obj = { DB_HOST: 1 };';
+
+    // NODE_ENV is an accessor (no `KEY:`), so only the object key DB_HOST is declared.
+    expect(detectConfigSchemaKeys(content)).toEqual(['DB_HOST']);
+  });
+
+  it('handles keys containing digits (e.g. OAUTH2_TOKEN, S3_BUCKET)', () => {
+    const content =
+      'cleanEnv(process.env, { OAUTH2_TOKEN: str(), S3_BUCKET: str() });';
+
+    expect(detectConfigSchemaKeys(content).sort()).toEqual([
+      'OAUTH2_TOKEN',
+      'S3_BUCKET',
+    ]);
+  });
+});

packages/cli/test/unit/services/scanCodebase.test.ts

@@ -90,6 +90,24 @@ describe('scanCodebase', () => {
       expect(result.stats.uniqueVariables).toBe(0);
     });
 
+    it('collects config-schema declared keys from a whole-process.env loader', async () => {
+      const testFile = path.join(tmpDir, 'env.ts');
+      fsSync.writeFileSync(
+        testFile,
+        'const cfg = z.object({ CLIENT_ID_GITHUB: z.string(), CLIENT_SECRET_GITHUB: z.string() }).parse(process.env);',
+      );
+
+      vi.mocked(findFiles).mockResolvedValue([testFile]);
+      vi.mocked(scanFile).mockReturnValue([]);
+
+      const result = await scanCodebase(defaultOpts);
+
+      expect(result.declaredKeys?.sort()).toEqual([
+        'CLIENT_ID_GITHUB',
+        'CLIENT_SECRET_GITHUB',
+      ]);
+    });
+
     it('handles files with no usages', async () => {
       const testFile = path.join(tmpDir, 'app.js');
       fsSync.writeFileSync(testFile, 'const x = 42;');