@xlameiro/env-typegen 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/) and uses
+[Changesets](https://github.com/changesets/changesets) for release management.
+
+<!-- Releases are added automatically by `changeset version` -->
+
+## [0.1.0] — 2026-03-16
+
+### Added
+
+#### Foundation (Phase 1)
+
+- TypeScript 5 strict mode with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`
+- Dual CJS + ESM build via tsup with full type declarations (`dist/index.d.ts`)
+- Vitest test infrastructure with v8 coverage (thresholds: 85% lines, 80% branches)
+- ESLint v9 flat config with `@typescript-eslint/recommended`
+
+#### Parser (Phase 2)
+
+- `parseEnvFile(path)` — reads a `.env.example` file from disk and returns a structured `ParsedEnvFile`
+- `parseEnvFileContent(content)` — parses raw string content; useful in tests or pipelines
+- `parseCommentBlock(block)` — extracts JSDoc-style annotations (`@type`, `@description`, `@example`, `@optional`) from comment lines above env var assignments
+- `inferType(value)` — infers `EnvVarType` (`string` | `number` | `boolean` | `url` | `email`) from a raw env value
+
+#### Generators (Phases 3 & 4)
+
+- `generateTypeScriptTypes(parsed)` — produces a `type Env = { ... }` TypeScript declaration with inferred types
+- `generateEnvValidation(parsed)` — produces a runtime validation helper alongside the type
+- `generateZodSchema(parsed)` — produces a Zod v4 `z.object({ ... })` schema; numbers use `z.coerce.number()`, booleans `z.coerce.boolean()`
+- `generateT3Env(parsed)` — produces a `@t3-oss/env-nextjs` `createEnv(...)` call; splits vars into `server` and `client` (`NEXT_PUBLIC_*`) buckets automatically
+- `generateDeclaration(parsed)` — produces a `.d.ts` file that augments `NodeJS.ProcessEnv` with the parsed var names and types
+
+#### Config & Utils (Phase 5)
+
+- `defineConfig(config)` — type-safe config factory (identity function for editor inference)
+- `loadConfig(cwd)` — discovers and loads `env-typegen.config.ts` / `env-typegen.config.js` / `env-typegen.config.mjs` starting from a given directory
+- `readEnvFile(path)` / `writeOutput(path, content)` — file I/O utilities
+- `formatOutput(content)` — formats generated source with Prettier
+- `log()`, `error()`, `success()`, `warn()` — colourised logger helpers
+
+#### CLI (Phase 6)
+
+- `env-typegen` binary via `dist/cli.js`
+- Flags: `--input` / `-i`, `--output` / `-o`, `--generator` / `-g` (repeatable), `--format` / `-f`, `--watch` / `-w`, `--config` / `-c`, `--version` / `-v`, `--help` / `-h`
+- Multiple generators produce separate output files with the generator name inserted before the extension (e.g. `env.generated.typescript.ts`, `env.generated.zod.ts`)
+- Watch mode via chokidar v4 — regenerates on every file change; SIGINT-safe
+- `runGenerate(options)` — programmatic pipeline API; runs without a CLI process
+
+#### Quality & Docs (Phase 7)
+
+- 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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 env-typegen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# env-typegen
+
+> 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)
+[![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/)
+
+## What it does
+
+`env-typegen` reads `.env.example` files and automatically generates:
+
+- TypeScript types (`type Env = { 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`
+
+## Quick Start
+
+```bash
+# Generate TypeScript types (default)
+npx env-typegen --input .env.example --output src/env.generated.ts
+
+# Generate 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
+
+# Watch mode — regenerate on every change
+npx env-typegen -i .env.example -o src/env.ts --watch
+```
+
+## Programmatic API
+
+```ts
+import { runGenerate, parseEnvFile, generateTypeScriptTypes } from "env-typegen";
+
+// High-level: full pipeline
+await runGenerate({
+  input: ".env.example",
+  output: "src/env.generated.ts",
+  generators: ["typescript"],
+  format: true,
+});
+
+// Low-level: parse then generate individually
+const parsed = await parseEnvFile(".env.example");
+const ts = generateTypeScriptTypes(parsed);
+```
+
+## Configuration
+
+Create `env-typegen.config.ts` at your project root:
+
+```ts
+import { defineConfig } from "env-typegen";
+
+export default defineConfig({
+  input: ".env.example",
+  output: "src/env.generated.ts",
+  generators: ["typescript", "zod"],
+  format: true,
+});
+```
+
+## Status
+
+| Phase | Description    | Status |
+| ----- | -------------- | ------ |
+| 1     | Foundation     | ✅     |
+| 2     | Parser         | ✅     |
+| 3     | Inferrer       | ✅     |
+| 4     | Generators     | ✅     |
+| 5     | Config & Utils | ✅     |
+| 6     | CLI            | ✅     |
+| 7     | Quality & Docs | ✅     |
+| 8     | Publishing     | 🔜     |
+
+## License
+
+MIT