import configparser
import re
from enum import Enum
from pathlib import Path
from urllib.request import pathname2url

from giturlparse import parse
from tree_sitter import Language, Parser, Query, QueryCursor, Tree
from tree_sitter import Node as TreeSitterNode

from sphinx_codelinks.analyse import cpp_macros

# The entity tables live with the naming in ``entity``; they stay importable from
# here, where they were.
from sphinx_codelinks.analyse.entity import (
    COMMENT_TYPES,
    ENTITY_HEAD_TYPES,
    FIRST_ENTITY_WRAPPER_TYPES,
    FIRST_ITEM_WRAPPER_TYPES,
    Association,
    CppNames,
    Mechanism,
    in_function_body,
    is_doc_comment,
    is_entity,
    is_trivia,
    is_wrapper,
    unwrap_entity,
)
from sphinx_codelinks.analyse.entity import (
    ENTITY_NODE_TYPES as ENTITY_NODE_TYPES,
)
from sphinx_codelinks.analyse.entity import (
    SCOPE_NODE_TYPES as SCOPE_NODE_TYPES,
)
from sphinx_codelinks.analyse.entity import (
    SCOPE_PREDICATES as SCOPE_PREDICATES,
)
from sphinx_codelinks.analyse.entity import (
    TRIVIA_TYPES as TRIVIA_TYPES,
)
from sphinx_codelinks.analyse.entity import (
    WRAPPER_TYPES as WRAPPER_TYPES,
)
from sphinx_codelinks.config import CommentCategory
from sphinx_codelinks.logger import get_logger
from sphinx_codelinks.source_discover.config import CommentType

logger = get_logger(__name__)

GIT_HOST_URL_TEMPLATE = {
    "github": "https://github.com/{owner}/{repo}/blob/{rev}/{path}#L{lineno}",
    "gitlab": "https://gitlab.com/{owner}/{repo}/-/blob/{rev}/{path}#L{lineno}",
}

PYTHON_QUERY = """
                ; Match comments
                (comment) @comment

                ; Match docstrings inside modules, functions, or classes
                (module (expression_statement (string)) @comment)
                (function_definition (block (expression_statement (string)) @comment))
                (class_definition (block (expression_statement (string)) @comment))
            """
# The query of every grammar whose comments are one ``comment`` node kind.
SIMPLE_COMMENT_QUERY = """(comment) @comment"""
# ``html_comment`` is a separate node kind the TypeScript/TSX grammars emit
# for ``<!--`` comments: legacy one-line comments, valid in classic scripts only.
# Without matching it, markers written in that style are silently dropped.
TYPE_SCRIPT_QUERY = """
    (comment) @comment
    (html_comment) @comment
"""
RUST_QUERY = """
    (line_comment) @comment
    (block_comment) @comment
"""
# @PowerShell comment nodes open with # or <#, IMPL_PS_16, impl, [FE_POWERSHELL]
# PowerShell's grammar reads some ``#`` text inside an expandable (double-quoted)
# string as a comment node within the string: a ``#`` line of a here-string, unless
# it is the string's first line, and, in an ordinary ``"…"`` string, a ``#`` that
# follows an interpolation past whitespace alone. It is string content. The strings
# are captured as ``string`` and the subexpressions ``$( … )`` as ``string_code``, so
# that :func:`captured_comments` leaves out a comment inside a string unless it is in
# a subexpression of it, which is code. Where such a comment takes the string's
# closing quote in, it lands in an ``ERROR`` node and in no string: it starts with the
# whitespace before its ``#``, so only a node that starts with ``#`` or ``<#``, as
# every PowerShell comment does, is captured.
POWERSHELL_QUERY = """
    ((comment) @comment (#match? @comment "^<?#"))
    (expandable_string_literal) @string
    (expandable_here_string_literal) @string
    (sub_expression) @string_code
"""

# JSON value node types that can be associated with a comment.
JSON_STRUCTURE_TYPES = {
    "pair",
    "object",
    "array",
    "string",
    "number",
    "true",
    "false",
    "null",
}

# TypeScript's own module variants. Legacy angle-bracket type assertions
# (``<T>x``) are valid syntax only here, not under the TSX grammar (see the
# CommentType.ts branch of init_tree_sitter for what goes wrong otherwise), so
# these three suffixes get the plain TypeScript grammar and everything else in
# the JS/TS family falls back to TSX.
TS_STRICT_GRAMMAR_SUFFIXES = {".ts", ".mts", ".cts"}


def ts_grammar_key(src_path: Path) -> str:
    """Return which tree-sitter-typescript grammar ``src_path`` needs.

    ``"typescript"`` for TypeScript's own module variants (``.ts``, ``.mts``,
    ``.cts``); ``"tsx"`` for the rest of the JavaScript/TypeScript family
    (``.tsx``, ``.jsx``, ``.js``, ``.mjs``, ``.cjs``). Used both to pick the
    grammar in ``init_tree_sitter`` and, by callers that parse many files, to
    cache one parser per grammar instead of rebuilding one per file.
    """
    return (
        "typescript" if src_path.suffix.lower() in TS_STRICT_GRAMMAR_SUFFIXES else "tsx"
    )


def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
    """Return True if file is likely text, False if binary."""
    try:
        with filepath.open("rb") as f:
            chunk = f.read(sample_size)
        # Quick binary heuristic: null byte present
        if b"\x00" in chunk:
            return False
        # Try UTF-8 decode on the sample
        chunk.decode("utf-8")
        return True
    except UnicodeDecodeError:
        return False


# @Tree-sitter parser initialization for multiple languages, IMPL_LANG_1, impl, [FE_C_SUPPORT, FE_CPP, FE_PY, FE_YAML, FE_RUST, FE_GO, FE_JSONC, FE_BASH, FE_TS, FE_POWERSHELL, FE_VHDL]
def init_tree_sitter(
    comment_type: CommentType, src_path: Path | None = None
) -> tuple[Parser, Query]:
    """Build the (parser, query) pair for ``comment_type``.

    ``src_path`` only matters for ``CommentType.ts``, whose grammar varies by
    file suffix (see ``ts_grammar_key``); every other comment type ignores it
    and uses a single grammar. When ``src_path`` is omitted the TSX grammar is
    assumed, which is the safe default for the whole JS/TS family except
    TypeScript's own module variants.
    """
    if comment_type == CommentType.cpp:
        import tree_sitter_cpp

        parsed_language = Language(tree_sitter_cpp.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.python:
        import tree_sitter_python

        parsed_language = Language(tree_sitter_python.language())
        query = Query(parsed_language, PYTHON_QUERY)
    elif comment_type == CommentType.cs:
        import tree_sitter_c_sharp

        parsed_language = Language(tree_sitter_c_sharp.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.ts:
        # @TypeScript comment query for tree-sitter, IMPL_TS_3, impl, [FE_TS]
        import tree_sitter_typescript

        # Legacy angle-bracket type assertions (``<T>x``) are valid TypeScript
        # syntax in .ts/.mts/.cts, but the same text is JSX syntax under the TSX
        # grammar: ``<string>x`` parses as a jsx_opening_element and swallows the
        # rest of the file into a single jsx_text node, silently dropping every
        # marker after it. So the plain TypeScript grammar is required for those
        # three suffixes. The TSX grammar remains the fallback for the rest of
        # the JS/TS family (.tsx, .jsx, .js, .mjs, .cjs): JavaScript has no such
        # cast syntax, so TSX is safe there, and it additionally handles JSX
        # embedded in plain .js.
        if src_path is not None and ts_grammar_key(src_path) == "typescript":
            parsed_language = Language(tree_sitter_typescript.language_typescript())
        else:
            parsed_language = Language(tree_sitter_typescript.language_tsx())
        query = Query(parsed_language, TYPE_SCRIPT_QUERY)
    elif comment_type == CommentType.yaml:
        import tree_sitter_yaml

        parsed_language = Language(tree_sitter_yaml.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.rust:
        import tree_sitter_rust

        parsed_language = Language(tree_sitter_rust.language())
        query = Query(parsed_language, RUST_QUERY)
    elif comment_type == CommentType.go:
        # @Go comment query for tree-sitter, IMPL_GO_3, impl, [FE_GO]
        import tree_sitter_go

        parsed_language = Language(tree_sitter_go.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.jsonc:
        import tree_sitter_json

        parsed_language = Language(tree_sitter_json.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.bash:
        # @Bash comment query for tree-sitter, IMPL_BASH_3, impl, [FE_BASH]
        import tree_sitter_bash

        parsed_language = Language(tree_sitter_bash.language())
        query = Query(parsed_language, SIMPLE_COMMENT_QUERY)
    elif comment_type == CommentType.powershell:
        # @PowerShell comment query for tree-sitter, IMPL_PS_3, impl, [FE_POWERSHELL]
        # ``#`` and ``<# #>`` comments are both ``comment`` nodes in this grammar.
        import tree_sitter_powershell

        parsed_language = Language(tree_sitter_powershell.language())
        query = Query(parsed_language, POWERSHELL_QUERY)
    elif comment_type == CommentType.vhdl:
        # @VHDL comment query for tree-sitter, IMPL_VHDL_3, impl, [FE_VHDL]
        import tree_sitter_vhdl

        parsed_language = Language(tree_sitter_vhdl.language())
        # VHDL names its ``--`` and ``/* */`` comments as Rust does
        query = Query(parsed_language, RUST_QUERY)
    else:
        raise ValueError(f"Unsupported comment style: {comment_type}")
    parser = Parser(parsed_language)
    return parser, query


def parse_source(
    src_string: bytes, parser: Parser, comment_type: CommentType, src_path: Path
) -> tuple[Tree, CppNames | None]:
    """The one parse of a source file the analysis reads, and, for a C++ file, what the
    whole file decides about the names of its entities (:class:`CppNames`).

    Every analysis of a file's markers parses it here, so that every C++ name is made
    the one way. A C++ file is parsed from a copy with the namespace macros it defines
    itself rewritten (:mod:`sphinx_codelinks.analyse.cpp_macros`): the tree's offsets
    are the file's, and every comment, name, tagged scope and excerpt is read from
    ``src_string``, through :class:`CppNames` and ``SourceFile.node_text``, never from
    the copy. A ``.c`` file is C: it is parsed as written, and gets no file-level names.

    The whole buffer is parsed in one piece: read one byte at a time, a multi-byte
    UTF-8 character inside a token (a YAML scalar, an identifier, a Rust, Go or C#
    character literal) is lexed as invalid, which loses every YAML comment after it
    and the scope a marker binds to in bash, YAML or Go. Do not reintroduce a read
    callback: a chunk boundary inside a character breaks the parse the same way (a
    from-offset chunk of four bytes or more happens to work; a block-aligned one
    does not).
    """
    if comment_type != CommentType.cpp or not cpp_macros.applies(src_path):
        return parser.parse(src_string), None
    tree, macros = cpp_macros.parse(parser, src_string)
    return tree, CppNames(src_string, tree.root_node, macros)


def captured_comments(tree: Tree, query: Query) -> list[TreeSitterNode] | None:
    """The comment nodes ``query`` captures in ``tree``.

    A query may also capture ``string`` nodes, in which a grammar places comment
    nodes that are string content (PowerShell's double-quoted strings), and
    ``string_code`` nodes, the code such a string holds (PowerShell's ``$( … )``). A
    comment is left out when, of those, the nearest one around it is a ``string``.
    """
    query_cursor = QueryCursor(query)
    captures: dict[str, list[TreeSitterNode]] = query_cursor.captures(tree.root_node)
    comments = captures.get("comment")
    strings = {node.id for node in captures.get("string", ())}
    if comments and strings:
        code = {node.id for node in captures.get("string_code", ())}
        comments = [
            comment for comment in comments if not _in_string(comment, strings, code)
        ]
    return comments


# @PowerShell comments inside strings are string content, IMPL_PS_7, impl, [FE_POWERSHELL]
def _in_string(node: TreeSitterNode, strings: set[int], code: set[int]) -> bool:
    """Whether the nearest of ``strings`` and ``code`` (node ids) around ``node`` is a
    string."""
    ancestor = node.parent
    while ancestor is not None:
        if ancestor.id in code:
            return False
        if ancestor.id in strings:
            return True
        ancestor = ancestor.parent
    return False


# @Comment extraction from source code using tree-sitter, IMPL_EXTR_1, impl, [FE_DEF]
def extract_comments(
    src_string: bytes, parser: Parser, query: Query
) -> list[TreeSitterNode] | None:
    """Get all comments from source files by tree-sitter.

    The buffer is parsed whole, as :func:`parse_source` explains; the analysis parses
    through :func:`parse_source`, and this is its comment capture alone.
    """
    return captured_comments(parser.parse(src_string), query)


def find_enclosing_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """The nearest entity ``node`` is inside of, if any. A wrapper ``node`` is inside of
    (a decorated definition, a template) counts as the entity it wraps; a PowerShell
    pipeline only when ``node`` is inside that entity, not in another of its commands."""
    current = node.parent
    while current is not None:
        if is_entity(current, comment_type):
            return current
        if is_wrapper(current, comment_type):
            wrapped = unwrap_entity(current, comment_type)
            if wrapped is not None and (
                current.type not in FIRST_ENTITY_WRAPPER_TYPES.get(comment_type, ())
                or _contains(wrapped, node)
            ):
                return wrapped
        current = current.parent
    return None


def _contains(outer: TreeSitterNode, node: TreeSitterNode) -> bool:
    """Whether ``node`` lies within ``outer``: a pipeline's entity is not around a
    comment in another command of the pipeline (``Describe 'x' { } | ForEach-Object {
    # c }``)."""
    return outer.start_byte <= node.start_byte and node.end_byte <= outer.end_byte


# The nodes a PowerShell script or script block holds its statements in. A comment
# before the first statement of a body, or after the last one on its row, is their
# sibling, not the statements'.
POWERSHELL_BODY_TYPES = frozenset(
    {"statement_list", "script_block", "script_block_body"}
)


def _first_named_inside(
    node: TreeSitterNode, wrappers: frozenset[str]
) -> TreeSitterNode:
    """``node``'s first named child, followed while the node is one of ``wrappers``, or
    ``node`` itself when it is none of them or wraps nothing."""
    while node.type in wrappers and node.named_children:
        node = node.named_children[0]
    return node


def _last_named_inside(
    node: TreeSitterNode, wrappers: frozenset[str]
) -> TreeSitterNode:
    """``node``'s last named child, followed while the node is one of ``wrappers``, or
    ``node`` itself when it is none of them or wraps nothing.

    No comment is skipped: where the trailing path looks into a body, a comment on the
    marker's row after the body's last statement is the marker itself, or beside the
    body with it, never last in the body (no input in a corpus of 610 files or in
    generated shapes reached one).
    """
    while node.type in wrappers and node.named_children:
        node = node.named_children[-1]
    return node


def find_next_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """The entity right after the comment ``node``, if only trivia stands between.

    Comments, blank lines and the language's other trivia (attributes, decorators) are
    skipped; anything else, a statement or a declaration that is no entity, ends the
    search. A comment Python's grammar places between a header (``def f():``) and its
    body is followed by the body's first statement; in every other grammar a block
    after a comment is the body of the entity the comment is inside. The entity found
    is looked through its wrappers (``@decorator``, ``template <…>``, ``export``).

    PowerShell's grammar places a comment before a body's first statement beside the
    body (its statement list, or the script block holding it), so such a comment is
    followed by that first statement too.
    """
    sibling = node.next_named_sibling
    while sibling is not None and is_trivia(sibling, comment_type):
        sibling = sibling.next_named_sibling
    if (
        comment_type == CommentType.python
        and sibling is not None
        and sibling.type == "block"
    ):
        sibling = next(
            (c for c in sibling.named_children if not is_trivia(c, comment_type)),
            None,
        )
    # @PowerShell next entity across statement bodies, IMPL_PS_6, impl, [FE_POWERSHELL]
    if comment_type == CommentType.powershell and sibling is not None:
        sibling = _first_named_inside(sibling, POWERSHELL_BODY_TYPES)
    if sibling is not None:
        sibling = _first_item(sibling, comment_type)
    return unwrap_entity(sibling, comment_type)


# @VHDL next entity through a wrapper's first item, IMPL_VHDL_4, impl, [FE_VHDL]
def _first_item(
    node: TreeSitterNode, comment_type: CommentType
) -> TreeSitterNode | None:
    """The first item of ``node`` when it is one of the language's first-item wrappers
    (:data:`FIRST_ITEM_WRAPPER_TYPES`), past comments and the child kinds the wrapper
    passes over (a VHDL design unit's context clauses); else ``node`` itself."""
    passed = FIRST_ITEM_WRAPPER_TYPES.get(comment_type, {}).get(node.type)
    if passed is None:
        return node
    return next(
        (
            child
            for child in node.named_children
            if not is_trivia(child, comment_type) and child.type not in passed
        ),
        None,
    )


def _code_before_on_row(node: TreeSitterNode) -> bool:
    """Whether code precedes the comment ``node`` on its first row.

    Walks the previous siblings, anonymous tokens included and comments skipped,
    climbing to the parent when there are none. A token that ends at column 0 of the
    row (a preprocessor directive's newline) is not on it, and an entity's head (an
    attribute, a decorator, a template header) is no code: the item it opens follows.
    """
    current: TreeSitterNode | None = node
    while current is not None:
        previous = current.prev_sibling
        while previous is not None and previous.type in COMMENT_TYPES:
            previous = previous.prev_sibling
        if previous is not None:
            if previous.type in ENTITY_HEAD_TYPES:
                return False
            return (
                previous.end_point.row == node.start_point.row
                and previous.end_point.column > 0
            )
        current = current.parent
    return False


def _entity_on_row(
    node: TreeSitterNode, comment_type: CommentType
) -> TreeSitterNode | None:
    """The entity that ends on the trailing comment ``node``'s row, before it.

    PowerShell's grammar places a comment after a body's last statement beside the
    body, so the entity is looked for at the end of that body.
    """
    previous = node.prev_named_sibling
    while previous is not None and previous.type in COMMENT_TYPES:
        previous = previous.prev_named_sibling
    if previous is not None and previous.end_point.row == node.start_point.row:
        # @PowerShell entity on a trailing marker's row, IMPL_PS_9, impl, [FE_POWERSHELL]
        if comment_type == CommentType.powershell:
            previous = _last_named_inside(previous, POWERSHELL_BODY_TYPES)
        if comment_type == CommentType.vhdl:
            return _innermost_on_row(previous, node.start_point.row, comment_type)
        return unwrap_entity(previous, comment_type)
    return None


# @VHDL entity on a trailing marker's row, IMPL_VHDL_6, impl, [FE_VHDL]
def _innermost_on_row(
    node: TreeSitterNode, row: int, comment_type: CommentType
) -> TreeSitterNode | None:
    """The innermost entity of ``node``'s subtree, ``node`` included, that ends on
    ``row``, following the last child that is no comment and ends there.

    VHDL's grammar places a comment after a declaration beside the declarative part
    that holds it (an architecture's ``signal s : bit; -- c`` is beside the
    architecture's head), and a comment after a port beside the port, so the entity
    a trailing comment follows is looked for down the subtree that ends on its row.

    The search does not enter a subprogram's parameter list: after
    ``procedure inc(variable v : inout integer); -- c`` the list ends on the row too,
    and the comment follows the subprogram, not its last parameter. A comment inside a
    list written over several rows starts its search at the parameter before it.
    """
    found = None
    current: TreeSitterNode | None = node
    while current is not None and current.type not in _ROW_SEARCH_STOP_TYPES:
        if is_entity(current, comment_type):
            found = current
        current = next(
            (
                child
                for child in reversed(current.named_children)
                if child.type not in COMMENT_TYPES and child.end_point.row == row
            ),
            None,
        )
    return found


# The nodes :func:`_innermost_on_row` does not enter: a VHDL subprogram's parameter list.
_ROW_SEARCH_STOP_TYPES = frozenset({"parameter_list_specification"})


def _is_file_header(node: TreeSitterNode) -> bool:
    """Whether the comment ``node`` is one of the comments before the file's first item,
    and a blank line separates the last of them from that item."""
    parent = node.parent
    if parent is None or parent.parent is not None:
        return False
    siblings = parent.children
    index = 0
    in_block = False
    last_comment: TreeSitterNode | None = None
    while index < len(siblings) and siblings[index].type in COMMENT_TYPES:
        if siblings[index].id == node.id:
            in_block = True
        last_comment = siblings[index]
        index += 1
    if not in_block or last_comment is None or index >= len(siblings):
        return in_block
    return siblings[index].start_point.row - _last_row(last_comment) > 1


def _last_row(comment: TreeSitterNode) -> int:
    """The last row the ``comment`` node is written on."""
    if comment.end_point.column == 0:
        # a Rust doc line comment (``///``) takes its line break in its ``doc_comment``
        # child, so its node ends at column 0 of the next row
        return comment.end_point.row - 1
    return comment.end_point.row


# The tokens that open the line of a C or C++ preprocessor conditional, as the grammar
# names them (``# if`` is ``#if`` too).
_CONDITIONAL_DIRECTIVES = frozenset(
    {"#if", "#ifdef", "#ifndef", "#elif", "#elifdef", "#elifndef", "#else", "#endif"}
)


def _directly_above_a_conditional(node: TreeSitterNode) -> bool:
    """Whether the line of a preprocessor conditional (``#if`` ... ``#endif``) comes
    right after the comment ``node``: past other comments only, and with no blank line
    between.

    When ``node`` ends a conditional's arm, what comes next is the arm's parent's: the
    next ``#elif`` or ``#else``, or the ``#endif``.
    """
    last_row = _last_row(node)
    current = node
    while True:
        following = current.next_sibling
        outer = current
        while following is None and outer.parent is not None:
            outer = outer.parent
            following = outer.next_sibling
        if following is None or following.start_point.row - last_row > 1:
            return False
        if following.type not in COMMENT_TYPES:
            break
        last_row = _last_row(following)
        current = following
    while following.child_count:
        following = following.children[0]
    return following.type in _CONDITIONAL_DIRECTIVES


class Unattached(Enum):
    """Why :func:`associate` attached a comment to no entity, where the analysis
    warns about it; every other comment on nothing is ``None``."""

    above_conditional = "above_conditional"
    """Rule 7: a C or C++ comment directly above a preprocessor conditional's line,
    outside a function's body."""


# A Doxygen or JSDoc tag saying a documentation comment documents the file, not the
# item after it: at the start of the text or after ASCII whitespace, ``*``, ``/`` or
# ``!``, and ending the word, which is ASCII (as Doxygen and JSDoc commands are).
_FILE_DOC_TAG = re.compile(
    r"(?:^|(?<=[ \t\n\r\f\v*/!]))[@\\]"
    r"(?:file|fileoverview|packageDocumentation|module)(?![A-Za-z0-9_])"
)


def documents_file(text: str) -> bool:
    """Whether a documentation comment's ``text`` says it documents the file.

    It does when a file tag (Doxygen's file command, JSDoc's fileoverview, module and
    packageDocumentation tags, see ``_FILE_DOC_TAG``) appears as a whole word, at the
    start or after whitespace or one of ``*/!``; an address such as ``a@file.com`` or a
    longer word such as ``@filename`` does not count.
    """
    return _FILE_DOC_TAG.search(text) is not None


# @A VHDL doc comment is its run of --! lines, IMPL_VHDL_7, impl, [FE_VHDL]
def _doc_block_text(
    node: TreeSitterNode, comment_type: CommentType, written: bytes
) -> str:
    """The text of the documentation block the doc comment ``node`` is part of, which
    rule 5 reads for a file tag.

    A block comment is its own block. VHDL has no block doc comment: Doxygen reads a
    run of ``--!`` lines on consecutive rows as one block, so a ``--! @file`` line
    makes the whole run document the file, the lines after it included.
    """
    if comment_type != CommentType.vhdl:
        return written.decode("utf-8", "replace")
    lines = [written]
    current = node
    while (previous := current.prev_sibling) is not None and _continues_doc_run(
        previous, current, comment_type
    ):
        lines.insert(0, previous.text or b"")
        current = previous
    current = node
    while (following := current.next_sibling) is not None and _continues_doc_run(
        current, following, comment_type
    ):
        lines.append(following.text or b"")
        current = following
    return b"\n".join(lines).decode("utf-8", "replace")


def _continues_doc_run(
    upper: TreeSitterNode, lower: TreeSitterNode, comment_type: CommentType
) -> bool:
    """Whether the comment ``lower`` continues the doc comment run ``upper`` is in: both
    documentation line comments, ``lower`` on the row after ``upper``'s last."""
    return (
        upper.type in COMMENT_TYPES
        and lower.type in COMMENT_TYPES
        and lower.start_point.row == _last_row(upper) + 1
        and is_doc_comment(upper, comment_type)
        and is_doc_comment(lower, comment_type)
    )


def _in_head_of(
    node: TreeSitterNode, entity: TreeSitterNode, comment_type: CommentType
) -> bool:
    """Whether the comment ``node`` sits in ``entity``'s head: inside, or right after, an
    attribute, a decorator or a template header that ``entity`` (or its wrapper) owns."""
    parent = node.parent
    head = parent if parent is not None and parent.type in ENTITY_HEAD_TYPES else None
    if head is None:
        previous = node.prev_sibling
        while previous is not None and previous.type in COMMENT_TYPES:
            previous = previous.prev_sibling
        if previous is not None and previous.type in ENTITY_HEAD_TYPES:
            head = previous
    owner = head.parent if head is not None else None
    if owner is None:
        return False
    if owner.id == entity.id:
        return True
    if not is_wrapper(owner, comment_type):
        return False
    wrapped = unwrap_entity(owner, comment_type)
    return wrapped is not None and wrapped.id == entity.id


def _is_inner_doc(text: bytes, comment_type: CommentType) -> bool:
    """Whether the comment ``text`` is a Rust inner doc comment (``//!``, ``/*!``): it
    documents what it is inside."""
    if comment_type != CommentType.rust:
        return False
    return text.startswith((b"//!", b"/*!"))


# PowerShell's comment-based-help keyword lines: a line of a comment that holds a
# help keyword alone, or a keyword that takes an argument and that one argument, with
# whitespace around, in any letter case, makes the comment help.
_POWERSHELL_HELP_KEYWORD = re.compile(
    r"^[ \t]*\.(?:"
    r"(?:SYNOPSIS|DESCRIPTION|EXAMPLE|INPUTS|OUTPUTS|NOTES|LINK|COMPONENT|ROLE"
    r"|FUNCTIONALITY)"
    r"|(?:PARAMETER|FORWARDHELPTARGETNAME|FORWARDHELPCATEGORY|REMOTEHELPRUNSPACE"
    r"|EXTERNALHELP)(?:[ \t]+[^ \t\r\n]+)?"
    r")[ \t\r]*$",
    re.IGNORECASE | re.MULTILINE,
)


def _powershell_hash_run(node: TreeSitterNode) -> list[TreeSitterNode]:
    """The ``#`` comments on consecutive rows that the ``#`` comment ``node`` is one
    of, in order."""
    run = [node]
    previous = node.prev_named_sibling
    while (
        previous is not None
        and previous.type in COMMENT_TYPES
        and not (previous.text or b"").startswith(b"<#")
        and previous.end_point.row == run[0].start_point.row - 1
    ):
        run.insert(0, previous)
        previous = previous.prev_named_sibling
    following = node.next_named_sibling
    while (
        following is not None
        and following.type in COMMENT_TYPES
        and not (following.text or b"").startswith(b"<#")
        and following.start_point.row == run[-1].end_point.row + 1
    ):
        run.append(following)
        following = following.next_named_sibling
    return run


# @PowerShell comment-based help documents its function, IMPL_PS_14, impl, [FE_POWERSHELL]
def powershell_help_function(
    node: TreeSitterNode, text: bytes | None = None
) -> TreeSitterNode | None:
    """The function whose comment-based help the comment ``node`` is, first in its body.

    Help is a ``<# #>`` comment, or a run of ``#`` comments on consecutive rows,
    holding a comment-based-help keyword line: a line that holds a keyword
    (``.SYNOPSIS``, ``.DESCRIPTION``, ``.EXAMPLE``, ...) alone, or one that takes an
    argument with that argument (``.PARAMETER Path``), in any letter case. First in
    the body is before every statement of the function's body (its ``param`` block
    included), where the grammar places it as the function's child.

    :param text: The comment's text as the file writes it; ``node.text`` when not given.
    """
    parent = node.parent
    if parent is None or parent.type != "function_statement":
        return None
    body = next((c for c in parent.named_children if c.type == "script_block"), None)
    if body is not None and node.start_byte > body.start_byte:
        return None
    written = (node.text or b"") if text is None else text
    if written.startswith(b"<#"):
        help_text = written[2:-2] if written.endswith(b"#>") else written[2:]
    else:
        help_text = b"\n".join(
            (comment.text or b"")[1:] for comment in _powershell_hash_run(node)
        )
    if _POWERSHELL_HELP_KEYWORD.search(help_text.decode("utf-8", "replace")) is None:
        return None
    return parent


def _find_yaml_structure_in_block_node(
    block_node: TreeSitterNode,
) -> TreeSitterNode | None:
    """Find YAML structure elements within a block_node."""
    for grandchild in block_node.named_children:
        if grandchild.type == "block_mapping":
            for ggchild in grandchild.named_children:
                if ggchild.type == "block_mapping_pair":
                    return ggchild
        elif grandchild.type == "block_sequence":
            for ggchild in grandchild.named_children:
                if ggchild.type == "block_sequence_item":
                    return ggchild
    return None


def find_yaml_next_structure(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find the next YAML structure element after the comment node."""
    current = node.next_named_sibling
    while current:
        if current.type in {
            "block_mapping_pair",
            "block_sequence_item",
            "flow_mapping",
            "flow_sequence",
        }:
            return current
        if current.type == "document":
            for child in current.named_children:
                if child.type == "block_node":
                    result = _find_yaml_structure_in_block_node(child)
                    if result:
                        return result
        if current.type == "block_node":
            result = _find_yaml_structure_in_block_node(current)
            if result:
                return result
        current = current.next_named_sibling
    return None


def find_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find a previous named sibling that is on the same row as the comment.

    Grammar-agnostic: used to detect inline comments in both YAML and JSONC.
    """
    comment_row = node.start_point.row
    current = node.prev_named_sibling

    while current:
        # Check if this sibling ends on the same row as the comment starts
        # This indicates it's an inline comment
        if current.end_point.row == comment_row:
            return current
        # If we find a sibling that ends before the comment row, we can stop
        # as we won't find any siblings on the same row going backwards
        if current.end_point.row < comment_row:
            break
        current = current.prev_named_sibling

    return None


def _yaml_associate(node: TreeSitterNode) -> Association | None:
    """The YAML structure (key-value pair, list item, etc.) a comment is attached to."""
    # First, check if this is an inline comment by looking for a previous sibling on the same row
    prev_sibling_same_row = find_prev_sibling_on_same_row(node)
    if prev_sibling_same_row:
        return Association(prev_sibling_same_row, "trailing")

    # If no previous sibling on same row, try to find the next named sibling (structure after the comment)
    structure = find_yaml_next_structure(node)
    if structure:
        return Association(structure, "leading")

    # If no next sibling found, traverse up to find parent structure
    parent = node.parent
    while parent:
        if parent.type in {"block_mapping_pair", "block_sequence_item"}:
            return Association(parent, "enclosing")
        parent = parent.parent

    return None


def find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find the YAML structure (key-value pair, list item, etc.) associated with a comment."""
    association = _yaml_associate(node)
    return association.node if association is not None else None


# @JSONC comment-to-structure association, IMPL_JSONC_2, impl, [FE_JSONC]
def _jsonc_associate(node: TreeSitterNode) -> Association | None:
    """Find the JSON structure (key/value pair, value, list item) for a comment.

    JSON is data rather than code, so association follows the same intent as YAML:
    an inline comment belongs to the value on its row, a leading comment belongs to
    the following structure, otherwise it belongs to the enclosing structure.
    """
    # Inline comment: a value/pair on the same row, before the comment
    prev_sibling_same_row = find_prev_sibling_on_same_row(node)
    if prev_sibling_same_row:
        return Association(prev_sibling_same_row, "trailing")

    # Leading comment: the next structure following the comment
    current = node.next_named_sibling
    while current:
        if current.type in JSON_STRUCTURE_TYPES:
            return Association(current, "leading")
        current = current.next_named_sibling

    # Otherwise: the enclosing structure
    parent = node.parent
    while parent:
        if parent.type in {"pair", "object", "array"}:
            return Association(parent, "enclosing")
        parent = parent.parent

    return None


def find_jsonc_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find the JSON structure (key/value pair, value, list item) for a comment."""
    association = _jsonc_associate(node)
    return association.node if association is not None else None


# @Attach a marker to the adjacent code entity, IMPL_ENTITY_1, impl, [FE_DEF]
def associate(
    node: TreeSitterNode,
    comment_type: CommentType = CommentType.cpp,
    *,
    text: bytes | None = None,
) -> Association | Unattached | None:
    """The entity a comment is attached to, and how (see :data:`Mechanism`).

    The rules, in order:

    1. YAML and JSONC: the data structure on the comment's row, else the next one,
       else the enclosing one.
    2. A Python docstring documents the definition it is in.
    3. A Rust inner doc comment (``//!``) documents what it is inside, and PowerShell
       comment-based help first in a function's body documents that function (see
       :func:`powershell_help_function`).
    4. A trailing comment (code before it on its row) belongs to the entity on its
       row, else to the enclosing one; an attribute, a decorator or a template header
       before it is no code.
    5. The comments before the file's first item, when a blank line separates the last
       of them from it, belong to the file: no entity. A documentation comment is
       exempt: it documents the next item, blank lines or not (rustc, Doxygen) --
       unless it says it documents the file (``@file``, ``@fileoverview``).
    6. A leading comment belongs to the entity right after it, when only trivia
       stands between (comments, blank lines, attributes, decorators), through its
       wrappers; never across other code.
    7. A C or C++ comment directly above the line of a preprocessor conditional
       (``#if``, ``#ifdef``, ``#ifndef``, ``#elif``, ``#elifdef``, ``#elifndef``,
       ``#else``, ``#endif``, as the grammar reads them) -- past other comments,
       with no blank line between -- belongs to no entity anywhere outside a
       function's body (at file level, in a namespace, class, struct, union or enum
       body, or in an ``extern "C"`` block): clang attaches a comment to no
       declaration across a ``#`` line. With a blank line between, or in a
       function's body (a lambda's, or a class defined in one, included), rule 8
       holds.
    8. Otherwise, the enclosing entity, if any.

    A documentation comment attached by rule 4 or 6 is a ``doc_comment``. By rule 8, a
    comment in the entity's head (after an attribute, a decorator or a template header
    the entity owns) leads it, and a trailing comment whose entity starts on its row
    (``def f():  # c``) is ``trailing``; any other is ``enclosing``.

    :param node: The comment node, or a Python docstring's ``expression_statement``.
    :param comment_type: The language of the file ``node`` was parsed from.
    :param text: The comment's text as the file writes it (``SourceComment.text``),
        where a C++ tree is parsed from a prepared copy; ``node.text`` when not given.
    :return: The association; :attr:`Unattached.above_conditional` when rule 7
        attaches the comment to no entity, and ``None`` when another rule does (file
        level).
    """
    if comment_type == CommentType.yaml:
        # YAML uses different structure association logic
        return _yaml_associate(node)

    if comment_type == CommentType.jsonc:
        # JSONC uses data-aware structure association logic
        return _jsonc_associate(node)

    written = (node.text or b"") if text is None else text
    declared: Mechanism = "doc_comment"
    if node.type == CommentCategory.docstring or _is_inner_doc(written, comment_type):
        scope = find_enclosing_scope(node, comment_type)
        return Association(scope, declared) if scope is not None else None
    if comment_type == CommentType.powershell:
        documented = powershell_help_function(node, written)
        if documented is not None:
            return Association(documented, declared)
    is_doc = is_doc_comment(node, comment_type, text=written)

    def enclosing(trailing: bool = False) -> Association | None:
        scope = find_enclosing_scope(node, comment_type)
        if scope is None:
            return None
        if _in_head_of(node, scope, comment_type):
            return Association(scope, declared if is_doc else "leading")
        if trailing and scope.start_point.row == node.start_point.row:
            return Association(scope, declared if is_doc else "trailing")
        return Association(scope, "enclosing")

    if _code_before_on_row(node):
        entity = _entity_on_row(node, comment_type)
        if entity is None:
            return enclosing(trailing=True)
        return Association(entity, declared if is_doc else "trailing")
    if _is_file_header(node) and (
        not is_doc or documents_file(_doc_block_text(node, comment_type, written))
    ):
        return None
    entity = find_next_scope(node, comment_type)
    if entity is None:
        if (
            comment_type == CommentType.cpp
            and not in_function_body(node)
            and _directly_above_a_conditional(node)
        ):
            return Unattached.above_conditional
        return enclosing()
    return Association(entity, declared if is_doc else "leading")


def find_associated_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """Find the associated scope of a comment: the node :func:`associate` binds."""
    association = associate(node, comment_type)
    return association.node if isinstance(association, Association) else None


def _git_dir(path: Path) -> Path | None:
    """The git directory for a checkout rooted at ``path``, or None if it is not one.

    In a plain checkout ``.git`` is a directory. In a LINKED WORKTREE it is a file
    holding ``gitdir: <path>`` -- git's documented gitfile format -- and the real
    directory is elsewhere, under the main repository's ``.git/worktrees/<name>``.
    Treating the file as "not a repository" is what made every worktree of this
    repository look unversioned (useblocks/sphinx-codelinks#106).
    """
    dot_git = path / ".git"
    if dot_git.is_dir():
        return dot_git
    if dot_git.is_file():
        content = dot_git.read_text(encoding="utf-8", errors="replace").strip()
        if content.startswith("gitdir:"):
            target = Path(content.split(":", 1)[1].strip())
            if not target.is_absolute():
                target = (path / target).resolve()
            if target.is_dir():
                return target
    return None


def _git_common_dir(git_dir: Path) -> Path:
    """The repository-wide git directory that ``git_dir`` belongs to.

    A linked worktree's git directory carries a ``commondir`` file naming the main
    repository's, and that is where ``config`` and every shared ref live -- only
    per-worktree state (``HEAD``, ``refs/bisect``, ``refs/worktree``) is local. A plain
    checkout has no ``commondir`` and the two are the same directory.
    """
    commondir = git_dir / "commondir"
    if not commondir.is_file():
        return git_dir
    target = Path(commondir.read_text(encoding="utf-8").strip())
    if not target.is_absolute():
        target = (git_dir / target).resolve()
    return target


def find_git_root(src_dir: Path) -> Path | None:
    """The git root :func:`locate_git_root` finds, without its warning when none."""
    current = src_dir.resolve()
    parents = list(current.parents)
    parents.append(current)
    for parent in parents:
        if _git_dir(parent) is not None:
            return parent
    return None


def locate_git_root(src_dir: Path) -> Path | None:
    """Traverse upwards to find git root."""
    found = find_git_root(src_dir)
    if found is not None:
        return found
    logger.warning(
        f"git root is not found in the parent of {src_dir}",
        subtype="git_root",
        location=str(src_dir),
    )
    return None


def get_remote_url(git_root: Path, remote_name: str = "origin") -> str | None:
    """Get remote url from the git directory's config."""
    git_dir = _git_dir(git_root)
    # a worktree's remotes are the main repository's, so `config` is in the common dir
    config_path = (
        _git_common_dir(git_dir) if git_dir is not None else git_root / ".git"
    ) / "config"
    if not config_path.exists():
        logger.warning(
            f"{config_path} does not exist",
            subtype="git_config",
            location=str(config_path),
        )
        return None

    config = configparser.ConfigParser(allow_no_value=True, strict=False)
    config.read(config_path)
    section = f'remote "{remote_name}"'
    if section in config and "url" in config[section]:
        url: str = config[section]["url"]
        return url
    logger.warning(
        f"remote-url is not found in {config_path}",
        subtype="git_remote",
        location=str(config_path),
    )
    return None


def _packed_ref(common_dir: Path, ref: str) -> str | None:
    """The sha ``packed-refs`` records for ``ref``, or None.

    A ref has no file of its own once ``git gc`` (or ``git pack-refs``) has run, which
    happens unattended on any long-lived checkout -- so a loose-file lookup alone reports
    "no rev" for a perfectly ordinary repository. The file is one ``<sha> <refname>`` per
    line; ``^<sha>`` lines are the peeled targets of annotated tags and are skipped, as
    is the leading ``#`` header.
    """
    packed = common_dir / "packed-refs"
    if not packed.is_file():
        return None
    for line in packed.read_text(encoding="utf-8", errors="replace").splitlines():
        if not line or line.startswith(("#", "^")):
            continue
        sha, _, name = line.partition(" ")
        if name.strip() == ref:
            return sha
    return None


def get_current_rev(git_root: Path) -> str | None:
    """Get current commit rev from the git directory's HEAD."""
    # HEAD is per-worktree, so it is read from the worktree's OWN git directory
    git_dir = _git_dir(git_root) or git_root / ".git"
    head_path = git_dir / "HEAD"
    if not head_path.exists():
        logger.warning(
            f"{head_path} does not exist",
            subtype="git_head",
            location=str(head_path),
        )
        return None
    head_content = head_path.read_text().strip()
    if not head_content.startswith("ref: "):
        # Detached HEAD (e.g. CI checkouts): .git/HEAD holds the commit SHA
        # directly, which is exactly the rev we want.
        return head_content

    ref = head_content.split(":", 1)[1].strip()
    common_dir = _git_common_dir(git_dir)
    ref_path = git_dir / ref
    if not ref_path.exists():
        # every branch is a SHARED ref, so in a worktree it lives in the common
        # directory; only refs/bisect and refs/worktree are per-worktree
        ref_path = common_dir / ref
    if ref_path.exists():
        return ref_path.read_text().strip()
    packed = _packed_ref(common_dir, ref)
    if packed is not None:
        return packed
    logger.warning(
        f"{ref_path} does not exist",
        subtype="git_ref",
        location=str(ref_path),
    )
    return None


def form_https_url(
    git_url: str, rev: str, project_path: Path, filepath: Path, lineno: int
) -> str | None:
    parsed_url = parse(git_url)
    template = GIT_HOST_URL_TEMPLATE.get(parsed_url.platform)
    if not template:
        logger.warning(
            f"Unsupported Git host: {parsed_url.platform}",
            subtype="git_host",
        )
        return git_url
    https_url = template.format(
        owner=parsed_url.owner,
        repo=parsed_url.repo,
        rev=rev,
        path=pathname2url(str(filepath.absolute().relative_to(project_path))),
        lineno=str(lineno),
    )
    return https_url