kisch 1.0.0 → 1.0.2

package/README.md

@@ -2,12 +2,12 @@
 
 ## NAME
 
-kisch - schema‑transformation tool for KiCad schematics
+kisch — schema‑transformation tool for KiCad schematics
 
 ## SYNOPSIS
 
 ```
-kisch <schema.kicad_sch> [options]
+kisch [options] [inout.kicad_sch]
 ```
 
 ## DESCRIPTION
@@ -33,103 +33,116 @@ Instead of exporting, regenerating, or synchronizing netlists, kisch transforms
 * 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.
+Think of kisch as a **schema transformation pass** over a KiCad schematic.
 
 ## COMMAND LINE INTERFACE
 
-The schematic file is the only positional argument.
+kisch arguments can be understood along **two axes**:
+
+|               | Input             | Output            |
+|---------------|-----------------|-----------------|
+| **Schematic** | `-i` / positional | `-o` / positional |
+| **JavaScript**| `-s`             | `-e`             |
+
+- Positional argument `[inout.kicad_sch]` is a shorthand for both `-i` and `-o`.
+- Flags cannot conflict; e.g., positional cannot be used together with `-i` or `-o`.
+- Filling a quadrant defines the pipeline: kisch reads that representation, optionally transforms it, and emits the target representation.
+
+### Arguments
 
 ```
-kisch schema.kicad_sch --script=<file> [options]
+[inout.kicad_sch]       Schematic to be used as input and output (shorthand for -i and -o)
 ```
 
 ### Options
 
-* `--script=<file>`
+* `-i, --input <input.kicad_sch>`  
+  Input schematic.
+
+* `-o, --output <output.kicad_sch>`  
+  Output schematic.
+
+* `-L, --symbol-dir <path>`  
+  Where to find KiCad symbols.
+
+* `-s, --script <script.js>`  
+  Input JavaScript script to apply to schematic.
+
+* `-e, --emit <script.js>`  
+  Emit JavaScript script based on schematic.
+
+* `-D, --define <key=value>`  
+  Define variable for the script.
 
-  JavaScript file that defines the transformation logic applied to the schematic.
+* `-q, --quiet`  
+  No output except errors.
+
+* `-h, --help`  
+  Display help.
+
+* `--version`  
+  Show version.
+
+### Examples
+
+**Transform existing schematic in-place:**
+```
+$ kisch design.sch --script x.js
+```
+
+**Generate script for later use:**
+```
+$ kisch --input fresh.sch --emit x.js
+```
 
-* `--symbol-library-path=<path>`
+**Load from one file, apply script, and save in another file:**
+```
+$ kisch --input template.sch --script x.js --output out.sch
+```
 
-  Path to a KiCad symbol library used when adding or resolving symbols.
+**Dry-run: just load schematic and apply script, do not save:**
+```
+$ kisch --input design.sch --script x.js
+```
 
-(Additional options may be added over time.)
+**Generate schematic from script (no input schematic):**
+```
+$ kisch --script new_design.js --output new_board.sch
+```
 
 ## SCRIPTING MODEL
 
-kisch is implemented as a Node.js CLI and executes user‑provided JavaScript to perform transformations.
+kisch executes user-provided JavaScript to transform a schematic loaded by the CLI.  
+
+The script is treated as the **source of truth**: any symbol or connection not present in the script will be removed.  
+If the script is empty, the resulting schematic will also be empty. To generate a script that reflects an existing schematic, use the `--emit` flag.
 
 A script typically:
 
-* Loads the schematic structure
 * Adds or modifies symbols
 * Connects pins and nets explicitly
-* Writes the transformed schematic back to disk
+* Returns a schematic that kisch will write back to disk (if an output is specified)
 
-The exact scripting API is intentionally minimal and focused on structural operations, not rendering or layout aesthetics.
+Scripts do **not** contain geometric layout information; placement is determined by KiCad or kisch heuristics.
 
-### Example
-
-The following example hooks up an ESP32-C3 supermini with a CAN transceiver.
+### Example Script
 
 ```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", {
+	let j1 = sch.declare("J1", {
 		symbol: "Connector_Generic:Conn_01x04",
-		footprint: "Peabrain:ScrewTerminals_4P",
+		footprint: "TerminalBlock:TerminalBlock_2P_5.08mm_Vertical"
 	});
 
-	let screw2 = sch.declare("J2", {
+	let j2 = 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",
+		footprint: "TerminalBlock:TerminalBlock_2P_5.08mm_Vertical"
 	});
 
-	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");
+	j1.pin(1).connect("GND");
+	j1.pin(2).connect("12V");
+	j2.pin(1).connect("GND");
+	j2.pin(2).connect("12V");
 }
 ```
 
@@ -144,10 +157,9 @@ export default async function (sch) {
 
 ## 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
+* kisch targets **KiCad 9** and above only
+* It ensures functional correctness, not placement aesthetics
 * Graphical placement quality remains the responsibility of the user
 
 ## USE CASES
@@ -155,16 +167,14 @@ export default async function (sch) {
 * Programmatic net and wire generation
 * Repetitive schematic patterns
 * Safe refactoring of large schematics
-* Hybrid GUI + code‑driven design workflows
+* 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... :)
+GPL v3

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "kisch",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/limikael/kisch.git"
+  },
   "scripts": {
     "test": "jasmine"
   },

package/src/Entity.js

@@ -68,6 +68,26 @@ class EntityPin {
 			this.entity.schematic.markConnectionDeclared(this.getPoint(),p.getPoint());
 		}
 	}
+
+	getConnections() {
+		let connections=[];
+
+		for (let net of this.entity.schematic.getNets()) {
+			if (this.isConnected(net))
+				connections.push(net);
+		}
+
+		for (let e of this.entity.schematic.getSymbolEntities()) {
+			if (e==this.entity)
+				continue;
+
+			for (let p of e.pins)
+				if (this.isConnected(p))
+					connections.push(p);
+		}
+
+		return connections;
+	}
 }
 
 export default class Entity {

package/src/LibrarySymbol.js

@@ -13,19 +13,29 @@ export default class LibrarySymbol {
      */
     get pins() {
         if (!this._pins) {
+            this._pins = [];
+
             // 1. Find the first nested symbol
-            const nestedSymbol = this.sexpr.find(
+            const nestedSymbols = this.sexpr.filter(
                 (e) => Array.isArray(e) && symEq(e[0],"symbol") && e !== this.sexpr[0]
             );
 
-            if (!nestedSymbol) {
+            for (let nestedSymbol of nestedSymbols) {
+                this._pins.push(...nestedSymbol
+                    .filter((e) => Array.isArray(e) && symEq(e[0],"pin"))
+                    .map((pinSexpr) => new LibrarySymbolPin(pinSexpr))
+                );
+
+            }
+
+            /*if (!nestedSymbol) {
                 this._pins = [];
             } else {
                 // 2. Collect all (pin ...) inside nested symbol
                 this._pins = nestedSymbol
                     .filter((e) => Array.isArray(e) && symEq(e[0],"pin"))
                     .map((pinSexpr) => new LibrarySymbolPin(pinSexpr));
-            }
+            }*/
         }
         return this._pins;
     }

package/src/Schematic.js

@@ -5,16 +5,36 @@ import {Point, pointKey, Rect} from "./cartesian-math.js";
 import {findGridPath} from "../src/manhattan-router.js";
 import {isSym, sym, sexpParse, sexpStringify, symName, sexpCallName} from "./sexp.js";
 import {placeRect} from "./place-rect.js";
+import {arrayUnique} from "./js-util.js";
 
 export default class Schematic {
-	constructor(fn, options) {
-		this.schematicFileName=fn;
+	constructor(options) {
+		if (typeof options=="string")
+			throw new Error("just pass options!!!");
+
 		this.symbolLibraryPath=options.symbolLibraryPath;
 		this.symbolLibrary=new SymbolLibrary(this.symbolLibraryPath);
 	}
 
-	async load() {
-		this.sexp=sexpParse(await fsp.readFile(this.schematicFileName,"utf8"))[0];
+	async init() {
+		await this.symbolLibrary.loadIndex();
+		this.entities=[];
+		this.uuid=crypto.randomUUID();
+
+		this.sexp=[sym("kicad_sch"),
+			[sym("version"),sym("20250114")],
+			[sym("generator"),"eeschema"],
+			[sym("generator_version"),"9.0"],
+			[sym("paper"),"A4"],
+			[sym("lib_symbols")]
+		];
+	}
+
+	async load(fn) {
+		await this.init();
+
+		//this.schematicFileName=fn;
+		this.sexp=sexpParse(await fsp.readFile(fn,"utf8"))[0];
 		this.entities=[];
 
 		for (let o of this.sexp) {
@@ -38,9 +58,9 @@ export default class Schematic {
 		return sexp;
 	}
 
-	async save() {
+	async save(fn) {
 		let content=sexpStringify([this.getSexp()],2);
-		await fsp.writeFile(this.schematicFileName,content);
+		await fsp.writeFile(fn,content);
 	}
 
 	getEntities() {
@@ -75,6 +95,16 @@ export default class Schematic {
 		return entities;
 	}
 
+	getNets() {
+		let nets=this.getEntities()
+			.filter(e=>e.getType()=="label")
+			.map(e=>e.getLabel());
+
+		nets=arrayUnique(nets);
+
+		return nets;
+	}
+
 	getEntitiesByConnectionPoint(connectonPoint) {
 		connectonPoint=Point.from(connectonPoint);
 		let entities=[];
@@ -223,6 +253,17 @@ export default class Schematic {
 		libSymbolsExpr.push(librarySymbol.getQualifiedSexpr());
 	}
 
+	ensureLibSymbolSync(symbol) {
+		let libSymbolsExpr=this.getLibSymbolsExp();
+		for (let e of libSymbolsExpr)
+			if (sexpCallName(e)=="symbol" && e[1]==symbol)
+				return;
+
+		let librarySymbol=this.symbolLibrary.loadLibrarySymbolSync(symbol);
+		//console.log("adding: "+symbol);
+		libSymbolsExpr.push(librarySymbol.getQualifiedSexpr());
+	}
+
 	async use(...symbols) {
 		symbols=symbols.flat(Infinity);
 		for (let symbol of symbols)
@@ -235,7 +276,9 @@ export default class Schematic {
 			entity=this.addSymbol(ref,options);
 
 		if (entity.getLibId()!=options.symbol)
-			throw new Error("Symbol declaration mismatch.");
+			throw new Error("Symbol declaration mismatch, code: "+options.symbol+" existing in schema: "+entity.getLibId()+" ref: "+ref);
+
+		this.ensureLibSymbolSync(options.symbol);
 
 		entity.setFootprint(options.footprint);
 		entity.declared=true;
@@ -248,7 +291,9 @@ export default class Schematic {
 		if (entity)
 			throw new Error("Reference already exists: "+reference);
 
-		let librarySymbol=this.symbolLibrary.getLibrarySymbol(symbol);
+		//let librarySymbol=this.symbolLibrary.getLibrarySymbol(symbol);
+		let librarySymbol=this.symbolLibrary.loadLibrarySymbolSync(symbol);
+
 		//let librarySymbol=await this.symbolLibrary.loadLibrarySymbol(symbol);
 		let rects=this.getSymbolEntities().map(e=>e.getBoundingRect().pad(2.54*4));
 
@@ -319,11 +364,52 @@ export default class Schematic {
 			return entity.declared;
 		});
 	}
+
+	getSource() {
+		let src="";
+		src+=`export default async function(sch) {\n`;
+		for (let e of this.getSymbolEntities()) {
+			src+=`    let ${e.getReference()}=sch.declare("${e.getReference()}",{\n`;
+			src+=`        "symbol": "${e.getLibId()}",\n`
+			src+=`        "footprint": "${e.getFootprint()}",\n`
+			src+=`    });\n\n`;
+		}
+
+		let allConnectionPoints=this.getConnectionPoints();
+		for (let e of this.getSymbolEntities()) {
+			for (let pin of e.pins) {
+				for (let c of pin.getConnections()) {
+					if (typeof c=="string") {
+						src+=`    ${e.getReference()}.pin(${pin.getNum()}).connect("${c}");\n`;
+					}
+
+					else {
+						if (e.getReference()<c.entity.getReference()) {
+							src+=`    ${e.getReference()}.pin(${pin.getNum()}).connect(`;
+							src+=`${c.entity.getReference()}.pin(${c.getNum()})`;
+							src+=`);\n`;
+						}
+					}
+				}
+			}
+		}
+
+		src+=`}\n`;
+
+		return src;
+	}
 }
 
-export async function openSchematic(fn, options) {
-	let schematic=new Schematic(fn, options);
-	await schematic.load();
+export async function loadSchematic(fn, options) {
+	let schematic=new Schematic(options);
+	await schematic.load(fn);
 
 	return schematic;
-}
+}
+
+export async function createSchematic(options) {
+	let schematic=new Schematic(options);
+	await schematic.init();
+
+	return schematic;
+}

package/src/SymbolLibrary.js

@@ -1,4 +1,4 @@
-import fs from "fs/promises";
+import fs, {promises as fsp} from "fs";
 import path from "path";
 import LibrarySymbol from "./LibrarySymbol.js";
 import {sexpParse, sym, isSym, symEq} from "../src/sexp.js";
@@ -11,7 +11,7 @@ import {sexpParse, sym, isSym, symEq} from "../src/sexp.js";
 export default class SymbolLibrary {
     constructor(dirPath) {
         this.dirPath = dirPath;
-        this.index = new Map(); // Maps libraryName -> filename
+        this.index = null; // lazy create index
         this.cache = new Map(); // Maps libraryName -> parsed list of symbols
         this.librarySymbols={};
     }
@@ -23,11 +23,39 @@ export default class SymbolLibrary {
         return this.librarySymbols[qualifiedName];
     }
 
-    /**
-     * Load the correct LibrarySymbol by full name "Lib:Symbol".
-     * @param {string} qualifiedName
-     * @returns {Promise<LibrarySymbol>}
-     */
+    loadLibrarySymbolSync(qualifiedName) {
+        if (this.librarySymbols[qualifiedName])
+            return this.librarySymbols[qualifiedName];
+
+        const [libraryName, symbolName] = qualifiedName.split(":");
+        if (!libraryName || !symbolName) {
+            throw new Error(
+                `Invalid qualified name "${qualifiedName}", expected "Library:Symbol"`
+            );
+        }
+
+        this._assertIndex();
+
+        const fileName = this.index.get(libraryName);
+        if (!fileName) {
+            throw new Error(`Library "${libraryName}" not found in ${this.dirPath}`);
+        }
+
+        //console.log(libraryName,fileName);
+
+        const syms = this._loadLibraryFileSync(libraryName, fileName);
+        const sexpr = syms.find((s) => s[1] === symbolName);
+        if (!sexpr) {
+            throw new Error(
+                `Symbol "${symbolName}" not found in library "${libraryName}"`
+            );
+        }
+
+        this.librarySymbols[qualifiedName]=new LibrarySymbol(sexpr,qualifiedName);
+
+        return this.librarySymbols[qualifiedName];
+    }
+
     async loadLibrarySymbol(qualifiedName) {
         if (this.librarySymbols[qualifiedName])
             return this.librarySymbols[qualifiedName];
@@ -61,14 +89,25 @@ export default class SymbolLibrary {
         return this.librarySymbols[qualifiedName];
     }
 
+    async loadIndex() {
+        await this._ensureIndex();
+    }
+
+    _assertIndex() {
+        if (!this.index)
+            throw new Error("Symbol index not loaded");
+    }
+
     /**
      * Scan the directory to find all .kicad_sym files and index them
      * by base name (without extension).
      */
     async _ensureIndex() {
-        if (this.index.size > 0) return;
+        if (this.index) return;
+
+        this.index = new Map();
 
-        const entries = await fs.readdir(this.dirPath);
+        const entries = await fsp.readdir(this.dirPath);
         for (const entry of entries) {
             if (entry.endsWith(".kicad_sym")) {
                 const libName = path.basename(entry, ".kicad_sym");
@@ -86,7 +125,28 @@ export default class SymbolLibrary {
         }
 
         const fullPath = path.join(this.dirPath, fileName);
-        const raw = await fs.readFile(fullPath, "utf8");
+        const raw = await fsp.readFile(fullPath, "utf8");
+        const sexprs = sexpParse(raw)[0]; // Your sexprParse
+
+        // Filter only top-level (symbol ...) forms
+        const symbols = sexprs.filter(
+            (e) => Array.isArray(e) && symEq(e[0],"symbol")
+        );
+
+        this.cache.set(libraryName, symbols);
+        return symbols;
+    }
+
+    /**
+     * Read and parse a .kicad_sym file if not cached.
+     */
+    _loadLibraryFileSync(libraryName, fileName) {
+        if (this.cache.has(libraryName)) {
+            return this.cache.get(libraryName);
+        }
+
+        const fullPath = path.join(this.dirPath, fileName);
+        const raw = fs.readFileSync(fullPath, "utf8");
         const sexprs = sexpParse(raw)[0]; // Your sexprParse
 
         // Filter only top-level (symbol ...) forms

package/src/js-util.js

@@ -0,0 +1,15 @@
+export class DeclaredError extends Error {
+    constructor(...args) {
+        super(...args);
+        this.declared=true;
+    }
+}
+
+export function arrayUnique(array) {
+    let result=new Set();
+
+    for (let item of array)
+        result.add(item);
+
+    return Array.from(result);
+}