copperhead 0.5.0 → 0.6.0

package/src/kicad/fab.ts

@@ -0,0 +1,121 @@
+/**
+ * Fab release gate checks (OpenSpec: add-fab-release-gate).
+ * Documentation presence is pure over file contents: LLM-free, network-free.
+ */
+
+/** Violation shape shared by the fab JSON report (`claim` / `actual` / optional location). */
+export interface FabViolation {
+  claim: string;
+  actual: string;
+  location?: string;
+}
+
+export interface FabCheckResult {
+  status: 'pass' | 'warn' | 'fail';
+  violations: FabViolation[];
+}
+
+export const DRAFT_QUALITY_HEADING = '## Draft quality';
+
+/** Config marker: repos produced by `copperhead create` set `origin` to `"create"`. */
+export const CREATE_ORIGIN = 'create';
+
+/**
+ * True when `.copperhead/config.json` marks the repo as create-produced.
+ * Accepts the raw parsed object (or a loaded config that retained `origin`).
+ */
+export function isCreateProducedRepo(config: unknown): boolean {
+  if (config === null || typeof config !== 'object') return false;
+  return (config as { origin?: unknown }).origin === CREATE_ORIGIN;
+}
+
+/**
+ * Body of `## Draft quality` through the next `##` heading, or `null` if the
+ * heading is absent. HTML comments and whitespace alone do not count as filled
+ * (init scaffolds the empty heading + a placeholder comment).
+ */
+export function draftQualitySection(layoutMd: string): string | null {
+  const lines = layoutMd.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]!.trim() === DRAFT_QUALITY_HEADING) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start < 0) return null;
+
+  const body: string[] = [];
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^##\s/.test(line.trim())) break;
+    body.push(line);
+  }
+  return body.join('\n');
+}
+
+export function isFilledDraftQuality(sectionBody: string): boolean {
+  const withoutComments = sectionBody.replace(/<!--[\s\S]*?-->/g, '');
+  return withoutComments.trim().length > 0;
+}
+
+export interface DocumentationPresenceInput {
+  /** Full LAYOUT.md text, or `null` when the file is missing. */
+  layoutMd: string | null;
+  /** Whether docs/DEVPLAN.md exists on disk. */
+  devplanExists: boolean;
+  /** From {@link isCreateProducedRepo}; only create repos require DEVPLAN.md. */
+  isCreateRepo: boolean;
+  /** Docs directory name used in violation locations (default `docs`). */
+  docsDir?: string;
+}
+
+/**
+ * Documentation-presence check for `check --fab` (task 1.5):
+ * - LAYOUT.md must have a filled `## Draft quality` section
+ * - create-produced repos must also have DEVPLAN.md
+ *
+ * Failures use the drift-report voice: file as location, claim `"release-ready"`.
+ */
+export function checkDocumentationPresence(input: DocumentationPresenceInput): FabCheckResult {
+  const docs = (input.docsDir ?? 'docs').replace(/[/\\]+$/, '');
+  const violations: FabViolation[] = [];
+  const layoutLoc = `${docs}/LAYOUT.md`;
+  const claim = 'release-ready';
+
+  if (input.layoutMd === null) {
+    violations.push({
+      claim,
+      actual: 'LAYOUT.md missing',
+      location: layoutLoc,
+    });
+  } else {
+    const section = draftQualitySection(input.layoutMd);
+    if (section === null) {
+      violations.push({
+        claim,
+        actual: `missing ${DRAFT_QUALITY_HEADING} section`,
+        location: layoutLoc,
+      });
+    } else if (!isFilledDraftQuality(section)) {
+      violations.push({
+        claim,
+        actual: `${DRAFT_QUALITY_HEADING} section is empty`,
+        location: layoutLoc,
+      });
+    }
+  }
+
+  if (input.isCreateRepo && !input.devplanExists) {
+    violations.push({
+      claim,
+      actual: 'missing',
+      location: `${docs}/DEVPLAN.md`,
+    });
+  }
+
+  return {
+    status: violations.length === 0 ? 'pass' : 'fail',
+    violations,
+  };
+}

package/src/memory/bom-table.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared markdown-table parsing for BOM.md and PINOUT.md (design D9's
+ * fixed-column contract). Originally lived inline in drift.ts; pulled out so
+ * the supplier BOM export work (add-supplier-bom-export) can parse BOM.md
+ * once, the same way, instead of duplicating this.
+ */
+
+export interface TableRow {
+    cells: string[];
+  }
+  
+  /**
+   * Parses every markdown pipe-table row out of a document, across however
+   * many tables the file contains, skipping separator rows (e.g. `|---|---|`).
+   * Malformed lines (stray `|` outside a real table) just become a row with
+   * whatever cells they split into — this function never throws.
+   */
+  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;
+  }
+  
+  /** True for a table's header row. BOM.md and PINOUT.md both lead with a
+   * Refdes or Pin column, so one check covers both doc types. */
+  export const isHeader = (row: TableRow): boolean =>
+    row.cells.some((c) => /^(refdes|pin)$/i.test(c));
+  
+  /**
+   * A typed BOM.md data row, per the fixed column contract that `init` writes
+   * (Refdes | Value | Footprint | MPN | Rationale — see scaffold.ts's
+   * `bomTable`). `flags` currently only ever contains `UNVERIFIED` (the MPN
+   * column literally says so) or `MISSING_MPN` (no MPN column value at all);
+   * more may be added as the export/fab-gate work grows.
+   */
+  export interface BomRow {
+    refdes: string;
+    value?: string;
+    footprint?: string;
+    mpn?: string;
+    flags: string[];
+  }
+  
+  /**
+   * Parses BOM.md's data rows into typed rows. Rows without a refdes in
+   * column 1 are dropped rather than thrown on: a hand-edited doc with a
+   * ragged or partial table shouldn't crash `check` or `export bom`, it
+   * should just be skipped (drift/export callers report the gaps that
+   * matter through their own comparisons against the schematic).
+   */
+  export function parseBomTable(md: string): BomRow[] {
+    const rows = parseMarkdownTables(md).filter((r) => !isHeader(r));
+    const out: BomRow[] = [];
+    for (const row of rows) {
+      const [refdes, value, footprint, mpn] = row.cells;
+      if (!refdes) continue;
+      const flags: string[] = [];
+      if (mpn === 'UNVERIFIED') flags.push('UNVERIFIED');
+      else if (!mpn) flags.push('MISSING_MPN');
+      out.push({
+        refdes,
+        value: value || undefined,
+        footprint: footprint || undefined,
+        mpn: mpn || undefined,
+        flags,
+      });
+    }
+    return out;
+  }

package/src/memory/drift.ts

@@ -2,6 +2,7 @@ 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';
+import { parseMarkdownTables, isHeader } from './bom-table.js';
 
 /**
  * Doc-vs-schematic drift check (AC-2.3). BOM.md and PINOUT.md use fixed table
@@ -13,28 +14,6 @@ export interface DriftMismatch {
   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));
-
 /**
  * The zero-symbol carve-out in checkDrift is right for the create pipeline,
  * but it would let `check` silently pass an established repo whose schematic