shibosoftwaredev/f1c100s-linux-nema17-stepper-controller

scripts/write-full-board-review.mjs

import fs from "node:fs"
import crypto from "node:crypto"

const read = path => JSON.parse(fs.readFileSync(path, "utf8"))
const circuitPath = "dist/index/circuit.json"
const circuitSha256 = crypto.createHash("sha256").update(fs.readFileSync(circuitPath)).digest("hex")
const bom = read("reports/bom-value-review.json")
const dfm = read("reports/additional-dfm-review.json")
const comparison = read("reports/published-comparison/regression-summary.json")
const drill = read("reports/published-comparison/reports/drill-clearance-regression.json")
const promotion = read("reports/current-sensing-promotion.json")
const findings = [
  { priority: "P1", id: "ethernet-termination-bom", certainty: "confirmed", inherited: true,
    title: "Four 49.9 ohm Ethernet terminations select 47 kohm parts",
    evidence: "R_ETH_TXN/TXP/RXN/RXP have resistance=49.9 but code C25792 selects 0402WGF4702TCE, 47000 ohm.",
    impact: "An assembly following the selected part codes does not implement the W5500 termination circuit; Ethernet cannot be signed off.",
    location: "ethernet.tsx:178", source: "https://jlcpcb.com/partdetail/C25792",
    action: "Select verified 49.9 ohm 0402 parts, assert catalog value/package against the design and re-audit BOM/CPL." },
  { priority: "P1", id: "current-reference-bom", certainty: "confirmed", inherited: true,
    title: "The motor-current reference selects 105 kohm instead of 9.1 kohm",
    evidence: "R_REF_TOP specifies 9100 ohm with C25742; JLCPCB selects 0402WGF1053TCE, 105000 ohm.",
    impact: "Nominal DRV8825 current limit would be about 0.041 A rather than 0.396 A with a 3.3 V reference, 2 kohm bottom resistor and 0.3 ohm regulation shunts.",
    location: "motor-stage.tsx:75", source: "https://jlcpcb.com/partdetail/C25742",
    action: "Correct the catalog selection without changing the intended divider; verify VREF and both current presets on first article." },
  { priority: "P1", id: "ethernet-ac-capacitor-bom", certainty: "confirmed", inherited: true,
    title: "Ethernet RX coupling capacitors select the wrong value and package",
    evidence: "C_ETH_RXN_AC/RXP_AC specify 6.8 nF, 50 V, footprint 0402. C1590 is CL10B104KA8NNNC, 100 nF, 25 V, 0603.",
    impact: "Both electrical BOM and assembly package disagree with the design.",
    location: "electrical-corrections.tsx:42", source: "https://jlcpcb.com/partdetail/CL10B104KA8NNNC/C1590",
    action: "Select correct 6.8 nF, appropriately rated 0402 parts and validate actual footprint dimensions." },
  { priority: "P1", id: "motor-transient-rating", certainty: "confirmed rating-coordination gap; no transient failure measured", inherited: true,
    title: "The motor bulk capacitor is not rated for the TVS's clamp envelope",
    evidence: "C_VM_BULK EEFCX1E220R is rated 25 V. D_VM_TVS SMBJ22CAQ is specified up to 35.5 V at rated peak pulse current. Both are across VMOTOR.",
    impact: "The TVS does not guarantee keeping the bulk capacitor below its voltage rating during regenerative or other transient conditions. Normal 15 V operation is not itself an overvoltage.",
    location: "motor-stage.tsx:37", sources: ["https://industrial.panasonic.com/ww/products/pt/sp-cap/models/EEFCX1E220R", "https://www.diodes.com/part/view/SMBJ22CAQ"],
    action: "Coordinate capacitor rating and transient clamp/energy margins, then test worst-case back-EMF and hot-plug transients." },
  { priority: "P1", id: "via-drill-clearance", certainty: "confirmed geometric rule failures", inherited: true,
    title: "Independent via-drill-to-foreign-copper DFM still fails",
    evidence: `${drill.currentFindings} deduplicated net/layer sites versus ${drill.baselineFindings} on v0.4.46; zero added sites. Minimum approximately 0.175 mm versus the published 0.20 mm requirement.`,
    source: "https://jlcpcb.com/capabilities/pcb-capabilities",
    artifact: "reports/published-comparison/reports/drill-clearance-regression.json",
    action: "Move affected via/foreign trace geometry with a manufacturing margin; retain 0.30/0.45 mm full-stack vias and rerun all-layer DRC, continuity and shorts." },
  { priority: "P1", id: "manufacturing-gate-and-stale-output", certainty: "confirmed workflow defect", inherited: "gate defect inherited; stale 183-part outputs predate 193-part current revision",
    title: "Manufacturing export does not enforce the known blockers",
    evidence: "export-assembly.py accepts native errors=0, via geometry, in-stock records and continuity, but not independent drill clearance, BOM value/package correctness or fabricationReady. The local fabrication audit has a different circuit hash and 183 parts, not 193.",
    location: "scripts/export-assembly.py:23",
    action: "Add independent DFM/BOM signoff gates before any cleanup/export; preserve previous outputs until the new package is verified; regenerate and hash-match Gerbers, drill, BOM and CPL after repairs." },
  { priority: "P2", id: "ethernet-signal-integrity", certainty: "layout-guideline deviation / qualification risk, not a measured link failure", inherited: true,
    title: "Ethernet MDI routing needs a controlled-impedance paired review",
    evidence: "Emitted TXN/TXP source routes are approximately 18.34/19.48 mm, one via each. RXN chip-to-cap and cap-to-jack source routes total about 31.70 mm with 3+2 vias; RXP totals 35.44 mm with 2+1 vias and different layer usage. No selected dielectric stackup or impedance calculation is supplied.",
    source: "https://docs.wiznet.io/Design-Guide/hardware_design_guide",
    action: "Route RX/TX as short paired paths using the actual four-layer stackup, maintain the reference return, minimize layer transitions and verify link/EMI performance. Metrics are deduplicated source-route copper, not a field-solver result." },
  { priority: "P2", id: "current-analog-routing", certainty: "confirmed routing detours; noise impact unmeasured", inherited: false,
    title: "New current telemetry has unnecessary analog routing exposure",
    evidence: "CURRENT_A_OUTPUT is approximately 86.72 mm/5 vias; B is 8.06 mm/2 vias. MOTION_DIR increased from 43.78 mm/3 vias to 99.11 mm/9 vias. Four Kelvin checks pass, so this is not a disconnected-sense claim.",
    artifact: "reports/published-comparison/regression-summary.json",
    source: "https://www.ti.com/lit/ds/symlink/ina241b.pdf",
    action: "Shorten and protect the analog path and its return, improve local bypass loops where possible, then characterize PWM settling, offset/gain and sampling aliasing. Do not label nominal samples calibrated RMS or use them as independent protection." },
  { priority: "P2", id: "rear-mount-and-harness", certainty: "unresolved physical/procurement interface", inherited: true,
    title: "Rear fastening and the actual motor cable are not yet build-qualified",
    evidence: "PCB-side 31 mm pattern and four 3.5 mm holes accept nominal 5.5 mm M3 heads without washers. Manufacturer drawing specifies the shaft-side M3 flange, not a qualified rear thread/bolt-length interface. It identifies motor connector HX25402-4Y, while J_MOTOR is 2 mm JST-PH. Assembly model does not establish compatibility.",
    source: "https://files.omc-stepperonline.com/17HS13-0404S1_Full_Datasheet.pdf",
    action: "Measure the actual rear fasteners and motor/spacer/PCB stack, verify driver/connector clearance, and specify a pinned adapter harness or correctly spliced PH pigtail. Do not promise reuse of original screw lengths or direct plug-in compatibility." },
  { priority: "P2", id: "additional-pad-dfm", certainty: "confirmed geometric gap below published SMD-pad rule", inherited: true,
    title: "Two exposed debug-pad gaps are below the published 0.15 mm rule",
    evidence: "PE7-to-PE6 and PE6-to-PE5 top pad clearances are approximately 0.115745 and 0.115612 mm. Additional PTH-to-foreign-track and PTH-to-PTH checks found no failures under the stated review scope.",
    artifact: "reports/additional-dfm-review.json", source: "https://jlcpcb.com/capabilities/pcb-capabilities",
    action: "Increase gaps or obtain explicit production CAM acceptance; do not silently waive the difference using the native 0.10 mm setting." },
  { priority: "P2", id: "silkscreen", certainty: "visually confirmed", inherited: "mostly inherited; current inline-shunt labels add out-of-board text",
    title: "Silkscreen is crowded and some labels are outside the outline",
    evidence: `${dfm.silkscreenBelowPublished1mmHeight} of ${dfm.silkscreenTextCount} text records are under JLCPCB's published 1 mm character height; rendered faces also show overlapping labels and R_INLINE_A/B outside the board.`,
    artifacts: ["reports/current-pcb-top.png", "reports/current-pcb-bottom.png"],
    source: "https://jlcpcb.com/capabilities/pcb-capabilities",
    action: "Remove unnecessary dense refdes text, keep all required markings inside the outline and clear of mask openings, and prioritize legible pin-1, polarity and service labels." },
  { priority: "P2", id: "test-and-warning-coverage", certainty: "confirmed", inherited: "26 module failures inherited; 12 warnings added",
    title: "The complete verification set is not green",
    evidence: "Native 0 errors/187 warnings versus 175 before. The reusable module suite has 6 passes and 26 failures on both revisions. Carrier continuity, shorts, Kelvin and host firmware/client tests pass, but do not waive failures elsewhere. Stock-only checks failed to detect the confirmed incorrect values.",
    artifacts: ["reports/module-test-regression.json", "reports/published-comparison/regression-summary.json", "reports/bom-value-review.json"],
    action: "Repair or correctly separate the module-profile tests, classify warnings without blanket suppression, and make the catalog-to-design value/package assertions mandatory." },
  { priority: "P2", id: "hardware-and-linux-bringup", certainty: "not performed / missing product qualification", inherited: true,
    title: "Power, Linux image and safety firmware still need physical qualification",
    evidence: "carrier.dtsi is explicitly a fragment, not a complete bootable image. No physical PD cold-start/fallback, Linux boot/Ethernet, ROM reflash, watchdog, current accuracy, thermal or transient measurements have been performed. The selected 1.2 V LDO is rated 500 mA, so actual core-load/thermal margin must be measured.",
    artifacts: ["hardware-validation.md", "firmware/carrier.dtsi", "firmware/stm32/README.md"],
    action: "After design/DFM fixes, prepare a reproducible image and execute the staged first-article acceptance record with the specified motor and supply. Hardware qualification is distinct from fabrication DFM." },
  { priority: "P3", id: "minor-pullup-and-release-text", certainty: "confirmed mismatch / stale text", inherited: true,
    title: "Clean up the small pull-up mismatch and historical release wording",
    evidence: "R_PD_GOOD_PU says 49.9 kohm but C25794 is 51 kohm; this is a small bias difference, unlike the Ethernet/reference errors. The promoted release's immutable README still calls itself non-latest/unpushed.",
    source: "https://jlcpcb.com/partdetail/0402WGF5102TCE/C25794",
    action: "Reconcile the pull-up value and documentation deliberately; update release wording in the next corrected publication without treating a label change as hardware signoff." },
]
const report = { reviewedAt: new Date().toISOString(), promotion,
  releaseVersion: promotion.version, localCircuit: { path: circuitPath, sha256: circuitSha256 },
  publishedCircuitSha256: comparison.inputs.releases.checkpoint.downloaded.find(e => e.path === "dist/index/circuit.json").sha256,
  publishedCopperMatchesLocallyAuditedCopper: comparison.publishedCopperMatchesLocallyAuditedCopper,
  verdict: "Development latest promoted as requested; NOT FABRICATION READY. Repair the confirmed BOM, rating and DFM blockers before manufacture.",
  fabricationReady: false, electricalOrRoutingChangesDuringReview: false,
  findings,
  preserved: { outlineMm: [42.3, 42.3], layers: 4, mountingHoles: 4,
    throughVias: 335, viaHoleMm: .3, viaPadMm: .45, blindOrBuriedVias: 0,
    sameEdgeUsb: true, topSideDriver: true, linuxAndMotionMcu: true, ethernet: true,
    pdVoltageAdcAndReadablePowerStatus: true, bothCoilTelemetryChannels: true,
    ledTemperatureAndBuzzer: true, original220PartsAnd209ProjectedNetsPreserved: true },
  passingChecks: ["normal build and cloud build", "native zero error records (not zero warnings)",
    "all-layer Gerber shorts", "emitted-copper continuity", "four Kelvin land-removal checks",
    "CLI schematic placement", "TypeScript", "host C sanitizer tests", "six Linux client tests", "ARM cross-build"],
  limitations: ["No fabricated hardware or oscilloscope measurements", "No fresh cloud AI schematic style analysis",
    "No complete production CAM/stackup/impedance solver or exact rear motor/harness fit qualification",
    "Inventory audit is point-in-time and does not reserve stock; nominal value decode is not full voltage/power/package signoff"] }
fs.writeFileSync("reports/full-board-review.json", JSON.stringify(report, null, 2) + "\n")
console.log(JSON.stringify({ verdict: report.verdict, findings: findings.length,
  bomMismatches: bom.mismatchCount, independentDrillFindings: drill.currentFindings,
  additionalDfm: dfm.counts, latestVerified: promotion.latestVerified }))