@cldmv/slothlet 2.4.3 → 2.5.1

package/dist/lib/helpers/api_builder.mjs

@@ -0,0 +1,1455 @@
+/*
+	Copyright 2025 CLDMV/Shinrai
+
+	Licensed under the Apache License, Version 2.0 (the "License");
+	you may not use this file except in compliance with the License.
+	You may obtain a copy of the License at
+
+		http://www.apache.org/licenses/LICENSE-2.0
+
+	Unless required by applicable law or agreed to in writing, software
+	distributed under the License is distributed on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+	See the License for the specific language governing permissions and
+	limitations under the License.
+*/
+
+
+
+
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+
+
+
+
+
+export async function analyzeModule(modulePath, options = {}) {
+	const { debug = false } = options;
+
+	const moduleUrl = pathToFileURL(modulePath).href;
+	const rawModule = await import(moduleUrl);
+
+	
+	let processedModule = rawModule;
+	const isCjs = modulePath.endsWith(".cjs") && "default" in rawModule;
+
+	if (isCjs) {
+		processedModule = rawModule.default;
+	}
+
+	const hasDefault = !!processedModule.default;
+	const isFunction = typeof processedModule.default === "function";
+	const exports = Object.entries(processedModule);
+	const namedExports = Object.entries(processedModule).filter(([k]) => k !== "default");
+
+	
+	let defaultExportType = null;
+	if (hasDefault) {
+		defaultExportType = typeof processedModule.default === "function" ? "function" : "object";
+	}
+
+	
+	let shouldWrapAsCallable = false;
+
+	
+	if (
+		hasDefault &&
+		typeof processedModule.default === "object" &&
+		processedModule.default !== null &&
+		typeof processedModule.default.default === "function"
+	) {
+		shouldWrapAsCallable = true;
+	}
+
+	
+	if (!shouldWrapAsCallable) {
+		for (const [_, exportValue] of namedExports) {
+			if (typeof exportValue === "object" && exportValue !== null && typeof exportValue.default === "function") {
+				shouldWrapAsCallable = true;
+				break;
+			}
+		}
+	}
+
+	if (debug) {
+		console.log(`[DEBUG] analyzeModule(${path.basename(modulePath)}):`, {
+			isCjs,
+			hasDefault,
+			isFunction,
+			defaultExportType,
+			shouldWrapAsCallable,
+			namedExportsCount: namedExports.length
+		});
+	}
+
+	return {
+		rawModule,
+		processedModule,
+		isFunction,
+		hasDefault,
+		isCjs,
+		exports,
+		defaultExportType,
+		shouldWrapAsCallable,
+		namedExports,
+		metadata: { modulePath }
+	};
+}
+
+
+export function processModuleFromAnalysis(analysis, options = {}) {
+	const { instance, debug = false } = options;
+	const { processedModule, isFunction, hasDefault, shouldWrapAsCallable, namedExports } = analysis;
+
+	if (!instance) {
+		throw new Error("processModuleFromAnalysis requires instance parameter for _toapiPathKey access");
+	}
+
+	
+	if (isFunction) {
+		let fn = processedModule.default;
+
+		
+		if (hasDefault) {
+			try {
+				Object.defineProperty(fn, "__slothletDefault", {
+					value: true,
+					writable: false,
+					enumerable: false,
+					configurable: true
+				});
+			} catch {
+				
+			}
+		}
+
+		
+		for (const [exportName, exportValue] of Object.entries(processedModule)) {
+			if (exportName !== "default") {
+				fn[instance._toapiPathKey(exportName)] = exportValue;
+			}
+		}
+		return fn;
+	}
+
+	
+	if (shouldWrapAsCallable) {
+		let callableObject = null;
+		let objectName = "callable";
+
+		
+		if (
+			hasDefault &&
+			typeof processedModule.default === "object" &&
+			processedModule.default !== null &&
+			typeof processedModule.default.default === "function"
+		) {
+			callableObject = processedModule.default;
+			objectName = processedModule.default.name || (namedExports[0] && namedExports[0][0] !== "default" ? namedExports[0][0] : "callable");
+		} else {
+			
+			for (const [exportName, exportValue] of namedExports) {
+				if (typeof exportValue === "object" && exportValue !== null && typeof exportValue.default === "function") {
+					callableObject = exportValue;
+					objectName = exportName;
+					break;
+				}
+			}
+		}
+
+		if (callableObject) {
+			const callableApi = {
+				[objectName]: function (...args) {
+					return callableObject.default.apply(callableObject, args);
+				}
+			}[objectName];
+
+			
+			for (const [methodName, method] of Object.entries(callableObject)) {
+				if (methodName === "default") continue;
+				callableApi[methodName] = method;
+			}
+
+			if (debug) {
+				console.log(`[DEBUG] Created callable wrapper for ${objectName}`);
+			}
+
+			return callableApi;
+		}
+	}
+
+	
+	if (hasDefault && typeof processedModule.default === "object") {
+		const obj = { ...processedModule.default };
+
+		
+		for (const [exportName, exportValue] of Object.entries(processedModule)) {
+			if (exportName !== "default" && exportValue !== obj) {
+				obj[instance._toapiPathKey(exportName)] = exportValue;
+			}
+		}
+
+		return obj;
+	}
+
+	
+	if (namedExports.length > 0) {
+		const apiExport = {};
+		for (const [exportName, exportValue] of namedExports) {
+			apiExport[instance._toapiPathKey(exportName)] = exportValue;
+		}
+		return apiExport;
+	}
+
+	
+	throw new Error(`No valid exports found in processed module`);
+}
+
+
+export async function analyzeDirectoryStructure(categoryPath, options = {}) {
+	const { instance, currentDepth = 0, debug = false } = options;
+
+	if (!instance || typeof instance._toapiPathKey !== "function") {
+		throw new Error("analyzeDirectoryStructure requires a valid slothlet instance");
+	}
+
+	const files = await fs.readdir(categoryPath, { withFileTypes: true });
+	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
+	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
+	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+
+	
+	let processingStrategy;
+	if (moduleFiles.length === 0) {
+		processingStrategy = "empty";
+	} else if (moduleFiles.length === 1 && subDirs.length === 0) {
+		processingStrategy = "single-file";
+	} else {
+		processingStrategy = "multi-file";
+	}
+
+	
+	let multiDefaultAnalysis = null;
+	if (processingStrategy === "multi-file") {
+		const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
+		multiDefaultAnalysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+	}
+
+	
+	const flatteningHints = {
+		shouldFlattenSingleFile: processingStrategy === "single-file",
+		shouldFlattenToParent: currentDepth > 0 && processingStrategy === "single-file",
+		hasMultipleDefaults: multiDefaultAnalysis?.hasMultipleDefaultExports || false,
+		selfReferentialFiles: multiDefaultAnalysis?.selfReferentialFiles || new Set()
+	};
+
+	if (debug) {
+		console.log(`[DEBUG] analyzeDirectoryStructure(${categoryName}):`, {
+			processingStrategy,
+			moduleCount: moduleFiles.length,
+			subDirCount: subDirs.length,
+			hasMultipleDefaults: flatteningHints.hasMultipleDefaults
+		});
+	}
+
+	return {
+		isSingleFile: processingStrategy === "single-file",
+		shouldAutoFlatten: flatteningHints.shouldFlattenSingleFile,
+		categoryName,
+		moduleFiles,
+		subDirs,
+		multiDefaultAnalysis,
+		processingStrategy,
+		flatteningHints
+	};
+}
+
+
+export async function getCategoryBuildingDecisions(categoryPath, options = {}) {
+	const { instance, currentDepth = 0, maxDepth = Infinity, debug = false } = options;
+
+	if (!instance) {
+		throw new Error("getCategoryBuildingDecisions requires a valid slothlet instance");
+	}
+
+	const analysis = await analyzeDirectoryStructure(categoryPath, { instance, currentDepth, maxDepth, debug });
+	const { processingStrategy, categoryName, moduleFiles, subDirs, multiDefaultAnalysis } = analysis;
+
+	const processedModules = [];
+	const subDirectories = [];
+
+	
+	if (processingStrategy !== "empty") {
+		for (const file of moduleFiles) {
+			const moduleExt = path.extname(file.name);
+			const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
+			const modulePath = path.join(categoryPath, file.name);
+
+			
+			const analysis = await analyzeModule(modulePath, {
+				debug,
+				instance
+			});
+			const processedModule = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+
+			
+			const flatteningInfo = {
+				shouldFlatten: false,
+				apiPathKey: moduleName,
+				reason: "default"
+			};
+
+			
+			if (processingStrategy === "single-file") {
+				
+				const functionNameMatchesFolder =
+					typeof processedModule === "function" &&
+					processedModule.name &&
+					processedModule.name.toLowerCase() === categoryName.toLowerCase();
+
+				const moduleNameMatchesCategory = moduleName === categoryName && typeof processedModule === "function" && currentDepth > 0;
+
+				if (functionNameMatchesFolder && currentDepth > 0) {
+					flatteningInfo.shouldFlatten = true;
+					flatteningInfo.apiPathKey = processedModule.name;
+					flatteningInfo.reason = "function name matches folder";
+				} else if (moduleNameMatchesCategory) {
+					flatteningInfo.shouldFlatten = true;
+					flatteningInfo.apiPathKey = categoryName;
+					flatteningInfo.reason = "module name matches category";
+				}
+			}
+
+			processedModules.push({
+				file,
+				moduleName,
+				processedModule,
+				flattening: flatteningInfo
+			});
+		}
+	}
+
+	
+	for (const subDirEntry of subDirs) {
+		if (currentDepth < maxDepth) {
+			const apiPathKey = instance._toapiPathKey(subDirEntry.name);
+			subDirectories.push({ dirEntry: subDirEntry, apiPathKey });
+		}
+	}
+
+	
+	const upwardFlatteningCandidate = { shouldFlatten: false, apiPathKey: null };
+	if (processedModules.length === 1 && subDirectories.length === 0) {
+		const single = processedModules[0];
+		if (single.moduleName === categoryName) {
+			upwardFlatteningCandidate.shouldFlatten = true;
+			upwardFlatteningCandidate.apiPathKey = single.moduleName;
+		}
+	}
+
+	if (debug) {
+		console.log(`[DEBUG] getCategoryBuildingDecisions(${categoryName}):`, {
+			processingStrategy,
+			moduleCount: processedModules.length,
+			subDirCount: subDirectories.length,
+			upwardFlattening: upwardFlatteningCandidate.shouldFlatten
+		});
+	}
+
+	return {
+		processingStrategy,
+		categoryName,
+		shouldFlattenSingle: processingStrategy === "single-file",
+		processedModules,
+		subDirectories,
+		multiDefaultAnalysis,
+		flatteningDecisions: analysis.flatteningHints,
+		upwardFlatteningCandidate
+	};
+}
+
+
+export function getFlatteningDecision(options) {
+	const {
+		mod,
+		fileName,
+		apiPathKey,
+		hasMultipleDefaultExports,
+		isSelfReferential,
+		
+		
+		moduleHasDefault = !!mod.default,
+		categoryName,
+		totalModules = 1
+	} = options;
+
+	const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+
+	
+	if (isSelfReferential) {
+		return {
+			shouldFlatten: false,
+			flattenToRoot: false,
+			flattenToCategory: false,
+			preserveAsNamespace: true,
+			useAutoFlattening: false,
+			reason: "self-referential export"
+		};
+	}
+
+	
+	if (hasMultipleDefaultExports) {
+		if (moduleHasDefault) {
+			
+			return {
+				shouldFlatten: false,
+				flattenToRoot: false,
+				flattenToCategory: false,
+				preserveAsNamespace: true,
+				useAutoFlattening: false,
+				reason: "multi-default context with default export"
+			};
+		} else {
+			
+			return {
+				shouldFlatten: true,
+				flattenToRoot: true,
+				flattenToCategory: true,
+				preserveAsNamespace: false,
+				useAutoFlattening: false,
+				reason: "multi-default context without default export"
+			};
+		}
+	}
+
+	
+	if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
+		return {
+			shouldFlatten: true,
+			flattenToRoot: false,
+			flattenToCategory: false,
+			preserveAsNamespace: false,
+			useAutoFlattening: true,
+			reason: "auto-flatten single named export matching filename"
+		};
+	}
+
+	
+	if (categoryName && fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0) {
+		return {
+			shouldFlatten: true,
+			flattenToRoot: false,
+			flattenToCategory: true,
+			preserveAsNamespace: false,
+			useAutoFlattening: false,
+			reason: "filename matches container, flatten to category"
+		};
+	}
+
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+	
+
+	
+	return {
+		shouldFlatten: false,
+		flattenToRoot: false,
+		flattenToCategory: false,
+		preserveAsNamespace: true,
+		useAutoFlattening: false,
+		reason: "traditional namespace preservation"
+	};
+}
+
+
+export function processModuleForAPI(options) {
+	const {
+		mod,
+		fileName,
+		apiPathKey,
+		hasMultipleDefaultExports,
+		isSelfReferential,
+		api,
+		getRootDefault,
+		setRootDefault,
+		context = {},
+		originalAnalysis = null
+	} = options;
+
+	const { debug = false, mode = "unknown", categoryName, totalModules = 1 } = context;
+
+	let processed = false;
+	let rootDefaultSet = false;
+	let flattened = false;
+	let namespaced = false;
+	const apiAssignments = {};
+
+	
+	
+	
+	const hasDefaultFunction = (mod && typeof mod.default === "function") || (mod && typeof mod === "function" && !mod.default);
+
+	
+	const defaultFunction = mod?.default || (typeof mod === "function" ? mod : null);
+
+	if (hasDefaultFunction) {
+		processed = true;
+
+		if (hasMultipleDefaultExports && !isSelfReferential) {
+			
+			apiAssignments[apiPathKey] = mod;
+			namespaced = true;
+
+			
+			
+
+			if (debug) {
+				console.log(
+					`[DEBUG] ${mode}: Multi-default function - using filename '${apiPathKey}' for default export, mod type: ${typeof mod}, function name: ${defaultFunction?.name}`
+				);
+			}
+		} else if (isSelfReferential) {
+			
+			apiAssignments[apiPathKey] = mod;
+			namespaced = true;
+
+			if (debug) {
+				console.log(`[DEBUG] ${mode}: Self-referential function - preserving ${fileName} as namespace`);
+			}
+		} else {
+			
+			if (debug) {
+				console.log(
+					`[DEBUG] ${mode}: Processing traditional default function: hasMultipleDefaultExports=${hasMultipleDefaultExports}, rootDefaultFunction=${!!(getRootDefault && getRootDefault())}`
+				);
+			}
+
+			
+			if (mode === "root" && getRootDefault && setRootDefault && !hasMultipleDefaultExports && !getRootDefault()) {
+				setRootDefault(defaultFunction);
+				rootDefaultSet = true;
+
+				if (debug) {
+					console.log(`[DEBUG] ${mode}: Set rootDefaultFunction to:`, defaultFunction.name);
+				}
+
+				
+				
+			} else {
+				
+				apiAssignments[apiPathKey] = mod;
+				namespaced = true;
+
+				
+				
+			}
+		}
+	} else {
+		
+		processed = true;
+
+		if (debug) {
+			console.log(`[DEBUG] ${mode}: Processing non-function or named-only exports for ${fileName}`);
+		}
+
+		
+		const decision = getFlatteningDecision({
+			mod,
+			fileName,
+			apiPathKey,
+			hasMultipleDefaultExports,
+			isSelfReferential,
+			
+			
+			
+			moduleHasDefault: originalAnalysis ? originalAnalysis.hasDefault : !!mod.default,
+			categoryName,
+			totalModules,
+			debug
+		});
+
+		if (debug) {
+			console.log(`[DEBUG] ${mode}: Flattening decision for ${fileName}: ${decision.reason}`);
+		}
+
+		if (decision.useAutoFlattening) {
+			
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			apiAssignments[apiPathKey] = mod[moduleKeys[0]];
+			flattened = true;
+		} else if (decision.flattenToRoot || decision.flattenToCategory) {
+			
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			for (const key of moduleKeys) {
+				apiAssignments[key] = mod[key];
+				if (debug) {
+					console.log(`[DEBUG] ${mode}: Flattened ${fileName}.${key} to ${decision.flattenToRoot ? "root" : "category"}.${key}`);
+				}
+			}
+			flattened = true;
+		} else if (isSelfReferential) {
+			
+			apiAssignments[apiPathKey] = mod[apiPathKey] || mod;
+			namespaced = true;
+		} else {
+			
+			apiAssignments[apiPathKey] = mod;
+			namespaced = true;
+		}
+	}
+
+	
+	for (const [key, value] of Object.entries(apiAssignments)) {
+		if (debug && key && typeof value === "function" && value.name) {
+			console.log(`[DEBUG] ${mode}: Assigning key '${key}' to function '${value.name}'`);
+		}
+		api[key] = value;
+	}
+
+	return {
+		processed,
+		rootDefaultSet,
+		flattened,
+		namespaced,
+		apiAssignments
+	};
+}
+
+
+export function applyFunctionNamePreference(options) {
+	const { mod, fileName, apiPathKey, categoryModules, toapiPathKey, debug = false } = options;
+
+	let hasPreferredName = false;
+	let preferredKey = apiPathKey;
+
+	
+	for (const [, exportValue] of Object.entries(mod)) {
+		if (typeof exportValue === "function" && exportValue.name) {
+			const functionNameLower = exportValue.name.toLowerCase();
+			const filenameLower = fileName.toLowerCase();
+
+			
+			if (functionNameLower === filenameLower && exportValue.name !== apiPathKey) {
+				
+				preferredKey = exportValue.name;
+				hasPreferredName = true;
+
+				if (debug) {
+					console.log(`[DEBUG] Using function name preference: ${exportValue.name} instead of ${apiPathKey} for ${fileName}`);
+				}
+				break;
+			}
+
+			
+			const sanitizedFunctionName = toapiPathKey(exportValue.name);
+			if (sanitizedFunctionName.toLowerCase() === apiPathKey.toLowerCase() && exportValue.name !== apiPathKey) {
+				preferredKey = exportValue.name;
+				hasPreferredName = true;
+
+				if (debug) {
+					console.log(`[DEBUG] Using function name preference: ${exportValue.name} instead of ${apiPathKey} for ${fileName}`);
+				}
+				break;
+			}
+		}
+	}
+
+	if (hasPreferredName) {
+		
+		categoryModules[preferredKey] = mod;
+	}
+
+	return { hasPreferredName, preferredKey };
+}
+
+
+export async function buildCategoryStructure(categoryPath, options = {}) {
+	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, instance } = options;
+
+	if (!instance || typeof instance._toapiPathKey !== "function" || typeof instance._shouldIncludeFile !== "function") {
+		throw new Error("buildCategoryStructure requires a valid slothlet instance");
+	}
+
+	const debug = instance.config?.debug || false;
+
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryStructure called with path: ${categoryPath}, mode: ${mode}, depth: ${currentDepth}`);
+	}
+
+	const files = await fs.readdir(categoryPath, { withFileTypes: true });
+	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
+	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
+	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+
+	
+	if (moduleFiles.length === 1 && subDirs.length === 0) {
+		const moduleExt = path.extname(moduleFiles[0].name);
+		const moduleName = instance._toapiPathKey(path.basename(moduleFiles[0].name, moduleExt));
+
+		
+		const analysis = await analyzeModule(path.join(categoryPath, moduleFiles[0].name), {
+			debug,
+			instance
+		});
+
+		
+		const mod = processModuleFromAnalysis(analysis, { instance, debug });
+
+		
+		const functionNameMatchesFolder = typeof mod === "function" && mod.name && mod.name.toLowerCase() === categoryName.toLowerCase();
+
+		const functionNameMatchesFilename =
+			typeof mod === "function" &&
+			mod.name &&
+			instance._toapiPathKey(mod.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
+			mod.name !== instance._toapiPathKey(moduleName);
+
+		
+
+		
+		
+
+		
+		if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
+			try {
+				Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
+			} catch {
+				
+			}
+			return mod;
+		}
+
+		
+		if (moduleName === categoryName && mod && typeof mod === "object" && !Array.isArray(mod) && currentDepth > 0) {
+			if (debug) {
+				console.log(`[DEBUG] Single-file auto-flattening: ${categoryName}/${moduleFiles[0].name} -> flatten object contents`);
+			}
+
+			
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+				return mod[moduleName]; 
+			}
+
+			
+			
+			
+			
+			
+			
+			if (moduleKeys.length > 1) {
+				if (debug) {
+					console.log(`[DEBUG] Default export flattening: ${categoryName}/${moduleFiles[0].name} -> flatten default object contents`);
+				}
+				return mod; 
+			}
+			return mod;
+		}
+
+		
+		if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			const fileName = moduleFiles[0].name.replace(/\.(mjs|cjs|js)$/, "");
+
+			
+			const isGenericFilename = ["singlefile", "index", "main", "default"].includes(fileName.toLowerCase());
+
+			
+			if (moduleKeys.length === 1 && isGenericFilename) {
+				if (debug) {
+					console.log(
+						`[DEBUG] Single-file parent-level auto-flattening: ${categoryName}/${moduleFiles[0].name} -> flatten to parent level`
+					);
+				}
+				const exportValue = mod[moduleKeys[0]];
+				return { [moduleKeys[0]]: exportValue }; 
+			}
+		}
+
+		
+		if (functionNameMatchesFolder && currentDepth > 0) {
+			try {
+				Object.defineProperty(mod, "name", { value: mod.name, configurable: true });
+			} catch {
+				
+			}
+			return mod;
+		}
+
+		
+		if (functionNameMatchesFilename) {
+			return { [mod.name]: mod };
+		}
+
+		
+		if (typeof mod === "function" && (!mod.name || mod.name === "default" || mod.__slothletDefault === true) && currentDepth > 0) {
+			try {
+				Object.defineProperty(mod, "name", { value: categoryName, configurable: true });
+			} catch {
+				
+			}
+			return mod;
+		}
+
+		
+		const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+		if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+			return mod[moduleName]; 
+		}
+
+		
+		return { [moduleName]: mod };
+	}
+
+	
+	const categoryModules = {};
+
+	
+	const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
+	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
+
+	
+	const defaultExportFiles = [];
+	for (const { fileName } of analysisDefaults) {
+		const file = moduleFiles.find((f) => path.basename(f.name, path.extname(f.name)) === fileName);
+		if (file) {
+			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
+				debug,
+				instance
+			});
+			const processedMod = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+			defaultExportFiles.push({ file, moduleName: instance._toapiPathKey(fileName), mod: processedMod });
+		}
+	}
+
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryStructure: Multi-default analysis results`);
+		console.log(`[DEBUG]   - totalDefaultExports: ${totalDefaultExports}`);
+		console.log(`[DEBUG]   - hasMultipleDefaultExports: ${hasMultipleDefaultExports}`);
+		console.log(`[DEBUG]   - selfReferentialFiles: ${Array.from(selfReferentialFiles)}`);
+	}
+
+	
+	for (const file of moduleFiles) {
+		const moduleExt = path.extname(file.name);
+		const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
+		const fileName = path.basename(file.name, moduleExt);
+		const apiPathKey = instance._toapiPathKey(fileName);
+
+		if (debug && moduleName === "config") {
+			console.log(`[DEBUG] Processing config file: ${file.name}, moduleName: ${moduleName}`);
+			console.log(`[DEBUG] selfReferentialFiles has config? ${selfReferentialFiles.has(moduleName)}`);
+		}
+
+		
+		let mod = null;
+		const existingDefault = defaultExportFiles.find((def) => def.moduleName === moduleName);
+		if (existingDefault) {
+			mod = existingDefault.mod; 
+		} else {
+			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
+				debug,
+				instance
+			});
+			mod = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+		}
+
+		
+		processModuleForAPI({
+			mod,
+			fileName,
+			apiPathKey,
+			hasMultipleDefaultExports,
+			isSelfReferential: selfReferentialFiles.has(moduleName),
+			api: categoryModules,
+			getRootDefault: () => null, 
+			setRootDefault: () => {}, 
+			context: {
+				debug,
+				mode: "category",
+				categoryName,
+				totalModules: moduleFiles.length
+			}
+		});
+	}
+
+	
+	for (const subDirEntry of subDirs) {
+		if (currentDepth < maxDepth) {
+			const key = instance._toapiPathKey(subDirEntry.name);
+			const subDirPath = path.join(categoryPath, subDirEntry.name);
+			let subModule;
+
+			if (mode === "lazy" && typeof subdirHandler === "function") {
+				
+				subModule = subdirHandler({
+					subDirEntry,
+					subDirPath,
+					key,
+					categoryModules,
+					currentDepth,
+					maxDepth
+				});
+			} else {
+				
+				subModule = await buildCategoryStructure(subDirPath, {
+					currentDepth: currentDepth + 1,
+					maxDepth,
+					mode: "eager",
+					instance
+				});
+			}
+
+			
+			
+			if (
+				typeof subModule === "function" &&
+				subModule.name &&
+				subModule.name.toLowerCase() === key.toLowerCase() &&
+				subModule.name !== key
+			) {
+				categoryModules[subModule.name] = subModule; 
+			} else {
+				categoryModules[key] = subModule; 
+			}
+		}
+	}
+
+	return categoryModules;
+}
+
+
+export async function buildRootAPI(dir, options = {}) {
+	const { lazy = false, maxDepth = Infinity, instance } = options;
+
+	if (!instance || typeof instance._shouldIncludeFile !== "function" || typeof instance._loadCategory !== "function") {
+		throw new Error("buildRootAPI requires a valid slothlet instance");
+	}
+
+	const debug = instance.config?.debug || false;
+
+	if (debug) {
+		console.log(`[DEBUG] buildRootAPI called with dir: ${dir}, lazy: ${lazy}, maxDepth: ${maxDepth}`);
+	}
+
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const api = {};
+	let rootDefaultFunction = null;
+
+	
+	const moduleFiles = entries.filter((e) => instance._shouldIncludeFile(e));
+
+	if (moduleFiles.length > 0) {
+		
+		const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
+		const analysis = await multidefault_analyzeModules(moduleFiles, dir, debug);
+		const { hasMultipleDefaultExports, selfReferentialFiles } = analysis;
+
+		
+		for (const entry of moduleFiles) {
+			const ext = path.extname(entry.name);
+			const fileName = path.basename(entry.name, ext);
+			const apiPathKey = instance._toapiPathKey(fileName);
+
+			const analysis = await analyzeModule(path.join(dir, entry.name), {
+				debug,
+				instance
+			});
+			const mod = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+
+			
+			processModuleForAPI({
+				mod,
+				fileName,
+				apiPathKey,
+				hasMultipleDefaultExports,
+				isSelfReferential: selfReferentialFiles.has(fileName),
+				api,
+				getRootDefault: () => rootDefaultFunction,
+				setRootDefault: (fn) => {
+					rootDefaultFunction = fn;
+				},
+				context: {
+					debug,
+					mode: "root",
+					totalModules: moduleFiles.length
+				}
+			});
+		}
+	}
+
+	
+	for (const entry of entries) {
+		if (entry.isDirectory() && !entry.name.startsWith(".")) {
+			const categoryPath = path.join(dir, entry.name);
+
+			if (lazy) {
+				
+				api[instance._toapiPathKey(entry.name)] = await instance._loadCategory(categoryPath, 0, maxDepth);
+			} else {
+				
+				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {
+					currentDepth: 1,
+					maxDepth,
+					mode: "eager",
+					instance
+				});
+			}
+		}
+	}
+
+	
+	let finalApi;
+	if (debug) {
+		console.log(`[DEBUG] Final assembly: rootDefaultFunction=${!!rootDefaultFunction}`);
+		console.log(`[DEBUG] API object keys before final assembly:`, Object.keys(api));
+	}
+
+	if (rootDefaultFunction) {
+		
+		Object.assign(rootDefaultFunction, api);
+		finalApi = rootDefaultFunction;
+
+		if (debug) {
+			console.log(`[DEBUG] Applied root contributor pattern - final API is function`);
+		}
+	} else {
+		
+		finalApi = api;
+
+		if (debug) {
+			console.log(`[DEBUG] No root function - final API is object`);
+		}
+	}
+
+	return finalApi;
+}
+
+
+export async function buildCategoryDecisions(categoryPath, options = {}) {
+	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
+	const { instance } = options;
+
+	if (!instance || typeof instance._toapiPathKey !== "function") {
+		throw new Error("buildCategoryDecisions requires instance parameter with _toapiPathKey method");
+	}
+
+	const debug = instance.config?.debug || false;
+
+	
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryDecisions called with path: ${categoryPath}, mode: ${mode}`);
+	}
+
+	const fs = await import("fs/promises");
+	const path = await import("path");
+
+	const files = await fs.readdir(categoryPath, { withFileTypes: true });
+	const moduleFiles = files.filter((f) => instance._shouldIncludeFile(f));
+	const categoryName = instance._toapiPathKey(path.basename(categoryPath));
+	const subDirs = files.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+
+	const decisions = {
+		type: null, 
+		categoryName,
+		moduleFiles,
+		subDirs,
+		currentDepth,
+		maxDepth,
+		mode,
+		subdirHandler,
+		
+		singleFile: null,
+		shouldFlatten: false,
+		flattenType: null, 
+		preferredName: null,
+		
+		multifileAnalysis: null,
+		processedModules: [],
+		categoryModules: {},
+		
+		subdirectoryDecisions: []
+	};
+
+	
+	if (moduleFiles.length === 1 && subDirs.length === 0) {
+		decisions.type = "single-file";
+		const moduleFile = moduleFiles[0];
+		const moduleExt = path.extname(moduleFile.name);
+		const moduleName = instance._toapiPathKey(path.basename(moduleFile.name, moduleExt));
+
+		decisions.singleFile = {
+			file: moduleFile,
+			moduleName,
+			moduleExt
+		};
+
+		
+		const analysis = await analyzeModule(path.join(categoryPath, moduleFile.name), {
+			debug,
+			instance
+		});
+		const mod = processModuleFromAnalysis(analysis, {
+			debug,
+			instance
+		});
+
+		decisions.singleFile.mod = mod;
+
+		
+		const functionNameMatchesFolder = typeof mod === "function" && mod.name && mod.name.toLowerCase() === categoryName.toLowerCase();
+
+		
+		const functionNameMatchesFilename =
+			typeof mod === "function" &&
+			mod.name &&
+			instance._toapiPathKey(mod.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
+			mod.name !== instance._toapiPathKey(moduleName);
+
+		
+		
+		if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
+			decisions.shouldFlatten = true;
+			decisions.flattenType = "function-folder-match";
+			decisions.preferredName = categoryName;
+			return decisions;
+		}
+
+		
+		
+		if (analysis.hasDefault && analysis.defaultExportType === "object" && moduleName === categoryName && currentDepth > 0) {
+			if (debug) {
+				console.log(`[DEBUG] Default export flattening: ${categoryName}/${moduleFile.name} -> flatten default object contents`);
+			}
+			decisions.shouldFlatten = true;
+			decisions.flattenType = "default-export-flatten";
+			return decisions;
+		}
+
+		
+		
+		if (moduleName === categoryName && mod && typeof mod === "object" && !Array.isArray(mod) && currentDepth > 0) {
+			
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			if (debug) {
+				console.log(
+					`[DEBUG] Auto-flatten check: moduleName="${moduleName}" categoryName="${categoryName}" moduleKeys=[${moduleKeys}] match=${moduleKeys.length === 1 && moduleKeys[0] === moduleName}`
+				);
+			}
+			if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+				if (debug) {
+					console.log(`[DEBUG] Single-file auto-flattening: ${categoryName}/${moduleFile.name} -> flatten object contents`);
+				}
+				decisions.shouldFlatten = true;
+				decisions.flattenType = "object-auto-flatten";
+				decisions.preferredName = moduleKeys[0]; 
+				return decisions;
+			}
+			
+			
+			
+			const fileBaseName = moduleFile.name.replace(/\.(mjs|cjs|js)$/, "");
+			if (fileBaseName === categoryName && moduleKeys.length > 0) {
+				if (debug) {
+					console.log(
+						`[DEBUG] Single-file filename-folder exact match flattening: ${categoryName}/${moduleFile.name} -> avoid double nesting`
+					);
+				}
+				decisions.shouldFlatten = true;
+				decisions.flattenType = "filename-folder-match-flatten";
+				return decisions;
+			}
+		}
+
+		
+		
+		
+		
+		if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
+			const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+			const fileName = moduleFile.name.replace(/\.(mjs|cjs|js)$/, "");
+
+			
+			
+			const isGenericFilename = ["singlefile", "index", "main", "default"].includes(fileName.toLowerCase());
+
+			
+			if (moduleKeys.length === 1 && isGenericFilename) {
+				if (debug) {
+					console.log(`[DEBUG] Single-file parent-level auto-flattening: ${categoryName}/${moduleFile.name} -> flatten to parent level`);
+				}
+				decisions.shouldFlatten = true;
+				decisions.flattenType = "parent-level-flatten";
+				decisions.preferredName = moduleKeys[0];
+				return decisions;
+			}
+		}
+
+		
+		
+		if (functionNameMatchesFolder && currentDepth > 0) {
+			decisions.shouldFlatten = true;
+			decisions.flattenType = "function-folder-match";
+			decisions.preferredName = mod.name;
+			return decisions;
+		}
+
+		
+		if (functionNameMatchesFilename) {
+			decisions.shouldFlatten = false;
+			decisions.preferredName = mod.name;
+			return decisions;
+		}
+
+		
+		
+		
+		if (
+			typeof mod === "function" &&
+			(!mod.name || mod.name === "default" || mod.__slothletDefault === true) && 
+			currentDepth > 0
+		) {
+			decisions.shouldFlatten = true;
+			decisions.flattenType = "default-function";
+			decisions.preferredName = categoryName;
+			return decisions;
+		}
+
+		
+		const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+		if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+			
+			decisions.shouldFlatten = true;
+			decisions.flattenType = "object-auto-flatten";
+			decisions.preferredName = moduleName;
+			return decisions;
+		}
+
+		
+		decisions.shouldFlatten = false;
+		decisions.preferredName = moduleName;
+		if (debug && moduleName === "nest") {
+			console.log(
+				`[DEBUG] buildCategoryDecisions single-file default: moduleName="${moduleName}" shouldFlatten=false preferredName="${decisions.preferredName}"`
+			);
+		}
+		return decisions;
+	}
+
+	
+	decisions.type = "multi-file";
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryDecisions: Processing multi-file case for ${categoryPath}`);
+	}
+
+	
+	const { multidefault_analyzeModules } = await import("@cldmv/slothlet/helpers/multidefault");
+	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, debug);
+
+	decisions.multifileAnalysis = analysis;
+
+	const { totalDefaultExports, hasMultipleDefaultExports, selfReferentialFiles, defaultExportFiles: analysisDefaults } = analysis;
+
+	
+	const defaultExportFiles = [];
+	for (const { fileName } of analysisDefaults) {
+		const file = moduleFiles.find((f) => path.basename(f.name, path.extname(f.name)) === fileName);
+		if (file) {
+			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
+				debug,
+				instance
+			});
+			const processedMod = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+			defaultExportFiles.push({ file, moduleName: instance._toapiPathKey(fileName), mod: processedMod });
+		}
+	}
+
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryDecisions: Using shared multidefault utility results`);
+		console.log(`[DEBUG]   - totalDefaultExports: ${totalDefaultExports}`);
+		console.log(`[DEBUG]   - hasMultipleDefaultExports: ${hasMultipleDefaultExports}`);
+		console.log(`[DEBUG]   - selfReferentialFiles: ${Array.from(selfReferentialFiles)}`);
+	}
+
+	
+	for (const file of moduleFiles) {
+		const moduleExt = path.extname(file.name);
+		const moduleName = instance._toapiPathKey(path.basename(file.name, moduleExt));
+
+		
+		let mod = null;
+		const existingDefault = defaultExportFiles.find((def) => def.moduleName === moduleName);
+		if (existingDefault) {
+			mod = existingDefault.mod; 
+		} else {
+			
+			const analysis = await analyzeModule(path.join(categoryPath, file.name), {
+				debug,
+				instance
+			});
+			mod = processModuleFromAnalysis(analysis, {
+				debug,
+				instance
+			});
+		}
+
+		const moduleDecision = {
+			file,
+			moduleName,
+			mod,
+			type: null, 
+			apiPathKey: null,
+			shouldFlatten: false,
+			flattenType: null,
+			specialHandling: null
+		};
+
+		if (moduleName === categoryName && mod && typeof mod === "object") {
+			moduleDecision.type = "category-match-object";
+			moduleDecision.specialHandling = "category-merge";
+		} else if (typeof mod === "function") {
+			moduleDecision.type = "function";
+
+			
+			const isSelfReferential = selfReferentialFiles.has(moduleName);
+
+			if (hasMultipleDefaultExports && mod.__slothletDefault === true && !isSelfReferential) {
+				
+				moduleDecision.apiPathKey = moduleName;
+				moduleDecision.specialHandling = "multi-default-filename";
+				if (debug) {
+					console.log(
+						`[DEBUG] Multi-default function case: ${moduleName} => ${moduleDecision.apiPathKey} (hasMultiple=${hasMultipleDefaultExports}, __slothletDefault=${mod.__slothletDefault}, isSelfRef=${isSelfReferential})`
+					);
+				}
+			} else if (selfReferentialFiles.has(moduleName)) {
+				
+				moduleDecision.type = "self-referential";
+				moduleDecision.specialHandling = "self-referential-namespace";
+			} else {
+				
+				const fnName = mod.name && mod.name !== "default" ? mod.name : moduleName;
+				if (debug) {
+					console.log(
+						`[DEBUG] Standard function case: ${moduleName}, fnName=${fnName}, mod.__slothletDefault=${mod.__slothletDefault}, hasMultiple=${hasMultipleDefaultExports}`
+					);
+				}
+
+				
+				
+				if (fnName && fnName.toLowerCase() === moduleName.toLowerCase() && fnName !== moduleName) {
+					
+					moduleDecision.apiPathKey = fnName;
+					moduleDecision.specialHandling = "prefer-function-name";
+				} else {
+					
+					moduleDecision.apiPathKey = instance._toapiPathKey(fnName);
+				}
+			}
+		} else {
+			moduleDecision.type = "object";
+
+			
+			let hasPreferredName = false;
+			const modWithPreferredNames = {};
+
+			for (const [exportName, exportValue] of Object.entries(mod)) {
+				if (
+					typeof exportValue === "function" &&
+					exportValue.name &&
+					instance._toapiPathKey(exportValue.name).toLowerCase() === instance._toapiPathKey(moduleName).toLowerCase() &&
+					exportValue.name !== instance._toapiPathKey(moduleName)
+				) {
+					
+					modWithPreferredNames[exportValue.name] = exportValue;
+					hasPreferredName = true;
+				} else {
+					modWithPreferredNames[instance._toapiPathKey(exportName)] = exportValue;
+				}
+			}
+
+			if (hasPreferredName) {
+				moduleDecision.specialHandling = "preferred-export-names";
+				moduleDecision.processedExports = modWithPreferredNames;
+			} else if (selfReferentialFiles.has(moduleName)) {
+				
+				moduleDecision.type = "self-referential";
+				moduleDecision.specialHandling = "self-referential-namespace";
+			} else {
+				
+				const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+				const apiPathKey = instance._toapiPathKey(moduleName);
+
+				
+				
+				if (!hasMultipleDefaultExports && mod.default && typeof mod.default === "object") {
+					moduleDecision.shouldFlatten = true;
+					moduleDecision.flattenType = "single-default-object";
+					moduleDecision.apiPathKey = apiPathKey;
+				} else if (hasMultipleDefaultExports && !mod.default && moduleKeys.length > 0) {
+					
+					moduleDecision.shouldFlatten = true;
+					moduleDecision.flattenType = "multi-default-no-default";
+				} else if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
+					
+					moduleDecision.shouldFlatten = true;
+					moduleDecision.flattenType = "single-named-export-match";
+					moduleDecision.apiPathKey = apiPathKey;
+				} else if (!mod.default && moduleKeys.length > 0 && moduleName === categoryName) {
+					
+					moduleDecision.shouldFlatten = true;
+					moduleDecision.flattenType = "category-name-match-flatten";
+				} else {
+					
+					moduleDecision.apiPathKey = apiPathKey;
+				}
+			}
+		}
+
+		decisions.processedModules.push(moduleDecision);
+	}
+
+	
+	for (const subDir of subDirs) {
+		const subDirPath = path.join(categoryPath, subDir.name);
+		const subDirDecision = {
+			name: subDir.name,
+			path: subDirPath,
+			apiPathKey: instance._toapiPathKey(subDir.name),
+			shouldRecurse: currentDepth < maxDepth
+		};
+		decisions.subdirectoryDecisions.push(subDirDecision);
+	}
+
+	return decisions;
+}