ModuleManager

ModuleManager is a VS Code extension for organizing Java code into independent modules with explicit dependencies and flexible project templates.

⚠️ Early Development — Use With Caution

This extension is under active development and may contain bugs or breaking changes.

Always use it inside a VS Code workspace folder. The extension moves project directories on disk when creating or reorganizing modules. Running it outside a workspace — or pointing it at a standalone folder that is not part of an open workspace — can result in unexpected file moves that are difficult to undo. Back up your work before use, and do not run it against any directory you cannot afford to lose or restore from version control.

Overview

• Creates basic Java modules with customizable project structure using built-in or custom templates.
• Stores module definitions in .module.json.
• Keeps modules isolated unless a dependency is explicitly declared.
• Syncs Eclipse metadata (.project, .classpath) from module descriptors automatically.
• Rejects module creation when the target directory already exists to prevent destructive rollback on pre-existing folders.
• Validates cross-module Java imports in real time — undeclared imports are flagged as diagnostics and a compile-blocking Java file is generated to enforce the dependency contract at build time.
• Detects and blocks circular dependencies when adding module dependencies.
• Updates workspace Java settings based on discovered module types (managed referenced library patterns for modules).
• Uses safe JSON-with-comments parsing for descriptors/settings and skips settings writes if .vscode/settings.json cannot be parsed as a JSON object.
• Automatically triggers a Java project reload (java.reloadProjects / java.cleanWorkspace) after syncing, with a 15-second cache to avoid hammering the Java extension.

Quick Start

1. Open a workspace folder in VS Code.
2. In Explorer, right-click and run Create Module, or open the Command Palette (Ctrl+Shift+P) and type Create Module.
3. Enter a module name.
4. Choose a project template from the template picker — browse built-in templates (Standard Maven, Spring Boot, Clean Architecture, etc.) or create a custom template.
5. Add dependencies only when needed — modules are fully isolated by default.

Each module gets its own .module.json, and metadata is synchronized automatically.

Module Structure

Modules are created with a flexible folder structure based on the selected template. Example (Standard Maven layout):

ModuleName/
  .module.json              ← Module descriptor (hidden in Explorer)
  .project                  ← Eclipse project metadata
  .classpath                ← Eclipse classpath metadata
  src/main/java/            ← Source code
  src/main/resources/       ← Configuration and assets
  src/test/java/            ← Tests
  src/test/resources/       ← Test fixtures
  README.md

The actual folder structure depends on the chosen template (Standard Maven, Spring Boot, Hexagonal Architecture, etc.).

Module Types

Maven and Gradle module types are coming soon.

Template System

ModuleManager provides a flexible template system for module structure. When creating a module, choose from:

Built-in Templates:

• Standard Maven — Classic Maven project layout. Default for any Java module.
• Spring Boot — Layered architecture: controller → service → repository → model.
• Database / Data Access — Specialized for database modules with DAO, DTO, mapper, etc.
• Microservice — API, domain, application, and infrastructure layers.
• Hexagonal Architecture — Ports & Adapters pattern with isolated domain.
• Clean Architecture — Uncle Bob's layered approach: presentation → domain → data.
• Library / Utility — Reusable library with clean public API.
• Event-Driven — Focused on events, handlers, publishers, and subscribers.
• Batch Processing — Spring Batch style with jobs, steps, readers, writers.
• Simple / Flat — Minimal flat structure for small scripts or prototypes.

Custom Templates:

• Create, edit, and manage your own templates for team-specific architectures.
• Starred templates appear in the favorites section for quick access.
• Recently used templates are tracked for convenience.

Dependency Model

• No declared dependency: cross-module imports are treated as violations. A diagnostic error is raised on the import line, and a compile-blocking Java file is generated inside the offending module.
• Declared dependency: imports are allowed and Eclipse metadata (.classpath, .project) is updated accordingly.
• Circular dependencies: blocked at the point of adding a dependency — a DFS graph check is run before committing.

Example descriptor:

{
  "name": "orders",
  "type": "basic",
  "createdAt": "2026-04-13T12:00:00.000Z",
  "dependencies": ["billing"]
}

Commands

Dependency Enforcement

When a Java file imports a class from a module that is not declared as a dependency, the extension:

1. Raises a VS Code diagnostic error on the import line.
2. Generates src/main/java/modulemanager/generated/ModuleManagerDependencyViolationBlocker.java with an intentional type mismatch, causing Java compilation to fail until the violation is resolved.

This runs on a 350 ms debounce whenever a .java or .module.json file is opened, changed, or saved.

Eclipse Metadata Sync

For basic modules, .project and .classpath XML are fully managed and regenerated from .module.json. Project names follow the pattern modulemanager.<relative.dotted.path>.

Requirements

• VS Code >= 1.104.0
• Node.js >= 16.x
• Java extension (Extension Pack for Java or Language Support for Java)

Contributing

See CONTRIBUTING.md to build and run the extension locally.

Author

[Danielitorc4]