alloy-di 1.2.3 → 1.4.0

package/dist/plugins/{vite-plugin → core}/container-loader.js

@@ -1,12 +1,13 @@
-import { normalizeImportPath } from "../core/utils.js";
-import { IdentifierResolver } from "../core/identifier-resolver.js";
-import { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition } from "../core/codegen.js";
+import { normalizeImportPath, writeFileIfChanged } from "./utils.js";
+import { IdentifierResolver } from "./identifier-resolver.js";
+import { GENERATED_FILE_NOTICE, generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition, generateScopeAugmentationDefinition } from "./codegen.js";
 import { augmentFactoryLazyServices, collectEagerReferencedNames, findDuplicateManifestServices, groupMetasByName, readManifests, reconcileLazySet, toMetaFromManifest } from "./manifest-utils.js";
+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";
-//#region src/plugins/vite-plugin/container-loader.ts
+//#region src/plugins/core/container-loader.ts
 async function loadVirtualContainerModule(options) {
 	const metas = options.localMetas.map((meta) => ({
 		...meta,
@@ -32,9 +33,16 @@ async function loadVirtualContainerModule(options) {
 	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);
+	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.resolvedVisualization, options.scopes);
 	return {
 		code,
 		moduleType: "js"
@@ -62,17 +70,21 @@ 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) {
+function writeTypeDefinitions(metas, loadedManifests, resolvedRoot, containerDeclarationDir, scopes) {
 	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);
+	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) : []);
+	if (scopeAugmentation) writeFileIfChanged(scopeAugmentationPath, scopeAugmentation);
+	else if (fs.existsSync(scopeAugmentationPath)) fs.rmSync(scopeAugmentationPath);
 	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);
+	writeFileIfChanged(path.join(dtsDir, "alloy-manifests.d.ts"), manifestsDts);
 }
 function resolveDeclarationImportPath(dtsDir, filePath) {
 	if (!path.isAbsolute(filePath)) return filePath;
@@ -81,15 +93,16 @@ function resolveDeclarationImportPath(dtsDir, filePath) {
 	if (!rel.startsWith(".")) rel = "./" + rel;
 	return rel;
 }
-function writeVisualizationArtifact(metas, lazyReferencedClassKeys, resolvedVisualization) {
+function writeVisualizationArtifact(metas, lazyReferencedClassKeys, resolvedVisualization, scopes) {
 	if (!resolvedVisualization) return;
 	const artifact = generateMermaidDiagram({
 		metas,
 		lazyClassKeys: new Set(lazyReferencedClassKeys),
-		options: resolvedVisualization.mermaidOptions
+		options: resolvedVisualization.mermaidOptions,
+		scopes
 	});
 	ensureDirectoryForFile(resolvedVisualization.outputPath);
-	fs.writeFileSync(resolvedVisualization.outputPath, `${artifact.diagram}\n`);
+	writeFileIfChanged(resolvedVisualization.outputPath, `%% ${GENERATED_FILE_NOTICE}\n${artifact.diagram}\n`);
 }
 //#endregion
 export { loadVirtualContainerModule };

package/dist/plugins/core/decorators.js

@@ -66,9 +66,9 @@ function parseDependencies(node, sourceFile) {
 	return [];
 }
 function extractServiceMetadata(decoratorName, callExpression, sourceFile) {
-	let scope = ServiceScope.TRANSIENT;
+	const isSingletonDecorator = decoratorName.endsWith("Singleton");
+	let scope = isSingletonDecorator ? ServiceScope.SINGLETON : ServiceScope.TRANSIENT;
 	let dependencies = [];
-	if (decoratorName.endsWith("Singleton")) scope = ServiceScope.SINGLETON;
 	const args = callExpression.arguments;
 	if (args.length === 0) return {
 		scope,
@@ -78,30 +78,20 @@ function extractServiceMetadata(decoratorName, callExpression, sourceFile) {
 	if (ts.isObjectLiteralExpression(firstArg)) {
 		for (const prop of firstArg.properties) if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
 			if (prop.name.text === "scope") {
-				if (ts.isStringLiteral(prop.initializer)) {
-					const val = prop.initializer.text;
-					if (val === "singleton") scope = ServiceScope.SINGLETON;
-					else if (val === "transient") scope = ServiceScope.TRANSIENT;
-				}
+				if (ts.isStringLiteralLike(prop.initializer)) scope = prop.initializer.text;
 			} else if (prop.name.text === "dependencies") dependencies = parseDependencies(prop.initializer, sourceFile);
 		}
-		if (decoratorName.endsWith("Singleton")) scope = ServiceScope.SINGLETON;
-		return {
-			scope,
-			dependencies
-		};
-	}
-	let depsNode;
-	if (ts.isStringLiteralLike(firstArg)) {
-		if (firstArg.text === "singleton") scope = ServiceScope.SINGLETON;
-	} else depsNode = firstArg;
-	if (args.length > 1) {
-		const secondArg = args[1];
-		if (ts.isStringLiteralLike(secondArg)) {
-			if (secondArg.text === "singleton") scope = ServiceScope.SINGLETON;
+	} else {
+		let depsNode;
+		if (ts.isStringLiteralLike(firstArg)) scope = firstArg.text;
+		else depsNode = firstArg;
+		if (args.length > 1) {
+			const secondArg = args[1];
+			if (ts.isStringLiteralLike(secondArg)) scope = secondArg.text;
 		}
+		if (depsNode) dependencies = parseDependencies(depsNode, sourceFile);
 	}
-	if (depsNode) dependencies = parseDependencies(depsNode, sourceFile);
+	if (isSingletonDecorator) scope = ServiceScope.SINGLETON;
 	return {
 		scope,
 		dependencies

package/dist/plugins/{vite-plugin → core}/discovery-runtime.js

@@ -1,6 +1,6 @@
-import { createClassKey } from "../core/utils.js";
-import { createDiscoveryStore } from "../core/discovery-store.js";
-//#region src/plugins/vite-plugin/discovery-runtime.ts
+import { createClassKey } from "./utils.js";
+import { createDiscoveryStore } from "./discovery-store.js";
+//#region src/plugins/core/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");
@@ -62,15 +62,5 @@ function createDiscoveryRuntime() {
 		}
 	};
 }
-/**
-* 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 };
+export { createDiscoveryRuntime, isDiscoverableFile };

package/dist/plugins/core/discovery-store.js

@@ -1,10 +1,14 @@
 import { scanSource } from "./scanner.js";
+import crypto from "node:crypto";
 //#region src/plugins/core/discovery-store.ts
 /**
 * Maintains a per-file cache of discovered DI metadata, lazy references, and
 * optionally source snapshots to drive incremental recompilation inside the
 * Alloy discovery pipeline.
 */
+function hashContent(code) {
+	return crypto.createHash("sha1").update(code).digest("hex");
+}
 /**
 * Creates a file-scoped discovery store that caches scanner output and
 * optionally the original source for diagnostics or incremental rebuilds.
@@ -15,6 +19,7 @@ import { scanSource } from "./scanner.js";
 function createDiscoveryStore(options = {}) {
 	const fileMetas = /* @__PURE__ */ new Map();
 	const fileLazyRefs = /* @__PURE__ */ new Map();
+	const fileContentHashes = /* @__PURE__ */ new Map();
 	const fileSources = options.trackSources ? /* @__PURE__ */ new Map() : void 0;
 	/**
 	* Scan and cache the latest metadata for a file, returning both the fresh
@@ -26,6 +31,14 @@ function createDiscoveryStore(options = {}) {
 	function updateFile(id, code) {
 		const previousMetas = fileMetas.get(id);
 		const previousLazyClassKeys = fileLazyRefs.get(id);
+		const contentHash = hashContent(code);
+		if (fileContentHashes.get(id) === contentHash) return {
+			metas: previousMetas ?? [],
+			lazyClassKeys: new Set(previousLazyClassKeys),
+			previousMetas,
+			previousLazyClassKeys
+		};
+		fileContentHashes.set(id, contentHash);
 		if (fileSources) fileSources.set(id, code);
 		const { metas, lazyClassKeys } = scanSource(code, id);
 		if (metas.length) fileMetas.set(id, metas);
@@ -49,6 +62,7 @@ function createDiscoveryStore(options = {}) {
 		const previousLazyClassKeys = fileLazyRefs.get(id);
 		fileMetas.delete(id);
 		fileLazyRefs.delete(id);
+		fileContentHashes.delete(id);
 		if (fileSources) fileSources.delete(id);
 		return {
 			previousMetas,
@@ -61,6 +75,7 @@ function createDiscoveryStore(options = {}) {
 	function clear() {
 		fileMetas.clear();
 		fileLazyRefs.clear();
+		fileContentHashes.clear();
 		fileSources?.clear();
 	}
 	return {

package/dist/plugins/{vite-plugin → core}/manifest-utils.js

@@ -1,6 +1,6 @@
-import { createClassKey, createSymbolKey, normalizeImportPath } from "../core/utils.js";
+import { createClassKey, createSymbolKey, normalizeImportPath } from "./utils.js";
 import { z } from "zod";
-//#region src/plugins/vite-plugin/manifest-utils.ts
+//#region src/plugins/core/manifest-utils.ts
 /**
 * Reads a list of manifest objects and returns aggregated service + provider module specifiers.
 *
@@ -83,9 +83,16 @@ async function readManifests(inputs) {
 function readManifestByVersion(manifest) {
 	return (manifest.schemaVersion ?? 1) === 2 ? readManifestV2(manifest) : readManifestV1(manifest);
 }
+function warnInvalidManifest(manifest, error) {
+	const packageName = typeof manifest.packageName === "string" && manifest.packageName ? manifest.packageName : "<unknown package>";
+	console.warn(`[alloy] Ignoring invalid manifest "${packageName}" — its services and providers will not be registered:\n${z.prettifyError(error)}`);
+}
 function readManifestV1(manifest) {
 	const parsed = manifestSchemaV1.safeParse(manifest);
-	if (!parsed.success) return null;
+	if (!parsed.success) {
+		warnInvalidManifest(manifest, parsed.error);
+		return null;
+	}
 	return {
 		schemaVersion: 1,
 		packageName: parsed.data.packageName,
@@ -98,7 +105,10 @@ function readManifestV1(manifest) {
 }
 function readManifestV2(manifest) {
 	const parsed = manifestSchemaV2.safeParse(manifest);
-	if (!parsed.success) return null;
+	if (!parsed.success) {
+		warnInvalidManifest(manifest, parsed.error);
+		return null;
+	}
 	return {
 		schemaVersion: 2,
 		packageName: parsed.data.packageName,

package/dist/plugins/core/scanner.js

@@ -36,7 +36,19 @@ function collectFileImports(sourceFile) {
 	}
 	return imports;
 }
+/**
+* Cheap pre-filter that avoids the TS parse for files that cannot contribute
+* discovery results: decorators require an `@` and lazy references require
+* the `Lazy` identifier.
+*/
+function mayContainDiscoverableSyntax(code) {
+	return code.includes("@") || code.includes("Lazy");
+}
 function scanSource(code, id) {
+	if (!mayContainDiscoverableSyntax(code)) return {
+		metas: [],
+		lazyClassKeys: /* @__PURE__ */ new Set()
+	};
 	const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.ESNext, true);
 	const discovered = /* @__PURE__ */ new Map();
 	const lazyRefs = /* @__PURE__ */ new Set();

package/dist/plugins/core/scopes-validation.d.ts

@@ -0,0 +1,19 @@
+//#region src/plugins/core/scopes-validation.d.ts
+/** Declared parent relationship for a single custom scope. */
+interface AlloyScopeConfig {
+  /**
+   * The next-longer-lived scope: either `"singleton"` or another custom scope.
+   * Defaults to `"singleton"` when omitted.
+   */
+  parent?: string;
+}
+/**
+ * Hierarchy of custom, application-defined scopes keyed by scope name. The two
+ * built-in lifecycles (`singleton` as the implicit root, `transient` as the
+ * implicit leaf) are never declared here.
+ */
+interface AlloyScopesConfig {
+  [scopeName: string]: AlloyScopeConfig;
+}
+//#endregion
+export { AlloyScopesConfig };

package/dist/plugins/core/scopes-validation.js

@@ -0,0 +1,225 @@
+import { normalizeImportPath } from "./utils.js";
+import path from "node:path";
+//#region src/plugins/core/scopes-validation.ts
+const SINGLETON = "singleton";
+const TRANSIENT = "transient";
+/**
+* Resolves a declared scope's parent, defaulting to the implicit `singleton`
+* root when omitted.
+*/
+function parentOf(config, name) {
+	return config[name]?.parent ?? SINGLETON;
+}
+/** Identifiers that never refer to a discoverable service in a dependency expression. */
+const RESERVED_IDENTIFIERS = new Set([
+	"Lazy",
+	"Symbol",
+	"Promise",
+	"import",
+	"this",
+	"arguments"
+]);
+/**
+* Validates the `scopes` plugin configuration in isolation (independent of any
+* discovered services). Catches authoring mistakes — redeclaring a built-in
+* scope, pointing at an unknown or illegal parent, or forming a cycle — and
+* throws a single actionable error. Returns silently when the config is empty
+* or valid.
+*/
+function validateScopesConfig(config) {
+	if (!config) return;
+	const names = Object.keys(config);
+	if (names.length === 0) return;
+	const errors = [];
+	for (const name of names) if (name === SINGLETON || name === TRANSIENT) errors.push(`- '${name}' is a built-in lifecycle and cannot be declared in 'scopes'.`);
+	for (const name of names) {
+		const declaredParent = parentOf(config, name);
+		if (declaredParent === TRANSIENT) errors.push(`- '${name}' declares 'transient' as its parent, but 'transient' is the implicit leaf and can never be a parent.`);
+		else if (declaredParent !== SINGLETON && !(declaredParent in config)) errors.push(`- '${name}' declares unknown parent '${declaredParent}'. Parents must be 'singleton' or another scope declared in 'scopes'.`);
+	}
+	for (const start of names) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = start;
+		while (current && current !== SINGLETON) {
+			if (seen.has(current)) {
+				errors.push(`- Cyclic scope hierarchy detected: ${[...seen, current].join(" -> ")}.`);
+				break;
+			}
+			seen.add(current);
+			current = current in config ? parentOf(config, current) : void 0;
+		}
+	}
+	if (errors.length) throw new Error(["[alloy] Invalid 'scopes' configuration:", ...dedupe(errors)].join("\n"));
+}
+/**
+* Returns the ancestor scopes of `scope` (longer-lived scopes it bubbles up
+* to), ordered nearest-first and always terminating with `singleton`. The
+* implicit `singleton` root has no ancestors; `transient` is the leaf and is
+* never an ancestor of anything.
+*/
+function getAncestorScopes(scope, config) {
+	if (scope === SINGLETON || scope === TRANSIENT) return [];
+	if (!(scope in config)) return [SINGLETON];
+	const ancestors = [];
+	let current = parentOf(config, scope);
+	const guard = /* @__PURE__ */ new Set();
+	while (current) {
+		if (guard.has(current)) break;
+		guard.add(current);
+		ancestors.push(current);
+		if (current === SINGLETON) break;
+		current = parentOf(config, current);
+	}
+	return ancestors;
+}
+/**
+* Decides whether a service in `hostScope` may depend on a service in
+* `depScope`. A service may depend only on services in its own scope or a
+* longer-lived (ancestor) scope. `transient` (the leaf) may depend on anything;
+* nothing longer-lived may depend on a `transient`.
+*/
+function isDependencyAllowed(hostScope, depScope, config) {
+	if (hostScope === TRANSIENT) return true;
+	if (depScope === hostScope) return true;
+	return getAncestorScopes(hostScope, config).includes(depScope);
+}
+/**
+* Validates the discovered service graph against the declared scope hierarchy:
+*
+* 1. **Unknown scope usage** — every service must declare a scope that is
+*    `singleton`, `transient`, or present in the `scopes` config.
+* 2. **Scope stability** — no service may depend on a shorter-lived
+*    (descendant) scope; such a captive dependency leaks the short-lived
+*    instance into its longer-lived host.
+*
+* All issues are gathered and reported together, mirroring the build's
+* circular-dependency diagnostics. Assumes `config` has already passed
+* {@link validateScopesConfig}.
+*/
+function validateScopeStability(metas, config) {
+	const scopesConfig = config ?? {};
+	const known = new Set([
+		SINGLETON,
+		TRANSIENT,
+		...Object.keys(scopesConfig)
+	]);
+	const { byClassName, byFilePath } = buildMetaIndexes(metas);
+	const unknownScopeErrors = [];
+	const violations = [];
+	for (const host of metas) {
+		const hostScope = host.metadata.scope;
+		if (!known.has(hostScope)) {
+			unknownScopeErrors.push(`- '${host.className}' declares unknown scope '${hostScope}'. Declare it in the 'scopes' plugin option or use a built-in lifecycle.`);
+			continue;
+		}
+		const visited = /* @__PURE__ */ new Set();
+		for (const dep of host.metadata.dependencies) for (const identifier of gatherIdentifiers(dep)) for (const target of resolveServiceMetas(identifier, host, byClassName, byFilePath)) {
+			if (target === host || visited.has(target)) continue;
+			visited.add(target);
+			const depScope = target.metadata.scope;
+			if (!known.has(depScope)) continue;
+			if (!isDependencyAllowed(hostScope, depScope, scopesConfig)) violations.push({
+				hostClassName: host.className,
+				hostScope,
+				hostFilePath: host.filePath,
+				depClassName: target.className,
+				depScope
+			});
+		}
+	}
+	if (!unknownScopeErrors.length && !violations.length) return;
+	const sections = [];
+	if (unknownScopeErrors.length) sections.push("[alloy] Unknown scope(s) used by discovered services:", ...dedupe(unknownScopeErrors));
+	if (violations.length) sections.push("[alloy] Scope stability violation(s) detected — a longer-lived service may only depend on equal- or longer-lived scopes:", ...dedupe(violations.map((v) => `- '${v.hostClassName}' (${v.hostScope}) depends on '${v.depClassName}' (${v.depScope}), a shorter-lived scope. The dependency would be captured and leak.`)));
+	throw new Error(sections.join("\n"));
+}
+function dedupe(values) {
+	return Array.from(new Set(values));
+}
+function buildMetaIndexes(metas) {
+	const byClassName = /* @__PURE__ */ new Map();
+	const byFilePath = /* @__PURE__ */ new Map();
+	for (const meta of metas) {
+		const classBucket = byClassName.get(meta.className) ?? [];
+		classBucket.push(meta);
+		byClassName.set(meta.className, classBucket);
+		const normalizedPath = normalizeImportPath(meta.filePath);
+		const pathBucket = byFilePath.get(normalizedPath) ?? [];
+		pathBucket.push(meta);
+		byFilePath.set(normalizedPath, pathBucket);
+	}
+	return {
+		byClassName,
+		byFilePath
+	};
+}
+/**
+* Collects the candidate service identifiers a dependency expression refers to.
+* Mirrors the visualizer's resolution so stability edges match the rendered
+* graph: prefer recorded references, fall back to inferring from the raw
+* expression for lazy imports.
+*/
+function gatherIdentifiers(dep) {
+	const identifiers = /* @__PURE__ */ new Set();
+	const ignored = new Set(dep.ignoredIdentifiers ?? []);
+	for (const ident of dep.referencedIdentifiers ?? []) {
+		const trimmed = ident.trim();
+		if (!trimmed || RESERVED_IDENTIFIERS.has(trimmed) || ignored.has(trimmed)) continue;
+		identifiers.add(trimmed);
+	}
+	if (!identifiers.size) for (const inferred of inferIdentifiersFromExpression(dep.expression)) {
+		const trimmed = inferred.trim();
+		if (!trimmed || RESERVED_IDENTIFIERS.has(trimmed) || ignored.has(trimmed)) continue;
+		identifiers.add(trimmed);
+	}
+	return Array.from(identifiers);
+}
+function inferIdentifiersFromExpression(expression) {
+	const matches = /* @__PURE__ */ new Set();
+	const thenPattern = /\.then\(\s*(?:\w+)\s*=>\s*\w+\.([A-Za-z_][A-Za-z0-9_]*)/g;
+	let match;
+	while ((match = thenPattern.exec(expression)) !== null) matches.add(match[1]);
+	if (!matches.size) {
+		const simple = expression.match(/([A-Za-z_][A-Za-z0-9_]*)$/);
+		if (simple) matches.add(simple[1]);
+	}
+	return Array.from(matches);
+}
+/**
+* Resolves a dependency identifier to the service metas it targets, using
+* recorded import references (by path + export name) with a class-name
+* fallback. Identifiers that resolve to no service (e.g. tokens) yield nothing.
+*/
+function resolveServiceMetas(identifier, meta, byClassName, byFilePath) {
+	const matches = [];
+	const importRef = meta.referencedImports?.find((ref) => !ref.isTypeOnly && ref.name === identifier);
+	if (importRef) {
+		const normalizedPath = resolveImportSpecifierPath(meta.filePath, importRef.path);
+		if (normalizedPath) {
+			const byPath = byFilePath.get(normalizedPath);
+			if (byPath?.length) {
+				if (importRef.originalName && importRef.originalName !== "*" && importRef.originalName !== "default") {
+					for (const candidate of byPath) if (candidate.className === importRef.originalName) matches.push(candidate);
+				}
+				if (!matches.length) matches.push(...byPath);
+			}
+		}
+		const fallbackName = importRef.originalName && importRef.originalName !== "*" && importRef.originalName !== "default" ? importRef.originalName : identifier;
+		const byName = byClassName.get(fallbackName);
+		if (byName) matches.push(...byName);
+	} else {
+		const byName = byClassName.get(identifier);
+		if (byName) matches.push(...byName);
+	}
+	return dedupeMetas(matches);
+}
+function dedupeMetas(metas) {
+	return Array.from(new Set(metas));
+}
+function resolveImportSpecifierPath(sourceFilePath, specifier) {
+	if (!specifier) return;
+	if (specifier.startsWith(".")) return normalizeImportPath(path.resolve(path.dirname(sourceFilePath), specifier));
+	return normalizeImportPath(specifier);
+}
+//#endregion
+export { isDependencyAllowed, validateScopeStability, validateScopesConfig };

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

@@ -1,6 +1,11 @@
-import { ServiceScope } from "../../lib/scope.js";
-
 //#region src/plugins/core/types.d.ts
+/**
+ * Build-time scope name. Unlike the runtime `ServiceScope` (a closed union of
+ * the two built-ins within the library's own compilation), discovered metadata
+ * may carry arbitrary, application-defined custom scope names (e.g. `session`,
+ * `request`) which are validated against the plugin `scopes` config.
+ */
+type BuildScope = string;
 interface ManifestTokenDependency {
   exportName: string;
   importPath: string;
@@ -33,7 +38,7 @@ interface ManifestServiceDescriptorBase {
    * Format: `alloy:<package-name>/<relative-path>#<ClassName>`
    */
   symbolKey: string;
-  scope: ServiceScope;
+  scope: BuildScope;
 }
 interface ManifestServiceDescriptorV1 extends ManifestServiceDescriptorBase {
   deps: string[];
@@ -59,4 +64,4 @@ interface AlloyManifest {
   };
 }
 //#endregion
-export { AlloyManifest };
+export { AlloyManifest, BuildScope };

package/dist/plugins/core/utils.js

@@ -30,14 +30,51 @@ function createAliasName(className, filePath) {
 function createSymbolKey(filePath, className) {
 	return `alloy:${normalizeImportPath(filePath)}#${className}`;
 }
-function walkSync(dir, fileList = []) {
-	if (!fs.existsSync(dir)) return fileList;
-	fs.readdirSync(dir).forEach((file) => {
-		const filePath = path.join(dir, file);
-		if (fs.statSync(filePath).isDirectory()) walkSync(filePath, fileList);
-		else fileList.push(filePath);
-	});
+const lastWrittenContent = /* @__PURE__ */ new Map();
+/**
+* Write a generated artifact only when its content actually changed.
+*
+* @returns true when the file was written, false when it already matched.
+*/
+function writeFileIfChanged(filePath, content) {
+	if (lastWrittenContent.get(filePath) === content) return false;
+	try {
+		if (fs.readFileSync(filePath, "utf-8") === content) {
+			lastWrittenContent.set(filePath, content);
+			return false;
+		}
+	} catch {}
+	fs.writeFileSync(filePath, content);
+	lastWrittenContent.set(filePath, content);
+	return true;
+}
+function walkSync(dir, fileList = [], visitedDirs) {
+	const visited = visitedDirs ?? /* @__PURE__ */ new Set();
+	let realDir;
+	try {
+		realDir = fs.realpathSync(dir);
+	} catch {
+		return fileList;
+	}
+	if (visited.has(realDir)) return fileList;
+	visited.add(realDir);
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".")) continue;
+		const filePath = path.join(dir, entry.name);
+		if (entry.isDirectory()) walkSync(filePath, fileList, visited);
+		else if (entry.isFile()) fileList.push(filePath);
+		else if (entry.isSymbolicLink()) {
+			let stat;
+			try {
+				stat = fs.statSync(filePath);
+			} catch {
+				continue;
+			}
+			if (stat.isDirectory()) walkSync(filePath, fileList, visited);
+			else if (stat.isFile()) fileList.push(filePath);
+		}
+	}
 	return fileList;
 }
 //#endregion
-export { createAliasName, createClassKey, createSymbolKey, hashString, normalizeImportPath, walkSync };
+export { createAliasName, createClassKey, createSymbolKey, hashString, normalizeImportPath, walkSync, writeFileIfChanged };

package/dist/plugins/{vite-plugin → core}/visualization-utils.d.ts

@@ -1,6 +1,6 @@
 import { MermaidDiagramOptions } from "./visualizer.js";
 
-//#region src/plugins/vite-plugin/visualization-utils.d.ts
+//#region src/plugins/core/visualization-utils.d.ts
 interface AlloyMermaidVisualizerOptions extends MermaidDiagramOptions {
   outputPath?: string;
 }

package/dist/plugins/{vite-plugin → core}/visualization-utils.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import fs from "node:fs";
-//#region src/plugins/vite-plugin/visualization-utils.ts
+//#region src/plugins/core/visualization-utils.ts
 const DEFAULT_MERMAID_FILENAME = "alloy-di.mmd";
 function resolveVisualizationOptions(input, projectRoot) {
 	if (!input) return null;

package/dist/plugins/{vite-plugin → core}/visualizer.d.ts

@@ -1,10 +1,10 @@
-import { ServiceScope } from "../../lib/scope.js";
+import { BuildScope } from "./types.js";
 
-//#region src/plugins/vite-plugin/visualizer.d.ts
+//#region src/plugins/core/visualizer.d.ts
 interface MermaidDiagramOptions {
   direction?: "LR" | "TB" | "BT" | "RL";
   includeLegend?: boolean;
-  scopeColors?: Partial<Record<ServiceScope, string>>;
+  scopeColors?: Partial<Record<BuildScope, string>>;
   lazyNodeFill?: string;
   factoryNodeFill?: string;
   tokenNodeFill?: string;