kisch 1.0.2 → 1.0.4

package/DSL.md

@@ -0,0 +1,209 @@
+# Kisch Schematic Script Reference
+
+## Overview
+
+A Kisch schematic is defined as a JavaScript module exporting a default async function:
+
+```js
+export default async function (sch, defines) {
+    // schematic definition here
+}
+```
+
+The function receives:
+
+- `sch` — the schematic builder API
+- `defines` — an object containing CLI-defined parameters
+
+The script declares symbols (components) and connects their pins using wires or net labels.
+
+# Core Concepts
+
+## 1. Declaring a Component
+
+Use:
+
+```js
+sch.declare(reference, options)
+```
+
+### Parameters
+
+- `reference` (string)  
+  The component reference (e.g., `"R1"`, `"J1"`).
+
+- `options` (object)
+  - `symbol` (string, required) — KiCad symbol library identifier  
+  - `footprint` (string, optional) — KiCad footprint library identifier  
+
+### Example
+
+```js
+let J1 = sch.declare("J1", {
+    symbol: "Connector_Generic:Conn_01x02",
+    footprint: "Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Horizontal"
+});
+```
+
+`declare()` returns a symbol object.
+
+## 2. Accessing an Existing Symbol
+
+If you did not store the return value from `declare`, you can retrieve it later:
+
+```js
+sch.sym("J1")
+```
+
+Returns the symbol instance with reference `"J1"`.
+
+## 3. Working with Pins
+
+Access a pin using:
+
+```js
+symbol.pin(pinNumber)
+```
+
+Example:
+
+```js
+J1.pin(2)
+```
+
+Returns a pin object.
+
+## 4. Connecting Pins
+
+`connect()` must always be called on a pin object.
+
+It accepts exactly **two argument types**:
+
+- A string → connect to a named net (via net label)
+- A pin object → connect directly to another pin (via wire)
+
+No other argument types are supported.
+
+### A) Connecting to a Net (String Argument)
+
+```js
+J1.pin(2).connect("GND");
+```
+
+Behavior:
+
+- A net label with the given name is created next to the pin (if not already present at that location).
+- The pin is connected to that net label.
+- The connection is implemented as a 0-length wire between the pin and the label.
+- Multiple pins using the same string connect electrically through that net name.
+
+Important:
+
+- This explicitly creates or uses a net label in the schematic.
+- This does not implicitly merge abstract nets.
+- If you want a named signal, use a string.
+
+### B) Connecting to Another Pin (Pin Object Argument)
+
+```js
+J2.pin(1).connect(J1.pin(2));
+```
+
+Behavior:
+
+- A wire is created directly between the two pins.
+- No net label is created automatically.
+- This represents a physical wire in the schematic.
+
+Important:
+
+- Connecting pin-to-pin does NOT create a named net.
+- If you want a named net, you must connect using a string.
+
+## 5. Conditional Configuration via `defines`
+
+Scripts can adapt based on CLI-defined values.
+
+### Passing Defines from CLI
+
+```
+kisch schema.kicad_sch -s script.js -Dtest=123 --define test2=456
+```
+
+Both forms are equivalent:
+
+- `-Dkey=value`
+- `--define key=value`
+
+Inside the script:
+
+```js
+defines.test   // "123"
+defines.test2  // "456"
+```
+
+All define values are strings.
+
+### Example Usage
+
+```js
+if (defines.test === "123") {
+    sch.declare("J6", {
+        symbol: "Connector_Generic:Conn_01x04"
+    });
+}
+```
+
+This enables variant-based schematic generation.
+
+# Minimal Complete Example
+
+```js
+export default async function (sch, defines) {
+
+    let J1 = sch.declare("J1", {
+        symbol: "Connector_Generic:Conn_01x02",
+        footprint: "Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Horizontal"
+    });
+
+    J1.pin(2).connect("GND");
+
+    let J5 = sch.declare("J5", {
+        symbol: "Connector_Generic:Conn_01x04"
+    });
+
+    J5.pin(1).connect(J1.pin(1));
+
+    if (defines.test === "123") {
+        sch.declare("J6", {
+            symbol: "Connector_Generic:Conn_01x04"
+        });
+    }
+}
+```
+
+# Design Constraints (Important for AI Generation)
+
+When generating Kisch scripts:
+
+- Always export a default async function.
+- Always use `sch.declare()` to create components.
+- Always access pins using `.pin(n)`.
+- Only use `.connect()` with:
+  - a string (net name), or
+  - a pin object.
+- Do not assume additional API methods unless explicitly documented.
+- All `defines` values are strings.
+- Connecting to a string creates a net label.
+- Connecting to a pin creates a direct wire.
+
+# Philosophy
+
+Kisch treats schematics as deterministic, programmable structures.
+
+- Wires are explicit.
+- Net labels are explicit.
+- There is no hidden net merging.
+- Behavior depends strictly on argument type.
+
+This makes schematic generation reproducible, scriptable, and suitable for AI-assisted workflows.

package/README.md

@@ -4,6 +4,8 @@
 
 kisch — schema‑transformation tool for KiCad schematics
 
+[Watch video tutorial](https://www.youtube.com/watch?v=VylXziX1D8U)
+
 ## SYNOPSIS
 
 ```
@@ -125,6 +127,8 @@ A script typically:
 
 Scripts do **not** contain geometric layout information; placement is determined by KiCad or kisch heuristics.
 
+Full scripting reference: [DSL.md](./DSL.md)
+
 ### Example Script
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kisch",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
     "test": "jasmine"
   },
   "bin": {
-    "kisch": "src/kisch-cli.js"
+    "kisch": "src/app/kisch-cli.js"
   },
   "keywords": [],
   "author": "",
@@ -22,5 +22,8 @@
   },
   "dependencies": {
     "commander": "^14.0.3"
+  },
+  "exports": {
+    ".": "./src/exports.js"
   }
 }

package/src/app/exports.js

@@ -0,0 +1 @@
+export {default as SymbolLibrary} from "./SymbolLibrary.js";

package/src/{kisch-cli.js → app/kisch-cli.js}

@@ -1,16 +1,12 @@
 #!/usr/bin/env node
 
 import {program} from "commander";
-import Schematic, {loadSchematic, createSchematic} from "./Schematic.js";
+import Schematic, {loadSchematic, createSchematic} from "../schematic/Schematic.js";
 import path from "node:path";
-import pkg from "../package.json" with { type: "json" };
-import {DeclaredError} from "./js-util.js";
+import pkg from "../../package.json" with { type: "json" };
+import {DeclaredError} from "../utils/js-util.js";
 import fs, {promises as fsp} from "fs";
-
-/*todo...
-
-defines
-wires*/
+import {compoundSymbol} from "../schematic/CompoundSymbol.js";
 
 let HELP_TEXT=`
 Examples:
@@ -45,6 +41,8 @@ program
     .option("-s, --script <script.js>", "Input script to apply to schematic.")
     .option("-e, --emit <script.js>", "Emit script based on schematic.")
     .option("-q, --quiet", "No output, except for errors.")
+    .option("-a, --append", "Append mode: don't remove undeclared.")
+    .option("--bounding-boxes", "Remove wires and draw bounding boxes instead (only for debug!).")
     //.option("-v, --verbose", "Print detailed execution info")
     .option(
         "-D, --define <key=value>", 
@@ -111,11 +109,29 @@ try {
             ([e.slice(0,e.indexOf("=")),e.slice(e.indexOf("=")+1)])
         ));
 
+        global.compoundSymbol=compoundSymbol;
         let mod=await import(path.resolve(options.script));
         if (typeof mod.default=="function")
             await mod.default(schematic,defines);
 
-        schematic.removeUndeclared();
+        if (!options.append)
+            schematic.removeUndeclared();
+    }
+
+    if (options.boundingBoxes) {
+        cons.info("Drawing bounding boxes...");
+        for (let e of schematic.getEntities({type: "wire"})) {
+            schematic.removeEntity(e);
+        }
+
+        for (let s of schematic.getEntities({type: "symbol"})) {
+            schematic.drawWireRect(s.getBoundingRect());
+            for (let p of s.getPins()) {
+                schematic.drawWirePoint(p.getPoint());
+                schematic.drawWirePoint(p.getLegPoint());
+                schematic.drawWireLine(p.getPoint(),p.getLegPoint());
+            }
+        }
     }
 
     if (options.emit) {

package/src/schematic/CompoundSymbol.js

@@ -0,0 +1,35 @@
+export default class CompoundSymbol {
+	constructor(...symbols) {
+		this.symbols=symbols;
+		this.pins=[];
+
+		for (let symbol of symbols) {
+			for (let pin of symbol.pins) {
+				//console.log(pin.getNum());
+
+				this.pins.push(pin);
+			}
+		}
+	}
+
+	pin(num) {
+		if (!num)
+			throw new Error("Pins start at 1");
+
+		return this.pins[num-1];
+	}
+
+	namePins(names) {
+		if (names.length!=this.pins.length)
+			throw new Error("pin count mismatch");
+
+		for (let i=0; i<this.pins.length; i++)
+			this[names[i]]=this.pins[i];
+
+		return this;
+	}
+}
+
+export function compoundSymbol(...args) {
+	return new CompoundSymbol(...args);
+}

package/src/{Entity.js → schematic/Entity.js}

@@ -1,31 +1,50 @@
-import {Point} from "./cartesian-math.js";
-import {sym, symName, sexpCallName} from "./sexp.js";
-import {Rect} from "./cartesian-math.js";
+import {Point, Rect} from "../utils/cartesian-math.js";
+import {sym, symName, sexpCallName} from "../utils/sexp.js";
 
 class EntityPin {
 	constructor(sexpr, entity) {
 		this.sexpr=sexpr;
 		this.entity=entity;
-
-		//console.log(this.sexpr);
 	}
 
 	getNum() {
 		return this.sexpr[1];
 	}
 
-	getPoint() {
+	initPoint() {
 		let librarySymbol=this.entity.getLibrarySymbol();
 		let librarySymbolPin=librarySymbol.getPin(Number(this.getNum()));
 		let pinAt=Point.from(librarySymbolPin.at);
+		let symbolAt=this.entity.getAt();
+		let symbolRot=this.entity.getRotation();
 		pinAt[1]=-pinAt[1];
 
-		return Point.from(this.entity.getAt()).add(pinAt);
+		//this.point=Point.from(symbolAt).add(pinAt.rotateDegrees(-symbolAt[2]));
+		//this.point=Point.from(symbolAt).add(pinAt.rotateDegrees(-this.entity.getRotation()));
+		this.point=Point.from(symbolAt).add(pinAt.rotateDegrees(-symbolRot));
+
+		let leg=new Point(librarySymbolPin.length,0);
+		leg=leg.rotateDegrees(-(librarySymbolPin.rotation+symbolRot));
+		this.legPoint=this.point.add(leg);
+	}
+
+	getLegPoint() {
+		if (!this.legPoint)
+			this.initPoint();
+
+		return this.legPoint;
+	}
+
+	getPoint() {
+		if (!this.point)
+			this.initPoint();
+
+		return this.point;
 	}
 
 	isConnected(p) {
 		if (typeof p=="string") {
-			for (let e of this.entity.schematic.getLabelEntities(p)) {
+			for (let e of this.entity.schematic.getEntities({label: p})) {
 				let p=e.getConnectionPoints()[0];
 				if (this.entity.schematic.arePointsConnected(this.getPoint(),p))
 					return true;
@@ -40,9 +59,12 @@ class EntityPin {
 	}
 
 	connect(p) {
+		if (!p)
+			return;
+
 		if (this.isConnected(p)) {
 			if (typeof p=="string") {
-				for (let e of this.entity.schematic.getLabelEntities(p)) {
+				for (let e of this.entity.schematic.getEntities({label: p})) {
 					let p=e.getConnectionPoints()[0];
 					if (this.entity.schematic.arePointsConnected(this.getPoint(),p)) {
 						e.declared=true;
@@ -64,11 +86,16 @@ class EntityPin {
 		}
 
 		else {
+			//console.log("connecting wire",this.toString(),"->",p.toString());
 			this.entity.schematic.addConnectionWire(this.getPoint(),p.getPoint());
 			this.entity.schematic.markConnectionDeclared(this.getPoint(),p.getPoint());
 		}
 	}
 
+	toString() {
+		return this.entity.getReference()+":"+this.getNum();
+	}
+
 	getConnections() {
 		let connections=[];
 
@@ -77,7 +104,7 @@ class EntityPin {
 				connections.push(net);
 		}
 
-		for (let e of this.entity.schematic.getSymbolEntities()) {
+		for (let e of this.entity.schematic.getEntities({type: "symbol"})) {
 			if (e==this.entity)
 				continue;
 
@@ -97,7 +124,7 @@ export default class Entity {
 		this.pins=[];
 
 		this.type=symName(this.sexpr[0]);
-		if (!["symbol","wire","label"].includes(this.type))
+		if (!["symbol","wire","label","junction"].includes(this.type))
 			throw new Error("Unknown entity: "+this.type);
 
 		for (let a of this.sexpr)
@@ -105,6 +132,14 @@ export default class Entity {
 				this.pins.push(new EntityPin(a,this));
 	}
 
+	getRotation() {
+		return this.getAt()[2];
+	}
+
+	getPins() {
+		return this.pins;
+	}
+
 	getSexp() {
 		return this.sexpr;
 	}
@@ -178,6 +213,36 @@ export default class Entity {
 		el[2]=footprint;
 	}
 
+	removeProp(name) {
+		if (this.getType()!="symbol")
+			throw new Error("Only symbols have props");
+
+		let index=this.sexpr.findIndex(a=>sexpCallName(a)=="property" && a[1]==name);
+		if (index<0)
+			return;
+
+		this.sexpr.splice(index,1);
+	}
+
+	setProp(name, value) {
+		if (this.getType()!="symbol")
+			throw new Error("Only symbols have props");
+
+		let el=this.sexpr.find(a=>sexpCallName(a)=="property" && a[1]==name);
+		if (!el) {
+			let exp=[sym("property"),name,"",
+				[sym("effects"),
+					[sym("hide"),sym("yes")]
+				]
+			];
+
+			this.sexpr.push(exp);
+			el=exp;
+		}
+
+		el[2]=value;
+	}
+
 	getLibId() {
 		return this.sexpr.find(x=>sexpCallName(x)=="lib_id")[1];
 	}
@@ -196,12 +261,18 @@ export default class Entity {
 	}
 
 	getBoundingRect() {
+		if (!this.librarySymbol)
+			throw new Error("Can't get bounding rect, no library symbol");
+
 		//console.log(this.librarySymbol);
 		let r=this.librarySymbol.getBoundingRect();
+		let corner=r.corner.rotateDegrees(-this.getRotation());
+		let size=r.size.rotateDegrees(-this.getRotation());
+
 		//console.log(r);
 		let p=Point.from(this.getAt());
 
-		return new Rect(p.add(r.corner),r.size);
+		return new Rect(p.add(corner),size);
 	}
 
 	getLibrarySymbol() {
@@ -219,12 +290,6 @@ export default class Entity {
 
 	getType() {
 		return this.type;
-		/*let t=symName(this.sexpr[0]);
-
-		if (!["symbol","wire","label"].includes(t))
-			throw new Error("Unknown entity: "+t);
-
-		return t;*/
 	}
 
 	getConnectionPoints() {
@@ -249,4 +314,43 @@ export default class Entity {
 				throw new Error("Unknown entity type: "+this.getType());
 		}
 	}
+
+	connect(...pins) {
+		if (this.getType()!="symbol")
+			throw new Error("can only connect sybols");
+
+		if (pins.length!=this.pins.length)
+			throw new Error("pin count mismatch");
+
+		for (let i=0; i<this.pins.length; i++)
+			this.pins[i].connect(pins[i]);
+	}
+
+	containsPoint(p) {
+		function isNumberInRangeInclusive(num, a, b) {
+		    return ((num >= Math.min(a, b)) && (num <= Math.max(a, b)));
+		}
+
+		if (this.getType()!="wire")
+			throw new Error("Only a wire can contain points");
+
+		p=Point.from(p);
+		let cp=this.getConnectionPoints();
+		if (cp[0][0]==cp[1][0]) { // vertical
+			if (p[0]!=cp[0][0])
+				return false;
+
+			return isNumberInRangeInclusive(p[1],cp[0][1],cp[1][1]);
+		}
+
+		else if (cp[0][1]==cp[1][1]) { // horizontal
+			if (p[1]!=cp[0][1])
+				return false;
+
+			return isNumberInRangeInclusive(p[0],cp[0][0],cp[1][0]);
+		}
+
+		else 
+			throw new Error("wire is not horizontal or vertical");
+	}
 }

package/src/{LibrarySymbol.js → schematic/LibrarySymbol.js}

@@ -1,5 +1,5 @@
-import {sym, isSym, symEq, symName, sexpStringify, sexpCallName} from "./sexp.js";
-import {Rect} from "./cartesian-math.js";
+import {sym, isSym, symEq, symName, sexpStringify, sexpCallName} from "../utils/sexp.js";
+import {Rect} from "../utils/cartesian-math.js";
 
 export default class LibrarySymbol {
     constructor(sexpr, qualifiedName) {
@@ -61,6 +61,13 @@ export default class LibrarySymbol {
             if (sexpCallName(x)=="rectangle") {
                 let start=x.find(x=>sexpCallName(x)=="start").slice(1);
                 let end=x.find(x=>sexpCallName(x)=="end").slice(1);
+
+                start[1]=-start[1];
+                end[1]=-end[1];
+
+                /*console.log(start);
+                console.log(end);*/
+
                 let r=Rect.fromCorners(start,end);
 
                 if (!rect)
@@ -68,6 +75,32 @@ export default class LibrarySymbol {
 
                 rect=rect.union(r);
             }
+
+            if (sexpCallName(x)=="polyline") {
+                //console.log("poly line...");
+                for (let sub of x) {
+                    if (sexpCallName(sub)=="pts") {
+                        for (let p of sub) {
+                            if (sexpCallName(p)=="xy") {
+                                let point=[p[1],p[2]];
+
+                                if (!rect)
+                                    rect=new Rect(point,[0,0]);
+
+                                //console.log("rect",rect);
+                                //console.log("point",point);
+
+                                rect=rect.includePoint(point);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        if (!rect) {
+            //console.log(symbolExp);
+            throw new Error("Symbol doesn't have any rect!");
         }
 
         //console.log(sexpStringify(symbolExp));
@@ -93,7 +126,9 @@ export class LibrarySymbolPin {
 
             switch (symName(e[0])) {
                 case "at":
+                    //console.log(e);
                     this.at = e.slice(1).map(Number); // [x, y, rotation]
+                    this.rotation=Number(e[3]);
                     break;
                 case "length":
                     this.length = Number(e[1]);