qtools-library-dot-d 1.0.12 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TQ White II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -227,8 +227,97 @@ 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.
 v1.09 - fixed broken error handling when library file path is bad; added demonstration application

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "qtools-library-dot-d",
-  "version": "1.0.12",
+  "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": "ISC",
+  "license": "MIT",
   "dependencies": {
     "qtools-asynchronous-pipe-plus": "^1.0.2",
     "qtools-functional-library": "^2.0.4"