copperhead 0.3.0

package/src/kicad/cli.ts

@@ -0,0 +1,106 @@
+import { execa, ExecaError } from 'execa';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { normalizeReport, type CheckReport } from './report.js';
+
+export class KicadCliMissingError extends Error {
+  constructor() {
+    super(
+      'kicad-cli not found on PATH. Install KiCad ≥ 8 (https://www.kicad.org/download/) and ensure kicad-cli is available.',
+    );
+    this.name = 'KicadCliMissingError';
+  }
+}
+
+export async function kicadCliVersion(): Promise<string> {
+  try {
+    const { stdout } = await execa('kicad-cli', ['version']);
+    return stdout.trim();
+  } catch (err) {
+    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
+    throw err;
+  }
+}
+
+async function runCheck(
+  kind: 'erc' | 'drc',
+  filePath: string,
+  extraArgs: string[] = [],
+): Promise<CheckReport> {
+  const dir = await mkdtemp(path.join(tmpdir(), 'copperhead-'));
+  const out = path.join(dir, `${kind}.json`);
+  const sub = kind === 'erc' ? ['sch', 'erc'] : ['pcb', 'drc'];
+  try {
+    await execa(
+      'kicad-cli',
+      [...sub, '--format', 'json', '--exit-code-violations', '--output', out, ...extraArgs, filePath],
+      { reject: false },
+    ).then((res) => {
+      if (res.failed && (res as unknown as ExecaError).code === 'ENOENT') {
+        throw new KicadCliMissingError();
+      }
+    });
+    const raw = JSON.parse(await readFile(out, 'utf8'));
+    return normalizeReport(raw, kind);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+export function runErc(schPath: string): Promise<CheckReport> {
+  return runCheck('erc', schPath);
+}
+
+export function runDrc(pcbPath: string): Promise<CheckReport> {
+  return runCheck('drc', pcbPath);
+}
+
+export interface FabExportResult {
+  produced: string[];
+  failed: { artifact: string; reason: string }[];
+}
+
+/**
+ * Export the fabrication package (SPEC §2.5 outputs): gerbers + drill, DXF and
+ * STEP outline, SVG renders. Each artifact fails independently with a reason so
+ * a missing STEP exporter never sinks the rest of the package.
+ */
+export async function exportFab(pcbPath: string, schPath: string | null, outDir: string): Promise<FabExportResult> {
+  const result: FabExportResult = { produced: [], failed: [] };
+  const jobs: { artifact: string; args: string[] }[] = [
+    { artifact: 'gerbers', args: ['pcb', 'export', 'gerbers', '--output', path.join(outDir, 'gerbers'), pcbPath] },
+    { artifact: 'drill', args: ['pcb', 'export', 'drill', '--output', path.join(outDir, 'gerbers'), pcbPath] },
+    { artifact: 'outline.dxf', args: ['pcb', 'export', 'dxf', '--output', path.join(outDir, 'outline.dxf'), '--layers', 'Edge.Cuts', pcbPath] },
+    { artifact: 'board.step', args: ['pcb', 'export', 'step', '--output', path.join(outDir, 'board.step'), pcbPath] },
+    { artifact: 'board.svg', args: ['pcb', 'export', 'svg', '--output', path.join(outDir, 'board.svg'), '--layers', 'F.Cu,B.Cu,Edge.Cuts', pcbPath] },
+  ];
+  if (schPath) {
+    jobs.push({ artifact: 'schematic.svg', args: ['sch', 'export', 'svg', '--output', path.join(outDir, 'renders'), schPath] });
+  }
+  for (const job of jobs) {
+    try {
+      await execa('kicad-cli', job.args);
+      result.produced.push(job.artifact);
+    } catch (err) {
+      if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
+      result.failed.push({ artifact: job.artifact, reason: String((err as ExecaError).stderr ?? (err as Error).message).slice(0, 200) });
+    }
+  }
+  return result;
+}
+
+/** Export an SVG render of a schematic or board; returns the output directory. */
+export async function exportSvg(kind: 'sch' | 'pcb', filePath: string, outDir: string): Promise<string> {
+  const args =
+    kind === 'sch'
+      ? ['sch', 'export', 'svg', '--output', outDir, filePath]
+      : ['pcb', 'export', 'svg', '--output', path.join(outDir, 'board.svg'), '--layers', 'F.Cu,B.Cu,Edge.Cuts', filePath];
+  try {
+    await execa('kicad-cli', args);
+  } catch (err) {
+    if ((err as ExecaError).code === 'ENOENT') throw new KicadCliMissingError();
+    throw err;
+  }
+  return outDir;
+}

package/src/kicad/report.ts

@@ -0,0 +1,81 @@
+export interface ViolationItem {
+  description: string;
+  x?: number;
+  y?: number;
+}
+
+export interface Violation {
+  severity: 'error' | 'warning' | string;
+  type: string;
+  description: string;
+  sheet?: string;
+  items: ViolationItem[];
+}
+
+export interface CheckReport {
+  ok: boolean;
+  source: 'erc' | 'drc';
+  violations: Violation[];
+}
+
+interface RawItem {
+  description?: string;
+  pos?: { x?: number; y?: number };
+}
+
+interface RawViolation {
+  severity?: string;
+  type?: string;
+  description?: string;
+  items?: RawItem[];
+}
+
+function normViolation(v: RawViolation, sheet?: string): Violation {
+  return {
+    severity: v.severity ?? 'error',
+    type: v.type ?? 'unknown',
+    description: v.description ?? '',
+    ...(sheet !== undefined ? { sheet } : {}),
+    items: (v.items ?? []).map((i) => ({
+      description: i.description ?? '',
+      ...(i.pos?.x !== undefined ? { x: i.pos.x } : {}),
+      ...(i.pos?.y !== undefined ? { y: i.pos.y } : {}),
+    })),
+  };
+}
+
+/**
+ * Normalize kicad-cli ERC and DRC JSON reports into one shape. ERC nests
+ * violations per sheet; DRC has top-level `violations` plus `unconnected_items`
+ * and `schematic_parity`. Tolerant of missing fields across KiCad versions.
+ */
+export function normalizeReport(raw: unknown, source: 'erc' | 'drc'): CheckReport {
+  const r = raw as {
+    sheets?: { path?: string; violations?: RawViolation[] }[];
+    violations?: RawViolation[];
+    unconnected_items?: RawViolation[];
+    schematic_parity?: RawViolation[];
+  };
+  const violations: Violation[] = [];
+  for (const sheet of r.sheets ?? []) {
+    for (const v of sheet.violations ?? []) violations.push(normViolation(v, sheet.path));
+  }
+  for (const v of r.violations ?? []) violations.push(normViolation(v));
+  for (const v of r.unconnected_items ?? []) violations.push(normViolation(v));
+  for (const v of r.schematic_parity ?? []) violations.push(normViolation(v));
+  return { ok: violations.length === 0, source, violations };
+}
+
+export function formatViolations(report: CheckReport): string {
+  if (report.ok) return `${report.source.toUpperCase()}: clean`;
+  const lines = [`${report.source.toUpperCase()}: ${report.violations.length} violation(s)`];
+  for (const v of report.violations) {
+    const where = v.sheet ? ` [sheet ${v.sheet}]` : '';
+    lines.push(`  ${v.severity} ${v.type}${where}: ${v.description}`);
+    for (const i of v.items) {
+      const pos = i.x !== undefined ? ` @ (${i.x}, ${i.y})` : '';
+      lines.push(`    - ${i.description}${pos}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/kicad/sexp.ts

@@ -0,0 +1,327 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Minimal READ-ONLY s-expression tooling for .kicad_sch files. This module
+ * never serializes: edits to KiCad files happen as anchored text replaces on
+ * the original source (SPEC §1.3 / design D4).
+ */
+
+export type SexpNode = string | SexpNode[];
+
+export function parseSexp(text: string): SexpNode[] {
+  const tokens: string[] = [];
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i]!;
+    if (c === '(' || c === ')') {
+      tokens.push(c);
+      i++;
+    } else if (c === '"') {
+      let j = i + 1;
+      let s = '';
+      while (j < text.length && text[j] !== '"') {
+        if (text[j] === '\\' && j + 1 < text.length) {
+          s += text[j + 1];
+          j += 2;
+        } else {
+          s += text[j];
+          j++;
+        }
+      }
+      tokens.push(JSON.stringify(s));
+      i = j + 1;
+    } else if (/\s/.test(c)) {
+      i++;
+    } else {
+      let j = i;
+      while (j < text.length && !/[\s()"]/.test(text[j]!)) j++;
+      tokens.push(text.slice(i, j));
+      i = j;
+    }
+  }
+  let pos = 0;
+  function parseNode(): SexpNode {
+    const tok = tokens[pos++]!;
+    if (tok === '(') {
+      const list: SexpNode[] = [];
+      while (pos < tokens.length && tokens[pos] !== ')') list.push(parseNode());
+      pos++; // consume ')'
+      return list;
+    }
+    return tok.startsWith('"') ? (JSON.parse(tok) as string) : tok;
+  }
+  const roots: SexpNode[] = [];
+  while (pos < tokens.length) roots.push(parseNode());
+  return roots;
+}
+
+export const isList = (n: SexpNode): n is SexpNode[] => Array.isArray(n);
+const tag = (n: SexpNode): string | null => (isList(n) && typeof n[0] === 'string' ? n[0] : null);
+
+export function children(node: SexpNode, name: string): SexpNode[][] {
+  if (!isList(node)) return [];
+  return node.filter((c): c is SexpNode[] => tag(c) === name);
+}
+
+export function child(node: SexpNode, name: string): SexpNode[] | undefined {
+  return children(node, name)[0];
+}
+
+function atomAt(node: SexpNode[] | undefined, idx: number): string | undefined {
+  const v = node?.[idx];
+  return typeof v === 'string' ? v : undefined;
+}
+
+function property(sym: SexpNode[], key: string): string | undefined {
+  for (const p of children(sym, 'property')) {
+    if (atomAt(p, 1) === key) return atomAt(p, 2);
+  }
+  return undefined;
+}
+
+export interface SchematicSymbol {
+  ref: string;
+  value: string;
+  footprint: string;
+  libId: string;
+  sheet: string;
+  at: { x: number; y: number; rot: number };
+  uuid: string;
+}
+
+export interface PinDef {
+  number: string;
+  name: string;
+  x: number;
+  y: number;
+}
+
+interface ParsedSheet {
+  filePath: string;
+  sheetName: string;
+  root: SexpNode[];
+}
+
+async function loadSheets(rootSch: string): Promise<ParsedSheet[]> {
+  const seen = new Set<string>();
+  const out: ParsedSheet[] = [];
+  async function load(file: string, sheetName: string): Promise<void> {
+    const abs = path.resolve(file);
+    if (seen.has(abs)) return;
+    seen.add(abs);
+    const text = await readFile(abs, 'utf8');
+    const root = parseSexp(text)[0];
+    if (root === undefined || !isList(root)) {
+      throw new Error(`not a KiCad s-expression file: ${file}`);
+    }
+    out.push({ filePath: abs, sheetName, root });
+    for (const sheet of children(root, 'sheet')) {
+      const sub = property(sheet, 'Sheetfile') ?? property(sheet, 'Sheet file');
+      const name = property(sheet, 'Sheetname') ?? property(sheet, 'Sheet name') ?? 'sheet';
+      if (sub) await load(path.resolve(path.dirname(abs), sub), name);
+    }
+  }
+  await load(rootSch, '/');
+  return out;
+}
+
+/** Pin definitions per lib symbol name, in symbol coordinates. */
+function libPinDefs(root: SexpNode[]): Map<string, PinDef[]> {
+  const map = new Map<string, PinDef[]>();
+  const libs = child(root, 'lib_symbols');
+  if (!libs) return map;
+  for (const sym of children(libs, 'symbol')) {
+    const name = atomAt(sym, 1);
+    if (!name) continue;
+    const pins: PinDef[] = [];
+    const walk = (n: SexpNode): void => {
+      if (!isList(n)) return;
+      if (tag(n) === 'pin') {
+        const at = child(n, 'at');
+        const num = atomAt(child(n, 'number'), 1);
+        const pinName = atomAt(child(n, 'name'), 1);
+        if (at && num !== undefined) {
+          pins.push({
+            number: num,
+            name: pinName ?? '~',
+            x: parseFloat(atomAt(at, 1) ?? '0'),
+            y: parseFloat(atomAt(at, 2) ?? '0'),
+          });
+        }
+      }
+      for (const c of n) walk(c);
+    };
+    walk(sym);
+    map.set(name, pins);
+  }
+  return map;
+}
+
+/** Symbol-space → schematic-space transform (schematic Y grows downward). */
+export function pinAbsolute(
+  symAt: { x: number; y: number; rot: number },
+  mirror: 'x' | 'y' | null,
+  pin: { x: number; y: number },
+): { x: number; y: number } {
+  let px = pin.x;
+  let py = pin.y;
+  if (mirror === 'y') px = -px;
+  if (mirror === 'x') py = -py;
+  const theta = (symAt.rot * Math.PI) / 180;
+  const rx = px * Math.cos(theta) - py * Math.sin(theta);
+  const ry = px * Math.sin(theta) + py * Math.cos(theta);
+  return { x: round(symAt.x + rx), y: round(symAt.y - ry) };
+}
+
+const round = (n: number): number => Math.round(n * 10000) / 10000;
+const key = (x: number, y: number): string => `${round(x)},${round(y)}`;
+
+class UnionFind {
+  private parent = new Map<string, string>();
+  find(k: string): string {
+    let p = this.parent.get(k);
+    if (p === undefined) {
+      this.parent.set(k, k);
+      return k;
+    }
+    if (p !== k) {
+      p = this.find(p);
+      this.parent.set(k, p);
+    }
+    return p;
+  }
+  union(a: string, b: string): void {
+    this.parent.set(this.find(a), this.find(b));
+  }
+}
+
+function symbolsOf(sheet: ParsedSheet): { node: SexpNode[]; sym: SchematicSymbol; mirror: 'x' | 'y' | null }[] {
+  const out: { node: SexpNode[]; sym: SchematicSymbol; mirror: 'x' | 'y' | null }[] = [];
+  for (const s of children(sheet.root, 'symbol')) {
+    const libId = atomAt(child(s, 'lib_id'), 1);
+    if (!libId) continue; // lib_symbols entries have no lib_id child
+    const at = child(s, 'at');
+    const mirrorAtom = atomAt(child(s, 'mirror'), 1);
+    out.push({
+      node: s,
+      mirror: mirrorAtom === 'x' || mirrorAtom === 'y' ? mirrorAtom : null,
+      sym: {
+        ref: property(s, 'Reference') ?? '?',
+        value: property(s, 'Value') ?? '',
+        footprint: property(s, 'Footprint') ?? '',
+        libId,
+        sheet: sheet.sheetName,
+        at: {
+          x: parseFloat(atomAt(at, 1) ?? '0'),
+          y: parseFloat(atomAt(at, 2) ?? '0'),
+          rot: parseFloat(atomAt(at, 3) ?? '0'),
+        },
+        uuid: atomAt(child(s, 'uuid'), 1) ?? '',
+      },
+    });
+  }
+  return out;
+}
+
+const isPowerSymbol = (libId: string): boolean => libId.startsWith('power:');
+
+/** One row per real component (power symbols excluded), across all sheets. */
+export async function listSymbols(rootSch: string): Promise<SchematicSymbol[]> {
+  const sheets = await loadSheets(rootSch);
+  const out: SchematicSymbol[] = [];
+  for (const sheet of sheets) {
+    for (const { sym } of symbolsOf(sheet)) {
+      if (!isPowerSymbol(sym.libId)) out.push(sym);
+    }
+  }
+  return out.sort((a, b) => a.ref.localeCompare(b.ref, undefined, { numeric: true }));
+}
+
+/** All net names visible via labels and power symbols, across all sheets. */
+export async function listNets(rootSch: string): Promise<string[]> {
+  const sheets = await loadSheets(rootSch);
+  const names = new Set<string>();
+  for (const sheet of sheets) {
+    for (const kind of ['label', 'global_label', 'hierarchical_label']) {
+      for (const l of children(sheet.root, kind)) {
+        const name = atomAt(l, 1);
+        if (name) names.add(name);
+      }
+    }
+    for (const { sym } of symbolsOf(sheet)) {
+      if (isPowerSymbol(sym.libId)) names.add(sym.value);
+    }
+  }
+  return [...names].sort();
+}
+
+export interface PinNet {
+  ref: string;
+  pinNumber: string;
+  pinName: string;
+  net: string | null;
+}
+
+/**
+ * Geometric connectivity per sheet: pins, labels, and wire endpoints that share
+ * coordinates (or are joined by wires) form a group; a group's net name comes
+ * from its labels or power symbols. Good enough for docs scaffolding and drift
+ * checks; not a full netlister.
+ */
+export async function pinNets(rootSch: string): Promise<PinNet[]> {
+  const sheets = await loadSheets(rootSch);
+  const out: PinNet[] = [];
+  for (const sheet of sheets) {
+    const pinDefs = libPinDefs(sheet.root);
+    const uf = new UnionFind();
+    const netNameAt = new Map<string, string>();
+
+    for (const w of children(sheet.root, 'wire')) {
+      const pts = children(child(w, 'pts') ?? [], 'xy').map((xy) => ({
+        x: parseFloat(atomAt(xy, 1) ?? '0'),
+        y: parseFloat(atomAt(xy, 2) ?? '0'),
+      }));
+      for (let i = 1; i < pts.length; i++) {
+        uf.union(key(pts[0]!.x, pts[0]!.y), key(pts[i]!.x, pts[i]!.y));
+      }
+    }
+    for (const kind of ['label', 'global_label', 'hierarchical_label']) {
+      for (const l of children(sheet.root, kind)) {
+        const name = atomAt(l, 1);
+        const at = child(l, 'at');
+        if (!name || !at) continue;
+        const k = key(parseFloat(atomAt(at, 1) ?? '0'), parseFloat(atomAt(at, 2) ?? '0'));
+        uf.find(k);
+        netNameAt.set(k, name);
+      }
+    }
+
+    const symPins: { sym: SchematicSymbol; pin: PinDef; k: string }[] = [];
+    for (const { sym, mirror } of symbolsOf(sheet)) {
+      const defs = pinDefs.get(sym.libId) ?? [];
+      for (const pin of defs) {
+        const abs = pinAbsolute(sym.at, mirror, pin);
+        const k = key(abs.x, abs.y);
+        uf.find(k);
+        if (isPowerSymbol(sym.libId)) {
+          netNameAt.set(k, sym.value);
+        } else {
+          symPins.push({ sym, pin, k });
+        }
+      }
+    }
+
+    const groupNet = new Map<string, string>();
+    for (const [k, name] of netNameAt) groupNet.set(uf.find(k), name);
+    for (const { sym, pin, k } of symPins) {
+      out.push({
+        ref: sym.ref,
+        pinNumber: pin.number,
+        pinName: pin.name,
+        net: groupNet.get(uf.find(k)) ?? null,
+      });
+    }
+  }
+  return out;
+}

package/src/memory/constraints.ts

@@ -0,0 +1,73 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Machine-readable constraint registry (SPEC §2.6). Built simultaneously with
+ * the docs: every stated/assumed/discovered constraint lands in both in the
+ * same tool turn. `affects` drives propagation.
+ */
+export interface Constraint {
+  min?: number;
+  max?: number;
+  forbidden?: string[];
+  value?: string | number;
+  source: string;
+  affects: string[];
+}
+
+export type ConstraintRegistry = Record<string, Constraint>;
+
+export function constraintsPath(repoRoot: string): string {
+  return path.join(repoRoot, '.copperhead', 'constraints.json');
+}
+
+export async function loadConstraints(repoRoot: string): Promise<ConstraintRegistry> {
+  const p = constraintsPath(repoRoot);
+  if (!existsSync(p)) return {};
+  return JSON.parse(await readFile(p, 'utf8')) as ConstraintRegistry;
+}
+
+export async function saveConstraint(
+  repoRoot: string,
+  key: string,
+  constraint: Constraint,
+): Promise<ConstraintRegistry> {
+  const registry = await loadConstraints(repoRoot);
+  registry[key] = constraint;
+  const p = constraintsPath(repoRoot);
+  await mkdir(path.dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(registry, null, 2) + '\n', 'utf8');
+  return registry;
+}
+
+export interface ConstraintViolation {
+  key: string;
+  description: string;
+  source: string;
+}
+
+/**
+ * Mechanical validation where possible (SPEC §2.6): forbidden pins against the
+ * pinout, numeric budget keys surfaced for the doc-level checks. Geometry
+ * checks are out of scope for Phase 1.
+ */
+export function checkForbiddenPins(
+  registry: ConstraintRegistry,
+  pinNets: { ref: string; pinName: string; net: string | null }[],
+): ConstraintViolation[] {
+  const violations: ConstraintViolation[] = [];
+  for (const [key, c] of Object.entries(registry)) {
+    if (!c.forbidden?.length) continue;
+    for (const pn of pinNets) {
+      if (pn.net && c.forbidden.includes(pn.pinName)) {
+        violations.push({
+          key,
+          description: `${pn.ref} pin ${pn.pinName} is connected to net ${pn.net} but is forbidden by ${key}`,
+          source: c.source,
+        });
+      }
+    }
+  }
+  return violations;
+}

package/src/memory/drift.ts

@@ -0,0 +1,97 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { listSymbols, pinNets, type SchematicSymbol } from '../kicad/sexp.js';
+
+/**
+ * Doc-vs-schematic drift check (AC-2.3). BOM.md and PINOUT.md use fixed table
+ * columns (the parseable contract, design D9); free-prose docs are not checked.
+ */
+export interface DriftMismatch {
+  doc: string;
+  claim: string;
+  actual: string;
+}
+
+export interface TableRow {
+  cells: string[];
+}
+
+export function parseMarkdownTables(md: string): TableRow[] {
+  const rows: TableRow[] = [];
+  for (const line of md.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('|')) continue;
+    const cells = t
+      .split('|')
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.every((c) => /^:?-+:?$/.test(c))) continue; // separator row
+    rows.push({ cells });
+  }
+  return rows;
+}
+
+const isHeader = (row: TableRow): boolean =>
+  row.cells.some((c) => /^(refdes|pin)$/i.test(c));
+
+export async function checkDrift(repoRoot: string, docsDir: string, schematic: string): Promise<DriftMismatch[]> {
+  const mismatches: DriftMismatch[] = [];
+  const schPath = path.join(repoRoot, schematic);
+  const symbols = await listSymbols(schPath);
+  const byRef = new Map<string, SchematicSymbol>(symbols.map((s) => [s.ref, s]));
+
+  const bomPath = path.join(repoRoot, docsDir, 'BOM.md');
+  if (existsSync(bomPath)) {
+    const rows = parseMarkdownTables(await readFile(bomPath, 'utf8')).filter((r) => !isHeader(r));
+    const seen = new Set<string>();
+    for (const row of rows) {
+      const [ref, value, footprint] = row.cells;
+      if (!ref) continue;
+      seen.add(ref);
+      const sym = byRef.get(ref);
+      if (!sym) {
+        mismatches.push({ doc: 'BOM.md', claim: `${ref} exists`, actual: `${ref} not in schematic` });
+        continue;
+      }
+      if (value !== undefined && value !== sym.value) {
+        mismatches.push({ doc: 'BOM.md', claim: `${ref} value ${value}`, actual: `${ref} value ${sym.value}` });
+      }
+      if (footprint !== undefined && footprint !== '' && footprint !== sym.footprint) {
+        mismatches.push({
+          doc: 'BOM.md',
+          claim: `${ref} footprint ${footprint}`,
+          actual: `${ref} footprint ${sym.footprint}`,
+        });
+      }
+    }
+    for (const sym of symbols) {
+      if (!seen.has(sym.ref)) {
+        mismatches.push({ doc: 'BOM.md', claim: `${sym.ref} absent`, actual: `${sym.ref} (${sym.value}) in schematic` });
+      }
+    }
+  }
+
+  const pinoutPath = path.join(repoRoot, docsDir, 'PINOUT.md');
+  if (existsSync(pinoutPath)) {
+    const nets = await pinNets(schPath);
+    const netOf = new Map(nets.map((p) => [`${p.ref}:${p.pinNumber}`, p.net]));
+    const rows = parseMarkdownTables(await readFile(pinoutPath, 'utf8')).filter((r) => !isHeader(r));
+    for (const row of rows) {
+      const [ref, pinNumber, , net] = row.cells;
+      if (!ref || !pinNumber) continue;
+      const k = `${ref}:${pinNumber}`;
+      if (!netOf.has(k)) {
+        mismatches.push({ doc: 'PINOUT.md', claim: `${k} exists`, actual: `${k} not in schematic` });
+        continue;
+      }
+      const actual = netOf.get(k) ?? 'NC';
+      const claimed = net === undefined || net === '' ? 'NC' : net;
+      if (claimed !== actual) {
+        mismatches.push({ doc: 'PINOUT.md', claim: `${k} net ${claimed}`, actual: `${k} net ${actual}` });
+      }
+    }
+  }
+
+  return mismatches;
+}