Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/datasheets

datasheets

Verified

Extract structured specifications from electronic component datasheet PDFs — pinouts, electrical characteristics, peripherals, topology, and features. Cache extractions per project for consumption by schematic and PCB analyzers. Primary consumer infrastructure for `kicad`, `emc`, `spice`, and `thermal` analyzers. Use this skill whenever the user asks to extract, verify, or read specs from a component datasheet; when analyzers need verified IC knowledge (EN pin thresholds, PG presence, USB peripheral speed); or when a review mentions datasheet coverage, extraction quality, or per-MPN specifications. Also triggers on "extract this datasheet", "what are the specs for MPN X", "verify datasheet extraction", or "check pin functions for part Y".

FileKindSize
SKILL.mdskill md11.2 KB
datasheet_types/__init__.pyscript1.9 KB
datasheet_types/base_block.pyscript6.5 KB
datasheet_types/cache_reader.pyscript12.3 KB
datasheet_types/codec.pyscript6.3 KB
datasheet_types/extraction.pyscript8.0 KB
datasheet_types/pinout.pyscript5.2 KB
datasheet_types/regulator.pyscript5.3 KB
datasheet_types/spec_value.pyscript2.4 KB
datasheet_types/trust_gating.pyscript5.0 KB
distributor_core/__init__.pyscript0 B
distributor_core/cli.pyscript2.9 KB
distributor_core/download.pyscript36.7 KB
distributor_core/inputs.pyscript9.0 KB
distributor_core/manifest.pyscript5.7 KB
distributor_core/sync.pyscript21.0 KB
distributor_core/verify.pyscript12.1 KB
examples/abm8g-106-12.000mhz-t.jsonconfig9.4 KB
examples/irlml6344.jsonconfig16.0 KB
examples/lm2596-adj.jsonconfig14.3 KB
examples/lm358.jsonconfig15.6 KB
examples/mbrs540t3g.jsonconfig12.3 KB
examples/stm32f103c8t6.jsonconfig51.1 KB
prompts/base.mdmarkdown4.5 KB
prompts/crystal.mdmarkdown8.8 KB
prompts/diode.mdmarkdown8.3 KB
prompts/mcu.mdmarkdown9.6 KB
prompts/opamp.mdmarkdown10.7 KB
prompts/pinout.mdmarkdown4.7 KB
prompts/regulator.mdmarkdown4.4 KB
prompts/scout.mdmarkdown3.5 KB
prompts/transistor.mdmarkdown12.5 KB
references/cache-layout.mdmarkdown8.4 KB
references/consumer-api.mdmarkdown10.8 KB
references/dispatch-claude-code.mdmarkdown9.4 KB
references/dispatcher-contract.mdmarkdown8.2 KB
references/extraction-pipeline.mdmarkdown1.7 KB
references/extraction-schema.mdmarkdown18.0 KB
references/field-extraction-guide.mdmarkdown14.9 KB
references/quality-scoring.mdmarkdown8.4 KB
schemas/CHANGELOG.mdmarkdown16.0 KB
schemas/base.schema.jsonconfig9.3 KB
schemas/crystal.schema.jsonconfig7.2 KB
schemas/diode.schema.jsonconfig7.9 KB
schemas/extraction.schema.jsonconfig3.7 KB
schemas/fixtures/lm2596-adj.example.jsonconfig14.3 KB
schemas/fixtures/manifest.example.jsonconfig1000 B
schemas/fixtures/minimal.example.jsonconfig2.1 KB
schemas/manifest.schema.jsonconfig3.0 KB
schemas/mcu.schema.jsonconfig12.4 KB
schemas/opamp.schema.jsonconfig9.2 KB
schemas/pinout.schema.jsonconfig5.9 KB
schemas/plan.schema.jsonconfig4.6 KB
schemas/regulator.schema.jsonconfig8.4 KB
schemas/scout.schema.jsonconfig2.9 KB
schemas/spec_value.schema.jsonconfig3.0 KB
schemas/transistor.schema.jsonconfig12.0 KB
scripts/_smoke_v14_roundtrip.pyscript8.9 KB
scripts/datasheet_extract_cache.pyscript21.2 KB
scripts/datasheet_features.pyscript17.1 KB
scripts/datasheet_page_selector.pyscript16.7 KB
scripts/datasheet_score.pyscript15.5 KB
scripts/datasheet_verify.pyscript45.6 KB
scripts/extraction_schema.pyscript1.8 KB
scripts/merge_results.pyscript13.0 KB
scripts/plan_extraction.pyscript9.5 KB
scripts/validate_extraction_result.pyscript4.0 KB
scripts/validate_sanity_vector.pyscript6.4 KB

scripts/datasheet_verify.py

View on GitHub
"""Datasheet verification bridge for kicad-happy.

Compares extracted datasheet specifications against actual schematic
connections. Produces findings for voltage violations, missing required
external components, and decoupling inadequacy.

Requires datasheets/extracted/ cache populated by the LLM extraction
pipeline (via sync_datasheets_digikey + Claude extraction).
"""

import os
import re
import sys

# Allow imports from same directory
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from datasheet_types.cache_reader import MAX_CACHE_BYTES, safe_extract_dir  # noqa: E402
from datasheet_extract_cache import find_extraction  # noqa: E402


MAX_EXTRACTION_BYTES = MAX_CACHE_BYTES


def _load_extraction(extract_dir: str, mpn: str) -> dict:
    """Load extraction JSON for an MPN. Always returns dict; never None.

    Returns {} only for: missing dir, missing MPN, file not found, JSON
    parse error, undecodable, non-object, symlinked or oversized file, or
    OSError. Quality is NOT a gate here — callers emit an `extraction_quality_low` info finding via
    `_quality_finding` instead.

    Lookup order (shared with the feature helpers and the lifecycle audit):
    a v1.4 file named after the part, then the extraction manifest, then any
    file named after the part.

    Two cache shapes supported:
    - v1.4: extraction.quality_score on 0-100 scale.
    - v1.3 legacy: extraction_metadata.extraction_score (cache manager) or
      meta.extraction_score on 0-10 scale.
    """
    if not extract_dir or not mpn:
        return {}

    return find_extraction(extract_dir, mpn)[0] or {}


def _is_sectioned_format(extraction: dict) -> bool:
    """Return True if extraction is sectioned (has a top-level 'base' key)."""
    return isinstance(extraction.get("base"), dict)


def _domain_absolute_voltage_max(base: dict, domain: str) -> float | None:
    """Resolve a per-domain abs-max voltage from base.absolute_max.

    Tries key patterns: "<domain>_max", "<domain>".  Returns the SpecValue
    `max` field (first entry) or None if unavailable.
    """
    abs_max = base.get("absolute_max") or {}
    for key in (f"{domain}_max", domain):
        sv_list = abs_max.get(key)
        if isinstance(sv_list, list) and sv_list:
            sv = sv_list[0]
            if isinstance(sv, dict):
                v = sv.get("max")
                if isinstance(v, (int, float)):
                    return v
    return None


def _domain_operating_voltage_max(base: dict, domain: str) -> float | None:
    """Resolve a per-domain operating-max voltage from base.recommended_operating."""
    rec_op = base.get("recommended_operating") or {}
    sv_list = rec_op.get(domain)
    if isinstance(sv_list, list) and sv_list:
        sv = sv_list[0]
        if isinstance(sv, dict):
            v = sv.get("max")
            if isinstance(v, (int, float)):
                return v
    return None


def _legacy_verifier_view(extraction: dict) -> dict:
    """Return a flat legacy view of an extraction dict for use by the verifiers.

    Flat legacy (has 'pins'): returned unchanged.
    Sectioned (base/pinout, has 'base'): synthesize the flat legacy keys the
    verifiers READ:
      - 'pins': list of dicts with 'number', 'name', 'type', 'voltage_abs_max',
        'voltage_operating_max'.  One entry per number of each base.pinout[]
        record, with voltage limits resolved per-domain from
        base.absolute_max / base.recommended_operating via power_domain.
        A pin's own absolute_max / recommended SpecValue lists
        (pinout.schema.json) override the domain values. A 5 V-tolerant pin
        takes only its own limits: the domain's are not its limits, so
        without its own it gets no check.
        'required_external' is NOT synthesised (no v2 equivalent) — verifiers
        skip pins without it, so externals/decoupling remain unverifiable.
      - 'application_circuit': NOT synthesised — no v2 equivalent key.
        verify_decoupling short-circuits on its absence.

    Returns {} (empty) if extraction is neither shape.
    """
    if not extraction:
        return extraction
    # v1: already has pins list at top level
    if "pins" in extraction:
        return extraction
    # sectioned: synthesise flat legacy pins from base.pinout
    if not _is_sectioned_format(extraction):
        return extraction
    base = extraction["base"]
    pinout = base.get("pinout") or []
    v1_pins = []
    for pin in pinout:
        if not isinstance(pin, dict):
            continue
        numbers = pin.get("numbers") or []
        if isinstance(numbers, str):
            numbers = [numbers]
        numbers = [str(n) for n in numbers if str(n)]
        if not numbers:
            continue
        pin_type = pin.get("type") or ""
        domain = pin.get("power_domain")
        v_abs_max = _spec_max_voltage(pin.get("absolute_max"))
        if not isinstance(v_abs_max, (int, float)):
            v_abs_max = None
        v_op_max = _spec_max_voltage(pin.get("recommended"))
        if not isinstance(v_op_max, (int, float)):
            v_op_max = None
        if domain and pin.get("is_5v_tolerant") is not True:
            if v_abs_max is None:
                v_abs_max = _domain_absolute_voltage_max(base, domain)
            if v_op_max is None:
                v_op_max = _domain_operating_voltage_max(base, domain)
        for pin_number in numbers:
            v1_pins.append({
                "number": pin_number,
                "name": pin.get("name") or f"pin {pin_number}",
                "type": pin_type,
                "voltage_abs_max": v_abs_max,
                "voltage_operating_max": v_op_max,
                # required_external intentionally absent — no v2 equivalent
            })
    # Build the minimal v1 view; no application_circuit (no v2 equivalent)
    return {"pins": v1_pins, "_v2_adapted": True}


def _not_verifiable_finding(mpn: str, detail: str) -> dict:
    """Info finding when a trust-gate-passing extraction has no usable data
    for a verifier.  Degradation must be VISIBLE, never silent.
    """
    return {
        "type": "extraction_not_verifiable",
        "severity": "info",
        "mpn": mpn,
        "detail": detail,
    }


def _v13_score(extraction: dict):
    """Legacy 0-10 score: the cache manager's `extraction_metadata`, else `meta`."""
    for block in ("extraction_metadata", "meta"):
        meta = extraction.get(block)
        score = meta.get("extraction_score") if isinstance(meta, dict) else None
        if isinstance(score, (int, float)):
            return score
    return None


def _v14_score(extraction: dict):
    """v1.4 0-100 score from the `extraction` block, or None."""
    block = extraction.get("extraction")
    score = block.get("quality_score") if isinstance(block, dict) else None
    return score if isinstance(score, (int, float)) else None


def _passes_trust_gate(extraction: dict) -> bool:
    """Return True if extraction quality is acceptable (or unknown).

    v1.4: extraction.quality_score 0-100, threshold 60.
    v1.3: extraction_metadata (else meta).extraction_score 0-10, threshold 6.0.
    No quality metadata at all: pass (don't gate; let downstream decide).
    """
    quality_v14 = _v14_score(extraction)
    if quality_v14 is not None:
        return quality_v14 >= 60
    quality_v13 = _v13_score(extraction)
    if isinstance(quality_v13, (int, float)):
        return quality_v13 >= 6.0
    return True


def _quality_finding(mpn, extraction):
    """Info finding when extraction quality is below the trust threshold.

    Quality is visible data, not a gate. Returns None
    when the extraction passes the threshold or carries no score.
    """
    if not extraction or _passes_trust_gate(extraction):
        return None
    q14 = _v14_score(extraction)
    q13 = _v13_score(extraction)
    score = q14 if q14 is not None else q13
    return {
        "type": "extraction_quality_low",
        "severity": "info",
        "mpn": mpn,
        "quality_score": score,
        "detail": (f"{mpn}: extraction quality score {score} is below the "
                   f"trust threshold; verification findings for this part "
                   f"are based on a low-quality extraction"),
    }


def _resolve_extract_dir(project_dir: str) -> str:
    """The project's own datasheets/extracted/ directory, or "" when absent.
    The parent folder is not searched: for a project in a shared temp dir it
    could hold extractions planted by another user."""
    c = os.path.join(project_dir, "datasheets", "extracted")
    return c if os.path.isdir(c) and safe_extract_dir(c) is not None else ""


def _estimate_net_voltage(net_name: str, rail_voltages: dict) -> float:
    """Estimate the voltage on a net from rail_voltages or name parsing."""
    if not net_name:
        return None

    # Direct lookup in rail_voltages
    v = rail_voltages.get(net_name)
    if v is not None:
        return v

    # Parse from name: +3V3 → 3.3, +5V → 5.0, 12V0 → 12.0
    nu = net_name.upper().lstrip("+").rstrip("V")
    # VnnVn format: 3V3 → 3.3
    m = re.match(r'^(\d+)V(\d+)$', nu)
    if m:
        return float(f"{m.group(1)}.{m.group(2)}")
    # Plain voltage: 5V → 5.0, 12V → 12.0
    m = re.match(r'^(\d+\.?\d*)V?$', nu)
    if m:
        return float(m.group(1))

    return None


def verify_pin_voltages(components: list, nets: dict, extraction_dir: str,
                        rail_voltages: dict) -> list:
    """P1: Verify pin voltage boundaries against datasheet abs max / operating ranges.

    For each IC with an extraction, checks every pin's connected net voltage
    against the pin's voltage_abs_max and voltage_operating_max from the
    extraction.

    Returns list of finding dicts.
    """
    findings = []
    seen_quality_mpns: set = set()

    for comp in components:
        if comp.get("type") != "ic":
            continue
        ref = comp["reference"]
        mpn = comp.get("mpn") or comp.get("value", "")
        if not mpn or mpn == ref:
            continue

        extraction = _load_extraction(extraction_dir, mpn)
        if mpn not in seen_quality_mpns:
            seen_quality_mpns.add(mpn)
            qf = _quality_finding(mpn, extraction)
            if qf:
                findings.append(qf)
        if not extraction:
            continue
        view = _legacy_verifier_view(extraction)
        if not view or not view.get("pins"):
            # Loud only for v2-adapted views; v1 caches without
            # pins keep the pre-adapter silent-skip behavior byte-identical.
            if view.get("_v2_adapted") and _passes_trust_gate(extraction):
                findings.append(_not_verifiable_finding(
                    mpn,
                    "pin-voltage checks could not run: extraction has no usable pin voltage data",
                ))
            continue

        pin_nets = comp.get("pin_nets", {})
        if not pin_nets:
            continue

        # Build pin lookup from extraction: pin_number → pin_data
        ext_pins = {}
        for p in view["pins"]:
            pnum = str(p.get("number", ""))
            if pnum:
                ext_pins[pnum] = p

        for pin_num, net_name in pin_nets.items():
            ext_pin = ext_pins.get(pin_num)
            if not ext_pin:
                continue

            # Skip GND pins
            pin_type = (ext_pin.get("type") or "").lower()
            if pin_type in ("ground", "gnd"):
                continue

            v_abs_max = ext_pin.get("voltage_abs_max")
            v_op_max = ext_pin.get("voltage_operating_max")
            net_voltage = _estimate_net_voltage(net_name, rail_voltages)

            if net_voltage is None:
                continue

            pin_name = ext_pin.get("name", f"pin {pin_num}")

            # Check abs max violation
            if v_abs_max is not None and net_voltage > v_abs_max:
                findings.append({
                    "type": "pin_voltage_abs_max_exceeded",
                    "severity": "error",
                    "ref": ref,
                    "mpn": mpn,
                    "pin_number": pin_num,
                    "pin_name": pin_name,
                    "net": net_name,
                    "net_voltage_V": net_voltage,
                    "abs_max_V": v_abs_max,
                    "margin_V": round(v_abs_max - net_voltage, 3),
                    "detail": (f"{ref} pin {pin_num} ({pin_name}) on {net_name} "
                               f"({net_voltage}V) exceeds absolute maximum "
                               f"({v_abs_max}V) by {net_voltage - v_abs_max:.2f}V"),
                })
            # Check operating range exceeded (warning, not critical)
            elif v_op_max is not None and net_voltage > v_op_max:
                margin_pct = (v_abs_max - net_voltage) / v_abs_max * 100 if v_abs_max else 0
                findings.append({
                    "type": "pin_voltage_operating_exceeded",
                    "severity": "error" if margin_pct < 10 else "warning",
                    "ref": ref,
                    "mpn": mpn,
                    "pin_number": pin_num,
                    "pin_name": pin_name,
                    "net": net_name,
                    "net_voltage_V": net_voltage,
                    "operating_max_V": v_op_max,
                    "abs_max_V": v_abs_max,
                    "detail": (f"{ref} pin {pin_num} ({pin_name}) on {net_name} "
                               f"({net_voltage}V) exceeds recommended operating "
                               f"maximum ({v_op_max}V)"),
                })

    return findings


def verify_required_externals(components: list, nets: dict, extraction_dir: str,
                              comp_lookup: dict) -> list:
    """P1: Verify required external components per datasheet pin specs.

    Checks pins with 'required_external' field in extraction — these are
    pins where the datasheet says "connect X here" (bypass cap, pull-up,
    inductor, etc.). Verifies something appropriate is actually connected.

    Returns list of finding dicts.
    """
    findings = []
    seen_quality_mpns: set = set()

    for comp in components:
        if comp.get("type") != "ic":
            continue
        ref = comp["reference"]
        mpn = comp.get("mpn") or comp.get("value", "")
        if not mpn or mpn == ref:
            continue

        extraction = _load_extraction(extraction_dir, mpn)
        if mpn not in seen_quality_mpns:
            seen_quality_mpns.add(mpn)
            qf = _quality_finding(mpn, extraction)
            if qf:
                findings.append(qf)
        if not extraction:
            continue
        view = _legacy_verifier_view(extraction)
        if not view or not view.get("pins"):
            # Loud only for v2-adapted views; v1 caches without
            # pins keep the pre-adapter silent-skip behavior byte-identical.
            if view.get("_v2_adapted") and _passes_trust_gate(extraction):
                findings.append(_not_verifiable_finding(
                    mpn,
                    "required-external checks could not run: extraction has no usable pin data",
                ))
            continue
        # v2-adapted views have pins but no required_external per pin
        if view.get("_v2_adapted") and _passes_trust_gate(extraction):
            findings.append(_not_verifiable_finding(
                mpn,
                "required-external checks could not run: "
                "v2 extraction format has no per-pin required_external data",
            ))

        pin_nets = comp.get("pin_nets", {})

        ext_pins = {}
        for p in view["pins"]:
            pnum = str(p.get("number", ""))
            if pnum:
                ext_pins[pnum] = p

        for pin_num, net_name in pin_nets.items():
            ext_pin = ext_pins.get(pin_num)
            if not ext_pin:
                continue

            required = ext_pin.get("required_external")
            if not required:
                continue

            pin_name = ext_pin.get("name", f"pin {pin_num}")
            pin_type = (ext_pin.get("type") or "").lower()

            # Skip ground pins (always connected)
            if pin_type in ("ground", "gnd"):
                continue

            # Check what's connected to this pin's net
            net_info = nets.get(net_name, {})
            net_pins = net_info.get("pins", []) if isinstance(net_info, dict) else []

            # Find other components on this net (excluding the IC itself)
            connected_refs = set()
            connected_types = set()
            for p in net_pins:
                c_ref = p.get("component", "")
                if c_ref and c_ref != ref:
                    connected_refs.add(c_ref)
                    c = comp_lookup.get(c_ref, {})
                    connected_types.add(c.get("type", ""))

            # Parse required_external for expected component types
            req_lower = required.lower()
            expected_types = set()
            if any(k in req_lower for k in ("cap", "capacitor", "decoupling", "bypass")):
                expected_types.add("capacitor")
            if any(k in req_lower for k in ("resistor", "pull-up", "pullup", "pull-down", "divider")):
                expected_types.add("resistor")
            if any(k in req_lower for k in ("inductor", "ferrite", "bead")):
                expected_types.update(("inductor", "ferrite_bead"))
            if any(k in req_lower for k in ("diode", "schottky")):
                expected_types.add("diode")

            if not expected_types:
                continue  # Can't parse requirement — skip

            # Check if any expected type is connected
            if not expected_types & connected_types:
                # Nothing matching the requirement is connected
                findings.append({
                    "type": "missing_required_external",
                    "severity": "error",
                    "ref": ref,
                    "mpn": mpn,
                    "pin_number": pin_num,
                    "pin_name": pin_name,
                    "net": net_name,
                    "required": required,
                    "expected_types": sorted(expected_types),
                    "connected_types": sorted(connected_types),
                    "detail": (f"{ref} pin {pin_num} ({pin_name}): datasheet requires "
                               f"\"{required}\" but none found on net {net_name}"),
                })

    return findings


# Capacitance units, micro as "u", the micro sign or Greek mu.
_CAP_UNIT = r'(?:uf|\u00b5f|\u03bcf|nf|pf)'
# A count is not followed by more digits/letters or by a capacitance unit.
_NOT_A_VALUE = r'(?![\w.]|\s*' + _CAP_UNIT + ')'


def _parse_cap_recommendation(text: str) -> dict:
    """Parse a capacitor recommendation string into structured requirements.

    Examples:
        "10uF ceramic, X5R or X7R" -> {min_farads: 10e-6, count: 1, dielectric: ["X5R","X7R"]}
        "22uF ceramic x2" -> {min_farads: 22e-6, count: 2}
        "2 x 10uF" -> {min_farads: 10e-6, count: 2}
        "100nF" -> {min_farads: 100e-9, count: 1}
    """
    from kicad_core.values import parse_value

    result = {"min_farads": None, "count": 1, "dielectric": [], "max_distance_mm": None}

    if not text:
        return result

    text_lower = text.lower()

    # Count: a number multiplying a capacitance ("2 x 10uF"), an "x2" glued
    # to the unit ("22uFx2"), else a standalone "x2"/"x 2" that is not itself
    # followed by a value. The digit of X5R/X7R is a temperature code and
    # "max 10mm" / "10x10mm" are not quantities.
    count_match = (re.search(r'(?<![\w.])(\d+)\s*[x\u00d7]\s*\d+\.?\d*\s*' + _CAP_UNIT, text_lower)
                   or re.search(_CAP_UNIT + r'\s*[x\u00d7]\s*(\d+)' + _NOT_A_VALUE, text_lower)
                   or re.search(r'(?<![a-z0-9])[x\u00d7]\s*(\d+)' + _NOT_A_VALUE, text_lower))
    if count_match:
        result["count"] = int(count_match.group(1))

    # Extract distance: "within 10mm", "< 5mm"
    dist_match = re.search(r'within\s+(\d+\.?\d*)\s*mm', text_lower)
    if not dist_match:
        dist_match = re.search(r'<\s*(\d+\.?\d*)\s*mm', text_lower)
    if dist_match:
        result["max_distance_mm"] = float(dist_match.group(1))

    # Extract dielectric: X5R, X7R, C0G, NP0
    for d in ("X5R", "X7R", "X7S", "C0G", "NP0", "X6S"):
        if d.lower() in text_lower:
            result["dielectric"].append(d)

    # Extract capacitance value
    cap_match = re.search(r'(\d+\.?\d*)\s*(uF|\u00b5F|\u03bcF|nF|pF|u|\u00b5|\u03bc|n|p)', text, re.IGNORECASE)
    if cap_match:
        val_str = cap_match.group(1) + cap_match.group(2)
        parsed = parse_value(val_str, component_type="capacitor")
        if parsed:
            result["min_farads"] = parsed

    return result


_RECOMMENDATION_ROLES = {
    "input_cap_recommended": ("input",),
    "output_cap_recommended": ("output",),
    "decoupling_cap": ("input", "output"),
}


def _power_pin_roles(pin: dict) -> tuple:
    """Supply roles of an extracted power pin. The extraction schema lets
    power pins carry direction "passive" or none; their role then comes from
    the pin's function (VIN/VOUT; SW, FB and GND pins supply nothing), else
    its name (an OUT or VO<n> pin is an output, any other a supply input)."""
    direction = (pin.get("direction") or "").lower()
    if direction == "bidirectional":
        return ("input", "output")
    if direction in ("input", "output"):
        return (direction,)
    if direction not in ("passive", ""):
        return ()
    function = (pin.get("function") or "").upper()
    if function in ("SW", "FB", "GND"):
        return ()
    if function in ("VIN", "VOUT"):
        return ("input",) if function == "VIN" else ("output",)
    name = (pin.get("name") or "").upper()
    if "OUT" in name or re.fullmatch(r"VO\d*", name):
        return ("output",)
    return ("input",)


def _ic_ground_nets(pin_nets: dict, ext_pins: dict) -> set:
    """Nets on the IC's own ground pins (type ground, or function GND on a
    pin typed power): a ground under a name the ground-name rules miss (Masse, Net-(U1-PGND))."""
    out = set()
    for pin_num, net_name in pin_nets.items():
        ep = ext_pins.get(pin_num) or {}
        if ((ep.get("type") or "").lower() == "ground"
                or (ep.get("function") or "").upper() == "GND"):
            out.add(net_name)
    return out


def _on_ground(net_name, ic_ground: set) -> bool:
    from kicad_core.netnames import is_ground_name
    return net_name in ic_ground or is_ground_name(net_name)


def verify_decoupling(components: list, nets: dict, extraction_dir: str,
                      comp_lookup: dict, parsed_values: dict) -> list:
    """P2: Verify per-IC decoupling against datasheet application circuit.

    For each IC with an extraction containing application_circuit.decoupling_cap
    or input_cap_recommended / output_cap_recommended, checks that the actual
    caps on power pins meet the requirements (count, value, type).

    Returns list of finding dicts.
    """
    findings = []
    seen_quality_mpns: set = set()

    for comp in components:
        if comp.get("type") != "ic":
            continue
        ref = comp["reference"]
        mpn = comp.get("mpn") or comp.get("value", "")
        if not mpn or mpn == ref:
            continue

        extraction = _load_extraction(extraction_dir, mpn)
        if mpn not in seen_quality_mpns:
            seen_quality_mpns.add(mpn)
            qf = _quality_finding(mpn, extraction)
            if qf:
                findings.append(qf)
        if not extraction:
            continue
        view = _legacy_verifier_view(extraction)
        if not view or not view.get("application_circuit"):
            # Loud only for v2-adapted views; v1 caches that never
            # populated the optional application_circuit field keep the
            # pre-adapter silent-skip behavior byte-identical.
            if view.get("_v2_adapted") and _passes_trust_gate(extraction):
                findings.append(_not_verifiable_finding(
                    mpn,
                    "decoupling checks could not run: extraction has no application_circuit data",
                ))
            continue
        app_circuit = view["application_circuit"]

        pin_nets = comp.get("pin_nets", {})
        ext_pins = {str(p.get("number", "")): p for p in view.get("pins", [])}

        # Collect recommendations
        recommendations = []
        for key in ("input_cap_recommended", "output_cap_recommended", "decoupling_cap"):
            text = app_circuit.get(key)
            if text:
                recommendations.append((key, text, _parse_cap_recommendation(text)))

        if not recommendations:
            continue

        ic_ground = _ic_ground_nets(pin_nets, ext_pins)

        # Supply nets per role; a recommendation is checked only on the
        # pins of its role, and a symbol without such a pin is skipped.
        role_nets = {"input": set(), "output": set()}
        for pin_num, net_name in pin_nets.items():
            ep = ext_pins.get(pin_num)
            if not ep or (ep.get("type") or "").lower() != "power" or _on_ground(net_name, ic_ground):
                continue
            for role in _power_pin_roles(ep):
                role_nets[role].add(net_name)

        for key, text, req in recommendations:
            if req["min_farads"] is None:
                continue
            nets_for_key = sorted(set().union(*(role_nets[r] for r in _RECOMMENDATION_ROLES[key])))
            if not nets_for_key:
                continue

            # A bypass cap returns to ground; a cap listed without its
            # terminal nets is taken as given.
            caps, seen = [], set()
            for net_name in nets_for_key:
                net_info = nets.get(net_name, {})
                for p in net_info.get("pins", []) if isinstance(net_info, dict) else []:
                    c_ref = p.get("component", "")
                    c = comp_lookup.get(c_ref, {})
                    if c.get("type") != "capacitor" or c_ref == ref or c_ref in seen:
                        continue
                    cap_nets = c.get("pin_nets")
                    if isinstance(cap_nets, dict) and cap_nets and not any(
                            n != net_name and _on_ground(n, ic_ground) for n in cap_nets.values()):
                        continue
                    seen.add(c_ref)
                    caps.append({
                        "ref": c_ref,
                        "value": c.get("value", ""),
                        "farads": parsed_values.get(c_ref, 0),
                        "net": net_name,
                    })

            # Find matching caps (value >= recommended)
            matching = [c for c in caps if c["farads"] >= req["min_farads"] * 0.8]
            total_matching = len(matching)

            if total_matching < req["count"]:
                severity = "error" if total_matching == 0 else "warning"
                findings.append({
                    "type": "decoupling_insufficient",
                    "severity": severity,
                    "ref": ref,
                    "mpn": mpn,
                    "requirement_key": key,
                    "requirement_text": text,
                    "required_count": req["count"],
                    "required_min_farads": req["min_farads"],
                    "actual_count": total_matching,
                    "actual_caps": [{"ref": c["ref"], "value": c["value"]} for c in caps],
                    "detail": (f"{ref} ({mpn}): datasheet recommends \"{text}\" "
                               f"but found {total_matching}/{req['count']} matching caps "
                               f"on power pins"),
                })

    return findings


def _merge_ic_units(components):
    """One entry per physical IC: the analysis lists each unit of a
    multi-unit part separately, with only that unit's pins. Units merge when
    reference, lib_id and value agree; a repeated unit number starts a second
    part, and an unannotated `U?` reference never merges."""
    out, groups = [], {}
    for c in components:
        ref = c.get("reference", "")
        if c.get("type") != "ic" or not ref or ref.endswith("?"):
            out.append(c)
            continue
        key = (ref, c.get("lib_id", ""), c.get("value", ""))
        unit = c.get("unit") or 1
        group = groups.get(key)
        if group is None or unit in group["units"]:
            merged = dict(c)
            merged["pin_nets"] = dict(c.get("pin_nets") or {})
            group = {"entry": merged, "units": {unit}}
            groups[key] = group
            out.append(merged)
            continue
        group["units"].add(unit)
        entry = group["entry"]
        for pin, net in (c.get("pin_nets") or {}).items():
            entry["pin_nets"].setdefault(pin, net)
        if not entry.get("mpn") and c.get("mpn"):
            entry["mpn"] = c["mpn"]
    return out


def run_datasheet_verification(analysis: dict, project_dir: str = "") -> dict:
    """Run all datasheet verification checks.

    Args:
        analysis: Full schematic analysis JSON (from analyze_schematic.py)
        project_dir: Project directory for finding datasheets/extracted/

    Returns dict with:
        findings: list of verification findings
        summary: {ics_checked, ics_with_extractions, total_findings, by_severity}
    """
    components = _merge_ic_units(analysis.get("components", []))
    nets = analysis.get("nets", {})
    rail_voltages = analysis.get("rail_voltages", {})
    parsed_values = {}
    comp_lookup = {}
    for c in components:
        ref = c.get("reference", "")
        comp_lookup[ref] = c
        pv = c.get("parsed_value")
        if isinstance(pv, (int, float)):
            parsed_values[ref] = pv
        elif isinstance(pv, dict):
            parsed_values[ref] = pv.get("value", 0)

    # Resolve extraction directory
    if not project_dir:
        src_file = analysis.get("file", "")
        if src_file:
            project_dir = os.path.dirname(os.path.abspath(src_file))
    extract_dir = _resolve_extract_dir(project_dir) if project_dir else ""

    if not extract_dir:
        return {"findings": [], "summary": {
            "ics_checked": 0, "ics_with_extractions": 0,
            "total_findings": 0, "by_severity": {},
            "note": "No datasheets/extracted/ directory found",
        }}

    # Count ICs with extractions
    ic_count = 0
    ic_with_ext = 0
    for c in components:
        if c.get("type") == "ic":
            ic_count += 1
            mpn = c.get("mpn") or c.get("value", "")
            if mpn and _load_extraction(extract_dir, mpn):
                ic_with_ext += 1

    # Run checks
    all_findings = []
    all_findings.extend(verify_pin_voltages(components, nets, extract_dir, rail_voltages))
    all_findings.extend(verify_required_externals(components, nets, extract_dir, comp_lookup))
    all_findings.extend(verify_decoupling(components, nets, extract_dir, comp_lookup, parsed_values))

    # Merge per-MPN info findings emitted independently by each verifier:
    # - extraction_not_verifiable: combine details into one finding per MPN.
    # - extraction_quality_low: identical duplicates; keep the first per MPN
    #   (once per distinct MPN).
    nv_by_mpn: dict = {}
    seen_quality_low: set = set()
    other_findings: list = []
    for f in all_findings:
        ftype = f.get("type")
        if ftype == "extraction_not_verifiable":
            mpn_key = f.get("mpn", "")
            if mpn_key not in nv_by_mpn:
                nv_by_mpn[mpn_key] = f.copy()
            else:
                # Append additional detail from subsequent verifiers
                existing = nv_by_mpn[mpn_key]["detail"]
                extra = f.get("detail", "")
                if extra and extra not in existing:
                    nv_by_mpn[mpn_key]["detail"] = f"{existing}; {extra}"
        elif ftype == "extraction_quality_low":
            mpn_key = f.get("mpn", "")
            if mpn_key in seen_quality_low:
                continue
            seen_quality_low.add(mpn_key)
            other_findings.append(f)
        else:
            other_findings.append(f)
    # Reconstruct: non-nv findings first, then one nv per MPN
    all_findings = other_findings + list(nv_by_mpn.values())

    # Build severity summary
    by_severity = {}
    for f in all_findings:
        sev = f.get("severity", "info")
        by_severity[sev] = by_severity.get(sev, 0) + 1

    return {
        "findings": all_findings,
        "summary": {
            "ics_checked": ic_count,
            "ics_with_extractions": ic_with_ext,
            "total_findings": len(all_findings),
            "by_severity": by_severity,
        },
    }


# ---------------------------------------------------------------------------
# v1.4 extension: verify_v14_extraction
# ---------------------------------------------------------------------------

def _spec_max(sv_list):
    if isinstance(sv_list, list) and sv_list and isinstance(sv_list[0], dict):
        return sv_list[0].get("max")
    return None


def _spec_max_voltage(sv_list):
    """First SpecValue max with a voltage (or unspecified) unit.

    Per-pin absolute_max lists may mix voltage and current entries
    (pinout.schema.json) — comparing a current rating against net volts
    would fabricate false CRITICALs.
    """
    if not isinstance(sv_list, list):
        return None
    for sv in sv_list:
        if isinstance(sv, dict) and sv.get("unit") in (None, "", "V"):
            return sv.get("max")
    return None


def _all_pin_numbers(pinout):
    nums = set()
    for pin in pinout if isinstance(pinout, list) else []:
        if not isinstance(pin, dict):
            continue
        for n in pin.get("numbers", []) or []:
            nums.add(str(n))
    return nums


_PIN_FIELDS_BY_CATEGORY = {
    "regulator": ("feedback_pin", "compensation_pin", "enable_pin", "power_good_pin", "vin_pin", "vout_pin"),
    "diode": (),
    "transistor": (),  # pin_assignment is a nested object — checked separately if needed
    "opamp": ("shutdown_pin",),
    "mcu": ("reset_pin",),  # boot_pins is a list-of-objects, not validated
    "crystal": (),
}


def verify_v14_extraction(extraction: dict) -> list[dict]:
    """Return inconsistencies in a v1.4 extraction JSON.

    Each finding: {path, severity ('warning'|'error'), description}.
    Empty list = clean.
    """
    issues: list[dict] = []
    base = extraction.get("base") or {}
    pinout = base.get("pinout") or []
    rec_op = base.get("recommended_operating") or {}
    abs_max = base.get("absolute_max") or {}

    # 1. power_domain references resolve to recommended_operating keys
    rec_keys = set(rec_op.keys())
    if not isinstance(pinout, list):
        issues.append({
            "path": "base.pinout",
            "severity": "error",
            "description": "base.pinout is not a list",
        })
        pinout = []
    unresolved: dict = {}  # domain label -> [(pin index, raw value)]
    for i, pin in enumerate(pinout):
        if not isinstance(pin, dict):
            issues.append({
                "path": f"base.pinout[{i}]",
                "severity": "error",
                "description": "pin entry is not an object",
            })
            continue
        pd = pin.get("power_domain")
        if pd is None:
            continue
        if not isinstance(pd, str):
            pd = repr(pd)
        if pd not in rec_keys:
            unresolved.setdefault(pd, []).append(i)
    for pd, idxs in unresolved.items():
        desc = (f"power_domain {pd!r} does not resolve to a key in "
                f"base.recommended_operating ({sorted(rec_keys)})")
        if len(idxs) > 1:
            others = ", ".join(f"base.pinout[{j}]" for j in idxs[1:])
            desc += f"; {len(idxs)} pins affected, also {others}"
        issues.append({
            "path": f"base.pinout[{idxs[0]}].power_domain",
            "severity": "warning",
            "description": desc,
        })

    # 2. min/max sanity within each SpecValue
    for block_name, block in (("recommended_operating", rec_op), ("absolute_max", abs_max)):
        for key, sv_list in (block or {}).items():
            if not isinstance(sv_list, list):
                continue
            for j, sv in enumerate(sv_list):
                if not isinstance(sv, dict):
                    continue
                lo, hi = sv.get("min"), sv.get("max")
                if lo is not None and hi is not None:
                    try:
                        if float(lo) > float(hi):
                            issues.append({
                                "path": f"base.{block_name}.{key}[{j}]",
                                "severity": "error",
                                "description": f"min > max ({lo} > {hi})",
                            })
                    except (TypeError, ValueError):
                        pass

    # 3. recommended.max <= absolute.max for matching parameter pairs (heuristic on key suffix)
    for rec_key, rec_list in rec_op.items():
        rec_hi = _spec_max(rec_list)
        if rec_hi is None:
            continue
        # Try exact match (rec key VIN ↔ abs_max key VIN_max), or same key in absolute_max
        candidates = [f"{rec_key}_max", rec_key]
        for cand in candidates:
            if cand not in abs_max:
                continue
            abs_hi = _spec_max(abs_max[cand])
            if abs_hi is None:
                continue
            try:
                if float(rec_hi) > float(abs_hi):
                    issues.append({
                        "path": f"base.recommended_operating.{rec_key}",
                        "severity": "error",
                        "description": f"recommended.max ({rec_hi}) exceeds absolute_max.{cand}.max ({abs_hi})",
                    })
            except (TypeError, ValueError):
                pass
            break

    # 4. category pin references resolve to pinout (registry-driven)
    pin_nums = _all_pin_numbers(pinout)
    for category, fields in _PIN_FIELDS_BY_CATEGORY.items():
        block = extraction.get(category)
        if not isinstance(block, dict) or block.get("_extraction_failed"):
            continue
        for f in fields:
            v = block.get(f)
            if v is None:
                continue
            if str(v) not in pin_nums:
                issues.append({
                    "path": f"{category}.{f}",
                    "severity": "error",
                    "description": f"references pin {v!r} which is not present in base.pinout ({sorted(pin_nums)})",
                })

    # 4b. absolute_max placement sniff — flag entries whose evidence.section
    # looks like an operating-point / characterization table. Catches the
    # "Table 2 electrical characteristics stuffed into absolute_max" failure
    # mode observed on USBLC6-2SC6. Uses a denylist for known operating-point markers; a
    # section that contains stress markers ("absolute"/"stress"/"maximum
    # ratings") is allowed through even if it also contains operating
    # words (combined tables). Default is silent-pass on ambiguous names.
    _op_marker_re = re.compile(
        r'\b(electrical\s+characteristic|operating\s+condition|recommended\s+operating|dc\s+characteristic|ac\s+characteristic)',
        re.IGNORECASE,
    )
    _stress_marker_re = re.compile(
        r'\b(absolute|stress|maximum\s+rating)',
        re.IGNORECASE,
    )
    for key, sv_list in (abs_max or {}).items():
        if not isinstance(sv_list, list):
            continue
        for j, sv in enumerate(sv_list):
            if not isinstance(sv, dict):
                continue
            evidence = sv.get("evidence") or {}
            section = (evidence.get("section") or "").strip()
            if not section:
                continue  # no evidence to sniff — silent skip
            looks_operating = bool(_op_marker_re.search(section))
            looks_stress = bool(_stress_marker_re.search(section))
            if looks_operating and not looks_stress:
                issues.append({
                    "path": f"base.absolute_max.{key}[{j}].evidence.section",
                    "severity": "warning",
                    "description": (
                        f"absolute_max entry cites section {section!r}, which "
                        "looks like operating-point / characterization data "
                        "(no 'absolute'/'stress'/'maximum rating' keywords). "
                        "May be placed in the wrong slot."
                    ),
                })

    # 5. categories array consistency
    cats = extraction.get("categories") or []
    for cat in cats:
        payload = extraction.get(cat)
        if payload is None:
            issues.append({
                "path": f"categories[{cat!r}]",
                "severity": "error",
                "description": f"categories lists {cat!r} but top-level {cat} field is missing",
            })
        elif isinstance(payload, dict) and payload.get("_extraction_failed") is True:
            issues.append({
                "path": f"{cat}",
                "severity": "error",
                "description": f"category {cat!r} payload is the partial-merge sentinel: {payload.get('reason') or 'no reason given'}",
            })
        elif isinstance(payload, dict) and not payload:
            issues.append({
                "path": f"categories[{cat!r}]",
                "severity": "error",
                "description": f"categories lists {cat!r} but top-level {cat} field is an empty object",
            })
        elif isinstance(payload, list) and not payload:
            issues.append({
                "path": f"categories[{cat!r}]",
                "severity": "error",
                "description": f"categories lists {cat!r} but top-level {cat} field is an empty list",
            })

    return issues


def _cli_v14(argv: list[str] | None = None) -> int:
    """v1.4 verifier CLI.

    Two invocation shapes supported:

    1. Positional (original): ``datasheet_verify.py <extraction_path>``
    2. Flag-based (harness 4-check gate, Check 2):
       ``datasheet_verify.py --mpn <mpn> --extract-dir <dir> --self-consistency --json``

    Output shape:
        positional → {"issues": [...], "count": N}
        flag-based with --json → {"violations": [...], "count": N, "mpn": ..., "extract_dir": ...}

    Exit codes:
        0  no issues, or warnings only
        1  at least one error
        2  CLI / I/O error (missing file, bad JSON, missing required flags)
    """
    import argparse, json as _json, re as _re, sys as _sys
    from pathlib import Path as _Path

    ap = argparse.ArgumentParser(
        description="Verify v1.4 extraction JSON for cross-field consistency."
    )
    ap.add_argument(
        "extraction_path",
        nargs="?",
        help="path to <mpn>.json extraction (positional mode)",
    )
    ap.add_argument(
        "--mpn",
        help="MPN to look up under --extract-dir (flag mode)",
    )
    ap.add_argument(
        "--extract-dir",
        type=_Path,
        help="directory containing <mpn>.json (flag mode)",
    )
    ap.add_argument(
        "--self-consistency",
        action="store_true",
        help=(
            "explicit opt-in to v1.4 self-consistency mode "
            "(flag mode; required when using --mpn/--extract-dir)"
        ),
    )
    ap.add_argument(
        "--json",
        dest="emit_json",
        action="store_true",
        help="emit harness-shape JSON ({violations: [...]}) instead of legacy {issues: [...]}",
    )
    args = ap.parse_args(argv)

    flag_mode = bool(args.mpn or args.extract_dir or args.self_consistency)
    positional_mode = args.extraction_path is not None

    if flag_mode and positional_mode:
        print(
            "error: cannot mix positional extraction_path with --mpn/--extract-dir flags",
            file=_sys.stderr,
        )
        return 2
    if flag_mode:
        if not (args.mpn and args.extract_dir and args.self_consistency):
            print(
                "error: flag mode requires --mpn, --extract-dir, and --self-consistency",
                file=_sys.stderr,
            )
            return 2
        sanitized = _re.sub(r"[^A-Za-z0-9_.-]", "_", args.mpn.strip())
        path = args.extract_dir / f"{sanitized}.json"
    elif positional_mode:
        path = _Path(args.extraction_path)
    else:
        ap.print_usage(_sys.stderr)
        print(
            "error: must supply either positional extraction_path "
            "or --mpn/--extract-dir/--self-consistency",
            file=_sys.stderr,
        )
        return 2

    if not path.exists():
        print(f"error: extraction file not found: {path}", file=_sys.stderr)
        return 2
    try:
        extraction = _json.loads(path.read_text(encoding="utf-8"))
    except (_json.JSONDecodeError, RecursionError) as exc:
        print(f"error: extraction file is not valid JSON: {exc}", file=_sys.stderr)
        return 2

    issues = verify_v14_extraction(extraction)

    if flag_mode and args.emit_json:
        _json.dump(
            {
                "violations": issues,
                "count": len(issues),
                "mpn": args.mpn,
                "extract_dir": str(args.extract_dir),
            },
            _sys.stdout,
            indent=2,
        )
    elif args.emit_json or positional_mode:
        _json.dump({"issues": issues, "count": len(issues)}, _sys.stdout, indent=2)
    else:
        # Flag mode without --json: minimal human summary.
        print(f"{args.mpn}: {len(issues)} issue(s)")
        for i in issues:
            print(f"  [{i['severity']}] {i['path']}: {i['description']}")
    if args.emit_json or positional_mode:
        _sys.stdout.write("\n")
    return 1 if any(i.get("severity") == "error" for i in issues) else 0


if __name__ == "__main__":
    for _stream in (sys.stdout, sys.stderr):  # UTF-8 on a cp1252 pipe (Windows)
        if hasattr(_stream, "reconfigure"):
            _kw = {"newline": "\n"}
            if (getattr(_stream, "encoding", "") or "").lower().replace("-", "") != "utf8":
                _kw.update(encoding="utf-8", errors="backslashreplace")
            _stream.reconfigure(**_kw)
    sys.exit(_cli_v14())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall