@noego/wood 0.5.0 → 0.6.0

package/dist/testing/test_wood_config.cjs

@@ -32,14 +32,17 @@ __export(test_wood_config_exports, {
   testWood: () => testWood
 });
 module.exports = __toCommonJS(test_wood_config_exports);
+var import_controller_lifecycle = require("../controller/controller_lifecycle.js");
 var import_node_path = __toESM(require("node:path"), 1);
 var import_ioc = require("@noego/ioc");
 var import_testing = require("@noego/testing");
-var import_wood_router = require("../router/wood_router.cjs");
+var import_runtime_module = require("../runtime/runtime_module.js");
+var import_navigation = require("../navigation/index.js");
 var import_test_wood = require("./test_wood.cjs");
 var import_wood_config_source = require("./wood_config_source.cjs");
 var import_wood_test_selection = require("./wood_test_selection.cjs");
 var import_wood_env_renderer = require("./wood_env_renderer.cjs");
+var import_registration_only_root = require("./registration_only_root.cjs");
 const CONTAINER_REGISTRY_SYMBOL = /* @__PURE__ */ Symbol.for("@noego/wood.container.registry");
 function globalRegistrySize() {
   const registry = globalThis[CONTAINER_REGISTRY_SYMBOL];
@@ -50,23 +53,158 @@ function tierMissing(tier, member) {
     `the ${member} is not available: this environment was built without { ${tier} } \u2014 add it to select()`
   );
 }
-function buildRouter(root, source, operations, importer) {
-  const router = new import_wood_router.WoodRouter({
-    container: root,
-    controllersDir: source.mainControllersDir,
-    middlewareDir: source.mainMiddlewareDir,
-    mode: "dev"
-  });
-  const bound = /* @__PURE__ */ new Set();
+function recordComposer(compose) {
+  if (typeof compose !== "function") throw new import_test_wood.TestWoodError("owner composition expects a callback");
+  const calls = [];
+  const root = {
+    use: (preset) => {
+      calls.push({ method: "use", args: [preset], flat: false });
+      return root;
+    },
+    classes: (config) => {
+      calls.push({ method: "classes", args: [config], flat: false });
+      return root;
+    },
+    functions: (config) => {
+      calls.push({ method: "functions", args: [config], flat: false });
+      return root;
+    },
+    values: (config) => {
+      calls.push({ method: "values", args: [config], flat: false });
+      return root;
+    },
+    methods: (config) => {
+      calls.push({ method: "methods", args: [config], flat: false });
+      return root;
+    }
+  };
+  compose(root);
+  return calls;
+}
+function applyCalls(builder, calls) {
+  let next = builder;
+  for (const call of [...calls].sort((a, b) => a.order - b.order)) {
+    next = next[call.method](...call.args);
+  }
+  return next;
+}
+function ownerTokens(builder) {
+  const tokens = /* @__PURE__ */ new Set();
+  const visit = (token) => {
+    if (tokens.has(token)) return;
+    tokens.add(token);
+    if (typeof token !== "function") return;
+    const injected = Reflect.getMetadata?.(/* @__PURE__ */ Symbol.for("ioc:inject:tokens"), token);
+    const design = Reflect.getMetadata?.("design:paramtypes", token) ?? [];
+    const indices = /* @__PURE__ */ new Set([...design.keys(), ...injected?.keys() ?? []]);
+    for (const index of indices) visit(injected?.has(index) ? injected.get(index) : design[index]);
+  };
+  for (const write of builder.writes) {
+    if (write.op === "use") {
+      for (const registration of (0, import_ioc.flattenModule)(write.module)) {
+        visit(registration.token);
+        if (registration.kind === "class") visit(registration.implementation);
+        for (const dependency of registration.dependencies) visit(dependency);
+      }
+    } else if (write.op !== "methods") {
+      visit(write.key);
+      if (write.op === "classes") visit(write.implementation);
+    }
+  }
+  return tokens;
+}
+function tokenLabel(token) {
+  if (typeof token === "function" && token.name) return token.name;
+  return String(token);
+}
+function callEntries(call) {
+  applyCalls((0, import_testing.testIoc)(), [{ ...call, order: 0 }]);
+  const config = call.args[0];
+  if (Array.isArray(config) || config instanceof Map) return [...config];
+  return Reflect.ownKeys(config).map((key) => [key, config[key]]);
+}
+function resolveOwnerToken(key, exact, main, renderer, method) {
+  let token = key;
+  if (!exact && typeof key === "string") {
+    const matches = [.../* @__PURE__ */ new Set([...main, ...renderer])].filter(
+      (candidate) => candidate === key || typeof candidate === "function" && candidate.name === key
+    );
+    if (matches.length > 1) {
+      throw new import_test_wood.TestWoodError(`Ambiguous ${method} replacement name "${key}"; use an exact token`);
+    }
+    token = matches[0] ?? key;
+  }
+  const ownsMain = main.has(token);
+  const ownsRenderer = renderer.has(token);
+  if (!ownsMain && !ownsRenderer) {
+    throw new import_test_wood.TestWoodError(
+      `Unknown ${method} replacement ${tokenLabel(token)} in the selected roots; register it with .main() or .renderer()`
+    );
+  }
+  if (ownsMain && ownsRenderer) {
+    throw new import_test_wood.TestWoodError(
+      `Ambiguous ${method} replacement ${tokenLabel(token)} belongs to main and renderer; target .main() or .renderer() explicitly`
+    );
+  }
+  return { token, owner: ownsMain ? "main" : "renderer" };
+}
+function routeCalls(calls, main, renderer, target) {
+  for (const call of calls) {
+    if (!call.flat || call.method !== "classes") continue;
+    const exact = Array.isArray(call.args[0]) || call.args[0] instanceof Map;
+    for (const [key, implementation] of callEntries(call)) {
+      const routed = resolveOwnerToken(key, exact || typeof key !== "string", main, renderer, call.method);
+      (routed.owner === "main" ? main : renderer).add(implementation);
+    }
+  }
+  const result = [];
+  for (const call of calls) {
+    if (!call.flat) {
+      if (target === "main") result.push(call);
+      continue;
+    }
+    const exact = Array.isArray(call.args[0]) || call.args[0] instanceof Map;
+    for (const [key, value] of callEntries(call)) {
+      const routed = resolveOwnerToken(key, exact || typeof key !== "string", main, renderer, call.method);
+      if (routed.owner === target) {
+        result.push({ ...call, flat: false, args: [[[routed.token, value]]] });
+      }
+    }
+  }
+  return result;
+}
+async function loadController(source, importer, reference, owner) {
+  const file = owner === "main" ? source.mainControllerFile(reference) : source.rendererControllerFile(reference);
+  const controller = await (0, import_wood_config_source.importDefaultExport)(
+    importer,
+    file,
+    `${owner} controller "${reference}"`
+  );
+  if (typeof controller !== "function") {
+    throw new import_test_wood.TestWoodError(`${owner} controller "${reference}" must default-export a class (${file})`);
+  }
+  return controller;
+}
+async function loadMainControllers(source, operations, importer) {
+  const controllers = /* @__PURE__ */ new Map();
   for (const operation of operations.values()) {
-    if (bound.has(operation.controller)) continue;
-    bound.add(operation.controller);
-    const file = source.mainControllerFile(operation.controller);
-    router.registerControllerLoader(operation.controller, () => importer(file));
-  }
-  router.loadOperations(operations);
-  router.validateControllers();
-  return router;
+    if (!controllers.has(operation.controller)) {
+      controllers.set(operation.controller, await loadController(source, importer, operation.controller, "main"));
+    }
+  }
+  return controllers;
+}
+async function loadRendererControllers(source, views, importer) {
+  const controllers = /* @__PURE__ */ new Map();
+  const references = /* @__PURE__ */ new Set();
+  for (const view of views) {
+    if (view.controller) references.add(view.controller);
+    for (const controller of view.layoutControllers ?? []) if (controller) references.add(controller);
+  }
+  for (const reference of references) {
+    controllers.set(reference, await loadController(source, importer, reference, "renderer"));
+  }
+  return controllers;
 }
 async function runCompose(root, source, context) {
   const composePath = source.hookModule(source.config.main.testing?.compose);
@@ -97,16 +235,8 @@ function assertNoGlobalContainerLeak(before, source) {
     );
   }
 }
-async function assembleEnvironment(state, selection) {
-  const source = (0, import_wood_config_source.loadWoodConfigSource)(state.configPath);
-  const operations = (0, import_wood_test_selection.selectOperations)(source.operations, selection.main);
-  const catalog = selection.pages ? (0, import_wood_test_selection.selectCatalog)(source.views(), selection.pages) : null;
-  const registryBefore = globalRegistrySize();
-  let composed = null;
-  let renderer = null;
-  const controllerScopes = [];
-  let router = null;
-  const context = {
+function createComposeContext(source, state, selection, operations, live) {
+  return {
     configPath: source.configPath,
     configDir: source.configDir,
     config: source.config,
@@ -114,47 +244,189 @@ async function assembleEnvironment(state, selection) {
     operations,
     importer: state.importer,
     call: async (operation, input) => {
-      if (!router) throw new import_test_wood.TestWoodError("compose context call() is available from start() onward, not during compose");
-      const live = router;
-      return await import_ioc.ExecutionContext.run(env.root, () => live.dispatch(operation, input));
+      if (!live.router || !live.env) {
+        throw new import_test_wood.TestWoodError("compose context call() is available from start() onward, not during compose");
+      }
+      const router = live.router;
+      return await import_ioc.ExecutionContext.run(
+        live.env.root,
+        () => router.dispatch(operation, input)
+      );
     }
   };
-  const env = await state.ioc.build({
-    prepare: async (root2) => {
-      composed = await runCompose(root2, source, context);
+}
+function createAssemblyDisposer(live, mainRegistrations, rendererRegistrations, controllerScopes) {
+  let closing = null;
+  return () => closing ?? (closing = (0, import_registration_only_root.cleanupAll)("testWood cleanup failed", [
+    ["renderer", async () => {
+      if (live.renderer) await live.renderer.dispose();
+    }],
+    ...[...controllerScopes].reverse().map(
+      (scope, index) => [`controller scope ${controllerScopes.length - index}`, () => scope.dispose()]
+    ),
+    ["compose drain", async () => {
+      await live.composed?.drain?.();
+    }],
+    ["main root", async () => {
+      if (live.env) await disposeRoot(live.env);
+      else await mainRegistrations.actualRoot.dispose();
+    }],
+    ["unbuilt renderer root", async () => {
+      if (!live.renderer && rendererRegistrations) await rendererRegistrations.actualRoot.dispose();
+    }],
+    ["compose external dispose", async () => {
+      await live.composed?.dispose?.();
+    }]
+  ]));
+}
+async function loadAssemblyControllers(inputs) {
+  const main = await loadMainControllers(inputs.source, inputs.operations, inputs.state.importer);
+  const renderer = inputs.catalog ? await loadRendererControllers(inputs.source, inputs.catalog.all(), inputs.state.importer) : /* @__PURE__ */ new Map();
+  return { main, renderer };
+}
+function installAssemblyRuntime(inputs, mainControllers) {
+  (0, import_runtime_module.installWoodRuntime)(inputs.mainRegistrations.root, {
+    controllersDir: inputs.source.mainControllersDir,
+    middlewareDir: inputs.source.mainMiddlewareDir,
+    mode: "dev",
+    registerRuntime: (configuredRouter) => {
+      for (const [identity, controller] of mainControllers) {
+        configuredRouter.registerControllerLoader(identity, () => Promise.resolve({ default: controller }));
+      }
+      configuredRouter.loadOperations(inputs.operations);
     }
   });
-  const root = env.root;
-  const dispose = async () => {
-    if (renderer) await renderer.dispose();
-    for (const scope of controllerScopes.reverse()) await scope.dispose();
-    await composed?.drain?.();
-    try {
-      await disposeRoot(env);
-    } finally {
-      await composed?.dispose?.();
+}
+async function configureRendererRegistrations(inputs) {
+  const registrations = inputs.rendererRegistrations;
+  if (!registrations) return;
+  registrations.declare(import_navigation.Navigation);
+  registrations.declare(import_test_wood.WOOD_FRONTEND_BRIDGE);
+  await import_ioc.ExecutionContext.run(
+    registrations.root,
+    () => inputs.live.composed?.configureRendererRoot?.(registrations.root)
+  );
+}
+function registerControllersBeforeOverlays(inputs, mainControllers, rendererControllers) {
+  for (const controller of mainControllers.values()) {
+    inputs.mainRegistrations.declare(controller);
+    if (!inputs.mainRegistrations.actualRoot.isRegistered(controller)) {
+      inputs.mainRegistrations.root.registerClass(controller);
     }
+  }
+  for (const controller of rendererControllers.values()) {
+    inputs.rendererRegistrations?.declare(controller);
+  }
+}
+function buildAssemblyIoc(inputs) {
+  const explicitMain = inputs.state.mainCalls.filter((call) => !call.flat);
+  const mainOwners = /* @__PURE__ */ new Set([
+    ...inputs.mainRegistrations.owners,
+    ...ownerTokens(applyCalls((0, import_testing.testIoc)(), explicitMain))
+  ]);
+  const rendererOwners = /* @__PURE__ */ new Set([
+    ...inputs.rendererRegistrations?.owners ?? [],
+    ...ownerTokens(applyCalls((0, import_testing.testIoc)(), inputs.state.rendererCalls))
+  ]);
+  const routedMain = routeCalls(inputs.state.mainCalls, mainOwners, rendererOwners, "main");
+  const routedRenderer = routeCalls(inputs.state.mainCalls, mainOwners, rendererOwners, "renderer");
+  return {
+    main: applyCalls((0, import_testing.testIoc)(), routedMain),
+    renderer: applyCalls((0, import_testing.testIoc)(), [...inputs.state.rendererCalls, ...routedRenderer])
   };
+}
+async function materializeEnvironment(inputs) {
+  const controllers = await loadAssemblyControllers(inputs);
+  inputs.live.composed = await runCompose(inputs.mainRegistrations.root, inputs.source, inputs.context);
+  installAssemblyRuntime(inputs, controllers.main);
+  await configureRendererRegistrations(inputs);
+  registerControllersBeforeOverlays(inputs, controllers.main, controllers.renderer);
+  const ioc = buildAssemblyIoc(inputs);
+  inputs.live.env = await (0, import_registration_only_root.buildRecordedEnvironment)(ioc.main, inputs.mainRegistrations, "main");
+  const root = inputs.live.env.root;
+  inputs.live.router = await Promise.resolve(
+    import_ioc.ExecutionContext.run(root, () => root.get(import_runtime_module.WoodRouter))
+  );
+  await import_ioc.ExecutionContext.run(root, () => inputs.live.composed?.start?.());
+  assertNoGlobalContainerLeak(inputs.registryBefore, inputs.source);
+  if (inputs.catalog && inputs.rendererRegistrations) {
+    inputs.live.renderer = await (0, import_wood_env_renderer.buildRendererTier)({
+      source: inputs.source,
+      router: inputs.live.router,
+      catalog: inputs.catalog,
+      operations: inputs.operations,
+      importer: inputs.state.importer,
+      hooks: inputs.live.composed,
+      dom: inputs.selection.dom,
+      ioc: ioc.renderer,
+      registrations: inputs.rendererRegistrations,
+      controllerClasses: controllers.renderer
+    });
+  }
+  return environmentSurface({
+    root,
+    env: inputs.live.env,
+    router: inputs.live.router,
+    operations: inputs.operations,
+    renderer: inputs.live.renderer,
+    controllerScopes: inputs.controllerScopes,
+    dispose: inputs.dispose
+  });
+}
+async function rollbackEnvironment(error, dispose) {
   try {
-    router = buildRouter(root, source, operations, state.importer);
-    await import_ioc.ExecutionContext.run(root, () => composed?.start?.());
-    assertNoGlobalContainerLeak(registryBefore, source);
-    if (catalog) {
-      renderer = await (0, import_wood_env_renderer.buildRendererTier)({
-        source,
-        router,
-        catalog,
-        operations,
-        importer: state.importer,
-        hooks: composed,
-        dom: selection.dom
-      });
-    }
-    return environmentSurface({ root, env, router, operations, renderer, controllerScopes, dispose });
+    await dispose();
+  } catch (cleanupError) {
+    const failures = [
+      ...error instanceof import_registration_only_root.TestWoodCleanupError ? error.failures : [],
+      ...cleanupError instanceof import_registration_only_root.TestWoodCleanupError ? cleanupError.failures : [{ owner: "build rollback", error: cleanupError }]
+    ];
+    throw new import_registration_only_root.TestWoodCleanupError("testWood build failed and rollback failed", failures, error);
+  }
+  throw error;
+}
+async function assembleEnvironment(state, selection) {
+  const source = (0, import_wood_config_source.loadWoodConfigSource)(state.configPath);
+  const operations = (0, import_wood_test_selection.selectOperations)(source.operations, selection.main);
+  const catalog = selection.pages ? (0, import_wood_test_selection.selectCatalog)(source.views(), selection.pages) : null;
+  if (!catalog && state.rendererCalls.length) {
+    throw new import_test_wood.TestWoodError(".renderer() composition requires a selected pages tier");
+  }
+  const registryBefore = globalRegistrySize();
+  const mainRegistrations = new import_registration_only_root.RegistrationOnlyRoot("main.testing.compose");
+  const rendererRegistrations = catalog ? new import_registration_only_root.RegistrationOnlyRoot("configureRendererRoot") : null;
+  const controllerScopes = [];
+  const live = {
+    composed: null,
+    env: null,
+    renderer: null,
+    router: null
+  };
+  const context = createComposeContext(source, state, selection, operations, live);
+  const dispose = createAssemblyDisposer(
+    live,
+    mainRegistrations,
+    rendererRegistrations,
+    controllerScopes
+  );
+  const inputs = {
+    state,
+    selection,
+    source,
+    operations,
+    catalog,
+    registryBefore,
+    mainRegistrations,
+    rendererRegistrations,
+    controllerScopes,
+    live,
+    context,
+    dispose
+  };
+  try {
+    return await materializeEnvironment(inputs);
   } catch (error) {
-    await dispose().catch(() => {
-    });
-    throw error;
+    return rollbackEnvironment(error, dispose);
   }
 }
 function environmentSurface(parts) {
@@ -176,9 +448,18 @@ function environmentSurface(parts) {
     },
     controller: async (controller) => {
       const scope = root.extend();
-      controllerScopes.push(scope);
+      const ownsController = !root.isRegistered(controller);
+      let instance;
+      controllerScopes.push({ dispose: () => import_ioc.ExecutionContext.run(scope, () => (0, import_registration_only_root.cleanupAll)("controller cleanup failed", [
+        ["controller", async () => {
+          if (ownsController) await (0, import_controller_lifecycle.disposeControllerLifecycle)(instance);
+        }],
+        ["scope", () => scope.dispose()]
+      ])) });
       if (!scope.isRegistered(controller)) scope.registerClass(controller);
-      return await scope.get(controller);
+      instance = await import_ioc.ExecutionContext.run(scope, () => scope.get(controller));
+      (0, import_controller_lifecycle.guardControllerLifecycleOnce)(instance);
+      return instance;
     },
     get: async (token) => await root.get(token),
     get frontend() {
@@ -205,7 +486,19 @@ function environmentSurface(parts) {
     // Method expectations only: `settle()` is the completion contract for
     // owned renderer work, and a test may legitimately verify while a
     // deliberately deferred stream is still in flight.
-    verify: () => env.verify(),
+    verify: async () => {
+      const failures = [];
+      await env.verify().catch((error) => failures.push({ owner: "main", error }));
+      if (renderer) {
+        await renderer.verify().catch((error) => failures.push({ owner: "renderer", error }));
+      }
+      if (failures.length === 1) throw failures[0].error;
+      if (failures.length) {
+        throw new import_test_wood.TestWoodError(
+          "testWood verification failed in both roots:\n  " + failures.map(({ owner, error }) => `${owner}: ${error instanceof Error ? error.message : String(error)}`).join("\n  ")
+        );
+      }
+    },
     dispose,
     [import_testing.ENV_REGISTRY]: env[import_testing.ENV_REGISTRY]
   };
@@ -221,7 +514,8 @@ class TestWoodBuilder {
     return new TestWoodBuilder({
       configPath: import_node_path.default.resolve(configPath),
       selection: null,
-      ioc: (0, import_testing.testIoc)(),
+      mainCalls: [],
+      rendererCalls: [],
       importer: import_wood_config_source.defaultImporter
     });
   }
@@ -235,21 +529,33 @@ class TestWoodBuilder {
     if (typeof importer !== "function") throw new import_test_wood.TestWoodError("importer() expects a function");
     return this.derive({ importer });
   }
-  /* ---- Composition: exact @noego/testing semantics on the main root ---- */
+  /** Explicitly compose or replace dependencies on the main-process root. */
+  main(compose) {
+    return this.append("main", recordComposer(compose));
+  }
+  /** Explicitly compose or replace dependencies on the renderer root. */
+  renderer(compose) {
+    return this.append("renderer", recordComposer(compose));
+  }
+  /** Reusable presets retain the historical main-root default. */
   use(preset) {
-    return this.derive({ ioc: this.state.ioc.use(preset) });
+    return this.append("main", [{ method: "use", args: [preset], flat: false }]);
   }
+  /** Exact-token replacement routed to the sole declared selected owner. */
   classes(config) {
-    return this.derive({ ioc: this.state.ioc.classes(config) });
+    return this.append("main", [{ method: "classes", args: [config], flat: true }]);
   }
+  /** Exact-token replacement routed to the sole declared selected owner. */
   functions(config) {
-    return this.derive({ ioc: this.state.ioc.functions(config) });
+    return this.append("main", [{ method: "functions", args: [config], flat: true }]);
   }
+  /** Exact-token replacement routed to the sole declared selected owner. */
   values(config) {
-    return this.derive({ ioc: this.state.ioc.values(config) });
+    return this.append("main", [{ method: "values", args: [config], flat: true }]);
   }
+  /** Exact-token method seams routed to the sole declared selected owner. */
   methods(config) {
-    return this.derive({ ioc: this.state.ioc.methods(config) });
+    return this.append("main", [{ method: "methods", args: [config], flat: true }]);
   }
   async build() {
     if (!this.state.selection) {
@@ -257,6 +563,12 @@ class TestWoodBuilder {
     }
     return assembleEnvironment(this.state, (0, import_wood_test_selection.resolveSelection)(this.state.selection));
   }
+  append(owner, calls) {
+    const start = this.state.mainCalls.length + this.state.rendererCalls.length;
+    const ordered = calls.map((call, index) => ({ ...call, order: start + index }));
+    applyCalls((0, import_testing.testIoc)(), ordered);
+    return owner === "main" ? this.derive({ mainCalls: [...this.state.mainCalls, ...ordered] }) : this.derive({ rendererCalls: [...this.state.rendererCalls, ...ordered] });
+  }
   derive(patch) {
     return new TestWoodBuilder({ ...this.state, ...patch });
   }