kisch 1.0.0

package/README.md

@@ -0,0 +1,170 @@
+# KISCH(1)
+
+## NAME
+
+kisch - schema‑transformation tool for KiCad schematics
+
+## SYNOPSIS
+
+```
+kisch <schema.kicad_sch> [options]
+```
+
+## DESCRIPTION
+
+**kisch** is a command‑line tool for transforming KiCad schematic files.
+
+Rather than treating schematics as static drawings edited exclusively through a GUI, kisch treats a `.kicad_sch` file as a *schema* that can be programmatically rewritten.
+
+The intended workflow is to let KiCad do what it is good at (symbol placement and visual inspection), and let kisch do what GUIs are bad at: repetitive edits, precise connectivity, and large‑scale structural changes.
+
+kisch operates directly on KiCad 9 schematic files. It does not use netlists and does not rely on KiCad’s internal APIs; it reads and rewrites `.kicad_sch` files as data.
+
+## PHILOSOPHY
+
+KiCad used to treat netlists as a first‑class artifact. In modern KiCad, the schematic file itself *is* the source of truth.
+
+kisch embraces this shift.
+
+Instead of exporting, regenerating, or synchronizing netlists, kisch transforms the schematic directly. This enables workflows where:
+
+* Symbols are placed manually in KiCad
+* Connectivity is defined programmatically
+* Large schematics can be refactored safely and repeatably
+* Accidental GUI‑level wiring mistakes are avoided
+
+Think of kisch as a schema transformation pass over a KiCad schematic.
+
+## COMMAND LINE INTERFACE
+
+The schematic file is the only positional argument.
+
+```
+kisch schema.kicad_sch --script=<file> [options]
+```
+
+### Options
+
+* `--script=<file>`
+
+  JavaScript file that defines the transformation logic applied to the schematic.
+
+* `--symbol-library-path=<path>`
+
+  Path to a KiCad symbol library used when adding or resolving symbols.
+
+(Additional options may be added over time.)
+
+## SCRIPTING MODEL
+
+kisch is implemented as a Node.js CLI and executes user‑provided JavaScript to perform transformations.
+
+A script typically:
+
+* Loads the schematic structure
+* Adds or modifies symbols
+* Connects pins and nets explicitly
+* Writes the transformed schematic back to disk
+
+The exact scripting API is intentionally minimal and focused on structural operations, not rendering or layout aesthetics.
+
+### Example
+
+The following example hooks up an ESP32-C3 supermini with a CAN transceiver.
+
+```js
+export default async function (sch) {
+	await sch.use([
+		"Connector_Generic:Conn_01x04",
+		"Connector_Generic:Conn_02x02_Counter_Clockwise",
+		"Connector_Generic:Conn_02x08_Counter_Clockwise",
+		"Connector_Generic:Conn_02x04_Counter_Clockwise"
+	]);
+
+	let screw1 = sch.declare("J1", {
+		symbol: "Connector_Generic:Conn_01x04",
+		footprint: "Peabrain:ScrewTerminals_4P",
+	});
+
+	let screw2 = sch.declare("J2", {
+		symbol: "Connector_Generic:Conn_01x04",
+		footprint: "Peabrain:ScrewTerminals_4P",
+	});
+
+	let vreg = sch.declare("U1", {
+		symbol: "Connector_Generic:Conn_02x02_Counter_Clockwise",
+		footprint: "Peabrain:VoltageRegulator",
+	});
+
+	let esp32 = sch.declare("U2", {
+		symbol: "Connector_Generic:Conn_02x08_Counter_Clockwise",
+		footprint: "Peabrain:ESP32",
+	});
+
+	let tja1050 = sch.declare("U3", {
+		symbol: "Connector_Generic:Conn_02x04_Counter_Clockwise",
+		footprint: "Peabrain:TJA1050",
+	});
+
+	screw1.pin(1).connect("GND");
+	screw1.pin(2).connect("12V");
+	screw1.pin(3).connect("CANH");
+	screw1.pin(4).connect("CANL");
+
+	screw2.pin(1).connect("GND");
+	screw2.pin(2).connect("12V");
+	screw2.pin(3).connect("CANH");
+	screw2.pin(4).connect("CANL");
+
+	tja1050.pin(1).connect("5V");
+	tja1050.pin(2).connect(esp32.pin(1)); // TX
+	tja1050.pin(3).connect(esp32.pin(13)); // RX
+	tja1050.pin(4).connect("GND");
+	tja1050.pin(6).connect("CANL");
+	tja1050.pin(7).connect("CANH");
+
+	esp32.pin(16).connect("5V");
+	esp32.pin(15).connect("GND");
+
+	vreg.pin(1).connect("12V");
+	vreg.pin(2).connect("GND");
+	vreg.pin(3).connect("GND");
+	vreg.pin(4).connect("5V");
+}
+```
+
+## SUPPORTED FILES
+
+* KiCad 9 schematic files (`.kicad_sch`)
+
+## UNSUPPORTED FILES
+
+* PCB files (`.kicad_pcb`)
+* Netlists (deprecated by design)
+
+## LIMITATIONS
+
+* kisch targets **KiCad 9 only**
+* Only schematic files are supported
+* kisch cares about schematic geometry just enough to be correct, but not enough to be pretty
+* It can place new symbols so that they function correctly (e.g. without overlapping other symbols), but it does not attempt to find the best or most readable placement
+* Graphical placement quality remains the responsibility of the user
+
+## USE CASES
+
+* Programmatic net and wire generation
+* Repetitive schematic patterns
+* Safe refactoring of large schematics
+* Hybrid GUI + code‑driven design workflows
+
+## INSTALLATION
+
+kisch is a Node.js‑based CLI. Install with:
+
+```
+npm install -g kisch
+```
+
+## LICENSE
+
+GPL v3 for now... Haven't thought about it... :)

package/lab/kish-test.js

@@ -0,0 +1,35 @@
+import {openSchematic} from "../src/Schematic.js";
+import fs, {promises as fsp} from "fs";
+
+await fsp.rm("lab/kitest",{force: true, recursive: true});
+await fsp.cp("lab/kitest-org","lab/kitest",{recursive: true});
+
+let schematic=await openSchematic("lab/kitest/kitest.kicad_sch",{
+	symbolLibraryPath: "/home/micke/Repo.ext/kicad-symbols"
+});
+
+await schematic.use(
+	"Connector_Generic:Conn_01x08"
+);
+
+schematic.sym("J1").pin(1).connect(schematic.sym("J3").pin(2));
+schematic.sym("J3").pin(1).connect("GND");
+schematic.sym("J1").pin(1).connect(schematic.sym("J3").pin(1));
+
+let r=schematic.sym("J3").getBoundingRect();
+
+/*for (let i=4; i<20; i++) {
+	schematic.declare("J"+i,{
+		symbol: "Connector_Generic:Conn_01x08",
+	});
+}*/
+
+schematic.declare("J4",{
+	symbol: "Connector_Generic:Conn_01x04",
+});
+
+schematic.sym("J4").pin(1).connect("GND");
+schematic.sym("J4").pin(4).connect(schematic.sym("J3").pin(3));
+schematic.sym("J1").pin(1).connect(schematic.sym("J4").pin(1));
+
+await schematic.save();

package/lab/kitest-org/kitest.kicad_pcb

@@ -0,0 +1,2 @@
+(kicad_pcb (version 20241229) (generator "pcbnew") (generator_version "9.0")
+)

package/lab/kitest-org/kitest.kicad_prl

@@ -0,0 +1,98 @@
+{
+  "board": {
+    "active_layer": 0,
+    "active_layer_preset": "",
+    "auto_track_width": true,
+    "hidden_netclasses": [],
+    "hidden_nets": [],
+    "high_contrast_mode": 0,
+    "net_color_mode": 1,
+    "opacity": {
+      "images": 0.6,
+      "pads": 1.0,
+      "shapes": 1.0,
+      "tracks": 1.0,
+      "vias": 1.0,
+      "zones": 0.6
+    },
+    "selection_filter": {
+      "dimensions": true,
+      "footprints": true,
+      "graphics": true,
+      "keepouts": true,
+      "lockedItems": false,
+      "otherItems": true,
+      "pads": true,
+      "text": true,
+      "tracks": true,
+      "vias": true,
+      "zones": true
+    },
+    "visible_items": [
+      "vias",
+      "footprint_text",
+      "footprint_anchors",
+      "ratsnest",
+      "grid",
+      "footprints_front",
+      "footprints_back",
+      "footprint_values",
+      "footprint_references",
+      "tracks",
+      "drc_errors",
+      "drawing_sheet",
+      "bitmaps",
+      "pads",
+      "zones",
+      "drc_warnings",
+      "drc_exclusions",
+      "locked_item_shadows",
+      "conflict_shadows",
+      "shapes"
+    ],
+    "visible_layers": "ffffffff_ffffffff_ffffffff_ffffffff",
+    "zone_display_mode": 0
+  },
+  "git": {
+    "repo_type": "",
+    "repo_username": "",
+    "ssh_key": ""
+  },
+  "meta": {
+    "filename": "kitest.kicad_prl",
+    "version": 5
+  },
+  "net_inspector_panel": {
+    "col_hidden": [],
+    "col_order": [],
+    "col_widths": [],
+    "custom_group_rules": [],
+    "expanded_rows": [],
+    "filter_by_net_name": true,
+    "filter_by_netclass": true,
+    "filter_text": "",
+    "group_by_constraint": false,
+    "group_by_netclass": false,
+    "show_unconnected_nets": false,
+    "show_zero_pad_nets": false,
+    "sort_ascending": true,
+    "sorting_column": -1
+  },
+  "open_jobsets": [],
+  "project": {
+    "files": []
+  },
+  "schematic": {
+    "selection_filter": {
+      "graphics": true,
+      "images": true,
+      "labels": true,
+      "lockedItems": false,
+      "otherItems": true,
+      "pins": true,
+      "symbols": true,
+      "text": true,
+      "wires": true
+    }
+  }
+}