brokk_bifrost_python/

source_support.rs

//! The language half of Python's resolution logic: module lookup, the export
//! index, the import binder, base-class resolution and the skeleton renderer,
//! written as free functions over a source trait instead of as methods on
//! `PythonAnalyzer`.
//!
//! `PythonAnalyzer` (in `brokk-bifrost-analysis`) owns the lazy cells (seven
//! moka caches, one `OnceLock` and two `PoolSafeMemo`s) and implements
//! [`PythonSource`] out of its own accessors, so the functions below
//! reach back for the memoized products they need without naming the analyzer
//! type.

use brokk_bifrost_core::analyzer::capabilities::ImportAnalysisProvider;
use brokk_bifrost_core::analyzer::model::ImportInfo;
use brokk_bifrost_core::analyzer::prepared_syntax::{IndexedFileFacts, PreparedSyntaxTree};
use brokk_bifrost_core::analyzer::project::Project;
use brokk_bifrost_core::analyzer::query_token::QueryToken;
use brokk_bifrost_core::analyzer::symbol_path::parse_symbol_path;
use brokk_bifrost_core::analyzer::usages::model::{
    ExportEntry, ExportIndex, ImportBinder, ImportBinding, ImportKind, ReexportStar,
};
use brokk_bifrost_core::analyzer::{CodeUnit, CodeUnitIndex, Language, ProjectFile};
use brokk_bifrost_core::hash::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use tree_sitter::Node;

use crate::bindings::{python_direct_scope_bindings_bounded, python_executable_scope_children};
use crate::declarations::{
    module_code_unit, parse_python_tree, python_base_origin_node, python_declared_import_root,
    python_import_root, python_project_module_components, python_repeated_root_extension_dir,
};
use crate::imports::{
    PythonImportDetails, python_import_details, python_namespace_binding_module,
    python_namespace_binding_name, resolve_exported_fqn, resolve_import_bindings,
    resolve_python_relative_module,
};

/// The analyzer-resident products Python's language logic resolves through, on
/// top of the two core capability traits it reads declarations and imports
/// with. The analyzer is the only implementor and every method forwards to one
/// of its own accessors, so the cells stay where they are and no free function
/// can reach past this surface.
///
/// The usage index is deliberately absent: [`PythonUsageIndex::build`] and
/// everything it calls take this trait, so the build cannot re-enter the memo
/// it is filling. Code that runs once the index exists takes
/// [`crate::graph_support::PythonUsageSource`].
pub trait PythonSource:
    CodeUnitIndex + ImportAnalysisProvider + crate::source_facts::PythonSourceFactProvider
{
    /// Path-derived module units for `module_fq`; `None` when the store could
    /// not answer the path-symbol query at all.
    /// Cover language-local memo inputs on hits as well as misses.
    fn record_memo_inputs(&self) -> [u8; 32];

    fn path_module_fqn(&self, module_fq: &str) -> Option<Vec<CodeUnit>>;

    /// [`Self::path_module_fqn`] for a whole batch, resolved in one store
    /// transaction.
    fn path_module_fqns_batch(&self, module_fqs: &[String]) -> Vec<Option<Vec<CodeUnit>>>;

    fn definition_fqn(&self, fqn: &str) -> Vec<CodeUnit>;

    /// Every workspace Python module's project-root name, for resolving an
    /// absolute specifier written against a source root below the project root.
    ///
    /// Memoized for the analyzer generation by the implementor: the product is
    /// path math over the workspace file listing, and every import whose
    /// specifier names no indexed module asks for it.
    fn module_spellings(&self) -> Arc<PythonModuleSpellings>;

    /// Shared by handle: both products are immutable for the analyzer
    /// generation that cached them, and callers ask for them once per receiver
    /// type, annotation or export name, so deep-cloning the whole map out of
    /// the cache on every hit was pure waste.
    fn import_binder_of(&self, file: &ProjectFile) -> Arc<ImportBinder>;

    fn export_index_of(&self, file: &ProjectFile) -> Arc<ExportIndex>;

    /// The admitted active syntax for executable-body and use-site queries.
    /// Captured declaration properties are read from signature metadata.
    /// `None` is unavailable and does not authorize a declaration parser
    /// fallback. The token proves the request cache is live.
    fn prepared_syntax(
        &self,
        token: QueryToken<'_>,
        file: &ProjectFile,
    ) -> Option<Arc<PreparedSyntaxTree>>;

    /// Every file's indexed facts, visited in the analyzer's own bulk-read
    /// batches. `None` marks a file the index carries no record for.
    fn visit_file_facts(
        &self,
        files: &[ProjectFile],
        keep_going: &dyn Fn() -> bool,
        visit: &mut dyn FnMut(&ProjectFile, Option<&dyn IndexedFileFacts>),
    );
}

/// Keep only the candidates an absolute import written in `importer` can mean.
///
/// A Python module name is path-derived and relative to an import root, so one
/// snapshot that vendors two distributions side by side spells the same module
/// twice: Feathr's `registry/purview-registry/registry/models.py` and
/// `registry/sql-registry/registry/models.py` are both `registry.models`
/// (#3475). Python resolves an absolute import against the `sys.path` entries
/// the importing program runs with, and the entry always on it is the root the
/// importing file itself lives under, so that root's module is the one the
/// import means. An enclosing root qualifies as well as the importer's own
/// package root, which is what lets a distribution's top-level script import
/// its own packages; when more than one qualifies, the nearest one shadows the
/// rest the way a closer `sys.path` entry does.
///
/// A candidate set that no containing root owns survives whole. That leaves a
/// genuine cross-root import resolvable and keeps the ambiguity visible to
/// whichever caller asked for a unique identity, rather than inventing a
/// preference the workspace does not state.
pub fn retain_modules_for_importer<T>(
    project: &dyn Project,
    importer: &ProjectFile,
    candidates: &mut Vec<T>,
    source_of: impl Fn(&T) -> &ProjectFile,
) {
    retain_nearest_owning_root(importer.rel_path(), candidates, |candidate| {
        let source = source_of(candidate);
        debug_assert_eq!(
            importer.root(),
            source.root(),
            "one workspace's Python files share one project root"
        );
        python_import_root(project, source)
    });
}

/// The `sys.path`-entry shadowing rule on its own: keep the candidates whose
/// root contains `importer`, nearest first, and leave a set no candidate root
/// owns untouched.
///
/// Shared by native environment routes and the legacy candidate lookups.
/// A candidate found by its
/// identity has the root [`python_import_root`] named for it; a candidate found
/// by [`PythonModuleSpellings`] has the root the specifier was written against.
/// Both are resolved against the importing program's path the same way.
pub fn retain_nearest_owning_root<T>(
    importer: &Path,
    candidates: &mut Vec<T>,
    root_of: impl Fn(&T) -> PathBuf,
) {
    if candidates.len() < 2 {
        return;
    }
    let owning_depth = |candidate: &T| {
        let root = root_of(candidate);
        importer
            .starts_with(&root)
            .then(|| root.components().count())
    };
    let depths = candidates.iter().map(owning_depth).collect::<Vec<_>>();
    let Some(nearest) = depths.iter().copied().flatten().max() else {
        return;
    };
    *candidates = std::mem::take(candidates)
        .into_iter()
        .zip(depths)
        .filter(|(_, depth)| *depth == Some(nearest))
        .map(|(candidate, _)| candidate)
        .collect();
}

/// One workspace Python module, named from the project root.
#[derive(Clone, Debug)]
struct ProjectRootModuleName {
    file: ProjectFile,
    components: Vec<String>,
}

/// A module whose project-root name *ends with* an absolute specifier, and the
/// source root that spelling would have to be written against.
///
/// This is candidate evidence, not binding evidence: a tail match only says the
/// file could be the module if its implied root were on the importing program's
/// path. [`PythonModuleSpellings::establishes_source_root`] decides whether the
/// workspace's own structure makes that root real, and only an established
/// candidate ever binds.
#[derive(Clone, Debug)]
pub struct PythonSourceRootModule {
    pub file: ProjectFile,
    /// The directory the specifier is resolved against: `file`'s relative path
    /// with the specifier's own components removed. Never empty, because the
    /// project root is the spelling the module index already answers exactly.
    pub source_root: PathBuf,
}

/// Every workspace Python module's project-root name, keyed by its last
/// component.
///
/// A Python module name is path-derived and relative to a `sys.path` entry, so
/// one file has one valid absolute name per ancestor directory on that path:
/// `dependency/core/lib/common/__init__.py` is `dependency.core.lib.common`
/// from the project root and `core.lib.common` from `dependency/`, which is the
/// entry dayu's `PYTHONPATH` adds and the only one its sources ever write
/// (#3506). Exactly one of those names is the module's identity, so an import
/// written against any other root has to be matched against the *end* of the
/// project-root name. The last component is the one part every name of a module
/// shares, so it is the key.
///
/// Built from path math over the workspace file listing: no parse, no store
/// read, and no `sys.path` guess -- a candidate only ever comes back paired
/// with the root that would have to be on the path for it to be the answer.
/// The same listing states which directories are packages, which is the
/// evidence a root without a packaging declaration is established by. A root
/// below a packaging declaration is established by the one thing the listing
/// cannot state -- the package marker's own `__path__` extension -- so those
/// markers, and only the markers that could state one, are read.
#[derive(Default)]
pub struct PythonModuleSpellings {
    project: Option<Arc<dyn Project>>,
    by_last_component: HashMap<String, Vec<ProjectRootModuleName>>,
    /// Every directory of the snapshot that holds an `__init__.py`, i.e. every
    /// package directory the workspace states.
    package_dirs: HashSet<PathBuf>,
    /// The directories a package marker adds to its own `__path__`, by the
    /// package directory that states them, once the statements a later
    /// `__path__` assignment replaces are dropped.
    ///
    /// `rtdetr_pose/__init__.py` appending `rtdetr_pose/rtdetr_pose` is what
    /// makes the shorter spelling `rtdetr_pose.config` name the file the
    /// declared root already names `rtdetr_pose.rtdetr_pose.config`, and it is
    /// the only thing that does: the repeated directory name, and the empty
    /// markers that make the directories packages, state nothing -- nor does
    /// an append in a branch that never runs, one whose guard another branch
    /// holds, or one a later `__path__ = ...` discards (#3506).
    path_extensions: HashMap<PathBuf, HashSet<PathBuf>>,
}

impl std::fmt::Debug for PythonModuleSpellings {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PythonModuleSpellings")
            .field("by_last_component", &self.by_last_component)
            .field("package_dirs", &self.package_dirs)
            .field("path_extensions", &self.path_extensions)
            .finish_non_exhaustive()
    }
}

impl PythonModuleSpellings {
    /// Complete spelling authority, including selected packaging roots and executed path extensions.
    /// Sorting rows removes hash iteration order; source text never enters this projection.
    pub fn authority_rows(&self) -> Vec<String> {
        let mut rows = Vec::new();
        for (last, candidates) in &self.by_last_component {
            for candidate in candidates {
                let root = self
                    .project()
                    .and_then(|project| python_declared_import_root(project, &candidate.file))
                    .map(|path| {
                        brokk_bifrost_core::path_utils::workspace_relative_slash_path(&path)
                    });
                rows.push(format!(
                    "module:{last:?}:{:?}:{:?}:{root:?}",
                    brokk_bifrost_core::path_utils::rel_path_string(&candidate.file),
                    candidate.components
                ));
            }
        }
        rows.extend(self.package_dirs.iter().map(|directory| {
            format!(
                "package:{:?}",
                brokk_bifrost_core::path_utils::workspace_relative_slash_path(directory)
            )
        }));
        for (directory, extensions) in &self.path_extensions {
            for extension in extensions {
                rows.push(format!(
                    "extension:{:?}:{:?}",
                    brokk_bifrost_core::path_utils::workspace_relative_slash_path(directory),
                    brokk_bifrost_core::path_utils::workspace_relative_slash_path(extension)
                ));
            }
        }
        rows.sort();
        rows
    }

    pub(crate) fn project(&self) -> Option<&dyn Project> {
        self.project.as_deref()
    }

    /// Index the snapshot's Python files.
    ///
    /// `project` supplies the same snapshot as the listing, including unsaved
    /// marker text and packaging declarations. Marker source is read only when
    /// it can state a path extension. The retained handle owns no new index.
    pub fn build(files: impl IntoIterator<Item = ProjectFile>, project: Arc<dyn Project>) -> Self {
        let mut by_last_component: HashMap<String, Vec<ProjectRootModuleName>> = HashMap::default();
        let mut package_dirs: HashSet<PathBuf> = HashSet::default();
        let mut package_markers: Vec<ProjectFile> = Vec::new();
        for file in files {
            if file.rel_path().file_name().and_then(|name| name.to_str()) == Some("__init__.py")
                && let Some(directory) = file.rel_path().parent()
            {
                package_dirs.insert(directory.to_path_buf());
                package_markers.push(file.clone());
            }
            let components = python_project_module_components(&file);
            let Some(last) = components.last() else {
                continue;
            };
            by_last_component
                .entry(last.clone())
                .or_default()
                .push(ProjectRootModuleName { file, components });
        }
        let mut path_extensions: HashMap<PathBuf, HashSet<PathBuf>> = HashMap::default();
        for marker in package_markers {
            let Some(directory) = marker.rel_path().parent() else {
                continue;
            };
            if !python_package_holds_a_repeat_of_itself(directory, &package_dirs) {
                continue;
            }
            let Ok(source) = project.read_source(&marker) else {
                continue;
            };
            let extended = parse_python_tree(&source)
                .map(|tree| {
                    crate::package_paths::appended_path_dirs(tree.root_node(), &source)
                        .into_iter()
                        .filter_map(|relative| {
                            brokk_bifrost_core::path_utils::normalize_relative_path_from(
                                directory, &relative,
                            )
                        })
                        .collect::<Vec<_>>()
                })
                .unwrap_or_default();
            if !extended.is_empty() {
                path_extensions
                    .entry(directory.to_path_buf())
                    .or_default()
                    .extend(extended);
            }
        }
        Self {
            project: Some(project),
            by_last_component,
            package_dirs,
            path_extensions,
        }
    }

    /// The modules whose project-root name ends with `module_fq`, each with the
    /// source root that would make the shorter name the right one.
    ///
    /// The project-root name itself is deliberately absent: that one is the
    /// module's identity, which the module index answers exactly, so this
    /// reports only the additional names and only for a dotted specifier. A
    /// single-component specifier names a top-level module, every top-level
    /// workspace module is already named from the project root, and a bare name
    /// that merely matches the last component of a deeper module is a
    /// coincidence rather than a source root -- the stdlib `typing` must not
    /// resolve to a workspace's own `seaborn._core.typing`.
    pub fn suffix_candidates(&self, module_fq: &str) -> Vec<PythonSourceRootModule> {
        // A leading dot makes the specifier relative to the importing file's own
        // package, which `resolve_python_relative_module` resolves before any
        // lookup; no `sys.path` entry takes part in it.
        if module_fq.starts_with('.') {
            return Vec::new();
        }
        let components = parse_symbol_path(Language::Python, module_fq);
        let Some(last) = components.last().filter(|_| components.len() > 1) else {
            return Vec::new();
        };
        let mut modules = Vec::new();
        for candidate in self
            .by_last_component
            .get(last.as_str())
            .into_iter()
            .flatten()
        {
            // A proper suffix only, so a shorter or equal-length name cannot
            // match: an equal one is the identity this does not answer.
            let Some(dropped) = candidate
                .components
                .len()
                .checked_sub(components.len())
                .filter(|dropped| *dropped > 0)
            else {
                continue;
            };
            if candidate.components[dropped..] != components[..] {
                continue;
            }
            // The dropped components are the leading directories of the file's
            // own relative path, so they are the source root exactly.
            let source_root: PathBuf = candidate
                .file
                .rel_path()
                .components()
                .take(dropped)
                .collect();
            debug_assert!(
                !source_root.as_os_str().is_empty(),
                "dropping a component of {:?} leaves a directory",
                candidate.file.rel_path()
            );
            modules.push(PythonSourceRootModule {
                file: candidate.file.clone(),
                source_root,
            });
        }
        modules
    }

    /// Whether the workspace's own structure establishes `candidate`'s implied
    /// source root as a root the candidate's specifier can be written against.
    ///
    /// Two kinds of evidence count, and a candidate with neither stays only a
    /// candidate.
    ///
    /// A packaging manifest that declares a root for the candidate's file
    /// (`tool.setuptools.packages.find.where`, `setup.py`'s `package_dir`) is
    /// the workspace stating the root itself, and it is authoritative for the
    /// files below it: the specifier is then the file's declared module name
    /// and nowhere else. `source/realpkg/vendor/api.py` under
    /// `where = ["source"]` is `realpkg.vendor.api`, so `vendor.api` -- whose
    /// implied root is `source/realpkg` -- does not name it, even though a
    /// package chain runs from that implied root down to it. A declaration of
    /// the project root counts the same way: `where = ["."]` is the workspace
    /// saying its packages begin at the project root, which is not the same as
    /// saying nothing, so `otherpkg/vendor/api.py` is `otherpkg.vendor.api` and
    /// `vendor.api` -- whose implied root is `otherpkg`, a package the
    /// declaration names -- does not name it either (#3506).
    ///
    /// A declaration leaves one shorter spelling open, the double-nested
    /// distribution directory, because there the specifier writes the implied
    /// root's own name again before the module's path:
    /// `rtdetr_pose/rtdetr_pose/config.py` is `rtdetr_pose.config` from
    /// `rtdetr_pose/`. The shape is not the evidence, because it is only a
    /// repeated directory name: the package the specifier starts from has to
    /// state that the repeated directory is on its search path, by adding it to
    /// its own `__path__` in its `__init__.py`
    /// ([`python_repeated_root_extension_dir`] names the directory that
    /// statement has to name), and the statement has to be one the interpreter
    /// runs and keeps: an append behind `if False:` and an append a later
    /// `__path__ = ...` replaces are not that statement. With that statement,
    /// and only with it, the declared root keeps admitting the spelling; the
    /// module still has to be reached through a real package chain from the
    /// implied root.
    ///
    /// Without a declaration the evidence has to be the snapshot's own package
    /// chain: every directory from the implied root down to the candidate's own
    /// directory must hold an `__init__.py`, so the specifier names a complete
    /// package/module chain that starts at that root. This is what
    /// `dependency/core/lib/common/__init__.py` has for `core.lib.common` when
    /// `dependency/` is on `PYTHONPATH`, and what
    /// `rtdetr_pose/rtdetr_pose/config.py` has for `rtdetr_pose.config` in a
    /// project that declares no packages at all. A bare tail match with no
    /// chain behind it is not proof of a root and never binds (#3506).
    pub fn establishes_source_root(&self, candidate: &PythonSourceRootModule) -> bool {
        if let Some(declared) = python_declared_import_root(
            self.project()
                .expect("source-root candidates have a selected project"),
            &candidate.file,
        ) {
            if declared == candidate.source_root {
                return true;
            }
            let Some(extension) = python_repeated_root_extension_dir(
                &candidate.file,
                &candidate.source_root,
                &declared,
            ) else {
                return false;
            };
            return self.package_chain_reaches_module(candidate)
                && self
                    .path_extensions
                    .get(&candidate.source_root)
                    .is_some_and(|extended| extended.contains(&extension));
        }
        self.package_chain_reaches_module(candidate)
    }

    /// Whether a complete `__init__.py` package chain runs from the candidate's
    /// implied source root down to its own module.
    ///
    /// This is the snapshot's own evidence that the implied root is a root the
    /// specifier can be written against: every directory from it down to the
    /// file's directory is a package the workspace states, so the written name
    /// runs through that package chain rather than through a coincidence of the
    /// file's last path component.
    fn package_chain_reaches_module(&self, candidate: &PythonSourceRootModule) -> bool {
        debug_assert!(
            candidate
                .file
                .rel_path()
                .starts_with(&candidate.source_root),
            "a candidate's implied root is a prefix of its own path"
        );
        let mut directory = candidate.file.rel_path().parent();
        while let Some(current) = directory {
            if !self.package_dirs.contains(current) {
                return false;
            }
            if current == candidate.source_root {
                return true;
            }
            directory = current.parent();
        }
        false
    }
}

/// Whether `directory` is a package that holds a directory of its own name
/// which is also a package.
///
/// This is the only layout a package marker has a repeated spelling to extend
/// `__path__` for, and it is a name-only question the listing answers, so the
/// markers whose source could state a path extension are the only ones ever
/// read (#3506).
fn python_package_holds_a_repeat_of_itself(
    directory: &Path,
    package_dirs: &HashSet<PathBuf>,
) -> bool {
    directory
        .file_name()
        .is_some_and(|name| package_dirs.contains(&directory.join(name)))
}

/// The module `module_fq` names, as written in `importer`.
///
/// `importer` is `None` for an FQN-level question that no import statement
/// asked -- a dotted name looked up on its own has no import root to be
/// resolved against. With an importer the candidates are narrowed by
/// [`retain_modules_for_importer`] first, and a specifier the index holds under
/// no name at all falls through to [`module_under_source_root`].
pub fn resolve_module_code_unit(
    python: &dyn PythonSource,
    importer: Option<&ProjectFile>,
    module_fq: &str,
) -> Option<CodeUnit> {
    let indexed = match python.path_module_fqn(module_fq) {
        // A path lookup that succeeds but finds no module unit is an answer:
        // it does not fall through to the definition lookup.
        Some(units) => indexed_module_for_importer(python.project(), importer, units),
        None => indexed_module_for_importer(
            python.project(),
            importer,
            python.definition_fqn(module_fq),
        ),
    };
    match indexed {
        IndexedModuleLookup::Unique(module) => Some(module),
        // The index spells the specifier more than once and the workspace does
        // not say which of them the import means. A tail match elsewhere names
        // a different module, so it cannot break this tie.
        IndexedModuleLookup::Ambiguous => None,
        IndexedModuleLookup::Missing => {
            let importer = importer?;
            module_under_source_root(&python.module_spellings(), importer, module_fq)
        }
    }
}

/// What the exact index says about a module specifier, before any source-root
/// inference runs.
///
/// The three cases are kept apart because only one of them may fall through to
/// the source-root candidates. A specifier the index spells exactly but several
/// times is an ambiguity of identity (#3475): answering it with a suffix
/// candidate that happens to end in the same name would replace a module the
/// import names with an unrelated one the workspace never offered.
enum IndexedModuleLookup {
    Unique(CodeUnit),
    Ambiguous,
    Missing,
}

fn indexed_module_for_importer(
    project: &dyn Project,
    importer: Option<&ProjectFile>,
    units: Vec<CodeUnit>,
) -> IndexedModuleLookup {
    let mut modules = units
        .into_iter()
        .filter(CodeUnit::is_module)
        .collect::<Vec<_>>();
    if let Some(importer) = importer {
        retain_modules_for_importer(project, importer, &mut modules, CodeUnit::source);
    }
    match modules.len() {
        0 => IndexedModuleLookup::Missing,
        1 => IndexedModuleLookup::Unique(modules.remove(0)),
        _ => IndexedModuleLookup::Ambiguous,
    }
}

/// The file an absolute `module_fq` names when it is written against a source
/// root the workspace's own structure establishes.
///
/// Python resolves an absolute import against the `sys.path` entries the
/// importing program runs with. A workspace states the project root and its
/// packaging roots, and [`python_import_root`] names modules from those; it does
/// not state an entry only `PYTHONPATH` adds -- dayu's `dependency/`, whose
/// `core.lib.common` is indexed as `dependency.core.lib.common` -- and a
/// distribution directory holding a same-named package makes the inner package
/// importable under both spellings, so YOLOZU's `rtdetr_pose/rtdetr_pose` is
/// indexed as `rtdetr_pose.rtdetr_pose.config` and written as
/// `rtdetr_pose.config` (#3506).
///
/// A tail match alone is not that evidence: `source/realpkg/vendor/api.py`
/// ends in `vendor/api.py`, but under `where = ["source"]` it is
/// `realpkg.vendor.api` and nothing else. What establishes a root is the
/// snapshot's own structure -- a packaging manifest that declares it, or a
/// complete `__init__.py` package chain from it down to the module -- and only
/// a candidate whose implied root is established that way binds.
/// [`PythonModuleSpellings::establishes_source_root`] is that decision; the
/// candidates it rejects stay visible to the diagnostics as the spellings the
/// workspace does index, which is a resolution gap and not externality.
///
/// Uniqueness is required after the same nearest-root narrowing an indexed
/// module gets: two workspace copies of one module are an ambiguity the
/// workspace does not resolve, and choosing between them here would invent a
/// preference it never stated (#3475's rule, applied to the roots it cannot
/// see).
pub fn python_module_file_under_source_root(
    spellings: &PythonModuleSpellings,
    importer: &ProjectFile,
    module_fq: &str,
) -> Option<ProjectFile> {
    let mut candidates = spellings.suffix_candidates(module_fq);
    retain_nearest_owning_root(importer.rel_path(), &mut candidates, |candidate| {
        candidate.source_root.clone()
    });
    candidates.retain(|candidate| spellings.establishes_source_root(candidate));
    let [candidate] = candidates.as_slice() else {
        return None;
    };
    debug_assert_eq!(
        importer.root(),
        candidate.file.root(),
        "one workspace's Python files share one project root"
    );
    Some(candidate.file.clone())
}

/// [`python_module_file_under_source_root`] as the module unit the store-backed
/// resolvers answer with. The unit is built from the file's own path, which is
/// where its identity comes from, so it is the same unit the path-symbol index
/// holds for that file.
fn module_under_source_root(
    spellings: &PythonModuleSpellings,
    importer: &ProjectFile,
    module_fq: &str,
) -> Option<CodeUnit> {
    let file = python_module_file_under_source_root(spellings, importer, module_fq)?;
    module_code_unit(spellings.project()?, &file)
}

/// Batched sibling of `resolve_module_code_unit`: resolves every FQN's path-symbol lookup in one
/// store transaction instead of one per FQN, then falls back to the (unbatched, rarer)
/// definition-lookup path per FQN exactly as the single-FQN version does. Preserves its per-item
/// semantics precisely, including that a path lookup which succeeds but finds no module unit does
/// *not* fall through to the definition lookup.
pub fn resolve_module_code_units_batch(
    python: &dyn PythonSource,
    importer: Option<&ProjectFile>,
    module_fqs: &[String],
) -> Vec<Option<CodeUnit>> {
    let path_results = python.path_module_fqns_batch(module_fqs);
    let mut lookups: Vec<IndexedModuleLookup> = Vec::with_capacity(module_fqs.len());
    let mut needs_definition_fallback = Vec::new();
    for (i, units) in path_results.into_iter().enumerate() {
        match units {
            Some(units) => lookups.push(indexed_module_for_importer(
                python.project(),
                importer,
                units,
            )),
            None => {
                needs_definition_fallback.push(i);
                // Placeholder, replaced by the definition lookup below.
                lookups.push(IndexedModuleLookup::Missing);
            }
        }
    }
    for i in needs_definition_fallback {
        lookups[i] = indexed_module_for_importer(
            python.project(),
            importer,
            python.definition_fqn(&module_fqs[i]),
        );
    }
    let mut results: Vec<Option<CodeUnit>> = vec![None; module_fqs.len()];
    let mut needs_source_root = Vec::new();
    for (i, lookup) in lookups.into_iter().enumerate() {
        match lookup {
            IndexedModuleLookup::Unique(module) => results[i] = Some(module),
            IndexedModuleLookup::Ambiguous => {}
            IndexedModuleLookup::Missing => needs_source_root.push(i),
        }
    }
    if let Some(importer) = importer
        && !needs_source_root.is_empty()
    {
        // One memo handle for the whole batch: a workspace's external imports
        // all miss the index, so this arm runs for most of the batch.
        let spellings = python.module_spellings();
        for i in needs_source_root {
            results[i] = module_under_source_root(&spellings, importer, &module_fqs[i]);
        }
    }
    results
}

pub fn compute_export_index_of(
    python: &dyn PythonSource,
    token: QueryToken<'_>,
    file: &ProjectFile,
) -> ExportIndex {
    let mut index = ExportIndex::empty();
    let mut events = Vec::new();
    let declarations = python.top_level_declarations(file);
    collect_local_export_events(
        declarations.iter(),
        |code_unit| {
            python
                .ranges(code_unit)
                .iter()
                .map(|range| range.start_byte)
                .max()
                .unwrap_or(usize::MAX)
        },
        &mut events,
    );

    let imports = python.import_info_of(token, file);
    collect_reexport_events_from_imports(python, file, &imports, &mut events, &mut index);

    finish_export_index(events, index)
}

pub fn export_index_from_file_facts(
    python: &dyn PythonSource,
    file: &ProjectFile,
    facts: &dyn IndexedFileFacts,
    module_name: &str,
) -> ExportIndex {
    let mut index = ExportIndex::empty();
    let mut events = Vec::new();
    collect_local_export_events(
        facts.top_level_declarations().iter(),
        |code_unit| {
            facts
                .declaration_ranges(code_unit)
                .into_iter()
                .flatten()
                .map(|range| range.start_byte)
                .max()
                .unwrap_or(usize::MAX)
        },
        &mut events,
    );

    if !facts
        .top_level_declarations()
        .iter()
        .any(CodeUnit::is_module)
        && let Some(identifier) = module_name.rsplit('.').next()
        && !identifier.is_empty()
        && !identifier.starts_with('_')
    {
        events.push((
            0,
            identifier.to_string(),
            ExportEntry::Local {
                local_name: identifier.to_string(),
            },
        ));
    }

    collect_reexport_events_from_imports(python, file, facts.imports(), &mut events, &mut index);

    finish_export_index(events, index)
}

fn collect_local_export_events<'a>(
    declarations: impl IntoIterator<Item = &'a CodeUnit>,
    mut start_byte: impl FnMut(&CodeUnit) -> usize,
    events: &mut Vec<(usize, String, ExportEntry)>,
) -> HashSet<String> {
    let mut local_names = HashSet::default();
    for code_unit in declarations {
        let identifier = code_unit.identifier().trim();
        if identifier.is_empty() {
            continue;
        }
        local_names.insert(identifier.to_string());
        events.push((
            start_byte(code_unit),
            identifier.to_string(),
            ExportEntry::Local {
                local_name: identifier.to_string(),
            },
        ));
    }
    local_names
}

fn finish_export_index(
    mut events: Vec<(usize, String, ExportEntry)>,
    mut index: ExportIndex,
) -> ExportIndex {
    events.sort_by_key(|(start_byte, _, _)| *start_byte);
    for (_, exported_name, entry) in events {
        index.exports_by_name.insert(exported_name, entry);
    }
    index
}

fn collect_reexport_events_from_imports(
    python: &dyn PythonSource,
    file: &ProjectFile,
    imports: &[ImportInfo],
    events: &mut Vec<(usize, String, ExportEntry)>,
    index: &mut ExportIndex,
) {
    for import in imports {
        if import
            .path
            .as_ref()
            .is_none_or(|path| !path.lexical_scopes.is_empty())
        {
            continue;
        }
        record_single_reexport_event(python, file, import, events, index);
    }
}

fn record_single_reexport_event(
    python: &dyn PythonSource,
    file: &ProjectFile,
    import: &ImportInfo,
    events: &mut Vec<(usize, String, ExportEntry)>,
    index: &mut ExportIndex,
) {
    let Some(PythonImportDetails::FromImport {
        module,
        name,
        alias,
        wildcard,
    }) = python_import_details(import)
    else {
        return;
    };
    let start_byte = import
        .path
        .as_ref()
        .map(|path| path.declaration_start_byte)
        .unwrap_or(usize::MAX);
    let resolved_module = if module.starts_with('.') {
        resolve_python_relative_module(python.project(), file, &module)
    } else {
        Some(module.clone())
    };
    let Some(resolved_module) = resolved_module else {
        return;
    };

    if wildcard {
        index.reexport_stars.push(ReexportStar {
            module_specifier: resolved_module,
        });
        return;
    }
    let exported_name = alias.unwrap_or(name.clone());
    // `from P import S` binds the submodule `P.S` itself when that module
    // exists, exactly as the import binder reads it below. Recording it as
    // "the name S inside module P.S" would follow the subpackage's own
    // exports, which silently mis-resolves whenever the subpackage re-exports
    // a member named after itself (issue #1762).
    let module_candidate = format!("{resolved_module}.{name}");
    if resolve_module_code_unit(python, Some(file), &module_candidate).is_some() {
        events.push((
            start_byte,
            exported_name,
            ExportEntry::ReexportedModule {
                module_specifier: module_candidate,
            },
        ));
        return;
    }
    events.push((
        start_byte,
        exported_name,
        ExportEntry::ReexportedNamed {
            module_specifier: resolved_module,
            imported_name: name,
        },
    ));
}

pub fn import_binder_from_imports(
    python: &dyn PythonSource,
    file: &ProjectFile,
    imports: &[ImportInfo],
) -> ImportBinder {
    let mut binder = ImportBinder::empty();

    for (local_name, binding) in import_bindings_from_imports(python, file, imports) {
        binder.bindings.insert(local_name, binding);
    }

    binder
}

/// Resolve each structured import without collapsing repeated local names.
///
/// Candidate discovery needs every lexical binding. The ordinary binder keeps
/// one effective binding for simple lookups.
pub fn import_bindings_from_imports(
    python: &dyn PythonSource,
    file: &ProjectFile,
    imports: &[ImportInfo],
) -> Vec<(String, ImportBinding)> {
    let mut bindings = Vec::new();

    for import in imports {
        let Some(details) = python_import_details(import) else {
            continue;
        };
        match details {
            PythonImportDetails::Import { module, alias } => {
                let local_name = python_namespace_binding_name(import, alias.as_deref(), &module);
                let module_specifier =
                    python_namespace_binding_module(import, alias.as_deref(), &module);
                bindings.push((
                    local_name,
                    ImportBinding {
                        module_specifier,
                        namespace_imported_module: Some(module),
                        kind: ImportKind::Namespace,
                        imported_name: None,
                    },
                ));
            }
            PythonImportDetails::FromImport {
                module,
                name,
                wildcard,
                ..
            } => {
                let resolved_module = if module.starts_with('.') {
                    resolve_python_relative_module(python.project(), file, &module)
                } else {
                    Some(module.clone())
                };
                let Some(resolved_module) = resolved_module else {
                    continue;
                };
                if wildcard {
                    // A glob import introduces each public declaration as a
                    // real local binding. Expand it from the structured module
                    // declarations so constructor and receiver inference can
                    // resolve the same names Python places in the namespace.
                    bindings.extend(
                        public_declarations_in_module(python, file, &resolved_module)
                            .into_iter()
                            .map(|declaration| {
                                let name = declaration.identifier().to_string();
                                (
                                    name.clone(),
                                    ImportBinding {
                                        module_specifier: resolved_module.clone(),
                                        namespace_imported_module: None,
                                        kind: ImportKind::Named,
                                        imported_name: Some(name),
                                    },
                                )
                            }),
                    );
                    continue;
                }
                // Non-wildcard from-imports always populate `identifier`
                // as `alias ?? name` (see `python_import_details`), so
                // `local_name()` reproduces the same alias-first fallback
                // without re-deriving it here.
                let local_name = import
                    .local_name()
                    .map(str::to_string)
                    .unwrap_or_else(|| name.clone());
                let module_candidate = format!("{resolved_module}.{name}");
                let exported = resolve_exported_fqn(python, Some(file), &module_candidate);
                let exported_module =
                    if !exported.is_empty() && exported.iter().all(CodeUnit::is_module) {
                        let mut paths = exported.iter().map(CodeUnit::fq_segment_texts);
                        let path = paths
                            .next()
                            .expect("non-empty exported modules have a first path");
                        paths
                            .all(|candidate| candidate == path)
                            .then(|| path.join("."))
                    } else {
                        None
                    };
                let implicit_submodule = if exported.is_empty()
                    && resolve_module_code_unit(python, Some(file), &module_candidate).is_some()
                {
                    Some(module_candidate)
                } else {
                    None
                };
                if let Some(module_specifier) = exported_module.or(implicit_submodule) {
                    bindings.push((
                        local_name,
                        ImportBinding {
                            module_specifier,
                            namespace_imported_module: None,
                            kind: ImportKind::Namespace,
                            imported_name: None,
                        },
                    ));
                    continue;
                }
                bindings.push((
                    local_name,
                    ImportBinding {
                        module_specifier: resolved_module,
                        namespace_imported_module: None,
                        kind: ImportKind::Named,
                        imported_name: Some(name),
                    },
                ));
            }
        }
    }

    bindings
}

pub fn public_declarations_in_module(
    python: &dyn PythonSource,
    importer: &ProjectFile,
    module_fq: &str,
) -> Vec<CodeUnit> {
    let Some(module_code_unit) = resolve_module_code_unit(python, Some(importer), module_fq) else {
        return Vec::new();
    };
    python
        .direct_children(&module_code_unit)
        .into_iter()
        .filter(|code_unit| !code_unit.identifier().starts_with('_'))
        .collect()
}

pub fn resolve_base_class(
    python: &dyn PythonSource,
    token: QueryToken<'_>,
    code_unit: &CodeUnit,
    raw: &str,
) -> Option<CodeUnit> {
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return None;
    }

    let binder = python.import_binder_of(code_unit.source());
    if let Some((head, tail)) = trimmed.split_once('.') {
        if let Some(binding) = binder.bindings.get(head)
            && binding.kind == ImportKind::Namespace
        {
            let fq_name = format!("{}.{}", binding.module_specifier, tail);
            return python.definitions(&fq_name).next();
        }
        return python.definitions(trimmed).next();
    }

    if let Some(binding) = binder.bindings.get(trimmed) {
        match binding.kind {
            ImportKind::Namespace => {
                return resolve_module_code_unit(
                    python,
                    Some(code_unit.source()),
                    &binding.module_specifier,
                );
            }
            ImportKind::Named => {
                let imported_name = binding.imported_name.as_ref()?;
                let fqn = format!("{}.{}", binding.module_specifier, imported_name);
                return resolve_exported_fqn(python, Some(code_unit.source()), &fqn)
                    .into_iter()
                    .next()
                    .or_else(|| python.definitions(&fqn).next());
            }
            _ => {}
        }
    }

    if python
        .import_info_of(token, code_unit.source())
        .iter()
        .any(|import| import.is_wildcard)
        && let Some(imported) =
            resolve_import_bindings(python, token, code_unit.source()).get(trimmed)
    {
        return Some(imported.clone());
    }

    if let Some(local) = resolve_preceding_local_class_base(python, token, code_unit, trimmed) {
        return Some(local);
    }

    let local_fq_name = format!("{}.{}", code_unit.package_name(), trimmed);
    python
        .definitions(&local_fq_name)
        .next()
        .or_else(|| python.definitions(trimmed).next())
}

fn class_definition_in_statement(node: Node<'_>) -> Option<Node<'_>> {
    if node.kind() == "class_definition" {
        return Some(node);
    }
    (node.kind() == "decorated_definition")
        .then(|| {
            let mut cursor = node.walk();
            node.named_children(&mut cursor)
                .find(|child| child.kind() == "class_definition")
        })
        .flatten()
}

fn declaration_statement(node: Node<'_>) -> Option<Node<'_>> {
    match node.kind() {
        "decorated_definition" if class_definition_in_statement(node).is_some() => Some(node),
        "class_definition" => Some(
            node.parent()
                .filter(|parent| parent.kind() == "decorated_definition")
                .unwrap_or(node),
        ),
        _ => None,
    }
}

fn scope_statement_binds_name(node: Node<'_>, source: &str, name: &str) -> bool {
    let mut stack = vec![node];
    while let Some(node) = stack.pop() {
        if node.kind() == "wildcard_import" {
            return true;
        }
        if matches!(node.kind(), "global_statement" | "nonlocal_statement") {
            let mut cursor = node.walk();
            if node.named_children(&mut cursor).any(|child| {
                child.kind() == "identifier"
                    && child.utf8_text(source.as_bytes()).ok() == Some(name)
            }) {
                return true;
            }
        }
        let Some(bindings) = python_direct_scope_bindings_bounded(node, source, || true) else {
            return true;
        };
        if bindings
            .iter()
            .any(|binding| binding.declaration.utf8_text(source.as_bytes()).ok() == Some(name))
        {
            return true;
        }
        stack.extend(python_executable_scope_children(node));
    }
    false
}

fn resolve_preceding_local_class_base(
    python: &dyn PythonSource,
    token: QueryToken<'_>,
    code_unit: &CodeUnit,
    raw: &str,
) -> Option<CodeUnit> {
    let parent = python.parent_of(code_unit)?;
    if !parent.is_function() && !parent.is_class() {
        return None;
    }
    let prepared = python.prepared_syntax(token, code_unit.source())?;
    let source = prepared.source();
    let current_node = prepared.declaration_node(code_unit)?;
    let current_statement = declaration_statement(current_node)?;
    let current_class = class_definition_in_statement(current_statement)?;
    let base_list = current_class.child_by_field_name("superclasses")?;
    let mut base_cursor = base_list.walk();
    if !base_list.named_children(&mut base_cursor).any(|base| {
        let origin = python_base_origin_node(base);
        origin.kind() == "identifier" && origin.utf8_text(source.as_bytes()).ok() == Some(raw)
    }) {
        return None;
    }
    let block = current_statement.parent()?;
    let mut block_cursor = block.walk();
    let siblings = block.named_children(&mut block_cursor).collect::<Vec<_>>();
    let current_index = siblings
        .iter()
        .position(|sibling| sibling.id() == current_statement.id())?;

    let mut preceding: Option<(usize, CodeUnit, Node<'_>)> = None;
    for candidate in prepared.direct_children(&parent) {
        if !candidate.is_class()
            || candidate.source() != code_unit.source()
            || candidate.identifier() != raw
        {
            continue;
        }
        let Some(candidate_node) = prepared.declaration_node(candidate) else {
            continue;
        };
        let Some(candidate_statement) = declaration_statement(candidate_node) else {
            continue;
        };
        if candidate_statement.parent().map(|node| node.id()) != Some(block.id())
            || candidate_statement.start_byte() >= current_statement.start_byte()
        {
            continue;
        }
        if preceding
            .as_ref()
            .is_none_or(|(start, _, _)| candidate_statement.start_byte() > *start)
        {
            preceding = Some((
                candidate_statement.start_byte(),
                candidate.clone(),
                candidate_statement,
            ));
        }
    }
    let (_, candidate, candidate_statement) = preceding?;
    let candidate_index = siblings
        .iter()
        .position(|sibling| sibling.id() == candidate_statement.id())?;
    if candidate_index >= current_index
        || siblings[candidate_index + 1..current_index]
            .iter()
            .any(|statement| scope_statement_binds_name(*statement, source, raw))
    {
        return None;
    }
    Some(candidate)
}

pub fn render_skeleton_recursive(
    index: &dyn CodeUnitIndex,
    code_unit: &CodeUnit,
    indent: &str,
    header_only: bool,
    out: &mut String,
) {
    enum Work {
        Declaration(CodeUnit, String),
        Elision(String),
    }
    let mut stack = vec![Work::Declaration(code_unit.clone(), indent.to_string())];
    while let Some(work) = stack.pop() {
        let Work::Declaration(unit, indent) = work else {
            let Work::Elision(indent) = work else {
                unreachable!()
            };
            out.push_str(&indent);
            out.push_str("[...]\n");
            continue;
        };
        if !unit.is_module()
            && !unit.is_file_scope()
            && let Some(signature) = index.signatures(&unit).first()
        {
            // A property's declaration label is callable-shaped, but the
            // skeleton has always displayed its header as a field.
            let signature = if unit.is_field() {
                signature.strip_suffix(" ...").unwrap_or(signature)
            } else {
                signature
            };
            for line in signature.lines() {
                out.push_str(&indent);
                out.push_str(line);
                out.push('\n');
            }
        }
        let children = index.direct_children(&unit);
        let child_indent = format!("{indent}  ");
        if header_only && children.iter().any(|child| !child.is_field()) {
            stack.push(Work::Elision(child_indent.clone()));
        }
        for child in children
            .into_iter()
            .rev()
            .filter(|child| !header_only || child.is_field())
        {
            stack.push(Work::Declaration(child, child_indent.clone()));
        }
    }
}