blockwatch 0.5.1

mod bash;
mod c;
mod c_sharp;
mod cmake;
mod cpp;
mod css;
mod dart;
mod dockerfile;
mod elixir;
mod go;
mod graphql;
mod groovy;
mod hcl;
mod html;
mod java;
mod javascript;
mod kotlin;
mod lua;
mod makefile;
mod markdown;
mod nix;
mod php;
mod proto;
mod python;
mod ruby;
/// Rust comment parsing. Serves as the stand-in language for the block parser's own unit tests,
/// which is why it alone is visible outside this module.
pub(crate) mod rust;
mod scala;
mod sql;
mod starlark;
mod swift;
mod toml;
mod tsx;
mod typescript;
mod xml;
mod yaml;

use crate::block_parser::BlocksParser;
use crate::{Position, character_column_at};
use std::collections::HashMap;
use std::ffi::OsString;
use std::ops::Range;
use std::sync::{Arc, Mutex};
use tree_sitter::{Language, Node, Parser, Tree, TreeCursor};

/// A parser for one language, shared between files and threads.
///
/// Each parser owns a mutable tree-sitter `Parser` and is therefore behind a `Mutex`; the `Arc`
/// lets languages that share a grammar (`.cc` and `.cpp`, `.yaml` and `.yml`) share one instance.
pub(crate) type LanguageParser = Arc<Mutex<Box<dyn BlocksParser>>>;

/// Parsers keyed by file extension (or by the whole filename for extensionless files such as
/// `Dockerfile`). Also serves as the list of extensions the CLI recognizes.
pub type LanguageParsers = HashMap<OsString, LanguageParser>;

/// Returns a map of all available language parsers by their file extensions.
pub fn language_parsers() -> anyhow::Result<LanguageParsers> {
    fn parser<P: BlocksParser + 'static>(p: P) -> LanguageParser {
        Arc::new(Mutex::new(Box::new(p) as Box<dyn BlocksParser>))
    }

    let bash_parser = parser(bash::parser()?);
    let c_parser = parser(c::parser()?);
    let c_sharp_parser = parser(c_sharp::parser()?);
    let cmake_parser = parser(cmake::parser()?);
    let cpp_parser = parser(cpp::parser()?);
    let css_parser = parser(css::parser()?);
    let dart_parser = parser(dart::parser()?);
    let dockerfile_parser = parser(dockerfile::parser()?);
    let elixir_parser = parser(elixir::parser()?);
    let go_parser = parser(go::parser()?);
    let graphql_parser = parser(graphql::parser()?);
    let groovy_parser = parser(groovy::parser()?);
    let hcl_parser = parser(hcl::parser()?);
    let html_parser = parser(html::parser()?);
    let java_parser = parser(java::parser()?);
    let js_parser = parser(javascript::parser()?);
    let kotlin_parser = parser(kotlin::parser()?);
    let lua_parser = parser(lua::parser()?);
    let makefile_parser = parser(makefile::parser()?);
    let markdown_parser = parser(markdown::parser()?);
    let nix_parser = parser(nix::parser()?);
    let php_parser = parser(php::parser()?);
    let proto_parser = parser(proto::parser()?);
    let python_parser = parser(python::parser()?);
    let ruby_parser = parser(ruby::parser()?);
    let rust_parser = parser(rust::parser()?);
    let scala_parser = parser(scala::parser()?);
    let sql_parser = parser(sql::parser()?);
    let starlark_parser = parser(starlark::parser()?);
    let swift_parser = parser(swift::parser()?);
    let toml_parser = parser(toml::parser()?);
    let typescript_parser = parser(typescript::parser()?);
    let typescript_tsx_parser = parser(tsx::parser()?);
    let xml_parser = parser(xml::parser()?);
    let yaml_parser = parser(yaml::parser()?);

    Ok(HashMap::from([
        // <block affects="README.md:supported-grammar, src/blocks.rs:supported-extensions" keep-sorted>
        ("BUILD".into(), Arc::clone(&starlark_parser)),
        ("CMakeLists.txt".into(), Arc::clone(&cmake_parser)),
        ("Containerfile".into(), Arc::clone(&dockerfile_parser)),
        ("Dockerfile".into(), Arc::clone(&dockerfile_parser)),
        ("Jenkinsfile".into(), Arc::clone(&groovy_parser)),
        ("Makefile".into(), Arc::clone(&makefile_parser)),
        ("WORKSPACE".into(), Arc::clone(&starlark_parser)),
        ("bash".into(), Arc::clone(&bash_parser)),
        ("bazel".into(), Arc::clone(&starlark_parser)),
        ("bzl".into(), Arc::clone(&starlark_parser)),
        ("bzlmod".into(), Arc::clone(&starlark_parser)),
        ("c".into(), c_parser),
        ("cc".into(), Arc::clone(&cpp_parser)),
        ("cmake".into(), cmake_parser),
        ("containerfile".into(), Arc::clone(&dockerfile_parser)),
        ("cpp".into(), Arc::clone(&cpp_parser)),
        ("cs".into(), c_sharp_parser),
        ("css".into(), css_parser),
        ("d.ts".into(), Arc::clone(&typescript_parser)),
        ("dart".into(), dart_parser),
        ("dockerfile".into(), dockerfile_parser),
        ("ex".into(), Arc::clone(&elixir_parser)),
        ("exs".into(), elixir_parser),
        ("go".into(), Arc::clone(&go_parser)),
        ("go.mod".into(), Arc::clone(&go_parser)),
        ("go.sum".into(), Arc::clone(&go_parser)),
        ("go.work".into(), go_parser),
        ("gql".into(), Arc::clone(&graphql_parser)),
        ("gradle".into(), Arc::clone(&groovy_parser)),
        ("graphql".into(), graphql_parser),
        ("groovy".into(), Arc::clone(&groovy_parser)),
        ("h".into(), cpp_parser),
        ("hcl".into(), Arc::clone(&hcl_parser)),
        ("htm".into(), Arc::clone(&html_parser)),
        ("html".into(), html_parser),
        ("java".into(), java_parser),
        ("jenkinsfile".into(), groovy_parser),
        ("js".into(), Arc::clone(&js_parser)),
        ("jsx".into(), js_parser),
        ("kt".into(), Arc::clone(&kotlin_parser)),
        ("kts".into(), kotlin_parser),
        ("lua".into(), lua_parser),
        ("makefile".into(), Arc::clone(&makefile_parser)),
        ("markdown".into(), Arc::clone(&markdown_parser)),
        ("md".into(), markdown_parser),
        ("mk".into(), makefile_parser),
        ("nix".into(), nix_parser),
        ("php".into(), Arc::clone(&php_parser)),
        ("phtml".into(), php_parser),
        ("proto".into(), proto_parser),
        ("py".into(), Arc::clone(&python_parser)),
        ("pyi".into(), python_parser),
        ("rb".into(), ruby_parser),
        ("rs".into(), rust_parser),
        ("sbt".into(), Arc::clone(&scala_parser)),
        ("scala".into(), scala_parser),
        ("sh".into(), bash_parser),
        ("sql".into(), sql_parser),
        ("star".into(), starlark_parser),
        ("swift".into(), swift_parser),
        ("tf".into(), Arc::clone(&hcl_parser)),
        ("tfvars".into(), hcl_parser),
        ("toml".into(), toml_parser),
        ("ts".into(), typescript_parser),
        ("tsx".into(), typescript_tsx_parser),
        ("xml".into(), xml_parser),
        ("yaml".into(), Arc::clone(&yaml_parser)),
        ("yml".into(), yaml_parser),
        // </block>
    ]))
}

/// Parses comment string from a source code by returning an iterator of `Comment`s.
pub(crate) trait CommentsParser: Send + Sync {
    /// Returns an iterator of `Comment`s from the source code.
    fn parse<'source>(
        &'source mut self,
        source_code: &'source str,
    ) -> impl Iterator<Item = Comment> + 'source;
}

/// What the comment walk does at a node.
enum Visit {
    /// Recurse into the node's children; the node yields no comment.
    Continue,
    /// Stop at this node, not descending into its children.
    /// If the node is a comment, then it must contain `Some(Comment)`.
    Break(Option<Comment>),
}

/// Maps a node to a [`Visit`]: the one place a grammar's node kinds are interpreted, one per language.
type NodeVisitor = Box<dyn Fn(&Node, &str) -> Visit + Send + Sync>;

struct TreeSitterCommentsParser {
    parser: Parser,
    node_visitor: NodeVisitor,
    tree: Option<Tree>,
}

impl TreeSitterCommentsParser {
    fn new(language: &Language, node_visitor: NodeVisitor) -> Self {
        let mut parser = Parser::new();
        parser
            .set_language(language)
            .expect("Error setting Tree-sitter language");
        Self {
            parser,
            node_visitor,
            tree: None,
        }
    }

    /// Stops the walk at nodes of `kinds` without reading a comment out of them.
    fn with_break_at_node_kinds(self, kinds: &'static [&'static str]) -> Self {
        let Self {
            parser,
            node_visitor,
            tree,
        } = self;
        Self {
            parser,
            node_visitor: Box::new(move |node, source_code| {
                if kinds.contains(&node.kind()) {
                    return Visit::Break(None);
                }
                node_visitor(node, source_code)
            }),
            tree,
        }
    }

    /// Stops the walk at every node the `predicate` accepts, without reading a comment out of it.
    ///
    /// Unlike [`Self::with_break_at_node_kinds`], the predicate also sees the source code, so it
    /// can judge a node by the surrounding text.
    fn with_break_when(self, predicate: fn(&Node, &str) -> bool) -> Self {
        let Self {
            parser,
            node_visitor,
            tree,
        } = self;
        Self {
            parser,
            node_visitor: Box::new(move |node, source_code| {
                if predicate(node, source_code) {
                    return Visit::Break(None);
                }
                node_visitor(node, source_code)
            }),
            tree,
        }
    }
}

impl CommentsParser for TreeSitterCommentsParser {
    fn parse<'a>(&'a mut self, source_code: &'a str) -> impl Iterator<Item = Comment> + 'a {
        let tree = self.parser.parse(source_code, None).unwrap();
        self.tree = Some(tree);
        // It is safe to unwrap here because we just set self.tree
        CommentsIterator::new(self.tree.as_ref().unwrap(), &self.node_visitor, source_code)
    }
}

/// Builds a [`NodeVisitor`] from `comment_text`, a function that returns a node's normalized
/// comment text when the node is a comment, or `None` otherwise. The visitor turns that answer
/// into a [`Visit`], one node at a time:
///
/// - not a comment: [`Visit::Continue`] — keep walking into the node's children;
/// - a comment: [`Visit::Break`] carrying the comment — its children are not visited, because a
///   comment's own text already covers any comment nested inside it.
fn comment_visitor<F>(comment_text: F) -> NodeVisitor
where
    F: Fn(&Node, &str) -> Option<String> + Send + Sync + 'static,
{
    Box::new(
        move |node, source_code| match comment_text(node, source_code) {
            None => Visit::Continue,
            Some(text) => Visit::Break(Some(Comment::from_node(node, source_code, text))),
        },
    )
}

struct CommentsIterator<'source> {
    cursor: TreeCursor<'source>,
    node_visitor: &'source NodeVisitor,
    source_code: &'source str,
    /// Whether the root node has been visited yet.
    start_visited: bool,
    /// Whether the next advance must skip the current node's children (set on [`Visit::Break`]).
    skip_children: bool,
    /// Whether the walk has run out of nodes. Once set, the iterator yields `None` forever: the
    /// cursor comes to rest on the root, so advancing it again would walk the whole tree a second
    /// time and re-emit every comment.
    done: bool,
}

impl<'source> CommentsIterator<'source> {
    fn new(
        tree: &'source Tree,
        node_visitor: &'source NodeVisitor,
        source_code: &'source str,
    ) -> Self {
        let cursor = tree.walk();
        Self {
            cursor,
            node_visitor,
            source_code,
            start_visited: false,
            skip_children: false,
            done: false,
        }
    }

    /// Advances to the next node in pre-order, skipping the current node's children when `descend`
    /// is false. Returns `false` once the tree is exhausted.
    fn goto_next(&mut self, descend: bool) -> bool {
        if descend && self.cursor.goto_first_child() {
            return true;
        }
        loop {
            if self.cursor.goto_next_sibling() {
                return true;
            }
            if !self.cursor.goto_parent() {
                return false;
            }
        }
    }
}

impl<'source> Iterator for CommentsIterator<'source> {
    type Item = Comment;

    /// Yields comments in pre-order, and keeps yielding `None` once the tree is exhausted.
    fn next(&mut self) -> Option<Self::Item> {
        if self.done {
            return None;
        }
        loop {
            if !self.start_visited {
                self.start_visited = true;
            } else {
                let descend = !self.skip_children;
                if !self.goto_next(descend) {
                    self.done = true;
                    return None;
                }
            }
            self.skip_children = false;
            match (self.node_visitor)(&self.cursor.node(), self.source_code) {
                Visit::Continue => {}
                Visit::Break(comment) => {
                    self.skip_children = true;
                    if let Some(comment) = comment {
                        return Some(comment);
                    }
                }
            }
        }
    }
}

#[derive(Debug, PartialEq)]
/// A single comment extracted from a source file — the only place block tags may appear.
pub(crate) struct Comment {
    /// Position range of the comment in the source.
    pub(crate) position_range: Range<Position>,
    /// Byte offset (i.e. position) of the comment in the source.
    pub(crate) source_range: Range<usize>,
    /// The `comment_string` is expected to be the content of the comment with all language specific
    /// comment symbols like `//`, `/**`, `#`, etc replaced with the corresponding number of
    /// whitespaces ("  " for "//", "   " for `/**`, etc.) so that the length of the comment is
    /// preserved. Offsets into this text therefore map straight back onto the source file.
    pub(crate) comment_text: String,
}

impl Comment {
    /// Builds a [`Comment`] spanning `node`, converting tree-sitter's 0-based rows and byte columns
    /// to the 1-based line/character positions used throughout.
    fn from_node(node: &Node, source_code: &str, comment_text: String) -> Self {
        Self {
            position_range: Position::new(
                node.start_position().row + 1,
                character_column_at(source_code, node.start_byte()),
            )
                ..Position::new(
                    node.end_position().row + 1,
                    character_column_at(source_code, node.end_byte()),
                ),
            source_range: node.start_byte()..node.end_byte(),
            comment_text,
        }
    }

    /// Sets the columns from where the comment's bytes fall in `source`.
    fn set_character_columns(&mut self, source: &str) {
        self.position_range.start.character = character_column_at(source, self.source_range.start);
        self.position_range.end.character = character_column_at(source, self.source_range.end);
    }

    /// Shifts a comment that was parsed from the sub-region spanned by `region_node` into the
    /// coordinates of the full `source`.
    fn shift_into_source(&mut self, region_node: &Node, source: &str) {
        self.position_range.start.line += region_node.start_position().row;
        self.position_range.end.line += region_node.start_position().row;
        self.source_range.start += region_node.start_byte();
        self.source_range.end += region_node.start_byte();
        // A region can start mid-line, so the columns from the region parse are not source columns.
        self.set_character_columns(source);
    }
}

/// Blanks every byte to a space, keeping line breaks (`\n`, `\r`) so that row and column offsets
/// stay aligned with the original bytes.
fn blank_preserving_line_breaks(bytes: &mut [u8]) {
    for byte in bytes {
        if *byte != b'\n' && *byte != b'\r' {
            *byte = b' ';
        }
    }
}

/// C-style comments parser for a query that returns both line and block comments.
fn c_style_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            if node.kind() != comment_node_kind {
                return None;
            }
            let comment = source_code.get(node.byte_range()).unwrap();
            Some(if comment.starts_with("//") {
                comment.replacen("//", "  ", 1)
            } else {
                c_style_multiline_comment_processor(comment)
            })
        }),
    )
}

/// C-style comments parser for the separate line and block comment queries.
fn c_style_line_and_block_comments_parser(
    language: &Language,
    line_comment_node_kind: &'static str,
    block_comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            let kind = node.kind();
            if kind == line_comment_node_kind {
                Some(source_code[node.byte_range()].replacen("//", "  ", 1))
            } else if kind == block_comment_node_kind {
                Some(c_style_multiline_comment_processor(
                    &source_code[node.byte_range()],
                ))
            } else {
                None
            }
        }),
    )
}

/// C-style comments parser that additionally blanks the full `///` doc-comment marker, for
/// languages where `///` is the primary documentation style (e.g. Dart, C#).
fn c_style_and_doc_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            if node.kind() != comment_node_kind {
                return None;
            }
            let comment = &source_code[node.byte_range()];
            Some(if comment.starts_with("///") {
                comment.replacen("///", "   ", 1)
            } else if comment.starts_with("//") {
                comment.replacen("//", "  ", 1)
            } else {
                c_style_multiline_comment_processor(comment)
            })
        }),
    )
}

/// Normalized comment text for a language with C-style line and block comments and a `///`
/// doc-comment style (e.g. Java, Swift), or `None` when `node` is not one of those comments.
fn c_style_and_doc_line_and_block_comment_text(
    node: &Node,
    source_code: &str,
    line_comment_node_kind: &str,
    block_comment_node_kind: &str,
) -> Option<String> {
    let kind = node.kind();
    if kind == line_comment_node_kind {
        let comment = &source_code[node.byte_range()];
        Some(if comment.starts_with("///") {
            comment.replacen("///", "   ", 1)
        } else {
            comment.replacen("//", "  ", 1)
        })
    } else if kind == block_comment_node_kind {
        Some(c_style_multiline_comment_processor(
            &source_code[node.byte_range()],
        ))
    } else {
        None
    }
}

/// Like [`c_style_line_and_block_comments_parser`], but additionally blanks the full `///`
/// doc-comment marker, for languages where `///` is the primary documentation style
/// (e.g. Swift).
fn c_style_and_doc_line_and_block_comments_parser(
    language: &Language,
    line_comment_node_kind: &'static str,
    block_comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            c_style_and_doc_line_and_block_comment_text(
                node,
                source_code,
                line_comment_node_kind,
                block_comment_node_kind,
            )
        }),
    )
}

/// C-style comments parser that also handles the legacy JavaScript HTML-like comments
/// (Annex B of the ECMAScript spec): single lines starting with `<!--` or `-->`.
fn c_style_and_html_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
    html_comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            let kind = node.kind();
            if kind == comment_node_kind {
                let comment = &source_code[node.byte_range()];
                Some(if comment.starts_with("//") {
                    comment.replacen("//", "  ", 1)
                } else {
                    c_style_multiline_comment_processor(comment)
                })
            } else if kind == html_comment_node_kind {
                let comment = &source_code[node.byte_range()];
                Some(if comment.starts_with("<!--") {
                    comment.replacen("<!--", "    ", 1)
                } else {
                    comment.replacen("-->", "   ", 1)
                })
            } else {
                None
            }
        }),
    )
}

/// Comments parser shared by the ECMAScript-family grammars (JavaScript, TypeScript, TSX). All
/// three expose their comments under the same `comment` node kind and recognize the legacy
/// HTML-like comments (`<!--` / `-->`) as `html_comment`, so they differ only in which grammar is
/// loaded.
fn ecmascript_comments_parser(language: &Language) -> TreeSitterCommentsParser {
    c_style_and_html_comments_parser(language, "comment", "html_comment")
}

/// Comments parser for languages that support `#` line comments in addition to the C-style
/// `//` and `/* */` comments.
/// Blanks the leading `//` or `#` line-comment marker, or the `/* */` block-comment delimiters,
/// of a hash-or-C-style comment, preserving the comment's length.
fn hash_and_c_style_comment_text(comment: &str) -> String {
    if comment.starts_with("//") {
        comment.replacen("//", "  ", 1)
    } else if comment.starts_with("#") {
        comment.replacen("#", " ", 1)
    } else {
        c_style_multiline_comment_processor(comment)
    }
}

fn hash_and_c_style_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            if node.kind() != comment_node_kind {
                return None;
            }
            Some(hash_and_c_style_comment_text(
                &source_code[node.byte_range()],
            ))
        }),
    )
}

/// Python-style comments parser.
fn python_style_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            if node.kind() != comment_node_kind {
                return None;
            }
            let comment = &source_code[node.byte_range()];
            Some(if comment.starts_with('#') {
                comment.replacen('#', " ", 1)
            } else {
                // A comment form without a leading `#`: keep it intact rather than blanking a
                // `#` that belongs to its content.
                comment.to_string()
            })
        }),
    )
}

/// XML-style comments parser.
fn xml_style_comments_parser(
    language: &Language,
    comment_node_kind: &'static str,
) -> TreeSitterCommentsParser {
    TreeSitterCommentsParser::new(
        language,
        comment_visitor(move |node, source_code| {
            if node.kind() == comment_node_kind {
                let comment = &source_code[node.byte_range()];
                let open_idx = comment.find("<!--").expect("open comment tag is expected");
                let close_idx = comment.rfind("-->").expect("close comment tag is expected");
                let mut result = String::with_capacity(comment.len());
                result.push_str(&comment[..open_idx]);
                // Replace "<!--" with spaces.
                result.push_str("    ");
                result.push_str(&comment[open_idx + 4..close_idx]);
                // Replace "-->" with spaces.
                result.push_str("   ");
                result.push_str(&comment[close_idx + 3..]);
                Some(result)
            } else {
                None
            }
        }),
    )
}

fn c_style_multiline_comment_processor(comment: &str) -> String {
    let mut result = String::with_capacity(comment.len());
    let open_idx = comment.find("/*").expect("expected '/*' in a comment");
    let close_idx = comment.rfind("*/").expect("expected '*/' in a comment");
    // Add everything before the "/*"
    result.push_str(&comment[..open_idx]);
    // Replace "/*" with spaces.
    result.push_str("  ");
    let content = &comment[open_idx + 2..close_idx];
    for line in content.split_inclusive('\n') {
        let mut decorative_star_found = false;

        // Find the index of the first non-whitespace character
        if let Some(first_non_whitespace_idx) = line.find(|c: char| !c.is_whitespace()) {
            // Check if that first non-whitespace character is a '*'
            if line[first_non_whitespace_idx..].starts_with('*') {
                decorative_star_found = true;
                // Add leading whitespace.
                result.push_str(&line[..first_non_whitespace_idx]);
                // Replace "*" with a space.
                result.push(' ');
                // Add the rest of the line.
                result.push_str(&line[first_non_whitespace_idx + 1..]);
            }
        }
        if !decorative_star_found {
            // Not a decorative '*', or all whitespace. Add unchanged.
            result.push_str(line);
        }
    }
    // Replace "*/" with spaces.
    result.push_str("  ");
    // Add everything after the "*/".
    result.push_str(&comment[close_idx + 2..]);

    result
}