@protoboardai/ext-hardware 0.0.0-stage → 0.2.1

package/skills/system-compose/scripts/scenarios.ts

@@ -0,0 +1,82 @@
+/**
+ * Fault scenarios: run the system checks on deliberately broken variants of
+ * the project's system and report whether each fault is caught.
+ *
+ *   npx tsx <this file> [src/scenarios.ts] [--json]
+ *
+ * The scenarios file exports `SCENARIOS`, each
+ *   { id, label, description?, expect: string[], system?: ModuleDef, overrides?: ModuleDef[] }
+ * where `system` defaults to the project root, `overrides` replace
+ * definitions by id (e.g. a frame cut for the wrong stack, a board with a
+ * pin on the wrong net; every board below the system is checked on its own
+ * nets, as `protoboard check` does), and `expect`
+ * lists the diagnostic codes the fault must raise at error or warning
+ * severity (e.g. "UHD_LINK_STATE", "UHD_BUS_ADDRESS", "UHD_ASSEMBLY").
+ * A scenario with `expect: []` (the nominal build) must raise no errors.
+ * Boards below the root (definitions that declare nets) get the system rules
+ * on their own nets too, as `protoboard check` runs them.
+ * Exit 1 when a fault goes uncaught or the nominal build has errors.
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { assemble, checkSystem, type ModuleDef, type ModuleLookup } from "@deltarobotics/uhd";
+import { boardModules, loadProject } from "@protoboardai/core";
+
+interface Scenario {
+  id: string;
+  label: string;
+  description?: string;
+  expect: string[];
+  system?: ModuleDef;
+  overrides?: ModuleDef[];
+}
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const file = resolve(args.find((a) => !a.startsWith("--")) ?? "src/scenarios.ts");
+const p = await loadProject(process.cwd(), { checks: false, extensions: false });
+if (!p.rootDef) throw new Error("the project has no root system");
+const { SCENARIOS } = (await import(pathToFileURL(file).href)) as { SCENARIOS?: Scenario[] };
+if (!SCENARIOS?.length) throw new Error(`${file} exports no SCENARIOS`);
+
+// assembly is rooted at the first top-level instance with interface frames (as `protoboard check` does)
+const structure = p.instances.find((i) => i.parent === "" && p.lookup(i.definition)?.interfaces.some((f) => f.geometry?.frame));
+
+const results = SCENARIOS.map((s) => {
+  const byId = new Map((s.overrides ?? []).map((d) => [d.id, d]));
+  const lookup: ModuleLookup = (id) => byId.get(id) ?? p.lookup(id);
+  const system = s.system ?? p.rootDef!;
+  const found: { code: string; severity: string; message: string }[] = checkSystem(system, lookup).diagnostics.map((d) => ({
+    code: `UHD_${d.rule.toUpperCase()}`,
+    severity: d.severity,
+    message: d.message,
+  }));
+  // the boards below the system, each checked on its own nets (as `protoboard check` does: the root covers the
+  // tree for categories and passive overrides; a board is powered from outside it)
+  for (const { def, path } of boardModules(system, lookup)) {
+    for (const d of checkSystem(def, lookup).diagnostics) {
+      if (d.rule === "unknown_category" || d.rule === "passive_override" || d.rule === "unpowered") continue;
+      found.push({ code: `UHD_${d.rule.toUpperCase()}`, severity: d.severity, message: `${path}: ${d.message}` });
+    }
+  }
+  if (structure) {
+    for (const i of assemble(system, lookup, { root: [structure.path] }).issues) {
+      found.push({ code: i.severity === "info" ? "UHD_UNPLACED" : "UHD_ASSEMBLY", severity: i.severity, message: `${i.subject}: ${i.message}` });
+    }
+  }
+  const raised = found.filter((d) => d.severity !== "info");
+  const missed = s.expect.filter((c) => !raised.some((d) => d.code === c));
+  const errors = found.filter((d) => d.severity === "error");
+  const ok = s.expect.length ? missed.length === 0 : errors.length === 0;
+  return { id: s.id, label: s.label, expect: s.expect, ok, missed, raised: raised.map((d) => `${d.severity} ${d.code}: ${d.message}`) };
+});
+
+if (json) console.log(JSON.stringify(results, null, 2));
+else {
+  for (const r of results) {
+    console.log(`${r.ok ? "caught " : "MISSED "} ${r.id.padEnd(22)} ${r.label}`);
+    if (!r.ok && r.expect.length) console.log(`         expected ${r.missed.join(", ")}`);
+    for (const line of r.raised.filter((l) => (r.expect.length ? r.expect.some((c) => l.includes(c)) : l.startsWith("error")))) console.log(`         ${line.slice(0, 180)}`);
+  }
+}
+process.exitCode = results.every((r) => r.ok) ? 0 : 1;

package/skills/system-review/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: system-review
+description: Independent review of a composed UHD system against its brief — every requirement traced to a check, document value or test; every link, harness and mate justified by both parts' interfaces; every diagnostic dispositioned; fault scenarios caught. Run by a fresh agent after system-compose (or before a release); writes a findings file and never edits the model itself.
+---
+
+# System review
+
+A fresh agent, with no memory of how the system was built, checks that it
+does what the brief says and that the model says only what the sources
+support. The composer's reasoning is not evidence; the files are.
+
+## Purpose
+
+Catch what the composer cannot see in their own work: requirements nothing
+shows, links that pass only by inference, warnings quietly accepted, gaps
+presented as facts. Use it when **system-compose** hands off (0 errors,
+scenarios caught), before a release, and after any large change to the
+system. In **build-a-project** it closes stage 4 and is repeated in stage 8.
+It never edits the model; findings go back to the composer.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| Brief, decisions, requirement → evidence mapping | `docs/brief.md`, `docs/decisions.md` (or the test plan) | **system-compose** step 1 |
+| Check results | `npx protoboard check --format json` | the project |
+| The system | `npx protoboard inspect --format json`, `npx protoboard inspect <instance> --format json` | the project |
+| Scenario run | `npx tsx node_modules/@protoboardai/ext-hardware/skills/system-compose/scripts/scenarios.ts --json` | **system-compose** step 4 |
+| Part evidence | `parts/evidence/<id>/`, catalog origins in `parts/origins.json`, catalog files in `parts/catalog/<id>/` | the part skills, `parts add` |
+
+## Steps
+
+### 1. Requirements
+
+Each requirement in the brief has one of: a validator that ran and passes, a
+document value, a planned test, or an explicit "not verified" entry. A
+requirement with none is a finding. Model checks never count as physical
+acceptance.
+
+### 2. Coverage
+
+```bash
+npx protoboard check --severity info --format json
+```
+
+In `checks[]`, every validator ran. A skipped validator, or a check `reason`
+about unchecked refs, is unknown coverage: list it.
+
+### 3. Links
+
+For a sample of links (all power links, every link to the main controller,
+every mechanical mate), open both interfaces:
+
+```bash
+npx protoboard inspect <instance> --format json
+```
+
+Confirm the parameters that DRC compared come from the parts' sources, and
+that the connection exists in the hardware (pinout, manual wiring diagram).
+Links that pass only by inference (`valid_inferred`) or manual override need a
+reason.
+
+### 4. Harnesses
+
+Every electrical link that leaves a board is carried by a harness or a stated
+solder joint; every mechanical joint has a fastener stack whose arithmetic you
+re-derive (**harness-verify**).
+
+### 5. Diagnostics
+
+Every warning has a disposition in `docs/decisions.md` or an open item; no
+parameter was removed or widened to make a rule pass (compare with the part's
+sources).
+
+### 6. Scenarios
+
+```bash
+npx tsx node_modules/@protoboardai/ext-hardware/skills/system-compose/scripts/scenarios.ts --json
+```
+
+All caught; the nominal build raises no errors. Think of one realistic
+mistake the scenarios do not cover and say whether the checks would catch it.
+
+### 7. Assumptions and gaps
+
+List every `assumption` and `data_gap` trait in local definitions:
+
+```bash
+npx protoboard build                       # then search .protoboard/build/resolved.json, or grep src/ and parts/local/
+```
+
+Each is either acceptable for this revision or an open item.
+
+### 8. Write the review
+
+`docs/reviews/system-review-<YYYY-MM-DD>.md`:
+
+```md
+# System review — <project> @ <git revision>
+Reviewer: <agent/person> · check: <E> errors, <W> warnings · scenarios: <caught>/<total>
+
+| id | severity | entity | finding | evidence | suggested fix |
+| --- | --- | --- | --- | --- | --- |
+| R1 | major | link dji_fc (derived bec_10v ↔ vcc) | ... | O4 manual p.x | ... |
+
+## Requirement trace
+| requirement | shown by | status |
+```
+
+Hand the file to the composer; do not edit the model in the review.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Severity | **blocker**: wrong hardware would be built or damaged. **major**: a claim not supported by a source. **minor**: traceability, naming. |
+| Sample size for links | All power links, all links to the main controller, all mates; plus at least three others chosen at random. |
+| A requirement shown only by a model check | Acceptable for the model; list the physical test that would confirm it, or "not verified". |
+| Unknown coverage | Always a finding (minor unless it hides a requirement). |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| The review | `docs/reviews/system-review-<YYYY-MM-DD>.md` |
+
+## Verification
+
+The review file exists, names the git revision and the check and scenario
+counts, has a row for every requirement in the brief, and every finding cites
+its evidence (a file and line, a source page, a command output). No model
+file changed (`git status --short src/ parts/` shows nothing from the review).
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| `checks[]` has a `skipped` validator | Unknown coverage | Record it; ask the composer to fix the reason (a missing tool, an upstream error) |
+| Errors in `check` | The system was not ready for review | Stop; hand back to **system-compose** |
+| `UHD_LINK_STATE` warning (`valid_inferred`) | DRC matched by inference | Check the datasheets yourself; a finding unless a reason is recorded |
+| A warning with no disposition | Accepted silently | Finding (major) |
+| A scenario `MISSED` | The check the design relies on does not fire | Finding (major or blocker) |
+| `HW_NO_SOURCES`, `HW_NOT_VERIFIED` | Part evidence missing | Finding; the part goes back to **uhd-part-research** / **uhd-part-verify** |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).

package/skills/test-and-measure/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: test-and-measure
+description: Plan and record physical tests for a UHD system — derive a test plan from the brief's requirements and the model (first-article inspection, board bring-up, functional checks; what each test proves, pass criteria from model values), write step-by-step procedures, and record results as measured test-data files (UHD tech-docs schema, status standin|measured) that replace stand-in data in the documents. Use when a design needs acceptance evidence, before building a prototype, and whenever measurements come back from the bench.
+---
+
+# Test and measure
+
+```
+brief requirements ─┐
+UHD model values ───┼─► docs/test-plan.md ─► docs/procedures/<test-id>.md ─► bench / flight
+stand-in data ──────┘                                                            │
+                                   docs/test-data/<test-id>.json (status: measured) ◄┘
+                                                │
+                              documents rebuilt: stand-in watermark gone, values marked M
+```
+
+Model checks validate the model. Only measurements on a physical unit,
+recorded against a release and a unit, establish that the hardware meets its
+brief. Never write a measured file for a test that was not run.
+
+## Purpose
+
+Turn requirements and model claims into tests a person can run, and turn
+their results into evidence the documents and the release carry. Use it when
+a design needs acceptance evidence, before a prototype is built (the plan
+goes into the Manufacturing Package's test and validation plan), and
+whenever measurements come back. In **build-a-project** it is part of stage
+10; recording results happens after the release, against it. This skill
+plans and records; a person performs every physical test.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| Requirements and their "shown by" mapping | `docs/brief.md`, `docs/decisions.md` | **system-compose** step 1 |
+| Model values and warnings | `npx protoboard check --format json`, `npx protoboard inspect --format json` | the project |
+| Stand-in data the documents use | `docs/test-data/*.json` with `status: "standin"` | **uhd-tech-docs** (`protoboard run tech-docs`) |
+| Firmware items to verify | the firmware reference's UNVERIFIED list, the generator's warnings | **firmware-config** |
+| Bench results | raw logs, CSVs, photos from the person who ran the test | the bench |
+
+## Steps
+
+### 1. Test plan from requirements and the model
+
+`docs/test-plan.md`, one row per test ([template and the quad's plan](references/test-plan.md)):
+
+| Column | Content |
+| --- | --- |
+| `id` | kebab-case; **the same id as its test-data file** (`hover-current`) |
+| requirement | the brief line(s) it proves, quoted |
+| model claim | the value queries it checks, e.g. `sys:checks.diagnostics[rule=propulsion_current].details.totalPeak`, `def:<part>:…` — the numbers the documents print |
+| level | inspection · bench · propulsion · flight |
+| pass criterion | from the requirement, or the model value with a stated tolerance; never invented after the result |
+| depends on | tests that must pass first (power-up before props on) |
+| status | planned · procedure written · run (pass/fail) · blocked |
+
+Derive tests systematically:
+
+- every requirement in the brief → at least one test or an explicit
+  "not tested in this revision";
+- every warning and every `assumption` / `data_gap` the model carries → a
+  measurement that would retire it (fastener torques, frame mass, the
+  propulsion-current warning → a current log at full throttle);
+- every stand-in data file the documents use (`status: "standin"`) → the test
+  that replaces it, with the same id and columns;
+- every firmware setting marked verify (motor order, compass alignment) → a
+  bench check (**firmware-verify**);
+- the Manufacturing Package's basic validation plan
+  (`docs/specs/release-package-and-evals.md` §2 in the stack repository):
+  **first-article inspection** (dimensions, fits, seals against the CAD and
+  the enclosure check's report); **board bring-up** for each custom board
+  (rails against the board's nets, idle current against the supply budget,
+  programming and boot, bus scans with the expected I2C addresses from the
+  parts, a smoke test per peripheral); **functional checks** per requirement;
+  and the records each one captures.
+
+Order by risk and by what destroys hardware first: inspection → power-up with
+a current limit, no props or loads → rails and peripherals → motor direction
+and order → thrust stand → hover → endurance.
+
+### 2. Procedures
+
+`docs/procedures/<test-id>.md` ([template](references/procedure-template.md)):
+preconditions (release/revision, unit serial, firmware dump hash, battery
+state), equipment with calibration date, safety and abort criteria, numbered
+steps, what to record and in which raw file, the pass criterion, and the
+test-data columns the result fills. A procedure is runnable by someone who has
+not read the model.
+
+### 3. Recording results
+
+One file per test: `docs/test-data/<test-id>.json`, schema
+`uhd-test-data/1` (`node_modules/@protoboardai/ext-docs/skills/uhd-tech-docs/templates/test-data.schema.json`,
+guide `…/uhd-tech-docs/references/test-data.md`).
+
+- `status: "measured"`; `subject.system` and the tested `modules`;
+- `conditions[]`: battery voltage, ambient, prop, firmware, all-up weight…
+  as measured on the day (units, `""` for text);
+- `provenance`: `method` (the procedure, one paragraph), `date` (ISO),
+  `operator` and/or `instruments[]`, `rawFiles[]` (logs, CSVs, photos; keep
+  them next to the file or in a data store they can be fetched from); no
+  `derivedFrom` (that is stand-in provenance);
+- `columns`, `rows`, `summary`: **the same ids and units as the stand-in it
+  replaces**, so documents pick it up unchanged. A new test gets a new id.
+
+Validate before committing:
+
+```bash
+npx tsx node_modules/@protoboardai/ext-hardware/skills/test-and-measure/scripts/test-data.ts docs/test-data
+npx tsx node_modules/@protoboardai/ext-hardware/skills/test-and-measure/scripts/test-data.ts docs/test-data/hover-current.json --replaces <standin dir or file>
+```
+
+It fails on template placeholders (all-zero summaries, "EXAMPLE ONLY"
+method), a missing date or operator, rows that do not match the columns, and
+(with `--replaces`) changed ids, columns or units.
+
+A failed test is data too: record it as measured with its conditions, then
+open the design issue it exposes. Measured results never rewrite the design
+specification; they feed the next revision (**system-compose**).
+
+### 4. Replacing stand-ins in the documents
+
+Documents are built by **uhd-tech-docs** (`@protoboardai/ext-docs`) from the
+project's `docs/test-data/`; a measured file with the stand-in's id wins, the
+stand-in generator never overwrites it, charts lose the STAND-IN watermark and
+values get the **M** marker.
+
+```bash
+npx protoboard run tech-docs
+npx protoboard run tech-docs-verify          # fails if a measured chart still carries a watermark
+```
+
+Then the visual review in **uhd-tech-docs-verify**.
+
+### 5. Tie results to a release
+
+Every measured file names what was tested: put the release revision and unit
+serial in `conditions` (`{ "name": "Release", "value": "quad5-r1", "unit": "" }`,
+`{ "name": "Unit", "value": "SN001", "unit": "" }`). See **release**: measured
+results attach to a release later as evidence and never change its frozen
+inputs.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Test or "not tested" | Every requirement gets a test, or an explicit "not tested in this revision" with the reason. |
+| Pass criterion | From the requirement, or the model value with a stated tolerance, written before the test is run. |
+| Order | What can destroy hardware is tested last and behind its prerequisites; first power always through a current limit. |
+| New id or same id | A result that replaces a stand-in keeps its id, columns and units; anything else is a new test with a new id. |
+| A failed test | Record it as measured; open the design issue; do not edit the model to match it in the same revision. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| Test plan | `docs/test-plan.md` |
+| Procedures | `docs/procedures/<test-id>.md` |
+| Measured results and raw files | `docs/test-data/<test-id>.json`, raw files next to them or in a fetchable store |
+
+## Verification
+
+```bash
+npx tsx node_modules/@protoboardai/ext-hardware/skills/test-and-measure/scripts/test-data.ts docs/test-data   # exit 0
+npx protoboard run tech-docs-verify                                                                        # succeeds after a rebuild
+```
+
+Every requirement has a row in the plan; every stand-in file has a test with
+its id; every measured file names its release and unit.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| `test-data.ts` fails on placeholders | A template value was left in | Replace it with the measurement, or do not commit the file |
+| `test-data.ts --replaces` reports changed ids, columns or units | The result would not replace the stand-in | Match the stand-in's columns, or give the test a new id |
+| `tech-docs-verify` "standin" finding | A measured chart still has a watermark, or a stand-in value lacks its marker | Rebuild the documents (`run tech-docs`) |
+| `UHD_PROPULSION_CURRENT`, `UHD_SUPPLY_BUDGET` warnings | A model claim that needs a measurement | Plan the test that retires it |
+| `UHD_FASTENER_TORQUE` warnings | Torques are assumptions | Plan the torque inspection |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).

package/skills/test-and-measure/references/procedure-template.md

@@ -0,0 +1,45 @@
+# Procedure template
+
+```md
+# <test-id>: <title>
+
+Plan row: docs/test-plan.md#<test-id> · Result file: docs/test-data/<test-id>.json
+
+## Preconditions
+- Release / revision: <release id or git revision>; unit: <serial>
+- Firmware: <version>, configuration dump <file> (sha256 <…>)
+- Battery: <pack id>, resting voltage <V> (record it in conditions)
+- Tests passed first: <ids>
+
+## Equipment
+| instrument | model | range / resolution | calibration date |
+
+## Safety and abort
+- Props off unless the step says otherwise; current-limited supply for first power.
+- Abort if: <smoke, current above X A, temperature above Y °C, loss of link>.
+
+## Steps
+1. …
+2. Record <quantity> in <raw file> (column `<id>`, unit <unit>).
+
+## Pass criterion
+<quoted from the plan; decided before the test>
+
+## Result
+Write docs/test-data/<test-id>.json (status "measured", same columns as the
+stand-in), validate it with scripts/test-data.ts, and list the raw files in
+provenance.rawFiles. Record failures the same way.
+```
+
+## Example: hover-current (quadcopter-5in)
+
+- Preconditions: `motor-order-direction` passed; props fitted per the
+  assembly guide; all-up weight measured on a scale (condition "All-up weight
+  (weighed)").
+- Equipment: FC current sensor, calibrated against a clamp meter at 3
+  currents; scale 0.1 g.
+- Steps: hover in still air 60 s per ballast step; Blackbox logging on;
+  average current over the steady 40 s.
+- Columns (must match the stand-in): `auw` g, `thrust_motor` g,
+  `current_total` A, `power_total` W; summary `auw_g`, `hover_current_A`,
+  `hover_power_W`, `avionics_current_A`.

package/skills/test-and-measure/references/test-plan.md

@@ -0,0 +1,35 @@
+# Test plan template, with the quadcopter's first rows
+
+```md
+# Test plan — <project> (<revision>)
+
+Scope: what this plan accepts and what it does not (e.g. "bench and hover;
+no endurance or crash testing in this revision").
+
+| id | requirement | model claim (value queries) | level | pass criterion | depends on | status |
+| --- | --- | --- | --- | --- | --- | --- |
+```
+
+## Quadcopter-5in: first rows (derived from `docs/brief.md` and the model)
+
+Requirements quoted from the brief: "True-X 5-inch … ≥ 5 mm prop clearance",
+"6S LiPo power (CNHL 1100 mAh 100C)", "Acceptance: … the unit is assembled per
+the generated guide, and bench/flight measurements replace the stand-in data
+in the datasheet."
+
+| id | requirement | model claim | level | pass criterion | depends on |
+| --- | --- | --- | --- | --- | --- |
+| `frame-inspection` | frame fabricated from its CAD | frame CAD: plate DXF, `frames.json`, feature manifest; hole Ø = fastener + 0.2 mm | inspection | every hole pattern within ±0.1 mm of the DXF (caliper/pin gauge); plate thickness as `plate_thickness_mm` | — |
+| `prop-clearance` | ≥ 5 mm prop clearance | wheelbase and prop diameter (frame metadata, prop part) | inspection | measured tip-to-tip gap ≥ 5 mm on all adjacent pairs | `frame-inspection` |
+| `fastener-torque` | assembled per the guide | every `fastenerStack` torque (all assumptions today) | inspection | torque driver at the model value; no stripped thread, no crushed grommet; record any change as a new assumption | `frame-inspection` |
+| `power-up` | 6S power | supply budgets per rail (`UHD_SUPPLY_BUDGET` details) | bench | current-limited supply, no props: idle current within the budget; BEC rails 5 V / 10 V / 4.5 V within the parts' stated tolerance | `fastener-torque` |
+| `peripherals` | ELRS, O4, GNSS/compass | link `rx_crsf`; cables `dji_fc`/`dji_o4` (derived UART5 ↔ MSP) and `gnss_socket`/`gnss_pads` (derived UART1, I2C1); firmware CLI | bench | receiver link, OSD visible in goggles, GPS fix, compass detected (**firmware-verify**) | `power-up` |
+| `motor-order-direction` | Quad-X, correct spin | Betaflight Quad-X order; motor/prop spin | bench | Motors tab: M1…M4 at rear-right, front-right, rear-left, front-left; directions match the props | `peripherals` |
+| `throttle-sweep` | replaces the datasheet stand-in | stand-in `throttle-sweep` (same columns) | propulsion | curve recorded on a thrust stand; within ±15 % of the maker's points or a design issue is opened | `motor-order-direction` |
+| `hover-current` | replaces the stand-in | stand-in `hover-current`; all-up weight | flight | measured hover current and AUW recorded; weigh before flight | `throttle-sweep` |
+| `propulsion-peak-current` | retire `UHD_PROPULSION_CURRENT` | `details.totalPeak` 171.88 A vs pack 110 A continuous / 220 A burst | flight | Blackbox current log of full-throttle punches; decision recorded (accept bursts / limit current) | `hover-current` |
+
+Stand-in files the documents currently use (the project's
+`docs/test-data/`, written by `protoboard run tech-docs`): `throttle-sweep`,
+`hover-current`, `flight-time`, `thrust-to-weight`, `esc-temp-punchout`,
+`battery-discharge`. Each needs a row whose id matches.

package/skills/test-and-measure/scripts/test-data.ts

@@ -0,0 +1,94 @@
+/**
+ * Validate test-data files (UHD tech-docs convention, schema uhd-test-data/1:
+ * @protoboardai/ext-docs skills/uhd-tech-docs/templates/test-data.schema.json).
+ *
+ *   npx tsx <this file> <file-or-dir> [--replaces <standin-file-or-dir>] [--json]
+ *
+ * Checks every <id>.json: required fields, id == file name, status
+ * standin|measured, measured files carry provenance.date (and operator or
+ * instruments), rows match the columns, units present, no placeholder zeros
+ * left in a measured file's summary. With --replaces, a measured file must
+ * keep the stand-in's id, column ids and units so documents pick it up
+ * unchanged. Exit 1 on any error.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+interface TestData {
+  id: string;
+  title: string;
+  status: "standin" | "measured";
+  subject: { system: string; modules?: string[] };
+  conditions: { name: string; value: number | string; unit: string }[];
+  provenance: { method: string; date?: string; operator?: string; instruments?: string[]; rawFiles?: string[]; derivedFrom?: string[]; assumptions?: string[] };
+  columns: { id: string; label: string; unit: string }[];
+  rows: (number | string)[][];
+  summary: { id: string; label: string; value: number | string; unit: string }[];
+}
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const replacesAt = args.indexOf("--replaces");
+const replaces = replacesAt >= 0 ? args[replacesAt + 1] : undefined;
+const target = args.find((a, k) => !a.startsWith("--") && (replacesAt < 0 || k !== replacesAt + 1));
+if (!target) throw new Error("usage: test-data.ts <file-or-dir> [--replaces <standin-file-or-dir>] [--json]");
+
+const files = (path: string) => (statSync(path).isDirectory() ? readdirSync(path).filter((f) => f.endsWith(".json")).sort().map((f) => join(path, f)) : [path]);
+
+function validate(file: string): string[] {
+  const errs: string[] = [];
+  let d: TestData;
+  try {
+    d = JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    return [`not JSON: ${(e as Error).message}`];
+  }
+  for (const k of ["id", "title", "status", "subject", "conditions", "provenance", "columns", "rows", "summary"] as const) if (d[k] === undefined) errs.push(`missing ${k}`);
+  if (errs.length) return errs;
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(d.id)) errs.push(`id "${d.id}" must be kebab-case`);
+  if (d.id !== basename(file, ".json")) errs.push(`id "${d.id}" must equal the file name`);
+  if (d.status !== "standin" && d.status !== "measured") errs.push(`status must be standin or measured, not "${d.status}"`);
+  if (!d.subject.system) errs.push("subject.system is required");
+  if (!d.provenance.method) errs.push("provenance.method is required");
+  if (!d.columns.length) errs.push("at least one column");
+  for (const c of [...d.columns, ...d.summary, ...d.conditions]) if (typeof c.unit !== "string") errs.push(`"${"id" in c ? c.id : c.name}" has no unit (use "" for text)`);
+  d.rows.forEach((r, k) => {
+    if (r.length !== d.columns.length) errs.push(`row ${k} has ${r.length} values for ${d.columns.length} columns`);
+  });
+  if (d.status === "measured") {
+    if (!d.provenance.date || !/^\d{4}-\d\d-\d\d/.test(d.provenance.date)) errs.push("a measured file needs provenance.date (ISO date of the test)");
+    if (!d.provenance.operator && !d.provenance.instruments?.length) errs.push("a measured file needs provenance.operator or provenance.instruments");
+    if (/EXAMPLE ONLY/i.test(d.provenance.method)) errs.push("provenance.method is still the template's EXAMPLE ONLY text");
+    if (d.summary.length && d.summary.every((s) => s.value === 0)) errs.push("every summary value is 0: template placeholders, not measurements");
+    if (d.provenance.derivedFrom?.length) errs.push("a measured file must not carry derivedFrom (that is stand-in provenance)");
+  } else if (!d.provenance.derivedFrom?.length) {
+    errs.push("a stand-in needs provenance.derivedFrom (the model queries it was derived from)");
+  }
+  return errs;
+}
+
+function compare(measured: string, standin: string): string[] {
+  const m = JSON.parse(readFileSync(measured, "utf8")) as TestData;
+  const s = JSON.parse(readFileSync(standin, "utf8")) as TestData;
+  const errs: string[] = [];
+  if (m.id !== s.id) errs.push(`id ${m.id} vs stand-in ${s.id}`);
+  const cols = (d: TestData) => d.columns.map((c) => `${c.id}[${c.unit}]`).join(", ");
+  if (cols(m) !== cols(s)) errs.push(`columns ${cols(m)} vs stand-in ${cols(s)}`);
+  const sums = (d: TestData) => new Map(d.summary.map((x) => [x.id, x.unit]));
+  for (const [id, unit] of sums(s)) if (sums(m).get(id) !== unit) errs.push(`summary ${id} [${unit}] missing or in other units`);
+  return errs;
+}
+
+const results = files(target).map((f) => {
+  const errors = validate(f);
+  if (replaces && !errors.length) {
+    const other = statSync(replaces).isDirectory() ? join(replaces, basename(f)) : replaces;
+    if (existsSync(other)) errors.push(...compare(f, other).map((e) => `replaces ${other}: ${e}`));
+    else errors.push(`no stand-in ${other} to replace`);
+  }
+  return { file: f, status: (() => { try { return JSON.parse(readFileSync(f, "utf8")).status; } catch { return undefined; } })(), errors };
+});
+
+if (json) console.log(JSON.stringify(results, null, 2));
+else for (const r of results) console.log(`${r.errors.length ? "FAIL" : "ok  "} ${r.file} (${r.status ?? "?"})${r.errors.map((e) => `\n       ${e}`).join("")}`);
+process.exitCode = results.some((r) => r.errors.length) ? 1 : 0;