@vlynk-studios/nodulus-core 1.2.0 → 1.2.5

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.5] - 2026-04-11
+
+### Added
+- **Configurable NITS Registry**: The NITS registry path is now configurable via `nits.registryPath` in `nodulus.config.ts` (defaults to `.nodulus/registry.json`).
+- **Internal Compatibility Layer**: Prepared core structures for upcoming v1.3.0 and v2.0.0 features (Domains, Shared Layouts, and Submodules).
+- **Public Registration Types**: Exported `ModuleRegistration` and `FeatureRegistration` types for enhanced framework integrations and tooling.
+- **NITS Identity Tracking**: Nodulus 1.2.5+ includes the **NITS (Nodulus Integrated Tracking System)**, which assigns a stable, unique ID to every module.
+
+### Changed
+- **Encapsulated Public API**: Refactored `src/index.ts` to use explicit named exports, hiding internal registry logic and internal types from the public surface.
+- **Express v5 Alignment**: Updated `peerDependencies` to require `express >= 5.0.0`, enforcing compatibility with the project's native Express 5 types.
+- **ESM Hook Cleanup**: Removed legacy `__filename` checks in the alias resolver, optimizing for a pure ESM environment.
+- **CI/CD Stability**: Updated root `package.json` scripts (`build`, `test`, `typecheck`) with `--if-present` to prevent build failures when some workspaces lack these scripts.
+- **CLI Robustness**: Centralized CLI error handling in `cli/index.ts`, removing direct `process.exit()` calls to improve testability and reliability.
+- **Type Safety**: Eliminated `any` types in `ast-parser.ts` and `resolver.ts`, transitioning to strict `estree` and `node` types.
+- **Async I/O Migration**: Refactored `sync-tsconfig` and identifier parsers to use asynchronous file operations for non-blocking execution.
+- **ESM Hook Stability**: Implemented a singleton promise pattern in the ESM alias resolver to prevent race conditions during concurrent activations.
+
+### Fixed
+- **Phantom Types Elimination**: Removed the legacy `types/` directory and corrected `tsconfig.json` to prevent re-generation of invalid type definitions.
+- **Alias Resolution Consistency**: Resolved a major discrepancy where `@modules/*` aliases resolved differently in runtime vs `tsconfig.json`. Now both use consistent dual-mapping (index file + directory wildcard).
+- **Custom Alias Precision**: Fixed a bug where wildcard suffixes (`/*`) were incorrectly forced on aliases pointing to single files instead of directories.
+- **Unimplemented Feature Warnings**: Added helpful warnings when detected configuration keys (`domains`, `shared`) that are not yet natively supported in the v1.x branch.
+- **CLI Precision**: Fixed a bug in the global error handler where exit code `0` was shadowed by `1`.
+- **Parsing Resilience**: Resolved a syntax error in the `check` command that caused failures during bulk analysis.
+- **Isolated Alias Logic**: Extracted tsconfig path generation into a pure utility function.
+
 ## [1.2.0] - 2026-04-09
 
 ### Added

package/README.md

@@ -104,6 +104,8 @@ createApp(app: Application, options?: CreateAppOptions): Promise<NodulusApp>
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `modules` | `string` | `'src/modules/*'` | Glob pointing to module folders |
+| `domains` | `string` | `undefined` | Glob pointing to domain folders (v2.0.0+) |
+| `shared` | `string` | `undefined` | Glob pointing to shared global folders (v2.0.0+) |
 | `prefix` | `string` | `''` | Global route prefix (e.g. `'/api/v1'`) |
 | `aliases` | `Record<string, string>` | `{}` | Folder aliases beyond the auto-generated `@modules/*` |
 | `strict` | `boolean` | `true` in dev | Enables circular-dependency detection and undeclared-import errors |
@@ -299,6 +301,9 @@ const config: NodulusConfig = {
     '@middleware': './src/middleware',
     '@shared':     './src/shared',
   },
+  nits: {
+    registryPath: './.nodulus/registry.json'
+  }
 }
 
 export default config
@@ -385,6 +390,24 @@ Nodulus Architecture Analysis
 
 ---
 
+### NITS Identity Tracking
+
+Nodulus 1.2.5+ includes the **NITS (Nodulus Integrated Tracking System)**, which assigns a stable, unique ID to every module.
+ This allows the framework to track modules even when they are renamed or moved across the filesystem, preventing identity loss during refactors.
+
+NITS maintains a state file at `.nodulus/registry.json` in your project root. **This file should be committed to version control.**
+
+#### Resolving Merge Conflicts
+
+Because `registry.json` tracks project-level state, parallel branches might occasionally result in Git merge conflicts. To resolve them:
+
+1.  **Accept either side** (or both) of the conflict to make the JSON valid again.
+2.  Run `npx nodulus check`.
+3.  The NITS reconciler will automatically detect duplicate IDs or path shifts, "heal" the registry, and save the corrected state.
+4.  Commit the updated `.nodulus/registry.json`.
+
+---
+
 ## Logging
 
 Nodulus emits structured, color-coded log events throughout the bootstrap pipeline using [picocolors](https://github.com/alexeyraspopov/picocolors).
@@ -543,6 +566,8 @@ import type {
   RegisteredModule,
   MountedRoute,
   GetAliasesOptions,
+  ModuleRegistration,
+  FeatureRegistration,
   LogLevel,
   LogHandler,
 } from '@vlynk-studios/nodulus-core'