brokk_bifrost_core/analyzer/

common.rs

//! The language-blind half of the analyzer's shared helpers.
//!
//! Everything here is decided by a path extension or a byte range, so none of
//! it needs a grammar, an analyzer handle, or a store. The language-aware rest
//! of `analyzer::common` stays in `brokk-bifrost-analysis` and re-exports these
//! at their original paths.

use tree_sitter::Node;

use crate::analyzer::structural::facts::Span;
use crate::analyzer::{CodeUnit, Language, ProjectFile};
use crate::cancellation::CancellationToken;
use std::path::Path;

/// Qualify `name` with a dot-separated namespace or package prefix.
pub fn qualify_dotted_name(prefix: &str, name: &str) -> String {
    if prefix.is_empty() {
        name.to_string()
    } else {
        format!("{prefix}.{name}")
    }
}

#[cfg(test)]
pub(crate) fn test_range(start_byte: usize) -> crate::analyzer::Range {
    crate::analyzer::Range {
        start_byte,
        end_byte: start_byte + 1,
        start_line: 1,
        end_line: 1,
    }
}

/// The byte span a tree-sitter node covers, in the shared structural span
/// shape. Adapters use this to record token anchors (e.g. an import's binder
/// token) on parser-derived models.
pub fn node_span(node: Node<'_>) -> Span {
    Span {
        start_byte: node.start_byte(),
        end_byte: node.end_byte(),
    }
}

pub fn span_from_nodes(first: Node<'_>, last: Node<'_>) -> Span {
    Span {
        start_byte: first.start_byte(),
        end_byte: last.end_byte(),
    }
}

pub fn packed_bits_is_empty(words: &[u64]) -> bool {
    words.iter().all(|word| *word == 0)
}

pub fn packed_bits_len(words: &[u64]) -> usize {
    words.iter().map(|word| word.count_ones() as usize).sum()
}

pub fn language_for_target(target: &CodeUnit) -> Language {
    declaration_language_for_file(target.source())
}

pub fn language_for_file(file: &ProjectFile) -> Language {
    file.language()
}

pub(crate) fn estimated_string_vec_bytes(values: &[String], capacity: usize) -> usize {
    capacity
        .saturating_mul(std::mem::size_of::<String>())
        .saturating_add(
            values
                .iter()
                .map(String::capacity)
                .fold(0usize, usize::saturating_add),
        )
}

/// Select the workspace delegate needed for source or static dependency input.
/// Metadata activates its reader without becoming a programming-language file.
/// Admission and refresh must use the same rule for files-only workspaces.
pub fn workspace_language_for_file(file: &ProjectFile) -> Language {
    match file.rel_path().file_name().and_then(|name| name.to_str()) {
        Some("Cargo.toml" | "Cargo.lock") => Language::Rust,
        Some("go.mod") => Language::Go,
        Some(
            "package.json"
            | "package-lock.json"
            | "npm-shrinkwrap.json"
            | "pnpm-lock.yaml"
            | "yarn.lock",
        ) => Language::JavaScript,
        _ => language_for_file(file),
    }
}

/// The single language whose adapter adopts files by include inference
/// (#1837).
///
/// The CLAIMS SEAM registry that drives inference is
/// `analyzer::languages::claim_inferring_languages` over in
/// `brokk-bifrost-analysis`, which core cannot reach; core needs the same fact
/// to name a declaration found in a claimed file. `core_claiming_language_
/// matches_the_claims_seam` in that module asserts the two agree. The
/// registry's own single-claimant invariant -- also what
/// `LanguageAdapter::storage_language_key_for_file` rests on -- is what lets
/// this be one language rather than a set.
pub const INCLUDE_CLAIMING_LANGUAGE: Language = Language::Cpp;

/// The language whose spelling rules name a declaration that lives in `file`.
///
/// This differs from [`language_for_file`] for exactly the files include-driven
/// inference adopts (#1837). Those have, by construction, an extension no
/// language's registry claims, so the extension answers `Language::None` -- yet
/// a declaration only exists in such a file because the claiming analyzer
/// parsed it, and its qualified name must be spelled in that analyzer's
/// language. Rendering a C++ namespace head with `Language::None`'s neutral `.`
/// join turned `tbb::interface5` into `tbb.interface5` and tripped the FqName
/// round-trip assertion at construction, panicking the workspace build on
/// midonet's extensionless vendored TBB headers (issue #1878).
///
/// Use [`language_for_file`] to ask which language's extension list owns a
/// path; use this to ask how a declaration found in that path is named.
pub fn declaration_language_for_file(file: &ProjectFile) -> Language {
    file.declaration_language()
}

/// The language whose spelling rules name a declaration found in a file at
/// `rel_path`, decided from the path alone.
///
/// [`declaration_language_for_file`] is the same answer for a caller holding
/// the file. This is for the callers that hold only a workspace-relative path
/// -- a stored row keyed by path, a checker reading a tool payload -- and both
/// reach it through the same `declaration_language_of` rule, so the owner is
/// one function rather than one per entry point.
pub fn declaration_language_for_rel_path(rel_path: &Path) -> Language {
    declaration_language_of(
        Language::from_path(rel_path),
        Language::path_is_unclaimed(rel_path),
    )
}

/// The declaration-naming rule over the two facts a path decides:
/// [`ProjectFile::language`] and [`ProjectFile::has_unclaimed_extension`].
///
/// [`ProjectFile::language`]: crate::analyzer::ProjectFile::language
/// [`ProjectFile::has_unclaimed_extension`]: crate::analyzer::ProjectFile::has_unclaimed_extension
pub(crate) fn declaration_language_of(language: Language, unclaimed_extension: bool) -> Language {
    match language {
        Language::None if unclaimed_extension => INCLUDE_CLAIMING_LANGUAGE,
        language => language,
    }
}

/// Whether an analyzer covering `languages` could have indexed `file`, judged
/// from the path alone: no store query, no filesystem access, no snapshot.
///
/// This is the lexical half of the ownership test each language analyzer
/// applies to a live path (`TreeSitterAnalyzer::adapter_owns_file`): the file's
/// extension names one of the analyzer's languages, or the analyzer includes
/// the one language whose adapter adopts files by include inference and the
/// extension is claimed by no language at all.
///
/// A caller uses it to size a candidate set before spending store work on it.
/// It over-approximates in exactly one direction -- a path can be eligible and
/// still be unanalyzed -- so it may only decide how much work to attempt, never
/// whether a file is a result. [`CodeUnitIndex::retain_analyzed`] decides that.
///
/// [`CodeUnitIndex::retain_analyzed`]: crate::analyzer::code_unit_index::CodeUnitIndex::retain_analyzed
pub fn languages_may_analyze(
    languages: &std::collections::BTreeSet<Language>,
    file: &ProjectFile,
) -> bool {
    languages.contains(&language_for_file(file))
        || (languages.contains(&INCLUDE_CLAIMING_LANGUAGE) && file.has_unclaimed_extension())
}

/// Default longest single line a source file may contain before tree-sitter parsing is
/// skipped. Minified/generated single-line bundles (committed webpack output, mermaid.min.js,
/// etc.) have 16KB+ lines and otherwise both livelock the parser and explode downstream
/// consumers (e.g. the semantic indexer extracting thousands of bogus chunks). Hand-written
/// and normally-formatted generated source stays far below this, so the cap is effectively
/// invisible to real code. 16000 is comfortably above any human-authored line while still
/// catching moderately-sized minified bundles that a higher cap would let through.
pub const DEFAULT_MAX_LINE_LENGTH: usize = 16_000;

/// Longest single line a source file may contain before tree-sitter parsing is skipped.
/// Defaults to [`DEFAULT_MAX_LINE_LENGTH`]; `BIFROST_MAX_LINE_LENGTH` overrides it, and an
/// explicit `0` disables the limit entirely (parse everything, at your own risk).
pub fn max_line_length_limit() -> Option<usize> {
    match std::env::var("BIFROST_MAX_LINE_LENGTH") {
        Ok(v) => match v.trim().parse::<usize>() {
            Ok(0) => None,
            Ok(n) => Some(n),
            Err(_) => Some(DEFAULT_MAX_LINE_LENGTH),
        },
        Err(_) => Some(DEFAULT_MAX_LINE_LENGTH),
    }
}

/// Whether `source` must NOT be handed to tree-sitter: it is binary (contains NUL
/// bytes) or pathological for the parser (a line longer than the configured cap).
/// Centralizes the "is this safe to parse?" decision for every parse site so no
/// consumer livelocks on adversarial input.
pub fn is_unparseable_source(source: &str) -> bool {
    if source.as_bytes().contains(&0) {
        return true;
    }
    match max_line_length_limit() {
        Some(limit) => source.lines().any(|line| line.len() > limit),
        None => false,
    }
}

/// `text` with every whitespace run collapsed to a single space and the ends
/// trimmed.
///
/// Used to render a multi-line source header (a class or callable signature)
/// as one stable line.
pub fn collapse_whitespace(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    for token in text.split_whitespace() {
        if !out.is_empty() {
            out.push(' ');
        }
        out.push_str(token);
    }
    out
}

/// Split a language-specific call reference into its receiver and member.
///
/// The first parenthesis begins the argument list. Separators are tried in
/// order, and the last occurrence of the first matching separator is used.
pub fn extract_call_reference_parts<'a>(
    reference: &'a str,
    separators: &[&str],
) -> Option<(&'a str, &'a str)> {
    debug_assert!(separators.iter().all(|separator| !separator.is_empty()));
    let trimmed = reference.trim();
    let before_args = trimmed
        .split_once('(')
        .map(|(head, _)| head)
        .unwrap_or(trimmed);
    separators
        .iter()
        .find_map(|separator| before_args.rsplit_once(*separator))
}

/// Verbatim source text spanned by `node`, or `""` when the byte range is not a
/// valid `str` boundary (adversarial or partially-parsed input).
///
/// This is the single "slice a node's bytes" primitive. It replaces the
/// per-language `source.get(node.byte_range()).unwrap_or("")` copies and the
/// panicking `&source[node.byte_range()]` slicers (bad ranges now yield `""`
/// instead of panicking). Use [`node_source_text_trimmed`] when surrounding
/// whitespace must be dropped, and [`node_ident_text`] when a language sigil
/// (`r#`, `@`) must be normalized off identifier tokens.
pub fn node_source_text<'a>(node: Node<'_>, source: &'a str) -> &'a str {
    source.get(node.byte_range()).unwrap_or("")
}

/// The UTF-8 source text spanned by `node`, or `None` when its range is invalid
/// for `source`.
pub fn try_node_source_text<'a>(node: Node<'_>, source: &'a str) -> Option<&'a str> {
    node.utf8_text(source.as_bytes()).ok()
}

/// [`node_source_text`] with leading/trailing whitespace trimmed. Trimming is
/// load-bearing on the usages side, where a "name" node can span a compound
/// token whose canonical text is the trimmed inner identifier; declaration-side
/// callers that must preserve exact spans use [`node_source_text`] instead.
pub fn node_source_text_trimmed<'a>(node: Node<'_>, source: &'a str) -> &'a str {
    node_source_text(node, source).trim()
}

pub fn nonempty_node_source_text(node: Node<'_>, source: &str) -> Option<String> {
    let text = node_source_text_trimmed(node, source);
    (!text.is_empty()).then(|| text.to_string())
}

/// Per-language identifier sigil: which tree-sitter node kinds are single
/// identifier tokens, and the escape/sigil `prefix` (`r#` in Rust, `@` in C#)
/// to strip from those tokens so identity text (short/fq names) and
/// reference/member text agree on the canonical spelling.
///
/// Stripping is gated on `is_identifier_kind`: the sigil is only removed from
/// genuine identifier leaf nodes, never from spans where the same character is
/// meaningful (C# `@"..."` verbatim strings, attribute markers, larger token
/// runs). See [`node_ident_text`].
///
/// The mechanism is language-blind and lives here; each sigil constant is
/// language knowledge and lives with its language (Rust's in
/// `brokk-bifrost-rust`, C#'s still in `brokk-bifrost-analysis`).
pub struct IdentifierSigil {
    pub is_identifier_kind: fn(&str) -> bool,
    pub prefix: &'static str,
}

/// Node text with a language identifier sigil normalized off.
///
/// Slices `node`'s source (empty on a bad range), optionally trims, then strips
/// `sigil.prefix` iff `node`'s kind satisfies `sigil.is_identifier_kind`. This
/// is the one place the sigil-normalization invariant lives; the per-surface
/// (declaration / graph / get-definition) copies delegate here so they cannot
/// drift out of agreement.
pub fn node_ident_text<'a>(
    node: Node<'_>,
    source: &'a str,
    trim: bool,
    sigil: &IdentifierSigil,
) -> &'a str {
    let raw = source.get(node.byte_range()).unwrap_or("");
    let text = if trim { raw.trim() } else { raw };
    if (sigil.is_identifier_kind)(node.kind()) {
        text.strip_prefix(sigil.prefix).unwrap_or(text)
    } else {
        text
    }
}

/// Parse only `[start, end)` of `source` as `language`, confining the parser to
/// that region via tree-sitter included ranges. Every node keeps its original
/// byte offset and line/column position, exactly like the historical
/// "padded copy" technique (issues #941/#1015), but without materializing an
/// O(file) whitespace prefix or making the lexer walk it -- on a large file with
/// a region near the end that padding turned each recovery reparse into seconds
/// of whitespace lexing (issue #1309's cold-start profile).
///
/// Returns `None` for an empty or invalid region (out of bounds, or not on
/// char boundaries), mirroring the padded implementations' refusal to build a
/// reparse for nothing.
pub fn parse_source_region(
    language: &tree_sitter::Language,
    source: &str,
    start: usize,
    end: usize,
) -> Option<tree_sitter::Tree> {
    parse_source_region_with_cancellation(language, source, start, end, None)
}

/// Cancellation-aware form of [`parse_source_region`].
pub fn parse_source_region_with_cancellation(
    language: &tree_sitter::Language,
    source: &str,
    start: usize,
    end: usize,
    cancellation: Option<&CancellationToken>,
) -> Option<tree_sitter::Tree> {
    parse_source_ranges_with_cancellation(language, source, &[(start, end)], cancellation)
}

/// Parse only the byte spans in `ranges` of `source` as `language`, confining
/// the parser to those spans via tree-sitter included ranges. Every node
/// keeps its original byte offset and line/column position, exactly like
/// [`parse_source_region`] for a single span -- this is the form a recovery
/// needs when the clean text is scattered across more than one span of the
/// original source rather than one contiguous region. For example, a C
/// prototype hidden behind a K&R-compatibility macro invocation such as
/// `RET name _(( args ));` is recovered by parsing `RET name`, then the
/// parenthesized `args` list (keeping one of the two nested parenthesis
/// pairs so it reads as an ordinary parameter list), then the terminating
/// `;`, each at its own original offset, which is exactly what a
/// preprocessor's `#define _(args) args` expansion would leave behind
/// (issue #2932).
///
/// `ranges` must be non-empty and given in increasing, non-overlapping
/// order (each span's end at or before the next span's start); this
/// mirrors tree-sitter's own requirement on `Parser::set_included_ranges`.
/// Returns `None` if `ranges` is empty or if any span is empty or invalid
/// (out of bounds, not on char boundaries, or out of order).
pub fn parse_source_ranges_with_cancellation(
    language: &tree_sitter::Language,
    source: &str,
    ranges: &[(usize, usize)],
    cancellation: Option<&CancellationToken>,
) -> Option<tree_sitter::Tree> {
    if ranges.is_empty() {
        return None;
    }
    let bytes = source.as_bytes();
    let mut point = tree_sitter::Point { row: 0, column: 0 };
    let mut previous_end = 0usize;
    let mut ts_ranges = Vec::with_capacity(ranges.len());
    for &(start, end) in ranges {
        if start >= end
            || end > source.len()
            || !source.is_char_boundary(start)
            || !source.is_char_boundary(end)
            || start < previous_end
        {
            return None;
        }
        let start_point = advance_ts_point(bytes, point, previous_end, start);
        let end_point = advance_ts_point(bytes, start_point, start, end);
        ts_ranges.push(tree_sitter::Range {
            start_byte: start,
            end_byte: end,
            start_point,
            end_point,
        });
        point = end_point;
        previous_end = end;
    }
    parse_source_with_cancellation(language, source, Some(&ts_ranges), cancellation)
}

/// Parse one parser-provided source range without recomputing its points.
pub fn parse_source_range_with_cancellation(
    language: &tree_sitter::Language,
    source: &str,
    range: tree_sitter::Range,
    cancellation: Option<&CancellationToken>,
) -> Option<tree_sitter::Tree> {
    if range.start_byte >= range.end_byte
        || range.end_byte > source.len()
        || !source.is_char_boundary(range.start_byte)
        || !source.is_char_boundary(range.end_byte)
    {
        return None;
    }
    parse_source_with_cancellation(language, source, Some(&[range]), cancellation)
}

/// Parse source with an optional set of validated tree-sitter ranges, stopping
/// promptly when cancellation is requested.
pub fn parse_source_with_cancellation(
    language: &tree_sitter::Language,
    source: &str,
    included_ranges: Option<&[tree_sitter::Range]>,
    cancellation: Option<&CancellationToken>,
) -> Option<tree_sitter::Tree> {
    if cancellation.is_some_and(CancellationToken::is_cancelled) {
        return None;
    }
    let mut parser = tree_sitter::Parser::new();
    parser.set_language(language).ok()?;
    if let Some(ranges) = included_ranges {
        parser.set_included_ranges(ranges).ok()?;
    }
    if let Some(cancellation) = cancellation {
        let mut read = |offset: usize, _| &source.as_bytes()[offset..];
        let mut progress = |_: &tree_sitter::ParseState| cancellation.is_cancelled();
        parser.parse_with_options(
            &mut read,
            None,
            Some(tree_sitter::ParseOptions::new().progress_callback(&mut progress)),
        )
    } else {
        parser.parse(source, None)
    }
}

/// Advance `point` across `bytes[from..to]`. Tree-sitter columns count bytes.
///
/// Public because every producer of `tree_sitter::Range` must compute points
/// with this exact math: a point that disagrees with its byte offset corrupts
/// the positions of every node in the parse.
pub fn advance_ts_point(
    bytes: &[u8],
    point: tree_sitter::Point,
    from: usize,
    to: usize,
) -> tree_sitter::Point {
    let slice = &bytes[from..to];
    match slice.iter().rposition(|&b| b == b'\n') {
        None => tree_sitter::Point {
            row: point.row,
            column: point.column + slice.len(),
        },
        Some(last_newline) => tree_sitter::Point {
            row: point.row + slice.iter().filter(|&&b| b == b'\n').count(),
            column: slice.len() - last_newline - 1,
        },
    }
}