name: module-dependencies description: How to manage module dependencies in IntelliJ codebase. Use when adding or modifying module dependencies in iml files.

Module Dependencies Management

This document describes how to manage module dependencies when working with IntelliJ IDEA codebase.

Documentation

Modularization Overview - Module organization principles:
Project Structure - Naming conventions, Kotlin usage, dependencies

Build System Overview

The repository uses a hybrid build system:

JPS (*.iml files): Source of truth for module dependencies
Bazel (BUILD files): Auto-generated from *.iml files
Generator: run build/jpsModelToBazel.cmd after changing .iml files

Running the IML-to-Bazel Generator

To manually run the converter that generates Bazel BUILD files from .iml files:

./build/jpsModelToBazel.cmd

This is useful when:

The automatic converter didn't run (e.g., .iml files were modified outside the IDE)
You need to regenerate BUILD files after git operations
Troubleshooting build system synchronization issues

BUILD.bazel Auto-Generated Sections

BUILD.bazel files have auto-generated sections marked with comments:

### auto-generated section `build module.name` start
... generated content ...
### auto-generated section `build module.name` end
 
### auto-generated section `test module.name` start
... generated content ...
### auto-generated section `test module.name` end

Key rules:

Content inside auto-generated sections is overwritten by the generator
Content outside auto-generated sections is preserved during regeneration

Skip Generation Marker

To prevent auto-generation of a section (so you can provide custom content):

### skip generation section `test module.name`

Example - Custom test target with preserved content:

load("@community//build:tests-options.bzl", "jps_test")
 
# Custom test target (before auto-generated sections)
jps_test(
  name = "my-tests_test",
  runtime_deps = [
    ":my-tests_test_lib",
    "//:main_test_lib",
  ],
)
 
### skip generation section `test my.module.name`
 
### auto-generated section `build my.module.name` start
... (let generator handle the build section)

Important Notes

⚠️ DO NOT manually edit .iml files via JetBrains MCP - The IDE's automatic converter runs concurrently and can interfere with edits.

When you need to fix missing dependencies:

Use the standard Edit tool (not mcp__jetbrains__replace_text_in_file) for .iml files
The converter will automatically update BUILD.bazel files
Verify compilation with ./bazel-build-all.cmd