@vlynk-studios/nodulus-core 1.2.0 → 1.2.5

package/dist/index.d.ts

@@ -1,21 +1,5 @@
-import { RequestHandler, Router, Application } from 'express';
+import { RequestHandler, Application } from 'express';
 
-interface ControllerEntry {
-    name: string;
-    path: string;
-    prefix: string;
-    middlewares: RequestHandler[];
-    router?: Router;
-    enabled: boolean;
-}
-interface ModuleEntry {
-    name: string;
-    path: string;
-    indexPath: string;
-    imports: string[];
-    exports: string[];
-    controllers: ControllerEntry[];
-}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /**
  * Function that receives a log event from Nodulus.
@@ -93,9 +77,24 @@ interface SchemaEntry {
 }
 /** Discriminated union for all file-level identifier entries. */
 type FileEntry = ServiceEntry | RepositoryEntry | SchemaEntry;
+interface NitsConfig {
+    /**
+     * Custom similarity threshold (0.0 to 1.0).
+     * If omitted, a dynamic threshold based on module size is used.
+     */
+    similarityThreshold?: number;
+    /** Whether to enable NITS identity tracking. Default: true. */
+    enabled?: boolean;
+    /** Custom path to the NITS registry file. Default: '.nodulus/registry.json'. */
+    registryPath?: string;
+}
 interface CreateAppOptions {
     /** Glob pointing to module folders. Default: 'src/modules/*'. */
     modules?: string;
+    /** Glob pointing to domain folders (v2.0.0+). Default: undefined. */
+    domains?: string;
+    /** Glob pointing to shared global folders (v2.0.0+). Default: undefined. */
+    shared?: string;
     /** Global route prefix. Example: '/api/v1'. Default: ''. */
     prefix?: string;
     /** Folder aliases beyond the auto-generated @modules/* entries. Default: {}. */
@@ -122,16 +121,8 @@ interface CreateAppOptions {
      * Default: 'info' (debug is off unless explicitly set).
      */
     logLevel?: LogLevel;
-}
-/** Resolved configuration used internally (defaults applied). */
-interface ResolvedConfig {
-    modules: string;
-    prefix: string;
-    aliases: Record<string, string>;
-    strict: boolean;
-    resolveAliases: boolean;
-    logger: LogHandler;
-    logLevel: LogLevel;
+    /** NITS (Nodulus Integrated Tracking System) configuration. */
+    nits?: NitsConfig;
 }
 /** A module as it appears in the NodularApp result after bootstrap. */
 interface RegisteredModule {
@@ -184,6 +175,8 @@ interface GetAliasesOptions {
     absolute?: boolean;
 }
 
+type ModuleRegistration = RegisteredModule;
+type FeatureRegistration = FileEntry;
 /**
  * Returns a read-only view of the registry active in the current async context.
  *
@@ -193,14 +186,12 @@ interface GetAliasesOptions {
  */
 declare const getRegistry: () => NodulusRegistryAdvanced;
 
-type NodulusErrorCode = "MODULE_NOT_FOUND" | "DUPLICATE_MODULE" | "MISSING_IMPORT" | "UNDECLARED_IMPORT" | "CIRCULAR_DEPENDENCY" | "EXPORT_MISMATCH" | "INVALID_CONTROLLER" | "ALIAS_NOT_FOUND" | "DUPLICATE_ALIAS" | "DUPLICATE_BOOTSTRAP" | "REGISTRY_MISSING_CONTEXT" | "INVALID_MODULE_DECLARATION" | "DUPLICATE_SERVICE" | "DUPLICATE_REPOSITORY" | "DUPLICATE_SCHEMA" | "INVALID_ESM_ENV";
+type NodulusErrorCode = "MODULE_NOT_FOUND" | "DUPLICATE_MODULE" | "MISSING_IMPORT" | "UNDECLARED_IMPORT" | "CIRCULAR_DEPENDENCY" | "EXPORT_MISMATCH" | "INVALID_CONTROLLER" | "ALIAS_NOT_FOUND" | "DUPLICATE_ALIAS" | "DUPLICATE_BOOTSTRAP" | "REGISTRY_MISSING_CONTEXT" | "INVALID_MODULE_DECLARATION" | "DUPLICATE_SERVICE" | "DUPLICATE_REPOSITORY" | "DUPLICATE_SCHEMA" | "INVALID_ESM_ENV" | "CLI_ERROR";
 declare class NodulusError extends Error {
     readonly code: NodulusErrorCode;
     readonly details?: string;
     constructor(code: NodulusErrorCode, message: string, details?: string);
 }
-/** @deprecated — not used internally. Messages are defined at each throw site. */
-declare const ERROR_MESSAGES: Record<NodulusErrorCode, string>;
 
 declare function Module(name: string, options?: ModuleOptions): void;
 
@@ -264,4 +255,4 @@ declare function createApp(app: Application, options?: CreateAppOptions): Promis
 
 declare function getAliases(options?: GetAliasesOptions): Promise<Record<string, string>>;
 
-export { Controller, type ControllerEntry, type ControllerOptions, type CreateAppOptions, ERROR_MESSAGES, type FileEntry, type GetAliasesOptions, type LogHandler, type LogLevel, Module, type ModuleEntry, type ModuleOptions, type MountedRoute, type NodulusApp, type NodulusConfig, NodulusError, type NodulusErrorCode, type NodulusRegistry, type NodulusRegistryAdvanced, type RegisteredModule, Repository, type RepositoryEntry, type RepositoryOptions, type ResolvedConfig, Schema, type SchemaEntry, type SchemaOptions, Service, type ServiceEntry, type ServiceOptions, createApp, getAliases, getRegistry };
+export { Controller, type ControllerOptions, type CreateAppOptions, type FeatureRegistration, type GetAliasesOptions, type LogHandler, type LogLevel, Module, type ModuleOptions, type ModuleRegistration, type MountedRoute, type NodulusApp, type NodulusConfig, NodulusError, type NodulusErrorCode, type NodulusRegistry, type NodulusRegistryAdvanced, type RegisteredModule, Repository, type RepositoryOptions, Schema, type SchemaOptions, Service, type ServiceOptions, createApp, getAliases, getRegistry };

package/dist/index.js

@@ -12,24 +12,36 @@ var NodulusError = class extends Error {
     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/utils/cycle-detector.ts
+function findCircularDependencies(dependencyMap) {
+  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 = dependencyMap.get(node) || [];
+    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 dependencyMap.keys()) {
+    if (!visited.has(node)) {
+      dfs(node);
+    }
+  }
+  return cycles;
+}
 
 // src/core/registry.ts
 var toRegisteredModule = (entry) => ({
@@ -71,32 +83,11 @@ function createRegistry() {
       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);
-        }
+      const dependencyMap = /* @__PURE__ */ new Map();
+      for (const [name, entry] of modules.entries()) {
+        dependencyMap.set(name, entry.imports);
       }
-      return cycles;
+      return findCircularDependencies(dependencyMap);
     },
     registerModule(name, options, dirPath, indexPath) {
       if (modules.has(name)) {
@@ -366,7 +357,7 @@ function Schema(name, options = {}) {
 // src/bootstrap/createApp.ts
 import fs2 from "fs";
 import path8 from "path";
-import { pathToFileURL as pathToFileURL3 } from "url";
+import { pathToFileURL as pathToFileURL2 } from "url";
 import fg from "fast-glob";
 
 // src/core/config.ts
@@ -432,25 +423,27 @@ function createLogger(handler, minLevel) {
 var defaultStrict = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
 var DEFAULTS = {
   modules: "src/modules/*",
+  domains: void 0,
+  shared: void 0,
   prefix: "",
   aliases: {},
   strict: defaultStrict,
   resolveAliases: true,
   logger: defaultLogHandler,
-  logLevel: resolveLogLevel()
+  logLevel: resolveLogLevel(),
+  nits: {
+    enabled: true,
+    similarityThreshold: void 0,
+    // Use dynamic by default
+    registryPath: ".nodulus/registry.json"
+  }
 };
 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);
+  const candidates = [tsPath, jsPath];
   let configPathToLoad = null;
   for (const candidate of candidates) {
     if (fs.existsSync(candidate)) {
@@ -477,6 +470,8 @@ var loadConfig = async (options = {}) => {
   }
   return {
     modules: options.modules ?? fileConfig.modules ?? DEFAULTS.modules,
+    domains: options.domains ?? fileConfig.domains ?? DEFAULTS.domains,
+    shared: options.shared ?? fileConfig.shared ?? DEFAULTS.shared,
     prefix: options.prefix ?? fileConfig.prefix ?? DEFAULTS.prefix,
     aliases: {
       ...DEFAULTS.aliases,
@@ -487,25 +482,33 @@ var loadConfig = async (options = {}) => {
     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)
+    logLevel: resolveLogLevel(options.logLevel ?? fileConfig.logLevel),
+    nits: {
+      enabled: options.nits?.enabled ?? fileConfig.nits?.enabled ?? DEFAULTS.nits.enabled,
+      similarityThreshold: options.nits?.similarityThreshold ?? fileConfig.nits?.similarityThreshold ?? DEFAULTS.nits.similarityThreshold,
+      registryPath: options.nits?.registryPath ?? fileConfig.nits?.registryPath ?? DEFAULTS.nits.registryPath
+    }
   };
 };
 
 // src/aliases/resolver.ts
 import { register } from "module";
-import { pathToFileURL as pathToFileURL2 } from "url";
 var isHookRegistered = false;
-function activateAliasResolver(moduleAliases, folderAliases, log) {
+var registrationPromise = null;
+async 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 = `
+  if (registrationPromise) return registrationPromise;
+  registrationPromise = (async () => {
+    try {
+      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';
 
@@ -513,43 +516,57 @@ const aliases = ${serialisedAliases};
 
 export async function resolve(specifier, context, nextResolve) {
   for (const alias of Object.keys(aliases)) {
-    if (specifier === alias || specifier.startsWith(alias + '/')) {
+    if (alias.endsWith('/*')) {
+      const baseAlias = alias.slice(0, -2);
+      if (specifier.startsWith(baseAlias + '/')) {
+        const baseTarget = aliases[alias].slice(0, -2);
+        const subPath = specifier.slice(baseAlias.length + 1);
+        const resolvedPath = path.resolve(baseTarget, subPath);
+        return nextResolve(pathToFileURL(resolvedPath).href, context);
+      }
+    } else if (specifier === alias) {
       const target = aliases[alias];
-      const resolvedPath = specifier.replace(alias, target);
-      return nextResolve(pathToFileURL(path.resolve(resolvedPath)).href, context);
+      return nextResolve(pathToFileURL(path.resolve(target)).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
+      const dataUrl = `data:text/javascript,${encodeURIComponent(loaderCode)}`;
+      const parentUrl = import.meta.url;
+      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)
       });
+    } finally {
+      registrationPromise = null;
     }
-  } catch (err) {
-    log.warn("ESM alias hook registration threw an unexpected error \u2014 aliases may not resolve at runtime", {
-      error: err?.message ?? String(err)
-    });
-  }
+  })();
+  return registrationPromise;
 }
 
 // src/aliases/cache.ts
-var aliasCache = {};
+var globalAliasCache = {};
 function updateAliasCache(aliases) {
-  aliasCache = { ...aliases };
+  globalAliasCache = { ...aliases };
 }
 function getAliasCache() {
-  return aliasCache;
+  const activeRegistry = registryContext.getStore();
+  if (activeRegistry) {
+    return activeRegistry.getAllAliases();
+  }
+  return globalAliasCache;
 }
 
 // src/bootstrap/createApp.ts
@@ -585,6 +602,9 @@ async function createApp(app, options = {}) {
     try {
       const config = await loadConfig(options);
       const log = createLogger(config.logger, config.logLevel);
+      if (config.domains || config.shared) {
+        log.warn("Infrastructure (domains/shared) is not yet supported in v1.2.x. These keys in configuration will be ignored until v2.0.0.");
+      }
       log.info("Bootstrap started", {
         modules: pc2.cyan(config.modules),
         prefix: pc2.cyan(config.prefix || "(none)"),
@@ -623,14 +643,16 @@ async function createApp(app, options = {}) {
         for (const mod of resolvedModules) {
           const modName = path8.basename(mod.dirPath);
           const aliasKey = `@modules/${modName}`;
-          pureModuleAliases[aliasKey] = mod.dirPath;
-          registry.registerAlias(aliasKey, mod.dirPath);
+          pureModuleAliases[aliasKey] = mod.indexPath;
+          pureModuleAliases[`${aliasKey}/*`] = `${mod.dirPath}/*`;
+          registry.registerAlias(aliasKey, mod.indexPath);
+          registry.registerAlias(`${aliasKey}/*`, `${mod.dirPath}/*`);
         }
-        activateAliasResolver(pureModuleAliases, config.aliases, log);
+        await activateAliasResolver(pureModuleAliases, config.aliases, log);
         updateAliasCache(registry.getAllAliases());
       }
       for (const mod of resolvedModules) {
-        const imported = await import(pathToFileURL3(mod.indexPath).href);
+        const imported = await import(pathToFileURL2(mod.indexPath).href);
         const allRegistered = registry.getAllModules();
         const registeredMod = allRegistered.find((m) => path8.normalize(m.path) === path8.normalize(mod.dirPath));
         if (!registeredMod) {
@@ -712,7 +734,7 @@ async function createApp(app, options = {}) {
           file = path8.normalize(file);
           let imported;
           try {
-            imported = await import(pathToFileURL3(file).href);
+            imported = await import(pathToFileURL2(file).href);
           } catch (err) {
             throw new NodulusError(
               "INVALID_CONTROLLER",
@@ -867,7 +889,6 @@ async function getAliases(options = {}) {
 }
 export {
   Controller,
-  ERROR_MESSAGES,
   Module,
   NodulusError,
   Repository,