@cldmv/slothlet 2.8.0 → 2.10.0

package/dist/lib/helpers/api_builder/analysis.mjs

@@ -0,0 +1,532 @@
+/*
+	Copyright 2026 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 { types as utilTypes } from "node:util";
+import { pathToFileURL } from "node:url";
+import { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
+import { setActiveInstance } from "@cldmv/slothlet/helpers/instance-manager";
+
+
+
+
+
+
+export function isLikelySerializable(val) {
+	const type = typeof val;
+
+	
+	if (type !== "object" || val === null) {
+		return type === "string" || type === "number" || type === "boolean" || type === "undefined";
+	}
+
+	
+	return (
+		Array.isArray(val) || val instanceof Date || val instanceof RegExp || val?.constructor === Object || typeof val.toJSON === "function" 
+	);
+}
+
+
+
+
+
+
+export async function analyzeModule(modulePath, options = {}) {
+	const { debug = false, instance = null } = options;
+
+	const moduleUrl = pathToFileURL(modulePath).href;
+
+	
+	
+	let importUrl = moduleUrl;
+	const separator = moduleUrl.includes("?") ? "&" : "?";
+
+	
+	importUrl = `${moduleUrl}${separator}_t=${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+	if (instance && instance.instanceId) {
+		const runtimeType = instance.config?.runtime || "async";
+
+		
+		if (runtimeType === "live") {
+			importUrl = `${importUrl}&slothlet_instance=${instance.instanceId}`;
+			importUrl = `${importUrl}&slothlet_runtime=${runtimeType}`;
+
+			
+			setActiveInstance(instance.instanceId);
+		}
+		
+		
+	}
+
+	if (debug) {
+		console.log(`[DEBUG] analyzeModule: Importing ${path.basename(modulePath)}`);
+		console.log(`[DEBUG]   URL: ${importUrl}`);
+	}
+
+	const rawModule = await import(importUrl);
+
+	
+	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; 
+
+		
+		const namedExportsToAdd = Object.entries(processedModule).filter(
+			([exportName, exportValue]) => exportName !== "default" && exportValue !== obj
+		);
+
+		if (namedExportsToAdd.length > 0) {
+			
+			
+			const isCustomProxy = utilTypes?.isProxy?.(obj) ?? false;
+
+			if (isCustomProxy) {
+				
+				
+				for (const [exportName, exportValue] of namedExportsToAdd) {
+					const apiKey = instance._toapiPathKey(exportName);
+					obj[apiKey] = exportValue;
+				}
+
+				
+				
+				const proxyWithStructure = obj; 
+
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				
+				proxyWithStructure.default = obj; 
+
+				
+				if (!proxyWithStructure.toJSON) {
+					Object.defineProperty(proxyWithStructure, "toJSON", {
+						value: function () {
+							
+							const serializable = {};
+
+							
+							for (const key of Reflect.ownKeys(this)) {
+								
+								if (typeof key !== "string") continue;
+
+								const descriptor = Reflect.getOwnPropertyDescriptor(this, key);
+								if (!descriptor || !descriptor.enumerable) continue;
+
+								if (key === "default") {
+									
+									continue;
+								}
+
+								const value = this[key];
+								if (typeof value === "function") {
+									serializable[key] = "[Function]";
+								} else if (isLikelySerializable(value)) {
+									
+									serializable[key] = value;
+								} else {
+									
+									try {
+										JSON.stringify(value);
+										serializable[key] = value;
+									} catch {
+										serializable[key] = "[Non-serializable value]";
+									}
+								}
+							}
+
+							
+							serializable._slothlet_proxy_info = {
+								type: "proxy",
+								circular_reference: "Property .default points to this object (excluded from serialization)",
+								warning: "This is a slothlet API proxy with circular .default reference"
+							};
+							return serializable;
+						},
+						writable: false,
+						enumerable: false,
+						configurable: true
+					});
+				}
+
+				
+				for (const [exportName, exportValue] of namedExportsToAdd) {
+					const apiKey = instance._toapiPathKey(exportName);
+					if (!(apiKey in proxyWithStructure)) {
+						proxyWithStructure[apiKey] = exportValue;
+					}
+				}
+
+				return proxyWithStructure;
+			} else {
+				
+				for (const [exportName, exportValue] of namedExportsToAdd) {
+					obj[instance._toapiPathKey(exportName)] = exportValue;
+				}
+
+				return obj;
+			}
+		}
+
+		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") {
+		multiDefaultAnalysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
+	}
+
+	
+	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
+	};
+}