@cldmv/slothlet 2.11.0 → 3.0.1

package/dist/lib/processors/loader.mjs

@@ -0,0 +1,355 @@
+/*
+	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 { readdir, stat } from "node:fs/promises";
+import { join, extname, basename, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
+
+
+export class Loader extends ComponentBase {
+	static slothletProperty = "loader";
+
+	constructor(slothlet) {
+		super(slothlet);
+	}
+
+	
+	async loadModule(filePath, instanceID, moduleID, cacheBust = null) {
+		try {
+			
+			
+			if (filePath.endsWith(".cjs")) {
+				return this.#loadCJSIsolated(filePath);
+			}
+
+			
+			const isTypeScript = filePath.endsWith(".ts") || filePath.endsWith(".mts");
+			const typescriptConfig = this.slothlet.config?.typescript;
+
+			let moduleUrl;
+
+			if (isTypeScript && typescriptConfig?.enabled) {
+				const mode = typescriptConfig.mode;
+				if (mode === "strict") {
+					
+					if (!typescriptConfig.types?.output) {
+						throw new this.SlothletError("TS_STRICT_REQUIRES_OUTPUT", {}, null, { validationError: true });
+					}
+					if (!typescriptConfig.types?.interfaceName) {
+						throw new this.SlothletError("TS_STRICT_REQUIRES_INTERFACE_NAME", {}, null, { validationError: true });
+					}
+
+					
+					if (!this.slothlet._typesGenerated) {
+						const { fork } = await import("child_process");
+						const path = await import("path");
+						const { fileURLToPath } = await import("url");
+
+						
+						const __dirname = path.dirname(fileURLToPath(import.meta.url));
+						const scriptPath = path.resolve(__dirname, "../../../tools/build/generate-types-worker.mjs");
+
+						
+						
+						const childConfig = JSON.stringify({
+							dir: this.slothlet.config.root || this.slothlet.config.dir,
+							mode: "eager",
+							typescript: {
+								enabled: true,
+								mode: "fast"
+							},
+							types: typescriptConfig.types
+						});
+
+						
+						await new Promise((resolve, reject) => {
+							const child = fork(scriptPath, [], {
+								stdio: ["pipe", "pipe", "pipe", "ipc"],
+								env: { ...process.env, SLOTHLET_CONFIG: childConfig }
+							});
+
+							let errorOutput = "";
+
+							child.stderr?.on("data", (data) => {
+								errorOutput += data.toString();
+							});
+
+							child.on("message", (msg) => {
+								
+								
+								if (msg.type === "success") {
+									this.slothlet._typesGenerated = true;
+									resolve();
+									
+									
+									
+									
+								} else if (msg.type === "error") {
+									
+									
+									
+									reject(new this.SlothletError("TS_TYPE_GENERATION_FAILED", {}, { message: msg.error }));
+								}
+								
+							});
+
+							child.on("error", (error) => {
+								reject(new this.SlothletError("TS_TYPE_GENERATION_FORK_FAILED", {}, error));
+							});
+
+							child.on("exit", (code) => {
+								if (code !== 0 && !this.slothlet._typesGenerated) {
+									reject(
+										new this.SlothletError("TS_TYPE_GENERATION_PROCESS_EXITED", { code, output: errorOutput }, null, {
+											validationError: true
+										})
+									);
+								}
+							});
+						});
+					}
+
+					
+					const { transformTypeScriptStrict, createDataUrl, formatDiagnostics } = await import("@cldmv/slothlet/processors/typescript");
+
+					
+					const result = await transformTypeScriptStrict(filePath, {
+						target: typescriptConfig.target,
+						module: typescriptConfig.module,
+						strict: typescriptConfig.strict,
+						typeDefinitionPath: typescriptConfig.types.output,
+						compilerOptions: typescriptConfig.compilerOptions
+					});
+
+					
+					if (result.diagnostics && result.diagnostics.length > 0) {
+						
+						const ts = await import("typescript");
+						const errors = formatDiagnostics(result.diagnostics, ts.default);
+
+						
+						const error = new this.SlothletError("TS_TYPE_CHECK_ERRORS", { filePath, errors: errors.join("\n") }, null, {
+							validationError: true
+						});
+						error.diagnostics = result.diagnostics;
+						throw error;
+					}
+
+					
+					moduleUrl = createDataUrl(result.code);
+				} else {
+					
+					const { transformTypeScript, createDataUrl } = await import("@cldmv/slothlet/processors/typescript");
+
+					
+					const transformedCode = await transformTypeScript(filePath, {
+						target: typescriptConfig.target,
+						sourcemap: typescriptConfig.sourcemap
+					});
+
+					
+					moduleUrl = createDataUrl(transformedCode);
+				}
+			} else {
+				
+				const fileUrl = pathToFileURL(filePath).href;
+				
+				
+				moduleUrl = `${fileUrl}?slothlet_instance=${instanceID}`;
+				if (moduleID) {
+					moduleUrl += `&module=${moduleID}`;
+				}
+				
+				
+				
+				
+				if (cacheBust) {
+					moduleUrl += `&_reload=${cacheBust}`;
+				}
+			}
+
+			const module = await import(moduleUrl);
+			return module;
+		} catch (error) {
+			throw new this.SlothletError(
+				"MODULE_IMPORT_FAILED",
+				{
+					modulePath: filePath
+				},
+				error
+			);
+		}
+	}
+
+	
+	#loadCJSIsolated(filePath) {
+		const requireFn = createRequire(filePath);
+		const resolved = requireFn.resolve(filePath);
+
+		
+		delete requireFn.cache[resolved];
+		const exports = requireFn(resolved);
+		
+		delete requireFn.cache[resolved];
+
+		
+		
+		
+		const namespace = { default: exports };
+		if (exports !== null && typeof exports === "object") {
+			for (const key of Object.keys(exports)) {
+				if (key !== "default") {
+					namespace[key] = exports[key];
+				}
+			}
+		}
+		return namespace;
+	}
+
+	
+	async scanDirectory(dir, options = {}) {
+		
+		const typescriptConfig = this.slothlet.config?.typescript;
+		const defaultExtensions = [".mjs", ".cjs", ".js"];
+		const typescriptExtensions = typescriptConfig?.enabled ? [".ts", ".mts"] : [];
+		const allExtensions = [...defaultExtensions, ...typescriptExtensions];
+
+		const {
+			recursive = true,
+			extensions = allExtensions,
+			isRootScan = true,
+			currentDepth = 0,
+			maxDepth = Infinity,
+			fileFilter = null
+		} = options;
+
+		try {
+			await stat(dir);
+		} catch (error) {
+			throw new this.SlothletError(
+				"INVALID_DIRECTORY",
+				{
+					dir
+				},
+				error
+			);
+		}
+
+		const structure = {
+			files: [], 
+			directories: [] 
+		};
+
+		const entries = await readdir(dir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+
+			if (entry.isDirectory()) {
+				
+				
+				if (fileFilter) {
+					continue;
+				}
+
+				
+				if (recursive && currentDepth < maxDepth) {
+					const subStructure = await this.scanDirectory(fullPath, { ...options, isRootScan: false, currentDepth: currentDepth + 1 });
+					structure.directories.push({
+						path: fullPath,
+						name: entry.name,
+						children: subStructure
+					});
+				}
+			} else if (entry.isFile()) {
+				const ext = extname(entry.name);
+				if (extensions.includes(ext)) {
+					
+					if (entry.name.startsWith("__")) {
+						continue;
+					}
+
+					
+					if (fileFilter && !fileFilter(entry.name)) {
+						continue;
+					}
+
+					const nameWithoutExt = basename(entry.name, ext);
+					structure.files.push({
+						path: fullPath,
+						name: nameWithoutExt,
+						fullName: entry.name,
+						moduleID: this.slothlet.helpers.sanitize.getModuleId(fullPath, dir)
+					});
+				}
+			}
+		}
+
+		
+		if (isRootScan && structure.files.length === 0 && structure.directories.length === 0) {
+			new this.SlothletWarning("WARN_DIRECTORY_EMPTY", {
+				dir,
+				resolvedPath: resolve(dir)
+			});
+		}
+
+		return structure;
+	}
+
+	
+	extractExports(module) {
+		const exports = {};
+
+		
+		if (module.default !== undefined) {
+			exports.default = module.default;
+		}
+
+		
+		for (const key of Object.keys(module)) {
+			if (key !== "default" && key !== "module.exports" && typeof key === "string") {
+				exports[key] = module[key];
+			}
+		}
+
+		
+		
+		
+		
+		if (exports.default && typeof exports.default === "object" && exports.default !== null && "default" in exports.default) {
+			
+			
+			const rootNamedKeys = Object.keys(exports).filter((k) => k !== "default" && k !== "module.exports");
+			const defaultKeys = Object.keys(exports.default).filter((k) => k !== "default");
+
+			
+			const isCJSPattern = rootNamedKeys.every((k) => k in exports.default);
+
+			if (isCJSPattern && defaultKeys.length > 0) {
+				
+				
+				exports.default = exports.default.default;
+			}
+		}
+
+		return exports;
+	}
+}

package/dist/lib/processors/type-generator.mjs

@@ -0,0 +1,291 @@
+/*
+	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 "fs";
+import path from "path";
+import { SlothletError } from "@cldmv/slothlet/errors";
+
+let typescriptInstance = null;
+
+
+async function getTypeScript() {
+	if (!typescriptInstance) {
+		try {
+			typescriptInstance = await import("typescript");
+			
+			
+			
+		} catch (error) {
+			throw new SlothletError("TYPESCRIPT_NOT_INSTALLED", { feature: "type-generation" }, error);
+		}
+		
+	}
+	return typescriptInstance;
+}
+
+
+export async function generateTypes(api, options) {
+	const ts = await getTypeScript();
+
+	if (!options.output) {
+		throw new SlothletError("INVALID_CONFIG", {
+			option: "types.output",
+			expected: "a string output path",
+			value: options.output,
+			hint: "Provide a string output path for the generated .d.ts file, e.g. './types/api.d.ts'.",
+			validationError: true
+		});
+	}
+
+	if (!options.interfaceName) {
+		throw new SlothletError("INVALID_CONFIG", {
+			option: "types.interfaceName",
+			expected: "a string interface name",
+			value: options.interfaceName,
+			hint: "Provide a string interface name for the generated TypeScript interface, e.g. 'SlothletAPI'.",
+			validationError: true
+		});
+	}
+
+	
+	const nodes = traverseAPI(api);
+
+	
+	for (const node of nodes) {
+		if (node.metadata?.filePath) {
+			node.typeInfo = await extractTypesFromFile(node.metadata.filePath, ts);
+		}
+	}
+
+	
+	const declaration = generateDeclaration(nodes, options);
+
+	
+	const outputPath = path.resolve(options.output);
+	const outputDir = path.dirname(outputPath);
+
+	if (!fs.existsSync(outputDir)) {
+		fs.mkdirSync(outputDir, { recursive: true });
+	}
+
+	fs.writeFileSync(outputPath, declaration, "utf8");
+
+	return {
+		output: declaration,
+		filePath: outputPath
+	};
+}
+
+
+function traverseAPI(api, currentPath = [], visited = new Set()) {
+	const nodes = [];
+
+	if (!api || typeof api !== "object") {
+		return nodes;
+	}
+
+	
+	if (visited.has(api)) {
+		return nodes;
+	}
+	visited.add(api);
+
+	for (const [key, value] of Object.entries(api)) {
+		
+		if (key.startsWith("_") || key.startsWith("__") || key === "slothlet" || key === "shutdown" || key === "destroy") {
+			continue;
+		}
+
+		const nodePath = [...currentPath, key];
+		const metadata = value?.__metadata;
+
+		if (typeof value === "function") {
+			nodes.push({
+				type: "function",
+				path: nodePath,
+				value,
+				metadata
+			});
+		} else if (typeof value === "object" && value !== null) {
+			nodes.push({
+				type: "object",
+				path: nodePath,
+				value,
+				metadata
+			});
+
+			
+			const childNodes = traverseAPI(value, nodePath, visited);
+			nodes.push(...childNodes);
+		}
+	}
+
+	return nodes;
+}
+
+
+async function extractTypesFromFile(filePath, ts) {
+	try {
+		const source = fs.readFileSync(filePath, "utf8");
+		const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+
+		const exports = [];
+
+		
+		function visit(node) {
+			
+			if (ts.isFunctionDeclaration(node) && node.name) {
+				const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+				
+				
+				if (hasExport) {
+					exports.push({
+						name: node.name.text,
+						type: "function",
+						signature: extractFunctionSignature(node, source, ts)
+					});
+				}
+			}
+
+			
+			if (ts.isVariableStatement(node)) {
+				const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+				if (hasExport) {
+					for (const decl of node.declarationList.declarations) {
+						if (!decl.name || !ts.isIdentifier(decl.name)) continue;
+						const init = decl.initializer;
+						if (!init) continue;
+						if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+							exports.push({
+								name: decl.name.text,
+								type: "function",
+								signature: extractFunctionSignature(init, source, ts)
+							});
+						}
+					}
+				}
+			}
+
+			ts.forEachChild(node, visit);
+		}
+
+		visit(sourceFile);
+
+		return { exports, sourceFile };
+	} catch (____error) {
+		
+		return { exports: [] };
+	}
+}
+
+
+function extractFunctionSignature(node, ____source, ____ts) {
+	const params = node.parameters
+		.map((p) => {
+			const name = p.name.getText(node.getSourceFile());
+			const type = p.type ? p.type.getText(node.getSourceFile()) : "any";
+			return `${name}: ${type}`;
+		})
+		.join(", ");
+
+	const returnType = node.type ? node.type.getText(node.getSourceFile()) : "any";
+
+	return `(${params}): ${returnType}`;
+}
+
+
+function generateDeclaration(nodes, options) {
+	const interfaceName = options.interfaceName;
+	const lines = [];
+
+	lines.push("");
+	lines.push("");
+
+	
+	const structure = {};
+
+	for (const node of nodes) {
+		if (node.type === "function") {
+			
+			
+			
+			const fnName = node.path[node.path.length - 1];
+			const exportInfo = node.typeInfo?.exports?.find((e) => e.name === fnName);
+			
+			
+			const signature = exportInfo?.signature ?? "(...args: any[]): any";
+			setNestedProperty(structure, node.path, { type: "function", signature });
+		}
+		
+		
+	}
+
+	
+	lines.push(`export interface ${interfaceName} {`);
+	generateInterfaceContent(structure, lines, 1);
+	lines.push("}");
+	lines.push("");
+
+	
+	lines.push(`declare const self: ${interfaceName};`);
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+
+function setNestedProperty(obj, path, value) {
+	let current = obj;
+
+	for (let i = 0; i < path.length - 1; i++) {
+		const key = path[i];
+		if (!current[key]) {
+			current[key] = {};
+		}
+		current = current[key];
+	}
+
+	const lastKey = path[path.length - 1];
+	current[lastKey] = value;
+}
+
+
+function generateInterfaceContent(structure, lines, indent) {
+	const indentation = "\t".repeat(indent);
+
+	for (const [key, value] of Object.entries(structure)) {
+		
+		
+		if (value.type === "function") {
+			lines.push(`${indentation}${key}${value.signature};`);
+			
+			
+			
+		} else if (typeof value === "object" && value !== null) {
+			
+			lines.push(`${indentation}${key}: {`);
+			generateInterfaceContent(value, lines, indent + 1);
+			lines.push(`${indentation}};`);
+		} else {
+			
+		}
+		
+	}
+}