alloy-di 1.2.3 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # alloy-di
 
-`alloy-di` is a compile-time dependency injection toolkit for Vite. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
+`alloy-di` is a build-time dependency injection toolkit for Vite. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
 
 ## Highlights
 

package/dist/lib/container.d.ts

@@ -1,4 +1,5 @@
 import { Constructor, Newable, Token } from "./types.js";
+import { ResolutionContext, ServiceScope } from "./scope.js";
 import { ServiceIdentifier } from "./service-identifiers.js";
 
 //#region src/lib/container.d.ts
@@ -8,13 +9,23 @@ import { ServiceIdentifier } from "./service-identifiers.js";
  * It stores metadata discovered at build time, resolves constructor dependencies,
  * performs singleton caching, and supports token-based value providers.
  */
-declare class Container {
+declare class Container implements ResolutionContext {
   private readonly singletons;
   private readonly pendingSingletons;
   private readonly instanceOverrides;
   private readonly metadataCache;
   private readonly valueProviders;
   private readonly factoryWarningCache;
+  private readonly scopeHierarchy;
+  readonly scopeName: ServiceScope;
+  readonly parent: ResolutionContext | null;
+  getCached(target: Constructor): unknown;
+  setCached(target: Constructor, instance: unknown): void;
+  getPending(target: Constructor): Promise<unknown> | undefined;
+  setPending(target: Constructor, promise: Promise<unknown>): void;
+  deletePending(target: Constructor): void;
+  getProvider(tokenId: symbol): unknown;
+  hasProvider(tokenId: symbol): boolean;
   /**
    * Resolve (and construct) the requested service.
    *
@@ -23,6 +34,14 @@ declare class Container {
    */
   get<T>(target: Newable<T>): Promise<T>;
   get<T>(identifier: ServiceIdentifier<T>): Promise<T>;
+  /** @internal */
+  _registerScopeHierarchy(hierarchy: Record<string, string>): void;
+  /** @internal */
+  _validateScopeParent(childScope: ServiceScope, parentScope: ServiceScope): void;
+  /** @internal */
+  _resolveInContext<T>(target: Newable<T> | ServiceIdentifier<T>, context: ResolutionContext, options?: {
+    skipFactoryWarning?: boolean;
+  }): Promise<T>;
   /**
    * Provide a concrete instance override for a class constructor.
    * Used by test utilities to inject mocks/stubs without altering global metadata.
@@ -62,10 +81,8 @@ declare class Container {
    * @throws Error if a circular dependency is detected
    */
   private resolve;
-  /**
-   * Resolve a singleton service with caching and in-flight creation coalescing.
-   */
-  private resolveSingleton;
+  private findContextForScope;
+  private resolveCached;
   /**
    * Instantiate a class by resolving and injecting all declared dependencies.
    * Handles factory-lazy services by importing the real class before instantiation.

package/dist/lib/container.js

@@ -43,9 +43,51 @@ var Container = class {
 	metadataCache = /* @__PURE__ */ new Map();
 	valueProviders = /* @__PURE__ */ new Map();
 	factoryWarningCache = /* @__PURE__ */ new WeakSet();
+	scopeHierarchy = /* @__PURE__ */ new Map();
+	scopeName = ServiceScope.SINGLETON;
+	parent = null;
+	getCached(target) {
+		return this.singletons.get(target);
+	}
+	setCached(target, instance) {
+		this.singletons.set(target, instance);
+	}
+	getPending(target) {
+		return this.pendingSingletons.get(target);
+	}
+	setPending(target, promise) {
+		this.pendingSingletons.set(target, promise);
+	}
+	deletePending(target) {
+		this.pendingSingletons.delete(target);
+	}
+	getProvider(tokenId) {
+		return this.valueProviders.get(tokenId);
+	}
+	hasProvider(tokenId) {
+		return this.valueProviders.has(tokenId);
+	}
 	async get(targetOrIdentifier) {
 		if (typeof targetOrIdentifier === "symbol") return this.getByIdentifier(targetOrIdentifier);
-		return this.getByConstructor(targetOrIdentifier);
+		return this.getByConstructor(targetOrIdentifier, this);
+	}
+	/** @internal */
+	_registerScopeHierarchy(hierarchy) {
+		for (const [child, parent] of Object.entries(hierarchy)) this.scopeHierarchy.set(child, parent);
+	}
+	/** @internal */
+	_validateScopeParent(childScope, parentScope) {
+		const declaredParent = this.scopeHierarchy.get(childScope);
+		if (declaredParent && declaredParent !== parentScope) throw new Error(`[alloy] Invalid scope hierarchy construction: scope '${String(childScope)}' is declared with parent '${String(declaredParent)}', but was constructed with parent scope '${String(parentScope)}'.`);
+	}
+	/** @internal */
+	async _resolveInContext(target, context, options) {
+		if (typeof target === "symbol") {
+			const ctor = getConstructorByIdentifier(target);
+			if (!ctor) throw new Error(`No service registered for identifier ${target.description ?? target.toString()}`);
+			return this.getByConstructor(ctor, context, { skipFactoryWarning: true });
+		}
+		return this.getByConstructor(target, context, options);
 	}
 	/**
 	* Provide a concrete instance override for a class constructor.
@@ -69,7 +111,7 @@ var Container = class {
 	async getByIdentifier(identifier) {
 		const ctor = getConstructorByIdentifier(identifier);
 		if (!ctor) throw new Error(`No service registered for identifier ${identifier.description ?? identifier.toString()}`);
-		return this.getByConstructor(ctor, { skipFactoryWarning: true });
+		return this.getByConstructor(ctor, this, { skipFactoryWarning: true });
 	}
 	/**
 	* Register a concrete value for an injection token at runtime.
@@ -88,9 +130,9 @@ var Container = class {
 		if (!this.valueProviders.has(token.id)) throw new Error(`No provider registered for token ${token.description ?? String(token.id)}`);
 		return this.valueProviders.get(token.id);
 	}
-	async getByConstructor(target, options) {
+	async getByConstructor(target, context, options) {
 		if (!options?.skipFactoryWarning) this.maybeWarnFactoryLazyConstructorUsage(target);
-		return this.resolve(target, []);
+		return this.resolve(target, [], context);
 	}
 	maybeWarnFactoryLazyConstructorUsage(target) {
 		if (!isDevEnvironment()) return;
@@ -107,7 +149,7 @@ var Container = class {
 	* @returns Promise resolving to the service instance
 	* @throws Error if a circular dependency is detected
 	*/
-	async resolve(target, resolutionStack) {
+	async resolve(target, resolutionStack, context) {
 		const overridden = this.instanceOverrides.get(target);
 		if (overridden) return overridden;
 		if (resolutionStack.includes(target)) throw new DependencyResolutionError(`Circular dependency detected: ${[...resolutionStack.map((t) => t.name), target.name].join(" -> ")}`, {
@@ -117,26 +159,40 @@ var Container = class {
 		});
 		const metadata = this.getServiceMetadata(target);
 		const nextStack = [...resolutionStack, target];
-		if (metadata.scope === ServiceScope.SINGLETON) return this.resolveSingleton(target, metadata, nextStack);
-		return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory);
+		const targetCtx = this.findContextForScope(metadata.scope, context);
+		if (metadata.scope === ServiceScope.SINGLETON) return this.resolveCached(target, metadata, nextStack, targetCtx);
+		if (metadata.scope === ServiceScope.TRANSIENT) return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory, targetCtx);
+		if (targetCtx.scopeName === metadata.scope) return this.resolveCached(target, metadata, nextStack, targetCtx);
+		return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory, targetCtx);
 	}
-	/**
-	* Resolve a singleton service with caching and in-flight creation coalescing.
-	*/
-	async resolveSingleton(target, metadata, resolutionStack) {
-		const cached = this.singletons.get(target);
+	findContextForScope(scope, startingContext) {
+		if (scope === ServiceScope.SINGLETON) {
+			let current = startingContext;
+			while (current.parent) current = current.parent;
+			return current;
+		}
+		if (scope === ServiceScope.TRANSIENT) return startingContext;
+		let current = startingContext;
+		while (current) {
+			if (current.scopeName === scope) return current;
+			current = current.parent;
+		}
+		return startingContext;
+	}
+	async resolveCached(target, metadata, resolutionStack, targetCtx) {
+		const cached = targetCtx.getCached(target);
 		if (cached) return cached;
-		const pending = this.pendingSingletons.get(target);
+		const pending = targetCtx.getPending(target);
 		if (pending) return await pending;
-		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory).then((instance) => {
-			this.singletons.set(target, instance);
+		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory, targetCtx).then((instance) => {
+			targetCtx.setCached(target, instance);
 			return instance;
 		});
-		this.pendingSingletons.set(target, creation);
+		targetCtx.setPending(target, creation);
 		try {
 			return await creation;
 		} finally {
-			this.pendingSingletons.delete(target);
+			targetCtx.deletePending(target);
 		}
 	}
 	/**
@@ -149,9 +205,9 @@ var Container = class {
 	* @param factory - Optional lazy factory to import the real class
 	* @returns Promise resolving to the instantiated service
 	*/
-	async createInstance(target, dependencies, resolutionStack, factory) {
+	async createInstance(target, dependencies, resolutionStack, factory, context) {
 		const ctor = factory ? await this.importWithRetry(factory, target, resolutionStack) : target;
-		return new ctor(...await Promise.all(dependencies.map((param) => this.resolveParam(param, ctor, resolutionStack))));
+		return new ctor(...await Promise.all(dependencies.map((param) => this.resolveParam(param, ctor, resolutionStack, context))));
 	}
 	/**
 	* Resolve a single dependency entry, handling lazies, tokens, and constructors.
@@ -163,7 +219,7 @@ var Container = class {
 	* @returns Promise resolving to the dependency instance
 	* @throws Error if dependency type is invalid
 	*/
-	async resolveParam(param, target, resolutionStack) {
+	async resolveParam(param, target, resolutionStack, context) {
 		const classification = classifyDependency(param);
 		if (!classification) {
 			const stackPath = this.formatStackPath(target, resolutionStack);
@@ -176,10 +232,10 @@ var Container = class {
 		switch (classification.kind) {
 			case "lazy": {
 				const depClass = await this.importWithRetry(classification.lazy, target, resolutionStack);
-				return this.resolve(depClass, resolutionStack);
+				return this.resolve(depClass, resolutionStack, context);
 			}
-			case "token": return this.resolveTokenLike(classification.token, target, resolutionStack);
-			case "constructor": return this.resolve(classification.ctor, resolutionStack);
+			case "token": return this.resolveTokenLike(classification.token, target, resolutionStack, context);
+			case "constructor": return this.resolve(classification.ctor, resolutionStack, context);
 		}
 		return classification;
 	}
@@ -238,8 +294,12 @@ var Container = class {
 	/**
 	* Resolve a token dependency via registered value providers.
 	*/
-	resolveTokenLike(tok, target, resolutionStack) {
-		if (this.valueProviders.has(tok.id)) return this.valueProviders.get(tok.id);
+	resolveTokenLike(tok, target, resolutionStack, context) {
+		let current = context;
+		while (current) {
+			if (current.hasProvider(tok.id)) return current.getProvider(tok.id);
+			current = current.parent;
+		}
 		const stackPath = this.formatStackPath(target, resolutionStack);
 		throw new DependencyResolutionError(`No provider registered for token ${tok.description ?? String(tok.id)} while resolving ${target.name}. Resolution stack: ${stackPath}`, {
 			target,

package/dist/lib/decorators.d.ts

@@ -1,6 +1,6 @@
 import { Newable, Token } from "./types.js";
-import { Lazy } from "./lazy.js";
 import { ServiceScope } from "./scope.js";
+import { Lazy } from "./lazy.js";
 
 //#region src/lib/decorators.d.ts
 /**

package/dist/lib/env-detection.d.ts

@@ -0,0 +1,24 @@
+//#region src/lib/env-detection.d.ts
+type ImportMetaEnvShape = {
+  MODE?: string;
+  PROD?: boolean;
+  NODE_ENV?: string;
+  [key: string]: unknown;
+};
+type EnvDetectionOverrides = {
+  /**
+   * Explicit import.meta.env replacement. Use `null` to force "no env" behavior.
+   */
+  importMetaEnv?: ImportMetaEnvShape | null;
+  /**
+   * Explicit NODE_ENV replacement. Use `null` to ignore process.env.
+   */
+  nodeEnv?: string | null;
+  /**
+   * Short-circuit the entire detection logic with a predetermined boolean.
+   */
+  isDev?: boolean;
+};
+declare function setEnvDetectionOverrides(overrides: EnvDetectionOverrides | undefined): void;
+//#endregion
+export { EnvDetectionOverrides, setEnvDetectionOverrides };

package/dist/lib/env-detection.js

@@ -2,11 +2,20 @@
 function isRecord(value) {
 	return typeof value === "object" && value !== null;
 }
+/**
+* Build-time-injected detection overrides.
+*
+* The Vite plugin emits a `setEnvDetectionOverrides({ isDev: ... })` call
+* into the generated container module so detection in plugin-driven setups
+* uses the bundler's authoritative mode instead of runtime sniffing.
+*/
+let injectedOverrides;
+function setEnvDetectionOverrides(overrides) {
+	injectedOverrides = overrides;
+}
 function readImportMetaEnvFromRuntime() {
 	if (typeof import.meta === "undefined") return;
-	const candidate = import.meta;
-	if (!isRecord(candidate) || !("env" in candidate)) return;
-	const envValue = candidate.env;
+	const envValue = import.meta.env;
 	if (!isRecord(envValue)) return;
 	const env = {};
 	if (typeof envValue.MODE === "string") env.MODE = envValue.MODE;
@@ -15,8 +24,11 @@ function readImportMetaEnvFromRuntime() {
 	return env;
 }
 function readProcessNodeEnv() {
-	if (typeof process === "undefined") return;
-	return "development";
+	try {
+		return "development";
+	} catch {
+		return;
+	}
 }
 function getImportMetaEnv(overrides) {
 	if (overrides?.importMetaEnv === null) return;
@@ -29,14 +41,15 @@ function getNodeEnv(overrides) {
 	return readProcessNodeEnv();
 }
 function isDevEnvironment(overrides) {
-	if (typeof overrides?.isDev === "boolean") return overrides.isDev;
-	const nodeEnv = getNodeEnv(overrides);
+	const effective = overrides ?? injectedOverrides;
+	if (typeof effective?.isDev === "boolean") return effective.isDev;
+	const nodeEnv = getNodeEnv(effective);
 	if (typeof nodeEnv === "string") return nodeEnv !== "production";
-	const importMetaEnv = getImportMetaEnv(overrides);
+	const importMetaEnv = getImportMetaEnv(effective);
 	if (typeof importMetaEnv?.PROD === "boolean") return !importMetaEnv.PROD;
 	if (typeof importMetaEnv?.MODE === "string") return importMetaEnv.MODE !== "production";
 	if (typeof importMetaEnv?.NODE_ENV === "string") return importMetaEnv.NODE_ENV !== "production";
 	return true;
 }
 //#endregion
-export { isDevEnvironment };
+export { isDevEnvironment, setEnvDetectionOverrides };

package/dist/lib/providers.d.ts

@@ -1,7 +1,7 @@
 import { Newable, Token } from "./types.js";
+import { ServiceScope } from "./scope.js";
 import { Container } from "./container.js";
 import { Lazy } from "./lazy.js";
-import { ServiceScope } from "./scope.js";
 
 //#region src/lib/providers.d.ts
 /**

package/dist/lib/scope.d.ts

@@ -1,8 +1,25 @@
+import { Constructor } from "./types.js";
+
 //#region src/lib/scope.d.ts
 declare const ServiceScope: {
   readonly SINGLETON: "singleton";
   readonly TRANSIENT: "transient";
 };
-type ServiceScope = (typeof ServiceScope)[keyof typeof ServiceScope];
+interface AlloyScopes {
+  singleton: true;
+  transient: true;
+}
+type ServiceScope = keyof AlloyScopes;
+interface ResolutionContext {
+  readonly scopeName: ServiceScope;
+  getCached(target: Constructor): unknown;
+  setCached(target: Constructor, instance: unknown): void;
+  getPending(target: Constructor): Promise<unknown> | undefined;
+  setPending(target: Constructor, promise: Promise<unknown>): void;
+  deletePending(target: Constructor): void;
+  getProvider(tokenId: symbol): unknown;
+  hasProvider(tokenId: symbol): boolean;
+  readonly parent: ResolutionContext | null;
+}
 //#endregion
-export { ServiceScope };
+export { AlloyScopes, ResolutionContext, ServiceScope };

package/dist/plugins/core/codegen.js

@@ -1,6 +1,7 @@
 import { createClassKey, createSymbolKey, hashString, normalizeImportPath } from "./utils.js";
 import { IdentifierResolver } from "./identifier-resolver.js";
 import path from "node:path";
+import ts from "typescript";
 //#region src/plugins/core/codegen.ts
 function escapeSingleQuotes(value) {
 	return value.replaceAll("'", "\\'");
@@ -91,12 +92,72 @@ function resolveDependencyImports(metas, pool, serviceBindings, runtimeImports)
 		importMap
 	};
 }
+/**
+* True when an identifier occupies a name position rather than referencing a
+* binding: property-access names (`ns.Api`), object keys — including method
+* and accessor keys (`{ Api() {} }`, `{ get Api() {} }`) — class member
+* names, qualified names, and destructuring property names.
+*/
+function isNonReferencePosition(node) {
+	const parent = node.parent;
+	if (ts.isPropertyAccessExpression(parent)) return parent.name === node;
+	if (ts.isQualifiedName(parent)) return parent.right === node;
+	if (ts.isBindingElement(parent)) return parent.propertyName === node;
+	if (ts.isPropertyAssignment(parent) || ts.isMethodDeclaration(parent) || ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isMethodSignature(parent) || ts.isPropertySignature(parent)) return parent.name === node;
+	return false;
+}
+/**
+* Decide how to rewrite one identifier node, or skip it.
+*
+* Only binding references are rewritten: name positions and string/comment
+* content keep their text. Shorthand properties expand
+* (`{ Api }` -> `{ Api: Api_1 }`) so the key survives the rename.
+*/
+function createIdentifierEdit(node, source, replacement) {
+	const parent = node.parent;
+	if (isNonReferencePosition(node)) return;
+	const start = node.getStart(source);
+	if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) return {
+		start,
+		end: node.end,
+		text: `${node.text}: ${replacement}`
+	};
+	return {
+		start,
+		end: node.end,
+		text: replacement
+	};
+}
+/**
+* Rewrite identifier references inside a reconstructed dependency expression.
+*
+* The expression is parsed and identifier nodes are replaced by position, so
+* `$`-prefixed names rewrite correctly and occurrences inside string literals
+* (e.g. lazy `import('/src/Api')` specifiers) and comments are untouched —
+* the previous `\b`-regex text replacement got both wrong.
+*/
+function rewriteReferencedIdentifiers(expression, referenced, rewriter) {
+	const wrapped = `(${expression});`;
+	const source = ts.createSourceFile("alloy-dependency-expression.ts", wrapped, ts.ScriptTarget.ESNext, true);
+	const edits = [];
+	const visit = (node) => {
+		if (ts.isIdentifier(node) && referenced.has(node.text)) {
+			const replacement = rewriter(node.text);
+			if (replacement && replacement !== node.text) {
+				const edit = createIdentifierEdit(node, source, replacement);
+				if (edit) edits.push(edit);
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	let result = wrapped;
+	for (const edit of edits.toSorted((a, b) => b.start - a.start)) result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+	return result.slice(1, -2);
+}
 function reconstructDependencyExpression(dep, rewriter, contextDir) {
 	let expr = dep.expression;
-	for (const ident of dep.referencedIdentifiers) {
-		const replacement = rewriter(ident);
-		if (replacement && replacement !== ident) expr = expr.replaceAll(new RegExp(`\\b${ident}\\b`, "g"), replacement);
-	}
+	if (dep.referencedIdentifiers.length > 0) expr = rewriteReferencedIdentifiers(expr, new Set(dep.referencedIdentifiers), rewriter);
 	if (dep.isLazy) expr = expr.replaceAll(/import\s*\(\s*(['"])(.+?)\1\s*\)/g, (match, quote, importPath) => {
 		if (importPath.startsWith(".")) return `import(${quote}${normalizeImportPath(path.resolve(contextDir, importPath))}${quote})`;
 		return match;
@@ -128,11 +189,11 @@ function reconstructOptionsText(meta, importMap, serviceRenames) {
 	if (parts.length === 0) return "{}";
 	return `{ ${parts.join(", ")} }`;
 }
-function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths) {
+function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths, options) {
 	const hasProviderModules = providerModulePaths.length > 0;
 	const activeMetas = filterActiveMetas(metas, lazyReferencedClassKeys);
 	const resolver = new IdentifierResolver(activeMetas);
-	const runtimeImports = computeRuntimeImports(activeMetas, hasProviderModules);
+	const runtimeImports = computeRuntimeImports(activeMetas, hasProviderModules, options?.isDev !== void 0);
 	const pool = createNamePool([
 		...runtimeImports,
 		"registrations",
@@ -189,8 +250,9 @@ function enrichRegistrations(activeMetas, naming) {
 		};
 	});
 }
-function computeRuntimeImports(activeMetas, hasProviderModules) {
+function computeRuntimeImports(activeMetas, hasProviderModules, hasEnvOverrides = false) {
 	const imports = new Set(["Container", "dependenciesRegistry"]);
+	if (hasEnvOverrides) imports.add("setEnvDetectionOverrides");
 	const needsLazyImport = activeMetas.some((m) => m.metadata.dependencies.some((d) => d.isLazy) || !!m.metadata.factory);
 	if (hasProviderModules) imports.add("applyProviders");
 	if (needsLazyImport) imports.add("Lazy");
@@ -244,6 +306,18 @@ function createIdentifierExports(registrations) {
 	return `${registrations.map((meta) => `const ${meta.identifierConst} = registerServiceIdentifier(${meta.importName}, Symbol.for('${escapeSingleQuotes(meta.symbolDescription)}'));`).join("\n")}\n\nexport const serviceIdentifiers = {\n${registrations.map((meta) => `  '${meta.exportKey}': ${meta.identifierConst}`).join(",\n")}\n};\n`;
 }
 /**
+* Builds the runtime scope-hierarchy registration statement. The generated
+* container records the declared parent of each custom scope so child scopes
+* constructed via `alloy-di/scopes` can be validated against the build-time
+* hierarchy. Returns an empty string when no custom scopes are configured.
+*/
+function createScopeHierarchyBlock(scopes) {
+	if (!scopes) return "";
+	const names = Object.keys(scopes);
+	if (!names.length) return "";
+	return `\ncontainer._registerScopeHierarchy({\n${names.map((name) => `  ${JSON.stringify(name)}: ${JSON.stringify(scopes[name].parent ?? "singleton")}`).join(",\n")}\n});\n`;
+}
+/**
 * Generates the virtual container module code.
 * This module:
 * 1. Imports the runtime container and necessary helpers.
@@ -257,9 +331,11 @@ function createIdentifierExports(registrations) {
 * @param lazyReferencedClassKeys - Set of service keys that are referenced ONLY lazily (and thus should not be imported/registered eagerly in this bundle).
 * @param providerModulePaths - List of provider modules to import and apply.
 */
-function generateContainerModule(metas, lazyReferencedClassKeys, providerModulePaths) {
+function generateContainerModule(metas, lazyReferencedClassKeys, providerModulePaths, options) {
 	const hasProviderModules = providerModulePaths.length > 0;
-	const { runtimeImportStatement, registrationsBlock, stubsBlock, identifierExportBlock } = buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths);
+	const { runtimeImportStatement, registrationsBlock, stubsBlock, identifierExportBlock } = buildImportsAndRegistrations(metas, lazyReferencedClassKeys, providerModulePaths, options);
+	const envOverridesBlock = options?.isDev === void 0 ? "" : `\nsetEnvDetectionOverrides({ isDev: ${options.isDev} });\n`;
+	const scopeHierarchyBlock = createScopeHierarchyBlock(options?.scopes);
 	let providerImportBlock = "";
 	let providerInvocationBlock = "";
 	if (hasProviderModules) {
@@ -268,12 +344,12 @@ function generateContainerModule(metas, lazyReferencedClassKeys, providerModuleP
 		providerInvocationBlock = `\nconst providerDefinitions = [${aliasNames.join(", ")}];\nfor (const definition of providerDefinitions) {\n  applyProviders(container, definition);\n}\n`;
 	}
 	return `
-${runtimeImportStatement}${stubsBlock}
+${runtimeImportStatement}${envOverridesBlock}${stubsBlock}
 ${providerImportBlock}
 ${registrationsBlock}
 
 const container = new Container();
-
+${scopeHierarchyBlock}
 for (const entry of registrations) {
   dependenciesRegistry.set(entry.ctor, entry.meta);
 }
@@ -281,6 +357,11 @@ ${providerInvocationBlock}${identifierExportBlock}
 export default container;
 `;
 }
+const GENERATED_FILE_NOTICE = "This file was auto-generated by Alloy. Manual changes will be overwritten.";
+const GENERATED_FILE_HEADER = `/**
+ * ${GENERATED_FILE_NOTICE}
+ */
+`;
 /**
 * Generates the TypeScript declaration definition (`.d.ts`) for the virtual container module.
 * It exports the `ServiceIdentifiers` interface matching the runtime exports.
@@ -305,7 +386,7 @@ function generateContainerTypeDefinition(metas, pathResolver) {
 		const exportKey = createIdentifierExportKey(meta, resolver);
 		interfaceMembers.push(`${exportKey}: ServiceIdentifier<${importName}>;`);
 	}
-	return `
+	return `${GENERATED_FILE_HEADER}
 declare module "virtual:alloy-container" {
   import { Container, ServiceIdentifier } from "alloy-di/runtime";
   ${imports.length ? imports.join("\n") + "\n" : ""}
@@ -321,6 +402,29 @@ declare module "virtual:alloy-container" {
 `;
 }
 /**
+* Generates a standalone declaration file that augments `AlloyScopes` with the
+* custom scope names, opening the `ServiceScope` union so `@Injectable('<scope>')`
+* type-checks. Returns `undefined` when no custom scopes are configured.
+*
+* This MUST live in its own file: module augmentation requires the file to be a
+* module (hence the trailing `export {}`), whereas the container declaration
+* must stay a global script so `virtual:alloy-container` resolves everywhere.
+* Combining the two in one file turns the container declaration into a module
+* and breaks resolution of the virtual module.
+*/
+function generateScopeAugmentationDefinition(scopeNames) {
+	if (!scopeNames.length) return;
+	return `${GENERATED_FILE_HEADER}
+declare module "alloy-di/runtime" {
+  interface AlloyScopes {
+${scopeNames.map((name) => `    ${JSON.stringify(name)}: true;`).join("\n")}
+  }
+}
+
+export {};
+`;
+}
+/**
 * Generates ambient type declarations for external Alloy manifests consumed by the project.
 * Creates:
 * 1. `declare module "PKG/manifest"` typed as `LibraryManifest`.
@@ -329,7 +433,7 @@ declare module "virtual:alloy-container" {
 * @param manifests - List of loaded manifest info (packageName and services).
 */
 function generateManifestTypeDefinition(manifests) {
-	return manifests.map((m) => {
+	return GENERATED_FILE_HEADER + manifests.map((m) => {
 		const serviceIdentifiers = m.services.map((s) => `  export const ${s.exportName}Identifier: ServiceIdentifier;`).join("\n");
 		return `
 declare module "${m.packageName}/manifest" {
@@ -420,4 +524,4 @@ ${serviceIdentifiers}
 	}).join("\n");
 }
 //#endregion
-export { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition };
+export { GENERATED_FILE_NOTICE, generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition, generateScopeAugmentationDefinition };