alloy-di 0.1.0

package/dist/lib/testing/mocking.js

@@ -0,0 +1,109 @@
+import { isConstructor } from "../types.js";
+import { isLazy } from "../lazy.js";
+import { getRawDependencies } from "./registry.js";
+import { vi } from "vitest";
+
+//#region src/lib/testing/mocking.ts
+/** Create a lightweight auto-mock instance for a class constructor. */
+function mockClass(ctor) {
+	const proto = ctor.prototype;
+	const spies = {};
+	const mockObj = {
+		spies,
+		__target: ctor
+	};
+	for (const key of Object.getOwnPropertyNames(proto)) {
+		if (key === "constructor") continue;
+		if (typeof proto[key] === "function") {
+			const fn = vi.fn();
+			spies[key] = fn;
+			mockObj[key] = fn;
+		}
+	}
+	return {
+		target: ctor,
+		mock: mockObj
+	};
+}
+function collectDependencyGraph(target) {
+	const constructors = /* @__PURE__ */ new Set();
+	const lazyDependencies = [];
+	const queue = [target];
+	const visited = /* @__PURE__ */ new Set();
+	while (queue.length) {
+		const current = queue.shift();
+		if (!current || visited.has(current)) continue;
+		visited.add(current);
+		constructors.add(current);
+		const deps = getRawDependencies(current);
+		for (const dep of deps) {
+			if (isLazy(dep)) {
+				lazyDependencies.push({ lazy: dep });
+				continue;
+			}
+			if (isConstructor(dep)) queue.push(dep);
+		}
+	}
+	return {
+		constructors,
+		lazyDependencies
+	};
+}
+function createMocksForConstructors(constructors, target, overrides) {
+	const mocks = /* @__PURE__ */ new Map();
+	for (const ctor of constructors) {
+		if (ctor === target) continue;
+		if (overrides.has(ctor)) continue;
+		const classMock = mockClass(ctor);
+		mocks.set(ctor, classMock.mock);
+	}
+	return mocks;
+}
+function applyMocksToContainer(container, mocks) {
+	for (const [ctor, mock] of mocks.entries()) container.overrideInstance(ctor, mock);
+}
+function patchLazyDependencies(lazyDeps, mocks, overrides) {
+	const patches = [];
+	for (const { lazy } of lazyDeps) {
+		const originalImporter = lazy.importer;
+		lazy.importer = async () => {
+			const realCtor = await originalImporter();
+			let mockObj = mocks.get(realCtor);
+			if (!overrides.has(realCtor) && !mockObj) {
+				mockObj = mockClass(realCtor).mock;
+				mocks.set(realCtor, mockObj);
+			}
+			if (!mockObj) return realCtor;
+			return buildMockCtorFrom(realCtor, mockObj);
+		};
+		patches.push({
+			lazy,
+			originalImporter
+		});
+	}
+	return patches;
+}
+/** Traverse dependency graph (deep) and create class mocks, including lazy deps. */
+function applyAutoMocks(options) {
+	const { target, container, overridesCtors } = options;
+	const graph = collectDependencyGraph(target);
+	const mocks = createMocksForConstructors(graph.constructors, target, overridesCtors);
+	applyMocksToContainer(container, mocks);
+	return {
+		mocks,
+		lazyPatches: patchLazyDependencies(graph.lazyDependencies, mocks, overridesCtors)
+	};
+}
+/** Build a class constructor that exposes spies from a mock object via prototype methods */
+function buildMockCtorFrom(realCtor, mock) {
+	function MockCtor() {}
+	const proto = realCtor.prototype;
+	for (const key of Object.getOwnPropertyNames(proto)) {
+		if (key === "constructor") continue;
+		if (typeof proto[key] === "function" && key in mock.spies) MockCtor.prototype[key] = mock.spies[key];
+	}
+	return MockCtor;
+}
+
+//#endregion
+export { applyAutoMocks };

package/dist/lib/testing/registry.js

@@ -0,0 +1,19 @@
+import { dependenciesRegistry } from "../decorators.js";
+
+//#region src/lib/testing/registry.ts
+/** Take a deep(ish) snapshot of current dependency registry state. */
+function snapshotRegistry() {
+	return new Map(dependenciesRegistry);
+}
+/** Restore dependency registry from a prior snapshot. */
+function restoreRegistry(snapshot) {
+	dependenciesRegistry.clear();
+	for (const [k, v] of snapshot.entries()) dependenciesRegistry.set(k, v);
+}
+/** Get raw declared dependencies including constructors, Lazy and Tokens */
+function getRawDependencies(target) {
+	return (dependenciesRegistry.get(target)?.dependencies ?? (() => []))();
+}
+
+//#endregion
+export { getRawDependencies, restoreRegistry, snapshotRegistry };

package/dist/lib/types.d.ts

@@ -0,0 +1,22 @@
+//#region src/lib/types.d.ts
+/**
+ * Represents a class constructor with arbitrary parameters.
+ * We intentionally use `any[]` here because the DI container never inspects
+ * constructor parameter types at runtime and widening to `unknown[]` causes
+ * TypeScript incompatibilities (strict contravariance) when passing concrete
+ * constructor signatures. Using `any` preserves ergonomic usage while remaining
+ * safe: instantiation is delegated to the actual class.
+ */
+type Newable<T> = new (...args: any[]) => T;
+/** Generic constructor shape (helper for internal checks). */
+type Constructor = new (...args: any[]) => unknown;
+/** Typed token for non-class values or abstract contracts. */
+interface Token<T> {
+  readonly id: symbol;
+  readonly description?: string;
+  readonly __type?: T;
+}
+/** Create a unique typed token for values or abstractions. */
+declare function createToken<T>(description?: string): Token<T>;
+//#endregion
+export { Constructor, Newable, Token, createToken };

package/dist/lib/types.js

@@ -0,0 +1,21 @@
+//#region src/lib/types.ts
+/** Create a unique typed token for values or abstractions. */
+function createToken(description) {
+	return {
+		id: Symbol(description),
+		description
+	};
+}
+function isToken(value) {
+	return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, "id") && typeof value.id === "symbol";
+}
+function isConstructor(value) {
+	if (typeof value !== "function") return false;
+	const proto = value.prototype;
+	if (!proto || typeof proto !== "object") return false;
+	if (proto.constructor !== value) return false;
+	return true;
+}
+
+//#endregion
+export { createToken, isConstructor, isToken };

package/dist/plugins/core/codegen.js

@@ -0,0 +1,288 @@
+import { createClassKey, createSymbolKey, hashString, normalizeImportPath } from "./utils.js";
+import { IdentifierResolver } from "./identifier-resolver.js";
+import path from "node:path";
+
+//#region src/plugins/core/codegen.ts
+function escapeSingleQuotes(value) {
+	return value.replace(/'/g, "\\'");
+}
+/**
+* Generates a unique export key for the service identifier map.
+* If there are name collisions (multiple classes with same name), it appends a hash of the file path.
+*/
+function createIdentifierExportKey(meta, resolver) {
+	if (resolver.count(meta.className) <= 1) return meta.className;
+	const hash = hashString(normalizeImportPath(meta.filePath));
+	return `${meta.className}_${hash}`;
+}
+function createSymbolDescription(meta) {
+	return createSymbolKey(meta.filePath, meta.className);
+}
+/**
+* Analyzes dependencies across all discovered services and resolves imports.
+* Deduplicates imports and handles naming collisions by generating unique local names.
+*/
+function resolveDependencyImports(metas) {
+	const importMap = /* @__PURE__ */ new Map();
+	const nameCounts = /* @__PURE__ */ new Map();
+	const getUniqueName = (name) => {
+		const count = nameCounts.get(name) || 0;
+		nameCounts.set(name, count + 1);
+		return count === 0 ? name : `${name}_${count}`;
+	};
+	for (const meta of metas) if (meta.referencedImports) for (const ref of meta.referencedImports) {
+		if (ref.isTypeOnly) continue;
+		const dir = path.dirname(meta.filePath);
+		const normalizedPath = normalizeImportPath(ref.path.startsWith(".") ? path.resolve(dir, ref.path) : ref.path);
+		const key = `${normalizedPath}::${ref.originalName ?? "default"}`;
+		let resolved = importMap.get(key);
+		if (!resolved) {
+			resolved = {
+				localName: getUniqueName(ref.name),
+				importPath: normalizedPath,
+				originalName: ref.originalName
+			};
+			importMap.set(key, resolved);
+		}
+	}
+	return {
+		dependencyImports: Array.from(importMap.values()),
+		importMap
+	};
+}
+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.replace(new RegExp(`\\b${ident}\\b`, "g"), replacement);
+	}
+	if (dep.isLazy) expr = expr.replace(/import\s*\(\s*(['"])(.+?)\1\s*\)/g, (match, quote, importPath) => {
+		if (importPath.startsWith(".")) return `import(${quote}${normalizeImportPath(path.resolve(contextDir, importPath))}${quote})`;
+		return match;
+	});
+	return expr;
+}
+function reconstructOptionsText(meta, importMap) {
+	const { scope, dependencies, factory } = meta.metadata;
+	const parts = [];
+	if (factory) {
+		const expr = reconstructDependencyExpression(factory, () => "", path.dirname(meta.filePath));
+		parts.push(`factory: ${expr}`);
+	}
+	if (scope === "singleton") parts.push(`scope: 'singleton'`);
+	if (dependencies && dependencies.length > 0) {
+		const depExprs = dependencies.map((dep) => {
+			return reconstructDependencyExpression(dep, (ident) => {
+				const ref = meta.referencedImports?.find((r) => r.name === ident && !r.isTypeOnly);
+				if (ref) {
+					const dir = path.dirname(meta.filePath);
+					const key = `${normalizeImportPath(ref.path.startsWith(".") ? path.resolve(dir, ref.path) : ref.path)}::${ref.originalName ?? "default"}`;
+					const resolved = importMap.get(key);
+					return resolved ? resolved.localName : ident;
+				}
+				return ident;
+			}, path.dirname(meta.filePath));
+		});
+		parts.push(`dependencies: () => [${depExprs.join(", ")}]`);
+	}
+	if (parts.length === 0) return "{}";
+	return `{ ${parts.join(", ")} }`;
+}
+function buildImportsAndRegistrations(metas, lazyReferencedClassKeys, hasProviderModules) {
+	const activeMetas = metas.filter((meta) => !lazyReferencedClassKeys.has(createClassKey(meta.filePath, meta.className)));
+	const { dependencyImports, importMap } = resolveDependencyImports(activeMetas);
+	const resolver = new IdentifierResolver(activeMetas);
+	const resolvedImports = activeMetas.map((meta) => {
+		const importName = resolver.resolve(meta.className, meta.filePath);
+		const isFactoryLazy = !!meta.metadata.factory;
+		const identifierConst = `${importName}Identifier`;
+		const exportKey = createIdentifierExportKey(meta, resolver);
+		const symbolDescription = meta.identifierKey ?? createSymbolDescription(meta);
+		const optionsText = reconstructOptionsText(meta, importMap);
+		return {
+			...meta,
+			importName,
+			isFactoryLazy,
+			identifierConst,
+			exportKey,
+			symbolDescription,
+			optionsText
+		};
+	});
+	const needsLazyImport = activeMetas.some((m) => m.metadata.dependencies.some((d) => d.isLazy) || !!m.metadata.factory);
+	const runtimeImports = new Set(["Container", "dependenciesRegistry"]);
+	if (hasProviderModules) runtimeImports.add("applyProviders");
+	if (needsLazyImport) runtimeImports.add("Lazy");
+	if (resolvedImports.length) runtimeImports.add("registerServiceIdentifier");
+	const runtimeImportStatement = `\nimport { ${Array.from(runtimeImports).join(", ")} } from 'alloy-di/runtime';\n`;
+	const stubDeclarations = [];
+	const importedNames = new Set(runtimeImports);
+	for (const dep of dependencyImports) {
+		if (dep.importPath === "alloy-di/runtime" && dep.originalName && dep.localName === dep.originalName && runtimeImports.has(dep.originalName)) continue;
+		if (importedNames.has(dep.localName)) continue;
+		if (dep.originalName === "default") stubDeclarations.push(`import ${dep.localName} from '${dep.importPath}';`);
+		else if (dep.originalName === "*") stubDeclarations.push(`import * as ${dep.localName} from '${dep.importPath}';`);
+		else if (dep.originalName && dep.originalName !== dep.localName) stubDeclarations.push(`import { ${dep.originalName} as ${dep.localName} } from '${dep.importPath}';`);
+		else stubDeclarations.push(`import { ${dep.localName} } from '${dep.importPath}';`);
+		importedNames.add(dep.localName);
+	}
+	for (const meta of resolvedImports) {
+		if (meta.isFactoryLazy) {
+			stubDeclarations.push(`class ${meta.importName} {}`);
+			continue;
+		}
+		if (importedNames.has(meta.importName)) continue;
+		const importPath = !/^(\/|[A-Za-z]:\\|\.|~)/.test(meta.filePath) && !meta.filePath.includes("\\") ? meta.filePath : normalizeImportPath(meta.filePath);
+		if (meta.importName === meta.className) stubDeclarations.push(`import { ${meta.className} } from '${importPath}';`);
+		else stubDeclarations.push(`import { ${meta.className} as ${meta.importName} } from '${importPath}';`);
+		importedNames.add(meta.importName);
+	}
+	const registrationEntries = resolvedImports.map((m) => `  { ctor: ${m.importName}, meta: ${m.optionsText} }`).join(",\n");
+	const registrationsBlock = registrationEntries ? `const registrations = [\n${registrationEntries}\n];` : `const registrations = [];`;
+	const stubsBlock = stubDeclarations.length ? `${stubDeclarations.join("\n")}\n` : "";
+	const identifierDeclarations = resolvedImports.map((meta) => `const ${meta.identifierConst} = registerServiceIdentifier(${meta.importName}, Symbol.for('${escapeSingleQuotes(meta.symbolDescription)}'));`).join("\n");
+	const identifierExportEntries = resolvedImports.map((meta) => `  '${meta.exportKey}': ${meta.identifierConst}`).join(",\n");
+	return {
+		runtimeImportStatement,
+		registrationsBlock,
+		stubsBlock,
+		identifierDeclarations,
+		identifierExportBlock: resolvedImports.length ? `${identifierDeclarations}\n\nexport const serviceIdentifiers = {\n${identifierExportEntries}\n};\n` : `export const serviceIdentifiers = {};\n`
+	};
+}
+/**
+* Generates the virtual container module code.
+* This module:
+* 1. Imports the runtime container and necessary helpers.
+* 2. Imports all discovered service classes (or creates stubs for factory-lazy services).
+* 3. Registers each service with the global `dependenciesRegistry`.
+* 4. Applies any configured providers.
+* 5. Exports the configured `Container` instance as default.
+* 6. Exports `serviceIdentifiers` map for consumers to use safe injection keys.
+*
+* @param metas - List of discovered services.
+* @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) {
+	const hasProviderModules = providerModulePaths.length > 0;
+	const { runtimeImportStatement, registrationsBlock, stubsBlock, identifierExportBlock } = buildImportsAndRegistrations(metas, lazyReferencedClassKeys, hasProviderModules);
+	let providerImportBlock = "";
+	let providerInvocationBlock = "";
+	if (hasProviderModules) {
+		const aliasNames = providerModulePaths.map((_, idx) => `providers_${idx}`);
+		providerImportBlock = providerModulePaths.map((p, idx) => `import ${aliasNames[idx]} from '${p}';`).join("\n") + "\n";
+		providerInvocationBlock = `\nconst providerDefinitions = [${aliasNames.join(", ")}];\nfor (const definition of providerDefinitions) {\n  applyProviders(container, definition);\n}\n`;
+	}
+	return `
+${runtimeImportStatement}${stubsBlock}
+${providerImportBlock}
+${registrationsBlock}
+
+const container = new Container();
+
+for (const entry of registrations) {
+  dependenciesRegistry.set(entry.ctor, entry.meta);
+}
+${providerInvocationBlock}${identifierExportBlock}
+export default container;
+`;
+}
+/**
+* Generates the TypeScript declaration definition (`.d.ts`) for the virtual container module.
+* It exports the `ServiceIdentifiers` interface matching the runtime exports.
+*
+* @param metas - List of discovered services.
+* @param pathResolver - Function to resolve absolute file paths to import paths relative to the declaration file location.
+*/
+function generateContainerTypeDefinition(metas, pathResolver) {
+	const resolver = new IdentifierResolver(metas);
+	const imports = [];
+	const interfaceMembers = [];
+	for (const meta of metas) {
+		const importName = resolver.resolve(meta.className, meta.filePath);
+		const importPath = pathResolver(meta.filePath);
+		if (importName === meta.className) imports.push(`import { ${meta.className} } from '${importPath}';`);
+		else imports.push(`import { ${meta.className} as ${importName} } from '${importPath}';`);
+		const exportKey = createIdentifierExportKey(meta, resolver);
+		interfaceMembers.push(`${exportKey}: ServiceIdentifier<${importName}>;`);
+	}
+	return `
+declare module "virtual:alloy-container" {
+  import { Container, ServiceIdentifier } from "alloy-di/runtime";
+  ${imports.length ? imports.join("\n") + "\n" : ""}
+  export interface ServiceIdentifiers {
+    ${interfaceMembers.length ? interfaceMembers.join("\n    ") : ""}
+  }
+
+  export const serviceIdentifiers: ServiceIdentifiers;
+
+  const container: Container;
+  export default container;
+}
+`;
+}
+/**
+* Generates ambient type declarations for external Alloy manifests consumed by the project.
+* Creates:
+* 1. `declare module "PKG/manifest"` typed as `LibraryManifest`.
+* 2. `declare module "PKG/service-identifiers"` exporting typed `ServiceIdentifier` constants.
+*
+* @param manifests - List of loaded manifest info (packageName and services).
+*/
+function generateManifestTypeDefinition(manifests) {
+	return manifests.map((m) => {
+		const serviceIdentifiers = m.services.map((s) => `  export const ${s.exportName}Identifier: ServiceIdentifier;`).join("\n");
+		return `
+declare module "${m.packageName}/manifest" {
+  type ServiceScope = "singleton" | "transient";
+
+  interface ManifestLazyDependency {
+    exportName: string;
+    importPath: string;
+    retry?: {
+      retries: number;
+      backoffMs?: number;
+      factor?: number;
+    };
+  }
+
+  interface ManifestTokenDependency {
+    exportName: string;
+    importPath: string;
+    symbolKey?: string;
+  }
+
+  interface ManifestService {
+    exportName: string;
+    importPath: string;
+    symbolKey: string;
+    scope: ServiceScope;
+    deps: string[];
+    lazyDeps: ManifestLazyDependency[];
+    tokenDeps?: ManifestTokenDependency[];
+  }
+
+  interface LibraryManifest {
+    schemaVersion: number;
+    packageName: string;
+    buildMode: "preserve-modules" | "bundled" | "chunks";
+    services: ManifestService[];
+    providers: string[];
+    diagnostics?: Record<string, unknown>;
+  }
+
+  export const manifest: LibraryManifest;
+  export default manifest;
+}
+
+declare module "${m.packageName}/service-identifiers" {
+  import { ServiceIdentifier } from "alloy-di/runtime";
+${serviceIdentifiers}
+}
+`;
+	}).join("\n");
+}
+
+//#endregion
+export { generateContainerModule, generateContainerTypeDefinition, generateManifestTypeDefinition };

package/dist/plugins/core/decorators.js

@@ -0,0 +1,90 @@
+import { ServiceScope } from "../../lib/scope.js";
+import ts from "typescript";
+
+//#region src/plugins/core/decorators.ts
+function extractRefs(node, sourceFile, identifiers) {
+	if (ts.isPropertyAssignment(node)) {
+		extractRefs(node.initializer, sourceFile, identifiers);
+		if (ts.isComputedPropertyName(node.name)) extractRefs(node.name.expression, sourceFile, identifiers);
+		return;
+	}
+	if (ts.isIdentifier(node)) {
+		identifiers.add(node.text);
+		return;
+	}
+	if (ts.isCallExpression(node)) {
+		const name = node.expression.getText(sourceFile);
+		if (name === "Lazy" || name.endsWith(".Lazy")) {
+			node.arguments.forEach((arg) => extractRefs(arg, sourceFile, identifiers));
+			return;
+		}
+	}
+	ts.forEachChild(node, (n) => extractRefs(n, sourceFile, identifiers));
+}
+function createDependencyDescriptor(node, sourceFile) {
+	const expression = node.getText(sourceFile);
+	const referencedIdentifiers = /* @__PURE__ */ new Set();
+	let isLazy = false;
+	if (ts.isCallExpression(node)) {
+		const callName = node.expression.getText(sourceFile);
+		if (callName === "Lazy" || callName.endsWith(".Lazy")) isLazy = true;
+	}
+	extractRefs(node, sourceFile, referencedIdentifiers);
+	return {
+		expression,
+		referencedIdentifiers: Array.from(referencedIdentifiers),
+		isLazy
+	};
+}
+function parseDependencies(node, sourceFile) {
+	if (ts.isArrowFunction(node)) return parseDependencies(node.body, sourceFile);
+	if (ts.isParenthesizedExpression(node)) return parseDependencies(node.expression, sourceFile);
+	if (ts.isCallExpression(node)) return node.arguments.map((arg) => createDependencyDescriptor(arg, sourceFile));
+	if (ts.isArrayLiteralExpression(node)) return node.elements.map((arg) => createDependencyDescriptor(arg, sourceFile));
+	return [];
+}
+function extractServiceMetadata(decoratorName, callExpression, sourceFile) {
+	let scope = ServiceScope.TRANSIENT;
+	let dependencies = [];
+	if (decoratorName.endsWith("Singleton")) scope = ServiceScope.SINGLETON;
+	const args = callExpression.arguments;
+	if (args.length === 0) return {
+		scope,
+		dependencies
+	};
+	const firstArg = args[0];
+	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;
+				}
+			} 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;
+		}
+	}
+	if (depsNode) dependencies = parseDependencies(depsNode, sourceFile);
+	return {
+		scope,
+		dependencies
+	};
+}
+
+//#endregion
+export { extractServiceMetadata };

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

@@ -0,0 +1,78 @@
+import { scanSource } from "./scanner.js";
+
+//#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.
+*/
+/**
+* Creates a file-scoped discovery store that caches scanner output and
+* optionally the original source for diagnostics or incremental rebuilds.
+*
+* @param options.trackSources - When true, persist the full source text.
+* @returns An object exposing cache maps plus mutation helpers.
+*/
+function createDiscoveryStore(options = {}) {
+	const fileMetas = /* @__PURE__ */ new Map();
+	const fileLazyRefs = /* @__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
+	* scan results and whatever was previously stored for diff consumers.
+	*
+	* @param id - Module identifier or path.
+	* @param code - Current file contents to analyze.
+	*/
+	function updateFile(id, code) {
+		const previousMetas = fileMetas.get(id);
+		const previousLazyClassKeys = fileLazyRefs.get(id);
+		if (fileSources) fileSources.set(id, code);
+		const { metas, lazyClassKeys } = scanSource(code, id);
+		if (metas.length) fileMetas.set(id, metas);
+		else fileMetas.delete(id);
+		if (lazyClassKeys.size) fileLazyRefs.set(id, lazyClassKeys);
+		else fileLazyRefs.delete(id);
+		return {
+			metas,
+			lazyClassKeys,
+			previousMetas,
+			previousLazyClassKeys
+		};
+	}
+	/**
+	* Purge all cached information for a given file.
+	*
+	* @param id - Module identifier or path being removed.
+	*/
+	function removeFile(id) {
+		const previousMetas = fileMetas.get(id);
+		const previousLazyClassKeys = fileLazyRefs.get(id);
+		fileMetas.delete(id);
+		fileLazyRefs.delete(id);
+		if (fileSources) fileSources.delete(id);
+		return {
+			previousMetas,
+			previousLazyClassKeys
+		};
+	}
+	/**
+	* Clear every cached entry, including optional source snapshots.
+	*/
+	function clear() {
+		fileMetas.clear();
+		fileLazyRefs.clear();
+		fileSources?.clear();
+	}
+	return {
+		fileMetas,
+		fileLazyRefs,
+		fileSources,
+		updateFile,
+		removeFile,
+		clear
+	};
+}
+
+//#endregion
+export { createDiscoveryStore };

package/dist/plugins/core/identifier-resolver.js

@@ -0,0 +1,22 @@
+import { createAliasName } from "./utils.js";
+
+//#region src/plugins/core/identifier-resolver.ts
+var IdentifierResolver = class {
+	counts;
+	constructor(metas) {
+		this.counts = /* @__PURE__ */ new Map();
+		for (const meta of metas) {
+			const current = this.counts.get(meta.className) ?? 0;
+			this.counts.set(meta.className, current + 1);
+		}
+	}
+	count(className) {
+		return this.counts.get(className) ?? 0;
+	}
+	resolve(className, importPath) {
+		return this.count(className) > 1 ? createAliasName(className, importPath) : className;
+	}
+};
+
+//#endregion
+export { IdentifierResolver };