@vlynk-studios/nodulus-core 1.1.0

package/dist/index.js

@@ -0,0 +1,880 @@
+// src/core/registry.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/core/errors.ts
+var NodulusError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "NodulusError";
+    this.code = code;
+    this.details = details;
+  }
+};
+var ERROR_MESSAGES = {
+  MODULE_NOT_FOUND: "This folder was discovered but index.ts does not call Module(). Add Module('name') to the top of index.ts.",
+  DUPLICATE_MODULE: "A module with this name or path already exists. Ensure every module name is unique across the app.",
+  MISSING_IMPORT: "A module listed in 'imports' does not exist in the registry. Verify the module name exists and its index.ts calls Module().",
+  UNDECLARED_IMPORT: "Attempted to import a module not listed in this module's 'imports' field. Add the missing dependency to Module() options.",
+  CIRCULAR_DEPENDENCY: "A circular dependency chain was detected. Extract shared logic into a third module to break the cycle.",
+  EXPORT_MISMATCH: "A name declared in 'exports' is not a real export of index.ts. Ensure you 'export { ... }' the matching member.",
+  INVALID_CONTROLLER: "Controller has no default export of an Express Router. Add 'export default router;' to the controller file.",
+  ALIAS_NOT_FOUND: "An alias points to a target directory that does not exist. Verify the path in nodulus.config.ts or createApp() options.",
+  DUPLICATE_ALIAS: "An alias with this name is already registered to a different path. Check for naming collisions in your config.",
+  DUPLICATE_BOOTSTRAP: "createApp() was called more than once with the same Express instance. Reuse the existing NodulusApp instead.",
+  REGISTRY_MISSING_CONTEXT: "No active registry found in the current async context. Ensure Nodulus API calls run within a createApp() scope.",
+  INVALID_MODULE_DECLARATION: "The Module() call violates architectural rules. Ensure it's called at the top level of index.ts.",
+  DUPLICATE_SERVICE: "A service with this name is already registered. Ensure every Service() name is unique within the same module.",
+  DUPLICATE_REPOSITORY: "A repository with this name is already registered. Ensure every Repository() name is unique within the same module.",
+  DUPLICATE_SCHEMA: "A schema with this name is already registered. Ensure every Schema() name is unique within the same module.",
+  INVALID_ESM_ENV: `Nodulus requires an ESM environment. Please ensure '"type": "module"' is present heavily in your root package.json file.`
+};
+
+// src/core/registry.ts
+var toRegisteredModule = (entry) => ({
+  name: entry.name,
+  path: entry.path,
+  imports: entry.imports,
+  exports: entry.exports,
+  controllers: entry.controllers.map((c) => c.name)
+});
+function createRegistry() {
+  const modules = /* @__PURE__ */ new Map();
+  const aliases = /* @__PURE__ */ new Map();
+  const controllers = /* @__PURE__ */ new Map();
+  const services = /* @__PURE__ */ new Map();
+  const repositories = /* @__PURE__ */ new Map();
+  const schemas = /* @__PURE__ */ new Map();
+  return {
+    hasModule(name) {
+      return modules.has(name);
+    },
+    getModule(name) {
+      const entry = modules.get(name);
+      return entry ? toRegisteredModule(entry) : void 0;
+    },
+    getAllModules() {
+      return Array.from(modules.values()).map(toRegisteredModule);
+    },
+    resolveAlias(alias) {
+      return aliases.get(alias);
+    },
+    getAllAliases() {
+      return Object.fromEntries(aliases.entries());
+    },
+    getDependencyGraph() {
+      const graph = /* @__PURE__ */ new Map();
+      for (const [name, entry] of modules.entries()) {
+        graph.set(name, entry.imports);
+      }
+      return graph;
+    },
+    findCircularDependencies() {
+      const cycles = [];
+      const visited = /* @__PURE__ */ new Set();
+      const recStack = /* @__PURE__ */ new Set();
+      const path10 = [];
+      const dfs = (node) => {
+        visited.add(node);
+        recStack.add(node);
+        path10.push(node);
+        const deps = modules.get(node)?.imports || [];
+        for (const neighbor of deps) {
+          if (!visited.has(neighbor)) {
+            dfs(neighbor);
+          } else if (recStack.has(neighbor)) {
+            const cycleStart = path10.indexOf(neighbor);
+            cycles.push([...path10.slice(cycleStart), neighbor]);
+          }
+        }
+        recStack.delete(node);
+        path10.pop();
+      };
+      for (const node of modules.keys()) {
+        if (!visited.has(node)) {
+          dfs(node);
+        }
+      }
+      return cycles;
+    },
+    registerModule(name, options, dirPath, indexPath) {
+      if (modules.has(name)) {
+        throw new NodulusError(
+          "DUPLICATE_MODULE",
+          `A module with this name already exists. Each module must have a unique name.`,
+          `Module name: ${name}`
+        );
+      }
+      const existing = Array.from(modules.values()).find((m) => m.path === dirPath);
+      if (existing) {
+        throw new NodulusError(
+          "DUPLICATE_MODULE",
+          `A module is already registered for this folder. Call Module() only once per directory.`,
+          `Existing: ${existing.name}, New: ${name}, Folder: ${dirPath}`
+        );
+      }
+      const entry = {
+        name,
+        path: dirPath,
+        indexPath,
+        imports: options.imports || [],
+        exports: options.exports || [],
+        controllers: []
+      };
+      modules.set(name, entry);
+    },
+    registerAlias(alias, targetPath) {
+      const existing = aliases.get(alias);
+      if (existing && existing !== targetPath) {
+        throw new NodulusError(
+          "DUPLICATE_ALIAS",
+          `An alias with this name is already registered to a different target path.`,
+          `Alias: ${alias}, Existing: ${existing}, New: ${targetPath}`
+        );
+      }
+      aliases.set(alias, targetPath);
+    },
+    registerControllerMetadata(entry) {
+      if (controllers.has(entry.path)) {
+        throw new NodulusError(
+          "INVALID_CONTROLLER",
+          `Controller() was called more than once in the same file.`,
+          `File: ${entry.path}`
+        );
+      }
+      controllers.set(entry.path, entry);
+    },
+    getControllerMetadata(filePath) {
+      return controllers.get(filePath);
+    },
+    getAllControllersMetadata() {
+      return Array.from(controllers.values());
+    },
+    getRawModule(name) {
+      return modules.get(name);
+    },
+    registerFileMetadata(entry) {
+      if (entry.type === "service") {
+        if (services.has(entry.name)) {
+          throw new NodulusError(
+            "DUPLICATE_SERVICE",
+            `A service named "${entry.name}" is already registered. Each Service() name must be unique within the registry.`,
+            `Duplicate name: ${entry.name}`
+          );
+        }
+        services.set(entry.name, entry);
+      } else if (entry.type === "repository") {
+        if (repositories.has(entry.name)) {
+          throw new NodulusError(
+            "DUPLICATE_REPOSITORY",
+            `A repository named "${entry.name}" is already registered. Each Repository() name must be unique within the registry.`,
+            `Duplicate name: ${entry.name}`
+          );
+        }
+        repositories.set(entry.name, entry);
+      } else if (entry.type === "schema") {
+        if (schemas.has(entry.name)) {
+          throw new NodulusError(
+            "DUPLICATE_SCHEMA",
+            `A schema named "${entry.name}" is already registered. Each Schema() name must be unique within the registry.`,
+            `Duplicate name: ${entry.name}`
+          );
+        }
+        schemas.set(entry.name, entry);
+      }
+    },
+    getAllServices() {
+      return Array.from(services.values());
+    },
+    getService(name) {
+      return services.get(name);
+    },
+    getAllRepositories() {
+      return Array.from(repositories.values());
+    },
+    getRepository(name) {
+      return repositories.get(name);
+    },
+    getAllSchemas() {
+      return Array.from(schemas.values());
+    },
+    getSchema(name) {
+      return schemas.get(name);
+    },
+    clearRegistry() {
+      modules.clear();
+      aliases.clear();
+      controllers.clear();
+      services.clear();
+      repositories.clear();
+      schemas.clear();
+    }
+  };
+}
+var registryContext = new AsyncLocalStorage();
+function getActiveRegistry() {
+  const store = registryContext.getStore();
+  if (!store) {
+    throw new NodulusError(
+      "REGISTRY_MISSING_CONTEXT",
+      "No active registry found in the current async context. Ensure code runs inside a createApp() execution scope."
+    );
+  }
+  return store;
+}
+var getRegistry = () => getActiveRegistry();
+
+// src/identifiers/module.ts
+import path2 from "path";
+
+// src/core/caller.ts
+import path from "path";
+import { fileURLToPath } from "url";
+function resolveCallerFile(identifierName) {
+  const originalFunc = Error.prepareStackTrace;
+  let callerFile = null;
+  try {
+    const err = new Error();
+    Error.prepareStackTrace = (_, stack2) => stack2;
+    const stack = err.stack;
+    if (stack && stack.length > 3) {
+      callerFile = stack[3].getFileName() || null;
+    }
+  } catch {
+  } finally {
+    Error.prepareStackTrace = originalFunc;
+  }
+  if (!callerFile) {
+    throw new NodulusError(
+      "INVALID_MODULE_DECLARATION",
+      `${identifierName} could not determine caller path. Stack trace unavailable.`,
+      "Ensure you are using Node.js >= 20.6 with ESM and no bundler obfuscation."
+    );
+  }
+  if (callerFile.startsWith("file://")) {
+    callerFile = fileURLToPath(callerFile);
+  }
+  return callerFile;
+}
+function getModuleCallerInfo(identifierName) {
+  const filePath = resolveCallerFile(identifierName);
+  return { filePath, dirPath: path.dirname(filePath) };
+}
+function getFileCallerInfo(identifierName) {
+  return { filePath: resolveCallerFile(identifierName) };
+}
+
+// src/identifiers/module.ts
+function Module(name, options = {}) {
+  if (typeof name !== "string") {
+    throw new TypeError(`Module name must be a string, received ${typeof name}`);
+  }
+  const { filePath: indexPath, dirPath } = getModuleCallerInfo("Module()");
+  if (dirPath) {
+    const folderName = path2.basename(dirPath);
+    if (folderName && folderName !== name) {
+      throw new NodulusError(
+        "INVALID_MODULE_DECLARATION",
+        `Module name "${name}" does not match its containing folder "${folderName}".`,
+        `The module name in Module() MUST match the folder name exactly.`
+      );
+    }
+  }
+  const fileName = path2.basename(indexPath);
+  const isIndexFile = /index\.(ts|js|mts|mjs)$/.test(fileName);
+  if (!isIndexFile) {
+    throw new NodulusError(
+      "INVALID_MODULE_DECLARATION",
+      `Module() was called from "${fileName}", but it must be called only from the module's index file.`,
+      `File: ${indexPath}`
+    );
+  }
+  getActiveRegistry().registerModule(name, options, dirPath, indexPath);
+}
+
+// src/identifiers/controller.ts
+import path3 from "path";
+function Controller(prefix, options = {}) {
+  if (typeof prefix !== "string") {
+    throw new TypeError(`Controller prefix must be a string, received ${typeof prefix}`);
+  }
+  const { filePath } = getFileCallerInfo("Controller()");
+  const name = path3.parse(filePath).name;
+  getActiveRegistry().registerControllerMetadata({
+    name,
+    path: filePath,
+    prefix,
+    middlewares: options.middlewares ?? [],
+    enabled: options.enabled ?? true
+  });
+}
+
+// src/identifiers/service.ts
+import path4 from "path";
+function Service(name, options = {}) {
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new TypeError(`Service name must be a non-empty string, received ${typeof name}`);
+  }
+  const { filePath } = getFileCallerInfo("Service()");
+  const inferredModule = options.module ?? path4.basename(path4.dirname(filePath));
+  getActiveRegistry().registerFileMetadata({
+    name,
+    path: filePath,
+    type: "service",
+    module: inferredModule,
+    description: options.description
+  });
+}
+
+// src/identifiers/repository.ts
+import path5 from "path";
+function Repository(name, options = {}) {
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new TypeError(`Repository name must be a non-empty string, received ${typeof name}`);
+  }
+  const { filePath } = getFileCallerInfo("Repository()");
+  const inferredModule = options.module ?? path5.basename(path5.dirname(filePath));
+  getActiveRegistry().registerFileMetadata({
+    name,
+    path: filePath,
+    type: "repository",
+    module: inferredModule,
+    description: options.description,
+    source: options.source
+  });
+}
+
+// src/identifiers/schema.ts
+import path6 from "path";
+function Schema(name, options = {}) {
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new TypeError(`Schema name must be a non-empty string, received ${typeof name}`);
+  }
+  const { filePath } = getFileCallerInfo("Schema()");
+  const inferredModule = options.module ?? path6.basename(path6.dirname(filePath));
+  getActiveRegistry().registerFileMetadata({
+    name,
+    path: filePath,
+    type: "schema",
+    module: inferredModule,
+    description: options.description,
+    library: options.library
+  });
+}
+
+// src/bootstrap/createApp.ts
+import fs2 from "fs";
+import path8 from "path";
+import { pathToFileURL as pathToFileURL3 } from "url";
+import fg from "fast-glob";
+
+// src/core/config.ts
+import fs from "fs";
+import path7 from "path";
+import { pathToFileURL } from "url";
+
+// src/core/logger.ts
+import pc from "picocolors";
+var LEVEL_ORDER = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var LEVEL_STYLE = {
+  debug: (msg) => pc.gray(msg),
+  info: (msg) => pc.cyan(msg),
+  warn: (msg) => pc.yellow(msg),
+  error: (msg) => pc.red(msg)
+};
+var LEVEL_LABELS = {
+  debug: "debug",
+  info: "info ",
+  // trailing space for alignment
+  warn: "warn ",
+  error: "error"
+};
+var defaultLogHandler = (level, message) => {
+  const prefix = pc.gray("[Nodulus]");
+  const label = LEVEL_STYLE[level](LEVEL_LABELS[level]);
+  const line = `${prefix} ${label} ${message}`;
+  if (level === "warn" || level === "error") {
+    process.stderr.write(line + "\n");
+  } else {
+    process.stdout.write(line + "\n");
+  }
+};
+function resolveLogLevel(explicit) {
+  if (explicit) return explicit;
+  const nodeDebug = process.env.NODE_DEBUG ?? "";
+  if (nodeDebug.split(",").map((s) => s.trim()).includes("nodulus")) {
+    return "debug";
+  }
+  return "info";
+}
+function createLogger(handler, minLevel) {
+  const minOrder = LEVEL_ORDER[minLevel];
+  const emit = (level, message, meta) => {
+    if (LEVEL_ORDER[level] >= minOrder) {
+      handler(level, message, meta);
+    }
+  };
+  return {
+    debug: (msg, meta) => emit("debug", msg, meta),
+    info: (msg, meta) => emit("info", msg, meta),
+    warn: (msg, meta) => emit("warn", msg, meta),
+    error: (msg, meta) => emit("error", msg, meta)
+  };
+}
+
+// src/core/config.ts
+var defaultStrict = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+var DEFAULTS = {
+  modules: "src/modules/*",
+  prefix: "",
+  aliases: {},
+  strict: defaultStrict,
+  resolveAliases: true,
+  logger: defaultLogHandler,
+  logLevel: resolveLogLevel()
+};
+var loadConfig = async (options = {}) => {
+  const cwd = process.cwd();
+  let fileConfig = {};
+  const tsPath = path7.join(cwd, "nodulus.config.ts");
+  const jsPath = path7.join(cwd, "nodulus.config.js");
+  const isProduction = process.env.NODE_ENV === "production";
+  const hasTsLoader = process.execArgv.some((arg) => arg.includes("ts-node") || arg.includes("tsx")) || process._preload_modules?.some((m) => m.includes("ts-node") || m.includes("tsx"));
+  const candidates = [];
+  if (!isProduction || hasTsLoader) {
+    candidates.push(tsPath);
+  }
+  candidates.push(jsPath);
+  let configPathToLoad = null;
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      configPathToLoad = candidate;
+      break;
+    }
+  }
+  if (configPathToLoad) {
+    try {
+      const importUrl = pathToFileURL(configPathToLoad).href;
+      const mod = await import(importUrl);
+      fileConfig = mod.default || mod.config || mod;
+    } catch (error) {
+      if (configPathToLoad.endsWith(".ts") && error.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+        throw new Error(
+          `[Nodulus] Found "nodulus.config.ts" but your environment cannot load raw TypeScript files.
+  - In production: Run "npm run build" to generate a .js config OR use nodulus.config.js.
+  - In development: Ensure you are running with a loader like "tsx" or "ts-node".`,
+          { cause: error }
+        );
+      }
+      throw new Error(`[Nodulus] Failed to parse or evaluate config file at ${configPathToLoad}: ${error.message}`, { cause: error });
+    }
+  }
+  return {
+    modules: options.modules ?? fileConfig.modules ?? DEFAULTS.modules,
+    prefix: options.prefix ?? fileConfig.prefix ?? DEFAULTS.prefix,
+    aliases: {
+      ...DEFAULTS.aliases,
+      ...fileConfig.aliases || {},
+      ...options.aliases || {}
+      // Options override file aliases
+    },
+    strict: options.strict ?? fileConfig.strict ?? DEFAULTS.strict,
+    resolveAliases: options.resolveAliases ?? fileConfig.resolveAliases ?? DEFAULTS.resolveAliases,
+    logger: options.logger ?? fileConfig.logger ?? DEFAULTS.logger,
+    logLevel: resolveLogLevel(options.logLevel ?? fileConfig.logLevel)
+  };
+};
+
+// src/aliases/resolver.ts
+import { register } from "module";
+import { pathToFileURL as pathToFileURL2 } from "url";
+var isHookRegistered = false;
+function activateAliasResolver(moduleAliases, folderAliases, log) {
+  if (isHookRegistered) return;
+  const combinedAliases = { ...moduleAliases, ...folderAliases };
+  for (const [alias, target] of Object.entries(folderAliases)) {
+    log.debug(`Alias registered: ${alias} \u2192 ${target}`, { alias, target, source: "config" });
+  }
+  for (const [alias, target] of Object.entries(moduleAliases)) {
+    log.debug(`Alias registered: ${alias} \u2192 ${target}`, { alias, target, source: "module" });
+  }
+  const serialisedAliases = JSON.stringify(combinedAliases);
+  const loaderCode = `
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+
+const aliases = ${serialisedAliases};
+
+export async function resolve(specifier, context, nextResolve) {
+  for (const alias of Object.keys(aliases)) {
+    if (specifier === alias || specifier.startsWith(alias + '/')) {
+      const target = aliases[alias];
+      const resolvedPath = specifier.replace(alias, target);
+      return nextResolve(pathToFileURL(path.resolve(resolvedPath)).href, context);
+    }
+  }
+  return nextResolve(specifier, context);
+}
+`;
+  try {
+    const dataUrl = `data:text/javascript,${encodeURIComponent(loaderCode)}`;
+    const parentUrl = typeof __filename === "undefined" ? import.meta.url : pathToFileURL2(__filename).href;
+    if (typeof register === "function") {
+      register(dataUrl, { parentURL: parentUrl });
+      isHookRegistered = true;
+      log.info(`ESM alias hook activated (${Object.keys(combinedAliases).length} alias(es))`, {
+        aliasCount: Object.keys(combinedAliases).length
+      });
+    } else {
+      log.warn("ESM alias hook could not be registered \u2014 upgrade to Node.js >= 20.6.0 for runtime alias support", {
+        nodeVersion: process.version
+      });
+    }
+  } catch (err) {
+    log.warn("ESM alias hook registration threw an unexpected error \u2014 aliases may not resolve at runtime", {
+      error: err?.message ?? String(err)
+    });
+  }
+}
+
+// src/aliases/cache.ts
+var aliasCache = {};
+function updateAliasCache(aliases) {
+  aliasCache = { ...aliases };
+}
+function getAliasCache() {
+  return aliasCache;
+}
+
+// src/bootstrap/createApp.ts
+import { performance } from "perf_hooks";
+import pc2 from "picocolors";
+async function createApp(app, options = {}) {
+  if (app.__nodulusBootstrapped) {
+    throw new NodulusError(
+      "DUPLICATE_BOOTSTRAP",
+      "createApp() was called more than once with the same Express instance."
+    );
+  }
+  let isEsm = false;
+  try {
+    const pkgPath = path8.resolve(process.cwd(), "package.json");
+    if (fs2.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf8"));
+      if (pkg.type === "module") {
+        isEsm = true;
+      }
+    }
+  } catch (_e) {
+  }
+  if (!isEsm) {
+    throw new NodulusError(
+      "INVALID_ESM_ENV",
+      'Nodulus requires an ESM environment. Please ensure "type": "module" is present in your root package.json file.'
+    );
+  }
+  const registry = createRegistry();
+  return registryContext.run(registry, async () => {
+    const startTime = performance.now();
+    try {
+      const config = await loadConfig(options);
+      const log = createLogger(config.logger, config.logLevel);
+      log.info("Bootstrap started", {
+        modules: pc2.cyan(config.modules),
+        prefix: pc2.cyan(config.prefix || "(none)"),
+        strict: pc2.yellow(String(config.strict)),
+        nodeVersion: pc2.gray(process.version)
+      });
+      const globPattern = config.modules.replace(/\\/g, "/");
+      const moduleDirs = await fg(globPattern, {
+        onlyDirectories: true,
+        absolute: true,
+        cwd: process.cwd()
+      });
+      moduleDirs.sort();
+      const resolvedModules = [];
+      for (const dirPath of moduleDirs) {
+        log.debug(`Discovered module directory: ${dirPath}`, { dirPath });
+        const tsPath = path8.join(dirPath, "index.ts");
+        const jsPath = path8.join(dirPath, "index.js");
+        let indexPath = null;
+        if (fs2.existsSync(tsPath)) {
+          indexPath = tsPath;
+        } else if (fs2.existsSync(jsPath)) {
+          indexPath = jsPath;
+        }
+        if (!indexPath) {
+          throw new NodulusError(
+            "MODULE_NOT_FOUND",
+            `No index.ts or index.js found for module. A module directory must have an index file mapping its dependencies.`,
+            `Directory: ${dirPath}`
+          );
+        }
+        resolvedModules.push({ dirPath, indexPath });
+      }
+      if (config.resolveAliases !== false) {
+        const pureModuleAliases = {};
+        for (const mod of resolvedModules) {
+          const modName = path8.basename(mod.dirPath);
+          const aliasKey = `@modules/${modName}`;
+          pureModuleAliases[aliasKey] = mod.dirPath;
+          registry.registerAlias(aliasKey, mod.dirPath);
+        }
+        activateAliasResolver(pureModuleAliases, config.aliases, log);
+        updateAliasCache(registry.getAllAliases());
+      }
+      for (const mod of resolvedModules) {
+        const imported = await import(pathToFileURL3(mod.indexPath).href);
+        const allRegistered = registry.getAllModules();
+        const registeredMod = allRegistered.find((m) => path8.normalize(m.path) === path8.normalize(mod.dirPath));
+        if (!registeredMod) {
+          throw new NodulusError(
+            "MODULE_NOT_FOUND",
+            `No index.ts found calling Module(). Add Module() to the module's index.ts.`,
+            `File: ${mod.indexPath}`
+          );
+        }
+        log.info(`Module loaded: ${pc2.green(registeredMod.name)}`, {
+          name: registeredMod.name,
+          imports: registeredMod.imports,
+          exports: registeredMod.exports,
+          path: registeredMod.path
+        });
+        const actualExports = Object.keys(imported).filter((key) => key !== "default");
+        const declaredExports = registeredMod.exports || [];
+        for (const declared of declaredExports) {
+          if (!actualExports.includes(declared)) {
+            throw new NodulusError(
+              "EXPORT_MISMATCH",
+              `A name declared in exports does not exist as a real export of index.ts.`,
+              `Module: ${registeredMod.name}, Missing Export: ${declared}`
+            );
+          }
+        }
+        if (config.strict) {
+          for (const actual of actualExports) {
+            if (!declaredExports.includes(actual)) {
+              log.warn(
+                `Module "${registeredMod.name}" exports "${actual}" but it is not declared in Module() options "exports" array.`,
+                { name: registeredMod.name, exportName: actual }
+              );
+            }
+          }
+        }
+      }
+      const allModules = registry.getAllModules();
+      for (const mod of allModules) {
+        for (const importName of mod.imports) {
+          if (!registry.hasModule(importName)) {
+            throw new NodulusError(
+              "MISSING_IMPORT",
+              `A module declared in imports does not exist in the registry.`,
+              `Module "${mod.name}" is trying to import missing module "${importName}"`
+            );
+          }
+        }
+      }
+      if (config.strict) {
+        const cycles = registry.findCircularDependencies();
+        if (cycles.length > 0) {
+          const cycleStrings = cycles.map((cycle) => cycle.join(" -> ")).join(" | ");
+          throw new NodulusError(
+            "CIRCULAR_DEPENDENCY",
+            `Circular dependency detected. Extract the shared dependency into a separate module.`,
+            `Cycles found: ${cycleStrings}`
+          );
+        }
+      }
+      for (const mod of allModules) {
+        const rawMod = registry.getRawModule(mod.name);
+        if (!rawMod) continue;
+        const files = await fg("**/*.{ts,js,mts,mjs,cjs}", {
+          cwd: mod.path,
+          absolute: true,
+          ignore: [
+            "**/*.types.*",
+            "**/*.d.ts",
+            "**/*.spec.*",
+            "**/*.test.*",
+            "index.*"
+            // Escapes root index.ts/js
+          ]
+        });
+        files.sort();
+        for (let file of files) {
+          log.debug(`Scanning controller file: ${file}`, { filePath: file, module: mod.name });
+          file = path8.normalize(file);
+          let imported;
+          try {
+            imported = await import(pathToFileURL3(file).href);
+          } catch (err) {
+            throw new NodulusError(
+              "INVALID_CONTROLLER",
+              `Failed to import controller file. Check for syntax errors or missing dependencies.`,
+              `File: ${file} \u2014 ${err.message}`
+            );
+          }
+          const resolvedFile = path8.normalize(file);
+          const ctrlMeta = registry.getControllerMetadata(resolvedFile) || registry.getAllControllersMetadata().find((c) => path8.normalize(c.path) === resolvedFile);
+          if (ctrlMeta) {
+            const isRouter = imported.default && typeof imported.default === "function" && typeof imported.default.use === "function";
+            if (!isRouter) {
+              throw new NodulusError(
+                "INVALID_CONTROLLER",
+                `Controller has no default export of a Router. Add export default router.`,
+                `File: ${file}`
+              );
+            }
+            log.debug(`Controller registered: ${pc2.green(ctrlMeta.name)} \u2192 ${pc2.cyan(ctrlMeta.prefix)}`, {
+              name: ctrlMeta.name,
+              prefix: ctrlMeta.prefix,
+              module: mod.name,
+              middlewareCount: ctrlMeta.middlewares.length
+            });
+            ctrlMeta.router = imported.default;
+            rawMod.controllers.push(ctrlMeta);
+          }
+        }
+        if (rawMod.controllers.length === 0) {
+          log.warn(`Module "${mod.name}" has no controllers \u2014 no routes will be mounted from it`, {
+            name: mod.name,
+            path: mod.path
+          });
+        }
+      }
+      const mountedRoutes = [];
+      for (const mod of allModules) {
+        const rawMod = registry.getRawModule(mod.name);
+        if (!rawMod) continue;
+        for (const ctrl of rawMod.controllers) {
+          if (!ctrl.enabled) {
+            log.info(`Controller "${ctrl.name}" is disabled \u2014 skipping mount`, {
+              name: ctrl.name,
+              module: mod.name,
+              prefix: ctrl.prefix
+            });
+            continue;
+          }
+          const fullPath = (config.prefix + ctrl.prefix).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+          if (ctrl.router) {
+            if (ctrl.middlewares && ctrl.middlewares.length > 0) {
+              app.use(fullPath, ...ctrl.middlewares, ctrl.router);
+            } else {
+              app.use(fullPath, ctrl.router);
+            }
+            let foundRoutes = false;
+            const extractedRoutes = [];
+            if (ctrl.router.stack && Array.isArray(ctrl.router.stack)) {
+              for (const layer of ctrl.router.stack) {
+                const routeObj = layer.route;
+                if (routeObj && routeObj.methods) {
+                  foundRoutes = true;
+                  const routePath = routeObj.path;
+                  const methods = Object.keys(routeObj.methods).filter((m) => routeObj.methods[m]).map((m) => m.toUpperCase());
+                  for (const method of methods) {
+                    const fullRoutePath = (fullPath + (routePath === "/" ? "" : routePath)).replace(/\/+/g, "/");
+                    extractedRoutes.push({ method, path: fullRoutePath });
+                    mountedRoutes.push({
+                      method,
+                      path: fullRoutePath,
+                      module: mod.name,
+                      controller: ctrl.name
+                    });
+                  }
+                }
+              }
+            }
+            if (!foundRoutes) {
+              extractedRoutes.push({ method: "USE", path: fullPath });
+              mountedRoutes.push({
+                method: "USE",
+                path: fullPath,
+                module: mod.name,
+                controller: ctrl.name
+              });
+            }
+            const methodColors = {
+              GET: pc2.green,
+              POST: pc2.yellow,
+              PUT: pc2.cyan,
+              PATCH: pc2.magenta,
+              DELETE: pc2.red,
+              USE: pc2.gray
+            };
+            for (const route of extractedRoutes) {
+              const colorFn = methodColors[route.method] || pc2.white;
+              log.info(`  ${colorFn(route.method.padEnd(6))} ${pc2.white(route.path)}  ${pc2.gray(`(${ctrl.name})`)}`, {
+                method: route.method,
+                path: route.path,
+                module: mod.name,
+                controller: ctrl.name
+              });
+            }
+          }
+        }
+      }
+      app.__nodulusBootstrapped = true;
+      const safeRegisteredModules = allModules.map((m) => registry.getModule(m.name));
+      const durationMs = Math.round(performance.now() - startTime);
+      log.info(`${pc2.green("Bootstrap complete")} \u2014 ${pc2.cyan(allModules.length)} module(s), ${pc2.cyan(mountedRoutes.length)} route(s) in ${pc2.yellow(`${durationMs}ms`)}`, {
+        moduleCount: allModules.length,
+        routeCount: mountedRoutes.length,
+        durationMs
+      });
+      return {
+        modules: safeRegisteredModules,
+        routes: mountedRoutes,
+        registry
+      };
+    } catch (err) {
+      registry.clearRegistry();
+      throw err;
+    }
+  });
+}
+
+// src/aliases/getAliases.ts
+import path9 from "path";
+async function getAliases(options = {}) {
+  const includeFolders = options.includeFolders ?? true;
+  const absolute = options.absolute ?? false;
+  const allAliases = getAliasCache();
+  const result = {};
+  const cwd = process.cwd();
+  for (const [alias, target] of Object.entries(allAliases)) {
+    if (!includeFolders && !alias.startsWith("@modules/")) {
+      continue;
+    }
+    let resolvedPath;
+    if (absolute) {
+      resolvedPath = path9.isAbsolute(target) ? target : path9.resolve(cwd, target);
+    } else {
+      resolvedPath = path9.isAbsolute(target) ? path9.relative(cwd, target) : target;
+      resolvedPath = resolvedPath.replace(/\\/g, "/");
+      if (!resolvedPath.startsWith(".") && !resolvedPath.startsWith("/")) {
+        resolvedPath = "./" + resolvedPath;
+      }
+    }
+    result[alias] = resolvedPath;
+  }
+  return result;
+}
+export {
+  Controller,
+  ERROR_MESSAGES,
+  Module,
+  NodulusError,
+  Repository,
+  Schema,
+  Service,
+  createApp,
+  getAliases,
+  getRegistry
+};
+//# sourceMappingURL=index.js.map