@cldmv/slothlet 2.7.1 → 2.9.0

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

@@ -0,0 +1,737 @@
+/*
+	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 { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
+import { analyzeModule, processModuleFromAnalysis } from "@cldmv/slothlet/helpers/api_builder/analysis";
+
+
+
+
+
+
+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 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 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 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 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;
+		return decisions;
+	}
+
+	
+	decisions.type = "multi-file";
+	if (debug) {
+		console.log(`[DEBUG] buildCategoryDecisions: Processing multi-file case for ${categoryPath}`);
+	}
+
+	
+	const analysis = await multidefault_analyzeModules(moduleFiles, categoryPath, { debug, instance });
+
+	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, analysis });
+		}
+	}
+
+	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;
+		let analysis = null;
+		const existingDefault = defaultExportFiles.find((def) => def.moduleName === moduleName);
+		if (existingDefault) {
+			mod = existingDefault.mod; 
+			
+			analysis = existingDefault.analysis;
+		} else {
+			
+			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 && analysis.hasDefault && analysis.defaultExportType === "object") {
+					moduleDecision.shouldFlatten = true;
+					moduleDecision.flattenType = "single-default-object";
+					moduleDecision.apiPathKey = apiPathKey;
+				} else if (hasMultipleDefaultExports && !analysis.hasDefault && 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 (!analysis.hasDefault && 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;
+}