@cldmv/slothlet 2.11.0 → 3.0.1

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

@@ -1,495 +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 { 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,
-		existingApi: options.existingApi
-	});
-
-	
-	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;
-			}
-		}
-	}
-
-	
-	
-	let defaultFunctions = [];
-	for (const moduleDecision of processedModules) {
-		const { mod, type } = moduleDecision;
-		if (type === "function" && typeof mod === "function") {
-			defaultFunctions.push({ mod, moduleDecision });
-		}
-	}
-
-	
-	
-	
-	if (defaultFunctions.length === 1 && Object.keys(categoryModules).length === 1) {
-		const categoryDefaultFunction = defaultFunctions[0].mod;
-
-		
-		if (categoryDefaultFunction.name !== categoryName) {
-			try {
-				Object.defineProperty(categoryDefaultFunction, "name", { value: categoryName, configurable: true });
-			} catch {
-				
-			}
-		}
-
-		return categoryDefaultFunction;
-	}
-
-	
-	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 buildCategoryStructure(categoryPath, {
-					currentDepth: 1,
-					maxDepth,
-					mode: "lazy",
-					subdirHandler: (ctx) => {
-						
-						return instance._loadCategory(ctx.subDirPath, ctx.currentDepth, ctx.maxDepth);
-					},
-					instance
-				});
-			} 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;
-}