Default root_module = "ignore"

python/tach/cli.py

@@ -1183,12 +1183,24 @@ def main() -> None:
         print_no_config_found()
         sys.exit(1)
 
+    # Deprecation warnings
     if project_config.use_regex_matching:
         print(
             f"{BCOLORS.WARNING}WARNING: regex matching for exclude paths is deprecated. "
             + f"Update your exclude paths in {CONFIG_FILE_NAME}.toml to use glob patterns instead, and remove the 'use_regex_matching' setting.{BCOLORS.ENDC}"
             + "\n"
         )
+    if (
+        project_config.root_module == "ignore"
+        and project_config.has_root_module_reference()
+    ):
+        print(
+            f"{BCOLORS.WARNING}WARNING: root module treatment is set to 'ignore' (default as of 0.23.0), but '<root>' appears in your configuration."
+            + f"\n\nRun '{TOOL_NAME} sync' to remove the root module from your dependencies,"
+            + f" or update 'root_module' in {CONFIG_FILE_NAME}.toml to 'allow' or 'forbid' instead."
+            + f"\nDocumentation: https://docs.gauge.sh/usage/configuration#the-root-module{BCOLORS.ENDC}"
+            + "\n"
+        )
 
     # Exclude paths on the CLI extend those from the project config
     try:

python/tach/extension.pyi

@@ -147,6 +147,8 @@ class UnusedDependencies:
 
 RuleSetting = Literal["error", "warn", "off"]
 
+RootModuleTreatment = Literal["allow", "ignore", "dependenciesonly", "forbid"]
+
 class RulesConfig:
     unused_ignore_directives: RuleSetting
     require_ignore_directive_reasons: RuleSetting
@@ -163,12 +165,14 @@ class ProjectConfig:
     forbid_circular_dependencies: bool
     use_regex_matching: bool
     rules: RulesConfig
+    root_module: RootModuleTreatment
 
     def __new__(cls) -> ProjectConfig: ...
     def serialize_json(self) -> str: ...
     def set_location(self, location: Path) -> None: ...
     def has_no_modules(self) -> bool: ...
     def has_no_dependencies(self) -> bool: ...
+    def has_root_module_reference(self) -> bool: ...
     def module_paths(self) -> list[str]: ...
     def utility_paths(self) -> list[str]: ...
     def create_module(self, path: str) -> None: ...

python/tests/example/valid/tach.toml

@@ -9,6 +9,7 @@ exclude = [
 
 exact = true
 forbid_circular_dependencies = true
+root_module = "allow"
 
 [[modules]]
 path = "domain_one"

src/config/project.rs

@@ -470,6 +470,17 @@ impl ProjectConfig {
         })
     }
 
+    pub fn has_root_module_reference(&self) -> bool {
+        self.all_modules().any(|module| {
+            module.path == "<root>"
+                || module
+                    .depends_on
+                    .as_ref()
+                    .map(|deps| deps.iter().any(|dep| dep.path == "<root>"))
+                    .unwrap_or(false)
+        })
+    }
+
     pub fn module_paths(&self) -> Vec<String> {
         self.all_modules()
             .map(|module| module.path.clone())

src/config/root_module.rs

@@ -6,9 +6,9 @@ pub const ROOT_MODULE_SENTINEL_TAG: &str = "<root>";
 #[derive(Debug, Serialize, Default, Deserialize, Clone, PartialEq)]
 #[serde(rename_all = "lowercase")]
 pub enum RootModuleTreatment {
-    #[default]
     Allow,
     Forbid,
+    #[default]
     Ignore,
     DependenciesOnly,
 }