KiCad_Library/update_component_index.py

#!/usr/bin/env python3
"""
Parses all .kicad_sym files in symbols/ and updates the Component Index
table in README.md with the actual contents of the library.

Reads the following fields from each symbol:
  Value, MPN, Digikey_PN, Manufacturer, Footprint, ki_description (or Description)

Run locally:   python3 .github/scripts/update_component_index.py
Run in CI:     triggered automatically on push to symbols/
"""

import re
import os
from pathlib import Path
from datetime import date

SYMBOLS_DIR = Path("symbols")
README_PATH = Path("README.md")

# Maps symbol filename (without extension) to a human-readable category label
LIBRARY_LABELS = {
    "0_ic_logic":     "0_ic_logic",
    "0_ic_mcu":       "0_ic_mcu",
    "0_ic_driver":    "0_ic_driver",
    "0_ic_power":     "0_ic_power",
    "0_ic_analog":    "0_ic_analog",
    "0_ic_rf":        "0_ic_rf",
    "0_ic_interface": "0_ic_interface",
    "0_passive":      "0_passive",
    "0_connector":    "0_connector",
    "0_discrete":     "0_discrete",
}

# Order categories should appear in the table
CATEGORY_ORDER = [
    "0_ic_logic",
    "0_ic_driver",
    "0_ic_power",
    "0_ic_analog",
    "0_ic_mcu",
    "0_ic_rf",
    "0_ic_interface",
    "0_passive",
    "0_connector",
    "0_discrete",
]


def parse_field(symbol_block: str, field_name: str) -> str:
    """Extract a named field value from a symbol block."""
    # KiCad sym format: (property "FieldName" "Value" ...)
    pattern = rf'\(property\s+"{re.escape(field_name)}"\s+"([^"]*)"'
    match = re.search(pattern, symbol_block)
    return match.group(1).strip() if match else ""


def parse_symbols_from_file(filepath: Path) -> list[dict]:
    """
    Parse all symbols from a .kicad_sym file.
    Returns a list of dicts with keys: name, mpn, description, footprint, digikey_pn, manufacturer
    """
    content = filepath.read_text(encoding="utf-8")
    symbols = []

    # Find all top-level symbol blocks
    # Each starts with: (symbol "NAME"
    symbol_pattern = re.compile(r'\(symbol\s+"([^"]+)"(?!\s+\(extends)', re.MULTILINE)

    matches = list(symbol_pattern.finditer(content))

    for i, match in enumerate(matches):
        name = match.group(1)

        # Skip sub-units (contain _ followed by digits at the end e.g. "SN74HC193_0_1")
        # KiCad uses these internally for multi-unit symbols
        if re.search(r'_\d+_\d+$', name):
            continue

        # Extract the block for this symbol (up to next top-level symbol or end)
        start = match.start()
        end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
        block = content[start:end]

        mpn          = parse_field(block, "MPN") or parse_field(block, "Value") or name
        description  = (parse_field(block, "ki_description")
                        or parse_field(block, "Description")
                        or parse_field(block, "description")
                        or "")
        footprint    = parse_field(block, "Footprint")
        digikey_pn   = parse_field(block, "Digikey_PN") or parse_field(block, "Digikey PN") or "-"
        manufacturer = parse_field(block, "Manufacturer") or "-"

        # Shorten footprint for table readability — keep library:name but trim long paths
        if footprint and ":" in footprint:
            lib_part, fp_name = footprint.split(":", 1)
            # Truncate very long footprint names
            if len(fp_name) > 30:
                fp_name = fp_name[:27] + "..."
            footprint = f"{lib_part}:{fp_name}"

        symbols.append({
            "name":         name,
            "mpn":          mpn,
            "description":  description,
            "footprint":    footprint or "-",
            "digikey_pn":   digikey_pn,
            "manufacturer": manufacturer,
        })

    return symbols


def build_component_table(all_symbols: dict[str, list[dict]]) -> str:
    """Build the full markdown component index table."""
    lines = []
    lines.append("| MPN | Description | Manufacturer | Symbol Library | Footprint | Digikey PN |")
    lines.append("|---|---|---|---|---|---|")

    total = 0
    for category in CATEGORY_ORDER:
        symbols = all_symbols.get(category, [])
        if not symbols:
            continue
        for s in sorted(symbols, key=lambda x: x["mpn"]):
            lines.append(
                f"| {s['mpn']} "
                f"| {s['description'] or '—'} "
                f"| {s['manufacturer']} "
                f"| {category} "
                f"| {s['footprint']} "
                f"| {s['digikey_pn']} |"
            )
            total += 1

    lines.append("")
    lines.append(f"*{total} components — auto-generated {date.today().isoformat()}*")
    return "\n".join(lines)


def update_readme(new_table: str) -> bool:
    """
    Replace the content between the Component Index header and the next
    top-level ## header in README.md with the new table.
    Returns True if the file was changed.
    """
    readme = README_PATH.read_text(encoding="utf-8")

    # Match from ## Component Index to the next ## section or end of file
    pattern = re.compile(
        r'(## Component Index\n+)(.*?)(\n## |\Z)',
        re.DOTALL
    )

    match = pattern.search(readme)
    if not match:
        print("ERROR: Could not find '## Component Index' section in README.md")
        return False

    original_block = match.group(2)
    new_block = new_table + "\n\n"

    if original_block == new_block:
        return False

    updated_readme = (
        readme[:match.start(2)]
        + new_block
        + readme[match.start(3):]
    )

    README_PATH.write_text(updated_readme, encoding="utf-8")
    return True


def main():
    if not SYMBOLS_DIR.exists():
        print(f"ERROR: symbols/ directory not found. Run from repo root.")
        return

    if not README_PATH.exists():
        print(f"ERROR: README.md not found. Run from repo root.")
        return

    all_symbols: dict[str, list[dict]] = {}

    for sym_file in sorted(SYMBOLS_DIR.glob("*.kicad_sym")):
        lib_name = sym_file.stem
        symbols = parse_symbols_from_file(sym_file)
        if symbols:
            all_symbols[lib_name] = symbols
            print(f"  {lib_name}: {len(symbols)} symbol(s)")
        else:
            print(f"  {lib_name}: empty")

    if not any(all_symbols.values()):
        print("No symbols found — README not updated.")
        return

    total = sum(len(v) for v in all_symbols.values())
    print(f"\nTotal: {total} symbols across {len(all_symbols)} libraries")

    table = build_component_table(all_symbols)
    changed = update_readme(table)

    if changed:
        print("\nREADME.md component index updated.")
    else:
        print("\nREADME.md already up to date.")


if __name__ == "__main__":
    main()