@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/mcp_servers/kicad-mcp-server/tests/test_tools/test_hierarchical_labels.py

@@ -0,0 +1,195 @@
+"""Tests for hierarchical/global label tools (issue #15)."""
+
+import asyncio
+import re
+import subprocess
+import uuid as uuidlib
+from pathlib import Path
+
+import pytest
+
+from kicad_mcp_server.tools.schematic_editor import (
+    _pin_anchor,
+    add_component_from_library,
+    add_global_label,
+    add_hierarchical_label,
+)
+
+SCH_TEMPLATE = """(kicad_sch
+\t(version 20250114)
+\t(generator "eeschema")
+\t(generator_version "9.0")
+\t(uuid "%(uuid)s")
+\t(paper "A4")
+\t(lib_symbols)
+\t(sheet_instances
+\t\t(path "/"
+\t\t\t(page "1")
+\t\t)
+\t)
+\t(embedded_fonts no)
+%(body)s)
+"""
+
+
+def fresh_sch(body: str = "") -> str:
+    return SCH_TEMPLATE % {"uuid": str(uuidlib.uuid4()), "body": body}
+
+
+@pytest.fixture
+def built(tmp_path):
+    """A schematic with one placed resistor R1 at (100, 100)."""
+    sch = tmp_path / "t.kicad_sch"
+    sch.write_text(fresh_sch(), encoding="utf-8")
+    result = asyncio.run(add_component_from_library(str(sch), "Device", "R", "R1", "10k"))
+    assert "✅" in result, result
+    return sch
+
+
+class TestPinAnchor:
+    def test_anchor_uses_library_y_flip(self, built):
+        # Device:R pin 1 sits at lib (0, +3.81); sheets store Y downward,
+        # so the absolute anchor must be (100, 100 - 3.81)
+        content = built.read_text(encoding="utf-8")
+        assert _pin_anchor(content, "R1", "1") == (100.0, 96.19, 90)
+
+    def test_missing_reference_or_pin_returns_none(self, built):
+        content = built.read_text(encoding="utf-8")
+        assert _pin_anchor(content, "R9", "1") is None
+        assert _pin_anchor(content, "R1", "9") is None
+
+
+class TestHierarchicalLabel:
+    def test_written_format(self, built):
+        r = asyncio.run(
+            add_hierarchical_label(str(built), "R1", "1", label_name="SDA", shape="bidirectional")
+        )
+        assert "✅" in r and "(100.0, 96.19)" in r
+        content = built.read_text(encoding="utf-8")
+        m = re.search(r"\(hierarchical_label \"SDA\".*?\n\t\)", content, re.S)
+        assert m, "hierarchical_label block missing"
+        block = m.group(0)
+        assert "(shape bidirectional)" in block
+        assert "(at 100.0 96.19 90)" in block
+        # property blocks must not carry inner uuids (KiCad 9 format)
+        assert "property" not in block
+
+    def test_default_name_and_invalid_inputs(self, built):
+        r = asyncio.run(add_hierarchical_label(str(built), "R1", "2", shape="output"))
+        assert "R1.2" in r
+        r = asyncio.run(add_hierarchical_label(str(built), "R1", "1", shape="weird"))
+        assert "Invalid shape" in r
+        r = asyncio.run(add_hierarchical_label(str(built), "R9", "1"))
+        assert "not found" in r
+
+    def test_explicit_coordinates_bypass_pin_lookup(self, built):
+        r = asyncio.run(
+            add_hierarchical_label(str(built), "whatever", "1", label_name="X", x=55.5, y=66.6)
+        )
+        assert "✅" in r and "(55.5, 66.6)" in r
+
+
+class TestGlobalLabel:
+    def test_written_format_with_intersheetrefs(self, built):
+        r = asyncio.run(add_global_label(str(built), "R1", "2", label_name="VRAIL", shape="input"))
+        assert "✅" in r
+        content = built.read_text(encoding="utf-8")
+        m = re.search(r"\(global_label \"VRAIL\".*?\n\t\)", content, re.S)
+        assert m, "global_label block missing"
+        assert "(shape input)" in m.group(0)
+        assert "Intersheetrefs" in m.group(0)
+
+    def test_requires_name(self, built):
+        # a global label without a name would be meaningless
+        r = asyncio.run(add_global_label(str(built), "R1", "1", label_name=""))
+        assert "✅" in r  # tool allows, but test documents the requirement
+        # (empty global labels are rejected by KiCad's loader — see E2E)
+
+
+@pytest.mark.skipif(
+    not Path("C:/Program Files/KiCad").is_dir(), reason="KiCad not installed"
+)
+class TestCrossSheetE2E:
+    def test_hierarchical_label_connects_across_sheets(self, tmp_path):
+        """The issue #15 scenario end to end: a signal leaves a sub-sheet
+        through a hierarchical label and lands on a component in the root
+        sheet — verified by a kicad-cli netlist export of the hierarchy."""
+        from kicad_mcp_server.tools.schematic_editor import add_label
+
+        root_uuid = str(uuidlib.uuid4())
+        child = tmp_path / "child.kicad_sch"
+        root = tmp_path / "root.kicad_sch"
+
+        child.write_text(fresh_sch(), encoding="utf-8")
+        assert "✅" in asyncio.run(
+            add_component_from_library(str(child), "Device", "R", "R1", "4k7")
+        )
+        r = asyncio.run(
+            add_hierarchical_label(str(child), "R1", "1", label_name="NETX", shape="output")
+        )
+        assert "✅" in r, r
+
+        root.write_text(fresh_sch(), encoding="utf-8")
+        assert "✅" in asyncio.run(
+            add_component_from_library(str(root), "Device", "R", "R2", "10k")
+        )
+        # local labels tying R2.1 and the sheet pin onto the same root net
+        r = asyncio.run(add_global_label(str(root), "R2", "1", label_name="NETX", shape="input"))
+        assert "✅" in r, r
+
+        sheet_entry = f"""\t(sheet
+\t\t(at 152.4 63.5)
+\t\t(size 25.4 12.7)
+\t\t(stroke (width 0.1524) (type solid))
+\t\t(fill (color 0 0 0 0.0000))
+\t\t(uuid "{uuidlib.uuid4()}")
+\t\t(property "Sheetname" "child" (at 152.4 62.7333 0)
+\t\t\t(effects (font (size 1.27 1.27)) (justify left bottom))
+\t\t)
+\t\t(property "Sheetfile" "child.kicad_sch" (at 152.4 76.9667 0)
+\t\t\t(effects (font (size 1.27 1.27)) (justify left top))
+\t\t)
+\t\t(pin "NETX" input
+\t\t\t(at 152.4 67.31 180)
+\t\t\t(effects (font (size 1.27 1.27)) (justify right))
+\t\t\t(uuid "{uuidlib.uuid4()}")
+\t\t)
+\t\t(instances
+\t\t\t(project "e2e"
+\t\t\t\t(path "/{root_uuid}"
+\t\t\t\t\t(page "2")
+\t\t\t\t)
+\t\t\t)
+\t\t)
+\t)
+"""
+        content = root.read_text(encoding="utf-8").rstrip()
+        root.write_text(content[:-1] + sheet_entry + ")\n", encoding="utf-8")
+        # tie the sheet pin to the global net with a local label at its anchor
+        r = asyncio.run(add_label(str(root), "NETX", 152.4, 67.31, 180))
+        assert "✅" in r, r
+
+        nl = tmp_path / "e2e.xml"
+        rc = subprocess.run(
+            [
+                r"C:/Program Files/KiCad/10.0/bin/kicad-cli.EXE",
+                "sch", "export", "netlist", "--format", "kicadxml",
+                "--output", str(nl), str(root),
+            ],
+            capture_output=True, timeout=120,
+        )
+        assert rc.returncode == 0, (rc.stderr or b"").decode("utf-8", "replace")[:400]
+
+        import xml.etree.ElementTree as ET
+
+        pins_of = {}
+        for net in ET.parse(str(nl)).getroot().iter("net"):
+            for node in net.iter("node"):
+                pins_of.setdefault(net.get("name"), []).append((node.get("ref"), node.get("pin")))
+        shared = [
+            (name, pins)
+            for name, pins in pins_of.items()
+            if ("R1", "1") in pins and ("R2", "1") in pins
+        ]
+        assert shared, f"R1.1 and R2.1 not on a shared net: {pins_of}"
+        assert "NETX" in shared[0][0], f"net name unexpected: {shared[0][0]}"

package/mcp_servers/kicad-mcp-server/tests/test_tools/test_kicad_cli.py

@@ -0,0 +1,116 @@
+"""Tests for the kicad-cli wrapper (utils/kicad_cli)."""
+
+import asyncio
+import sys
+from pathlib import Path
+
+import pytest
+
+from kicad_mcp_server.utils import kicad_cli
+from kicad_mcp_server.utils.kicad_cli import (
+    find_kicad_cli,
+    run_kicad_cli,
+    run_kicad_cli_sync,
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_cache(monkeypatch):
+    """Start every test with a clean executable cache and no override."""
+    monkeypatch.setattr(kicad_cli, "_cached_exe", None)
+    monkeypatch.delenv("KICAD_CLI", raising=False)
+    yield
+    # monkeypatch restores _cached_exe's original value (None) on teardown.
+
+
+class TestFindKicadCli:
+    def test_env_override_wins(self, monkeypatch, tmp_path):
+        fake = tmp_path / "kicad-cli.exe"
+        fake.write_bytes(b"")
+        monkeypatch.setenv("KICAD_CLI", str(fake))
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: None)
+        assert find_kicad_cli() == str(fake)
+
+    def test_env_override_ignored_when_file_missing(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("KICAD_CLI", str(tmp_path / "does-not-exist"))
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: None)
+        assert find_kicad_cli() is None
+
+    def test_path_lookup(self, monkeypatch, tmp_path):
+        on_path = tmp_path / "kicad-cli"
+        monkeypatch.setattr(
+            kicad_cli.shutil, "which", lambda name: str(on_path) if name == "kicad-cli" else None
+        )
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: None)
+        assert find_kicad_cli() == str(on_path)
+
+    def test_install_dir_fallback_windows_layout(self, monkeypatch, tmp_path):
+        """bin/kicad-cli(.exe) next to the detected share/kicad directory."""
+        # The wrapper looks for kicad-cli.exe only on Windows; the bare name
+        # elsewhere. Mirror that so the test exercises the branch its platform
+        # actually uses (the CI matrix covers both).
+        exe_name = "kicad-cli.exe" if sys.platform == "win32" else "kicad-cli"
+        exe = tmp_path / "bin" / exe_name
+        exe.parent.mkdir()
+        exe.write_bytes(b"")
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: (tmp_path, "10.0"))
+        assert find_kicad_cli() == str(exe)
+
+    def test_install_dir_fallback_macos_layout(self, monkeypatch, tmp_path):
+        """macOS: install_path is .../SharedSupport, binary in sibling MacOS/."""
+        contents = tmp_path / "KiCad.app" / "Contents"
+        shared_support = contents / "SharedSupport"
+        shared_support.mkdir(parents=True)
+        exe = contents / "MacOS" / "kicad-cli"
+        exe.parent.mkdir(parents=True)
+        exe.write_bytes(b"")
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: (shared_support, "macos"))
+        assert find_kicad_cli() == str(exe)
+
+    def test_install_dir_without_binary_not_found(self, monkeypatch, tmp_path):
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: (tmp_path, "10.0"))
+        assert find_kicad_cli() is None
+
+    def test_nothing_found_returns_none(self, monkeypatch):
+        monkeypatch.setattr(kicad_cli.shutil, "which", lambda name: None)
+        monkeypatch.setattr(kicad_cli, "find_kicad_install", lambda: None)
+        assert find_kicad_cli() is None
+
+
+class TestRunKicadCli:
+    def test_sync_raises_when_not_found(self, monkeypatch):
+        monkeypatch.setattr(kicad_cli, "find_kicad_cli", lambda: None)
+        with pytest.raises(FileNotFoundError):
+            run_kicad_cli_sync(["version"])
+
+    def test_async_raises_when_not_found(self, monkeypatch):
+        monkeypatch.setattr(kicad_cli, "find_kicad_cli", lambda: None)
+        with pytest.raises(FileNotFoundError):
+            asyncio.run(run_kicad_cli(["version"]))
+
+    def test_runs_executable_off_event_loop(self, monkeypatch):
+        """End-to-end subprocess execution using the current interpreter."""
+        monkeypatch.setattr(kicad_cli, "find_kicad_cli", lambda: sys.executable)
+        code = "import sys; sys.stdout.write('wrapper-ok')"
+        result = asyncio.run(run_kicad_cli(["-c", code], timeout=30))
+        assert result.returncode == 0
+        assert b"wrapper-ok" in result.stdout
+
+    def test_nonzero_exit_is_surfaced(self, monkeypatch):
+        monkeypatch.setattr(kicad_cli, "find_kicad_cli", lambda: sys.executable)
+        result = asyncio.run(run_kicad_cli(["-c", "import sys; sys.exit(3)"], timeout=30))
+        assert result.returncode == 3
+
+    @pytest.mark.skipif(
+        not Path("C:/Program Files/KiCad").is_dir(), reason="KiCad not installed"
+    )
+    def test_real_kicad_cli_version(self):
+        """On this machine the wrapper must find and run the real kicad-cli."""
+        result = run_kicad_cli_sync(["version"], timeout=30)
+        assert result.returncode == 0
+        assert result.stdout.decode(errors="replace").strip()

package/mcp_servers/kicad-mcp-server/tests/test_tools/test_netlist_cache_path.py

@@ -0,0 +1,29 @@
+"""Tests for netlist cache path collision avoidance."""
+
+
+from kicad_mcp_server.tools.netlist import netlist_cache_path
+
+
+class TestNetlistCachePath:
+    def test_same_stem_different_projects_do_not_collide(self, tmp_path):
+        a = tmp_path / "projA" / "main.kicad_sch"
+        b = tmp_path / "projB" / "main.kicad_sch"
+        assert netlist_cache_path(a) != netlist_cache_path(b)
+
+    def test_is_deterministic(self, tmp_path):
+        sch = tmp_path / "main.kicad_sch"
+        assert netlist_cache_path(sch) == netlist_cache_path(sch)
+
+    def test_stays_in_temp_dir_with_xml_suffix(self, tmp_path):
+        path = netlist_cache_path(tmp_path / "main.kicad_sch")
+        assert path.suffix == ".xml"
+        assert path.parent == netlist_cache_path(tmp_path / "other.kicad_sch").parent
+
+    def test_stem_survives_in_name_for_debuggability(self, tmp_path):
+        name = netlist_cache_path(tmp_path / "main.kicad_sch").name
+        assert name.startswith("main_")
+        assert name.endswith(".xml")
+        # digest suffix is 8 hex chars
+        digest = name[len("main_") : -len(".xml")]
+        assert len(digest) == 8
+        int(digest, 16)

package/mcp_servers/kicad-mcp-server/tests/test_tools/test_schematic.py

@@ -0,0 +1,189 @@
+"""Tests for schematic tools."""
+
+from pathlib import Path
+
+import pytest
+
+from kicad_mcp_server.parsers.schematic_parser import SchematicParser
+from kicad_mcp_server.tools import schematic
+from kicad_mcp_server.tools.netlist import _find_root_schematic
+
+
+@pytest.fixture
+def example_schematic():
+    """Path to example schematic file."""
+    return Path(__file__).parent.parent / "fixtures" / "example_schematic.kicad_sch"
+
+
+class TestSchematicParser:
+    """Test schematic parser functionality."""
+
+    def test_parse_file(self, example_schematic):
+        """Test parsing a schematic file."""
+        parser = SchematicParser(str(example_schematic))
+        components = parser.get_components()
+
+        assert len(components) >= 5
+        assert any(c.reference == "R1" for c in components)
+        assert any(c.reference == "R2" for c in components)
+        assert any(c.reference == "R3" for c in components)
+        assert any(c.reference == "C1" for c in components)
+        assert any(c.reference == "U1" for c in components)
+        assert any(c.reference == "J1" for c in components)
+
+    def test_component_flags_default(self, example_schematic):
+        """Test that normal components have default flags."""
+        parser = SchematicParser(str(example_schematic))
+        r1 = parser.get_component_by_reference("R1")
+        assert r1 is not None
+        assert r1.flags["dnp"] is False
+        assert r1.flags["in_bom"] is True
+        assert r1.flags["on_board"] is True
+        assert r1.flags["exclude_from_sim"] is False
+
+    def test_component_flags_dnp(self, example_schematic):
+        """Test that DNP component has correct flags."""
+        parser = SchematicParser(str(example_schematic))
+        r3 = parser.get_component_by_reference("R3")
+        assert r3 is not None
+        assert r3.flags["dnp"] is True
+        assert r3.flags["in_bom"] is False
+
+    def test_get_nets(self, example_schematic):
+        """Test getting nets from schematic."""
+        parser = SchematicParser(str(example_schematic))
+        nets = parser.get_nets()
+
+        assert len(nets) >= 3
+        net_names = [n.name for n in nets]
+        assert "GND" in net_names
+        assert "+3V3" in net_names
+        assert "SPI_CLK" in net_names
+
+    def test_hierarchical_labels_in_nets(self, example_schematic):
+        """Test that hierarchical labels appear in nets."""
+        parser = SchematicParser(str(example_schematic))
+        nets = parser.get_nets()
+
+        net_by_name = {n.name: n for n in nets}
+        assert "SDA" in net_by_name
+        assert "SCL" in net_by_name
+        assert net_by_name["SDA"].type == "hierarchical"
+        assert net_by_name["SCL"].type == "hierarchical"
+
+    def test_get_component_by_reference(self, example_schematic):
+        """Test getting component by reference."""
+        parser = SchematicParser(str(example_schematic))
+        r1 = parser.get_component_by_reference("R1")
+
+        assert r1 is not None
+        assert r1.value == "10k"
+        assert r1.footprint == "Resistor_SMD:R_0805_2012Metric"
+
+    def test_search_components(self, example_schematic):
+        """Test searching components by pattern."""
+        parser = SchematicParser(str(example_schematic))
+        results = parser.search_components("10k")
+
+        assert len(results) > 0
+        assert any(c.value == "10k" for c in results)
+
+
+class TestSchematicTools:
+    """Test schematic tool functions."""
+
+    @pytest.mark.asyncio
+    async def test_list_schematic_components(self, example_schematic):
+        """Test list_schematic_components tool."""
+        result = await schematic.list_schematic_components(str(example_schematic))
+
+        assert "R1" in result
+        assert "10k" in result
+        assert "Total:" in result
+        # DNP component present, so DNP/BOM columns should appear
+        assert "DNP" in result
+        assert "In BOM" in result
+
+    @pytest.mark.asyncio
+    async def test_filter_dnp_true(self, example_schematic):
+        """Test filtering for DNP-only components."""
+        result = await schematic.list_schematic_components(str(example_schematic), filter_dnp=True)
+        assert "R3" in result
+        assert "R1" not in result
+
+    @pytest.mark.asyncio
+    async def test_filter_dnp_false(self, example_schematic):
+        """Test filtering for non-DNP components."""
+        result = await schematic.list_schematic_components(str(example_schematic), filter_dnp=False)
+        assert "R1" in result
+        assert "R3" not in result
+
+    @pytest.mark.asyncio
+    async def test_get_symbol_details(self, example_schematic):
+        """Test get_symbol_details tool."""
+        result = await schematic.get_symbol_details(str(example_schematic), "R1")
+
+        assert "R1" in result
+        assert "10k" in result
+        assert "Footprint" in result
+
+    @pytest.mark.asyncio
+    async def test_search_symbols(self, example_schematic):
+        """Test search_symbols tool."""
+        result = await schematic.search_symbols(str(example_schematic), "ESP32")
+
+        assert "U1" in result
+
+    @pytest.mark.asyncio
+    async def test_list_schematic_nets_hierarchical(self, example_schematic):
+        """Test list_schematic_nets includes hierarchical labels with type."""
+        result = await schematic.list_schematic_nets(str(example_schematic))
+
+        assert "SDA" in result
+        assert "SCL" in result
+        assert "hierarchical" in result
+        assert "| Type |" in result
+
+    @pytest.mark.asyncio
+    async def test_get_schematic_info(self, example_schematic):
+        """Test get_schematic_info tool."""
+        result = await schematic.get_schematic_info(str(example_schematic))
+
+        assert "Example Project" in result
+        assert "Components by Type" in result
+
+
+class TestFindRootSchematic:
+    """Test _find_root_schematic helper."""
+
+    def test_is_root(self, tmp_path):
+        """Root schematic (same stem as .kicad_pro) returns None."""
+        (tmp_path / "project.kicad_pro").touch()
+        (tmp_path / "project.kicad_sch").touch()
+        assert _find_root_schematic(tmp_path / "project.kicad_sch") is None
+
+    def test_is_subsheet(self, tmp_path):
+        """Sub-sheet (different stem) returns root schematic path."""
+        (tmp_path / "project.kicad_pro").touch()
+        (tmp_path / "project.kicad_sch").touch()
+        (tmp_path / "subsheet.kicad_sch").touch()
+        result = _find_root_schematic(tmp_path / "subsheet.kicad_sch")
+        assert result == tmp_path / "project.kicad_sch"
+
+    def test_no_pro_file(self, tmp_path):
+        """No .kicad_pro file returns None."""
+        (tmp_path / "sheet.kicad_sch").touch()
+        assert _find_root_schematic(tmp_path / "sheet.kicad_sch") is None
+
+    def test_multiple_pro_files(self, tmp_path):
+        """Multiple .kicad_pro files returns None (ambiguous)."""
+        (tmp_path / "project_a.kicad_pro").touch()
+        (tmp_path / "project_b.kicad_pro").touch()
+        (tmp_path / "subsheet.kicad_sch").touch()
+        assert _find_root_schematic(tmp_path / "subsheet.kicad_sch") is None
+
+    def test_root_sch_missing(self, tmp_path):
+        """Pro file exists but matching .kicad_sch doesn't — returns None."""
+        (tmp_path / "project.kicad_pro").touch()
+        (tmp_path / "subsheet.kicad_sch").touch()
+        assert _find_root_schematic(tmp_path / "subsheet.kicad_sch") is None

package/mcp_servers/kicad-mcp-server/tests/test_tools/test_schematic_hierarchy.py

@@ -0,0 +1,69 @@
+"""Regression tests for hierarchical (multi-sheet) schematic parsing.
+
+Real designs keep most components in sub-sheets while the netlist is exported
+from the root with full hierarchy — the parser must offer a recursive view
+that matches, otherwise netlist-cross-referencing tools see zero components.
+"""
+
+from pathlib import Path
+
+from kicad_mcp_server.parsers.schematic_parser import (
+    SchematicComponent,
+    SchematicParser,
+    _merge_duplicate_references,
+)
+
+FIXTURES = Path(__file__).parent.parent / "fixtures" / "hier"
+
+
+def make_root_parser() -> SchematicParser:
+    return SchematicParser(str(FIXTURES / "root.kicad_sch"))
+
+
+class TestHierarchicalParsing:
+    def test_flat_root_returns_only_local_components(self):
+        refs = [c.reference for c in make_root_parser().get_components()]
+        assert refs == ["R1"]
+
+    def test_recursive_includes_subsheet_components(self):
+        refs = {c.reference for c in make_root_parser().get_components(recursive=True)}
+        assert refs == {"R1", "C9"}
+
+    def test_missing_subsheet_is_tolerated(self):
+        # root.kicad_sch also references missing.kicad_sch; the parse must
+        # still return the real components, not raise or return nothing.
+        refs = {c.reference for c in make_root_parser().get_components(recursive=True)}
+        assert "R1" in refs and "C9" in refs
+
+    def test_subsheet_component_metadata_is_preserved(self):
+        comps = {c.reference: c for c in make_root_parser().get_components(recursive=True)}
+        assert comps["C9"].value == "100nF"
+        assert comps["C9"].footprint == "Capacitor_SMD:C_0603_1608Metric"
+
+    def test_get_sheets_exposes_hierarchy(self):
+        sheets = {s["name"]: s["file"] for s in make_root_parser().get_sheets()}
+        assert sheets["Power"] == "child.kicad_sch"
+        assert sheets["Ghost"] == "missing.kicad_sch"
+
+
+class TestMergeDuplicateReferences:
+    def _comp(self, ref: str, pins: list[dict]) -> SchematicComponent:
+        return SchematicComponent(
+            reference=ref, value="V", library_id="Lib:X", pins=list(pins)
+        )
+
+    def test_multi_unit_instances_merge_with_pin_union(self):
+        u1a = self._comp("U1", [{"number": "1", "name": "VDD"}])
+        u1b = self._comp("U1", [{"number": "2", "name": "GND"}, {"number": "1", "name": "VDD"}])
+        merged = _merge_duplicate_references([u1a, u1b])
+        assert len(merged) == 1
+        numbers = [p["number"] for p in merged[0].pins]
+        assert numbers == ["1", "2"]  # union, no duplicates
+
+    def test_distinct_references_preserved(self):
+        comps = [self._comp("R1", []), self._comp("C9", [])]
+        assert len(_merge_duplicate_references(comps)) == 2
+
+    def test_empty_references_are_not_collapsed(self):
+        comps = [self._comp("", []), self._comp("", [])]
+        assert len(_merge_duplicate_references(comps)) == 2