@prodverdict/engine 0.0.1

package/src/evaluators/access.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateAccess } from './access.js';
+import { createFixtureStripeReader, createFixtureDatabaseReader } from '../connectors/fixture.js';
+import type { StripeSubscription } from '../connectors/types.js';
+import type { AppUser } from '../connectors/types.js';
+import type { AccessContractConfig } from '../config/schema.js';
+
+const baseCfg: AccessContractConfig = {
+  type: 'access',
+  source_of_truth: 'stripe',
+  database: {
+    url_env: 'DATABASE_URL',
+    users_table: 'users',
+    columns: {
+      id: 'id',
+      stripe_customer_id: 'stripe_customer_id',
+      has_paid_access: 'has_paid_access',
+      plan: 'plan',
+    },
+  },
+  stripe: { secret_env: 'STRIPE_SECRET_KEY' },
+  plans: { price_pro: 'pro', price_starter: 'starter' },
+  severity: 'high',
+  fix: 'Sync has_paid_access from webhooks.',
+};
+
+function makeSub(overrides: Partial<StripeSubscription> = {}): StripeSubscription {
+  return {
+    id: 'sub_1',
+    customerId: 'cus_1',
+    status: 'active',
+    priceIds: ['price_pro'],
+    ...overrides,
+  };
+}
+
+function makeUser(overrides: Partial<AppUser> = {}): AppUser {
+  return {
+    id: 'u1',
+    stripeCustomerId: 'cus_1',
+    hasPaidAccess: true,
+    plan: 'pro',
+    ...overrides,
+  };
+}
+
+describe('evaluateAccess — pass cases', () => {
+  it('returns no findings when everything is aligned', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub()]),
+      database: createFixtureDatabaseReader([makeUser()]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings).toHaveLength(0);
+  });
+
+  it('returns no findings for canceled sub + no access', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'canceled' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: false, plan: null })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings).toHaveLength(0);
+  });
+
+  it('ignores users with no stripe_customer_id', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([]),
+      database: createFixtureDatabaseReader([makeUser({ stripeCustomerId: null, hasPaidAccess: false })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings).toHaveLength(0);
+  });
+});
+
+describe('evaluateAccess — revenue leak (active sub, no access)', () => {
+  it('produces a high finding when active sub + has_paid_access=false', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'active' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: false })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const high = findings.filter((f) => f.severity === 'high');
+    expect(high).toHaveLength(1);
+    expect(high[0]!.entity).toBe('user:u1');
+    expect(high[0]!.message).toMatch(/Revenue leak/);
+  });
+
+  it('triggers for trialing subscriptions too', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'trialing' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: false })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings.some((f) => f.severity === 'high')).toBe(true);
+  });
+});
+
+describe('evaluateAccess — wrongful access (lapsed sub, still has access)', () => {
+  it('produces a high finding for canceled sub + has_paid_access=true', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'canceled' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: true })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const high = findings.filter((f) => f.severity === 'high');
+    expect(high).toHaveLength(1);
+    expect(high[0]!.message).toMatch(/Wrongful access/);
+  });
+
+  it('triggers for unpaid subscriptions', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'unpaid' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: true })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings.some((f) => f.severity === 'high')).toBe(true);
+  });
+
+  it('triggers for past_due subscriptions', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ status: 'past_due' })]),
+      database: createFixtureDatabaseReader([makeUser({ hasPaidAccess: true })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings.some((f) => f.severity === 'high')).toBe(true);
+  });
+});
+
+describe('evaluateAccess — plan drift', () => {
+  it('flags unknown price ID (not in plans map)', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ priceIds: ['price_unknown'] })]),
+      database: createFixtureDatabaseReader([makeUser()]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const priceFinding = findings.find((f) => f.entity.startsWith('price:'));
+    expect(priceFinding).toBeDefined();
+    expect(priceFinding!.severity).toBe('high');
+    expect(priceFinding!.entity).toBe('price:price_unknown');
+  });
+
+  it('flags plan mismatch between app and Stripe price', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ priceIds: ['price_starter'] })]),
+      database: createFixtureDatabaseReader([makeUser({ plan: 'pro' })]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const planFinding = findings.find((f) => f.message.includes('plan is'));
+    expect(planFinding).toBeDefined();
+    expect(planFinding!.severity).toBe('high');
+  });
+});
+
+describe('evaluateAccess — duplicate customer', () => {
+  it('flags when two users share a stripe_customer_id', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub()]),
+      database: createFixtureDatabaseReader([
+        makeUser({ id: 'u1' }),
+        makeUser({ id: 'u2' }),
+      ]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const dup = findings.find((f) => f.entity.startsWith('customer:'));
+    expect(dup).toBeDefined();
+    expect(dup!.severity).toBe('medium');
+    expect(dup!.message).toMatch(/Duplicate/);
+  });
+});
+
+describe('evaluateAccess — orphan references', () => {
+  it('flags user with customer ID but no Stripe subscriptions found', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([]),
+      database: createFixtureDatabaseReader([makeUser()]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    expect(findings.some((f) => f.message.includes('no Stripe subscriptions'))).toBe(true);
+    expect(findings[0]!.severity).toBe('medium');
+  });
+
+  it('low-severity finding for Stripe customer with active sub but no app user', async () => {
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ customerId: 'cus_orphan' })]),
+      database: createFixtureDatabaseReader([]),
+    };
+    const findings = await evaluateAccess(baseCfg, sources);
+    const low = findings.find((f) => f.severity === 'low');
+    expect(low).toBeDefined();
+    expect(low!.entity).toBe('customer:cus_orphan');
+  });
+});
+
+describe('evaluateAccess — config without plans map', () => {
+  it('skips plan checks when plans map is absent', async () => {
+    const cfg: AccessContractConfig = { ...baseCfg, plans: undefined };
+    const sources = {
+      stripe: createFixtureStripeReader([makeSub({ priceIds: ['price_anything'] })]),
+      database: createFixtureDatabaseReader([makeUser()]),
+    };
+    const findings = await evaluateAccess(cfg, sources);
+    const planFindings = findings.filter((f) => f.entity.startsWith('price:'));
+    expect(planFindings).toHaveLength(0);
+  });
+});

package/src/evaluators/access.ts

@@ -0,0 +1,159 @@
+import type { Finding, Severity } from '../types.js';
+import type { AccessContractConfig } from '../config/schema.js';
+import type { StripeReader, DatabaseReader, AppUser, StripeSubscription } from '../connectors/types.js';
+
+const LAPSED_STATUSES = new Set(['canceled', 'unpaid', 'past_due', 'incomplete_expired']);
+const ACTIVE_STATUSES = new Set(['active', 'trialing']);
+
+export interface AccessDataSources {
+  stripe: StripeReader;
+  database: DatabaseReader;
+}
+
+export async function evaluateAccess(
+  cfg: AccessContractConfig,
+  sources: AccessDataSources,
+): Promise<Finding[]> {
+  const [subscriptions, users] = await Promise.all([
+    sources.stripe.listSubscriptions(),
+    sources.database.listUsers(),
+  ]);
+
+  const findings: Finding[] = [];
+  const defaultFix = cfg.fix;
+  const severity = cfg.severity;
+
+  const subsByCustomerId = groupByCustomerId(subscriptions);
+  const usersByCustomerId = new Map<string, AppUser[]>();
+
+  for (const user of users) {
+    if (!user.stripeCustomerId) continue;
+    const arr = usersByCustomerId.get(user.stripeCustomerId) ?? [];
+    arr.push(user);
+    usersByCustomerId.set(user.stripeCustomerId, arr);
+  }
+
+  // Check 1: duplicate stripe_customer_id across multiple app users
+  for (const [customerId, mapped] of usersByCustomerId) {
+    if (mapped.length > 1) {
+      const ids = mapped.map((u) => u.id).join(', ');
+      findings.push({
+        contract: 'access',
+        severity: 'medium',
+        entity: `customer:${customerId}`,
+        message: `stripe_customer_id "${customerId}" is linked to ${mapped.length} users (${ids}). Duplicate mapping.`,
+        fix: 'Ensure each Stripe customer maps to exactly one app user.',
+      });
+    }
+  }
+
+  // Check 2: per-user access state vs Stripe state
+  for (const user of users) {
+    if (!user.stripeCustomerId) {
+      // No Stripe link at all — skip access checks (not necessarily an error)
+      continue;
+    }
+
+    const subs = subsByCustomerId.get(user.stripeCustomerId);
+
+    if (!subs || subs.length === 0) {
+      // App has a customer ID but Stripe has no record
+      findings.push({
+        contract: 'access',
+        severity: 'medium',
+        entity: `user:${user.id}`,
+        message: `User has stripe_customer_id "${user.stripeCustomerId}" but no Stripe subscriptions were found.`,
+        fix: 'Verify the stripe_customer_id is correct or remove the stale reference.',
+      });
+      continue;
+    }
+
+    // Use the most relevant subscription (active/trialing preferred; otherwise latest)
+    const activeSub = subs.find((s) => ACTIVE_STATUSES.has(s.status));
+    const lapsedSub = subs.find((s) => LAPSED_STATUSES.has(s.status));
+    const anySub = activeSub ?? lapsedSub ?? subs[0]!;
+
+    if (activeSub) {
+      // Should have access
+      if (!user.hasPaidAccess) {
+        findings.push({
+          contract: 'access',
+          severity,
+          entity: `user:${user.id}`,
+          message:
+            `User has an active/trialing Stripe subscription (${activeSub.id}, status: ${activeSub.status}) ` +
+            `but has_paid_access is false. Revenue leak — user cannot access paid features.`,
+          fix: defaultFix ?? 'Set has_paid_access=true and assign the correct plan on subscription activation.',
+        });
+      }
+
+      // Check plan mapping drift
+      if (cfg.plans) {
+        for (const priceId of activeSub.priceIds) {
+          const expectedPlan = cfg.plans[priceId];
+          if (expectedPlan === undefined) {
+            findings.push({
+              contract: 'access',
+              severity,
+              entity: `price:${priceId}`,
+              message: `Subscription ${activeSub.id} uses price "${priceId}" which is not in the plans map.`,
+              fix: `Add "${priceId}" to the plans map in prodverdict.yml, or remove it from Stripe if deprecated.`,
+            });
+          } else if (user.plan !== null && user.plan !== expectedPlan) {
+            findings.push({
+              contract: 'access',
+              severity,
+              entity: `user:${user.id}`,
+              message:
+                `User plan is "${user.plan}" but active Stripe price "${priceId}" maps to plan "${expectedPlan}".`,
+              fix: defaultFix ?? `Update the user's plan to "${expectedPlan}" to match the Stripe price.`,
+            });
+          }
+        }
+      }
+    } else if (lapsedSub) {
+      // Should not have access
+      if (user.hasPaidAccess) {
+        findings.push({
+          contract: 'access',
+          severity,
+          entity: `user:${user.id}`,
+          message:
+            `User has a ${anySub.status} Stripe subscription (${anySub.id}) ` +
+            `but has_paid_access is still true. Wrongful access — user is accessing paid features without a valid subscription.`,
+          fix: defaultFix ?? 'Set has_paid_access=false and revoke plan access in the cancellation/webhook handler.',
+        });
+      }
+    }
+  }
+
+  // Check 3: Stripe customers with subscriptions but no matching app user
+  for (const [customerId, subs] of subsByCustomerId) {
+    if (!usersByCustomerId.has(customerId)) {
+      const activeSub = subs.find((s) => ACTIVE_STATUSES.has(s.status));
+      if (activeSub) {
+        findings.push({
+          contract: 'access',
+          severity: 'low',
+          entity: `customer:${customerId}`,
+          message: `Stripe customer "${customerId}" has an active subscription (${activeSub.id}) but no matching app user row.`,
+          fix: 'Verify the customer was not deleted from the app, or handle the Stripe subscription cleanup.',
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function groupByCustomerId(
+  subscriptions: StripeSubscription[],
+): Map<string, StripeSubscription[]> {
+  const map = new Map<string, StripeSubscription[]>();
+  for (const sub of subscriptions) {
+    const arr = map.get(sub.customerId) ?? [];
+    arr.push(sub);
+    map.set(sub.customerId, arr);
+  }
+  return map;
+}

package/src/evaluators/config.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { evaluateConfig, scanEnvReferences, parseEnvFile } from './config.js';
+import type { ConfigContractConfig } from '../config/schema.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function makeConfig(overrides: Partial<ConfigContractConfig> = {}): ConfigContractConfig {
+  return {
+    type: 'config',
+    severity: 'high',
+    rules: [],
+    scan_references: false,
+    env_example_file: '.env.example',
+    check_placeholders: true,
+    ignore_vars: [],
+    ...overrides,
+  };
+}
+
+describe('evaluateConfig', () => {
+  describe('required rule', () => {
+    it('passes when required var is set', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'required', name: 'STRIPE_SECRET_KEY' }] }),
+        { repoRoot: process.cwd(), env: { STRIPE_SECRET_KEY: 'sk_live_abc' } },
+      );
+      expect(findings).toHaveLength(0);
+    });
+
+    it('fails when required var is missing', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'required', name: 'STRIPE_SECRET_KEY' }] }),
+        { repoRoot: process.cwd(), env: {} },
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.severity).toBe('high');
+      expect(findings[0]!.entity).toBe('env:STRIPE_SECRET_KEY');
+    });
+
+    it('fails when required var is empty string', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'required', name: 'DATABASE_URL' }] }),
+        { repoRoot: process.cwd(), env: { DATABASE_URL: '' } },
+      );
+      expect(findings).toHaveLength(1);
+    });
+
+    it('uses per-rule severity override', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({
+          rules: [{ type: 'required', name: 'OPTIONAL_THING', severity: 'low' }],
+        }),
+        { repoRoot: process.cwd(), env: {} },
+      );
+      expect(findings[0]!.severity).toBe('low');
+    });
+
+    it('warns about placeholder values', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'required', name: 'API_KEY' }], check_placeholders: true }),
+        { repoRoot: process.cwd(), env: { API_KEY: 'your_key_here' } },
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.severity).toBe('medium');
+    });
+
+    it('does not warn about placeholders when check_placeholders is false', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'required', name: 'API_KEY' }], check_placeholders: false }),
+        { repoRoot: process.cwd(), env: { API_KEY: 'your_key_here' } },
+      );
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('not_default rule', () => {
+    it('passes when value is not in forbidden list', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'not_default', name: 'DEBUG', forbidden_values: ['true', '1'] }] }),
+        { repoRoot: process.cwd(), env: { DEBUG: 'false' } },
+      );
+      expect(findings).toHaveLength(0);
+    });
+
+    it('fails when value matches a forbidden value', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'not_default', name: 'DEBUG', forbidden_values: ['true', '1'] }] }),
+        { repoRoot: process.cwd(), env: { DEBUG: 'true' } },
+      );
+      expect(findings).toHaveLength(1);
+      expect(findings[0]!.entity).toBe('env:DEBUG');
+    });
+
+    it('is case-insensitive', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'not_default', name: 'LOG_LEVEL', forbidden_values: ['debug'] }] }),
+        { repoRoot: process.cwd(), env: { LOG_LEVEL: 'DEBUG' } },
+      );
+      expect(findings).toHaveLength(1);
+    });
+
+    it('skips check when var is unset', async () => {
+      const findings = await evaluateConfig(
+        makeConfig({ rules: [{ type: 'not_default', name: 'DEBUG', forbidden_values: ['true'] }] }),
+        { repoRoot: process.cwd(), env: {} },
+      );
+      expect(findings).toHaveLength(0);
+    });
+  });
+
+  describe('scan_references', () => {
+    let tmpDir: string;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pv-config-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('finds env vars referenced in source but not in .env.example', async () => {
+      fs.writeFileSync(path.join(tmpDir, 'index.ts'), 'const key = process.env.MISSING_VAR;');
+      fs.writeFileSync(path.join(tmpDir, '.env.example'), '# no vars\n');
+
+      const findings = await evaluateConfig(
+        makeConfig({ scan_references: true }),
+        { repoRoot: tmpDir, env: {} },
+      );
+
+      const envFinding = findings.find((f) => f.entity === 'env:MISSING_VAR');
+      expect(envFinding).toBeDefined();
+      expect(envFinding!.severity).toBe('low');
+    });
+
+    it('does not flag vars declared in .env.example', async () => {
+      fs.writeFileSync(path.join(tmpDir, 'index.ts'), 'const key = process.env.DECLARED_VAR;');
+      fs.writeFileSync(path.join(tmpDir, '.env.example'), 'DECLARED_VAR=example_value\n');
+
+      const findings = await evaluateConfig(
+        makeConfig({ scan_references: true }),
+        { repoRoot: tmpDir, env: {} },
+      );
+
+      expect(findings.filter((f) => f.entity === 'env:DECLARED_VAR')).toHaveLength(0);
+    });
+
+    it('does not flag always-available vars like NODE_ENV', async () => {
+      fs.writeFileSync(path.join(tmpDir, 'index.ts'), 'if (process.env.NODE_ENV === "production") {}');
+      fs.writeFileSync(path.join(tmpDir, '.env.example'), '');
+
+      const findings = await evaluateConfig(
+        makeConfig({ scan_references: true }),
+        { repoRoot: tmpDir, env: {} },
+      );
+
+      expect(findings.filter((f) => f.entity === 'env:NODE_ENV')).toHaveLength(0);
+    });
+
+    it('respects ignore_vars', async () => {
+      fs.writeFileSync(path.join(tmpDir, 'index.ts'), 'const x = process.env.INTERNAL_VAR;');
+      fs.writeFileSync(path.join(tmpDir, '.env.example'), '');
+
+      const findings = await evaluateConfig(
+        makeConfig({ scan_references: true, ignore_vars: ['INTERNAL_VAR'] }),
+        { repoRoot: tmpDir, env: {} },
+      );
+
+      expect(findings.filter((f) => f.entity === 'env:INTERNAL_VAR')).toHaveLength(0);
+    });
+  });
+});
+
+describe('scanEnvReferences', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pv-scan-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('finds process.env.X references', () => {
+    fs.writeFileSync(path.join(tmpDir, 'app.ts'), 'const key = process.env.STRIPE_KEY;');
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('STRIPE_KEY')).toBe(true);
+  });
+
+  it('finds import.meta.env.X references', () => {
+    fs.writeFileSync(path.join(tmpDir, 'app.ts'), 'const base = import.meta.env.VITE_API_URL;');
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('VITE_API_URL')).toBe(true);
+  });
+
+  it('finds process.env["X"] references', () => {
+    fs.writeFileSync(path.join(tmpDir, 'app.ts'), "const x = process.env['DATABASE_URL'];");
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('DATABASE_URL')).toBe(true);
+  });
+
+  it('skips node_modules', () => {
+    const nmDir = path.join(tmpDir, 'node_modules', 'pkg');
+    fs.mkdirSync(nmDir, { recursive: true });
+    fs.writeFileSync(path.join(nmDir, 'index.js'), 'process.env.SHOULD_SKIP;');
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('SHOULD_SKIP')).toBe(false);
+  });
+
+  it('skips dist/', () => {
+    const distDir = path.join(tmpDir, 'dist');
+    fs.mkdirSync(distDir, { recursive: true });
+    fs.writeFileSync(path.join(distDir, 'index.js'), 'process.env.DIST_VAR;');
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('DIST_VAR')).toBe(false);
+  });
+
+  it('skips test/spec source files', () => {
+    fs.writeFileSync(path.join(tmpDir, 'app.ts'), 'const key = process.env.PROD_VAR;');
+    fs.writeFileSync(path.join(tmpDir, 'app.test.ts'), 'const x = process.env.TEST_FIXTURE_VAR;');
+    fs.writeFileSync(path.join(tmpDir, 'app.spec.tsx'), 'const y = process.env.SPEC_VAR;');
+    const refs = scanEnvReferences(tmpDir);
+    expect(refs.has('PROD_VAR')).toBe(true);
+    expect(refs.has('TEST_FIXTURE_VAR')).toBe(false);
+    expect(refs.has('SPEC_VAR')).toBe(false);
+  });
+});
+
+describe('parseEnvFile', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pv-parse-env-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('parses KEY=VALUE pairs', () => {
+    const file = path.join(tmpDir, '.env');
+    fs.writeFileSync(file, 'FOO=bar\nBAZ=qux\n');
+    const result = parseEnvFile(file);
+    expect(result.get('FOO')).toBe('bar');
+    expect(result.get('BAZ')).toBe('qux');
+  });
+
+  it('strips quotes', () => {
+    const file = path.join(tmpDir, '.env');
+    fs.writeFileSync(file, 'SECRET="my_secret"\n');
+    expect(parseEnvFile(file).get('SECRET')).toBe('my_secret');
+  });
+
+  it('skips comment lines', () => {
+    const file = path.join(tmpDir, '.env');
+    fs.writeFileSync(file, '# comment\nKEY=val\n');
+    const result = parseEnvFile(file);
+    expect(result.size).toBe(1);
+  });
+
+  it('returns empty map for missing file', () => {
+    expect(parseEnvFile('/nonexistent/.env').size).toBe(0);
+  });
+});