@cldmv/slothlet 2.7.1 → 2.9.0

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

@@ -0,0 +1,457 @@
+/*
+	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 { types as utilTypes } from "node:util";
+import { sanitizePathName } from "@cldmv/slothlet/helpers/sanitize";
+import { multidefault_analyzeModules } from "@cldmv/slothlet/helpers/multidefault";
+import { analyzeModule, processModuleFromAnalysis } from "@cldmv/slothlet/helpers/api_builder/analysis";
+import { processModuleForAPI, buildCategoryDecisions } from "@cldmv/slothlet/helpers/api_builder/decisions";
+
+
+
+
+
+
+export function toapiPathKey(name, sanitizeConfig = {}) {
+	return sanitizePathName(name, sanitizeConfig);
+}
+
+
+export function shouldIncludeFile(entry) {
+	
+	if (!entry.isFile()) return false;
+	
+	if (!(entry.name.endsWith(".mjs") || entry.name.endsWith(".cjs") || entry.name.endsWith(".js"))) return false;
+	
+	if (entry.name.startsWith(".")) return false;
+	
+	if (entry.name.startsWith("__slothlet_")) return false;
+	return true;
+}
+
+
+
+
+
+
+export async function buildCategoryStructure(categoryPath, options = {}) {
+	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, instance } = options;
+
+	if (!instance || typeof instance._toapiPathKey !== "function") {
+		throw new Error("buildCategoryStructure requires a valid slothlet instance");
+	}
+
+	
+	const decisions = await buildCategoryDecisions(categoryPath, {
+		currentDepth,
+		maxDepth,
+		mode,
+		subdirHandler,
+		instance
+	});
+
+	
+	if (decisions.type === "single-file") {
+		const { singleFile } = decisions;
+		const { mod, moduleName } = singleFile;
+
+		
+		if (decisions.shouldFlatten) {
+			switch (decisions.flattenType) {
+				case "function-folder-match":
+				case "default-function":
+					try {
+						Object.defineProperty(mod, "name", { value: decisions.preferredName, configurable: true });
+					} catch {
+						
+					}
+					return mod;
+
+				case "default-export-flatten":
+					
+					return mod;
+
+				case "object-auto-flatten":
+					
+					return mod[decisions.preferredName];
+
+				case "parent-level-flatten": {
+					
+					const exportValue = mod[Object.keys(mod).filter((k) => k !== "default")[0]];
+					return { [decisions.preferredName]: exportValue };
+				}
+
+				case "filename-folder-match-flatten":
+					
+					return mod;
+			}
+		}
+
+		
+		if (decisions.preferredName && decisions.preferredName !== moduleName) {
+			return { [decisions.preferredName]: mod };
+		}
+
+		
+		return { [moduleName]: mod };
+	}
+
+	
+	const categoryModules = {};
+	const { categoryName, processedModules, subdirectoryDecisions } = decisions;
+
+	
+	for (const moduleDecision of processedModules) {
+		const { moduleName, mod, type, apiPathKey, shouldFlatten, flattenType, specialHandling, processedExports } = moduleDecision;
+		
+		if (specialHandling === "category-merge") {
+			
+			if (Object.prototype.hasOwnProperty.call(mod, categoryName) && typeof mod[categoryName] === "object" && mod[categoryName] !== null) {
+				Object.assign(categoryModules, mod[categoryName]);
+				for (const [key, value] of Object.entries(mod)) {
+					if (key !== categoryName) categoryModules[instance._toapiPathKey(key)] = value;
+				}
+			} else {
+				Object.assign(categoryModules, mod);
+			}
+		} else if (type === "function") {
+			
+			if (specialHandling === "multi-default-filename") {
+				try {
+					Object.defineProperty(mod, "name", { value: moduleName, configurable: true });
+				} catch {
+					
+				}
+				categoryModules[moduleName] = mod;
+			} else if (specialHandling === "prefer-function-name") {
+				categoryModules[apiPathKey] = mod;
+			} else {
+				
+				categoryModules[apiPathKey] = mod;
+			}
+		} else if (type === "self-referential") {
+			
+			categoryModules[moduleName] = mod[moduleName] || mod;
+		} else if (type === "object") {
+			
+			if (specialHandling === "preferred-export-names") {
+				Object.assign(categoryModules, processedExports);
+			} else if (shouldFlatten) {
+				switch (flattenType) {
+					case "single-default-object": {
+						
+						
+						let flattened;
+
+						
+						const defaultExport = mod.default;
+						const hasNamedExports = Object.keys(mod).some((k) => k !== "default");
+
+						if (hasNamedExports && defaultExport && typeof defaultExport === "object") {
+							
+							const isProxy = utilTypes?.isProxy?.(defaultExport) ?? false;
+
+							if (isProxy) {
+								
+								flattened = defaultExport;
+								let assignmentFailed = false;
+								
+								const failedMap = new Map();
+
+								
+								for (const [key, value] of Object.entries(mod)) {
+									if (key !== "default") {
+										try {
+											flattened[key] = value;
+										} catch (e) {
+											
+											assignmentFailed = true;
+											failedMap.set(key, value);
+											if (instance.config?.debug) {
+												console.warn(
+													`Could not assign '${key}' to proxy object in module '${moduleName}' at '${categoryPath}':`,
+													e.message
+												);
+											}
+										}
+									}
+								}
+
+								
+								if (assignmentFailed) {
+									
+									
+									
+									
+									
+									
+									
+									
+									
+									const originalProxy = flattened;
+									flattened = new Proxy(originalProxy, {
+										get(target, prop, receiver) {
+											
+											if (failedMap.has(prop)) return failedMap.get(prop);
+
+											
+											return Reflect.get(target, prop, receiver);
+										},
+										has(target, prop) {
+											
+											if (failedMap.has(prop)) return true;
+											return Reflect.has(target, prop);
+										},
+										ownKeys(target) {
+											const originalKeys = Reflect.ownKeys(target);
+											const failedKeys = Array.from(failedMap.keys());
+											return [...new Set([...originalKeys, ...failedKeys])];
+										},
+										getOwnPropertyDescriptor(target, prop) {
+											if (failedMap.has(prop)) {
+												return { configurable: true, enumerable: true, value: failedMap.get(prop) };
+											}
+											return Reflect.getOwnPropertyDescriptor(target, prop);
+										}
+									});
+								}
+							} else {
+								
+								flattened = { ...defaultExport };
+								for (const [key, value] of Object.entries(mod)) {
+									if (key !== "default") {
+										flattened[key] = value;
+									}
+								}
+							}
+						} else {
+							
+							flattened = defaultExport;
+						}
+
+						categoryModules[apiPathKey] = flattened;
+						break;
+					}
+					case "multi-default-no-default": {
+						
+						const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+						for (const key of moduleKeys) {
+							categoryModules[key] = mod[key];
+						}
+						break;
+					}
+					case "single-named-export-match":
+						
+						categoryModules[apiPathKey] = mod[apiPathKey];
+						break;
+					case "category-name-match-flatten": {
+						
+						const moduleKeys = Object.keys(mod).filter((k) => k !== "default");
+						for (const key of moduleKeys) {
+							categoryModules[key] = mod[key];
+						}
+						break;
+					}
+				}
+			} else {
+				
+				categoryModules[apiPathKey] = mod;
+			}
+		}
+	}
+
+	
+	for (const subDirDecision of subdirectoryDecisions) {
+		if (subDirDecision.shouldRecurse) {
+			const { name, path: subDirPath, apiPathKey } = subDirDecision;
+			let subModule;
+
+			if (mode === "lazy" && typeof subdirHandler === "function") {
+				subModule = subdirHandler({
+					subDirEntry: { name },
+					subDirPath,
+					key: apiPathKey,
+					categoryModules,
+					currentDepth,
+					maxDepth
+				});
+			} else {
+				subModule = await buildCategoryStructure(subDirPath, {
+					currentDepth: currentDepth + 1,
+					maxDepth,
+					mode: "eager",
+					instance
+				});
+			}
+
+			
+			
+			if (
+				typeof subModule === "function" &&
+				subModule.name &&
+				subModule.name.toLowerCase() === apiPathKey.toLowerCase() &&
+				subModule.name !== apiPathKey
+			) {
+				
+				categoryModules[subModule.name] = subModule;
+			} else {
+				categoryModules[apiPathKey] = subModule;
+			}
+		}
+	}
+
+	
+	const keys = Object.keys(categoryModules);
+	if (keys.length === 1) {
+		const singleKey = keys[0];
+		if (singleKey === categoryName) {
+			const single = categoryModules[singleKey];
+			if (typeof single === "function") {
+				if (single.name !== categoryName) {
+					try {
+						Object.defineProperty(single, "name", { value: categoryName, configurable: true });
+					} catch {
+						
+					}
+				}
+				return single;
+			} else if (single && typeof single === "object" && !Array.isArray(single)) {
+				return single;
+			}
+		}
+	}
+
+	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 analysis = await multidefault_analyzeModules(moduleFiles, dir, { debug, instance });
+		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;
+}