ryo_executor/engine/

registry_generator.rs

//! RegistryGenerator - Generate source files from ASTRegistry + SymbolRegistry
//!
//! This generator works purely from SymbolPath, without requiring existing files
//! or span information. File paths are derived from SymbolPath hierarchy.
//!
//! # Responsibility Boundary
//!
//! `RegistryGenerator` is responsible **only** for:
//! - Deriving module structure from SymbolPath hierarchy
//! - Generating valid Rust source code for each module
//! - Outputting **crate-relative paths** (e.g., `"src/lib.rs"`, `"src/models.rs"`)
//!
//! It is **NOT** responsible for:
//! - Knowing workspace layout (e.g., `"crates/core/src/lib.rs"`)
//! - Converting to `WorkspaceFilePath`
//! - Writing files to disk
//!
//! The caller (typically `BlueprintExecutor::sync_files_and_rebuild`) handles
//! the conversion from crate-relative paths to workspace-relative paths by
//! consulting existing file metadata.
//!
//! # Design
//!
//! ```text
//! ASTRegistry + SymbolRegistry
//!         ↓
//!   Group by SymbolPath.crate_name()
//!         ↓
//!   Build module hierarchy from SymbolPath
//!         ↓
//!   Generate PureFile per module
//!         ↓
//!   Output: GeneratedWorkspace
//!     - crate_name: "core"
//!     - files: {"src/lib.rs" → source, "src/models.rs" → source, ...}
//! ```
//!
//! # Example
//!
//! ```ignore
//! let generator = RegistryGenerator::multi_file();
//! let workspace = generator.generate(&ast_registry, &symbol_registry);
//!
//! // workspace.crates["core"].files contains:
//! // - "src/lib.rs" → "pub struct Config { ... }"
//! // - "src/models.rs" → "pub struct User { ... }"
//!
//! // The caller then converts these to WorkspaceFilePath:
//! // - "crates/core/src/lib.rs"
//! // - "crates/core/src/models.rs"
//! ```

use ryo_analysis::{ASTRegistry, CodeGraphV2, SymbolId, SymbolKind};
use ryo_source::pure::ModScope;
use ryo_source::pure::{PureAttribute, PureFile, PureItem, PureMod, PureVis, ToSynError};
use ryo_symbol::{CrateName, SymbolPath, SymbolRegistry};
use std::collections::{BTreeMap, HashMap, HashSet};

/// Key type for module symbol attributes map: `(crate_name, mod_path_segments, is_public)`
type ModSymbolKey = (String, Vec<String>, bool);

/// Value type for module symbol attributes map: `(is_inline, attributes)`
type ModSymbolValue = (bool, Vec<PureAttribute>);

/// Key for grouping symbols by crate: `(crate_name, is_main)`
type CrateKey = (String, bool);

/// Symbol entry for generation: `(symbol_id, symbol_path, pure_item)`
type SymbolEntry = (SymbolId, SymbolPath, PureItem);

/// Options for multi-file generation.
struct MultiFileOpts<'a> {
    /// If true, root file is `src/main.rs`, otherwise `src/lib.rs`
    is_main: bool,
    /// Module-level use items keyed by `(crate, segments, is_main)`
    module_use_items: &'a HashMap<ModSymbolKey, Vec<PureItem>>,
    /// Module symbol entries (empty modules)
    mod_symbols: &'a HashMap<ModSymbolKey, ModSymbolValue>,
    /// Fully-qualified paths of inline modules
    inline_module_paths: &'a HashSet<String>,
    /// When `Some`, only these file keys are serialized to output
    affected_file_keys: Option<&'a HashSet<String>>,
}

/// Result of generation for a single crate.
///
/// Contains generated source files keyed by **crate-relative paths**
/// (e.g., `"src/lib.rs"`, `"src/models.rs"`), not workspace-relative paths.
#[derive(Debug, Clone)]
pub struct GeneratedCrate {
    /// Crate name (e.g., `"core"`, `"app"`)
    pub crate_name: String,

    /// Generated files: crate-relative path → generated file
    ///
    /// Keys are paths relative to the crate root, such as:
    /// - `"src/lib.rs"` (library entry point)
    /// - `"src/main.rs"` (binary entry point)
    /// - `"src/models.rs"` (submodule)
    /// - `"src/models/user.rs"` (nested submodule)
    ///
    /// **Note**: These are NOT workspace-relative paths. The caller must
    /// prepend the crate's root directory (e.g., `"crates/core"`) to get
    /// the full workspace path.
    pub files: HashMap<String, GeneratedFile>,
}

/// A single generated file.
#[derive(Debug, Clone)]
pub struct GeneratedFile {
    /// The generated source code as a string
    pub source: String,
    /// The PureFile AST representation (useful for diff comparison)
    pub pure_file: PureFile,
}

/// Result of multi-crate workspace generation.
///
/// Contains all generated crates, keyed by crate name.
///
/// # Path Convention
///
/// All file paths within this structure are **crate-relative**, not workspace-relative.
/// For example, a workspace with structure:
///
/// ```text
/// workspace/
/// ├── Cargo.toml
/// └── crates/
///     ├── core/
///     │   └── src/lib.rs
///     └── app/
///         └── src/main.rs
/// ```
///
/// Would produce:
/// - `crates["core"].files["src/lib.rs"]`
/// - `crates["app"].files["src/main.rs"]`
///
/// The caller is responsible for combining these with crate root paths
/// to produce workspace-relative paths like `"crates/core/src/lib.rs"`.
#[derive(Debug, Clone, Default)]
pub struct GeneratedWorkspace {
    /// Map of crate_name → GeneratedCrate
    pub crates: HashMap<String, GeneratedCrate>,
}

impl GeneratedWorkspace {
    /// Get total file count across all crates.
    pub fn total_files(&self) -> usize {
        self.crates.values().map(|c| c.files.len()).sum()
    }

    /// Iterate all files with full paths.
    pub fn iter_files(&self) -> impl Iterator<Item = (&str, &str, &GeneratedFile)> {
        self.crates.iter().flat_map(|(crate_name, crate_data)| {
            crate_data
                .files
                .iter()
                .map(move |(path, file)| (crate_name.as_str(), path.as_str(), file))
        })
    }
}

/// Generator that creates source files from ASTRegistry + SymbolRegistry.
///
/// Derives file structure purely from SymbolPath hierarchy - no existing files
/// or span information required. This enables:
/// - Fresh file generation from scratch
/// - Module addition/removal without span manipulation
/// - Consistent output regardless of original file layout
///
/// # Output Format
///
/// The generator outputs `GeneratedWorkspace` containing **crate-relative paths**
/// (e.g., `"src/lib.rs"`). It does NOT handle workspace layout concerns like
/// where each crate lives within the workspace (e.g., `"crates/core/src/lib.rs"`).
///
/// # Generation Modes
///
/// - **Single-file mode** (`single_file()`): All symbols in one file with nested `mod { }` blocks
/// - **Multi-file mode** (`multi_file()`): Each module gets its own `.rs` file
/// - **Multi-file mod.rs** (`multi_file_mod_rs()`): Legacy `mod.rs` style instead of `module.rs`
///
/// # Example
///
/// ```ignore
/// let generator = RegistryGenerator::multi_file();
/// let workspace = generator.generate(&ast_registry, &symbol_registry);
///
/// // For symbols: core::Config, core::models::User
/// // Output: {"src/lib.rs": "...", "src/models.rs": "..."}
/// ```
#[derive(Debug, Clone, Default)]
pub struct RegistryGenerator {
    /// Generate single file with nested mods (true) or multi-file (false)
    pub single_file: bool,
    /// Use mod.rs style (legacy) vs module.rs style (modern) for multi-file
    pub use_mod_rs: bool,
    /// Per-crate existing file keys (crate-relative paths) used to respect
    /// on-disk module layout (`<mod>/mod.rs` vs flat `<mod>.rs`).
    ///
    /// Keyed by `CrateName` so that `ryo-executor`'s `executor/mod.rs` does NOT
    /// pollute the lookup for `ryo-agent`'s flat `executor.rs` — the core fix
    /// for cross-crate mod-ambiguity contamination observed at scale (RL061).
    ///
    /// Populated by [`with_existing_files_per_crate`]; absent crates fall back
    /// to [`existing_file_keys_workspace_wide`].
    existing_file_keys_per_crate: HashMap<CrateName, HashSet<String>>,
    /// Workspace-wide fallback set populated by the legacy
    /// [`with_existing_files`] API for callers that do not distinguish between
    /// crates (unit tests / single-crate workspaces).
    existing_file_keys_workspace_wide: HashSet<String>,
    /// Whitelist of crates that own a `src/lib.rs` on disk. When populated,
    /// the generator declines to emit a lib-style root file (`src/lib.rs`)
    /// for `is_main = false` crates whose name is absent from this set.
    ///
    /// Populated by [`with_lib_crates`] from the caller's
    /// cargo-metadata-derived view. Binary-only crates (e.g. `ryo-cli`,
    /// `ryo-ui` in ryo-rs — `[[bin]]` with no `[lib]`) live OUTSIDE this
    /// set; ExtractTrait against a library impl no longer synthesises a
    /// `pub mod ...;` stub into those crates and the workspace cargo-check
    /// pass stops chasing phantom library targets. Empty set = legacy
    /// behaviour (no filtering), preserved for single-crate test
    /// contexts that never call [`with_lib_crates`].
    lib_crates: HashSet<CrateName>,
}

impl RegistryGenerator {
    /// Create a new generator with single-file output.
    pub fn single_file() -> Self {
        Self {
            single_file: true,
            use_mod_rs: false,
            existing_file_keys_per_crate: HashMap::new(),
            existing_file_keys_workspace_wide: HashSet::new(),
            lib_crates: HashSet::new(),
        }
    }

    /// Create a new generator with multi-file output (modern style).
    pub fn multi_file() -> Self {
        Self {
            single_file: false,
            use_mod_rs: false,
            existing_file_keys_per_crate: HashMap::new(),
            existing_file_keys_workspace_wide: HashSet::new(),
            lib_crates: HashSet::new(),
        }
    }

    /// Create a new generator with multi-file output (mod.rs style).
    pub fn multi_file_mod_rs() -> Self {
        Self {
            single_file: false,
            use_mod_rs: true,
            existing_file_keys_per_crate: HashMap::new(),
            existing_file_keys_workspace_wide: HashSet::new(),
            lib_crates: HashSet::new(),
        }
    }

    /// Provide existing crate-relative file paths as a **workspace-wide
    /// fallback**.
    ///
    /// All crates see this same set when no per-crate entry is present.
    /// Preserved as the original API for backward compatibility and for
    /// callers (unit tests / single-crate workspaces) that do not need
    /// per-crate isolation. Multi-crate production code should prefer
    /// [`with_existing_files_per_crate`].
    pub fn with_existing_files<I>(mut self, paths: I) -> Self
    where
        I: IntoIterator,
        I::Item: Into<String>,
    {
        self.existing_file_keys_workspace_wide = paths.into_iter().map(Into::into).collect();
        self
    }

    /// Declare which crates own a `src/lib.rs` on disk.
    ///
    /// When this set is non-empty, [`generate_internal`] will silently drop
    /// any `is_main = false` crate that is NOT a member — preventing the
    /// generator from synthesising a phantom `src/lib.rs` for binary-only
    /// crates. The defensive guard previously living in
    /// `BlueprintExecutor::sync_files_and_rebuild` (`f42eb504`) becomes
    /// redundant once this whitelist is supplied: the generator simply
    /// never produces the offending file.
    ///
    /// Leave the set empty (the default) to retain the legacy behaviour —
    /// every crate the symbol registry knows about is emitted with a
    /// lib-style root unless its symbols carry the `main::` prefix.
    pub fn with_lib_crates(mut self, crates: HashSet<CrateName>) -> Self {
        self.lib_crates = crates;
        self
    }

    /// Provide per-crate existing file path sets.
    ///
    /// Preferred API for multi-crate workspaces. Each crate sees only its own
    /// key set, preventing `<crate_A>/mod.rs` entries from leaking into the
    /// layout decision for `<crate_B>` (RL061 fix).
    ///
    /// Crates absent from `map` fall back to the workspace-wide set populated
    /// by [`with_existing_files`].
    pub fn with_existing_files_per_crate(
        mut self,
        map: HashMap<CrateName, HashSet<String>>,
    ) -> Self {
        self.existing_file_keys_per_crate = map;
        self
    }

    /// Look up the effective existing-file key set for a crate.
    ///
    /// Returns the per-crate set when available, falling back to the
    /// workspace-wide set.
    fn existing_keys_for_crate(&self, crate_name: Option<&CrateName>) -> &HashSet<String> {
        if let Some(name) = crate_name {
            if let Some(set) = self.existing_file_keys_per_crate.get(name) {
                return set;
            }
        }
        &self.existing_file_keys_workspace_wide
    }

    /// Generate source files from registries.
    ///
    /// Handles both library symbols (`crate::Foo`) and binary symbols (`main::crate::Foo`).
    /// Binary symbols are output to `src/main.rs` while library symbols go to `src/lib.rs`.
    pub fn generate(
        &self,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Result<GeneratedWorkspace, ToSynError> {
        self.generate_internal(ast_registry, symbol_registry, None, None)
    }

    /// Internal generation with optional file-level filter.
    ///
    /// When `affected_file_keys` is `Some`, only files whose crate-relative path
    /// (e.g. "src/models.rs") is in the set will be serialized via `to_source()`.
    /// This avoids the expensive prettyplease formatting for unmodified files.
    ///
    /// When `None`, all files are generated (full generation mode).
    fn generate_internal(
        &self,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
        affected_file_keys: Option<&HashSet<String>>,
        affected_crates: Option<&HashSet<CrateName>>,
    ) -> Result<GeneratedWorkspace, ToSynError> {
        // First pass: identify all inline module paths
        // Inline modules are marked during initial parsing in ASTRegistry.
        // Items inside inline modules should NOT be added separately to the symbol list
        // because they are already contained in the PureMod.items field.
        let mut inline_module_paths: HashSet<String> = HashSet::new();
        for id in ast_registry.inline_module_ids() {
            if let Some(path) = symbol_registry.path(id) {
                inline_module_paths.insert(path.to_string());
            }
        }

        // Group symbols by crate, separating lib and main symbols
        // Key: (crate_name, is_main)
        let mut crates: HashMap<CrateKey, Vec<SymbolEntry>> = HashMap::new();

        for (id, item) in ast_registry.iter() {
            // Skip impl blocks, methods, and fields - they're associated items
            // handled separately from module_items and should not create module tree entries.
            // Fields can leak here due to name collisions between struct fields and impl methods
            // (e.g., `Type::field_name` path shared by both), where re-registration changes
            // the kind from Method to Field while the PureItem remains Fn.
            let kind = symbol_registry.kind(id);
            if matches!(
                kind,
                Some(SymbolKind::Impl | SymbolKind::Method | SymbolKind::Field)
            ) {
                continue;
            }

            if let Some(path) = symbol_registry.path(id) {
                // Skip associated items inside impl blocks (e.g., type Context, type Error)
                // These have paths like "module::<impl Trait for Type>::ItemName"
                if path.segments().any(|s| s.starts_with("<impl ")) {
                    continue;
                }

                // Skip items that are children of inline modules.
                // Inline modules contain their items in PureMod.items, so we don't need
                // to add child items separately - they would create duplicate entries.
                let path_str = path.to_string();
                let is_child_of_inline = inline_module_paths.iter().any(|inline_path| {
                    // Check if this item's path is a child of an inline module
                    // Must check for :: separator to avoid false positives
                    // e.g., "crate::testing" should NOT match "crate::test"
                    let prefix_with_sep = format!("{}::", inline_path);
                    path_str.starts_with(&prefix_with_sep)
                });
                if is_child_of_inline {
                    continue;
                }

                let (crate_name, is_main) = if path.is_main_symbol() {
                    // main::my_crate::Foo -> crate_name = "my_crate", is_main = true
                    (
                        path.main_target_crate()
                            .unwrap_or(path.crate_name())
                            .to_string(),
                        true,
                    )
                } else {
                    // my_crate::Foo -> crate_name = "my_crate", is_main = false
                    (path.crate_name().to_string(), false)
                };

                crates.entry((crate_name, is_main)).or_default().push((
                    id,
                    path.clone(),
                    item.clone(),
                ));
            }
        }

        // Collect module_items (use statements, etc.) by module path
        // Key: (crate_name, module_path_segments, is_main)
        let mut module_use_items: HashMap<ModSymbolKey, Vec<PureItem>> = HashMap::new();

        for (module_id, items) in ast_registry.iter_module_items() {
            tracing::debug!(
                "iter_module_items: module_id={:?}, items_count={}, has_use={}",
                module_id,
                items.len(),
                items.iter().any(|i| matches!(i, PureItem::Use(_)))
            );
            if let Some(path) = symbol_registry.path(module_id) {
                let (crate_name, is_main) = if path.is_main_symbol() {
                    (
                        path.main_target_crate()
                            .unwrap_or(path.crate_name())
                            .to_string(),
                        true,
                    )
                } else {
                    (path.crate_name().to_string(), false)
                };

                // Get module segments (path minus crate prefix)
                // Use mod_path() which correctly handles both lib and main symbols
                // Filter out impl block segments (e.g., "<impl Trait for Type>") which
                // should not create module hierarchy entries
                let segments: Vec<String> = path
                    .mod_path()
                    .iter()
                    .map(|s| s.name())
                    .filter(|name| !name.starts_with("<impl "))
                    .map(|s| s.to_string())
                    .collect();

                // Filter Use items and Impl blocks
                // New design: impl blocks are stored in module_items (file-level construct)
                // Other items in module_items are already in symbols and should be filtered
                let file_level_items: Vec<PureItem> = items
                    .iter()
                    .filter(|item| matches!(item, PureItem::Use(_) | PureItem::Impl(_)))
                    .cloned()
                    .collect();

                if !file_level_items.is_empty() {
                    tracing::debug!(
                        "Adding {} file_level_items to module_use_items for path={}, segments={:?}",
                        file_level_items.len(),
                        path,
                        segments
                    );
                    module_use_items
                        .entry((crate_name, segments, is_main))
                        .or_default()
                        .extend(file_level_items);
                }
            }
        }

        // Ensure crates exists for all modules with module_items (use statements)
        // This handles cases where a file has only use statements and no other symbols
        for (crate_name, segments, is_main) in module_use_items.keys() {
            if segments.is_empty() {
                // Root module (e.g., "crate") - ensure crate entry exists
                crates.entry((crate_name.clone(), *is_main)).or_default();
            }
        }

        // Collect Mod symbols from SymbolRegistry (for empty modules without child items)
        // Key: (crate_name, module_segments, is_main), Value: (is_pub, attrs)
        let mut mod_symbols: HashMap<ModSymbolKey, ModSymbolValue> = HashMap::new();
        for (id, path) in symbol_registry.iter() {
            let Some(kind) = symbol_registry.kind(id) else {
                continue;
            };
            if kind != SymbolKind::Mod {
                continue;
            }
            // Skip inline modules (marked via mark_inline_module)
            // These are already included in their parent file and will be output as-is
            // External modules (not marked) need visibility preserved even if items is non-empty
            if ast_registry.is_inline_module(id) {
                continue;
            }
            let mod_attrs = if let Some(PureItem::Mod(m)) = ast_registry.get(id) {
                m.attrs.clone()
            } else {
                Vec::new()
            };

            let segments: Vec<&str> = path.segments().collect();
            let (crate_name, is_main) = if path.is_main_symbol() {
                (
                    path.main_target_crate()
                        .unwrap_or(path.crate_name())
                        .to_string(),
                    true,
                )
            } else {
                (path.crate_name().to_string(), false)
            };

            // Handle crate root modules (e.g., "crate" or "main::crate")
            // Store with empty segments to set attrs on root tree node
            if segments.len() <= 1 || (path.is_main_symbol() && segments.len() <= 2) {
                // Crate root - store with empty segments for root node attrs
                mod_symbols.insert(
                    (crate_name.clone(), vec![], is_main),
                    (true, mod_attrs), // Crate root is always "pub" in a sense
                );
                crates.entry((crate_name, is_main)).or_default();
                continue;
            }

            // Module segments (path minus crate prefix)
            // Filter out impl block segments (shouldn't happen for Mod symbols, but defensive)
            let skip_count = if is_main { 2 } else { 1 };
            let module_segments: Vec<String> = segments[skip_count..]
                .iter()
                .filter(|s| !s.starts_with("<impl "))
                .map(|s| s.to_string())
                .collect();

            // Determine visibility from SymbolRegistry
            let is_pub = symbol_registry
                .visibility(id)
                .map(|v| matches!(v, ryo_symbol::Visibility::Public))
                .unwrap_or(false);

            mod_symbols.insert(
                (crate_name.clone(), module_segments, is_main),
                (is_pub, mod_attrs),
            );

            // Ensure crate entry exists
            crates.entry((crate_name, is_main)).or_default();
        }

        // Generate each crate (merge lib and main into same GeneratedCrate)
        let mut workspace = GeneratedWorkspace::default();

        for ((crate_name, is_main), symbols) in crates {
            // R2 guard: when `lib_crates` is non-empty (caller supplied a
            // cargo-metadata-derived whitelist) drop `is_main = false`
            // entries for crates that do NOT own a `src/lib.rs` on disk.
            // The generator otherwise synthesises a `pub mod ...;` stub
            // root for every workspace crate's lib-style symbol path,
            // including binary-only crates whose modules are reached
            // through `main.rs` (`ryo-cli`, `ryo-ui` in ryo-rs). That
            // phantom lib.rs is what `f42eb504`'s sync-side defensive
            // guard had to mask; with this filter the generator never
            // emits it in the first place.
            if !is_main && !self.lib_crates.is_empty() {
                if let Ok(name) = CrateName::new(crate_name.as_str()) {
                    if !self.lib_crates.contains(&name) {
                        continue;
                    }
                }
            }

            // R3 guard: when `affected_crates` is supplied (= caller is
            // `generate_affected` running an incremental mutation pass),
            // drop crates that no modified symbol touched. Without this
            // filter every workspace crate's lib.rs flows through the
            // sort/format pipeline even when the mutation lives entirely
            // inside one library, surfacing as cosmetic diff noise on
            // every cross-crate lib.rs in `rl061_tempfile_diff_observe`
            // post-`a638ee27` (9 lib.rs Modified for one impl change).
            if let Some(crates_filter) = affected_crates {
                if let Ok(name) = CrateName::new(crate_name.as_str()) {
                    if !crates_filter.contains(&name) {
                        continue;
                    }
                }
            }

            let entry = workspace
                .crates
                .entry(crate_name.clone())
                .or_insert_with(|| GeneratedCrate {
                    crate_name: crate_name.clone(),
                    files: HashMap::new(),
                });

            let generated_files = if self.single_file {
                self.generate_single_file_inner(
                    &crate_name,
                    symbols,
                    is_main,
                    &module_use_items,
                    &mod_symbols,
                )
            } else {
                self.generate_multi_file_inner(
                    &crate_name,
                    symbols,
                    MultiFileOpts {
                        is_main,
                        module_use_items: &module_use_items,
                        mod_symbols: &mod_symbols,
                        inline_module_paths: &inline_module_paths,
                        affected_file_keys,
                    },
                )
            };

            entry.files.extend(generated_files?);
        }

        Ok(workspace)
    }

    /// Generate only files affected by modified symbols.
    ///
    /// This method determines which files need regeneration based on the modified symbols
    /// and the generator's file layout strategy (CrateLayout-aware).
    ///
    /// # Strategy
    ///
    /// 1. Collect affected modules from modified symbols
    /// 2. Determine file paths based on CrateLayout (bin-only/lib/mixed)
    /// 3. Generate only the affected files
    ///
    /// # Arguments
    ///
    /// * `ast_registry` - The AST registry containing all symbols
    /// * `symbol_registry` - The symbol registry with path information
    /// * `modified_symbols` - SymbolIds that were modified during mutation
    /// * `metadata` - Cargo metadata for CrateInfo lookup
    ///
    /// # Returns
    ///
    /// A `GeneratedWorkspace` containing only the affected files with crate-relative paths.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let modified = vec![status_id, todo_item_id];
    /// let workspace = generator.generate_affected(
    ///     &ast_registry,
    ///     &symbol_registry,
    ///     &modified,
    ///     &metadata,
    /// );
    /// // workspace.crates["my_crate"].files contains only affected files
    /// ```
    /// Generate only files affected by modified symbols.
    ///
    /// Maps each modified SymbolId to its crate-relative file path, then runs
    /// the full organization phase (fast: HashMap grouping) but only serializes
    /// affected files via `to_source()` (expensive: prettyplease).
    ///
    /// # DESIGN INVARIANT
    ///
    /// **Full-workspace serialization is PROHIBITED.** Only files containing
    /// modified symbols may be serialized. This is critical because:
    ///
    /// 1. `to_source()` (prettyplease) is O(file_size) per file
    /// 2. Regenerating unmodified files causes format drift
    ///    (`vec![]` → `vec!()`, shorthand expansion, etc.)
    /// 3. Writing unmodified files wastes I/O and triggers re-indexing
    ///
    /// If `modified_symbols` is empty, returns an empty workspace immediately.
    pub fn generate_affected(
        &self,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
        modified_symbols: &[SymbolId],
        _metadata: &ryo_symbol::CargoMetadataProvider,
    ) -> Result<GeneratedWorkspace, ToSynError> {
        if modified_symbols.is_empty() {
            return Ok(GeneratedWorkspace::default());
        }

        // Step 1: Map modified SymbolIds → crate-relative file paths.
        //
        // SymbolPath derivation rules (multi-file mode):
        //   crate::Item              → src/lib.rs
        //   crate::module::Item      → src/module.rs
        //   crate::module::sub::Item → src/module/sub.rs
        //   main::crate::Item        → src/main.rs
        //   main::crate::cli::Args   → src/cli.rs
        //
        // IMPORTANT: Method/Impl symbols have paths like crate::Type::method
        // where "Type" is a struct/enum, NOT a module. We must resolve these
        // to their file-level ancestor (direct child of a Mod) before computing
        // the file key, otherwise "Type" would be misinterpreted as a module name.
        let mut affected_file_keys: HashSet<String> = modified_symbols
            .iter()
            .filter_map(|&id| {
                let path = symbol_registry.path(id)?;
                let resolved =
                    Self::resolve_to_file_level_symbol(path, symbol_registry, ast_registry);
                Some(self.symbol_path_to_file_key(&resolved))
            })
            .collect();

        // Step 1b: For modified Mod symbols (non-inline), also include the module's
        // OWN file. symbol_path_to_file_key maps a module to its PARENT file (where
        // `mod foo;` is declared), but we also need the module's content file
        // (e.g., `src/foo.rs`) to be generated — especially for newly created modules
        // that have no prior file on disk.
        for &id in modified_symbols {
            if symbol_registry.kind(id) != Some(SymbolKind::Mod) {
                continue;
            }
            if ast_registry.is_inline_module(id) {
                continue;
            }
            if let Some(path) = symbol_registry.path(id) {
                // The module's own file key = parent_file_key + derive_child_path(mod_name)
                let parent_key = self.symbol_path_to_file_key(path);
                let crate_name_opt = CrateName::new(path.crate_name()).ok();
                if let Some(mod_name) = path.segments().last() {
                    let mod_file_key =
                        self.derive_child_path(&parent_key, mod_name, crate_name_opt.as_ref());
                    affected_file_keys.insert(mod_file_key);
                }
            }
        }

        tracing::debug!(
            "generate_affected: {} modified symbols → {} affected file keys: {:?}",
            modified_symbols.len(),
            affected_file_keys.len(),
            affected_file_keys,
        );

        // Step 2: Compute the set of crates that own a modified symbol.
        // generate_internal uses this whitelist to skip the per-crate
        // generation pipeline for crates that no modification touched —
        // previously every crate's lib.rs was regenerated and reformatted
        // even when the mutation lived entirely inside one library, which
        // produced 9 spurious lib.rs Modified entries against the
        // AllowStore ExtractTrait probe even after the binary-only-crate
        // pre-flight filter (`a638ee27`).
        let affected_crates: HashSet<CrateName> = modified_symbols
            .iter()
            .filter_map(|&id| {
                let path = symbol_registry.path(id)?;
                CrateName::new(path.crate_name()).ok()
            })
            .collect();

        // Step 3: Run organization + selective serialization.
        // The organization phase (symbol grouping, module tree building) runs for ALL symbols
        // but is fast (HashMap operations only). The expensive to_source() serialization
        // is skipped for files not in affected_file_keys.
        self.generate_internal(
            ast_registry,
            symbol_registry,
            Some(&affected_file_keys),
            Some(&affected_crates),
        )
    }

    /// Resolve a symbol path to its file-level ancestor.
    ///
    /// Methods and associated items have paths like `crate::Type::method` where
    /// "Type" is a struct/enum, not a module. `symbol_path_to_file_key` would
    /// incorrectly treat "Type" as a module segment and map to `src/Type.rs`.
    ///
    /// This function walks up the path until it finds a symbol whose parent is a
    /// non-inline Mod (or the crate root). Inline modules (defined with `mod name { ... }`)
    /// don't have separate files, so symbols inside them must be mapped to the
    /// file of the enclosing non-inline module.
    ///
    /// # Examples
    /// - `crate::Config::new` (Method) → `crate::Config` (Struct, parent=Mod)
    /// - `crate::foo::Bar::new` (Method) → `crate::foo::Bar` (Struct, parent=Mod)
    /// - `crate::Config` (Struct) → `crate::Config` (already file-level)
    /// - `crate::tests::test_foo` (inside inline mod) → `crate::tests::test_foo`
    ///   but parent `crate::tests` is inline → file key maps to `src/lib.rs`
    fn resolve_to_file_level_symbol(
        path: &SymbolPath,
        registry: &SymbolRegistry,
        ast_registry: &ASTRegistry,
    ) -> SymbolPath {
        let mut current = path.clone();
        loop {
            if let Some(parent) = current.parent() {
                if let Some(parent_id) = registry.lookup(&parent) {
                    if registry.kind(parent_id) == Some(SymbolKind::Mod) {
                        // If this module is inline, keep walking up — inline modules
                        // don't have separate files.
                        if ast_registry.is_inline_module(parent_id) {
                            current = parent;
                            continue;
                        }
                        return current;
                    }
                }
                current = parent;
            } else {
                return current;
            }
        }
    }

    /// Map a SymbolPath to its crate-relative file path.
    ///
    /// This replicates the file derivation logic used by `build_module_tree` +
    /// `generate_files_from_tree` to determine which file a symbol belongs to.
    ///
    /// # Examples
    /// - `my_crate::Config`           → `"src/lib.rs"`
    /// - `my_crate::models::User`     → `"src/models.rs"`
    /// - `my_crate::models::sub::Foo` → `"src/models/sub.rs"`
    /// - `main::my_app::cli::Args`    → `"src/cli.rs"`
    fn symbol_path_to_file_key(&self, path: &SymbolPath) -> String {
        let segments: Vec<&str> = path.segments().collect();
        let is_main = path.is_main_symbol();
        let skip_count = if is_main { 2 } else { 1 };

        // Module segments = everything between crate prefix and item name.
        // For `crate::models::User`: skip_count=1, segments=["crate","models","User"]
        //   → module_segments = ["models"]
        // For `crate::Config`:       skip_count=1, segments=["crate","Config"]
        //   → module_segments = []
        // For a module itself `crate::models`: segments=["crate","models"]
        //   → module_segments = [] (the module lives in the parent file for mod declaration,
        //     but its own content is in src/models.rs)
        //
        // Edge case: when a Mod symbol itself is modified, we want BOTH the parent file
        // (for `mod foo;` declaration) AND the module's own file. However,
        // `collect_modified_symbols` already handles this by including the parent module
        // for SymbolAdded/SymbolRemoved events.
        let item_segments = if segments.len() > skip_count {
            &segments[skip_count..segments.len() - 1]
        } else {
            &[]
        };

        // Filter out impl block segments
        let module_segments: Vec<&str> = item_segments
            .iter()
            .filter(|s| !s.starts_with("<impl "))
            .copied()
            .collect();

        let root_file = if is_main { "src/main.rs" } else { "src/lib.rs" };

        // Resolve CrateName for per-crate `derive_child_path` lookup.
        let crate_name_opt = CrateName::new(path.crate_name()).ok();

        if module_segments.is_empty() {
            root_file.to_string()
        } else {
            // Walk the derive_child_path chain to get the correct file path
            let mut current = root_file.to_string();
            for seg in &module_segments {
                current = self.derive_child_path(&current, seg, crate_name_opt.as_ref());
            }
            current
        }
    }

    /// Generate source files using CodeGraphV2 for module traversal.
    ///
    /// This version uses the Contains edges in CodeGraphV2 to traverse the module
    /// hierarchy instead of re-grouping symbols with HashMaps. This provides O(1)
    /// child lookup per symbol instead of O(N) HashMap grouping.
    ///
    /// # Arguments
    /// * `code_graph` - The code graph with Contains edges representing module hierarchy
    /// * `ast_registry` - The AST registry containing symbol ASTs
    /// * `symbol_registry` - The symbol registry with path information
    pub fn generate_with_graph(
        &self,
        code_graph: &CodeGraphV2,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Result<GeneratedWorkspace, ToSynError> {
        let mut workspace = GeneratedWorkspace::default();

        // Get crate roots from CodeGraphV2 and find their direct children
        // Group children by crate_name and is_main
        let mut crate_children: HashMap<(String, bool), Vec<SymbolId>> = HashMap::new();

        for &root_id in code_graph.crate_roots() {
            // Get path to determine crate_name and is_main
            if let Some(path) = symbol_registry.path(root_id) {
                let (crate_name, is_main) = if path.is_main_symbol() {
                    (
                        path.main_target_crate()
                            .unwrap_or(path.crate_name())
                            .to_string(),
                        true,
                    )
                } else {
                    (path.crate_name().to_string(), false)
                };

                // Get direct children of this crate root
                let children: Vec<SymbolId> = code_graph.children_of(root_id).collect();
                crate_children
                    .entry((crate_name, is_main))
                    .or_default()
                    .extend(children);
            }
        }

        // Generate each crate
        for ((crate_name, is_main), root_ids) in crate_children {
            let entry = workspace
                .crates
                .entry(crate_name.clone())
                .or_insert_with(|| GeneratedCrate {
                    crate_name: crate_name.clone(),
                    files: HashMap::new(),
                });

            let generated_files = if self.single_file {
                self.generate_single_file_from_graph(
                    &crate_name,
                    &root_ids,
                    is_main,
                    code_graph,
                    ast_registry,
                    symbol_registry,
                )
            } else {
                self.generate_multi_file_from_graph(
                    &crate_name,
                    &root_ids,
                    is_main,
                    code_graph,
                    ast_registry,
                    symbol_registry,
                )
            };

            entry.files.extend(generated_files?);
        }

        Ok(workspace)
    }

    /// Generate single file using CodeGraphV2 traversal.
    fn generate_single_file_from_graph(
        &self,
        _crate_name: &str,
        root_ids: &[SymbolId],
        is_main: bool,
        code_graph: &CodeGraphV2,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Result<HashMap<String, GeneratedFile>, ToSynError> {
        let items =
            self.collect_items_from_graph(root_ids, code_graph, ast_registry, symbol_registry);

        // Extract inner attributes (#![...]) from crate root module for file-level attrs
        let file_attrs = self.extract_file_attrs_from_ids(root_ids, ast_registry, symbol_registry);

        let pure_file = PureFile {
            attrs: file_attrs,
            items,
        };
        let source = pure_file.to_source()?;

        let root_file = if is_main { "src/main.rs" } else { "src/lib.rs" };

        let mut files = HashMap::new();
        files.insert(root_file.to_string(), GeneratedFile { source, pure_file });
        Ok(files)
    }

    /// Generate multi-file using CodeGraphV2 traversal.
    fn generate_multi_file_from_graph(
        &self,
        _crate_name: &str,
        root_ids: &[SymbolId],
        is_main: bool,
        code_graph: &CodeGraphV2,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Result<HashMap<String, GeneratedFile>, ToSynError> {
        let root_file = if is_main { "src/main.rs" } else { "src/lib.rs" };

        let mut files = HashMap::new();
        self.generate_file_from_graph(
            root_file,
            root_ids,
            None, // top-level: scan root_ids for crate root Mod
            code_graph,
            ast_registry,
            symbol_registry,
            &mut files,
        )?;
        Ok(files)
    }

    /// Recursively collect items from graph for single-file mode.
    fn collect_items_from_graph(
        &self,
        ids: &[SymbolId],
        code_graph: &CodeGraphV2,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Vec<PureItem> {
        let mut items = Vec::new();

        // Separate Mod symbols from other items
        let mut mods: Vec<SymbolId> = Vec::new();
        let mut non_mods: Vec<SymbolId> = Vec::new();

        for &id in ids {
            if let Some(kind) = symbol_registry.kind(id) {
                if kind == SymbolKind::Mod {
                    // Check if this Mod is actually a crate root (not a real submodule)
                    // Use SymbolPath::is_crate_root() which uses precomputed crate_root_depth
                    if let Some(path) = symbol_registry.path(id) {
                        if path.is_crate_root() {
                            // Crate root Mod: treat as non-mod (inline its contents)
                            // Examples: main::my_app, my_lib
                            non_mods.push(id);
                        } else {
                            // Real submodule: separate file
                            // Examples: main::my_app::utils, my_lib::utils
                            mods.push(id);
                        }
                    } else {
                        mods.push(id);
                    }
                } else {
                    non_mods.push(id);
                }
            }
        }

        // Add non-mod items first (excluding impl blocks)
        // Impl blocks are added from module_items below
        for id in non_mods {
            // Skip impl blocks - they're handled separately from module_items
            if symbol_registry.kind(id) == Some(SymbolKind::Impl) {
                continue;
            }
            if let Some(item) = ast_registry.get(id) {
                items.push(item.clone());
            }
        }

        // Add use statements and impl blocks from module_items
        // New design: impl blocks are stored in module_items (file-level construct)
        // Use statements also stored in module_items for positioning control
        for &id in ids {
            if let Some(module_items) = ast_registry.get_module_items(id) {
                for item in module_items {
                    if matches!(item, PureItem::Use(_) | PureItem::Impl(_)) {
                        items.push(item.clone());
                    }
                }
            }
        }

        // Add nested modules with their content
        for mod_id in mods {
            let children: Vec<SymbolId> = code_graph.children_of(mod_id).collect();
            let child_items =
                self.collect_items_from_graph(&children, code_graph, ast_registry, symbol_registry);

            // Get module name from path
            if let Some(path) = symbol_registry.path(mod_id) {
                let mod_name = path.segments().last().unwrap_or("unknown").to_string();

                // Determine visibility
                let vis = if child_items.iter().any(is_public) {
                    PureVis::Public
                } else {
                    PureVis::Private
                };

                // Add use statements from this module to child_items
                let mut all_items = Vec::new();
                if let Some(module_items) = ast_registry.get_module_items(mod_id) {
                    for item in module_items {
                        if let PureItem::Use(_) = item {
                            all_items.push(item.clone());
                        }
                    }
                }
                all_items.extend(child_items);

                // Preserve attributes from original PureMod if available
                let mod_attrs = ast_registry
                    .get(mod_id)
                    .and_then(|item| {
                        if let PureItem::Mod(m) = item {
                            Some(m.attrs.clone())
                        } else {
                            None
                        }
                    })
                    .unwrap_or_default();

                items.push(PureItem::Mod(PureMod {
                    attrs: mod_attrs,
                    vis,
                    name: mod_name,
                    items: all_items,
                    scope: Default::default(),
                }));
            }
        }

        // NOTE: merge_impl_blocks disabled for sequential impl numbering
        // merge_impl_blocks(&mut items);
        sort_items(&mut items);
        items
    }

    /// Recursively generate files from graph for multi-file mode.
    ///
    /// `containing_mod_id` is the Mod symbol whose body this file represents.
    /// `None` at the top-level entry (`src/lib.rs` / `src/main.rs`) so the
    /// existing crate-root scan path is used; `Some(mod_id)` in recursive
    /// calls so submodule files preserve their `//! ...` inner doc lines.
    #[allow(clippy::too_many_arguments)]
    fn generate_file_from_graph(
        &self,
        current_path: &str,
        ids: &[SymbolId],
        containing_mod_id: Option<SymbolId>,
        code_graph: &CodeGraphV2,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
        files: &mut HashMap<String, GeneratedFile>,
    ) -> Result<(), ToSynError> {
        let mut items = Vec::new();

        // Separate Mod symbols from other items
        let mut mods: Vec<SymbolId> = Vec::new();
        let mut non_mods: Vec<SymbolId> = Vec::new();

        for &id in ids {
            if let Some(kind) = symbol_registry.kind(id) {
                if kind == SymbolKind::Mod {
                    // Check if this Mod is actually a crate root (not a real submodule)
                    // Use SymbolPath::is_crate_root() which uses precomputed crate_root_depth
                    if let Some(path) = symbol_registry.path(id) {
                        if path.is_crate_root() {
                            // Crate root Mod: treat as non-mod (inline its contents)
                            // Examples: main::my_app, my_lib
                            non_mods.push(id);
                        } else {
                            // Real submodule: separate file
                            // Examples: main::my_app::utils, my_lib::utils
                            mods.push(id);
                        }
                    } else {
                        mods.push(id);
                    }
                } else {
                    non_mods.push(id);
                }
            }
        }

        // Add non-mod items (excluding impl blocks)
        // Impl blocks are added from module_items below
        for id in non_mods {
            // Skip impl blocks - they're handled separately from module_items
            if symbol_registry.kind(id) == Some(SymbolKind::Impl) {
                continue;
            }
            if let Some(item) = ast_registry.get(id) {
                items.push(item.clone());
            }
        }

        // Add use statements and impl blocks from module_items for the root level
        // New design: impl blocks are stored in module_items (file-level construct)
        for &id in ids {
            if let Some(module_items) = ast_registry.get_module_items(id) {
                for item in module_items {
                    if matches!(item, PureItem::Use(_) | PureItem::Impl(_)) {
                        items.push(item.clone());
                    }
                }
            }
        }

        // Add mod declarations or inline modules for children
        // Track which modules are inline (should not generate separate files)
        let mut inline_mod_ids: Vec<SymbolId> = Vec::new();

        for &mod_id in &mods {
            if let Some(path) = symbol_registry.path(mod_id) {
                let mod_name = path.segments().last().unwrap_or("unknown").to_string();

                // Check if this is an inline module (has items in ASTRegistry)
                if let Some(PureItem::Mod(m)) = ast_registry.get(mod_id) {
                    if !m.items.is_empty() {
                        // Inline module - include as-is with its content
                        items.push(PureItem::Mod(m.clone()));
                        inline_mod_ids.push(mod_id);
                        continue;
                    }
                }

                // External module - generate mod declaration
                // Use visibility from original PureMod if available,
                // NOT inferred from children (fixes mod → pub mod bug)
                let (vis, attrs) = ast_registry
                    .get(mod_id)
                    .and_then(|item| {
                        if let PureItem::Mod(m) = item {
                            Some((m.vis.clone(), m.attrs.clone()))
                        } else {
                            None
                        }
                    })
                    .unwrap_or((PureVis::Private, vec![]));

                items.push(PureItem::Mod(PureMod {
                    attrs,
                    vis,
                    name: mod_name,
                    items: vec![], // External module
                    scope: Default::default(),
                }));
            }
        }

        // NOTE: merge_impl_blocks is disabled to preserve sequential impl numbering.
        // With the new impl numbering system (<impl Foo>::1, <impl Foo>::2),
        // each impl block is intentionally separate and should not be merged.
        // merge_impl_blocks(&mut items);

        // Sort items for stable output
        sort_items(&mut items);

        // Extract inner attributes (#![...]) for file-level attrs.
        // For submodule files the container Mod is passed explicitly so that
        // its `//! ...` doc lines (which live on the Mod, not on the file's
        // child items) are preserved across regeneration.
        let file_attrs = self.extract_file_attrs_from_ids_with_container(
            ids,
            containing_mod_id,
            ast_registry,
            symbol_registry,
        );

        let pure_file = PureFile {
            attrs: file_attrs,
            items,
        };
        let source = pure_file.to_source()?;
        files.insert(
            current_path.to_string(),
            GeneratedFile { source, pure_file },
        );

        // Recursively generate child module files (skip inline modules)
        for mod_id in mods {
            // Skip inline modules - they don't need separate files
            if inline_mod_ids.contains(&mod_id) {
                continue;
            }

            if let Some(path) = symbol_registry.path(mod_id) {
                let mod_name = path.segments().last().unwrap_or("unknown").to_string();
                let crate_name_opt = CrateName::new(path.crate_name()).ok();
                let child_path =
                    self.derive_child_path(current_path, &mod_name, crate_name_opt.as_ref());
                let children: Vec<SymbolId> = code_graph.children_of(mod_id).collect();
                self.generate_file_from_graph(
                    &child_path,
                    &children,
                    Some(mod_id), // submodule: pull inner attrs (#![...] / //!) from this Mod
                    code_graph,
                    ast_registry,
                    symbol_registry,
                    files,
                )?;
            }
        }
        Ok(())
    }

    /// Generate a single file with nested mod {} blocks.
    ///
    /// - `is_main`: If true, output to `src/main.rs`, otherwise `src/lib.rs`
    fn generate_single_file_inner(
        &self,
        crate_name: &str,
        symbols: Vec<(SymbolId, SymbolPath, PureItem)>,
        is_main: bool,
        module_use_items: &HashMap<ModSymbolKey, Vec<PureItem>>,
        mod_symbols: &HashMap<ModSymbolKey, ModSymbolValue>,
    ) -> Result<HashMap<String, GeneratedFile>, ToSynError> {
        // Build module tree from symbols
        let mut tree = self.build_module_tree(crate_name, &symbols, is_main);

        // Add empty modules from SymbolRegistry (modules without child items)
        self.add_mod_symbols_to_tree(&mut tree, crate_name, is_main, mod_symbols);

        // Add use statements from module_items
        self.add_use_items_to_tree(&mut tree, crate_name, is_main, module_use_items);

        // Convert tree to PureFile
        let pure_file = self.tree_to_pure_file(&tree);
        let source = pure_file.to_source()?;

        let root_file = if is_main { "src/main.rs" } else { "src/lib.rs" };

        let mut files = HashMap::new();
        files.insert(root_file.to_string(), GeneratedFile { source, pure_file });
        Ok(files)
    }

    /// Generate multiple files following Rust module conventions.
    ///
    /// - `is_main`: If true, root is `src/main.rs`, otherwise `src/lib.rs`
    /// - `affected_file_keys`: When `Some`, only files in the set are serialized.
    fn generate_multi_file_inner(
        &self,
        crate_name: &str,
        symbols: Vec<SymbolEntry>,
        opts: MultiFileOpts<'_>,
    ) -> Result<HashMap<String, GeneratedFile>, ToSynError> {
        let MultiFileOpts {
            is_main,
            module_use_items,
            mod_symbols,
            inline_module_paths,
            affected_file_keys,
        } = opts;

        // Build module tree from symbols
        let mut tree = self.build_module_tree(crate_name, &symbols, is_main);

        // Add empty modules from SymbolRegistry (modules without child items)
        self.add_mod_symbols_to_tree(&mut tree, crate_name, is_main, mod_symbols);

        // Add use statements from module_items
        self.add_use_items_to_tree(&mut tree, crate_name, is_main, module_use_items);

        let root_file = if is_main { "src/main.rs" } else { "src/lib.rs" };

        // Extract inline module paths (full segments, crate prefix stripped) for this crate.
        //
        // Last-segment-only collection (the previous shape) collapsed sibling modules
        // that share a final segment (e.g. `foo::tests` and `bar::tests`) into a single
        // `"tests"` key, so `bar::tests` could be misclassified as inline.  Keeping the
        // full segment vector eliminates the collision.
        let crate_prefix = format!("{}::", crate_name);
        let inline_mod_paths: HashSet<Vec<String>> = inline_module_paths
            .iter()
            .filter(|p| p.starts_with(&crate_prefix))
            .filter_map(|p| p.strip_prefix(&crate_prefix))
            .map(|s| s.split("::").map(|seg| seg.to_string()).collect())
            .collect();

        // Resolve CrateName for per-crate `existing_file_keys` lookup inside the
        // recursive `derive_child_path` walk.
        let current_crate = CrateName::new(crate_name).ok();

        // Generate files from tree
        let mut files = HashMap::new();
        self.generate_files_from_tree(
            &tree,
            root_file,
            &[],
            &mut files,
            &inline_mod_paths,
            affected_file_keys,
            current_crate.as_ref(),
        )?;
        Ok(files)
    }

    /// Add use statements from module_items to the module tree.
    fn add_use_items_to_tree(
        &self,
        tree: &mut ModuleNode,
        crate_name: &str,
        is_main: bool,
        module_use_items: &HashMap<ModSymbolKey, Vec<PureItem>>,
    ) {
        tracing::debug!(
            "add_use_items_to_tree: crate_name={}, is_main={}, module_use_items_count={}",
            crate_name,
            is_main,
            module_use_items.len()
        );
        // Collect matching use items first
        let mut items_to_add: Vec<(Vec<String>, Vec<PureItem>)> = Vec::new();

        for ((item_crate, segments, item_is_main), use_items) in module_use_items {
            if item_crate != crate_name || *item_is_main != is_main {
                continue;
            }
            tracing::debug!(
                "  Matched: segments={:?}, use_items_count={}",
                segments,
                use_items.len()
            );
            items_to_add.push((segments.clone(), use_items.clone()));
        }

        // Now add them to the tree
        for (segments, use_items) in items_to_add {
            let target_node = if segments.is_empty() {
                tree as &mut ModuleNode
            } else {
                let seg_refs: Vec<&str> = segments.iter().map(|s| s.as_str()).collect();
                tree.get_or_create_path(&seg_refs)
            };

            // Add use items (they will be sorted later)
            for use_item in use_items {
                target_node.items.push(use_item);
            }
        }
    }

    /// Add empty modules from SymbolRegistry to the module tree.
    ///
    /// This ensures modules without child items (empty modules) still get
    /// mod declarations in the output. RegistryGenerator derives module
    /// hierarchy from child item paths, so empty modules would otherwise
    /// be missing from the output.
    fn add_mod_symbols_to_tree(
        &self,
        tree: &mut ModuleNode,
        crate_name: &str,
        is_main: bool,
        mod_symbols: &HashMap<ModSymbolKey, ModSymbolValue>,
    ) {
        for ((item_crate, segments, item_is_main), (is_pub, attrs)) in mod_symbols {
            if item_crate != crate_name || *item_is_main != is_main {
                continue;
            }
            // Get target node: root tree for empty segments, or navigate to path
            let node = if segments.is_empty() {
                // Crate root - set attrs on the root tree node itself
                tree as &mut ModuleNode
            } else {
                let seg_refs: Vec<&str> = segments.iter().map(|s| s.as_str()).collect();
                tree.get_or_create_path(&seg_refs)
            };

            // Set explicit visibility for empty modules (skip for root)
            if !segments.is_empty() && node.is_pub.is_none() {
                node.is_pub = Some(*is_pub);
            }
            // Set attributes (both outer #[...] and inner #![...])
            if node.attrs.is_empty() && !attrs.is_empty() {
                node.attrs = attrs.clone();
            }
        }
    }

    /// Build a module tree from symbols.
    ///
    /// - `is_main`: If true, paths are `main::crate::module::Item` format
    fn build_module_tree(
        &self,
        crate_name: &str,
        symbols: &[(SymbolId, SymbolPath, PureItem)],
        is_main: bool,
    ) -> ModuleNode {
        let mut root = ModuleNode::new(crate_name.to_string());

        for (_id, path, item) in symbols {
            // Get module path (all segments except crate name and item name)
            let segments: Vec<&str> = path.segments().collect();

            // For main symbols: main::crate_name::module::Item
            // For lib symbols:  crate_name::module::Item
            let skip_count = if is_main { 2 } else { 1 }; // Skip "main::" + "crate" or just "crate"

            if segments.len() <= skip_count {
                // Crate-level item (shouldn't happen normally)
                continue;
            }

            // module_segments = segments between crate and item name
            // Filter out impl block segments (e.g., "<impl Trait for Type>")
            let module_segments: Vec<&str> = segments[skip_count..segments.len() - 1]
                .iter()
                .filter(|s| !s.starts_with("<impl "))
                .copied()
                .collect();

            // Navigate/create module path
            let target_module = root.get_or_create_path(&module_segments);

            // Add item to module
            target_module.items.push(item.clone());
        }

        root
    }

    /// Convert module tree to PureFile (single file with nested mods).
    fn tree_to_pure_file(&self, tree: &ModuleNode) -> PureFile {
        let items = self.collect_items_recursive(tree, true);
        // Extract inner attributes (#![...]) from root node for file-level attrs
        let file_attrs: Vec<PureAttribute> =
            tree.attrs.iter().filter(|a| a.is_inner).cloned().collect();
        PureFile {
            attrs: file_attrs,
            items,
        }
    }

    /// Collect items recursively, creating nested mod {} blocks.
    fn collect_items_recursive(&self, node: &ModuleNode, _is_root: bool) -> Vec<PureItem> {
        let mut items = Vec::new();

        // Add direct items (sorted), filtering out Prod file-based mod declarations
        // (e.g. `mod foo;` with empty items, scope=Prod) — those are regenerated from
        // node.children below to avoid duplicates. Keep:
        //   * inline modules (items non-empty), and
        //   * `#[cfg(test)] mod tests;` style empty Test declarations (scope=Test),
        //     which represent intentional test scaffolding and must round-trip in
        //     single-file output (registry.rs marks them inline on the read path).
        let mut direct_items: Vec<PureItem> = node
            .items
            .iter()
            .filter(|item| match item {
                PureItem::Mod(m) => !m.items.is_empty() || m.scope == ModScope::Test,
                _ => true,
            })
            .cloned()
            .collect();
        // NOTE: merge_impl_blocks disabled for sequential impl numbering
        // merge_impl_blocks(&mut direct_items);
        sort_items(&mut direct_items);
        items.extend(direct_items);

        // Add child modules as nested mod {}
        for (name, child) in &node.children {
            let child_items = self.collect_items_recursive(child, false);

            // Determine visibility: explicit flag takes precedence, otherwise check items
            let vis = if let Some(is_pub) = child.is_pub {
                if is_pub {
                    PureVis::Public
                } else {
                    PureVis::Private
                }
            } else if child.items.iter().any(is_public) {
                PureVis::Public
            } else {
                PureVis::Private
            };

            // Use outer attributes (#[...]) for module declaration
            let mod_attrs: Vec<PureAttribute> = child
                .attrs
                .iter()
                .filter(|a| !a.is_inner)
                .cloned()
                .collect();

            items.push(PureItem::Mod(PureMod {
                attrs: mod_attrs,
                vis,
                name: name.clone(),
                items: child_items,
                scope: Default::default(),
            }));
        }

        items
    }

    /// Generate files from tree (multi-file mode).
    ///
    /// `mod_segments`: Path segments of the current module relative to the crate root.
    /// Empty at the root (`src/lib.rs` / `src/main.rs`); appended one segment per recursion.
    /// Combined with each child name to look up `known_inline_mods` by full path, which
    /// prevents sibling-module collisions (e.g. `foo::tests` vs `bar::tests`).
    ///
    /// `known_inline_mods`: Set of fully-qualified module path segments that are known
    /// inline modules from ASTRegistry (crate prefix stripped, e.g. `["foo", "tests"]`).
    /// These modules should NOT generate separate files, even if they appear in tree.children.
    ///
    /// `affected_file_keys`: When `Some`, only serialize files whose crate-relative path
    /// is in the set. The tree walk still recurses for all children (to handle nested modules),
    /// but `to_source()` is skipped for non-affected files.
    // The 8 arguments mirror the existing recursive tree-walk shape; collapsing
    // them into a parameter struct is a separate architecture concern.
    #[allow(clippy::too_many_arguments)]
    fn generate_files_from_tree(
        &self,
        tree: &ModuleNode,
        current_path: &str,
        mod_segments: &[String],
        files: &mut HashMap<String, GeneratedFile>,
        known_inline_mods: &HashSet<Vec<String>>,
        affected_file_keys: Option<&HashSet<String>>,
        current_crate: Option<&CrateName>,
    ) -> Result<(), ToSynError> {
        tracing::debug!(
            "Generating file: {} (module: {}, mod_segments={:?}, {} children, {} items, known_inline_mods={:?})",
            current_path,
            tree.name,
            mod_segments,
            tree.children.len(),
            tree.items.len(),
            known_inline_mods
        );

        // Build the fully-qualified path of a child of this module: `[mod_segments..., name]`.
        let child_path = |name: &str| -> Vec<String> {
            let mut p = Vec::with_capacity(mod_segments.len() + 1);
            p.extend_from_slice(mod_segments);
            p.push(name.to_string());
            p
        };

        // Collect items for this module (without children content)
        let mut items = Vec::new();

        // Add direct items (structs, enums, functions, etc.)
        // Only keep modules that are explicitly marked as inline via mark_inline_module().
        // External modules (not marked) get separate files, even if PureMod.items is non-empty.
        // This fixes the bug where external module files (e.g., filter.rs) would get inlined
        // into lib.rs just because their PureMod.items was non-empty after parsing.
        let mut direct_items: Vec<PureItem> = tree
            .items
            .iter()
            .filter(|item| match item {
                PureItem::Mod(m) => {
                    // Only keep modules explicitly marked as inline in ASTRegistry.
                    // Check by full path so that e.g. `foo::tests` (inline) and
                    // `bar::tests` (external) are not conflated by their shared last segment.
                    known_inline_mods.contains(&child_path(&m.name))
                }
                _ => true,
            })
            .cloned()
            .collect();
        // NOTE: merge_impl_blocks disabled for sequential impl numbering
        // merge_impl_blocks(&mut direct_items);
        sort_items(&mut direct_items);

        items.extend(direct_items);

        // Collect external mod declarations for children (no content -
        // separate files). These are kept in a separate Vec so we can
        // prepend them to `items` rather than appending — Rust convention
        // places `mod foo;` declarations at the top of the file, before
        // `use ...` and definitions. Appending here surfaced as a tail-
        // migration of `mod types;` (line 48 → 6082) in
        // `dsl_macro_verbatim_diff_observe`'s regen of
        // `crates/ryo-app/src/api/mod.rs`, even after the visibility flip
        // (`cd58231e`) silenced the `pub mod` promotion. Skip children
        // that are already inline modules (avoid duplicates).
        let mut external_mod_decls: Vec<PureItem> = Vec::new();
        for (name, child) in &tree.children {
            if known_inline_mods.contains(&child_path(name)) {
                continue;
            }

            // Try to get visibility from tree.items (original PureMod)
            // This preserves the original `mod foo;` vs `pub mod foo;` distinction
            let original_mod = tree.items.iter().find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if &m.name == name {
                        return Some(m);
                    }
                }
                None
            });

            // Use original visibility if available, then explicit flag, then infer from items
            let vis = if let Some(m) = original_mod {
                m.vis.clone()
            } else if let Some(is_pub) = child.is_pub {
                if is_pub {
                    PureVis::Public
                } else {
                    PureVis::Private
                }
            } else {
                PureVis::Private
            };

            // Use outer attributes (#[...]) for module declaration (e.g., #[cfg(test)] mod tests;)
            let mod_attrs: Vec<PureAttribute> = if let Some(m) = original_mod {
                m.attrs.iter().filter(|a| !a.is_inner).cloned().collect()
            } else {
                child
                    .attrs
                    .iter()
                    .filter(|a| !a.is_inner)
                    .cloned()
                    .collect()
            };

            external_mod_decls.push(PureItem::Mod(PureMod {
                attrs: mod_attrs,
                vis,
                name: name.clone(),
                items: vec![], // External module
                scope: Default::default(),
            }));
        }

        // Prepend external mod declarations to the existing items so the
        // regenerated file leads with `mod foo;` lines (matching the
        // original on-disk layout and Rust convention). `sort_items`
        // already ran against `direct_items` above and intentionally
        // leaves the order of these declarations alphabetical-by-name via
        // BTreeMap iteration over `tree.children`, so the prepend is a
        // single in-place splice rather than a re-sort.
        if !external_mod_decls.is_empty() {
            let mut combined = external_mod_decls;
            combined.append(&mut items);
            items = combined;
        }

        // Create file for this module — but ONLY if it's in the affected set (or no filter).
        //
        // DESIGN RULE: to_source() is the most expensive operation in the generation pipeline
        // (prettyplease formatting). Skipping it for unaffected files is the primary optimization.
        let is_affected = affected_file_keys
            .map(|keys| keys.contains(current_path))
            .unwrap_or(true);

        if is_affected {
            let file_attrs: Vec<PureAttribute> =
                tree.attrs.iter().filter(|a| a.is_inner).cloned().collect();
            let pure_file = PureFile {
                attrs: file_attrs,
                items,
            };
            let source = pure_file.to_source()?;
            files.insert(
                current_path.to_string(),
                GeneratedFile { source, pure_file },
            );
        } else {
            tracing::debug!("Skipping unaffected file: {}", current_path);
        }

        // Recursively generate child files (skip inline modules - they don't need separate files)
        // NOTE: Always recurse even when current file is unaffected — child files may be affected.
        for (name, child) in &tree.children {
            let child_segments = child_path(name);
            if known_inline_mods.contains(&child_segments) {
                tracing::debug!("Skipping inline module {} (no separate file)", name);
                continue;
            }
            let child_file_path = self.derive_child_path(current_path, name, current_crate);
            tracing::debug!("  → Child module: {} at {}", name, child_file_path);
            self.generate_files_from_tree(
                child,
                &child_file_path,
                &child_segments,
                files,
                known_inline_mods,
                affected_file_keys,
                current_crate,
            )?;
        }
        Ok(())
    }

    /// Derive child module file path.
    ///
    /// Resolution policy:
    /// 1. If the per-crate existing key set (falling back to the workspace-wide
    ///    set when no per-crate entry is present) already contains the
    ///    `<parent_dir><child>/mod.rs` candidate, preserve that layout — this
    ///    prevents creating a duplicate sibling `<child>.rs` next to an
    ///    existing `<child>/mod.rs`.
    /// 2. If the same set contains the flat `<child>.rs` candidate, prefer
    ///    that.
    /// 3. Otherwise fall back to the generator mode default (`use_mod_rs`).
    ///
    /// `current_crate` selects the per-crate key set. Pass `None` only when the
    /// calling code has no crate context (rare — callers should propagate the
    /// `CrateName` from `SymbolPath::crate_name`).
    fn derive_child_path(
        &self,
        parent_path: &str,
        child_name: &str,
        current_crate: Option<&CrateName>,
    ) -> String {
        // parent_path: "src/lib.rs" or "src/models.rs" or "src/models/user.rs"
        let parent_dir = if parent_path.ends_with("/lib.rs") || parent_path.ends_with("/main.rs") {
            // Root: src/lib.rs → src/
            parent_path
                .trim_end_matches("lib.rs")
                .trim_end_matches("main.rs")
        } else if parent_path.ends_with("/mod.rs") {
            // mod.rs style: src/models/mod.rs → src/models/
            parent_path.trim_end_matches("mod.rs")
        } else {
            // Modern style: src/models.rs → src/models/
            parent_path.trim_end_matches(".rs")
        };

        let mod_rs_candidate = format!("{}{}/mod.rs", parent_dir, child_name);
        let flat_candidate =
            if parent_path.ends_with("/lib.rs") || parent_path.ends_with("/main.rs") {
                format!("{}{}.rs", parent_dir, child_name)
            } else {
                format!("{}/{}.rs", parent_dir, child_name)
            };

        // Step 1: prefer existing on-disk layout (avoid creating sibling duplicates).
        // Use the per-crate key set so that `ryo-executor`'s `executor/mod.rs`
        // does NOT bleed into the lookup for `ryo-agent`'s flat `executor.rs`.
        let keys = self.existing_keys_for_crate(current_crate);
        if keys.contains(&mod_rs_candidate) {
            return mod_rs_candidate;
        }
        if keys.contains(&flat_candidate) {
            return flat_candidate;
        }

        // Step 2/3: fall back to generator mode default.
        if self.use_mod_rs {
            mod_rs_candidate
        } else {
            flat_candidate
        }
    }

    /// Extract inner attributes (#![...]) from symbol IDs for file-level attrs.
    ///
    /// Looks for crate root Mod symbols or the first Mod symbol in the list
    /// and extracts their inner attributes.
    fn extract_file_attrs_from_ids(
        &self,
        ids: &[SymbolId],
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Vec<PureAttribute> {
        self.extract_file_attrs_from_ids_with_container(ids, None, ast_registry, symbol_registry)
    }

    /// Extract inner attributes (`#![...]`, including `//!` doc comments) for a
    /// generated file.
    ///
    /// Two source paths:
    /// 1. When `containing_mod_id` is `Some(mod_id)`, pull inner attrs directly
    ///    from that Mod symbol. This is used for submodule files (`foo.rs` /
    ///    `foo/mod.rs`) where the file represents the body of `mod foo` whose
    ///    `//!` lives on the Mod symbol itself, not on its children.
    /// 2. Otherwise, scan `ids` for a crate root Mod and pull from there.
    ///    Used for the crate entry file (`src/lib.rs` / `src/main.rs`).
    ///
    /// Without path (1), regenerating a submodule file (e.g. via Mutation that
    /// touches a symbol inside `crates/foo/src/bar.rs`) drops the file's
    /// `//! ...` doc lines because the Mod symbol for `bar` is not in `ids`
    /// — only its children are.
    fn extract_file_attrs_from_ids_with_container(
        &self,
        ids: &[SymbolId],
        containing_mod_id: Option<SymbolId>,
        ast_registry: &ASTRegistry,
        symbol_registry: &SymbolRegistry,
    ) -> Vec<PureAttribute> {
        if let Some(mod_id) = containing_mod_id {
            if let Some(PureItem::Mod(m)) = ast_registry.get(mod_id) {
                return m.attrs.iter().filter(|a| a.is_inner).cloned().collect();
            }
        }

        for &id in ids {
            // Check if this is a crate root Mod
            if let Some(kind) = symbol_registry.kind(id) {
                if kind == SymbolKind::Mod {
                    if let Some(path) = symbol_registry.path(id) {
                        if path.is_crate_root() {
                            // Found crate root, extract inner attrs
                            if let Some(PureItem::Mod(m)) = ast_registry.get(id) {
                                return m.attrs.iter().filter(|a| a.is_inner).cloned().collect();
                            }
                        }
                    }
                }
            }
        }
        Vec::new()
    }
}

/// Internal module tree node.
#[derive(Debug, Clone, Default)]
struct ModuleNode {
    name: String,
    items: Vec<PureItem>,
    children: BTreeMap<String, ModuleNode>,
    /// Explicit visibility override (for empty modules from SymbolRegistry)
    is_pub: Option<bool>,
    /// Module attributes (both outer `#[...]` and inner `#![...]`).
    /// - `is_inner: false` → module declaration attrs (e.g., `#[cfg(test)] mod tests;`)
    /// - `is_inner: true` → file-level inner attrs (e.g., `#![allow(...)]`)
    attrs: Vec<PureAttribute>,
}

impl ModuleNode {
    fn new(name: String) -> Self {
        Self {
            name,
            items: Vec::new(),
            children: BTreeMap::new(),
            is_pub: None,
            attrs: Vec::new(),
        }
    }

    fn get_or_create_path(&mut self, segments: &[&str]) -> &mut ModuleNode {
        if segments.is_empty() {
            return self;
        }

        let child = self
            .children
            .entry(segments[0].to_string())
            .or_insert_with(|| ModuleNode::new(segments[0].to_string()));

        child.get_or_create_path(&segments[1..])
    }
}

/// Sort items for idiomatic Rust ordering.
///
/// Order:
/// 1. Use statements
/// 2. Definitions (const, static, type, struct, enum, trait, fn)
/// 3. Impl blocks
/// 4. Modules (except tests)
/// 5. Macros
/// 6. Tests module (always last)
fn sort_items(items: &mut [PureItem]) {
    items.sort_by(|a, b| {
        let kind_a = item_sort_key(a);
        let kind_b = item_sort_key(b);

        match kind_a.cmp(&kind_b) {
            std::cmp::Ordering::Equal => {
                let name_cmp = item_name(a).cmp(item_name(b));
                if name_cmp != std::cmp::Ordering::Equal {
                    return name_cmp;
                }
                // For impl blocks with same self_ty, sort by trait presence
                // impl Foo (no trait) comes before impl Trait for Foo
                match (a, b) {
                    (PureItem::Impl(a_impl), PureItem::Impl(b_impl)) => {
                        match (&a_impl.trait_, &b_impl.trait_) {
                            (None, None) => std::cmp::Ordering::Equal,
                            (None, Some(_)) => std::cmp::Ordering::Less,
                            (Some(_), None) => std::cmp::Ordering::Greater,
                            (Some(a_trait), Some(b_trait)) => a_trait.cmp(b_trait),
                        }
                    }
                    _ => std::cmp::Ordering::Equal,
                }
            }
            other => other,
        }
    });
}

fn item_sort_key(item: &PureItem) -> u8 {
    // Rust convention orders file-level items roughly as:
    //   `mod foo;` (external)  →  `use ...;`  →  const  →  static  →  type
    //   →  struct  →  enum  →  trait  →  fn  →  impl  →  macro_rules!
    //   →  inline `mod foo { ... }`  →  `#[cfg(test)] mod tests { ... }`
    //
    // The previous key table led with `Use(_) = 0` and pushed `Mod(_)` to
    // `= 9`, which forced regenerated files to surface module declarations
    // after impl blocks — far from the on-disk layout. Aligning the keys
    // with the convention shrinks the diff noise that `sort_items` emits
    // for files like `crates/ryo-app/src/api/mod.rs`, while keeping
    // `mod tests` pinned at the tail.
    match item {
        PureItem::Mod(m) if m.name == "tests" => 12, // tests module last
        PureItem::Mod(_) => 0,                       // external + non-tests inline mods first
        PureItem::Use(_) => 1,
        PureItem::Const(_) => 2,
        PureItem::Static(_) => 3,
        PureItem::Type(_) => 4,
        PureItem::Struct(_) => 5,
        PureItem::Enum(_) => 6,
        PureItem::Trait(_) => 7,
        PureItem::Fn(_) => 8,
        PureItem::Impl(_) => 9,
        PureItem::Macro(_) => 10,
        PureItem::Other(_) => 11,
        PureItem::Verbatim(_) => 13,
    }
}

fn item_name(item: &PureItem) -> &str {
    match item {
        PureItem::Struct(s) => &s.name,
        PureItem::Enum(e) => &e.name,
        PureItem::Fn(f) => &f.name,
        PureItem::Trait(t) => &t.name,
        PureItem::Impl(i) => &i.self_ty,
        PureItem::Const(c) => &c.name,
        PureItem::Static(s) => &s.name,
        PureItem::Type(t) => &t.name,
        PureItem::Mod(m) => &m.name,
        PureItem::Macro(m) => &m.path,
        _ => "",
    }
}

fn is_public(item: &PureItem) -> bool {
    match item {
        PureItem::Struct(s) => matches!(s.vis, PureVis::Public),
        PureItem::Enum(e) => matches!(e.vis, PureVis::Public),
        PureItem::Fn(f) => matches!(f.vis, PureVis::Public),
        PureItem::Trait(t) => matches!(t.vis, PureVis::Public),
        PureItem::Const(c) => matches!(c.vis, PureVis::Public),
        PureItem::Static(s) => matches!(s.vis, PureVis::Public),
        PureItem::Type(t) => matches!(t.vis, PureVis::Public),
        PureItem::Mod(m) => matches!(m.vis, PureVis::Public),
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use ryo_source::pure::{
        PureBlock, PureEnum, PureFields, PureFn, PureGenerics, PureStruct, PureVariant,
    };
    use ryo_symbol::SymbolKind;

    fn make_struct(name: &str) -> PureItem {
        PureItem::Struct(PureStruct {
            attrs: vec![],
            vis: PureVis::Public,
            name: name.to_string(),
            generics: PureGenerics::default(),
            fields: PureFields::Unit,
        })
    }

    fn make_fn(name: &str) -> PureItem {
        PureItem::Fn(PureFn {
            attrs: vec![],
            vis: PureVis::Public,
            is_async: false,
            is_async_inferred: false,
            is_const: false,
            is_unsafe: false,
            abi: None,
            name: name.to_string(),
            generics: PureGenerics::default(),
            params: vec![],
            ret: None,
            body: PureBlock::default(),
        })
    }

    fn make_path(s: &str) -> SymbolPath {
        SymbolPath::parse(s).unwrap()
    }

    #[test]
    fn test_derive_child_path_default_flat() {
        // Boundary: with no existing_file_keys, modern multi_file uses flat .rs
        let gen = RegistryGenerator::multi_file();
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "models", None),
            "src/models.rs"
        );
        assert_eq!(
            gen.derive_child_path("src/models.rs", "user", None),
            "src/models/user.rs"
        );
    }

    #[test]
    fn test_derive_child_path_respects_existing_mod_rs() {
        // Boundary: when <mod>/mod.rs is in the workspace-wide fallback set,
        // prefer mod.rs over creating a duplicate sibling <mod>.rs.
        let gen = RegistryGenerator::multi_file()
            .with_existing_files(vec!["src/models/mod.rs".to_string()]);
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "models", None),
            "src/models/mod.rs",
            "existing mod.rs must be preferred over flat sibling"
        );
        // A sibling module with no on-disk mod.rs still uses flat default
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "config", None),
            "src/config.rs"
        );
    }

    #[test]
    fn test_derive_child_path_respects_existing_flat() {
        // Boundary: when <mod>.rs is in the workspace-wide fallback set (and
        // use_mod_rs=true), the existing flat layout wins over the legacy mode
        // default.
        let gen = RegistryGenerator::multi_file_mod_rs()
            .with_existing_files(vec!["src/models.rs".to_string()]);
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "models", None),
            "src/models.rs",
            "existing flat layout must override use_mod_rs default"
        );
        // A sibling module with no on-disk entry falls back to use_mod_rs default
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "config", None),
            "src/config/mod.rs"
        );
    }

    #[test]
    fn test_derive_child_path_per_crate_isolation() {
        // Cross-crate contamination scenario (RL061 fix):
        //   crate A (ryo-executor) uses mod.rs layout: executor/mod.rs
        //   crate B (ryo-agent)    uses flat layout:   executor.rs
        //
        // Without per-crate isolation the workspace-wide HashSet merges both
        // keys, so when ryo-agent's layout lookup runs `derive_child_path`
        // first hits `executor/mod.rs` (from ryo-executor) and emits a phantom
        // `executor/mod.rs` next to the existing flat `executor.rs` — the
        // exact bug captured by `sync_phantom_mod_rs_probe.rs`.
        let crate_a = CrateName::new("ryo-executor").unwrap();
        let crate_b = CrateName::new("ryo-agent").unwrap();

        let mut per_crate: HashMap<CrateName, HashSet<String>> = HashMap::new();
        per_crate
            .entry(crate_a.clone())
            .or_default()
            .insert("src/executor/mod.rs".to_string());
        per_crate
            .entry(crate_b.clone())
            .or_default()
            .insert("src/executor.rs".to_string());

        let gen = RegistryGenerator::multi_file().with_existing_files_per_crate(per_crate);

        assert_eq!(
            gen.derive_child_path("src/lib.rs", "executor", Some(&crate_a)),
            "src/executor/mod.rs",
            "crate A must keep mod.rs layout from its own key set",
        );
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "executor", Some(&crate_b)),
            "src/executor.rs",
            "crate B must use flat layout — crate A's mod.rs key MUST NOT bleed here",
        );
    }

    #[test]
    fn test_derive_child_path_per_crate_falls_back_to_workspace_wide() {
        // When a crate has no per-crate entry, fall back to the workspace-wide
        // set populated by the legacy `with_existing_files` API. This
        // preserves the original single-set semantics for unit-test callers.
        let crate_a = CrateName::new("ryo-executor").unwrap();
        let crate_unknown = CrateName::new("unknown-crate").unwrap();

        let mut per_crate: HashMap<CrateName, HashSet<String>> = HashMap::new();
        per_crate
            .entry(crate_a)
            .or_default()
            .insert("src/executor/mod.rs".to_string());

        let gen = RegistryGenerator::multi_file()
            .with_existing_files(vec!["src/storage/mod.rs".to_string()])
            .with_existing_files_per_crate(per_crate);

        // unknown-crate is absent from the per-crate map → workspace-wide
        // fallback applies, so `storage` resolves to its mod.rs layout.
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "storage", Some(&crate_unknown)),
            "src/storage/mod.rs",
            "absent crate must fall back to workspace-wide set",
        );
        // `None` current_crate also falls back to workspace-wide.
        assert_eq!(
            gen.derive_child_path("src/lib.rs", "storage", None),
            "src/storage/mod.rs",
            "None current_crate must fall back to workspace-wide set",
        );
    }

    #[test]
    fn test_single_file_basic() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register symbols
        let config_path = make_path("my_crate::Config");
        let config_id = symbol_registry
            .register(config_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        let helper_path = make_path("my_crate::helper");
        let helper_id = symbol_registry
            .register(helper_path, SymbolKind::Function)
            .unwrap();
        ast_registry.set(helper_id, make_fn("helper"));

        // Generate
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        assert_eq!(workspace.crates.len(), 1);
        let crate_data = workspace.crates.get("my_crate").unwrap();
        assert_eq!(crate_data.files.len(), 1);

        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"));
        assert!(lib.source.contains("fn helper"));
    }

    #[test]
    fn test_single_file_nested_modules() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // my_crate::Config
        let config_path = make_path("my_crate::Config");
        let config_id = symbol_registry
            .register(config_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // my_crate::models::User
        let user_path = make_path("my_crate::models::User");
        let user_id = symbol_registry
            .register(user_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        // my_crate::models::dto::UserDto
        let dto_path = make_path("my_crate::models::dto::UserDto");
        let dto_id = symbol_registry
            .register(dto_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(dto_id, make_struct("UserDto"));

        // Generate
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let lib = workspace
            .crates
            .get("my_crate")
            .unwrap()
            .files
            .get("src/lib.rs")
            .unwrap();

        // Verify structure
        assert!(lib.source.contains("struct Config"));
        assert!(lib.source.contains("mod models"));
        assert!(lib.source.contains("struct User"));
        assert!(lib.source.contains("mod dto"));
        assert!(lib.source.contains("struct UserDto"));

        // Verify it's valid Rust
        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));
    }

    #[test]
    fn test_multi_file_submodule_preserves_inner_attrs() {
        // Boundary regression: submodule files (foo.rs / foo/mod.rs) must
        // preserve `//!` / `#![...]` inner attributes that live on the
        // submodule's Mod symbol. Pre-fix `extract_file_attrs_from_ids` only
        // pulled from crate root Mod, so submodule files lost their `//!`
        // doc on every regeneration.
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Submodule `my_crate::models` with `#![allow(unused)]` inner attr
        let models_mod = PureMod {
            attrs: vec![PureAttribute {
                path: "allow".to_string(),
                meta: PureAttrMeta::List("unused".to_string()),
                is_inner: true,
            }],
            vis: PureVis::Public,
            name: "models".to_string(),
            items: vec![],
            scope: Default::default(),
        };
        let models_id = symbol_registry
            .register(make_path("my_crate::models"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(models_id, PureItem::Mod(models_mod));

        // A child item inside the submodule
        let user_id = symbol_registry
            .register(make_path("my_crate::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let crate_data = workspace.crates.get("my_crate").unwrap();
        let models = crate_data
            .files
            .get("src/models.rs")
            .expect("models.rs should be generated");

        // === Inner attrs must reach the submodule's file ===
        assert!(
            !models.pure_file.attrs.is_empty(),
            "submodule file lost its inner attrs (regression of D-2 `//!` drop)"
        );
        assert!(
            models.pure_file.attrs.iter().all(|a| a.is_inner),
            "all file-level attrs must be inner: {:?}",
            models.pure_file.attrs
        );
        assert_eq!(models.pure_file.attrs[0].path, "allow");
        assert!(models.source.contains("allow(unused)"));
    }

    #[test]
    fn test_multi_file_modern_style() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // my_crate::Config
        let config_path = make_path("my_crate::Config");
        let config_id = symbol_registry
            .register(config_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // my_crate::models::User
        let user_path = make_path("my_crate::models::User");
        let user_id = symbol_registry
            .register(user_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // Should have: lib.rs and models.rs
        assert_eq!(crate_data.files.len(), 2);
        assert!(crate_data.files.contains_key("src/lib.rs"));
        assert!(crate_data.files.contains_key("src/models.rs"));

        // lib.rs has Config and mod models declaration
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"));
        assert!(lib.source.contains("mod models;"));

        // models.rs has User
        let models = crate_data.files.get("src/models.rs").unwrap();
        assert!(models.source.contains("struct User"));
    }

    #[test]
    fn test_multi_crate() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // crate_a::Foo
        let foo_path = make_path("crate_a::Foo");
        let foo_id = symbol_registry
            .register(foo_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(foo_id, make_struct("Foo"));

        // crate_b::Bar
        let bar_path = make_path("crate_b::Bar");
        let bar_id = symbol_registry
            .register(bar_path, SymbolKind::Struct)
            .unwrap();
        ast_registry.set(bar_id, make_struct("Bar"));

        // Generate
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // Should have 2 crates
        assert_eq!(workspace.crates.len(), 2);
        assert!(workspace.crates.contains_key("crate_a"));
        assert!(workspace.crates.contains_key("crate_b"));

        // Each with their respective symbols
        let crate_a = workspace.crates.get("crate_a").unwrap();
        assert!(crate_a
            .files
            .get("src/lib.rs")
            .unwrap()
            .source
            .contains("struct Foo"));

        let crate_b = workspace.crates.get("crate_b").unwrap();
        assert!(crate_b
            .files
            .get("src/lib.rs")
            .unwrap()
            .source
            .contains("struct Bar"));
    }

    #[test]
    fn test_all_generated_valid_rust() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Build a complex structure
        for (path, name) in [
            ("app::Config", "Config"),
            ("app::models::User", "User"),
            ("app::models::Post", "Post"),
            ("app::models::dto::UserDto", "UserDto"),
            ("app::utils::helpers::format", "format"),
        ] {
            let sp = make_path(path);
            let kind = if name == "format" {
                SymbolKind::Function
            } else {
                SymbolKind::Struct
            };
            let id = symbol_registry.register(sp, kind).unwrap();
            if name == "format" {
                ast_registry.set(id, make_fn(name));
            } else {
                ast_registry.set(id, make_struct(name));
            }
        }

        // Test both single and multi file
        for generator in [
            RegistryGenerator::single_file(),
            RegistryGenerator::multi_file(),
            RegistryGenerator::multi_file_mod_rs(),
        ] {
            let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

            for (crate_name, path, file) in workspace.iter_files() {
                syn::parse_str::<syn::File>(&file.source).unwrap_or_else(|_| {
                    panic!(
                        "[{}] {} should be valid Rust:\n{}",
                        crate_name, path, file.source
                    )
                });
            }
        }
    }

    // ========================================================================
    // AddMod / RemoveMod Tests - No Span Manipulation Required!
    // ========================================================================

    /// Test: Adding a new module by just registering symbols.
    ///
    /// This proves that file creation is automatic from SymbolPath -
    /// no span manipulation or file creation needed.
    #[test]
    fn test_add_mod_no_span_required() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Initial state: just Config at root
        let config_id = symbol_registry
            .register(make_path("app::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Generate initial state
        let generator = RegistryGenerator::multi_file();
        let before = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // Before: only lib.rs
        assert_eq!(before.crates.get("app").unwrap().files.len(), 1);
        assert!(before
            .crates
            .get("app")
            .unwrap()
            .files
            .contains_key("src/lib.rs"));

        // === AddMod: Just register new symbols under new module path ===
        // No span manipulation! No file creation! Just registry operations!
        let user_id = symbol_registry
            .register(make_path("app::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        let post_id = symbol_registry
            .register(make_path("app::models::Post"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(post_id, make_struct("Post"));

        // Generate after AddMod
        let after = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // After: lib.rs AND models.rs automatically created!
        let app = after.crates.get("app").unwrap();
        assert_eq!(app.files.len(), 2);
        assert!(app.files.contains_key("src/lib.rs"));
        assert!(app.files.contains_key("src/models.rs")); // NEW FILE - auto generated!

        // lib.rs now has mod declaration
        let lib = app.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"));
        assert!(lib.source.contains("mod models;"));

        // models.rs has the new symbols
        let models = app.files.get("src/models.rs").unwrap();
        assert!(models.source.contains("struct User"));
        assert!(models.source.contains("struct Post"));

        // All valid Rust
        syn::parse_str::<syn::File>(&lib.source).unwrap();
        syn::parse_str::<syn::File>(&models.source).unwrap();
    }

    /// Test: Adding deeply nested modules automatically creates file hierarchy.
    #[test]
    fn test_add_nested_mod_no_span_required() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Initial: empty crate (just need one symbol to have a crate)
        let config_id = symbol_registry
            .register(make_path("app::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Add deeply nested module: app::api::v1::handlers::UserHandler
        let handler_id = symbol_registry
            .register(
                make_path("app::api::v1::handlers::UserHandler"),
                SymbolKind::Struct,
            )
            .unwrap();
        ast_registry.set(handler_id, make_struct("UserHandler"));

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let app = workspace.crates.get("app").unwrap();

        // Should have: lib.rs, api.rs, api/v1.rs, api/v1/handlers.rs
        assert_eq!(app.files.len(), 4);
        assert!(app.files.contains_key("src/lib.rs"));
        assert!(app.files.contains_key("src/api.rs"));
        assert!(app.files.contains_key("src/api/v1.rs"));
        assert!(app.files.contains_key("src/api/v1/handlers.rs"));

        // Verify chain of mod declarations
        assert!(app
            .files
            .get("src/lib.rs")
            .unwrap()
            .source
            .contains("mod api;"));
        assert!(app
            .files
            .get("src/api.rs")
            .unwrap()
            .source
            .contains("mod v1;"));
        assert!(app
            .files
            .get("src/api/v1.rs")
            .unwrap()
            .source
            .contains("mod handlers;"));
        assert!(app
            .files
            .get("src/api/v1/handlers.rs")
            .unwrap()
            .source
            .contains("struct UserHandler"));

        // All valid Rust
        for file in app.files.values() {
            syn::parse_str::<syn::File>(&file.source).unwrap();
        }
    }

    /// Test: Removing a module by removing symbols from registries.
    ///
    /// This proves that file deletion is automatic - when no symbols exist
    /// under a path, the file disappears from generation.
    #[test]
    fn test_remove_mod_no_span_required() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Initial state: Config + models module with User
        let config_id = symbol_registry
            .register(make_path("app::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        let user_id = symbol_registry
            .register(make_path("app::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        // Generate before removal
        let generator = RegistryGenerator::multi_file();
        let before = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // Before: lib.rs + models.rs
        assert_eq!(before.crates.get("app").unwrap().files.len(), 2);

        // === RemoveMod: Just remove symbols from registries ===
        // No span manipulation! No file deletion! Just registry operations!
        ast_registry.remove(user_id);
        symbol_registry.remove(user_id);

        // Generate after RemoveMod
        let after = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // After: only lib.rs (models.rs automatically gone!)
        let app = after.crates.get("app").unwrap();
        assert_eq!(app.files.len(), 1);
        assert!(app.files.contains_key("src/lib.rs"));
        assert!(!app.files.contains_key("src/models.rs")); // REMOVED - auto!

        // lib.rs no longer has mod declaration
        let lib = app.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"));
        assert!(!lib.source.contains("mod models")); // mod declaration gone!

        syn::parse_str::<syn::File>(&lib.source).unwrap();
    }

    /// Test: Partial module removal (some symbols remain).
    #[test]
    fn test_partial_remove_mod() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Initial: models with User and Post
        let config_id = symbol_registry
            .register(make_path("app::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        let user_id = symbol_registry
            .register(make_path("app::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        let post_id = symbol_registry
            .register(make_path("app::models::Post"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(post_id, make_struct("Post"));

        // Remove only User, keep Post
        ast_registry.remove(user_id);
        symbol_registry.remove(user_id);

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let app = workspace.crates.get("app").unwrap();

        // models.rs still exists (Post remains)
        assert_eq!(app.files.len(), 2);
        assert!(app.files.contains_key("src/models.rs"));

        let models = app.files.get("src/models.rs").unwrap();
        assert!(!models.source.contains("struct User")); // User removed
        assert!(models.source.contains("struct Post")); // Post remains

        syn::parse_str::<syn::File>(&models.source).unwrap();
    }

    // ========================================================================
    // Main Entry Point Tests (main:: prefix)
    // ========================================================================

    /// Test: Binary entry point (main::crate::...) outputs to main.rs
    #[test]
    fn test_main_entry_point() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Library symbol: my_crate::Config -> lib.rs
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Binary symbol: main::my_crate::main -> main.rs
        let main_id = symbol_registry
            .register(make_path("main::my_crate::main"), SymbolKind::Function)
            .unwrap();
        ast_registry.set(main_id, make_fn("main"));

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        // Should have one crate with both lib.rs and main.rs
        assert_eq!(workspace.crates.len(), 1);
        let crate_data = workspace.crates.get("my_crate").unwrap();

        assert!(crate_data.files.contains_key("src/lib.rs"));
        assert!(crate_data.files.contains_key("src/main.rs"));

        // lib.rs has Config
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"));
        assert!(!lib.source.contains("fn main"));

        // main.rs has main function
        let main = crate_data.files.get("src/main.rs").unwrap();
        assert!(main.source.contains("fn main"));
        assert!(!main.source.contains("struct Config"));

        // Both valid Rust
        syn::parse_str::<syn::File>(&lib.source).unwrap();
        syn::parse_str::<syn::File>(&main.source).unwrap();
    }

    /// Test: main.rs with nested modules
    #[test]
    fn test_main_with_modules() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // main::my_crate::main
        let main_id = symbol_registry
            .register(make_path("main::my_crate::main"), SymbolKind::Function)
            .unwrap();
        ast_registry.set(main_id, make_fn("main"));

        // main::my_crate::cli::Args (module in main.rs)
        let args_id = symbol_registry
            .register(make_path("main::my_crate::cli::Args"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(args_id, make_struct("Args"));

        // Generate (single file mode)
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();
        let main = crate_data.files.get("src/main.rs").unwrap();

        // main.rs should have main function and cli module
        assert!(main.source.contains("fn main"));
        assert!(main.source.contains("mod cli"));
        assert!(main.source.contains("struct Args"));

        syn::parse_str::<syn::File>(&main.source).unwrap();
    }

    /// Test: Multi-file mode with main.rs modules
    #[test]
    fn test_main_multi_file_modules() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // main::my_crate::main
        let main_id = symbol_registry
            .register(make_path("main::my_crate::main"), SymbolKind::Function)
            .unwrap();
        ast_registry.set(main_id, make_fn("main"));

        // main::my_crate::cli::Args
        let args_id = symbol_registry
            .register(make_path("main::my_crate::cli::Args"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(args_id, make_struct("Args"));

        // Generate (multi-file mode)
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // Should have main.rs and cli.rs
        assert!(crate_data.files.contains_key("src/main.rs"));
        assert!(crate_data.files.contains_key("src/cli.rs"));

        // main.rs has main and mod declaration
        let main = crate_data.files.get("src/main.rs").unwrap();
        assert!(main.source.contains("fn main"));
        assert!(main.source.contains("mod cli;"));

        // cli.rs has Args
        let cli = crate_data.files.get("src/cli.rs").unwrap();
        assert!(cli.source.contains("struct Args"));

        // All valid Rust
        syn::parse_str::<syn::File>(&main.source).unwrap();
        syn::parse_str::<syn::File>(&cli.source).unwrap();
    }

    /// Test: Both lib.rs and main.rs with separate module trees
    #[test]
    fn test_lib_and_main_separate_modules() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Library: my_crate::lib_mod::LibStruct
        let lib_id = symbol_registry
            .register(
                make_path("my_crate::lib_mod::LibStruct"),
                SymbolKind::Struct,
            )
            .unwrap();
        ast_registry.set(lib_id, make_struct("LibStruct"));

        // Binary: main::my_crate::bin_mod::BinStruct
        let bin_id = symbol_registry
            .register(
                make_path("main::my_crate::bin_mod::BinStruct"),
                SymbolKind::Struct,
            )
            .unwrap();
        ast_registry.set(bin_id, make_struct("BinStruct"));

        // Generate
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // Should have 4 files: lib.rs, lib_mod.rs, main.rs, bin_mod.rs
        assert_eq!(crate_data.files.len(), 4);
        assert!(crate_data.files.contains_key("src/lib.rs"));
        assert!(crate_data.files.contains_key("src/lib_mod.rs"));
        assert!(crate_data.files.contains_key("src/main.rs"));
        assert!(crate_data.files.contains_key("src/bin_mod.rs"));

        // lib.rs has mod lib_mod
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("mod lib_mod;"));
        assert!(!lib.source.contains("mod bin_mod"));

        // main.rs has mod bin_mod
        let main = crate_data.files.get("src/main.rs").unwrap();
        assert!(main.source.contains("mod bin_mod;"));
        assert!(!main.source.contains("mod lib_mod"));

        // Modules have correct content
        assert!(crate_data
            .files
            .get("src/lib_mod.rs")
            .unwrap()
            .source
            .contains("struct LibStruct"));
        assert!(crate_data
            .files
            .get("src/bin_mod.rs")
            .unwrap()
            .source
            .contains("struct BinStruct"));

        // All valid Rust
        for file in crate_data.files.values() {
            syn::parse_str::<syn::File>(&file.source).unwrap();
        }
    }

    /// Test: Move symbol between modules (remove from one, add to another).
    #[test]
    fn test_move_symbol_between_modules() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Initial: User in models
        let config_id = symbol_registry
            .register(make_path("app::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        let user_id = symbol_registry
            .register(make_path("app::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));

        let generator = RegistryGenerator::multi_file();

        // Before: User in models
        let before = generator.generate(&ast_registry, &symbol_registry).unwrap();
        assert!(before
            .crates
            .get("app")
            .unwrap()
            .files
            .contains_key("src/models.rs"));

        // === Move: Remove from models, add to entities ===
        ast_registry.remove(user_id);
        symbol_registry.remove(user_id);

        let new_user_id = symbol_registry
            .register(make_path("app::entities::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(new_user_id, make_struct("User"));

        // After: User in entities, models gone
        let after = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let app = after.crates.get("app").unwrap();

        assert!(!app.files.contains_key("src/models.rs")); // Old module gone
        assert!(app.files.contains_key("src/entities.rs")); // New module created

        let entities = app.files.get("src/entities.rs").unwrap();
        assert!(entities.source.contains("struct User"));

        // lib.rs updated
        let lib = app.files.get("src/lib.rs").unwrap();
        assert!(!lib.source.contains("mod models"));
        assert!(lib.source.contains("mod entities;"));

        syn::parse_str::<syn::File>(&lib.source).unwrap();
        syn::parse_str::<syn::File>(&entities.source).unwrap();
    }

    // ========================================================================
    // Adapter Method Tests (dump_to_workspace_files)
    // ========================================================================
    // CodeGraphV2-based generation tests (generate_with_graph)
    // ========================================================================

    use ryo_analysis::{CodeEdgeV2, CodeGraphV2};

    fn setup_registries_with_graph() -> (ASTRegistry, SymbolRegistry, CodeGraphV2) {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();
        let mut code_graph = CodeGraphV2::new();

        // Register crate root module
        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        code_graph.add_node(crate_id);
        code_graph.add_crate_root(crate_id);

        // Root level struct
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));
        code_graph.add_node(config_id);
        code_graph.add_edge(crate_id, config_id, CodeEdgeV2::Contains);

        // Module
        let models_id = symbol_registry
            .register(make_path("my_crate::models"), SymbolKind::Mod)
            .unwrap();
        code_graph.add_node(models_id);
        code_graph.add_edge(crate_id, models_id, CodeEdgeV2::Contains);

        // Item in module
        let user_id = symbol_registry
            .register(make_path("my_crate::models::User"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(user_id, make_struct("User"));
        code_graph.add_node(user_id);
        code_graph.add_edge(models_id, user_id, CodeEdgeV2::Contains);

        (ast_registry, symbol_registry, code_graph)
    }

    #[test]
    fn test_generate_with_graph_single_file() {
        let (ast_registry, symbol_registry, code_graph) = setup_registries_with_graph();

        let generator = RegistryGenerator::single_file();
        let workspace = generator
            .generate_with_graph(&code_graph, &ast_registry, &symbol_registry)
            .unwrap();

        assert_eq!(workspace.crates.len(), 1);
        let crate_data = workspace.crates.get("my_crate").unwrap();
        assert_eq!(crate_data.files.len(), 1);

        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(lib.source.contains("struct Config"), "Should have Config");
        assert!(lib.source.contains("mod models"), "Should have mod models");
        assert!(
            lib.source.contains("struct User"),
            "Should have User in nested mod"
        );

        // Verify valid Rust
        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));
    }

    #[test]
    fn test_generate_with_graph_multi_file() {
        let (ast_registry, symbol_registry, code_graph) = setup_registries_with_graph();

        let generator = RegistryGenerator::multi_file();
        let workspace = generator
            .generate_with_graph(&code_graph, &ast_registry, &symbol_registry)
            .unwrap();

        assert_eq!(workspace.crates.len(), 1);
        let crate_data = workspace.crates.get("my_crate").unwrap();
        assert_eq!(
            crate_data.files.len(),
            2,
            "Should have lib.rs and models.rs"
        );

        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(
            lib.source.contains("struct Config"),
            "lib.rs should have Config"
        );
        assert!(
            lib.source.contains("mod models;"),
            "lib.rs should have mod declaration"
        );

        let models = crate_data.files.get("src/models.rs").unwrap();
        assert!(
            models.source.contains("struct User"),
            "models.rs should have User"
        );

        // Verify valid Rust
        syn::parse_str::<syn::File>(&lib.source).unwrap();
        syn::parse_str::<syn::File>(&models.source).unwrap();
    }

    #[test]
    fn test_generate_with_graph_matches_original() {
        let (ast_registry, symbol_registry, code_graph) = setup_registries_with_graph();

        let generator = RegistryGenerator::single_file();

        // Generate with both methods
        let original = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let with_graph = generator
            .generate_with_graph(&code_graph, &ast_registry, &symbol_registry)
            .unwrap();

        // Same number of crates
        assert_eq!(original.crates.len(), with_graph.crates.len());

        // Same crate names
        for crate_name in original.crates.keys() {
            assert!(with_graph.crates.contains_key(crate_name));
        }
    }

    // ========================================================================
    // SameAST → SameOutput Tests - Inline Test Module (Idempotent Generation)
    // ========================================================================

    use ryo_source::pure::{
        PureAttrMeta, PureAttribute, PureField, PureImpl, PureImplItem, PureTupleField, PureType,
        PureUse, PureUseTree,
    };

    /// Build inline test module AST manually for testing generator output.
    ///
    /// `attrs` is empty: `#[cfg(test)]` is injected by the emitter (`ToSyn for PureMod`)
    /// when `scope == ModScope::Test`.  Storing the attribute redundantly in `attrs` is
    /// no longer necessary since the `ModScope` migration and would duplicate the output.
    fn make_inline_test_module() -> PureMod {
        PureMod {
            attrs: vec![],
            vis: PureVis::Private,
            name: "tests".to_string(),
            items: vec![
                PureItem::Use(PureUse {
                    vis: PureVis::Private,
                    tree: PureUseTree::Path {
                        path: "super".to_string(),
                        tree: Box::new(PureUseTree::Glob),
                    },
                }),
                PureItem::Fn(PureFn {
                    attrs: vec![PureAttribute {
                        path: "test".to_string(),
                        meta: PureAttrMeta::Path,
                        is_inner: false,
                    }],
                    vis: PureVis::Private,
                    is_async: false,
                    is_async_inferred: false,
                    is_const: false,
                    is_unsafe: false,
                    abi: None,
                    name: "test_config".to_string(),
                    generics: PureGenerics::default(),
                    params: vec![],
                    ret: None,
                    body: PureBlock::default(),
                }),
            ],
            scope: ModScope::Test,
        }
    }

    /// Test: #[cfg(test)] inline module outputs correctly with attributes preserved
    #[test]
    fn test_inline_test_module_idempotent_output() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register and set Config struct
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Register tests module and mark as inline
        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(make_inline_test_module()));
        ast_registry.mark_inline_module(tests_id);

        // Generate output
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // Verify output is valid Rust
        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));

        // Verify Config struct is present
        assert!(
            lib.source.contains("struct Config"),
            "Output should contain Config struct"
        );

        // Verify tests module is inline (not mod tests;)
        assert!(
            lib.source.contains("mod tests {"),
            "Output should have inline mod tests, got:\n{}",
            lib.source
        );

        // Verify #[cfg(test)] attribute is preserved
        assert!(
            lib.source.contains("#[cfg(test)]"),
            "Output should preserve #[cfg(test)] attribute, got:\n{}",
            lib.source
        );

        // Verify test_config function is present
        assert!(
            lib.source.contains("fn test_config"),
            "Output should contain test_config function"
        );

        // Verify #[test] attribute is preserved
        assert!(
            lib.source.contains("#[test]"),
            "Output should preserve #[test] attribute, got:\n{}",
            lib.source
        );

        // === Idempotency test: generate again, should be identical ===
        let workspace2 = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let lib2 = workspace2
            .crates
            .get("my_crate")
            .unwrap()
            .files
            .get("src/lib.rs")
            .unwrap();

        assert_eq!(
            lib.source, lib2.source,
            "Idempotent: same AST should produce identical output"
        );
    }

    /// Test: empty `#[cfg(test)] mod tests;` declaration is preserved in single-file
    /// output. Regression guard for `collect_items_recursive` filter — previously the
    /// filter `!m.items.is_empty()` silently dropped Test-scoped empty mod declarations,
    /// breaking round-trip for the common `#[cfg(test)] mod tests;` (with separate
    /// tests.rs) pattern when regenerating as a single file.
    #[test]
    fn test_empty_cfg_test_mod_preserved_in_single_file() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register a struct so the crate has at least one Prod item.
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Register `#[cfg(test)] mod tests;` — empty items, scope=Test.
        // `attrs` is empty: the emitter re-injects #[cfg(test)] from scope.
        let tests_mod = PureMod {
            attrs: vec![],
            vis: PureVis::Private,
            name: "tests".to_string(),
            items: vec![],
            scope: ModScope::Test,
        };
        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(tests_mod));
        ast_registry.mark_inline_module(tests_id);

        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let lib = workspace
            .crates
            .get("my_crate")
            .unwrap()
            .files
            .get("src/lib.rs")
            .unwrap();

        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));

        // The mod tests declaration must survive (regression target).
        let has_mod_tests = lib
            .pure_file
            .items
            .iter()
            .any(|item| matches!(item, PureItem::Mod(m) if m.name == "tests"));
        assert!(
            has_mod_tests,
            "Empty #[cfg(test)] mod tests; must be preserved in single-file output, got:\n{}",
            lib.source
        );

        // And #[cfg(test)] must be emitted on it.
        assert!(
            lib.source.contains("#[cfg(test)]"),
            "Output should preserve #[cfg(test)] attribute, got:\n{}",
            lib.source
        );
    }

    /// Test: Inline module with impl block outputs correctly
    #[test]
    fn test_inline_module_with_impl_idempotent_output() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Build tests module with struct + impl
        let tests_mod = PureMod {
            attrs: vec![PureAttribute {
                path: "cfg".to_string(),
                meta: PureAttrMeta::List("test".to_string()),
                is_inner: false,
            }],
            vis: PureVis::Private,
            name: "tests".to_string(),
            items: vec![
                PureItem::Struct(PureStruct {
                    attrs: vec![],
                    vis: PureVis::Private,
                    name: "TestHelper".to_string(),
                    generics: PureGenerics::default(),
                    fields: PureFields::Named(vec![PureField {
                        attrs: vec![],
                        vis: PureVis::Private,
                        name: "value".to_string(),
                        ty: PureType::Path("i32".to_string()),
                    }]),
                }),
                PureItem::Impl(PureImpl {
                    attrs: vec![],
                    generics: PureGenerics::default(),
                    is_unsafe: false,
                    trait_: None,
                    self_ty: "TestHelper".to_string(),
                    items: vec![PureImplItem::Fn(PureFn {
                        attrs: vec![],
                        vis: PureVis::Private,
                        is_async: false,
                        is_async_inferred: false,
                        is_const: false,
                        is_unsafe: false,
                        abi: None,
                        name: "new".to_string(),
                        generics: PureGenerics::default(),
                        params: vec![],
                        ret: Some(PureType::Path("Self".to_string())),
                        body: PureBlock::default(),
                    })],
                }),
                PureItem::Fn(PureFn {
                    attrs: vec![PureAttribute {
                        path: "test".to_string(),
                        meta: PureAttrMeta::Path,
                        is_inner: false,
                    }],
                    vis: PureVis::Private,
                    is_async: false,
                    is_async_inferred: false,
                    is_const: false,
                    is_unsafe: false,
                    abi: None,
                    name: "test_with_helper".to_string(),
                    generics: PureGenerics::default(),
                    params: vec![],
                    ret: None,
                    body: PureBlock::default(),
                }),
            ],
            scope: ModScope::Test,
        };

        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(tests_mod));
        ast_registry.mark_inline_module(tests_id);

        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // Verify valid Rust
        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));

        // Verify structure
        assert!(lib.source.contains("struct Config"));
        assert!(lib.source.contains("#[cfg(test)]"));
        assert!(lib.source.contains("mod tests {"));
        assert!(lib.source.contains("struct TestHelper"));
        assert!(lib.source.contains("impl TestHelper"));
        assert!(lib.source.contains("fn new"));
        assert!(lib.source.contains("fn test_with_helper"));

        // Idempotency
        let workspace2 = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let lib2 = workspace2
            .crates
            .get("my_crate")
            .unwrap()
            .files
            .get("src/lib.rs")
            .unwrap();
        assert_eq!(lib.source, lib2.source, "Idempotent output");
    }

    /// Test: Multi-file mode keeps inline modules inline (doesn't create separate files)
    #[test]
    fn test_inline_module_multi_file_no_separate_file() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // External module (utils) - will get separate file
        let utils_id = symbol_registry
            .register(make_path("my_crate::utils"), SymbolKind::Mod)
            .unwrap();
        // Set empty PureMod (external module declaration)
        ast_registry.set(
            utils_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "utils".to_string(),
                items: vec![], // Empty = external module
                scope: Default::default(),
            }),
        );

        let helper_id = symbol_registry
            .register(make_path("my_crate::utils::helper"), SymbolKind::Function)
            .unwrap();
        ast_registry.set(helper_id, make_fn("helper"));

        // Inline module (tests) - stays inline
        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(make_inline_test_module()));
        ast_registry.mark_inline_module(tests_id);

        // Use multi-file mode
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // Should have lib.rs and utils.rs, but NOT tests.rs
        assert!(
            crate_data.files.contains_key("src/lib.rs"),
            "Should have lib.rs"
        );
        assert!(
            crate_data.files.contains_key("src/utils.rs"),
            "Should have utils.rs (external module)"
        );
        assert!(
            !crate_data.files.contains_key("src/tests.rs"),
            "Should NOT have tests.rs (inline module stays inline)"
        );

        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // lib.rs should have inline tests module (not mod tests;)
        assert!(
            lib.source.contains("mod tests {"),
            "tests should be inline, got:\n{}",
            lib.source
        );

        // lib.rs should have #[cfg(test)] attribute
        assert!(
            lib.source.contains("#[cfg(test)]"),
            "Should preserve #[cfg(test)], got:\n{}",
            lib.source
        );

        // lib.rs should have mod utils; declaration (external)
        assert!(
            lib.source.contains("mod utils;"),
            "Should have mod utils; declaration, got:\n{}",
            lib.source
        );

        // Verify all files are valid Rust
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Boundary regression: sibling modules sharing a last segment must NOT be
    /// conflated when one is inline and the other is external.
    ///
    /// Layout:
    /// - `my_crate::foo::tests` — inline (`mark_inline_module`)
    /// - `my_crate::bar::tests` — external (NOT marked inline; contains `helper` fn)
    ///
    /// Pre-fix bug: `inline_mod_names` collected only last segments, so
    /// `{"tests"}` would match both, and `bar::tests` was incorrectly skipped —
    /// no `src/bar/tests.rs` file emitted, and no `mod tests;` declaration in
    /// `src/bar.rs`. After the fix, `known_inline_mods` carries full segment
    /// vectors so `["bar", "tests"]` is distinct from `["foo", "tests"]`.
    #[test]
    fn test_inline_sibling_last_segment_collision() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // foo (external module, parent of inline tests)
        let foo_id = symbol_registry
            .register(make_path("my_crate::foo"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            foo_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "foo".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );

        // foo::tests — inline
        let foo_tests_id = symbol_registry
            .register(make_path("my_crate::foo::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(foo_tests_id, PureItem::Mod(make_inline_test_module()));
        ast_registry.mark_inline_module(foo_tests_id);

        // bar (external module, parent of external tests)
        let bar_id = symbol_registry
            .register(make_path("my_crate::bar"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            bar_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "bar".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );

        // bar::tests — external (NOT marked inline)
        let bar_tests_id = symbol_registry
            .register(make_path("my_crate::bar::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            bar_tests_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Private,
                name: "tests".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );

        // Something inside bar::tests so the file has content
        let helper_id = symbol_registry
            .register(
                make_path("my_crate::bar::tests::helper"),
                SymbolKind::Function,
            )
            .unwrap();
        ast_registry.set(helper_id, make_fn("helper"));

        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();
        let crate_data = workspace.crates.get("my_crate").unwrap();

        // foo::tests stays inline — no separate file under foo/
        assert!(
            !crate_data.files.contains_key("src/foo/tests.rs"),
            "foo::tests is inline; src/foo/tests.rs must not be generated. Files: {:?}",
            crate_data.files.keys().collect::<Vec<_>>()
        );

        // bar::tests is external — must get a separate file. With the pre-fix
        // bug, the `"tests"` last-segment collision would skip this file.
        let bar_tests_key = if crate_data.files.contains_key("src/bar/tests.rs") {
            "src/bar/tests.rs"
        } else if crate_data.files.contains_key("src/bar/tests/mod.rs") {
            "src/bar/tests/mod.rs"
        } else {
            panic!(
                "bar::tests is external; expected src/bar/tests.rs or src/bar/tests/mod.rs. Files: {:?}",
                crate_data.files.keys().collect::<Vec<_>>()
            );
        };
        let bar_tests = crate_data.files.get(bar_tests_key).unwrap();
        assert!(
            bar_tests.source.contains("fn helper"),
            "bar::tests file should contain helper fn, got:\n{}",
            bar_tests.source
        );

        // bar.rs must carry `mod tests;` (or `pub mod tests;`) declaration —
        // pre-fix bug skipped this declaration via the collision.
        let bar_key = if crate_data.files.contains_key("src/bar.rs") {
            "src/bar.rs"
        } else if crate_data.files.contains_key("src/bar/mod.rs") {
            "src/bar/mod.rs"
        } else {
            panic!(
                "bar parent module file missing. Files: {:?}",
                crate_data.files.keys().collect::<Vec<_>>()
            );
        };
        let bar_src = &crate_data.files.get(bar_key).unwrap().source;
        assert!(
            bar_src.contains("mod tests"),
            "{} should declare `mod tests`, got:\n{}",
            bar_key,
            bar_src
        );
        assert!(
            !bar_src.contains("mod tests {"),
            "{} must NOT inline tests (external module); got:\n{}",
            bar_key,
            bar_src
        );

        // foo's parent file must still inline `mod tests { ... }`.
        let foo_key = if crate_data.files.contains_key("src/foo.rs") {
            "src/foo.rs"
        } else if crate_data.files.contains_key("src/foo/mod.rs") {
            "src/foo/mod.rs"
        } else {
            panic!(
                "foo parent module file missing. Files: {:?}",
                crate_data.files.keys().collect::<Vec<_>>()
            );
        };
        let foo_src = &crate_data.files.get(foo_key).unwrap().source;
        assert!(
            foo_src.contains("mod tests {"),
            "{} should inline `mod tests {{ ... }}`, got:\n{}",
            foo_key,
            foo_src
        );

        // All generated files parse as valid Rust.
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Test: External module declaration preserves attributes (#[cfg(test)] mod tests;)
    #[test]
    fn test_external_mod_preserves_attrs() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register external tests module with #[cfg(test)] attribute
        let tests_mod = PureMod {
            attrs: vec![PureAttribute {
                path: "cfg".to_string(),
                meta: PureAttrMeta::List("test".to_string()),
                is_inner: false, // Outer attribute for mod declaration
            }],
            vis: PureVis::Private,
            name: "tests".to_string(),
            items: vec![], // Empty = external module
            scope: ModScope::Test,
        };

        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(tests_mod));
        // NOT marked as inline - this is an external module

        // Register a struct inside tests module
        let helper_id = symbol_registry
            .register(make_path("my_crate::tests::TestHelper"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(helper_id, make_struct("TestHelper"));

        // Generate multi-file
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // === Verify PureFile structure directly ===
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // File-level attrs should be empty (no inner attrs on crate root)
        assert_eq!(
            lib.pure_file.attrs.len(),
            0,
            "lib.rs should have no file-level attrs, got: {:?}",
            lib.pure_file.attrs
        );

        // Find mod tests declaration
        let tests_mod_item = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "tests" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod tests in lib.rs");

        // Verify mod tests is external (empty items)
        assert!(
            tests_mod_item.items.is_empty(),
            "External mod should have empty items"
        );

        // Verify outer attribute count (exactly 1)
        assert_eq!(
            tests_mod_item.attrs.len(),
            1,
            "mod tests should have exactly 1 attribute, got: {:?}",
            tests_mod_item.attrs
        );

        // Verify attribute content
        let attr = &tests_mod_item.attrs[0];
        assert_eq!(attr.path, "cfg", "Attr path should be 'cfg'");
        assert!(!attr.is_inner, "Should be outer attribute");
        assert!(
            matches!(&attr.meta, PureAttrMeta::List(s) if s == "test"),
            "Attr meta should be List(\"test\"), got: {:?}",
            attr.meta
        );

        // Verify tests.rs exists
        assert!(
            crate_data.files.contains_key("src/tests.rs"),
            "Should have tests.rs for external module"
        );

        // Verify all files are valid Rust
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Test: Inner attributes (#![allow(...)]) are preserved at file level
    /// Verifies PureFile.attrs structure directly.
    #[test]
    fn test_inner_attrs_at_file_level() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root with inner attributes
        let crate_mod = PureMod {
            attrs: vec![
                PureAttribute {
                    path: "allow".to_string(),
                    meta: PureAttrMeta::List("dead_code".to_string()),
                    is_inner: true, // Inner attribute for file
                },
                PureAttribute {
                    path: "warn".to_string(),
                    meta: PureAttrMeta::List("unused_variables".to_string()),
                    is_inner: true,
                },
            ],
            vis: PureVis::Public,
            name: "my_crate".to_string(),
            items: vec![],
            scope: Default::default(),
        };

        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(crate_id, PureItem::Mod(crate_mod));

        // Register a struct
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Generate single file
        let generator = RegistryGenerator::single_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // === Verify PureFile.attrs structure directly ===
        assert_eq!(
            lib.pure_file.attrs.len(),
            2,
            "lib.rs should have exactly 2 file-level attrs, got: {:?}",
            lib.pure_file.attrs
        );

        // All file-level attrs should be inner
        for attr in &lib.pure_file.attrs {
            assert!(attr.is_inner, "File-level attr should be inner: {:?}", attr);
        }

        // Verify first attr: #![allow(dead_code)]
        let attr0 = &lib.pure_file.attrs[0];
        assert_eq!(attr0.path, "allow");
        assert!(matches!(&attr0.meta, PureAttrMeta::List(s) if s == "dead_code"));

        // Verify second attr: #![warn(unused_variables)]
        let attr1 = &lib.pure_file.attrs[1];
        assert_eq!(attr1.path, "warn");
        assert!(matches!(&attr1.meta, PureAttrMeta::List(s) if s == "unused_variables"));

        // Verify valid Rust
        syn::parse_str::<syn::File>(&lib.source)
            .unwrap_or_else(|_| panic!("Should be valid Rust:\n{}", lib.source));
    }

    /// Test: Mixed outer and inner attributes are correctly separated
    /// - Outer attrs (#[...]) → mod declaration
    /// - Inner attrs (#![...]) → file level of the module's file
    #[test]
    fn test_mixed_outer_inner_attrs_separation() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register utils module with BOTH outer and inner attributes
        let utils_mod = PureMod {
            attrs: vec![
                // Outer: goes to mod declaration in parent (#[doc = "..."] mod utils;)
                PureAttribute {
                    path: "doc".to_string(),
                    meta: PureAttrMeta::NameValue("\"Utils module\"".to_string()),
                    is_inner: false,
                },
                // Inner: goes to file level in utils.rs (#![allow(dead_code)])
                PureAttribute {
                    path: "allow".to_string(),
                    meta: PureAttrMeta::List("dead_code".to_string()),
                    is_inner: true,
                },
                // Another outer
                PureAttribute {
                    path: "cfg".to_string(),
                    meta: PureAttrMeta::List("feature = \"utils\"".to_string()),
                    is_inner: false,
                },
            ],
            vis: PureVis::Public,
            name: "utils".to_string(),
            items: vec![], // External module
            scope: Default::default(),
        };

        let utils_id = symbol_registry
            .register(make_path("my_crate::utils"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(utils_id, PureItem::Mod(utils_mod));

        // Register a function inside utils
        let helper_fn_id = symbol_registry
            .register(make_path("my_crate::utils::helper"), SymbolKind::Function)
            .unwrap();
        ast_registry.set(helper_fn_id, make_fn("helper"));

        // Generate multi-file
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // === Check lib.rs: mod utils declaration should have ONLY outer attrs ===
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        let utils_mod_decl = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "utils" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod utils in lib.rs");

        // Should have exactly 2 outer attrs (doc and cfg)
        assert_eq!(
            utils_mod_decl.attrs.len(),
            2,
            "mod utils declaration should have 2 outer attrs, got: {:?}",
            utils_mod_decl.attrs
        );

        // All should be outer (not inner)
        for attr in &utils_mod_decl.attrs {
            assert!(
                !attr.is_inner,
                "mod declaration attrs should be outer: {:?}",
                attr
            );
        }

        // Verify specific attrs
        assert!(
            utils_mod_decl.attrs.iter().any(|a| a.path == "doc"),
            "Should have doc attr"
        );
        assert!(
            utils_mod_decl.attrs.iter().any(|a| a.path == "cfg"),
            "Should have cfg attr"
        );

        // === Check utils.rs: should have inner attrs at file level ===
        let utils_file = crate_data
            .files
            .get("src/utils.rs")
            .expect("Should have utils.rs");

        assert_eq!(
            utils_file.pure_file.attrs.len(),
            1,
            "utils.rs should have 1 file-level attr (inner), got: {:?}",
            utils_file.pure_file.attrs
        );

        let file_attr = &utils_file.pure_file.attrs[0];
        assert!(file_attr.is_inner, "File attr should be inner");
        assert_eq!(file_attr.path, "allow");
        assert!(matches!(&file_attr.meta, PureAttrMeta::List(s) if s == "dead_code"));

        // Verify all files are valid Rust
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Test: No spurious attributes are added
    /// When source has no attrs, output should have no attrs.
    #[test]
    fn test_no_spurious_attrs() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root WITHOUT attrs
        let crate_mod = PureMod {
            attrs: vec![], // No attrs
            vis: PureVis::Public,
            name: "my_crate".to_string(),
            items: vec![],
            scope: Default::default(),
        };

        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(crate_id, PureItem::Mod(crate_mod));

        // Register module WITHOUT attrs
        let utils_mod = PureMod {
            attrs: vec![], // No attrs
            vis: PureVis::Public,
            name: "utils".to_string(),
            items: vec![],
            scope: Default::default(),
        };

        let utils_id = symbol_registry
            .register(make_path("my_crate::utils"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(utils_id, PureItem::Mod(utils_mod));

        // Register struct in utils
        let config_id = symbol_registry
            .register(make_path("my_crate::utils::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Generate multi-file
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // lib.rs should have no file-level attrs
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert_eq!(
            lib.pure_file.attrs.len(),
            0,
            "lib.rs should have no attrs, got: {:?}",
            lib.pure_file.attrs
        );

        // mod utils declaration should have no attrs
        let utils_mod_decl = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "utils" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod utils");

        assert_eq!(
            utils_mod_decl.attrs.len(),
            0,
            "mod utils declaration should have no attrs, got: {:?}",
            utils_mod_decl.attrs
        );

        // utils.rs should have no file-level attrs
        let utils_file = crate_data.files.get("src/utils.rs").unwrap();
        assert_eq!(
            utils_file.pure_file.attrs.len(),
            0,
            "utils.rs should have no attrs, got: {:?}",
            utils_file.pure_file.attrs
        );
    }

    /// Test: External module with non-empty items should NOT be inlined
    ///
    /// This reproduces the bug where external modules (like filter.rs) get inlined
    /// into lib.rs because their PureMod.items is non-empty after parsing.
    ///
    /// The correct behavior: Only modules marked via `ast_registry.mark_inline_module()`
    /// should be inlined. External modules (not marked) should generate separate files,
    /// regardless of whether their PureMod.items is empty or not.
    #[test]
    fn test_external_module_with_items_not_inlined() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register a struct at crate root
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Simulate external module "filter" that was parsed from filter.rs
        // Key: PureMod.items is NON-EMPTY (contains the Filter enum)
        // But it's NOT marked as inline via mark_inline_module()
        let filter_mod = PureMod {
            attrs: vec![],
            vis: PureVis::Public,
            name: "filter".to_string(),
            items: vec![
                // Filter enum inside the module
                PureItem::Enum(PureEnum {
                    attrs: vec![],
                    vis: PureVis::Public,
                    name: "Filter".to_string(),
                    generics: PureGenerics::default(),
                    variants: vec![
                        PureVariant {
                            attrs: vec![],
                            name: "Identity".to_string(),
                            fields: PureFields::Unit,
                            discriminant: None,
                        },
                        PureVariant {
                            attrs: vec![],
                            name: "Field".to_string(),
                            fields: PureFields::Tuple(vec![PureTupleField {
                                attrs: vec![],
                                vis: PureVis::Private,
                                ty: PureType::Path("String".to_string()),
                            }]),
                            discriminant: None,
                        },
                    ],
                }),
            ],
            scope: Default::default(),
        };

        let filter_id = symbol_registry
            .register(make_path("my_crate::filter"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(filter_id, PureItem::Mod(filter_mod));
        // NOTE: NOT calling ast_registry.mark_inline_module(filter_id)
        // This simulates an external module parsed from filter.rs

        // Also register the Filter enum separately (as it would be in symbol_registry)
        let filter_enum_id = symbol_registry
            .register(make_path("my_crate::filter::Filter"), SymbolKind::Enum)
            .unwrap();
        ast_registry.set(
            filter_enum_id,
            PureItem::Enum(PureEnum {
                attrs: vec![],
                vis: PureVis::Public,
                name: "Filter".to_string(),
                generics: PureGenerics::default(),
                variants: vec![
                    PureVariant {
                        attrs: vec![],
                        name: "Identity".to_string(),
                        fields: PureFields::Unit,
                        discriminant: None,
                    },
                    PureVariant {
                        attrs: vec![],
                        name: "Field".to_string(),
                        fields: PureFields::Tuple(vec![PureTupleField {
                            attrs: vec![],
                            vis: PureVis::Private,
                            ty: PureType::Path("String".to_string()),
                        }]),
                        discriminant: None,
                    },
                ],
            }),
        );

        // Generate multi-file output
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // === Key assertions ===

        // 1. filter.rs should exist as a separate file
        assert!(
            crate_data.files.contains_key("src/filter.rs"),
            "External module 'filter' should have its own file (filter.rs). Got files: {:?}",
            crate_data.files.keys().collect::<Vec<_>>()
        );

        // 2. lib.rs should have `mod filter;` declaration (not inline)
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(
            lib.source.contains("mod filter;"),
            "lib.rs should have 'mod filter;' declaration, got:\n{}",
            lib.source
        );

        // 3. lib.rs should NOT have inline module content
        assert!(
            !lib.source.contains("mod filter {"),
            "lib.rs should NOT have inline 'mod filter {{...}}', got:\n{}",
            lib.source
        );

        // 4. lib.rs should NOT contain Filter enum
        assert!(
            !lib.source.contains("enum Filter"),
            "lib.rs should NOT contain Filter enum (should be in filter.rs), got:\n{}",
            lib.source
        );

        // 5. filter.rs should contain the Filter enum
        let filter_file = crate_data.files.get("src/filter.rs").unwrap();
        assert!(
            filter_file.source.contains("pub enum Filter"),
            "filter.rs should contain 'pub enum Filter', got:\n{}",
            filter_file.source
        );

        // Verify all files are valid Rust
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Test: Inline module (marked) should stay inline even with items
    ///
    /// Complementary test: modules marked via mark_inline_module() should
    /// remain inline in the parent file.
    #[test]
    fn test_marked_inline_module_stays_inline() {
        use ryo_source::pure::{PureBlock, PureFn};

        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();

        // Register a struct at crate root
        let config_id = symbol_registry
            .register(make_path("my_crate::Config"), SymbolKind::Struct)
            .unwrap();
        ast_registry.set(config_id, make_struct("Config"));

        // Inline module "tests" - marked via mark_inline_module()
        let tests_mod = PureMod {
            attrs: vec![PureAttribute {
                path: "cfg".to_string(),
                meta: PureAttrMeta::List("test".to_string()),
                is_inner: false,
            }],
            vis: PureVis::Private,
            name: "tests".to_string(),
            items: vec![PureItem::Fn(PureFn {
                attrs: vec![PureAttribute {
                    path: "test".to_string(),
                    meta: PureAttrMeta::Path,
                    is_inner: false,
                }],
                vis: PureVis::Private,
                is_async: false,
                is_async_inferred: false,
                is_const: false,
                is_unsafe: false,
                abi: None,
                name: "test_something".to_string(),
                generics: PureGenerics::default(),
                params: vec![],
                ret: None,
                body: PureBlock::default(),
            })],
            scope: ModScope::Test,
        };

        let tests_id = symbol_registry
            .register(make_path("my_crate::tests"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(tests_id, PureItem::Mod(tests_mod));
        // Mark as inline - this is the key difference from the previous test
        ast_registry.mark_inline_module(tests_id);

        // Generate multi-file output
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // === Key assertions ===

        // 1. tests.rs should NOT exist (inline module stays in lib.rs)
        assert!(
            !crate_data.files.contains_key("src/tests.rs"),
            "Inline module 'tests' should NOT have its own file. Got files: {:?}",
            crate_data.files.keys().collect::<Vec<_>>()
        );

        // 2. lib.rs should have inline module content
        let lib = crate_data.files.get("src/lib.rs").unwrap();
        assert!(
            lib.source.contains("mod tests {"),
            "lib.rs should have inline 'mod tests {{...}}', got:\n{}",
            lib.source
        );

        // 3. lib.rs should contain the test function
        assert!(
            lib.source.contains("fn test_something"),
            "lib.rs should contain test_something function, got:\n{}",
            lib.source
        );

        // 4. lib.rs should have #[cfg(test)] attribute
        assert!(
            lib.source.contains("#[cfg(test)]"),
            "lib.rs should have #[cfg(test)] attribute, got:\n{}",
            lib.source
        );

        // Verify all files are valid Rust
        for (path, file) in &crate_data.files {
            syn::parse_str::<syn::File>(&file.source)
                .unwrap_or_else(|_| panic!("[{}] Should be valid Rust:\n{}", path, file.source));
        }
    }

    /// Test: External module visibility should be preserved (not inferred from children)
    ///
    /// Bug: When an external module contains public items (e.g., `pub enum Filter`),
    /// the module declaration was incorrectly changed from `mod filter;` to `pub mod filter;`.
    ///
    /// Expected: Module visibility should come from the original source, not be inferred
    /// from child item visibility.
    #[test]
    fn test_external_module_visibility_preserved() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            crate_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "my_crate".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );

        // Register external module "error" with PRIVATE visibility
        // Even though it contains a PUBLIC enum
        let error_mod = PureMod {
            attrs: vec![],
            vis: PureVis::Private, // <-- PRIVATE module
            name: "error".to_string(),
            items: vec![
                // Public enum inside the private module
                PureItem::Enum(PureEnum {
                    attrs: vec![],
                    vis: PureVis::Public, // <-- PUBLIC item inside
                    name: "Error".to_string(),
                    generics: PureGenerics::default(),
                    variants: vec![PureVariant {
                        attrs: vec![],
                        name: "IoError".to_string(),
                        fields: PureFields::Unit,
                        discriminant: None,
                    }],
                }),
            ],
            scope: Default::default(),
        };

        let error_mod_id = symbol_registry
            .register(make_path("my_crate::error"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(error_mod_id, PureItem::Mod(error_mod));
        // Set visibility in SymbolRegistry (as parser would do)
        let _ = symbol_registry.set_visibility(error_mod_id, ryo_symbol::Visibility::Private);
        // NOT marking as inline - this is an external module

        // Register the Error enum separately
        let error_enum_id = symbol_registry
            .register(make_path("my_crate::error::Error"), SymbolKind::Enum)
            .unwrap();
        ast_registry.set(
            error_enum_id,
            PureItem::Enum(PureEnum {
                attrs: vec![],
                vis: PureVis::Public,
                name: "Error".to_string(),
                generics: PureGenerics::default(),
                variants: vec![PureVariant {
                    attrs: vec![],
                    name: "IoError".to_string(),
                    fields: PureFields::Unit,
                    discriminant: None,
                }],
            }),
        );

        // Generate with multi-file mode
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // lib.rs should have PRIVATE mod declaration: `mod error;`
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // Find the mod error declaration in items
        let error_mod_decl = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "error" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod error in lib.rs");

        // CRITICAL: Visibility should be PRIVATE, not PUBLIC
        assert!(
            matches!(error_mod_decl.vis, PureVis::Private),
            "mod error should be PRIVATE (original visibility), but got: {:?}\nlib.rs:\n{}",
            error_mod_decl.vis,
            lib.source
        );

        // Verify source contains `mod error;` not `pub mod error;`
        assert!(
            lib.source.contains("mod error;") && !lib.source.contains("pub mod error;"),
            "lib.rs should have 'mod error;' (private), not 'pub mod error;'\nGot:\n{}",
            lib.source
        );
    }

    /// Test: External module visibility should use PureMod.vis when SymbolRegistry has no visibility
    ///
    /// This test reproduces the actual bug: SymbolRegistry.visibility() returns None,
    /// and the code falls back to inferring visibility from child items.
    ///
    /// Expected: Should use PureMod.vis from ASTRegistry, not infer from children.
    #[test]
    fn test_external_module_visibility_from_pure_mod() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            crate_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "my_crate".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );

        // Register external module "error" with PRIVATE visibility in PureMod
        // But do NOT call symbol_registry.set_visibility() (simulating parser behavior)
        let error_mod = PureMod {
            attrs: vec![],
            vis: PureVis::Private, // <-- PRIVATE in PureMod
            name: "error".to_string(),
            items: vec![
                // Public enum inside the private module
                PureItem::Enum(PureEnum {
                    attrs: vec![],
                    vis: PureVis::Public, // <-- PUBLIC item inside
                    name: "Error".to_string(),
                    generics: PureGenerics::default(),
                    variants: vec![PureVariant {
                        attrs: vec![],
                        name: "IoError".to_string(),
                        fields: PureFields::Unit,
                        discriminant: None,
                    }],
                }),
            ],
            scope: Default::default(),
        };

        let error_mod_id = symbol_registry
            .register(make_path("my_crate::error"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(error_mod_id, PureItem::Mod(error_mod));
        // NOTE: NOT calling symbol_registry.set_visibility() - this is the bug scenario
        // NOT marking as inline - this is an external module

        // Register the Error enum separately
        let error_enum_id = symbol_registry
            .register(make_path("my_crate::error::Error"), SymbolKind::Enum)
            .unwrap();
        ast_registry.set(
            error_enum_id,
            PureItem::Enum(PureEnum {
                attrs: vec![],
                vis: PureVis::Public,
                name: "Error".to_string(),
                generics: PureGenerics::default(),
                variants: vec![PureVariant {
                    attrs: vec![],
                    name: "IoError".to_string(),
                    fields: PureFields::Unit,
                    discriminant: None,
                }],
            }),
        );

        // Generate with multi-file mode
        let generator = RegistryGenerator::multi_file();
        let workspace = generator.generate(&ast_registry, &symbol_registry).unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();

        // lib.rs should have PRIVATE mod declaration: `mod error;`
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // Find the mod error declaration in items
        let error_mod_decl = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "error" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod error in lib.rs");

        // CRITICAL: Visibility should be PRIVATE (from PureMod.vis), not PUBLIC (inferred from children)
        assert!(
            matches!(error_mod_decl.vis, PureVis::Private),
            "mod error should be PRIVATE (from PureMod.vis), but got: {:?}\n\
             This indicates visibility is being inferred from child items instead of PureMod.vis\n\
             lib.rs:\n{}",
            error_mod_decl.vis,
            lib.source
        );
    }

    /// Test: External module visibility should be preserved in generate_with_graph path
    ///
    /// Bug: generate_file_from_graph infers visibility from children (has_public check)
    /// instead of using the original PureMod.vis.
    ///
    /// This test uses generate_with_graph which calls generate_file_from_graph.
    #[test]
    fn test_external_module_visibility_with_graph() {
        use ryo_analysis::{CodeEdgeV2, CodeGraphV2};

        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();
        let mut code_graph = CodeGraphV2::new();

        // Register crate root
        let crate_id = symbol_registry
            .register(make_path("my_crate"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(
            crate_id,
            PureItem::Mod(PureMod {
                attrs: vec![],
                vis: PureVis::Public,
                name: "my_crate".to_string(),
                items: vec![],
                scope: Default::default(),
            }),
        );
        code_graph.add_node(crate_id);
        code_graph.add_crate_root(crate_id);

        // Register external module "error" with PRIVATE visibility in PureMod
        let error_mod = PureMod {
            attrs: vec![],
            vis: PureVis::Private, // <-- PRIVATE module
            name: "error".to_string(),
            items: vec![], // Empty items = external module (file-based)
            scope: Default::default(),
        };

        let error_mod_id = symbol_registry
            .register(make_path("my_crate::error"), SymbolKind::Mod)
            .unwrap();
        ast_registry.set(error_mod_id, PureItem::Mod(error_mod));
        code_graph.add_node(error_mod_id);
        code_graph.add_edge(crate_id, error_mod_id, CodeEdgeV2::Contains);

        // Register PUBLIC Error enum inside the PRIVATE module
        let error_enum_id = symbol_registry
            .register(make_path("my_crate::error::Error"), SymbolKind::Enum)
            .unwrap();
        ast_registry.set(
            error_enum_id,
            PureItem::Enum(PureEnum {
                attrs: vec![],
                vis: PureVis::Public, // <-- PUBLIC item inside PRIVATE module
                name: "Error".to_string(),
                generics: PureGenerics::default(),
                variants: vec![PureVariant {
                    attrs: vec![],
                    name: "IoError".to_string(),
                    fields: PureFields::Unit,
                    discriminant: None,
                }],
            }),
        );
        code_graph.add_node(error_enum_id);
        code_graph.add_edge(error_mod_id, error_enum_id, CodeEdgeV2::Contains);

        // Generate using generate_with_graph (the actual code path used by ryo)
        let generator = RegistryGenerator::multi_file();
        let workspace = generator
            .generate_with_graph(&code_graph, &ast_registry, &symbol_registry)
            .unwrap();

        let crate_data = workspace.crates.get("my_crate").unwrap();
        let lib = crate_data.files.get("src/lib.rs").unwrap();

        // Find the mod error declaration
        let error_mod_decl = lib
            .pure_file
            .items
            .iter()
            .find_map(|item| {
                if let PureItem::Mod(m) = item {
                    if m.name == "error" {
                        return Some(m);
                    }
                }
                None
            })
            .expect("Should have mod error in lib.rs");

        // CRITICAL: Visibility should be PRIVATE (from PureMod.vis), not PUBLIC (inferred from children)
        assert!(
            matches!(error_mod_decl.vis, PureVis::Private),
            "mod error should be PRIVATE (from PureMod.vis), but got: {:?}\n\
             Bug: generate_file_from_graph is inferring visibility from children instead of PureMod.vis\n\
             lib.rs:\n{}",
            error_mod_decl.vis,
            lib.source
        );
    }

    // ========================================================================
    // generate_affected / symbol_path_to_file_key tests
    // ========================================================================

    #[test]
    fn test_symbol_path_to_file_key_root_items() {
        let gen = RegistryGenerator::multi_file();

        // crate::Config → src/lib.rs
        let path = SymbolPath::parse("my_crate::Config").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/lib.rs");

        // crate (root module itself) → src/lib.rs
        let path = SymbolPath::parse("my_crate").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/lib.rs");
    }

    #[test]
    fn test_symbol_path_to_file_key_module_items() {
        let gen = RegistryGenerator::multi_file();

        // crate::models::User → src/models.rs
        let path = SymbolPath::parse("my_crate::models::User").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/models.rs");
    }

    #[test]
    fn test_symbol_path_to_file_key_nested_modules() {
        let gen = RegistryGenerator::multi_file();

        // crate::models::sub::Foo → src/models/sub.rs
        let path = SymbolPath::parse("my_crate::models::sub::Foo").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/models/sub.rs");
    }

    #[test]
    fn test_symbol_path_to_file_key_main_symbol() {
        let gen = RegistryGenerator::multi_file();

        // main::my_app::Config → src/main.rs
        let path = SymbolPath::parse("main::my_app::Config").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/main.rs");

        // main::my_app::cli::Args → src/cli.rs
        let path = SymbolPath::parse("main::my_app::cli::Args").unwrap();
        assert_eq!(gen.symbol_path_to_file_key(&path), "src/cli.rs");
    }

    #[test]
    fn test_generate_affected_empty_symbols_returns_empty() {
        let ast_registry = ASTRegistry::new();
        let symbol_registry = SymbolRegistry::new();
        let gen = RegistryGenerator::multi_file();

        // Empty affected set → no files generated
        let workspace = gen
            .generate_internal(&ast_registry, &symbol_registry, Some(&HashSet::new()), None)
            .unwrap();
        assert_eq!(workspace.total_files(), 0);
    }

    #[test]
    fn test_generate_affected_only_affected_files() {
        // Setup: two modules (models and handlers), modify only models
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        // Register crate root
        let root_id = symbol_registry
            .register(SymbolPath::parse("test_crate").unwrap(), SymbolKind::Mod)
            .unwrap();

        // Register models module and item
        let models_mod_id = symbol_registry
            .register(
                SymbolPath::parse("test_crate::models").unwrap(),
                SymbolKind::Mod,
            )
            .unwrap();
        let user_id = symbol_registry
            .register(
                SymbolPath::parse("test_crate::models::User").unwrap(),
                SymbolKind::Struct,
            )
            .unwrap();

        // Register handlers module and item
        let handlers_mod_id = symbol_registry
            .register(
                SymbolPath::parse("test_crate::handlers").unwrap(),
                SymbolKind::Mod,
            )
            .unwrap();
        let process_id = symbol_registry
            .register(
                SymbolPath::parse("test_crate::handlers::process").unwrap(),
                SymbolKind::Function,
            )
            .unwrap();

        // Add AST entries
        ast_registry.set(root_id, make_mod("test_crate"));
        ast_registry.set(models_mod_id, make_mod("models"));
        ast_registry.set(user_id, make_struct("User"));
        ast_registry.set(handlers_mod_id, make_mod("handlers"));
        ast_registry.set(process_id, make_fn("process"));

        let gen = RegistryGenerator::multi_file();

        // Full generation should produce 3 files
        let full = gen.generate(&ast_registry, &symbol_registry).unwrap();
        let full_crate = full.crates.get("test_crate").unwrap();
        assert!(
            full_crate.files.len() >= 3,
            "Full gen should have lib.rs, models.rs, handlers.rs but got: {:?}",
            full_crate.files.keys().collect::<Vec<_>>()
        );

        // Affected generation with only User modified → only src/models.rs
        let workspace = gen
            .generate_internal(
                &ast_registry,
                &symbol_registry,
                Some(&HashSet::from(["src/models.rs".to_string()])),
                None,
            )
            .unwrap();
        let affected_crate = workspace.crates.get("test_crate").unwrap();
        assert_eq!(
            affected_crate.files.len(),
            1,
            "Affected gen should only have models.rs but got: {:?}",
            affected_crate.files.keys().collect::<Vec<_>>()
        );
        assert!(affected_crate.files.contains_key("src/models.rs"));
        assert!(!affected_crate.files.contains_key("src/lib.rs"));
        assert!(!affected_crate.files.contains_key("src/handlers.rs"));
    }

    fn make_mod(name: &str) -> PureItem {
        PureItem::Mod(PureMod {
            attrs: vec![],
            vis: PureVis::Public,
            name: name.to_string(),
            items: vec![],
            scope: Default::default(),
        })
    }

    /// Regression: when on-disk layout is flat (`src/storage.rs` only) and a
    /// symbol inside `crate::storage` is modified, the generator must NOT emit
    /// a duplicate `src/storage/mod.rs`. Both coexisting triggers cargo error
    /// "file for module `storage` found at both src/storage.rs and src/storage/mod.rs".
    /// Observed in precheck_real_fn_probe for RL061 ExtractTrait on ryo-app.
    #[test]
    fn test_generate_affected_no_duplicate_mod_rs_when_flat_exists() {
        let mut ast_registry = ASTRegistry::new();
        let mut symbol_registry = SymbolRegistry::new();

        let root_id = symbol_registry
            .register(SymbolPath::parse("ryo_app").unwrap(), SymbolKind::Mod)
            .unwrap();
        let storage_mod_id = symbol_registry
            .register(
                SymbolPath::parse("ryo_app::storage").unwrap(),
                SymbolKind::Mod,
            )
            .unwrap();
        let item_id = symbol_registry
            .register(
                SymbolPath::parse("ryo_app::storage::NewItem").unwrap(),
                SymbolKind::Struct,
            )
            .unwrap();

        ast_registry.set(root_id, make_mod("ryo_app"));
        ast_registry.set(storage_mod_id, make_mod("storage"));
        ast_registry.set(item_id, make_struct("NewItem"));

        // On-disk: only flat `src/storage.rs` exists. No `src/storage/mod.rs`.
        let gen =
            RegistryGenerator::multi_file().with_existing_files(vec!["src/storage.rs".to_string()]);

        // Drive the public Step 1 + 1b path (symbol_path_to_file_key + derive_child_path)
        // by computing affected_file_keys the same way `generate_affected` does, then
        // calling generate_internal. This bypasses the CargoMetadataProvider dependency
        // while exercising the exact file-key derivation logic under scrutiny.
        let modified = [storage_mod_id, item_id];

        // Step 1: map each modified symbol to its file-level path
        let mut affected_file_keys: std::collections::HashSet<String> = modified
            .iter()
            .filter_map(|&id| {
                let path = symbol_registry.path(id)?;
                let resolved = RegistryGenerator::resolve_to_file_level_symbol(
                    path,
                    &symbol_registry,
                    &ast_registry,
                );
                Some(gen.symbol_path_to_file_key(&resolved))
            })
            .collect();

        // Step 1b: for non-inline Mod symbols, add the module's own content file
        for &id in &modified {
            if symbol_registry.kind(id) != Some(SymbolKind::Mod) {
                continue;
            }
            if ast_registry.is_inline_module(id) {
                continue;
            }
            if let Some(path) = symbol_registry.path(id) {
                let parent_key = gen.symbol_path_to_file_key(path);
                let crate_name_opt = CrateName::new(path.crate_name()).ok();
                if let Some(mod_name) = path.segments().last() {
                    let mod_file_key =
                        gen.derive_child_path(&parent_key, mod_name, crate_name_opt.as_ref());
                    affected_file_keys.insert(mod_file_key);
                }
            }
        }

        // Hard contract: must NOT contain `src/storage/mod.rs`.
        assert!(
            !affected_file_keys.contains("src/storage/mod.rs"),
            "Must not emit src/storage/mod.rs when flat src/storage.rs already exists. \
             Got affected_file_keys = {:?}",
            affected_file_keys
        );
        assert!(
            affected_file_keys.contains("src/storage.rs"),
            "Must emit src/storage.rs. Got = {:?}",
            affected_file_keys
        );

        // Run generation and re-assert on the actual file output.
        let workspace = gen
            .generate_internal(
                &ast_registry,
                &symbol_registry,
                Some(&affected_file_keys),
                None,
            )
            .unwrap();
        let crate_data = workspace.crates.get("ryo_app").unwrap();
        assert!(
            !crate_data.files.contains_key("src/storage/mod.rs"),
            "Generated workspace must not contain src/storage/mod.rs. Files = {:?}",
            crate_data.files.keys().collect::<Vec<_>>()
        );
    }
}