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,508 @@
1
+ """The parts verification report: every BOM line verified, or the design does not ship.
2
+
3
+ ``verify_design(workspace)`` checks each BOM line against live catalogue data
4
+ (existence, package vs footprint, pin count, stock, basic/extended) and its
5
+ datasheet pinout against the symbol and footprint, and writes
6
+ ``.traceforge/reports/parts-verification.md`` and ``.json``. Each line ends as
7
+ ``verified``, ``mismatch`` or ``unverified`` (with the reason); the overall
8
+ verdict is "all parts verified" only when every line is verified. Without
9
+ network or cache a line is "unverified: offline", never silently ok.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import re
16
+ from collections.abc import Callable
17
+ from datetime import UTC, datetime
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ from traceforge import sexpr
22
+ from traceforge.checks import Finding
23
+ from traceforge.parts.catalog import Catalog
24
+ from traceforge.parts.model import is_lcsc_code
25
+ from traceforge.parts.packages import compare, parse_catalog_package, parse_footprint
26
+ from traceforge.parts.pinout import check_pinout
27
+
28
+ REPORT_DIR = ".traceforge/reports"
29
+ REPORT_NAME = "parts-verification"
30
+ ALL_VERIFIED = "all parts verified"
31
+ _MISMATCH_CHECKS = {"parts.package", "parts.exists", "parts.mpn", "parts.value"}
32
+ _MECHANICAL = re.compile(r"MountingHole|Fiducial|TestPoint|NetTie|Logo|Symbol:", re.I)
33
+ _MECH_PAD = re.compile(r"^(?:S|SH|MP|MH|EP|PAD)\d*$", re.I)
34
+
35
+
36
+ def _iso(epoch: float) -> str:
37
+ if not epoch:
38
+ return ""
39
+ return datetime.fromtimestamp(epoch, UTC).isoformat(timespec="seconds")
40
+
41
+
42
+ def symbol_pins(schematic_path: Path) -> dict[str, list[tuple[str, str]]]:
43
+ """lib_id -> [(pin number, pin name)] from the symbols embedded in the schematics."""
44
+ from traceforge.kicad.libraries import _pins
45
+
46
+ out: dict[str, list[tuple[str, str]]] = {}
47
+ files = [schematic_path, *sorted(schematic_path.parent.glob("*.kicad_sch"))]
48
+ for file in dict.fromkeys(files):
49
+ try:
50
+ root = sexpr.parse(file.read_text(encoding="utf-8"))
51
+ except (OSError, ValueError):
52
+ continue
53
+ library = sexpr.find(root, "lib_symbols")
54
+ if library is None:
55
+ continue
56
+ for node in sexpr.find_all(library, "symbol"):
57
+ lib_id = str(node[1])
58
+ if lib_id not in out:
59
+ pins = _pins(node, lib_id)
60
+ out[lib_id] = list(dict.fromkeys((p.number, p.name) for p in pins))
61
+ return out
62
+
63
+
64
+ def _is_mechanical(line) -> bool:
65
+ if line.lcsc or line.mpn:
66
+ return False
67
+ prefix = re.match(r"^[A-Za-z]+", line.refs[0])
68
+ kind = prefix.group(0).upper() if prefix else ""
69
+ return kind in {"H", "MH", "FID", "TP", "NT", "LOGO"} or bool(
70
+ _MECHANICAL.search(line.footprint)
71
+ )
72
+
73
+
74
+ def _catalogue_facts(line) -> dict[str, Any]:
75
+ report, part = line.report, line.part
76
+ facts: dict[str, Any] = {}
77
+ if report is not None:
78
+ facts["query"] = report.query
79
+ facts["attempts"] = [
80
+ {
81
+ "provider": a.provider,
82
+ "outcome": a.outcome,
83
+ **({"detail": a.detail} if a.detail else {}),
84
+ **({"fetched": _iso(a.fetched_at)} if a.fetched_at else {}),
85
+ }
86
+ for a in report.attempts
87
+ ]
88
+ fetched = [a.fetched_at for a in report.attempts if a.fetched_at]
89
+ if fetched:
90
+ facts["fetched"] = _iso(max(fetched))
91
+ if part is not None:
92
+ for key in (
93
+ "lcsc",
94
+ "manufacturer",
95
+ "mpn",
96
+ "description",
97
+ "package",
98
+ "pin_count",
99
+ "stock",
100
+ "library_type",
101
+ "lifecycle",
102
+ "datasheet_url",
103
+ "product_url",
104
+ ):
105
+ value = getattr(part, key)
106
+ if value not in ("", None):
107
+ facts[key] = value
108
+ facts["sources"] = list(part.sources)
109
+ if part.stale:
110
+ facts["stale"] = True
111
+ if not part.product_url and part.lcsc:
112
+ facts["product_url"] = f"https://www.lcsc.com/product-detail/{part.lcsc}.html"
113
+ return facts
114
+
115
+
116
+ def _pad_numbers(line) -> list[str] | None:
117
+ return None if line.pads is None else [n for n, _ in line.pads]
118
+
119
+
120
+ def _verify_line(line, findings: list[Finding], pins_by_lib, folder: Path, llm) -> dict:
121
+ refs = set(line.refs)
122
+ own = [f for f in findings if refs & set(f.refs)]
123
+ entry: dict[str, Any] = {
124
+ "refs": list(line.refs),
125
+ "value": line.value,
126
+ "footprint": line.footprint,
127
+ "lcsc": line.lcsc,
128
+ "mpn": line.mpn,
129
+ "catalogue": _catalogue_facts(line),
130
+ "notes": [],
131
+ }
132
+ mismatches: list[str] = []
133
+ unverified: list[str] = []
134
+ part = line.part
135
+ report = line.report
136
+ if not (line.lcsc or line.mpn):
137
+ unverified.append("no part number (LCSC or MPN field)")
138
+ elif line.lcsc and not is_lcsc_code(line.lcsc) and not line.mpn:
139
+ mismatches.append(f"malformed LCSC number {line.lcsc!r}")
140
+ elif report is None or (report.part is None and (report.offline or not report.answered)):
141
+ unverified.append("offline (no network and no cached catalogue data)")
142
+ elif report.part is None:
143
+ if is_lcsc_code(line.lcsc):
144
+ mismatches.append(f"LCSC {report.query} does not exist in the catalogue")
145
+ else:
146
+ unverified.append(f"MPN {line.mpn} not found in the configured catalogues")
147
+ for finding in own:
148
+ if finding.check in _MISMATCH_CHECKS and finding.severity in {"P0", "P1"}:
149
+ if not (finding.check == "parts.exists" and mismatches):
150
+ mismatches.append(finding.message.split(": ", 1)[-1])
151
+ elif finding.check == "parts.stock" and finding.severity in {"P0", "P1"}:
152
+ unverified.append("out of stock")
153
+ elif finding.check in {"parts.stock", "parts.lifecycle", "parts.package"}:
154
+ entry["notes"].append(finding.message.split(": ", 1)[-1])
155
+ # package vs footprint and pin count, stated per line
156
+ pads = _pad_numbers(line)
157
+ if part is not None:
158
+ if not line.footprint:
159
+ unverified.append("no footprint assigned")
160
+ else:
161
+ cat = parse_catalog_package(
162
+ part.package, description=part.description, attributes=part.attributes
163
+ )
164
+ fp = parse_footprint(line.footprint, line.pads)
165
+ problems = compare(cat, fp, pads=line.pads)
166
+ entry["package"] = {
167
+ "catalogue": part.package,
168
+ "catalogue_facts": cat.describe(),
169
+ "footprint_facts": fp.describe(),
170
+ "result": "; ".join(f"{m.aspect}: {m.detail}" for m in problems) or "ok",
171
+ }
172
+ stem = re.sub(r"[^A-Z0-9]", "", (part.mpn or "").upper())
173
+ named = len(stem) >= 5 and stem in re.sub(r"[^A-Z0-9]", "", line.footprint.upper())
174
+ if named and not problems:
175
+ entry["package"]["result"] = f"ok (footprint is drawn for {part.mpn})"
176
+ elif not (cat.family or cat.chip or cat.pins):
177
+ unverified.append(
178
+ f"catalogue package {part.package!r} states nothing to compare with the footprint"
179
+ )
180
+ signal = {n for n in pads or [] if n and not _MECH_PAD.match(n)}
181
+ entry["pin_count"] = {
182
+ "catalogue": part.pin_count,
183
+ "footprint_pads": len(signal) if pads is not None else None,
184
+ "result": (
185
+ "unknown"
186
+ if part.pin_count is None or pads is None
187
+ else "ok"
188
+ if part.pin_count == len(signal)
189
+ else f"catalogue {part.pin_count} pins, footprint {len(signal)} pads"
190
+ ),
191
+ }
192
+ if part.stale:
193
+ entry["notes"].append("catalogue data from an expired cache entry (network failed)")
194
+ entry["stock"] = part.stock
195
+ entry["library_type"] = part.library_type or "unknown"
196
+ # pinout
197
+ pins = pins_by_lib.get(line.lib_id, [])
198
+ urls = [u for u in (part.datasheet_url if part else "", line.datasheet) if u]
199
+ if not (line.lcsc or line.mpn) and not urls:
200
+ pinout = None
201
+ else:
202
+ pinout = check_pinout(
203
+ ref=line.refs[0],
204
+ footprint=line.footprint,
205
+ symbol_pins=pins,
206
+ pad_numbers=pads,
207
+ datasheet_urls=urls,
208
+ folder=folder,
209
+ description=f"{part.description} {part.category}" if part else "",
210
+ name=f"{part.lcsc}_{part.mpn}" if part else line.value,
211
+ llm=llm,
212
+ )
213
+ if pinout is not None:
214
+ entry["pinout"] = pinout.to_dict() | {"summary": pinout.summary()}
215
+ if pinout.status == "mismatch":
216
+ for issue in pinout.issues:
217
+ mismatches.append(f"pinout: {issue['detail']} [{issue['evidence']}]")
218
+ elif pinout.status == "unverified":
219
+ unverified.append(f"pinout {pinout.reason}")
220
+ if mismatches:
221
+ entry["verdict"] = "mismatch"
222
+ entry["reasons"] = list(dict.fromkeys(mismatches + unverified))
223
+ elif unverified:
224
+ entry["verdict"] = "unverified"
225
+ entry["reasons"] = list(dict.fromkeys(unverified))
226
+ else:
227
+ entry["verdict"] = "verified"
228
+ entry["reasons"] = []
229
+ return entry
230
+
231
+
232
+ def verify_design(
233
+ workspace: Path,
234
+ *,
235
+ catalog: Catalog | None = None,
236
+ llm: Callable[[str], str] | None = None,
237
+ write: bool = True,
238
+ ) -> dict[str, Any]:
239
+ """Verify every BOM line of the workspace's design; write the report files."""
240
+ from traceforge.kicad.pcb import read_board
241
+ from traceforge.kicad.project import discover
242
+ from traceforge.kicad.schematic import read_schematic
243
+ from traceforge.parts.verify import check_parts
244
+
245
+ workspace = Path(workspace)
246
+ ws = discover(workspace)
247
+ started = datetime.now(UTC).isoformat(timespec="seconds")
248
+ if ws.schematic is None:
249
+ data: dict[str, Any] = {
250
+ "schema": "traceforge.parts-verification/v1",
251
+ "workspace": str(workspace),
252
+ "generated": started,
253
+ "verdict": "unverified: no schematic",
254
+ "all_verified": False,
255
+ "lines": [],
256
+ "counts": {},
257
+ }
258
+ if write:
259
+ data["files"] = _write(workspace, data)
260
+ return data
261
+ schematic = read_schematic(ws.schematic)
262
+ board = read_board(ws.pcb) if ws.pcb else None
263
+ lines: list = []
264
+ findings, summary = check_parts(schematic, board, catalog=catalog, lines_out=lines)
265
+ pins_by_lib = symbol_pins(ws.schematic)
266
+ folder = workspace / ".traceforge" / "datasheets"
267
+ entries, excluded = [], []
268
+ for line in lines:
269
+ if _is_mechanical(line):
270
+ excluded.append({"refs": line.refs, "footprint": line.footprint})
271
+ continue
272
+ entries.append(_verify_line(line, findings, pins_by_lib, folder, llm))
273
+ counts = {
274
+ k: sum(e["verdict"] == k for e in entries) for k in ("verified", "mismatch", "unverified")
275
+ }
276
+ all_ok = bool(entries) and counts["verified"] == len(entries)
277
+ if all_ok:
278
+ verdict = ALL_VERIFIED
279
+ elif not entries:
280
+ verdict = "unverified: no BOM lines"
281
+ else:
282
+ bad = [f"{counts['mismatch']} mismatch"] if counts["mismatch"] else []
283
+ bad += [f"{counts['unverified']} unverified"] if counts["unverified"] else []
284
+ verdict = f"NOT verified: {', '.join(bad)} of {len(entries)} BOM lines"
285
+ data = {
286
+ "schema": "traceforge.parts-verification/v1",
287
+ "workspace": str(workspace),
288
+ "schematic": str(ws.schematic),
289
+ "pcb": str(ws.pcb) if ws.pcb else "",
290
+ "generated": started,
291
+ "verdict": verdict,
292
+ "all_verified": all_ok,
293
+ "counts": counts,
294
+ "providers": summary.get("providers", []),
295
+ "lines": entries,
296
+ "excluded": excluded,
297
+ }
298
+ if write:
299
+ data["files"] = _write(workspace, data)
300
+ return data
301
+
302
+
303
+ def report_findings(data: dict[str, Any]) -> list[Finding]:
304
+ """Gate findings: P0 per mismatched line, P1 per unverified line."""
305
+ findings = []
306
+ for entry in data.get("lines", []):
307
+ label = ", ".join(entry["refs"][:8])
308
+ part = entry.get("lcsc") or entry.get("mpn") or entry.get("value")
309
+ if entry["verdict"] == "mismatch":
310
+ findings.append(
311
+ Finding(
312
+ "P0",
313
+ "parts.verified",
314
+ f"{label}: {part} mismatch: " + "; ".join(entry["reasons"][:4]),
315
+ list(entry["refs"]),
316
+ _evidence(entry),
317
+ action="pick a part that matches, or fix the symbol/footprint",
318
+ )
319
+ )
320
+ elif entry["verdict"] == "unverified":
321
+ findings.append(
322
+ Finding(
323
+ "P1",
324
+ "parts.verified",
325
+ f"{label}: {part} unverified: " + "; ".join(entry["reasons"][:3]),
326
+ list(entry["refs"]),
327
+ _evidence(entry),
328
+ action="verify the part (network, part number, datasheet) before release",
329
+ )
330
+ )
331
+ if not data.get("lines") and not data.get("all_verified"):
332
+ findings.append(Finding("P1", "parts.verified", f"parts {data.get('verdict')}"))
333
+ return findings
334
+
335
+
336
+ def _evidence(entry: dict) -> str:
337
+ cat = entry.get("catalogue", {})
338
+ bits = [
339
+ f"{cat.get('lcsc') or entry.get('lcsc') or '-'} = "
340
+ f"{cat.get('manufacturer', '')} {cat.get('mpn', '')}".strip()
341
+ ]
342
+ if cat.get("product_url"):
343
+ bits.append(cat["product_url"])
344
+ if cat.get("fetched"):
345
+ bits.append(f"fetched {cat['fetched']}")
346
+ pin = entry.get("pinout") or {}
347
+ if pin.get("evidence"):
348
+ bits.append(f"pinout: {pin['evidence']}")
349
+ return "; ".join(bits)
350
+
351
+
352
+ def _write(workspace: Path, data: dict[str, Any]) -> dict[str, str]:
353
+ folder = workspace / REPORT_DIR
354
+ folder.mkdir(parents=True, exist_ok=True)
355
+ json_path = folder / f"{REPORT_NAME}.json"
356
+ md_path = folder / f"{REPORT_NAME}.md"
357
+ files = {"json": str(json_path), "markdown": str(md_path)}
358
+ json_path.write_text(json.dumps({**data, "files": files}, indent=1, default=str), "utf-8")
359
+ md_path.write_text(markdown(data), encoding="utf-8")
360
+ return files
361
+
362
+
363
+ def _cell(text: Any) -> str:
364
+ return str(text if text not in (None, "") else "-").replace("|", "\\|").replace("\n", " ")
365
+
366
+
367
+ def markdown(data: dict[str, Any]) -> str:
368
+ counts = data.get("counts", {})
369
+ out = [
370
+ "# Parts verification",
371
+ "",
372
+ f"**Verdict: {data['verdict']}**",
373
+ "",
374
+ f"- Workspace: `{data['workspace']}`",
375
+ f"- Generated: {data['generated']}",
376
+ f"- Lines: {counts.get('verified', 0)} verified, {counts.get('mismatch', 0)} mismatch, "
377
+ f"{counts.get('unverified', 0)} unverified",
378
+ f"- Catalogues: {', '.join(data.get('providers', [])) or '-'}",
379
+ "",
380
+ "| Refs | Part | Manufacturer / MPN | Package vs footprint | Pins | Pinout | Stock / type "
381
+ "| Verdict |",
382
+ "|---|---|---|---|---|---|---|---|",
383
+ ]
384
+ for e in data.get("lines", []):
385
+ cat = e.get("catalogue", {})
386
+ pkg = e.get("package", {})
387
+ pins = e.get("pin_count", {})
388
+ pin = e.get("pinout", {})
389
+ verdict = e["verdict"] + (f": {'; '.join(e['reasons'])}" if e.get("reasons") else "")
390
+ out.append(
391
+ "| "
392
+ + " | ".join(
393
+ _cell(x)
394
+ for x in (
395
+ ", ".join(e["refs"]),
396
+ e.get("lcsc") or e.get("mpn"),
397
+ f"{cat.get('manufacturer', '')} {cat.get('mpn', '')}".strip(),
398
+ f"{pkg.get('catalogue', '')} vs {e['footprint'].split(':')[-1]}: "
399
+ f"{pkg.get('result', '-')}"
400
+ if pkg
401
+ else e["footprint"].split(":")[-1],
402
+ pins.get("result"),
403
+ pin.get("summary"),
404
+ f"{e.get('stock', '-')} / {e.get('library_type', '-')}",
405
+ verdict,
406
+ )
407
+ )
408
+ + " |"
409
+ )
410
+ out += ["", "## Catalogue facts used", ""]
411
+ for e in data.get("lines", []):
412
+ cat = e.get("catalogue", {})
413
+ src = cat.get("product_url") or ", ".join(cat.get("sources", [])) or "-"
414
+ attempts = ", ".join(f"{a['provider']}: {a['outcome']}" for a in cat.get("attempts", []))
415
+ line = (
416
+ f"- **{', '.join(e['refs'])}** {cat.get('lcsc', e.get('lcsc') or '')} "
417
+ f"{cat.get('mpn', '')}: package {cat.get('package', '-')}, "
418
+ f"{cat.get('pin_count', '-')} pins, stock {cat.get('stock', '-')}, "
419
+ f"{cat.get('library_type', '-')}; source {src}; fetched {cat.get('fetched', '-')}"
420
+ f" ({attempts or 'no lookup'})"
421
+ )
422
+ if cat.get("datasheet_url"):
423
+ line += f"; datasheet {cat['datasheet_url']}"
424
+ pin = e.get("pinout", {})
425
+ if pin.get("evidence"):
426
+ line += f"; pinout evidence: {pin['evidence']}"
427
+ for issue in pin.get("issues", [])[:12]:
428
+ line += f"\n - pinout: {issue['detail']} ({issue['evidence']})"
429
+ for note in e.get("notes", []):
430
+ line += f"\n - note: {note}"
431
+ out.append(line)
432
+ if data.get("excluded"):
433
+ out += [
434
+ "",
435
+ "Not purchased parts (excluded): "
436
+ + ", ".join(r for x in data["excluded"] for r in x["refs"]),
437
+ ]
438
+ return "\n".join(out) + "\n"
439
+
440
+
441
+ def main(args) -> int:
442
+ """`traceforge verify`: exit 0 only when every part is verified."""
443
+ import os
444
+
445
+ if args.offline:
446
+ os.environ["TRACEFORGE_OFFLINE"] = "1"
447
+ workspace = Path(getattr(args, "path", None) or getattr(args, "workspace", ".")).resolve()
448
+ llm = None
449
+ if args.pinout_model:
450
+ from traceforge.parts.pinout import model_extractor
451
+
452
+ llm = model_extractor(workspace)
453
+ data = verify_design(workspace, llm=llm)
454
+ if args.json:
455
+ print(json.dumps(data, indent=1, default=str))
456
+ else:
457
+ for entry in data["lines"]:
458
+ reasons = f": {'; '.join(entry['reasons'])}" if entry["reasons"] else ""
459
+ part = entry.get("lcsc") or entry.get("mpn") or "-"
460
+ print(f"{entry['verdict']:<10} {', '.join(entry['refs'])} {part}{reasons}")
461
+ print(f"\n{data['verdict']}")
462
+ for path in data.get("files", {}).values():
463
+ print(f" {path}")
464
+ return 0 if data["all_verified"] else 1
465
+
466
+
467
+ def brief(data: dict[str, Any]) -> dict[str, Any]:
468
+ """The verdict and the lines that are not verified (for tool results and notices)."""
469
+ problems = [
470
+ {
471
+ "refs": e["refs"],
472
+ "part": e.get("lcsc") or e.get("mpn") or e.get("value"),
473
+ "verdict": e["verdict"],
474
+ "reasons": e["reasons"][:4],
475
+ }
476
+ for e in data.get("lines", [])
477
+ if e["verdict"] != "verified"
478
+ ]
479
+ out: dict[str, Any] = {
480
+ "verdict": data["verdict"],
481
+ "all_verified": data["all_verified"],
482
+ "counts": data.get("counts", {}),
483
+ "report": data.get("files", {}).get("markdown", ""),
484
+ }
485
+ if problems:
486
+ out["not_verified"] = problems
487
+ out["gate"] = (
488
+ "The design is NOT finished: do not report it as done or ready for fabrication "
489
+ "until every part is verified (fix mismatches; resolve unverified parts)."
490
+ )
491
+ return out
492
+
493
+
494
+ def gate_text(data: dict[str, Any]) -> str:
495
+ """One paragraph for the end of an agent turn."""
496
+ if data["all_verified"]:
497
+ return f"Parts verification: {ALL_VERIFIED} ({data.get('files', {}).get('markdown', '')})."
498
+ lines = [
499
+ f"- {', '.join(e['refs'])} {e.get('lcsc') or e.get('mpn') or ''}: {e['verdict']}"
500
+ + (f" ({'; '.join(e['reasons'][:2])})" if e["reasons"] else "")
501
+ for e in data.get("lines", [])
502
+ if e["verdict"] != "verified"
503
+ ]
504
+ return (
505
+ f"Parts verification: {data['verdict']}. The design is not finished until every part "
506
+ f"is verified (report: {data.get('files', {}).get('markdown', '')}).\n"
507
+ + "\n".join(lines[:20])
508
+ )