env-typed-checker 0.2.3 → 0.2.4

package/README.md

@@ -1,299 +1,334 @@
-# env-typed-checker 
+# env-typed-checker
 
-Validate and parse environment variables using a tiny schema — with both a **TypeScript/Node API** and a **CLI**.
+Validate and parse environment variables with a small schema, using either:
 
-It helps your app fail fast when configuration is wrong:
+- TypeScript/Node API (`envDoctor`)
+- CLI (`env-typed-checker check` and `generate`)
 
-- ❌ Missing required variables
-- ❌ Wrong types (e.g. `PORT="abc"`)
-- ❌ Invalid URLs / emails / JSON
-- ❌ Values not matching allowed enums or regex patterns
-- ✅ Optional values + defaults
-- ✅ CLI checks for CI + .env generation
+This package helps your app fail fast when config is wrong.
+This README is the complete guide for installing, configuring, and using the package.
 
+## Why use this
 
----
+- Catch missing env vars early
+- Parse types (`number`, `boolean`, `json`) safely
+- Validate `url`, `email`, `enum`, and `regex` values
+- Keep one schema for runtime + CI checks
+- Generate `.env` / `.env.example` from schema
+- Redact secret values in CLI validation output
 
-## ✨ Features
-
-- Simple schema syntax (`"number"`, `"boolean?"`, `"email"` `"url"`, `"json"`, `"string"`)
-- Advanced specs: `enum` and `regex`
-- Optional values with `?` and `optional: true`
-- Defaults (typed + validated)
-- CLI:
-  - `check` → validate env
-  - `generate` → generate/update `.env` from schema (no overwrite by default)
-- Uses `.env` via `dotenv` (optional)
-- Friendly aggregated errors (see everything that’s wrong at once)
-
----
-
-## 📦 Install
+## Install
 
 ```bash
 npm install env-typed-checker
 ```
 
-Or run via npx:
+Or run directly:
 
 ```bash
 npx env-typed-checker --help
 ```
 
-## 🚀 Quick Start (Code)
-
-```ts
-import { envDoctor } from "env-typed-checker";
+Requirements:
 
-export const config = envDoctor({
-  PORT: "number",
-  DB_URL: "url",
-  ADMIN_EMAIL: "email",
-  DEBUG: "boolean?",
-});
+- Node.js `>=18`
 
-```
+## Quick start (recommended): one schema for CLI + code
 
-### What you get
+If you are new to this package, start with this pattern.
 
-* PORT → `number`
-* DB_URL → `string` (validated as URL)
-* ADMIN_EMAIL → `string` (validated as email)
-* DEBUG → `boolean` | `undefined` (optional)
+### 1) Create `env.schema.json`
 
+```json
+{
+  "PORT": { "type": "number", "default": 3000, "description": "HTTP port", "example": "8080" },
+  "DB_URL": { "type": "url", "description": "Primary database URL", "example": "postgres://user:pass@localhost:5432/app", "secret": true },
+  "ADMIN_EMAIL": { "type": "email", "description": "Ops contact email", "example": "ops@example.com" },
+  "DEBUG": "boolean?",
+  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"], "default": "dev" },
+  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" },
+  "FEATURE_FLAGS": { "type": "json", "default": { "beta": false } }
+}
+```
 
-### 🧩 Supported Types
-| Type | Description |
-| :--- | :--- |
-| **string** | Any string value |
-| **number** | A finite number (automatically parsed from string) |
-| **boolean** | Supports `true` / `false`, `1` / `0`, and `yes` / `no` |
-| **json** | Validates and parses a valid JSON string |
-| **url** | Validates for a properly formatted URL |
-| **email** | Validates for a properly formatted email |
+### 2) Reuse the same schema in app code
 
+ESM (NodeNext / `"type": "module"`):
 
-### Optional Values
-Add ? to make a variable optional:
 ```ts
-envDoctor({ DEBUG: "boolean?" });
-```
+// src/config.ts
+import { envDoctor, type EnvDoctorSchema } from "env-typed-checker";
+import schema from "../env.schema.json" assert { type: "json" };
 
-Or use object-style:
-
-```ts
-envDoctor({
-  DEBUG: { type: "boolean", optional: true },
+export const config = envDoctor(schema as EnvDoctorSchema, {
+  loadDotEnv: true,
 });
 ```
-Missing optional vars become `undefined` unless you provide a default.
 
-### 🎯 Defaults
-Defaults can be provided in object-style specs.
+CommonJS (or TS compiling to CJS):
 
 ```ts
-import { envDoctor } from "env-typed-checker";
+// src/config.ts
+import { envDoctor, type EnvDoctorSchema } from "env-typed-checker";
 
-const config = envDoctor({
-  PORT: { type: "number", default: 3000 },
-  DEBUG: { type: "boolean", default: "false" }, // string is allowed (parsed)
-  NODE_ENV: { type: "enum", values: ["dev", "prod"], default: "dev" },
-});
-```
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const schema = require("../env.schema.json") as EnvDoctorSchema;
 
-### Notes:
+export const config = envDoctor(schema, { loadDotEnv: true });
+```
 
-- `number` default: number or string (string will be parsed)
-- `boolean` default: boolean or string (string will be parsed)
-- `url/email` defaults must be strings and must validate
-- `json` defaults can be any JSON-like value
+TypeScript JSON import note:
 
-### ✅ Enum and Regex
+```json
+{
+  "compilerOptions": {
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  }
+}
+```
 
-### Enum
+### 3) Validate env via CLI
 
-```ts
-const config = envDoctor({
-  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
-});
+```bash
+npx env-typed-checker check --schema env.schema.json
 ```
 
-### Regex
+### 4) Generate `.env.example` from the same schema
 
-```ts
-const config = envDoctor({
-  SLUG: { type: "regex", pattern: "^[a-z0-9-]+$", flags: "i" },
-});
+```bash
+npx env-typed-checker generate --schema env.schema.json --out .env.example --comment-docs --example-values
 ```
 
-### ⚙️ Options
+Example output:
 
-```ts
-envDoctor(schema, {
-  loadDotEnv: true,   // default: true (loads .env)
-  env: process.env    // default: process.env (override for tests)
-});
+```env
+# HTTP port
+# example: 8080
+PORT=8080
+
+# Primary database URL
+# example: postgres://user:pass@localhost:5432/app
+DB_URL=postgres://user:pass@localhost:5432/app
 ```
 
+### 5) Use in CI (GitHub Actions annotations)
 
-### 🧪 Testing with custom env
+```yml
+- name: Validate env
+  run: npx env-typed-checker check --schema env.schema.json --format github
+```
+
+## API quick reference
 
 ```ts
 import { envDoctor } from "env-typed-checker";
 
-const cfg = envDoctor(
-  { PORT: "number" },
-  { loadDotEnv: false, env: { PORT: "3000" } }
+const config = envDoctor(
+  {
+    PORT: "number",
+    DEBUG: "boolean?",
+    NODE_ENV: { type: "enum", values: ["dev", "prod"] },
+  },
+  {
+    loadDotEnv: true,
+    env: process.env,
+  },
 );
-
-console.log(cfg.PORT); // 3000
 ```
 
-### ❌ Error Example
+### Parsed output types
 
-Given a `.env` like:
+| Schema type | Parsed result |
+| :--- | :--- |
+| `string` | `string` |
+| `number` | `number` |
+| `boolean` | `boolean` |
+| `json` | `unknown` |
+| `url` | `string` |
+| `email` | `string` |
+| `enum` | one of listed values |
+| `regex` | `string` |
 
-```env
-PORT=abc
-DB_URL=not-a-url
-NODE_ENV=staging
-```
+## Schema reference
 
-```ts
-import { envDoctor } from "env-typed-checker";
+### Primitive shorthand
 
-envDoctor({
-  PORT: "number",
-  DB_URL: "url"
-  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
-});
+```json
+{
+  "PORT": "number",
+  "DEBUG": "boolean?",
+  "DB_URL": "url"
+}
 ```
 
-### Output:
+- Add `?` to mark optional keys.
+- Missing optional keys become `undefined` (unless default exists).
 
-```ts
-ENV validation failed
-- PORT: expected number, got "abc"
-- DB_URL: expected url, got "not-a-url"
-- NODE_ENV: must be one of [dev, prod]
+### Object syntax
+
+```json
+{
+  "PORT": { "type": "number", "default": 3000 },
+  "DEBUG": { "type": "boolean", "optional": true },
+  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"] },
+  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" }
+}
 ```
-All errors are shown together so you can fix them in one go.
 
-# 🖥️ CLI
+### Defaults
 
-Validate your environment without writing code — perfect for CI pipelines.
+- `number`: number or numeric string
+- `boolean`: boolean or boolean-like string
+- `url` / `email`: valid strings
+- `json`: any JSON-like value
 
-## 1) Create a schema file
+### Metadata fields (object syntax only)
 
-`env.schema.json`
 ```json
 {
-  "PORT": "number",
-  "DB_URL": "url",
-  "ADMIN_EMAIL": "email",
-  "DEBUG": "boolean?",
-  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"] },
-  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" }
+  "API_KEY": {
+    "type": "string",
+    "description": "External service token",
+    "example": "sk_test_123",
+    "secret": true
+  }
 }
 ```
 
-## 2) Run the check
+- `description?: string` used by `generate --comment-docs`
+- `example?: string` used in comments and optional generation values
+- `secret?: boolean` redacts invalid raw values in CLI `check`
 
-```bash
-npx env-typed-checker check --schema env.schema.json
+If you need metadata for a primitive shorthand key, wrap it in object syntax:
+
+```json
+{
+  "PORT": { "type": "number", "description": "HTTP port" }
+}
 ```
 
-Useful flags
+### Runtime behavior notes
+
+- Empty strings (`""`) are treated as missing values.
+- Validation errors are aggregated and returned together.
+- CLI `check` merges `.env` values over current shell env when dotenv loading is enabled.
+
+## CLI reference
+
+### `check`
 
 ```bash
-# Use a specific env file (instead of .env)
-npx env-typed-checker check --schema env.schema.json --env-file .env.production
+env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv] [--format pretty|json|github]
+```
 
-# Skip dotenv loading and validate only process.env
-npx env-typed-checker check --schema env.schema.json --no-dotenv
+Flags:
+
+- `--schema <file>` required schema file
+- `--env-file <file>` env file path (default `.env`)
+- `--no-dotenv` validate only current `process.env`
+- `--format pretty|json|github` output style (default `pretty`)
+
+### `check` output formats
+
+`pretty` (default):
+
+```text
+ENV validation failed
+- PORT: expected number, got "abc"
 ```
 
-### `generate` — generate or update `.env`
+`json`:
+
+```json
+{"error":"ENV validation failed","issues":[{"key":"PORT","kind":"invalid","message":"expected number, got \"abc\""}]}
+```
 
-Generate values from schema (writes missing keys; does not overwrite existing values).
+`github` (for workflow annotations):
 
-```bash
-npx env-typed-checker generate --schema env.schema.json
+```text
+::error title=ENV validation::PORT: expected number, got "abc"
 ```
-### By default:
 
-- output file: .env
-- mode: update
+When a key has `secret: true`, CLI output redacts raw invalid values:
 
-### Flags
+```text
+SECRET_TOKEN: expected number, got "<redacted>"
+```
+
+### `generate`
 
 ```bash
-# Custom output file
-npx env-typed-checker generate --schema env.schema.json --out .env.example
+env-typed-checker generate --schema <file> [--out <file>] [--mode update|create] [--no-defaults] [--comment-types] [--comment-docs] [--example-values]
+```
 
-# Create mode: refuse to overwrite an existing file
-npx env-typed-checker generate --schema env.schema.json --out .env --mode=create
+Defaults:
 
-# Update mode: append only missing keys (safe)
-npx env-typed-checker generate --schema env.schema.json --out .env --mode=update
+- output file: `.env`
+- mode: `update`
+- behavior: append only missing keys
 
-# Do not write defaults (leave blank values)
-npx env-typed-checker generate --schema env.schema.json --no-defaults
+Flags:
 
-# Add inline type comments (useful for .env.example)
-npx env-typed-checker generate --schema env.schema.json --comment-types
-```
+- `--out <file>` custom output path
+- `--mode create` fail if file already exists
+- `--mode update` append missing keys only
+- `--no-defaults` write empty values instead of defaults
+- `--comment-types` add inline type comments
+- `--comment-docs` add `description` and `example` comments above keys
+- `--example-values` use schema `example` values as generated values
 
-### Exit codes
+## Exit codes
 
-* `0` = OK
-* `1` = validation failed
-* `2` = CLI usage / unexpected error
+- `0` success
+- `1` validation failed
+- `2` CLI usage error or unexpected error
 
-## ✅ CI Example (GitHub Actions)
+## CI examples
 
-Add this to your workflow to fail the build if env is invalid:
+GitHub Actions with annotations:
 
 ```yml
 - name: Validate env
-  run: npx env-typed-checker check --schema env.schema.json
+  run: npx env-typed-checker check --schema env.schema.json --format github
 ```
-If you use a specific env file in CI:
+
+With custom env file:
 
 ```yml
 - name: Validate env
-  run: npx env-typed-checker check --schema env.schema.json --env-file .env.ci
+  run: npx env-typed-checker check --schema env.schema.json --env-file .env.ci --format github
 ```
 
-## 🛠 Development
-Clone the repo and install:
-```bash
-npm install
-npm test
-```
-### Common scripts:
-```bash
-npm run build      # build package
-npm run test       # run tests
-npm run typecheck  # TypeScript check
-npm run dev        # watch build
-```
+## Testing with custom env in code
+
+```ts
+import { envDoctor } from "env-typed-checker";
 
-### 🤝 Contributing
-PRs are welcome!
+const cfg = envDoctor(
+  { PORT: "number" },
+  { loadDotEnv: false, env: { PORT: "3000" } },
+);
+
+console.log(cfg.PORT); // 3000
+```
 
-* Improve docs / examples
-* Add more schema features
-* Improve CLI output formatting
-* Add integrations / templates
+## Common mistakes
 
+- Missing `--schema` in CLI commands
+- Using shorthand string syntax when you need metadata (`description`, `example`, `secret`)
+- Forgetting `resolveJsonModule` when importing `env.schema.json` in TypeScript
 
-# 📝 License
-MIT
+## Development
 
+```bash
+npm install
+npm run lint
+npm run typecheck
+npm run test:coverage
+npm run build
+```
 
----
+## License
 
-```yml
-::contentReference[oaicite:0]{index=0}
-```
+MIT

package/dist/{chunk-L5DK6LRX.mjs → chunk-CCJEPMPN.mjs}

@@ -102,6 +102,33 @@ function coerceDefault(kind, def) {
     }
   }
 }
+function normalizeMeta(schemaValue) {
+  let description = void 0;
+  if (hasOwn(schemaValue, "description")) {
+    const d = schemaValue.description;
+    if (d !== void 0 && typeof d !== "string") {
+      throw new Error(`"description" must be a string if provided`);
+    }
+    description = d;
+  }
+  let example = void 0;
+  if (hasOwn(schemaValue, "example")) {
+    const ex = schemaValue.example;
+    if (ex !== void 0 && typeof ex !== "string") {
+      throw new Error(`"example" must be a string if provided`);
+    }
+    example = ex;
+  }
+  let secret = false;
+  if (hasOwn(schemaValue, "secret")) {
+    const s = schemaValue.secret;
+    if (s !== void 0 && typeof s !== "boolean") {
+      throw new Error(`"secret" must be a boolean if provided`);
+    }
+    secret = s === true;
+  }
+  return { description, example, secret };
+}
 function normalizeSpec(schemaValue) {
   if (typeof schemaValue === "string") {
     const optional = schemaValue.endsWith("?");
@@ -119,12 +146,17 @@ function normalizeSpec(schemaValue) {
         `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url, email (optional with ?)`
       );
     }
-    return { kind: base, optional };
+    return {
+      kind: base,
+      optional,
+      secret: false
+    };
   }
   if (!schemaValue || typeof schemaValue !== "object" || Array.isArray(schemaValue)) {
     throw new Error("Schema value must be a string or object spec.");
   }
   const t = schemaValue.type;
+  const meta = normalizeMeta(schemaValue);
   const primitiveAllowed = [
     "string",
     "number",
@@ -136,7 +168,12 @@ function normalizeSpec(schemaValue) {
   if (primitiveAllowed.includes(t)) {
     const optional = !!schemaValue.optional;
     const defaultValue = hasOwn(schemaValue, "default") ? coerceDefault(t, schemaValue.default) : void 0;
-    return { kind: t, optional, defaultValue };
+    return {
+      kind: t,
+      optional,
+      defaultValue,
+      ...meta
+    };
   }
   if (t === "enum") {
     const values = schemaValue.values;
@@ -157,7 +194,13 @@ function normalizeSpec(schemaValue) {
       }
       defaultValue = def;
     }
-    return { kind: "enum", optional, values, defaultValue };
+    return {
+      kind: "enum",
+      optional,
+      values,
+      defaultValue,
+      ...meta
+    };
   }
   if (t === "regex") {
     const pattern = schemaValue.pattern;
@@ -187,7 +230,14 @@ function normalizeSpec(schemaValue) {
       }
       defaultValue = def;
     }
-    return { kind: "regex", optional, re, display, defaultValue };
+    return {
+      kind: "regex",
+      optional,
+      re,
+      display,
+      defaultValue,
+      ...meta
+    };
   }
   throw new Error(
     `Unsupported object spec type "${String(t)}". Supported: primitives (string/number/boolean/json/url/email), enum, regex`
@@ -259,4 +309,4 @@ export {
   normalizeSpec,
   envDoctor
 };
-//# sourceMappingURL=chunk-L5DK6LRX.mjs.map
+//# sourceMappingURL=chunk-CCJEPMPN.mjs.map

package/dist/chunk-CCJEPMPN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/envDoctor.ts","../src/errors/EnvDoctorError.ts","../src/validators/primitives.ts","../src/core/runner.ts"],"sourcesContent":["import * as dotenv from \"dotenv\";\nimport { validateAndParse } from \"./runner\";\nimport type { EnvDoctorOptions, EnvDoctorResult, EnvDoctorSchema } from \"../types\";\n\nexport type { EnvDoctorOptions, EnvDoctorSchema } from \"../types\";\nexport { EnvDoctorError } from \"../errors/EnvDoctorError\";\n\nexport function envDoctor<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  options: EnvDoctorOptions = {}\n): EnvDoctorResult<TSchema> {\n  const { loadDotEnv = true, env = process.env } = options;\n\n  if (loadDotEnv) dotenv.config();\n\n  return validateAndParse(schema, env);\n}\n","export type EnvDoctorIssue =\n  | { key: string; kind: \"missing\"; message: string }\n  | { key: string; kind: \"invalid\"; message: string };\n\nexport class EnvDoctorError extends Error {\n  public readonly issues: EnvDoctorIssue[];\n\n  constructor(issues: EnvDoctorIssue[]) {\n    const header = \"ENV validation failed\";\n    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);\n    super([header, ...lines].join(\"\\n\"));\n    this.name = \"EnvDoctorError\";\n    this.issues = issues;\n  }\n}\n","import type { EnvBaseType, EnvSchemaValue } from \"../types\";\n\nconst EMAIL_RE = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nexport function parseByType(type: EnvBaseType, raw: string): unknown {\n  switch (type) {\n    case \"string\":\n      return raw;\n\n    case \"number\": {\n      const n = Number(raw.trim());\n      if (!Number.isFinite(n)) throw new Error(`expected number, got \"${raw}\"`);\n      return n;\n    }\n\n    case \"boolean\": {\n      const v = raw.trim().toLowerCase();\n      if ([\"true\", \"1\", \"yes\", \"y\", \"on\"].includes(v)) return true;\n      if ([\"false\", \"0\", \"no\", \"n\", \"off\"].includes(v)) return false;\n      throw new Error(\n        `expected boolean (true/false/1/0/yes/no/on/off), got \"${raw}\"`,\n      );\n    }\n\n    case \"json\": {\n      try {\n        return JSON.parse(raw);\n      } catch {\n        throw new Error(`expected json, got \"${raw}\"`);\n      }\n    }\n\n    case \"url\": {\n      try {\n        new URL(raw);\n        return raw;\n      } catch {\n        throw new Error(`expected url, got \"${raw}\"`);\n      }\n    }\n\n    case \"email\": {\n      const s = raw.trim();\n      if (!EMAIL_RE.test(s)) {\n        throw new Error(`expected email, got \"${raw}\"`);\n      }\n      return s;\n    }\n\n    default: {\n      throw new Error(`unsupported primitive type: ${String(type)}`);\n    }\n  }\n}\n\nfunction hasOwn(obj: unknown, key: string): boolean {\n  return Object.prototype.hasOwnProperty.call(obj, key);\n}\n\n/**\n * Type-check + normalize a default value into the right runtime type.\n * - Allows string defaults for number/boolean (parsed)\n * - Validates url/email defaults\n * - json defaults can be any value\n */\nfunction coerceDefault(kind: EnvBaseType, def: unknown): unknown {\n  if (def === undefined) return undefined;\n\n  switch (kind) {\n    case \"string\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for string must be a string`);\n      return def;\n    }\n\n    case \"number\": {\n      if (typeof def === \"number\") {\n        if (!Number.isFinite(def))\n          throw new Error(`default for number must be finite`);\n        return def;\n      }\n      if (typeof def === \"string\") return parseByType(\"number\", def);\n      throw new Error(`default for number must be number or string`);\n    }\n\n    case \"boolean\": {\n      if (typeof def === \"boolean\") return def;\n      if (typeof def === \"string\") return parseByType(\"boolean\", def);\n      throw new Error(`default for boolean must be boolean or string`);\n    }\n\n    case \"json\": {\n      // allow any JSON-ish value\n      return def;\n    }\n\n    case \"url\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for url must be a string`);\n      return parseByType(\"url\", def);\n    }\n\n    case \"email\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for email must be a string`);\n      return parseByType(\"email\", def);\n    }\n\n    /* c8 ignore next */\n    default: {\n      throw new Error(`unsupported default kind: ${String(kind)}`);\n    }\n  }\n}\n\n/** Normalized spec used by the runner */\nexport type NormalizedSpec =\n  | {\n      kind: EnvBaseType;\n      optional: boolean;\n      defaultValue?: unknown;\n      description?: string;\n      example?: string;\n      secret: boolean;\n    }\n  | {\n      kind: \"enum\";\n      optional: boolean;\n      values: readonly string[];\n      defaultValue?: string;\n      description?: string;\n      example?: string;\n      secret: boolean;\n    }\n  | {\n      kind: \"regex\";\n      optional: boolean;\n      re: RegExp;\n      display: string;\n      defaultValue?: string;\n      description?: string;\n      example?: string;\n      secret: boolean;\n    };\n\nfunction normalizeMeta(schemaValue: Record<string, unknown>): {\n  description?: string;\n  example?: string;\n  secret: boolean;\n} {\n  let description: string | undefined = undefined;\n  if (hasOwn(schemaValue, \"description\")) {\n    const d = schemaValue.description;\n    if (d !== undefined && typeof d !== \"string\") {\n      throw new Error(`\"description\" must be a string if provided`);\n    }\n    description = d;\n  }\n\n  let example: string | undefined = undefined;\n  if (hasOwn(schemaValue, \"example\")) {\n    const ex = schemaValue.example;\n    if (ex !== undefined && typeof ex !== \"string\") {\n      throw new Error(`\"example\" must be a string if provided`);\n    }\n    example = ex;\n  }\n\n  let secret = false;\n  if (hasOwn(schemaValue, \"secret\")) {\n    const s = schemaValue.secret;\n    if (s !== undefined && typeof s !== \"boolean\") {\n      throw new Error(`\"secret\" must be a boolean if provided`);\n    }\n    secret = s === true;\n  }\n\n  return { description, example, secret };\n}\n\nexport function normalizeSpec(schemaValue: EnvSchemaValue): NormalizedSpec {\n  // --------------------\n  // String style: \"number?\" etc.\n  // --------------------\n  if (typeof schemaValue === \"string\") {\n    const optional = schemaValue.endsWith(\"?\");\n    const base = optional ? schemaValue.slice(0, -1) : schemaValue;\n\n    const allowed: readonly EnvBaseType[] = [\n      \"string\",\n      \"number\",\n      \"boolean\",\n      \"json\",\n      \"url\",\n      \"email\",\n    ];\n\n    if (!allowed.includes(base as EnvBaseType)) {\n      throw new Error(\n        `Unsupported type \"${schemaValue}\". Supported: string, number, boolean, json, url, email (optional with ?)`,\n      );\n    }\n\n    return {\n      kind: base as EnvBaseType,\n      optional,\n      secret: false,\n    };\n  }\n\n  // --------------------\n  // Object style\n  // --------------------\n  if (\n    !schemaValue ||\n    typeof schemaValue !== \"object\" ||\n    Array.isArray(schemaValue)\n  ) {\n    throw new Error(\"Schema value must be a string or object spec.\");\n  }\n\n  const t = (schemaValue as any).type;\n  const meta = normalizeMeta(schemaValue as Record<string, unknown>);\n\n  // --------------------\n  // Primitive object spec: { type: \"number\", optional?: true, default?: ... }\n  // --------------------\n  const primitiveAllowed: readonly EnvBaseType[] = [\n    \"string\",\n    \"number\",\n    \"boolean\",\n    \"json\",\n    \"url\",\n    \"email\",\n  ];\n\n  if (primitiveAllowed.includes(t)) {\n    const optional = !!(schemaValue as any).optional;\n    const defaultValue = hasOwn(schemaValue, \"default\")\n      ? coerceDefault(t as EnvBaseType, (schemaValue as any).default)\n      : undefined;\n\n    return {\n      kind: t as EnvBaseType,\n      optional,\n      defaultValue,\n      ...meta,\n    };\n  }\n\n  // --------------------\n  // Enum: { type: \"enum\", values: [...], optional?: true, default?: \"dev\" }\n  // --------------------\n  if (t === \"enum\") {\n    const values = (schemaValue as any).values;\n    if (\n      !Array.isArray(values) ||\n      values.length === 0 ||\n      !values.every((v: any) => typeof v === \"string\")\n    ) {\n      throw new Error(`enum spec requires \"values\": string[] (non-empty)`);\n    }\n\n    const optional = !!(schemaValue as any).optional;\n\n    let defaultValue: string | undefined = undefined;\n    if (hasOwn(schemaValue, \"default\")) {\n      const def = (schemaValue as any).default;\n      if (typeof def !== \"string\") {\n        throw new Error(`default for enum must be a string`);\n      }\n      if (!values.includes(def)) {\n        throw new Error(\n          `default \"${def}\" must be one of [${values.join(\", \")}]`,\n        );\n      }\n      defaultValue = def;\n    }\n\n    return {\n      kind: \"enum\",\n      optional,\n      values,\n      defaultValue,\n      ...meta,\n    };\n  }\n\n  // --------------------\n  // Regex: { type: \"regex\", pattern: \"...\", flags?: \"...\", optional?: true, default?: \"abc\" }\n  // --------------------\n  if (t === \"regex\") {\n    const pattern = (schemaValue as any).pattern;\n    const flags = (schemaValue as any).flags;\n\n    if (typeof pattern !== \"string\" || pattern.length === 0) {\n      throw new Error(`regex spec requires \"pattern\": string`);\n    }\n    if (flags !== undefined && typeof flags !== \"string\") {\n      throw new Error(`regex spec \"flags\" must be a string if provided`);\n    }\n\n    let re: RegExp;\n    try {\n      re = new RegExp(pattern, flags);\n    } catch (e) {\n      throw new Error(`invalid regex: ${String(e)}`);\n    }\n\n    const display = `/${pattern}/${flags ?? \"\"}`;\n    const optional = !!(schemaValue as any).optional;\n\n    let defaultValue: string | undefined = undefined;\n    if (hasOwn(schemaValue, \"default\")) {\n      const def = (schemaValue as any).default;\n      if (typeof def !== \"string\") {\n        throw new Error(`default for regex must be a string`);\n      }\n      if (!re.test(def)) {\n        throw new Error(`default \"${def}\" does not match ${display}`);\n      }\n      defaultValue = def;\n    }\n\n    return {\n      kind: \"regex\",\n      optional,\n      re,\n      display,\n      defaultValue,\n      ...meta,\n    };\n  }\n\n  throw new Error(\n    `Unsupported object spec type \"${String(t)}\". Supported: primitives (string/number/boolean/json/url/email), enum, regex`,\n  );\n}\n","import { EnvDoctorError, type EnvDoctorIssue } from \"../errors/EnvDoctorError\";\nimport { normalizeSpec, parseByType } from \"../validators/primitives\";\nimport type { EnvDoctorResult, EnvDoctorSchema } from \"../types\";\n\nexport function validateAndParse<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  env: Record<string, string | undefined>,\n): EnvDoctorResult<TSchema> {\n  const issues: EnvDoctorIssue[] = [];\n  const out: Record<string, unknown> = {};\n\n  for (const [key, schemaValue] of Object.entries(schema)) {\n    let spec: ReturnType<typeof normalizeSpec>;\n\n    try {\n      spec = normalizeSpec(schemaValue);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      issues.push({ key, kind: \"invalid\", message: msg });\n      continue;\n    }\n\n    const raw = env[key];\n\n    // treat undefined or empty string as \"missing\"\n    if (raw === undefined || raw === \"\") {\n      if (spec.defaultValue !== undefined) {\n        out[key] = spec.defaultValue;\n      } else if (spec.optional) {\n        out[key] = undefined;\n      } else {\n        issues.push({\n          key,\n          kind: \"missing\",\n          message: \"missing required environment variable\",\n        });\n      }\n      continue;\n    }\n\n    try {\n      if (spec.kind === \"enum\") {\n        if (!spec.values.includes(raw)) {\n          throw new Error(\n            `expected one of [${spec.values.join(\", \")}], got \"${raw}\"`,\n          );\n        }\n        out[key] = raw;\n      } else if (spec.kind === \"regex\") {\n        if (!spec.re.test(raw)) {\n          throw new Error(`does not match ${spec.display}`);\n        }\n        out[key] = raw;\n      } else {\n        // primitives: string/number/boolean/json/url/email\n        out[key] = parseByType(spec.kind, raw);\n      }\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      issues.push({ key, kind: \"invalid\", message: msg });\n    }\n  }\n\n  if (issues.length > 0) throw new EnvDoctorError(issues);\n\n  return out as EnvDoctorResult<TSchema>;\n}\n"],"mappings":"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","names":[]}