tools/epro2/kicad: hierarchical export + global_label + 5-Voltage power ports

Three coupled changes so kicad-cli sch erc runs at the project level
(across all sheets of one schematic) instead of single-sheet:

1. (label) → (global_label (shape passive)). EPRO2 nets are
   project-global by construction (named rails span every page in the
   SCH and physically wire across PCBs); KiCad's local label is sheet-
   scoped and triggers `label_dangling` for any name not duplicated on
   the same page.

2. New root_sch_writer that groups SCH_PAGE docs by their parent SCH
   (META.schematic), emits one root .kicad_sch per group with one
   (sheet ...) entry per child, and threads the root-assigned uuid back
   into each child's (sheet_instances) so KiCad can bind them.
   --all-sch now defaults to this; --flat falls back to one-file-per-page.

3. EPRO2's "5-Voltage" placeholder COMPONENT (partId
   pid8a0e77bacb214e, 365 instances on ESP-VoCat) is the editor's power
   port. The rail name lives in the placement's `Global Net Name` ATTR,
   not in the PART. We now emit a (global_label "<rail>") at the
   placement coords whenever that attr is set (101/365 of them on
   ESP-VoCat — the rest are unconfigured drafts).

ESP-VoCat 5 hierarchical roots: 2325 → 2265 violations. Modest because
5 of 6 SCHs are single-page (no cross-sheet nets to resolve), and the
one 4-page schematic (CoreBoard) shares only a handful of names across
sheets — most net names are de-facto sheet-local. The remaining ~190
pin_not_connected are dominated by 0402-style passives whose pin tip
lies on a wire's interior, not at an endpoint; KiCad needs an explicit
(junction) at those points and we don't yet emit one. Marked as the
next follow-up in log.md.

47 → 52 unit tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tools/epro2/tests/test_root_sch_writer.py

@@ -0,0 +1,68 @@
+"""Root sheet writer regression: hierarchical parent .kicad_sch."""
+
+from tools.epro2.kicad._sexpr_reader import parse
+from tools.epro2.kicad.root_sch_writer import ChildSheet, write_root_sheet
+
+
+def _block(parsed, name):
+    return [c for c in parsed if isinstance(c, list) and c and c[0] == name]
+
+
+def test_root_emits_one_sheet_block_per_child():
+    children = [
+        ChildSheet("Overview.kicad_sch", "Overview", "uuid-1"),
+        ChildSheet("MCU.kicad_sch", "MCU", "uuid-2"),
+        ChildSheet("Codec.kicad_sch", "Codec", "uuid-3"),
+    ]
+    parsed = parse(write_root_sheet("CoreBoard", children))
+    sheets = _block(parsed, "sheet")
+    assert len(sheets) == 3
+    # Each sheet block carries the assigned uuid + Sheetname + Sheetfile
+    titles = []
+    files = []
+    uuids = []
+    for sh in sheets:
+        uuids.append(next(c for c in sh if isinstance(c, list) and c[0] == "uuid")[1])
+        for c in sh:
+            if isinstance(c, list) and c[0] == "property":
+                if c[1] == "Sheetname":
+                    titles.append(c[2])
+                elif c[1] == "Sheetfile":
+                    files.append(c[2])
+    assert titles == ["Overview", "MCU", "Codec"]
+    assert files == ["Overview.kicad_sch", "MCU.kicad_sch", "Codec.kicad_sch"]
+    assert uuids == ["uuid-1", "uuid-2", "uuid-3"]
+
+
+def test_root_assigns_sequential_page_numbers_starting_at_2():
+    """Root itself is page 1 of the hierarchy; children start at page 2 so
+    that a child's (sheet_instances (page "<n>")) lines up with the root's
+    (instances ... (page "<n>"))."""
+    children = [
+        ChildSheet("a.kicad_sch", "A", "u-a"),
+        ChildSheet("b.kicad_sch", "B", "u-b"),
+    ]
+    parsed = parse(write_root_sheet("Project", children))
+    sheets = _block(parsed, "sheet")
+    page_nums = []
+    for sh in sheets:
+        inst = next(c for c in sh if isinstance(c, list) and c[0] == "instances")
+        proj = next(c for c in inst if isinstance(c, list) and c[0] == "project")
+        path = next(c for c in proj if isinstance(c, list) and c[0] == "path")
+        page = next(c for c in path if isinstance(c, list) and c[0] == "page")
+        page_nums.append(page[1])
+    assert page_nums == ["2", "3"]
+    # And the root's own page is 1
+    root_inst = _block(parsed, "sheet_instances")[0]
+    root_path = next(c for c in root_inst if isinstance(c, list) and c[0] == "path")
+    root_page = next(c for c in root_path if isinstance(c, list) and c[0] == "page")
+    assert root_page[1] == "1"
+
+
+def test_root_handles_zero_children():
+    """Empty schematic: still emit a valid kicad_sch with no (sheet) blocks."""
+    parsed = parse(write_root_sheet("Empty", []))
+    assert parsed[0] == "kicad_sch"
+    assert _block(parsed, "sheet") == []
+    # sheet_instances still required (KiCad demands at least one path)
+    assert _block(parsed, "sheet_instances")

tools/epro2/tests/test_sch_writer.py

@@ -100,11 +100,13 @@ def test_text_object_emits_text_block_when_non_empty():
     assert texts[0][1] == "Hello"
 
 
-def test_named_wire_emits_label_at_line_start():
+def test_named_wire_emits_global_label_at_line_start():
     """EPRO2 binds wire segments into nets by NAME (WIRE.NET attr), not by
     geometry alone. Each LINE whose lineGroup points to a WIRE with a NET
-    attr must get a (label "<NET>") at one endpoint — same-named labels on
-    distinct LINEs are how KiCad's ERC recognizes a multi-segment net."""
+    attr gets a (global_label "<NET>") at one endpoint — global, not local,
+    because EPRO2 nets span every page of the schematic and (via PCB) the
+    whole project; local (label) on a single page would always be flagged
+    `label_dangling` for cross-sheet nets."""
     d = _doc([
         ("w1", {"_type": "WIRE"}),
         ("a1", {"_type": "ATTR", "parentId": "w1", "key": "NET", "value": "GND"}),
@@ -115,7 +117,7 @@ def test_named_wire_emits_label_at_line_start():
     ])
     text = write_sch_page(d, sheet_origin_mm=(0.0, 0.0))
     p = parse(text)
-    labels = _block(p, "label")
+    labels = _block(p, "global_label")
     assert len(labels) == 2  # one label per non-degenerate LINE
     assert all(lab[1] == "GND" for lab in labels)
     # First label sits at the first LINE's start endpoint
@@ -136,10 +138,61 @@ def test_unnamed_wire_emits_no_label():
     ])
     text = write_sch_page(d, sheet_origin_mm=(0.0, 0.0))
     p = parse(text)
-    assert _block(p, "label") == []
+    assert _block(p, "global_label") == []
     assert getattr(write_sch_page, "last_stats").labels == 0
 
 
+def test_power_port_component_emits_global_label_at_placement():
+    """EPRO2 represents power rails (VCC/GND/VBUS/...) as generic
+    placeholder COMPONENTs whose net name lives in a `Global Net Name`
+    ATTR on the placement (not on the underlying PART). Without an
+    explicit (global_label) at the pin tip, every such instance reads
+    as pin_not_connected even when the symbol's pin sits on a wire."""
+    d = _doc([
+        ("e1", {"_type": "COMPONENT", "partId": "pid8a0e77bacb214e",
+                "x": 100, "y": 50, "rotation": 0}),
+        ("a1", {"_type": "ATTR", "parentId": "e1",
+                "key": "Global Net Name", "value": "VBUS"}),
+    ])
+    text = write_sch_page(d, sheet_origin_mm=(0.0, 0.0))
+    p = parse(text)
+    labels = _block(p, "global_label")
+    assert len(labels) == 1
+    assert labels[0][1] == "VBUS"
+    at = next(c for c in labels[0] if isinstance(c, list) and c[0] == "at")
+    assert at[1] == 100 * MIL_TO_MM
+    assert at[2] == 50 * MIL_TO_MM
+
+
+def test_unnamed_power_port_emits_no_label():
+    """Unnamed placeholder power-ports (Global Net Name absent) stay as
+    bare symbol placements — we have no rail name to bind them to."""
+    d = _doc([
+        ("e1", {"_type": "COMPONENT", "partId": "pid8a0e77bacb214e",
+                "x": 0, "y": 0}),
+    ])
+    text = write_sch_page(d, sheet_origin_mm=(0.0, 0.0))
+    p = parse(text)
+    assert _block(p, "global_label") == []
+
+
+def test_sheet_path_and_page_num_propagate_to_sheet_instances():
+    """When a page is written as a child of a hierarchical root, its
+    (sheet_instances) must echo the uuid the root assigned (path
+    "/<assigned_uuid>") and its hierarchy page number — without that the
+    root can't bind the child and ERC treats it as standalone."""
+    d = _doc([("META", {"_type": "META", "title": "child"})])
+    text = write_sch_page(
+        d, sheet_path="/22222222-3333-4444-5555-666666666666", page_num=3,
+    )
+    p = parse(text)
+    inst = _block(p, "sheet_instances")[0]
+    path = next(c for c in inst if isinstance(c, list) and c[0] == "path")
+    assert path[1] == "/22222222-3333-4444-5555-666666666666"
+    page = next(c for c in path if isinstance(c, list) and c[0] == "page")
+    assert page[1] == "3"
+
+
 def test_non_sch_page_doc_rejected():
     d = Document(doc_uuid="x", doc_type="PCB")
     try: