@cldmv/slothlet 2.10.0 → 3.0.0

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

@@ -1,532 +0,0 @@
-/*
-	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
-	};
-}