@vlynk-studios/nodulus-core 1.1.0 → 1.2.5

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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
+- **CLI Command `check`**: Added static code analysis to enforce boundaries via fast AST parsing (`acorn`). Uncovers architectural violations before loading.
+- **Rule Detection Mechanisms**: Captures circular dependencies, deep private imports, and undeclared external imports between modules.
+- **CI/CD Integration Tools**: `--strict` mode forcing process exits on rule breakage and `--format json` payload schema reports.
+
 ## [1.1.0] - 2026-04-08
 
 ### Changed

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
@@ -356,6 +361,51 @@ Added paths:
 
 Run this command initially, and whenever you create, rename, or drop modules in the project. It behaves idempotently and automatically purges references to modules that were deleted.
 
+### `nodulus check`
+
+Performs static code architecture analysis by inspecting raw Abstract Syntax Trees (AST) across your module structures without mutating or evaluating your application code.
+
+```bash
+npx nodulus check
+```
+
+```text
+Nodulus Architecture Analysis
+
+✔ orders — OK
+✗ payments — 2 problem(s)
+  WARN  Private import detected: module "payments" directly imports internal path from "@modules/users/users.repository.js". (payments.service.ts:3)
+       Suggestion: Import only the public index: "@modules/users".
+✔ users — OK
+
+2 problem(s) found.
+```
+
+| Option                 | Description                                                                              |
+|------------------------|------------------------------------------------------------------------------------------|
+| `--strict`             | Gracefully halts pipelines (`exit 1`) if architectural violations are mapped. Ideal for CI/CD gates. |
+| `--module <name>` | Narrow the analysis exclusively to a specific module scope within your system.           |
+| `--format <json,text>` | Exposes structural violations as digestible JSON payloads for external pipelines.        |
+| `--no-circular`        | Disables heavy Depth-First Search cycle logic detections (`A → B → A`).             |
+
+---
+
+### 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
@@ -516,6 +566,8 @@ import type {
   RegisteredModule,
   MountedRoute,
   GetAliasesOptions,
+  ModuleRegistration,
+  FeatureRegistration,
   LogLevel,
   LogHandler,
 } from '@vlynk-studios/nodulus-core'