varlock 0.0.11 → 0.0.13

package/dist/{chunk-ZW2T4C6A.js → chunk-MV5ZAKN7.js}

@@ -2,10 +2,10 @@ import { redactString } from './chunk-FGMXIEFA.js';
 import { __commonJS, __name, __toESM } from './chunk-XN24GZXQ.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import fs2 from 'fs/promises';
-import path from 'path';
+import fs, { accessSync } from 'fs';
+import fs2, { access } from 'fs/promises';
+import path2 from 'path';
 import { ParsedEnvSpecStaticValue, ParsedEnvSpecFunctionCall, ParsedEnvSpecKeyValuePair, parseEnvSpecDotEnvFile } from '@env-spec/parser';
-import fs from 'fs';
 import process2 from 'process';
 
 // ../../node_modules/.pnpm/ansis@4.1.0/node_modules/ansis/index.cjs
@@ -780,7 +780,7 @@ function mapValues(obj, fn) {
 }
 __name(mapValues, "mapValues");
 function times(count, fn) {
-  return Array.from({ length: count }, (_4, i) => fn(i));
+  return Array.from({ length: count }, (_3, i) => fn(i));
 }
 __name(times, "times");
 function map(array, fn) {
@@ -791,6 +791,14 @@ function flatMap(array, fn) {
   return array.flatMap(fn);
 }
 __name(flatMap, "flatMap");
+function intersection(...arrays) {
+  return arrays.reduce((a2, b) => a2.filter((value) => b.includes(value)));
+}
+__name(intersection, "intersection");
+function pick(obj, keys) {
+  return Object.fromEntries(Object.entries(obj).filter(([key]) => keys.includes(key)));
+}
+__name(pick, "pick");
 var _ = {
   keyBy,
   sortBy,
@@ -805,6 +813,8 @@ var _ = {
   times,
   map,
   flatMap,
+  intersection,
+  pick,
   // type checks
   isString,
   isBoolean,
@@ -945,12 +955,29 @@ var EmptyRequiredValueError = class extends ValidationError {
     super("Value is required but is currently empty");
   }
 };
+
+// ../utils/src/try-catch.ts
+function isPromise2(obj) {
+  return !!obj && (typeof obj === "object" || typeof obj === "function") && typeof obj.then === "function";
+}
+__name(isPromise2, "isPromise");
+async function tryCatch(tryFn, catchFn) {
+  try {
+    return await tryFn();
+  } catch (err) {
+    const catchResult = catchFn(err);
+    if (isPromise2(catchResult)) {
+      await catchResult;
+    }
+  }
+}
+__name(tryCatch, "tryCatch");
 var asyncExec = promisify(exec);
 
 // ../utils/src/git-utils.ts
-async function checkIsFileGitIgnored(path5, warnIfNotGitRepo = false) {
+async function checkIsFileGitIgnored(path3, warnIfNotGitRepo = false) {
   try {
-    await asyncExec(`git check-ignore ${path5} -q`);
+    await asyncExec(`git check-ignore ${path3} -q`);
     return true;
   } catch (err) {
     const stderr = err.stderr;
@@ -967,23 +994,24 @@ async function checkIsFileGitIgnored(path5, warnIfNotGitRepo = false) {
   }
 }
 __name(checkIsFileGitIgnored, "checkIsFileGitIgnored");
-
-// ../utils/src/try-catch.ts
-function isPromise2(obj) {
-  return !!obj && (typeof obj === "object" || typeof obj === "function") && typeof obj.then === "function";
+async function pathExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
-__name(isPromise2, "isPromise");
-async function tryCatch(tryFn, catchFn) {
+__name(pathExists, "pathExists");
+function pathExistsSync(p) {
   try {
-    return await tryFn();
-  } catch (err) {
-    const catchResult = catchFn(err);
-    if (isPromise2(catchResult)) {
-      await catchResult;
-    }
+    accessSync(p);
+    return true;
+  } catch {
+    return false;
   }
 }
-__name(tryCatch, "tryCatch");
+__name(pathExistsSync, "pathExistsSync");
 
 // env-graph/lib/data-types.ts
 var EnvGraphDataType = class {
@@ -1780,7 +1808,8 @@ async function getTsDefinitionForItem(item, indentLevel = 0) {
       }
     }
   }
-  itemSrc.push(`readonly ${item.key}${item.isRequired ? "" : "?"}: ${itemTsType};`);
+  const isRequired = item.isRequired && !item.isRequiredDynamic;
+  itemSrc.push(`readonly ${item.key}${isRequired ? "" : "?"}: ${itemTsType};`);
   itemSrc.push("");
   return my_dash_default.map(itemSrc, (line) => `${i}${line}`);
 }
@@ -1832,16 +1861,16 @@ export type EnvSchemaAsStrings = {
   return tsSrc.join("\n");
 }
 __name(generateTsTypesSrc, "generateTsTypesSrc");
-async function generateTypes(graph, lang, outputPath) {
+async function generateTypes(graph, lang, typesPath) {
   if (lang !== "ts") throw new Error(`Unsupported @generateTypes lang: ${lang}`);
   const tsSrc = await generateTsTypesSrc(graph);
-  if (!graph.basePath) return;
-  const typesPath = path.join(graph.basePath, outputPath);
   await fs.promises.writeFile(typesPath, tsSrc, "utf-8");
 }
 __name(generateTypes, "generateTypes");
 
 // env-graph/lib/env-graph.ts
+var processExists = !!globalThis.process;
+var originalProcessEnv = { ...processExists && process.env };
 var EnvGraph2 = class {
   static {
     __name(this, "EnvGraph");
@@ -1850,26 +1879,29 @@ var EnvGraph2 = class {
   // or just the files that are relevant to the current resolution attempt
   // (which would mean it's always through the lens of the current directory/package)
   basePath;
-  /** array of data sources */
-  dataSources = [];
-  finalOverridesDataSource;
+  /** root data source (.env.schema) */
+  rootDataSource;
+  /** place to store process.env overrides */
+  overrideValues = {};
   /** config item key of env flag (toggles env-specific data sources enabled) */
   envFlagKey;
-  /** current value of the environment flag */
-  envFlagValue;
+  /** graph-level fallback value for environment flag */
+  envFlagFallback;
   configSchema = {};
-  addDataSource(dataSource) {
-    dataSource.graph = this;
-    this.dataSources.push(dataSource);
-  }
-  get schemaDataSource() {
-    const schemas = this.dataSources.filter((f) => f.type === "schema");
-    if (schemas.length > 1) throw new Error("Multiple schema data sources found");
-    if (schemas.length === 0) return void 0;
-    return schemas[0];
+  /** virtual imports for testing */
+  virtualImports;
+  setVirtualImports(basePath, files) {
+    this.virtualImports = {};
+    for (const [fileName, fileContents] of Object.entries(files)) {
+      this.virtualImports[path2.join(basePath, fileName)] = fileContents;
+    }
   }
   get sortedDataSources() {
-    return my_dash_default.sortBy(this.dataSources, (f) => 10 * EnvGraphDataSource.DATA_SOURCE_TYPES[f.type].precedence + (f.applyForEnv ? 1 : 0));
+    function getSourceAndChildren(s) {
+      return [s, ...s.children ? s.children.flatMap(getSourceAndChildren) : []];
+    }
+    __name(getSourceAndChildren, "getSourceAndChildren");
+    return this.rootDataSource ? getSourceAndChildren(this.rootDataSource) : [];
   }
   registeredResolverFunctions = {};
   registerResolver(resolverClass) {
@@ -1890,78 +1922,15 @@ var EnvGraph2 = class {
     for (const resolverClass of BaseResolvers) {
       this.registerResolver(resolverClass);
     }
+    this.overrideValues = originalProcessEnv;
+  }
+  async setRootDataSource(source) {
+    if (this.rootDataSource) throw new Error("root data source already set");
+    this.rootDataSource = source;
+    source.graph = this;
+    await source.finishInit();
   }
   async finishLoad() {
-    const sortedDataSources = this.sortedDataSources;
-    for (const source of sortedDataSources) {
-      if (source.loadingError) {
-        throw source.loadingError;
-      }
-      if (source.type === "example") {
-        source.disabled = true;
-        continue;
-      }
-      if (source.decorators?.envFlag) {
-        if (source.applyForEnv) {
-          throw new Error(`@envFlag cannot be set from within an env-specific data source - ${source.label}`);
-        } else if (this.envFlagKey) {
-          throw new Error("only a single @envFlag setting is allowed");
-        } else {
-          const envFlagKey = source.decorators.envFlag.simplifiedValue;
-          if (!my_dash_default.isString(envFlagKey)) {
-            throw new Error("@envFlag must be a string");
-          } else {
-            this.envFlagKey = envFlagKey;
-          }
-        }
-      }
-      if (source.applyForEnv) {
-        if (source.applyForEnv && this.envFlagValue !== source.applyForEnv) {
-          source.disabled = true;
-          continue;
-        }
-      }
-      if (source.decorators?.disable && source.decorators.disable.simplifiedValue) {
-        source.disabled = true;
-        continue;
-      }
-      for (const itemKey in source.configItemDefs) {
-        if (source.ignoreNewDefs && !this.configSchema[itemKey]) continue;
-        const itemDef = source.configItemDefs[itemKey];
-        this.configSchema[itemKey] ??= new ConfigItem3(this, itemKey);
-        this.configSchema[itemKey].addDef(itemDef, source);
-      }
-      if (source.type === "schema" && this.envFlagKey) {
-        if (!this.configSchema[this.envFlagKey]) {
-          throw new Error(`@envFlag key ${this.envFlagKey} not found in schema`);
-        }
-        const envFlagItem = this.configSchema[this.envFlagKey];
-        await envFlagItem.process();
-        for (const depKey of envFlagItem.valueResolver?.deps || []) {
-          const depItem = this.configSchema[depKey];
-          if (!depItem) {
-            throw new Error(`envFlag resolver is using non-existant dependency: ${depKey}`);
-          }
-          await depItem.process();
-          if (depItem.valueResolver?.deps.length) {
-            throw new Error("envFlag cannot follow a chain of dependencies");
-          }
-          await depItem.resolve();
-        }
-        await envFlagItem.resolve();
-        if (!envFlagItem.isValid) {
-          const err = new Error("resolved @envFlag value is not valid");
-          err.cause = envFlagItem.errors[0];
-          throw err;
-        }
-        if (envFlagItem.resolvedValue) {
-          if (!my_dash_default.isString(envFlagItem.resolvedValue)) {
-            throw new Error("expected resolved @envFlag value to be a string");
-          }
-          this.envFlagValue = envFlagItem.resolvedValue;
-        }
-      }
-    }
     for (const itemKey in this.configSchema) {
       const item = this.configSchema[itemKey];
       await item.process();
@@ -1987,6 +1956,7 @@ var EnvGraph2 = class {
     return adjList;
   }
   async resolveEnvValues() {
+    if (my_dash_default.keys(this.configSchema).length === 0) return;
     const adjList = this.graphAdjacencyList;
     const reverseAdjList = {};
     for (const itemKey in adjList) {
@@ -2051,7 +2021,7 @@ var EnvGraph2 = class {
       serializedGraph.sources.push({
         label: source.label,
         enabled: !source.disabled,
-        path: source instanceof FileBasedDataSource ? path.relative(this.basePath ?? "", source.fullPath) : void 0
+        path: source instanceof FileBasedDataSource ? path2.relative(this.basePath ?? "", source.fullPath) : void 0
       });
     }
     for (const itemKey in this.configSchema) {
@@ -2072,13 +2042,30 @@ var EnvGraph2 = class {
     await generateTypes(this, lang, outputPath);
   }
   getRootDecoratorValue(decoratorName) {
-    const dec = this.schemaDataSource?.decorators?.[decoratorName];
-    return dec?.simplifiedValue;
+    const sources = Array.from(this.sortedDataSources).reverse();
+    for (const s of sources) {
+      if (s.disabled) continue;
+      if (s.importKeys) continue;
+      const decs = s.getRootDecorators(decoratorName);
+      if (decs.length) return decs[0].simplifiedValue;
+    }
+    return void 0;
+  }
+  getRootDecorators(decoratorName) {
+    const sources = Array.from(this.sortedDataSources).reverse();
+    const combinedDecsWithSources = [];
+    for (const source of sources) {
+      if (source.disabled) continue;
+      if (source.importKeys) continue;
+      const decs = source.getRootDecorators(decoratorName);
+      combinedDecsWithSources.push([source, decs]);
+    }
+    return combinedDecsWithSources;
   }
 };
 
 // env-graph/lib/config-item.ts
-var ConfigItem3 = class {
+var ConfigItem4 = class {
   static {
     __name(this, "ConfigItem");
   }
@@ -2095,9 +2082,19 @@ var ConfigItem3 = class {
   get key() {
     return this.#key;
   }
-  defs = [];
-  addDef(itemDef, source) {
-    this.defs.unshift({ itemDef, source });
+  /**
+   * fetch ordered list of definitions for this item, by following up sorted data sources list
+   */
+  get defs() {
+    const defs = [];
+    for (const source of this.#envGraph.sortedDataSources) {
+      if (!source.configItemDefs[this.#key]) continue;
+      if (source.disabled) continue;
+      if (source.importKeys && !source.importKeys.includes(this.#key)) continue;
+      const itemDef = source.configItemDefs[this.#key];
+      if (itemDef) defs.push({ itemDef, source });
+    }
+    return defs;
   }
   get description() {
     for (const def of this.defs) {
@@ -2116,6 +2113,9 @@ var ConfigItem3 = class {
     return links;
   }
   get valueResolver() {
+    if (this.key in this.envGraph.overrideValues) {
+      return new StaticValueResolver(this.envGraph.overrideValues[this.key]);
+    }
     for (const def of this.defs) {
       if (def.itemDef.resolver) return def.itemDef.resolver;
     }
@@ -2146,10 +2146,6 @@ var ConfigItem3 = class {
     return this.valueResolver?.schemaErrors || [];
   }
   async process() {
-    const finalOverrideDef = this.envGraph.finalOverridesDataSource?.configItemDefs[this.key];
-    if (finalOverrideDef) {
-      this.defs.unshift({ itemDef: finalOverrideDef, source: this.envGraph.finalOverridesDataSource });
-    }
     for (const def of this.defs) {
       await def.itemDef.resolver?.process(this);
     }
@@ -2175,57 +2171,113 @@ var ConfigItem3 = class {
       const dataTypeFactory = this.envGraph.dataTypesRegistry[dataTypeName];
       this.dataType = dataTypeFactory(...my_dash_default.isPlainObject(dataTypeArgs) ? [dataTypeArgs] : dataTypeArgs);
     }
-  }
-  get isRequired() {
-    for (const def of this.defs) {
-      const defDecorators = def.itemDef.decorators || {};
-      if ("required" in defDecorators) {
-        const val = defDecorators.required.simplifiedValue;
-        if (typeof val === "boolean") return val;
-        if (typeof val === "string") return val === "true";
-        return Boolean(val);
+    this.processRequired();
+  }
+  /**
+   * special early resolution helper
+   * currently used to resolve the envFlag before everything else has been loaded
+   * */
+  async earlyResolve() {
+    await this.process();
+    for (const depKey of this.valueResolver?.deps || []) {
+      const depItem = this.envGraph.configSchema[depKey];
+      if (!depItem) {
+        throw new Error(`eager resolution eror - non-existant dependency: ${depKey}`);
       }
-      if ("optional" in defDecorators) {
-        const val = defDecorators.optional.simplifiedValue;
-        if (typeof val === "boolean") return !val;
-        if (typeof val === "string") return val !== "true";
-        return !val;
+      await depItem.process();
+      if (depItem.valueResolver?.deps.length) {
+        throw new Error("eager resolution cannot follow a chain of dependencies");
       }
-      if ("defaultRequired" in def.source.decorators) {
-        const val = def.source.decorators.defaultRequired.simplifiedValue;
-        if (val === "infer") {
-          if (def.source.type === "schema") {
-            const resolver = def.itemDef.resolver;
-            if (resolver instanceof StaticValueResolver) {
-              return resolver.staticValue !== void 0 && resolver.staticValue !== "";
+      await depItem.resolve(true);
+    }
+    await this.resolve(true);
+  }
+  _isRequired = true;
+  /**
+   * need to track if required-ness is dynamic, e.g. based on current env
+   * because that will affect type generation (only _always_ required items are never undefined)
+   * */
+  _isRequiredDynamic = false;
+  processRequired() {
+    try {
+      for (const def of this.defs) {
+        const defDecorators = def.itemDef.decorators || {};
+        if ("required" in defDecorators || "optional" in defDecorators) {
+          if ("required" in defDecorators && "optional" in defDecorators) {
+            throw new SchemaError("@required and @optional cannot both be set");
+          }
+          const requiredDecoratorVal = defDecorators.required?.value || defDecorators.optional?.value;
+          const usingOptional = "optional" in defDecorators;
+          if (requiredDecoratorVal instanceof ParsedEnvSpecStaticValue) {
+            const staticVal = requiredDecoratorVal.value;
+            if (my_dash_default.isBoolean(staticVal)) {
+              this._isRequired = usingOptional ? !staticVal : staticVal;
             } else {
-              return true;
+              throw new SchemaError("@required/@optional can only be set to true/false if using a static value");
+            }
+          } else if (requiredDecoratorVal instanceof ParsedEnvSpecFunctionCall) {
+            this._isRequiredDynamic = true;
+            const requiredFnName = requiredDecoratorVal.name;
+            const requiredFnArgs = requiredDecoratorVal.simplifiedArgs;
+            if (requiredFnName === "forEnv") {
+              const currentEnv = def.source.envFlagValue;
+              if (!currentEnv) {
+                throw new SchemaError("Cannot set @required using forEnv() because environment flag is not set");
+              }
+              const envMatches = requiredFnArgs.includes(currentEnv);
+              this._isRequired = usingOptional ? !envMatches : envMatches;
             }
-          } else {
-            continue;
           }
+          return;
+        }
+        const defaultRequiredValue = def.source.getRootDecoratorSimpleValue("defaultRequired");
+        if (defaultRequiredValue !== void 0) {
+          if (defaultRequiredValue === "infer") {
+            if (def.source.type === "schema") {
+              const resolver = def.itemDef.resolver;
+              if (resolver === void 0) {
+                this._isRequired = false;
+              } else if (resolver instanceof StaticValueResolver) {
+                this._isRequired = resolver.staticValue !== void 0 && resolver.staticValue !== "";
+              } else {
+                this._isRequired = true;
+              }
+              return;
+            } else {
+              continue;
+            }
+          }
+          this._isRequired = defaultRequiredValue;
+          return;
         }
-        return val;
       }
+    } catch (err) {
+      this.schemaErrors.push(err instanceof SchemaError ? err : new SchemaError(err));
     }
-    return true;
+  }
+  get isRequired() {
+    return this._isRequired;
+  }
+  get isRequiredDynamic() {
+    return this._isRequiredDynamic;
   }
   get isSensitive() {
     for (const def of this.defs) {
       const defDecorators = def.itemDef.decorators || {};
       if ("sensitive" in defDecorators) {
         return defDecorators.sensitive.simplifiedValue;
-      } else if ("defaultSensitive" in def.source.decorators) {
-        const dec = def.source.decorators.defaultSensitive;
-        if (dec.value instanceof ParsedEnvSpecFunctionCall && dec.value.name === "inferFromPrefix") {
-          const args = dec.value.simplifiedArgs;
+      }
+      const defaultSensitiveDec = def.source.getRootDecorators("defaultSensitive")[0];
+      if (defaultSensitiveDec) {
+        if (defaultSensitiveDec.value instanceof ParsedEnvSpecFunctionCall && defaultSensitiveDec.value.name === "inferFromPrefix") {
+          const args = defaultSensitiveDec.value.simplifiedArgs;
           const prefix = Array.isArray(args) && args.length > 0 ? args[0] : void 0;
           if (typeof prefix === "string" && this.key.startsWith(prefix)) {
             return false;
           }
           return true;
         }
-        return dec.simplifiedValue;
+        return defaultSensitiveDec.simplifiedValue;
       }
     }
     return true;
@@ -2256,18 +2308,31 @@ var ConfigItem3 = class {
   get isCoerced() {
     return this.resolvedRawValue !== this.resolvedValue;
   }
-  async resolve() {
+  async resolve(reset2 = false) {
     if (this.schemaErrors.length) return;
     if (this.resolverSchemaErrors.length) return;
-    if (!this.valueResolver) throw new Error("Expected a resolver to be set");
+    if (reset2) {
+      this.isResolved = false;
+      this.isValidated = false;
+      this.resolutionError = void 0;
+      this.coercionError = void 0;
+      this.validationErrors = void 0;
+      this.resolvedRawValue = void 0;
+      this.resolvedValue = void 0;
+    }
     if (this.isResolved) {
       return;
     }
-    try {
-      this.resolvedRawValue = await this.valueResolver.resolve();
-    } catch (err) {
-      this.resolutionError = new ResolutionError(`error resolving value: ${err}`);
-      this.resolutionError.cause = err;
+    if (!this.valueResolver) {
+      this.isResolved = true;
+      this.resolvedRawValue = void 0;
+    } else {
+      try {
+        this.resolvedRawValue = await this.valueResolver.resolve();
+      } catch (err) {
+        this.resolutionError = new ResolutionError(`error resolving value: ${err}`);
+        this.resolutionError.cause = err;
+      }
     }
     if (this.resolvedRawValue instanceof RegExp) {
       this.resolutionError = new ResolutionError("regex() is meant to be used within function args, not as a final resolved value");
@@ -2330,78 +2395,255 @@ var ConfigItem3 = class {
 // env-graph/lib/data-source.ts
 var DATA_SOURCE_TYPES = Object.freeze({
   schema: {
-    fileSuffixes: ["schema"],
-    precedence: 0
+    fileSuffixes: ["schema"]
   },
   example: {
-    fileSuffixes: ["sample", "example"],
-    precedence: 1
+    fileSuffixes: ["sample", "example"]
   },
   defaults: {
-    fileSuffixes: ["default", "defaults"],
-    precedence: 2
+    fileSuffixes: ["default", "defaults"]
   },
   values: {
-    fileSuffixes: [],
-    precedence: 3
+    fileSuffixes: []
   },
   overrides: {
-    fileSuffixes: ["local", "override"],
-    precedence: 4
-  }
+    fileSuffixes: ["local", "override"]
+  },
+  container: {}
 });
-var EnvGraphDataSource = class {
+var EnvGraphDataSource3 = class {
   static {
     __name(this, "EnvGraphDataSource");
   }
   static DATA_SOURCE_TYPES = DATA_SOURCE_TYPES;
-  // reference back to the graph
+  /** reference back to the graph */
   graph;
+  /** parent data source - everything except the root will have a parent */
+  parent;
+  /** child data sources */
+  children = [];
+  /**
+   * tracks if this data source was imported, and additional settings about the import (restricting keys)
+   * */
+  importMeta;
+  get isImport() {
+    return !!this.importMeta?.isImport || !!this.parent?.isImport;
+  }
+  get importKeys() {
+    const importKeysArrays = [];
+    let currentSource = this;
+    while (currentSource) {
+      if (currentSource.importMeta?.importKeys && currentSource.importMeta.importKeys.length) {
+        importKeysArrays.push(currentSource.importMeta.importKeys);
+      }
+      currentSource = currentSource.parent;
+    }
+    if (importKeysArrays.length) {
+      const keysToImport = my_dash_default.intersection(...importKeysArrays);
+      return keysToImport;
+    }
+  }
+  /** adds a child data source and sets up the correct references in both directions */
+  async addChild(child, importMeta) {
+    if (!this.graph) throw new Error("expected graph to be set");
+    this.children.unshift(child);
+    child.parent = this;
+    child.graph = this.graph;
+    if (importMeta) child.importMeta = importMeta;
+    await child.finishInit();
+  }
+  /** environment flag key (as set by @envFlag decorator) - only if set within this source */
+  _envFlagKey;
+  /** environment flag key getter that will follow up the parent chain */
+  get envFlagKey() {
+    return this._envFlagKey || this.parent?.envFlagKey;
+  }
+  /** environment flag config item getter (follows up the parent chain) */
+  get envFlagConfigItem() {
+    const envFlagKey = this.envFlagKey;
+    return envFlagKey ? this.graph?.configSchema[envFlagKey] : void 0;
+  }
+  /** environment flag value getter (follows up the parent chain), and checks the graph-level fallback */
+  get envFlagValue() {
+    const envFlagItem = this.envFlagConfigItem;
+    if (envFlagItem) return envFlagItem.resolvedValue;
+    return this.graph.envFlagFallback;
+  }
+  /** helper to resolve the envFlag value */
+  async resolveCurrentEnv() {
+    const envFlagItem = this.envFlagConfigItem;
+    if (envFlagItem) {
+      await envFlagItem.earlyResolve();
+      return envFlagItem.resolvedValue;
+    }
+    return this.graph.envFlagFallback;
+  }
+  /** finish init process for this data source */
+  async finishInit() {
+    if (!this.graph) throw new Error("expected graph to be set");
+    await this._finishInit();
+    if (this.loadingError) {
+      return;
+    }
+    const disableDecorator = this.getRootDecorators("disable")?.[0];
+    if (disableDecorator) {
+      if (disableDecorator.value instanceof ParsedEnvSpecFunctionCall) {
+        if (disableDecorator.value.name === "forEnv") {
+          const disableForEnvs = disableDecorator.value.simplifiedArgs;
+          if (!my_dash_default.isArray(disableForEnvs)) {
+            this._loadingError = new Error("expected disable decorator args to be array");
+            return;
+          }
+          const currentEnv = await this.resolveCurrentEnv();
+          if (disableForEnvs.includes(currentEnv)) {
+            this._disabled = true;
+          }
+        } else {
+          this._loadingError = new Error(`unknown disable decorator function: ${disableDecorator.name}`);
+          return;
+        }
+      } else if (disableDecorator.simplifiedValue) {
+        this._disabled = true;
+      }
+    }
+    if (this.disabled) return;
+    const envFlagDecoratorValue = this.getRootDecoratorSimpleValue("envFlag");
+    if (envFlagDecoratorValue) {
+      if (!this.configItemDefs[envFlagDecoratorValue]) {
+        this._loadingError = new Error(`@envFlag key ${envFlagDecoratorValue} must be an item within this schema`);
+        return;
+      }
+      this._envFlagKey = envFlagDecoratorValue;
+    }
+    for (const itemKey of this.importKeys || my_dash_default.keys(this.configItemDefs)) {
+      const itemDef = this.configItemDefs[itemKey];
+      if (!itemDef) continue;
+      this.graph.configSchema[itemKey] ??= new ConfigItem4(this.graph, itemKey);
+    }
+    const importDecorators = this.getRootDecorators("import");
+    if (importDecorators.length) {
+      for (const importDecorator of importDecorators) {
+        const importArgs = importDecorator.bareFnArgs?.simplifiedValues;
+        if (!my_dash_default.isArray(importArgs)) {
+          throw new Error("expected @import args to be array");
+        }
+        const importPath = importArgs[0];
+        if (!importPath) throw new Error("@import decorator must have a value");
+        if (!my_dash_default.isString(importPath)) throw new Error("expected @import path to be string");
+        const importKeys = importArgs.slice(1);
+        if (!importKeys.every(my_dash_default.isString)) {
+          throw new Error("expected @import keys to all be strings");
+        }
+        if (importPath.startsWith("./") || importPath.startsWith("../")) {
+          if (!(this instanceof FileBasedDataSource)) {
+            throw new Error("@import of files can only be used from a file-based data source");
+          }
+          const fullImportPath = path2.resolve(this.fullPath, "..", importPath);
+          const fileName = path2.basename(fullImportPath);
+          if (this.graph.virtualImports) {
+            if (importPath.endsWith("/")) {
+              if (!Object.keys(this.graph.virtualImports).some((p) => p.startsWith(fullImportPath))) {
+                this._loadingError = new Error(`Virtual directory import ${fullImportPath} not found`);
+                return;
+              }
+              await this.addChild(new DirectoryDataSource(fullImportPath), {
+                isImport: true,
+                importKeys
+              });
+            } else {
+              if (!this.graph.virtualImports[fullImportPath]) {
+                this._loadingError = new Error(`Virtual import ${fullImportPath} not found`);
+                return;
+              }
+              const source = new DotEnvFileDataSource(fullImportPath, {
+                overrideContents: this.graph.virtualImports[fullImportPath]
+              });
+              await this.addChild(source, { isImport: true, importKeys });
+            }
+          } else {
+            const fsStat = await tryCatch(async () => fs2.stat(importPath), (_err) => {
+            });
+            if (!fsStat) {
+              this._loadingError = new Error(`Import path does not exist: ${fullImportPath}`);
+              return;
+            }
+            if (importPath.endsWith("/")) {
+              if (fsStat.isDirectory()) {
+                await this.addChild(new DirectoryDataSource(fullImportPath), {
+                  isImport: true,
+                  importKeys
+                });
+              } else {
+                this._loadingError = new Error(`Imported path ending with "/" is not a directory: ${fullImportPath}`);
+                return;
+              }
+            } else {
+              if (fsStat.isDirectory()) {
+                this._loadingError = new Error('Imported path is a directory, add trailing "/" to import');
+                return;
+              } else if (!fileName.startsWith(".env.")) {
+                this._loadingError = new Error("imported file must be a .env.* file");
+                return;
+              }
+              await this.addChild(new DotEnvFileDataSource(fullImportPath), { isImport: true, importKeys });
+            }
+          }
+        } else if (importPath.startsWith("http://") || importPath.startsWith("https://")) {
+          this._loadingError = new Error("http imports not supported yet");
+          return;
+        } else if (importPath.startsWith("npm:")) {
+          this._loadingError = new Error("npm imports not supported yet");
+          return;
+        } else {
+          this._loadingError = new Error("unsupported import type");
+          return;
+        }
+      }
+    }
+    if (envFlagDecoratorValue) {
+      const envFlagItem = this.envFlagConfigItem;
+      await envFlagItem.earlyResolve();
+      if (!envFlagItem.isValid) {
+        const err = new Error("resolved @envFlag value is not valid");
+        err.cause = envFlagItem.errors[0];
+        throw err;
+      }
+      if (!my_dash_default.isString(envFlagItem.resolvedValue)) {
+        throw new Error("expected resolved @envFlag value to be a string");
+      }
+    }
+  }
+  /**
+   * called by the finishInit - meant to be overridden by subclasses
+   * to add specific behaviour for that data source type
+   * @internal
+   * */
+  async _finishInit() {
+  }
   type = "values";
   applyForEnv;
-  disabled = false;
-  ignoreNewDefs = false;
+  _disabled = false;
+  get disabled() {
+    return this._disabled || this.parent?._disabled;
+  }
   /** an error encountered while loading/parsing the data source */
-  loadingError;
+  _loadingError;
+  get loadingError() {
+    return this._loadingError;
+  }
   get isValid() {
     return !this.loadingError;
   }
   configItemDefs = {};
-  decorators = {};
-  getStaticValues() {
-    const obj = {};
-    for (const [key, def] of Object.entries(this.configItemDefs)) {
-      if (def.resolver instanceof StaticValueResolver) {
-        obj[key] = String(def.resolver.staticValue ?? "");
-      }
-    }
-    return obj;
+  decorators = [];
+  getRootDecorators(decName) {
+    return this.decorators.filter((d) => d.name === decName);
   }
-};
-var ProcessEnvDataSource = class _ProcessEnvDataSource extends EnvGraphDataSource {
-  static {
-    __name(this, "ProcessEnvDataSource");
-  }
-  type = "overrides";
-  typeLabel = "process";
-  label = "process.env";
-  ignoreNewDefs = true;
-  static processEnvValues;
-  // ? do we want to set decorator values from env vars here? -- ex: _ENV_FLAG_KEY
-  // depends if we want those to work only within process.env
-  constructor() {
-    super();
-    if (!_ProcessEnvDataSource.processEnvValues) {
-      _ProcessEnvDataSource.processEnvValues = {};
-      for (const itemKey of Object.keys(process.env)) {
-        _ProcessEnvDataSource.processEnvValues[itemKey] = process.env[itemKey];
-      }
-    }
-    for (const itemKey of Object.keys(_ProcessEnvDataSource.processEnvValues)) {
-      this.configItemDefs[itemKey] = {
-        resolver: new StaticValueResolver(_ProcessEnvDataSource.processEnvValues[itemKey])
-      };
-    }
+  getRootDecoratorSimpleValue(decName) {
+    const decorators = this.getRootDecorators(decName);
+    if (decorators.length === 0) return void 0;
+    if (decorators.length > 1) throw new Error(`Multiple ${decName} decorators found`);
+    return decorators[0].simplifiedValue;
   }
 };
 var EnvSourceParseError = class extends Error {
@@ -2414,7 +2656,7 @@ var EnvSourceParseError = class extends Error {
     this.location = _location;
   }
 };
-var FileBasedDataSource = class extends EnvGraphDataSource {
+var FileBasedDataSource = class extends EnvGraphDataSource3 {
   static {
     __name(this, "FileBasedDataSource");
   }
@@ -2437,43 +2679,44 @@ var FileBasedDataSource = class extends EnvGraphDataSource {
   constructor(fullPath, opts) {
     super();
     this.fullPath = fullPath;
-    this.fileName = path.basename(fullPath);
+    this.fileName = path2.basename(fullPath);
     if (opts?.overrideContents) {
       this.rawContents = opts.overrideContents;
       this.isGitIgnored = opts.overrideGitIgnored;
     }
-    if (!this.fileName.startsWith(".env")) {
-      throw new Error('file name must start with ".env"');
-    }
-    const fileNameParts = this.fileName.substring(1).split(".");
-    const maybeExtension = fileNameParts[fileNameParts.length - 1];
-    if (this.validFileExtensions.includes(maybeExtension)) {
-      fileNameParts.pop();
-    }
-    const maybeFileType = fileNameParts[fileNameParts.length - 1];
-    for (const [possibleSourceType, possibleSourceSpec] of Object.entries(DATA_SOURCE_TYPES)) {
-      if (possibleSourceSpec.fileSuffixes.includes(maybeFileType)) {
-        this.type = possibleSourceType;
-        break;
+    if (this.fileName.startsWith(".env")) {
+      const fileNameParts = this.fileName.substring(1).split(".");
+      const maybeExtension = fileNameParts[fileNameParts.length - 1];
+      if (this.validFileExtensions.includes(maybeExtension)) {
+        fileNameParts.pop();
+      }
+      const maybeFileType = fileNameParts[fileNameParts.length - 1];
+      for (const [possibleSourceType, possibleSourceSpec] of Object.entries(DATA_SOURCE_TYPES)) {
+        if (!("fileSuffixes" in possibleSourceSpec)) continue;
+        if (possibleSourceSpec.fileSuffixes.includes(maybeFileType)) {
+          this.type = possibleSourceType;
+          break;
+        }
+      }
+      if (this.type !== "values") fileNameParts.pop();
+      if (fileNameParts.length > 2) {
+        throw Error(`Unsure how to interpret filename - ${this.fileName}`);
+      } else if (fileNameParts.length === 2) {
+        this.applyForEnv = fileNameParts[1];
       }
-    }
-    if (this.type !== "values") fileNameParts.pop();
-    if (fileNameParts.length > 2) {
-      throw Error(`Unsure how to interpret filename - ${this.fileName}`);
-    } else if (fileNameParts.length === 2) {
-      this.applyForEnv = fileNameParts[1];
-      if (this.applyForEnv === "dev") this.applyForEnv = "development";
-      if (this.applyForEnv === "stage") this.applyForEnv = "staging";
-      if (this.applyForEnv === "prod") this.applyForEnv = "production";
     }
   }
   // no async constructors... :(
-  async finishInit() {
+  async _finishInit() {
     if (!this.rawContents) {
+      if (!await pathExists(this.fullPath)) {
+        this._loadingError = new Error(`File does not exist: ${this.fullPath}`);
+        return;
+      }
       this.isGitIgnored = await checkIsFileGitIgnored(this.fullPath);
       this.rawContents = await fs2.readFile(this.fullPath, "utf8");
     }
-    await this._parseContents();
+    if (this.rawContents) await this._parseContents();
   }
 };
 var DotEnvFileDataSource = class extends FileBasedDataSource {
@@ -2487,7 +2730,7 @@ var DotEnvFileDataSource = class extends FileBasedDataSource {
   convertParserValueToResolvers(value) {
     if (!this.graph) throw new Error("expected graph to be set");
     if (value === void 0) {
-      return new StaticValueResolver(void 0);
+      return void 0;
     } else if (value instanceof ParsedEnvSpecStaticValue) {
       return new StaticValueResolver(value.unescapedValue);
     } else if (value instanceof ParsedEnvSpecFunctionCall) {
@@ -2501,12 +2744,16 @@ var DotEnvFileDataSource = class extends FileBasedDataSource {
       for (const arg of argsFromParser) {
         if (arg instanceof ParsedEnvSpecKeyValuePair) {
           keyValueArgs ??= {};
-          keyValueArgs[arg.key] = this.convertParserValueToResolvers(arg.value);
+          const valResolver = this.convertParserValueToResolvers(arg.value);
+          if (!valResolver) throw new Error("Did not expect to find undefined resolver in key-value arg");
+          keyValueArgs[arg.key] = valResolver;
         } else {
           if (keyValueArgs) {
             return new ErrorResolver(new SchemaError("After switching to key-value function args, cannot switch back"));
           }
-          argsAsResolversArray.push(this.convertParserValueToResolvers(arg));
+          const argResolver = this.convertParserValueToResolvers(arg);
+          if (!argResolver) throw new Error("Did not expect to find undefined resolver in array arg");
+          argsAsResolversArray.push(argResolver);
         }
       }
       if (keyValueArgs) argsAsResolversArray.push(keyValueArgs);
@@ -2520,19 +2767,19 @@ var DotEnvFileDataSource = class extends FileBasedDataSource {
     this.parsedFile = await tryCatch(
       () => parseEnvSpecDotEnvFile(rawContents),
       (error) => {
-        this.loadingError = new EnvSourceParseError(error.message, {
+        this._loadingError = new EnvSourceParseError(error.message, {
           path: this.fullPath,
           lineNumber: error.location.start.line,
           colNumber: error.location.start.column,
           lineStr: rawContents.split("\n")[error.location.start.line - 1]
         });
-        this.loadingError.cause = error;
+        this._loadingError.cause = error;
       }
     );
     if (this.loadingError) return;
     if (!this.parsedFile) throw new Error("Failed to parse .env file");
-    this.decorators = this.parsedFile.decoratorsObject;
     if (!this.graph) throw new Error("expected graph to be set");
+    this.decorators = this.parsedFile.decoratorsArray;
     for (const item of this.parsedFile.configItems) {
       item.processExpansion();
       this.configItemDefs[item.key] = {
@@ -2543,24 +2790,57 @@ var DotEnvFileDataSource = class extends FileBasedDataSource {
     }
   }
 };
-var SKIP_FILE_TYPES = [".md", ".d.ts"];
-async function findEnvFiles(opts) {
-  const cwd = opts?.cwd || process.cwd();
-  const envFiles = [];
-  const filesWithinDir = await fs2.readdir(cwd);
-  for (const fileName of filesWithinDir) {
-    if (fileName === ".env" || fileName.startsWith(".env.")) {
-      let skip = false;
-      for (const fileType of SKIP_FILE_TYPES) {
-        if (fileName.endsWith(fileType)) skip = true;
+var DirectoryDataSource = class extends EnvGraphDataSource3 {
+  constructor(basePath) {
+    super();
+    this.basePath = basePath;
+  }
+  static {
+    __name(this, "DirectoryDataSource");
+  }
+  type = "container";
+  typeLabel = "directory";
+  get label() {
+    return `directory - ${this.basePath}`;
+  }
+  schemaDataSource;
+  get loadingError() {
+    return this._loadingError || this.schemaDataSource?.loadingError;
+  }
+  get envFlagKey() {
+    return this.schemaDataSource?._envFlagKey || this.parent?.envFlagKey;
+  }
+  async addAutoLoadedFile(fileName) {
+    if (!this.graph) throw new Error("expected graph to be set");
+    const filePath = path2.join(this.basePath, fileName);
+    if (this.graph.virtualImports) {
+      if (this.graph.virtualImports[filePath]) {
+        const source2 = new DotEnvFileDataSource(filePath, { overrideContents: this.graph.virtualImports[filePath] });
+        await this.addChild(source2);
+        return source2;
       }
-      if (skip) continue;
-      envFiles.push(path.join(cwd, fileName));
+      return;
     }
+    if (!await pathExists(filePath)) return;
+    const source = new DotEnvFileDataSource(filePath);
+    await this.addChild(source);
+    return source;
   }
-  return envFiles;
-}
-__name(findEnvFiles, "findEnvFiles");
+  async _finishInit() {
+    if (!this.graph) throw new Error("expected graph to be set");
+    await this.addAutoLoadedFile(".env.schema");
+    await this.addAutoLoadedFile(".env");
+    if (this.children.length) {
+      this.schemaDataSource = this.children[this.children.length - 1];
+    }
+    await this.addAutoLoadedFile(".env.local");
+    const currentEnv = await this.resolveCurrentEnv() || this.envFlagValue;
+    if (currentEnv) {
+      await this.addAutoLoadedFile(`.env.${currentEnv}`);
+      await this.addAutoLoadedFile(`.env.${currentEnv}.local`);
+    }
+  }
+};
 
 // env-graph/lib/loader.ts
 function autoDetectBasePath() {
@@ -2578,17 +2858,9 @@ async function loadEnvGraph(opts) {
     await opts.afterInit(graph);
   }
   if (opts?.currentEnvFallback) {
-    graph.envFlagValue = opts.currentEnvFallback;
-  }
-  const envFilePaths = await findEnvFiles({
-    cwd: graph.basePath
-  });
-  for (const envFilePath of envFilePaths) {
-    const fileDataSource = new DotEnvFileDataSource(envFilePath);
-    graph.addDataSource(fileDataSource);
-    await fileDataSource.finishInit();
+    graph.envFlagFallback = opts.currentEnvFallback;
   }
-  graph.finalOverridesDataSource = new ProcessEnvDataSource();
+  await graph.setRootDataSource(new DirectoryDataSource(graph.basePath));
   await graph.finishLoad();
   return graph;
 }
@@ -2775,6 +3047,6 @@ function gracefulExit(signal = 0) {
 __name(gracefulExit, "gracefulExit");
 //! these are probably not relevant anymore, or needs to move to a plugin layer?
 
-export { CoercionError, ConfigLoadError, DotEnvFileDataSource, EnvGraph2 as EnvGraph, EnvSourceParseError, ProcessEnvDataSource, ResolutionError, SchemaError, StaticValueResolver, ValidationError, ansis_default, asyncExitHook, checkIsFileGitIgnored, getItemSummary, gracefulExit, joinAndCompact, loadEnvGraph, my_dash_default };
-//# sourceMappingURL=chunk-ZW2T4C6A.js.map
-//# sourceMappingURL=chunk-ZW2T4C6A.js.map
+export { CoercionError, ConfigLoadError, DotEnvFileDataSource, EnvGraph2 as EnvGraph, EnvSourceParseError, FileBasedDataSource, ResolutionError, SchemaError, ValidationError, ansis_default, asyncExitHook, checkIsFileGitIgnored, getItemSummary, gracefulExit, joinAndCompact, loadEnvGraph, my_dash_default, pathExists, pathExistsSync, tryCatch };
+//# sourceMappingURL=chunk-MV5ZAKN7.js.map
+//# sourceMappingURL=chunk-MV5ZAKN7.js.map