qtools-library-dot-d 1.0.12 → 1.1.0

package/qtools-library-dot-d.js

@@ -12,6 +12,11 @@ const fs = require('fs');
 const qt = require('qtools-functional-library');
 
 //START OF moduleFunction() ============================================================
+// Two ways to load. setLibraryPath(dirPath) is the original single directory, and behaves exactly as in 1.0.13,
+// including swallowing a module's load error into the exception list. setLibraryPathList(pathList) loads framework
+// roots, then instance roots, and refuses by name what single-path mode would let pass silently: name collisions,
+// undeclared overrides, interface failures, load errors and (opt-in) forbidden requires. See README, "Loading from
+// several directories".
 const moduleFunction =
 	({ moduleName } = {}) =>
 	({ libraryName = 'libraryDotD' }) => {
@@ -22,14 +27,19 @@ const moduleFunction =
 		// SET LIBRARY PATH
 
 		let libraryPath;
+		let libraryPathMode = ''; // 'singlePath' (setLibraryPath) or 'pathList' (setLibraryPathList); never both
 
 		const setLibraryPath = (dirPath, callback) => {
+			if (libraryPathMode == 'pathList') {
+				throw `LIBRARY_PATH_MODE_CONFLICT: ${libraryName} already has a path list; setLibraryPath(${dirPath}) refused`;
+			}
 			try {
 				libraryPath = fs.realpathSync(dirPath);
 			} catch (err) {
 				throw err.toString();
 				return;
 			}
+			libraryPathMode = 'singlePath';
 
 			if (typeof callback == 'function') {
 				callback('', libraryPath);
@@ -38,6 +48,149 @@ const moduleFunction =
 			}
 		};
 
+		// --------------------------------------------------------------------------------
+		// SET LIBRARY PATH LIST (instance and framework roots)
+
+		/**
+		 * One root in a path list. A plain string means { dirPath, provenance: 'framework', mayBeAbsent: false }.
+		 * @typedef {Object} PathListEntry
+		 * @property {string} dirPath
+		 * @property {'instance'|'framework'} provenance - framework roots load first, then instance roots
+		 * @property {boolean} [mayBeAbsent=false] - a missing root is refused (PLUGIN_ROOT_NOT_FOUND) unless true
+		 */
+
+		/**
+		 * The contract every element of an interface-checked library must meet (setInterface).
+		 * @interface InterfaceSpec
+		 * @property {string} describeFunctionName - element[describeFunctionName]() returns its description object
+		 * @property {string[]} requiredFunctionList - functions every element must carry
+		 * @property {string} nameFieldName - description field that must equal the name passed to library.add
+		 * @property {string} versionFieldName - description field holding the element's own version
+		 * @property {*} contractVersion - description.contractVersion must equal this (strict ===)
+		 */
+
+		/**
+		 * Where an element came from (getProvenance). overrides is present only for a declared instance override.
+		 * @typedef {Object} ProvenanceRecord
+		 * @property {'instance'|'framework'} provenance
+		 * @property {string} filePath - the module (file or directory) whose require() added the element
+		 * @property {{provenance: string, filePath: string, version: *, reason: string}} [overrides]
+		 */
+
+		const provenanceNameList = ['instance', 'framework'];
+		let libraryPathList = [];
+
+		// Refusals in the setters are thrown when no callback is given, matching setLibraryPath.
+		const deliverResult = (errString, result, callback) => {
+			if (typeof callback == 'function') {
+				callback(errString, result);
+				return;
+			}
+			if (errString) {
+				throw errString;
+			}
+			return result;
+		};
+
+		const normalizePathListEntry = (pathListEntry, entryIndex) => {
+			if (typeof pathListEntry == 'string') {
+				return { dirPath: pathListEntry, provenance: 'framework', mayBeAbsent: false };
+			}
+			const { dirPath, provenance, mayBeAbsent = false } = pathListEntry || {};
+			const problemList = [
+				typeof dirPath == 'string' && dirPath ? '' : 'dirPath must be a non-empty string',
+				provenanceNameList.includes(provenance) ? '' : `provenance must be one of ${provenanceNameList.join(', ')} (got ${JSON.stringify(provenance)})`,
+				typeof mayBeAbsent == 'boolean' ? '' : `mayBeAbsent must be boolean (got ${JSON.stringify(mayBeAbsent)})`,
+			].filter((problem) => problem);
+			if (problemList.length) {
+				return { entryProblem: `PATH_LIST_ENTRY_INVALID: ${libraryName} entry ${entryIndex}: ${problemList.join('; ')}` };
+			}
+			return { dirPath, provenance, mayBeAbsent };
+		};
+
+		const setLibraryPathList = (pathList, callback) => {
+			if (libraryPathMode == 'singlePath') {
+				return deliverResult(`LIBRARY_PATH_MODE_CONFLICT: ${libraryName} already has a single library path; setLibraryPathList refused`, undefined, callback);
+			}
+			if (!Array.isArray(pathList) || !pathList.length) {
+				return deliverResult(`PATH_LIST_INVALID: ${libraryName} setLibraryPathList needs a non-empty array (got ${JSON.stringify(pathList)})`, undefined, callback);
+			}
+
+			const normalizedEntryList = pathList.map(normalizePathListEntry);
+			const problemList = normalizedEntryList
+				.filter(({ entryProblem }) => entryProblem)
+				.map(({ entryProblem }) => entryProblem);
+
+			const resolvedEntryList = normalizedEntryList
+				.filter(({ entryProblem }) => !entryProblem)
+				.map((pathListEntry) => {
+					const { dirPath, provenance, mayBeAbsent } = pathListEntry;
+					const rootExists = fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+					if (rootExists) {
+						return { dirPath: fs.realpathSync(dirPath), provenance, mayBeAbsent, rootIsAbsent: false };
+					}
+					if (mayBeAbsent) {
+						logList.push(`ROOT_ABSENT_ALLOWED: ${provenance} root ${dirPath} is not an existing directory; nothing loaded from it`);
+						return { dirPath, provenance, mayBeAbsent, rootIsAbsent: true };
+					}
+					problemList.push(`PLUGIN_ROOT_NOT_FOUND: ${libraryName} ${provenance} root ${dirPath} is not an existing directory`);
+					return { dirPath, provenance, mayBeAbsent, rootIsAbsent: true };
+				});
+
+			if (problemList.length) {
+				return deliverResult(problemList.join('\n'), undefined, callback);
+			}
+
+			libraryPathList = resolvedEntryList;
+			libraryPathMode = 'pathList';
+			return deliverResult('', libraryPathList.map((pathListEntry) => ({ ...pathListEntry })), callback);
+		};
+
+		// --------------------------------------------------------------------------------
+		// SET INTERFACE (opt-in check of every added item, path-list mode only)
+
+		let interfaceSpec;
+
+		const setInterface = (newInterfaceSpec) => {
+			const { describeFunctionName, requiredFunctionList, nameFieldName, versionFieldName, contractVersion } =
+				newInterfaceSpec || {};
+			const isNameString = (candidate) => typeof candidate == 'string' && candidate;
+			const problemList = [
+				isNameString(describeFunctionName) ? '' : 'describeFunctionName',
+				Array.isArray(requiredFunctionList) && requiredFunctionList.every(isNameString) ? '' : 'requiredFunctionList (array of function names)',
+				isNameString(nameFieldName) ? '' : 'nameFieldName',
+				isNameString(versionFieldName) ? '' : 'versionFieldName',
+				contractVersion !== undefined && contractVersion !== null ? '' : 'contractVersion',
+			].filter((problem) => problem);
+			if (problemList.length) {
+				throw `INTERFACE_SPEC_INCOMPLETE: ${libraryName} setInterface is missing or has invalid: ${problemList.join(', ')}`;
+			}
+			interfaceSpec = { describeFunctionName, requiredFunctionList: [...requiredFunctionList], nameFieldName, versionFieldName, contractVersion };
+			return { ...interfaceSpec };
+		};
+
+		// --------------------------------------------------------------------------------
+		// SET FORBIDDEN REQUIRE CHECK (opt-in static scan, path-list mode only)
+
+		let forbiddenRequireSpec;
+
+		const setForbiddenRequireCheck = (newForbiddenRequireSpec) => {
+			const { provenanceList, allowedModuleList } = newForbiddenRequireSpec || {};
+			const problemList = [
+				Array.isArray(provenanceList) && provenanceList.length && provenanceList.every((provenance) => provenanceNameList.includes(provenance))
+					? ''
+					: `provenanceList must be a non-empty array of ${provenanceNameList.join(', ')}`,
+				Array.isArray(allowedModuleList) && allowedModuleList.every((allowedModuleName) => typeof allowedModuleName == 'string')
+					? ''
+					: 'allowedModuleList must be an array of module names',
+			].filter((problem) => problem);
+			if (problemList.length) {
+				throw `FORBIDDEN_REQUIRE_SPEC_INVALID: ${libraryName} setForbiddenRequireCheck: ${problemList.join('; ')}`;
+			}
+			forbiddenRequireSpec = { provenanceList: [...provenanceList], allowedModuleList: [...allowedModuleList] };
+			return { ...forbiddenRequireSpec };
+		};
+
 		// --------------------------------------------------------------------------------
 		// SET CUSTOM MODULE ADDING FUNCTION
 
@@ -86,12 +239,161 @@ const moduleFunction =
 		const exceptionList = [];
 		const library = (() => {
 			const add = (name, item) => {
+				if (libraryPathMode == 'pathList') {
+					addFromPathList(name, item);
+					return;
+				}
 				libraryObject[name] = item; //used only for producing display listings
 				externalElements[name] = item;
 			};
 			return { add };
 		})();
 
+		// ======================================================================================
+		// PATH LIST ADD (collision, declared override, interface check, provenance)
+
+		const refusalList = [];
+		// No prototype: an element named 'constructor' or 'valueOf' must not find Object.prototype's member.
+		const provenanceByName = Object.create(null); // { provenance, filePath, overrides? } per element
+		const declaredVersionByName = Object.create(null);
+		let loadContext; // { provenance, filePath, addedNameList } while one module is being required
+		let apiNameList = []; // the library's own API names; filled once externalElements exists
+		let reservedNameList = []; // apiNameList plus Object.prototype's members
+
+		const refuse = ({ refusalCode, elementName, filePath, message }) =>
+			refusalList.push({ refusalCode, elementName, filePath, message: `${refusalCode}: ${message}` });
+
+		const checkInterface = (elementName, item) => {
+			const { describeFunctionName, requiredFunctionList, nameFieldName, contractVersion } = interfaceSpec;
+			const missingFunctionList = [describeFunctionName, ...requiredFunctionList].filter(
+				(functionName) => item === null || item === undefined || typeof item[functionName] != 'function',
+			);
+			if (missingFunctionList.length) {
+				return { refusalCode: 'PLUGIN_INTERFACE_INCOMPLETE', message: `'${elementName}' lacks required function(s): ${missingFunctionList.join(', ')}` };
+			}
+			const describeOutput = item[describeFunctionName]();
+			if (describeOutput === null || typeof describeOutput != 'object') {
+				return { refusalCode: 'PLUGIN_INTERFACE_INCOMPLETE', message: `'${elementName}' ${describeFunctionName}() did not return an object` };
+			}
+			if (describeOutput[nameFieldName] !== elementName) {
+				return {
+					refusalCode: 'PLUGIN_NAME_MISMATCH',
+					message: `added as '${elementName}' but ${describeFunctionName}().${nameFieldName} is ${JSON.stringify(describeOutput[nameFieldName])}`,
+				};
+			}
+			if (describeOutput.contractVersion !== contractVersion) {
+				return {
+					refusalCode: 'PLUGIN_CONTRACT_MISMATCH',
+					message: `'${elementName}' declares contractVersion ${JSON.stringify(describeOutput.contractVersion)}; ${libraryName} requires ${JSON.stringify(contractVersion)}`,
+				};
+			}
+			return { describeOutput };
+		};
+
+		const findOverrideDeclarationProblem = (overrideDeclaration) => {
+			const { replacesVersion, reason } = overrideDeclaration;
+			const hasReplacesVersion = replacesVersion !== undefined && replacesVersion !== null && replacesVersion !== '';
+			const hasReason = typeof reason == 'string' && reason;
+			return hasReplacesVersion && hasReason ? '' : 'overridesFramework needs both replacesVersion and a reason';
+		};
+
+		const addFromPathList = (elementName, item) => {
+			if (!loadContext) {
+				// Nothing is loading, so there is no file to attribute this to and no loadModules callback left to report it.
+				throw `PLUGIN_ADD_OUTSIDE_LOAD: ${libraryName} library.add('${elementName}') arrived while no module was loading`;
+			}
+			const { provenance, filePath } = loadContext;
+			const refuseHere = (refusalCode, message) => refuse({ refusalCode, elementName, filePath, message: `${message} (${filePath})` });
+			loadContext.addedNameList.push(elementName);
+
+			if (reservedNameList.includes(elementName)) {
+				const reservedBy = apiNameList.includes(elementName) ? `a ${libraryName} API name` : 'a member of Object.prototype';
+				refuseHere('PLUGIN_NAME_RESERVED', `'${elementName}' is ${reservedBy} and cannot be an element`);
+				return;
+			}
+
+			let describeOutput = {};
+			if (interfaceSpec) {
+				const interfaceResult = checkInterface(elementName, item);
+				if (interfaceResult.refusalCode) {
+					refuseHere(interfaceResult.refusalCode, interfaceResult.message);
+					return;
+				}
+				describeOutput = interfaceResult.describeOutput;
+			}
+
+			// With an interface the declaration lives in the describe output; without one, on the item itself.
+			const overrideDeclaration = interfaceSpec
+				? describeOutput.overridesFramework
+				: item !== null && item !== undefined
+					? item.overridesFramework
+					: undefined;
+			if (overrideDeclaration) {
+				const declarationProblem = findOverrideDeclarationProblem(overrideDeclaration);
+				if (declarationProblem) {
+					refuseHere('PLUGIN_OVERRIDE_DECLARATION_INVALID', `'${elementName}': ${declarationProblem}`);
+					return;
+				}
+			}
+
+			const priorRecord = provenanceByName[elementName];
+			let overrides;
+			if (priorRecord) {
+				const isDeclaredOverride = priorRecord.provenance == 'framework' && provenance == 'instance' && overrideDeclaration;
+				if (!isDeclaredOverride) {
+					refuseHere('PLUGIN_NAME_COLLISION', `'${elementName}' is already loaded from ${priorRecord.filePath}; refused from`);
+					return;
+				}
+				const frameworkVersion = declaredVersionByName[elementName];
+				const { replacesVersion, reason } = overrideDeclaration;
+				if (frameworkVersion === undefined) {
+					logList.push(
+						`OVERRIDE_TARGET_UNVERSIONED: instance '${elementName}' (${filePath}) replaces framework ${priorRecord.filePath}, which declares no version; replacesVersion ${JSON.stringify(replacesVersion)} cannot be checked`,
+					);
+				} else if (frameworkVersion !== replacesVersion) {
+					logList.push(
+						`OVERRIDE_TARGET_CHANGED: instance '${elementName}' (${filePath}) was written against framework version ${JSON.stringify(replacesVersion)}; framework now declares ${JSON.stringify(frameworkVersion)} (${priorRecord.filePath})`,
+					);
+				}
+				overrides = { provenance: priorRecord.provenance, filePath: priorRecord.filePath, version: frameworkVersion, reason };
+			} else if (overrideDeclaration) {
+				logList.push(`OVERRIDE_TARGET_ABSENT: '${elementName}' (${filePath}) declares overridesFramework but no framework element of that name is loaded`);
+			}
+
+			provenanceByName[elementName] = overrides ? { provenance, filePath, overrides } : { provenance, filePath };
+			declaredVersionByName[elementName] = interfaceSpec ? describeOutput[interfaceSpec.versionFieldName] : undefined;
+			libraryObject[elementName] = item; //used only for producing display listings
+			externalElements[elementName] = item;
+		};
+
+		const formatProvenanceSuffix = (elementName) => {
+			const provenanceRecord = provenanceByName[elementName];
+			if (libraryPathMode != 'pathList' || !provenanceRecord) {
+				return '';
+			}
+			const { provenance, filePath, overrides } = provenanceRecord;
+			const overridesString = overrides
+				? `; overrides framework v${overrides.version === undefined ? '(undeclared)' : overrides.version} (${overrides.filePath}) because ${overrides.reason}`
+				: '';
+			return ` [${provenance}: ${filePath}${overridesString}]`;
+		};
+
+		const getProvenance = (elementName) => {
+			if (libraryPathMode != 'pathList') {
+				throw `PROVENANCE_NOT_RECORDED: ${libraryName} records provenance only for libraries loaded with setLibraryPathList`;
+			}
+			const provenanceRecord = provenanceByName[elementName];
+			if (!provenanceRecord) {
+				throw `PROVENANCE_UNKNOWN_NAME: ${libraryName} has no element named '${elementName}'`;
+			}
+			return provenanceRecord.qtClone();
+		};
+
+		const getProvenanceList = () =>
+			Object.keys(libraryObject).map((elementName) => ({ elementName, ...getProvenance(elementName) }));
+
+		const getRefusalList = () => refusalList.map((refusalRecord) => ({ ...refusalRecord }));
+
 		// ======================================================================================
 		// LIBRARY OBJECT
 
@@ -113,7 +415,7 @@ const moduleFunction =
 							(typeof libraryObject[name]).match(/(string|number)/i)
 								? libraryObject[name]
 								: formatProperty(libraryObject[name])
-						}\n\t`,
+						}${formatProvenanceSuffix(name)}\n\t`,
 					`\n${libraryName} Library Elements\n\t`,
 				)
 				.replace(/\n\t$/, '');
@@ -151,6 +453,11 @@ const moduleFunction =
 					{ excludeMode: true },
 				),
 			);
+			if (libraryPathMode == 'pathList') {
+				externalElements.qtSelectProperties(['setLibraryPathList', 'setInterface', 'setForbiddenRequireCheck'], {
+					excludeMode: true,
+				});
+			}
 			Object.freeze(externalElements);
 			Object.seal(externalElements);
 		};
@@ -158,7 +465,240 @@ const moduleFunction =
 		// ======================================================================================
 		// LOAD MODULES (actual execution)
 
-		const loadModules = ({ passThroughParameters }, callback) => {
+		const loadModules = (loadOptions, callback) => {
+			if (libraryPathMode == 'pathList') {
+				return loadModulesFromPathList(loadOptions, callback);
+			}
+			if (interfaceSpec || forbiddenRequireSpec) {
+				refuse({
+					refusalCode: 'REQUIRES_PATH_LIST',
+					elementName: '',
+					filePath: libraryPath,
+					message: `${libraryName} setInterface and setForbiddenRequireCheck apply only to libraries loaded with setLibraryPathList`,
+				});
+				return deliverResult(refusalList[refusalList.length - 1].message, undefined, callback);
+			}
+			return loadModulesFromSinglePath(loadOptions, callback);
+		};
+
+		// --------------------------------------------------------------------------------
+		// LOAD MODULES FROM A PATH LIST
+
+		const moduleFilePattern = /\.(c|m)?js$/;
+		// Static string-literal requires only. A require built from a variable or a ${} template is not seen.
+		const requireCallPattern = /\brequire\s*\(\s*(['"`])([^'"`$]+)\1\s*\)/g;
+
+		const listModuleSourceFiles = (entryPath, isDirectory) =>
+			isDirectory
+				? fs
+						.readdirSync(entryPath, { recursive: true })
+						.filter((relativePath) => moduleFilePattern.test(relativePath))
+						.map((relativePath) => path.join(entryPath, relativePath))
+						.filter((sourceFilePath) => fs.statSync(sourceFilePath).isFile())
+				: [entryPath];
+
+		const requirableExtensionList = ['.js', '.cjs', '.mjs', '.json'];
+
+		const isInsidePath = (candidatePath, containmentRootPath) =>
+			candidatePath == containmentRootPath || candidatePath.startsWith(containmentRootPath + path.sep);
+
+		const isExistingFile = (candidatePath) => fs.existsSync(candidatePath) && fs.statSync(candidatePath).isFile();
+
+		const readPackageMain = (dirPath) => {
+			const packageJsonPath = path.join(dirPath, 'package.json');
+			if (!isExistingFile(packageJsonPath)) {
+				return '';
+			}
+			try {
+				// Plugin-supplied JSON, like a plugin's require(), can only be guarded here.
+				return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).main || '';
+			} catch (err) {
+				return '';
+			}
+		};
+
+		// The file Node would load for a path (exact, with an extension, package.json main, or index), by its realpath.
+		// Returns '' when nothing resolves; the caller treats that as forbidden rather than guessing.
+		const resolveRequirePath = (requestedPath) => {
+			const isDirectory = fs.existsSync(requestedPath) && fs.statSync(requestedPath).isDirectory();
+			const packageMain = isDirectory ? readPackageMain(requestedPath) : '';
+			const candidatePathList = [
+				requestedPath,
+				...requirableExtensionList.map((extension) => `${requestedPath}${extension}`),
+				...(packageMain ? [path.resolve(requestedPath, packageMain), ...requirableExtensionList.map((extension) => `${path.resolve(requestedPath, packageMain)}${extension}`)] : []),
+				...requirableExtensionList.map((extension) => path.join(requestedPath, `index${extension}`)),
+			];
+			const resolvedPath = candidatePathList.find(isExistingFile);
+			return resolvedPath ? fs.realpathSync(resolvedPath) : '';
+		};
+
+		// Why a path is not acceptable as plugin code inside containmentRootPath, or '' when it is.
+		const findPathProblem = (resolvedPath, containmentRootPath) => {
+			if (!resolvedPath) {
+				return 'does not resolve to a file';
+			}
+			if (!isInsidePath(resolvedPath, containmentRootPath)) {
+				return `resolves outside ${containmentRootPath} (${resolvedPath})`;
+			}
+			if (!requirableExtensionList.includes(path.extname(resolvedPath))) {
+				return `resolves to a non-module file (${resolvedPath})`;
+			}
+			return '';
+		};
+
+		const findRequireProblem = ({ requiredName, sourceFilePath, containmentRootPath }) => {
+			if (requiredName.startsWith('.') || path.isAbsolute(requiredName)) {
+				// Node resolves relative to the requiring file's realpath, so a symlinked file is judged where it really is.
+				const requestedPath = path.resolve(path.dirname(fs.realpathSync(sourceFilePath)), requiredName);
+				return findPathProblem(resolveRequirePath(requestedPath), containmentRootPath);
+			}
+			const { allowedModuleList } = forbiddenRequireSpec;
+			const isAllowed = allowedModuleList.includes(requiredName) || allowedModuleList.includes(requiredName.replace(/^node:/, ''));
+			return isAllowed ? '' : 'is not an allowed module';
+		};
+
+		const findForbiddenRequireList = ({ entryPath, isDirectory, rootDirPath }) => {
+			// A directory plugin may use only its own directory; a single-file plugin may use its root.
+			const containmentRootPath = fs.realpathSync(isDirectory ? entryPath : rootDirPath);
+			const entryProblem = findPathProblem(resolveRequirePath(entryPath), containmentRootPath);
+			if (entryProblem) {
+				return [`the module itself ${entryProblem}`];
+			}
+			return listModuleSourceFiles(entryPath, isDirectory).flatMap((sourceFilePath) => {
+				const sourceFileProblem = findPathProblem(fs.realpathSync(sourceFilePath), containmentRootPath);
+				if (sourceFileProblem) {
+					return [`${sourceFilePath} ${sourceFileProblem}`];
+				}
+				return [...fs.readFileSync(sourceFilePath, 'utf8').matchAll(requireCallPattern)]
+					.map((requireMatch) => ({ requiredName: requireMatch[2], requireProblem: findRequireProblem({ requiredName: requireMatch[2], sourceFilePath, containmentRootPath }) }))
+					.filter(({ requireProblem }) => requireProblem)
+					.map(({ requiredName, requireProblem }) => `require('${requiredName}') in ${sourceFilePath} ${requireProblem}`);
+			});
+		};
+
+		const loadOneModule = ({ entryPath, provenance, moduleArgs, tolerateLoadErrors }) => {
+			loadContext = { provenance, filePath: entryPath, addedNameList: [] };
+			let loadErrorString = '';
+			try {
+				// The one catch in path-list mode: a third-party module's top-level throw can only be caught here.
+				require(entryPath)(moduleArgs);
+			} catch (err) {
+				loadErrorString = err.toString().split('\n').qtFirst('n/a');
+			}
+			const { addedNameList } = loadContext;
+			loadContext = undefined;
+
+			if (loadErrorString && tolerateLoadErrors) {
+				const listedString = `PLUGIN_LOAD_FAILED: ${path.basename(entryPath)}: ${loadErrorString}`;
+				exceptionList.push(listedString);
+				logList.push(`${listedString} (${entryPath}; listed because tolerateLoadErrors)`);
+				return;
+			}
+			if (loadErrorString) {
+				refuse({ refusalCode: 'PLUGIN_LOAD_FAILED', elementName: '', filePath: entryPath, message: `${entryPath}: ${loadErrorString}` });
+				return;
+			}
+			if (!addedNameList.length) {
+				logList.push(`MODULE_ADDED_NOTHING: ${provenance} ${entryPath} loaded but called library.add() for nothing`);
+			}
+		};
+
+		const loadOneRoot = ({ pathListEntry, moduleArgs, tolerateLoadErrors }) => {
+			const { dirPath: rootDirPath, provenance } = pathListEntry;
+			const scanForbiddenRequires = forbiddenRequireSpec && forbiddenRequireSpec.provenanceList.includes(provenance);
+
+			fs.readdirSync(rootDirPath).forEach((entryName) => {
+				const entryPath = path.join(rootDirPath, entryName);
+				const isDirectory = fs.statSync(entryPath).isDirectory();
+				if (entryName.startsWith('.') || (!isDirectory && !moduleFilePattern.test(entryName))) {
+					logList.push(`SKIPPED_NON_MODULE: ${provenance} ${entryPath}`);
+					return;
+				}
+				if (scanForbiddenRequires) {
+					const forbiddenRequireList = findForbiddenRequireList({ entryPath, isDirectory, rootDirPath });
+					if (forbiddenRequireList.length) {
+						refuse({
+							refusalCode: 'PLUGIN_FORBIDDEN_REQUIRE',
+							elementName: '',
+							filePath: entryPath,
+							message: `${provenance} ${entryPath} may require only allowed modules or its own files; found ${forbiddenRequireList.join(', ')}`,
+						});
+						return; // never executed
+					}
+				}
+				loadOneModule({ entryPath, provenance, moduleArgs, tolerateLoadErrors });
+			});
+		};
+
+		let pathListLoadCount = 0;
+
+		const loadModulesFromPathList = ({ passThroughParameters, tolerateLoadErrors = false } = {}, callback) => {
+			const asynchronousPipePlus = new require('qtools-asynchronous-pipe-plus')();
+			const pipeRunner = asynchronousPipePlus.pipeRunner;
+			const taskListPlus = asynchronousPipePlus.taskListPlus;
+
+			const taskList = new taskListPlus();
+
+			// --------------------------------------------------------------------------------
+			// REFUSE A SECOND LOAD (every element would collide with itself)
+
+			taskList.push((args, next) => {
+				if (pathListLoadCount > 0) {
+					next(`LOAD_MODULES_REPEATED: ${libraryName} path-list libraries load once; loadModules was already called`, args);
+					return;
+				}
+				pathListLoadCount++;
+				next('', args);
+			});
+
+			// --------------------------------------------------------------------------------
+			// REFUSE A CUSTOM ADD FUNCTION (it cannot report which file failed)
+
+			taskList.push((args, next) => {
+				if (add !== defaultAdd) {
+					next(`CUSTOM_ADD_REQUIRES_SINGLE_PATH: ${libraryName} setCustomAddFunction is not supported with setLibraryPathList`, args);
+					return;
+				}
+				next('', args);
+			});
+
+			// --------------------------------------------------------------------------------
+			// LOAD ROOTS BY PROVENANCE: FRAMEWORK FIRST, THEN INSTANCE, WHATEVER THE LIST ORDER
+
+			taskList.push((args, next) => {
+				const moduleArgs = { dotD: { logList, library }, passThroughParameters };
+				const orderedEntryList = ['framework', 'instance'].flatMap((provenance) =>
+					libraryPathList.filter((pathListEntry) => pathListEntry.provenance == provenance && !pathListEntry.rootIsAbsent),
+				);
+				orderedEntryList.forEach((pathListEntry) => loadOneRoot({ pathListEntry, moduleArgs, tolerateLoadErrors }));
+				next('', args);
+			});
+
+			// --------------------------------------------------------------------------------
+			// REPORT EVERY REFUSAL AT ONCE
+
+			taskList.push((args, next) => {
+				if (refusalList.length) {
+					next(refusalList.map(({ message }) => message).join('\n'), args);
+					return;
+				}
+				next('', args);
+			});
+
+			// --------------------------------------------------------------------------------
+			// INIT AND EXECUTE THE PIPELINE
+
+			let pipeResult;
+			pipeRunner(taskList.getList(), {}, (err) => {
+				pipeResult = deliverResult(err, undefined, callback);
+			});
+			return pipeResult;
+		};
+
+		// --------------------------------------------------------------------------------
+		// LOAD MODULES FROM ONE PATH (1.0.13 behaviour, unchanged)
+
+		const loadModulesFromSinglePath = ({ passThroughParameters }, callback) => {
 			const asynchronousPipePlus = new require(
 				'qtools-asynchronous-pipe-plus',
 			)();
@@ -215,6 +755,12 @@ const moduleFunction =
 
 		const externalElements = {
 			setLibraryPath,
+			setLibraryPathList,
+			setInterface,
+			setForbiddenRequireCheck,
+			getProvenance,
+			getProvenanceList,
+			getRefusalList,
 			setCustomAddFunction,
 			logList,
 			library,
@@ -223,6 +769,11 @@ const moduleFunction =
 			qtdProcessLog: logList.formatList,
 		};
 		externalElements.seal = sealActual(externalElements);
+		// Elements become own properties of this object, so an element may not take an API name, nor a name
+		// Object.prototype carries: '__proto__' would replace the prototype, and a qtools-functional-library
+		// method such as qtSelectProperties (installed on Object.prototype) would be shadowed, breaking seal().
+		apiNameList = Object.keys(externalElements);
+		reservedNameList = [...apiNameList, ...Object.getOwnPropertyNames(Object.prototype)];
 		return externalElements;
 	};