@protoboardai/ext-release 0.0.0-stage → 0.2.0

package/lib/manifest.ts

@@ -0,0 +1,159 @@
+/**
+ * The release manifest, `protoboard.release/v0` (release-package-and-evals.md
+ * §3): what was released and from what. Everything in it is derived from
+ * committed inputs, never from the clock or the machine, so rebuilding the
+ * same release in a clean environment gives the same bytes.
+ */
+import { createHash } from "node:crypto";
+import { FRAMEWORK_VERSION, stableStringify, uhdVersion, type Project } from "@protoboardai/core";
+import type { Freshness } from "./preconditions.ts";
+import { exportKey } from "./preconditions.ts";
+import { RELEASE_SCHEMA, type PackageFile, type Unit } from "./types.ts";
+import { byCode, sha256 } from "./util.ts";
+
+export interface ManifestFile {
+  path: string;
+  digest: string;
+  bytes: number;
+  unit?: string;
+  role: string;
+  /** Project-relative source of a copied file. */
+  from?: string;
+}
+
+export interface ReleaseManifest {
+  schema: typeof RELEASE_SCHEMA;
+  project: { name: string; root: string };
+  version: string;
+  /** Release date: SOURCE_DATE_EPOCH, else the source commit's date. */
+  date: string;
+  source: { commit: string; dirty: string[] } | null;
+  framework: { protoboard: string; uhd: { version?: string; revision?: string } };
+  extensions: { id: string; version: string }[];
+  tools: { id: string; detail?: string }[];
+  /** Font files the documents were printed with (they change the PDFs' bytes). */
+  fonts: { file: string; digest: string }[];
+  build: number;
+  units: { id: string; folder: string; kind: Unit["kind"]; entry: string; definition: string; name: string; instances: string[]; perProduct: number; parents: string[] }[];
+  model: { bundle: string; digest: string };
+  parts: { id: string; tier: string; kind: string; source: string; provider?: string; service?: string; revision?: string | number; digest: string; envelopeDigest?: string; instances: number }[];
+  outputs: {
+    module: string;
+    capability: string;
+    provider: { id: string; version: string };
+    config: string;
+    configDigest: string;
+    moduleDigest?: string;
+    record: string;
+    projectDigest: string;
+    tools: { id: string; detail?: string }[];
+    files: { path: string; digest: string }[];
+    packaged: string[];
+  }[];
+  /** Project files other operations generated that the package carries (firmware configuration, …). */
+  generated: { path: string; digest: string; operation: string; extension: string; record?: string; packaged: string[]; role: string }[];
+  firmware: { path: string; digest: string; from?: string }[];
+  check: { errors: number; warnings: number; info: number; findings: { code: string; severity: string; message: string; validator: string }[]; validators: { validator: string; subject?: string; status: string; reason?: string }[] };
+  sections: { unit: string; section: string; contributors: string[] }[];
+  /** Every file in the package except this manifest. */
+  files: ManifestFile[];
+  /** sha256 over the canonical `files` list. */
+  packageDigest: string;
+}
+
+export interface ManifestInputs {
+  p: Project;
+  version: string;
+  date: string;
+  source: ReleaseManifest["source"];
+  build: number;
+  units: Unit[];
+  bundle: PackageFile;
+  fresh: Freshness;
+  files: PackageFile[];
+  tools: { id: string; detail?: string }[];
+  fonts: { file: string; digest: string }[];
+  sections: ReleaseManifest["sections"];
+}
+
+export function buildManifest(m: ManifestInputs): ReleaseManifest {
+  const { p } = m;
+  const uhd = uhdVersion(p.root);
+  const used = new Map<string, number>();
+  for (const i of p.instances) used.set(i.definition, (used.get(i.definition) ?? 0) + 1);
+  const files: ManifestFile[] = m.files
+    .map((f) => ({ path: f.path, digest: sha256(f.content), bytes: f.content.length, ...(f.unit ? { unit: f.unit } : {}), role: f.role, ...(f.from ? { from: f.from } : {}) }))
+    .sort((a, b) => byCode(a.path, b.path));
+  const packagedFrom = (from: string) => files.filter((f) => f.from === from).map((f) => f.path);
+  const outputs: ReleaseManifest["outputs"] = [];
+  for (const b of [...p.capabilities].filter((b) => b.module && !b.problem).sort((a, b) => byCode(a.module!, b.module!))) {
+    const rec = m.fresh.exports.get(exportKey(b));
+    if (!rec) continue;
+    const own = rec.record.outputs.filter((o) => o.path.startsWith(b.out + "/")).sort((x, y) => byCode(x.path, y.path));
+    outputs.push({
+      module: b.module!,
+      capability: b.capability,
+      provider: rec.record.extension,
+      config: b.config,
+      configDigest: b.configDigest,
+      ...(rec.record.capability?.moduleDigest ? { moduleDigest: rec.record.capability.moduleDigest } : {}),
+      record: rec.file,
+      projectDigest: rec.record.projectDigest,
+      tools: rec.record.tools.map((t) => ({ id: t.id, ...(t.detail ? { detail: t.detail } : {}) })),
+      files: own.map((o) => ({ path: o.path, digest: o.digest })),
+      packaged: own.flatMap((o) => packagedFrom(o.path)),
+    });
+  }
+  const capOut = new Set(outputs.flatMap((o) => o.files.map((f) => f.path)));
+  const generated: ReleaseManifest["generated"] = [];
+  for (const from of [...new Set(files.filter((f) => f.from && !capOut.has(f.from)).map((f) => f.from!))].sort(byCode)) {
+    const w = m.fresh.writers.get(from);
+    const f = files.find((x) => x.from === from)!;
+    generated.push({ path: from, digest: f.digest, operation: w?.record.operation ?? "", extension: w?.record.extension.id ?? "", ...(w ? { record: w.file } : {}), packaged: packagedFrom(from), role: f.role });
+  }
+  const findings = p.diagnostics.filter((d) => d.severity !== "info").map((d) => ({ code: d.code, severity: d.severity, message: d.message, validator: d.validator }));
+  const count = (s: string) => p.diagnostics.filter((d) => d.severity === s).length;
+  const manifest: Omit<ReleaseManifest, "packageDigest"> = {
+    schema: RELEASE_SCHEMA,
+    project: { name: p.name, root: p.rootDef!.id },
+    version: m.version,
+    date: m.date,
+    source: m.source,
+    framework: { protoboard: FRAMEWORK_VERSION, uhd: { ...(uhd.version ? { version: uhd.version } : {}), ...(uhd.revision ? { revision: uhd.revision } : {}) } },
+    extensions: p.extensions.map((e) => ({ id: e.manifest.id, version: e.manifest.version })).sort((a, b) => byCode(a.id, b.id)),
+    tools: m.tools,
+    fonts: m.fonts,
+    build: m.build,
+    units: m.units.map((u) => ({ id: u.id, folder: u.folder, kind: u.kind, entry: u.entry, definition: u.definition, name: u.name, instances: u.instances, perProduct: u.perProduct, parents: u.parents })),
+    model: { bundle: m.bundle.path, digest: sha256(m.bundle.content) },
+    parts: [...used.keys()]
+      .sort(byCode)
+      .map((id) => p.definitions.get(id))
+      .filter((r) => !!r)
+      .map((r) => ({
+        id: r!.def.id,
+        tier: r!.origin.tier,
+        kind: r!.def.kind ?? "module",
+        source: r!.origin.source.file,
+        ...(r!.origin.provider ? { provider: r!.origin.provider } : {}),
+        ...(r!.origin.service ? { service: r!.origin.service } : {}),
+        ...(r!.origin.revision !== undefined ? { revision: r!.origin.revision } : {}),
+        digest: r!.origin.digest ?? sha256(stableStringify(r!.def)),
+        ...(r!.origin.envelopeDigest ? { envelopeDigest: r!.origin.envelopeDigest } : {}),
+        instances: used.get(r!.def.id)!,
+      })),
+    outputs,
+    generated,
+    firmware: files.filter((f) => f.role === "firmware-config").map((f) => ({ path: f.path, digest: f.digest, ...(f.from ? { from: f.from } : {}) })),
+    check: {
+      errors: count("error"),
+      warnings: count("warning"),
+      info: count("info"),
+      findings,
+      validators: p.checks.map((c) => ({ validator: c.validator, ...(c.subject ? { subject: c.subject } : {}), status: c.status, ...(c.reason ? { reason: c.reason } : {}) })),
+    },
+    sections: m.sections,
+    files,
+  };
+  return { ...manifest, packageDigest: "sha256:" + createHash("sha256").update(stableStringify(files)).digest("hex") };
+}

package/lib/offers.ts

@@ -0,0 +1,123 @@
+/**
+ * Ordering data, offline only. A release never calls a service; it reads what
+ * the project holds. Which offer a line is quoted from, and its price, are
+ * the bill of materials' (bom.ts, ext-sourcing `quoteHeldLines`); this
+ * module reads the rest: the sourcing record's lifecycle and alternates,
+ * the pack the model states, and a listing the model cites.
+ *
+ *   1. catalog offers vendored by `protoboard parts offers` into
+ *      `parts/offers.json` (`protoboard.offers/v0`: the parts service's
+ *      offers by part id, prices by source, with the service and retrieval
+ *      time);
+ *   2. sourcing evidence, `parts/evidence/<id>/sourcing.json`
+ *      (@protoboardai/ext-sourcing: dated offers with price breaks, lifecycle,
+ *      alternates);
+ *   3. a supplier listing the model itself cites (a `usage_note` trait whose
+ *      note starts "Supplier listing:" and whose source is the listing URL):
+ *      where to buy, without price or stock.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { OFFERS_FILE, OFFERS_SCHEMA, type Project } from "@protoboardai/core";
+import type { OffersFile } from "@protoboardai/core";
+import { readProjectOffers } from "@protoboardai/core/offers";
+import type { Offer, SourcingRecord } from "@protoboardai/ext-sourcing/lib/sourcing.ts";
+
+export type { OffersFile } from "@protoboardai/core";
+type CatalogOffer = OffersFile["parts"][string][number];
+
+export interface Sourcing {
+  /** Offers from every offline source, in the sourcing record's shape. */
+  offers: (Offer & { origin: "catalog" | "sourcing" })[];
+  record?: SourcingRecord;
+  recordFile?: string;
+  /** A listing the model cites, when no offer exists. */
+  listing?: { supplier: string; url: string };
+  /** Units per pack the model states (performance trait pack_quantity). */
+  packQuantity?: number;
+}
+
+export function readOffersFile(root: string): OffersFile | undefined {
+  const f = join(root, OFFERS_FILE);
+  if (!existsSync(f)) return undefined;
+  const data = JSON.parse(readFileSync(f, "utf8")) as OffersFile;
+  if (data.schema !== OFFERS_SCHEMA) throw new Error(`${OFFERS_FILE} is not ${OFFERS_SCHEMA}`);
+  return data;
+}
+
+/**
+ * A catalog offer in the sourcing record's shape. An offer states the MPN it
+ * is for (a series part's offers are per value); one vendored before MPNs
+ * were required is taken to be for the definition's own MPN.
+ */
+const catalogOffer = (o: CatalogOffer, defMpn: string): Offer & { origin: "catalog" } => {
+  const currency = o.currency;
+  const breaks = currency
+    ? o.priceBreaks?.length
+      ? o.priceBreaks.map((b) => ({ quantity: b.quantity, unit_price: b.unitPrice, currency }))
+      : typeof o.unitPrice === "number"
+        ? [{ quantity: o.minQuantity ?? 1, unit_price: o.unitPrice, currency }]
+        : []
+    : [];
+  return {
+    origin: "catalog",
+    supplier: o.supplier,
+    ...(o.sku ? { supplier_sku: o.sku } : {}),
+    mpn: o.mpn || defMpn,
+    // the listing's link; the library says nothing about how it fetched a price, and a file vendored before that is read the same way
+    url: o.url ?? "",
+    as_of: o.observedAt,
+    via: "api",
+    ...(o.authorized !== undefined ? { authorized: o.authorized } : {}),
+    stock: o.stock ?? null,
+    moq: o.minQuantity ?? null,
+    ...(o.packaging ? { packaging: o.packaging } : {}),
+    price_breaks: breaks,
+    lead_time_weeks: o.leadTimeWeeks ?? null,
+    ...(o.market ? { market: o.market } : {}),
+    note: "catalog offer",
+  };
+};
+
+/**
+ * Everything the project holds about buying `def`. With `placementMpn` (one
+ * value of a series passive, whose placements differ in MPN), only offers
+ * and a sourcing record for that MPN count: each catalog offer names the MPN
+ * it is for (one vendored without one counts for the definition's own).
+ */
+export function sourcingFor(p: Project, def: ModuleDef, catalog?: OffersFile, placementMpn?: string): Sourcing {
+  const mpn = def.part_number ?? "";
+  const catalogOffers: Sourcing["offers"] = (catalog?.parts[def.id] ?? []).map((o) => catalogOffer(o, mpn));
+  // the sourcing record through core's one offer reader (PB-1033), which also says the precedence:
+  // a project part's own evidence first, a library part's library offers first
+  const held = readProjectOffers(p.root, { catalog: p.config.catalog }).forPart(def.id);
+  let record: SourcingRecord | undefined = held.record?.data as SourcingRecord | undefined;
+  let recordFile: string | undefined = held.record?.file;
+  const own: Sourcing["offers"] = (record?.offers ?? []).map((o) => ({ ...o, origin: "sourcing" as const }));
+  const offers: Sourcing["offers"] = held.library || !own.length ? [...catalogOffers, ...own] : [...own, ...catalogOffers];
+  let listing: Sourcing["listing"];
+  for (const t of def.traits ?? []) {
+    const params = (t.params ?? {}) as Record<string, unknown>;
+    const note = typeof params.note === "string" ? params.note : "";
+    const src = Array.isArray(params.source) ? params.source[0] : params.source;
+    if (t.type === "usage_note" && note.startsWith("Supplier listing:") && typeof src === "string") {
+      const host = (() => {
+        try {
+          return new URL(src).hostname.replace(/^www\./, "");
+        } catch {
+          return src;
+        }
+      })();
+      listing = { supplier: host, url: src };
+      break;
+    }
+  }
+  const pack = (def.traits ?? []).map((t) => (t.params as Record<string, unknown> | undefined)?.pack_quantity).find((v) => typeof v === "number" && Number.isInteger(v) && v > 1) as number | undefined;
+  const same = (a: string, b: string) => a.trim().toUpperCase() === b.trim().toUpperCase();
+  const placed = placementMpn ? offers.filter((o) => same(o.mpn, placementMpn)) : offers;
+  // the record's lifecycle and alternates are about its own MPN
+  if (placementMpn && record && !same(record.mpn, placementMpn)) record = undefined;
+  if (!record && !placed.some((o) => o.origin === "sourcing")) recordFile = undefined;
+  return { offers: placed, ...(record ? { record } : {}), ...(recordFile ? { recordFile } : {}), ...(listing ? { listing } : {}), ...(pack ? { packQuantity: pack } : {}) };
+}

package/lib/preconditions.ts

@@ -0,0 +1,141 @@
+/**
+ * What must hold before a release is written (release-package-and-evals.md §1):
+ * `protoboard check` reports no errors, and nothing generated is stale against
+ * its sources. Staleness is decided from evidence, never assumed:
+ *
+ *   - providers' checks: any finding whose code ends in `_STALE` (warning or
+ *     error), and a provider check that was skipped (its result is unknown);
+ *   - every bound module has been exported, and its out/ is exactly what the
+ *     latest export record lists (same files, same digests), made from the
+ *     current config and, when the record has it, the current module;
+ *   - every file an operation record wrote is still the bytes it wrote
+ *     (latest record per file; files since deleted are not checked here;
+ *     earlier packages under release/ are not inputs, so not checked);
+ *   - the source tree: a git work tree with uncommitted changes outside
+ *     release/ and operations/ is refused unless `allowDirty` (recorded).
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { listOperationRecords, moduleDigest, type CapabilityBinding, type OperationRecord, type Project } from "@protoboardai/core";
+import { posix, sha256 } from "./util.ts";
+import type { SectionDiagnostic } from "./types.ts";
+
+export interface Freshness {
+  /** `<capability>:<module>` (exportKey) → its latest succeeded export record. */
+  exports: Map<string, { file: string; record: OperationRecord }>;
+  /** Project file → the latest record that wrote it. */
+  writers: Map<string, { file: string; record: OperationRecord }>;
+  diagnostics: SectionDiagnostic[];
+}
+
+const listFiles = (abs: string, base = abs): string[] =>
+  !existsSync(abs) ? [] : readdirSync(abs).flatMap((f) => (statSync(join(abs, f)).isDirectory() ? listFiles(join(abs, f), base) : [posix(relative(base, join(abs, f)))]));
+
+/** Records, newest last, with the outputs each one wrote. */
+export function freshness(p: Project): Freshness {
+  const diagnostics: SectionDiagnostic[] = [];
+  const stale = (message: string) => diagnostics.push({ code: "REL_STALE", severity: "error", message });
+  const records = listOperationRecords(p).filter((r) => r.record.status === "succeeded");
+  const writers = new Map<string, { file: string; record: OperationRecord }>();
+  for (const r of records) for (const o of r.record.outputs) writers.set(o.path, r);
+
+  // ---- every recorded output is still the bytes its latest writer wrote
+  // (not the release's own packages: a release replaces its folder, and nothing reads them back)
+  for (const [path, r] of writers) {
+    if (r.record.operation === "release" && path.startsWith("release/")) continue;
+    const abs = join(p.root, path);
+    if (!existsSync(abs)) continue;
+    const out = r.record.outputs.find((o) => o.path === path)!;
+    if (sha256(readFileSync(abs)) !== out.digest) stale(`${path} was changed after ${r.record.operation} wrote it (${r.file}); re-run the operation instead of editing generated files`);
+  }
+
+  // ---- every bound module: exported, by the current config and module, and out/ untouched.
+  // Two capabilities may share a module's out/ (a board's circuit and firmware exports): its
+  // files are then checked against the latest export of each capability together.
+  const exports = new Map<string, { file: string; record: OperationRecord }>();
+  const byOut = new Map<string, { b: CapabilityBinding; rec: { file: string; record: OperationRecord } }[]>();
+  for (const b of p.capabilities) {
+    if (b.problem || !b.module) continue;
+    const rerun = `protoboard run ${b.capability}:export --module ${b.module}`;
+    const rec = [...records].reverse().find((r) => r.record.operation === `${b.capability}:export` && r.record.capability?.module === b.module);
+    if (!rec) {
+      stale(`${b.module} has no recorded ${b.capability}:export (${b.out}/ cannot be traced to a run); run \`${rerun}\``);
+      continue;
+    }
+    exports.set(exportKey(b), rec);
+    byOut.set(b.out, [...(byOut.get(b.out) ?? []), { b, rec }]);
+    const cap = rec.record.capability!;
+    if (cap.config !== b.config || cap.configDigest !== b.configDigest) stale(`${b.module}: ${b.config} changed since the last export (${rec.file}); run \`${rerun}\``);
+    if (cap.provider !== providerId(p, b)) stale(`${b.module}: the last export was made by ${cap.provider}, the config now names ${b.provider}; run \`${rerun}\``);
+    const def = p.definitions.get(b.module)?.def;
+    if (cap.moduleDigest && def && cap.moduleDigest !== moduleDigest(def, p.lookup)) stale(`${b.module} changed since its last export (${rec.file}); run \`protoboard run ${b.capability}:generate --module ${b.module}\` and export`);
+  }
+  for (const [out, rs] of byOut) {
+    const recorded = new Map(rs.flatMap(({ rec }) => rec.record.outputs.filter((o) => o.path.startsWith(out + "/")).map((o) => [o.path, rec] as const)));
+    const present = listFiles(join(p.root, out)).map((f) => `${out}/${f}`);
+    const names = rs.map(({ b, rec }) => `${b.capability}: ${rec.file}`).join("; ");
+    const reruns = rs.map(({ b }) => `\`protoboard run ${b.capability}:export --module ${b.module}\``).join(" or ");
+    for (const f of present.filter((f) => !recorded.has(f))) stale(`${f} is not from the last export of ${rs[0].b.module} (${names}); remove it or run ${reruns}`);
+    for (const [f, rec] of [...recorded].filter(([f]) => !present.includes(f))) stale(`${f} from the last export of ${rs[0].b.module} is missing (${rec.file}); run ${reruns}`);
+  }
+  return { exports, writers, diagnostics };
+}
+
+/** Key of `Freshness.exports`: one export per capability of a module. */
+export const exportKey = (b: Pick<CapabilityBinding, "capability" | "module">) => `${b.capability}:${b.module}`;
+
+const providerId = (p: Project, b: CapabilityBinding) => p.extensions.find((e) => e.package === b.provider)?.manifest.id ?? b.provider;
+
+/** Git state of the project: commit and whether design inputs have uncommitted changes. */
+export function gitState(root: string, ignore: string[]): { commit: string; date: string; dirty: string[] } | undefined {
+  const git = (...args: string[]) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  try {
+    if (git("rev-parse", "--is-inside-work-tree").trim() !== "true") return undefined;
+    // a project inside an ignored folder of another repository is not under version control
+    try {
+      git("check-ignore", "-q", "protoboard.config.ts");
+      return undefined;
+    } catch {
+      // not ignored
+    }
+    const commit = git("rev-parse", "HEAD").trim();
+    const date = git("log", "-1", "--format=%cI", "HEAD").trim();
+    const top = git("rev-parse", "--show-toplevel").trim();
+    const prefix = posix(relative(top, root));
+    const dirty = git("status", "--porcelain", "--untracked-files=all", "--", ".")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => l.slice(3).replace(/^"|"$/g, "").split(" -> ").pop()!)
+      .map((f) => (prefix ? posix(relative(prefix, f)) : f))
+      .filter((f) => !ignore.some((i) => f === i || f.startsWith(i + "/")));
+    return { commit, date, dirty };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Everything that stops a release, as errors; plus the check summary
+ * findings worth keeping (warnings), which the manifest records.
+ */
+export function preconditions(p: Project, fresh: Freshness): SectionDiagnostic[] {
+  const out: SectionDiagnostic[] = [];
+  const errors = p.diagnostics.filter((d) => d.severity === "error");
+  if (errors.length)
+    out.push({
+      code: "REL_CHECK_ERRORS",
+      severity: "error",
+      message: `protoboard check reports ${errors.length} error(s); fix them first: ${errors
+        .slice(0, 5)
+        .map((d) => `${d.code} ${d.message}`)
+        .join(" · ")}${errors.length > 5 ? " · …" : ""}`,
+    });
+  // stale standard outputs are the freshness check's own findings below, with the same evidence (the records)
+  for (const d of p.diagnostics.filter((d) => /_STALE$/.test(d.code) && d.severity !== "info" && d.code !== "PB_OUTPUT_STALE")) out.push({ code: "REL_STALE", severity: "error", message: `${d.code} (${d.validator}): ${d.message}` });
+  for (const c of p.checks.filter((c) => c.status === "skipped" && /\/(circuit|cad):check$/.test(c.validator)))
+    out.push({ code: "REL_FRESHNESS_UNKNOWN", severity: "error", message: `${c.validator}${c.subject ? ` [${c.subject}]` : ""} was skipped (${c.reason}); without it the module's outputs cannot be shown to be current` });
+  for (const d of p.diagnostics.filter((d) => d.code === "PB_OUTPUT_NOT_EXPORTED")) out.push({ code: "REL_NOT_EXPORTED", severity: "error", message: d.message });
+  out.push(...fresh.diagnostics);
+  return out;
+}

package/lib/product.ts

@@ -0,0 +1,64 @@
+/**
+ * The package's first page (PB-935): what the device is, its features, what
+ * it does and what it must meet, each requirement with how it is shown,
+ * from the project's own statement (`docs/product.json`, and the brief's
+ * requirements table; @protoboardai/core readProduct). What the project has
+ * not stated is said plainly on the page, never filled in, and reported by
+ * `release --check` as a warning.
+ */
+import { PRODUCT_FILE, PRODUCT_PART_TEXT, type ProductStatement } from "@protoboardai/core";
+import type { Block, SectionDiagnostic } from "./types.ts";
+
+const HOW_TO_STATE = `State it in ${PRODUCT_FILE} (the system-compose skill, step 1).`;
+
+/** The warnings a release reports about the statement. */
+export function productDiagnostics(product: ProductStatement): SectionDiagnostic[] {
+  const out: SectionDiagnostic[] = [];
+  if (product.problems.length) out.push({ code: "REL_PRODUCT_INVALID", severity: "warning", message: `${PRODUCT_FILE} is not used: ${product.problems.join("; ")}` });
+  if (product.missing.length) {
+    const what = product.missing.map((k) => ({ summary: "what the device is (summary)", features: "its features", functions: "the system's functions", requirements: "its requirements" })[k]);
+    out.push({
+      code: "REL_PRODUCT_NOT_STATED",
+      severity: "warning",
+      message: `the package's first page cannot say ${what.join(", ")}: ${product.file ? `${PRODUCT_FILE} does not state ${what.length === 1 ? "it" : "them"}` : `the project has no ${PRODUCT_FILE}`}. The page says so instead; nothing is made up. ${HOW_TO_STATE}`,
+    });
+  }
+  return out;
+}
+
+/** The first page's blocks. `description` is the root module's own, shown when no summary is stated. */
+export function productBlocks(product: ProductStatement, description?: string): Block[] {
+  const out: Block[] = [];
+  const missing = (k: keyof typeof PRODUCT_PART_TEXT): Block => ({ kind: "note", level: "caution", text: `${PRODUCT_PART_TEXT[k].missing} ${HOW_TO_STATE}` });
+  out.push({ kind: "heading", text: PRODUCT_PART_TEXT.summary.title });
+  if (product.summary) out.push({ kind: "paragraph", text: product.summary });
+  else {
+    if (description) out.push({ kind: "paragraph", text: description });
+    out.push(missing("summary"));
+  }
+  out.push({ kind: "heading", text: PRODUCT_PART_TEXT.features.title });
+  out.push(product.features.length ? { kind: "list", items: product.features } : missing("features"));
+  out.push({ kind: "heading", text: PRODUCT_PART_TEXT.functions.title });
+  if (product.functions.length) {
+    const by = product.functions.some((f) => f.by);
+    out.push({
+      kind: "table",
+      columns: [{ key: "id", label: "ID" }, { key: "text", label: "Function" }, ...(by ? [{ key: "by", label: "Done by" }] : [])],
+      rows: product.functions.map((f) => ({ id: f.id ?? "", text: f.text, by: f.by ?? "" })),
+      ...(product.functionsFrom && product.functionsFrom !== PRODUCT_FILE ? { note: `From ${product.functionsFrom}.` } : {}),
+    });
+  } else out.push(missing("functions"));
+  out.push({ kind: "heading", text: PRODUCT_PART_TEXT.requirements.title });
+  if (product.requirements.length) {
+    const pass = product.requirements.some((r) => r.pass);
+    const ids = product.requirements.some((r) => r.id);
+    const unshown = product.requirements.filter((r) => !r.how).length;
+    out.push({
+      kind: "table",
+      columns: [...(ids ? [{ key: "id", label: "ID" }] : []), { key: "text", label: "Requirement" }, { key: "how", label: "How it is shown" }, ...(pass ? [{ key: "pass", label: "Pass" }] : [])],
+      rows: product.requirements.map((r) => ({ id: r.id ?? "", text: r.text, how: r.how ?? "Not stated", pass: r.pass ?? "" })),
+      note: `From ${product.requirementsFrom}. The system test plan carries one functional check per requirement.${unshown ? ` ${unshown} of ${product.requirements.length} do not say how they are shown; the test plan's method for those follows their wording.` : ""}`,
+    });
+  } else out.push(missing("requirements"));
+  return out;
+}