import json
import os
from collections.abc import Generator, Iterable
from dataclasses import dataclass
from pathlib import Path
from typing import Any, cast

from tree_sitter import Node as TreeSitterNode
from tree_sitter import Parser, Query

from sphinx_codelinks.analyse import multiline_parser, utils
from sphinx_codelinks.analyse.entity import CodeScope, code_scope, scope_language
from sphinx_codelinks.analyse.models import (
    MarkedContentType,
    MultilineNeed,
    NeedIdRefs,
    OneLineNeed,
    SourceComment,
    SourceFile,
    SourceMap,
    WarningSubTypeEnum,
)
from sphinx_codelinks.analyse.oneline_parser import (
    OnelineParserInvalidWarning,
    docstring_tag,
    jsdoc_tag,
    oneline_parser,
)
from sphinx_codelinks.analyse.references import _relative_posix
from sphinx_codelinks.config import (
    UNIX_NEWLINE,
    CommentCategory,
    OneLineCommentStyle,
    SourceAnalyseConfig,
)
from sphinx_codelinks.logger import get_logger
from sphinx_codelinks.source_discover.config import CommentType

logger = get_logger(__name__)

# The last key of the marked content's sort. Two entries can start at one position
# only with overlapping markers (a need-id marker that ends with the one-line start
# sequence), which the configuration check does not refuse. Such a tie is listed
# references, then one-line needs, then multi-line needs: an explicit rank, because
# the type names sort the other way round. Two references never tie: the marker
# matches of a line do not overlap (``find_marker_matches``).
_KIND_RANK: dict[MarkedContentType, int] = {
    MarkedContentType.need_id_refs: 0,
    MarkedContentType.need: 1,
    MarkedContentType.multiline_need: 2,
}


def _is_alphanumeric(char: str) -> bool:
    """Whether ``char``'s Unicode general category is a letter (L*) or a number (N*).

    The one notion of alphanumeric of the reference markers' rules, shared with another
    implementation of them. ``str.isalnum`` is exactly that test (no other character
    passes it): characters Unicode calls Alphabetic without being letters -- a circled
    letter (So), a combining mark (Mn, Mc) -- are not alphanumeric here. The
    classification follows each tool's own Unicode tables (here the running Python's,
    ``unicodedata.unidata_version``), so a character newer than the older of two tables
    can be classed differently.
    """
    return char.isalnum()


def _is_word_char(char: str) -> bool:
    """A word character, for a reference marker's boundary: alphanumeric (see
    :func:`_is_alphanumeric`) or ``_``."""
    return _is_alphanumeric(char) or char == "_"


def _find_marker(line: str, marker: str, start: int) -> int:
    """The index of the first match of ``marker`` in ``line`` at or after ``start``.

    A marker whose last character is a word character matches only where the
    character after it is not one (or the line ends): ``\\verifies`` does not match
    ``\\verifiesall``. No condition applies before the match. ``-1`` when none.
    """
    word_final = _is_word_char(marker[-1])
    idx = line.find(marker, start)
    while idx != -1:
        after = idx + len(marker)
        if not (word_final and after < len(line) and _is_word_char(line[after])):
            return idx
        idx = line.find(marker, idx + 1)
    return -1


def find_marker_matches(
    line: str, markers: Iterable[str], *, first_only: bool = False
) -> list[tuple[str, int, int]]:
    """The reference-marker matches of one line, left to right: ``(marker, start, end)``.

    The line is scanned from left to right. At each index, among the markers that
    match there (see :func:`_find_marker`), the LONGEST wins, and the scan resumes at
    the end of that match, so matches never overlap. The same marker can match more
    than once. An empty marker never matches.

    :param line: One line of a comment.
    :param markers: The configured reference markers.
    :param first_only: Stop after the first match.
    """
    candidates = [marker for marker in markers if marker]
    matches: list[tuple[str, int, int]] = []
    pos = 0
    while candidates:
        best: tuple[int, str] | None = None
        for marker in candidates:
            idx = _find_marker(line, marker, pos)
            if idx == -1:
                continue
            if (
                best is None
                or idx < best[0]
                or (idx == best[0] and len(marker) > len(best[1]))
            ):
                best = (idx, marker)
        if best is None:
            break
        idx, marker = best
        matches.append((marker, idx, idx + len(marker)))
        if first_only:
            break
        pos = idx + len(marker)
    return matches


def _char_column(src: bytes, byte_offset: int) -> int:
    """The column, in characters, of ``byte_offset`` in the UTF-8 ``src``."""
    line_start = src.rfind(b"\n", 0, byte_offset) + 1
    return len(src[line_start:byte_offset].decode("utf-8", errors="replace"))


def _count(n: int, noun: str) -> str:
    """Format ``n noun`` with a naive (append-s) plural for progress summaries."""
    return f"{n} {noun}" if n == 1 else f"{n} {noun}s"


def _row_count(src_comment: SourceComment) -> int:
    """The rows a comment covers: a Rust ``///`` node's text ends with its newline, which
    starts no row of its own."""
    return src_comment.text.rstrip(b"\n").count(b"\n") + 1


#: The message of a ``marker_above_conditional`` warning.
ABOVE_CONDITIONAL_MSG = (
    "directly above a preprocessor conditional, so attached to no entity: "
    "put the marker inside the arm, above the definition"
)

#: How a tag warning names the tag it found.
_TAG_NAMES = {
    WarningSubTypeEnum.docstring_tag: "docstring tag",
    WarningSubTypeEnum.jsdoc_tag: "JSDoc tag",
}


def _is_jsdoc(text: bytes) -> bool:
    """Whether the comment ``text`` is a JSDoc comment: a block comment opened by
    exactly ``/**``, as JSDoc reads one (``/***`` and the empty ``/**/`` are not)."""
    return (
        text.startswith(b"/**")
        and not text.startswith(b"/***")
        and not text.startswith(b"/**/")
    )


def _docstring_contents(
    node: TreeSitterNode, raw: bytes, column: int
) -> list[tuple[str, int, int]]:
    """The content of each string of a docstring statement, between its quotes.

    Each with its 0-based row and its column, in characters: the quotes' column plus
    the prefix letters' and the delimiter's length. ``raw`` is the statement's text as
    the file writes it, ``column`` its column.
    """
    contents = []
    for string in node.named_children:
        if string.type != "string":
            continue
        kinds = {child.type: child for child in string.children}
        start, end = kinds.get("string_start"), kinds.get("string_end")
        if start is None or end is None:
            continue
        begin = start.end_byte - node.start_byte
        before = raw[:begin]
        row_start = before.rfind(b"\n") + 1
        content_column = len(before[row_start:].decode("utf-8", errors="replace"))
        if row_start == 0:
            content_column += column
        contents.append(
            (
                raw[begin : end.start_byte - node.start_byte].decode(
                    "utf-8", errors="replace"
                ),
                start.end_point.row,
                content_column,
            )
        )
    return contents


def _scanned_texts(
    src_comment: SourceComment, claimed_rows: set[int] | None
) -> list[tuple[str, int, int]]:
    """What the one-line and reference extractors scan of a comment.

    Each text comes with the 0-based row and the column, in characters, at which it
    starts. A docstring is scanned as its content, without the quotes; a block
    comment without its closing ``*/``, and a legacy ``<!-- … -->`` comment without
    its ``-->``, which are not marker text. The rows a multi-line need claims are
    blanked.
    """
    node = src_comment.node
    if getattr(node, "type", None) == CommentCategory.docstring:
        texts = _docstring_contents(node, src_comment.text, src_comment.column)
    else:
        text = src_comment.text.decode("utf-8")
        if text.startswith("/*") and text.endswith("*/"):
            text = text[:-2]
        elif text.startswith("<!--") and text.endswith("-->"):
            text = text[:-3]
        texts = [(text, node.start_point.row, src_comment.column)]
    if claimed_rows:
        # a block's lines are its own: no one-line need and no reference in them
        texts = [
            (multiline_parser.blank_rows(text, row, claimed_rows), row, column)
            for text, row, column in texts
        ]
    return texts


@dataclass
class AnalyseWarning:
    file_path: str
    lineno: int
    msg: str
    type: str
    sub_type: str


class SourceAnalyse:
    def __init__(
        self,
        analyse_config: SourceAnalyseConfig,
        *,
        name: str = "",
    ) -> None:
        self.name = name
        self.analyse_config = analyse_config
        self.src_files: list[SourceFile] = []
        self.src_comments: list[SourceComment] = []
        self.need_id_refs: list[NeedIdRefs] = []
        self.oneline_needs: list[OneLineNeed] = []
        self.multiline_needs: list[MultilineNeed] = []
        self.all_marked_content: list[NeedIdRefs | OneLineNeed | MultilineNeed] = []
        # Use explicitly configured git_root if provided, otherwise auto-detect
        if self.analyse_config.git_root is not None:
            self.git_root: Path | None = self.analyse_config.git_root.resolve()
        else:
            self.git_root = utils.locate_git_root(self.analyse_config.src_dir)
        self.git_remote_url: str | None = (
            utils.get_remote_url(self.git_root) if self.git_root else None
        )
        self.git_commit_rev: str | None = (
            utils.get_current_rev(self.git_root) if self.git_root else None
        )
        self.project_path: Path = self.git_root or self.analyse_config.src_dir
        self.warnings: list[AnalyseWarning] = []
        """The analysis' warnings, one-line and multi-line alike, in extraction order."""
        # Per-run memo of parsed compile_commands.json, keyed by DB path, so the
        # database is read once per run instead of once per source file.
        self._flags_map_cache: dict[Path, dict[Path, list[str]] | None] = {}

    @property
    def oneline_warnings(self) -> list[AnalyseWarning]:
        """The old name of :attr:`warnings`, kept for one release; read-only."""
        return self.warnings

    def get_src_strings(self) -> Generator[tuple[Path, bytes], Any, None]:
        """Load source files and extract their content."""
        for src_path in self.analyse_config.src_files:
            if not utils.is_text_file(src_path):
                continue
            with src_path.open("r", encoding="utf-8", newline="") as f:
                # Normalize all line endings to Unix LF
                text = f.read()
            text = text.replace("\r\n", "\n").replace("\r", "\n")
            yield src_path, text.encode("utf-8")

    def create_src_objects(self) -> None:
        comment_type = self.analyse_config.comment_type
        # One (parser, query) pair per distinct grammar actually needed, built
        # lazily so a parser is never rebuilt per file. Every comment type
        # except TypeScript uses a single grammar for the whole run;
        # TypeScript alone varies its grammar per file (utils.ts_grammar_key)
        # because a legacy TypeScript-only cast parses as JSX under the wrong
        # grammar — see the CommentType.ts branch of utils.init_tree_sitter.
        parser_cache: dict[str, tuple[Parser, Query]] = {}

        for src_path, src_string in self.get_src_strings():
            # `comment_type` is normally a CommentType member, but a few call
            # sites carry it as a plain (possibly invalid) str instead — see
            # SourceAnalyseConfig.comment_type — so key on `str(comment_type)`
            # rather than `.value`, which only the enum has.
            cache_key = (
                utils.ts_grammar_key(src_path)
                if comment_type == CommentType.ts
                else str(comment_type)
            )
            if cache_key not in parser_cache:
                parser_cache[cache_key] = utils.init_tree_sitter(comment_type, src_path)
            parser, query = parser_cache[cache_key]

            tree, cpp_names = utils.parse_source(
                src_string, parser, comment_type, src_path
            )
            comments: list[TreeSitterNode] | None = utils.captured_comments(tree, query)
            if not comments:
                continue
            src_comments: list[SourceComment] = [
                SourceComment(node, _char_column(src_string, node.start_byte))
                for node in comments
            ]

            src_file = SourceFile(src_path.absolute())
            src_file.cpp_names = cpp_names
            src_file.add_comments(src_comments)
            if self.analyse_config.get_multiline_needs:
                src_file.lines = src_string.decode("utf-8").split(UNIX_NEWLINE)
            self.src_files.append(src_file)
            self.src_comments.extend(src_comments)

    def _flags_map_for(self, db_path: Path) -> dict[Path, list[str]] | None:
        """Return the parsed compile_commands.json for ``db_path``, memoized.

        The database is read and parsed once per run instead of once per source
        file (O(files x entries) -> O(entries)). A present-but-malformed or
        unreadable database is warned once and cached as ``None`` so callers fall
        back to the configured defines without re-reading or re-warning per file.
        """
        from sphinx_codelinks.analyse.preproc import compile_db

        if db_path in self._flags_map_cache:
            return self._flags_map_cache[db_path]
        try:
            flags = compile_db.load_flags_map(db_path)
        except (OSError, ValueError, TypeError) as exc:
            logger.warning(
                f"codelinks: failed to read {db_path} ({exc}); "
                f"falling back to the configured defines"
            )
            self._flags_map_cache[db_path] = None
            return None
        self._flags_map_cache[db_path] = flags
        return flags

    def _resolve_preproc_args(self, src_path: Path) -> list[str] | None:
        from sphinx_codelinks.analyse.preproc import compile_db

        # `run()` calls this (via create_src_objects_libclang) only when
        # `preprocessor is not None`, but keep the guard: it narrows the type for
        # the checker and is a cheap defense (an `assert` would trip bandit S101).
        preproc = self.analyse_config.preprocessor
        if preproc is None:
            return []
        db_path = preproc.compile_commands
        if db_path is None:
            db_path = compile_db.find_compile_db(src_path, self.project_path)
        if db_path is not None and db_path.is_file():
            flags = self._flags_map_for(db_path)
            if flags is None:
                # Present-but-malformed/unreadable DB (warned once in the helper):
                # fall back to the configured defines so extraction still runs.
                return compile_db.defines_to_args(
                    preproc.defines, preproc.includes, preproc.std
                )
            args = flags.get(src_path.absolute().resolve())
            if args is not None:
                return args
            # Absent from the DB. compile_commands.json lists only compiled
            # translation units, never headers — so a header here is parsed
            # standalone with the global defines (one run = one variant). A
            # compiled source absent from the build is skipped (spec §3.3).
            if compile_db.is_translation_unit_source(src_path):
                return None
            return compile_db.defines_to_args(
                preproc.defines, preproc.includes, preproc.std
            )
        # No readable DB. `find_compile_db` only ever returns a real file, so a
        # non-None `db_path` that reaches here is an explicit `compile_commands`
        # path that is not a readable file (typo/missing): warn and fall back
        # rather than skip silently. A genuinely absent DB (db_path is None) just
        # falls back to the manual defines applied globally.
        if db_path is not None:
            logger.warning(
                f"codelinks: compile_commands path {db_path} is not a readable "
                f"file; falling back to the configured defines"
            )
        return compile_db.defines_to_args(
            preproc.defines, preproc.includes, preproc.std
        )

    # @Extract traceability objects with the preprocessor-aware libclang engine, IMPL_PREPROC_1, impl, [FE_PREPROC]
    def create_src_objects_libclang(self) -> None:
        from sphinx_codelinks.analyse.preproc import (
            libclang_parser,
            loader,
        )

        # Resolve the exception via the loader (never a direct ``import
        # clang.cindex``) so a missing ``libclang`` extra still surfaces the
        # loader's friendly install hint rather than a bare ImportError.
        translation_unit_load_error = (
            loader.load_clang_cindex().TranslationUnitLoadError
        )

        for src_path in self.analyse_config.src_files:
            if not utils.is_text_file(src_path):
                continue
            args = self._resolve_preproc_args(src_path)
            if args is None:
                logger.debug(
                    f"codelinks: skipping {src_path} — not found in compile_commands.json"
                )
                continue
            try:
                comments = libclang_parser.extract_active_comments(src_path, args)
            except translation_unit_load_error:
                # Last-resort guard. Standalone parses pin ``-x`` to match the
                # ``-std`` (see defines_to_args), so the common case — a ``.h``/
                # ``.c`` header handed a C++ ``-std`` — now parses as C++ and its
                # markers extract. This only fires if libclang still cannot load
                # the file as a translation unit at all; skip it rather than
                # aborting the whole run. Surfaced as a ``warning`` so the silent
                # data-loss (a file's markers dropped) is visible — accepting that
                # this fails ``sphinx-build -W``.
                logger.warning(
                    f"codelinks: skipping {src_path} — libclang could not load it "
                    f"as a translation unit"
                )
                continue
            if not comments:
                continue
            # ``c`` is a LibclangComment duck-typing the tree-sitter Node
            # interface SourceComment reads (``.text`` / ``.start_point.row``);
            # the Node-only path (find_associated_scope) is guarded by
            # ``is_libclang`` so it never runs on these. The cast is that duck typing,
            # which is why ty, seeing two unrelated classes, has to be told.
            src_comments = [
                SourceComment(
                    cast("TreeSitterNode", c),  # ty: ignore[disjoint-cast]
                    c.column,
                )
                for c in comments
            ]
            src_file = SourceFile(src_path.absolute())
            src_file.add_comments(src_comments)
            if self.analyse_config.get_multiline_needs:
                # multi-line needs read what precedes a comment on its row from
                # the row itself
                text = src_path.read_text(encoding="utf-8", errors="replace")
                text = text.replace("\r\n", "\n").replace("\r", "\n")
                src_file.lines = text.split(UNIX_NEWLINE)
            self.src_files.append(src_file)
            self.src_comments.extend(src_comments)

    def extract_marker(
        self,
        text: str,
    ) -> Generator[tuple[str, list[str], int, int, int], None, None]:
        """Yield each reference-marker match of ``text`` with its ids.

        Yields ``(marker, need_ids, row_offset, start_column, end_column)``, the
        columns spanning the match's own id text. The matches of a line are found by
        :func:`find_marker_matches`; a match's id text runs from its end to the start
        of the next match on the line, or to the end of the line. A match with no id
        yields nothing.
        """
        markers = self.analyse_config.need_id_refs_config.markers
        row_offset = 0
        for line in text.split(UNIX_NEWLINE):
            matches = find_marker_matches(line, markers)
            for index, (marker, _start, end) in enumerate(matches):
                is_last = index == len(matches) - 1
                after_marker = (
                    line[end:] if is_last else line[end : matches[index + 1][1]]
                )
                markered_text = after_marker.strip()
                if is_last and markered_text.endswith("*/"):
                    # The end of a one-line block comment, not an id.
                    markered_text = markered_text[:-2].rstrip()
                need_ids = markered_text.replace(",", " ").split()
                if not need_ids:
                    continue
                start_column = end + len(after_marker) - len(after_marker.lstrip())
                end_column = start_column + len(markered_text)
                yield marker, need_ids, row_offset, start_column, end_column
            row_offset += 1

    # @Extract need ID references from code comments, IMPL_LNK_1, impl, [FE_LNK]
    def extract_anchors(
        self,
        text: str,
        filepath: Path,
        tagged_scope: TreeSitterNode | None,
        src_comment: SourceComment,
        first_row: int | None = None,
        first_column: int | None = None,
        *,
        scope: CodeScope | None = None,
    ) -> list[NeedIdRefs]:
        """Extract need-ids-refs from a comment.

        ``text`` starts at ``first_row`` and ``first_column`` (by default the
        comment's own row and column). ``scope`` is the named ``tagged_scope``.
        """
        if first_row is None:
            first_row = src_comment.node.start_point.row
        if first_column is None:
            first_column = src_comment.column
        anchors: list[NeedIdRefs] = []
        for (
            marker,
            need_ids,
            row_offset,
            start_column,
            end_column,
        ) in self.extract_marker(text):
            lineno = first_row + row_offset + 1
            line_column = first_column if row_offset == 0 else 0
            remote_url = self.git_remote_url
            if self.git_remote_url and self.git_commit_rev:
                remote_url = utils.form_https_url(
                    self.git_remote_url,
                    self.git_commit_rev,
                    self.project_path,
                    filepath,
                    lineno,
                )
            source_map: SourceMap = {
                "start": {
                    "row": lineno - 1,
                    "column": line_column + start_column,
                },
                "end": {
                    "row": lineno - 1,
                    "column": line_column + end_column,
                },
            }
            anchors.append(
                NeedIdRefs(
                    filepath,
                    remote_url,
                    source_map,
                    src_comment,
                    tagged_scope,
                    need_ids,
                    marker,
                    scope=scope,
                )
            )
        return anchors

    def _is_need_id_refs_line(self, line: str) -> bool:
        """Whether a comment line is an ``@need-ids:`` reference rather than a need.

        A line whose text, after comment decoration and whitespace, starts with a
        configured need-id-refs marker is a reference, and never a one-line need.
        Without it the default one-line start sequence ``@`` also
        matched ``// @need-ids: A, B`` and made a need titled ``need-ids: A`` with the id
        ``B``. A line with anything alphanumeric before the marker is not a reference
        line here (``// see @need-ids: X`` -- the one-line parser ignores it anyway, and
        the references on it are still extracted), and a line holding a one-line need
        before the marker (``[[…]] @need-ids: X``) keeps its need: only a line that
        STARTS with the marker is withheld from the one-line parser. The marker is the
        line's first match as :func:`find_marker_matches` finds it, so a word that only
        begins with a marker (``\\verifiesall`` for ``\\verifies``) is none.
        """
        matches = find_marker_matches(
            line, self.analyse_config.need_id_refs_config.markers, first_only=True
        )
        return bool(matches) and not any(
            _is_alphanumeric(char) for char in line[: matches[0][1]]
        )

    def extract_oneline_need(
        self,
        text: str,
        src_comment: SourceComment,
        oneline_comment_style: OneLineCommentStyle,
        first_row: int | None = None,
    ) -> Generator[tuple[dict[str, str | list[str] | int], int]]:
        if first_row is None:
            first_row = src_comment.node.start_point.row
        # every line counts as terminated, the last one too
        lines = [f"{line}{UNIX_NEWLINE}" for line in text.split(UNIX_NEWLINE)]
        row_offset = 0

        # Only a Python docstring can hold docstring tags; a ``#`` comment never does.
        in_docstring = (
            getattr(src_comment.node, "type", None) == CommentCategory.docstring
        )
        # Only a TypeScript or JavaScript JSDoc comment can hold JSDoc tags.
        in_jsdoc = self.analyse_config.comment_type == CommentType.ts and _is_jsdoc(
            src_comment.text
        )
        for line in lines:
            if self._is_need_id_refs_line(line):
                row_offset += 1
                continue
            start_sequence = oneline_comment_style.start_sequence
            tag, kind, holders = None, WarningSubTypeEnum.docstring_tag, "docstrings"
            if in_docstring:
                tag = docstring_tag(line, start_sequence)
            elif in_jsdoc and start_sequence == "@":
                # ``@`` is JSDoc's own sigil: under any other start sequence a JSDoc
                # line is read as any other line is
                tag = jsdoc_tag(line, start_sequence)
                kind, holders = WarningSubTypeEnum.jsdoc_tag, "JSDoc comments"
                if tag is not None and not oneline_parser(line, oneline_comment_style):
                    # a tag line the one-line parser would ignore stays silent
                    row_offset += 1
                    continue
            if tag is not None:
                if src_comment.source_file:
                    self.warnings.append(
                        AnalyseWarning(
                            str(src_comment.source_file.filepath),
                            first_row + row_offset + 1,
                            f"'{start_sequence}{tag}' is a {_TAG_NAMES[kind]}, not a "
                            "one-line need; use a start sequence that "
                            f"{holders} do not contain",
                            MarkedContentType.need,
                            kind.value,
                        )
                    )
                row_offset += 1
                continue
            resolved = oneline_parser(line, oneline_comment_style)
            if not resolved:
                row_offset += 1
                continue
            if isinstance(resolved, OnelineParserInvalidWarning):
                if not src_comment.source_file:
                    row_offset += 1
                    continue
                lineno = first_row + row_offset + 1
                warning = AnalyseWarning(
                    str(src_comment.source_file.filepath),
                    lineno,
                    resolved.msg,
                    MarkedContentType.need,
                    resolved.sub_type.value,
                )
                self.warnings.append(warning)
                row_offset += 1
                continue
            yield resolved, row_offset
            row_offset += 1

    # @Extract one-line traceability needs from comments, IMPL_ONE_1, impl, [FE_DEF, FE_CMT]
    def extract_oneline_needs(
        self,
        text: str,
        filepath: Path,
        tagged_scope: TreeSitterNode | None,
        src_comment: SourceComment,
        oneline_comment_style: OneLineCommentStyle,
        first_row: int | None = None,
        first_column: int | None = None,
        *,
        scope: CodeScope | None = None,
    ) -> list[OneLineNeed]:
        """Extract the one-line needs of a comment.

        ``text`` starts at ``first_row`` and ``first_column`` (by default the
        comment's own row and column). ``scope`` is the named ``tagged_scope``.
        """
        if first_row is None:
            first_row = src_comment.node.start_point.row
        if first_column is None:
            first_column = src_comment.column
        row_offset = 0
        oneline_needs = []
        for resolved, row_offset in self.extract_oneline_need(
            text, src_comment, oneline_comment_style, first_row
        ):
            lineno = first_row + row_offset + 1
            line_column = first_column if row_offset == 0 else 0
            start_column = line_column + cast("int", resolved["start_column"])
            end_column = line_column + cast("int", resolved["end_column"])
            remote_url = self.git_remote_url
            if self.git_remote_url and self.git_commit_rev:
                remote_url = utils.form_https_url(
                    self.git_remote_url,
                    self.git_commit_rev,
                    self.project_path,
                    filepath,
                    lineno,
                )
            source_map: SourceMap = {
                "start": {
                    "row": lineno - 1,
                    "column": start_column,
                },
                "end": {
                    "row": lineno - 1,
                    "column": end_column,
                },
            }
            del resolved["start_column"]
            del resolved["end_column"]
            oneline_needs.append(
                OneLineNeed(
                    filepath,
                    remote_url,
                    source_map,
                    src_comment,
                    tagged_scope,
                    resolved,  # int arguments were deleted  # ty: ignore[invalid-argument-type]
                    scope=scope,
                )
            )
        return oneline_needs

    # @Extract multi-line needs from comment runs, IMPL_MLN_1, impl, [FE_MULTILINE_NEEDS]
    def extract_multiline_needs(self) -> dict[int, set[int]]:
        """Extract the multi-line needs of every file, and the rows their blocks claim.

        Runs before the other extractors: the rows a block claims (and those of a
        refused header, consumed to its close) are hidden from them.

        :return: For each comment holding claimed rows (keyed by ``id()`` of its
            :class:`SourceComment`), those 0-based rows.
        """
        claimed: dict[int, set[int]] = {}
        config = self.analyse_config.multiline_needs_config
        for src_file in self.src_files:
            for run in multiline_parser.form_runs(
                src_file.src_comments, src_file.lines
            ):
                result = multiline_parser.parse_run(
                    run.lines,
                    config,
                    leaderless_block=run.leaderless_block,
                    mixed_leaders=run.mixed_leaders,
                )
                for issue in result.issues:
                    self.warnings.append(
                        AnalyseWarning(
                            str(src_file.filepath),
                            issue.row + 1,
                            issue.msg,
                            MarkedContentType.multiline_need,
                            issue.kind.value,
                        )
                    )
                for block in result.blocks:
                    self.multiline_needs.append(
                        self._multiline_need(block, run, src_file.filepath)
                    )
                if not result.claimed_rows:
                    continue
                for src_comment in run.comments:
                    first = src_comment.node.start_point.row
                    rows = result.claimed_rows.intersection(
                        range(first, first + _row_count(src_comment))
                    )
                    if rows:
                        claimed.setdefault(id(src_comment), set()).update(rows)
        return claimed

    def _multiline_need(
        self,
        block: multiline_parser.ParsedBlock,
        run: multiline_parser.CommentRun,
        filepath: Path,
    ) -> MultilineNeed:
        """The record of one parsed block (see :class:`MultilineNeed`)."""
        src_comment = next(
            (
                comment
                for comment in run.comments
                if comment.node.start_point.row
                <= block.open_row
                < comment.node.start_point.row + _row_count(comment)
            ),
            run.comments[0],
        )
        tagged_scope, scope, unattached = self._associate(src_comment, filepath)
        lineno = block.open_row + 1
        remote_url = self.git_remote_url
        if self.git_remote_url and self.git_commit_rev:
            remote_url = utils.form_https_url(
                self.git_remote_url,
                self.git_commit_rev,
                self.project_path,
                filepath,
                lineno,
            )
        source_map: SourceMap = {
            "start": {"row": block.open_row, "column": block.open_col},
            "end": {"row": block.close_row, "column": block.end_col},
        }
        content_start = (
            {"line": block.content_start[0] + 1, "col": block.content_start[1]}
            if block.content_start is not None
            else None
        )
        source: dict[str, Any] = {
            "project": self.name,
            "path": _relative_posix(filepath, self.project_path),
            "root": "git" if self.git_root is not None else "src_dir",
            "commit": self.git_commit_rev,
            "start": {"line": lineno, "col": block.open_col},
            "end": {"line": block.close_row + 1, "col": block.end_col},
            "content_start": content_start,
            "option_lines": dict(block.option_rows),
            "scope": scope,
        }
        need = MultilineNeed(
            filepath,
            remote_url,
            source_map,
            src_comment,
            tagged_scope,
            block.need,
            block.markup,
            source,
            scope=scope,
        )
        self._warn_unattached(unattached, [need])
        return need

    def _associate(
        self, src_comment: SourceComment, filepath: Path
    ) -> tuple[TreeSitterNode | None, CodeScope | None, utils.Unattached | None]:
        """The entity a comment of ``filepath`` is attached to: its node and its
        ``scope`` object, and why it is attached to none where the analysis warns
        about that (:class:`~sphinx_codelinks.analyse.utils.Unattached`).

        A libclang comment has no tree-sitter node, so it is attached to nothing.
        """
        if getattr(src_comment.node, "is_libclang", False):
            return None, None, None
        comment_type = self.analyse_config.comment_type
        association = utils.associate(
            src_comment.node, comment_type, text=src_comment.text
        )
        if association is None:
            return None, None, None
        if isinstance(association, utils.Unattached):
            return None, None, association
        source_file = src_comment.source_file
        written = (
            source_file.node_text(association.node)
            if source_file is not None
            else association.node.text
        )
        if not written:
            return None, None, None
        return (
            association.node,
            code_scope(
                association,
                comment_type,
                scope_language(comment_type, filepath),
                source_file.cpp_names if source_file is not None else None,
            ),
            None,
        )

    def _warn_unattached(
        self,
        unattached: utils.Unattached | None,
        records: Iterable[NeedIdRefs | OneLineNeed | MultilineNeed],
    ) -> None:
        """Warn about each marker in ``records`` that rule 7 attached to no entity, at
        its line (a multi-line need's open line)."""
        if unattached is not utils.Unattached.above_conditional:
            return
        for record in records:
            self.warnings.append(
                AnalyseWarning(
                    str(record.filepath),
                    record.source_map["start"]["row"] + 1,
                    ABOVE_CONDITIONAL_MSG,
                    record.type,
                    WarningSubTypeEnum.marker_above_conditional.value,
                )
            )

    def extract_marked_content(self) -> None:
        claimed: dict[int, set[int]] = {}
        if self.analyse_config.get_multiline_needs:
            claimed = self.extract_multiline_needs()
        for src_comment in self.src_comments:
            if not src_comment.text:
                continue
            filepath = (
                src_comment.source_file.filepath if src_comment.source_file else None
            )
            if not filepath:
                continue
            tagged_scope, scope, unattached = self._associate(src_comment, filepath)
            for text, first_row, first_column in _scanned_texts(
                src_comment, claimed.get(id(src_comment))
            ):
                if self.analyse_config.get_need_id_refs:
                    anchors = self.extract_anchors(
                        text,
                        filepath,
                        tagged_scope,
                        src_comment,
                        first_row,
                        first_column,
                        scope=scope,
                    )
                    self._warn_unattached(unattached, anchors)
                    self.need_id_refs.extend(anchors)
                if self.analyse_config.get_oneline_needs:
                    oneline_needs = self.extract_oneline_needs(
                        text,
                        filepath,
                        tagged_scope,
                        src_comment,
                        self.analyse_config.oneline_comment_style,
                        first_row,
                        first_column,
                        scope=scope,
                    )
                    self._warn_unattached(unattached, oneline_needs)
                    self.oneline_needs.extend(oneline_needs)

    def merge_marked_content(self) -> None:
        """List the marked content in source order: by file, row and column (#2150).

        Tree-sitter hands a file's comments over in an order that differs between
        runs, so the column is what keeps two entries of one row in a stable order.
        ``oneline_needs`` is sorted too, by row, then file, then column: ``src-trace``
        creates and renders the needs in its order, so of two markers with one id in
        one file the leftmost is the one created, and on one row the needs of two files
        keep the file order they had before the column was a key -- for a caller that
        passes the files in discovery order, as every production caller does.
        """
        # The file component is the key discovery sorts the files by
        # (``SourceDiscover``), not the ``Path``: a ``Path`` compares by parts, so
        # ``a/b.cpp`` would sort before ``a-c.cpp``, which discovery lists first.
        self.oneline_needs.sort(
            key=lambda x: (
                x.source_map["start"]["row"],
                os.path.normcase(os.path.normpath(x.filepath)),
                x.source_map["start"]["column"],
            )
        )
        self.all_marked_content.extend(self.need_id_refs)
        self.all_marked_content.extend(self.oneline_needs)
        self.all_marked_content.extend(self.multiline_needs)
        self.all_marked_content.sort(
            key=lambda x: (
                x.filepath,
                x.source_map["start"]["row"],
                x.source_map["start"]["column"],
                _KIND_RANK[x.type],
            )
        )

    def dump_marked_content(self, outdir: Path) -> None:
        output_path = outdir / "marked_content.json"
        output_path.parent.mkdir(parents=True, exist_ok=True)
        to_dump = [
            marked_content.to_dict() for marked_content in self.all_marked_content
        ]
        with output_path.open("w") as f:
            json.dump(to_dump, f)

    def run(self, *, log_summary: bool = True) -> None:
        """Parse the source files and extract their markers.

        :param log_summary: Whether to print the per-project summary line; a caller
            that prints its own (the configuration pass of the Sphinx extension) passes
            ``False``.
        """
        if (
            self.analyse_config.preprocessor is not None
            and self.analyse_config.comment_type == CommentType.cpp
        ):
            self.create_src_objects_libclang()
        else:
            self.create_src_objects()
        self.extract_marked_content()
        self.merge_marked_content()
        if log_summary:
            self.log_summary()

    def log_summary(self, extra: str = "") -> None:
        """Emit a per-project marker (default-visible) plus a -v breakdown.

        :param extra: Appended to the default-visible line (the ``src-trace``
            directive's count of the one-line needs it did not create).
        """
        label = f"codelinks [{self.name}]" if self.name else "codelinks"
        logger.info(
            f"{label}: {_count(len(self.src_files), 'file')}, "
            f"{_count(len(self.all_marked_content), 'marker')}{extra}"
        )
        logger.debug(
            f"{label}: {_count(len(self.src_comments), 'comment')}, "
            f"{_count(len(self.oneline_needs), 'oneline need')}, "
            f"{_count(len(self.need_id_refs), 'id-ref')}, "
            f"{_count(len(self.multiline_needs), 'multi-line need')}"
        )