@tscircuit/cli 0.1.1175 → 0.1.1176

package/dist/cli/main.js

@@ -98409,7 +98409,7 @@ var import_perfect_cli = __toESM2(require_dist2(), 1);
 // lib/getVersion.ts
 import { createRequire as createRequire2 } from "node:module";
 // package.json
-var version = "0.1.1173";
+var version = "0.1.1175";
 var package_default = {
   name: "@tscircuit/cli",
   version,
@@ -98421,7 +98421,7 @@ var package_default = {
   devDependencies: {
     "@babel/standalone": "^7.26.9",
     "@biomejs/biome": "^1.9.4",
-    "@tscircuit/circuit-json-placement-analysis": "^0.0.4",
+    "@tscircuit/circuit-json-placement-analysis": "^0.0.5",
     "@tscircuit/circuit-json-routing-analysis": "^0.0.1",
     "@tscircuit/fake-snippets": "^0.0.182",
     "@tscircuit/file-server": "^0.0.32",
@@ -110751,6 +110751,673 @@ var analyzeComponentPlacement = (circuitJson, componentName) => {
 `)
   };
 };
+var TOP_ISSUE_LIMIT = 5;
+var CENTER_ANCHOR2 = "center";
+var ISSUE_TYPE_ORDER = [
+  "pad_overlap",
+  "off_board",
+  "courtyard_collision",
+  "connector_body_intrusion",
+  "footprint_intrusion"
+];
+var toNumber22 = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var fmtNumber2 = (value) => {
+  if (Number.isInteger(value))
+    return String(value);
+  return value.toFixed(3).replace(/\.0+$/, "").replace(/(\.\d*?)0+$/, "$1");
+};
+var fmtMm2 = (value) => `${fmtNumber2(value)}mm`;
+var getBoundsFromCenterAndSize = (centerX, centerY, width, height) => ({
+  min_x: centerX - width / 2,
+  max_x: centerX + width / 2,
+  min_y: centerY - height / 2,
+  max_y: centerY + height / 2,
+  width,
+  height
+});
+var getBoundsFromPoints = (points) => {
+  const xs = [];
+  const ys = [];
+  for (const point of points) {
+    const x = toNumber22(point.x);
+    const y = toNumber22(point.y);
+    if (x === null || y === null)
+      continue;
+    xs.push(x);
+    ys.push(y);
+  }
+  if (xs.length === 0 || ys.length === 0)
+    return null;
+  const min_x = Math.min(...xs);
+  const max_x = Math.max(...xs);
+  const min_y = Math.min(...ys);
+  const max_y = Math.max(...ys);
+  return {
+    min_x,
+    max_x,
+    min_y,
+    max_y,
+    width: max_x - min_x,
+    height: max_y - min_y
+  };
+};
+var getOverlap = (a, b) => {
+  const overlapX = Math.min(a.max_x, b.max_x) - Math.max(a.min_x, b.min_x);
+  const overlapY = Math.min(a.max_y, b.max_y) - Math.max(a.min_y, b.min_y);
+  if (overlapX <= 0 || overlapY <= 0)
+    return null;
+  return {
+    overlapX,
+    overlapY,
+    clearance: -Math.min(overlapX, overlapY)
+  };
+};
+var layersIntersect = (a, b) => {
+  const bSet = new Set(b);
+  return a.some((layer) => bSet.has(layer));
+};
+var getArea = (bounds) => {
+  if (!bounds)
+    return Number.POSITIVE_INFINITY;
+  return bounds.width * bounds.height;
+};
+var stripNumericSuffix = (name) => {
+  const stripped = name.replace(/\d+$/, "");
+  return stripped.length >= 2 ? stripped : name;
+};
+var getSummaryLabel = (type, count) => {
+  if (count === 0)
+    return null;
+  switch (type) {
+    case "pad_overlap":
+      return `${count} pad overlap${count === 1 ? "" : "s"}`;
+    case "off_board":
+      return `${count} off-board`;
+    case "courtyard_collision":
+      return `${count} courtyard collision${count === 1 ? "" : "s"}`;
+    case "connector_body_intrusion":
+      return `${count} connector-body intrusion${count === 1 ? "" : "s"}`;
+    case "footprint_intrusion":
+      return `${count} footprint intrusion${count === 1 ? "" : "s"}`;
+  }
+};
+var getMoveDirectionForEdge = (edge) => {
+  switch (edge) {
+    case "left":
+      return "right";
+    case "right":
+      return "left";
+    case "top":
+      return "down";
+    case "bottom":
+      return "up";
+  }
+};
+var getBoardEdgeStatus = (bounds, boardBounds, componentName) => {
+  if (!bounds || !boardBounds)
+    return null;
+  const clearances = [
+    { edge: "left", clearance: bounds.min_x - boardBounds.min_x },
+    { edge: "right", clearance: boardBounds.max_x - bounds.max_x },
+    { edge: "top", clearance: bounds.min_y - boardBounds.min_y },
+    {
+      edge: "bottom",
+      clearance: boardBounds.max_y - bounds.max_y
+    }
+  ];
+  const outside = clearances.filter((entry) => entry.clearance < 0).sort((a, b) => a.clearance - b.clearance);
+  const selected = outside[0] ?? [...clearances].sort((a, b) => a.clearance - b.clearance)[0] ?? null;
+  if (!selected)
+    return null;
+  return {
+    component_name: componentName,
+    edge: selected.edge,
+    status: selected.clearance < 0 ? "outside" : "inside",
+    distance: Math.abs(selected.clearance)
+  };
+};
+var formatBoardEdgeStatus = (status) => `${fmtMm2(status.distance)} ${status.status} ${status.edge} edge`;
+var chooseMover = (a, b, preferredMover) => {
+  if (preferredMover === a.name)
+    return { mover: a, anchor: b };
+  if (preferredMover === b.name)
+    return { mover: b, anchor: a };
+  if (a.isConnectorLike && !b.isConnectorLike)
+    return { mover: b, anchor: a };
+  if (b.isConnectorLike && !a.isConnectorLike)
+    return { mover: a, anchor: b };
+  const areaA = getArea(a.bounds);
+  const areaB = getArea(b.bounds);
+  if (areaA < areaB)
+    return { mover: a, anchor: b };
+  if (areaB < areaA)
+    return { mover: b, anchor: a };
+  return a.order > b.order ? { mover: a, anchor: b } : { mover: b, anchor: a };
+};
+var getMoveDirectionBetweenComponents = (mover, anchor, axis) => {
+  if (axis === "x") {
+    if ((mover.centerX ?? 0) >= (anchor.centerX ?? 0))
+      return "right";
+    return "left";
+  }
+  if ((mover.centerY ?? 0) >= (anchor.centerY ?? 0))
+    return "down";
+  return "up";
+};
+var getSeparationSuggestion = (a, b, overlapX, overlapY, preferredMover) => {
+  if (a.centerX === null || a.centerY === null || b.centerX === null || b.centerY === null) {
+    return;
+  }
+  const { mover, anchor } = chooseMover(a, b, preferredMover);
+  const axis = overlapX <= overlapY ? "x" : "y";
+  const distance = axis === "x" ? overlapX : overlapY;
+  const direction = getMoveDirectionBetweenComponents(mover, anchor, axis);
+  return `move ${mover.name} ${fmtMm2(distance)} ${direction}`;
+};
+var getCountainmentBonus = (a, b) => {
+  if (!a.bounds || !b.bounds || a.centerX === null || a.centerY === null)
+    return 0;
+  const centerInsideB = a.centerX >= b.bounds.min_x && a.centerX <= b.bounds.max_x && a.centerY >= b.bounds.min_y && a.centerY <= b.bounds.max_y;
+  return centerInsideB ? 25 : 0;
+};
+var createIssue = (issue) => issue;
+var getComponentByPcbId = (componentsByPcbId, pcbComponentId) => {
+  if (typeof pcbComponentId !== "string")
+    return null;
+  return componentsByPcbId.get(pcbComponentId) ?? null;
+};
+var getLayers = (value) => {
+  if (!Array.isArray(value))
+    return [];
+  return value.filter((layer) => typeof layer === "string");
+};
+var buildComponentContexts = (circuitJson) => {
+  const components = [];
+  const sourceComponentsById = /* @__PURE__ */ new Map;
+  const componentByName = /* @__PURE__ */ new Map;
+  const componentsByPcbId = /* @__PURE__ */ new Map;
+  let order = 0;
+  for (const el of circuitJson) {
+    if (el.type !== "source_component" || typeof el.source_component_id !== "string" || typeof el.name !== "string") {
+      continue;
+    }
+    if (componentByName.has(el.name))
+      continue;
+    const context = {
+      name: el.name,
+      sourceComponent: el,
+      sourceComponentId: el.source_component_id,
+      pcbComponent: null,
+      pcbComponentId: null,
+      centerX: null,
+      centerY: null,
+      layer: null,
+      width: null,
+      height: null,
+      bounds: null,
+      anchorAlignment: CENTER_ANCHOR2,
+      placementMode: "none",
+      pads: [],
+      courtyards: [],
+      isConnectorLike: false,
+      order: order++
+    };
+    const xDefinitionRaw = el.pcbX ?? el.pcb_x ?? el.x;
+    const yDefinitionRaw = el.pcbY ?? el.pcb_y ?? el.y;
+    context.xDefinition = xDefinitionRaw === undefined ? undefined : String(xDefinitionRaw);
+    context.yDefinition = yDefinitionRaw === undefined ? undefined : String(yDefinitionRaw);
+    if (context.xDefinition !== undefined || context.yDefinition !== undefined) {
+      context.placementMode = "props_set";
+    } else if (el.placement_mode === "auto") {
+      context.placementMode = "auto";
+    }
+    components.push(context);
+    sourceComponentsById.set(context.sourceComponentId, context);
+    componentByName.set(context.name, context);
+  }
+  for (const el of circuitJson) {
+    if (el.type !== "pcb_component" || typeof el.source_component_id !== "string" || typeof el.pcb_component_id !== "string") {
+      continue;
+    }
+    const context = sourceComponentsById.get(el.source_component_id);
+    if (!context)
+      continue;
+    context.pcbComponent = el;
+    context.pcbComponentId = el.pcb_component_id;
+    componentsByPcbId.set(el.pcb_component_id, context);
+    const center = typeof el.center === "object" && el.center ? el.center : null;
+    context.centerX = center ? toNumber22(center.x) : null;
+    context.centerY = center ? toNumber22(center.y) : null;
+    context.layer = typeof el.layer === "string" ? el.layer : null;
+    context.width = toNumber22(el.width);
+    context.height = toNumber22(el.height);
+    if (context.centerX !== null && context.centerY !== null && context.width !== null && context.height !== null) {
+      context.bounds = getBoundsFromCenterAndSize(context.centerX, context.centerY, context.width, context.height);
+    }
+    if (context.placementMode === "none" && el.position_mode === "auto") {
+      context.placementMode = "auto";
+    }
+    if (context.sourceComponent.ftype === "simple_pin_header" && context.width !== null && context.height !== null) {
+      context.orientation = context.width >= context.height ? "horizontal" : "vertical";
+    }
+  }
+  for (const el of circuitJson) {
+    if (el.type === "pcb_silkscreen_text" && typeof el.anchor_alignment === "string") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      context.anchorAlignment = el.anchor_alignment;
+      continue;
+    }
+    if (el.type === "pcb_smtpad") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      const x = toNumber22(el.x);
+      const y = toNumber22(el.y);
+      const width = toNumber22(el.width);
+      const height = toNumber22(el.height);
+      const layer = typeof el.layer === "string" ? el.layer : null;
+      if (x === null || y === null || width === null || height === null || !layer)
+        continue;
+      context.pads.push({
+        bounds: getBoundsFromCenterAndSize(x, y, width, height),
+        layers: [layer]
+      });
+      continue;
+    }
+    if (el.type === "pcb_plated_hole") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      const x = toNumber22(el.x);
+      const y = toNumber22(el.y);
+      const layers = getLayers(el.layers);
+      if (x === null || y === null || layers.length === 0)
+        continue;
+      let width = null;
+      let height = null;
+      if (el.shape === "circle") {
+        const diameter = toNumber22(el.outer_diameter) ?? toNumber22(el.hole_diameter);
+        width = diameter;
+        height = diameter;
+      } else if (el.shape === "circular_hole_with_rect_pad" || el.shape === "pill_hole_with_rect_pad" || el.shape === "rotated_pill_hole_with_rect_pad") {
+        width = toNumber22(el.rect_pad_width);
+        height = toNumber22(el.rect_pad_height);
+      } else if (el.shape === "hole_with_polygon_pad") {
+        const padOutline = Array.isArray(el.pad_outline) ? el.pad_outline : [];
+        const padBounds = getBoundsFromPoints(padOutline.map((point) => ({
+          x: (toNumber22(point.x) ?? 0) + x,
+          y: (toNumber22(point.y) ?? 0) + y
+        })));
+        if (padBounds) {
+          context.pads.push({
+            bounds: padBounds,
+            layers
+          });
+        }
+        continue;
+      }
+      if (width === null || height === null)
+        continue;
+      context.pads.push({
+        bounds: getBoundsFromCenterAndSize(x, y, width, height),
+        layers
+      });
+      continue;
+    }
+    if (el.type === "pcb_courtyard_rect") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      const center = typeof el.center === "object" && el.center ? el.center : null;
+      const centerX = center ? toNumber22(center.x) : null;
+      const centerY = center ? toNumber22(center.y) : null;
+      const width = toNumber22(el.width);
+      const height = toNumber22(el.height);
+      if (centerX === null || centerY === null || width === null || height === null)
+        continue;
+      context.courtyards.push(getBoundsFromCenterAndSize(centerX, centerY, width, height));
+      continue;
+    }
+    if (el.type === "pcb_courtyard_outline") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      const outline = Array.isArray(el.outline) ? el.outline : [];
+      const bounds = getBoundsFromPoints(outline);
+      if (bounds)
+        context.courtyards.push(bounds);
+      continue;
+    }
+    if (el.type === "pcb_courtyard_polygon") {
+      const context = getComponentByPcbId(componentsByPcbId, el.pcb_component_id);
+      if (!context)
+        continue;
+      const points = Array.isArray(el.points) ? el.points : [];
+      const bounds = getBoundsFromPoints(points);
+      if (bounds)
+        context.courtyards.push(bounds);
+    }
+  }
+  for (const context of components) {
+    const nameUpper = context.name.toUpperCase();
+    const ftype = String(context.sourceComponent.ftype ?? "").toUpperCase();
+    const manufacturerPartNumber = String(context.sourceComponent.manufacturer_part_number ?? context.sourceComponent.manufacturerPartNumber ?? "").toUpperCase();
+    const platedHoleCount = context.pads.filter((pad) => pad.layers.includes("bottom")).length;
+    context.isConnectorLike = ftype === "SIMPLE_PIN_HEADER" || nameUpper.startsWith("USB") || /^J[A-Z0-9_]*\d*$/.test(nameUpper) || /USB|CONN|CONNECTOR|HEADER|SOCKET|JST|HDMI|RJ|BARREL/.test(manufacturerPartNumber) || platedHoleCount >= 4 && context.bounds !== null && Math.max(context.bounds.width, context.bounds.height) >= 4;
+  }
+  const pcbBoard = circuitJson.find((el) => el.type === "pcb_board");
+  const boardCenter = pcbBoard && typeof pcbBoard.center === "object" && pcbBoard.center ? pcbBoard.center : null;
+  const boardCenterX = boardCenter ? toNumber22(boardCenter.x) : null;
+  const boardCenterY = boardCenter ? toNumber22(boardCenter.y) : null;
+  const boardWidth = toNumber22(pcbBoard?.width);
+  const boardHeight = toNumber22(pcbBoard?.height);
+  const boardBounds = boardCenterX !== null && boardCenterY !== null && boardWidth !== null && boardHeight !== null ? getBoundsFromCenterAndSize(boardCenterX, boardCenterY, boardWidth, boardHeight) : null;
+  return {
+    components,
+    componentByName,
+    boardBounds
+  };
+};
+var buildIssues = (components, boardBounds) => {
+  const issues = [];
+  for (const component of components) {
+    const boardEdgeStatus = getBoardEdgeStatus(component.bounds, boardBounds, component.name);
+    if (!boardEdgeStatus || boardEdgeStatus.status !== "outside")
+      continue;
+    const moveDirection = getMoveDirectionForEdge(boardEdgeStatus.edge);
+    issues.push(createIssue({
+      type: "off_board",
+      componentA: component.name,
+      clearance: -boardEdgeStatus.distance,
+      severity: 220 + boardEdgeStatus.distance * 100,
+      summary: `${component.name} is ${fmtMm2(boardEdgeStatus.distance)} outside ${boardEdgeStatus.edge} edge`,
+      suggested_move: `move ${component.name} ${fmtMm2(boardEdgeStatus.distance)} ${moveDirection} to clear ${boardEdgeStatus.edge} edge`
+    }));
+  }
+  for (let i = 0;i < components.length; i += 1) {
+    const a = components[i];
+    if (!a)
+      continue;
+    for (let j = i + 1;j < components.length; j += 1) {
+      const b = components[j];
+      if (!b)
+        continue;
+      if (!a.bounds || !b.bounds)
+        continue;
+      if (a.layer !== null && b.layer !== null && a.layer !== b.layer)
+        continue;
+      let strongestPadOverlap = null;
+      for (const padA of a.pads) {
+        for (const padB of b.pads) {
+          if (!layersIntersect(padA.layers, padB.layers))
+            continue;
+          const overlap = getOverlap(padA.bounds, padB.bounds);
+          if (!overlap)
+            continue;
+          if (!strongestPadOverlap || overlap.clearance < strongestPadOverlap.clearance) {
+            strongestPadOverlap = overlap;
+          }
+        }
+      }
+      const bodyOverlap = getOverlap(a.bounds, b.bounds);
+      let strongestCourtyardOverlap = null;
+      if (!strongestPadOverlap) {
+        for (const courtyardA of a.courtyards) {
+          for (const courtyardB of b.courtyards) {
+            const overlap = getOverlap(courtyardA, courtyardB);
+            if (!overlap)
+              continue;
+            if (!strongestCourtyardOverlap || overlap.clearance < strongestCourtyardOverlap.clearance) {
+              strongestCourtyardOverlap = overlap;
+            }
+          }
+        }
+      }
+      if (strongestPadOverlap) {
+        issues.push(createIssue({
+          type: "pad_overlap",
+          componentA: a.name,
+          componentB: b.name,
+          clearance: strongestPadOverlap.clearance,
+          severity: 300 + Math.abs(strongestPadOverlap.clearance) * 120,
+          summary: `${a.name} and ${b.name} pad overlap by ${fmtMm2(Math.abs(strongestPadOverlap.clearance))}`,
+          suggested_move: getSeparationSuggestion(a, b, strongestPadOverlap.overlapX, strongestPadOverlap.overlapY)
+        }));
+      }
+      if (bodyOverlap) {
+        if (a.isConnectorLike || b.isConnectorLike) {
+          const connector = a.isConnectorLike ? a : b;
+          const intruder = connector === a ? b : a;
+          const overlapX = bodyOverlap.overlapX;
+          const overlapY = bodyOverlap.overlapY;
+          const containmentBonus = getCountainmentBonus(intruder, connector);
+          issues.push(createIssue({
+            type: "connector_body_intrusion",
+            componentA: intruder.name,
+            componentB: connector.name,
+            clearance: bodyOverlap.clearance,
+            severity: 260 + Math.abs(bodyOverlap.clearance) * 100 + containmentBonus,
+            summary: `${intruder.name} intrudes ${fmtMm2(Math.abs(bodyOverlap.clearance))} into ${connector.name} connector body`,
+            suggested_move: getSeparationSuggestion(a, b, overlapX, overlapY, intruder.name)
+          }));
+        } else if (!strongestPadOverlap) {
+          const containmentBonus = getCountainmentBonus(a, b) + getCountainmentBonus(b, a);
+          issues.push(createIssue({
+            type: "footprint_intrusion",
+            componentA: a.name,
+            componentB: b.name,
+            clearance: bodyOverlap.clearance,
+            severity: 180 + Math.abs(bodyOverlap.clearance) * 80 + containmentBonus,
+            summary: `${a.name} and ${b.name} footprint intrusion by ${fmtMm2(Math.abs(bodyOverlap.clearance))}`,
+            suggested_move: getSeparationSuggestion(a, b, bodyOverlap.overlapX, bodyOverlap.overlapY)
+          }));
+        }
+      } else if (strongestCourtyardOverlap) {
+        issues.push(createIssue({
+          type: "courtyard_collision",
+          componentA: a.name,
+          componentB: b.name,
+          clearance: strongestCourtyardOverlap.clearance,
+          severity: 120 + Math.abs(strongestCourtyardOverlap.clearance) * 80,
+          summary: `${a.name} and ${b.name} courtyard collision by ${fmtMm2(Math.abs(strongestCourtyardOverlap.clearance))}`,
+          suggested_move: getSeparationSuggestion(a, b, strongestCourtyardOverlap.overlapX, strongestCourtyardOverlap.overlapY)
+        }));
+      }
+    }
+  }
+  return issues.sort((a, b) => b.severity - a.severity);
+};
+var buildClusters = (components, issues) => {
+  const componentsByName = new Map(components.map((component) => [component.name, component]));
+  const adjacency = /* @__PURE__ */ new Map;
+  const incidentSeverity = /* @__PURE__ */ new Map;
+  for (const component of components) {
+    adjacency.set(component.name, /* @__PURE__ */ new Set);
+    incidentSeverity.set(component.name, 0);
+  }
+  for (const issue of issues) {
+    if (!issue.componentB)
+      continue;
+    adjacency.get(issue.componentA)?.add(issue.componentB);
+    adjacency.get(issue.componentB)?.add(issue.componentA);
+    incidentSeverity.set(issue.componentA, (incidentSeverity.get(issue.componentA) ?? 0) + issue.severity);
+    incidentSeverity.set(issue.componentB, (incidentSeverity.get(issue.componentB) ?? 0) + issue.severity);
+  }
+  const visited = /* @__PURE__ */ new Set;
+  const clusters = [];
+  for (const component of components) {
+    if (visited.has(component.name))
+      continue;
+    const queue = [component.name];
+    const members = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (visited.has(current))
+        continue;
+      visited.add(current);
+      members.push(current);
+      for (const neighbor of adjacency.get(current) ?? []) {
+        if (!visited.has(neighbor))
+          queue.push(neighbor);
+      }
+    }
+    if (members.length < 3)
+      continue;
+    const memberSet = new Set(members);
+    const severity = issues.filter((issue) => issue.componentB && memberSet.has(issue.componentA) && memberSet.has(issue.componentB)).reduce((sum, issue) => sum + issue.severity, 0);
+    if (severity === 0)
+      continue;
+    const sortedMembers = [...members].sort((a, b) => {
+      const severityA = incidentSeverity.get(a) ?? 0;
+      const severityB = incidentSeverity.get(b) ?? 0;
+      if (severityA !== severityB)
+        return severityB - severityA;
+      const orderA = componentsByName.get(a)?.order ?? 0;
+      const orderB = componentsByName.get(b)?.order ?? 0;
+      return orderA - orderB;
+    });
+    const labelComponent = sortedMembers.find((name) => componentsByName.get(name)?.isConnectorLike) ?? sortedMembers[0];
+    if (!labelComponent)
+      continue;
+    clusters.push({
+      clusterName: `${stripNumericSuffix(labelComponent)} cluster`,
+      componentNames: sortedMembers,
+      severity
+    });
+  }
+  return clusters.sort((a, b) => b.severity - a.severity);
+};
+var buildCountsByType = (issues) => {
+  const counts = {};
+  for (const issue of issues) {
+    counts[issue.type] = (counts[issue.type] ?? 0) + 1;
+  }
+  return counts;
+};
+var buildComponentStatuses = (components, boardBounds, issues) => components.map((component) => {
+  const componentIssues = issues.filter((issue) => issue.componentA === component.name || issue.componentB === component.name);
+  return {
+    componentName: component.name,
+    placementMode: component.placementMode,
+    sourcePlacement: {
+      xDefinition: component.xDefinition,
+      yDefinition: component.yDefinition
+    },
+    resolvedPlacement: {
+      center: component.centerX !== null && component.centerY !== null && component.layer !== null ? {
+        x: component.centerX,
+        y: component.centerY,
+        layer: component.layer
+      } : undefined,
+      bounds: component.bounds ? {
+        width: component.bounds.width,
+        height: component.bounds.height,
+        min_x: component.bounds.min_x,
+        max_x: component.bounds.max_x,
+        min_y: component.bounds.min_y,
+        max_y: component.bounds.max_y
+      } : undefined,
+      anchorAlignment: component.anchorAlignment,
+      orientation: component.orientation
+    },
+    boardEdgeStatus: getBoardEdgeStatus(component.bounds, boardBounds, component.name),
+    issues: componentIssues
+  };
+});
+var formatSourcePlacement = (component) => {
+  const bits = [`placement_mode=${component.placementMode}`];
+  if (component.sourcePlacement.xDefinition !== undefined) {
+    bits.push(`x=${component.sourcePlacement.xDefinition}`);
+  }
+  if (component.sourcePlacement.yDefinition !== undefined) {
+    bits.push(`y=${component.sourcePlacement.yDefinition}`);
+  }
+  return bits.join(", ");
+};
+var formatResolvedPlacement = (component) => {
+  const bits = [];
+  const center = component.resolvedPlacement.center;
+  const bounds = component.resolvedPlacement.bounds;
+  if (center) {
+    bits.push(`center=(${fmtMm2(center.x)}, ${fmtMm2(center.y)}) on ${center.layer}`);
+  }
+  if (bounds) {
+    bits.push(`bounds=(minX=${fmtMm2(bounds.min_x)}, maxX=${fmtMm2(bounds.max_x)}, minY=${fmtMm2(bounds.min_y)}, maxY=${fmtMm2(bounds.max_y)})`);
+    bits.push(`size=(width=${fmtMm2(bounds.width)}, height=${fmtMm2(bounds.height)})`);
+  }
+  bits.push(`anchor_alignment="${component.resolvedPlacement.anchorAlignment}"`);
+  if (component.resolvedPlacement.orientation) {
+    bits.push(`orientation=${component.resolvedPlacement.orientation}`);
+  }
+  return bits.join("; ");
+};
+var formatIssue = (issue) => {
+  const suffix = issue.suggested_move ? ` Suggested move: ${issue.suggested_move}.` : "";
+  return `${issue.summary}.${suffix}`;
+};
+var formatPlacementAnalysisReport = (report) => {
+  const lines = [];
+  const summaryBits = ISSUE_TYPE_ORDER.map((type) => getSummaryLabel(type, report.summary.countsByType[type] ?? 0)).filter((entry) => Boolean(entry));
+  lines.push(summaryBits.length > 0 ? `placement summary: ${summaryBits.join(", ")}` : "placement summary: no placement issues");
+  if (report.summary.topIssues.length > 0) {
+    lines.push("");
+    lines.push("worst issues:");
+    report.summary.topIssues.forEach((issue, index) => {
+      lines.push(`${index + 1}. ${formatIssue(issue)}`);
+    });
+  }
+  if (report.summary.likelyBadClusters.length > 0) {
+    lines.push("");
+    lines.push("likely bad clusters:");
+    for (const cluster of report.summary.likelyBadClusters) {
+      lines.push(`- ${cluster.clusterName}: ${cluster.componentNames.join(", ")}`);
+    }
+  }
+  lines.push("");
+  lines.push("board-edge status:");
+  for (const component of report.components) {
+    if (!component.boardEdgeStatus)
+      continue;
+    lines.push(`- ${component.componentName}: ${formatBoardEdgeStatus(component.boardEdgeStatus)}`);
+  }
+  const flaggedComponents = report.components.filter((component) => component.issues.length > 0);
+  if (flaggedComponents.length > 0) {
+    lines.push("");
+    lines.push("flagged components:");
+    for (const component of flaggedComponents) {
+      lines.push(`- ${component.componentName}`);
+      lines.push(`  source placement: ${formatSourcePlacement(component)}`);
+      lines.push(`  resolved placement: ${formatResolvedPlacement(component)}`);
+      if (component.boardEdgeStatus) {
+        lines.push(`  board edge status: ${formatBoardEdgeStatus(component.boardEdgeStatus)}`);
+      }
+      lines.push("  issues:");
+      for (const issue of component.issues) {
+        lines.push(`  - ${formatIssue(issue)}`);
+      }
+    }
+  }
+  return lines.join(`
+`);
+};
+var buildPlacementAnalysisReport = (circuitJson) => {
+  const { components, boardBounds } = buildComponentContexts(circuitJson);
+  const issues = buildIssues(components, boardBounds);
+  const clusters = buildClusters(components, issues);
+  const countsByType = buildCountsByType(issues);
+  return {
+    summary: {
+      totalIssueCount: issues.length,
+      countsByType,
+      topIssues: issues.slice(0, TOP_ISSUE_LIMIT),
+      likelyBadClusters: clusters
+    },
+    components: buildComponentStatuses(components, boardBounds, issues),
+    issues
+  };
+};
 var analyzeAllPlacements = (circuitJson) => {
   const componentNames = [];
   const seenNames = /* @__PURE__ */ new Set;
@@ -110767,10 +111434,12 @@ var analyzeAllPlacements = (circuitJson) => {
     analysis: analyzeComponentPlacement(circuitJson, componentName)
   }));
   const lineItems = analyses.flatMap(({ analysis }) => analysis.getLineItems());
+  const report = buildPlacementAnalysisReport(circuitJson);
   return {
     getLineItems: () => lineItems,
-    getString: () => analyses.map(({ analysis }) => analysis.getString()).join(`
-`)
+    getString: () => formatPlacementAnalysisReport(report),
+    getIssues: () => report.issues,
+    getReport: () => report
   };
 };
 
@@ -110785,8 +111454,10 @@ var checkPlacement = async (file, refdes) => {
     },
     allowPrebuiltCircuitJson: true
   });
-  const analysis = refdes ? analyzeComponentPlacement(circuitJson, refdes) : analyzeAllPlacements(circuitJson);
-  return analysis.getString();
+  if (refdes) {
+    return analyzeComponentPlacement(circuitJson, refdes).getString();
+  }
+  return analyzeAllPlacements(circuitJson).getString();
 };
 var registerCheckPlacement = (program2) => {
   program2.commands.find((c) => c.name() === "check").command("placement").description("Partially build and validate the placement").argument("[file]", "Path to the entry file").argument("[refdes]", "Optional refdes to scope the check").action(async (file, refdes) => {
@@ -133568,7 +134239,7 @@ var getDirectionalFreeSpace = (spatialIndex, componentIndex, directions) => {
   }
   return freeSpaceByDirection;
 };
-var fmtMm2 = (value) => `${value.toFixed(1)}mm`;
+var fmtMm3 = (value) => `${value.toFixed(1)}mm`;
 var roundsToZeroMm = (value) => Math.abs(value) < 0.05;
 var toNumber3 = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
 var getPcbComponentBounds = (element) => {
@@ -133612,10 +134283,10 @@ var getPlacedComponents = (circuitJson) => {
   }
   return placedComponents;
 };
-var getOffsetFromTopOfRegion = (componentBounds, regionBounds) => fmtMm2(regionBounds.maxY - componentBounds.maxY);
-var getOffsetFromBottomOfRegion = (componentBounds, regionBounds) => fmtMm2(componentBounds.minY - regionBounds.minY);
-var getOffsetFromLeftOfRegion = (componentBounds, regionBounds) => fmtMm2(componentBounds.minX - regionBounds.minX);
-var getOffsetFromRightOfRegion = (componentBounds, regionBounds) => fmtMm2(regionBounds.maxX - componentBounds.maxX);
+var getOffsetFromTopOfRegion = (componentBounds, regionBounds) => fmtMm3(regionBounds.maxY - componentBounds.maxY);
+var getOffsetFromBottomOfRegion = (componentBounds, regionBounds) => fmtMm3(componentBounds.minY - regionBounds.minY);
+var getOffsetFromLeftOfRegion = (componentBounds, regionBounds) => fmtMm3(componentBounds.minX - regionBounds.minX);
+var getOffsetFromRightOfRegion = (componentBounds, regionBounds) => fmtMm3(regionBounds.maxX - componentBounds.maxX);
 var addEdgeAlignedOffsets = (nearbyComponent, componentBounds, regionBounds) => {
   if (nearbyComponent.onLeftEdgeOfRegion || nearbyComponent.onRightEdgeOfRegion) {
     nearbyComponent.distToTopOfRegion = getOffsetFromTopOfRegion(componentBounds, regionBounds);
@@ -133747,28 +134418,28 @@ var getOutsideComponentCandidate = (component, componentIndex, regionBounds) =>
         if (roundsToZeroMm(candidate.distance)) {
           nearbyComponentCandidate.onLeftEdgeOfRegion = true;
         } else {
-          nearbyComponentCandidate.distToLeftEdgeOfRegion = fmtMm2(candidate.distance);
+          nearbyComponentCandidate.distToLeftEdgeOfRegion = fmtMm3(candidate.distance);
         }
         break;
       case "right":
         if (roundsToZeroMm(candidate.distance)) {
           nearbyComponentCandidate.onRightEdgeOfRegion = true;
         } else {
-          nearbyComponentCandidate.distToRightEdgeOfRegion = fmtMm2(candidate.distance);
+          nearbyComponentCandidate.distToRightEdgeOfRegion = fmtMm3(candidate.distance);
         }
         break;
       case "top":
         if (roundsToZeroMm(candidate.distance)) {
           nearbyComponentCandidate.onTopEdgeOfRegion = true;
         } else {
-          nearbyComponentCandidate.distToTopOfRegion = fmtMm2(candidate.distance);
+          nearbyComponentCandidate.distToTopOfRegion = fmtMm3(candidate.distance);
         }
         break;
       case "bottom":
         if (roundsToZeroMm(candidate.distance)) {
           nearbyComponentCandidate.onBottomEdgeOfRegion = true;
         } else {
-          nearbyComponentCandidate.distToBottomOfRegion = fmtMm2(candidate.distance);
+          nearbyComponentCandidate.distToBottomOfRegion = fmtMm3(candidate.distance);
         }
         break;
     }
@@ -168821,7 +169492,7 @@ function normalizeDegrees(angle) {
 var doBoundsOverlap = (bounds1, bounds2) => {
   return !(bounds1.maxX < bounds2.minX || bounds2.maxX < bounds1.minX || bounds1.maxY < bounds2.minY || bounds2.maxY < bounds1.minY);
 };
-var getBoundsFromPoints = (points) => {
+var getBoundsFromPoints2 = (points) => {
   if (points.length === 0) {
     return null;
   }
@@ -198646,8 +199317,8 @@ function checkCourtyardOverlap(circuitJson) {
           for (const b22 of byComponent.get(idB)) {
             const polyA = getCourtyardPolygon(a2);
             const polyB = getCourtyardPolygon(b22);
-            const boundsA = getBoundsFromPoints(polyA);
-            const boundsB = getBoundsFromPoints(polyB);
+            const boundsA = getBoundsFromPoints2(polyA);
+            const boundsB = getBoundsFromPoints2(polyB);
             if (!boundsA || !boundsB)
               continue;
             if (areBoundsOverlappingPolygon(boundsA, polyB) || areBoundsOverlappingPolygon(boundsB, polyA)) {
@@ -219679,7 +220350,7 @@ var CourtyardOutline = class extends PrimitiveComponent2 {
     if (!props.outline || props.outline.length === 0) {
       return { width: 0, height: 0 };
     }
-    const bounds = getBoundsFromPoints(props.outline);
+    const bounds = getBoundsFromPoints2(props.outline);
     if (!bounds) {
       return { width: 0, height: 0 };
     }
@@ -223588,7 +224259,7 @@ var NormalComponent__getMinimumFlexContainerSize = (component) => {
     if (!pcbGroup)
       return null;
     if (pcbGroup.outline && pcbGroup.outline.length > 0) {
-      const bounds = getBoundsFromPoints(pcbGroup.outline);
+      const bounds = getBoundsFromPoints2(pcbGroup.outline);
       if (!bounds)
         return null;
       return {
@@ -226857,7 +227528,7 @@ function Group_doInitialPcbComponentAnchorAlignment(group) {
   let height = pcbGroup.height;
   const { center: center2 } = pcbGroup;
   if (pcbGroup.outline && pcbGroup.outline.length > 0) {
-    const bounds2 = getBoundsFromPoints(pcbGroup.outline);
+    const bounds2 = getBoundsFromPoints2(pcbGroup.outline);
     if (bounds2) {
       width = bounds2.maxX - bounds2.minX;
       height = bounds2.maxY - bounds2.minY;
@@ -230167,7 +230838,7 @@ var Group6 = class extends NormalComponent3 {
         x: distance.parse(point6.x),
         y: distance.parse(point6.y)
       }));
-      const outlineBounds = getBoundsFromPoints(numericOutline);
+      const outlineBounds = getBoundsFromPoints2(numericOutline);
       if (!outlineBounds)
         return;
       const centerX2 = (outlineBounds.minX + outlineBounds.maxX) / 2;
@@ -232099,7 +232770,7 @@ var Board = class extends Group6 {
     let width = dbBoard?.width ?? props.width;
     let height = dbBoard?.height ?? props.height;
     if ((width == null || height == null) && props.outline?.length) {
-      const outlineBounds = getBoundsFromPoints(props.outline);
+      const outlineBounds = getBoundsFromPoints2(props.outline);
       if (outlineBounds) {
         width ??= outlineBounds.maxX - outlineBounds.minX;
         height ??= outlineBounds.maxY - outlineBounds.minY;
@@ -232155,7 +232826,7 @@ var Board = class extends Group6 {
       let width = pcbGroup.width ?? 0;
       let height = pcbGroup.height ?? 0;
       if (pcbGroup.outline && pcbGroup.outline.length > 0) {
-        const bounds = getBoundsFromPoints(pcbGroup.outline);
+        const bounds = getBoundsFromPoints2(pcbGroup.outline);
         if (bounds) {
           width = bounds.maxX - bounds.minX;
           height = bounds.maxY - bounds.minY;
@@ -232306,7 +232977,7 @@ var Board = class extends Group6 {
     }
     let outlineTranslation = { x: 0, y: 0 };
     if (outline && outline.length > 0 && (this.parent?.lowercaseComponentName === "panel" || this.parent?.lowercaseComponentName === "subpanel")) {
-      const outlineBounds = getBoundsFromPoints(outline);
+      const outlineBounds = getBoundsFromPoints2(outline);
       if (outlineBounds) {
         const outlineCenterX = (outlineBounds.minX + outlineBounds.maxX) / 2;
         const outlineCenterY = (outlineBounds.minY + outlineBounds.maxY) / 2;
@@ -232421,7 +233092,7 @@ var Board = class extends Group6 {
     if (this.pcb_board_id) {
       db.pcb_board.update(this.pcb_board_id, { center: position2 });
       if (pcbBoard?.outline) {
-        const outlineBounds = getBoundsFromPoints(pcbBoard.outline);
+        const outlineBounds = getBoundsFromPoints2(pcbBoard.outline);
         if (outlineBounds) {
           const oldOutlineCenter = {
             x: (outlineBounds.minX + outlineBounds.maxX) / 2,
@@ -232724,7 +233395,7 @@ var getBoardDimensionsFromProps = (board) => {
   let width = props.width != null ? distance.parse(props.width) : undefined;
   let height = props.height != null ? distance.parse(props.height) : undefined;
   if ((width === undefined || height === undefined) && props.outline?.length) {
-    const outlineBounds = getBoundsFromPoints(props.outline);
+    const outlineBounds = getBoundsFromPoints2(props.outline);
     if (outlineBounds) {
       width ??= outlineBounds.maxX - outlineBounds.minX;
       height ??= outlineBounds.maxY - outlineBounds.minY;
@@ -236890,13 +237561,13 @@ var solveForGlobalCapacityNodes = async (circuitJson) => {
   await solver.solveUntilPhase("highDensityRouteSolver");
   return solver.uniformPortDistributionSolver?.getOutput() ?? [];
 };
-var fmtNumber2 = (value) => {
+var fmtNumber3 = (value) => {
   if (Number.isInteger(value))
     return String(value);
   return value.toFixed(3).replace(/\.0+$/, "").replace(/(\.\d*?)0+$/, "$1");
 };
 var fmtMm22 = (value) => `${value.toFixed(1)}mm`;
-var fmtPercent = (value) => `${fmtNumber2(value * 100)}%`;
+var fmtPercent = (value) => `${fmtNumber3(value * 100)}%`;
 var isCrampedPortPoint = (portPointId) => portPointId?.includes("_cramped") ?? false;
 var clamp012 = (value) => Math.max(0, Math.min(1, value));
 var roundProbability = (value) => Number.parseFloat(value.toFixed(3));

package/dist/lib/index.js

@@ -60678,7 +60678,7 @@ var getNodeHandler = (winterSpec, { port, middleware = [] }) => {
   }));
 };
 // package.json
-var version = "0.1.1173";
+var version = "0.1.1175";
 var package_default = {
   name: "@tscircuit/cli",
   version,
@@ -60690,7 +60690,7 @@ var package_default = {
   devDependencies: {
     "@babel/standalone": "^7.26.9",
     "@biomejs/biome": "^1.9.4",
-    "@tscircuit/circuit-json-placement-analysis": "^0.0.4",
+    "@tscircuit/circuit-json-placement-analysis": "^0.0.5",
     "@tscircuit/circuit-json-routing-analysis": "^0.0.1",
     "@tscircuit/fake-snippets": "^0.0.182",
     "@tscircuit/file-server": "^0.0.32",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/cli",
-  "version": "0.1.1175",
+  "version": "0.1.1176",
   "main": "dist/cli/main.js",
   "exports": {
     ".": "./dist/cli/main.js",
@@ -9,7 +9,7 @@
   "devDependencies": {
     "@babel/standalone": "^7.26.9",
     "@biomejs/biome": "^1.9.4",
-    "@tscircuit/circuit-json-placement-analysis": "^0.0.4",
+    "@tscircuit/circuit-json-placement-analysis": "^0.0.5",
     "@tscircuit/circuit-json-routing-analysis": "^0.0.1",
     "@tscircuit/fake-snippets": "^0.0.182",
     "@tscircuit/file-server": "^0.0.32",