# Contributing to envprowl

Thanks for considering it — this project is intentionally small so it's easy
to get a first PR merged in an evening.

## Setup

```bash
git clone https://github.com/BBguss/envprowl.git
cd envprowl
npm install
npm run dev -- --help   # runs the CLI straight from source via tsx
npm test
```

## Project layout

```
src/
  cli.ts             entry point — argument parsing, wiring things together
  parser.ts          reads .env-style files into key/value pairs
  config.ts          loads and applies .envprowlrc (ignore list, severity overrides)
  reporter.ts         prints results to the terminal, or as JSON with --json
  validators/
    types.ts          the Validator interface
    required.ts        checks for missing/empty keys
    format.ts           heuristic format checks (URL, port, boolean)
    secrets.ts           flags values that look like leaked API keys/tokens
    undeclared.ts        flags keys in .env not declared in .env.example
    index.ts            registry — new validators get added here
tests/
  *.test.ts           one test file per validator (plus config.test.ts), uses node:test (no extra deps)
```

## Adding a new validator

This is the easiest and most welcome type of contribution.

1. Create `src/validators/your-name.ts`:

   ```ts
   import type { Validator, ValidationIssue } from "./types.js";

   export const yourValidator: Validator = {
     name: "your-name",
     run(actual, expected): ValidationIssue[] {
       const issues: ValidationIssue[] = [];
       // your check here
       return issues;
     },
   };
   ```

2. Register it in `src/validators/index.ts`.
3. Add a test file in `tests/` following the pattern in `format.test.ts`.
4. Update the validator table in `README.md`.

Ideas for validators that aren't built yet (pick one, or bring your own):

- More secret patterns in `secrets.ts` (Google API keys, npm tokens, Twilio, etc.)
- Detect duplicate keys within the same `.env` file
- Warn on trailing whitespace or obviously mismatched quoting
- A validator that checks values against a regex defined per-key in `.envprowlrc`

Other good first issues outside of validators:

- Support multiline values in `parser.ts` (currently one key=value per line)
- A `--fix` flag that generates a `.env` stub from `.env.example`
- Better error messages when `.envprowlrc` fails validation (currently just a raw JSON parse error)

## Pull request guidelines

- Keep PRs focused — one validator or one fix per PR is easier to review than five.
- Add or update a test for any behavior change.
- Run `npm test` before opening the PR.
- No need to ask permission first — open the PR and we'll discuss there. For
  larger changes (new CLI flags, breaking changes), an issue first is helpful
  but not required.

## Reporting bugs

Open an issue with:
- Your `.env.example` and `.env` (redact real secrets!)
- The command you ran
- What you expected vs. what happened

## Code of conduct

Be respectful. Assume good faith. That's it.