kicadts 0.0.1

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kicadts",
+  "module": "dist/index.js",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tscircuit/kicadts"
+  },
+  "scripts": {
+    "build": "tsup-node lib/index.ts --format esm --dts",
+    "download-references": "bun run scripts/download-references.ts",
+    "download-demos": "git clone --depth 1 --filter=blob:none --sparse git@gitlab.com:kicad/code/kicad.git kicad-demos && cd kicad-demos && git sparse-checkout set demos",
+    "typecheck": "bunx tsc --noEmit",
+    "format": "biome format --write .",
+    "format:check": "biome format ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@types/bun": "latest",
+    "tsup": "^8.5.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/scripts/download-references.ts

@@ -0,0 +1,66 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type ReferenceSpec = {
+  readonly url: string;
+  readonly filename: string;
+};
+
+const references: ReferenceSpec[] = [
+  {
+    url: "https://gitlab.com/kicad/services/kicad-dev-docs/-/raw/master/content/file-formats/sexpr-intro/_index.en.adoc",
+    filename: "SEXPR_MAIN.adoc",
+  },
+  {
+    url: "https://gitlab.com/kicad/services/kicad-dev-docs/-/raw/master/content/file-formats/sexpr-schematic/_index.en.adoc",
+    filename: "SCHEMATIC_SEXPR.adoc",
+  },
+  {
+    url: "https://gitlab.com/kicad/services/kicad-dev-docs/-/raw/master/content/file-formats/sexpr-pcb/_index.en.adoc",
+    filename: "PCB_SEXPR.adoc",
+  },
+  {
+    url: "https://gitlab.com/kicad/services/kicad-dev-docs/-/raw/master/content/file-formats/sexpr-footprint/_index.en.adoc",
+    filename: "FOOTPRINT_SEXPR.adoc",
+  },
+  {
+    url: "https://gitlab.com/kicad/services/kicad-dev-docs/-/raw/master/content/file-formats/sexpr-symbol-lib/_index.en.adoc",
+    filename: "SCH_SYM_SEXPR.adoc",
+  },
+];
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "..");
+const referencesDir = resolve(repoRoot, "references");
+
+async function fetchReference(reference: ReferenceSpec): Promise<void> {
+  const response = await fetch(reference.url);
+
+  if (!response.ok) {
+    throw new Error(`${reference.url} (${response.status} ${response.statusText})`);
+  }
+
+  const content = await response.text();
+  const targetPath = resolve(referencesDir, reference.filename);
+
+  await writeFile(targetPath, content, "utf8");
+  console.log(`Saved ${reference.filename}`);
+}
+
+async function main(): Promise<void> {
+  await mkdir(referencesDir, { recursive: true });
+
+  await Promise.all(
+    references.map(async (reference) => {
+      try {
+        await fetchReference(reference);
+      } catch (error) {
+        console.error(`Failed to download ${reference.filename}:`, error);
+        process.exitCode = 1;
+      }
+    }),
+  );
+}
+
+await main();

package/tests/fixtures/expectEqualPrimitiveSExpr.ts

@@ -0,0 +1,200 @@
+import { expect } from "bun:test"
+import type { PrimitiveSExpr } from "lib/sexpr/parseToPrimitiveSExpr"
+
+interface ExpectEqualPrimitiveSExprOptions {
+  context?: Record<string, unknown>
+  path?: string
+}
+
+type CanonicalPrimitiveSExpr =
+  | string
+  | number
+  | boolean
+  | null
+  | CanonicalPrimitiveSExpr[]
+
+const ORDERED_TAGS = new Set(["xy"])
+
+const canonicalKey = (value: CanonicalPrimitiveSExpr): string =>
+  JSON.stringify(value)
+
+const canonicalizePrimitiveSExpr = (
+  value: PrimitiveSExpr,
+): CanonicalPrimitiveSExpr => {
+  if (!Array.isArray(value)) {
+    return value
+  }
+
+  if (value.length === 0) {
+    return []
+  }
+
+  const first = value[0]
+
+  if (typeof first === "string") {
+    return canonicalizeNode(value as CanonicalPrimitiveSExpr[])
+  }
+
+  if (Array.isArray(first)) {
+    const canonicalChildren = value.map((child) =>
+      canonicalizePrimitiveSExpr(child),
+    ) as CanonicalPrimitiveSExpr[]
+
+    canonicalChildren.sort((a, b) =>
+      canonicalKey(a).localeCompare(canonicalKey(b)),
+    )
+
+    return canonicalChildren
+  }
+
+  return value.map((child) => canonicalizePrimitiveSExpr(child))
+}
+
+const canonicalizeNode = (
+  list: CanonicalPrimitiveSExpr[],
+): CanonicalPrimitiveSExpr => {
+  const [head, ...tail] = list
+
+  if (head === undefined) {
+    return []
+  }
+
+  const positional: CanonicalPrimitiveSExpr[] = []
+  const grouped = new Map<string, CanonicalPrimitiveSExpr[]>()
+
+  for (const element of tail) {
+    if (Array.isArray(element)) {
+      const tag = element[0]
+      if (typeof tag === "string" && !ORDERED_TAGS.has(tag)) {
+        const canonicalChild = canonicalizePrimitiveSExpr(element)
+        const bucket = grouped.get(tag)
+        if (bucket) {
+          bucket.push(canonicalChild)
+        } else {
+          grouped.set(tag, [canonicalChild])
+        }
+        continue
+      }
+    }
+
+    positional.push(canonicalizePrimitiveSExpr(element))
+  }
+
+  const groupedValues: CanonicalPrimitiveSExpr[] = []
+  const sortedTags = [...grouped.keys()].sort()
+  for (const tag of sortedTags) {
+    const items = grouped.get(tag)!
+    items.sort((a, b) => canonicalKey(a).localeCompare(canonicalKey(b)))
+    groupedValues.push(...items)
+  }
+
+  return [canonicalizePrimitiveSExpr(head), ...positional, ...groupedValues]
+}
+
+export const expectEqualPrimitiveSExpr = (
+  actual: PrimitiveSExpr,
+  expected: PrimitiveSExpr,
+  options: ExpectEqualPrimitiveSExprOptions = {},
+): void => {
+  const normalizedActual = canonicalizePrimitiveSExpr(actual)
+  const normalizedExpected = canonicalizePrimitiveSExpr(expected)
+
+  const rootPath = options.path ?? "sexpr"
+  const contextEntries = options.context
+    ? Object.entries(options.context)
+    : []
+
+  const formatPath = (segments: readonly string[]): string => segments.join("")
+
+  const buildPayload = (path: string, value: unknown): Record<string, unknown> => {
+    if (contextEntries.length === 0) {
+      return { path, value }
+    }
+
+    const payload: Record<string, unknown> = {}
+    for (const [key, contextValue] of contextEntries) {
+      payload[key] = contextValue
+    }
+    payload.path = path
+    payload.value = value
+    return payload
+  }
+
+  const expectWithPath = (
+    segments: readonly string[],
+    actualValue: unknown,
+    expectedValue: unknown,
+  ): void => {
+    const path = formatPath(segments)
+    expect(buildPayload(path, actualValue)).toEqual(
+      buildPayload(path, expectedValue),
+    )
+  }
+
+  const getNodeToken = (
+    value: CanonicalPrimitiveSExpr,
+  ): string | undefined => {
+    if (!Array.isArray(value)) {
+      return undefined
+    }
+
+    const [head] = value
+    return typeof head === "string" ? head : undefined
+  }
+
+  const describePathSegment = (
+    child: CanonicalPrimitiveSExpr,
+    index: number,
+  ): string => {
+    const token = getNodeToken(child)
+    if (token) {
+      return `[${index}:${token}]`
+    }
+    return `[${index}]`
+  }
+
+  const describeType = (value: CanonicalPrimitiveSExpr): string => {
+    if (Array.isArray(value)) {
+      return "array"
+    }
+    if (value === null) {
+      return "null"
+    }
+    return typeof value
+  }
+
+  const compare = (
+    currentActual: CanonicalPrimitiveSExpr,
+    currentExpected: CanonicalPrimitiveSExpr,
+    path: readonly string[],
+  ): void => {
+    const actualType = describeType(currentActual)
+    const expectedType = describeType(currentExpected)
+
+    if (actualType !== expectedType) {
+      expectWithPath([...path, ".type"], actualType, expectedType)
+      return
+    }
+
+    if (Array.isArray(currentActual) && Array.isArray(currentExpected)) {
+      expectWithPath(
+        [...path, ".length"],
+        currentActual.length,
+        currentExpected.length,
+      )
+
+      const limit = Math.min(currentActual.length, currentExpected.length)
+      for (let index = 0; index < limit; index += 1) {
+        const childActual = currentActual[index]!
+        const childExpected = currentExpected[index]!
+        const childSegment = describePathSegment(childActual, index)
+        compare(childActual, childExpected, [...path, childSegment])
+      }
+      return
+    }
+
+    expectWithPath(path, currentActual, currentExpected)
+  }
+
+  compare(normalizedActual, normalizedExpected, [rootPath])
+}

package/tests/sexpr/KicadPcbDemos.test.ts

@@ -0,0 +1,48 @@
+import { expect, test } from "bun:test"
+import { KicadPcb, SxClass } from "lib/sexpr"
+import { parseToPrimitiveSExpr } from "lib/sexpr/parseToPrimitiveSExpr"
+import type { PrimitiveSExpr } from "lib/sexpr/parseToPrimitiveSExpr"
+
+import { expectEqualPrimitiveSExpr } from "../fixtures/expectEqualPrimitiveSExpr"
+
+const numericLike = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/
+
+const normalizePrimitive = (value: PrimitiveSExpr): PrimitiveSExpr => {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizePrimitive(item))
+  }
+  if (typeof value === "string" && numericLike.test(value)) {
+    const parsed = Number(value)
+    if (!Number.isNaN(parsed)) {
+      return parsed
+    }
+  }
+  return value
+}
+
+const demoPcbPaths = [
+  "kicad-demos/demos/flat_hierarchy/flat_hierarchy.kicad_pcb",
+  "kicad-demos/demos/custom_pads_test/custom_pads_test.kicad_pcb",
+]
+
+test("kicad_pcb round-trips selected KiCad demo boards", async () => {
+  for (const path of demoPcbPaths) {
+    const original = await Bun.file(path).text()
+    const classes = SxClass.parse(original)
+
+    expect(classes).toHaveLength(1)
+    expect(classes[0]).toBeInstanceOf(KicadPcb)
+
+    const roundTrip = classes.map((instance) => instance.getString()).join("\n")
+
+    const originalPrimitive = parseToPrimitiveSExpr(original).map((form) =>
+      normalizePrimitive(form),
+    )
+
+    const roundTripPrimitive = parseToPrimitiveSExpr(roundTrip).map((form) =>
+      normalizePrimitive(form),
+    )
+
+    expectEqualPrimitiveSExpr(roundTripPrimitive, originalPrimitive, { path })
+  }
+})

package/tests/sexpr/KicadSchDemos.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test"
+import { KicadSch, SxClass } from "lib/sexpr"
+import { parseToPrimitiveSExpr } from "lib/sexpr/parseToPrimitiveSExpr"
+import type { PrimitiveSExpr } from "lib/sexpr/parseToPrimitiveSExpr"
+
+import { expectEqualPrimitiveSExpr } from "../fixtures/expectEqualPrimitiveSExpr"
+
+const numericLike = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/
+
+const normalizePrimitive = (value: PrimitiveSExpr): PrimitiveSExpr => {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizePrimitive(item))
+  }
+  if (typeof value === "string" && numericLike.test(value)) {
+    const parsed = Number(value)
+    if (!Number.isNaN(parsed)) {
+      return parsed
+    }
+  }
+  return value
+}
+
+const demoSchematics = [
+  "kicad-demos/demos/simulation/rectifier/rectifier.kicad_sch",
+  "kicad-demos/demos/simulation/up-down-counter/up-down-c.kicad_sch",
+  "kicad-demos/demos/simulation/analog-multiplier/a-multi.kicad_sch",
+]
+
+test("kicad_sch round-trips kicad demo schematics", async () => {
+  for (const path of demoSchematics) {
+    const original = await Bun.file(path).text()
+    const classes = SxClass.parse(original)
+
+    expect(classes).toHaveLength(1)
+    expect(classes[0]).toBeInstanceOf(KicadSch)
+
+    const roundTrip = classes.map((instance) => instance.getString()).join("\n")
+
+    const originalPrimitive = parseToPrimitiveSExpr(original).map((form) =>
+      normalizePrimitive(form),
+    )
+
+    const roundTripPrimitive = parseToPrimitiveSExpr(roundTrip).map((form) =>
+      normalizePrimitive(form),
+    )
+
+    expectEqualPrimitiveSExpr(roundTripPrimitive, originalPrimitive, { path })
+  }
+})

package/tests/sexpr/classes/Footprint.test.ts

@@ -0,0 +1,277 @@
+import {
+  At,
+  Footprint,
+  FootprintAttr,
+  FootprintPrivateLayers,
+  FootprintSolderMaskMargin,
+  FpArc,
+  FpCircle,
+  FpPoly,
+  FpRect,
+  FpText,
+  FpTextBox,
+  Layer,
+  SxClass,
+} from "lib/sexpr"
+import { expect, test } from "bun:test"
+
+test("Footprint", () => {
+  const [fp] = SxClass.parse(`
+    (footprint "Resistor_SMD:R_0603"
+      locked
+      placed
+      (layer F.Cu)
+      (tedit 5E4C0E65)
+      (uuid 12345678-1234-1234-1234-123456789abc)
+      (at 10.16 5.08 90)
+      (descr "0603 chip resistor")
+      (tags "resistor smd")
+      (property "Sheetfile" "example.kicad_sch")
+      (path "/abcdef01")
+      (autoplace_cost90 4)
+      (solder_mask_margin 0.05)
+      (attr smd exclude_from_bom)
+      (private_layers F.CrtYd B.CrtYd)
+      (net_tie_pad_groups "A,B" "C,D")
+      (fp_text reference R1 (at 0 0) (layer F.SilkS)
+        (effects (font (size 1 1) (thickness 0.15)))
+      )
+      (fp_text_box locked "Label"
+        (start -1 -1)
+        (end 1 1)
+        (pts (xy -1 -1) (xy 1 -1) (xy 1 1) (xy -1 1))
+        (layer F.SilkS)
+        (effects (font (size 1.2 1.2) (thickness 0.18)))
+        (uuid 99999999-aaaa-bbbb-cccc-dddddddddddd)
+      )
+      (fp_rect
+        (start -2 -2)
+        (end 2 2)
+        (layer F.Cu)
+        (stroke (width 0.1) (type solid) (color 0 0 0 1))
+        (uuid 22222222-3333-4444-5555-666666666666)
+      )
+      (fp_circle locked
+        (center 0 0)
+        (end 1 0)
+        (layer F.SilkS)
+        (stroke (width 0.05) (type dash) (color 0.5 0.5 0.5 1))
+        (uuid 77777777-8888-9999-aaaa-bbbbbbbbbbbb)
+      )
+      (fp_arc
+        (start -3 0)
+        (mid 0 1)
+        (end 3 0)
+        (layer F.SilkS)
+        (stroke (width 0.08) (type solid) (color 0 0 0 1))
+        (uuid 44444444-5555-6666-7777-888888888888)
+      )
+      (fp_poly
+        (pts (xy 0 0) (xy 2 0) (xy 2 2) (xy 0 2))
+        (layer F.Mask)
+        (stroke (width 0.05) (type solid) (color 0 0 0 1))
+        (fill yes)
+        (uuid 99999999-aaaa-bbbb-cccc-eeeeeeeeeeee)
+      )
+      (pad "1" smd roundrect
+        (at 0 0 90)
+        (size 1.2 0.6)
+        (layers F.Cu F.Paste F.Mask)
+        (roundrect_rratio 0.25)
+        (solder_mask_margin 0.05)
+        (clearance 0.1)
+        (net 1 "GND")
+        (pinfunction "GND")
+        (pintype "passive")
+        (uuid 12121212-3434-5656-7878-909090909090)
+      )
+    )
+  `)
+
+  expect(fp).toBeInstanceOf(Footprint)
+  const footprint = fp as Footprint
+
+  expect(footprint.libraryLink).toBe("Resistor_SMD:R_0603")
+  expect(footprint.locked).toBe(true)
+  expect(footprint.placed).toBe(true)
+  expect(footprint.layer).toBeInstanceOf(Layer)
+  expect(footprint.tedit?.value).toBe("5E4C0E65")
+  expect(footprint.uuid?.value).toBe("12345678-1234-1234-1234-123456789abc")
+  const position = footprint.position
+  expect(position).toBeDefined()
+  expect(position?.x).toBe(10.16)
+  expect(position?.y).toBe(5.08)
+  expect(position).toBeInstanceOf(At)
+  if (position instanceof At) {
+    expect(position.angle).toBe(90)
+  }
+  expect(footprint.descr?.value).toBe("0603 chip resistor")
+  expect(footprint.tags?.value).toBe("resistor smd")
+  expect(footprint.properties[0]?.key).toBe("Sheetfile")
+  expect(footprint.properties[0]?.value).toBe("example.kicad_sch")
+  expect(footprint.path?.value).toBe("/abcdef01")
+  expect(footprint.autoplaceCost90?.value).toBe(4)
+  expect(footprint.solderMaskMargin?.value).toBe(0.05)
+  expect(footprint.attr).toBeInstanceOf(FootprintAttr)
+  expect(footprint.attr?.type).toBe("smd")
+  expect(footprint.attr?.excludeFromBom).toBe(true)
+  expect(footprint.privateLayers).toBeInstanceOf(FootprintPrivateLayers)
+  expect(footprint.privateLayers?.layers).toEqual(["F.CrtYd", "B.CrtYd"])
+  expect(footprint.netTiePadGroups?.groups).toEqual(["A,B", "C,D"])
+  expect(footprint.fpTexts.length).toBe(1)
+  const text = footprint.fpTexts[0] as FpText
+  expect(text.type).toBe("reference")
+  expect(text.text).toBe("R1")
+  expect(text.layer?.names).toEqual(["F.SilkS"])
+  expect(text.effects).toBeDefined()
+  expect(footprint.fpTextBoxes.length).toBe(1)
+  const textBox = footprint.fpTextBoxes[0] as FpTextBox
+  expect(textBox.locked).toBe(true)
+  expect(textBox.text).toBe("Label")
+  expect(textBox.start?.x).toBe(-1)
+  expect(textBox.end?.y).toBe(1)
+  expect(footprint.fpRects.length).toBe(1)
+  const rect = footprint.fpRects[0] as FpRect
+  expect(rect.start?.x).toBe(-2)
+  expect(rect.end?.y).toBe(2)
+  expect(rect.layer?.names).toEqual(["F.Cu"])
+  expect(rect.stroke).toBeDefined()
+  expect(footprint.fpCircles.length).toBe(1)
+  const circle = footprint.fpCircles[0] as FpCircle
+  expect(circle.center?.x).toBe(0)
+  expect(circle.end?.x).toBe(1)
+  expect(footprint.fpArcs.length).toBe(1)
+  const arc = footprint.fpArcs[0] as FpArc
+  expect(arc.start?.x).toBe(-3)
+  expect(arc.mid?.y).toBe(1)
+  expect(arc.end?.x).toBe(3)
+  expect(footprint.fpPolys.length).toBe(1)
+  const poly = footprint.fpPolys[0] as FpPoly
+  expect(poly.points?.points.length).toBe(4)
+  expect(poly.fill?.filled).toBe(true)
+  expect(footprint.fpPads.length).toBe(1)
+  const pad = footprint.fpPads[0]!
+  expect(pad.number).toBe("1")
+  expect(pad.padType).toBe("smd")
+  expect(pad.layers?.layers).toEqual(["F.Cu", "F.Paste", "F.Mask"])
+  expect(pad.net?.name).toBe("GND")
+
+  footprint.locked = false
+  footprint.placed = false
+  footprint.solderMaskMargin = new FootprintSolderMaskMargin(0.09)
+
+  expect(footprint.getString()).toMatchInlineSnapshot(`
+    "(footprint
+      \"Resistor_SMD:R_0603\"
+      (layer F.Cu)
+      (tedit 5E4C0E65)
+      (uuid 12345678-1234-1234-1234-123456789abc)
+      (at 10.16 5.08 90)
+      (descr \"0603 chip resistor\")
+      (tags \"resistor smd\")
+      (path \"/abcdef01\")
+      (autoplace_cost90 4)
+      (solder_mask_margin 0.09)
+      (attr smd exclude_from_bom)
+      (private_layers F.CrtYd B.CrtYd)
+      (net_tie_pad_groups \"A,B\" \"C,D\")
+      (property \"Sheetfile\" \"example.kicad_sch\"
+      )
+      (fp_text
+        reference
+        \"R1\"
+        (at 0 0)
+        (layer F.SilkS)
+        (effects
+          (font
+            (size 1 1)
+            (thickness 0.15)
+          )
+        )
+      )
+      (fp_text_box
+        locked
+        \"Label\"
+        (start -1 -1)
+        (end 1 1)
+        (pts
+          (xy -1 -1)
+          (xy 1 -1)
+          (xy 1 1)
+          (xy -1 1)
+        )
+        (layer F.SilkS)
+        (effects
+          (font
+            (size 1.2 1.2)
+            (thickness 0.18)
+          )
+        )
+        (uuid 99999999-aaaa-bbbb-cccc-dddddddddddd)
+      )
+      (fp_rect
+        (start -2 -2)
+        (end 2 2)
+        (layer F.Cu)
+        (stroke
+          (width 0.1)
+          (type solid)
+          (color 0 0 0 1)
+        )
+        (uuid 22222222-3333-4444-5555-666666666666)
+      )
+      (fp_circle
+        (center 0 0)
+        (end 1 0)
+        (layer F.SilkS)
+        (stroke
+          (width 0.05)
+          (type dash)
+          (color 0.5 0.5 0.5 1)
+        )
+        (uuid 77777777-8888-9999-aaaa-bbbbbbbbbbbb)
+        locked
+      )
+      (fp_arc
+        (start -3 0)
+        (mid 0 1)
+        (end 3 0)
+        (layer F.SilkS)
+        (stroke
+          (width 0.08)
+          (type solid)
+          (color 0 0 0 1)
+        )
+        (uuid 44444444-5555-6666-7777-888888888888)
+      )
+      (fp_poly
+        (pts
+          (xy 0 0)
+          (xy 2 0)
+          (xy 2 2)
+          (xy 0 2)
+        )
+        (layer F.Mask)
+        (stroke
+          (width 0.05)
+          (type solid)
+          (color 0 0 0 1)
+        )
+        (fill yes)
+        (uuid 99999999-aaaa-bbbb-cccc-eeeeeeeeeeee)
+      )
+      (pad \"1\" smd roundrect
+        (at 0 0 90)
+        (size 1.2 0.6)
+        (layers F.Cu F.Paste F.Mask)
+        (roundrect_rratio 0.25)
+        (net 1 \"GND\")
+        (pinfunction GND)
+        (pintype passive)
+        (solder_mask_margin 0.05)
+        (clearance 0.1)
+        (uuid 12121212-3434-5656-7878-909090909090)
+      )
+    )"
+  `)
+})