traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/kicad/formats.py

@@ -0,0 +1,1073 @@
+"""KiCad file-format versions: detection, and conversion between KiCad 7, 8, 9 and 10 syntax.
+
+Every KiCad file starts with ``(version YYYYMMDD)``. The readers in this package accept
+files from KiCad 6 through 10; this module maps a version stamp to a KiCad release and
+rewrites node trees between the syntax of different releases, so the design compiler
+and the edit tools can write the format of the KiCad the user actually has.
+
+What changes between releases (only what traceforge reads or writes):
+
+* KiCad 8 (schematic 20231120, board 20240108): ``generator_version``; ``uuid`` instead
+  of ``tstamp`` on board items; footprint ``fp_text reference/value`` became
+  ``property`` fields with their own position, layer and visibility; ``Sheetfile`` /
+  ``Sheetname`` footprint properties became ``(sheetfile ..)`` / ``(sheetname ..)``;
+  hidden text is ``(hide yes)``; booleans are ``yes``/``no``; ``exclude_from_sim`` on
+  symbols; ``ki_description`` became the ``Description`` field.
+* KiCad 9 (schematic 20250114, board 20241229): ``(embedded_fonts no)`` and embedded
+  files; ``(hide yes)`` also on symbol pins and pin names/numbers; new board layer
+  numbering (B.Cu is 2, technical layers odd); component classes; complex padstacks;
+  tables; rule areas.
+* KiCad 10 (schematic 20260306, board 20260206): board files no longer store net codes
+  (``(net "GND")``); symbol properties carry ``show_name`` / ``do_not_autoplace`` and a
+  property-level ``(hide yes)``; ``(power global|local)``; ``in_pos_files`` and
+  ``(body_style N)`` (was ``convert``) on symbols; ``duplicate_pad_numbers_are_jumpers``
+  on footprints; ``(tenting (front yes) (back yes))`` instead of ``(tenting front back)``;
+  jumper pad groups; variants; symbol libraries may be directories
+  (``Name.kicad_symdir``) of one-symbol files.
+
+KiCad opens files written by older releases, never newer ones, so the safe default is
+the version of the KiCad installed on the machine.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from traceforge.sexpr import Node, Sym, find, find_all
+
+# The newest file version each release writes. Index by major version.
+SCH_VERSIONS = {6: 20211123, 7: 20230121, 8: 20231120, 9: 20250114, 10: 20260306}
+PCB_VERSIONS = {6: 20211014, 7: 20221018, 8: 20240108, 9: 20241229, 10: 20260206}
+SYM_VERSIONS = {6: 20211014, 7: 20220914, 8: 20231120, 9: 20241209, 10: 20251024}
+
+# Releases traceforge can write.
+WRITABLE = (7, 8, 9, 10)
+DEFAULT_WRITE_VERSION = 7
+
+# Board files stopped storing net codes from this version (KiCad 10 development).
+PCB_NETNAME_ONLY = 20251028
+# Board files use (uuid ...) for every item from this version (KiCad 8 normalisation).
+PCB_UUID_VERSION = 20231014
+
+
+@dataclass(frozen=True)
+class FileInfo:
+    kind: str  # schematic | board | footprint | symbol_library | unknown
+    version: int
+    major: int | None
+    generator: str
+    generator_version: str
+
+    def to_dict(self) -> dict:
+        return {
+            "kind": self.kind,
+            "version": self.version,
+            "kicad": self.major,
+            "generator": self.generator,
+            "generator_version": self.generator_version,
+        }
+
+
+_KINDS = {
+    "kicad_sch": "schematic",
+    "kicad_pcb": "board",
+    "footprint": "footprint",
+    "module": "footprint",
+    "kicad_symbol_lib": "symbol_library",
+}
+
+
+def _table(kind: str) -> dict[int, int]:
+    if kind == "schematic":
+        return SCH_VERSIONS
+    if kind == "symbol_library":
+        return SYM_VERSIONS
+    return PCB_VERSIONS
+
+
+def major_for(kind: str, version: int) -> int | None:
+    """The KiCad release that writes ``version`` for this kind of file.
+
+    Development versions between two releases map to the later release, which is
+    the oldest KiCad that can open them.
+    """
+    if not version:
+        return None
+    table = _table(kind)
+    for major in sorted(table):
+        if version <= table[major]:
+            return major
+    return max(table) + 1  # newer than anything we know: a future release
+
+
+def version_for(kind: str, major: int) -> int:
+    table = _table(kind)
+    if major not in table:
+        raise ValueError(f"unknown KiCad version {major}; known: {sorted(table)}")
+    return table[major]
+
+
+_HEADER = re.compile(
+    r"^\s*\((kicad_sch|kicad_pcb|footprint|module|kicad_symbol_lib)\b"
+    r"(?:.*?\(version\s+(\d+)\))?"
+    r"(?:.*?\(generator\s+\"?([^\")]*)\"?\))?"
+    r"(?:.*?\(generator_version\s+\"?([^\")]*)\"?\))?",
+    re.S,
+)
+
+
+def file_info(path: str | Path) -> FileInfo:
+    """Read the header of a KiCad file without parsing all of it."""
+    with open(path, encoding="utf-8", errors="replace") as handle:
+        head = handle.read(1500)
+    return header_info(head)
+
+
+def header_info(text: str) -> FileInfo:
+    match = _HEADER.match(text)
+    if not match:
+        return FileInfo("unknown", 0, None, "", "")
+    kind = _KINDS[match.group(1)]
+    version = int(match.group(2) or 0)
+    return FileInfo(
+        kind, version, major_for(kind, version), match.group(3) or "", match.group(4) or ""
+    )
+
+
+def root_info(root: Node) -> FileInfo:
+    kind = _KINDS.get(str(root[0]) if root else "", "unknown")
+    version_node = find(root, "version")
+    version = int(str(version_node[1])) if version_node and len(version_node) > 1 else 0
+    generator = find(root, "generator")
+    gen_version = find(root, "generator_version")
+    return FileInfo(
+        kind,
+        version,
+        major_for(kind, version) if kind != "unknown" else None,
+        str(generator[1]) if generator and len(generator) > 1 else "",
+        str(gen_version[1]) if gen_version and len(gen_version) > 1 else "",
+    )
+
+
+def installed_major() -> int | None:
+    """Major version of the installed ``kicad-cli``, or None when KiCad is not installed."""
+    from traceforge.kicad.cli import KicadCli, KicadCliError
+
+    cli = KicadCli()
+    if not cli.available:
+        return None
+    try:
+        return cli.version()[0]
+    except KicadCliError:
+        return None
+
+
+def resolve_target(requested: int | str | None) -> int:
+    """Turn ``7``/``8``/``9``/``10``/``"auto"``/None into a version to write.
+
+    ``auto`` (and None) picks the installed KiCad's own format, capped at the newest
+    format traceforge writes (newer releases open it); without KiCad it writes the
+    KiCad 7 format, which every supported release opens.
+    """
+    if requested in (None, "", "auto"):
+        installed = installed_major()
+        if installed is None:
+            return DEFAULT_WRITE_VERSION
+        return max(min(installed, max(WRITABLE)), min(WRITABLE))
+    try:
+        major = int(str(requested).split(".")[0])
+    except ValueError as exc:
+        raise ValueError(
+            f"--kicad-version must be 7, 8, 9, 10 or auto (got {requested!r})"
+        ) from exc
+    if major > max(WRITABLE):
+        return max(WRITABLE)  # newer releases open the newest format we write
+    if major not in WRITABLE:
+        raise ValueError(f"traceforge writes KiCad {', '.join(map(str, WRITABLE))} files")
+    return major
+
+
+# ----------------------------------------------------------------------- helpers
+
+
+def is_hidden(node: Node) -> bool:
+    """Visibility of a text, field or pin in any KiCad syntax.
+
+    KiCad 6/7: a bare ``hide`` atom (in the item or in its ``effects``); KiCad 8+:
+    ``(hide yes)`` in ``effects`` (schematic) or on the item (board, KiCad 10 symbols).
+    """
+    for scope in (node, find(node, "effects")):
+        if scope is None:
+            continue
+        if any(isinstance(atom, Sym) and atom == "hide" for atom in scope[1:]):
+            return True
+        flag = find(scope, "hide")
+        if flag is not None:
+            return len(flag) == 1 or str(flag[1]) == "yes"
+    return False
+
+
+def flag(node: Node | None, key: str, default: bool = False) -> bool:
+    """``(key yes|no)``, a bare ``(key)``, or a bare ``key`` atom -> bool."""
+    if node is None:
+        return default
+    child = find(node, key)
+    if child is not None:
+        return len(child) == 1 or str(child[1]) in {"yes", "true"}
+    if any(isinstance(atom, Sym) and atom == key for atom in node[1:]):
+        return True
+    return default
+
+
+def _remove_flag(node: Node, key: str) -> None:
+    node[:] = [
+        c
+        for i, c in enumerate(node)
+        if i == 0
+        or not ((isinstance(c, Sym) and c == key) or (isinstance(c, list) and c and c[0] == key))
+    ]
+
+
+def _set_hidden(node: Node, hidden: bool, *, style: str, where: str) -> None:
+    """Rewrite visibility of ``node``.
+
+    ``style`` is ``bare`` (``hide`` atom) or ``bool`` (``(hide yes)``); ``where`` is
+    ``effects`` or ``item``. Visible items carry no flag.
+    """
+    effects = find(node, "effects")
+    _remove_flag(node, "hide")
+    if effects is not None:
+        _remove_flag(effects, "hide")
+    if not hidden:
+        return
+    token: Sym | Node = Sym("hide") if style == "bare" else [Sym("hide"), Sym("yes")]
+    if where == "effects":
+        if effects is None:
+            effects = [Sym("effects"), [Sym("font"), [Sym("size"), Sym("1.27"), Sym("1.27")]]]
+            node.append(effects)
+        effects.append(token)
+        return
+    # On the item: KiCad puts it after (layer ..) on board text, before effects otherwise.
+    anchor = None
+    for index, child in enumerate(node):
+        if isinstance(child, list) and child and child[0] in {"layer", "unlocked", "at"}:
+            anchor = index
+    position = anchor + 1 if anchor is not None else len(node)
+    node.insert(position, token)
+
+
+def _set_bool(node: Node, key: str, value: bool, *, after: tuple[str, ...] = ()) -> None:
+    """Set ``(key yes|no)``, inserting it after the last child named in ``after``."""
+    existing = find(node, key)
+    word = Sym("yes" if value else "no")
+    if existing is not None:
+        existing[1:] = [word]
+        return
+    position = len(node)
+    for index, child in enumerate(node):
+        if isinstance(child, list) and child and child[0] in after:
+            position = index + 1
+    node.insert(position, [Sym(key), word])
+
+
+def _walk_all(node: Node):
+    yield node
+    for child in node:
+        if isinstance(child, list):
+            yield from _walk_all(child)
+
+
+def _strip(node: Node, keys: set[str]) -> None:
+    """Remove every descendant node whose name is in ``keys``."""
+    node[:] = [
+        c
+        for c in node
+        if not (isinstance(c, list) and c and isinstance(c[0], str) and c[0] in keys)
+    ]
+    for child in node:
+        if isinstance(child, list):
+            _strip(child, keys)
+
+
+def _set_header(root: Node, version: int, major: int, generator_name: str | None = None) -> None:
+    version_node = find(root, "version")
+    if version_node is None:
+        version_node = [Sym("version"), Sym("0")]
+        root.insert(1, version_node)
+    version_node[1:] = [Sym(str(version))]
+    generator = find(root, "generator")
+    if generator is not None and generator_name:
+        generator[1:] = [generator_name]
+    _remove_flag(root, "generator_version")
+    if major >= 8:
+        index = root.index(generator) + 1 if generator is not None else 2
+        root.insert(index, [Sym("generator_version"), f"{major}.0"])
+
+
+def _ensure_trailing(node: Node, key: str, value: str, before: tuple[str, ...] = ()) -> None:
+    if find(node, key) is not None:
+        return
+    position = len(node)
+    for index, child in enumerate(node):
+        if isinstance(child, list) and child and child[0] in before:
+            position = index
+            break
+    node.insert(position, [Sym(key), Sym(value)])
+
+
+# -------------------------------------------------------------------- schematic
+
+
+# Symbol-level attributes, oldest first, in KiCad's order. ``since`` is the first
+# release that writes them.
+_SYMBOL_ATTRS_SINCE = {
+    "exclude_from_sim": 8,
+    "in_pos_files": 10,
+    "duplicate_pin_numbers_are_jumpers": 10,
+}
+_SCH_ONLY_SINCE = {
+    "embedded_fonts": 9,
+    "embedded_files": 9,
+    "show_name": 10,
+    "do_not_autoplace": 10,
+    "jumper_pin_groups": 10,
+    "body_styles": 10,
+}
+
+
+def convert_symbol_tree(node: Node, major: int) -> None:
+    """Rewrite a library symbol, a placed symbol, or a whole schematic/library in place."""
+    for item in list(_walk_all(node)):
+        head = str(item[0]) if item and isinstance(item[0], str) else ""
+        if head == "property":
+            _convert_sch_property(item, major)
+        elif head in {"pin_names", "pin_numbers"}:
+            _set_hidden(item, is_hidden(item), style="bool" if major >= 9 else "bare", where="item")
+        elif head == "pin" and len(item) > 2 and isinstance(item[1], Sym):
+            # library pin: (pin <type> <shape> (at ..) ...)
+            hidden = is_hidden(item)
+            _remove_flag(item, "hide")
+            if hidden:
+                token = Sym("hide") if major < 9 else [Sym("hide"), Sym("yes")]
+                position = len(item)
+                for index, child in enumerate(item):
+                    if isinstance(child, list) and child and child[0] in {"at", "length"}:
+                        position = index + 1
+                item.insert(position, token)
+        elif head in {"label", "global_label", "hierarchical_label", "text", "netclass_flag"}:
+            autoplaced = find(item, "fields_autoplaced")
+            if autoplaced is not None:
+                autoplaced[1:] = [Sym("yes")] if major >= 8 else []
+            effects = find(item, "effects")
+            if effects is not None:
+                _set_hidden(
+                    item,
+                    is_hidden(item),
+                    style="bool" if major >= 8 else "bare",
+                    where="effects",
+                )
+        elif head == "symbol" and (find(item, "lib_id") is not None or find(item, "in_bom")):
+            autoplaced = find(item, "fields_autoplaced")
+            if autoplaced is not None:
+                autoplaced[1:] = [Sym("yes")] if major >= 8 else []
+            if major >= 8 and find(item, "exclude_from_sim") is None:
+                _insert_before(item, [Sym("exclude_from_sim"), Sym("no")], ("in_bom",))
+            _convert_body_style(item, major)
+            if major >= 10 and find(item, "on_board") is not None:
+                _set_bool(
+                    item, "in_pos_files", flag(item, "in_pos_files", True), after=("on_board",)
+                )
+                if find(item, "lib_id") is None:  # library symbol
+                    _set_bool(
+                        item,
+                        "duplicate_pin_numbers_are_jumpers",
+                        flag(item, "duplicate_pin_numbers_are_jumpers"),
+                        after=("in_pos_files",),
+                    )
+        elif head == "power" and major < 10:
+            del item[1:]  # (power global) -> (power)
+        elif head == "power" and len(item) == 1:
+            item.append(Sym("global"))  # KiCad 10 names the scope of power symbols
+    # Attributes newer than the target disappear.
+    remove = {k for k, since in {**_SYMBOL_ATTRS_SINCE, **_SCH_ONLY_SINCE}.items() if since > major}
+    _strip(node, remove)
+
+
+def _convert_body_style(item: Node, major: int) -> None:
+    """Placed symbols: ``(convert N)`` up to KiCad 9, ``(body_style N)`` from KiCad 10."""
+    if find(item, "lib_id") is None:
+        return
+    old, new = ("convert", "body_style") if major >= 10 else ("body_style", "convert")
+    style = find(item, old)
+    if style is not None:
+        style[0] = Sym(new)
+    style = find(item, new)
+    if major >= 10 and style is None:
+        unit = find(item, "unit")
+        index = item.index(unit) + 1 if unit is not None else len(item)
+        item.insert(index, [Sym("body_style"), Sym("1")])
+    elif major < 10 and style is not None and str(style[1]) == "1":
+        item.remove(style)  # KiCad 9 omits the default body style
+
+
+def _insert_before(node: Node, item: Node, before: tuple[str, ...]) -> None:
+    for index, child in enumerate(node):
+        if isinstance(child, list) and child and child[0] in before:
+            node.insert(index, item)
+            return
+    node.append(item)
+
+
+def _convert_sch_property(item: Node, major: int) -> None:
+    if len(item) > 1 and major >= 8 and item[1] == "ki_description":
+        item[1] = "Description"
+    elif len(item) > 1 and major < 8 and item[1] == "Description":
+        item[1] = "ki_description"
+    if len(item) > 1 and str(item[1]) in {"Sheetfile", "Sheetname", "Sheet file", "Sheet name"}:
+        pass
+    hidden = is_hidden(item)
+    if major >= 10:
+        # KiCad 10: (at) [(hide yes)] (show_name no) (do_not_autoplace no) (effects ...).
+        # Flags already on the property keep their place.
+        effects = find(item, "effects")
+        if effects is not None:
+            _remove_flag(effects, "hide")
+        if any(isinstance(atom, Sym) and atom == "hide" for atom in item[1:]):
+            _remove_flag(item, "hide")
+        positioned = find(item, "at") is not None  # private ki_* fields have no position
+        for key in ("show_name", "do_not_autoplace"):
+            existing = find(item, key)
+            if existing is not None:
+                existing[1:] = [Sym("yes" if flag(item, key) else "no")]
+            elif positioned:
+                _insert_before(item, [Sym(key), Sym("no")], ("effects",))
+        existing = find(item, "hide")
+        if existing is not None and hidden:
+            existing[1:] = [Sym("yes")]
+        elif existing is not None:
+            item.remove(existing)
+        elif hidden:
+            _insert_before(item, [Sym("hide"), Sym("yes")], ("effects",))
+        return
+    if find(item, "effects") is None and not hidden:
+        return
+    # KiCad 8/9 keep (hide yes) in effects; KiCad 7 a bare hide in effects.
+    _set_hidden(item, hidden, style="bool" if major >= 8 else "bare", where="effects")
+
+
+def convert_schematic(root: Node, major: int) -> Node:
+    """Rewrite a ``kicad_sch`` tree to the syntax of KiCad ``major`` (7, 8, 9 or 10)."""
+    _check_writable(major)
+    _set_header(root, SCH_VERSIONS[major], major)
+    convert_symbol_tree(root, major)
+    if major >= 9:
+        for library_symbol in _library_symbols(root):
+            _ensure_trailing(library_symbol, "embedded_fonts", "no")
+        _ensure_trailing(root, "embedded_fonts", "no")
+    return root
+
+
+def _library_symbols(root: Node) -> list[Node]:
+    library = find(root, "lib_symbols")
+    if library is None:
+        return [s for s in find_all(root, "symbol") if find(s, "lib_id") is None]
+    return find_all(library, "symbol")
+
+
+def convert_symbol_library(root: Node, major: int) -> Node:
+    _check_writable(major)
+    _set_header(root, SYM_VERSIONS[major], major)
+    convert_symbol_tree(root, major)
+    if major >= 9:
+        for symbol in find_all(root, "symbol"):
+            _ensure_trailing(symbol, "embedded_fonts", "no")
+    return root
+
+
+def _check_writable(major: int) -> None:
+    if major not in WRITABLE:
+        raise ValueError(f"cannot write KiCad {major} files (supported: {WRITABLE})")
+
+
+# ------------------------------------------------------------------------ board
+
+# Layer numbering. KiCad 7/8 number copper 0..31 (B.Cu = 31) and technical layers
+# 32..49; KiCad 9 interleaves them (copper even, B.Cu = 2, technical odd).
+LEGACY_LAYER_IDS = {
+    "F.Cu": 0,
+    **{f"In{i}.Cu": i for i in range(1, 31)},
+    "B.Cu": 31,
+    "B.Adhes": 32,
+    "F.Adhes": 33,
+    "B.Paste": 34,
+    "F.Paste": 35,
+    "B.SilkS": 36,
+    "F.SilkS": 37,
+    "B.Mask": 38,
+    "F.Mask": 39,
+    "Dwgs.User": 40,
+    "Cmts.User": 41,
+    "Eco1.User": 42,
+    "Eco2.User": 43,
+    "Edge.Cuts": 44,
+    "Margin": 45,
+    "B.CrtYd": 46,
+    "F.CrtYd": 47,
+    "B.Fab": 48,
+    "F.Fab": 49,
+    **{f"User.{i}": 49 + i for i in range(1, 10)},
+}
+V9_LAYER_IDS = {
+    "F.Cu": 0,
+    "B.Cu": 2,
+    **{f"In{i}.Cu": 2 + 2 * i for i in range(1, 31)},
+    "F.Mask": 1,
+    "B.Mask": 3,
+    "F.SilkS": 5,
+    "B.SilkS": 7,
+    "F.Adhes": 9,
+    "B.Adhes": 11,
+    "F.Paste": 13,
+    "B.Paste": 15,
+    "Dwgs.User": 17,
+    "Cmts.User": 19,
+    "Eco1.User": 21,
+    "Eco2.User": 23,
+    "Edge.Cuts": 25,
+    "Margin": 27,
+    "B.CrtYd": 29,
+    "F.CrtYd": 31,
+    "B.Fab": 33,
+    "F.Fab": 35,
+    **{f"User.{i}": 37 + 2 * i for i in range(1, 46)},
+}
+
+# Layers plotted by default in generated boards: copper, paste, silk, mask, outline.
+_PLOT_LAYERS = ("Cu", "F.Paste", "B.Paste", "F.SilkS", "B.SilkS", "F.Mask", "B.Mask", "Edge.Cuts")
+
+
+def layer_selection(layers: list[str], major: int) -> str:
+    """The ``layerselection`` mask KiCad writes in ``pcbplotparams``."""
+    ids = V9_LAYER_IDS if major >= 9 else LEGACY_LAYER_IDS
+    mask = 0
+    for name in layers:
+        if name in ids:
+            mask |= 1 << ids[name]
+    if major >= 9:
+        words = [(mask >> (32 * i)) & 0xFFFFFFFF for i in range(3, -1, -1)]
+        return "0x" + "_".join(f"{w:08x}" for w in words)
+    return f"0x{mask >> 32:07x}_{mask & 0xFFFFFFFF:08x}"
+
+
+def default_plot_layers(copper: list[str]) -> list[str]:
+    return [*copper, *(name for name in _PLOT_LAYERS if name != "Cu")]
+
+
+_PCB_ONLY_SINCE = {
+    "generator_version": 8,
+    "legacy_teardrops": 8,
+    "embedded_fonts": 9,
+    "embedded_files": 9,
+    "component_classes": 9,
+    "tenting": 9,
+    "padstack": 9,
+    "duplicate_pad_numbers_are_jumpers": 10,
+    "jumper_pad_groups": 10,
+    "variants": 10,
+    "variant": 10,
+    "covering": 10,
+    "plugging": 10,
+    "capping": 10,
+    "filling": 10,
+}
+# (units ...) is also a dimension format field, so it is only removed from footprints.
+_FOOTPRINT_ONLY_SINCE = {"units": 10, "point": 10}
+_MODEL_DIR = re.compile(r"\$\{KICAD(\d+)_3DMODEL_DIR\}")
+_PLOT_BOOLEANS = {"true": "yes", "false": "no"}
+
+
+def convert_board(root: Node, major: int) -> Node:
+    """Rewrite a ``kicad_pcb`` tree to the syntax of KiCad ``major`` (7, 8, 9 or 10)."""
+    _check_writable(major)
+    source = root_info(root)
+    _set_header(root, PCB_VERSIONS[major], major)
+    general = find(root, "general")
+    if general is not None:
+        if major >= 8:
+            _set_bool(general, "legacy_teardrops", False, after=("thickness",))
+    layers = find(root, "layers")
+    if layers is not None:
+        ids = V9_LAYER_IDS if major >= 9 else LEGACY_LAYER_IDS
+        for entry in layers[1:]:
+            if isinstance(entry, list) and len(entry) > 1 and str(entry[1]) in ids:
+                entry[0] = Sym(str(ids[str(entry[1])]))
+    setup = find(root, "setup")
+    if setup is not None:
+        _convert_tenting(setup, major)
+    params = find(setup, "pcbplotparams") if setup is not None else None
+    if params is not None:
+        for item in params[1:]:
+            if (
+                isinstance(item, list)
+                and len(item) == 2
+                and str(item[1]) in {"true", "false", "yes", "no"}
+            ):
+                word = str(item[1])
+                if major >= 8:
+                    item[1] = Sym(_PLOT_BOOLEANS.get(word, word))
+                else:
+                    item[1] = Sym({"yes": "true", "no": "false"}.get(word, word))
+        selection = find(params, "layerselection")
+        renumbered = ((source.major or 7) >= 9) != (major >= 9)
+        if selection is not None and layers is not None and renumbered:
+            copper = [
+                str(e[1])
+                for e in layers[1:]
+                if isinstance(e, list) and len(e) > 1 and str(e[1]).endswith(".Cu")
+            ]
+            selection[1] = Sym(layer_selection(default_plot_layers(copper), major))
+        on_all = find(params, "plot_on_all_layers_selection")
+        if on_all is not None and renumbered:
+            on_all[1] = Sym(layer_selection([], major))
+    for footprint in [*find_all(root, "footprint"), *find_all(root, "module")]:
+        convert_footprint(footprint, major, standalone=False)
+    _convert_board_items(root, major)
+    _convert_nets(root, major, source.version)
+    remove = {k for k, since in _PCB_ONLY_SINCE.items() if since > major}
+    _strip(root, remove)
+    if major < 10:  # KiCad 10 board points
+        root[:] = [c for c in root if not (isinstance(c, list) and c and c[0] == "point")]
+    if major >= 9:
+        _ensure_trailing(root, "embedded_fonts", "no")
+    return root
+
+
+_SHAPE_FILL_V9 = {"none": "no", "solid": "yes"}
+_SHAPE_FILL_LEGACY = {"no": "none", "yes": "solid"}
+
+
+def _convert_tenting(setup: Node, major: int) -> None:
+    """Via tenting: ``(tenting front back)`` in KiCad 9, ``(tenting (front yes) (back yes))``
+    in KiCad 10, which also adds covering/plugging/capping/filling (left at defaults)."""
+    tenting = find(setup, "tenting")
+    if tenting is None:
+        return
+    sides = {}
+    for side in ("front", "back"):
+        if any(isinstance(a, Sym) and a == side for a in tenting[1:]):
+            sides[side] = True
+        else:
+            sides[side] = flag(tenting, side)
+    if major >= 10:
+        tenting[1:] = [[Sym(side), Sym("yes" if on else "no")] for side, on in sides.items()]
+    else:
+        tenting[1:] = [Sym(side) for side, on in sides.items() if on] or [Sym("none")]
+
+
+def _convert_shape_fill(item: Node, major: int) -> None:
+    """Graphic shapes: ``(fill none|solid)`` up to KiCad 8, ``(fill no|yes)`` from KiCad 9."""
+    fill = find(item, "fill")
+    if fill is None or len(fill) != 2 or isinstance(fill[1], list):
+        return
+    mapping = _SHAPE_FILL_V9 if major >= 9 else _SHAPE_FILL_LEGACY
+    fill[1] = Sym(mapping.get(str(fill[1]), str(fill[1])))
+
+
+def _convert_board_items(root: Node, major: int) -> None:
+    stamp_from, stamp_to = ("tstamp", "uuid") if major >= 8 else ("uuid", "tstamp")
+    for item in _walk_all(root):
+        if not item or not isinstance(item[0], str):
+            continue
+        head = str(item[0])
+        if head.startswith(("gr_", "fp_")):
+            _convert_shape_fill(item, major)
+        if head in {"footprint", "module", "kicad_pcb"}:
+            continue
+        # Top-level and nested item stamps (segments, vias, zones, gr_*, groups...).
+        for child in item:
+            if isinstance(child, list) and child and child[0] == stamp_from and len(child) > 1:
+                child[0] = Sym(stamp_to)
+                child[1] = str(child[1])
+        if head in {"gr_text", "gr_text_box"}:
+            _set_hidden(item, is_hidden(item), style="bool" if major >= 8 else "bare", where="item")
+        if head in {"via", "pad"}:
+            for key in ("remove_unused_layers", "keep_end_layers", "free", "locked"):
+                _normalise_flag(item, key, major)
+
+
+def _normalise_flag(node: Node, key: str, major: int) -> None:
+    """Bare ``key`` / ``(key)`` (KiCad 7) <-> ``(key yes)`` (KiCad 8+). Absent stays absent."""
+    present_bare = any(isinstance(a, Sym) and a == key for a in node[1:])
+    child = find(node, key)
+    if not present_bare and child is None:
+        return
+    value = present_bare or child is None or len(child) == 1 or str(child[1]) == "yes"
+    if major >= 8 and child is not None and not present_bare:
+        child[1:] = [Sym("yes" if value else "no")]  # keep its position
+        return
+    _remove_flag(node, key)
+    if major >= 8:
+        node.append([Sym(key), Sym("yes" if value else "no")])
+    elif value:
+        if key in {"remove_unused_layers", "keep_end_layers"}:
+            node.append([Sym(key)])
+        else:
+            node.append(Sym(key))
+
+
+def _convert_nets(root: Node, major: int, source_version: int) -> None:
+    """KiCad 10 boards store net names only; KiCad 7-9 need a net table and codes."""
+    if major >= 10:
+        _nets_by_name(root)
+        return
+    table = [n for n in find_all(root, "net") if len(n) >= 3]
+    codes = {str(n[2]): int(str(n[1])) for n in table}
+    names_in_use: list[str] = []
+    for item in _walk_all(root):
+        if item and item[0] in {"pad", "segment", "arc", "via", "zone"}:
+            net = find(item, "net")
+            if net is not None and len(net) >= 2 and not isinstance(net[1], Sym):
+                names_in_use.append(str(net[1]))
+    if not names_in_use and table:
+        return
+    if not table:
+        codes = {"": 0}
+    for name in names_in_use:
+        if name not in codes:
+            codes[name] = max(codes.values(), default=0) + 1
+    if not table:
+        # Insert the net table where KiCad keeps it: after setup, before items.
+        index = len(root)
+        for i, child in enumerate(root):
+            if (
+                isinstance(child, list)
+                and child
+                and child[0]
+                in {
+                    "net",
+                    "footprint",
+                    "module",
+                    "gr_line",
+                    "gr_rect",
+                    "gr_arc",
+                    "gr_circle",
+                    "gr_poly",
+                    "gr_text",
+                    "segment",
+                    "via",
+                    "zone",
+                }
+            ):
+                index = i
+                break
+        for offset, (name, code) in enumerate(sorted(codes.items(), key=lambda kv: kv[1])):
+            root.insert(index + offset, [Sym("net"), Sym(str(code)), name])
+    for item in _walk_all(root):
+        if not item or item[0] not in {"pad", "segment", "arc", "via", "zone"}:
+            continue
+        net = find(item, "net")
+        if net is None or len(net) < 2 or isinstance(net[1], Sym):
+            continue
+        name = str(net[1])
+        if item[0] == "pad":
+            net[1:] = [Sym(str(codes[name])), name]
+        else:
+            net[1:] = [Sym(str(codes[name]))]
+            if item[0] == "zone" and find(item, "net_name") is None:
+                item.insert(item.index(net) + 1, [Sym("net_name"), name])
+
+
+def _nets_by_name(root: Node) -> None:
+    """Drop the net table and refer to nets by name, as KiCad 10 writes boards."""
+    names = {str(n[1]): str(n[2]) for n in find_all(root, "net") if len(n) >= 3}
+    root[:] = [c for c in root if not (isinstance(c, list) and c and c[0] == "net")]
+    for item in _walk_all(root):
+        if not item or item[0] not in {"pad", "segment", "arc", "via", "zone"}:
+            continue
+        net = find(item, "net")
+        if net is None:
+            continue
+        if len(net) >= 3:  # pad: (net code "name")
+            name = str(net[2])
+        elif len(net) == 2 and isinstance(net[1], Sym):  # (net code)
+            name = names.get(str(net[1]), "")
+            net_name = find(item, "net_name")
+            if net_name is not None and len(net_name) > 1:
+                name = name or str(net_name[1])
+        else:
+            name = str(net[1]) if len(net) == 2 else ""
+        _remove_flag(item, "net_name")
+        if name:
+            net[1:] = [name]
+        else:
+            item.remove(net)  # unconnected
+
+
+def convert_footprint(node: Node, major: int, *, standalone: bool = True) -> Node:
+    """Rewrite one footprint (a library ``.kicad_mod`` or a footprint on a board)."""
+    if standalone:
+        _check_writable(major)
+        _set_header(node, PCB_VERSIONS[major], major)
+    stamp_from, stamp_to = ("tstamp", "uuid") if major >= 8 else ("uuid", "tstamp")
+    if not standalone:
+        for child in node:
+            if isinstance(child, list) and child and child[0] == stamp_from and len(child) > 1:
+                child[0] = Sym(stamp_to)
+    layer = str(find(node, "layer")[1]) if find(node, "layer") else "F.Cu"
+    fab = "B.Fab" if layer.startswith("B.") else "F.Fab"
+    new: Node = [node[0]]
+    sheet_values: dict[str, str] = {}
+    locked = False
+    for child in node[1:]:
+        if isinstance(child, Sym) and child in {"locked", "placed"}:
+            locked = locked or child == "locked"
+            if major < 8:
+                new.append(child)
+            elif child == "placed":
+                new.append([Sym("placed"), Sym("yes")])
+            continue
+        if not isinstance(child, list) or not child:
+            new.append(child)
+            continue
+        head = str(child[0])
+        if head in {"locked", "placed"}:
+            if major >= 8:
+                new.append(child if len(child) > 1 else [Sym(head), Sym("yes")])
+            elif len(child) == 1 or str(child[1]) == "yes":
+                new.append(Sym(head))
+            continue
+        if head in {"sheetname", "sheetfile"} and len(child) > 1:
+            sheet_values[head] = str(child[1])
+            continue
+        if head == "property" and len(child) > 2 and str(child[1]) in {"Sheetfile", "Sheetname"}:
+            sheet_values["sheet" + str(child[1])[5:].lower()] = str(child[2])
+            continue
+        if head == "fp_text" and len(child) > 2 and str(child[1]) in {"reference", "value"}:
+            child = _fp_text_to_property(child) if major >= 8 else child
+        elif head == "property" and len(child) > 2 and str(child[1]) in {"Reference", "Value"}:
+            child = child if major >= 8 else _property_to_fp_text(child)
+        elif head == "property" and len(child) > 2:
+            child = _footprint_field(child, major, fab)
+        if isinstance(child, list) and child and child[0] in {"fp_text", "property"}:
+            _set_hidden(
+                child, is_hidden(child), style="bool" if major >= 8 else "bare", where="item"
+            )
+            stamp = find(child, stamp_from)
+            if stamp is not None:
+                stamp[0] = Sym(stamp_to)
+        new.append(child)
+    if sheet_values:
+        position = _after_fields(new)
+        if major >= 8:
+            entries = [
+                [Sym(key), sheet_values[key]]
+                for key in ("sheetname", "sheetfile")
+                if key in sheet_values
+            ]
+        else:
+            entries = [
+                [Sym("property"), "Sheet" + key[5:], sheet_values[key]]
+                for key in ("sheetfile", "sheetname")
+                if key in sheet_values
+            ]
+        path_index = next(
+            (i for i, c in enumerate(new) if isinstance(c, list) and c and c[0] == "path"), None
+        )
+        if path_index is not None:
+            position = path_index + 1 if major >= 8 else path_index
+        new[position:position] = entries
+    if locked and major >= 8 and find(new, "locked") is None:
+        new.insert(2, [Sym("locked"), Sym("yes")])
+    node[:] = new
+    for item in _walk_all(node):
+        if item and item[0] in {
+            "fp_line",
+            "fp_rect",
+            "fp_circle",
+            "fp_arc",
+            "fp_poly",
+            "pad",
+            "fp_text_box",
+            "group",
+            "zone",
+            "dimension",
+        }:
+            for child in item:
+                if isinstance(child, list) and child and child[0] == stamp_from and len(child) > 1:
+                    child[0] = Sym(stamp_to)
+        if item and item[0] == "pad":
+            for key in ("remove_unused_layers", "keep_end_layers", "locked"):
+                _normalise_flag(item, key, major)
+        if item and str(item[0]).startswith("fp_"):
+            _convert_shape_fill(item, major)
+    remove = {
+        k for k, since in {**_PCB_ONLY_SINCE, **_FOOTPRINT_ONLY_SINCE}.items() if since > major
+    }
+    node[:] = [
+        c
+        for c in node
+        if not (isinstance(c, list) and c and isinstance(c[0], str) and c[0] in remove)
+    ]
+    for child in node:
+        if isinstance(child, list):
+            _strip(child, {k for k in remove if k not in _FOOTPRINT_ONLY_SINCE})
+    for model in find_all(node, "model"):
+        if len(model) > 1 and isinstance(model[1], str):
+            # Library 3D-model paths name the release: ${KICAD9_3DMODEL_DIR}.
+            model[1] = _MODEL_DIR.sub(
+                lambda m: (
+                    f"${{KICAD{min(int(m.group(1)), major)}_3DMODEL_DIR}}"
+                    if int(m.group(1)) > major
+                    else m.group(0)
+                ),
+                str(model[1]),
+            )
+    if major >= 10 and find(node, "duplicate_pad_numbers_are_jumpers") is None:
+        attr = find(node, "attr")
+        index = node.index(attr) + 1 if attr is not None else _after_fields(node)
+        node.insert(index, [Sym("duplicate_pad_numbers_are_jumpers"), Sym("no")])
+    if major >= 9:
+        _ensure_trailing(node, "embedded_fonts", "no", before=("model",))
+    return node
+
+
+def _after_fields(node: Node) -> int:
+    position = len(node)
+    for index, child in enumerate(node):
+        if isinstance(child, list) and child and child[0] in {"property", "fp_text", "path"}:
+            position = index + 1
+        if isinstance(child, list) and child and child[0] in {"attr", "fp_line", "pad"}:
+            break
+    return position
+
+
+def _fp_text_to_property(item: Node) -> Node:
+    kind = "Reference" if item[1] == "reference" else "Value"
+    hidden = is_hidden(item)
+    rest = [c for c in item[3:] if not (isinstance(c, Sym) and c == "hide")]
+    node: Node = [Sym("property"), kind, item[2], *rest]
+    _set_hidden(node, hidden, style="bool", where="item")
+    return node
+
+
+def _property_to_fp_text(item: Node) -> Node:
+    kind = "reference" if item[1] == "Reference" else "value"
+    hidden = is_hidden(item)
+    rest = [
+        c
+        for c in item[3:]
+        if not (
+            isinstance(c, list)
+            and c
+            and c[0] in {"hide", "unlocked", "show_name", "do_not_autoplace"}
+        )
+    ]
+    node: Node = [Sym("fp_text"), Sym(kind), item[2], *rest]
+    _set_hidden(node, hidden, style="bare", where="item")
+    return node
+
+
+def _footprint_field(item: Node, major: int, fab_layer: str) -> Node:
+    """User fields (LCSC, MPN, Datasheet...) on a footprint.
+
+    KiCad 7 stores them as ``(property "key" "value")``. KiCad 8 made them real text
+    fields with position, layer and visibility; private ``ki_*`` keys keep the short form.
+    """
+    key = str(item[1])
+    short = not any(isinstance(c, list) for c in item[3:])
+    if major < 8:
+        return [Sym("property"), item[1], item[2]]
+    if not short or key.startswith("ki_"):
+        return item
+    return [
+        Sym("property"),
+        item[1],
+        item[2],
+        [Sym("at"), Sym("0"), Sym("0"), Sym("0")],
+        [Sym("unlocked"), Sym("yes")],
+        [Sym("layer"), fab_layer],
+        [Sym("hide"), Sym("yes")],
+        [Sym("effects"), [Sym("font"), [Sym("size"), Sym("1.27"), Sym("1.27")]]],
+    ]
+
+
+# ------------------------------------------------------------------------- entry
+
+
+def convert(root: Node, major: int) -> Node:
+    """Convert any supported KiCad tree in place; returns it for chaining."""
+    head = str(root[0]) if root else ""
+    if head == "kicad_sch":
+        return convert_schematic(root, major)
+    if head == "kicad_pcb":
+        return convert_board(root, major)
+    if head in {"footprint", "module"}:
+        return convert_footprint(root, major)
+    if head == "kicad_symbol_lib":
+        return convert_symbol_library(root, major)
+    raise ValueError(f"not a KiCad file tree: {head!r}")
+
+
+def board_net_node(root: Node, name: str, *, pad: bool = False) -> Node:
+    """The ``(net ...)`` child for a new pad, track, via or zone on this board.
+
+    KiCad 10 boards refer to nets by name; older boards by code (pads also repeat
+    the name). Raises KeyError when a code-based board has no such net.
+    """
+    info = root_info(root)
+    if info.version >= PCB_NETNAME_ONLY and not any(len(n) >= 3 for n in find_all(root, "net")):
+        return [Sym("net"), name]
+    codes = {str(n[2]): str(n[1]) for n in find_all(root, "net") if len(n) >= 3}
+    if name not in codes:
+        raise KeyError(name)
+    return [Sym("net"), Sym(codes[name]), name] if pad else [Sym("net"), Sym(codes[name])]
+
+
+def board_net_names(root: Node) -> list[str]:
+    """Every net name on a board, from the net table or (KiCad 10) from the items."""
+    names = {str(n[2]) for n in find_all(root, "net") if len(n) >= 3}
+    if not names:
+        for item in _walk_all(root):
+            if item and item[0] in {"pad", "segment", "arc", "via", "zone"}:
+                net = find(item, "net")
+                if net is not None and len(net) >= 2 and not isinstance(net[1], Sym):
+                    names.add(str(net[1]))
+    names.discard("")
+    return sorted(names)
+
+
+def stamp_key(root: Node) -> str:
+    """``uuid`` (KiCad 8+) or ``tstamp`` (KiCad 6/7) for new board items."""
+    return "uuid" if root_info(root).version >= PCB_UUID_VERSION else "tstamp"
+
+
+__all__ = [
+    "DEFAULT_WRITE_VERSION",
+    "FileInfo",
+    "LEGACY_LAYER_IDS",
+    "PCB_VERSIONS",
+    "SCH_VERSIONS",
+    "SYM_VERSIONS",
+    "V9_LAYER_IDS",
+    "WRITABLE",
+    "board_net_names",
+    "board_net_node",
+    "convert",
+    "convert_board",
+    "convert_footprint",
+    "convert_schematic",
+    "convert_symbol_library",
+    "file_info",
+    "flag",
+    "header_info",
+    "installed_major",
+    "is_hidden",
+    "layer_selection",
+    "major_for",
+    "resolve_target",
+    "root_info",
+    "stamp_key",
+    "version_for",
+]