alloy-di 1.2.0 → 1.2.3

package/dist/plugins/core/scanner.js

@@ -1,8 +1,10 @@
 import { createClassKey, createSymbolKey } from "./utils.js";
 import { extractServiceMetadata } from "./decorators.js";
-import { processLazyCall } from "./lazy.js";
+import { processLazyCall, resolveModuleSpecifierCandidates } from "./lazy.js";
+import fs from "node:fs";
 import ts, { SyntaxKind } from "typescript";
 //#region src/plugins/core/scanner.ts
+const ALLOY_RUNTIME_MODULE = "alloy-di/runtime";
 function collectFileImports(sourceFile) {
 	const imports = /* @__PURE__ */ new Map();
 	for (const statement of sourceFile.statements) if (ts.isImportDeclaration(statement) && statement.importClause && ts.isStringLiteral(statement.moduleSpecifier)) {
@@ -39,12 +41,14 @@ function scanSource(code, id) {
 	const discovered = /* @__PURE__ */ new Map();
 	const lazyRefs = /* @__PURE__ */ new Set();
 	const fileImports = collectFileImports(sourceFile);
+	const decoratorResolutionCache = /* @__PURE__ */ new Map();
 	const visit = (node) => {
 		if (ts.isClassDeclaration(node)) handleClassDeclaration(node, {
 			id,
 			sourceFile,
 			fileImports,
-			discovered
+			discovered,
+			decoratorResolutionCache
 		});
 		else if (ts.isCallExpression(node)) processLazyCall(node, id, sourceFile, lazyRefs);
 		ts.forEachChild(node, visit);
@@ -57,9 +61,9 @@ function scanSource(code, id) {
 }
 function handleClassDeclaration(node, context) {
 	if (!node.name) return;
-	const decoratorCall = findServiceDecorator(node, context.sourceFile);
-	if (!decoratorCall) return;
-	const decoratorName = decoratorCall.expression.getText(context.sourceFile);
+	const decoratorMatch = findServiceDecorator(node, context.sourceFile, context.fileImports, context.id, context.decoratorResolutionCache);
+	if (!decoratorMatch) return;
+	const { decoratorCall, decoratorName } = decoratorMatch;
 	const className = node.name.getText(context.sourceFile);
 	const metadata = extractServiceMetadata(decoratorName, decoratorCall, context.sourceFile);
 	const referencedImports = collectReferencedImports(metadata, context.fileImports);
@@ -72,15 +76,98 @@ function handleClassDeclaration(node, context) {
 		referencedImports
 	});
 }
-function findServiceDecorator(node, sourceFile) {
+function findServiceDecorator(node, sourceFile, fileImports, id, resolutionCache) {
 	const decorators = ts.getDecorators ? ts.getDecorators(node) : void 0;
 	if (!decorators?.length) return;
 	for (const decorator of decorators) {
-		if (!ts.isCallExpression(decorator.expression)) continue;
-		const name = decorator.expression.expression.getText(sourceFile);
-		if (name.endsWith("Injectable") || name.endsWith("Singleton")) return decorator.expression;
+		if (!ts.isCallExpression(decorator.expression)) {
+			warnOnBareAlloyDecorator(decorator, sourceFile, fileImports, id, resolutionCache);
+			continue;
+		}
+		const decoratorName = resolveDecoratorName(decorator.expression.expression, fileImports, id, new Set([id]), resolutionCache);
+		if (decoratorName) return {
+			decoratorCall: decorator.expression,
+			decoratorName
+		};
+	}
+}
+/**
+* Warn when an alloy decorator is applied bare (`@Injectable` instead of
+* `@Injectable()`). The scanner only registers call-expression decorators, so
+* the service would silently vanish from the container — and at runtime the
+* factory throws. Surfacing the location here makes the misuse findable at
+* build time.
+*/
+function warnOnBareAlloyDecorator(decorator, sourceFile, fileImports, id, resolutionCache) {
+	if (!ts.isIdentifier(decorator.expression) && !ts.isPropertyAccessExpression(decorator.expression)) return;
+	if (!resolveDecoratorName(decorator.expression, fileImports, id, new Set([id]), resolutionCache)) return;
+	const { line } = sourceFile.getLineAndCharacterOfPosition(decorator.getStart(sourceFile));
+	const appliedText = decorator.expression.getText(sourceFile);
+	console.warn(`[alloy] ${id}:${line + 1} applies @${appliedText} without calling it — use @${appliedText}(). The class will not be registered.`);
+}
+function resolveDecoratorName(expression, fileImports, id, visitedModules, resolutionCache) {
+	if (ts.isIdentifier(expression)) {
+		const importInfo = fileImports.get(expression.text);
+		if (!importInfo || importInfo.isTypeOnly) return;
+		return resolveImportedDecorator(importInfo.path, importInfo.originalName ?? expression.text, id, visitedModules, resolutionCache);
+	}
+	if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression)) {
+		const importInfo = fileImports.get(expression.expression.text);
+		if (!importInfo || importInfo.isTypeOnly || importInfo.originalName !== "*") return;
+		return resolveImportedDecorator(importInfo.path, expression.name.text, id, visitedModules, resolutionCache);
+	}
+}
+function resolveImportedDecorator(importPath, requestedName, fromId, visitedModules, resolutionCache) {
+	if (importPath === ALLOY_RUNTIME_MODULE) return isAlloyDecoratorName(requestedName) ? requestedName : void 0;
+	if (!importPath.startsWith(".")) return;
+	for (const candidate of resolveModuleSpecifierCandidates(fromId, importPath)) {
+		const cacheKey = `${candidate}:${requestedName}`;
+		const cached = resolutionCache.get(cacheKey);
+		if (cached) return cached;
+		if (cached === null) continue;
+		if (visitedModules.has(candidate) || !fs.existsSync(candidate)) continue;
+		visitedModules.add(candidate);
+		try {
+			const source = fs.readFileSync(candidate, "utf8");
+			const sourceFile = ts.createSourceFile(candidate, source, ts.ScriptTarget.ESNext, true);
+			const resolved = resolveDecoratorExport(requestedName, sourceFile, collectFileImports(sourceFile), candidate, visitedModules, resolutionCache);
+			resolutionCache.set(cacheKey, resolved ?? null);
+			if (resolved) return resolved;
+		} catch {
+			continue;
+		} finally {
+			visitedModules.delete(candidate);
+		}
 	}
 }
+function resolveDecoratorExport(requestedName, sourceFile, fileImports, id, visitedModules, resolutionCache) {
+	for (const statement of sourceFile.statements) {
+		if (!ts.isExportDeclaration(statement)) continue;
+		const moduleSpecifier = statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : void 0;
+		if (!statement.exportClause) {
+			if (!moduleSpecifier) continue;
+			const resolved = resolveImportedDecorator(moduleSpecifier, requestedName, id, visitedModules, resolutionCache);
+			if (resolved) return resolved;
+			continue;
+		}
+		if (!ts.isNamedExports(statement.exportClause)) continue;
+		for (const element of statement.exportClause.elements) {
+			if (element.name.text !== requestedName) continue;
+			const resolved = resolveNamedExportElement(element, moduleSpecifier, fileImports, id, visitedModules, resolutionCache);
+			if (resolved) return resolved;
+		}
+	}
+}
+function resolveNamedExportElement(element, moduleSpecifier, fileImports, id, visitedModules, resolutionCache) {
+	const sourceName = element.propertyName?.text ?? element.name.text;
+	if (moduleSpecifier) return resolveImportedDecorator(moduleSpecifier, sourceName, id, visitedModules, resolutionCache);
+	const importInfo = fileImports.get(sourceName);
+	if (!importInfo || importInfo.isTypeOnly) return;
+	return resolveImportedDecorator(importInfo.path, importInfo.originalName ?? sourceName, id, visitedModules, resolutionCache);
+}
+function isAlloyDecoratorName(name) {
+	return name === "Injectable" || name === "Singleton";
+}
 function collectReferencedImports(metadata, fileImports) {
 	const referenced = [];
 	const seen = /* @__PURE__ */ new Set();

package/dist/plugins/core/types.d.ts

@@ -1,7 +1,31 @@
 import { ServiceScope } from "../../lib/scope.js";
 
 //#region src/plugins/core/types.d.ts
-interface ManifestServiceDescriptor {
+interface ManifestTokenDependency {
+  exportName: string;
+  importPath: string;
+}
+interface ManifestLazyDependency {
+  exportName: string;
+  importPath: string;
+  retry?: {
+    retries: number;
+    backoffMs?: number;
+    factor?: number;
+  };
+}
+interface ManifestClassDependencyEntry {
+  kind: "class";
+  exportName: string;
+}
+interface ManifestTokenDependencyEntry extends ManifestTokenDependency {
+  kind: "token";
+}
+interface ManifestLazyDependencyEntry extends ManifestLazyDependency {
+  kind: "lazy";
+}
+type ManifestDependencyEntry = ManifestClassDependencyEntry | ManifestTokenDependencyEntry | ManifestLazyDependencyEntry;
+interface ManifestServiceDescriptorBase {
   exportName: string;
   importPath: string;
   /**
@@ -10,22 +34,17 @@ interface ManifestServiceDescriptor {
    */
   symbolKey: string;
   scope: ServiceScope;
+}
+interface ManifestServiceDescriptorV1 extends ManifestServiceDescriptorBase {
   deps: string[];
   /** Token dependencies (non-service identifiers) exported publicly by the package. */
-  tokenDeps?: {
-    exportName: string;
-    importPath: string;
-  }[];
-  lazyDeps: {
-    exportName: string;
-    importPath: string;
-    retry?: {
-      retries: number;
-      backoffMs?: number;
-      factor?: number;
-    };
-  }[];
+  tokenDeps?: ManifestTokenDependency[];
+  lazyDeps: ManifestLazyDependency[];
+}
+interface ManifestServiceDescriptorV2 extends ManifestServiceDescriptorBase {
+  deps: ManifestDependencyEntry[];
 }
+type ManifestServiceDescriptor = ManifestServiceDescriptorV1 | ManifestServiceDescriptorV2;
 interface AlloyManifest {
   schemaVersion: number;
   packageName: string;

package/dist/plugins/core/utils.js

@@ -18,7 +18,7 @@ function ensureLeadingSlash(value) {
 }
 function hashString(value) {
 	let hash = 0;
-	for (let i = 0; i < value.length; i++) hash = Math.trunc(hash * 31 + value.charCodeAt(i));
+	for (let i = 0; i < value.length; i++) hash = hash * 31 + value.charCodeAt(i) | 0;
 	return Math.abs(hash).toString(36);
 }
 function createClassKey(filePath, className) {

package/dist/plugins/rollup-plugin/index.js

@@ -1,4 +1,5 @@
 import { ServiceScope } from "../../lib/scope.js";
+import { parseLazyDependencyExpression, resolveModuleSpecifierCandidates } from "../core/lazy.js";
 import { createDiscoveryStore } from "../core/discovery-store.js";
 import { determineBuildMode, hasPreserveModules, resolveImportPathForBuild } from "./build-utils.js";
 import path from "node:path";
@@ -9,6 +10,31 @@ import ts from "typescript";
 function hasExportModifier(node) {
 	return !!(ts.canHaveModifiers(node) ? ts.getModifiers(node) : void 0)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
 }
+function getDependencyImports(meta, dep) {
+	const imports = meta.referencedImports ?? [];
+	if (imports.length === 0 || dep.referencedIdentifiers.length === 0) return [];
+	const identifiers = new Set(dep.referencedIdentifiers);
+	return imports.filter((entry) => identifiers.has(entry.name));
+}
+function getDependencyReferenceName(expression) {
+	const statement = ts.createSourceFile("dependency.ts", `const __dep = (${expression});`, ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS).statements[0];
+	if (!statement || !ts.isVariableStatement(statement)) return;
+	const initializer = statement.declarationList.declarations[0]?.initializer;
+	if (!initializer) return;
+	return extractReferenceNameFromExpression(initializer);
+}
+function extractReferenceNameFromExpression(expression) {
+	if (ts.isIdentifier(expression)) return expression.text;
+	if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+	if (ts.isAsExpression(expression) || ts.isParenthesizedExpression(expression) || ts.isNonNullExpression(expression) || ts.isTypeAssertionExpression(expression)) return extractReferenceNameFromExpression(expression.expression);
+}
+function resolveClassDependencyName(dep, meta, knownServiceNames) {
+	const imports = getDependencyImports(meta, dep);
+	for (const entry of imports) if (entry.originalName && knownServiceNames.has(entry.originalName)) return entry.originalName;
+	const referenceName = getDependencyReferenceName(dep.expression);
+	if (referenceName && knownServiceNames.has(referenceName)) return referenceName;
+	return dep.referencedIdentifiers.find((name) => knownServiceNames.has(name));
+}
 function alloy(options = {}) {
 	const fileName = options.fileName ?? "alloy.manifest.mjs";
 	const packageJsonFile = options.packageJsonPath ? path.isAbsolute(options.packageJsonPath) ? options.packageJsonPath : path.resolve(process.cwd(), options.packageJsonPath) : path.resolve(process.cwd(), "package.json");
@@ -83,6 +109,38 @@ function alloy(options = {}) {
 	function resolveImportPath(targetPath, buildMode) {
 		return resolveImportPathForBuild(targetPath, packageName, buildMode);
 	}
+	function resolveDependencyImportPath(specifier, sourceFilePath, buildMode) {
+		if (specifier.startsWith(".")) return resolveImportPath(resolveModuleSpecifierCandidates(sourceFilePath, specifier)[0] ?? path.resolve(path.dirname(sourceFilePath), specifier), buildMode);
+		if (path.isAbsolute(specifier)) return resolveImportPath(specifier, buildMode);
+		return specifier;
+	}
+	function createTokenDependency(dep, meta, buildMode) {
+		const preferredImport = getDependencyImports(meta, dep).find((entry) => entry.originalName !== "*");
+		return {
+			kind: "token",
+			exportName: preferredImport?.originalName ?? getDependencyReferenceName(dep.expression) ?? dep.referencedIdentifiers[0] ?? dep.expression,
+			importPath: preferredImport ? resolveDependencyImportPath(preferredImport.path, meta.filePath, buildMode) : packageName
+		};
+	}
+	function createManifestDependency(dep, meta, knownServiceNames, buildMode) {
+		if (dep.isLazy) {
+			const parsedLazy = parseLazyDependencyExpression(dep.expression, meta.filePath);
+			if (!parsedLazy) return null;
+			const entry = {
+				kind: "lazy",
+				exportName: parsedLazy.exportName,
+				importPath: resolveDependencyImportPath(parsedLazy.specifier, meta.filePath, buildMode)
+			};
+			if (parsedLazy.retry) entry.retry = parsedLazy.retry;
+			return entry;
+		}
+		const className = resolveClassDependencyName(dep, meta, knownServiceNames);
+		if (className) return {
+			kind: "class",
+			exportName: className
+		};
+		return createTokenDependency(dep, meta, buildMode);
+	}
 	return {
 		name: "alloy-manifest",
 		transform(code, id) {
@@ -108,55 +166,26 @@ function alloy(options = {}) {
 					importPath,
 					symbolKey,
 					scope,
-					deps: [],
-					lazyDeps: []
+					deps: []
 				});
 				if (buildMode !== "preserve-modules" && !exportedNames.has(meta.className)) missingExports.push(meta.className);
 			}
 			const serviceByName = /* @__PURE__ */ new Map();
-			for (const s of services) serviceByName.set(s.exportName, s);
-			const serviceTokenDeps = /* @__PURE__ */ new Map();
+			const knownServiceNames = /* @__PURE__ */ new Set();
+			for (const service of services) {
+				serviceByName.set(service.exportName, service);
+				knownServiceNames.add(service.exportName);
+			}
 			for (const metas of discovery.fileMetas.values()) for (const meta of metas) {
 				const svc = serviceByName.get(meta.className);
 				if (!svc) continue;
 				for (const dep of meta.metadata.dependencies) {
-					if (dep.isLazy) continue;
-					for (const name of dep.referencedIdentifiers) if (serviceByName.has(name)) svc.deps.push(name);
-					else {
-						const set = serviceTokenDeps.get(svc.exportName) ?? /* @__PURE__ */ new Set();
-						set.add(name);
-						serviceTokenDeps.set(svc.exportName, set);
-					}
+					const manifestDep = createManifestDependency(dep, meta, knownServiceNames, buildMode);
+					if (manifestDep) svc.deps.push(manifestDep);
 				}
 			}
-			for (const [id, refs] of discovery.fileLazyRefs.entries()) {
-				const metas = discovery.fileMetas.get(id) ?? [];
-				for (const meta of metas) {
-					const svc = serviceByName.get(meta.className);
-					if (!svc) continue;
-					const firstForExport = /* @__PURE__ */ new Map();
-					for (const key of refs) {
-						const [targetPath, exportName] = key.split("::");
-						if (!targetPath || !exportName) continue;
-						const importPath = resolveImportPath(targetPath, buildMode);
-						if (!firstForExport.has(exportName)) firstForExport.set(exportName, importPath);
-					}
-					for (const [exportName, importPath] of firstForExport.entries()) svc.lazyDeps.push({
-						exportName,
-						importPath
-					});
-				}
-			}
-			for (const [exportName, tokens] of serviceTokenDeps.entries()) {
-				const svc = serviceByName.get(exportName);
-				if (!svc || !tokens.size) continue;
-				svc.tokenDeps = Array.from(tokens).map((t) => ({
-					exportName: t,
-					importPath: packageName
-				}));
-			}
 			const manifest = {
-				schemaVersion: 1,
+				schemaVersion: 2,
 				packageName,
 				buildMode,
 				services,
@@ -187,7 +216,7 @@ function alloy(options = {}) {
 				}
 				manifest.providers = resolvedProviders;
 			}
-			const code = `// Generated Alloy manifest (v1)\nexport const manifest = ${JSON.stringify(manifest, null, 2)};\n`;
+			const code = `// Generated Alloy manifest (v2)\nexport const manifest = ${JSON.stringify(manifest, null, 2)};\n`;
 			const identifiersCode = ["// Generated Alloy Service Identifiers", ...services.map((s) => `export const ${s.exportName}Identifier = Symbol.for("${s.symbolKey}");`)].join("\n");
 			if (this.emitFile) {
 				this.emitFile({

package/dist/plugins/vite-plugin/container-loader.js

@@ -0,0 +1,95 @@
+import { normalizeImportPath } from "../core/utils.js";
+import { IdentifierResolver } from "../core/identifier-resolver.js";
+import { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition } from "../core/codegen.js";
+import { augmentFactoryLazyServices, collectEagerReferencedNames, findDuplicateManifestServices, groupMetasByName, readManifests, reconcileLazySet, toMetaFromManifest } from "./manifest-utils.js";
+import { generateMermaidDiagram } from "./visualizer.js";
+import { ensureDirectoryForFile } from "./visualization-utils.js";
+import path from "node:path";
+import fs from "node:fs";
+//#region src/plugins/vite-plugin/container-loader.ts
+async function loadVirtualContainerModule(options) {
+	const metas = options.localMetas.map((meta) => ({
+		...meta,
+		metadata: { ...meta.metadata }
+	}));
+	const lazyClassKeys = new Set(options.lazyReferencedClassKeys);
+	assignIdentifierKeys(metas, options.packageName, options.resolvedRoot);
+	const manifestData = await readManifests(options.manifests);
+	const manifestServices = manifestData.services;
+	const loadedManifests = manifestData.loadedManifests;
+	assertNoDuplicateManifestServices(metas, manifestServices);
+	const combinedMetas = [...metas, ...manifestServices.map((svc) => ({
+		className: svc.exportName,
+		filePath: svc.importPath,
+		metadata: {
+			scope: svc.scope,
+			dependencies: []
+		}
+	}))];
+	const resolver = new IdentifierResolver(combinedMetas);
+	const metasByName = groupMetasByName(combinedMetas);
+	for (const svc of manifestServices) metas.push(toMetaFromManifest(svc, metasByName, resolver, lazyClassKeys));
+	const providerImports = Array.from(new Set([...options.providerImportPaths, ...manifestData.providers]));
+	reconcileLazySet(metas, lazyClassKeys, collectEagerReferencedNames(metas));
+	augmentFactoryLazyServices(metas, options.lazyServiceKeys);
+	const code = generateContainerModule(metas, lazyClassKeys, providerImports);
+	writeTypeDefinitions(metas, loadedManifests, options.resolvedRoot, options.containerDeclarationDir);
+	writeVisualizationArtifact(metas, lazyClassKeys, options.resolvedVisualization);
+	return {
+		code,
+		moduleType: "js"
+	};
+}
+function assignIdentifierKeys(metas, packageName, resolvedRoot) {
+	for (const meta of metas) {
+		const normalizedMetaPath = normalizeImportPath(meta.filePath);
+		const trimmedNormalizedMetaPath = normalizedMetaPath.replaceAll(/^\/+/g, "");
+		const looksRootRelative = normalizedMetaPath === "/src" || normalizedMetaPath.startsWith("/src/");
+		let relPath = path.relative(resolvedRoot, meta.filePath);
+		if (path.sep === "\\") relPath = relPath.split(path.sep).join("/");
+		if (looksRootRelative || !relPath || relPath.startsWith("..") || relPath.startsWith("\\")) relPath = trimmedNormalizedMetaPath || normalizedMetaPath.replaceAll(/^\/+/g, "");
+		meta.identifierKey = `alloy:${packageName}/${relPath}#${meta.className}`;
+	}
+}
+function assertNoDuplicateManifestServices(metas, manifestServices) {
+	if (!metas.length || !manifestServices.length) return;
+	const duplicates = findDuplicateManifestServices(metas, manifestServices);
+	if (!duplicates.length) return;
+	const details = duplicates.map((d) => `- ${d.exportName}: local [${d.localPaths.join(", ")}] vs manifest '${d.manifestImport}'`).join("\n");
+	throw new Error([
+		"[alloy] Duplicate service registrations detected.",
+		details,
+		"Resolve by removing one source (local or manifest) to avoid ambiguous DI keys."
+	].join("\n"));
+}
+function writeTypeDefinitions(metas, loadedManifests, resolvedRoot, containerDeclarationDir) {
+	const dtsDir = path.resolve(resolvedRoot, containerDeclarationDir ?? "./src");
+	const dtsContent = generateContainerTypeDefinition(metas, (filePath) => resolveDeclarationImportPath(dtsDir, filePath));
+	if (!fs.existsSync(dtsDir)) fs.mkdirSync(dtsDir, { recursive: true });
+	fs.writeFileSync(path.join(dtsDir, "alloy-container.d.ts"), dtsContent);
+	if (loadedManifests.length === 0) return;
+	const manifestsDts = generateManifestTypeDefinition(loadedManifests.map((m) => ({
+		packageName: m.packageName,
+		services: m.services
+	})));
+	fs.writeFileSync(path.join(dtsDir, "alloy-manifests.d.ts"), manifestsDts);
+}
+function resolveDeclarationImportPath(dtsDir, filePath) {
+	if (!path.isAbsolute(filePath)) return filePath;
+	let rel = path.relative(dtsDir, filePath);
+	rel = rel.split(path.sep).join(path.posix.sep);
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return rel;
+}
+function writeVisualizationArtifact(metas, lazyReferencedClassKeys, resolvedVisualization) {
+	if (!resolvedVisualization) return;
+	const artifact = generateMermaidDiagram({
+		metas,
+		lazyClassKeys: new Set(lazyReferencedClassKeys),
+		options: resolvedVisualization.mermaidOptions
+	});
+	ensureDirectoryForFile(resolvedVisualization.outputPath);
+	fs.writeFileSync(resolvedVisualization.outputPath, `${artifact.diagram}\n`);
+}
+//#endregion
+export { loadVirtualContainerModule };

package/dist/plugins/vite-plugin/discovery-runtime.js

@@ -0,0 +1,76 @@
+import { createClassKey } from "../core/utils.js";
+import { createDiscoveryStore } from "../core/discovery-store.js";
+//#region src/plugins/vite-plugin/discovery-runtime.ts
+/** Files the discovery scanner processes (mirrors the transform hook filter). */
+function isDiscoverableFile(file) {
+	return /\.tsx?$/i.test(file) && !/\.d\.ts$/i.test(file) && !file.includes("node_modules");
+}
+/**
+* Serializes the codegen-relevant fields of a file's discovered metas so two
+* scans can be compared. Changes here (added/removed services, scope, deps,
+* factory, or resolved imports) mean the generated container must be rebuilt;
+* edits that leave them untouched (e.g. a method body) should not.
+*/
+function metasSignature(metas) {
+	return JSON.stringify(metas.map((m) => ({
+		className: m.className,
+		filePath: m.filePath,
+		scope: m.metadata.scope,
+		factory: m.metadata.factory?.expression ?? null,
+		dependencies: m.metadata.dependencies.map((d) => ({
+			expression: d.expression,
+			isLazy: d.isLazy,
+			referencedIdentifiers: d.referencedIdentifiers
+		})),
+		referencedImports: (m.referencedImports ?? []).map((r) => ({
+			name: r.name,
+			path: r.path,
+			originalName: r.originalName ?? null,
+			isTypeOnly: Boolean(r.isTypeOnly)
+		}))
+	})));
+}
+function lazyKeysSignature(keys) {
+	if (!keys || keys.size === 0) return "";
+	return Array.from(keys).toSorted().join("|");
+}
+function createDiscoveryRuntime() {
+	const discovery = createDiscoveryStore();
+	const discoveredClasses = /* @__PURE__ */ new Map();
+	const lazyReferencedClassKeys = /* @__PURE__ */ new Set();
+	return {
+		discoveredClasses,
+		lazyReferencedClassKeys,
+		processUpdate(id, code) {
+			const { metas, lazyClassKeys, previousMetas, previousLazyClassKeys } = discovery.updateFile(id, code);
+			if (previousMetas) for (const meta of previousMetas) discoveredClasses.delete(createClassKey(meta.filePath, meta.className));
+			for (const meta of metas) discoveredClasses.set(createClassKey(meta.filePath, meta.className), meta);
+			if (previousLazyClassKeys) for (const key of previousLazyClassKeys) lazyReferencedClassKeys.delete(key);
+			if (lazyClassKeys.size) for (const key of lazyClassKeys) lazyReferencedClassKeys.add(key);
+			return metasSignature(previousMetas ?? []) !== metasSignature(metas) || lazyKeysSignature(previousLazyClassKeys) !== lazyKeysSignature(lazyClassKeys);
+		},
+		removeDiscoveredFile(file) {
+			const removed = discovery.removeFile(file);
+			if (removed.previousMetas) for (const meta of removed.previousMetas) discoveredClasses.delete(createClassKey(meta.filePath, meta.className));
+			if (removed.previousLazyClassKeys) for (const key of removed.previousLazyClassKeys) lazyReferencedClassKeys.delete(key);
+			return Boolean(removed.previousMetas?.length || removed.previousLazyClassKeys?.size);
+		},
+		clear() {
+			discovery.clear();
+			discoveredClasses.clear();
+			lazyReferencedClassKeys.clear();
+		}
+	};
+}
+/**
+* Invalidate the generated container module in every environment's module
+* graph so its `load` hook re-runs and regenerates from current discovery.
+*/
+function invalidateContainerModule(server, resolvedVirtualModuleId) {
+	for (const environment of Object.values(server.environments)) {
+		const mod = environment.moduleGraph.getModuleById(resolvedVirtualModuleId);
+		if (mod) environment.moduleGraph.invalidateModule(mod);
+	}
+}
+//#endregion
+export { createDiscoveryRuntime, invalidateContainerModule, isDiscoverableFile };

package/dist/plugins/vite-plugin/index.d.ts

@@ -1,19 +1,9 @@
 import { ServiceIdentifier } from "../../lib/service-identifiers.js";
 import { AlloyManifest } from "../core/types.js";
-import { MermaidDiagramOptions } from "./visualizer.js";
+import { AlloyMermaidVisualizerOptions, AlloyVisualizationOptions } from "./visualization-utils.js";
 import { Plugin } from "vite";
 
 //#region src/plugins/vite-plugin/index.d.ts
-interface AlloyMermaidVisualizerOptions extends MermaidDiagramOptions {
-  outputPath?: string;
-}
-interface AlloyVisualizationOptions {
-  /**
-   * Configure Mermaid diagram emission. Use `true` for defaults or provide
-   * overrides for layout, colors, or output path.
-   */
-  mermaid?: boolean | AlloyMermaidVisualizerOptions;
-}
 interface AlloyPluginOptions {
   providers?: string[];
   /** Optional list of manifest objects to ingest */