@protoboardai/ext-release 0.0.0-stage → 0.2.1

package/lib/sections/bom.ts

@@ -0,0 +1,101 @@
+/**
+ * The bill-of-materials section (PK2): the unit's module breakdown as
+ * bom.pdf and bom.csv, and for the root unit the whole product's ordering
+ * list (ordering-list.csv) with its quantity rule and cost coverage.
+ */
+import { orderingCsv, orderingList, orderTotals, SPARE_DEFAULTS, unitBom, unitBomCsv, type OrderLine } from "../bom.ts";
+import { readFx } from "@protoboardai/ext-sourcing/lib/cost.ts";
+import type { Block, SectionContext, SectionContribution } from "../types.ts";
+import { num } from "../util.ts";
+
+const ACTION: Record<string, string> = { build: "build", fabricate: "make", buy: "buy", included: "included" };
+
+export function sectionBom({ project: p, unit: u, units, release }: SectionContext): SectionContribution[] {
+  const rows = unitBom(p, u);
+  const indent = (level: number, text: string) => `${"· ".repeat(level)}${text}`;
+  const breakdown: Block[] = [
+    {
+      kind: "paragraph",
+      text: `One build of ${u.name}, in the order of its module tree (sub-assembly → board → components). Quantities are per build; ${u.kind === "root" ? "the product is built once per order" : `the product needs ${u.perProduct}`}. The same rows are in bom.csv, keyed by instance path.`,
+    },
+    {
+      kind: "table",
+      columns: [
+        { key: "item", label: "Item" },
+        { key: "qty", label: "Qty", align: "right" },
+        { key: "action", label: "Make / buy" },
+        { key: "mfr", label: "Manufacturer" },
+        { key: "mpn", label: "MPN" },
+        ...(rows.some((r) => r.value) ? [{ key: "value", label: "Value" }] : []),
+        { key: "path", label: "Instance" },
+      ],
+      rows: rows.map((r) => ({ item: indent(r.level, r.item), qty: r.qty_per_unit, action: r.kind === "unit" ? "unit" : ACTION[r.action], mfr: r.manufacturer, mpn: r.mpn, value: r.value, path: r.path })),
+      caption: "Module breakdown",
+    },
+  ];
+  const out: SectionContribution[] = [{ blocks: breakdown, files: [{ path: "bom.csv", content: unitBomCsv(rows), role: "purchasing", description: "module breakdown of one build" }] }];
+  if (u.kind !== "root") return out;
+
+  const lines = orderingList(p, units, release.config);
+  const fx = readFx(p.root).table;
+  const t = orderTotals(lines, fx);
+  const converted = [...new Set(lines.map((l) => l.supplier_currency).filter(Boolean))].sort();
+  const blocks: Block[] = [
+    {
+      kind: "paragraph",
+      text: `Everything to obtain for ${release.build} ${release.build === 1 ? "product" : "products"}, across all units, one line per part. The full list with suppliers, offers, alternates, lifecycle and sources is ordering-list.csv.`,
+    },
+    {
+      kind: "figures",
+      items: [
+        { label: "Buy", value: String(t.buy), sub: `${t.priced} with a dated price` },
+        { label: "Make", value: String(t.fabricate), sub: "custom parts and cables" },
+        { label: "Included", value: String(t.included), sub: "ship with another part" },
+        { label: "Cost (priced lines)", value: t.costText || "—", sub: [t.priced < t.buy ? `${t.buy - t.priced} bought line(s) unpriced` : "every bought line priced", t.costNote].filter(Boolean).join("; ") },
+      ],
+    },
+    {
+      kind: "table",
+      columns: [
+        { key: "item", label: "Item" },
+        { key: "action", label: "Action" },
+        { key: "needed", label: "Need", align: "right" },
+        { key: "spares", label: "Spare", align: "right" },
+        { key: "order", label: "Order", align: "right" },
+        { key: "where", label: "Supplier / process" },
+        { key: "price", label: "Unit price", align: "right" },
+        { key: "life", label: "Lifecycle" },
+      ],
+      rows: groupLines(lines),
+      caption: "Ordering list",
+    },
+    {
+      kind: "note",
+      level: "tip",
+      text: `Order = need (per product × products) + spares, rounded up to whole packs and the offer's minimum order. Spares: ${SPARE_DEFAULTS.map((d) => `${d.why}: ${d.percent} %, at least ${d.min}`).join("; ")}; nothing else unless release.spares says so. Each bought line is quoted as the bill of materials quotes it: the offer chosen for it in the project (parts/bom.json), else the offer that costs least for the order among those the project holds. Every price is in US dollars${converted.length ? `; prices in ${converted.join(", ")} were converted at the rates of ${fx.date} (${fx.source}) and are marked` : ""}.`,
+    },
+  ];
+  out.push({ title: "Ordering list", order: 10, blocks, files: [{ path: "ordering-list.csv", content: orderingCsv(lines), role: "purchasing", description: "whole-product ordering list" }] });
+  return out;
+}
+
+function groupLines(lines: OrderLine[]) {
+  const rows: (Record<string, string | number> | { group: string })[] = [];
+  for (const [action, title] of [["fabricate", "Make"], ["buy", "Buy"], ["included", "Included with another part"]] as const) {
+    const these = lines.filter((l) => l.action === action);
+    if (!these.length) continue;
+    rows.push({ group: title });
+    for (const l of these)
+      rows.push({
+        item: `${l.item}${l.value ? `, ${l.value}` : ""}${l.mpn ? ` (${l.mpn})` : ""}`,
+        action: l.action === "fabricate" ? "make" : l.action,
+        needed: l.needed,
+        spares: l.spares,
+        order: l.packs ? `${l.order} (${l.packs} × ${l.pack_qty})` : l.order,
+        where: l.action === "fabricate" ? l.process : l.action === "included" ? l.note : l.supplier || "no offer recorded",
+        price: l.unit_price !== null ? `${num(l.unit_price, 4)} ${l.currency}${l.supplier_currency ? ` (from ${l.supplier_currency})` : ""}` : "",
+        life: l.lifecycle,
+      });
+  }
+  return rows;
+}

package/lib/sections/model.ts

@@ -0,0 +1,78 @@
+/**
+ * Model queries the baseline sections share: a unit's definition, mass,
+ * links (the joining operations inside one build) and boundary interfaces.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { jointTorques, systemMass, type ModuleDef, type SystemMass } from "@deltarobotics/uhd";
+import type { Project } from "@protoboardai/core";
+import type { Unit } from "../types.ts";
+import { num } from "../util.ts";
+
+export const unitDef = (p: Project, u: Unit) => p.lookup(u.definition)!;
+
+/** Volume of a module's generated CAD body, from the geometry manifest its artifacts reference (volume_mm3). */
+export function cadVolume(p: Project) {
+  return (def: ModuleDef): number | undefined => {
+    for (const a of def.artifacts ?? []) {
+      if (a.format !== "json" || !a.provenance?.generatedFrom) continue;
+      const r = p.artifacts.find((x) => x.definition === def.id && x.id === a.id);
+      if (r?.present !== true || !r.resolved || !existsSync(r.resolved)) continue;
+      try {
+        const v = (JSON.parse(readFileSync(r.resolved, "utf8")) as { volume_mm3?: unknown }).volume_mm3;
+        if (typeof v === "number") return v;
+      } catch {
+        // not a manifest
+      }
+    }
+    return undefined;
+  };
+}
+
+/** Mass of one build of the unit (sub-units included): stated weights, else CAD volume × density; missing instances listed. */
+export function unitMass(p: Project, u: Unit): SystemMass {
+  return systemMass(unitDef(p, u), p.lookup, cadVolume(p));
+}
+
+export const grams = (g: number) => (g >= 1000 ? `${num(g / 1000, 3)} kg` : `${num(g, 1)} g`);
+
+export interface UnitLink {
+  /** Link id, prefixed with the declaring member's path inside the unit. */
+  id: string;
+  name: string;
+  a: string;
+  b: string;
+  /** Unit-relative path of the harness that carries it, and its definition. */
+  harness?: { path: string; def: ModuleDef };
+  mate: boolean;
+  torques: string[];
+}
+
+/** The links made while building one unit: declared by its module and by every member folded into it. */
+export function unitLinks(p: Project, u: Unit): UnitLink[] {
+  const out: UnitLink[] = [];
+  const declarers: { path: string; def: ModuleDef }[] = [{ path: "", def: unitDef(p, u) }, ...u.members.filter((m) => !m.unit).map((m) => ({ path: m.path, def: p.lookup(m.definition)! }))];
+  for (const { path, def } of declarers) {
+    if (def.kind === "harness") continue; // a harness's own conductors are made with the harness
+    for (const l of def.links ?? []) {
+      const end = (e: (typeof l)["a"]) => {
+        const child = "child" in e ? e.child : "";
+        const at = [path, child].filter(Boolean).join("/");
+        const m = u.members.find((x) => x.path === at);
+        return `${m?.name ?? (at || def.name)}${e.interfaceId ? ` · ${e.interfaceId}` : ""}`;
+      };
+      const hp = l.harness ? [path, l.harness].filter(Boolean).join("/") : undefined;
+      const hm = hp ? u.members.find((x) => x.path === hp) : undefined;
+      const hdef = hm ? p.lookup(hm.definition) : undefined;
+      out.push({
+        id: [path, l.id].filter(Boolean).join("/"),
+        name: l.name ?? l.id,
+        a: end(l.a),
+        b: end(l.b),
+        ...(hp && hdef ? { harness: { path: hp, def: hdef } } : {}),
+        mate: !!l.mate || !!hdef?.fastenerStack?.length,
+        torques: hdef ? jointTorques(hdef, p.lookup).map((t) => `${t.part?.name ?? t.child}: ${num(t.torque.torqueNm, 2)} N·m${t.basis === "assumption" ? " (assumed)" : ""}`) : [],
+      });
+    }
+  }
+  return out;
+}

package/lib/sections/testplan.ts

@@ -0,0 +1,76 @@
+/**
+ * The test plan of one unit (PK5, basic for v0.1): the checks of
+ * ./tests.ts as tables by group, and the records to capture, with a CSV
+ * to fill in (files/test/test-record.csv, one row per check).
+ */
+import { unitPlan } from "@protoboardai/ext-docs/plan";
+import type { Block, SectionContext, SectionContribution } from "../types.ts";
+import { toCsv } from "../util.ts";
+import { unitTests, type TestGroup, type TestItem } from "./tests.ts";
+
+const GROUPS: { group: TestGroup; title: string; intro: string; none: (s: SectionContext) => string | undefined }[] = [
+  {
+    group: "fai",
+    title: "First-article inspection",
+    intro: "The first of each part made for this unit, before it is used. Nominal sizes come from the CAD outputs and the model's interfaces; the tolerance is the one on the fabrication order.",
+    none: () => "No parts are made for this unit: check purchased parts on receipt against their part numbers (work order, first operation).",
+  },
+  {
+    group: "joint",
+    title: "Fits and joints",
+    intro: "One check per assembly operation, made at its inspection point (work order) before the next operation covers it up.",
+    none: () => "This unit makes no joints.",
+  },
+  {
+    group: "bringup",
+    title: "Bring-up",
+    intro: "In this order, stopping at the first failure, at the point the work order calls for it (before any step that must follow the test, such as fitting propellers). Expected voltages are the design values in the model; currents are the model's supply budget.",
+    none: () => "Nothing in this unit is powered on its own; it is tested where it is assembled.",
+  },
+  {
+    group: "function",
+    title: "Functional checks",
+    intro: "One per requirement of the project's brief, on the finished product (the work order's last operation). The method follows the requirement's wording; refine it before testing.",
+    none: (s) => (s.unit.kind === "root" ? "The project has no requirements source (docs/brief.md), so no functional checks are generated." : undefined),
+  },
+];
+
+export async function testPlanSection(s: SectionContext): Promise<SectionContribution> {
+  const { project: p, unit: u } = s;
+  const tests = unitTests(p, u, await unitPlan(p, u));
+  const blocks: Block[] = [
+    { kind: "note", level: "caution", text: "Basic test plan (v0.1): generated from the model. It lists what to check and the pass criterion the model supports; it does not replace a qualification plan, and nothing here has been run." },
+  ];
+  for (const g of GROUPS) {
+    const items = tests.items.filter((t) => t.group === g.group);
+    const none = items.length ? undefined : g.none(s);
+    if (!items.length && !none) continue;
+    blocks.push({ kind: "heading", text: g.title });
+    if (!items.length) {
+      blocks.push({ kind: "paragraph", text: none! });
+      continue;
+    }
+    const intro = g.group === "bringup" && tests.powerBudget ? `${g.intro} The project's power budget is ${tests.powerBudget}.` : g.group === "function" && tests.requirements ? `${g.intro} Source: ${tests.requirements}.` : g.intro;
+    blocks.push({ kind: "paragraph", text: intro, keep: true });
+    blocks.push({ kind: "table", columns: [{ key: "id", label: "ID", nowrap: true }, { key: "check", label: "Check" }, { key: "how", label: "How" }, { key: "pass", label: "Pass" }, { key: "record", label: "Record" }], rows: items.map(row) });
+  }
+  blocks.push({ kind: "heading", text: "Records to capture" });
+  blocks.push({
+    kind: "list",
+    items: [
+      `For each unit built: its serial number and the release it was built to (${s.release.version}).`,
+      "For each check: pass or fail, the measured value where the check names one, the instrument, who checked and when.",
+      "Any deviation from this package, and what was decided.",
+      "files/test/test-record.csv has one row per check to fill in; measured results are attached to the release later as evidence.",
+    ],
+  });
+  return { blocks, files: [{ path: "files/test/test-record.csv", content: recordCsv(tests.items, s), role: "test", description: "test record to fill in, one row per check" }] };
+}
+
+const row = (t: TestItem) => ({ id: t.id, check: `${t.check}: ${t.subject}`, how: t.how, pass: t.pass, record: t.record });
+
+const recordCsv = (items: TestItem[], s: SectionContext) =>
+  toCsv(
+    ["release", "unit", "serial", "id", "group", "check", "subject", "pass_criterion", "result", "measured", "instrument", "by", "date", "note"],
+    items.map((t) => ({ release: s.release.version, unit: s.unit.id, serial: "", id: t.id, group: t.group, check: t.check, subject: t.subject, pass_criterion: t.pass, result: "", measured: "", instrument: "", by: "", date: "", note: "" })),
+  );