@cldmv/slothlet 2.11.0 → 3.0.1

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

@@ -1,748 +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 { 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) {
-			console.log(`[DEBUG] ${mode}: About to assign key '${key}' - current api[${key}]:`, api[key] ? Object.keys(api[key]) : "undefined");
-			console.log(`[DEBUG] ${mode}: New value for key '${key}':`, typeof value === "object" && value ? Object.keys(value) : typeof value);
-		}
-
-		
-		if (api[key] && typeof api[key] === "object" && typeof value === "object" && !Array.isArray(api[key]) && !Array.isArray(value)) {
-			if (debug) {
-				console.log(`[DEBUG] ${mode}: Merging objects for key '${key}' - existing:`, Object.keys(api[key]), "new:", Object.keys(value));
-			}
-			
-			Object.assign(api[key], value);
-		} else {
-			api[key] = value;
-		}
-	}
-
-	return {
-		processed,
-		rootDefaultSet,
-		flattened,
-		namespaced,
-		apiAssignments
-	};
-}
-
-
-
-
-
-
-export async function buildCategoryDecisions(categoryPath, options = {}) {
-	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, existingApi: _ } = 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;
-}