@nestia/sdk 14.0.1 → 14.0.3

package/src/executable/internal/NestiaSdkWatcher.ts

@@ -4,14 +4,96 @@ import path from "path";
 import { INestiaConfig } from "../../INestiaConfig";
 import { SourceFinder } from "../../utils/SourceFinder";
 
+/**
+ * Regenerates the Swagger document when the sources or the configuration
+ * change.
+ *
+ * @evidence contracts/common.md#principled-implementation A session watches the directories of the inputs and the configuration files, ignores the outputs and dependency directories, debounces changes, and queues a change that arrives during a generation.
+ * @evidence contracts/common.md#clear-and-simple-design One public function over a session class and private path helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The watchers are installed before each generation so no change between generation and watching is lost, and every watcher is closed on stop.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation One non-recursive `fs.watch` is installed per directory, which every supported platform provides, in place of the `recursive` option that older Linux releases lack. The event's file name can be missing on some platforms and the directory then stands for the change, and a rename without an extension is read as a possible directory change because platforms report directory creation as a rename. Locations are compared by filesystem identity: every ignored path and every event target is resolved to the real path of its nearest existing ancestor, which carries the case and links the volume keeps, so no operating-system name decides a case policy. Remaining assumptions: `fs.watch` event semantics differ per platform, and only SIGINT and SIGTERM are handled, so an abrupt termination ends the watchers with the process.
+ * efficient algorithms: Each regeneration walks the watched trees once, one `readdir` and one real-path resolution per directory, and does so twice, before the generation so no edit is lost and after it to see what it wrote, so the cost grows with the number of watched directories and their entries and repeats for every debounced regeneration. A watched directory can appear at any time, so an incremental plan would still have to rescan, and the full rebuild is kept because regeneration is itself far costlier than a scan.
+ * reuse equivalent work: Changes inside the debounce window collapse into one regeneration and a change during a running generation sets one pending reason, so equivalent triggers share a run. Each run reloads the configurations because the configuration file is an input, so no result is reused across runs.
+ * bound retention and release resources: The session owns one watcher per planned directory, one debounce timer and one pending reason; sync, errors and stop release those handles. Its optional finalizer releases caller-owned generation resources on success, failure and stop. CLI regeneration loads configurations/controllers inside one disposable child whose temporary outputs and module realm end after that generation. Arbitrary programmatic callbacks retain their own module caches and resources; the scheduler cannot release caller-owned caches or objects retained outside their callbacks.
+ */
 export namespace NestiaSdkWatcher {
+  /**
+   * The input of the watcher: the configuration file, the configuration loader,
+   * the generator, and the project file.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds the loaders and the generator the session calls.
+   * @evidence contracts/common.md#clear-and-simple-design Native configuration/project paths sit beside the configuration, generation and optional finalization callbacks that own their respective phases.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidence contracts/portability.md#os-neutral-implementation The two file fields are native paths of the project, resolved with `path.resolve` before any comparison.
+   * efficient algorithms: The record has no computation.
+   * reuse equivalent work: The record coordinates no work.
+   * bound retention and release resources: The record owns no handle or task; the session that holds it owns the resources.
+   */
   export interface IProps {
     configFile: string;
+    /**
+     * Loads the current configurations; it is called again at every
+     * regeneration so a changed file is read.
+     *
+     * @evidence contracts/common.md#principled-implementation The loader is a function, not a value, because the configuration file itself is watched.
+     * @evidence contracts/common.md#clear-and-simple-design One callback.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is caller code.
+     * @evidence contracts/common.md#meaningful-documentation The comment states when it is called.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation A caller callback owns no filesystem or process access here; the loader it wraps owns those decisions.
+     * efficient algorithms: The signature performs no computation.
+     * reuse equivalent work: The signature coordinates nothing; the session decides when to call it.
+     * bound retention and release resources: The signature retains nothing; the session drops the returned configurations after each run.
+     */
     configurations: () => Promise<INestiaConfig[]>;
+    /**
+     * Runs the generation for the loaded configurations.
+     *
+     * @evidence contracts/common.md#principled-implementation The watcher only schedules the call and reports its errors.
+     * @evidence contracts/common.md#clear-and-simple-design One callback.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is caller code.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what it does.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation A caller callback owns no filesystem or process access here; the generator it wraps owns those decisions.
+     * efficient algorithms: The signature performs no computation.
+     * reuse equivalent work: The signature coordinates nothing; the session serializes its calls.
+     * bound retention and release resources: The signature retains nothing.
+     */
     generate: (configurations: INestiaConfig[]) => Promise<void>;
+
+    /**
+     * Releases caller-owned per-generation resources after success or failure,
+     * and when the session is stopped. It may overlap an in-flight generation
+     * during stop, so its implementation must make release idempotent.
+     *
+     * @evidence contracts/common.md#principled-implementation The hook lets the caller release generation-owned resources on completion, failure and stop, including overlap with an active generation.
+     * @evidence contracts/common.md#clear-and-simple-design One optional finalizer avoids making the scheduler depend on a particular generator resource representation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Resource release is delegated to its actual owner rather than changing foreign caches or callbacks.
+     * @evidence contracts/common.md#meaningful-documentation The comment states call timing and the idempotency required when stop overlaps work.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This callback signature exposes no native path or process representation; the caller’s finalizer owns that boundary.
+     * efficient algorithms: The signature performs no release computation; its caller supplies the implementation.
+     * reuse equivalent work: The signature shares no results; the session determines finalization timing.
+     * bound retention and release resources: The signature owns no retained state or handle; the session joins the caller’s release operation and the caller owns external resources.
+     */
+    finalize?: () => Promise<void>;
     projectFile: string;
   }
 
+  /**
+   * Starts the watch session, generates once, and never resolves until the
+   * process ends.
+   *
+   * The session closes its watchers and exits on SIGINT and SIGTERM.
+   *
+   * @evidence contracts/common.md#principled-implementation The first generation runs before the promise that never settles, and a failed generation is printed with its causes and does not stop the session.
+   * @evidence contracts/common.md#clear-and-simple-design One function that creates the session and blocks.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The watchers are released by the signal handlers.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the blocking and the signals.
+   * @evidence contracts/portability.md#os-neutral-implementation The signal handlers are registered with `process.once` for SIGINT and SIGTERM and exit with status 0 after closing the watchers; SIGINT is delivered on every platform while Windows never delivers SIGTERM, so a termination request there ends the process without the handler.
+   * efficient algorithms: The function creates one session and awaits one generation; its cost is that of the first regeneration described by the namespace.
+   * reuse equivalent work: The first generation is the only work the function itself requests, and later regenerations are coordinated by the session, which collapses equivalent triggers.
+   * bound retention and release resources: The returned promise never settles by design, so the session lives until the process ends; the handlers release its watchers and timer on SIGINT and SIGTERM, and the process exit releases them otherwise.
+   */
   export const watch = async (props: IProps): Promise<void> => {
     const session = new WatchSession(props);
     session.registerSignals();
@@ -33,7 +115,15 @@ class WatchSession {
   public registerSignals(): void {
     const stop = (): void => {
       this.dispose();
-      process.exit(0);
+      void (async () => {
+        try {
+          await this.props.finalize?.();
+          process.exit(0);
+        } catch (error) {
+          printError(error);
+          process.exit(1);
+        }
+      })();
     };
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
@@ -47,36 +137,58 @@ class WatchSession {
     }
 
     this.running = true;
-    let nextReason: string | null = reason;
-    do {
-      const current: string = nextReason;
-      nextReason = null;
-      this.pending = null;
-      let configurations: INestiaConfig[] = [];
-      try {
-        if (current === "initial generation")
-          console.log("Starting nestia swagger watch mode");
-        else console.log(`Change detected (${current}); regenerating swagger`);
-
-        configurations = await this.props.configurations();
-        // Watchers must be live before artifacts are written: consumers react
-        // to the artifact appearing, and an edit arriving between the write
-        // and a later watcher installation would be lost forever. Changes
-        // during generation queue through `pending`.
-        await this.refresh(configurations);
-        await this.props.generate(configurations);
-        await this.refresh(configurations);
-        console.log(
-          `Watching ${this.watchers.size} directories. Press Ctrl+C to stop.`,
-        );
-      } catch (error) {
-        await this.refresh(configurations);
-        console.error("Nestia swagger watch generation failed:");
-        printError(error);
-      }
-      nextReason = this.pending;
-    } while (nextReason !== null && !this.stopped);
-    this.running = false;
+    try {
+      let nextReason: string | null = reason;
+      do {
+        const current: string = nextReason;
+        nextReason = null;
+        this.pending = null;
+        let configurations: INestiaConfig[] = [];
+        let generationError: unknown;
+        try {
+          if (current === "initial generation")
+            console.log("Starting nestia swagger watch mode");
+          else
+            console.log(`Change detected (${current}); regenerating swagger`);
+
+          configurations = await this.props.configurations();
+          // Watchers must be live before artifacts are written: consumers react
+          // to the artifact appearing, and an edit arriving between the write
+          // and a later watcher installation would be lost forever. Changes
+          // during generation queue through `pending`.
+          await this.refresh(configurations);
+          await this.props.generate(configurations);
+          await this.refresh(configurations);
+          console.log(
+            `Watching ${this.watchers.size} directories. Press Ctrl+C to stop.`,
+          );
+        } catch (error) {
+          generationError = error;
+          if (!this.stopped) {
+            console.error("Nestia swagger watch generation failed:");
+            printError(error);
+            try {
+              await this.refresh(configurations);
+            } catch (refreshError) {
+              console.error("Nestia swagger watch refresh failed:");
+              printError(refreshError);
+            }
+          }
+        } finally {
+          try {
+            await this.props.finalize?.();
+          } catch (error) {
+            if (!this.stopped && error !== generationError) {
+              console.error("Nestia swagger watch cleanup failed:");
+              printError(error);
+            }
+          }
+        }
+        nextReason = this.pending;
+      } while (nextReason !== null && !this.stopped);
+    } finally {
+      this.running = false;
+    }
   }
 
   private schedule(reason: string): void {
@@ -89,6 +201,7 @@ class WatchSession {
   }
 
   private async refresh(configurations: INestiaConfig[]): Promise<void> {
+    if (this.stopped) return;
     const next = await collectWatchPlan({
       configurations,
       configFile: this.props.configFile,
@@ -107,6 +220,7 @@ class WatchSession {
   }
 
   private sync(next: Set<string>): void {
+    if (this.stopped) return;
     for (const [directory, watcher] of this.watchers)
       if (next.has(directory) === false) {
         watcher.close();
@@ -169,7 +283,7 @@ const collectWatchPlan = async (props: {
     for (const target of outputTargets(config)) ignored.add(target);
   }
   return {
-    ignored: [...ignored],
+    ignored: [...ignored].map(canonical),
     targets: [...targets],
   };
 };
@@ -280,18 +394,32 @@ const shouldReact = (props: { event: string; target: string }): boolean => {
   return props.event === "rename" && ext.length === 0;
 };
 
-const shouldIgnore = (location: string, ignored: string[]): boolean =>
-  ignored.some((elem) => isSameOrInside(location, elem));
-
-const isSameOrInside = (child: string, parent: string): boolean => {
-  const left: string = comparable(child);
-  const right: string = comparable(parent);
-  return left === right || left.startsWith(`${right}${path.sep}`);
+// `ignored` holds canonical paths, see `canonical`.
+const shouldIgnore = (location: string, ignored: string[]): boolean => {
+  const target: string = canonical(location);
+  return ignored.some(
+    (elem) => target === elem || target.startsWith(`${elem}${path.sep}`),
+  );
 };
 
-const comparable = (location: string): string => {
+// The filesystem decides which spellings name one location, so the nearest
+// existing ancestor is resolved to its real path, which holds the case and the
+// links the filesystem keeps, and the part that does not exist yet is appended
+// as written. An operating-system name says nothing about the case policy of a
+// volume, which a mount or a directory may set apart from its neighbors.
+const canonical = (location: string): string => {
   const resolved: string = path.resolve(location);
-  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  const rest: string[] = [];
+  for (let current: string = resolved; ; ) {
+    try {
+      return path.join(fs.realpathSync.native(current), ...[...rest].reverse());
+    } catch {
+      const parent: string = path.dirname(current);
+      if (parent === current) return resolved;
+      rest.push(path.basename(current));
+      current = parent;
+    }
+  }
 };
 
 const staticRoot = (pattern: string): string => {

package/src/executable/internal/NestiaSwaggerWatch.ts

@@ -0,0 +1,359 @@
+import cp from "child_process";
+import fs from "fs";
+import path from "path";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { NestiaSdkApplication } from "../../NestiaSdkApplication";
+import { TemporaryDirectory } from "../../utils/TemporaryDirectory";
+import { NestiaConfigLoader } from "./NestiaConfigLoader";
+
+/**
+ * Owns one disposable Swagger generation process and its two-phase protocol.
+ *
+ * Configuration functions and controller classes stay in their original Node
+ * realm. Only path information reaches the watcher; generation waits until the
+ * watcher has installed its watches and explicitly starts the second phase.
+ *
+ * @evidence contracts/common.md#principled-implementation A child loads configuration and controllers in one realm, sends only a path projection, and waits for the parent's generate message before writing artifacts. Ending that realm releases both CommonJS and ESM module retention without altering a loader cache.
+ * @evidence contracts/common.md#clear-and-simple-design One open operation returns the prepared watch plan and generation/close callbacks; the same emitted module owns the child entry so source and installed builds share one protocol.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Arbitrary configuration functions execute normally in the child; none is stringified, cloned or replaced. No foreign module cache or resolver is changed.
+ * @evidence contracts/common.md#meaningful-documentation The comment explains the realm boundary and why artifact generation waits for the watcher handshake.
+ * @evidence contracts/portability.md#os-neutral-implementation Node launches this emitted module with its own executable, argument arrays, explicit cwd, IPC and windowsHide. Paths remain native filesystem values and no executable shim or shell command is constructed.
+ * efficient algorithms: Each generation creates one child and projects only the configuration paths required by watcher planning; no controller/module graph is copied into the parent.
+ * reuse equivalent work: Configuration loading and generation share one child and its loaded configuration objects. Changed inputs require a new realm, while the inherited native compiler caches remain reusable outside its disposable outputs.
+ * bound retention and release resources: The parent owns one child per opened generation and awaits its exit on success, failure or close. The child explicitly releases its registered temporary outputs before exit; process exit also releases its module realm.
+ */
+export namespace NestiaSwaggerWatch {
+  /**
+   * A prepared child whose configurations contain only watcher path data.
+   *
+   * @evidence contracts/common.md#principled-implementation The projection is sufficient for watch planning, while callbacks retain the actual child that owns nonserializable configuration functions and controller classes.
+   * @evidence contracts/common.md#clear-and-simple-design The record exposes the prepared plan, the explicit generation phase and idempotent release.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The projection is never passed to a generator as a replacement configuration; the child's original objects drive generation.
+   * @evidence contracts/common.md#meaningful-documentation Member comments distinguish watcher-only data, phase ordering and release ownership.
+   * @evidence contracts/portability.md#os-neutral-implementation The configuration projection carries native input/output paths; the callbacks hide Node's IPC and process representation from the watcher instead of exposing a shell or executable shim.
+   * efficient algorithms: The record performs no computation; open and its callbacks own projection and process coordination.
+   * reuse equivalent work: The record carries a prepared generation but makes no reuse decision; open keeps its configuration and generator in the same child.
+   * bound retention and release resources: The record transfers one prepared child's lifetime to its caller, which must invoke generate or close and finalize on errors. close is idempotent and waits for worker resource release.
+   */
+  export interface IGeneration {
+    /** Paths used only to install watches, never to generate artifacts. */
+    configurations: INestiaConfig[];
+
+    /**
+     * Starts generation after the caller installs its watchers.
+     *
+     * @evidence contracts/common.md#principled-implementation The callback starts the prepared child’s second phase and resolves only after the result and child exit are observed.
+     * @evidence contracts/common.md#clear-and-simple-design One argument-free phase transition uses the configuration already held by the child.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It invokes the actual child generator without substituting projected watcher data for its configuration.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the required watcher-installation ordering.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This callback signature hides the process representation; open owns the Node fork and IPC boundary.
+     * efficient algorithms: The signature selects no computation; open and the child generator own it.
+     * reuse equivalent work: The signature decides no sharing policy; the prepared child retains the actual configuration.
+     * bound retention and release resources: The signature acquires no resource; the record’s owner must invoke this operation or close as documented.
+     */
+    generate: () => Promise<void>;
+
+    /**
+     * Ends the child and waits for its owned resources to be released. A
+     * synchronous compiler or user callback delays processing the disconnect;
+     * release waits for that work rather than abandoning its outputs.
+     *
+     * @evidence contracts/common.md#principled-implementation The callback disconnects an active child once and joins its actual exit, including a reported cleanup failure.
+     * @evidence contracts/common.md#clear-and-simple-design One release operation is shared by cancellation and failure paths.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It waits for owned child cleanup rather than changing foreign loader caches.
+     * @evidence contracts/common.md#meaningful-documentation The comment states release timing and the limitation imposed by synchronous child work.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This callback signature hides Node IPC disconnection; open owns its platform boundary.
+     * efficient algorithms: The signature performs no cleanup algorithm itself; open defines the implementation.
+     * reuse equivalent work: The signature coordinates no producer reuse; open makes release idempotent.
+     * bound retention and release resources: The signature acquires no resource itself; the prepared record and open operation define child lifetime transfer and release.
+     */
+    close: () => Promise<void>;
+  }
+
+  /**
+   * Loads one watch plan in a fresh child without starting generation.
+   *
+   * @evidence contracts/common.md#principled-implementation A prepared IPC message resolves the plan; generate sends the second-phase request and awaits both its result and actual process exit. An early exit or process/IPC error rejects rather than certifying generation.
+   * @evidence contracts/common.md#clear-and-simple-design Preparation, generation result and exit have distinct promises, and one close callback joins resource release on every path.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The emitted child entry executes real loader and generator operations once. Failures retain their cause messages; no retry or cached-success substitution occurs.
+   * @evidence contracts/common.md#meaningful-documentation The comment states that preparation does not write generated artifacts and the returned callbacks define the two-phase lifetime.
+   * @evidence contracts/portability.md#os-neutral-implementation Node launches the existing emitted __filename with its own executable, inherited runtime arguments, explicit cwd, windowsHide and IPC; cancellation uses channel disconnection and awaits actual close without platform shell commands.
+   * efficient algorithms: One child is opened for one generation and one path-only projection is delivered; retained parent protocol state is constant apart from that configuration list and bounded error causes.
+   * reuse equivalent work: The child's loaded configuration is reused for the second phase after watches are installed, so callbacks and controller dependencies are not reconstructed or recompiled between preparation and generation. A changed-input generation needs a fresh realm; compiler disk caches are inherited separately.
+   * bound retention and release resources: Preparation errors close the child before rejection; generation awaits its result and close, and the explicit close callback joins cleanup on cancellation or failure before the second phase. Watcher finalization releases the record after every run and on stop.
+   */
+  export const open = async (props: {
+    configFile: string;
+    projectFile: string;
+    signal?: AbortSignal;
+  }): Promise<IGeneration> => {
+    const child = cp.spawn(
+      process.execPath,
+      [...workerExecArgv(), __filename],
+      {
+        cwd: process.cwd(),
+        stdio: ["inherit", "inherit", "inherit", "ipc"],
+        windowsHide: true,
+        env: { ...process.env, NESTIA_WATCH_CHILD: "1" },
+      },
+    );
+    let resolvePrepared!: (value: INestiaConfig[]) => void;
+    let rejectPrepared!: (error: Error) => void;
+    let resolveGenerated!: () => void;
+    let rejectGenerated!: (error: Error) => void;
+    const prepared = new Promise<INestiaConfig[]>((resolve, reject) => {
+      resolvePrepared = resolve;
+      rejectPrepared = reject;
+    });
+    const generated = new Promise<void>((resolve, reject) => {
+      resolveGenerated = resolve;
+      rejectGenerated = reject;
+    });
+    // Preparation can fail before the caller awaits the generation phase.
+    generated.catch(() => {});
+    let ended = false;
+    let closing = false;
+    let spawned = false;
+    let failure: Error | undefined;
+    let closeFailure: Error | undefined;
+    const fail = (error: Error): void => {
+      failure ??= error;
+      rejectPrepared(error);
+      rejectGenerated(error);
+    };
+    const exited = new Promise<void>((resolve) => {
+      child.once("spawn", () => {
+        spawned = true;
+      });
+      child.once("error", () => {
+        if (!spawned) {
+          ended = true;
+          resolve();
+        }
+      });
+      child.once("exit", (code, signal) => {
+        ended = true;
+        if (
+          closing &&
+          failure === undefined &&
+          (code !== 0 || signal !== null)
+        ) {
+          closeFailure = new Error(
+            `Swagger generation cleanup exited: ${signal ?? code}`,
+          );
+          fail(closeFailure);
+        } else if (!closing && (code !== 0 || signal !== null))
+          fail(
+            new Error(`Swagger generation process exited: ${signal ?? code}`),
+          );
+        else if (!closing) {
+          rejectPrepared(
+            new Error("Swagger generation exited before preparation."),
+          );
+          rejectGenerated(
+            new Error("Swagger generation exited before reporting its result."),
+          );
+        }
+        resolve();
+      });
+    });
+    child.on("error", fail);
+    child.on("message", (message: any) => {
+      if (message?.type === "prepared") resolvePrepared(message.configurations);
+      else if (message?.type === "complete") resolveGenerated();
+      else if (message?.type === "failed")
+        fail(deserializeError(message.error));
+    });
+    const send = (message: object): void => {
+      if (!child.connected) {
+        fail(new Error("Swagger generation IPC channel is closed."));
+        return;
+      }
+      child.send(message, (error) => {
+        if (error) fail(error);
+      });
+    };
+    const close = async (): Promise<void> => {
+      if (!ended && !closing) {
+        closing = true;
+        rejectGenerated(new Error("Swagger generation was cancelled."));
+        // Disconnect is the child's cancellation boundary, including failure
+        // between watch-plan preparation and the generation handshake.
+        if (child.connected) child.disconnect();
+      }
+      await exited;
+      if (closeFailure) throw closeFailure;
+    };
+    const abort = (): void => {
+      const error = new Error("Swagger generation was cancelled.");
+      error.name = "AbortError";
+      rejectPrepared(error);
+      rejectGenerated(error);
+      void close().catch(fail);
+    };
+    props.signal?.addEventListener("abort", abort, { once: true });
+    void exited.then(() => props.signal?.removeEventListener("abort", abort));
+    if (props.signal?.aborted) abort();
+    else
+      send({
+        type: "prepare",
+        configFile: props.configFile,
+        projectFile: props.projectFile,
+      });
+    try {
+      const configurations = await prepared;
+      return {
+        configurations,
+        generate: async () => {
+          send({ type: "generate" });
+          try {
+            await generated;
+            await exited;
+            if (failure) throw failure;
+          } finally {
+            await close();
+          }
+        },
+        close,
+      };
+    } catch (error) {
+      await close();
+      throw error;
+    }
+  };
+}
+
+const serializeError = (error: unknown, depth = 0): any => ({
+  message: error instanceof Error ? error.message : String(error),
+  cause:
+    error instanceof Error && error.cause !== undefined && depth < 10
+      ? serializeError(error.cause, depth + 1)
+      : undefined,
+});
+
+const deserializeError = (error: any): Error =>
+  new Error(error?.message ?? "Swagger generation failed.", {
+    cause:
+      error?.cause === undefined ? undefined : deserializeError(error.cause),
+  });
+
+const projectConfigurations = (
+  configurations: INestiaConfig[],
+): INestiaConfig[] =>
+  configurations.map((config) => ({
+    input:
+      typeof config.input === "function"
+        ? fs.existsSync(path.resolve("src"))
+          ? path.resolve("src")
+          : process.cwd()
+        : config.input,
+    output: config.output,
+    e2e: config.e2e,
+    distribute: config.distribute,
+    swagger:
+      config.swagger === undefined
+        ? undefined
+        : { output: config.swagger.output },
+  }));
+
+// Preserve runtime flags and preloads. Eval/print/input-mode switches select
+// the parent's entry rather than this emitted child file. Inspector flags are
+// negated last, including those inherited through NODE_OPTIONS, so children do
+// not compete for the parent's debug port or wait for another debugger.
+const workerExecArgv = (): string[] => {
+  const output: string[] = [];
+  for (let index = 0; index < process.execArgv.length; ++index) {
+    const argument = process.execArgv[index]!;
+    if (["-e", "--eval", "-p", "--print", "--input-type"].includes(argument)) {
+      ++index;
+      continue;
+    }
+    if (/^--(?:eval|print|input-type)=/.test(argument)) continue;
+    if (["-c", "--check", "--test"].includes(argument)) continue;
+    output.push(argument);
+  }
+  return [
+    ...output,
+    ...["--no-inspect", "--no-inspect-brk", "--no-inspect-wait"].filter(
+      (flag) => process.allowedNodeEnvironmentFlags.has(flag),
+    ),
+  ];
+};
+
+const childMain = (): void => {
+  let configurations: INestiaConfig[] | undefined;
+  let running = false;
+  const finish = (code: number): never => {
+    try {
+      TemporaryDirectory.dispose();
+    } catch (error) {
+      console.error(error);
+      code = 1;
+    }
+    process.exit(code);
+  };
+  const reply = (message: object, exitCode?: number): void => {
+    if (!process.connected) finish(0);
+    process.send!(message, (error) => {
+      if (error) {
+        if (!process.connected) finish(0);
+        console.error(error);
+        finish(1);
+      }
+      if (exitCode !== undefined) finish(exitCode);
+    });
+  };
+  process.once("disconnect", () => finish(0));
+  process.on("message", (message: any) => {
+    if (running) return;
+    running = true;
+    void (async () => {
+      try {
+        if (message?.type === "prepare") {
+          process.env.NESTIA_PROJECT = message.projectFile;
+          const options = await NestiaConfigLoader.compilerOptions(
+            message.projectFile,
+          );
+          configurations = await NestiaConfigLoader.configurations(
+            message.configFile,
+            options.raw.compilerOptions ?? {},
+          );
+          reply({
+            type: "prepared",
+            configurations: projectConfigurations(configurations),
+          });
+        } else if (
+          message?.type === "generate" &&
+          configurations !== undefined
+        ) {
+          if (
+            configurations.length > 1 &&
+            !configurations.some((config) => !!config.swagger?.output)
+          )
+            throw new Error(
+              "Every configurations are invalid to generate Swagger Document, configure INestiaConfig.swagger property.",
+            );
+          for (const config of configurations) {
+            if (configurations.length > 1 && !config.swagger?.output) continue;
+            await new NestiaSdkApplication(config).swagger();
+          }
+          TemporaryDirectory.dispose();
+          reply({ type: "complete" }, 0);
+        } else throw new Error("Invalid Swagger watch generation protocol.");
+      } catch (error) {
+        try {
+          TemporaryDirectory.dispose();
+        } catch (cleanup) {
+          console.error(cleanup);
+        }
+        reply({ type: "failed", error: serializeError(error) }, 1);
+      } finally {
+        running = false;
+      }
+    })();
+  });
+};
+
+if (require.main === module && process.env.NESTIA_WATCH_CHILD === "1")
+  childMain();

package/src/factories/ExpressionFactory.ts

@@ -10,10 +10,25 @@ import {
  * `MinusToken` prefix unary, matching how the TypeScript factory itself emits
  * negative numeric literals.
  *
- * Infinity is written `1e999`, the literal that evaluates to it and the only
- * spelling that is also a literal type; `Infinity` names a value, not a type.
+ * Infinity is written `1e999`, a numeric literal that evaluates to it and can
+ * also appear in a literal type; `Infinity` names a value, not a type.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the number literal builder.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ExpressionFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace ExpressionFactory {
+  /**
+   * Builds a numeric literal, with a prefix minus for a negative value.
+   *
+   * @evidence contracts/common.md#principled-implementation A negative literal is a prefix unary minus on a positive literal in the syntax tree, so the builder produces that shape.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the negative case.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ExpressionFactory.number constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const number = (
     value: number,
   ): NumericLiteral | PrefixUnaryExpression =>