import configparser
from collections.abc import Callable
from pathlib import Path
from urllib.request import pathname2url

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

from sphinx_codelinks.config import CommentCategory
from sphinx_codelinks.logger import get_logger
from sphinx_codelinks.source_discover.config import CommentType

# Language-specific node types for scope detection.
#
# YAML and JSONC are intentionally absent. They are data formats, not code, so a
# comment associates with the surrounding data structure (key/value pair, list
# item, or scalar) rather than with an enclosing or following declaration. That
# needs a different algorithm (inline same-row association first, scalar targets,
# grammar-specific traversal), implemented in find_yaml_associated_structure and
# find_jsonc_associated_structure and dispatched from find_associated_scope.
# Those bespoke finders never read this table (only find_next_scope and
# find_enclosing_scope do), so an entry here would be dead.
SCOPE_NODE_TYPES = {
    # @Python Scope Node Types, IMPL_PY_2, impl, [FE_PY]
    CommentType.python: {"function_definition", "class_definition"},
    # @C and C++ Scope Node Types, IMPL_C_2, impl, [FE_C_SUPPORT, FE_CPP]
    CommentType.cpp: {"function_definition", "class_specifier", "struct_specifier"},
    CommentType.cs: {"method_declaration", "class_declaration", "property_declaration"},
    # @TypeScript Scope Node Types, IMPL_TS_2, impl, [FE_TS]
    # The last five are scopes only when they hold a function or a class: see
    # SCOPE_PREDICATES.
    CommentType.ts: {
        "function_declaration",
        "generator_function_declaration",
        "function_signature",
        "class_declaration",
        "abstract_class_declaration",
        "interface_declaration",
        "type_alias_declaration",
        "enum_declaration",
        "module",
        "internal_module",
        "method_definition",
        "method_signature",
        "abstract_method_signature",
        "lexical_declaration",
        "variable_declaration",
        "public_field_definition",
        "assignment_expression",
        "export_statement",
    },
    # @Rust Scope Node Types, IMPL_RUST_2, impl, [FE_RUST]
    CommentType.rust: {
        "function_item",
        "struct_item",
        "enum_item",
        "impl_item",
        "trait_item",
        "mod_item",
    },
    # @Go Scope Node Types, IMPL_GO_4, impl, [FE_GO]
    CommentType.go: {
        "function_declaration",
        "method_declaration",
        "type_declaration",
        "type_spec",
    },
    # @Bash Scope Node Types, IMPL_BASH_2, impl, [FE_BASH]
    CommentType.bash: {"function_definition"},
    # @VHDL Scope Node Types, IMPL_VHDL_2, impl, [FE_VHDL]
    # VHDL's design elements, which find_vhdl_associated_scope binds a marker to.
    # Sequential statements are not among them: a marker among those documents its
    # process or subprogram.
    CommentType.vhdl: {
        # design units
        "entity_declaration",
        "architecture_definition",
        "package_declaration",
        "package_definition",
        "package_instantiation_declaration",
        "configuration_declaration",
        "context_declaration",
        # subprograms
        "subprogram_declaration",
        "subprogram_definition",
        "subprogram_instantiation_declaration",
        # declarations
        "type_declaration",
        "subtype_declaration",
        "component_declaration",
        "constant_declaration",
        "signal_declaration",
        "variable_declaration",
        "file_declaration",
        "alias_declaration",
        # generics, ports and parameters
        "interface_declaration",
        "interface_constant_declaration",
        "interface_signal_declaration",
        "interface_variable_declaration",
        "interface_file_declaration",
        "interface_type_declaration",
        "interface_subprogram_declaration",
        "interface_package_declaration",
        # concurrent statements
        "process_statement",
        "block_statement",
        "for_generate_statement",
        "if_generate_statement",
        "case_generate_statement",
        "component_instantiation_statement",
        "concurrent_simple_signal_assignment",
        "concurrent_conditional_signal_assignment",
        "concurrent_selected_signal_assignment",
        "concurrent_assertion_statement",
        "concurrent_procedure_call_statement",
    },
}

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
"""

# 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_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.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


# @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 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).
    """
    tree = parser.parse(src_string)
    query_cursor = QueryCursor(query)
    captures: dict[str, list[TreeSitterNode]] = query_cursor.captures(tree.root_node)

    return captures.get("comment")


# What a TypeScript declaration's value can be wrapped in without changing what it
# is: ``(() => {}) as Handler``, ``<Handler>(() => {})``, ``f!``, ``x satisfies T``.
TS_VALUE_WRAPPER_TYPES = {
    "parenthesized_expression",
    "as_expression",
    "satisfies_expression",
    "non_null_expression",
    "type_assertion",
}
# The values that make a declaration a scope.
TS_FUNCTION_VALUE_TYPES = {
    "arrow_function",
    "function_expression",
    "generator_function",
    "class",
}


def _is_function_like(value: TreeSitterNode | None) -> bool:
    """True if ``value``, seen through its wrappers, is a function or a class."""
    while value is not None and value.type in TS_VALUE_WRAPPER_TYPES:
        children = value.named_children
        if not children:
            return False
        # ``<T>x`` names its type first, every other wrapper its expression
        value = children[-1] if value.type == "type_assertion" else children[0]
    return value is not None and value.type in TS_FUNCTION_VALUE_TYPES


def _declares_function(node: TreeSitterNode) -> bool:
    """A ``const``/``let``/``var`` declaration one of whose declarators is a function,
    or one declared with ``declare`` (``declare const x: T``), which holds no value and
    is the declared thing itself. Only the ``declare``-prefixed form: a variable inside a
    ``declare namespace``, ``module`` or ``global`` body, or a bare ``export const x: T;``
    in a ``.d.ts``, is no scope here and binds the next declaration."""
    if node.parent is not None and node.parent.type == "ambient_declaration":
        return True
    return any(
        _is_function_like(declarator.child_by_field_name("value"))
        for declarator in node.named_children
        if declarator.type == "variable_declarator"
    )


def _value_is_function(node: TreeSitterNode) -> bool:
    """A class field (``handler = () => {}``) or a default export of a function or class."""
    return _is_function_like(node.child_by_field_name("value"))


def _assigns_function(node: TreeSitterNode) -> bool:
    """An assignment of a function, as ``module.exports = function () {}`` is."""
    return _is_function_like(node.child_by_field_name("right"))


# Node types a scope can be wrapped in, per language: when the next sibling of a comment
# is one of them, its children are searched for the scope. Every language has ``block``.
DEFAULT_SCOPE_CONTAINER_TYPES = frozenset({"block"})
SCOPE_CONTAINER_TYPES: dict[CommentType, frozenset[str]] = {
    # ``export …``, ``declare …``, and an expression statement holding an assignment
    # or a top-level ``namespace``
    CommentType.ts: DEFAULT_SCOPE_CONTAINER_TYPES
    | {"export_statement", "ambient_declaration", "expression_statement"},
}

# Scope node types that are a scope only when their predicate holds, per language, so
# that a comment does not bind to a declaration that merely precedes the one it
# documents (``const flag = true;`` before a function).
SCOPE_PREDICATES: dict[CommentType, dict[str, Callable[[TreeSitterNode], bool]]] = {
    CommentType.ts: {
        "lexical_declaration": _declares_function,
        "variable_declaration": _declares_function,
        "public_field_definition": _value_is_function,
        "assignment_expression": _assigns_function,
        "export_statement": _value_is_function,
    },
}


def _matches_scope(node: TreeSitterNode, comment_type: CommentType) -> bool:
    if node.type not in SCOPE_NODE_TYPES.get(comment_type, ()):
        return False
    predicate = SCOPE_PREDICATES.get(comment_type, {}).get(node.type)
    return predicate is None or predicate(node)


def find_enclosing_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """Find the enclosing scope of a comment."""
    current: TreeSitterNode = node
    while current:
        if _matches_scope(current, comment_type):
            return current
        current: TreeSitterNode | None = current.parent  # required for node traversal
    return None


def find_next_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """Find the next scope of a comment."""
    containers = SCOPE_CONTAINER_TYPES.get(comment_type, DEFAULT_SCOPE_CONTAINER_TYPES)
    current: TreeSitterNode = node
    while current:
        if _matches_scope(current, comment_type):
            return current
        current: TreeSitterNode | None = (
            current.next_named_sibling
        )  # required for node traversal
        if current and current.type in containers:
            for child in current.named_children:
                if _matches_scope(child, comment_type):
                    return child
                # a container in a container, as ``export declare …`` nests an
                # ``ambient_declaration`` in an ``export_statement``
                if child.type in containers and child.type != "block":
                    for grandchild in child.named_children:
                        if _matches_scope(grandchild, comment_type):
                            return grandchild

    return None


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 find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find the YAML structure (key-value pair, list item, etc.) associated with a comment."""
    # 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 prev_sibling_same_row

    # 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 structure

    # 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 parent
        parent = parent.parent

    return None


# @JSONC comment-to-structure association, IMPL_JSONC_2, impl, [FE_JSONC]
def find_jsonc_associated_structure(node: TreeSitterNode) -> TreeSitterNode | 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 prev_sibling_same_row

    # Leading comment: the next structure following the comment
    current = node.next_named_sibling
    while current:
        if current.type in JSON_STRUCTURE_TYPES:
            return current
        current = current.next_named_sibling

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

    return None


# The VHDL nodes that wrap the design elements a leading comment documents: a marker
# above one binds the wrapper's first item. A design unit's first item is the one after
# its context clauses.
VHDL_SCOPE_WRAPPER_TYPES = frozenset(
    {
        "design_unit",
        "process_head",
        "block_head",
        "generate_head",
        "generate_block",
        "interface_list",
    }
)
VHDL_CONTEXT_CLAUSE_TYPES = frozenset(
    {"library_clause", "use_clause", "context_reference"}
)
VHDL_COMMENT_TYPES = frozenset({"line_comment", "block_comment"})


def _vhdl_innermost_on_row(node: TreeSitterNode, row: int) -> TreeSitterNode | None:
    """The innermost design element of ``node``'s subtree, ``node`` included, that
    ends on ``row``, following the last non-comment child that ends there."""
    found = None
    current: TreeSitterNode | None = node
    while current is not None:
        if _matches_scope(current, CommentType.vhdl):
            found = current
        current = next(
            (
                child
                for child in reversed(current.named_children)
                if child.type not in VHDL_COMMENT_TYPES and child.end_point.row == row
            ),
            None,
        )
    return found


# @VHDL comment-to-design-element association, IMPL_VHDL_4, impl, [FE_VHDL]
def find_vhdl_associated_scope(node: TreeSitterNode) -> TreeSitterNode | None:
    """Find the VHDL design element a comment documents.

    A trailing comment -- the previous non-comment sibling ends on the comment's row --
    documents the innermost design element ending on that row, a port inside its
    ``interface_list`` included. A leading comment documents the next non-comment
    sibling, if that is a design element, or the first item of a wrapper; the walk
    never passes a sibling. Otherwise the comment documents the nearest enclosing
    design element, or nothing at file level. Comment siblings are skipped: a VHDL
    ``line_comment`` holds its newline, so the comment on the row above ends on this one.
    """
    row = node.start_point.row
    previous = node.prev_named_sibling
    while previous is not None and previous.type in VHDL_COMMENT_TYPES:
        previous = previous.prev_named_sibling
    if previous is not None and previous.end_point.row == row:
        return _vhdl_innermost_on_row(previous, row) or find_enclosing_scope(
            node, CommentType.vhdl
        )
    following = node.next_named_sibling
    while following is not None and following.type in VHDL_COMMENT_TYPES:
        following = following.next_named_sibling
    if following is not None and following.type in VHDL_SCOPE_WRAPPER_TYPES:
        skipped = (
            VHDL_CONTEXT_CLAUSE_TYPES
            if following.type == "design_unit"
            else frozenset()
        )
        following = next(
            (
                child
                for child in following.named_children
                if child.type not in VHDL_COMMENT_TYPES and child.type not in skipped
            ),
            None,
        )
    if following is not None and _matches_scope(following, CommentType.vhdl):
        return following
    return find_enclosing_scope(node, CommentType.vhdl)


def find_associated_scope(
    node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
) -> TreeSitterNode | None:
    """Find the associated scope of a comment."""
    if comment_type == CommentType.vhdl:
        # VHDL binds to the design element next to the comment, never past it
        return find_vhdl_associated_scope(node)

    if comment_type == CommentType.yaml:
        # YAML uses different structure association logic
        return find_yaml_associated_structure(node)

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

    if node.type == CommentCategory.docstring:
        # Only for python's docstring
        return find_enclosing_scope(node, comment_type)
    # General comments regardless of comment types
    associated_scope = find_next_scope(node, comment_type)
    if not associated_scope:
        associated_scope = find_enclosing_scope(node, comment_type)
    return associated_scope


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