alloy-di 1.5.0 → 2.0.0

package/README.md

@@ -1,13 +1,13 @@
 # alloy-di
 
-`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.
+`alloy-di` is a build-time dependency injection toolkit for TypeScript apps. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
 
 ## Highlights
 
 - **Build-time graph** – services, scopes, and dependencies are resolved while bundling, so runtime work stays minimal.
-- **Visualize your DI graph** – enable the Vite plugin’s `visualize` option to emit a Mermaid diagram (`./alloy-di.mmd` by default) that captures scopes, lazy edges, and tokens for easy review.
+- **Visualize your DI graph** – enable the build plugin’s `visualize` option to emit a Mermaid diagram (`./alloy-di.mmd` by default) that captures scopes, lazy edges, and tokens for easy review.
 - **First-class lazy loading** – use `Lazy()` or provider-based lazy registrations to keep optional features in separate chunks.
-- **Framework agnostic** – works anywhere Vite runs: React, Vue, Svelte, SSR, libraries, and plain TS apps.
+- **Bundler support** – use the generated container from Vite, webpack, or Rspack applications.
 - **Type safe** – generates `serviceIdentifiers` and manifest declarations for precise inference.
 
 ## Install
@@ -51,13 +51,17 @@ pnpm add -D alloy-di
    const app = await container.get(serviceIdentifiers.AppService);
    ```
 
-> **Build tip:** The default Vite scaffold (`pnpm create vite@latest`) wires `"build": "tsc && vite build"`. Alloy writes its ambient declarations during `vite build`, so running `tsc` first can fail on fresh trees. Swap the order (`vite build && tsc`), or manually run `vite build` to generate the declarations first.
+> **Build tip:** The default Vite scaffold (`pnpm create vite@latest`) wires `"build": "tsc && vite build"`. Run `alloy generate` before type-checking so fresh checkouts and CI have Alloy's ambient declarations available, for example `"build": "alloy generate && tsc && vite build"`.
+
+By default Alloy scans `src` for decorated services. If your services live elsewhere, configure `sourceDirs` in the Vite plugin; `alloy generate` will reuse that config.
+
+Webpack and Rspack apps can use `alloy-di/webpack` or `alloy-di/rspack` with the same options. Run `alloy generate --bundler webpack` or `alloy generate --bundler rspack` before type-checking.
 
 Need manifests, providers, or testing utilities? See the docs site for complete guides.
 
 ## Visualize your dependency graph
 
-Enable the Vite plugin’s `visualize` option to have Alloy emit a Mermaid diagram that reflects every discovered service, scope, lazy edge, and token. By default the graph is written to `./alloy-di.mmd`, but you can customize the output path, color palette, or layout direction to fit your workflow.
+Enable the build plugin’s `visualize` option to have Alloy emit a Mermaid diagram that reflects every discovered service, scope, lazy edge, and token. By default the graph is written to `./alloy-di.mmd`, but you can customize the output path, color palette, or layout direction to fit your workflow.
 
 ```ts
 import { defineConfig } from "vite";
@@ -90,8 +94,9 @@ The site covers getting started, plugin options, manifest authoring, lazy loadin
 
 ## Examples in this repo
 
-- `packages/examples/app` – React + Vite app consuming decorated services, manifests, and providers.
+- `packages/examples/app-vite` – React + Vite app consuming decorated services, manifests, and providers.
+- `packages/examples/app-webpack-rspack` – the same React app source built with webpack and Rspack.
 - `packages/examples/library-internal` – monorepo library that emits `alloy.manifest.mjs` via the Rolldown plugin.
 - `packages/examples/library-external` – plain classes registered through providers.
 
-Clone the repo, run `pnpm install`, then `pnpm --filter @alloy-di/example-app dev` to explore.
+Clone the repo, run `pnpm install`, then `pnpm --filter @alloy-di/example-app-vite dev` to explore.

package/bin/alloy.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/cli.js";
+
+try {
+  await runCli();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+import { AlloyPluginOptions } from "./plugins/consumer-plugin.js";
+import { AlloyGenerateOptions, generate } from "./generate.js";
+//#region src/cli.d.ts
+type GenerateBundler = "vite" | "webpack" | "rspack" | "none";
+interface GenerateCliOptions {
+  root?: string;
+  configFile?: string;
+  bundler?: GenerateBundler;
+  mode?: string;
+  help?: boolean;
+}
+interface RunCliDependencies {
+  generate: typeof generate;
+  resolveGenerateOptions: typeof resolveGenerateOptions;
+  log: (message: string) => void;
+}
+declare function printUsage(log?: (message: string) => void): void;
+declare function readOptionValue(args: string[], index: number, optionName: string): string;
+declare function parseGenerateArgs(args: string[]): GenerateCliOptions;
+declare function getAlloyOptions(plugin: unknown): AlloyPluginOptions | undefined;
+declare function resolveGenerateOptions(cliOptions: GenerateCliOptions): Promise<AlloyGenerateOptions>;
+declare function runCli(args?: string[], deps?: RunCliDependencies): Promise<void>;
+//#endregion
+export { GenerateBundler, GenerateCliOptions, RunCliDependencies, getAlloyOptions, parseGenerateArgs, printUsage, readOptionValue, resolveGenerateOptions, runCli };

package/dist/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { generate } from "./generate.js";
+import { ALLOY_PLUGIN_OPTIONS } from "./plugins/consumer-plugin.js";
+import { ALLOY_VITE_PLUGIN_OPTIONS } from "./plugins/vite-plugin/index.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/cli.ts
+const defaultRunCliDependencies = {
+	generate,
+	resolveGenerateOptions,
+	log: (message) => console.log(message)
+};
+function printUsage(log = console.log) {
+	log(`Usage:
+  alloy generate [--root <dir>] [--config <file>] [--bundler <vite|webpack|rspack|none>] [--mode <mode>]
+
+Commands:
+  generate  Generate Alloy declaration files without bundling.
+
+Options:
+  --root    Project root. Defaults to the current working directory.
+  --config  Bundler config file to load. Pass "false" to skip config loading.
+  --bundler Config loader to use. Defaults to "vite" unless --config false is set.
+  --mode    Mode passed to webpack/Rspack config functions. Defaults to "production".`);
+}
+function readOptionValue(args, index, optionName) {
+	const value = args[index + 1];
+	if (!value || value.startsWith("-")) throw new Error(`[alloy] ${optionName} requires a value.`);
+	return value;
+}
+function parseGenerateArgs(args) {
+	const options = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--root" || arg === "-r") {
+			options.root = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--config" || arg === "-c") {
+			options.configFile = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--bundler" || arg === "-b") {
+			const bundler = readOptionValue(args, i, arg);
+			if (bundler !== "vite" && bundler !== "webpack" && bundler !== "rspack" && bundler !== "none") throw new Error(`[alloy] --bundler must be one of "vite", "webpack", "rspack", or "none".`);
+			options.bundler = bundler;
+			i++;
+		} else if (arg === "--mode" || arg === "-m") {
+			options.mode = readOptionValue(args, i, arg);
+			i++;
+		} else if (arg === "--help" || arg === "-h") {
+			options.help = true;
+			return options;
+		} else throw new Error(`[alloy] Unknown option "${arg}".`);
+	}
+	return options;
+}
+function getAlloyOptions(plugin) {
+	if (!plugin || typeof plugin !== "object") return;
+	const candidate = plugin;
+	return candidate[ALLOY_PLUGIN_OPTIONS] ?? candidate[ALLOY_VITE_PLUGIN_OPTIONS];
+}
+async function resolveGenerateOptions(cliOptions) {
+	const root = cliOptions.root ? path.resolve(cliOptions.root) : process.cwd();
+	const bundler = resolveBundler(cliOptions);
+	if (bundler === "none") return { root };
+	if (bundler === "vite") return resolveViteGenerateOptions(cliOptions, root);
+	return resolveWebpackLikeGenerateOptions(cliOptions, root, bundler);
+}
+function resolveBundler(cliOptions) {
+	if (cliOptions.configFile === "false") return "none";
+	return cliOptions.bundler ?? "vite";
+}
+async function resolveViteGenerateOptions(cliOptions, root) {
+	let vite;
+	try {
+		vite = await import("vite");
+	} catch {
+		throw new Error("[alloy] Could not load Vite. Install vite or run with --config false and provide options programmatically.");
+	}
+	const inlineConfig = {
+		root,
+		configFile: cliOptions.configFile
+	};
+	const config = await vite.resolveConfig(inlineConfig, "build", "production", "production");
+	const alloyOptions = config.plugins.map((plugin) => getAlloyOptions(plugin)).find((options) => Boolean(options));
+	if (!alloyOptions) throw new Error("[alloy] Could not find alloy() in the resolved Vite plugins.");
+	return {
+		...alloyOptions,
+		root: config.root
+	};
+}
+async function resolveWebpackLikeGenerateOptions(cliOptions, root, bundler) {
+	const alloyOptions = normalizeWebpackLikeConfigs(await evaluateWebpackLikeConfig(await loadBundlerConfig(resolveBundlerConfigFile(root, bundler, cliOptions.configFile), bundler), cliOptions.mode)).flatMap((config) => Array.isArray(config.plugins) ? config.plugins : []).map((plugin) => getAlloyOptions(plugin)).find((options) => Boolean(options));
+	if (!alloyOptions) throw new Error(`[alloy] Could not find alloy() in the resolved ${bundlerLabel(bundler)} plugins.`);
+	return {
+		...alloyOptions,
+		root
+	};
+}
+function resolveBundlerConfigFile(root, bundler, configFile) {
+	if (configFile) return path.isAbsolute(configFile) ? configFile : path.resolve(root, configFile);
+	for (const extension of [
+		"js",
+		"mjs",
+		"cjs"
+	]) {
+		const candidate = path.resolve(root, `${bundler}.config.${extension}`);
+		try {
+			if (fsExists(candidate)) return candidate;
+		} catch {}
+	}
+	throw new Error(`[alloy] Could not find ${bundlerLabel(bundler)} config. Pass --config <file> or --config false.`);
+}
+function fsExists(filePath) {
+	return fs.existsSync(filePath);
+}
+async function loadBundlerConfig(configFile, bundler) {
+	if (/\.[cm]?ts$/i.test(configFile)) throw new Error(`[alloy] ${bundlerLabel(bundler)} TypeScript config loading is not supported by alloy generate yet. Use a JavaScript config wrapper or pass --config false.`);
+	try {
+		const imported = await import(pathToFileURL(configFile).href);
+		return imported.default ?? imported;
+	} catch (error) {
+		throw new Error(`[alloy] Could not load ${bundlerLabel(bundler)} config at ${configFile}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+async function evaluateWebpackLikeConfig(config, mode = "production") {
+	if (typeof config !== "function") return config;
+	return config({
+		mode,
+		production: mode === "production"
+	}, {
+		mode,
+		env: { mode }
+	});
+}
+function normalizeWebpackLikeConfigs(config) {
+	return (Array.isArray(config) ? config : [config]).filter((candidate) => Boolean(candidate) && typeof candidate === "object");
+}
+function bundlerLabel(bundler) {
+	return bundler === "rspack" ? "Rspack" : "webpack";
+}
+async function runCli(args = process.argv.slice(2), deps = defaultRunCliDependencies) {
+	const [command, ...commandArgs] = args;
+	if (!command || command === "--help" || command === "-h") {
+		printUsage(deps.log);
+		return;
+	}
+	if (command !== "generate") throw new Error(`[alloy] Unknown command "${command}".`);
+	const cliOptions = parseGenerateArgs(commandArgs);
+	if (cliOptions.help) {
+		printUsage(deps.log);
+		return;
+	}
+	const options = await deps.resolveGenerateOptions(cliOptions);
+	const result = await deps.generate(options);
+	deps.log(`[alloy] Generated declarations for ${result.serviceCount} service(s) in ${result.declarationDir}.`);
+}
+function isMainModule() {
+	return process.argv[1] ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+}
+if (isMainModule()) try {
+	await runCli();
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+}
+//#endregion
+export { getAlloyOptions, parseGenerateArgs, printUsage, readOptionValue, resolveGenerateOptions, runCli };

package/dist/generate.d.ts

@@ -0,0 +1,28 @@
+import { AlloyPluginOptions } from "./plugins/consumer-plugin.js";
+
+//#region src/generate.d.ts
+interface AlloyGenerateOptions extends AlloyPluginOptions {
+  /**
+   * Project root to scan. Defaults to `process.cwd()`.
+   */
+  root?: string;
+  /**
+   * Override the package name used for generated service identifier keys.
+   * Defaults to the nearest `package.json` name under `root`.
+   */
+  packageName?: string;
+}
+interface AlloyGenerateResult {
+  root: string;
+  declarationDir: string;
+  serviceCount: number;
+  manifestCount: number;
+}
+/**
+ * Generates Alloy's ambient TypeScript declarations without running a Vite
+ * build. This is intended for fresh checkouts and CI pipelines that type-check
+ * before bundling.
+ */
+declare function generate(options?: AlloyGenerateOptions): Promise<AlloyGenerateResult>;
+//#endregion
+export { AlloyGenerateOptions, AlloyGenerateResult, generate };

package/dist/generate.js

@@ -0,0 +1,46 @@
+import { normalizeImportPath } from "./plugins/core/utils.js";
+import { prepareContainerData, writeDeclarationArtifacts } from "./plugins/core/container-loader.js";
+import { DEFAULT_SOURCE_DIRS, createDiscoveryRuntimeForSourceDirs, readPackageName, toLazyServiceKey } from "./plugins/core/generation-inputs.js";
+import path from "node:path";
+//#region src/generate.ts
+/**
+* Generates Alloy's ambient TypeScript declarations without running a Vite
+* build. This is intended for fresh checkouts and CI pipelines that type-check
+* before bundling.
+*/
+async function generate(options = {}) {
+	const root = path.resolve(options.root ?? process.cwd());
+	const packageName = options.packageName ?? readPackageName(root);
+	const discoveryRuntime = createDiscoveryRuntimeForSourceDirs(root, options.sourceDirs ?? DEFAULT_SOURCE_DIRS, { factoryProviders: false });
+	const providerImportPaths = (options.providers ?? []).map((entry) => {
+		return normalizeImportPath(path.isAbsolute(entry) ? entry : path.resolve(root, entry));
+	});
+	const prepared = await prepareContainerData({
+		localMetas: Array.from(discoveryRuntime.discoveredClasses.values()),
+		lazyReferencedClassKeys: discoveryRuntime.lazyReferencedClassKeys,
+		manifests: options.manifests ?? [],
+		providerImportPaths,
+		factoryProviders: [],
+		lazyServiceKeys: new Set((options.lazyServices ?? []).map(toLazyServiceKey)),
+		packageName,
+		resolvedRoot: root,
+		containerDeclarationDir: options.containerDeclarationDir,
+		resolvedVisualization: null,
+		scopes: options.scopes
+	});
+	writeDeclarationArtifacts({
+		metas: prepared.metas,
+		loadedManifests: prepared.loadedManifests,
+		resolvedRoot: root,
+		containerDeclarationDir: options.containerDeclarationDir,
+		scopes: options.scopes
+	});
+	return {
+		root,
+		declarationDir: path.resolve(root, options.containerDeclarationDir ?? "./src"),
+		serviceCount: prepared.metas.length,
+		manifestCount: prepared.loadedManifests.length
+	};
+}
+//#endregion
+export { generate };

package/dist/lib/container.d.ts

@@ -1,6 +1,6 @@
 import { Constructor, Newable, Token } from "./types.js";
-import { FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope } from "./scope.js";
 import { ServiceIdentifier } from "./service-identifiers.js";
+import { FactoryCacheEntry, FactoryPendingEntry, ResolutionContext, ServiceScope } from "./scope.js";
 
 //#region src/lib/container.d.ts
 /**
@@ -36,6 +36,7 @@ declare class Container implements ResolutionContext {
   readonly scopeName: ServiceScope;
   readonly parent: ResolutionContext | null;
   getCached(target: Constructor): unknown;
+  hasCached(target: Constructor): boolean;
   setCached(target: Constructor, instance: unknown): void;
   getPending(target: Constructor): Promise<unknown> | undefined;
   setPending(target: Constructor, promise: Promise<unknown>): void;

package/dist/lib/container.js

@@ -53,6 +53,9 @@ var Container = class {
 	getCached(target) {
 		return this.singletons.get(target);
 	}
+	hasCached(target) {
+		return this.singletons.has(target);
+	}
 	setCached(target, instance) {
 		this.singletons.set(target, instance);
 	}
@@ -202,8 +205,7 @@ var Container = class {
 	* @throws Error if a circular dependency is detected
 	*/
 	async resolve(target, resolutionStack, context) {
-		const overridden = this.instanceOverrides.get(target);
-		if (overridden) return overridden;
+		if (this.instanceOverrides.has(target)) return this.instanceOverrides.get(target);
 		if (resolutionStack.includes(target)) throw new DependencyResolutionError(`Circular dependency detected: ${[...resolutionStack.map((t) => t.name), target.name].join(" -> ")}`, {
 			target,
 			resolutionStack,
@@ -232,8 +234,7 @@ var Container = class {
 		return startingContext;
 	}
 	async resolveCached(target, metadata, resolutionStack, targetCtx) {
-		const cached = targetCtx.getCached(target);
-		if (cached) return cached;
+		if (targetCtx.hasCached(target)) return targetCtx.getCached(target);
 		const pending = targetCtx.getPending(target);
 		if (pending) return await pending;
 		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory, targetCtx).then((instance) => {

package/dist/lib/lazy.d.ts

@@ -14,6 +14,10 @@ interface Lazy<T> {
     factor?: number;
   };
 }
+/**
+ * Narrow an unknown value to a `Lazy` wrapper based on the hidden identifier symbol.
+ */
+declare function isLazy(value: unknown): value is Lazy<unknown>;
 /**
  * Helper type to extract the instance type from a Newable constructor.
  */
@@ -36,4 +40,4 @@ declare function Lazy<F extends () => Promise<Newable<any> | {
 }>>(importer: F, retry?: Lazy<any>["retry"]): Lazy<InferLazyType<F>>;
 declare function Lazy<T>(importer: Importer<T>, retry?: Lazy<T>["retry"]): Lazy<T>;
 //#endregion
-export { LAZY_IDENTIFIER, Lazy };
+export { LAZY_IDENTIFIER, Lazy, isLazy };

package/dist/lib/scope.d.ts

@@ -27,6 +27,7 @@ interface FactoryPendingEntry {
 interface ResolutionContext {
   readonly scopeName: ServiceScope;
   getCached(target: Constructor): unknown;
+  hasCached(target: Constructor): boolean;
   setCached(target: Constructor, instance: unknown): void;
   getPending(target: Constructor): Promise<unknown> | undefined;
   setPending(target: Constructor, promise: Promise<unknown>): void;

package/dist/lib/types.d.ts

@@ -18,5 +18,7 @@ interface Token<T> {
 }
 /** Create a unique typed token for values or abstractions. */
 declare function createToken<T>(description?: string): Token<T>;
+declare function isToken(value: unknown): value is Token<unknown>;
+declare function isConstructor(value: unknown): value is Constructor;
 //#endregion
-export { Constructor, Newable, Token, createToken };
+export { Constructor, Newable, Token, createToken, isConstructor, isToken };

package/dist/plugins/consumer-plugin.d.ts

@@ -0,0 +1,40 @@
+import { ServiceIdentifier } from "../lib/service-identifiers.js";
+import { AlloyManifest } from "./core/types.js";
+import { AlloyScopesConfig } from "./core/scopes-validation.js";
+import { AlloyMermaidVisualizerOptions, AlloyVisualizationOptions } from "./core/visualization-utils.js";
+
+//#region src/plugins/consumer-plugin.d.ts
+interface AlloyPluginOptions {
+  providers?: string[];
+  /**
+   * Source directories to scan for decorated services before the virtual
+   * container is loaded. Relative paths are resolved against the project root.
+   * Defaults to ["src"].
+   */
+  sourceDirs?: string[];
+  /** Optional list of manifest objects to ingest */
+  manifests?: AlloyManifest[];
+  /** List of ServiceIdentifiers to mark as instantiation-lazy (adds factory Lazy wrapper) */
+  lazyServices?: ServiceIdentifier[];
+  /**
+   * Output directory for the generated `virtual-container.d.ts` file.
+   * Relative paths are resolved against the project root.
+   * Defaults to "./src".
+   */
+  containerDeclarationDir?: string;
+  /**
+   * Emit dependency graph artifacts. When `true`, writes a Mermaid diagram to
+   * `${projectRoot}/alloy-di.mmd`. Provide an object to customize output.
+   */
+  visualize?: boolean | AlloyVisualizationOptions;
+  /**
+   * Declares custom, application-defined scopes and their parent ordering, e.g.
+   * `{ session: { parent: 'singleton' }, request: { parent: 'session' } }`.
+   * Drives type-safe scope names (emitted into the generated declaration),
+   * runtime hierarchy registration, and build-time scope-stability validation.
+   */
+  scopes?: AlloyScopesConfig;
+}
+declare const ALLOY_PLUGIN_OPTIONS: unique symbol;
+//#endregion
+export { ALLOY_PLUGIN_OPTIONS, AlloyPluginOptions };

package/dist/plugins/consumer-plugin.js

@@ -0,0 +1,101 @@
+import { normalizeImportPath, writeFileIfChanged } from "./core/utils.js";
+import { resolveVisualizationOptions } from "./core/visualization-utils.js";
+import { loadVirtualContainerModule } from "./core/container-loader.js";
+import { createDiscoveryRuntime, isDiscoverableFile } from "./core/discovery-runtime.js";
+import { DEFAULT_SOURCE_DIRS, readPackageName, scanSourceDirectories, toLazyServiceKey } from "./core/generation-inputs.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/plugins/consumer-plugin.ts
+const ALLOY_PLUGIN_OPTIONS = Symbol.for("alloy-di.plugin-options");
+function createConsumerPluginContext(options = {}) {
+	const configuredProviderEntries = Array.from(options.providers ?? []);
+	const configuredSourceDirs = Array.from(options.sourceDirs ?? DEFAULT_SOURCE_DIRS);
+	const providerModuleRefs = [];
+	const lazyServiceKeys = new Set((options.lazyServices ?? []).map(toLazyServiceKey));
+	const discoveryRuntime = createDiscoveryRuntime();
+	let resolvedRoot = process.cwd();
+	let packageName = "UNKNOWN_PACKAGE";
+	let resolvedVisualization = null;
+	let isDevMode;
+	function configure(config = {}) {
+		resolvedRoot = config.root ?? process.cwd();
+		isDevMode = config.isDevMode;
+		packageName = readPackageName(resolvedRoot);
+		providerModuleRefs.length = 0;
+		for (const entry of configuredProviderEntries) {
+			const absPath = path.isAbsolute(entry) ? entry : path.resolve(resolvedRoot, entry);
+			providerModuleRefs.push({
+				absPath,
+				importPath: normalizeImportPath(absPath)
+			});
+		}
+		resolvedVisualization = resolveVisualizationOptions(options.visualize, resolvedRoot);
+	}
+	async function loadContainer() {
+		return loadVirtualContainerModule({
+			localMetas: Array.from(discoveryRuntime.discoveredClasses.values()),
+			lazyReferencedClassKeys: discoveryRuntime.lazyReferencedClassKeys,
+			manifests: options.manifests ?? [],
+			providerImportPaths: providerModuleRefs.map((ref) => ref.importPath),
+			factoryProviders: shouldTrackFactoryProviders() ? Array.from(discoveryRuntime.factoryProvidersByFile.values()).flat() : [],
+			lazyServiceKeys,
+			packageName,
+			resolvedRoot,
+			containerDeclarationDir: options.containerDeclarationDir,
+			resolvedVisualization,
+			isDevMode,
+			scopes: options.scopes
+		});
+	}
+	function shouldTrackFactoryProviders() {
+		return Boolean(resolvedVisualization);
+	}
+	return {
+		options,
+		virtualModuleId: "virtual:alloy-container",
+		resolvedVirtualModuleId: "\0virtual:alloy-container",
+		get root() {
+			return resolvedRoot;
+		},
+		sourceDirs: configuredSourceDirs,
+		configure,
+		shouldTrackFactoryProviders,
+		processTransform(code, id) {
+			return discoveryRuntime.processUpdate(id, code, { factoryProviders: shouldTrackFactoryProviders() });
+		},
+		processFileUpdate(file, code) {
+			return discoveryRuntime.processUpdate(file, code, { factoryProviders: shouldTrackFactoryProviders() });
+		},
+		removeFile(file) {
+			return discoveryRuntime.removeDiscoveredFile(file);
+		},
+		buildStart(addWatchFile) {
+			discoveryRuntime.clear();
+			for (const ref of providerModuleRefs) {
+				addWatchFile?.(ref.absPath);
+				if (shouldTrackFactoryProviders()) try {
+					const code = fs.readFileSync(ref.absPath, "utf-8");
+					discoveryRuntime.processUpdate(ref.absPath, code, { factoryProviders: true });
+				} catch {}
+			}
+			scanSourceDirectories(discoveryRuntime, resolvedRoot, configuredSourceDirs, { factoryProviders: shouldTrackFactoryProviders() });
+		},
+		loadContainer,
+		async writeContainerCache(filePath) {
+			const result = await loadContainer();
+			fs.mkdirSync(path.dirname(filePath), { recursive: true });
+			return writeFileIfChanged(filePath, result.code);
+		},
+		getWatchFiles() {
+			return providerModuleRefs.map((ref) => ref.absPath);
+		},
+		getWatchDirectories() {
+			return configuredSourceDirs.map((sourceDir) => path.isAbsolute(sourceDir) ? sourceDir : path.resolve(resolvedRoot, sourceDir));
+		}
+	};
+}
+function isAlloyDiscoverableFile(file) {
+	return isDiscoverableFile(file);
+}
+//#endregion
+export { ALLOY_PLUGIN_OPTIONS, createConsumerPluginContext, isAlloyDiscoverableFile };

package/dist/plugins/core/codegen.js

@@ -171,7 +171,7 @@ function reconstructOptionsText(meta, importMap, serviceRenames) {
 		const expr = reconstructDependencyExpression(factory, () => "", path.dirname(meta.filePath));
 		parts.push(`factory: ${expr}`);
 	}
-	if (scope === "singleton") parts.push(`scope: 'singleton'`);
+	if (scope && scope !== "transient") parts.push(`scope: '${escapeSingleQuotes(scope)}'`);
 	if (dependencies && dependencies.length > 0) {
 		const depExprs = dependencies.map((dep) => {
 			return reconstructDependencyExpression(dep, (ident) => {

package/dist/plugins/core/container-loader.js

@@ -5,10 +5,29 @@ import { augmentFactoryLazyServices, collectEagerReferencedNames, findDuplicateM
 import { validateScopeStability, validateScopesConfig } from "./scopes-validation.js";
 import { generateMermaidDiagram } from "./visualizer.js";
 import { ensureDirectoryForFile } from "./visualization-utils.js";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
 //#region src/plugins/core/container-loader.ts
 async function loadVirtualContainerModule(options) {
+	const prepared = await prepareContainerData(options);
+	const code = generateContainerModule(prepared.metas, prepared.lazyClassKeys, prepared.providerImports, {
+		isDev: options.isDevMode,
+		scopes: options.scopes
+	});
+	writeDeclarationArtifacts({
+		metas: prepared.metas,
+		loadedManifests: prepared.loadedManifests,
+		resolvedRoot: options.resolvedRoot,
+		containerDeclarationDir: options.containerDeclarationDir,
+		scopes: options.scopes
+	});
+	writeVisualizationArtifact(prepared.metas, prepared.lazyClassKeys, options.factoryProviders, options.resolvedVisualization, options.scopes);
+	return {
+		code,
+		moduleType: "js"
+	};
+}
+async function prepareContainerData(options) {
 	const metas = options.localMetas.map((meta) => ({
 		...meta,
 		metadata: { ...meta.metadata }
@@ -33,19 +52,13 @@ async function loadVirtualContainerModule(options) {
 	const providerImports = Array.from(new Set([...options.providerImportPaths, ...manifestData.providers]));
 	reconcileLazySet(metas, lazyClassKeys, collectEagerReferencedNames(metas));
 	augmentFactoryLazyServices(metas, options.lazyServiceKeys);
-	if (options.scopes && Object.keys(options.scopes).length > 0) {
-		validateScopesConfig(options.scopes);
-		validateScopeStability(metas, options.scopes);
-	}
-	const code = generateContainerModule(metas, lazyClassKeys, providerImports, {
-		isDev: options.isDevMode,
-		scopes: options.scopes
-	});
-	writeTypeDefinitions(metas, loadedManifests, options.resolvedRoot, options.containerDeclarationDir, options.scopes);
-	writeVisualizationArtifact(metas, lazyClassKeys, options.factoryProviders, options.resolvedVisualization, options.scopes);
+	if (options.scopes && Object.keys(options.scopes).length > 0) validateScopesConfig(options.scopes);
+	validateScopeStability(metas, options.scopes);
 	return {
-		code,
-		moduleType: "js"
+		metas,
+		loadedManifests,
+		lazyClassKeys,
+		providerImports
 	};
 }
 function assignIdentifierKeys(metas, packageName, resolvedRoot) {
@@ -70,13 +83,14 @@ function assertNoDuplicateManifestServices(metas, manifestServices) {
 		"Resolve by removing one source (local or manifest) to avoid ambiguous DI keys."
 	].join("\n"));
 }
-function writeTypeDefinitions(metas, loadedManifests, resolvedRoot, containerDeclarationDir, scopes) {
+function writeDeclarationArtifacts(options) {
+	const { metas, loadedManifests, resolvedRoot, containerDeclarationDir } = options;
 	const dtsDir = path.resolve(resolvedRoot, containerDeclarationDir ?? "./src");
 	const dtsContent = generateContainerTypeDefinition(metas, (filePath) => resolveDeclarationImportPath(dtsDir, filePath));
 	if (!fs.existsSync(dtsDir)) fs.mkdirSync(dtsDir, { recursive: true });
 	writeFileIfChanged(path.join(dtsDir, "alloy-container.d.ts"), dtsContent);
 	const scopeAugmentationPath = path.join(dtsDir, "alloy-scopes.d.ts");
-	const scopeAugmentation = generateScopeAugmentationDefinition(scopes ? Object.keys(scopes) : []);
+	const scopeAugmentation = generateScopeAugmentationDefinition(options.scopes ? Object.keys(options.scopes) : []);
 	if (scopeAugmentation) writeFileIfChanged(scopeAugmentationPath, scopeAugmentation);
 	else if (fs.existsSync(scopeAugmentationPath)) fs.rmSync(scopeAugmentationPath);
 	if (loadedManifests.length === 0) return;
@@ -106,4 +120,4 @@ function writeVisualizationArtifact(metas, lazyReferencedClassKeys, factoryProvi
 	writeFileIfChanged(resolvedVisualization.outputPath, `%% ${GENERATED_FILE_NOTICE}\n${artifact.diagram}\n`);
 }
 //#endregion
-export { loadVirtualContainerModule };
+export { loadVirtualContainerModule, prepareContainerData, writeDeclarationArtifacts };