kigit 0.0.1__tar.gz

kigit-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,220 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "kigit"
+version = "0.0.1"
+description = "KiCad-semantics aware git diff and git status CLI tool"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.25.1",
+]
+authors = []
+
+[project.scripts]
+kigit = "kigit.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.153.2",
+    "pytest>=9.0.3",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["tests"]
+testpaths = ["tests"]

kigit-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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.)",
+}