fix(testing): wire appended libraries before the module-under-test (#88) (#330)

Two coherent changes on this branch, one commit each.

## 1. `fix(testing)` — appendLibrary ordering (closes #88)

`TestRunner.appendLibrary` and the module-extension `appendLibrary`
disagreed on *when* an appended library constructs relative to the
module-under-test:

| append site | before | after |
|---|---|---|
| `.extend().appendLibrary(x).toTest()` | `x` → module | `x` → module |
| `.extend().toTest().appendLibrary(x)` | **module → `x`** (bug) | `x` →
module |

**Root cause:** `TestRunner.buildApp` demotes the module-under-test to a
library and keeps only the test service in the synthetic application, so
the appended library and the module were unordered siblings —
declaration order made the module construct first. The module-extension
path keeps the module as the *application* (its services wire last), so
appended libraries naturally wire first.

**Fix:** declare appended libraries as `optionalDepends` of the wrapped
target, so `buildSortOrder` wires them before the module — matching the
extension path, so doubles/spies can be installed before the module's
construction logic runs. Appended libraries stay on the same
`bootstrap({ appendLibrary })` path (replace-by-name + warning
untouched); no change to the shared `bootstrap()` engine.

**Also:** guards a NPE in `module.appendLibrary`/`replaceLibrary` when
the base library declares no `depends` (it dereferenced
`workingModule.depends` without the optional chaining
`toApplication`/`toLibrary` already use).

Regression tests added in `testing/testing.spec.mts` cover both append
sites, cross-site agreement, and the no-`depends` case.

## 2. `chore` — toolchain / deps

- yarn `4.14.1` → `4.16.0` (`yarn set version stable`)
- 48h supply-chain age gate: `.yarnrc.yml` `npmMinimalAgeGate: 2880`
(yarn measures this in minutes; its default is `1440` = 24h)
- `upgrade` script gains `ncu --cooldown 48h` so dependency *selection*
respects the same 48h window that `yarn install` enforces via the gate
- ran `yarn upgrade`: 16 deps bumped — the cooldown visibly held
`eslint-plugin-unicorn` at `65.0.1` instead of the <48h-old `66.0.0`
- package version `26.6.14` → `26.6.15`

## Verification

- `yarn test run` → **392 passed / 10 skipped / 0 failed**
- `yarn lint` → clean
- `tsc -p tsconfig.lib.json --noEmit` → exit 0

## Follow-up

Filed #329 (feat: opt-in pre-construction setup hook for `TestRunner`) —
the ergonomic, additive companion to the appendLibrary path. It
intentionally does **not** change `.setup()`'s post-wire semantics
("full graph available, seed early state before the test runs").

Author: zoe-codez

.yarnrc.yml

@@ -2,4 +2,9 @@ compressionLevel: mixed
 
 nodeLinker: node-modules
 
+# 48h supply-chain age gate: refuse to resolve npm versions published less than
+# 2880 minutes ago (yarn measures npmMinimalAgeGate in minutes; default is 1440).
+# `yarn upgrade` (ncu --cooldown 48h) applies the same 48h window at selection time.
+npmMinimalAgeGate: 2880
+
 npmRegistryServer: "https://registry.npmjs.org/"

package.json

@@ -5,7 +5,7 @@
   "repository": {
     "url": "git+https://github.com/Digital-Alchemy-TS/core"
   },
-  "version": "26.6.14",
+  "version": "26.6.15",
   "author": {
     "url": "https://github.com/zoe-codez",
     "name": "Zoe Codez"
@@ -16,7 +16,7 @@
     "build": "rm -rf dist/; tsc -p tsconfig.lib.json",
     "lint": "eslint src",
     "test": "vitest",
-    "upgrade": "ncu --upgrade && truncate -s 0 yarn.lock && yarn install"
+    "upgrade": "ncu --upgrade --cooldown 48h && truncate -s 0 yarn.lock && yarn install"
   },
   "bugs": {
     "email": "bugs@digital-alchemy.app",
@@ -48,55 +48,55 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.69.1",
+    "@dotenvx/dotenvx": "^1.71.3",
     "chalk": "^5.6.2",
     "cron": "^4.4.0",
     "dayjs": "^1.11.21",
     "ini": "^7.0.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "minimist": "^1.2.8",
     "uuid": "^14.0.0"
   },
   "devDependencies": {
-    "@cspell/eslint-plugin": "^10.0.0",
+    "@cspell/eslint-plugin": "^10.0.1",
     "@eslint/compat": "^2.1.0",
     "@eslint/eslintrc": "^3.3.5",
     "@eslint/js": "^10.0.1",
     "@faker-js/faker": "^10.4.0",
     "@types/ini": "^4.1.1",
     "@types/js-yaml": "^4.0.9",
     "@types/minimist": "^1.2.5",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.3",
     "@types/sinonjs__fake-timers": "^15.0.1",
-    "@typescript-eslint/eslint-plugin": "8.60.1",
-    "@typescript-eslint/parser": "8.60.1",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@typescript-eslint/eslint-plugin": "8.61.0",
+    "@typescript-eslint/parser": "8.61.0",
+    "@vitest/coverage-v8": "^4.1.8",
     "chalk": "^5.6.2",
     "dayjs": "^1.11.21",
-    "eslint": "10.4.1",
+    "eslint": "10.5.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsonc": "^3.1.2",
+    "eslint-plugin-jsonc": "^3.2.0",
     "eslint-plugin-no-unsanitized": "^4.1.5",
     "eslint-plugin-prettier": "^5.5.6",
-    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-security": "^4.0.1",
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "eslint-plugin-sonarjs": "^4.0.3",
     "eslint-plugin-sort-keys-fix": "^1.1.2",
-    "eslint-plugin-unicorn": "^64.0.0",
+    "eslint-plugin-unicorn": "^65.0.1",
     "ini": "^7.0.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.2.0",
     "minimist": "^1.2.8",
-    "npm-check-updates": "^22.2.1",
+    "npm-check-updates": "^22.2.3",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "tslib": "^2.8.1",
-    "tsx": "^4.22.3",
-    "type-fest": "^5.6.0",
+    "tsx": "^4.22.4",
+    "type-fest": "^5.7.0",
     "typescript": "^6.0.3",
     "uuid": "^14.0.0",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
-  "packageManager": "yarn@4.14.1"
+  "packageManager": "yarn@4.16.0"
 }

src/helpers/module.mts

@@ -233,7 +233,9 @@ export function createModule<S extends ServiceMap, C extends OptionalModuleConfi
             `${name} already is appended`,
           );
         }
-        const exists = workingModule.depends.some(i => i.name === name);
+        // depends may be undefined when seeded from a library/application with no
+        // declared dependencies (createModule.fromLibrary of a no-depends library)
+        const exists = workingModule.depends?.some(i => i.name === name) ?? false;
         if (exists) {
           // base depends list owns this name; callers must use replaceLibrary to swap it
           throw new BootstrapException(
@@ -280,7 +282,8 @@ export function createModule<S extends ServiceMap, C extends OptionalModuleConfi
           // already in the appended set — replace in-place
           appendLibrary.set(name, library);
         } else {
-          const exists = workingModule.depends.some(i => i.name === name);
+          // depends may be undefined (see appendLibrary above)
+          const exists = workingModule.depends?.some(i => i.name === name) ?? false;
           if (!exists) {
             // neither appended nor in base depends; require explicit append first
             throw new BootstrapException(

src/testing/test-module.mts

@@ -275,12 +275,22 @@ export function TestRunner<S extends ServiceMap, C extends OptionalModuleConfigu
 
     // wrap the target's services and configuration into a library so it can be
     // mixed with appended libraries and the run_first setup library
+    //
+    // issue #88: the module-extension path (createModule.extend().appendLibrary())
+    // keeps the module-under-test as the *application*, so appended libraries —
+    // being plain libraries — wire before it. Here the target is demoted to a
+    // library, so without an explicit constraint it and the appended libraries
+    // are unordered siblings and declaration order lets the target win. Declaring
+    // the appended libraries as optional dependencies of the wrapped target makes
+    // buildSortOrder wire them first, matching the extension path so doubles/spies
+    // are installed before the module's construction logic runs.
+    const optionalDepends = [...(optional ?? []), ...appendLibraries.values()];
     const testLibrary = target
       ? CreateLibrary({
           configuration: target.configuration,
           depends,
           name: target.name,
-          optionalDepends: optional,
+          optionalDepends,
           priorityInit: target.priorityInit,
           services: target.services,
         })

testing/testing.spec.mts

@@ -166,6 +166,95 @@ describe("Testing", () => {
     });
   });
 
+  // #MARK: appendLibrary ordering (issue #88)
+  describe("appendLibrary ordering (issue #88)", () => {
+    // https://github.com/Digital-Alchemy-TS/core/issues/88
+    // An appended library must construct BEFORE the module-under-test regardless
+    // of whether appendLibrary is called on the module extension (Version 1) or
+    // the test runner (Version 2), so doubles/spies can be installed against its
+    // dependencies before the module's own construction logic runs.
+    let order: string[];
+
+    // no `depends` on purpose: also guards the regressed NPE in
+    // module.appendLibrary (workingModule.depends.some on undefined)
+    const orderedExample = CreateLibrary({
+      // @ts-expect-error testing
+      name: "example",
+      services: {
+        main() {
+          order.push("example");
+        },
+      },
+    });
+
+    const orderedSpy = CreateLibrary({
+      // @ts-expect-error testing
+      name: "spy",
+      services: {
+        spy() {
+          order.push("spy");
+        },
+      },
+    });
+
+    beforeEach(() => {
+      order = [];
+    });
+
+    it("constructs the appended library first (append on module extension)", async () => {
+      expect.assertions(1);
+      const test = createModule
+        .fromLibrary(orderedExample)
+        .extend()
+        .appendLibrary(orderedSpy)
+        .toTest();
+      await test.run(() => {});
+      await test.teardown();
+      expect(order).toEqual(["spy", "example"]);
+    });
+
+    it("constructs the appended library first (append on test runner)", async () => {
+      expect.assertions(1);
+      const test = createModule
+        .fromLibrary(orderedExample)
+        .extend()
+        .toTest()
+        .appendLibrary(orderedSpy);
+      await test.run(() => {});
+      await test.teardown();
+      expect(order).toEqual(["spy", "example"]);
+    });
+
+    it("produces the same order from both append sites", async () => {
+      expect.assertions(1);
+      const v1 = createModule
+        .fromLibrary(orderedExample)
+        .extend()
+        .appendLibrary(orderedSpy)
+        .toTest();
+      await v1.run(() => {});
+      await v1.teardown();
+      const v1Order = [...order];
+
+      order = [];
+      const v2 = createModule
+        .fromLibrary(orderedExample)
+        .extend()
+        .toTest()
+        .appendLibrary(orderedSpy);
+      await v2.run(() => {});
+      await v2.teardown();
+      expect([...order]).toEqual(v1Order);
+    });
+
+    it("does not throw when appending to a base library with no depends", () => {
+      expect.assertions(1);
+      expect(() =>
+        createModule.fromLibrary(orderedExample).extend().appendLibrary(orderedSpy),
+      ).not.toThrow();
+    });
+  });
+
   // #MARK: appendService
   describe("appendService", () => {
     it("cannot append an existing service", () => {