traceforge-pcb 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,455 @@
1
+ """Check a design's part numbers against live catalogue data.
2
+
3
+ For every BOM part with an LCSC code or MPN: does the part exist, does its
4
+ package fit the footprint (chip size, SOIC body width, pin count, pitch,
5
+ SMD/THT), does it match the schematic value and MPN, is it in stock, is it a
6
+ JLCPCB basic or extended part. Without network and cache the findings say so
7
+ ("not verified: offline") instead of passing silently.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ from dataclasses import dataclass, field
14
+
15
+ from traceforge.checks import Finding
16
+ from traceforge.kicad.pcb import Board
17
+ from traceforge.kicad.schematic import Schematic
18
+ from traceforge.parts.catalog import Catalog, LookupReport, default_catalog
19
+ from traceforge.parts.model import PartInfo, is_lcsc_code, normalize_lcsc
20
+ from traceforge.parts.net import Offline
21
+ from traceforge.parts.packages import compare, parse_catalog_package, parse_footprint
22
+ from traceforge.parts.providers.base import norm_mpn, same_device
23
+ from traceforge.parts.providers.jlc import parse_value
24
+
25
+ LCSC_FIELDS = (
26
+ "LCSC",
27
+ "LCSC Part",
28
+ "LCSC Part #",
29
+ "LCSC#",
30
+ "LCSC_PN",
31
+ "JLCPCB Part",
32
+ "JLCPCB",
33
+ "JLC",
34
+ )
35
+ MPN_FIELDS = (
36
+ "MPN",
37
+ "Manufacturer_Part_Number",
38
+ "Mfr. Part #",
39
+ "MFR",
40
+ "MFG Part",
41
+ "Part Number",
42
+ "PN",
43
+ )
44
+ LOW_STOCK = 100
45
+ _COLORS = ("red", "green", "blue", "white", "yellow", "orange", "amber", "pink", "purple")
46
+ _MPN_LIKE = re.compile(r"^(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9][A-Za-z0-9.+/_-]{3,}$")
47
+ _PASSIVE_PREFIX = ("R", "C", "L", "FB", "D", "LED", "F", "J", "P", "SW", "H", "TP")
48
+
49
+
50
+ def _field(fields: dict[str, str], names: tuple[str, ...]) -> str:
51
+ lowered = {k.lower(): v for k, v in fields.items()}
52
+ for name in names:
53
+ value = (lowered.get(name.lower()) or "").strip()
54
+ if value and value not in {"~", "-", "N/A", "n/a"}:
55
+ return value
56
+ return ""
57
+
58
+
59
+ @dataclass
60
+ class BomLine:
61
+ refs: list[str]
62
+ value: str
63
+ footprint: str
64
+ lcsc: str = ""
65
+ mpn: str = ""
66
+ pads: list[tuple[str, str]] | None = None
67
+ lib_id: str = ""
68
+ datasheet: str = ""
69
+ part: PartInfo | None = None
70
+ report: LookupReport | None = None
71
+ notes: list[str] = field(default_factory=list)
72
+
73
+ @property
74
+ def label(self) -> str:
75
+ refs = ", ".join(self.refs[:8]) + (
76
+ f" (+{len(self.refs) - 8})" if len(self.refs) > 8 else ""
77
+ )
78
+ return refs
79
+
80
+
81
+ def _ref_prefix(ref: str) -> str:
82
+ match = re.match(r"^[A-Za-z]+", ref)
83
+ return match.group(0).upper() if match else ""
84
+
85
+
86
+ def _library_pads(lib_id: str) -> list[tuple[str, str]] | None:
87
+ try:
88
+ from traceforge import sexpr
89
+ from traceforge.tools.kicad_tools import libraries
90
+
91
+ node = libraries().footprint(lib_id)
92
+ except Exception: # noqa: BLE001 - library missing or not installed
93
+ return None
94
+ return [(str(pad[1]), str(pad[2])) for pad in sexpr.find_all(node, "pad") if len(pad) > 2]
95
+
96
+
97
+ def bom_lines(schematic: Schematic, board: Board | None = None) -> list[BomLine]:
98
+ footprints = {f.reference: f for f in board.footprints} if board else {}
99
+ grouped: dict[tuple, BomLine] = {}
100
+ for ref, units in sorted(schematic.components().items()):
101
+ unit = units[0]
102
+ if unit.is_power or not unit.in_bom or unit.dnp or not unit.on_board:
103
+ continue
104
+ fields: dict[str, str] = {}
105
+ for u in units:
106
+ fields.update({k: v for k, v in u.fields.items() if v})
107
+ lcsc = _field(fields, LCSC_FIELDS)
108
+ mpn = _field(fields, MPN_FIELDS)
109
+ footprint = unit.footprint
110
+ pads = None
111
+ if ref in footprints:
112
+ fp = footprints[ref]
113
+ footprint = footprint or fp.lib_id
114
+ pads = [(p.number, p.kind) for p in fp.pads]
115
+ key = (lcsc.upper(), mpn, footprint, unit.value)
116
+ if key not in grouped:
117
+ datasheet = (fields.get("Datasheet") or "").strip()
118
+ grouped[key] = BomLine(
119
+ [],
120
+ unit.value,
121
+ footprint,
122
+ lcsc,
123
+ mpn,
124
+ pads,
125
+ unit.lib_id,
126
+ datasheet if datasheet.startswith("http") else "",
127
+ )
128
+ grouped[key].refs.append(ref)
129
+ return list(grouped.values())
130
+
131
+
132
+ def _catalog_facts(part: PartInfo):
133
+ return parse_catalog_package(
134
+ part.package, description=part.description, attributes=part.attributes
135
+ )
136
+
137
+
138
+ def _evidence(part: PartInfo) -> str:
139
+ bits = [f"{part.lcsc or '-'} = {part.manufacturer} {part.mpn}".strip()]
140
+ if part.package:
141
+ bits.append(f"package {part.package}")
142
+ if part.pin_count:
143
+ bits.append(f"{part.pin_count} pins")
144
+ if part.stock is not None:
145
+ bits.append(f"stock {part.stock}")
146
+ if part.library_type:
147
+ bits.append(part.library_type)
148
+ if part.product_url:
149
+ bits.append(part.product_url)
150
+ return "; ".join(bits)
151
+
152
+
153
+ def _passive_value(line: BomLine, part: PartInfo) -> str | None:
154
+ """Mismatch text when a resistor/capacitor/inductor value differs from the catalogue."""
155
+ prefix = _ref_prefix(line.refs[0])
156
+ keys = {
157
+ "R": ("Resistance",),
158
+ "C": ("Capacitance",),
159
+ "L": ("Inductance",),
160
+ }.get(prefix)
161
+ if not keys:
162
+ return None
163
+ unit = {"R": "", "C": "F", "L": "H"}[prefix]
164
+ catalog_text = next((part.attributes[k] for k in keys if part.attributes.get(k)), "")
165
+ if not catalog_text:
166
+ return None
167
+ wanted = parse_value(line.value.split("_")[0].split(" ")[0], unit)
168
+ actual = parse_value(catalog_text, unit)
169
+ if wanted is None or actual is None or actual == 0 and wanted == 0:
170
+ return None
171
+ if abs(wanted - actual) > 1e-6 * max(abs(wanted), abs(actual)):
172
+ return f"schematic value {line.value!r}, catalogue part is {catalog_text}"
173
+ return None
174
+
175
+
176
+ def _led_color(line: BomLine, part: PartInfo) -> str | None:
177
+ if _ref_prefix(line.refs[0]) not in {"D", "LED"}:
178
+ return None
179
+ value = line.value.lower()
180
+ wanted = [c for c in _COLORS if c in value]
181
+ if not wanted:
182
+ return None
183
+ text = " ".join(
184
+ [
185
+ part.attributes.get("Illumination Color", ""),
186
+ part.attributes.get("Emitted Color", ""),
187
+ part.description,
188
+ ]
189
+ ).lower()
190
+ have = [c for c in _COLORS if c in text]
191
+ if have and not set(wanted) & set(have):
192
+ return f"value says {', '.join(wanted)}, catalogue part is {', '.join(have)}"
193
+ return None
194
+
195
+
196
+ def _check_part(line: BomLine, part: PartInfo, findings: list[Finding]) -> None:
197
+ evidence = _evidence(part)
198
+ if part.stale:
199
+ evidence += " (cached data; the network was unavailable)"
200
+ if line.footprint:
201
+ fp_facts = parse_footprint(line.footprint, line.pads)
202
+ cat_facts = _catalog_facts(part)
203
+ mismatches = compare(cat_facts, fp_facts, pads=line.pads)
204
+ if mismatches:
205
+ severity = min(m.severity for m in mismatches)
206
+ findings.append(
207
+ Finding(
208
+ severity,
209
+ "parts.package",
210
+ f"{line.label}: {part.lcsc or part.mpn} ({part.mpn}) does not fit footprint "
211
+ f"{line.footprint.split(':')[-1]}: "
212
+ + "; ".join(f"{m.aspect}: {m.detail}" for m in mismatches),
213
+ list(line.refs),
214
+ evidence + f"; footprint: {fp_facts.describe()}",
215
+ )
216
+ )
217
+ if line.mpn and part.mpn and not same_device(line.mpn, part.mpn) and is_lcsc_code(line.lcsc):
218
+ findings.append(
219
+ Finding(
220
+ "P1",
221
+ "parts.mpn",
222
+ f"{line.label}: MPN field {line.mpn!r} but LCSC {part.lcsc} is {part.mpn!r}; "
223
+ "the assembler places the LCSC part",
224
+ list(line.refs),
225
+ evidence,
226
+ )
227
+ )
228
+ mismatch = _passive_value(line, part)
229
+ if mismatch:
230
+ findings.append(
231
+ Finding("P1", "parts.value", f"{line.label}: {mismatch}", list(line.refs), evidence)
232
+ )
233
+ color = _led_color(line, part)
234
+ if color:
235
+ findings.append(
236
+ Finding(
237
+ "P1", "parts.value", f"{line.label}: LED colour: {color}", list(line.refs), evidence
238
+ )
239
+ )
240
+ if part.stock is not None and part.stock <= 0:
241
+ alternates = (
242
+ f"; LCSC alternates: {', '.join(part.alternatives[:4])}" if part.alternatives else ""
243
+ )
244
+ findings.append(
245
+ Finding(
246
+ "P1",
247
+ "parts.stock",
248
+ f"{line.label}: {part.lcsc or part.mpn} ({part.mpn}) is out of stock"
249
+ + (f" ({part.lifecycle})" if part.lifecycle and part.lifecycle != "normal" else ""),
250
+ list(line.refs),
251
+ evidence + alternates,
252
+ )
253
+ )
254
+ elif part.stock is not None and part.stock < LOW_STOCK:
255
+ findings.append(
256
+ Finding(
257
+ "P2",
258
+ "parts.stock",
259
+ f"{line.label}: only {part.stock} of {part.lcsc or part.mpn} in stock",
260
+ list(line.refs),
261
+ evidence,
262
+ )
263
+ )
264
+ if part.lifecycle and re.search(
265
+ r"discontinu|obsolete|eol|nrnd|not recommended", part.lifecycle, re.I
266
+ ):
267
+ findings.append(
268
+ Finding(
269
+ "P1",
270
+ "parts.lifecycle",
271
+ f"{line.label}: {part.mpn} lifecycle is {part.lifecycle}",
272
+ list(line.refs),
273
+ evidence,
274
+ )
275
+ )
276
+
277
+
278
+ def _infer_from_value(line: BomLine, catalog: Catalog, findings: list[Finding]) -> None:
279
+ """The LCSC code is missing or unknown: try the value/MPN as a part-number prefix.
280
+
281
+ "ATtiny85-20S" matches ATTINY85-20SU/-20SF/-20SH, all SOIC-8-208mil; if every
282
+ catalogue match that states a fact contradicts the footprint, say so.
283
+ """
284
+ candidate = line.mpn or line.value
285
+ if not candidate or not _MPN_LIKE.match(candidate) or not line.footprint:
286
+ return
287
+ if not line.mpn and _ref_prefix(line.refs[0]) in _PASSIVE_PREFIX:
288
+ return
289
+ try:
290
+ results = catalog.search(candidate, in_stock=False, limit=20)
291
+ except Offline:
292
+ return
293
+ stem = norm_mpn(candidate)
294
+ matches = [p for p in results if norm_mpn(p.mpn).startswith(stem)]
295
+ if not matches:
296
+ return
297
+ fp_facts = parse_footprint(line.footprint, line.pads)
298
+ conflicts: list[tuple[PartInfo, list]] = []
299
+ supporters = []
300
+ for part in matches:
301
+ facts = _catalog_facts(part)
302
+ problems = [m for m in compare(facts, fp_facts, pads=line.pads) if m.severity == "P0"]
303
+ if problems:
304
+ conflicts.append((part, problems))
305
+ else:
306
+ supporters.append((part, facts))
307
+ if not conflicts:
308
+ return
309
+ aspects = {m.aspect for _, problems in conflicts for m in problems}
310
+ real_support = [
311
+ p
312
+ for p, facts in supporters
313
+ if ("body width" not in aspects or facts.body_width)
314
+ and ("size" not in aspects or facts.chip)
315
+ and ("pin count" not in aspects or facts.pins)
316
+ and ("pitch" not in aspects or facts.pitch)
317
+ and ("mounting" not in aspects or facts.mounting)
318
+ ]
319
+ if real_support:
320
+ return
321
+ part, problems = conflicts[0]
322
+ names = sorted({p.mpn for p, _ in conflicts})
323
+ findings.append(
324
+ Finding(
325
+ "P0" if len(conflicts) >= 2 else "P1",
326
+ "parts.package",
327
+ f"{line.label}: {candidate!r} matches catalogue parts ({', '.join(names[:6])}) that do "
328
+ f"not fit footprint {line.footprint.split(':')[-1]}: {problems[0].detail}",
329
+ list(line.refs),
330
+ "; ".join(f"{p.lcsc} {p.mpn} package {p.package}" for p, _ in conflicts[:5])
331
+ + f"; footprint facts: {fp_facts.describe()}",
332
+ )
333
+ )
334
+
335
+
336
+ def check_parts(
337
+ schematic: Schematic,
338
+ board: Board | None = None,
339
+ *,
340
+ catalog: Catalog | None = None,
341
+ library_pads: bool = True,
342
+ lines_out: list[BomLine] | None = None,
343
+ ) -> tuple[list[Finding], dict]:
344
+ """Findings plus a summary {lines, verified, offline, providers}.
345
+
346
+ ``lines_out`` receives the BOM lines with their lookup reports (for the
347
+ per-line verification report).
348
+ """
349
+ catalog = catalog or default_catalog()
350
+ lines = bom_lines(schematic, board)
351
+ if lines_out is not None:
352
+ lines_out.extend(lines)
353
+ if library_pads:
354
+ for line in lines:
355
+ if line.pads is None and line.footprint:
356
+ line.pads = _library_pads(line.footprint)
357
+ queries = [
358
+ normalize_lcsc(line.lcsc) if is_lcsc_code(line.lcsc) else line.mpn
359
+ for line in lines
360
+ if is_lcsc_code(line.lcsc) or line.mpn
361
+ ]
362
+ reports = catalog.lookup_many(queries)
363
+ findings: list[Finding] = []
364
+ offline_refs: list[str] = []
365
+ malformed: list[str] = []
366
+ missing: list[str] = []
367
+ verified = 0
368
+ basic, preferred, extended = [], [], []
369
+ for line in lines:
370
+ if line.lcsc and not is_lcsc_code(line.lcsc):
371
+ malformed.append(f"{line.label}: {line.lcsc!r}")
372
+ query = normalize_lcsc(line.lcsc) if is_lcsc_code(line.lcsc) else line.mpn
373
+ if not query:
374
+ continue
375
+ report = reports.get(query)
376
+ line.report = report
377
+ if report is None:
378
+ continue
379
+ if report.part is None:
380
+ if report.offline or not report.answered:
381
+ offline_refs.extend(line.refs)
382
+ continue
383
+ verified += 1
384
+ if is_lcsc_code(line.lcsc):
385
+ findings.append(
386
+ Finding(
387
+ "P0",
388
+ "parts.exists",
389
+ f"{line.label}: LCSC {query} does not exist in the JLCPCB/LCSC catalogue",
390
+ list(line.refs),
391
+ f"asked {report.describe()}",
392
+ )
393
+ )
394
+ else:
395
+ missing.append(f"{line.label}: {line.mpn}")
396
+ _infer_from_value(line, catalog, findings)
397
+ continue
398
+ verified += 1
399
+ part = report.part
400
+ line.part = part
401
+ _check_part(line, part, findings)
402
+ if part.lcsc and part.library_type:
403
+ bucket = {"basic": basic, "preferred": preferred}.get(part.library_type, extended)
404
+ bucket.extend(f"{r}={part.lcsc}" for r in line.refs)
405
+ if malformed:
406
+ findings.append(
407
+ Finding(
408
+ "P1",
409
+ "parts.exists",
410
+ "malformed LCSC numbers (expected C followed by digits)",
411
+ evidence="; ".join(malformed[:30]),
412
+ )
413
+ )
414
+ if missing:
415
+ findings.append(
416
+ Finding(
417
+ "P2",
418
+ "parts.exists",
419
+ "MPNs not found in the configured catalogues (check spelling, or configure "
420
+ "Nexar/DigiKey/Mouser keys for non-JLCPCB parts)",
421
+ evidence="; ".join(missing[:30]),
422
+ )
423
+ )
424
+ if offline_refs:
425
+ findings.append(
426
+ Finding(
427
+ "P2",
428
+ "parts.offline",
429
+ "part numbers not verified: offline (no network and no cached catalogue data)",
430
+ sorted(set(offline_refs))[:80],
431
+ )
432
+ )
433
+ if extended:
434
+ findings.append(
435
+ Finding(
436
+ "P3",
437
+ "parts.library_type",
438
+ f"{len(set(e.split('=')[1] for e in extended))} JLCPCB extended part numbers "
439
+ "(each adds a feeder setup fee; basic or preferred parts avoid it)",
440
+ sorted({e.split("=")[0] for e in extended})[:80],
441
+ "extended: " + ", ".join(extended[:40]),
442
+ )
443
+ )
444
+ findings.sort(key=lambda f: f.severity)
445
+ summary = {
446
+ "bom_lines": len(lines),
447
+ "with_part_numbers": len(queries),
448
+ "verified": verified,
449
+ "not_verified_offline": len(set(offline_refs)),
450
+ "basic": len(basic),
451
+ "preferred": len(preferred),
452
+ "extended": len(extended),
453
+ "providers": catalog.provider_names(),
454
+ }
455
+ return findings, summary