kigit 0.0.1__py3-none-any.whl

kigit/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+__version__ = "0.0.1"

kigit/cli.py

@@ -0,0 +1,157 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+import typer
+from typing import Annotated
+from pathlib import Path
+from typer import rich_utils
+
+from kigit.extractor import export_netlist
+from kigit.parser import parse_netlist_from_xml
+from kigit.file_ops import find_sch_file, cleanup_temp_data
+from kigit.git_operations import get_reference_file
+from kigit.diff import diff_netlists
+from kigit.output_generator import generate_output
+from kigit.health_checker import verify_dependencies
+from kigit.logger import configure_logger, get_logger
+from kigit.constants import STATUS_MESSAGES, LOG_DIR, SCHEMATICS_FILE_EXTENSION
+from kigit.message_printer import print_message
+import importlib.metadata
+import sys
+
+logger = get_logger()
+
+# Override color of help subtext to white.
+rich_utils.STYLE_HELPTEXT = ""
+
+app = typer.Typer(
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    help="""
+    Welcome to kigit :sparkles:
+    
+    Use [bold bright_green]kigit[/bold bright_green] or [bold bright_green]kigit --help[/bold bright_green] for general help and [bold bright_green]kigit COMMAND --help[/bold bright_green] for help on a specific command.
+    
+    :warning:  [yellow]Important:[/yellow] In order for this tool to work, committing an initial schematics file to the git repository is expected. An untracked schematics file won't work.
+    """,
+)
+
+
+# Runs before each command
+@app.callback()
+def init():
+    configure_logger()
+
+
+@app.command()
+def version():
+    """
+    Gives app version.
+    """
+    version = importlib.metadata.version("kigit")
+    print_message(f"kigit version {version}", type="Override")
+
+
+@app.command()
+def check_health():
+    """
+    Checks if all required dependencies to run kigit are present on the system.
+    """
+
+    verify_dependencies(silent=False)
+
+
+@app.command()
+def diff(
+    c1_ref: Annotated[
+        str,
+        typer.Option(
+            "--c1-ref", "-c1", help="Hash of reference commit for comparison."
+        ),
+    ] = "HEAD",
+    c2_ref: Annotated[
+        str | None,
+        typer.Option(
+            "--c2-ref",
+            "-c2",
+            help="Hash of reference commit for comparison with the first reference commit.",
+        ),
+    ] = None,
+    search_depth: Annotated[
+        int,
+        typer.Option(
+            "--search-depth",
+            "-p",
+            help="Search depth when looking up the schematics file.",
+        ),
+    ] = 2,
+    search_directory: Annotated[
+        Path,
+        typer.Option(
+            "--search-directory", "-d", help="Root path for schematics file lookup."
+        ),
+    ] = Path("."),
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Shows a more detailed diffing output."),
+    ] = False,
+):
+    """
+    Summarizes differences between two KiCad project states in a structured and understandable way, filtering out noise from formatting, ordering, and tool-generated metadata.
+
+    [deep_sky_blue1]Remarks:[/deep_sky_blue1]
+    When omitting the second reference commit, the comparison will be done between the first reference commit (default: HEAD) and the file in the working directory.
+    """
+
+    try:
+        result = verify_dependencies()
+
+        if not result:
+            raise typer.Exit(code=1)
+
+        schematics_file_path = find_sch_file(
+            search_directory, SCHEMATICS_FILE_EXTENSION, search_depth
+        )
+
+        if schematics_file_path is None:
+            print_message(
+                formatted_message=STATUS_MESSAGES[
+                    "NO_SCHEMATICS_FILE_FOUND_MESSAGE"
+                ].format(search_directory=search_directory),
+                type="Error",
+            )
+            raise typer.Exit(code=1)
+
+        c1_sch_path = get_reference_file(c1_ref, schematics_file_path)
+        c1_netlist_xml = export_netlist(c1_sch_path)
+        c1_netlist = parse_netlist_from_xml(c1_netlist_xml)
+
+        if c2_ref is None:
+            c2_sch_path = schematics_file_path
+        else:
+            c2_sch_path = get_reference_file(c2_ref, schematics_file_path)
+
+        c2_netlist_xml = export_netlist(c2_sch_path)
+        c2_netlist = parse_netlist_from_xml(c2_netlist_xml)
+
+        netlist_diff = diff_netlists(c1_netlist, c2_netlist)
+
+        print_message(generate_output(netlist_diff, verbose), type="Override")
+    except typer.Exit as e:
+        sys.exit(e.exit_code)
+    except Exception as x:
+        logger.exception(x)
+        print_message(
+            formatted_message=STATUS_MESSAGES["GENERAL_EXCEPTION_MESSAGE"].format(
+                log_dir=LOG_DIR
+            ),
+            type="Error",
+        )
+    finally:
+        cleanup_temp_data()
+
+
+if __name__ == "__main__":
+    app()

kigit/constants.py

@@ -0,0 +1,22 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+SCHEMATICS_FILE_EXTENSION = ".kicad_sch"
+PROJECT_FILE_EXTENSION = ".kicad_pro"
+IGNORED_LOOKUP_PATHS = [".git", ".history", "kigit-log"]
+NETLIST_TEMP_DIR = ".kigit_netlist_temp"
+SUBDIR_FOR_DIFFS = ".kigit_temp"
+REF_SCH_FILENAME = "schematic.kicad_sch"
+LOGGER_KEY = "c_logger"
+LOG_DIR = "kigit-log"
+LOG_FILE_NAME = "kigit.log"
+
+STATUS_MESSAGES = {
+    "NO_SCHEMATICS_FILE_FOUND_MESSAGE": "No schematics file (.kicad_sch) has been found with the current parameters. Try adjusting the search depth if the file is nested.\nRoot path used: '{search_directory}'",
+    "GENERAL_EXCEPTION_MESSAGE": "App has exited with an exception. See the '{log_dir}' folder for app logs.",
+    "GIT_NOT_FOUND_MESSAGE": "Couldn't find Git on your system. Git is required for this tool to work.",
+    "KICAD_NOT_FOUND_MESSAGE": "Couldn't find KiCad on your system. KiCad is required for this tool to work.",
+    "NO_CHANGES_TO_SHOW_MESSAGE": "No semantically meaningful changes to show.\n\n (Hint: only added, removed, changed and renamed items are shown (i.e. code changes are discarded.)",
+}

kigit/diff.py

@@ -0,0 +1,121 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from dataclasses import dataclass
+from kigit.parser import Net, Node
+from kigit.semantic_categorization import classify_change_impact
+
+
+@dataclass(frozen=True)
+class NetRename:
+    old: Net
+    new: Net
+
+
+@dataclass(frozen=True)
+class NetDiff:
+    new: Net
+    old: Net
+    impact_tags: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class NetlistDiff:
+    added: frozenset[Net]
+    removed: frozenset[Net]
+    changed: frozenset[NetDiff]
+    renamed: frozenset[NetRename]
+
+
+def _match_renames(removed, added):
+    candidates = [
+        (r, a)
+        for r in removed
+        for a in added
+        if r.nodes and set(r.nodes) == set(a.nodes)
+    ]
+
+    candidates.sort(key=lambda pair: (pair[0].name, pair[1].name))
+
+    used_old, used_new, renames = set(), set(), []
+    for r, a in candidates:
+        if r.name in used_old or a.name in used_new:
+            continue
+        renames.append(NetRename(old=r, new=a))
+        used_old.add(r.name)
+        used_new.add(a.name)
+
+    leftover_removed = frozenset(r for r in removed if r.name not in used_old)
+    leftover_added = frozenset(a for a in added if a.name not in used_new)
+    return frozenset(renames), leftover_removed, leftover_added
+
+
+def diff_netlists(old, new):
+    old_nets = {n.name: n for n in old.nets if not _is_unconnected(n)}
+    new_nets = {n.name: n for n in new.nets if not _is_unconnected(n)}
+
+    added = frozenset(new_nets[name] for name in new_nets.keys() - old_nets.keys())
+    removed = frozenset(old_nets[name] for name in old_nets.keys() - new_nets.keys())
+
+    renamed, removed, added = _match_renames(removed, added)
+
+    changed = set()
+    for name in old_nets.keys() & new_nets.keys():
+        old_net = old_nets[name]
+        new_net = new_nets[name]
+
+        changes = get_net_changes(old_net, new_net)
+        if not changes:
+            continue
+
+        impact_tags = tuple(classify_change_impact(old_net, new_net, changes))
+        changed.add(NetDiff(old=old_net, new=new_net, impact_tags=impact_tags))
+
+    return NetlistDiff(
+        added=added, removed=removed, changed=frozenset(changed), renamed=renamed
+    )
+
+
+def _is_unconnected(net):
+    return net.name.startswith("unconnected-")
+
+
+def get_net_changes(old: Net, new: Net) -> dict | None:
+    if old == new:
+        return None
+
+    changes = {}
+
+    if old.name != new.name:
+        changes["name"] = {"old": old.name, "new": new.name}
+
+    if old.net_class != new.net_class:
+        changes["net_class"] = {"old": old.net_class, "new": new.net_class}
+
+    if old.nodes != new.nodes:
+        changes["nodes"] = compare_node_lists(old.nodes, new.nodes)
+
+    return changes
+
+
+def compare_node_lists(
+    old_nodes: tuple[Node, ...], new_nodes: tuple[Node, ...]
+) -> dict:
+
+    # Assuming n.ref, n.pin can uniquely identify a node.
+    # TODO: Might change later if criteria isn't enough
+
+    old_dict = {(n.ref, n.pin): n for n in old_nodes}
+    new_dict = {(n.ref, n.pin): n for n in new_nodes}
+
+    return {
+        "added": [new_dict[key] for key in new_dict.keys() - old_dict.keys()],
+        "removed": [old_dict[key] for key in old_dict.keys() - new_dict.keys()],
+        "changed": [
+            {"old": old_dict[key], "new": new_dict[key]}
+            for key in old_dict.keys() & new_dict.keys()
+            if old_dict[key] != new_dict[key]
+        ],
+    }

kigit/extractor.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+import subprocess
+from pathlib import Path
+from kigit.constants import NETLIST_TEMP_DIR
+
+KICAD_CLI = "kicad-cli"
+
+
+def export_netlist(sch_path: Path) -> str:
+    """Runs `kicad-cli sch export netlist --format kicadxml` and returns the unparsed xml as str."""
+
+    if not sch_path.is_file():
+        raise FileNotFoundError(sch_path)
+
+    ouput_path = Path(NETLIST_TEMP_DIR) / "netlist.xml"
+    ouput_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        subprocess.run(
+            [
+                "kicad-cli",
+                "sch",
+                "export",
+                "netlist",
+                "--format",
+                "kicadxml",
+                "--output",
+                ouput_path,
+                sch_path.as_posix(),
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            check=True,
+        ).stdout
+
+        with open(ouput_path) as file:
+            return file.read()
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"Got an invalid response when calling kicad-cli:\n Error:\n {e.stderr}"
+        )

kigit/file_ops.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from os import walk
+from os.path import join
+from pathlib import Path
+from shutil import rmtree
+from kigit.constants import (
+    PROJECT_FILE_EXTENSION,
+    SUBDIR_FOR_DIFFS,
+    NETLIST_TEMP_DIR,
+    IGNORED_LOOKUP_PATHS,
+)
+
+
+def _find_first_file(root_path: Path, extension: str, depth: int) -> Path | None:
+    """Searches the current directory with the provided depth for the first file that matches the provided extension"""
+
+    if not extension.startswith("."):
+        extension = "." + extension
+
+    for dirpath, dirs, files in walk(root_path):
+        current_dir = Path(dirpath).relative_to(root_path)
+
+        current_depth = len(current_dir.parts)
+        if current_depth > depth:
+            dirs.clear()
+            continue
+
+        dirs[:] = [d for d in dirs if not should_ignore_path(current_dir / d)]
+
+        for file in files:
+            if file.endswith(extension):
+                return Path(join(dirpath, file))
+
+    return None
+
+
+def find_sch_file(root_path: Path, extension: str, depth: int) -> Path | None:
+    """Searches the current directory with the provided depth for the first file that matches the provided extension"""
+
+    pro_file_path: Path | None = _find_first_file(
+        root_path=root_path, extension=PROJECT_FILE_EXTENSION, depth=depth
+    )
+    if pro_file_path is None:
+        return None
+
+    if not extension.startswith("."):
+        extension = "." + extension
+
+    for dirpath, dirs, files in walk(root_path):
+        current_dir = Path(dirpath).relative_to(root_path)
+
+        current_depth = len(current_dir.parts)
+        if current_depth > depth:
+            dirs.clear()
+            continue
+
+        dirs[:] = [d for d in dirs if not should_ignore_path(current_dir / d)]
+
+        for file in files:
+            if file.endswith(extension) and Path(file).stem == pro_file_path.stem:
+                return Path(join(dirpath, file))
+
+    return None
+
+
+def should_ignore_path(path: Path) -> bool:
+    for ignored in IGNORED_LOOKUP_PATHS:
+        ignored_path = Path(ignored)
+        try:
+            path.relative_to(ignored_path)
+            return True
+        except ValueError:
+            # Not relative, continue
+            pass
+
+    return False
+
+
+def cleanup_temp_data():
+    if Path.exists(Path(SUBDIR_FOR_DIFFS)):
+        rmtree(SUBDIR_FOR_DIFFS, ignore_errors=True)
+
+    if Path.exists(Path(NETLIST_TEMP_DIR)):
+        rmtree(NETLIST_TEMP_DIR, ignore_errors=True)

kigit/git_operations.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+import shutil
+from pathlib import Path
+from kigit.constants import SUBDIR_FOR_DIFFS, REF_SCH_FILENAME
+import subprocess
+
+
+def get_reference_file(ref: str, file_path: Path) -> Path:
+    out_file_path = Path(SUBDIR_FOR_DIFFS) / REF_SCH_FILENAME
+
+    try:
+        result = subprocess.run(
+            ["git", "show", f"{ref}:{Path(file_path).as_posix()}"],
+            text=True,
+            check=True,
+            capture_output=True,
+            encoding="utf-8",
+        )
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"Failed to retrieve file '{file_path}' from git ref '{ref}': {e.stderr}"
+        )
+
+    out_file_path.parent.mkdir(parents=True, exist_ok=True)
+    out_file_path.write_text(result.stdout, encoding="utf-8")
+
+    return out_file_path

kigit/health_checker.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+import subprocess
+from kigit.constants import STATUS_MESSAGES
+from kigit.message_printer import print_message
+
+
+def check_git() -> bool:
+    try:
+        subprocess.run(
+            ["git", "--version"],
+            capture_output=True,
+            check=True,
+            text=True,
+            encoding="utf-8",
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+    return True
+
+
+def check_kicad() -> bool:
+    try:
+        subprocess.run(
+            ["kicad-cli", "--version"],
+            capture_output=True,
+            check=True,
+            text=True,
+            encoding="utf-8",
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+    return True
+
+
+def verify_dependencies(silent: bool = True) -> bool:
+    has_git = check_git()
+    has_kicad = check_kicad()
+    has_errors = False
+
+    if not has_git:
+        print_message(STATUS_MESSAGES["GIT_NOT_FOUND_MESSAGE"], type="Error")
+        has_errors = True
+
+    if not has_kicad:
+        print_message(STATUS_MESSAGES["KICAD_NOT_FOUND_MESSAGE"], type="Error")
+        has_errors = True
+
+    if not silent and not has_errors:
+        print_message("All dependencies OK. Ready to use kigit.", type="Success")
+
+    return not has_errors

kigit/logger.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from kigit.constants import LOG_DIR, LOGGER_KEY, LOG_FILE_NAME
+from pathlib import Path
+
+import logging
+
+
+def get_logger():
+    return logging.getLogger(LOGGER_KEY)
+
+
+def ensure_log_path_exists():
+    path = Path(".") / LOG_DIR
+
+    if not path.exists():
+        path.mkdir(exist_ok=True)
+
+
+def configure_logger():
+    ensure_log_path_exists()
+    logger = get_logger()
+
+    # Remove all present handlers to avoid duplicate logging messages
+    logger.handlers.clear()
+
+    path = Path(".") / LOG_DIR / LOG_FILE_NAME
+    logging.basicConfig(
+        format="\n[%(levelname)s]\nDate: %(asctime)s\nFile: (%(filename)s)\nLine: %(lineno)d\nFunction: %(funcName)s\nLog Message: %(message)s\n",
+        handlers=[logging.FileHandler(Path(path))],
+    )

kigit/message_printer.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from typing import Literal
+
+import typer
+
+
+def print_message(
+    formatted_message: str,
+    type: Literal[
+        "Error", "Success", "Warning", "Information", "Override"
+    ] = "Override",
+):
+    if type == "Error":
+        color = typer.colors.BRIGHT_RED
+    elif type == "Warning":
+        color = typer.colors.BRIGHT_YELLOW
+    elif type == "Success":
+        color = typer.colors.BRIGHT_GREEN
+    elif type == "Information":
+        color = typer.colors.BRIGHT_BLUE
+    else:
+        color = typer.colors.WHITE
+
+    if type == "Override":
+        # Use the colors that are specified in the message
+        typer.echo(typer.style(formatted_message))
+    else:
+        typer.echo(typer.style(formatted_message, color), err=type == "Error")

kigit/output_generator.py

@@ -0,0 +1,243 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+import typer
+from typing import Optional
+from kigit.parser import Node, Net
+from kigit.diff import NetRename, NetlistDiff, get_net_changes, NetDiff
+from kigit.constants import STATUS_MESSAGES
+from kigit.semantic_categorization import classify_net_properties
+
+SECTION_SEPARATOR = "========================================="
+
+
+def format_pin_function(pin_function: Optional[str]) -> str:
+    """Extract and format pin function from KiCad format."""
+    if not pin_function:
+        return ""
+
+    base_function = (
+        pin_function[: pin_function.rfind("_")] if "_" in pin_function else pin_function
+    )
+    return f"with {base_function} function "
+
+
+def format_node(node: Node, prefix: str = "") -> str:
+    """Format a single node for display."""
+    pin_func = format_pin_function(node.pin_function)
+    return f"{prefix}Element {node.ref} on pin {node.pin} {pin_func}and {node.pintype} type."
+
+
+def format_net_nodes(nodes: tuple[Node, ...], prefix: str = "") -> str:
+    """Format all nodes in a net."""
+    return "\n".join(format_node(node, prefix) for node in nodes)
+
+
+def generate_net_section(nets: frozenset[Net], section_type: str) -> str:
+    if not nets:
+        return ""
+
+    color_map = {
+        "added": typer.colors.GREEN,
+        "removed": typer.colors.RED,
+    }
+    color = color_map.get(section_type, typer.colors.WHITE)
+
+    lines = []
+    for net in nets:
+        lines.append(typer.style(f"\tNet '{net.name}':", fg=color))
+        for node in net.nodes:
+            prefix = "+ " if section_type == "added" else "- "
+            lines.append(f"\t\t{prefix}{format_node(node)}")
+
+    header = typer.style(f"{section_type.title()} Nets:\n", fg=color, bold=True)
+    body = "\n".join(lines) + "\n"
+    return header + body + "\n" + SECTION_SEPARATOR + "\n\n"
+
+
+def format_node_change(node_info: dict) -> str:
+    """Format a single changed node."""
+    old, new = node_info["old"], node_info["new"]
+    changes = []
+
+    if old.ref != new.ref:
+        changes.append(f"ref {old.ref} → {new.ref}")
+    if old.pin != new.pin:
+        changes.append(f"pin {old.pin} → {new.pin}")
+    if old.pin_function != new.pin_function:
+        changes.append(f"pin_function {old.pin_function} → {new.pin_function}")
+    if old.pintype != new.pintype:
+        changes.append(f"pintype {old.pintype} → {new.pintype}")
+
+    return ", ".join(changes) if changes else "no significant changes"
+
+
+def generate_node_changes(node_changes: dict) -> str:
+    """Generate output for node changes (added, removed, changed)."""
+    lines = []
+
+    if node_changes.get("added"):
+        lines.append("\t\tAdded nodes:")
+        for node in node_changes["added"]:
+            lines.append(
+                typer.style(
+                    f"\t\t\t+ {node.ref} pin {node.pin} ({node.pin_function or 'no function'}, {node.pintype})",
+                    fg=typer.colors.GREEN,
+                )
+            )
+
+    if node_changes.get("changed"):
+        lines.append("\t\tChanged nodes:")
+        for change in node_changes["changed"]:
+            lines.append(
+                typer.style(
+                    f"\t\t\t* {format_node_change(change)}", fg=typer.colors.YELLOW
+                )
+            )
+
+    if node_changes.get("removed"):
+        lines.append("\t\tRemoved nodes:")
+        for node in node_changes["removed"]:
+            lines.append(
+                typer.style(
+                    f"\t\t\t- {node.ref} pin {node.pin} ({node.pin_function or 'no function'}, {node.pintype})",
+                    fg=typer.colors.RED,
+                )
+            )
+
+    return "\n".join(lines)
+
+
+def generate_changed_section(changed_diffs: frozenset[NetDiff]) -> str:
+    """Generate output for changed nets."""
+    if not changed_diffs:
+        return ""
+
+    lines = [typer.style("Changed Nets:", fg=typer.colors.YELLOW, bold=True)]
+
+    for net_diff in sorted(changed_diffs, key=lambda nd: nd.old.name):
+        old_net = net_diff.old
+        new_net = net_diff.new
+
+        changes = get_net_changes(old_net, new_net)
+        if not changes:
+            continue
+
+        lines.append(
+            typer.style(
+                f"\tNet '{old_net.name}':",
+                fg=typer.colors.YELLOW,
+            )
+        )
+
+        properties = classify_net_properties(new_net)
+        if properties:
+            lines.append(f"\t\t* properties: {', '.join(properties)}")
+
+        if net_diff.impact_tags:
+            lines.append(
+                typer.style(
+                    f"\t\t* impact: {', '.join(net_diff.impact_tags)}",
+                    fg=typer.colors.CYAN,
+                )
+            )
+
+        for field_name, change_info in changes.items():
+            if field_name == "nodes":
+                lines.append(generate_node_changes(change_info))
+            else:
+                lines.append(
+                    f"\t\t* {field_name}: {change_info['old']} → {change_info['new']}"
+                )
+
+    body = "\n".join(lines) + "\n"
+
+    return body + "\n" + SECTION_SEPARATOR + "\n"
+
+
+def generate_renamed_section(net_renames: frozenset[NetRename]) -> str:
+    """Generate output for changed nets."""
+    if not net_renames:
+        return ""
+
+    lines = [typer.style("Renamed Nets:", fg=typer.colors.BRIGHT_MAGENTA, bold=True)]
+
+    for net_rename in net_renames:
+        old_net = net_rename.old
+        new_net = net_rename.new
+
+        lines.append(
+            typer.style(
+                f"\tNet renamed: '{old_net.name}' -> '{new_net.name}'",  # dont need (code: {old_net.code}) - Ilya
+                typer.colors.BRIGHT_MAGENTA,
+            )
+        )
+
+    body = "\n".join(lines) + "\n"
+    return body + "\n" + SECTION_SEPARATOR + "\n"
+
+
+def generate_output(netlist_diff: NetlistDiff, verbose: bool) -> str:
+    """Generate human-readable output from netlist differences."""
+
+    if not verbose:
+        return _generate_brief_output(netlist_diff)
+
+    sections = []
+
+    added_section = generate_net_section(netlist_diff.added, "added")
+    removed_section = generate_net_section(netlist_diff.removed, "removed")
+    changed_section = generate_changed_section(netlist_diff.changed)
+    renamed_secion = generate_renamed_section(netlist_diff.renamed)
+
+    if added_section:
+        sections.append(added_section)
+    if removed_section:
+        sections.append(removed_section)
+    if changed_section:
+        sections.append(changed_section)
+    if renamed_secion:
+        sections.append(renamed_secion)
+
+    return (
+        "".join(sections) if sections else STATUS_MESSAGES["NO_CHANGES_TO_SHOW_MESSAGE"]
+    )
+
+
+def _generate_brief_output(netlist_diff: NetlistDiff) -> str:
+    lines = []
+    if netlist_diff.added:
+        lines.append(
+            typer.style(
+                f"+ {len(netlist_diff.added)} net(s) added",
+                fg=typer.colors.GREEN,
+                bold=True,
+            )
+        )
+    if netlist_diff.removed:
+        lines.append(
+            typer.style(
+                f"- {len(netlist_diff.removed)} net(s) removed",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+        )
+    if netlist_diff.changed:
+        lines.append(
+            typer.style(
+                f"~ {len(netlist_diff.changed)} net(s) changed",
+                fg=typer.colors.YELLOW,
+                bold=True,
+            )
+        )
+    if netlist_diff.renamed:
+        lines.append(
+            typer.style(
+                f"~ {len(netlist_diff.renamed)} net(s) renamed",
+                fg=typer.colors.BRIGHT_MAGENTA,
+                bold=True,
+            )
+        )
+    return "\n".join(lines) if lines else STATUS_MESSAGES["NO_CHANGES_TO_SHOW_MESSAGE"]

kigit/parser.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from dataclasses import dataclass, field
+from typing import Optional
+import xml.etree.ElementTree as ET
+
+
+@dataclass(frozen=True)
+class Node:
+    ref: str
+    pin: str
+    pin_function: Optional[str]
+    pintype: str
+
+
+@dataclass(frozen=True)
+class Net:
+    code: str = field(compare=False)
+    name: str
+    net_class: str
+    nodes: tuple["Node", ...]
+
+
+@dataclass(frozen=True)
+class Netlist:
+    nets: tuple["Net", ...]
+
+
+def parse_netlist_from_xml(xml: str) -> Netlist:
+    root = ET.fromstring(xml)
+
+    nets_tag = root.find("nets")
+    if nets_tag is None:
+        raise ValueError("No <nets> tag found in netlist XML.")
+
+    nets = []
+    for net_el in nets_tag.findall("net"):
+        a = net_el.attrib
+        code = a.get("code") or ""
+        nodes = tuple(
+            Node(
+                ref=ne.attrib.get("ref") or "",
+                pin=ne.attrib.get("pin") or "",
+                pin_function=ne.attrib.get("pinfunction"),
+                pintype=ne.attrib.get("pintype") or "",
+            )
+            for ne in net_el.findall("node")
+        )
+        nets.append(
+            Net(
+                code=code,
+                name=a.get("name") or f"<net {code}>",
+                net_class=a.get("class") or "",
+                nodes=nodes,
+            )
+        )
+
+    return Netlist(nets=tuple(nets))

kigit/semantic_categorization.py

@@ -0,0 +1,74 @@
+# Copyright (c) 2026 RUB-SELAB-2026
+#
+# Licensed under the MIT License.
+# See the LICENSE file in the project root for full license information.
+
+from kigit.parser import Net
+
+CRITICAL_NET_NAMES = {"GND", "VCC", "+3V3", "+5V", "+24V", "VIN"}
+POWER_NAME_FRAGMENTS = ("VCC", "3V3", "5V", "24V", "VIN")
+HIGH_SPEED_KEYWORDS = {"CLK", "CLOCK", "SPI", "USB", "I2C", "UART", "TX", "RX"}
+
+MEDIUM_CONNECTIVITY_THRESHOLD = 5
+HIGH_CONNECTIVITY_THRESHOLD = 10
+
+
+def _is_power_net(name: str) -> bool:
+    return any(fragment in name for fragment in POWER_NAME_FRAGMENTS)
+
+
+def _is_critical_net(name: str) -> bool:
+    return name in CRITICAL_NET_NAMES or _is_power_net(name)
+
+
+def classify_net_properties(net: Net) -> list[str]:
+    """Describe the *nature* of a net (power, ground, high-speed, ...)."""
+    tags: list[str] = []
+    name = net.name.upper()
+
+    if _is_critical_net(name):
+        tags.append("critical-net")
+    if _is_power_net(name):
+        tags.append("power-net")
+    if "GND" in name:
+        tags.append("ground-net")
+    if any(keyword in name for keyword in HIGH_SPEED_KEYWORDS):
+        tags.append("high-speed-net")
+
+    node_count = len(net.nodes)
+    if node_count > HIGH_CONNECTIVITY_THRESHOLD:
+        tags.append("high-connectivity")
+    elif node_count > MEDIUM_CONNECTIVITY_THRESHOLD:
+        tags.append("medium-connectivity")
+    if node_count == 0:
+        tags.append("empty-net")
+
+    return tags
+
+
+def classify_change_impact(old: Net, new: Net, net_changes: dict | None) -> list[str]:
+    """Describe the *meaning* of a change."""
+    tags: list[str] = []
+
+    if _is_critical_net(old.name.upper()) or _is_critical_net(new.name.upper()):
+        tags.append("critical-net-change")
+
+    if len(new.nodes) > len(old.nodes):
+        tags.append("connectivity-increased")
+    elif len(new.nodes) < len(old.nodes):
+        tags.append("connectivity-decreased")
+
+    if net_changes and "nodes" in net_changes:
+        nodes_diff = net_changes["nodes"]
+        if nodes_diff.get("added"):
+            tags.append("node-added")
+        if nodes_diff.get("removed"):
+            tags.append("node-removed")
+        for change in nodes_diff.get("changed", []):
+            old_node, new_node = change["old"], change["new"]
+            if old_node.pin_function != new_node.pin_function:
+                tags.append("pin-function-changed")
+            if old_node.pintype != new_node.pintype:
+                tags.append("pin-type-changed")
+
+    return sorted(set(tags))

kigit-0.0.1.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.3
+Name: kigit
+Version: 0.0.1
+Summary: KiCad-semantics aware git diff and git status CLI tool
+Requires-Dist: typer>=0.25.1
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# kigit
+
+**KiCad-aware `git diff` and `git status` for your schematics.**
+
+[![PyPI version](https://img.shields.io/pypi/v/kigit.svg)](https://pypi.org/project/kigit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/kigit.svg)](https://pypi.org/project/kigit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`kigit` is a command-line tool that makes Git output for [KiCad](https://www.kicad.org/)
+projects readable. Raw `git diff` on a `.kicad_sch` file is dominated by formatting,
+re-ordering, and tool-generated metadata, so it tells you *that* a file changed but not
+*what* meaningfully changed. `kigit` cuts through that noise and reports the change in
+electrical terms instead: which nets were added, removed, renamed, or rewired.
+
+> **Status: early preview (0.0.1).** This is the first public release. It focuses on the
+> schematic netlist and intentionally does a small thing well. Interfaces and output may
+> change in future versions. Bug reports and feedback are very welcome.
+
+---
+
+## What it does
+
+`kigit` answers questions a plain text diff struggles with, such as *"Did the wiring
+actually change, or is this just KiCad reshuffling the file?"*
+
+For the schematic in your repository it:
+
+- locates the schematic via your project (`.kicad_pro`) file,
+- exports the **netlist** for two project states using KiCad's own `kicad-cli`,
+- compares the two netlists semantically, ignoring text-level noise, and
+- prints a structured, color-coded summary of the real changes.
+
+It reports nets that were **added**, **removed**, **changed** (nodes/pins added,
+removed, or modified; net-class changes), and **renamed** (a net whose connections are
+unchanged but whose name differs). Each changed net is annotated with semantic tags such
+as `power-net`, `ground-net`, `critical-net`, `high-speed-net`, connectivity level, and
+impact tags like `connectivity-increased`, `node-added`, or `pin-function-changed`.
+Purely cosmetic differences and unconnected (`unconnected-*`) nets are filtered out.
+
+### Not in scope yet
+
+To set expectations for 0.0.1, the following are **not** analyzed yet and are planned for
+later releases:
+
+- component **value** changes (e.g. a resistor going from 10k to 4.7k),
+- **PCB layout** (`.kicad_pcb`) changes,
+- further changes
+
+---
+
+## Requirements
+
+`kigit` orchestrates the tools you already use; it does not reimplement them.
+
+- **Python** 3.10 or newer.
+- **Git**, available on your `PATH`.
+- **KiCad 10.x**, with the bundled **`kicad-cli`** available on your `PATH`.
+  (`kicad-cli` ships with the standard KiCad installation on Windows, Linux, and macOS.)
+
+`kigit` is cross-platform and runs on **Windows and Linux** (and other platforms where
+Python, Git, and KiCad are available). Run `kigit check-health` at any time to confirm
+your environment is ready.
+
+---
+
+## Installation
+
+From PyPI with `pip`:
+
+```bash
+pip install kigit
+```
+
+Or as an isolated tool with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install kigit
+```
+
+---
+
+## Quick start
+
+> **Prerequisite:** your schematic must be committed to Git at least once. `kigit`
+> retrieves historical versions with `git show`, so an untracked schematic cannot be
+> diffed.
+
+```bash
+# Compare your working changes against the last commit (the "status" use case):
+kigit diff
+
+# Compare two commits, branches, or tags:
+kigit diff -c1 main -c2 my-feature-branch
+
+# See full detail instead of a summary:
+kigit diff --verbose
+
+# Confirm Git and KiCad are installed and reachable:
+kigit check-health
+```
+
+---
+
+## Commands
+
+Run `kigit` or `kigit --help` for general help, and `kigit COMMAND --help` for details on
+a specific command.
+
+### `kigit diff`
+
+Summarizes the differences between two KiCad project states, filtering out noise from
+formatting, ordering, and tool-generated metadata.
+
+| Option | Alias | Default | Description |
+| --- | --- | --- | --- |
+| `--c1-ref` | `-c1` | `HEAD` | Git reference (commit, branch, or tag) used as the **first** state for comparison. |
+| `--c2-ref` | `-c2` | *none* | Git reference used as the **second** state. When omitted, the first ref is compared against the **working-directory** schematic. |
+| `--search-depth` | `-p` | `2` | How many directory levels to descend when locating the schematic file. |
+| `--search-directory` | `-d` | `.` | Root directory for the schematic file lookup. |
+| `--verbose` | `-v` | `false` | Show a detailed, per-net and per-node breakdown instead of a brief count summary. |
+
+Behavior of the default invocation: with no `-c2`, `kigit diff` compares the first
+reference (default `HEAD`) against the current schematic on disk — i.e. "what have I
+changed since my last commit?".
+
+### `kigit check-health`
+
+Verifies that all required dependencies (Git and `kicad-cli`) are present on the system
+and reports any that are missing.
+
+### `kigit version`
+
+Prints the installed `kigit` version.
+
+---
+
+## Example output
+
+> The examples below are illustrative; actual output is color-coded in your terminal.
+
+Brief summary (default):
+
+```text
++ 3 net(s) added
+- 1 net(s) removed
+~ 2 net(s) changed
+~ 1 net(s) renamed
+```
+
+Detailed view (`--verbose`), showing how a changed net is annotated:
+
+```text
+Changed Nets:
+ Net '+5V':
+  * properties: critical-net, power-net, medium-connectivity
+  * impact: connectivity-increased, critical-net-change, node-added
+  Added nodes:
+   + U3 pin 4 (VCC, power_in)
+```
+
+When nothing meaningful changed:
+
+```text
+No semantically meaningful changes to show.
+
+ (Hint: only added, removed, changed and renamed items are shown (i.e. code changes are discarded.)
+```
+
+---
+
+## How it works
+
+1. **Locate** — find the project's `.kicad_pro` and the matching `.kicad_sch` within the
+   configured search directory and depth.
+2. **Retrieve** — for each requested Git reference, extract that version of the schematic
+   with `git show <ref>:<path>` into a temporary working area.
+3. **Export** — run `kicad-cli sch export netlist --format kicadxml` on each version to
+   produce a netlist in KiCad XML.
+4. **Parse** — read the `<nets>` section into an immutable model of nets and their
+   nodes (component reference, pin, pin function, pin type).
+5. **Diff** — compute added / removed / changed / renamed nets, ignoring net codes and
+   `unconnected-*` nets, and detect renames by matching nets with identical connections.
+6. **Classify & report** — tag each net and change with semantic categories and print a
+   readable summary.
+
+---
+
+## Logs and temporary files
+
+- Diagnostic logs are written to a `kigit-log/` directory in the current working
+  directory. If a run fails unexpectedly, this is the first place to look.
+- Temporary working data (`.kigit_temp/`, `.kigit_netlist_temp/`) is created during a run
+  and cleaned up automatically afterwards.
+
+You may wish to add `kigit-log/`, `.kigit_temp/`, and `.kigit_netlist_temp/` to your
+`.gitignore`.
+
+---
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for packaging, [pytest](https://docs.pytest.org/)
+and [Hypothesis](https://hypothesis.readthedocs.io/) for testing, and
+[Typer](https://typer.tiangolo.com/) for the command-line interface.
+
+---
+
+## License
+
+`kigit` is released under the [MIT License](LICENSE).
+
+---
+
+## Acknowledgements
+
+`kigit` is developed as a Software Engineering course project for and with help from 
+Auto-Intern GmbH, whose hardware team uses KiCad and Git for industrial monitoring
+systems. The goal is to help engineers make better commit decisions and to keep project
+history readable, with the intention of maintaining it as an open-source tool for the
+wider KiCad community.

kigit-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+kigit/__init__.py,sha256=Er02rv_MVlDoGZxPg9k32_6Lmlz3nY09F12A8NvW4X0,168
+kigit/cli.py,sha256=M_s2TVGnVuvR9DNuEzPtgcSvPVgUxQlSfEE5dQi0uPU,4784
+kigit/constants.py,sha256=WDLKbiPJ4veusBMLa30XKE5huRUpmw3YYn2OCMPw8Wg,1216
+kigit/diff.py,sha256=gaQHWULXJ3-ImNyECztcVEZpyUSxK7JwhX1QP6Imzb4,3470
+kigit/extractor.py,sha256=yz-xEV3eeGEAvA-KHJ9tBbQrDKU7Q-GUUYViqCQF37A,1278
+kigit/file_ops.py,sha256=d2yyDHRRYqfYVsVoeludo90vD5-JTCtWD8Ga3XipCwU,2581
+kigit/git_operations.py,sha256=CeZAisab3l1fn3YXIwy5fe6HPYBilPx0nvQ6Wmbz0vU,940
+kigit/health_checker.py,sha256=xMc1cMJ397DDD6c7wvulUH5n5y5i7yslCxCfY71prkA,1431
+kigit/logger.py,sha256=osAgd6q8RjU6wB6qYws1S7aSmztbkOXZjEvUo7JU9YI,893
+kigit/message_printer.py,sha256=c5inyH9lUsLwfqGvhE4b2kN4dQZ3L_971rWPGhiXS2M,893
+kigit/output_generator.py,sha256=V1x-XMzIt_Q_rUrv1zYibA-A3csEX5G82eJZaBwy2Yo,7805
+kigit/parser.py,sha256=hgcnnO1XuT_BV2LhLIxNgGHxNPGuBPjgfDJDb0QNyXk,1472
+kigit/semantic_categorization.py,sha256=TGit2Q8sXcEO7LRnrS8qbLeYiuiZ4sLK12h632-i4Ak,2487
+kigit-0.0.1.dist-info/WHEEL,sha256=1uB4K0BXH0KDzZOLGYqB4NnSgGon9oosxpA-QGkDuEA,80
+kigit-0.0.1.dist-info/entry_points.txt,sha256=92yizwoTA61iqADxwmHAfqdTWVEXavZkjDyHcr_KlCY,41
+kigit-0.0.1.dist-info/METADATA,sha256=5cXL3PnTQ8qgRTzjrt-JrS9bqGlLGBBOdxyQeGWI9mo,7843
+kigit-0.0.1.dist-info/RECORD,,

kigit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.9
+Root-Is-Purelib: true
+Tag: py3-none-any

kigit-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kigit = kigit.cli:app
+