@scuton/dotenv-guard 1.0.0

package/tests/generator.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, readFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { generateExample, ensureGitignore } from '../src/core/generator.js';
+
+const TEST_DIR = join(process.cwd(), '.test-gen-tmp');
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe('generateExample', () => {
+  it('should create .env.example from .env', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const outPath = join(TEST_DIR, '.env.example');
+    writeFileSync(envPath, 'DB_HOST=localhost\nDB_PORT=5432\nDEBUG=true');
+
+    generateExample(envPath, outPath);
+    const content = readFileSync(outPath, 'utf-8');
+
+    expect(content).toContain('DB_HOST=');
+    expect(content).toContain('DB_PORT=');
+    expect(content).toContain('DEBUG=');
+    expect(content).not.toContain('localhost');
+  });
+
+  it('should mask URL values with placeholder', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const outPath = join(TEST_DIR, '.env.example');
+    writeFileSync(envPath, 'API_URL=https://api.example.com/v1');
+
+    generateExample(envPath, outPath);
+    const content = readFileSync(outPath, 'utf-8');
+
+    expect(content).toContain('https://...');
+    expect(content).toContain('type:url');
+    expect(content).not.toContain('api.example.com');
+  });
+
+  it('should add type:boolean hint for boolean values', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const outPath = join(TEST_DIR, '.env.example');
+    writeFileSync(envPath, 'DEBUG=true');
+
+    generateExample(envPath, outPath);
+    const content = readFileSync(outPath, 'utf-8');
+
+    expect(content).toContain('type:boolean');
+  });
+
+  it('should add type:number hint for numeric values', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const outPath = join(TEST_DIR, '.env.example');
+    writeFileSync(envPath, 'MAX_RETRIES=5');
+
+    generateExample(envPath, outPath);
+    const content = readFileSync(outPath, 'utf-8');
+
+    expect(content).toContain('type:number');
+  });
+
+  it('should throw when .env does not exist', () => {
+    expect(() => generateExample(join(TEST_DIR, '.env.missing'), join(TEST_DIR, '.env.example')))
+      .toThrow('not found');
+  });
+
+  it('should include header comments', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const outPath = join(TEST_DIR, '.env.example');
+    writeFileSync(envPath, 'KEY=value');
+
+    const output = generateExample(envPath, outPath);
+    expect(output).toContain('# Environment Variables');
+    expect(output).toContain('# Copy this file');
+  });
+});
+
+describe('ensureGitignore', () => {
+  it('should add .env entries to .gitignore', () => {
+    writeFileSync(join(TEST_DIR, '.gitignore'), 'node_modules/\n');
+    const updated = ensureGitignore(TEST_DIR);
+
+    expect(updated).toBe(true);
+    const content = readFileSync(join(TEST_DIR, '.gitignore'), 'utf-8');
+    expect(content).toContain('.env');
+    expect(content).toContain('.env.local');
+  });
+
+  it('should not duplicate entries', () => {
+    writeFileSync(join(TEST_DIR, '.gitignore'), '.env\n.env.local\n.env.*.local\n');
+    const updated = ensureGitignore(TEST_DIR);
+    expect(updated).toBe(false);
+  });
+
+  it('should create .gitignore if it does not exist', () => {
+    const updated = ensureGitignore(TEST_DIR);
+    expect(updated).toBe(true);
+    expect(existsSync(join(TEST_DIR, '.gitignore'))).toBe(true);
+  });
+});

package/tests/leak.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { checkLeaks } from '../src/core/leak.js';
+
+const TEST_DIR = join(process.cwd(), '.test-leak-tmp');
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe('checkLeaks', () => {
+  it('should detect .gitignore missing .env', () => {
+    writeFileSync(join(TEST_DIR, '.gitignore'), 'node_modules/\ndist/\n');
+    const result = checkLeaks(TEST_DIR);
+    expect(result.gitignoreHasEnv).toBe(false);
+  });
+
+  it('should detect .gitignore including .env', () => {
+    writeFileSync(join(TEST_DIR, '.gitignore'), 'node_modules/\n.env\ndist/\n');
+    const result = checkLeaks(TEST_DIR);
+    expect(result.gitignoreHasEnv).toBe(true);
+  });
+
+  it('should detect .gitignore with .env* wildcard', () => {
+    writeFileSync(join(TEST_DIR, '.gitignore'), '.env*\n');
+    const result = checkLeaks(TEST_DIR);
+    expect(result.gitignoreHasEnv).toBe(true);
+  });
+
+  it('should report no pre-commit hook when .git/hooks missing', () => {
+    const result = checkLeaks(TEST_DIR);
+    expect(result.preCommitHookInstalled).toBe(false);
+  });
+
+  it('should detect pre-commit hook with dotenv-guard', () => {
+    const hooksDir = join(TEST_DIR, '.git', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(join(hooksDir, 'pre-commit'), '#!/bin/sh\n# dotenv-guard hook\nexit 0');
+    const result = checkLeaks(TEST_DIR);
+    expect(result.preCommitHookInstalled).toBe(true);
+  });
+
+  it('should handle non-git directory gracefully', () => {
+    const result = checkLeaks(TEST_DIR);
+    expect(result.leaks).toEqual([]);
+  });
+});

package/tests/parser.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { parseEnvFile, parseEnvFileToMap } from '../src/core/parser.js';
+
+describe('parseEnvFile', () => {
+  it('should parse simple KEY=VALUE pairs', () => {
+    const content = 'DB_HOST=localhost\nDB_PORT=5432';
+    const entries = parseEnvFile(content);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toMatchObject({ key: 'DB_HOST', value: 'localhost', line: 1 });
+    expect(entries[1]).toMatchObject({ key: 'DB_PORT', value: '5432', line: 2 });
+  });
+
+  it('should handle double-quoted values', () => {
+    const content = 'NAME="hello world"';
+    const entries = parseEnvFile(content);
+    expect(entries[0].value).toBe('hello world');
+  });
+
+  it('should handle single-quoted values', () => {
+    const content = "NAME='hello world'";
+    const entries = parseEnvFile(content);
+    expect(entries[0].value).toBe('hello world');
+  });
+
+  it('should skip empty lines and comments', () => {
+    const content = '# This is a comment\n\nKEY=value\n\n# Another comment';
+    const entries = parseEnvFile(content);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].key).toBe('KEY');
+  });
+
+  it('should handle inline comments on unquoted values', () => {
+    const content = 'PORT=3000 # server port';
+    const entries = parseEnvFile(content);
+    expect(entries[0].value).toBe('3000');
+    expect(entries[0].comment).toBe('server port');
+  });
+
+  it('should handle values with equals signs', () => {
+    const content = 'DATABASE_URL=postgresql://user:pass@host:5432/db?schema=public';
+    const entries = parseEnvFile(content);
+    expect(entries[0].value).toBe('postgresql://user:pass@host:5432/db?schema=public');
+  });
+
+  it('should handle empty values', () => {
+    const content = 'EMPTY=';
+    const entries = parseEnvFile(content);
+    expect(entries[0].value).toBe('');
+  });
+
+  it('should handle values with spaces around equals', () => {
+    const content = 'KEY = value';
+    const entries = parseEnvFile(content);
+    expect(entries[0]).toMatchObject({ key: 'KEY', value: 'value' });
+  });
+
+  it('should track correct line numbers', () => {
+    const content = '# comment\n\nFIRST=1\n\nSECOND=2';
+    const entries = parseEnvFile(content);
+    expect(entries[0].line).toBe(3);
+    expect(entries[1].line).toBe(5);
+  });
+
+  it('should skip invalid lines gracefully', () => {
+    const content = 'VALID=yes\n123INVALID=no\n-ALSO_INVALID=no\nALSO_VALID=yes';
+    const entries = parseEnvFile(content);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].key).toBe('VALID');
+    expect(entries[1].key).toBe('ALSO_VALID');
+  });
+});
+
+describe('parseEnvFileToMap', () => {
+  it('should return a Map of key-value pairs', () => {
+    const content = 'A=1\nB=2\nC=3';
+    const map = parseEnvFileToMap(content);
+    expect(map.size).toBe(3);
+    expect(map.get('A')).toBe('1');
+    expect(map.get('B')).toBe('2');
+    expect(map.get('C')).toBe('3');
+  });
+});

package/tests/sync.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { syncCheck } from '../src/core/sync.js';
+
+const TEST_DIR = join(process.cwd(), '.test-sync-tmp');
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe('syncCheck', () => {
+  it('should detect missing variables', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const examplePath = join(TEST_DIR, '.env.example');
+    writeFileSync(examplePath, 'A=1\nB=2\nC=3');
+    writeFileSync(envPath, 'A=1');
+
+    const result = syncCheck(envPath, examplePath);
+    expect(result.missing).toEqual(['B', 'C']);
+    expect(result.synced).toEqual(['A']);
+  });
+
+  it('should detect extra variables', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const examplePath = join(TEST_DIR, '.env.example');
+    writeFileSync(examplePath, 'A=1');
+    writeFileSync(envPath, 'A=1\nEXTRA=yes');
+
+    const result = syncCheck(envPath, examplePath);
+    expect(result.extra).toEqual(['EXTRA']);
+  });
+
+  it('should report full sync when all vars match', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const examplePath = join(TEST_DIR, '.env.example');
+    writeFileSync(examplePath, 'A=1\nB=2');
+    writeFileSync(envPath, 'A=hello\nB=world');
+
+    const result = syncCheck(envPath, examplePath);
+    expect(result.missing).toEqual([]);
+    expect(result.extra).toEqual([]);
+    expect(result.synced).toEqual(['A', 'B']);
+  });
+
+  it('should throw error when .env.example is missing', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const examplePath = join(TEST_DIR, '.env.example.nonexistent');
+    writeFileSync(envPath, 'A=1');
+
+    expect(() => syncCheck(envPath, examplePath)).toThrow('not found');
+  });
+
+  it('should treat all keys as missing when .env does not exist', () => {
+    const envPath = join(TEST_DIR, '.env.nonexistent');
+    const examplePath = join(TEST_DIR, '.env.example');
+    writeFileSync(examplePath, 'A=1\nB=2\nC=3');
+
+    const result = syncCheck(envPath, examplePath);
+    expect(result.missing).toEqual(['A', 'B', 'C']);
+    expect(result.synced).toEqual([]);
+  });
+
+  it('should handle empty .env.example', () => {
+    const envPath = join(TEST_DIR, '.env');
+    const examplePath = join(TEST_DIR, '.env.example');
+    writeFileSync(examplePath, '# just comments\n');
+    writeFileSync(envPath, 'A=1');
+
+    const result = syncCheck(envPath, examplePath);
+    expect(result.missing).toEqual([]);
+    expect(result.extra).toEqual(['A']);
+  });
+});

package/tests/validator.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { validate, inferRules, ValidationRule } from '../src/core/validator.js';
+
+describe('validate', () => {
+  it('should pass valid string values', () => {
+    const errors = validate(
+      { NAME: 'hello' },
+      [{ key: 'NAME', type: 'string', required: true }]
+    );
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should fail when required variable is missing', () => {
+    const errors = validate(
+      {},
+      [{ key: 'API_KEY', required: true }]
+    );
+    expect(errors).toHaveLength(1);
+    expect(errors[0].message).toContain('required');
+  });
+
+  it('should pass when optional variable is missing', () => {
+    const errors = validate(
+      {},
+      [{ key: 'OPTIONAL_VAR', required: false }]
+    );
+    expect(errors).toHaveLength(0);
+  });
+
+  it('should validate number type', () => {
+    const rules: ValidationRule[] = [{ key: 'COUNT', type: 'number' }];
+    expect(validate({ COUNT: '42' }, rules)).toHaveLength(0);
+    expect(validate({ COUNT: 'abc' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate number min/max', () => {
+    const rules: ValidationRule[] = [{ key: 'N', type: 'number', min: 1, max: 100 }];
+    expect(validate({ N: '50' }, rules)).toHaveLength(0);
+    expect(validate({ N: '0' }, rules)).toHaveLength(1);
+    expect(validate({ N: '101' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate boolean type', () => {
+    const rules: ValidationRule[] = [{ key: 'DEBUG', type: 'boolean' }];
+    expect(validate({ DEBUG: 'true' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: 'false' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: '1' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: '0' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: 'yes' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: 'no' }, rules)).toHaveLength(0);
+    expect(validate({ DEBUG: 'maybe' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate URL type', () => {
+    const rules: ValidationRule[] = [{ key: 'URL', type: 'url' }];
+    expect(validate({ URL: 'https://example.com' }, rules)).toHaveLength(0);
+    expect(validate({ URL: 'not-a-url' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate email type', () => {
+    const rules: ValidationRule[] = [{ key: 'EMAIL', type: 'email' }];
+    expect(validate({ EMAIL: 'user@example.com' }, rules)).toHaveLength(0);
+    expect(validate({ EMAIL: 'not-an-email' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate port type', () => {
+    const rules: ValidationRule[] = [{ key: 'PORT', type: 'port' }];
+    expect(validate({ PORT: '3000' }, rules)).toHaveLength(0);
+    expect(validate({ PORT: '0' }, rules)).toHaveLength(1);
+    expect(validate({ PORT: '65536' }, rules)).toHaveLength(1);
+    expect(validate({ PORT: 'abc' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate enum type', () => {
+    const rules: ValidationRule[] = [
+      { key: 'NODE_ENV', type: 'enum', enum: ['development', 'staging', 'production'] }
+    ];
+    expect(validate({ NODE_ENV: 'development' }, rules)).toHaveLength(0);
+    expect(validate({ NODE_ENV: 'invalid' }, rules)).toHaveLength(1);
+  });
+
+  it('should validate custom pattern', () => {
+    const rules: ValidationRule[] = [
+      { key: 'CODE', pattern: /^[A-Z]{3}-\d{3}$/ }
+    ];
+    expect(validate({ CODE: 'ABC-123' }, rules)).toHaveLength(0);
+    expect(validate({ CODE: 'abc-123' }, rules)).toHaveLength(1);
+  });
+});
+
+describe('inferRules', () => {
+  it('should infer type from comment hint', () => {
+    const rules = inferRules('DATABASE_URL=postgresql://... # type:url');
+    expect(rules[0].type).toBe('url');
+  });
+
+  it('should infer optional from comment', () => {
+    const rules = inferRules('REDIS_URL= # type:url optional');
+    expect(rules[0].required).toBe(false);
+  });
+
+  it('should infer enum from comment', () => {
+    const rules = inferRules('NODE_ENV=development # enum:development,staging,production');
+    expect(rules[0].type).toBe('enum');
+    expect(rules[0].enum).toEqual(['development', 'staging', 'production']);
+  });
+
+  it('should infer URL type from value pattern', () => {
+    const rules = inferRules('API_URL=https://api.example.com');
+    expect(rules[0].type).toBe('url');
+  });
+
+  it('should infer port type from key name and numeric value', () => {
+    const rules = inferRules('SERVER_PORT=3000');
+    expect(rules[0].type).toBe('port');
+  });
+
+  it('should infer boolean type from value', () => {
+    const rules = inferRules('DEBUG=true');
+    expect(rules[0].type).toBe('boolean');
+  });
+
+  it('should infer number type from numeric value', () => {
+    const rules = inferRules('MAX_RETRIES=5');
+    expect(rules[0].type).toBe('number');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "lib": ["ES2020"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "tests"]
+}