validate_hierarchy

Checks every sheet below the root, however deep, each file once. A relative sheet file
name is found beside the file holding the sheet, as KiCad finds it; a sheet that contains
itself, which KiCad refuses, is skipped. Per sheet block: orphaned labels and pins,
direction mismatches, a missing file, a file that cannot be parsed ("unreadable_file",
whose "note" names the file; its checks are skipped, the rest still run). Per sheet
instance, so a reused sheet counts once per use: duplicate and unannotated reference
designators, each read from the entry KiCad reads at that instance, the root's
symbol_instances table on a root in KiCad 6's form, else the symbol's own (the units of
one multi-unit part share theirs); an instance with no entry reads the symbol's first
entry, else its Reference property. Past 4096 instances a "references_unchecked" note says
the rest went unchecked. Per file: the points where kicad-cli 9 drops part of a line that
KiCad's editor keeps.

Those are a junction strictly inside a wire or bus ("junction_inside_wire") and, in a file
kicad-cli 9 loads, a bus entry end strictly inside one ("bus_entry_inside_wire"); KiCad's
editor never saves either, and earlier versions of this package wrote both. kicad-cli 9
(ERC, netlist export, PCB update) cuts the line there: per line, "kept" is the stretch it
keeps and "dropped" the stretch it loses, cutting off whatever joins the line only along
that. "editor" says what KiCad 9's editor makes of it: it splits the line, keeping a
junction where three or more directions meet ("keeps_junction"), deleting it elsewhere
("deletes_junction"), and at a bus entry end placing none ("splits_wire"). A file stamped
past KiCad 9's format gets neither reading. The readings follow KiCad's source; whether
kicad-cli 9 loads the sheet at all is not checked. To fix one, make the call in its
"repair" as given: add_junctions at the point, which splits the line, or remove_junction.
Such an issue carries a "note" in place of a repair in two cases only: its sheet is one the
connectivity model refuses (a symbol or pin at an angle KiCad cannot load; no reading
either), or it is a bus entry end where KiCad allows no junction.

Per file too: the no-connect flags ("no_connect_off_pin") and wire ends
("wire_end_off_pin") at the point releases 0.5.8 to 0.20.1 gave a pin of a symbol at
rotation 90 or 270 with a mirror. They mirrored before rotating, so that point is the
pin's end reflected through the symbol's origin, and 0.20.1's no_connect_pin,
wire_pins_to_net and connect_pins wrote there (measured). Only a point where KiCad draws
no pin is checked. Each issue names the symbol ("reference"), the "pin", the point ("x",
"y") and where KiCad draws the pin ("pin_x", "pin_y"), and a wire end its "wire". Where
the old transform put several pins at the point, the issue lists them under "pins" in
place of those four, with a note and no repair, since which pin the flag or wire was
written for is not known. A flag is not reported where a sheet pin or a hierarchical label
is too; a wire end is not where an end of another item but a bus's lies on it, a flag and
the Net-(<ref>-<pin>) label connect_pins wrote there apart; neither is where any reader
may join it to a pin KiCad draws for the point already. A flag carries a note: no tool
removes one by its position, so delete it in KiCad's editor, then no_connect_pin flags the
pin. A wire end's "repair" is wire_pins_to_net with the one local label name on its net
that the tool accepts, planned first; else a note, with the plan's refusal or, where the
net has no single such name, the pin the wire reaches. Nothing is written.

Args:
    schematic_path: Path to root .kicad_sch file. Optional; omit to use the configured default.