celery-env 0.1.3 → 0.1.5

package/README.md

@@ -171,7 +171,7 @@ competitors were checked with `npm view` on 2026-06-25.
 
 | Package | Version checked | Runtime deps | Unpacked npm size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
+| `celery-env` | 0.1.4 | 0 | 119.2 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |

package/docs/BENCHMARKS.md

@@ -73,7 +73,7 @@ Package footprint is separate from runtime speed. Celery is this branch's
 
 | Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
+| `celery-env` | 0.1.4 | 0 | 119.2 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |

package/docs/CLI.md

@@ -26,9 +26,9 @@ npx celery-env infer --schema env.schema.mjs
 ```
 
 Use `infer` when a project already has `.env` files or source code that reads
-env vars. It discovers `.env.example`, `.env`, `.env.local`, and common source
-directories by default. It writes a starter schema and refuses overwrite unless
-you pass `--force`.
+env vars. It discovers `.env.example`, `.env`, `.env.local`, common source
+directories, common config files, `scripts`, and `prisma` by default. It writes
+a starter schema and refuses overwrite unless you pass `--force`.
 
 You can pass sources explicitly:
 
@@ -39,11 +39,17 @@ npx celery-env infer \
   --scan src
 ```
 
-Inference is conservative. Ambiguous values become `str({ min: 1 })`. Only
-example, sample, or template env files can emit `example` metadata; local env
-values and secret-looking values are not copied into the generated schema.
+Inference is conservative starter-schema generation, not a replacement for
+review. Ambiguous values become `str({ min: 1 })`. Safe example values can
+infer enums and string-list item enums. A few common source defaults are also
+detected, such as `process.env.PORT ?? "3000"`, `Number(process.env.X ?? 60)`,
+and `process.env.DEBUG !== "false"`.
+
+Only example, sample, or template env files can emit `example` metadata. Local
+env values and secret-looking values are not copied into the generated schema.
 Review the result for project-specific constraints such as `requiredWhen`,
-`min`, `max`, or stricter URL protocols.
+optional values, conditional requirements, `min`, `max`, or stricter URL
+protocols.
 
 ## Generate
 

package/docs/COMPARISON.md

@@ -94,7 +94,7 @@ This table is package metadata, not benchmark speed. Celery is this branch's
 
 | Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
 | --- | ---: | ---: | ---: | ---: |
-| `celery-env` | 0.1.2 + infer | 0 | 117.7 kB | 26 |
+| `celery-env` | 0.1.4 | 0 | 119.2 kB | 26 |
 | `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
 | `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
 | `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "celery-env",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Type-safe process.env validation that generates zero-dependency standalone validators.",
   "type": "module",
   "types": "./src/index.d.ts",

package/src/cli.js

@@ -64,9 +64,14 @@ async function init(args) {
 async function infer(args) {
   if (!args.schema) usage(1);
   const schemaPath = resolve(args.schema);
-  const { inferSchemaSource } = await import("./infer.js");
+  const { inferSchema } = await import("./infer.js");
   await mkdir(dirname(schemaPath), { recursive: true });
-  await writeOutput(schemaPath, await inferSchemaSource({ envFiles: args.envFiles, scanPaths: args.scanPaths }), args.force);
+  const result = await inferSchema({ envFiles: args.envFiles, scanPaths: args.scanPaths });
+  await writeOutput(schemaPath, result.source, args.force);
+  console.log(`Wrote ${schemaPath}
+Scanned ${result.envFileCount} env file(s) and ${result.sourceFileCount} source file(s).
+Found ${result.keyCount} environment variable(s).
+Next: review the schema, then run celery-env generate --schema ${schemaPath} --out src/env.mjs --types src/env.d.ts`);
 }
 
 function parseArgs(argv) {

package/src/infer.js

@@ -6,10 +6,20 @@ const JS_IDENT = /^[$A-Z_a-z][$\w]*$/;
 const SOURCE_EXTENSIONS = new Set([".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".svelte", ".ts", ".tsx", ".vue"]);
 const SKIP_DIRS = new Set([".git", ".next", ".nuxt", ".output", ".tmp", "build", "coverage", "dist", "node_modules"]);
 const DEFAULT_ENV_FILES = [".env.example", ".env", ".env.local"];
-const DEFAULT_SCAN_PATHS = ["src", "app", "pages", "lib", "server"];
-const BOOL_VALUES = new Set(["true", "yes", "on", "false", "no", "off"]);
+const DEFAULT_SCAN_PATHS = ["src", "app", "pages", "lib", "server", "scripts", "prisma", ...["next", "vite", "astro"].flatMap((name) => configNames(name)), ...["server", "index"].flatMap((name) => configNames(name, ""))];
+const BOOL_VALUE = /^(?:true|yes|on|false|no|off)$/;
+const BOOLISH_KEY = /^(?:DEBUG|VERBOSE|(?:ENABLE|DISABLE|ENABLED|DISABLED|IS|HAS|USE|ALLOW|REGISTER)_.*|.*_(?:ENABLED|DISABLED|FLAG|FLAGS|ACTIVE))$/;
 const SECRET_KEY = /(?:SECRET|TOKEN|PASSWORD|PASS|PRIVATE|CREDENTIAL|AUTH|API_KEY|ACCESS_KEY)/i;
 const SECRET_VALUE = /(?:^sk_|^pk_|^gh[pousr]_|^xox[baprs]-|^eyJ|-----BEGIN |:\/\/[^/\s:@]+:[^/\s:@]+@|[A-Za-z0-9+/=_-]{32,})/;
+const ENUM_VALUE = /^[A-Za-z][A-Za-z0-9_.:-]{0,31}$/;
+const LOG_LEVELS = ["trace", "debug", "info", "warn", "error", "fatal"];
+const NAMED_ENUMS = {
+  COMMAND_SCOPE: ["global", "guild"],
+  LOGGER_LEVEL: LOG_LEVELS,
+  LOG_LEVEL: LOG_LEVELS,
+  NODE_ENV: ["development", "test", "production"],
+  VERCEL_ENV: ["development", "preview", "production"]
+};
 const MAX_ENV_FILE_BYTES = 256 * 1024;
 const MAX_SOURCE_FILE_BYTES = 1024 * 1024;
 const MAX_SOURCE_FILES = 2000;
@@ -17,6 +27,10 @@ const MAX_SOURCE_BYTES = 8 * 1024 * 1024;
 const MAX_SCAN_DEPTH = 32;
 
 export async function inferSchemaSource(options = {}) {
+  return (await inferSchema(options)).source;
+}
+
+export async function inferSchema(options = {}) {
   const cwd = resolve(options.cwd || process.cwd());
   const explicitEnvFiles = options.envFiles?.length;
   const explicitScanPaths = options.scanPaths?.length;
@@ -32,10 +46,11 @@ export async function inferSchemaSource(options = {}) {
     }
   }
 
-  for (const file of await sourceFiles(scanPaths, { rejectRootSymlinks: Boolean(explicitScanPaths) })) {
+  const scannedSources = await sourceFiles(scanPaths, { rejectRootSymlinks: Boolean(explicitScanPaths) });
+  for (const file of scannedSources) {
     const source = await readFile(file, "utf8");
-    for (const key of scanEnvKeys(source)) {
-      record(entries, key, { codeOnly: true });
+    for (const hint of scanEnvHints(source)) {
+      record(entries, hint.key, { defaults: hint.defaults });
     }
   }
 
@@ -43,7 +58,12 @@ export async function inferSchemaSource(options = {}) {
     throw new Error("No environment variables found; pass --env or --scan");
   }
 
-  return generateSchemaModule(entries);
+  return {
+    source: generateSchemaModule(entries),
+    envFileCount: envFiles.length,
+    sourceFileCount: scannedSources.length,
+    keyCount: entries.size
+  };
 }
 
 export function parseEnvSource(source) {
@@ -56,20 +76,33 @@ export function parseEnvSource(source) {
 }
 
 export function scanEnvKeys(source) {
-  const keys = new Set();
-  collectMatches(keys, source, /\bprocess\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1);
-  collectMatches(keys, source, /\bimport\.meta\.env\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1);
-  collectMatches(keys, source, /\bprocess\.env\[\s*(["'`])([A-Za-z_][A-Za-z0-9_]*)\1\s*\]/g, 2);
-  collectMatches(keys, source, /\bimport\.meta\.env\[\s*(["'`])([A-Za-z_][A-Za-z0-9_]*)\1\s*\]/g, 2);
-
-  for (const match of source.matchAll(/\{([^}]+)\}\s*=\s*process\.env\b/g)) {
-    for (const key of destructuredKeys(match[1])) keys.add(key);
+  return scanEnvHints(source).map((hint) => hint.key);
+}
+
+function scanEnvHints(source) {
+  const hints = new Map();
+  collectMatches(hints, source, /\b(?:process\.env|import\.meta\.env)\.([A-Za-z_][A-Za-z0-9_]*)\b/g, 1);
+  collectMatches(hints, source, /\b(?:process\.env|import\.meta\.env)\[\s*(["'`])([A-Za-z_][A-Za-z0-9_]*)\1\s*\]/g, 2);
+
+  for (const match of source.matchAll(/\{([^}]+)\}\s*=\s*(?:process\.env|import\.meta\.env)\b/g)) {
+    for (const key of destructuredKeys(match[1])) addHint(hints, key);
   }
-  for (const match of source.matchAll(/\{([^}]+)\}\s*=\s*import\.meta\.env\b/g)) {
-    for (const key of destructuredKeys(match[1])) keys.add(key);
+
+  const ref = String.raw`\b(?:process\.env|import\.meta\.env)\.([A-Za-z_][A-Za-z0-9_]*)\s*`;
+  for (const match of source.matchAll(new RegExp(`${ref}\\?\\?\\s*(["'\`])([^"'\`\\\\]*(?:\\\\.[^"'\`\\\\]*)*)\\2`, "g"))) {
+    addHint(hints, match[1], unescapeQuoted(match[3]));
+  }
+  for (const match of source.matchAll(new RegExp(`${ref}\\?\\?\\s*([+-]?(?:\\d+\\.\\d*|\\.\\d+|\\d+)|true|false)`, "g"))) {
+    addHint(hints, match[1], match[2]);
+  }
+  for (const match of source.matchAll(new RegExp(`${ref}!==\\s*(["'])(?:false|0)\\2`, "g"))) {
+    addHint(hints, match[1], "true");
+  }
+  for (const match of source.matchAll(new RegExp(`${ref}===\\s*(["'])(?:true|1)\\2`, "g"))) {
+    addHint(hints, match[1], "false");
   }
 
-  return [...keys].sort();
+  return [...hints.values()].sort((a, b) => a.key.localeCompare(b.key));
 }
 
 function parseEnvLine(line) {
@@ -126,8 +159,19 @@ function stripInlineComment(value) {
   return value;
 }
 
-function collectMatches(keys, source, pattern, group) {
-  for (const match of source.matchAll(pattern)) keys.add(match[group]);
+function collectMatches(hints, source, pattern, group) {
+  for (const match of source.matchAll(pattern)) addHint(hints, match[group]);
+}
+
+function addHint(hints, key, defaultValue) {
+  if (!ENV_NAME.test(key)) return;
+  const hint = hints.get(key) || { key, defaults: [] };
+  if (defaultValue !== undefined) hint.defaults.push(defaultValue);
+  hints.set(key, hint);
+}
+
+function configNames(name, infix = ".config") {
+  return ["js", "mjs", "ts"].map((ext) => `${name}${infix}.${ext}`);
 }
 
 function destructuredKeys(source) {
@@ -223,11 +267,11 @@ async function collectSourceFiles(out, path, state, depth, rejectSymlink) {
 function record(entries, key, source) {
   let entry = entries.get(key);
   if (!entry) {
-    entry = { key, values: [], code: false };
+    entry = { key, values: [], defaults: [] };
     entries.set(key, entry);
   }
-  if (source.codeOnly) entry.code = true;
-  else entry.values.push({ value: source.value, safeExamples: source.safeExamples });
+  if (source.defaults) entry.defaults.push(...source.defaults.filter((value) => !unsafe(key, value)));
+  if (source.value !== undefined) entry.values.push({ value: source.value, safeExamples: source.safeExamples });
 }
 
 function generateSchemaModule(entries) {
@@ -252,38 +296,44 @@ function generateSchemaModule(entries) {
 }
 
 function inferRule(entry) {
-  if (entry.key === "NODE_ENV") {
-    return { kind: "oneOf", values: ["development", "test", "production"], options: { default: "development" } };
-  }
+  const samples = entry.values.filter((item) => item.value !== "");
+  const defaults = cleanDefaults(entry);
+  const knownEnum = namedEnumRule(entry, samples, defaults);
+  if (knownEnum) return withExample(entry, withDefault(defaults, knownEnum));
 
-  const samples = entry.values.map((item) => item.value).filter((value) => value !== "");
-  if (!samples.length) return { kind: "str", options: { min: 1 } };
+  const observations = samples.concat(defaults.map((value) => ({ value, safeExamples: false })));
+  if (!observations.length) return { kind: "str", options: { min: 1 } };
 
-  const kinds = samples.map(inferValue);
+  const enumRule = sampleEnumRule(entry, samples);
+  if (enumRule) return withExample(entry, withDefault(defaults, enumRule));
+
+  const kinds = observations.map((item) => inferValue(entry.key, item.value, enumSafe(entry, item)));
   if (kinds.some((kind) => kind.kind === "str")) return stringRule(entry);
 
   const first = kinds[0].kind;
   if (!kinds.every((kind) => kind.kind === first)) return stringRule(entry);
 
   const rule = mergeRules(first, kinds);
-  const example = safeExample(entry, rule);
-  if (example !== undefined) rule.options = { ...rule.options, example };
-  return rule;
+  return withExample(entry, withDefault(defaults, rule));
 }
 
-function inferValue(value) {
-  if (BOOL_VALUES.has(value)) return { kind: "bool" };
+function inferValue(key, value, allowEnum) {
+  if (isBoolValue(key, value)) return { kind: "bool" };
   if (strictInt(value)) return { kind: "int", options: { strict: true } };
   if (strictNumber(value)) return { kind: "num", options: { strict: true } };
   const jsonRule = inferJson(value);
   if (jsonRule) return jsonRule;
-  const listRule = inferList(value);
+  const listRule = inferList(key, value, allowEnum);
   if (listRule) return listRule;
   const urlRule = inferUrl(value);
   if (urlRule) return urlRule;
   return { kind: "str", options: { min: 1 } };
 }
 
+function isBoolValue(key, value) {
+  return BOOL_VALUE.test(value) || ((value === "1" || value === "0") && BOOLISH_KEY.test(key));
+}
+
 function inferJson(value) {
   if (!/^\s*[\[{]/.test(value)) return;
   try {
@@ -292,19 +342,23 @@ function inferJson(value) {
   } catch {}
 }
 
-function inferList(value) {
+function inferList(key, value, allowEnum) {
   if (!value.includes(",") || /^\s*[\[{]/.test(value)) return;
   const parts = value.split(",").map((part) => part.trim());
   if (parts.length < 2 || parts.some((part) => part === "")) return;
   const items = parts.map((part) => {
-    if (BOOL_VALUES.has(part)) return { kind: "bool" };
+    if (isBoolValue(key, part)) return { kind: "bool" };
     if (strictInt(part)) return { kind: "int", options: { strict: true } };
     if (strictNumber(part)) return { kind: "num", options: { strict: true } };
     const urlRule = inferUrl(part);
     return urlRule || { kind: "str" };
   });
   const first = items[0].kind;
-  if (first === "str" || !items.every((item) => item.kind === first)) return;
+  if (first === "str") {
+    const values = allowEnum && enumValues(parts);
+    return { kind: "list", item: values ? { kind: "oneOf", values } : { kind: "str", options: { min: 1 } } };
+  }
+  if (!items.every((item) => item.kind === first)) return;
   return { kind: "list", item: mergeRules(first, items) };
 }
 
@@ -334,25 +388,72 @@ function mergeRules(kind, rules) {
   }
   if (kind === "list") {
     const itemKind = rules[0].item.kind;
+    if (!rules.every((rule) => rule.item.kind === itemKind)) return { kind: "list", item: { kind: "str", options: { min: 1 } } };
     return { kind: "list", item: mergeRules(itemKind, rules.map((rule) => rule.item)) };
   }
+  if (kind === "oneOf") return { kind, values: enumValues(rules.flatMap((rule) => rule.values)) };
   if (kind === "int" || kind === "num") return { kind, options: { strict: true } };
+  if (kind === "str" && rules.some((rule) => rule.options)) return { kind, options: { min: 1 } };
   return { kind };
 }
 
 function stringRule(entry) {
   const rule = { kind: "str", options: { min: 1 } };
+  withDefault(cleanDefaults(entry), rule);
   const example = safeExample(entry, rule);
-  if (example !== undefined) rule.options.example = example;
+  if (example !== undefined && rule.options.default !== example) rule.options.example = example;
   return rule;
 }
 
 function safeExample(entry, rule) {
   const sample = entry.values.find((item) => item.safeExamples && item.value !== "");
-  if (!sample || SECRET_KEY.test(entry.key) || SECRET_VALUE.test(sample.value)) return;
+  if (!sample || unsafe(entry.key, sample.value)) return;
   return exampleValue(sample.value, rule);
 }
 
+function withExample(entry, rule) {
+  const example = safeExample(entry, rule);
+  if (example !== undefined && rule.options?.default !== example) rule.options = { ...rule.options, example };
+  return rule;
+}
+
+function enumSafe(entry, item) {
+  return item.safeExamples && !unsafe(entry.key, item.value);
+}
+
+function sampleEnumRule(entry, samples) {
+  const values = samples.every((item) => enumSafe(entry, item)) && enumValues(samples.map((item) => item.value));
+  if (values && values.length > 1 && values.length <= 8) return { kind: "oneOf", values };
+}
+
+function namedEnumRule(entry, samples, defaults) {
+  const values = NAMED_ENUMS[entry.key];
+  if (!values) return;
+  const seen = samples.map((item) => item.value).concat(defaults);
+  if (seen.some((value) => !values.includes(value))) return;
+  if (entry.key !== "NODE_ENV" && !seen.length) return;
+  const options = entry.key === "NODE_ENV" ? { default: "development" } : undefined;
+  return { kind: "oneOf", values, options };
+}
+
+function cleanDefaults(entry) {
+  const values = [...new Set(entry.defaults.filter(Boolean))];
+  return values[1] ? [] : values;
+}
+
+function withDefault(defaults, rule) {
+  if (!defaults.length) return rule;
+  const value = exampleValue(defaults[0], rule);
+  if (value === undefined) return rule;
+  if (rule.kind === "oneOf" && !rule.values.includes(defaults[0])) return rule;
+  rule.options = { ...rule.options, default: value };
+  return rule;
+}
+
+function unsafe(key, value) {
+  return SECRET_KEY.test(key) || SECRET_VALUE.test(value);
+}
+
 function exampleValue(value, rule) {
   if (rule.kind === "bool") return value === "true" || value === "1" || value === "yes" || value === "on";
   if (rule.kind === "int" || rule.kind === "num") return Number(value);
@@ -373,7 +474,7 @@ function collectRuleImports(imports, rule) {
 }
 
 function ruleSource(rule) {
-  if (rule.kind === "oneOf") return `oneOf(${literal(rule.values)}, ${literal(rule.options)})`;
+  if (rule.kind === "oneOf") return rule.options && Object.keys(rule.options).length ? `oneOf(${literal(rule.values)}, ${literal(rule.options)})` : `oneOf(${literal(rule.values)})`;
   if (rule.kind === "list") {
     const item = ruleSource(rule.item);
     return rule.options && Object.keys(rule.options).length ? `list(${item}, ${literal(rule.options)})` : `list(${item})`;
@@ -387,9 +488,16 @@ function schemaKey(key) {
 }
 
 function literal(value) {
+  if (Array.isArray(value)) return `[${value.map(literal).join(", ")}]`;
+  if (value && typeof value === "object") return `{ ${Object.entries(value).map(([key, item]) => `${schemaKey(key)}: ${literal(item)}`).join(", ")} }`;
   return JSON.stringify(value);
 }
 
+function enumValues(values) {
+  if (!values.every((value) => ENUM_VALUE.test(value))) return;
+  return [...new Set(values)].sort();
+}
+
 function importSort(a, b) {
   return a.localeCompare(b);
 }