@djodjonx/neosyringe-core 0.1.0

package/dist/analyzer/index.mjs

@@ -0,0 +1,431 @@
+import * as ts from "typescript";
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+
+//#region src/analyzer/Analyzer.ts
+/**
+* Generates a unique, deterministic Token ID for a symbol.
+* Uses the symbol name and a short hash of its relative file path.
+*/
+function generateTokenId(symbol, sourceFile) {
+	const name = symbol.getName();
+	let relativePath = path.relative(process.cwd(), sourceFile.fileName);
+	relativePath = relativePath.split(path.sep).join("/");
+	return `${name}_${crypto.createHash("md5").update(relativePath).digest("hex").substring(0, 8)}`;
+}
+/**
+* Analyzes TypeScript source code to extract the dependency injection graph.
+*
+* This class uses the TypeScript Compiler API to:
+* 1. Locate `createContainer` calls.
+* 2. Parse the fluent chain of `bind` and `register` calls.
+* 3. Resolve symbols and types for services and their dependencies.
+* 4. Build a `DependencyGraph` representing the system.
+*/
+var Analyzer = class {
+	program;
+	checker;
+	/** Set of variable names that are parent containers (should not be added to main graph) */
+	parentContainerNames = /* @__PURE__ */ new Set();
+	/**
+	* Creates a new Analyzer instance.
+	* @param program - The TypeScript Program instance containing the source files to analyze.
+	*/
+	constructor(program) {
+		this.program = program;
+		this.checker = program.getTypeChecker();
+	}
+	/**
+	* Extracts the dependency graph from the program's source files.
+	*
+	* It scans all non-declaration source files for container configurations.
+	*
+	* @returns A `DependencyGraph` containing all registered services and their dependencies.
+	*/
+	extract() {
+		const graph = {
+			nodes: /* @__PURE__ */ new Map(),
+			roots: [],
+			buildArguments: []
+		};
+		for (const sourceFile of this.program.getSourceFiles()) {
+			if (sourceFile.isDeclarationFile) continue;
+			this.identifyParentContainers(sourceFile);
+		}
+		for (const sourceFile of this.program.getSourceFiles()) {
+			if (sourceFile.isDeclarationFile) continue;
+			this.visitNode(sourceFile, graph);
+		}
+		this.resolveAllDependencies(graph);
+		return graph;
+	}
+	/**
+	* First pass: identify containers used as parents so we can skip them in visitNode.
+	*/
+	identifyParentContainers(node) {
+		if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "useContainer" && ts.isIdentifier(node.initializer)) this.parentContainerNames.add(node.initializer.text);
+		ts.forEachChild(node, (child) => this.identifyParentContainers(child));
+	}
+	/**
+	* Visits an AST node to find container calls.
+	* @param node - The AST node to visit.
+	* @param graph - The graph to populate.
+	*/
+	visitNode(node, graph) {
+		if (ts.isCallExpression(node)) {
+			if (this.isDefineBuilderConfigCall(node)) {
+				const parent = node.parent;
+				if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+					if (this.parentContainerNames.has(parent.name.text)) return;
+					graph.exportedVariableName = parent.name.text;
+					let current = parent;
+					while (current && !ts.isVariableStatement(current)) current = current.parent;
+					if (current && ts.isVariableStatement(current)) graph.variableStatementStart = current.getStart();
+				}
+				graph.defineBuilderConfigStart = node.getStart();
+				graph.defineBuilderConfigEnd = node.getEnd();
+				this.parseBuilderConfig(node, graph);
+			}
+		}
+		ts.forEachChild(node, (child) => this.visitNode(child, graph));
+	}
+	isDefineBuilderConfigCall(node) {
+		const expression = node.expression;
+		if (ts.isIdentifier(expression)) return expression.text === "defineBuilderConfig";
+		return false;
+	}
+	parseBuilderConfig(node, graph) {
+		const args = node.arguments;
+		if (args.length < 1) return;
+		const configObj = args[0];
+		if (!ts.isObjectLiteralExpression(configObj)) return;
+		const nameProp = configObj.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === "name");
+		if (nameProp && ts.isPropertyAssignment(nameProp) && ts.isStringLiteral(nameProp.initializer)) graph.containerName = nameProp.initializer.text;
+		const injectionsProp = configObj.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === "injections");
+		if (injectionsProp && ts.isPropertyAssignment(injectionsProp) && ts.isArrayLiteralExpression(injectionsProp.initializer)) this.parseInjectionsArray(injectionsProp.initializer, graph);
+		const extendsProp = configObj.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === "extends");
+		if (extendsProp && ts.isPropertyAssignment(extendsProp) && ts.isArrayLiteralExpression(extendsProp.initializer)) this.parseExtendsArray(extendsProp.initializer, graph);
+		const useContainerProp = configObj.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === "useContainer");
+		if (useContainerProp && ts.isPropertyAssignment(useContainerProp)) {
+			if (!graph.legacyContainers) graph.legacyContainers = [];
+			if (!graph.parentProvidedTokens) graph.parentProvidedTokens = /* @__PURE__ */ new Set();
+			const containerExpr = useContainerProp.initializer;
+			if (ts.isIdentifier(containerExpr)) {
+				graph.legacyContainers.push(containerExpr.text);
+				this.extractParentContainerTokens(containerExpr, graph);
+			}
+		}
+	}
+	/**
+	* Extracts tokens provided by a parent container.
+	* Handles both NeoSyringe containers (defineBuilderConfig) and
+	* declared legacy containers (declareContainerTokens).
+	*/
+	extractParentContainerTokens(containerIdentifier, graph) {
+		const symbol = this.checker.getSymbolAtLocation(containerIdentifier);
+		if (!symbol) return;
+		this.parentContainerNames.add(containerIdentifier.text);
+		const resolvedSymbol = this.resolveSymbol(symbol);
+		const declaration = resolvedSymbol.valueDeclaration ?? resolvedSymbol.declarations?.[0];
+		if (!declaration) return;
+		if (ts.isVariableDeclaration(declaration) && declaration.initializer) {
+			const init = declaration.initializer;
+			if (ts.isCallExpression(init)) {
+				if (this.isDefineBuilderConfigCall(init) || this.isDefinePartialConfigCall(init)) {
+					const parentGraph = {
+						nodes: /* @__PURE__ */ new Map(),
+						roots: []
+					};
+					this.parseBuilderConfig(init, parentGraph);
+					for (const tokenId of parentGraph.nodes.keys()) graph.parentProvidedTokens.add(tokenId);
+					if (parentGraph.parentProvidedTokens) for (const tokenId of parentGraph.parentProvidedTokens) graph.parentProvidedTokens.add(tokenId);
+					return;
+				}
+				if (this.isDeclareContainerTokensCall(init)) {
+					this.extractDeclaredTokens(init, graph);
+					return;
+				}
+			}
+		}
+	}
+	/**
+	* Checks if a call expression is declareContainerTokens<T>().
+	*/
+	isDeclareContainerTokensCall(node) {
+		if (ts.isIdentifier(node.expression)) return node.expression.text === "declareContainerTokens";
+		return false;
+	}
+	/**
+	* Extracts tokens from declareContainerTokens<{ Token: Type }>().
+	* The type argument contains the token names.
+	*/
+	extractDeclaredTokens(node, graph) {
+		if (!node.typeArguments || node.typeArguments.length === 0) return;
+		const typeArg = node.typeArguments[0];
+		const properties = this.checker.getTypeFromTypeNode(typeArg).getProperties();
+		for (const prop of properties) {
+			const propType = this.checker.getTypeOfSymbol(prop);
+			if (propType) {
+				const tokenId = this.getTypeId(propType);
+				graph.parentProvidedTokens.add(tokenId);
+			} else graph.parentProvidedTokens.add(prop.getName());
+		}
+	}
+	parseExtendsArray(arrayLiteral, graph) {
+		for (const element of arrayLiteral.elements) if (ts.isIdentifier(element)) this.parsePartialConfig(element, graph);
+	}
+	parsePartialConfig(identifier, graph) {
+		const symbol = this.checker.getSymbolAtLocation(identifier);
+		if (!symbol) return;
+		const resolvedSymbol = this.resolveSymbol(symbol);
+		const declaration = resolvedSymbol.valueDeclaration ?? resolvedSymbol.declarations?.[0];
+		if (!declaration) return;
+		if (ts.isVariableDeclaration(declaration) && declaration.initializer && ts.isCallExpression(declaration.initializer)) {
+			const callExpr = declaration.initializer;
+			if (this.isDefinePartialConfigCall(callExpr)) this.parseBuilderConfig(callExpr, graph);
+		}
+		if (ts.isExportSpecifier(declaration)) {}
+	}
+	isDefinePartialConfigCall(node) {
+		const expression = node.expression;
+		if (ts.isIdentifier(expression)) return expression.text === "definePartialConfig";
+		return false;
+	}
+	parseInjectionsArray(arrayLiteral, graph) {
+		for (const element of arrayLiteral.elements) if (ts.isObjectLiteralExpression(element)) this.parseInjectionObject(element, graph);
+	}
+	parseInjectionObject(obj, graph) {
+		let tokenNode;
+		let providerNode;
+		let lifecycle = "singleton";
+		let useFactory = false;
+		let isScoped = false;
+		for (const prop of obj.properties) {
+			if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
+			if (prop.name.text === "token") tokenNode = prop.initializer;
+			else if (prop.name.text === "provider") providerNode = prop.initializer;
+			else if (prop.name.text === "lifecycle" && ts.isStringLiteral(prop.initializer)) {
+				if (prop.initializer.text === "transient") lifecycle = "transient";
+			} else if (prop.name.text === "useFactory") {
+				if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) useFactory = true;
+			} else if (prop.name.text === "scoped") {
+				if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) isScoped = true;
+			}
+		}
+		if (!tokenNode) return;
+		if (providerNode && (ts.isArrowFunction(providerNode) || ts.isFunctionExpression(providerNode))) useFactory = true;
+		let tokenId;
+		let implementationSymbol;
+		let tokenSymbol;
+		let type = "autowire";
+		let isInterfaceToken = false;
+		let isValueToken = false;
+		let factorySource;
+		let resolvedTokenNode = tokenNode;
+		const resolved = this.resolveToInitializer(tokenNode);
+		if (resolved) resolvedTokenNode = resolved;
+		if (ts.isCallExpression(resolvedTokenNode) && this.isUseInterfaceCall(resolvedTokenNode)) {
+			tokenId = this.extractInterfaceTokenId(resolvedTokenNode);
+			type = "explicit";
+			isInterfaceToken = true;
+		} else if (ts.isCallExpression(resolvedTokenNode) && this.isUsePropertyCall(resolvedTokenNode)) {
+			const propertyInfo = this.extractPropertyTokenId(resolvedTokenNode);
+			tokenId = propertyInfo.tokenId;
+			type = "explicit";
+			isValueToken = true;
+			if (!providerNode) throw new Error(`useProperty(${propertyInfo.className}, '${propertyInfo.paramName}') requires a provider (factory).`);
+			useFactory = true;
+		} else {
+			const tokenType = this.checker.getTypeAtLocation(tokenNode);
+			tokenId = this.getTypeIdFromConstructor(tokenType);
+			if (ts.isIdentifier(tokenNode)) tokenSymbol = this.checker.getSymbolAtLocation(tokenNode);
+		}
+		if (useFactory && providerNode) {
+			factorySource = providerNode.getText();
+			type = "factory";
+			if (tokenId) {
+				if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+				const definition = {
+					tokenId,
+					tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
+					registrationNode: obj,
+					type: "factory",
+					lifecycle,
+					isInterfaceToken,
+					isValueToken,
+					isFactory: true,
+					factorySource,
+					isScoped
+				};
+				graph.nodes.set(tokenId, {
+					service: definition,
+					dependencies: []
+				});
+			}
+			return;
+		}
+		if (providerNode) {
+			implementationSymbol = this.checker.getSymbolAtLocation(providerNode);
+			type = "explicit";
+		} else if (type === "explicit" && !providerNode) {
+			if (ts.isIdentifier(tokenNode)) {
+				implementationSymbol = this.checker.getSymbolAtLocation(tokenNode);
+				type = "autowire";
+			}
+		} else if (ts.isIdentifier(tokenNode)) {
+			implementationSymbol = this.checker.getSymbolAtLocation(tokenNode);
+			type = "autowire";
+		}
+		if (tokenId && implementationSymbol) {
+			if (graph.nodes.has(tokenId) && !isScoped) throw new Error(`Duplicate registration: '${tokenId}' is already registered.`);
+			const definition = {
+				tokenId,
+				implementationSymbol: this.resolveSymbol(implementationSymbol),
+				tokenSymbol: tokenSymbol ? this.resolveSymbol(tokenSymbol) : void 0,
+				registrationNode: obj,
+				type,
+				lifecycle,
+				isInterfaceToken: isInterfaceToken || ts.isCallExpression(tokenNode) && this.isUseInterfaceCall(tokenNode),
+				isScoped
+			};
+			graph.nodes.set(tokenId, {
+				service: definition,
+				dependencies: []
+			});
+		}
+	}
+	isUseInterfaceCall(node) {
+		if (ts.isIdentifier(node.expression)) return node.expression.text === "useInterface";
+		return false;
+	}
+	isUsePropertyCall(node) {
+		if (ts.isIdentifier(node.expression)) return node.expression.text === "useProperty";
+		return false;
+	}
+	/**
+	* Resolves a node to its original initializer expression.
+	* Handles identifiers, property access, imports, and unwraps type assertions/casts.
+	*/
+	resolveToInitializer(node) {
+		let expr = node;
+		while (ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr) || ts.isSatisfiesExpression && ts.isSatisfiesExpression(expr)) expr = expr.expression;
+		if (ts.isCallExpression(expr)) return expr;
+		if (ts.isIdentifier(expr)) return this.resolveIdentifierToInitializer(expr);
+		if (ts.isPropertyAccessExpression(expr)) return this.resolvePropertyAccessToInitializer(expr);
+	}
+	resolveIdentifierToInitializer(identifier) {
+		const symbol = this.checker.getSymbolAtLocation(identifier);
+		if (!symbol) return void 0;
+		const declarations = this.resolveSymbol(symbol).getDeclarations();
+		if (!declarations || declarations.length === 0) return void 0;
+		for (const decl of declarations) if (ts.isVariableDeclaration(decl) && decl.initializer) return this.resolveToInitializer(decl.initializer) ?? decl.initializer;
+	}
+	resolvePropertyAccessToInitializer(node) {
+		const objectInitializer = this.resolveToInitializer(node.expression);
+		if (objectInitializer && ts.isObjectLiteralExpression(objectInitializer)) {
+			const propName = node.name.text;
+			const prop = objectInitializer.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === propName);
+			if (prop && ts.isPropertyAssignment(prop)) return this.resolveToInitializer(prop.initializer) ?? prop.initializer;
+		}
+	}
+	extractPropertyTokenId(node) {
+		if (node.arguments.length < 2) throw new Error("useProperty requires two arguments: (Class, paramName)");
+		const classArg = node.arguments[0];
+		const nameArg = node.arguments[1];
+		if (!ts.isIdentifier(classArg)) throw new Error("useProperty first argument must be a class identifier.");
+		if (!ts.isStringLiteral(nameArg)) throw new Error("useProperty second argument must be a string literal.");
+		const className = classArg.text;
+		const paramName = nameArg.text;
+		return {
+			tokenId: `PropertyToken:${className}.${paramName}`,
+			className,
+			paramName
+		};
+	}
+	extractInterfaceTokenId(node) {
+		if (!node.typeArguments || node.typeArguments.length === 0) throw new Error("useInterface must have a type argument.");
+		const typeNode = node.typeArguments[0];
+		const symbol = this.checker.getTypeFromTypeNode(typeNode).getSymbol();
+		if (!symbol) return "AnonymousInterface";
+		const declarations = symbol.getDeclarations();
+		if (declarations && declarations.length > 0) return generateTokenId(symbol, declarations[0].getSourceFile());
+		return symbol.getName();
+	}
+	getTypeIdFromConstructor(type) {
+		const constructSignatures = type.getConstructSignatures();
+		let instanceType;
+		if (constructSignatures.length > 0) instanceType = constructSignatures[0].getReturnType();
+		else instanceType = type;
+		return this.getTypeId(instanceType);
+	}
+	extractScope(optionsNode) {
+		for (const prop of optionsNode.properties) if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) && prop.name.text === "scope" && ts.isStringLiteral(prop.initializer)) {
+			if (prop.initializer.text === "transient") return "transient";
+		}
+		return "singleton";
+	}
+	/**
+	* Resolves dependencies for all nodes in the graph.
+	* @param graph - The dependency graph.
+	*/
+	resolveAllDependencies(graph) {
+		for (const node of graph.nodes.values()) this.resolveDependencies(node, graph);
+	}
+	/**
+	* Resolves dependencies for a single service node by inspecting its constructor.
+	* @param node - The dependency node to resolve.
+	*/
+	resolveDependencies(node, graph) {
+		if (node.service.isFactory || node.service.type === "factory") return;
+		const symbol = node.service.implementationSymbol;
+		if (!symbol) return;
+		const declarations = symbol.getDeclarations();
+		if (!declarations || declarations.length === 0) return;
+		const classDecl = declarations.find((d) => ts.isClassDeclaration(d));
+		if (!classDecl) return;
+		const className = classDecl.name?.getText() ?? "Anonymous";
+		const constructor = classDecl.members.find((m) => ts.isConstructorDeclaration(m));
+		if (!constructor) return;
+		for (const param of constructor.parameters) {
+			const paramName = param.name.getText();
+			const typeNode = param.type;
+			if (!typeNode) continue;
+			const type = this.checker.getTypeFromTypeNode(typeNode);
+			const propertyTokenId = `PropertyToken:${className}.${paramName}`;
+			if (graph.nodes.has(propertyTokenId)) {
+				node.dependencies.push(propertyTokenId);
+				continue;
+			}
+			const depTokenId = this.getTypeId(type);
+			node.dependencies.push(depTokenId);
+		}
+	}
+	/**
+	* Generates a unique Token ID for a given Type.
+	* Uses file path hash + name for consistency and collision avoidance.
+	*
+	* @param type - The TypeScript Type.
+	* @returns A string identifier for the token.
+	*/
+	getTypeId(type) {
+		const symbol = type.getSymbol();
+		if (!symbol) return this.checker.typeToString(type);
+		const name = symbol.getName();
+		if (name === "__type" || name === "InterfaceToken" || name === "__brand") return this.checker.typeToString(type);
+		const declarations = symbol.getDeclarations();
+		if (declarations && declarations.length > 0) return generateTokenId(symbol, declarations[0].getSourceFile());
+		return symbol.getName();
+	}
+	/**
+	* Resolves a symbol, following aliases if necessary.
+	* @param symbol - The symbol to resolve.
+	* @returns The resolved symbol.
+	*/
+	resolveSymbol(symbol) {
+		if (symbol.flags & ts.SymbolFlags.Alias) return this.resolveSymbol(this.checker.getAliasedSymbol(symbol));
+		return symbol;
+	}
+};
+
+//#endregion
+export { Analyzer, generateTokenId };

package/dist/generator/index.cjs

@@ -0,0 +1,249 @@
+
+//#region src/generator/Generator.ts
+/**
+* Generates TypeScript code for the dependency injection container.
+*
+* Takes a validated dependency graph and produces:
+* - Import statements for all dependencies
+* - Factory functions for each service
+* - A NeoContainer class with resolve logic
+*/
+var Generator = class {
+	/**
+	* Creates a new Generator.
+	* @param graph - The validated dependency graph to generate code from.
+	* @param useDirectSymbolNames - If true, uses symbol names directly without import prefixes.
+	*/
+	constructor(graph, useDirectSymbolNames = false) {
+		this.graph = graph;
+		this.useDirectSymbolNames = useDirectSymbolNames;
+	}
+	/**
+	* Generates the complete container code as a string.
+	* @returns TypeScript source code for the generated container.
+	*/
+	generate() {
+		const sorted = this.topologicalSort();
+		const imports = /* @__PURE__ */ new Map();
+		const factories = [];
+		const resolveCases = [];
+		const getImport = (symbol) => {
+			if (this.useDirectSymbolNames) return symbol.getName();
+			const decl = symbol.declarations?.[0];
+			if (!decl) return "UNKNOWN";
+			const filePath = decl.getSourceFile().fileName;
+			if (!imports.has(filePath)) {
+				const alias = `Import_${imports.size}`;
+				imports.set(filePath, alias);
+			}
+			return `${imports.get(filePath)}.${symbol.getName()}`;
+		};
+		for (const tokenId of sorted) {
+			const node = this.graph.nodes.get(tokenId);
+			if (!node) continue;
+			if (node.service.type === "parent") continue;
+			const factoryId = this.getFactoryName(tokenId);
+			if (node.service.isFactory && node.service.factorySource) {
+				const userFactory = node.service.factorySource;
+				factories.push(`
+  private ${factoryId}(): any {
+    const userFactory = ${userFactory};
+    return userFactory(this);
+  }`);
+			} else {
+				const className = node.service.implementationSymbol ? getImport(node.service.implementationSymbol) : "undefined";
+				const args = node.dependencies.map((depId) => {
+					const depNode = this.graph.nodes.get(depId);
+					if (!depNode) return "undefined";
+					if (depNode.service.isInterfaceToken) return `this.resolve("${depNode.service.tokenId}")`;
+					else if (depNode.service.tokenSymbol) return `this.resolve(${getImport(depNode.service.tokenSymbol)})`;
+					else if (depNode.service.implementationSymbol) return `this.resolve(${getImport(depNode.service.implementationSymbol)})`;
+					return "undefined";
+				}).join(", ");
+				factories.push(`
+  private ${factoryId}(): any {
+    return new ${className}(${args});
+  }`);
+			}
+			const isTransient = node.service.lifecycle === "transient";
+			let tokenKey;
+			let tokenCheck;
+			if (node.service.isInterfaceToken) {
+				tokenKey = `"${node.service.tokenId}"`;
+				tokenCheck = `if (token === "${node.service.tokenId}")`;
+			} else if (node.service.tokenSymbol) {
+				const tokenClass = getImport(node.service.tokenSymbol);
+				tokenKey = tokenClass;
+				tokenCheck = `if (token === ${tokenClass})`;
+			} else if (node.service.implementationSymbol) {
+				const className = getImport(node.service.implementationSymbol);
+				tokenKey = className;
+				tokenCheck = `if (token === ${className})`;
+			} else {
+				tokenKey = `"${node.service.tokenId}"`;
+				tokenCheck = `if (token === "${node.service.tokenId}")`;
+			}
+			const creationLogic = isTransient ? `return this.${factoryId}();` : `
+            if (!this.instances.has(${tokenKey})) {
+                const instance = this.${factoryId}();
+                this.instances.set(${tokenKey}, instance);
+                return instance;
+            }
+            return this.instances.get(${tokenKey});
+          `;
+			resolveCases.push(`${tokenCheck} { ${creationLogic} }`);
+		}
+		const importLines = [];
+		if (!this.useDirectSymbolNames) for (const [filePath, alias] of imports) importLines.push(`import * as ${alias} from '${filePath}';`);
+		return `
+${importLines.join("\n")}
+
+// -- Container --
+export class NeoContainer {
+  private instances = new Map<any, any>();
+
+  // -- Factories --
+  ${factories.join("\n  ")}
+
+  constructor(
+    private parent?: any,
+    private legacy?: any[],
+    private name: string = 'NeoContainer'
+  ) {}
+
+  public resolve(token: any): any {
+    // 1. Try to resolve locally (or create if singleton)
+    const result = this.resolveLocal(token);
+    if (result !== undefined) return result;
+
+    // 2. Delegate to parent
+    if (this.parent) {
+        try {
+            return this.parent.resolve(token);
+        } catch (e) {
+            // Ignore error, try legacy
+        }
+    }
+
+    // 3. Delegate to legacy
+    if (this.legacy) {
+        for (const legacyContainer of this.legacy) {
+            // Assume legacy container has resolve()
+            try {
+                if (legacyContainer.resolve) return legacyContainer.resolve(token);
+            } catch (e) {
+                // Ignore
+            }
+        }
+    }
+
+    throw new Error(\`[\${this.name}] Service not found or token not registered: \${token}\`);
+  }
+
+  private resolveLocal(token: any): any {
+    ${resolveCases.join("\n    ")}
+    return undefined;
+  }
+
+  // For debugging/inspection
+  public get _graph() {
+    return ${JSON.stringify(Array.from(this.graph.nodes.keys()))};
+  }
+}
+${this.useDirectSymbolNames ? "" : `
+// -- Container Instance --
+export const ${this.graph.exportedVariableName || "container"} = ${this.generateInstantiation()};
+`}`;
+	}
+	/**
+	* Generates only the instantiation expression: new NeoContainer(...)
+	* This is used to replace defineBuilderConfig(...) in the source.
+	*/
+	generateInstantiation() {
+		return `new NeoContainer(${this.graph.buildArguments && this.graph.buildArguments.length > 0 ? this.graph.buildArguments[0] : "undefined"}, ${this.graph.legacyContainers ? `[${this.graph.legacyContainers.join(", ")}]` : "undefined"}, ${this.graph.containerName ? `'${this.graph.containerName}'` : "undefined"})`;
+	}
+	/**
+	* Sorts services in topological order (dependencies before dependents).
+	* @returns Array of TokenIds in dependency order.
+	*/
+	topologicalSort() {
+		const visited = /* @__PURE__ */ new Set();
+		const sorted = [];
+		const visit = (id) => {
+			if (visited.has(id)) return;
+			visited.add(id);
+			const node = this.graph.nodes.get(id);
+			if (node) {
+				for (const depId of node.dependencies) visit(depId);
+				sorted.push(id);
+			}
+		};
+		for (const id of this.graph.nodes.keys()) visit(id);
+		return sorted;
+	}
+	/**
+	* Creates a valid JavaScript function name from a token ID.
+	* @param tokenId - The token identifier.
+	* @returns A sanitized factory function name.
+	*/
+	getFactoryName(tokenId) {
+		return `create_${tokenId.replace(/[^a-zA-Z0-9]/g, "_")}`;
+	}
+};
+
+//#endregion
+//#region src/generator/GraphValidator.ts
+/**
+* Validates the dependency graph for correctness.
+* Detects circular dependencies, missing bindings, and duplicates.
+*/
+var GraphValidator = class {
+	/**
+	* Validates the graph structure.
+	*
+	* @param graph - The dependency graph to validate.
+	* @throws {Error} If a circular dependency or missing binding is detected.
+	*/
+	validate(graph) {
+		const visited = /* @__PURE__ */ new Set();
+		const recursionStack = /* @__PURE__ */ new Set();
+		const parentTokens = graph.parentProvidedTokens ?? /* @__PURE__ */ new Set();
+		for (const [nodeId, node] of graph.nodes) if (parentTokens.has(nodeId)) {
+			if (node.service.isScoped) continue;
+			throw new Error(`Duplicate registration: '${nodeId}' is already registered in the parent container. Use 'scoped: true' to override the parent's registration intentionally.`);
+		}
+		for (const [nodeId, node] of graph.nodes) for (const depId of node.dependencies) {
+			const isProvidedLocally = graph.nodes.has(depId);
+			const isProvidedByParent = parentTokens.has(depId);
+			if (!isProvidedLocally && !isProvidedByParent) {
+				const serviceName = nodeId;
+				throw new Error(`Missing binding: Service '${serviceName}' depends on '${depId}', but no provider was registered.`);
+			}
+		}
+		for (const nodeId of graph.nodes.keys()) if (!visited.has(nodeId)) this.detectCycle(nodeId, graph, visited, recursionStack, parentTokens);
+	}
+	/**
+	* Recursive Helper for Cycle Detection (DFS).
+	*
+	* @param nodeId - The current node ID.
+	* @param graph - The graph.
+	* @param visited - Set of all visited nodes.
+	* @param stack - Set of nodes in the current recursion stack (path).
+	* @param parentTokens - Tokens from parent container (skip traversal).
+	*/
+	detectCycle(nodeId, graph, visited, stack, parentTokens) {
+		visited.add(nodeId);
+		stack.add(nodeId);
+		const node = graph.nodes.get(nodeId);
+		if (node) for (const depId of node.dependencies) {
+			if (parentTokens.has(depId)) continue;
+			if (!visited.has(depId)) this.detectCycle(depId, graph, visited, stack, parentTokens);
+			else if (stack.has(depId)) throw new Error(`Circular dependency detected: ${[...stack, depId].join(" -> ")}`);
+		}
+		stack.delete(nodeId);
+	}
+};
+
+//#endregion
+exports.Generator = Generator;
+exports.GraphValidator = GraphValidator;