knot 1.9.6

Codebase Graph + Vector RAG Indexer for Java, TypeScript, JavaScript, Kotlin, Rust, Python, Groovy, C/C++, C#, Build Systems, and HTML/CSS codebases
Documentation
use anyhow::{Context, Result};
use streaming_iterator::StreamingIterator;
use tree_sitter::{Language, Parser, Query, QueryCursor};

use crate::models::ParsedEntity;
use crate::pipeline::parser::context::{ClassContext, extract_class_contexts};
use crate::pipeline::parser::languages::java;
use crate::pipeline::parser::utils::*;

/// Deterministic richness of one match's captures: how much of an entity's
/// real content (signature, docstring, decorators, inline comments) the
/// match carried. Only used to order duplicate matches of the same identity
/// before `dedup_by`, so the richest copy survives.
fn entity_richness(e: &ParsedEntity) -> usize {
    usize::from(e.signature.is_some())
        + usize::from(e.docstring.is_some())
        + e.decorators.len()
        + e.inline_comments.len()
        + usize::from(!e.reference_intents.is_empty())
        + usize::from(!e.embed_text.is_empty())
}

mod captures;
mod enrich;
mod post_passes;
#[cfg(test)]
mod tests;

#[expect(
    clippy::too_many_arguments,
    reason = "function is verbose but correct — extraction deferred"
)]
pub(crate) fn extract_entities(
    source: &str,
    language: Language,
    query_src: &str,
    lang_name: &str,
    file_path: &str,
    repo_name: &str,
) -> Result<Vec<ParsedEntity>> {
    let mut parser = Parser::new();
    parser
        .set_language(&language)
        .context("Failed to set Tree-sitter language")?;

    let tree = parser
        .parse(source, None)
        .context("Tree-sitter failed to parse source")?;

    let query = Query::new(&language, query_src).context("Failed to compile Tree-sitter query")?;

    let source_bytes = source.as_bytes();
    let mut cursor = QueryCursor::new();

    let capture_names: Vec<String> = query
        .capture_names()
        .iter()
        .map(|s| s.to_string())
        .collect();

    let mut entities: Vec<ParsedEntity> = Vec::new();
    // First pass: extract all class/interface names and their line ranges for context
    let mut class_contexts: Vec<ClassContext> = Vec::new();
    extract_class_contexts(tree.root_node(), source_bytes, &mut class_contexts);

    // Extract the package / file-scoped namespace name for FQN prefixing.
    // Java contributes its `package` declaration; C# its file-scoped
    // namespace (C# 10+), which has no body and cannot be reached by the
    // ancestor walk (plan §3.2).
    let package_prefix = match lang_name {
        "java" => java::extract_package_name(tree.root_node(), source_bytes),
        "csharp" => crate::pipeline::parser::languages::csharp::extract_file_scoped_namespace(
            tree.root_node(),
            source_bytes,
        ),
        _ => None,
    };

    // Second pass: extract entities and resolve their contexts
    let mut matches = cursor.matches(&query, tree.root_node(), source_bytes);
    let mut covered_ranges: Vec<(usize, usize)> = Vec::new();

    while let Some(m) = {
        matches.advance();
        matches.get()
    } {
        let mut state = captures::CaptureState::default();

        for cap in m.captures() {
            let cap_name = &capture_names[cap.index as usize];
            let node = cap.node;
            let text = node_text(node, source_bytes);

            captures::process_capture(cap_name, text, node, source_bytes, lang_name, &mut state);
        }

        enrich::enrich_and_create_entity(
            &mut state,
            source_bytes,
            lang_name,
            file_path,
            repo_name,
            &class_contexts,
            &package_prefix,
            &mut entities,
            &mut covered_ranges,
        );
    }

    // Deduplication
    //
    // When duplicate matches exist (e.g. `rust.scm` alternates `function_item`
    // into two patterns — one carrying `parameters: (parameters) @signature`,
    // one fallback without), sort the copies of one identity so the *richest*
    // match comes first: a match that captured the signature, the docstring
    // and the decorators strictly carries more of the entity's real content
    // than a bare name/line match. Without this tie-break, dedup silently
    // keeps the thin copy and the signature never reaches `embed_text`.
    entities.sort_by(|a, b| {
        a.file_path
            .cmp(&b.file_path)
            .then(a.name.cmp(&b.name))
            .then(format!("{:?}", a.kind).cmp(&format!("{:?}", b.kind)))
            .then(a.start_line.cmp(&b.start_line))
            .then(entity_richness(b).cmp(&entity_richness(a)))
            .then(a.signature.is_some().cmp(&b.signature.is_some()))
    });
    entities.dedup_by(|a, b| {
        a.file_path == b.file_path
            && a.name == b.name
            && a.kind == b.kind
            && a.start_line == b.start_line
    });

    post_passes::run_post_passes(
        tree.root_node(),
        source_bytes,
        lang_name,
        file_path,
        repo_name,
        &mut entities,
        &covered_ranges,
    );

    Ok(entities)
}