@xlameiro/env-typegen 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.2
+
+### Patch Changes
+
+- Refresh the published npm package metadata and README to match the current repository documentation.
+
 All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) and uses
@@ -7,7 +13,39 @@ This project adheres to [Semantic Versioning](https://semver.org/) and uses
 
 <!-- Releases are added automatically by `changeset version` -->
 
-## [0.1.0] — 2026-03-16
+## [0.1.1] — 2026-03-17
+
+### Fixed
+
+- **A1** — VERSION was hardcoded as `"0.1.0"` in `cli.ts`; now read dynamically from `package.json` via `createRequire` so it stays in sync without manual edits.
+- **A2** — Double-quotes in `@description` annotations were not escaped in the t3-generator output, corrupting the generated `createEnv(...)` call. Fixed with `.replace(/"/g, '\\"')`.
+- **A3** — Prettier parse errors in `formatOutput` were silently swallowed; a `console.warn` is now emitted before the raw-content fallback.
+- **A4** — Watch mode only listened for `"change"` events; it now also handles `"add"` and `"unlink"` so editor save-with-delete patterns are covered.
+- **A5** — Config file changes during `--watch` were silently ignored; a second chokidar watcher now monitors the config file and reloads it on change.
+- **C1** — `formatOutput` (Prettier) was called unnecessarily in dry-run mode; formatting now runs only when actually writing to disk.
+- **C3** — Removed duplicate alias exports (`generateTypeScript`, `generateZod`); the canonical names `generateTypeScriptTypes` and `generateZodSchema` are the only public exports.
+- **E1–E3** — README badge URLs had `YOUR_USERNAME` placeholders; replaced with the real GitHub/npm identifiers. Package name aligned to `@xlameiro/env-typegen` throughout all docs.
+- **E4** — README `--format` example was misleading; corrected to use `--generator`/`-f` for generator selection and document `--no-format` for disabling Prettier.
+- **E5** — `parseEnvFile` was documented as `async`/awaitable but is synchronous; removed erroneous `await` from all examples.
+- **DRY** — `CONFIG_FILE_NAMES` was duplicated between `config.ts` and `watch.ts`; exported from `config.ts` and imported in `watch.ts`.
+
+### Added
+
+- **B1** — `EnvTypegenConfig.input` now accepts `string | string[]`; CLI `--input`/`-i` can be repeated to process multiple `.env` files in one run.
+- **B2** — `inferenceRules?: InferenceRule[]` added to `EnvTypegenConfig` and `RunGenerateOptions`; custom rules are prepended before the built-in ruleset.
+- **B3** — Default generators changed from `["typescript"]` to all four: `["typescript", "zod", "t3", "declaration"]`, matching the spec.
+- **B4** — Dry-run mode now prints each generated output block to stdout so users can preview content without touching the filesystem.
+- **B5** — Watch mode debounces rapid file-change events (200 ms) to prevent multiple simultaneous pipeline runs on editor autosave.
+
+### Tests
+
+- Regression test for double-quotes in t3-generator descriptions (A2).
+- CLI version tests read expected version from `package.json` (A1).
+- Four `loadConfig()` unit tests with temp-dir fixtures (no stale state).
+- Dry-run stdout spy test verifying preview content appears (B4).
+- Integration tests expanded to five end-to-end scenarios via `execSync` against the built `dist/cli.js`.
+
+[0.1.1]: https://github.com/xlameiro/env-typegen/compare/packages/env-typegen@0.1.0...packages/env-typegen@0.1.1
 
 ### Added
 
@@ -54,4 +92,4 @@ This project adheres to [Semantic Versioning](https://semver.org/) and uses
 - Full TSDoc on every public export in `src/index.ts`
 - README with Quick Start (CLI examples), Programmatic API, and Configuration sections
 
-[0.1.0]: https://github.com/YOUR_USERNAME/env-typegen/releases/tag/v0.1.0
+[0.1.0]: https://github.com/xlameiro/env-typegen/releases/tag/v0.1.0

package/README.md

@@ -2,8 +2,8 @@
 
 > From `.env.example` to TypeScript in one command.
 
-[![npm version](https://badge.fury.io/js/env-typegen.svg)](https://npmjs.com/package/env-typegen)
-[![CI](https://github.com/YOUR_USERNAME/env-typegen/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/env-typegen/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/%40xlameiro%2Fenv-typegen.svg)](https://npmjs.com/package/@xlameiro/env-typegen)
+[![CI](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml/badge.svg)](https://github.com/xlameiro/env-typegen/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 
@@ -11,31 +11,53 @@
 
 `env-typegen` reads `.env.example` files and automatically generates:
 
-- TypeScript types (`type Env = { PORT: number; DATABASE_URL: string }`)
+- TypeScript types (`type EnvVars = { PORT: number; DATABASE_URL: string }`)
 - Zod v4 schemas (`z.object({ PORT: z.coerce.number() })`)
 - `@t3-oss/env-nextjs` `createEnv` configuration
 - `.d.ts` declaration files that augment `NodeJS.ProcessEnv`
 
+## Install
+
+```bash
+pnpm add -D @xlameiro/env-typegen
+# or
+npm install --save-dev @xlameiro/env-typegen
+```
+
 ## Quick Start
 
 ```bash
-# Generate TypeScript types (default)
+# Generate all outputs (default: typescript + zod + t3 + declaration)
 npx env-typegen --input .env.example --output src/env.generated.ts
 
-# Generate a Zod schema
+# Generate only a Zod schema
 npx env-typegen -i .env.example -o src/env.schema.ts -g zod
 
-# Generate multiple outputs and format with Prettier
-npx env-typegen -i .env.example -o src/env.ts -g typescript -g zod --format
+# Generate multiple outputs explicitly
+npx env-typegen -i .env.example -o src/env.ts -f typescript -f zod
+
+# Generate without running Prettier
+npx env-typegen -i .env.example -o src/env.ts --no-format
 
 # Watch mode — regenerate on every change
 npx env-typegen -i .env.example -o src/env.ts --watch
 ```
 
+## Generator formats
+
+Use `-f` / `--format` (or `-g` / `--generator` alias):
+
+| Value                | Meaning                              |
+| -------------------- | ------------------------------------ |
+| `ts` or `typescript` | Generate TypeScript types            |
+| `zod`                | Generate Zod schema                  |
+| `t3`                 | Generate `@t3-oss/env-nextjs` config |
+| `declaration`        | Generate `.d.ts` declaration         |
+
 ## Programmatic API
 
 ```ts
-import { runGenerate, parseEnvFile, generateTypeScriptTypes } from "env-typegen";
+import { runGenerate, parseEnvFile, generateTypeScriptTypes } from "@xlameiro/env-typegen";
 
 // High-level: full pipeline
 await runGenerate({
@@ -46,7 +68,7 @@ await runGenerate({
 });
 
 // Low-level: parse then generate individually
-const parsed = await parseEnvFile(".env.example");
+const parsed = parseEnvFile(".env.example");
 const ts = generateTypeScriptTypes(parsed);
 ```
 
@@ -55,7 +77,7 @@ const ts = generateTypeScriptTypes(parsed);
 Create `env-typegen.config.ts` at your project root:
 
 ```ts
-import { defineConfig } from "env-typegen";
+import { defineConfig } from "@xlameiro/env-typegen";
 
 export default defineConfig({
   input: ".env.example",
@@ -67,16 +89,11 @@ export default defineConfig({
 
 ## Status
 
-| Phase | Description    | Status |
-| ----- | -------------- | ------ |
-| 1     | Foundation     | ✅     |
-| 2     | Parser         | ✅     |
-| 3     | Inferrer       | ✅     |
-| 4     | Generators     | ✅     |
-| 5     | Config & Utils | ✅     |
-| 6     | CLI            | ✅     |
-| 7     | Quality & Docs | ✅     |
-| 8     | Publishing     | 🔜     |
+`env-typegen` is actively maintained and published on npm.
+
+## Changelog
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
 
 ## License
 

package/dist/cli.js

@@ -99,8 +99,9 @@ var require_picocolors = __commonJS({
 });
 
 // src/cli.ts
+import { createRequire } from "module";
 import { realpathSync } from "fs";
-import path6 from "path";
+import path7 from "path";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "url";
 import { inspect, parseArgs } from "util";
 
@@ -180,7 +181,7 @@ function generateT3Env(parsed) {
       const effectiveType = variable.annotatedType ?? variable.inferredType;
       let zodExpr = toT3ZodType(effectiveType);
       if (variable.description !== void 0) {
-        zodExpr += `.describe("${variable.description}")`;
+        zodExpr += `.describe("${variable.description.replace(/"/g, '\\"')}")`;
       }
       if (variable.isOptional) {
         zodExpr += ".optional()";
@@ -195,7 +196,7 @@ function generateT3Env(parsed) {
       const effectiveType = variable.annotatedType ?? variable.inferredType;
       let zodExpr = toT3ZodType(effectiveType);
       if (variable.description !== void 0) {
-        zodExpr += `.describe("${variable.description}")`;
+        zodExpr += `.describe("${variable.description.replace(/"/g, '\\"')}")`;
       }
       if (variable.isOptional) {
         zodExpr += ".optional()";
@@ -397,7 +398,9 @@ var inferenceRules = [
 // src/inferrer/type-inferrer.ts
 var sortedRules = [...inferenceRules].sort((left, right) => left.priority - right.priority);
 function inferType(key, value, options) {
-  for (const rule of sortedRules) {
+  const extra = options?.extraRules;
+  const rules = extra && extra.length > 0 ? [...extra].sort((a, b) => a.priority - b.priority).concat(sortedRules) : sortedRules;
+  for (const rule of rules) {
     if (rule.match(key, value)) {
       return rule.type;
     }
@@ -448,7 +451,7 @@ function parseCommentBlock(lines) {
 // src/parser/env-parser.ts
 var ENV_VAR_RE = /^([A-Z_][A-Z0-9_]*)=(.*)$/;
 var SECTION_HEADER_RE = /^#\s+[-=]{3,}\s+(.+?)\s+[-=]{3,}\s*$/;
-function parseEnvFileContent(content, filePath) {
+function parseEnvFileContent(content, filePath, options) {
   const lines = content.split("\n");
   const vars = [];
   const groups = [];
@@ -481,7 +484,11 @@ function parseEnvFileContent(content, filePath) {
       const key = envMatch[1] ?? "";
       const rawValue = envMatch[2] ?? "";
       const annotations = parseCommentBlock(commentBlock);
-      const inferredType = inferType(key, rawValue);
+      const inferredType = inferType(
+        key,
+        rawValue,
+        ...options?.inferenceRules !== void 0 ? [{ extraRules: options.inferenceRules }] : []
+      );
       const isRequired = rawValue.length > 0 || annotations.isRequired;
       const isOptional = rawValue.length === 0 && !annotations.isRequired;
       const isClientSide = key.startsWith("NEXT_PUBLIC_");
@@ -529,7 +536,11 @@ import { format } from "prettier";
 async function formatOutput(content, parser = "typescript") {
   try {
     return await format(content, { parser });
-  } catch {
+  } catch (err) {
+    console.warn(
+      "env-typegen: Prettier formatting failed, writing unformatted output.",
+      err instanceof Error ? err.message : String(err)
+    );
     return content;
   }
 }
@@ -555,6 +566,12 @@ function deriveOutputPath(base, generator, isSingle) {
   const outExt = generator === "declaration" ? ".d.ts" : baseExt;
   return `${noExt}.${generator}${outExt}`;
 }
+function deriveOutputBaseForInput(output, inputPath) {
+  const dir = path5.dirname(output);
+  const ext = path5.extname(output);
+  const stem = path5.basename(inputPath, path5.extname(inputPath));
+  return path5.join(dir, `${stem}${ext}`);
+}
 function buildOutput(generator, parsed) {
   switch (generator) {
     case "typescript":
@@ -580,7 +597,11 @@ async function persistOutput(params) {
   }
   if (dryRun) {
     if (!silent) {
-      success(`Dry run: ${outputPath}`);
+      if (!isSingle) {
+        console.log(`// --- ${generator}: ${outputPath} ---`);
+      }
+      console.log(generated);
+      success(`Dry run: would write ${outputPath}`);
     }
     return;
   }
@@ -597,47 +618,97 @@ async function runGenerate(options) {
     format: shouldFormat,
     stdout = false,
     dryRun = false,
-    silent = false
+    silent = false,
+    inferenceRules: inferenceRules2
   } = options;
+  const inputs = Array.isArray(input) ? input : [input];
+  const hasMultipleInputs = inputs.length > 1;
   const isSingle = generators.length === 1;
-  const content = await readEnvFile(input);
-  const parsed = parseEnvFileContent(content, input);
-  for (const generator of generators) {
-    let generated = buildOutput(generator, parsed);
-    if (shouldFormat) {
-      generated = await formatOutput(generated);
+  for (const inputPath of inputs) {
+    const outputBase = hasMultipleInputs ? deriveOutputBaseForInput(output, inputPath) : output;
+    const content = await readEnvFile(inputPath);
+    const parsed = parseEnvFileContent(
+      content,
+      inputPath,
+      inferenceRules2 !== void 0 ? { inferenceRules: inferenceRules2 } : void 0
+    );
+    for (const generator of generators) {
+      let generated = buildOutput(generator, parsed);
+      if (shouldFormat && !dryRun) {
+        generated = await formatOutput(generated);
+      }
+      const outputPath = deriveOutputPath(outputBase, generator, isSingle);
+      await persistOutput({
+        generated,
+        generator,
+        outputPath,
+        isSingle,
+        stdout,
+        dryRun,
+        silent
+      });
     }
-    const outputPath = deriveOutputPath(output, generator, isSingle);
-    await persistOutput({
-      generated,
-      generator,
-      outputPath,
-      isSingle,
-      stdout,
-      dryRun,
-      silent
-    });
   }
 }
 
 // src/watch.ts
+import path6 from "path";
 import { watch } from "chokidar";
-function startWatch({ inputPath, runOptions }) {
-  log(`Watching ${inputPath} for changes...`);
+function debounce(fn, delay) {
+  let timer;
+  return (...args) => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = void 0;
+      fn(...args);
+    }, delay);
+  };
+}
+function startWatch({ inputPath, runOptions, cwd = process.cwd() }) {
+  const inputLabel = Array.isArray(inputPath) ? inputPath.join(", ") : inputPath;
+  log(`Watching ${inputLabel} for changes...`);
   void runGenerate(runOptions).catch((err) => {
     const message = err instanceof Error ? err.message : JSON.stringify(err);
     error(message);
   });
-  const watcher = watch(inputPath, { persistent: true });
-  watcher.on("change", () => {
-    log(`${inputPath} changed, regenerating...`);
+  const handleChange = debounce((eventPath) => {
+    log(`${eventPath} changed, regenerating...`);
     void runGenerate(runOptions).catch((err) => {
       const message = err instanceof Error ? err.message : JSON.stringify(err);
       error(message);
     });
-  });
+  }, 200);
+  const handleConfigChange = debounce(async (eventPath) => {
+    log(`Config file ${eventPath} changed, reloading...`);
+    try {
+      const reloaded = await loadConfig(cwd);
+      if (reloaded) {
+        runOptions.generators = reloaded.generators ?? runOptions.generators;
+        runOptions.format = reloaded.format ?? runOptions.format;
+        if (reloaded.inferenceRules !== void 0) {
+          runOptions.inferenceRules = reloaded.inferenceRules;
+        }
+      }
+      void runGenerate(runOptions).catch((err) => {
+        const message = err instanceof Error ? err.message : JSON.stringify(err);
+        error(message);
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : JSON.stringify(err);
+      error(`Failed to reload config: ${message}`);
+    }
+  }, 200);
+  const inputWatcher = watch(inputPath, { persistent: true });
+  for (const event of ["add", "change", "unlink"]) {
+    inputWatcher.on(event, handleChange);
+  }
+  const configPaths = CONFIG_FILE_NAMES.map((name) => path6.resolve(cwd, name));
+  const configWatcher = watch(configPaths, { persistent: true, ignoreInitial: true });
+  for (const event of ["add", "change"]) {
+    configWatcher.on(event, (eventPath) => void handleConfigChange(eventPath));
+  }
   process.on("SIGINT", () => {
-    void watcher.close().then(() => {
+    void Promise.all([inputWatcher.close(), configWatcher.close()]).then(() => {
       log("Watcher stopped.");
       process.exit(0);
     });
@@ -645,7 +716,8 @@ function startWatch({ inputPath, runOptions }) {
 }
 
 // src/cli.ts
-var VERSION = "0.1.0";
+var _require = createRequire(import.meta.url);
+var VERSION = _require("../package.json").version;
 var HELP_TEXT = [
   "env-typegen \u2014 Generate TypeScript types from .env.example",
   "",
@@ -653,7 +725,7 @@ var HELP_TEXT = [
   "  env-typegen -i <path> [options]",
   "",
   "Options:",
-  "  -i, --input <path>         Path to .env.example file",
+  "  -i, --input <path>         Path to .env.example file(s). May be specified multiple times.",
   "  -o, --output <path>        Output file path (default: env.generated.ts)",
   "  -f, --format <name>        Generator format: ts|zod|t3|declaration",
   "                             May be specified multiple times.",
@@ -684,11 +756,16 @@ function getErrorMessage(errorValue) {
   return inspect(errorValue, { depth: 2 });
 }
 function resolveConfigRelative(value, configDir) {
-  if (value === void 0 || path6.isAbsolute(value)) return value;
-  return path6.resolve(configDir, value);
+  if (value === void 0 || path7.isAbsolute(value)) return value;
+  return path7.resolve(configDir, value);
 }
 function applyConfigPaths(config, configDir) {
-  const input = resolveConfigRelative(config.input, configDir);
+  let input;
+  if (Array.isArray(config.input)) {
+    input = config.input.map((v) => resolveConfigRelative(v, configDir) ?? v);
+  } else {
+    input = resolveConfigRelative(config.input, configDir);
+  }
   const output = resolveConfigRelative(config.output, configDir);
   return {
     ...config,
@@ -700,7 +777,7 @@ async function runCli(argv = process.argv.slice(2)) {
   const { values } = parseArgs({
     args: argv,
     options: {
-      input: { type: "string", short: "i" },
+      input: { type: "string", short: "i", multiple: true },
       output: { type: "string", short: "o" },
       generator: { type: "string", short: "g", multiple: true },
       format: { type: "string", short: "f", multiple: true },
@@ -726,15 +803,16 @@ async function runCli(argv = process.argv.slice(2)) {
   if (values.config === void 0) {
     fileConfig = await loadConfig(process.cwd());
   } else {
-    const configPath = path6.resolve(values.config);
-    const configDir = path6.dirname(configPath);
+    const configPath = path7.resolve(values.config);
+    const configDir = path7.dirname(configPath);
     const mod = await import(pathToFileURL2(configPath).href);
     const rawConfig = mod.default;
     if (rawConfig) {
       fileConfig = applyConfigPaths(rawConfig, configDir);
     }
   }
-  const input = values.input ?? fileConfig?.input;
+  const cliInput = values.input?.length ? values.input : void 0;
+  const input = cliInput ?? fileConfig?.input;
   if (input === void 0) {
     error("No input file specified. Use -i <path> or set input in env-typegen.config.ts");
     process.exit(1);
@@ -753,7 +831,7 @@ async function runCli(argv = process.argv.slice(2)) {
     }
     generators = [...new Set(normalizedGenerators)];
   } else {
-    generators = fileConfig?.generators ?? ["typescript"];
+    generators = fileConfig?.generators ?? ["typescript", "zod", "t3", "declaration"];
   }
   const shouldFormat = values["no-format"] === true ? false : fileConfig?.format ?? true;
   const useStdout = values.stdout ?? false;
@@ -767,7 +845,8 @@ async function runCli(argv = process.argv.slice(2)) {
     format: shouldFormat,
     stdout: useStdout,
     dryRun: isDryRun,
-    silent: isSilent
+    silent: isSilent,
+    ...fileConfig?.inferenceRules !== void 0 && { inferenceRules: fileConfig.inferenceRules }
   };
   if (shouldWatch) {
     startWatch({ inputPath: input, runOptions: options });
@@ -777,7 +856,7 @@ async function runCli(argv = process.argv.slice(2)) {
 }
 if (process.argv[1] !== void 0 && (() => {
   try {
-    return realpathSync(path6.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url));
+    return realpathSync(path7.resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url));
   } catch {
     return false;
   }