tag
+ assert len(children) == 1
+ div_tag = children[0]
+ assert isinstance(div_tag, HTMLTag)
+ assert div_tag.tag_name == "div"
+
+
+class TestRenderDocument:
+ def test_creates_div_with_class(
+ self, context: Context, html_root: HTMLRoot
+ ) -> None:
+ markdown = "document content"
+ doc = md.Document(markdown)
+ node = MarkdownNode(doc)
+
+ result = _render_document(context, html_root, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "div"
+ assert result.attributes.get("class") == "markdown"
+
+
+class TestRenderHtml:
+ def test_dispatches_to_correct_renderer(
+ self, context: Context, html_root: HTMLRoot
+ ) -> None:
+ markdown = "plain text"
+ doc = md.Document(markdown)
+ node = MarkdownNode(doc)
+
+ result = render_html(context, html_root, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "div"
+
+ def test_renders_paragraph(
+ self, context: Context, html_root: HTMLRoot
+ ) -> None:
+ markdown = "paragraph"
+ doc = md.Document(markdown)
+ para = doc.children[0]
+ node = MarkdownNode(para)
+
+ result = render_html(context, html_root, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "p"
+
+
+class TestDocstringVisitorEdgeCases:
+ def test_docstring_at_root_becomes_markdown(self) -> None:
+ visitor = _DocstringVisitor()
+ docstring = nodes.Docstring("**bold** text")
+
+ docstring.visit(visitor)
+
+ assert visitor.root is not None
+ assert isinstance(visitor.root, MarkdownNode)
+
+ def test_nested_docstrings(self) -> None:
+ visitor = _DocstringVisitor()
+ inner_doc = nodes.Docstring("inner")
+ outer = ListNode([inner_doc])
+
+ outer.visit(visitor)
+
+ children = list(outer.children)
+ assert len(children) == 1
+ assert isinstance(children[0], MarkdownNode)
+
+
+class TestReferenceVisitorEdgeCases:
+ def test_autolink_with_ref_becomes_reference(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "
"
+ root = MarkdownNode(md.Document(markdown))
+
+ root.visit(visitor)
+
+ checker = ReferenceChecker()
+ assert visitor.root is not None
+ visitor.root.visit(checker)
+ assert (
+ checker.found
+ ), "Autolink with ref: prefix should become Reference"
+
+ def test_link_with_multiple_children(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "[**bold** text](ref:test)"
+ root = MarkdownNode(md.Document(markdown))
+
+ root.visit(visitor)
+
+ checker = ReferenceChecker()
+ assert visitor.root is not None
+ visitor.root.visit(checker)
+ assert (
+ checker.found
+ ), "Link with multiple children should become Reference"
+
+ def test_link_without_ref_prefix_unchanged(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "[link](https://example.com)"
+ root = MarkdownNode(md.Document(markdown))
+
+ root.visit(visitor)
+
+ assert isinstance(
+ visitor.root, MarkdownNode
+ ), "Root should remain MarkdownNode"
+ checker = ReferenceChecker()
+ assert visitor.root is not None
+ visitor.root.visit(checker)
+ assert (
+ not checker.found
+ ), "Regular links should not become Reference nodes"
+
+
+class TestSearchVisitorEdgeCases:
+ def test_enter_returns_traverse_children_for_non_markdown(self) -> None:
+ visitor = _SearchVisitor()
+ blank = BlankNode()
+
+ result = visitor.enter(blank)
+
+ assert result == Visit.TraverseChildren
+
+ def test_exit_does_nothing(self) -> None:
+ visitor = _SearchVisitor()
+ blank = BlankNode()
+
+ visitor.exit(blank)
+
+ def test_raw_text_extraction(self) -> None:
+ visitor = _SearchVisitor()
+ markdown = "plain text content"
+ node = MarkdownNode(md.Document(markdown))
+
+ node.visit(visitor)
+
+ assert "plain text content" in visitor.texts
+
+ def test_to_search_joins_multiple_fragments_with_spaces(self) -> None:
+ # Two paragraphs produce separate RawText tokens: "bold" and
+ # "new paragraph". With " ".join() these become
+ # "bold new paragraph"; with "".join() they would become
+ # "boldnew paragraph".
+ node = MarkdownNode(md.Document("**bold**\n\nnew paragraph"))
+ result = node.to_search()
+
+ assert "bold new" in result
diff --git a/tests/test_mistletoe_extended.py b/tests/test_mistletoe_extended.py
new file mode 100644
index 0000000..362c9d0
--- /dev/null
+++ b/tests/test_mistletoe_extended.py
@@ -0,0 +1,269 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import typing
+from pathlib import Path
+
+import mistletoe as md
+import pytest
+from conftest import ReferenceChecker
+from mistletoe.token import Token as MarkdownToken
+
+from docc.context import Context
+from docc.document import BlankNode, Document, ListNode
+from docc.plugins.mistletoe import (
+ DocstringTransform,
+ MarkdownNode,
+ ReferenceTransform,
+ _DocstringVisitor,
+ _ReferenceVisitor,
+ _SearchVisitor,
+)
+from docc.plugins.python import nodes
+from docc.plugins.references import Reference
+from docc.settings import PluginSettings, Settings
+
+
+@pytest.fixture
+def plugin_settings() -> PluginSettings:
+ settings = Settings(Path("."), {"tool": {"docc": {}}})
+ return settings.for_plugin("docc.mistletoe.transform")
+
+
+class TestDocstringVisitor:
+ def test_enter_non_docstring_node(self) -> None:
+ visitor = _DocstringVisitor()
+ blank = BlankNode()
+
+ visitor.enter(blank)
+ assert visitor.root is blank
+
+ def test_exit_non_docstring_node(self) -> None:
+ visitor = _DocstringVisitor()
+ blank = BlankNode()
+
+ visitor.enter(blank)
+ visitor.exit(blank)
+
+ assert len(visitor.stack) == 0
+
+ def test_transforms_docstring_to_markdown(self) -> None:
+ visitor = _DocstringVisitor()
+ docstring = nodes.Docstring("Test **bold**")
+ parent = ListNode([docstring])
+
+ parent.visit(visitor)
+
+ children = list(parent.children)
+ assert len(children) == 1
+ assert not isinstance(children[0], nodes.Docstring)
+
+
+class TestReferenceVisitor:
+ def test_enter_non_markdown_node(self) -> None:
+ visitor = _ReferenceVisitor()
+ blank = BlankNode()
+
+ visitor.enter(blank)
+ assert visitor.root is blank
+
+ def test_exit_non_markdown_node(self) -> None:
+ visitor = _ReferenceVisitor()
+ blank = BlankNode()
+
+ visitor.enter(blank)
+ visitor.exit(blank)
+
+ assert len(visitor.stack) == 0
+
+ def test_transforms_ref_link_to_reference(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "[text](ref:identifier)"
+ root = MarkdownNode(md.Document(markdown))
+
+ root.visit(visitor)
+
+ checker = ReferenceChecker()
+ assert visitor.root is not None
+ visitor.root.visit(checker)
+ assert (
+ checker.found
+ ), "ref: link should be transformed to Reference node"
+
+ def test_ignores_non_ref_links(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "[text](https://example.com)"
+ root = MarkdownNode(md.Document(markdown))
+
+ root.visit(visitor)
+
+ checker = ReferenceChecker()
+ assert visitor.root is not None
+ visitor.root.visit(checker)
+ assert (
+ not checker.found
+ ), "Regular links should not become Reference nodes"
+
+ def test_ref_link_becomes_root_when_only_element(self) -> None:
+ visitor = _ReferenceVisitor()
+ markdown = "[ref](ref:test)"
+ token = md.Document(markdown)
+ paragraph = token.children[0]
+ link_token = paragraph.children[0]
+ link_node = MarkdownNode(link_token)
+ link_node.visit(visitor)
+
+ assert isinstance(
+ visitor.root, Reference
+ ), "Single ref link should become Reference root"
+
+
+class TestSearchVisitor:
+ def test_collect_empty(self) -> None:
+ result = _SearchVisitor.collect([])
+ assert result == []
+
+ def test_collect_blank_node(self) -> None:
+ blank = BlankNode()
+ result = _SearchVisitor.collect(blank)
+ assert result == []
+
+ def test_collect_single_node(self) -> None:
+ markdown = "Hello world"
+ node = MarkdownNode(md.Document(markdown))
+ result = _SearchVisitor.collect(node)
+ assert "Hello world" in " ".join(result)
+
+ def test_collect_multiple_nodes(self) -> None:
+ nodes_list = [
+ MarkdownNode(md.Document("First")),
+ MarkdownNode(md.Document("Second")),
+ ]
+ result = _SearchVisitor.collect(nodes_list)
+ combined = " ".join(result)
+ assert "First" in combined
+ assert "Second" in combined
+
+
+class TestDocstringTransform:
+ def test_transform_simple_docstring(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ docstring = nodes.Docstring("A simple docstring")
+ root = ListNode([docstring])
+ document = Document(root)
+ context = Context({Document: document})
+
+ transform = DocstringTransform(plugin_settings)
+ transform.transform(context)
+
+ children = list(context[Document].root.children)
+ assert not isinstance(children[0], nodes.Docstring)
+
+
+class TestReferenceTransform:
+ def test_transform_creates_references(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ markdown = "[link](ref:test.module)"
+ root = MarkdownNode(md.Document(markdown))
+ document = Document(root)
+ context = Context({Document: document})
+
+ transform = ReferenceTransform(plugin_settings)
+ transform.transform(context)
+
+ checker = ReferenceChecker()
+ context[Document].root.visit(checker)
+ assert (
+ checker.found
+ ), "Transform should create Reference nodes from ref: links"
+
+
+class TestMarkdownNodeChildren:
+ def test_children_with_token_children_none(self) -> None:
+ class MockToken:
+ children = None
+
+ node = MarkdownNode(typing.cast(MarkdownToken, MockToken()))
+ children = list(node.children)
+ assert children == []
+
+ def test_children_lazy_evaluation(self) -> None:
+ markdown = "Test **bold**"
+ node = MarkdownNode(md.Document(markdown))
+
+ assert node._children is None
+
+ children = list(node.children)
+
+ assert node._children is not None
+ assert len(children) > 0
+
+
+class TestMarkdownFormats:
+ def test_strong_text(self) -> None:
+ markdown = "**strong**"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "strong" in result
+
+ def test_emphasis_text(self) -> None:
+ markdown = "*emphasis*"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "emphasis" in result
+
+ def test_code_block(self) -> None:
+ markdown = "```python\ncode\n```"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "code" in result, "Code block content should be searchable"
+
+ def test_list_items(self) -> None:
+ markdown = "- item 1\n- item 2"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "item 1" in result
+ assert "item 2" in result
+
+ def test_heading(self) -> None:
+ markdown = "# Heading"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "Heading" in result
+
+ def test_link_with_text(self) -> None:
+ markdown = "[link text](http://example.com)"
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "link text" in result
+
+ def test_mixed_content(self) -> None:
+ markdown = """
+# Title
+
+Paragraph with **bold** and *italic*.
+
+- List item
+- Another item
+
+[Link](http://example.com)
+"""
+ node = MarkdownNode(md.Document(markdown))
+ result = node.to_search()
+ assert "Title" in result
+ assert "bold" in result
+ assert "List item" in result
diff --git a/tests/test_python_cst.py b/tests/test_python_cst.py
new file mode 100644
index 0000000..93afa22
--- /dev/null
+++ b/tests/test_python_cst.py
@@ -0,0 +1,627 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import dataclasses
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path, PurePath
+from typing import Dict, Mapping, Set
+from unittest.mock import patch
+
+import pytest
+
+from docc.document import BlankNode, Document, ListNode
+from docc.plugins.python import nodes
+from docc.plugins.python.cst import (
+ PythonBuilder,
+ PythonDiscover,
+ PythonSource,
+)
+from docc.settings import Settings
+from docc.source import Source
+
+
+@pytest.fixture
+def temp_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as td:
+ yield Path(td)
+
+
+@pytest.fixture
+def settings_with_paths(temp_dir: Path) -> Settings:
+ settings_dict: Dict[str, object] = {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {"paths": [str(temp_dir)]},
+ }
+ }
+ }
+ }
+ return Settings(temp_dir, settings_dict)
+
+
+class TestPythonDiscover:
+ def test_init_raises_on_non_sequence_paths(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {"docc.python.discover": {"paths": 123}}
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+
+ with pytest.raises(TypeError, match="paths must be a list"):
+ PythonDiscover(plugin_settings)
+
+ def test_init_raises_on_non_string_path(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {"docc.python.discover": {"paths": [123]}}
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+
+ with pytest.raises(
+ TypeError, match="every python path must be a string"
+ ):
+ PythonDiscover(plugin_settings)
+
+ def test_init_raises_on_empty_paths(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {"docc.python.discover": {"paths": []}}
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+
+ with pytest.raises(ValueError, match="python needs at least one path"):
+ PythonDiscover(plugin_settings)
+
+ def test_discover_finds_python_files(self, temp_dir: Path) -> None:
+ (temp_dir / "test.py").write_text("# test")
+
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {"paths": [str(temp_dir)]}
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+ discover = PythonDiscover(plugin_settings)
+
+ sources = list(discover.discover(frozenset()))
+ assert len(sources) == 1
+ assert isinstance(sources[0], PythonSource)
+
+ def test_discover_finds_nested_python_files(self, temp_dir: Path) -> None:
+ subdir = temp_dir / "subdir"
+ subdir.mkdir()
+ (subdir / "nested.py").write_text("# nested")
+
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {"paths": [str(temp_dir)]}
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+ discover = PythonDiscover(plugin_settings)
+
+ sources = list(discover.discover(frozenset()))
+ assert len(sources) == 1
+ assert "nested.py" in str(sources[0].relative_path)
+
+ def test_excluded_paths(self, temp_dir: Path) -> None:
+ subdir = temp_dir / "exclude_me"
+ subdir.mkdir()
+ (subdir / "test.py").write_text("# excluded")
+ (temp_dir / "keep.py").write_text("# keep")
+
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {
+ "paths": [str(temp_dir)],
+ "excluded_paths": ["exclude_me"],
+ }
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+ discover = PythonDiscover(plugin_settings)
+
+ sources = list(discover.discover(frozenset()))
+ assert len(sources) == 1
+ assert "keep.py" in str(sources[0].relative_path)
+
+ def test_excluded_paths_non_sequence_raises(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {
+ "paths": [str(temp_dir)],
+ "excluded_paths": 123,
+ }
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+
+ with pytest.raises(TypeError, match="excluded paths must be a list"):
+ PythonDiscover(plugin_settings)
+
+
+class TestPythonSource:
+ def test_relative_path_property(self, temp_dir: Path) -> None:
+ relative = PurePath("test.py")
+ absolute = temp_dir / "test.py"
+ absolute.write_text("# test")
+
+ source = PythonSource(temp_dir, relative, absolute)
+ assert source.relative_path == relative
+
+ def test_output_path_property(self, temp_dir: Path) -> None:
+ relative = PurePath("subdir") / "test.py"
+ absolute = temp_dir / "subdir" / "test.py"
+ absolute.parent.mkdir(exist_ok=True)
+ absolute.write_text("# test")
+
+ source = PythonSource(temp_dir, relative, absolute)
+ assert source.output_path == relative
+
+ def test_open_returns_file_handle(self, temp_dir: Path) -> None:
+ content = "# test content\nx = 1"
+ relative = PurePath("test.py")
+ absolute = temp_dir / "test.py"
+ absolute.write_text(content)
+
+ source = PythonSource(temp_dir, relative, absolute)
+ with source.open() as f:
+ assert f.read() == content
+
+
+class TestPythonBuilder:
+ def test_build_simple_module(self, temp_dir: Path) -> None:
+ content = '''"""Module docstring."""
+x = 1
+'''
+ (temp_dir / "test.py").write_text(content)
+
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {"paths": [str(temp_dir)]}
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+ discover = PythonDiscover(plugin_settings)
+ sources = set(discover.discover(frozenset()))
+
+ builder = PythonBuilder(plugin_settings)
+ documents: Dict[Source, Document] = {}
+ builder.build(sources, documents)
+
+ assert len(documents) == 1
+
+ def test_build_removes_sources_from_unprocessed(
+ self, temp_dir: Path
+ ) -> None:
+ (temp_dir / "test.py").write_text("x = 1")
+
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "plugins": {
+ "docc.python.discover": {"paths": [str(temp_dir)]}
+ }
+ }
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("docc.python.discover")
+ discover = PythonDiscover(plugin_settings)
+ sources: Set[Source] = set(discover.discover(frozenset()))
+ original_count = len(sources)
+
+ builder = PythonBuilder(plugin_settings)
+ documents: Dict[Source, Document] = {}
+ builder.build(sources, documents)
+
+ assert len(sources) == 0
+ assert len(documents) == original_count
+
+
+class TestPythonNodes:
+ def test_module_default_fields(self) -> None:
+ module = nodes.Module()
+ assert isinstance(module.name, BlankNode)
+ assert isinstance(module.docstring, BlankNode)
+ assert isinstance(module.members, ListNode)
+
+ def test_module_children(self) -> None:
+ module = nodes.Module()
+ children = list(module.children)
+ assert len(children) == 3
+
+ def test_module_to_search(self) -> None:
+ module = nodes.Module()
+ module.name = nodes.Name("test_module")
+ result = module.to_search()
+ assert isinstance(result, Mapping)
+ assert result["type"] == "module"
+ assert "test_module" in result["name"]
+
+ def test_class_default_fields(self) -> None:
+ cls = nodes.Class()
+ assert isinstance(cls.decorators, ListNode)
+ assert isinstance(cls.name, BlankNode)
+ assert isinstance(cls.bases, ListNode)
+ assert isinstance(cls.metaclass, BlankNode)
+ assert isinstance(cls.docstring, BlankNode)
+ assert isinstance(cls.members, ListNode)
+
+ def test_class_to_search(self) -> None:
+ cls = nodes.Class()
+ cls.name = nodes.Name("TestClass")
+ result = cls.to_search()
+ assert isinstance(result, Mapping)
+ assert result["type"] == "class"
+ assert "TestClass" in result["name"]
+
+ def test_function_default_fields(self) -> None:
+ func = nodes.Function(asynchronous=False)
+ assert func.asynchronous is False
+ assert isinstance(func.decorators, ListNode)
+ assert isinstance(func.name, BlankNode)
+ assert isinstance(func.parameters, ListNode)
+ assert isinstance(func.return_type, BlankNode)
+ assert isinstance(func.docstring, BlankNode)
+ assert isinstance(func.body, BlankNode)
+
+ def test_function_async(self) -> None:
+ func = nodes.Function(asynchronous=True)
+ assert func.asynchronous is True
+
+ def test_function_to_search(self) -> None:
+ func = nodes.Function(asynchronous=False)
+ func.name = nodes.Name("test_func")
+ result = func.to_search()
+ assert isinstance(result, Mapping)
+ assert result["type"] == "function"
+ assert "test_func" in result["name"]
+
+ def test_parameter(self) -> None:
+ param = nodes.Parameter()
+ assert param.star is None
+ assert isinstance(param.name, BlankNode)
+ assert isinstance(param.type_annotation, BlankNode)
+
+ def test_parameter_with_star(self) -> None:
+ param = nodes.Parameter(star="*")
+ assert param.star == "*"
+
+ double_star_param = nodes.Parameter(star="**")
+ assert double_star_param.star == "**"
+
+ def test_attribute_to_search(self) -> None:
+ attr = nodes.Attribute()
+ attr.names = ListNode([nodes.Name("test_attr")])
+ result = attr.to_search()
+ assert isinstance(result, Mapping)
+ assert result["type"] == "attribute"
+ assert "test_attr" in result["name"]
+
+ def test_name_children_empty(self) -> None:
+ name = nodes.Name("test")
+ assert tuple(name.children) == ()
+
+ def test_name_replace_child_raises(self) -> None:
+ name = nodes.Name("test")
+ with pytest.raises(TypeError):
+ name.replace_child(BlankNode(), BlankNode())
+
+ def test_name_with_full_name(self) -> None:
+ name = nodes.Name("test", "module.test")
+ assert name.name == "test"
+ assert name.full_name == "module.test"
+
+ def test_docstring_children_empty(self) -> None:
+ doc = nodes.Docstring("test docstring")
+ assert tuple(doc.children) == ()
+
+ def test_docstring_replace_child_raises(self) -> None:
+ doc = nodes.Docstring("test")
+ with pytest.raises(TypeError):
+ doc.replace_child(BlankNode(), BlankNode())
+
+ def test_docstring_to_search(self) -> None:
+ doc = nodes.Docstring("This is documentation")
+ assert doc.to_search() == "This is documentation"
+
+ def test_type_node(self) -> None:
+ type_node = nodes.Type()
+ assert isinstance(type_node.child, BlankNode)
+
+ def test_subscript_node(self) -> None:
+ sub = nodes.Subscript()
+ assert isinstance(sub.name, BlankNode)
+ assert isinstance(sub.generics, BlankNode)
+
+ def test_binary_operation(self) -> None:
+ binop = nodes.BinaryOperation()
+ assert isinstance(binop.left, BlankNode)
+ assert isinstance(binop.operator, BlankNode)
+ assert isinstance(binop.right, BlankNode)
+
+ def test_bit_or(self) -> None:
+ bit_or = nodes.BitOr()
+ children = list(bit_or.children)
+ assert len(children) == 0
+
+ def test_list_node(self) -> None:
+ list_node = nodes.List()
+ assert isinstance(list_node.elements, ListNode)
+
+ def test_tuple_node(self) -> None:
+ tuple_node = nodes.Tuple()
+ assert isinstance(tuple_node.elements, ListNode)
+
+ def test_access_node(self) -> None:
+ access = nodes.Access()
+ assert isinstance(access.value, BlankNode)
+ assert isinstance(access.attribute, BlankNode)
+
+
+class TestPythonNodeRepr:
+ def test_module_repr(self) -> None:
+ module = nodes.Module()
+ assert repr(module) == "Module(...)"
+
+ def test_class_repr(self) -> None:
+ cls = nodes.Class()
+ assert repr(cls) == "Class(...)"
+
+ def test_function_repr(self) -> None:
+ func = nodes.Function(asynchronous=False)
+ assert repr(func) == "Function(...)"
+
+
+class TestPythonNodeReplaceChild:
+ def test_replace_child_in_module(self) -> None:
+ old_name = nodes.Name("old")
+ new_name = nodes.Name("new")
+ module = nodes.Module()
+ module.name = old_name
+
+ module.replace_child(old_name, new_name)
+ assert module.name == new_name
+
+ def test_replace_child_not_found(self) -> None:
+ module = nodes.Module()
+ original_name = module.name
+ original_docstring = module.docstring
+ original_members = module.members
+
+ old = nodes.Name("old")
+ new = nodes.Name("new")
+
+ module.replace_child(old, new)
+
+ # Verify original field values are unchanged after no-op replace
+ assert module.name is original_name
+ assert module.docstring is original_docstring
+ assert module.members is original_members
+
+
+class TestNameVisitor:
+ def test_collect_single_name(self) -> None:
+ name = nodes.Name("test")
+ result = nodes._NameVisitor.collect(name)
+ assert result == ["test"]
+
+ def test_collect_multiple_names(self) -> None:
+ names = [nodes.Name("a"), nodes.Name("b"), nodes.Name("c")]
+ result = nodes._NameVisitor.collect(names)
+ assert result == ["a", "b", "c"]
+
+ def test_collect_from_list_node(self) -> None:
+ list_node = ListNode([nodes.Name("x"), nodes.Name("y")])
+ result = nodes._NameVisitor.collect(list_node)
+ assert result == ["x", "y"]
+
+ def test_collect_empty(self) -> None:
+ blank = BlankNode()
+ result = nodes._NameVisitor.collect(blank)
+ assert result == []
+
+
+class TestPythonNodeChildrenTypeError:
+ def test_children_raises_type_error_for_non_node_field(self) -> None:
+ """
+ PythonNode.children raises TypeError when a field annotated
+ as Node contains a non-Node value. This documents the
+ defensive contract in nodes.py:44.
+ """
+ module = nodes.Module()
+ # Forcefully set a Node-typed field to a non-Node value
+ object.__setattr__(module, "name", "not a node")
+
+ with pytest.raises(TypeError, match="child not Node"):
+ list(module.children)
+
+
+class TestFieldsCacheBehavioral:
+ """Behavioral tests for children and replace_child with caching."""
+
+ def setup_method(self) -> None:
+ nodes.PythonNode._fields_cache.clear()
+
+ def test_module_children_yields_expected_nodes(self) -> None:
+ """Module.children should yield all three default child nodes."""
+ module = nodes.Module()
+ children = list(module.children)
+ assert len(children) == 3
+ assert children[0] is module.name
+ assert children[1] is module.docstring
+ assert children[2] is module.members
+
+ def test_function_children_yields_expected_nodes(self) -> None:
+ """Function.children should yield all Node-typed fields."""
+ func = nodes.Function(asynchronous=False)
+ children = list(func.children)
+ # Function has 6 Node fields: decorators, name, parameters,
+ # return_type, docstring, body.
+ assert len(children) == 6
+
+ def test_class_children_yields_expected_nodes(self) -> None:
+ """Class.children should yield all Node-typed fields."""
+ cls = nodes.Class()
+ children = list(cls.children)
+ # Class has 6 Node fields: decorators, name, bases, metaclass,
+ # docstring, members.
+ assert len(children) == 6
+
+ def test_replace_child_works_with_cache(self) -> None:
+ """replace_child should correctly swap a child node."""
+ module = nodes.Module()
+ old_name = module.name
+ new_name = nodes.Name("replaced")
+ module.replace_child(old_name, new_name)
+ assert module.name is new_name
+
+
+class TestFieldsCacheCallCount:
+ """Spy tests verifying fields() is called once per subclass."""
+
+ def setup_method(self) -> None:
+ nodes.PythonNode._fields_cache.clear()
+
+ def test_fields_called_once_for_multiple_module_instances(self) -> None:
+ """Multiple Module instances should trigger only one fields() call."""
+ with patch(
+ "docc.plugins.python.nodes.fields", wraps=dataclasses.fields
+ ) as mock_fields:
+ first = nodes.Module()
+ second = nodes.Module()
+ list(first.children)
+ list(second.children)
+ list(first.children)
+ mock_fields.assert_called_once()
+
+ def test_fields_called_once_per_distinct_subclass(self) -> None:
+ """Each distinct subclass should trigger exactly one fields() call."""
+ with patch(
+ "docc.plugins.python.nodes.fields", wraps=dataclasses.fields
+ ) as mock_fields:
+ module = nodes.Module()
+ func = nodes.Function(asynchronous=False)
+ list(module.children)
+ list(func.children)
+ assert mock_fields.call_count == 2
+
+ def test_replace_child_does_not_trigger_extra_fields_call(self) -> None:
+ """replace_child should reuse cached fields without extra calls."""
+ with patch(
+ "docc.plugins.python.nodes.fields", wraps=dataclasses.fields
+ ) as mock_fields:
+ module = nodes.Module()
+ list(module.children)
+ assert mock_fields.call_count == 1
+
+ old_name = module.name
+ module.replace_child(old_name, nodes.Name("new"))
+ # Still only one call; replace_child used the cache.
+ assert mock_fields.call_count == 1
+
+
+class TestFieldsCacheKeying:
+ """Tests verifying cache keys and stored value types."""
+
+ def setup_method(self) -> None:
+ nodes.PythonNode._fields_cache.clear()
+
+ def test_cache_populated_with_correct_keys(self) -> None:
+ """Cache should contain Module and Function type keys."""
+ module = nodes.Module()
+ func = nodes.Function(asynchronous=False)
+ list(module.children)
+ list(func.children)
+
+ assert nodes.Module in nodes.PythonNode._fields_cache
+ assert nodes.Function in nodes.PythonNode._fields_cache
+
+ def test_cached_values_are_tuples_of_field(self) -> None:
+ """Cached values should be tuples of dataclasses.Field objects."""
+ module = nodes.Module()
+ list(module.children)
+
+ cached = nodes.PythonNode._fields_cache[nodes.Module]
+ assert isinstance(cached, tuple)
+ for item in cached:
+ assert isinstance(item, dataclasses.Field)
+
+ def test_cache_empty_after_clear(self) -> None:
+ """Clearing the cache should remove all entries."""
+ module = nodes.Module()
+ list(module.children)
+ assert len(nodes.PythonNode._fields_cache) > 0
+
+ nodes.PythonNode._fields_cache.clear()
+ assert len(nodes.PythonNode._fields_cache) == 0
diff --git a/tests/test_references.py b/tests/test_references.py
new file mode 100644
index 0000000..604ecd3
--- /dev/null
+++ b/tests/test_references.py
@@ -0,0 +1,386 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import tempfile
+from pathlib import Path, PurePath
+from typing import Iterator, Optional
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode, Document, ListNode
+from docc.plugins.references import (
+ Definition,
+ Index,
+ IndexContext,
+ IndexTransform,
+ Location,
+ Reference,
+ ReferenceError,
+)
+from docc.settings import PluginSettings, Settings
+from docc.source import Source
+
+
+@pytest.fixture
+def temp_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as td:
+ yield Path(td)
+
+
+@pytest.fixture
+def basic_settings(temp_dir: Path) -> Settings:
+ return Settings(temp_dir, {"tool": {"docc": {}}})
+
+
+@pytest.fixture
+def plugin_settings(basic_settings: Settings) -> PluginSettings:
+ return basic_settings.for_plugin("docc.references")
+
+
+_UNSET = object()
+
+
+class MockSource(Source):
+ _output_path: PurePath
+
+ def __init__(
+ self,
+ relative_path: object = _UNSET,
+ output_path: Optional[PurePath] = None,
+ ) -> None:
+ if relative_path is _UNSET:
+ self._relative_path: Optional[PurePath] = PurePath("test.py")
+ elif relative_path is None or isinstance(relative_path, PurePath):
+ self._relative_path = relative_path
+ else:
+ raise TypeError(f"unexpected type: {type(relative_path)}")
+ self._output_path = (
+ output_path or self._relative_path or PurePath("test.py")
+ )
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return self._relative_path
+
+ @property
+ def output_path(self) -> PurePath:
+ return self._output_path
+
+
+class TestLocation:
+ def test_create_location(self) -> None:
+ source = MockSource()
+ location = Location(source=source, identifier="test.func", specifier=0)
+
+ assert location.source is source
+ assert location.identifier == "test.func"
+ assert location.specifier == 0
+
+ def test_location_is_frozen(self) -> None:
+ source = MockSource()
+ location = Location(source=source, identifier="test", specifier=0)
+
+ with pytest.raises(AttributeError):
+ location.identifier = "changed" # pyre-ignore[41]
+
+ def test_location_equality(self) -> None:
+ source = MockSource()
+ first_location = Location(
+ source=source, identifier="test", specifier=0
+ )
+ second_location = Location(
+ source=source, identifier="test", specifier=0
+ )
+ third_location = Location(
+ source=source, identifier="test", specifier=1
+ )
+
+ assert first_location == second_location
+ assert first_location != third_location
+
+ def test_location_is_hashable(self) -> None:
+ source = MockSource()
+ location = Location(source=source, identifier="test", specifier=0)
+ location_set = {location}
+ assert location in location_set
+
+
+class TestIndex:
+ def test_create_index(self) -> None:
+ index = Index()
+ assert isinstance(index._index, dict)
+ assert len(index._index) == 0
+
+ def test_define_creates_location(self) -> None:
+ index = Index()
+ source = MockSource()
+
+ location = index.define(source, "test.module.func")
+
+ assert location.source is source
+ assert location.identifier == "test.module.func"
+ assert location.specifier == 0
+
+ def test_define_increments_specifier(self) -> None:
+ index = Index()
+ source = MockSource()
+
+ first_location = index.define(source, "test.func")
+ second_location = index.define(source, "test.func")
+ third_location = index.define(source, "test.func")
+
+ assert first_location.specifier == 0
+ assert second_location.specifier == 1
+ assert third_location.specifier == 2
+
+ def test_define_different_identifiers(self) -> None:
+ index = Index()
+ source = MockSource()
+
+ first_location = index.define(source, "func_a")
+ second_location = index.define(source, "func_b")
+ third_location = index.define(source, "func_a")
+
+ assert first_location.specifier == 0
+ assert second_location.specifier == 0
+ assert third_location.specifier == 1
+
+ def test_lookup_existing(self) -> None:
+ index = Index()
+ source = MockSource()
+ expected = index.define(source, "test.func")
+
+ result = list(index.lookup("test.func"))
+
+ assert len(result) == 1
+ assert result[0] == expected
+
+ def test_lookup_multiple(self) -> None:
+ index = Index()
+ source = MockSource()
+ first_location = index.define(source, "test.func")
+ second_location = index.define(source, "test.func")
+
+ result = list(index.lookup("test.func"))
+
+ assert len(result) == 2
+ assert first_location in result
+ assert second_location in result
+
+ def test_lookup_nonexistent_raises(self) -> None:
+ index = Index()
+
+ with pytest.raises(ReferenceError):
+ index.lookup("nonexistent")
+
+
+class TestReferenceError:
+ def test_basic_error(self) -> None:
+ error = ReferenceError("undefined_func")
+ assert "undefined_func" in str(error)
+ assert error.identifier == "undefined_func"
+ assert error.context is None
+
+ def test_error_with_context_source(self) -> None:
+ source = MockSource(relative_path=PurePath("src/module.py"))
+ context = Context({Source: source})
+ error = ReferenceError("missing_ref", context=context)
+
+ assert "missing_ref" in str(error)
+ assert "src/module.py" in str(error)
+ assert error.context is context
+
+ def test_error_with_context_no_relative_path(self) -> None:
+ source = MockSource(
+ relative_path=None, output_path=PurePath("output.html")
+ )
+ context = Context({Source: source})
+ error = ReferenceError("missing_ref", context=context)
+
+ assert "missing_ref" in str(error)
+ assert "output.html" in str(error)
+
+
+class TestBase:
+ def test_children_returns_tuple(self) -> None:
+ child = BlankNode()
+ base = Definition(identifier="test", child=child)
+
+ assert base.children == (child,)
+
+ def test_default_child_is_blank(self) -> None:
+ base = Definition(identifier="test")
+
+ assert isinstance(base.child, BlankNode)
+
+ def test_replace_child(self) -> None:
+ old_child = BlankNode()
+ new_child = BlankNode()
+ base = Definition(identifier="test", child=old_child)
+
+ base.replace_child(old_child, new_child)
+
+ assert base.child is new_child
+
+ def test_replace_child_no_match(self) -> None:
+ child = BlankNode()
+ other = BlankNode()
+ new_child = BlankNode()
+ base = Definition(identifier="test", child=child)
+
+ base.replace_child(other, new_child)
+
+ assert base.child is child
+
+
+class TestDefinition:
+ def test_create_definition(self) -> None:
+ child = BlankNode()
+ definition = Definition(identifier="test.func", child=child)
+
+ assert definition.identifier == "test.func"
+ assert definition.child is child
+ assert definition.specifier is None
+
+ def test_specifier_can_be_set(self) -> None:
+ definition = Definition(identifier="test", specifier=5)
+ assert definition.specifier == 5
+
+
+class TestReference:
+ def test_create_reference(self) -> None:
+ child = BlankNode()
+ reference = Reference(identifier="test.func", child=child)
+
+ assert reference.identifier == "test.func"
+ assert reference.child is child
+
+
+class TestIndexContext:
+ def test_provides_index(self) -> None:
+ assert IndexContext.provides() == Index
+
+ def test_init_creates_index(self, plugin_settings: PluginSettings) -> None:
+ ctx = IndexContext(plugin_settings)
+ assert isinstance(ctx.index, Index)
+
+ def test_provide_returns_index(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ ctx = IndexContext(plugin_settings)
+ provided = ctx.provide()
+
+ assert provided is ctx.index
+
+
+class TestIndexTransform:
+ def test_transform_indexes_definitions(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ index = Index()
+
+ definition = Definition(identifier="test.func")
+ root = ListNode([definition])
+ document = Document(root)
+
+ context = Context({Document: document, Source: source, Index: index})
+
+ transform = IndexTransform(plugin_settings)
+ transform.transform(context)
+
+ assert definition.specifier == 0
+
+ locations = list(index.lookup("test.func"))
+ assert len(locations) == 1
+ assert locations[0].identifier == "test.func"
+
+ def test_transform_nested_definitions(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ index = Index()
+
+ inner_def = Definition(identifier="inner")
+ outer_def = Definition(identifier="outer", child=inner_def)
+ root = ListNode([outer_def])
+ document = Document(root)
+
+ context = Context({Document: document, Source: source, Index: index})
+
+ transform = IndexTransform(plugin_settings)
+ transform.transform(context)
+
+ assert outer_def.specifier == 0
+ assert inner_def.specifier == 0
+
+ outer_locations = list(index.lookup("outer"))
+ inner_locations = list(index.lookup("inner"))
+ assert len(outer_locations) == 1
+ assert len(inner_locations) == 1
+
+ def test_transform_multiple_definitions_same_id(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ index = Index()
+
+ first_definition = Definition(identifier="same_id")
+ second_definition = Definition(identifier="same_id")
+ root = ListNode([first_definition, second_definition])
+ document = Document(root)
+
+ context = Context({Document: document, Source: source, Index: index})
+
+ transform = IndexTransform(plugin_settings)
+ transform.transform(context)
+
+ assert first_definition.specifier == 0
+ assert second_definition.specifier == 1
+
+ def test_transform_ignores_references(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ index = Index()
+
+ reference = Reference(identifier="some_ref")
+ root = ListNode([reference])
+ document = Document(root)
+
+ context = Context({Document: document, Source: source, Index: index})
+
+ transform = IndexTransform(plugin_settings)
+ transform.transform(context)
+
+ with pytest.raises(ReferenceError):
+ index.lookup("some_ref")
+
+
+class TestDefinitionReferenceInteraction:
+ def test_definition_child_is_reference(self) -> None:
+ ref = Reference(identifier="other")
+ definition = Definition(identifier="test", child=ref)
+
+ assert definition.child is ref
+ assert definition.children == (ref,)
+
+ def test_reference_child_is_definition(self) -> None:
+ definition = Definition(identifier="inner")
+ reference = Reference(identifier="test", child=definition)
+
+ assert reference.child is definition
+ assert reference.children == (definition,)
diff --git a/tests/test_resources.py b/tests/test_resources.py
new file mode 100644
index 0000000..b17c2e5
--- /dev/null
+++ b/tests/test_resources.py
@@ -0,0 +1,155 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+from io import StringIO
+from pathlib import Path, PurePath
+from typing import Dict, Set
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode, Document
+from docc.plugins.resources import (
+ ResourceBuilder,
+ ResourceNode,
+ ResourceSource,
+)
+from docc.settings import PluginSettings, Settings
+from docc.source import Source
+
+
+@pytest.fixture
+def plugin_settings() -> PluginSettings:
+ settings = Settings(Path("."), {"tool": {"docc": {}}})
+ return settings.for_plugin("docc.resources.build")
+
+
+class TestResourceSource:
+ def test_with_path_creates_source(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ assert source is not None
+ assert source.output_path == PurePath("static") / "docc"
+ assert source.extension == ".css"
+
+ def test_relative_path_is_none(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ assert source.relative_path is None
+
+ def test_output_path(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("output") / "style",
+ )
+ assert source.output_path == PurePath("output") / "style"
+
+
+class TestResourceNode:
+ def test_children_empty(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ node = ResourceNode(source.resource, source.extension)
+ assert node.children == ()
+
+ def test_extension(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ node = ResourceNode(source.resource, source.extension)
+ assert node.extension == ".css"
+
+ def test_replace_child_raises(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ node = ResourceNode(source.resource, source.extension)
+
+ with pytest.raises(TypeError):
+ node.replace_child(BlankNode(), BlankNode())
+
+ def test_output(self) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+ node = ResourceNode(source.resource, source.extension)
+ context = Context({})
+ destination = StringIO()
+
+ node.output(context, destination)
+
+ result = destination.getvalue()
+ assert len(result) > 0, "Output should not be empty"
+ assert "{" in result, "CSS output should contain style blocks"
+
+
+class TestResourceBuilder:
+ def test_build_processes_resource_sources(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = ResourceSource.with_path(
+ "docc.plugins.html",
+ PurePath("static") / "docc.css",
+ PurePath("static") / "docc",
+ )
+
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = ResourceBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert len(unprocessed) == 0
+ assert len(processed) == 1
+ assert source in processed
+ assert isinstance(processed[source].root, ResourceNode)
+
+ def test_build_ignores_non_resource_sources(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ class OtherSource(Source):
+ @property
+ def relative_path(self):
+ return PurePath("other.py")
+
+ @property
+ def output_path(self):
+ return PurePath("other.py")
+
+ source = OtherSource()
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = ResourceBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert source in unprocessed
+ assert len(processed) == 0
diff --git a/tests/test_search.py b/tests/test_search.py
new file mode 100644
index 0000000..dd6462c
--- /dev/null
+++ b/tests/test_search.py
@@ -0,0 +1,455 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import json
+from io import StringIO
+from pathlib import Path, PurePath
+from typing import Dict, Optional, Set
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode, Document
+from docc.plugins.references import Definition, Index, ReferenceError
+from docc.plugins.search import (
+ ByReference,
+ BySource,
+ Item,
+ Search,
+ Searchable,
+ SearchBuilder,
+ SearchContext,
+ SearchDiscover,
+ SearchNode,
+ SearchSource,
+ SearchTransform,
+ _SearchVisitor,
+)
+from docc.settings import PluginSettings, Settings
+from docc.source import Source
+
+
+@pytest.fixture
+def plugin_settings() -> PluginSettings:
+ settings = Settings(Path("."), {"tool": {"docc": {}}})
+ return settings.for_plugin("docc.search")
+
+
+class MockSource(Source):
+ _path: PurePath
+
+ def __init__(self, path: Optional[PurePath] = None) -> None:
+ self._path = path if path is not None else PurePath("mock.py")
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return self._path
+
+ @property
+ def output_path(self) -> PurePath:
+ return self._path
+
+
+class TestBySource:
+ def test_create(self) -> None:
+ source = MockSource()
+ location = BySource(source=source)
+ assert location.source is source
+
+ def test_frozen(self) -> None:
+ source = MockSource()
+ location = BySource(source=source)
+ with pytest.raises(AttributeError):
+ location.source = MockSource() # pyre-ignore[41]
+
+ def test_equality(self) -> None:
+ source = MockSource()
+ first_location = BySource(source=source)
+ second_location = BySource(source=source)
+ assert first_location == second_location
+
+
+class TestByReference:
+ def test_create(self) -> None:
+ location = ByReference(identifier="test.func", specifier=0)
+ assert location.identifier == "test.func"
+ assert location.specifier == 0
+
+ def test_create_without_specifier(self) -> None:
+ location = ByReference(identifier="test.func", specifier=None)
+ assert location.specifier is None
+
+ def test_frozen(self) -> None:
+ location = ByReference(identifier="test", specifier=0)
+ with pytest.raises(AttributeError):
+ location.identifier = "changed" # pyre-ignore[41]
+
+
+class TestItem:
+ def test_create_with_string_content(self) -> None:
+ source = MockSource()
+ location = BySource(source=source)
+ item = Item(location=location, content="test content")
+
+ assert item.location is location
+ assert item.content == "test content"
+
+ def test_create_with_dict_content(self) -> None:
+ source = MockSource()
+ location = BySource(source=source)
+ item = Item(
+ location=location, content={"type": "module", "name": ["test"]}
+ )
+
+ assert isinstance(item.content, dict)
+ assert item.content["type"] == "module"
+
+
+class TestSearch:
+ def test_init(self) -> None:
+ search = Search()
+ assert len(search._items) == 0
+
+ def test_add_string_content(self) -> None:
+ search = Search()
+ source = MockSource()
+ location = BySource(source=source)
+ item = Item(location=location, content="test content")
+
+ search.add(item)
+
+ # Note: Accessing _items directly as Search has no public query API
+ assert location in search._items
+ assert "text" in search._items[location]
+ assert "test content" in search._items[location]["text"]
+
+ def test_add_dict_content(self) -> None:
+ search = Search()
+ source = MockSource()
+ location = BySource(source=source)
+ item = Item(
+ location=location, content={"type": "module", "name": ["test"]}
+ )
+
+ search.add(item)
+
+ assert location in search._items
+ assert "type" in search._items[location]
+ assert "name" in search._items[location]
+
+ def test_add_multiple_items_same_location(self) -> None:
+ search = Search()
+ source = MockSource()
+ location = BySource(source=source)
+
+ search.add(Item(location=location, content="first"))
+ search.add(Item(location=location, content="second"))
+
+ assert "first" in search._items[location]["text"]
+ assert "second" in search._items[location]["text"]
+
+
+class TestSearchSource:
+ def test_relative_path_is_none(self) -> None:
+ source = SearchSource()
+ assert source.relative_path is None
+
+ def test_output_path(self) -> None:
+ source = SearchSource()
+ assert source.output_path == PurePath("search")
+
+
+class TestSearchNode:
+ def test_extension(self) -> None:
+ node = SearchNode()
+ assert node.extension == ".js"
+
+
+class TestSearchBuilder:
+ def test_build_processes_search_sources(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = SearchSource()
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = SearchBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert len(unprocessed) == 0
+ assert source in processed
+ assert isinstance(processed[source].root, SearchNode)
+
+ def test_build_ignores_non_search_sources(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ unprocessed: Set[Source] = {source}
+ processed: Dict[Source, Document] = {}
+
+ builder = SearchBuilder(plugin_settings)
+ builder.build(unprocessed, processed)
+
+ assert source in unprocessed
+ assert len(processed) == 0
+
+
+class TestSearchDiscover:
+ def test_discover_yields_search_source(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ discover = SearchDiscover(plugin_settings)
+ sources = list(discover.discover(frozenset()))
+
+ assert len(sources) == 1
+ assert isinstance(sources[0], SearchSource)
+
+
+class TestSearchContext:
+ def test_provides(self) -> None:
+ assert SearchContext.provides() == Search
+
+ def test_init(self, plugin_settings: PluginSettings) -> None:
+ ctx = SearchContext(plugin_settings)
+ assert isinstance(ctx.search, Search)
+
+ def test_provide(self, plugin_settings: PluginSettings) -> None:
+ ctx = SearchContext(plugin_settings)
+ provided = ctx.provide()
+ assert provided is ctx.search
+
+
+class TestSearchNodeOutput:
+ def test_output_by_source(self) -> None:
+ """
+ Test SearchNode.output() serializes search index to
+ JavaScript JSON with items indexed by BySource.
+ """
+ source = MockSource(PurePath("module.py"))
+ search = Search()
+ search.add(
+ Item(location=BySource(source=source), content="hello world")
+ )
+ index = Index()
+ context = Context({Search: search, Index: index})
+
+ node = SearchNode()
+ dest = StringIO()
+ node.output(context, dest)
+
+ output = dest.getvalue()
+ assert output.startswith("this.SEARCH_INDEX = ")
+ assert output.endswith("; Object.freeze(this.SEARCH_INDEX);")
+ # Parse the JSON portion
+ json_str = output[
+ len("this.SEARCH_INDEX = ") : -len(
+ "; Object.freeze(this.SEARCH_INDEX);"
+ )
+ ]
+ data = json.loads(json_str)
+ assert len(data) == 1
+ assert data[0]["source"]["path"] == "module.py"
+ assert "hello world" in data[0]["content"]["text"]
+
+ def test_output_by_reference_without_specifier(self) -> None:
+ """Test SearchNode.output() resolves ByReference location via Index."""
+ source = MockSource(PurePath("ref_module.py"))
+ search = Search()
+ location = ByReference(identifier="my.module.func", specifier=None)
+ search.add(Item(location=location, content="func docs"))
+
+ index = Index()
+ index.define(source, "my.module.func")
+
+ context = Context({Search: search, Index: index})
+ node = SearchNode()
+ dest = StringIO()
+ node.output(context, dest)
+
+ output = dest.getvalue()
+ json_str = output[
+ len("this.SEARCH_INDEX = ") : -len(
+ "; Object.freeze(this.SEARCH_INDEX);"
+ )
+ ]
+ data = json.loads(json_str)
+ assert len(data) == 1
+ assert data[0]["source"]["identifier"] == "my.module.func"
+ assert data[0]["source"]["path"] == "ref_module.py"
+
+ def test_output_by_reference_with_specifier(self) -> None:
+ """Test SearchNode.output() resolves ByReference with specifier."""
+ source = MockSource(PurePath("spec_module.py"))
+ search = Search()
+ location = ByReference(identifier="my.ident", specifier=0)
+ search.add(Item(location=location, content="spec docs"))
+
+ index = Index()
+ index.define(source, "my.ident") # specifier=0
+
+ context = Context({Search: search, Index: index})
+ node = SearchNode()
+ dest = StringIO()
+ node.output(context, dest)
+
+ output = dest.getvalue()
+ json_str = output[
+ len("this.SEARCH_INDEX = ") : -len(
+ "; Object.freeze(this.SEARCH_INDEX);"
+ )
+ ]
+ data = json.loads(json_str)
+ assert len(data) == 1
+ assert data[0]["source"]["specifier"] == 0
+ assert data[0]["source"]["path"] == "spec_module.py"
+
+ def test_output_by_reference_specifier_not_found_raises(self) -> None:
+ """
+ Test ByReference with specifier not found raises
+ ReferenceError.
+ """
+ source = MockSource(PurePath("err_module.py"))
+ search = Search()
+ # Use specifier=99 which won't match any definition
+ location = ByReference(identifier="my.missing", specifier=99)
+ search.add(Item(location=location, content="should fail"))
+
+ index = Index()
+ index.define(source, "my.missing") # specifier=0
+
+ context = Context({Search: search, Index: index})
+ node = SearchNode()
+ dest = StringIO()
+ with pytest.raises(ReferenceError):
+ node.output(context, dest)
+
+ def test_output_mixed_sources_and_references(self) -> None:
+ """
+ Test SearchNode.output() with both BySource and
+ ByReference items.
+ """
+ source = MockSource(PurePath("mixed.py"))
+ search = Search()
+ search.add(
+ Item(location=BySource(source=source), content="source item")
+ )
+ ref_location = ByReference(identifier="mixed.func", specifier=None)
+ search.add(Item(location=ref_location, content="ref item"))
+
+ index = Index()
+ index.define(source, "mixed.func")
+
+ context = Context({Search: search, Index: index})
+ node = SearchNode()
+ dest = StringIO()
+ node.output(context, dest)
+
+ output = dest.getvalue()
+ json_str = output[
+ len("this.SEARCH_INDEX = ") : -len(
+ "; Object.freeze(this.SEARCH_INDEX);"
+ )
+ ]
+ data = json.loads(json_str)
+ assert len(data) == 2
+
+
+class TestSearchTransform:
+ def test_transform_indexes_searchable_under_definition(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ """
+ Test that transform() indexes Searchable nodes wrapped in
+ Definitions as ByReference with the correct identifier.
+ """
+ source = MockSource(PurePath("test_transform.py"))
+ search = Search()
+
+ searchable = MockSearchable("indexed content")
+ definition = Definition(identifier="my.module.MyClass")
+ definition.specifier = 0
+ definition.child = searchable
+
+ document = Document(definition)
+ context = Context({Source: source, Search: search, Document: document})
+
+ transform = SearchTransform(plugin_settings)
+ transform.transform(context)
+
+ # The searchable should be indexed as ByReference
+ by_ref = ByReference(identifier="my.module.MyClass", specifier=0)
+ assert by_ref in search._items
+ assert "indexed content" in search._items[by_ref]["text"]
+
+
+class MockSearchable(BlankNode, Searchable):
+ def __init__(
+ self, content: str = "test content", search_children_val: bool = True
+ ) -> None:
+ self._content = content
+ self._search_children = search_children_val
+
+ def to_search(self) -> str:
+ return self._content
+
+ def search_children(self) -> bool:
+ return self._search_children
+
+
+class TestSearchVisitor:
+ def test_adds_searchable_content(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ search = Search()
+ document = Document(MockSearchable("searchable content"))
+ context = Context({Source: source, Search: search, Document: document})
+
+ visitor = _SearchVisitor(context)
+ document.root.visit(visitor)
+
+ by_source = BySource(source=source)
+ assert by_source in search._items
+ assert "searchable content" in search._items[by_source]["text"]
+
+ def test_respects_search_children(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockSource()
+ search = Search()
+ inner = MockSearchable("inner")
+
+ class ParentNode(MockSearchable):
+ def __init__(self):
+ super().__init__("parent", search_children_val=False)
+ self._children = [inner]
+
+ @property
+ def children(self):
+ return self._children
+
+ document = Document(ParentNode())
+ context = Context({Source: source, Search: search, Document: document})
+
+ visitor = _SearchVisitor(context)
+ document.root.visit(visitor)
+
+ # Note: Accessing _items is necessary as Search has no public query API
+ by_source = BySource(source=source)
+ assert "parent" in search._items[by_source]["text"]
+ # Verify children were NOT indexed when search_children=False
+ assert (
+ "inner" not in search._items[by_source]["text"]
+ ), "Children should be skipped when search_children() returns False"
diff --git a/tests/test_settings.py b/tests/test_settings.py
new file mode 100644
index 0000000..3c6e903
--- /dev/null
+++ b/tests/test_settings.py
@@ -0,0 +1,307 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import tempfile
+from pathlib import Path, PurePath
+from typing import Iterator
+
+import pytest
+
+from docc.settings import (
+ FILE_NAME,
+ MAX_DEPTH,
+ Output,
+ PluginSettings,
+ Settings,
+ SettingsError,
+)
+
+
+@pytest.fixture
+def temp_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as td:
+ yield Path(td)
+
+
+class TestOutput:
+ def test_create_with_path(self) -> None:
+ output = Output(path=Path("/output/docs"))
+ assert output.path == Path("/output/docs")
+
+ def test_create_with_none(self) -> None:
+ output = Output(path=None)
+ assert output.path is None
+
+
+class TestPluginSettings:
+ def test_init(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {"key": "value"})
+
+ assert plugin_settings["key"] == "value"
+
+ def test_len(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {"a": 1, "b": 2, "c": 3})
+
+ assert len(plugin_settings) == 3
+
+ def test_iter(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {"a": 1, "b": 2})
+
+ keys = list(plugin_settings)
+ assert "a" in keys
+ assert "b" in keys
+
+ def test_getitem(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {"test_key": "test_value"})
+
+ assert plugin_settings["test_key"] == "test_value"
+
+ def test_getitem_missing_raises(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {})
+
+ with pytest.raises(KeyError):
+ plugin_settings["missing"]
+
+ def test_get_with_default(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {})
+
+ assert plugin_settings.get("missing", "default") == "default"
+
+ def test_resolve_path(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {})
+
+ resolved = plugin_settings.resolve_path(PurePath("subdir"))
+ assert resolved.is_absolute()
+ assert str(temp_dir) in str(resolved)
+
+ def test_unresolve_path(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = PluginSettings(settings, {})
+
+ absolute = temp_dir / "subdir" / "file.py"
+ relative = plugin_settings.unresolve_path(absolute)
+
+ assert not relative.is_absolute()
+
+
+class TestSettings:
+ def test_init_with_empty_tool_docc(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ assert isinstance(settings.context, list)
+ assert settings.output.path is None
+
+ def test_init_without_tool_key(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {})
+ assert isinstance(settings.context, list)
+ assert settings.output.path is None
+
+ def test_init_with_invalid_tool_type(self, temp_dir: Path) -> None:
+ with pytest.raises(TypeError, match="must be a dict"):
+ Settings(temp_dir, {"tool": "not_a_dict"})
+
+ def test_output_path_from_settings(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"output": {"path": "docs"}}}},
+ )
+ assert settings.output.path == Path("docs")
+
+ def test_output_path_none_when_not_specified(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ assert settings.output.path is None
+
+ def test_for_plugin(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {"plugins": {"test.plugin": {"option": "value"}}}
+ }
+ },
+ )
+ plugin_settings = settings.for_plugin("test.plugin")
+
+ assert plugin_settings["option"] == "value"
+
+ def test_for_plugin_missing_returns_empty(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = settings.for_plugin("nonexistent.plugin")
+
+ assert len(plugin_settings) == 0
+
+ def test_context_default(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ context = settings.context
+
+ assert isinstance(context, list)
+ assert "docc.references.context" in context
+ assert "docc.search.context" in context
+ assert "docc.html.context" in context
+
+ def test_context_custom(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"context": ["custom.context"]}}},
+ )
+ context = settings.context
+
+ assert context == ["custom.context"]
+
+ def test_discovery_default(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ discovery = settings.discovery
+
+ assert isinstance(discovery, list)
+ assert "docc.python.discover" in discovery
+ assert "docc.html.discover" in discovery
+
+ def test_discovery_custom(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"discovery": ["custom.discover"]}}},
+ )
+ discovery = settings.discovery
+
+ assert discovery == ["custom.discover"]
+
+ def test_build_default(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ build = settings.build
+
+ assert isinstance(build, list)
+ assert "docc.python.build" in build
+
+ def test_build_custom(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"build": ["custom.build"]}}},
+ )
+ build = settings.build
+
+ assert build == ["custom.build"]
+
+ def test_transform_default(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ transform = settings.transform
+
+ assert isinstance(transform, list)
+ assert "docc.python.transform" in transform
+ assert "docc.html.transform" in transform
+
+ def test_transform_custom(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"transform": ["custom.transform"]}}},
+ )
+ transform = settings.transform
+
+ assert transform == ["custom.transform"]
+
+ def test_resolve_path(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ resolved = settings.resolve_path(PurePath("subdir"))
+
+ assert resolved.is_absolute()
+ assert str(temp_dir) in str(resolved)
+
+ def test_resolve_path_escapes_root_raises(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+
+ with pytest.raises(ValueError):
+ settings.resolve_path(PurePath("../escape"))
+
+ def test_unresolve_path(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ absolute = temp_dir / "subdir" / "file.py"
+ relative = settings.unresolve_path(absolute)
+
+ assert not relative.is_absolute()
+ assert relative == PurePath("subdir") / "file.py"
+
+
+class TestSettingsFromFile:
+ def test_from_file_finds_pyproject_toml(self, temp_dir: Path) -> None:
+ pyproject = temp_dir / "pyproject.toml"
+ pyproject.write_text('[tool.docc]\noutput = { path = "docs" }\n')
+
+ settings = Settings.from_file(temp_dir)
+
+ assert settings.output.path == Path("docs")
+
+ def test_from_file_searches_parent_directories(
+ self, temp_dir: Path
+ ) -> None:
+ pyproject = temp_dir / "pyproject.toml"
+ pyproject.write_text('[tool.docc]\noutput = { path = "docs" }\n')
+
+ subdir = temp_dir / "src" / "submodule"
+ subdir.mkdir(parents=True)
+
+ settings = Settings.from_file(subdir)
+
+ assert settings.output.path == Path("docs")
+
+ def test_from_file_respects_max_depth(self, temp_dir: Path) -> None:
+ deep_path = temp_dir
+ for i in range(MAX_DEPTH + 5):
+ deep_path = deep_path / f"level{i}"
+ deep_path.mkdir(parents=True)
+
+ with pytest.raises(SettingsError, match="could not find"):
+ Settings.from_file(deep_path)
+
+ def test_from_file_not_found_raises(self, temp_dir: Path) -> None:
+ with pytest.raises(SettingsError, match="could not find"):
+ Settings.from_file(temp_dir)
+
+ def test_from_file_with_complete_config(self, temp_dir: Path) -> None:
+ config = """
+[tool.docc]
+context = ["custom.context"]
+discovery = ["custom.discover"]
+build = ["custom.build"]
+transform = ["custom.transform"]
+
+[tool.docc.output]
+path = "output"
+
+[tool.docc.plugins."custom.plugin"]
+option = "value"
+"""
+ pyproject = temp_dir / "pyproject.toml"
+ pyproject.write_text(config)
+
+ settings = Settings.from_file(temp_dir)
+
+ assert settings.context == ["custom.context"]
+ assert settings.discovery == ["custom.discover"]
+ assert settings.build == ["custom.build"]
+ assert settings.transform == ["custom.transform"]
+ assert settings.output.path == Path("output")
+
+
+class TestSettingsConstants:
+ def test_max_depth(self) -> None:
+ assert MAX_DEPTH == 10
+
+ def test_file_name(self) -> None:
+ assert FILE_NAME == "pyproject.toml"
diff --git a/tests/test_source.py b/tests/test_source.py
new file mode 100644
index 0000000..4579ed0
--- /dev/null
+++ b/tests/test_source.py
@@ -0,0 +1,222 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import tempfile
+from io import StringIO
+from pathlib import Path, PurePath
+from typing import Optional, TextIO
+from unittest.mock import patch
+
+import pytest
+
+from docc.source import Source, TextSource
+
+
+class ConcreteSource(Source):
+ _output: PurePath
+
+ def __init__(
+ self,
+ relative: Optional[PurePath] = None,
+ output: Optional[PurePath] = None,
+ ) -> None:
+ self._relative = relative
+ self._output = output or PurePath("output.html")
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return self._relative
+
+ @property
+ def output_path(self) -> PurePath:
+ return self._output
+
+
+class ConcreteTextSource(TextSource):
+ _relative: PurePath
+ _output: PurePath
+
+ def __init__(
+ self,
+ content: str,
+ relative: Optional[PurePath] = None,
+ output: Optional[PurePath] = None,
+ ) -> None:
+ self._content = content
+ self._relative = relative or PurePath("test.py")
+ self._output = output or self._relative
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return self._relative
+
+ @property
+ def output_path(self) -> PurePath:
+ return self._output
+
+ def open(self) -> TextIO:
+ return StringIO(self._content)
+
+
+class TestSource:
+ def test_repr_with_relative_path(self) -> None:
+ source = ConcreteSource(relative=PurePath("src/module.py"))
+ result = repr(source)
+
+ assert "src/module.py" in result
+ assert "ConcreteSource" in result
+
+ def test_repr_without_relative_path(self) -> None:
+ source = ConcreteSource(relative=None)
+ result = repr(source)
+
+ assert "ConcreteSource" in result
+
+ def test_output_path(self) -> None:
+ source = ConcreteSource(output=PurePath("docs/output.html"))
+ assert source.output_path == PurePath("docs/output.html")
+
+
+class TestTextSource:
+ def test_open_returns_text_io(self) -> None:
+ source = ConcreteTextSource("content")
+ with source.open() as f:
+ assert f.read() == "content"
+
+ def test_line_returns_correct_line(self) -> None:
+ content = "line1\nline2\nline3"
+ source = ConcreteTextSource(content)
+
+ assert source.line(1) == "line1"
+ assert source.line(2) == "line2"
+ assert source.line(3) == "line3"
+
+ def test_line_out_of_range_raises(self) -> None:
+ content = "line1\nline2"
+ source = ConcreteTextSource(content)
+
+ with pytest.raises(IndexError, match="line 10 out of range"):
+ source.line(10)
+
+ def test_line_single_line(self) -> None:
+ content = "single line"
+ source = ConcreteTextSource(content)
+
+ assert source.line(1) == "single line"
+
+ def test_line_empty_content(self) -> None:
+ content = ""
+ source = ConcreteTextSource(content)
+
+ assert source.line(1) == ""
+
+ def test_line_with_empty_lines(self) -> None:
+ content = "first\n\nthird"
+ source = ConcreteTextSource(content)
+
+ assert source.line(1) == "first"
+ assert source.line(2) == ""
+ assert source.line(3) == "third"
+
+
+class TestTextSourceBoundary:
+ def test_line_zero_returns_last_line(self) -> None:
+ """
+ line(0) computes lines[0 - 1] = lines[-1], which silently
+ returns the last line due to Python negative indexing.
+ """
+ content = "first\nsecond\nthird"
+ source = ConcreteTextSource(content)
+ # line(0) accesses lines[-1] which is "third"
+ assert source.line(0) == "third"
+
+ def test_line_negative_one_returns_second_to_last(self) -> None:
+ """
+ line(-1) computes lines[-1 - 1] = lines[-2], which silently
+ returns the second-to-last line due to Python negative indexing.
+ """
+ content = "first\nsecond\nthird"
+ source = ConcreteTextSource(content)
+ # line(-1) accesses lines[-2] which is "second"
+ assert source.line(-1) == "second"
+
+
+class TestTextSourceWithFiles:
+ def test_line_from_real_file(self) -> None:
+ with tempfile.NamedTemporaryFile(
+ mode="w", suffix=".py", delete=False
+ ) as f:
+ f.write("# Line 1\n# Line 2\n# Line 3\n")
+ f.flush()
+ path = Path(f.name)
+
+ class FileTextSource(TextSource):
+ def __init__(self, file_path: Path):
+ self._path = file_path
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return PurePath(self._path.name)
+
+ @property
+ def output_path(self) -> PurePath:
+ return PurePath(self._path.name)
+
+ def open(self) -> TextIO:
+ return open(self._path, "r")
+
+ try:
+ source = FileTextSource(path)
+ assert source.line(1) == "# Line 1"
+ assert source.line(2) == "# Line 2"
+ finally:
+ path.unlink()
+
+
+class TestTextSourceCache:
+ def test_open_called_once_for_multiple_line_calls(self) -> None:
+ """Calling line() multiple times should only open the file once."""
+ content = "line1\nline2\nline3"
+ source = ConcreteTextSource(content)
+
+ with patch.object(source, "open", wraps=source.open) as mock_open:
+ source.line(1)
+ source.line(2)
+ source.line(3)
+
+ mock_open.assert_called_once()
+
+ def test_lines_cache_matches_content_split(self) -> None:
+ """After calling line(), _lines_cache matches content split."""
+ content = "alpha\nbeta\ngamma"
+ source = ConcreteTextSource(content)
+
+ source.line(1)
+
+ assert source._lines_cache == ["alpha", "beta", "gamma"]
+
+ def test_lines_cache_empty_content(self) -> None:
+ """Cache for empty content should be a list with one empty string."""
+ source = ConcreteTextSource("")
+
+ source.line(1)
+
+ assert source._lines_cache == [""]
+
+ def test_lines_cache_is_none_before_first_call(self) -> None:
+ """Before any line() call, the cache should be None."""
+ source = ConcreteTextSource("some content")
+
+ assert source._lines_cache is None
diff --git a/tests/test_transform.py b/tests/test_transform.py
new file mode 100644
index 0000000..12d0c2d
--- /dev/null
+++ b/tests/test_transform.py
@@ -0,0 +1,101 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+import tempfile
+from pathlib import Path
+from typing import Iterator
+
+import pytest
+
+from docc.context import Context
+from docc.settings import PluginSettings, Settings
+from docc.transform import Transform, load
+
+
+@pytest.fixture
+def temp_dir() -> Iterator[Path]:
+ with tempfile.TemporaryDirectory() as td:
+ yield Path(td)
+
+
+class ConcreteTransform(Transform):
+ def __init__(self, config: PluginSettings) -> None:
+ self.config = config
+
+ def transform(self, context: Context) -> None:
+ pass
+
+
+class TestTransform:
+ def test_concrete_transform_init(self, temp_dir: Path) -> None:
+ settings = Settings(temp_dir, {"tool": {"docc": {}}})
+ plugin_settings = settings.for_plugin("test")
+
+ transform = ConcreteTransform(plugin_settings)
+ assert transform.config is plugin_settings
+
+
+class TestTransformLoad:
+ def test_load_empty_transform_list(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"transform": []}}},
+ )
+
+ result = load(settings)
+ assert result == []
+
+ def test_load_single_transform(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"transform": ["docc.python.transform"]}}},
+ )
+
+ result = load(settings)
+ assert len(result) == 1
+ assert result[0][0] == "docc.python.transform"
+
+ def test_load_multiple_transforms(self, temp_dir: Path) -> None:
+ settings = Settings(
+ temp_dir,
+ {
+ "tool": {
+ "docc": {
+ "transform": [
+ "docc.python.transform",
+ "docc.mistletoe.transform",
+ ]
+ }
+ }
+ },
+ )
+
+ result = load(settings)
+ assert len(result) == 2
+
+ def test_load_preserves_order(self, temp_dir: Path) -> None:
+ transforms = [
+ "docc.python.transform",
+ "docc.mistletoe.transform",
+ "docc.html.transform",
+ ]
+ settings = Settings(
+ temp_dir,
+ {"tool": {"docc": {"transform": transforms}}},
+ )
+
+ result = load(settings)
+ for i, (name, _) in enumerate(result):
+ assert name == transforms[i]
diff --git a/tests/test_verbatim.py b/tests/test_verbatim.py
new file mode 100644
index 0000000..11bd038
--- /dev/null
+++ b/tests/test_verbatim.py
@@ -0,0 +1,700 @@
+# Copyright (C) 2025 Ethereum Foundation
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see .
+
+from io import StringIO
+from pathlib import Path, PurePath
+from typing import Any, List, Optional, Sequence, TextIO
+from unittest.mock import patch
+
+import pytest
+
+from docc.context import Context
+from docc.document import BlankNode, Document, ListNode
+from docc.plugins.html import HTMLTag, TextNode
+from docc.plugins.verbatim import (
+ Fragment,
+ Highlight,
+ Line,
+ Pos,
+ Text,
+ Transcribe,
+ Transcribed,
+ Verbatim,
+ VerbatimVisitor,
+ _BoundsVisitor,
+)
+from docc.settings import PluginSettings, Settings
+from docc.source import TextSource
+
+
+class MockTextSource(TextSource):
+ _path: PurePath
+
+ def __init__(self, content: str, path: Optional[PurePath] = None) -> None:
+ self._content = content
+ self._path = path if path is not None else PurePath("test.py")
+
+ @property
+ def relative_path(self) -> Optional[PurePath]:
+ return self._path
+
+ @property
+ def output_path(self) -> PurePath:
+ return self._path
+
+ def open(self) -> TextIO:
+ return StringIO(self._content)
+
+
+@pytest.fixture
+def plugin_settings() -> PluginSettings:
+ settings = Settings(Path("."), {"tool": {"docc": {}}})
+ return settings.for_plugin("docc.verbatim.transform")
+
+
+class TestPos:
+ def test_create(self) -> None:
+ pos = Pos(line=1, column=5)
+ assert pos.line == 1
+ assert pos.column == 5
+
+ def test_frozen(self) -> None:
+ pos = Pos(line=1, column=5)
+ with pytest.raises(AttributeError):
+ pos.line = 2 # pyre-ignore[41]
+
+ def test_repr(self) -> None:
+ pos = Pos(line=10, column=20)
+ assert repr(pos) == "10:20"
+
+ def test_ordering(self) -> None:
+ first_pos = Pos(line=1, column=0)
+ second_pos = Pos(line=1, column=5)
+ third_pos = Pos(line=2, column=0)
+
+ assert first_pos < second_pos < third_pos
+
+ def test_equality(self) -> None:
+ first_pos = Pos(line=1, column=5)
+ second_pos = Pos(line=1, column=5)
+ assert first_pos == second_pos
+
+
+class TestText:
+ def test_create(self) -> None:
+ text = Text(text="hello")
+ assert text.text == "hello"
+
+ def test_children_empty(self) -> None:
+ text = Text(text="hello")
+ assert text.children == ()
+
+ def test_replace_child_raises(self) -> None:
+ text = Text(text="hello")
+ with pytest.raises(TypeError):
+ text.replace_child(BlankNode(), BlankNode())
+
+
+class TestLine:
+ def test_create(self) -> None:
+ line = Line(number=1)
+ assert line.number == 1
+ assert list(line.children) == []
+
+ def test_children_with_content(self) -> None:
+ line = Line(number=1, _children=[Text("hello")])
+ children = list(line.children)
+ assert len(children) == 1
+ assert isinstance(children[0], Text)
+
+ def test_replace_child(self) -> None:
+ old = Text("old")
+ new = Text("new")
+ line = Line(number=1, _children=[old])
+
+ line.replace_child(old, new)
+
+ children = list(line.children)
+ assert new in children
+ assert old not in children
+
+ def test_repr(self) -> None:
+ line = Line(number=5)
+ assert "Line" in repr(line)
+ assert "5" in repr(line)
+
+
+class TestHighlight:
+ def test_create(self) -> None:
+ highlight = Highlight(highlights=["keyword"])
+ assert highlight.highlights == ["keyword"]
+
+ def test_children_empty(self) -> None:
+ highlight = Highlight()
+ assert list(highlight.children) == []
+
+ def test_children_with_content(self) -> None:
+ text = Text("highlighted")
+ highlight = Highlight(_children=[text])
+ assert text in highlight.children
+
+ def test_replace_child(self) -> None:
+ old = Text("old")
+ new = Text("new")
+ highlight = Highlight(_children=[old])
+
+ highlight.replace_child(old, new)
+
+ assert new in highlight.children
+ assert old not in highlight.children
+
+ def test_repr(self) -> None:
+ highlight = Highlight(highlights=["keyword", "function"])
+ result = repr(highlight)
+ assert "Highlight" in result
+ assert "keyword" in result
+
+
+class TestTranscribed:
+ def test_create(self) -> None:
+ transcribed = Transcribed()
+ assert list(transcribed.children) == []
+
+ def test_children(self) -> None:
+ line = Line(number=1)
+ transcribed = Transcribed(_children=[line])
+ assert line in transcribed.children
+
+ def test_replace_child(self) -> None:
+ old = Line(number=1)
+ new = Line(number=2)
+ transcribed = Transcribed(_children=[old])
+
+ transcribed.replace_child(old, new)
+
+ assert new in transcribed.children
+ assert old not in transcribed.children
+
+ def test_repr(self) -> None:
+ transcribed = Transcribed()
+ assert repr(transcribed) == "Transcribed(...)"
+
+
+class TestFragment:
+ def test_create(self) -> None:
+ start = Pos(line=1, column=0)
+ end = Pos(line=1, column=10)
+ fragment = Fragment(start, end)
+
+ assert fragment.start == start
+ assert fragment.end == end
+ assert fragment.highlights == []
+
+ def test_create_with_highlights(self) -> None:
+ start = Pos(line=1, column=0)
+ end = Pos(line=1, column=10)
+ fragment = Fragment(start, end, highlights=["keyword"])
+
+ assert fragment.highlights == ["keyword"]
+
+ def test_repr(self) -> None:
+ start = Pos(line=1, column=0)
+ end = Pos(line=1, column=10)
+ fragment = Fragment(start, end, highlights=["test"])
+
+ result = repr(fragment)
+ assert "Fragment" in result
+ assert "1:0" in result
+ assert "1:10" in result
+
+
+class TestVerbatim:
+ def test_create(self) -> None:
+ source = MockTextSource("content")
+ verbatim = Verbatim(source)
+
+ assert verbatim.source is source
+ assert list(verbatim.children) == []
+
+ def test_repr(self) -> None:
+ source = MockTextSource("content")
+ verbatim = Verbatim(source)
+
+ result = repr(verbatim)
+ assert "Verbatim" in result
+
+
+class TestVerbatimNode:
+ def test_append(self) -> None:
+ source = MockTextSource("content")
+ verbatim = Verbatim(source)
+ fragment = Fragment(Pos(1, 0), Pos(1, 5))
+
+ verbatim.append(fragment)
+
+ assert fragment in verbatim.children
+
+ def test_append_nested_verbatim_raises(self) -> None:
+ source = MockTextSource("content")
+ outer = Verbatim(source)
+ inner = Verbatim(source)
+
+ with pytest.raises(ValueError, match="cannot nest"):
+ outer.append(inner)
+
+ def test_replace_child(self) -> None:
+ source = MockTextSource("content")
+ verbatim = Verbatim(source)
+ old = Fragment(Pos(1, 0), Pos(1, 5))
+ new = Fragment(Pos(1, 0), Pos(1, 10))
+ verbatim.append(old)
+
+ verbatim.replace_child(old, new)
+
+ assert new in verbatim.children
+ assert old not in verbatim.children
+
+
+class TestBoundsVisitor:
+ def test_finds_start_end(self) -> None:
+ first_fragment = Fragment(Pos(1, 5), Pos(1, 10))
+ second_fragment = Fragment(Pos(2, 0), Pos(2, 15))
+
+ source = MockTextSource("line1\nline2")
+ verbatim = Verbatim(source)
+ verbatim.append(first_fragment)
+ verbatim.append(second_fragment)
+
+ visitor = _BoundsVisitor()
+ verbatim.visit(visitor)
+
+ assert visitor.start == Pos(1, 5)
+ assert visitor.end == Pos(2, 15)
+
+ def test_no_fragments(self) -> None:
+ visitor = _BoundsVisitor()
+ blank = BlankNode()
+ blank.visit(visitor)
+
+ assert visitor.start is None
+ assert visitor.end is None
+
+
+class ConcreteVerbatimVisitor(VerbatimVisitor):
+ lines: List[int]
+ texts: List[str]
+ highlights: List[Any]
+
+ def __init__(self) -> None:
+ super().__init__()
+ self.lines = []
+ self.texts = []
+ self.highlights = []
+
+ def line(self, source: TextSource, line: int) -> None:
+ self.lines.append(line)
+
+ def text(self, text: str) -> None:
+ self.texts.append(text)
+
+ def begin_highlight(self, highlights: Sequence[str]) -> None:
+ self.highlights.append(("begin", list(highlights)))
+
+ def end_highlight(self) -> None:
+ self.highlights.append(("end", None))
+
+
+class TestVerbatimVisitor:
+ def test_visit_verbatim_with_fragment(self) -> None:
+ source = MockTextSource("hello world")
+ verbatim = Verbatim(source)
+ fragment = Fragment(Pos(1, 0), Pos(1, 5), highlights=["keyword"])
+ verbatim.append(fragment)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ assert 1 in visitor.lines
+ assert ("begin", ["keyword"]) in visitor.highlights
+ assert ("end", None) in visitor.highlights
+
+ def test_visit_verbatim_multi_line_fragment(self) -> None:
+ source = MockTextSource("line one\nline two\nline three")
+ verbatim = Verbatim(source)
+ fragment = Fragment(Pos(1, 0), Pos(3, 10))
+ verbatim.append(fragment)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ assert 1 in visitor.lines
+ assert 2 in visitor.lines
+ assert 3 in visitor.lines
+
+ joined = "".join(visitor.texts)
+ assert "line one" in joined
+ assert "line two" in joined
+ assert "line three" in joined
+
+ def test_visit_verbatim_multiple_fragments(self) -> None:
+ source = MockTextSource("alpha\nbeta\ngamma\ndelta")
+ verbatim = Verbatim(source)
+ first_fragment = Fragment(Pos(1, 0), Pos(2, 4))
+ second_fragment = Fragment(Pos(3, 0), Pos(4, 5))
+ verbatim.append(first_fragment)
+ verbatim.append(second_fragment)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ joined = "".join(visitor.texts)
+ assert "alpha" in joined
+ assert "beta" in joined
+ assert "gamma" in joined
+ assert "delta" in joined
+
+ def test_nested_verbatim_raises(self) -> None:
+ # This test verifies the visitor's safety check against nested
+ # Verbatim. While Verbatim.append() prevents nesting at construction
+ # time, the visitor has an additional runtime check as defense-in-
+ # depth. We simulate already being inside a Verbatim by setting _depth.
+ source = MockTextSource("content")
+ outer = Verbatim(source)
+
+ visitor = ConcreteVerbatimVisitor()
+ visitor._depth = 1 # Simulate already inside a Verbatim
+
+ with pytest.raises(Exception, match="cannot be nested"):
+ visitor._enter_verbatim(outer)
+
+ def test_fragment_outside_verbatim_raises(self) -> None:
+ fragment = Fragment(Pos(1, 0), Pos(1, 5))
+ visitor = ConcreteVerbatimVisitor()
+
+ with pytest.raises(Exception, match="must appear inside"):
+ visitor._enter_fragment(fragment)
+
+
+class TestTranscribe:
+ def test_transform_simple(self, plugin_settings: PluginSettings) -> None:
+ source = MockTextSource("hello world")
+ verbatim = Verbatim(source)
+ fragment = Fragment(Pos(1, 0), Pos(1, 5))
+ verbatim.append(fragment)
+
+ document = Document(verbatim)
+ context = Context({Document: document})
+
+ transform = Transcribe(plugin_settings)
+ transform.transform(context)
+
+ assert isinstance(document.root, Transcribed)
+
+ def test_transcribe_multi_line(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ source = MockTextSource("line one\nline two\nline three")
+ verbatim = Verbatim(source)
+ fragment = Fragment(Pos(1, 0), Pos(3, 10))
+ verbatim.append(fragment)
+
+ document = Document(verbatim)
+ context = Context({Document: document})
+
+ transform = Transcribe(plugin_settings)
+ transform.transform(context)
+
+ assert isinstance(document.root, Transcribed)
+ lines = [
+ child
+ for child in document.root.children
+ if isinstance(child, Line)
+ ]
+ assert len(lines) == 3
+ assert lines[0].number == 1
+ assert lines[1].number == 2
+ assert lines[2].number == 3
+
+ def _find_text(node: object) -> List[Text]:
+ found: List[Text] = []
+ if isinstance(node, Text):
+ found.append(node)
+ if hasattr(node, "children"):
+ for child in node.children: # type: ignore[union-attr]
+ found.extend(_find_text(child))
+ return found
+
+ for line_node in lines:
+ text_nodes = _find_text(line_node)
+ assert len(text_nodes) > 0
+
+ def test_transform_no_verbatim(
+ self, plugin_settings: PluginSettings
+ ) -> None:
+ blank = BlankNode()
+ document = Document(blank)
+ context = Context({Document: document})
+
+ transform = Transcribe(plugin_settings)
+ transform.transform(context)
+
+ assert document.root is blank
+
+
+class TestVerbatimHtmlRendering:
+ """Tests for src/docc/plugins/verbatim/html.py render functions."""
+
+ def test_render_transcribed(self) -> None:
+ """render_transcribed produces an HTML table with class 'verbatim'."""
+ from docc.plugins.verbatim.html import render_transcribed
+
+ context = Context({})
+ parent = HTMLTag("div")
+ node = Transcribed()
+
+ result = render_transcribed(context, parent, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "table"
+ assert result.attributes.get("class") == "verbatim"
+ # The table should be appended to parent
+ assert result in parent.children
+
+ def test_render_line_inside_table(self) -> None:
+ """
+ render_line produces a tr with th (line number) and td>pre
+ (code) when parent is a table.
+ """
+ from docc.plugins.verbatim.html import render_line
+
+ context = Context({})
+ parent = HTMLTag("table")
+ node = Line(number=42)
+
+ result = render_line(context, parent, node)
+
+ # result should be the inside the |
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "pre"
+
+ # Parent (table) should have a | child
+ assert len(list(parent.children)) == 1
+ tbody = list(parent.children)[0]
+ assert isinstance(tbody, HTMLTag)
+ assert tbody.tag_name == "tbody"
+
+ # tbody should contain a
+ tr = list(tbody.children)[0]
+ assert isinstance(tr, HTMLTag)
+ assert tr.tag_name == "tr"
+
+ #
should contain | and |
+ tr_children = list(tr.children)
+ assert len(tr_children) == 2
+ th, td = tr_children
+ assert isinstance(th, HTMLTag)
+ assert th.tag_name == "th"
+ assert isinstance(td, HTMLTag)
+ assert td.tag_name == "td"
+
+ # | should contain TextNode with line number
+ th_children = list(th.children)
+ assert len(th_children) == 1
+ th_child = th_children[0]
+ assert isinstance(th_child, TextNode)
+ assert th_child._value == "42"
+
+ def test_render_line_outside_table(self) -> None:
+ """render_line appends |
directly to non-table parents."""
+ from docc.plugins.verbatim.html import render_line
+
+ context = Context({})
+ parent = HTMLTag("div")
+ node = Line(number=1)
+
+ result = render_line(context, parent, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "pre"
+ # Parent (div) should have
directly (no
)
+ assert len(list(parent.children)) == 1
+ tr = list(parent.children)[0]
+ assert isinstance(tr, HTMLTag)
+ assert tr.tag_name == "tr"
+
+ def test_render_text(self) -> None:
+ """render_text appends a TextNode with correct content."""
+ from docc.plugins.verbatim.html import render_text
+
+ context = Context({})
+ parent = HTMLTag("pre")
+ node = Text(text="hello world")
+
+ result = render_text(context, parent, node)
+
+ assert result is None
+ children = list(parent.children)
+ assert len(children) == 1
+ child = children[0]
+ assert isinstance(child, TextNode)
+ assert child._value == "hello world"
+
+ def test_render_highlight(self) -> None:
+ """render_highlight produces with hi-{name} hi classes."""
+ from docc.plugins.verbatim.html import render_highlight
+
+ context = Context({})
+ parent = HTMLTag("pre")
+ node = Highlight(highlights=["keyword", "function"])
+
+ result = render_highlight(context, parent, node)
+
+ assert isinstance(result, HTMLTag)
+ assert result.tag_name == "span"
+ classes = result.attributes.get("class") or ""
+ assert "hi-keyword" in classes
+ assert "hi-function" in classes
+ assert "hi" in classes.split()
+ # The span should be appended to parent
+ assert result in parent.children
+
+
+class TestBoundsCacheBehavior:
+ """Caching _BoundsVisitor results must not change output."""
+
+ def test_cached_bounds_produce_same_text_output(self) -> None:
+ """Caching does not change text output for wrapped Fragments."""
+ source = MockTextSource("alpha\nbeta\ngamma")
+ verbatim = Verbatim(source)
+
+ wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 4))])
+ verbatim.append(wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ joined = "".join(visitor.texts)
+ assert "alpha" in joined
+ assert "beta" in joined
+
+ def test_multiple_wrappers_produce_correct_output(self) -> None:
+ """Multiple wrappers with Fragments produce correct text."""
+ source = MockTextSource("aaa\nbbb\nccc\nddd")
+ verbatim = Verbatim(source)
+
+ first_wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 3))])
+ second_wrapper = ListNode([Fragment(Pos(3, 0), Pos(4, 3))])
+ verbatim.append(first_wrapper)
+ verbatim.append(second_wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ joined = "".join(visitor.texts)
+ assert "aaa" in joined
+ assert "bbb" in joined
+ assert "ccc" in joined
+ assert "ddd" in joined
+
+
+class TestBoundsCacheCallCount:
+ """The cache must eliminate redundant _BoundsVisitor creation."""
+
+ def test_single_wrapper_visited_once(self) -> None:
+ """Enter and exit of one node creates only one _BoundsVisitor."""
+ source = MockTextSource("hello\nworld")
+ verbatim = Verbatim(source)
+
+ wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 5))])
+ verbatim.append(wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+
+ with patch(
+ "docc.plugins.verbatim._BoundsVisitor",
+ wraps=_BoundsVisitor,
+ ) as mock_cls:
+ verbatim.visit(visitor)
+ # One wrapper node -> one _BoundsVisitor creation (not two).
+ assert mock_cls.call_count == 1
+
+ def test_two_wrappers_visited_once_each(self) -> None:
+ """Two distinct nodes each create exactly one _BoundsVisitor."""
+ source = MockTextSource("aaa\nbbb\nccc\nddd")
+ verbatim = Verbatim(source)
+
+ first_wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 3))])
+ second_wrapper = ListNode([Fragment(Pos(3, 0), Pos(4, 3))])
+ verbatim.append(first_wrapper)
+ verbatim.append(second_wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+
+ with patch(
+ "docc.plugins.verbatim._BoundsVisitor",
+ wraps=_BoundsVisitor,
+ ) as mock_cls:
+ verbatim.visit(visitor)
+ # Two unique wrappers -> exactly two creations.
+ assert mock_cls.call_count == 2
+
+
+class TestBoundsCacheKeying:
+ """The _bounds_cache dictionary must be keyed by id(node)."""
+
+ def test_cache_contains_wrapper_ids(self) -> None:
+ """Cache has entries keyed by id(node) for each wrapper node."""
+ source = MockTextSource("hello\nworld")
+ verbatim = Verbatim(source)
+
+ wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 5))])
+ verbatim.append(wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ assert id(wrapper) in visitor._bounds_cache
+
+ def test_cache_values_are_start_end_tuples(self) -> None:
+ """Cached values must be (start, end) tuples of Optional[Pos]."""
+ source = MockTextSource("hello\nworld")
+ verbatim = Verbatim(source)
+
+ wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 5))])
+ verbatim.append(wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ start, end = visitor._bounds_cache[id(wrapper)]
+ assert start == Pos(1, 0)
+ assert end == Pos(2, 5)
+
+ def test_cache_has_entry_per_wrapper(self) -> None:
+ """Each non-Fragment/non-Verbatim node gets its own cache entry."""
+ source = MockTextSource("aaa\nbbb\nccc\nddd")
+ verbatim = Verbatim(source)
+
+ first_wrapper = ListNode([Fragment(Pos(1, 0), Pos(2, 3))])
+ second_wrapper = ListNode([Fragment(Pos(3, 0), Pos(4, 3))])
+ verbatim.append(first_wrapper)
+ verbatim.append(second_wrapper)
+
+ visitor = ConcreteVerbatimVisitor()
+ verbatim.visit(visitor)
+
+ assert id(first_wrapper) in visitor._bounds_cache
+ assert id(second_wrapper) in visitor._bounds_cache
+ assert len(visitor._bounds_cache) == 2
diff --git a/tox.ini b/tox.ini
index 612d4d0..3fd5318 100644
--- a/tox.ini
+++ b/tox.ini
@@ -12,6 +12,7 @@ python =
description = run tests
extras =
lint
+ test
commands =
python --version
isort src tests setup.py --check --diff
@@ -25,6 +26,7 @@ description = check type annotations
platform = (linux|darwin)
extras =
lint
+ test
commands =
python --version
pyre --noninteractive check
diff --git a/whitelist.txt b/whitelist.txt
index 96390b2..a56fe2a 100644
--- a/whitelist.txt
+++ b/whitelist.txt
@@ -1,19 +1,38 @@
asts
autoescape
+autolink
+binop
+blockquote
+boldnew
+caplog
casefold
charref
charrefs
+chdir
checkable
+collector1
+collector2
+commonpath
+conftest
copyfileobj
ctx
+dasherize
decl
defs
delitem
+dest
+doc1
+doc2
docc
-commonpath
-dasherize
+docstrings
+docstrings1
+docstrings2
endtag
entityref
+env1
+env2
+envs
+ep
eq
ethereum
etree
@@ -22,9 +41,14 @@ exc
expr
fullname
func
-href
getitem
globbed
+h1
+h2
+h3
+hashable
+href
+img
isabstract
islice
j2
@@ -39,12 +63,16 @@ matcher
merchantability
metaclass
modulefinder
+names1
+names2
+ol
param
params
pathname2url
perf
Pos
ptag
+pyproject
qualname
removeprefix
renderer
@@ -54,20 +82,34 @@ ret
rvalue
setext
setitem
+source1
+source2
src
starttag
stmt
+stringio
strikethrough
subclasses
+subclassing
+subdir
+subdirectory
+subtrees
superclass
tbody
+td1
+td2
thead
this'll
toml
tomli
+tooltip
tostring
-traverser
traversable
+traverser
typeddict
+types1
+types2
+unittest
+unlink
unresolve
urlunsplit