zensical/python/tests/unit/extensions/test_macros.py

# Copyright (c) 2025-2026 Zensical and contributors

# SPDX-License-Identifier: MIT
# All contributions are certified under the DCO

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import pytest
from jinja2.exceptions import TemplateSyntaxError, UndefinedError
from markdown import Markdown

from zensical.extensions.context import (
    ContextExtension,
    ContextPreprocessor,
    Page,
)
from zensical.extensions.emoji import to_svg, twemoji
from zensical.extensions.macros import (
    MacroEnv,
    MacrosExtension,
    _fix_url,
    _format_value,
    _load_module,
    _load_one_yaml,
    _make_table,
    _merge_include_yaml,
    _pretty,
)

if TYPE_CHECKING:
    from pathlib import Path


MINIMAL_EXTENSIONS = {}

RECOMMENDED_EXTENSIONS = {
    "abbr": {},
    "admonition": {},
    "attr_list": {},
    "def_list": {},
    "footnotes": {},
    "md_in_html": {},
    "toc": {"permalink": True},
    "pymdownx.arithmatex": {"generic": True},
    "pymdownx.betterem": {},
    "pymdownx.caret": {},
    "pymdownx.details": {},
    "pymdownx.emoji": {
        "emoji_generator": to_svg,
        "emoji_index": twemoji,
    },
    "pymdownx.highlight": {
        "anchor_linenums": True,
        "line_spans": "__span",
        "pygments_lang_class": True,
    },
    "pymdownx.inlinehilite": {},
    "pymdownx.keys": {},
    "pymdownx.magiclink": {},
    "pymdownx.mark": {},
    "pymdownx.smartsymbols": {},
    "pymdownx.superfences": {
        "custom_fences": [{"name": "mermaid", "class": "mermaid"}]
    },
    "pymdownx.tabbed": {
        "alternate_style": True,
        "combine_header_slug": True,
    },
    "pymdownx.tasklist": {"custom_checkbox": True},
    "pymdownx.tilde": {},
}


def _page(meta: dict[str, Any] | None = None) -> dict[str, Any]:
    return {
        "url": "/",
        "path": "index.md",
        "meta": dict(meta or {}),
    }


@pytest.fixture(
    name="project_config",
    params=[MINIMAL_EXTENSIONS, RECOMMENDED_EXTENSIONS],
    ids=["minimal_markdown", "recommended_markdown"],
)
def _fixture_project_config(request: pytest.FixtureRequest) -> dict[str, Any]:
    active_markdown = dict(request.param)
    return {"site_name": "Demo", "markdown_extensions": active_markdown}


@pytest.fixture(name="md")
def _fixture_md(
    project_config: dict[str, Any],
    request: pytest.FixtureRequest,
    tmp_path: Path,
) -> Markdown:
    """Return a Markdown instance with MacrosExtension registered."""
    fixture_param = dict(getattr(request, "param", {}))
    allowed_keys = {"macros", "page", "project_config"}
    unexpected_keys = set(fixture_param) - allowed_keys
    if unexpected_keys:
        raise ValueError(
            f"Unsupported md fixture params: {sorted(unexpected_keys)}. "
            "Use only 'macros', 'page', and 'project_config'."
        )
    macro_config = dict(fixture_param.get("macros", {}))
    page = fixture_param.get("page", Page(url="/", path="index.md"))
    if isinstance(page, dict):
        page = Page(**page)
    project_overrides = dict(fixture_param.get("project_config", {}))
    effective_project_config = {**project_config, **project_overrides}
    if "root_dir" not in effective_project_config:
        effective_project_config["root_dir"] = str(tmp_path)
    markdown_extensions = dict(
        effective_project_config.get("markdown_extensions", {})
    )
    md = Markdown(
        extensions=list(markdown_extensions.keys()),
        extension_configs=markdown_extensions,
    )
    ContextExtension(page=page, config=effective_project_config).extendMarkdown(
        md
    )
    MacrosExtension(**macro_config).extendMarkdown(md)
    return md


@pytest.mark.parametrize(
    ("url", "expected"),
    [
        ("page.html", "../page.html"),
        ("assets/img.png", "../assets/img.png"),
        ("https://example.org", "https://example.org"),
        ("mailto:test@example.org", "mailto:test@example.org"),
    ],
)
def test_fix_url(url: str, expected: str) -> None:
    assert _fix_url(url) == expected


def test_macro_env_registers_macros_and_filters() -> None:
    env = MacroEnv()

    @env.macro
    def twice(value: int) -> int:
        return value * 2

    @env.filter(name="rev")
    def reverse(value: str) -> str:
        return value[::-1]

    assert env.macros["twice"](4) == 8
    assert env.filters["rev"]("abc") == "cba"


@pytest.mark.parametrize(
    ("payload", "expected"),
    [
        ([("alpha", "str", "hello")], "**alpha** | *str* | hello"),
        ([], ""),
    ],
)
def test_pretty(payload: list[tuple[str, str, str]], expected: str) -> None:
    output = _pretty(payload)
    if expected:
        assert expected in output
    else:
        assert output == ""


def test_make_table_escapes_pipe() -> None:
    table = _make_table(
        rows=[("left|right", "type", "a|b")],
        header=("Variable", "Type", "Content"),
    )
    assert "left\\|right" in table
    assert "a\\|b" in table


def test_format_value_for_callable_and_dict() -> None:
    def sample(name: str) -> str:
        """Doc first line.\nIgnored."""
        return name

    class Obj:
        pass

    value = {
        "count": 1,
        "name": "hello",
        "obj": Obj(),
    }

    rendered_callable = _format_value(sample)
    rendered_dict = _format_value(value)

    assert "(*name*)" in rendered_callable
    assert "Doc first line." in rendered_callable
    assert "**count** = 1" in rendered_dict
    assert "**obj** [*Obj*]" in rendered_dict


@pytest.mark.parametrize(
    ("relative_path", "content", "expected"),
    [
        ("ok.yaml", "a: 1\nb: x\n", {"a": 1, "b": "x"}),
        ("not_dict.yaml", "- 1\n- 2\n", None),
    ],
)
def test_load_one_yaml_with_relative_paths(
    tmp_path: Path,
    relative_path: str,
    content: str,
    expected: dict | None,
) -> None:
    (tmp_path / relative_path).write_text(content, encoding="utf-8")
    loaded = _load_one_yaml(relative_path, tmp_path)
    assert loaded == expected


def test_load_one_yaml_blocks_outside_project_root(tmp_path: Path) -> None:
    outside = tmp_path.parent / "outside.yaml"
    outside.write_text("x: 1\n", encoding="utf-8")
    loaded = _load_one_yaml(str(outside), tmp_path)
    assert loaded is None


@pytest.mark.parametrize(
    "include_yaml",
    [
        ["a.yaml", "b.yaml"],
        {"left": "a.yaml", "right": "b.yaml"},
    ],
)
def test_merge_include_yaml_list_and_dict(
    tmp_path: Path,
    include_yaml: list[str] | dict[str, str],
) -> None:
    (tmp_path / "a.yaml").write_text("x: 1\n", encoding="utf-8")
    (tmp_path / "b.yaml").write_text("y: 2\n", encoding="utf-8")
    variables: dict = {}
    _merge_include_yaml(include_yaml, tmp_path, variables)
    if isinstance(include_yaml, list):
        assert variables == {"x": 1, "y": 2}
    else:
        assert variables == {"left": {"x": 1}, "right": {"y": 2}}


def test_load_module_from_local_file(tmp_path: Path) -> None:
    (tmp_path / "main.py").write_text(
        "def define_env(env):\n"
        "    env.variables['site_name'] = 'Demo'\n"
        "    @env.macro\n"
        "    def twice(x):\n"
        "        return x * 2\n"
        "    @env.filter\n"
        "    def shout(s):\n"
        "        return s.upper()\n",
        encoding="utf-8",
    )
    variables, macros, filters = _load_module("main", tmp_path)
    assert variables["site_name"] == "Demo"
    assert macros["twice"](3) == 6
    assert filters["shout"]("hi") == "HI"


@pytest.mark.parametrize("module_name", ["../evil", "foo/bar", r"foo\\bar"])
def test_load_module_rejects_non_package_like_module_names(
    module_name: str,
) -> None:
    assert _load_module(module_name) == ({}, {}, {})


@pytest.mark.parametrize(
    ("md", "expected"),
    [
        ({"macros": {"render_by_default": False}}, "<p>Value: {{ 1 + 1 }}</p>"),
        ({"macros": {"render_by_default": True}}, "<p>Value: 2</p>"),
    ],
    indirect=["md"],
)
def test_preprocessor_respects_render_by_default(
    md: Markdown, expected: str
) -> None:
    source = "Value: {{ 1 + 1 }}"
    assert md.convert(source) == expected


@pytest.mark.parametrize(
    "md",
    [
        {
            "macros": {"render_by_default": False},
            "page": _page({"render_macros": True}),
        },
    ],
    indirect=True,
)
def test_preprocessor_renders_when_opted_in_by_page_meta(md: Markdown) -> None:
    assert md.convert("Value: {{ 1 + 1 }}") == "<p>Value: 2</p>"


@pytest.mark.parametrize(
    "md",
    [
        {
            "macros": {
                "render_by_default": True,
                "include_yaml": ["vars.yaml"],
                "module_name": "main",
            },
            "page": _page({"render_macros": True}),
            "project_config": {"extra": {"who": "world"}},
        },
    ],
    indirect=True,
)
def test_preprocessor_renders_with_include_yaml_and_module(
    md: Markdown,
    tmp_path: Path,
) -> None:
    (tmp_path / "vars.yaml").write_text("name: Ada\n", encoding="utf-8")
    (tmp_path / "main.py").write_text(
        "def define_env(env):\n"
        "    @env.macro\n"
        "    def greet(name):\n"
        "        return f'Hello {name}!'\n",
        encoding="utf-8",
    )
    rendered = md.convert("{{ greet(name) }}\n\n{{ who }}")
    assert "Hello Ada!" in rendered
    assert "world" in rendered


@pytest.mark.parametrize(
    "md",
    [{"macros": {"render_by_default": True}}],
    indirect=True,
)
def test_preprocessor_error_handling_keep_text_by_default(md: Markdown) -> None:
    assert "{{ not_closed" in md.convert("{{ not_closed")


@pytest.mark.parametrize(
    "md",
    [{"macros": {"render_by_default": True, "on_error_fail": True}}],
    indirect=True,
)
def test_preprocessor_error_handling_raises_when_enabled(md: Markdown) -> None:
    with pytest.raises(TemplateSyntaxError):
        md.convert("{{ not_closed")


@pytest.mark.parametrize(
    "md",
    [
        {
            "macros": {"render_by_default": True},
            "page": _page({"render_macros": True, "title": "Doc {{ 2 + 3 }}"}),
        },
    ],
    indirect=True,
)
def test_preprocessor_renders_jinja_in_title_meta(md: Markdown) -> None:
    md.convert("# {{ title }}")
    context = ContextPreprocessor.from_markdown(md)
    assert context is not None
    assert context.page.meta["title"] == "Doc 5"


@pytest.mark.parametrize(
    "md",
    [
        {
            "macros": {
                "render_by_default": True,
                "on_undefined": "strict",
                "on_error_fail": True,
            },
        }
    ],
    indirect=True,
)
def test_preprocessor_strict_undefined_raises(md: Markdown) -> None:
    with pytest.raises(UndefinedError):
        md.convert("{{ missing_variable }}")


@pytest.mark.parametrize(
    "md",
    [
        {
            "macros": {
                "render_by_default": True,
                "module_name": "main",
            },
            "project_config": {
                "markdown_extensions": {"pymdownx.superfences": {}}
            },
        }
    ],
    indirect=True,
)
def test_macro_fenced_code_block_processed_by_superfences(
    md: Markdown,
    tmp_path: Path,
) -> None:
    """A macro that outputs a fenced code block is processed by superfences."""
    (tmp_path / "main.py").write_text(
        "def define_env(env):\n"
        "    @env.macro\n"
        "    def code_snippet(lang, code):\n"
        "        return f'```{lang}\\n{code}\\n```\\n'\n",
        encoding="utf-8",
    )
    result = md.convert("{{ code_snippet('python', 'x = 1 + 1') }}")
    assert "<code>python" not in result
    assert "x = 1 + 1" not in result  # we expect spans