knot 1.15.0

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, Node, Parser, Query, QueryCursor};

use crate::models::{ImportScope, ParsedEntity};
use crate::pipeline::parser::context::{ClassContext, extract_class_contexts};
use crate::pipeline::parser::languages::{java, javascript, kotlin, typescript};
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())
}

/// Local names an ES module or CommonJS file imports. Receiverless call
/// resolution uses these to keep unrelated modules isolated (issue #48).
fn javascript_import_scope(
    root: Node<'_>,
    source: &[u8],
    entities: &[ParsedEntity],
) -> ImportScope {
    let mut module_bindings: Vec<String> = typescript::scan_import_module_aliases(root, source)
        .into_iter()
        .map(|(local_name, _, _, _)| local_name)
        .collect();
    module_bindings.extend(javascript::collect_require_binding_names(root, source));
    module_bindings.extend(
        entities
            .iter()
            .filter(|entity| entity.alias_module_path.is_some())
            .map(|entity| entity.name.clone()),
    );
    module_bindings.sort();
    module_bindings.dedup();
    ImportScope {
        module_bindings,
        ..ImportScope::default()
    }
}

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 and Kotlin contribute their `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),
        "kotlin" => kotlin::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,
    );

    let import_scope = match lang_name {
        "java" => Some(java::extract_import_scope(tree.root_node(), source_bytes)),
        "kotlin" => Some(kotlin::extract_import_scope(tree.root_node(), source_bytes)),
        "javascript" | "typescript" => Some(javascript_import_scope(
            tree.root_node(),
            source_bytes,
            &entities,
        )),
        _ => None,
    };
    if let Some(scope) = import_scope.map(std::sync::Arc::new) {
        for entity in &mut entities {
            entity.import_scope = Some(std::sync::Arc::clone(&scope));
        }
    }

    Ok(entities)
}