@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/modes/lazy.mjs

@@ -0,0 +1,97 @@
+/*
+	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 { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+export class LazyMode extends ComponentBase {
+	static slothletProperty = "lazy";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+	}
+
+	
+	createNamedMaterializeFunc(apiPath, handler) {
+		const safePath = String(apiPath || "api")
+			.replace(/\./g, "__")
+			.replace(/[^A-Za-z0-9_$]/g, "_");
+		const normalized = /^[A-Za-z_$]/.test(safePath[0]) ? safePath : `_${safePath}`;
+		const funcName = `${normalized}__lazy_materializeFunc`;
+		return {
+			[funcName]: async function (...args) {
+				return handler(...args);
+			}
+		}[funcName];
+	}
+
+	
+	async buildAPI({
+		dir,
+		apiPathPrefix = "",
+		collisionContext = "initial",
+		collisionMode = null,
+		moduleID,
+		apiDepth = Infinity,
+		cacheBust = null,
+		fileFilter = null
+	}) {
+		this.slothlet.debug("modes", {
+			key: "DEBUG_MODE_BUILD_LAZY_API_CALLED",
+			apiPathPrefix,
+			collisionMode,
+			collisionContext
+		});
+		const api = {};
+
+		const { modesProcessor } = this.slothlet.builders;
+		const { loader } = this.slothlet.processors;
+
+		const structure = await loader.scanDirectory(dir, { maxDepth: apiDepth, fileFilter });
+
+		const rootDirectory = {
+			name: ".",
+			path: dir,
+			children: {
+				files: structure.files,
+				directories: structure.directories
+			}
+		};
+
+		const rootDefaultFunction = await modesProcessor.processFiles(
+			api,
+			structure.files,
+			rootDirectory,
+			0,
+			"lazy",
+			true, 
+			false, 
+			false, 
+			apiPathPrefix,
+			collisionContext,
+			moduleID,
+			dir,
+			cacheBust,
+			collisionMode
+		);
+
+		return modesProcessor.applyRootContributor(api, rootDefaultFunction, "lazy");
+	}
+}

package/dist/lib/processors/flatten.mjs

@@ -0,0 +1,453 @@
+/*
+	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 { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+export class Flatten extends ComponentBase {
+	static slothletProperty = "flatten";
+
+	
+	constructor(slothlet) {
+		super(slothlet);
+	}
+
+	
+	#checkSelfReferential(mod, moduleName) {
+		if (!mod || typeof mod !== "object") return false;
+		return mod[moduleName] === mod;
+	}
+
+	
+	async #checkMultiDefault(analysis, hasMultipleDefaults, t) {
+		if (!hasMultipleDefaults) return null;
+
+		
+		if (analysis.hasDefault) {
+			return {
+				preserveAsNamespace: true,
+				reason: await t("FLATTEN_REASON_MULTI_DEFAULT_WITH_DEFAULT")
+			};
+		}
+
+		
+		return {
+			flattenToRoot: true,
+			reason: await t("FLATTEN_REASON_MULTI_DEFAULT_WITHOUT_DEFAULT")
+		};
+	}
+
+	
+	#checkAutoFlatten(mod, moduleName, moduleKeys) {
+		if (moduleKeys.length !== 1) return false;
+		return moduleKeys[0] === moduleName;
+	}
+
+	
+	async getFlatteningDecision(options) {
+		const { mod, moduleName, categoryName, analysis, hasMultipleDefaults, moduleKeys, t } = options;
+
+		
+		
+		const isAddapiFile = moduleName === "addapi";
+		if (isAddapiFile) {
+			
+			if (analysis.hasDefault && analysis.defaultExportType === "object" && moduleKeys.length > 0) {
+				return {
+					flattenToCategory: true,
+					flattenType: "addapi-metadata-default",
+					reason: await t("FLATTEN_REASON_ADDAPI_METADATA_DEFAULT")
+				};
+			}
+			
+			return {
+				flattenToCategory: true,
+				flattenType: "addapi-special-file",
+				reason: await t("FLATTEN_REASON_ADDAPI_SPECIAL_FILE")
+			};
+		}
+
+		
+		if (this.#checkSelfReferential(mod, moduleName)) {
+			return {
+				preserveAsNamespace: true,
+				reason: await t("FLATTEN_REASON_SELF_REFERENTIAL")
+			};
+		}
+
+		
+		const multiDefaultDecision = await this.#checkMultiDefault(analysis, hasMultipleDefaults, t);
+		if (multiDefaultDecision) {
+			
+			
+			if (multiDefaultDecision.preserveAsNamespace) {
+				const exportToCheck = typeof mod === "function" ? mod : mod?.default && typeof mod.default === "function" ? mod.default : null;
+				if (exportToCheck && exportToCheck.name && exportToCheck.name !== "default") {
+					const normalizedFunctionName = exportToCheck.name.toLowerCase().replace(/[-_]/g, "");
+					const normalizedModuleName = moduleName.toLowerCase().replace(/[-_]/g, "");
+					if (normalizedFunctionName === normalizedModuleName) {
+						multiDefaultDecision.preferredName = exportToCheck.name;
+					}
+				}
+			}
+			return multiDefaultDecision;
+		}
+
+		
+		if (this.#checkAutoFlatten(mod, moduleName, moduleKeys)) {
+			return {
+				useAutoFlattening: true,
+				reason: await t("FLATTEN_REASON_SINGLE_EXPORT_MATCHES_FILENAME")
+			};
+		}
+
+		
+		if (moduleName === categoryName) {
+			return {
+				flattenToCategory: true,
+				reason: await t("FLATTEN_REASON_FILENAME_MATCHES_CATEGORY")
+			};
+		}
+
+		
+		
+		const exportToCheck = typeof mod === "function" ? mod : mod?.default && typeof mod.default === "function" ? mod.default : null;
+
+		if (exportToCheck && exportToCheck.name && exportToCheck.name !== "default") {
+			
+			const normalizedFunctionName = exportToCheck.name.toLowerCase().replace(/[-_]/g, "");
+			const normalizedModuleName = moduleName.toLowerCase().replace(/[-_]/g, "");
+			const functionNameMatchesFilename = normalizedFunctionName === normalizedModuleName;
+
+			
+			if (functionNameMatchesFilename) {
+				return {
+					preserveAsNamespace: true,
+					preferredName: exportToCheck.name, 
+					reason: await t("FLATTEN_REASON_PRESERVING_FUNCTION_NAME")
+				};
+			}
+		}
+
+		
+		
+		
+
+		
+		return {
+			preserveAsNamespace: true,
+			reason: await t("FLATTEN_REASON_DEFAULT_PRESERVE_NAMESPACE")
+		};
+	}
+
+	
+	processModuleForAPI(options) {
+		const {
+			mod,
+			decision,
+			moduleName,
+			propertyName,
+			moduleKeys,
+			analysis,
+			file = null,
+			collisionContext = "initial",
+			apiPathPrefix = "",
+			isSelfReferential = false
+		} = options;
+
+		
+		
+		
+		const isAddapiFile =
+			moduleName === "addapi" ||
+			(file && file.name === "addapi") ||
+			(file && file.fullName && ["addapi.mjs", "addapi.cjs", "addapi.js", "addapi.ts"].includes(file.fullName.toLowerCase()));
+		if (isAddapiFile && analysis.hasDefault && moduleKeys.length > 0) {
+			const moduleContent = mod.default;
+			for (const key of moduleKeys) {
+				moduleContent[key] = mod[key];
+			}
+			return { moduleContent };
+		}
+
+		
+		if (decision.useAutoFlattening) {
+			return { moduleContent: mod[moduleName] };
+		}
+
+		
+		if (decision.flattenToRoot || decision.flattenToCategory) {
+			if (mod.default && moduleKeys.length === 0) {
+				return { moduleContent: mod.default };
+			}
+			if (mod.default && moduleKeys.length > 0) {
+				const moduleContent = typeof mod.default === "function" ? mod.default : { ...mod.default };
+				for (const key of moduleKeys) {
+					moduleContent[key] = mod[key];
+				}
+				return { moduleContent };
+			}
+			
+			const moduleContent = {};
+			for (const key of moduleKeys) {
+				moduleContent[key] = mod[key];
+			}
+			return { moduleContent };
+		}
+
+		
+		if (isSelfReferential) {
+			return { moduleContent: mod[moduleName] || mod };
+		}
+
+		
+		if (mod.default && moduleKeys.length > 0) {
+			if (typeof mod.default === "function") {
+				
+				const moduleContent = this.slothlet.helpers.modesUtils.ensureNamedExportFunction(mod.default, propertyName);
+				const collisionConfig = this.slothlet.config.api?.collision || this.slothlet.config.collision;
+				const collisionMode = collisionContext === "initial" ? collisionConfig.initial : collisionConfig.api;
+				for (const key of moduleKeys) {
+					if (!this.shouldAttachNamedExport(key, mod[key], moduleContent, mod.default)) {
+						continue;
+					}
+					const hasExisting = Object.prototype.hasOwnProperty.call(moduleContent, key);
+					if (hasExisting) {
+						if (collisionMode === "merge" || collisionMode === "skip") {
+							
+							continue;
+						} else if (collisionMode === "error") {
+							throw new this.slothlet.SlothletError(
+								"COLLISION_DEFAULT_EXPORT_ERROR",
+								{
+									key,
+									apiPath: `${apiPathPrefix}.${propertyName}`
+								},
+								null,
+								{ validationError: true }
+							);
+						} else if (collisionMode === "warn") {
+							new this.slothlet.SlothletWarning("WARNING_COLLISION_DEFAULT_EXPORT_OVERWRITE", {
+								key,
+								apiPath: `${apiPathPrefix}.${propertyName}`
+							});
+						}
+						
+					}
+					moduleContent[key] = mod[key];
+				}
+				return { moduleContent };
+			}
+			if (typeof mod.default === "object" && mod.default !== null) {
+				
+				const moduleContent = mod.default;
+				for (const key of moduleKeys) {
+					if (key in mod.default) {
+						continue;
+					}
+					if (!this.shouldAttachNamedExport(key, mod[key], moduleContent, mod.default)) {
+						continue;
+					}
+					moduleContent[key] = mod[key];
+				}
+				return { moduleContent };
+			}
+			
+			const moduleContent = { default: mod.default };
+			for (const key of moduleKeys) {
+				moduleContent[key] = mod[key];
+			}
+			return { moduleContent };
+		}
+
+		
+		if (mod.default && moduleKeys.length === 0) {
+			return { moduleContent: this.slothlet.helpers.modesUtils.ensureNamedExportFunction(mod.default, propertyName) };
+		}
+
+		
+		const moduleContent = {};
+		for (const key of moduleKeys) {
+			moduleContent[key] = mod[key];
+		}
+		return { moduleContent };
+	}
+
+	
+	async buildCategoryDecisions(options) {
+		const { categoryName, mod, moduleName, fileBaseName, analysis, moduleKeys, currentDepth, moduleFiles = [], t } = options;
+
+		const decision = {
+			shouldFlatten: false,
+			flattenType: "preserve",
+			preferredName: null,
+			reason: await t("FLATTEN_REASON_NO_CONDITIONS_MET")
+		};
+
+		
+		
+		const isAddapiFile =
+			moduleName === "addapi" ||
+			fileBaseName === "addapi" ||
+			(fileBaseName && ["addapi.mjs", "addapi.cjs", "addapi.js", "addapi.ts"].includes(fileBaseName.toLowerCase()));
+		if (isAddapiFile) {
+			
+			if (analysis.hasDefault && analysis.defaultExportType === "object" && moduleKeys.length > 0) {
+				return {
+					shouldFlatten: true,
+					flattenType: "addapi-metadata-default",
+					reason: await t("FLATTEN_REASON_ADDAPI_SPECIAL_FILE_PARENT")
+				};
+			}
+			
+			return {
+				shouldFlatten: true,
+				flattenType: "addapi-special-file",
+				reason: await t("FLATTEN_REASON_ADDAPI_SPECIAL_FILE")
+			};
+		}
+
+		
+		if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
+			return {
+				shouldFlatten: true,
+				flattenType: "function-folder-match",
+				reason: await t("FLATTEN_REASON_FUNCTION_FOLDER_MATCH")
+			};
+		}
+
+		
+		if (analysis.hasDefault && analysis.defaultExportType === "object" && moduleName === categoryName && currentDepth > 0) {
+			return {
+				shouldFlatten: true,
+				flattenType: "default-export-flatten",
+				reason: await t("FLATTEN_REASON_DEFAULT_OBJECT_EXPORT_FLATTEN")
+			};
+		}
+
+		
+		if (moduleName === categoryName && mod && typeof mod === "object" && !Array.isArray(mod) && currentDepth > 0) {
+			if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+				return {
+					shouldFlatten: true,
+					flattenType: "object-auto-flatten",
+					reason: await t("FLATTEN_REASON_SINGLE_EXPORT_MATCHES_FILENAME")
+				};
+			}
+		}
+
+		
+		if (fileBaseName === categoryName && moduleKeys.length > 0) {
+			return {
+				shouldFlatten: true,
+				flattenType: "filename-folder-match-flatten",
+				reason: await t("FLATTEN_REASON_BASENAME_MATCHES_CATEGORY")
+			};
+		}
+
+		
+		if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
+			const genericFilenames = ["singlefile", "index", "main", "default"];
+			const isGenericFilename = genericFilenames.includes(moduleName.toLowerCase());
+
+			if (moduleKeys.length === 1 && isGenericFilename) {
+				return {
+					shouldFlatten: true,
+					flattenType: "parent-level-flatten",
+					reason: await t("FLATTEN_REASON_GENERIC_FILENAME_SINGLE_EXPORT")
+				};
+			}
+		}
+
+		
+		if (typeof mod === "function" && mod.name && currentDepth > 0) {
+			const functionNameMatchesFolder =
+				mod.name.toLowerCase() === categoryName.toLowerCase() ||
+				mod.name.toLowerCase().replace(/[-_]/g, "") === categoryName.toLowerCase().replace(/[-_]/g, "");
+
+			if (functionNameMatchesFolder) {
+				return {
+					shouldFlatten: true,
+					flattenType: "function-folder-match",
+					preferredName: mod.name,
+					reason: await t("FLATTEN_REASON_FUNCTION_FOLDER_MATCH")
+				};
+			}
+		}
+
+		
+		
+		const exportToCheck = typeof mod === "function" ? mod : mod?.default && typeof mod.default === "function" ? mod.default : null;
+
+		if (exportToCheck && exportToCheck.name && exportToCheck.name !== "default") {
+			
+			const normalizedFunctionName = exportToCheck.name.toLowerCase().replace(/[-_]/g, "");
+			const normalizedModuleName = moduleName.toLowerCase().replace(/[-_]/g, "");
+			const functionNameMatchesFilename = normalizedFunctionName === normalizedModuleName;
+
+			
+			if (functionNameMatchesFilename) {
+				return {
+					shouldFlatten: false,
+					preferredName: exportToCheck.name, 
+					reason: await t("FLATTEN_REASON_PRESERVING_FUNCTION_NAME")
+				};
+			}
+		}
+
+		
+		if (typeof mod === "function" && (!mod.name || mod.name === "default" || mod.__slothletDefault === true) && currentDepth > 0) {
+			return {
+				shouldFlatten: true,
+				flattenType: "default-function",
+				preferredName: categoryName,
+				reason: await t("FLATTEN_REASON_DEFAULT_FUNCTION_EXPORT")
+			};
+		}
+
+		
+		if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
+			return {
+				shouldFlatten: true,
+				flattenType: "object-auto-flatten",
+				preferredName: moduleName,
+				reason: await t("FLATTEN_REASON_SINGLE_EXPORT_MATCHES_MODULE")
+			};
+		}
+
+		return decision;
+	}
+
+	
+	shouldAttachNamedExport(key, value, defaultFunc, originalDefault) {
+		if (!key || key === "default") {
+			return false;
+		}
+		if (value === defaultFunc || value === originalDefault) {
+			return false;
+		}
+		if (typeof defaultFunc === "function" && key === defaultFunc.name) {
+			return false;
+		}
+		if (typeof originalDefault === "function" && key === originalDefault.name) {
+			return false;
+		}
+		return true;
+	}
+}