@xlameiro/env-typegen 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -43,6 +43,21 @@ type ParsedEnvVar = {
      */
     isSecret?: boolean;
 };
+/**
+ * A non-fatal issue detected during parsing (e.g. a duplicate key).
+ * Collected in {@link ParsedEnvFile.warnings} when the parser encounters
+ * degenerate-but-valid input.
+ */
+type ParsedEnvWarning = {
+    /** Machine-readable code for programmatic handling. */
+    code: "ENV_DUPLICATE_KEY";
+    /** Human-readable description of the issue. */
+    message: string;
+    /** 1-based line number of the earlier (discarded) occurrence. */
+    line: number;
+    /** The duplicated variable name. */
+    key: string;
+};
 /**
  * The complete result of parsing a single .env.example file.
  * Passed to generators to produce TypeScript / Zod / t3-env output.
@@ -54,6 +69,11 @@ type ParsedEnvFile = {
     vars: ParsedEnvVar[];
     /** Unique group names found in the file, in order of appearance */
     groups: string[];
+    /**
+     * Non-fatal issues detected during parsing (e.g. duplicate keys).
+     * Undefined when no issues were found so the field is omitted in clean parses.
+     */
+    warnings?: ParsedEnvWarning[];
 };
 
 /**
@@ -461,9 +481,12 @@ type EnvContract$1 = {
 
 /**
  * Contract file names searched in order when calling {@link loadContract}.
- * Mirrors the search strategy used by `loadConfig` in `config.ts`.
+ * BUG-01: .mjs and .js are searched before .ts — TypeScript files cannot be
+ * loaded by Node.js import() at runtime without a loader like tsx or ts-node.
+ * Discovering a .mjs file first prevents a confusing ERR_UNKNOWN_FILE_EXTENSION
+ * failure when both .ts and .mjs files coexist in the same directory.
  */
-declare const CONTRACT_FILE_NAMES: readonly ["env.contract.ts", "env.contract.mjs", "env.contract.js"];
+declare const CONTRACT_FILE_NAMES: readonly ["env.contract.mjs", "env.contract.js", "env.contract.ts"];
 /**
  * Type-safe contract factory. Returns the contract object unchanged — exists
  * purely for IDE autocompletion and compile-time validation of the contract shape.

package/dist/index.d.ts

@@ -43,6 +43,21 @@ type ParsedEnvVar = {
      */
     isSecret?: boolean;
 };
+/**
+ * A non-fatal issue detected during parsing (e.g. a duplicate key).
+ * Collected in {@link ParsedEnvFile.warnings} when the parser encounters
+ * degenerate-but-valid input.
+ */
+type ParsedEnvWarning = {
+    /** Machine-readable code for programmatic handling. */
+    code: "ENV_DUPLICATE_KEY";
+    /** Human-readable description of the issue. */
+    message: string;
+    /** 1-based line number of the earlier (discarded) occurrence. */
+    line: number;
+    /** The duplicated variable name. */
+    key: string;
+};
 /**
  * The complete result of parsing a single .env.example file.
  * Passed to generators to produce TypeScript / Zod / t3-env output.
@@ -54,6 +69,11 @@ type ParsedEnvFile = {
     vars: ParsedEnvVar[];
     /** Unique group names found in the file, in order of appearance */
     groups: string[];
+    /**
+     * Non-fatal issues detected during parsing (e.g. duplicate keys).
+     * Undefined when no issues were found so the field is omitted in clean parses.
+     */
+    warnings?: ParsedEnvWarning[];
 };
 
 /**
@@ -461,9 +481,12 @@ type EnvContract$1 = {
 
 /**
  * Contract file names searched in order when calling {@link loadContract}.
- * Mirrors the search strategy used by `loadConfig` in `config.ts`.
+ * BUG-01: .mjs and .js are searched before .ts — TypeScript files cannot be
+ * loaded by Node.js import() at runtime without a loader like tsx or ts-node.
+ * Discovering a .mjs file first prevents a confusing ERR_UNKNOWN_FILE_EXTENSION
+ * failure when both .ts and .mjs files coexist in the same directory.
  */
-declare const CONTRACT_FILE_NAMES: readonly ["env.contract.ts", "env.contract.mjs", "env.contract.js"];
+declare const CONTRACT_FILE_NAMES: readonly ["env.contract.mjs", "env.contract.js", "env.contract.ts"];
 /**
  * Type-safe contract factory. Returns the contract object unchanged — exists
  * purely for IDE autocompletion and compile-time validation of the contract shape.

package/dist/index.js

@@ -157,7 +157,9 @@ var inferenceRules = [
   {
     id: "P10_url_scheme",
     priority: 10,
-    match: (_key, value) => /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(value),
+    // BUG-02: comma-separated URL lists (e.g. ALLOWED_ORIGINS) must NOT be inferred as
+    // a single URL — they don't pass z.string().url() or new URL() validation at runtime.
+    match: (_key, value) => !value.includes(",") && /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(value),
     type: "url"
   },
   {
@@ -243,6 +245,27 @@ function buildParsedVar(params, commentBlock, options) {
   }
   return parsedVar;
 }
+function deduplicateVars(vars) {
+  const seenKeys = /* @__PURE__ */ new Set();
+  const deduped = [];
+  const warnings = [];
+  for (let i = vars.length - 1; i >= 0; i--) {
+    const variable = vars[i];
+    if (variable === void 0) continue;
+    if (seenKeys.has(variable.key)) {
+      warnings.push({
+        code: "ENV_DUPLICATE_KEY",
+        message: `Duplicate key "${variable.key}" at line ${variable.lineNumber} \u2014 last occurrence wins.`,
+        line: variable.lineNumber,
+        key: variable.key
+      });
+    } else {
+      seenKeys.add(variable.key);
+      deduped.unshift(variable);
+    }
+  }
+  return { deduped, warnings };
+}
 function parseEnvFileContent(content, filePath, options) {
   const lines = content.split("\n");
   const vars = [];
@@ -285,7 +308,13 @@ function parseEnvFileContent(content, filePath, options) {
     );
     commentBlock = [];
   }
-  return { filePath, vars, groups };
+  const { deduped, warnings } = deduplicateVars(vars);
+  return {
+    filePath,
+    vars: deduped,
+    groups,
+    ...warnings.length > 0 && { warnings }
+  };
 }
 function parseEnvFile(filePath) {
   const content = readFileSync(filePath, "utf8");
@@ -486,9 +515,9 @@ function generateT3Env(parsed) {
   return lines.join("\n") + "\n";
 }
 var CONTRACT_FILE_NAMES = [
-  "env.contract.ts",
   "env.contract.mjs",
-  "env.contract.js"
+  "env.contract.js",
+  "env.contract.ts"
 ];
 function defineContract(contract) {
   return contract;
@@ -497,6 +526,12 @@ async function loadContract(cwd = process.cwd()) {
   for (const name of CONTRACT_FILE_NAMES) {
     const filePath = path6.resolve(cwd, name);
     if (existsSync(filePath)) {
+      if (filePath.endsWith(".ts")) {
+        throw new Error(
+          `Contract file ${filePath} is a TypeScript file and cannot be loaded at runtime by Node.js.
+Rename it to ${filePath.replace(/\.ts$/, ".mjs")} and use ESM syntax (export default ...), or run via \`tsx\` / \`ts-node\` as a loader.`
+        );
+      }
       const fileUrl = pathToFileURL(filePath).href;
       const mod = await import(fileUrl);
       return mod.default;
@@ -542,7 +577,8 @@ async function readEnvFile(filePath) {
     return await readFile(resolved, "utf8");
   } catch (err) {
     if (err instanceof Error && err.code === "ENOENT") {
-      throw new Error(`File not found: ${filePath}`);
+      const displayPath = path6.isAbsolute(filePath) ? filePath : `${filePath} (resolved: ${resolved})`;
+      throw new Error(`File not found: ${displayPath}`);
     }
     throw err;
   }
@@ -579,7 +615,14 @@ function success(message) {
 
 // src/pipeline.ts
 function deriveOutputPath(base, generator, isSingle) {
-  if (isSingle) return base;
+  if (isSingle) {
+    if (generator === "declaration" && !base.endsWith(".d.ts")) {
+      const ext2 = path6.extname(base);
+      const noExt2 = ext2.length > 0 ? base.slice(0, -ext2.length) : base;
+      return `${noExt2}.d.ts`;
+    }
+    return base;
+  }
   const ext = path6.extname(base);
   const noExt = ext.length > 0 ? base.slice(0, -ext.length) : base;
   const baseExt = ext.length > 0 ? ext : ".ts";
@@ -589,7 +632,8 @@ function deriveOutputPath(base, generator, isSingle) {
 function deriveOutputBaseForInput(output, inputPath) {
   const dir = path6.dirname(output);
   const ext = path6.extname(output);
-  const stem = path6.basename(inputPath, path6.extname(inputPath));
+  const rawBasename = path6.basename(inputPath);
+  const stem = rawBasename.startsWith(".") ? rawBasename.slice(1).replaceAll(".", "-") : path6.basename(inputPath, path6.extname(inputPath));
   return path6.join(dir, `${stem}${ext}`);
 }
 function buildOutput(generator, parsed) {
@@ -626,6 +670,12 @@ async function persistOutput(params) {
     success(`Generated ${outputPath}`);
   }
 }
+function emitParserWarnings(parsed) {
+  if (parsed.warnings === void 0) return;
+  for (const w of parsed.warnings) {
+    warn(`[${w.code}] ${w.message}`);
+  }
+}
 async function runGenerate(options) {
   const {
     input,
@@ -648,6 +698,7 @@ async function runGenerate(options) {
       inputPath,
       inferenceRules2 === void 0 ? void 0 : { inferenceRules: inferenceRules2 }
     );
+    emitParserWarnings(parsed);
     for (const generator of generators) {
       let generated = buildOutput(generator, parsed);
       if (shouldFormat && !dryRun) {
@@ -724,7 +775,8 @@ function checkInvalidType(variable, entry, environment) {
       break;
     }
     case "boolean": {
-      if (value !== "true" && value !== "false") {
+      const lower = value.toLowerCase();
+      if (!["true", "false", "1", "0", "yes", "no"].includes(lower)) {
         return {
           code: "ENV_INVALID_TYPE",
           key: variable.key,
@@ -847,7 +899,8 @@ function validateContract(parsed, contract, opts = {}) {
   const parsedByKey = new Map(parsed.vars.map((v) => [v.key, v]));
   for (const entry of contract.vars) {
     if (!entry.required) continue;
-    if (parsedByKey.has(entry.name)) continue;
+    const existing = parsedByKey.get(entry.name);
+    if (existing !== void 0 && existing.rawValue !== "") continue;
     issues.push({
       code: "ENV_MISSING",
       key: entry.name,
@@ -949,6 +1002,11 @@ function outputHuman(result) {
 async function runCheck(opts) {
   const contract = await resolveContract(opts.contract, opts.cwd);
   const parsed = parseEnvFile(opts.input);
+  if (parsed.warnings !== void 0) {
+    for (const w of parsed.warnings) {
+      warn(`[${w.code}] ${w.message}`);
+    }
+  }
   const validatorOpts = {};
   if (opts.environment !== void 0) validatorOpts.environment = opts.environment;
   if (opts.strict !== void 0) validatorOpts.strict = opts.strict;
@@ -1033,7 +1091,8 @@ async function loadCloudSource(options) {
     raw = await readFile(resolvedPath, "utf8");
   } catch (err) {
     if (err instanceof Error && err.code === "ENOENT") {
-      throw new Error(`File not found: ${options.filePath}`);
+      const displayPath = path6.isAbsolute(options.filePath) ? options.filePath : `${options.filePath} (resolved: ${resolvedPath})`;
+      throw new Error(`File not found: ${displayPath}`);
     }
     throw err;
   }
@@ -1041,7 +1100,7 @@ async function loadCloudSource(options) {
   return parseProviderPayload(options.provider, parsed);
 }
 var SECRET_KEY_RE = /(SECRET|TOKEN|PASSWORD|PRIVATE|API_KEY|ACCESS_KEY|CLIENT_SECRET)/i;
-var CONTRACT_FILE_NAMES2 = ["env.contract.ts", "env.contract.mjs", "env.contract.js"];
+var CONTRACT_FILE_NAMES2 = ["env.contract.mjs", "env.contract.js", "env.contract.ts"];
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1165,6 +1224,12 @@ async function loadValidationContract(options) {
   const discoveredContractPath = findDefaultContractPath(cwd);
   const resolvedContractPath = contractPath === void 0 ? discoveredContractPath : path6.resolve(cwd, contractPath);
   if (resolvedContractPath !== void 0 && existsSync(resolvedContractPath)) {
+    if (resolvedContractPath.endsWith(".ts")) {
+      throw new Error(
+        `Contract file ${resolvedContractPath} is a TypeScript file and cannot be loaded at runtime by Node.js.
+Rename it to ${resolvedContractPath.replace(/\.ts$/, ".mjs")} and use ESM syntax (export default ...), or run via \`tsx\` / \`ts-node\` as a loader.`
+      );
+    }
     const moduleUrl = pathToFileURL(resolvedContractPath).href;
     const moduleValue = await import(moduleUrl);
     const candidate = moduleValue.default ?? moduleValue.contract;
@@ -1418,7 +1483,7 @@ function isClientSecret(variable, key) {
 function checkContractVariable(key, variable, context) {
   const { options, issues } = context;
   const value = options.values[key];
-  const hasValue = value !== void 0;
+  const hasValue = value !== void 0 && (value !== "" || !variable.required);
   if (variable.required && !hasValue) {
     issues.push(
       createIssue({
@@ -1520,7 +1585,11 @@ function diffTypeConflicts(key, present, context) {
   for (const entry of present) {
     typeBySource.set(entry.sourceName, detectReceivedType(entry.value ?? ""));
   }
-  if (new Set(typeBySource.values()).size <= 1) return;
+  const knownTypes = /* @__PURE__ */ new Set();
+  for (const t of typeBySource.values()) {
+    if (t !== "unknown") knownTypes.add(t);
+  }
+  if (knownTypes.size <= 1) return;
   for (const [sourceName, detectedType] of typeBySource.entries()) {
     issues.push(
       createIssue({
@@ -1687,6 +1756,7 @@ async function loadEnvSource(options) {
     return parseEnvSourceContent(content);
   } catch (error_) {
     if (options.allowMissing === true && error_ instanceof Error && "code" in error_ && error_.code === "ENOENT") {
+      warn(`Target file not found: ${options.filePath} \u2014 treating as empty`);
       return {};
     }
     throw error_;
@@ -1854,7 +1924,8 @@ async function loadCommandConfig(configPath) {
   }
   const resolvedPath = path6.resolve(configPath);
   if (!existsSync(resolvedPath)) {
-    throw new Error(`Config file not found: ${configPath}`);
+    const displayPath = path6.isAbsolute(configPath) ? configPath : `${configPath} (resolved: ${resolvedPath})`;
+    throw new Error(`Config file not found: ${displayPath}`);
   }
   const configDir = path6.dirname(resolvedPath);
   const moduleValue = await import(pathToFileURL(resolvedPath).href);