Add KicadLibraryConverter API with user/builtin separation for kicad-library directories and files (tscircuit#47)

* Add KicadLibraryConverter API with user/builtin separation for kicad-library directories and files

* add test

* update

* Use object params

* update

* update

* update

* fix naming

* naming

* classify in stages

* update naming

* add test

* update

* rename

* update

Author: MustafaMulla29

lib/index.ts

@@ -2,3 +2,4 @@ export * from "./schematic/CircuitJsonToKicadSchConverter"
 export * from "./pcb/CircuitJsonToKicadPcbConverter"
 export * from "./project/CircuitJsonToKicadProConverter"
 export * from "./kicad-library/CircuitJsonToKicadLibraryConverter"
+export * from "./kicad-library/KicadLibraryConverter"

lib/kicad-library/KicadLibraryConverter.ts

@@ -0,0 +1,154 @@
+import { CircuitJsonToKicadLibraryConverter } from "./CircuitJsonToKicadLibraryConverter"
+import type {
+  KicadLibraryConverterOptions,
+  KicadLibraryConverterOutput,
+  KicadLibraryConverterContext,
+  BuiltTscircuitComponent,
+  ExtractedKicadComponent,
+} from "./KicadLibraryConverterTypes"
+import { classifyKicadFootprints } from "./stages/ClassifyKicadFootprintsStage"
+import { classifyKicadSymbols } from "./stages/ClassifyKicadSymbolsStage"
+import { buildKicadLibraryFiles } from "./stages/BuildKicadLibraryFilesStage"
+
+export type { KicadLibraryConverterOptions, KicadLibraryConverterOutput }
+
+/**
+ * Converts tscircuit component files to a KiCad library.
+ */
+export class KicadLibraryConverter {
+  private options: KicadLibraryConverterOptions
+  private output: KicadLibraryConverterOutput | null = null
+  private ctx: KicadLibraryConverterContext
+
+  constructor(options: KicadLibraryConverterOptions) {
+    this.options = options
+    this.ctx = createKicadLibraryConverterContext({
+      kicadLibraryName: options.kicadLibraryName ?? "tscircuit_library",
+      includeBuiltins: options.includeBuiltins ?? true,
+    })
+  }
+
+  async run(): Promise<void> {
+    // Stage 1: Build tscircuit components to circuit-json
+    this.ctx.builtTscircuitComponents = await this.buildTscircuitComponents()
+
+    // Stage 2: Extract KiCad footprints and symbols from circuit-json
+    this.ctx.extractedKicadComponents = this.extractKicadComponents()
+
+    // Stage 3: Classify footprints into user/builtin
+    classifyKicadFootprints(this.ctx)
+
+    // Stage 4: Classify symbols into user/builtin
+    classifyKicadSymbols(this.ctx)
+
+    // Stage 5: Build output files
+    buildKicadLibraryFiles(this.ctx)
+
+    this.output = {
+      kicadProjectFsMap: this.ctx.kicadProjectFsMap,
+      model3dSourcePaths: this.ctx.model3dSourcePaths,
+    }
+  }
+
+  /**
+   * Builds tscircuit components to circuit-json.
+   */
+  private async buildTscircuitComponents(): Promise<BuiltTscircuitComponent[]> {
+    const builtTscircuitComponents: BuiltTscircuitComponent[] = []
+    const { entrypoint } = this.options
+
+    const exports = await this.options.getExportsFromTsxFile(entrypoint)
+    const componentExports = exports.filter((name) => /^[A-Z]/.test(name))
+
+    for (const exportName of componentExports) {
+      let componentPath = entrypoint
+      if (this.options.resolveExportPath) {
+        const resolved = await this.options.resolveExportPath(
+          entrypoint,
+          exportName,
+        )
+        if (resolved) componentPath = resolved
+      }
+
+      const circuitJson = await this.options.buildFileToCircuitJson(
+        componentPath,
+        exportName,
+      )
+      if (
+        circuitJson &&
+        (!Array.isArray(circuitJson) || circuitJson.length > 0)
+      ) {
+        builtTscircuitComponents.push({
+          tscircuitComponentName: exportName,
+          circuitJson,
+        })
+      }
+    }
+
+    return builtTscircuitComponents
+  }
+
+  /**
+   * Extracts KiCad footprints and symbols from built tscircuit components.
+   */
+  private extractKicadComponents(): ExtractedKicadComponent[] {
+    const extractedKicadComponents: ExtractedKicadComponent[] = []
+
+    for (const builtTscircuitComponent of this.ctx.builtTscircuitComponents) {
+      const { tscircuitComponentName, circuitJson } = builtTscircuitComponent
+
+      const libConverter = new CircuitJsonToKicadLibraryConverter(circuitJson, {
+        libraryName: this.ctx.kicadLibraryName,
+        footprintLibraryName: this.ctx.kicadLibraryName,
+      })
+      libConverter.runUntilFinished()
+      const libOutput = libConverter.getOutput()
+
+      // Collect 3D model paths
+      for (const path of libOutput.model3dSourcePaths) {
+        if (!this.ctx.model3dSourcePaths.includes(path)) {
+          this.ctx.model3dSourcePaths.push(path)
+        }
+      }
+
+      extractedKicadComponents.push({
+        tscircuitComponentName,
+        kicadFootprints: libOutput.footprints,
+        kicadSymbols: libOutput.symbols,
+        model3dSourcePaths: libOutput.model3dSourcePaths,
+      })
+    }
+
+    return extractedKicadComponents
+  }
+
+  getOutput(): KicadLibraryConverterOutput {
+    if (!this.output) {
+      throw new Error(
+        "Converter has not been run yet. Call run() before getOutput().",
+      )
+    }
+    return this.output
+  }
+}
+
+/**
+ * Creates an initialized context for the KiCad library converter.
+ */
+function createKicadLibraryConverterContext(params: {
+  kicadLibraryName: string
+  includeBuiltins: boolean
+}): KicadLibraryConverterContext {
+  return {
+    kicadLibraryName: params.kicadLibraryName,
+    includeBuiltins: params.includeBuiltins,
+    builtTscircuitComponents: [],
+    extractedKicadComponents: [],
+    userKicadFootprints: [],
+    builtinKicadFootprints: [],
+    userKicadSymbols: [],
+    builtinKicadSymbols: [],
+    model3dSourcePaths: [],
+    kicadProjectFsMap: {},
+  }
+}

lib/kicad-library/KicadLibraryConverterTypes.ts

@@ -0,0 +1,113 @@
+import type { CircuitJson } from "circuit-json"
+import type { SymbolEntry, FootprintEntry } from "../types"
+
+export interface KicadLibraryConverterOptions {
+  /**
+   * Name for the generated KiCad library (e.g., "my-library").
+   * This will be used for the user library files.
+   */
+  kicadLibraryName?: string
+
+  /**
+   * The main entry point file for the library (e.g., "lib/my-library.ts").
+   * This file's exports define the public API of the library.
+   */
+  entrypoint: string
+
+  /**
+   * Callback to build circuit JSON from a file path and export name.
+   * Should handle both board components and symbol components:
+   * - For board components: render inside a <board> element
+   * - For symbol components: render inside a <chip> with the symbol prop
+   *   (Note: tscircuit symbols cannot render standalone - they must be
+   *   used as a prop on a <chip> component)
+   * Return null if the export cannot be rendered.
+   */
+  buildFileToCircuitJson: (
+    filePath: string,
+    componentName: string,
+  ) => Promise<CircuitJson | null>
+
+  /**
+   * Callback to get all exports from a TSX/TS file.
+   * Must evaluate the file (not just parse) to handle `export * from` patterns.
+   */
+  getExportsFromTsxFile: (filePath: string) => Promise<string[]>
+
+  /**
+   * Callback to resolve an export name to its file path.
+   * Returns the file path where the component is defined, or null if not resolvable.
+   */
+  resolveExportPath?: (
+    entrypoint: string,
+    exportName: string,
+  ) => Promise<string | null>
+
+  /**
+   * Whether to include builtin footprints/symbols (like 0402, soic8).
+   * Default: true
+   */
+  includeBuiltins?: boolean
+}
+
+export interface KicadLibraryConverterOutput {
+  /**
+   * Map of file paths to file contents for the generated KiCad library.
+   */
+  kicadProjectFsMap: Record<string, string | Buffer>
+
+  /**
+   * Source paths to 3D model files that need to be copied.
+   */
+  model3dSourcePaths: string[]
+}
+
+/**
+ * A component that has been built to circuit JSON.
+ */
+export interface BuiltTscircuitComponent {
+  tscircuitComponentName: string
+  circuitJson: CircuitJson
+}
+
+/**
+ * A component with its extracted KiCad footprints and symbols.
+ */
+export interface ExtractedKicadComponent {
+  tscircuitComponentName: string
+  kicadFootprints: FootprintEntry[]
+  kicadSymbols: SymbolEntry[]
+  model3dSourcePaths: string[]
+}
+
+/**
+ * Context for the KiCad library converter stages.
+ */
+export interface KicadLibraryConverterContext {
+  kicadLibraryName: string
+  includeBuiltins: boolean
+
+  /** Tscircuit components built to circuit-json */
+  builtTscircuitComponents: BuiltTscircuitComponent[]
+
+  /** KiCad footprints and symbols extracted from circuit-json */
+  extractedKicadComponents: ExtractedKicadComponent[]
+
+  /** User-defined footprints (custom footprint={<footprint>...}) */
+  userKicadFootprints: FootprintEntry[]
+
+  /** Builtin footprints (from footprinter like 0402, soic8) */
+  builtinKicadFootprints: FootprintEntry[]
+
+  /** User-defined symbols (custom symbol={<symbol>...} or renamed for custom footprint) */
+  userKicadSymbols: SymbolEntry[]
+
+  /** Builtin symbols (from schematic-symbols package) */
+  builtinKicadSymbols: SymbolEntry[]
+
+  /** 3D model source paths to copy */
+  model3dSourcePaths: string[]
+
+  /** Final output file map */
+  kicadProjectFsMap: Record<string, string | Buffer>
+}

lib/kicad-library/kicad-library-converter-utils/generateFpLibTable.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate fp-lib-table content for KiCad footprint library.
+ */
+export function generateFpLibTable(params: {
+  kicadLibraryName: string
+  includeBuiltin: boolean
+}): string {
+  const { kicadLibraryName, includeBuiltin } = params
+  let content = "(fp_lib_table\n"
+  content += `  (lib (name "${kicadLibraryName}")(type "KiCad")(uri "\${KIPRJMOD}/footprints/${kicadLibraryName}.pretty")(options "")(descr ""))\n`
+  if (includeBuiltin) {
+    content += `  (lib (name "tscircuit_builtin")(type "KiCad")(uri "\${KIPRJMOD}/footprints/tscircuit_builtin.pretty")(options "")(descr ""))\n`
+  }
+  content += ")\n"
+  return content
+}

lib/kicad-library/kicad-library-converter-utils/generateSymLibTable.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate sym-lib-table content for KiCad symbol library.
+ */
+export function generateSymLibTable(params: {
+  kicadLibraryName: string
+  includeBuiltin: boolean
+}): string {
+  const { kicadLibraryName, includeBuiltin } = params
+  let content = "(sym_lib_table\n"
+  content += `  (lib (name "${kicadLibraryName}")(type "KiCad")(uri "\${KIPRJMOD}/symbols/${kicadLibraryName}.kicad_sym")(options "")(descr ""))\n`
+  if (includeBuiltin) {
+    content += `  (lib (name "tscircuit_builtin")(type "KiCad")(uri "\${KIPRJMOD}/symbols/tscircuit_builtin.kicad_sym")(options "")(descr ""))\n`
+  }
+  content += ")\n"
+  return content
+}

lib/kicad-library/kicad-library-converter-utils/renameKicadFootprint.ts

@@ -0,0 +1,34 @@
+import type { FootprintEntry } from "../../types"
+import { parseKicadMod } from "kicadts"
+
+/**
+ * Rename a KiCad footprint entry to use a new name.
+ */
+export function renameKicadFootprint(params: {
+  kicadFootprint: FootprintEntry
+  newKicadFootprintName: string
+  kicadLibraryName: string
+}): FootprintEntry {
+  const { kicadFootprint, newKicadFootprintName, kicadLibraryName } = params
+
+  const footprint = parseKicadMod(kicadFootprint.kicadModString)
+
+  // Update the footprint name (libraryLink)
+  footprint.libraryLink = newKicadFootprintName
+
+  // Update 3D model paths to use the correct library name
+  for (const model of footprint.models) {
+    const currentPath = model.path
+    if (currentPath.includes("${KIPRJMOD}/")) {
+      // Extract the filename from the path
+      const filename = currentPath.split("/").pop() ?? ""
+      model.path = `\${KIPRJMOD}/3dmodels/${kicadLibraryName}.3dshapes/${filename}`
+    }
+  }
+
+  return {
+    footprintName: newKicadFootprintName,
+    kicadModString: footprint.getString(),
+    model3dSourcePaths: kicadFootprint.model3dSourcePaths,
+  }
+}

lib/kicad-library/kicad-library-converter-utils/renameKicadSymbol.ts

@@ -0,0 +1,29 @@
+import type { SymbolEntry } from "../../types"
+
+/**
+ * Rename a KiCad symbol entry to use a new name.
+ * Updates child symbol units (subSymbols) to match the new name.
+ */
+export function renameKicadSymbol(params: {
+  kicadSymbol: SymbolEntry
+  newKicadSymbolName: string
+}): SymbolEntry {
+  const { kicadSymbol, newKicadSymbolName } = params
+  const symbol = kicadSymbol.symbol
+  const oldName = symbol.libraryId
+
+  // Update main symbol name
+  symbol.libraryId = newKicadSymbolName
+
+  // Update child symbol unit names (e.g., "OldName_0_1" -> "NewName_0_1")
+  if (oldName && symbol.subSymbols) {
+    for (const subSymbol of symbol.subSymbols) {
+      if (subSymbol.libraryId?.startsWith(oldName)) {
+        const suffix = subSymbol.libraryId.slice(oldName.length)
+        subSymbol.libraryId = newKicadSymbolName + suffix
+      }
+    }
+  }
+
+  return { symbolName: newKicadSymbolName, symbol }
+}

lib/kicad-library/kicad-library-converter-utils/updateBuiltinKicadSymbolFootprint.ts

@@ -0,0 +1,21 @@
+import type { SymbolEntry } from "../../types"
+
+/**
+ * Update a builtin KiCad symbol's footprint reference to point to tscircuit_builtin library.
+ */
+export function updateBuiltinKicadSymbolFootprint(
+  kicadSymbol: SymbolEntry,
+): SymbolEntry {
+  const symbol = kicadSymbol.symbol
+  const properties = symbol.properties ?? []
+
+  for (const prop of properties) {
+    if (prop.key === "Footprint" && prop.value) {
+      const parts = prop.value.split(":")
+      const footprintName = parts.length > 1 ? parts[1] : parts[0]
+      prop.value = `tscircuit_builtin:${footprintName}`
+    }
+  }
+
+  return { symbolName: kicadSymbol.symbolName, symbol }
+}