# @Test suite for CLI commands including analyse\, discover\, and write, TEST_CLI_1, test, [IMPL_CLI_ANALYZE, IMPL_CLI_DISCOVER, IMPL_CLI_WRITE]
import json
import re
import tomllib
from pathlib import Path

import pytest
import toml
from typer.testing import CliRunner

from sphinx_codelinks.cmd import WRITE_RST_DEPRECATED, app
from sphinx_codelinks.source_discover.config import CommentType

from .conftest import DATA_DIR, TEST_DIR

ONELINE_COMMENT_TEMPLATE = {
    "start_sequence": "[[",
    "end_sequence": "]]",
    "field_split_char": ",",
    "needs_fields": [
        {"name": "id"},
        {"name": "title"},
        {"name": "type"},
    ],
}
SRC_DISCOVER_TEMPLATE = {
    "src_dir": str(TEST_DIR / "data" / "dcdc"),
    "exclude": ["**/charge/demo_1.cpp", "**/discharge/demo_3.cpp"],
    "include": ["**/charge/demo_2.cpp", "**/supercharge.cpp"],
    "gitignore": True,
    "comment_type": CommentType.cpp.value,
}
ANALYSE_CONFIG_TEMPLATE = {
    "get_oneline_needs": True,
    "oneline_comment_style": ONELINE_COMMENT_TEMPLATE,
}
CODELINKS_CONFIG_TEMPLATE = {
    "outdir": "set/it/to/somewhere",
    "projects": {
        "project_1": {
            "source_discover": SRC_DISCOVER_TEMPLATE,
            "analyse": ANALYSE_CONFIG_TEMPLATE,
        }
    },
}


runner = CliRunner()


def _normalize_output(text: str) -> str:
    """Normalize rich panel output: strip ANSI escapes, then collapse box-drawing
    chars and whitespace.

    Typer wraps error messages in rich panels whose line breaks depend on terminal
    width, which can cause substring assertions to fail. And typer forces a colour
    terminal when ``GITHUB_ACTIONS`` is set, so on CI the panel also carries ANSI
    escape codes -- including between the halves of a wrapped line -- which have to go
    first, before the whitespace between the halves can collapse.
    """
    text = re.sub(r"\x1b\[[0-9;?]*[A-Za-z]", "", text)
    # Remove box-drawing characters (─│╭╮╯╰) and collapse resulting whitespace
    text = re.sub(r"[─│╭╮╯╰]", " ", text)
    return re.sub(r"\s+", " ", text).strip()


@pytest.mark.parametrize(
    ("config_path"),
    [
        (DATA_DIR / "configs" / "minimum_config.toml"),
        (DATA_DIR / "configs" / "full_config.toml"),
    ],
)
def test_analyse(config_path: Path, tmp_path: Path) -> None:
    options: list[str] = ["analyse", str(config_path), "--outdir", str(tmp_path)]
    result = runner.invoke(app, options)

    output_path = tmp_path / "marked_content.json"

    assert output_path.exists()
    assert result.exit_code == 0

    with output_path.open("r") as f:
        marked_content = json.load(f)
    assert marked_content


def test_analyse_outputs_warnings(tmp_path: Path) -> None:
    """Test that the analyse CLI command outputs warnings to console."""
    # Create a config file that will produce warnings
    src_dir = TEST_DIR / "data" / "oneline_comment_default"
    config_dict = {
        "codelinks": {
            "outdir": str(tmp_path),
            "projects": {
                "test_project": {
                    "source_discover": {
                        "src_dir": str(src_dir),
                        "include": ["*.c"],
                        "comment_type": "cpp",
                    },
                    "analyse": {
                        "get_oneline_needs": True,
                        # Use default oneline_comment_style which will cause warnings
                        # for the test file with too many fields
                    },
                }
            },
        }
    }

    config_file = tmp_path / "test_config.toml"
    with config_file.open("w", encoding="utf-8") as f:
        toml.dump(config_dict, f)

    options: list[str] = ["analyse", str(config_file)]
    result = runner.invoke(app, options)

    assert result.exit_code == 0
    # Verify that warnings are output to console, one shape for every kind
    assert "Analyse warning in" in result.output
    assert "too_many_fields" in result.output


def test_analyse_logs_per_project_summary_and_gates_detail(tmp_path: Path) -> None:
    """Each project gets a default-visible ``codelinks [<project>]`` summary with
    counts; the per-type breakdown is gated behind --verbose; --quiet silences it."""
    config_path = DATA_DIR / "configs" / "minimum_config.toml"
    base = ["analyse", str(config_path), "--outdir", str(tmp_path)]

    # default: per-project summary shown, breakdown hidden
    result = runner.invoke(app, base)
    assert result.exit_code == 0
    assert "codelinks [" in result.output
    assert "markers" in result.output
    assert "oneline need" not in result.output

    # --verbose: per-type breakdown also shown
    verbose_result = runner.invoke(app, [*base, "--verbose"])
    assert verbose_result.exit_code == 0
    assert "codelinks [" in verbose_result.output
    assert "oneline need" in verbose_result.output

    # --quiet: summary silenced
    quiet_result = runner.invoke(app, [*base, "--quiet"])
    assert quiet_result.exit_code == 0
    assert "codelinks [" not in quiet_result.output


@pytest.mark.parametrize(
    ("gitignore", "stdout"),
    [
        (False, "4 files discovered"),
        (True, "3 files discovered"),
    ],
)
def test_discover(gitignore: bool, stdout: str, source_directory: Path) -> None:
    options = ["discover", str(source_directory)]
    options.append("--gitignore" if gitignore else "--no-gitignore")
    result = runner.invoke(app, options)
    assert result.exit_code == 0
    assert stdout in result.stdout


def test_discover_cli_default_exclude_matches_ts_default(tmp_path: Path) -> None:
    """Without ``-e``, ``discover --comment-type ts`` excludes what a ``ts`` project's
    configuration does: ``dist/app.js`` is not listed, ``src/app.ts`` is."""
    (tmp_path / "src").mkdir()
    (tmp_path / "src" / "app.ts").write_text(
        "// @Feature A, IMPL_1, impl\n", encoding="utf-8"
    )
    (tmp_path / "dist").mkdir()
    (tmp_path / "dist" / "app.js").write_text(
        "// @Feature A, IMPL_1, impl\n", encoding="utf-8"
    )

    result = runner.invoke(
        app,
        ["discover", str(tmp_path), "--comment-type", "ts", "--no-gitignore"],
    )
    assert result.exit_code == 0
    assert "1 files discovered" in result.stdout
    assert str(tmp_path / "src" / "app.ts") in result.stdout
    assert str(tmp_path / "dist" / "app.js") not in result.stdout


def test_discover_cli_excludes_replace_the_ts_default(tmp_path: Path) -> None:
    """``-e`` replaces the ``ts`` default rather than adding to it: the test file
    it names is dropped, and ``dist/app.js``, which the default would drop, is
    listed."""
    (tmp_path / "src").mkdir()
    for name in ("app.ts", "app.test.ts"):
        (tmp_path / "src" / name).write_text(
            "// @Feature A, IMPL_1, impl\n", encoding="utf-8"
        )
    (tmp_path / "dist").mkdir()
    (tmp_path / "dist" / "app.js").write_text(
        "// @Feature A, IMPL_1, impl\n", encoding="utf-8"
    )

    result = runner.invoke(
        app,
        [
            "discover",
            str(tmp_path),
            "--comment-type",
            "ts",
            "--no-gitignore",
            "-e",
            "**/*.test.ts",
        ],
    )
    assert result.exit_code == 0
    assert "2 files discovered" in result.stdout
    assert str(tmp_path / "src" / "app.ts") in result.stdout
    assert str(tmp_path / "dist" / "app.js") in result.stdout
    assert str(tmp_path / "src" / "app.test.ts") not in result.stdout


def test_discover_cli_cpp_default_exclude_is_empty(tmp_path: Path) -> None:
    """Without ``-e``, ``discover`` for ``cpp`` (the CLI's default) excludes nothing:
    ``lib/widget.cpp`` is listed."""
    lib_dir = tmp_path / "lib"
    lib_dir.mkdir()
    (lib_dir / "widget.cpp").write_text(
        "// @Feature A, IMPL_1, impl\n", encoding="utf-8"
    )

    result = runner.invoke(app, ["discover", str(tmp_path), "--no-gitignore"])
    assert result.exit_code == 0
    assert "1 files discovered" in result.stdout
    assert str(lib_dir / "widget.cpp") in result.stdout


@pytest.mark.parametrize(
    ("src_discover_dict", "analyse_dict", "output_lines"),
    [
        (
            {
                src_key: (123 if src_key == "exclude" else src_value)
                for src_key, src_value in SRC_DISCOVER_TEMPLATE.items()
            },
            ANALYSE_CONFIG_TEMPLATE,
            [
                "Invalid value: Invalid source discovery configuration:",
                "Schema validation error in field 'exclude': 123 is not of type 'array'",
            ],
        ),
        (
            {
                src_key: (123 if src_key == "include" else src_value)
                for src_key, src_value in SRC_DISCOVER_TEMPLATE.items()
            },
            ANALYSE_CONFIG_TEMPLATE,
            [
                "Invalid value: Invalid source discovery configuration:",
                "Schema validation error in field 'include': 123 is not of type 'array'",
            ],
        ),
        (
            {
                src_key: (
                    123 if src_key in ("exclude", "include", "src_dir") else src_value
                )
                for src_key, src_value in SRC_DISCOVER_TEMPLATE.items()
            },
            ANALYSE_CONFIG_TEMPLATE,
            [
                "Invalid value: Invalid source discovery configuration:",
                "Schema validation error in field 'src_dir': 123 is not of type 'string'",
                "Schema validation error in field 'exclude': 123 is not of type 'array'",
                "Schema validation error in field 'include': 123 is not of type 'array'",
            ],
        ),
        (
            SRC_DISCOVER_TEMPLATE,
            {
                analyse_key: (
                    {"not_expected": 123}
                    if analyse_key == "oneline_comment_style"
                    else analyse_value
                )
                for analyse_key, analyse_value in ANALYSE_CONFIG_TEMPLATE.items()
            },
            [
                "Invalid value: Invalid oneline comment style configuration:",
                "OneLineCommentStyle.__init__() got an unexpected keyword argument",
                "'not_expected'",
            ],
        ),
        (
            SRC_DISCOVER_TEMPLATE,
            {
                analyse_key: (
                    {"needs_fields": [{"name": "id"}, {"name": "id"}]}
                    if analyse_key == "oneline_comment_style"
                    else analyse_value
                )
                for analyse_key, analyse_value in ANALYSE_CONFIG_TEMPLATE.items()
            },
            [
                "Invalid value: OneLineCommentStyle configuration errors:",
                "Missing required fields: ['title', 'type']",
                "Field 'id' is defined multiple times.",
            ],
        ),
    ],
)
def test_analyse_config_negative(
    src_discover_dict, analyse_dict, output_lines, tmp_path: Path
) -> None:
    config_file = tmp_path / "codelinks_config.toml"
    codelink_dict = {"codelinks": CODELINKS_CONFIG_TEMPLATE}
    codelink_dict["codelinks"]["projects"]["project_1"]["source_discover"] = (
        src_discover_dict
    )
    codelink_dict["codelinks"]["projects"]["project_1"]["analyse"] = analyse_dict
    with config_file.open("w", encoding="utf-8") as f:
        toml.dump(codelink_dict, f)

    options = [
        "analyse",
        str(config_file),
    ]
    result = runner.invoke(app, options)
    assert result.exit_code != 0
    normalized = _normalize_output(result.output)
    for line in output_lines:
        assert line in normalized


@pytest.mark.parametrize(
    ("projects", "output_lines"),
    [
        (
            ["project_1", "project_2"],
            [
                "The following projects are not found:",
                "project_2",
            ],
        ),
    ],
)
def test_analyse_project_negative(projects, output_lines, tmp_path: Path) -> None:
    config_file = tmp_path / "codelinks_config.toml"
    codelink_dict = {"codelinks": CODELINKS_CONFIG_TEMPLATE}
    with config_file.open("w", encoding="utf-8") as f:
        toml.dump(codelink_dict, f)
    projects_config = []
    for project in projects:
        projects_config.append("--project")
        projects_config.append(project)

    options = [
        "analyse",
        str(config_file),
    ]
    options.extend(projects_config)
    result = runner.invoke(app, options)
    assert result.exit_code != 0
    normalized = _normalize_output(result.output)
    for line in output_lines:
        assert line in normalized


def test_write_rst_invalid_json(tmp_path: Path) -> None:
    json_obj = {
        "whatever": "json",
        "not": "expected",
    }
    json_text = json.dumps(json_obj)
    json_text = json_text.replace(",", "")
    jsonpath = tmp_path / "invalid_json.json"
    with jsonpath.open("w") as f:
        f.write(json_text)

    options = [
        "write",
        "rst",
        str(jsonpath),
        "--outpath",
        str(tmp_path / "out.rst"),
    ]
    result = runner.invoke(app, options)

    assert result.exit_code != 0
    assert "Expecting" in result.output


def test_analyse_never_reads_a_need_ids_comment_as_a_need(tmp_path: Path) -> None:
    """``codelinks analyse`` on the default one-line style: the ``@need-ids:`` comment
    is one reference record, and ``marked_content.json`` gains no need from it."""
    (tmp_path / "refs.cpp").write_text(
        "// @need-ids: REQ_001, IMPL_X\nvoid a() {}\n", encoding="utf-8"
    )
    config = tmp_path / "ubproject.toml"
    config.write_text(
        '[codelinks.projects.p.source_discover]\nsrc_dir = "./"\ncomment_type = "cpp"\n',
        encoding="utf-8",
    )
    outdir = tmp_path / "out"
    outdir.mkdir()

    result = runner.invoke(app, ["analyse", str(config), "--outdir", str(outdir)])

    assert result.exit_code == 0, result.output
    marked = json.loads((outdir / "marked_content.json").read_text(encoding="utf-8"))
    types = [obj["type"] for objs in marked.values() for obj in objs]
    assert types == ["need-id-refs"]


def test_write_rst_still_works_and_says_it_is_deprecated(tmp_path: Path) -> None:
    """``write rst`` is deprecated, not removed: it writes the file as before, and
    prints the notice on stderr (stdout carries only what it always did)."""
    marked = {
        "project_1": [
            {
                "filepath": "src/dummy_1.cpp",
                "remote_url": "https://example.com/src/dummy_1.cpp#L3",
                "source_map": {
                    "start": {"row": 2, "column": 13},
                    "end": {"row": 2, "column": 21},
                },
                "tagged_scope": None,
                "need_ids": ["NEED_001"],
                "marker": "@need-ids:",
                "type": "need-id-refs",
            }
        ]
    }
    jsonpath = tmp_path / "marked_content.json"
    jsonpath.write_text(json.dumps(marked), encoding="utf-8")
    outpath = tmp_path / "needextend.rst"

    result = runner.invoke(
        app, ["write", "rst", str(jsonpath), "--outpath", str(outpath)]
    )

    assert result.exit_code == 0, result.output
    assert WRITE_RST_DEPRECATED in _normalize_output(result.stderr)
    assert "deprecated" not in result.stdout
    assert outpath.read_text(encoding="utf-8") == (
        ".. needextend:: NEED_001\n"
        "   :remote_url: https://example.com/src/dummy_1.cpp#L3\n\n"
    )


@pytest.mark.parametrize(
    ("json_objs", "output_lines"),
    [
        (
            [
                {
                    "filepath": 123,
                    "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/multiline_needs/dummy_1.cpp#L4",
                    "source_map": {
                        "start": {"row": 3, "column": 8},
                        "end": {"row": 3, "column": 61},
                    },
                    "tagged_scope": "void dummy_func1(){\n     //...\n }",
                    "type": "need-id-refs",
                }
            ],
            [
                "Invalid value: Errors occurred",
                "Schema validation error in field 'filepath': 123 is not of type 'string'",
                "Marker is required for marked content of type 'need_id_refs'",
                "Need id refs are required for marked content of type 'need_id_refs'",
            ],
        ),
    ],
)
def test_write_rst_negative(json_objs: list[dict], output_lines, tmp_path) -> None:
    to_dump = {"project_1": json_objs}
    jsonpath = Path("invalid_objs.json")
    with jsonpath.open("w") as f:
        json.dump(to_dump, f)
    outpath = tmp_path / "needextend.rst"
    options = [
        "write",
        "rst",
        str(jsonpath),
        "--outpath",
        str(outpath),
    ]
    result = runner.invoke(app, options)

    assert result.exit_code != 0
    normalized = _normalize_output(result.output)
    for line in output_lines:
        assert line in normalized


def test_analyse_with_relative_git_root(tmp_path: Path) -> None:
    """Test that relative git_root is resolved relative to the config file location."""
    # Create a fake git repo structure
    fake_git_root = tmp_path / "fake_repo"
    fake_git_root.mkdir()
    (fake_git_root / ".git").mkdir()
    git_config = fake_git_root / ".git" / "config"
    git_config.write_text(
        '[remote "origin"]\n    url = https://github.com/test/repo.git\n'
    )
    git_head = fake_git_root / ".git" / "HEAD"
    git_head.write_text("ref: refs/heads/main\n")
    refs_dir = fake_git_root / ".git" / "refs" / "heads"
    refs_dir.mkdir(parents=True)
    (refs_dir / "main").write_text("abc123def456\n")

    # Create source file
    src_dir = fake_git_root / "src"
    src_dir.mkdir()
    src_file = src_dir / "test.c"
    src_file.write_text("// @Test, TEST_1, test\nvoid test() {}\n")

    # Create config in a subdirectory using a RELATIVE git_root path
    config_dir = tmp_path / "config"
    config_dir.mkdir()
    config_file = config_dir / "codelinks.toml"
    config_content = """
[codelinks.projects.test_project.source_discover]
src_dir = "../fake_repo/src"
gitignore = false

[codelinks.projects.test_project.analyse]
get_oneline_needs = true
git_root = "../fake_repo"
"""
    config_file.write_text(config_content)

    outdir = tmp_path / "output"
    outdir.mkdir()

    options = ["analyse", str(config_file), "--outdir", str(outdir)]
    result = runner.invoke(app, options)

    assert result.exit_code == 0, f"CLI failed: {result.stdout}"
    output_path = outdir / "marked_content.json"
    assert output_path.exists()

    with output_path.open("r") as f:
        marked_content = json.load(f)
    # Verify the content was analysed using the correct git_root
    assert len(marked_content["test_project"]) > 0


def test_analyse_with_absolute_git_root(tmp_path: Path) -> None:
    """Test that absolute git_root is used as-is."""
    # Create a fake git repo structure
    fake_git_root = tmp_path / "fake_repo"
    fake_git_root.mkdir()
    (fake_git_root / ".git").mkdir()
    git_config = fake_git_root / ".git" / "config"
    git_config.write_text(
        '[remote "origin"]\n    url = https://github.com/test/repo.git\n'
    )
    git_head = fake_git_root / ".git" / "HEAD"
    git_head.write_text("ref: refs/heads/main\n")
    refs_dir = fake_git_root / ".git" / "refs" / "heads"
    refs_dir.mkdir(parents=True)
    (refs_dir / "main").write_text("abc123def456\n")

    # Create source file
    src_dir = fake_git_root / "src"
    src_dir.mkdir()
    src_file = src_dir / "test.c"
    src_file.write_text("// @Test, TEST_2, test\nvoid test() {}\n")

    # Create config in a different location using an ABSOLUTE git_root path
    config_dir = tmp_path / "config"
    config_dir.mkdir()
    config_file = config_dir / "codelinks.toml"
    # Use absolute path for both src_dir and git_root
    config_content = f"""
[codelinks.projects.test_project.source_discover]
src_dir = "{src_dir.as_posix()}"
gitignore = false

[codelinks.projects.test_project.analyse]
get_oneline_needs = true
git_root = "{fake_git_root.as_posix()}"
"""
    config_file.write_text(config_content)

    outdir = tmp_path / "output"
    outdir.mkdir()

    options = ["analyse", str(config_file), "--outdir", str(outdir)]
    result = runner.invoke(app, options)

    assert result.exit_code == 0, f"CLI failed: {result.stdout}"
    output_path = outdir / "marked_content.json"
    assert output_path.exists()

    with output_path.open("r") as f:
        marked_content = json.load(f)
    # Verify the content was analysed using the correct git_root
    assert len(marked_content["test_project"]) > 0


# -- the TOML reader of `codelinks analyse` ----------------------------------------------


def _analyse(tmp_path: Path, toml_text: str) -> tuple[int, str]:
    config = tmp_path / "cl.toml"
    config.write_text(toml_text, encoding="utf-8")
    result = runner.invoke(app, ["analyse", str(config), "--outdir", str(tmp_path)])
    return result.exit_code, _normalize_output(result.output)


def test_analyse_toml_syntax_error_shows_the_reason(tmp_path: Path) -> None:
    """The parser's own message reaches the user, not only "Failed to load"."""
    broken = "[codelinks\n"
    with pytest.raises(tomllib.TOMLDecodeError) as parse_error:
        tomllib.loads(broken)

    exit_code, output = _analyse(tmp_path, broken)

    assert exit_code == 2
    assert _normalize_output(str(parse_error.value)) in output
    # ub-project's own words, not the catch-all's
    assert "Failed to load" not in output


@pytest.mark.parametrize(
    ("value", "type_name"),
    [('"x"', "str"), ("0", "int"), ("[]", "list"), ("false", "bool")],
)
def test_analyse_codelinks_not_a_table(
    tmp_path: Path, value: str, type_name: str
) -> None:
    """``codelinks`` that is not a table is named as such, for a falsy value too."""
    exit_code, output = _analyse(tmp_path, f"codelinks = {value}\n")

    assert exit_code == 2
    assert f"[codelinks] must be a table, got {type_name}" in output
    assert "No 'codelinks' section" not in output
    assert "Failed to load" not in output


@pytest.mark.parametrize(
    "toml_text",
    [
        pytest.param("[codelinks]\n", id="empty-table"),
        pytest.param("[needs]\nid_required = true\n", id="no-table"),
    ],
)
def test_analyse_without_codelinks_configuration(
    tmp_path: Path, toml_text: str
) -> None:
    """A missing or empty ``[codelinks]`` keeps today's words."""
    exit_code, output = _analyse(tmp_path, toml_text)

    assert exit_code == 2
    assert "No 'codelinks' section found" in output


def test_analyse_too_deeply_nested_toml_is_a_bad_parameter(tmp_path: Path) -> None:
    """``tomllib`` can fail with an exception ub-project does not wrap (a
    ``RecursionError`` on a pathologically nested file): still a usage error, rc 2,
    never a traceback."""
    exit_code, _output = _analyse(tmp_path, "x = " + "[" * 5000 + "]" * 5000 + "\n")

    # 1 would be the uncaught exception; typer reports a BadParameter as 2
    assert exit_code == 2


def _fake_git_repo(root: Path) -> None:
    """A repository on GitHub with one commit: ``config``, ``HEAD`` and one ref."""
    (root / ".git" / "refs" / "heads").mkdir(parents=True)
    (root / ".git" / "config").write_text(
        '[remote "origin"]\n    url = https://github.com/test/repo.git\n',
        encoding="utf-8",
    )
    (root / ".git" / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
    (root / ".git" / "refs" / "heads" / "main").write_text(
        "abc123def456\n", encoding="utf-8"
    )


def test_analyse_writes_a_multiline_need_record(tmp_path: Path) -> None:
    """``codelinks analyse`` writes a multi-line need as one ``multiline-need`` record:
    the need with its option values as written, the resolved markup, and a source whose
    path is relative to the repository root."""
    repo = tmp_path / "repo"
    _fake_git_repo(repo)
    (repo / "src").mkdir()
    src_file = repo / "src" / "demo.cpp"
    src_file.write_text(
        "// @need[md] impl: Demo need\n"
        "// :id: IMPL_DEMO\n"
        "// :links: REQ_1, REQ_2\n"
        "//\n"
        "// Calls *nothing*.\n"
        "// @endneed\n"
        "void demo() {}\n",
        encoding="utf-8",
    )
    config = repo / "ubproject.toml"
    config.write_text(
        "[codelinks.projects.demo.source_discover]\n"
        'src_dir = "src"\n'
        'comment_type = "cpp"\n'
        "gitignore = false\n"
        "[codelinks.projects.demo.analyse]\n"
        "get_multiline_needs = true\n",
        encoding="utf-8",
    )
    outdir = tmp_path / "out"
    outdir.mkdir()

    result = runner.invoke(app, ["analyse", str(config), "--outdir", str(outdir)])

    assert result.exit_code == 0, result.output
    marked = json.loads((outdir / "marked_content.json").read_text(encoding="utf-8"))
    (record,) = marked["demo"]
    assert Path(record.pop("filepath")) == src_file.resolve()
    assert record == {
        "remote_url": "https://github.com/test/repo/blob/abc123def456/src/demo.cpp#L1",
        "source_map": {
            "start": {"row": 0, "column": 3},
            "end": {"row": 5, "column": 11},
        },
        "tagged_scope": "void demo() {}",
        "type": "multiline-need",
        "need": {
            "type": "impl",
            "title": "Demo need",
            "id": "IMPL_DEMO",
            "links": "REQ_1, REQ_2",
            "content": "Calls *nothing*.",
            "doctype": ".md",
        },
        "markup": "md",
        "source": {
            "project": "demo",
            "path": "src/demo.cpp",
            "root": "git",
            "commit": "abc123def456",
            "start": {"line": 1, "col": 3},
            "end": {"line": 6, "col": 11},
            "content_start": {"line": 5, "col": 3},
            "option_lines": {"id": 2, "links": 3},
            "scope": {"kind": "function_definition", "start": 7, "end": 7},
        },
    }


def test_analyse_prints_a_multiline_need_warning_like_a_oneline_one(
    tmp_path: Path,
) -> None:
    """A refused block is printed in the one shape every analyse warning takes."""
    (tmp_path / "open.cpp").write_text(
        "// @need impl: Never closed\nvoid f() {}\n", encoding="utf-8"
    )
    config = tmp_path / "ubproject.toml"
    config.write_text(
        "[codelinks.projects.p.source_discover]\n"
        'src_dir = "./"\n'
        'comment_type = "cpp"\n'
        "[codelinks.projects.p.analyse]\n"
        "get_multiline_needs = true\n",
        encoding="utf-8",
    )
    outdir = tmp_path / "out"
    outdir.mkdir()

    result = runner.invoke(app, ["analyse", str(config), "--outdir", str(outdir)])

    assert result.exit_code == 0, result.output
    # rich wraps the console at its width, anywhere in a long path: compare without
    # whitespace
    expected = (
        f"Analyse warning in {tmp_path.resolve() / 'open.cpp'}:1 - "
        "multiline_need_unterminated: no '@endneed' line before the comment ends"
    )
    assert re.sub(r"\s+", "", expected) in re.sub(r"\s+", "", result.output)


@pytest.mark.parametrize(
    ("analyse", "message"),
    [
        pytest.param(
            {"get_rst": True},
            "analyse: 'get_rst' is no longer supported: the marked-rst blocks were "
            "replaced by multi-line needs (the @need and @endneed markers); use "
            "get_multiline_needs instead",
            id="get_rst",
        ),
        pytest.param(
            {"marked_rst": {"start_sequence": "@rst"}},
            "analyse: '[analyse.marked_rst]' is no longer supported",
            id="marked_rst",
        ),
        pytest.param(
            {"get_rst": False, "marked_rst": {"end_sequence": "@endrst"}},
            "analyse: 'get_rst' and '[analyse.marked_rst]' are no longer supported: "
            "the marked-rst blocks were replaced by multi-line needs (the @need and "
            "@endneed markers); use get_multiline_needs and [analyse.multiline_needs] "
            "instead",
            id="both",
        ),
    ],
)
def test_analyse_names_the_replacement_of_a_removed_key(
    analyse: dict, message: str, tmp_path: Path
) -> None:
    """The keys of the removed marked-rst blocks stop the CLI with one message naming
    what replaces them, through the channel of every other configuration error."""
    config_file = tmp_path / "codelinks_config.toml"
    with config_file.open("w", encoding="utf-8") as f:
        toml.dump(
            {
                "codelinks": {
                    "projects": {
                        "p": {
                            "source_discover": {"src_dir": str(tmp_path)},
                            "analyse": analyse,
                        }
                    }
                }
            },
            f,
        )

    result = runner.invoke(app, ["analyse", str(config_file)])

    assert result.exit_code != 0
    assert f"Invalid value: {message}" in _normalize_output(result.output)


@pytest.mark.parametrize(
    ("selected", "warnings"),
    [pytest.param([], 2, id="every_project"), pytest.param(["-p", "a"], 1, id="one")],
)
def test_analyse_tolerates_get_rst_false(
    tmp_path: Path, selected: list[str], warnings: int
) -> None:
    """``get_rst = false`` is warned about once per project the command analyses, and
    the analysis runs."""
    config_file = tmp_path / "codelinks_config.toml"
    project = {
        "source_discover": {"src_dir": str(tmp_path)},
        "analyse": {"get_rst": False},
    }
    with config_file.open("w", encoding="utf-8") as f:
        toml.dump({"codelinks": {"projects": {"a": project, "b": project}}}, f)

    result = runner.invoke(app, ["analyse", str(config_file), *selected])

    assert result.exit_code == 0, result.output
    output = _normalize_output(result.output)
    ignored = (
        "analyse: 'get_rst' is no longer read: the marked-rst blocks were replaced "
        "by multi-line needs (the @need and @endneed markers); get_rst = false asks "
        "for nothing and can be removed"
    )
    assert output.count(ignored) == warnings
    # each line names its project
    named = [name for name in ("a", "b") if f"Project {name!r}: {ignored}" in output]
    assert named == ["a", "b"][:warnings]