@tscircuit/checks 0.0.188 → 0.0.189

package/README.md

@@ -44,6 +44,26 @@ and output an array of arrays for any issues found.
 | [`runAllRoutingChecks`](./lib/run-all-checks.ts) | Runs all routing checks currently enabled (`checkEachPcbPortConnectedToPcbTraces`, `checkSourceTracesHavePcbTraces`, `checkEachPcbTraceNonOverlapping`, `checkPadTraceClearance`, `checkViaTraceClearance`, same/different net via spacing, and `checkPcbTracesOutOfBoard`). Trace-obstacle pairs are classified before aggregation, so each pair produces one overlap or clearance diagnostic, never both. |
 | [`runAllChecks`](./lib/run-all-checks.ts) | Runs placement, schematic, netlist, pin specification, and routing checks and returns a combined list of issues. |
 
+## Consolidated placement overlaps
+
+`runAllPlacementChecks` and `runAllChecks` report one placement conflict per
+component pair when footprint overlap causes multiple footprint, pad clearance,
+and courtyard diagnostics. The message names the components, counts the conflicts,
+and suggests moving them apart. Separate component pairs, clearance-only issues,
+standalone elements, and unrelated routing diagnostics remain separate.
+
+The result uses the existing `pcb_footprint_overlap_error` type and retains the
+union of affected pad and hole IDs for rendering. The exported
+`PcbComponentOverlapError` interface adds `pcb_component_ids` and `related_errors`
+with the original diagnostics, including measured clearances. These extra context
+fields are provided by checks; older Circuit JSON schema parsers may strip them.
+
+Individual checks still return detailed diagnostics. Use
+`runAllPlacementChecks(circuitJson, { consolidateOverlaps: false })` to obtain raw
+aggregate results, for example to apply exclusions before calling
+`consolidatePcbOverlapErrors(circuitJson, errors)`. Consolidation does not mutate
+its inputs and can be applied again when combining runners.
+
 ## Implementation Details
 
 > [!NOTE]

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as circuit_json from 'circuit-json';
-import { AnyCircuitElement, PcbPortNotConnectedError, PcbTraceError, PcbPlacementError, PcbComponentOutsideBoardError, PcbViaClearanceError, PcbTraceWarning, PcbTraceMissingError, PcbFootprintOverlapError, PcbComponentMissingCourtyardWarning, PcbTraceTooLongWarning, PcbPadPadClearanceError, PcbPadTraceClearanceError, PcbViaTraceClearanceError, SourceComponentMisconfiguredError, SourceComponentPinsUnderspecifiedWarning, SourceNoPowerPinDefinedWarning, SourceNoGroundPinDefinedWarning, SchematicComponentStylingWarning, PcbConnectorNotInAccessibleOrientationWarning, SourceConfusingNetNameWarning } from 'circuit-json';
+import { AnyCircuitElement, PcbPortNotConnectedError, PcbTraceError, PcbPlacementError, PcbComponentOutsideBoardError, PcbViaClearanceError, PcbTraceWarning, PcbTraceMissingError, PcbFootprintOverlapError, PcbPadPadClearanceError, PcbCourtyardOverlapError, PcbComponentMissingCourtyardWarning, PcbTraceTooLongWarning, PcbPadTraceClearanceError, PcbViaTraceClearanceError, SourceComponentMisconfiguredError, SourceComponentPinsUnderspecifiedWarning, SourceNoPowerPinDefinedWarning, SourceNoGroundPinDefinedWarning, SchematicComponentStylingWarning, PcbConnectorNotInAccessibleOrientationWarning, SourceConfusingNetNameWarning } from 'circuit-json';
 import { ConnectivityMap } from 'circuit-json-to-connectivity-map';
 
 declare function checkEachPcbPortConnectedToPcbTraces(circuitJson: AnyCircuitElement[]): PcbPortNotConnectedError[];
@@ -77,11 +77,27 @@ interface TraceBoardCheckConfig {
  */
 declare function checkPcbTracesOutOfBoard(circuitJson: AnyCircuitElement[], config?: TraceBoardCheckConfig): PcbTraceError[];
 
+/** Additional diagnostic context supplied by checks; the base error remains
+ * compatible with existing Circuit JSON renderers. */
+interface PcbComponentOverlapError extends PcbFootprintOverlapError {
+    pcb_component_ids?: string[];
+    related_errors?: PlacementOverlapError[];
+}
+type PlacementOverlapError = PcbComponentOverlapError | PcbPadPadClearanceError | PcbCourtyardOverlapError;
+/**
+ * Consolidate placement conflicts for the same exact pair of components, only
+ * when a footprint overlap was detected. Keep raw details and all affected
+ * pad/hole IDs on one renderer-compatible error. Unrelated checks, standalone
+ * elements, same-component clearance errors and clearance-only pairs survive.
+ * Does not mutate inputs; safe to apply again when combining check runners.
+ */
+declare function consolidatePcbOverlapErrors<T extends AnyCircuitElement>(circuitJson: AnyCircuitElement[], errors: T[]): (T | PcbComponentOverlapError)[];
+
 /**
  * Check for overlapping PCB components
  * Returns errors for components that overlap inappropriately
  */
-declare function checkPcbComponentOverlap(circuitJson: AnyCircuitElement[]): PcbFootprintOverlapError[];
+declare function checkPcbComponentOverlap(circuitJson: AnyCircuitElement[]): PcbComponentOverlapError[];
 
 /** Returns a warning for every PCB component without a courtyard. */
 declare function checkPcbComponentsMissingCourtyard(circuitJson: AnyCircuitElement[]): PcbComponentMissingCourtyardWarning[];
@@ -183,7 +199,9 @@ declare function checkSchematicComponentMissingReferenceDesignatorText(circuitJs
  */
 declare function checkSchematicComponentPortsOutsideBody(circuitJson: AnyCircuitElement[]): SchematicComponentStylingWarning[];
 
-declare function runAllPlacementChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.PcbPlacementError | circuit_json.PcbComponentOutsideBoardError | circuit_json.PcbFootprintOverlapError | circuit_json.PcbComponentMissingCourtyardWarning | circuit_json.PcbPadPadClearanceError | circuit_json.PcbConnectorNotInAccessibleOrientationWarning | circuit_json.PcbCourtyardOverlapError)[]>;
+declare function runAllPlacementChecks(circuitJson: AnyCircuitElement[], { consolidateOverlaps }?: {
+    consolidateOverlaps?: boolean | undefined;
+}): Promise<(circuit_json.PcbPlacementError | circuit_json.PcbComponentOutsideBoardError | PcbComponentOverlapError | circuit_json.PcbPadPadClearanceError | circuit_json.PcbCourtyardOverlapError | circuit_json.PcbComponentMissingCourtyardWarning | circuit_json.PcbConnectorNotInAccessibleOrientationWarning)[]>;
 declare function runAllNetlistChecks(circuitJson: AnyCircuitElement[]): Promise<({
     type: "source_pin_must_be_connected_error";
     source_pin_must_be_connected_error_id: string;
@@ -195,8 +213,8 @@ declare function runAllNetlistChecks(circuitJson: AnyCircuitElement[]): Promise<
 } | circuit_json.SourceComponentMisconfiguredError | circuit_json.SourceConfusingNetNameWarning)[]>;
 declare function runAllSchematicChecks(circuitJson: AnyCircuitElement[]): Promise<circuit_json.SchematicComponentStylingWarning[]>;
 declare function runAllPinSpecificationChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.SourceComponentPinsUnderspecifiedWarning | circuit_json.SourceNoPowerPinDefinedWarning | circuit_json.SourceNoGroundPinDefinedWarning)[]>;
-declare function runAllRoutingChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.PcbPortNotConnectedError | circuit_json.PcbTraceError | circuit_json.PcbViaClearanceError | circuit_json.PcbTraceMissingError | circuit_json.PcbTraceTooLongWarning | circuit_json.PcbPadPadClearanceError | circuit_json.PcbPadTraceClearanceError | circuit_json.PcbViaTraceClearanceError)[]>;
-declare function runAllChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.PcbPortNotConnectedError | circuit_json.PcbTraceError | circuit_json.PcbPlacementError | circuit_json.PcbComponentOutsideBoardError | circuit_json.PcbViaClearanceError | circuit_json.PcbTraceMissingError | circuit_json.PcbFootprintOverlapError | circuit_json.PcbComponentMissingCourtyardWarning | circuit_json.PcbTraceTooLongWarning | circuit_json.PcbPadPadClearanceError | circuit_json.PcbPadTraceClearanceError | circuit_json.PcbViaTraceClearanceError | {
+declare function runAllRoutingChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.PcbPortNotConnectedError | circuit_json.PcbTraceError | circuit_json.PcbViaClearanceError | circuit_json.PcbTraceMissingError | circuit_json.PcbPadPadClearanceError | circuit_json.PcbTraceTooLongWarning | circuit_json.PcbPadTraceClearanceError | circuit_json.PcbViaTraceClearanceError)[]>;
+declare function runAllChecks(circuitJson: AnyCircuitElement[]): Promise<(circuit_json.PcbPortNotConnectedError | circuit_json.PcbTraceError | circuit_json.PcbPlacementError | circuit_json.PcbComponentOutsideBoardError | circuit_json.PcbViaClearanceError | circuit_json.PcbTraceMissingError | PcbComponentOverlapError | circuit_json.PcbPadPadClearanceError | circuit_json.PcbCourtyardOverlapError | circuit_json.PcbComponentMissingCourtyardWarning | circuit_json.PcbTraceTooLongWarning | circuit_json.PcbPadTraceClearanceError | circuit_json.PcbViaTraceClearanceError | {
     type: "source_pin_must_be_connected_error";
     source_pin_must_be_connected_error_id: string;
     error_type: "source_pin_must_be_connected_error";
@@ -204,7 +222,7 @@ declare function runAllChecks(circuitJson: AnyCircuitElement[]): Promise<(circui
     source_component_id: string;
     source_port_id: string;
     subcircuit_id?: string;
-} | circuit_json.SourceComponentMisconfiguredError | circuit_json.SourceComponentPinsUnderspecifiedWarning | circuit_json.SourceNoPowerPinDefinedWarning | circuit_json.SourceNoGroundPinDefinedWarning | circuit_json.SchematicComponentStylingWarning | circuit_json.SourceConfusingNetNameWarning | circuit_json.PcbConnectorNotInAccessibleOrientationWarning | circuit_json.PcbCourtyardOverlapError)[]>;
+} | circuit_json.SourceComponentMisconfiguredError | circuit_json.SourceComponentPinsUnderspecifiedWarning | circuit_json.SourceNoPowerPinDefinedWarning | circuit_json.SourceNoGroundPinDefinedWarning | circuit_json.SchematicComponentStylingWarning | circuit_json.SourceConfusingNetNameWarning | circuit_json.PcbConnectorNotInAccessibleOrientationWarning)[]>;
 
 declare function checkConnectorAccessibleOrientation(circuitJson: AnyCircuitElement[]): PcbConnectorNotInAccessibleOrientationWarning[];
 
@@ -218,4 +236,4 @@ declare function checkTestPointAccessibility(circuitJson: AnyCircuitElement[]):
 /** Warn once per name when its source nets belong to multiple electrical islands. */
 declare function checkSameNameNetsAreConnected(circuitJson: AnyCircuitElement[]): SourceConfusingNetNameWarning[];
 
-export { NetManager, checkAllPinsInComponentAreUnderspecified, checkConnectorAccessibleOrientation, checkCopperToBoardEdgeClearance, checkDifferentNetViaSpacing, checkEachPcbPortConnectedToPcbTraces, checkEachPcbTraceNonOverlapping, checkNoGroundPinDefined, checkNoPowerPinDefined, checkPadPadClearance, checkPadTraceClearance, checkPcbComponentOverCutout, checkPcbComponentOverlap, checkPcbComponentsMissingCourtyard, checkPcbComponentsOutOfBoard, checkPcbCopperOverKeepout, checkPcbTraceLengths, checkPcbTraceViaCounts, checkPcbTracesOutOfBoard, checkPinMustBeConnected, checkSameNameNetsAreConnected, checkSameNetViaSpacing, checkSchematicComponentExcessiveVerticalPadding, checkSchematicComponentMissingReferenceDesignatorText, checkSchematicComponentPortsOutsideBody, checkSourceTracesHavePcbTraces, checkSourceTracesMatchPcbTraceThickness, checkTestPointAccessibility, checkTracesAreContiguous, checkTwoTerminalSwitchContactsOnDifferentNets, checkViaPadClearance, checkViaTraceClearance, checkViasInPads, checkViasOffBoard, dedupePcbDrcErrors, runAllChecks, runAllNetlistChecks, runAllPinSpecificationChecks, runAllPlacementChecks, runAllRoutingChecks, runAllSchematicChecks };
+export { NetManager, type PcbComponentOverlapError, checkAllPinsInComponentAreUnderspecified, checkConnectorAccessibleOrientation, checkCopperToBoardEdgeClearance, checkDifferentNetViaSpacing, checkEachPcbPortConnectedToPcbTraces, checkEachPcbTraceNonOverlapping, checkNoGroundPinDefined, checkNoPowerPinDefined, checkPadPadClearance, checkPadTraceClearance, checkPcbComponentOverCutout, checkPcbComponentOverlap, checkPcbComponentsMissingCourtyard, checkPcbComponentsOutOfBoard, checkPcbCopperOverKeepout, checkPcbTraceLengths, checkPcbTraceViaCounts, checkPcbTracesOutOfBoard, checkPinMustBeConnected, checkSameNameNetsAreConnected, checkSameNetViaSpacing, checkSchematicComponentExcessiveVerticalPadding, checkSchematicComponentMissingReferenceDesignatorText, checkSchematicComponentPortsOutsideBody, checkSourceTracesHavePcbTraces, checkSourceTracesMatchPcbTraceThickness, checkTestPointAccessibility, checkTracesAreContiguous, checkTwoTerminalSwitchContactsOnDifferentNets, checkViaPadClearance, checkViaTraceClearance, checkViasInPads, checkViasOffBoard, consolidatePcbOverlapErrors, dedupePcbDrcErrors, runAllChecks, runAllNetlistChecks, runAllPinSpecificationChecks, runAllPlacementChecks, runAllRoutingChecks, runAllSchematicChecks };

package/dist/index.js

@@ -3510,7 +3510,11 @@ function checkPcbComponentOverlap(circuitJson) {
               type: "pcb_footprint_overlap_error",
               pcb_error_id: `pcb_footprint_overlap_${id1}_${id2}`,
               error_type: "pcb_footprint_overlap_error",
-              message: `${elem1.type} ${elem1Description} overlaps with ${elem2.type} ${elem2Description}`
+              message: `${elem1.type} ${elem1Description} overlaps with ${elem2.type} ${elem2Description}`,
+              pcb_component_ids: [
+                elem1.pcb_component_id,
+                elem2.pcb_component_id
+              ].filter((id) => Boolean(id))
             };
             if (elem1.type === "pcb_smtpad" || elem2.type === "pcb_smtpad") {
               error.pcb_smtpad_ids = [];
@@ -4553,6 +4557,118 @@ function checkSchematicComponentPortsOutsideBody(circuitJson) {
   return warnings;
 }
 
+// lib/consolidate-pcb-overlap-errors.ts
+import { getPrimaryId as getPrimaryId9 } from "@tscircuit/circuit-json-util";
+function consolidatePcbOverlapErrors(circuitJson, errors) {
+  const ownerByElementId = /* @__PURE__ */ new Map();
+  const elementById = /* @__PURE__ */ new Map();
+  for (const element of circuitJson) {
+    const id = getPrimaryId9(element);
+    elementById.set(id, element);
+    if ("pcb_component_id" in element && element.pcb_component_id) {
+      ownerByElementId.set(id, element.pcb_component_id);
+    }
+  }
+  const rawErrors = errors.flatMap(
+    (error) => error.type === "pcb_footprint_overlap_error" ? error.related_errors ?? [error] : [error]
+  );
+  const groups = /* @__PURE__ */ new Map();
+  const keyByError = /* @__PURE__ */ new Map();
+  for (const error of rawErrors) {
+    let componentIds;
+    if (error.type === "pcb_footprint_overlap_error") {
+      if (error.pcb_keepout_ids?.length) continue;
+      const overlap = error;
+      const elementIds = [
+        ...error.pcb_smtpad_ids ?? [],
+        ...error.pcb_plated_hole_ids ?? [],
+        ...error.pcb_hole_ids ?? []
+      ];
+      if (elementIds.some((id) => !ownerByElementId.has(id))) continue;
+      componentIds = overlap.pcb_component_ids ?? elementIds.map((id) => ownerByElementId.get(id));
+    } else if (error.type === "pcb_pad_pad_clearance_error") {
+      if (error.pcb_pad_ids.some((id) => !ownerByElementId.has(id))) continue;
+      componentIds = error.pcb_pad_ids.map((id) => ownerByElementId.get(id));
+    } else if (error.type === "pcb_courtyard_overlap_error") {
+      componentIds = error.pcb_component_ids;
+    } else {
+      continue;
+    }
+    componentIds = [...new Set(componentIds)].sort();
+    if (componentIds.length !== 2) continue;
+    const key = JSON.stringify(componentIds);
+    keyByError.set(error, key);
+    const group = groups.get(key) ?? [];
+    group.push(error);
+    groups.set(key, group);
+  }
+  const summaries = /* @__PURE__ */ new Map();
+  for (const [key, group] of groups) {
+    const overlaps = group.filter(
+      (e) => e.type === "pcb_footprint_overlap_error"
+    );
+    if (group.length < 2 || overlaps.length === 0) continue;
+    const componentIds = JSON.parse(key);
+    const names = componentIds.map((id) => {
+      const component = elementById.get(id);
+      const source = component?.type === "pcb_component" ? elementById.get(component.source_component_id) : void 0;
+      return source?.type === "source_component" ? source.name : id;
+    });
+    const counts = [
+      [overlaps.length, "footprint overlap"],
+      [
+        group.filter((e) => e.type === "pcb_pad_pad_clearance_error").length,
+        "pad clearance violation"
+      ],
+      [
+        group.filter((e) => e.type === "pcb_courtyard_overlap_error").length,
+        "courtyard conflict"
+      ]
+    ];
+    const details = counts.filter(([count]) => count > 0).map(([count, label]) => `${count} ${label}${count === 1 ? "" : "s"}`);
+    const summary = {
+      type: "pcb_footprint_overlap_error",
+      error_type: "pcb_footprint_overlap_error",
+      pcb_error_id: `pcb_component_overlap_${componentIds.join("_")}`,
+      pcb_component_ids: componentIds,
+      message: `${names.join(" overlaps ")}: ${details.join(", ")}. Move the components apart.`,
+      related_errors: group
+    };
+    if (group.some((error) => error.is_fatal)) summary.is_fatal = true;
+    const affectedIds = /* @__PURE__ */ new Set();
+    for (const error of group) {
+      if (error.type === "pcb_footprint_overlap_error") {
+        for (const id of [
+          ...error.pcb_smtpad_ids ?? [],
+          ...error.pcb_plated_hole_ids ?? [],
+          ...error.pcb_hole_ids ?? []
+        ])
+          affectedIds.add(id);
+      } else if (error.type === "pcb_pad_pad_clearance_error") {
+        for (const id of error.pcb_pad_ids) affectedIds.add(id);
+      }
+    }
+    for (const [field, type] of [
+      ["pcb_smtpad_ids", "pcb_smtpad"],
+      ["pcb_plated_hole_ids", "pcb_plated_hole"],
+      ["pcb_hole_ids", "pcb_hole"]
+    ]) {
+      const ids = [...affectedIds].filter((id) => elementById.get(id)?.type === type).sort();
+      if (ids.length) summary[field] = ids;
+    }
+    summaries.set(key, summary);
+  }
+  const emitted = /* @__PURE__ */ new Set();
+  return rawErrors.flatMap((error) => {
+    const key = keyByError.get(error);
+    const summary = key === void 0 ? void 0 : summaries.get(key);
+    if (!summary || key === void 0) return [error];
+    if (emitted.has(key)) return [];
+    emitted.add(key);
+    return [summary];
+  });
+}
+
 // lib/check-same-name-nets-are-connected.ts
 function checkSameNameNetsAreConnected(circuitJson) {
   const parents = /* @__PURE__ */ new Map();
@@ -4881,8 +4997,8 @@ function checkTestPointAccessibility(circuitJson) {
 }
 
 // lib/run-all-checks.ts
-async function runAllPlacementChecks(circuitJson) {
-  return [
+async function runAllPlacementChecks(circuitJson, { consolidateOverlaps = true } = {}) {
+  const errors = [
     ...checkCopperToBoardEdgeClearance(circuitJson),
     ...checkViasInPads(circuitJson),
     ...checkPcbComponentsOutOfBoard(circuitJson),
@@ -4895,6 +5011,7 @@ async function runAllPlacementChecks(circuitJson) {
     ...checkConnectorAccessibleOrientation(circuitJson),
     ...checkTestPointAccessibility(circuitJson)
   ];
+  return consolidateOverlaps ? consolidatePcbOverlapErrors(circuitJson, errors) : errors;
 }
 async function runAllNetlistChecks(circuitJson) {
   return [
@@ -4977,6 +5094,7 @@ export {
   checkViaTraceClearance,
   checkViasInPads,
   checkViasOffBoard,
+  consolidatePcbOverlapErrors,
   dedupePcbDrcErrors,
   runAllChecks,
   runAllNetlistChecks,