qtools-library-dot-d 1.0.13 → 1.1.0

package/README.md

@@ -227,8 +227,96 @@ The dotD pattern works particularly well in:
 
 This pattern is used extensively in the qtools ecosystem for building scalable, maintainable Node.js applications.
 
+## Loading from several directories
+
+*New in 1.1.0. Opt-in: nothing changes for a library that uses `setLibraryPath`.*
+
+A library can load from an ordered list of roots, so that one installation (an *instance*) can add its own modules beside the shared *framework* ones, and replace a framework module only by saying so.
+
+```javascript
+const screenersDotD = qtLibDotD({ libraryName: 'corpusScreeners' });
+
+screenersDotD.setInterface({            // optional; checks every element
+    describeFunctionName: 'describeCorpusScreener',
+    requiredFunctionList: ['screenCorpus'],
+    nameFieldName: 'corpusScreenerName',
+    versionFieldName: 'corpusScreenerVersion',
+    contractVersion: 1,
+});
+
+screenersDotD.setForbiddenRequireCheck({ // optional; static scan of instance source
+    provenanceList: ['instance'],
+    allowedModuleList: require('module').builtinModules,
+});
+
+screenersDotD.setLibraryPathList([
+    { dirPath: instanceScreenersPath, provenance: 'instance', mayBeAbsent: true },
+    { dirPath: frameworkScreenersPath, provenance: 'framework' },
+]);
+
+screenersDotD.loadModules({ passThroughParameters }, (err) => {
+    // err names every refusal, one per line; '' when all loaded
+});
+```
+
+### The rules
+
+- **Entries.** `{ dirPath, provenance: 'instance' | 'framework', mayBeAbsent }`. A plain string is a framework root that must exist. `mayBeAbsent` is optional and false when omitted.
+- **Order.** Framework roots load first, then instance roots, whatever order the list gives them in.
+- **Missing roots.** Refused as `PLUGIN_ROOT_NOT_FOUND` unless `mayBeAbsent` is true, in which case the log says `ROOT_ABSENT_ALLOWED`.
+- **What is a module.** A `.js`/`.cjs`/`.mjs` file or a directory (`require()` must resolve it: `package.json` `main` or `index.js`). Dotfiles and other files are skipped and logged as `SKIPPED_NON_MODULE`; in single-path mode they would be "ignoring invalid file" lines.
+- **One name, one element.** A name added a second time is refused as `PLUGIN_NAME_COLLISION`, naming both files, unless an instance element replaces a framework element **and declares it**:
+
+  ```javascript
+  overridesFramework: { replacesVersion: '1', reason: 'why this instance needs its own' }
+  ```
+
+  The declaration lives in the element's describe output when an interface is set, otherwise on the element itself (an object or function property). It needs both fields, or it is refused as `PLUGIN_OVERRIDE_DECLARATION_INVALID`. Two framework elements, or two instance elements, of one name always collide.
+- **Stale overrides warn.** When `replacesVersion` is not strictly equal to the framework element's declared version (`versionFieldName`), the override is accepted and the log says `OVERRIDE_TARGET_CHANGED`. Without an interface there is no framework version to compare, and the log says `OVERRIDE_TARGET_UNVERSIONED`. A declaration with nothing to replace logs `OVERRIDE_TARGET_ABSENT`.
+- **Interface check.** With `setInterface`, all five fields are required (`INTERFACE_SPEC_INCOMPLETE`). Each element must carry the describe function and every required function (`PLUGIN_INTERFACE_INCOMPLETE`), describe itself by the name it was added under (`PLUGIN_NAME_MISMATCH`), and declare the library's `contractVersion` (`PLUGIN_CONTRACT_MISMATCH`).
+- **Load errors are refusals.** A module whose `require()` throws is refused as `PLUGIN_LOAD_FAILED`, naming the file. `loadModules({ passThroughParameters, tolerateLoadErrors: true })` lists it in the exception list instead, still as `PLUGIN_LOAD_FAILED`.
+- **Forbidden requires.** With `setForbiddenRequireCheck`, the source of every module from a listed provenance is scanned before it runs. A refused module is never executed (`PLUGIN_FORBIDDEN_REQUIRE`).
+  - **What is allowed:**
+    - names in `allowedModuleList` (a `node:` prefix is ignored);
+    - relative or absolute paths whose resolved file, judged by its real path after symlinks, stays inside the plugin's own directory. For a single-file module, that is its root.
+  - **What is refused:**
+    - a path that resolves to a non-module file, such as `require('./payload.txt')`, which CommonJS would run as JavaScript;
+    - a path that does not resolve at all;
+    - a module whose own real path, or `package.json` `main`, lies outside its directory.
+  - **What the scan cannot see.** The scan reads every `.js`/`.cjs`/`.mjs` file in a directory module, recursively (this needs Node 20 or later). It is a regular expression over string-literal `require('…')` and static template calls. It does **not** catch:
+    - a require whose name is built at run time: a variable, string concatenation, or a `${}` template;
+    - `import()`;
+    - `module.createRequire` (`module` is a built-in, so allowed).
+
+    It also refuses a `require('…')` that appears only in a comment. That is a false refusal, not a missed one.
+  - **Why the check exists.** It serves portability (spec R6), not security: it is not a sandbox.
+- **Reserved names.** An element may not take a library API name such as `toString` or `getProvenance`, nor a name `Object.prototype` carries (`constructor`, `hasOwnProperty`, `__proto__`, and the `qt…` methods qtools-functional-library installs there). Elements are properties of the library object itself, so such a name would shadow a method the library relies on: `qtSelectProperties` would break `seal()`. Refused as `PLUGIN_NAME_RESERVED`.
+- **Adding late.** `library.add()` after loading has finished throws `PLUGIN_ADD_OUTSIDE_LOAD`: there is no file to attribute it to and no callback left to report it. A module must register synchronously, while it is being required. A registration from a timer or a promise throws there, uncaught, and stops the process.
+- **Load once.** A second `loadModules` on a path-list library is refused (`LOAD_MODULES_REPEATED`); single-path libraries still simply re-add.
+- **Directory modules need an entry point.** `require(<dir>)` resolves `package.json` `main` or `index.js`. A layout like `screeners.d/<name>/<name>.js` without one of them is `PLUGIN_LOAD_FAILED`.
+- **A loadModules error is fatal.** Refusals are collected, and `loadModules` calls back with all of them. Elements that passed stay loaded, so after an error the library is partly populated. Treat the error as fatal and do not use the library.
+- **Silent modules.** A module that loads but adds nothing is logged as `MODULE_ADDED_NOTHING`.
+- **Not mixable.** One library uses either `setLibraryPath` or `setLibraryPathList` (`LIBRARY_PATH_MODE_CONFLICT`). `setInterface` and `setForbiddenRequireCheck` need a path list (`REQUIRES_PATH_LIST`), and so does the default add: `setCustomAddFunction` with a path list is refused (`CUSTOM_ADD_REQUIRES_SINGLE_PATH`).
+- **Without a callback,** `setLibraryPathList` and `loadModules` throw the refusal string, as `setLibraryPath` throws a bad path.
+- **Sealing.** `seal()` removes the setters, `library` and `logList`, as it always has. For a path-list library it also removes `setLibraryPathList`, `setInterface` and `setForbiddenRequireCheck`. The getters remain.
+
+### Provenance
+
+Every element records `{ provenance, filePath, overrides? }`:
+
+```javascript
+screenersDotD.getProvenance('transcriptDetector');
+// { provenance: 'instance', filePath: '…/corpusScreeners.d/transcriptDetector',
+//   overrides: { provenance: 'framework', filePath: '…', version: '1', reason: '…' } }
+screenersDotD.getProvenanceList();  // [{ elementName, provenance, filePath, overrides? }, …]
+screenersDotD.getRefusalList();     // [{ refusalCode, elementName, filePath, message }, …]
+```
+
+`toString()` adds the same on each element line, e.g. `transcriptDetector: object [instance: …; overrides framework v1 (…) because …]`. `getProvenance` throws `PROVENANCE_NOT_RECORDED` for a single-path library and `PROVENANCE_UNKNOWN_NAME` for a name it does not have. Warnings (`OVERRIDE_TARGET_…`, `ROOT_ABSENT_ALLOWED`, `SKIPPED_NON_MODULE`, `MODULE_ADDED_NOTHING`) are in `qtdProcessLog()`.
+
 ## HISTORY
 
+v1.1.0 - setLibraryPathList: framework and instance roots, declared overrides, opt-in interface and forbidden-require checks, provenance, named refusals; Object.prototype names reserved in path-list mode. setLibraryPath unchanged. Tests added (npm test); test/ not shipped in the package.
 v1.13 - License changed to MIT (was ISC). No code changes.
 v1.12 - clarified error message "Ignoring invalid file".
 v1.10 - there was a reason I did not return the exception list. Undone.

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "qtools-library-dot-d",
-  "version": "1.0.13",
+  "version": "1.1.0",
   "description": "Scan a directory for JS modules that can execute and addMe() that attaches it to some form of name/value list, eg, a Map() with functions as values or an xPressJS route/endpoint list.",
   "main": "qtools-library-dot-d.js",
+  "files": [
+    "qtools-library-dot-d.js",
+    "README.md",
+    "README2.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.js"
   },
   "author": "TQ White II",
   "license": "MIT",

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;
 	};