@openmixer/omx-contract 1.3.0 → 2.1.0

package/lib/fmt.mjs

@@ -3,10 +3,13 @@
 /**
  * The one formatting of a data file (spec §3.2): two-space indent, one key per line, keys in schema
  * order, a trailing newline. Names (items, fields, sheet keys) keep the order the author gave them:
- * a travels table's field order is its C block order.
+ * a travels table's field order is its C block order. A kernel file's sections come in their order (controls,
+ * tables, aggregates, constants), its controls in the author's order, each control's keys in schema order.
  */
 
 const ORDER = {
+  control: ['name', 'kind', 'global', 'table', 'rearms', 'since', 'doc', 'why', 'unit', 'ids', 'default', 'labels', 'travel', 'c'],
+  sections: ['controls', 'tables', 'aggregates', 'constants'],
   item: ['kind', 'since', 'doc', 'why', 'unit', 'value', 'values', 'ids', 'default', 'labels', 'fields', 'travel', 'c'],
   travel: ['min', 'max', 'step', 'unit', 'default', 'defaultFrom', 'scale', 'byKind', 'doc', 'why'],
   c: ['alias', 'render'],
@@ -52,10 +55,27 @@ function item(it) {
   return o;
 }
 
+function control(c) {
+  if (!isObj(c)) return c;
+  const o = ordered(c, ORDER.control);
+  if (isObj(o.travel)) o.travel = travel(o.travel);
+  if (isObj(o.c)) o.c = item({ c: o.c }).c;
+  return o;
+}
+
+const items = (m) => (isObj(m) ? Object.fromEntries(Object.entries(m).map(([k, v]) => [k, item(v)])) : m);
+
 /** The canonical text of a parsed data file. */
 export function formatDoc(doc) {
   const out = {};
   if ('$schema' in doc) out.$schema = doc.$schema;
-  for (const [k, v] of Object.entries(doc)) if (k !== '$schema') out[k] = item(v);
+  if (ORDER.sections.some((k) => k in doc)) {
+    for (const [k, v] of Object.entries(ordered(doc, ORDER.sections))) {
+      if (k === '$schema') continue;
+      out[k] = k === 'controls' && Array.isArray(v) ? v.map(control) : ORDER.sections.includes(k) ? items(v) : item(v);
+    }
+  } else {
+    for (const [k, v] of Object.entries(doc)) if (k !== '$schema') out[k] = item(v);
+  }
   return `${JSON.stringify(out, null, 2)}\n`;
 }

package/lib/validate.mjs

@@ -8,13 +8,51 @@
 import { readFileSync } from 'node:fs';
 import { posix } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
-import { resolveData } from './data.mjs';
+import { KERNEL_SECTIONS, entriesOf, isKernelFile, resolveData } from './data.mjs';
 import { eqDefaultBands, eqDefaultParams } from './eq-defaults.mjs';
 import { renderC } from '../render/c.mjs';
 import { renderTs } from '../render/ts.mjs';
 
 const SCHEMA = JSON.parse(readFileSync(new URL('../schema/omx-contract.schema.json', import.meta.url), 'utf8'));
 let compiled;
+/**
+ * The kernel-file shape (2.0.0), which the item schema cannot see: only the four sections at the top; every control
+ * named, of kind travel or choice, unique by name, a travel carrying a `travel` and a choice its `ids`; a control's
+ * `table` declared under `tables`; `rearms` a boolean, and only on a control; an aggregate's fields naming controls; a constant a scalar, a list or a sheet.
+ * A kernel file written as a flat item map (the 1.x shape) is refused as a whole. Any other data file returns [].
+ */
+export function shapeProblems(rel, doc) {
+  if (!isKernelFile(rel)) return [];
+  const sections = KERNEL_SECTIONS;
+  const keys = Object.keys(doc).filter((k) => k !== '$schema');
+  if (keys.length && !keys.some((k) => sections.includes(k))) {
+    return [`${rel} is a flat item map (the 1.x shape): a kernel file declares its items under ${sections.join(', ')}`];
+  }
+  const out = [];
+  for (const k of keys) if (!sections.includes(k)) out.push(`unknown top-level key ${k}: a kernel file holds ${sections.join(', ')}`);
+  const controls = doc.controls ?? [];
+  if (!Array.isArray(controls)) return [...out, 'controls must be a list'];
+  const seen = new Set();
+  for (const [i, c] of controls.entries()) {
+    if (typeof c.name !== 'string' || !/^[a-z][A-Za-z0-9]*$/.test(c.name)) out.push(`controls[${i}]: name ${JSON.stringify(c.name)} is not a lowerCamel identifier`);
+    if (seen.has(c.name)) out.push(`controls[${i}]: name ${c.name} declared twice`);
+    seen.add(c.name);
+    if (c.kind === 'travel' && !c.travel) out.push(`controls[${i}] ${c.name}: a travel without "travel"`);
+    else if (c.kind === 'choice' && !Array.isArray(c.ids)) out.push(`controls[${i}] ${c.name}: a choice without "ids"`);
+    else if (c.kind !== 'travel' && c.kind !== 'choice') out.push(`controls[${i}] ${c.name}: kind ${JSON.stringify(c.kind)} is neither travel nor choice`);
+    if (c.table && !(doc.tables && c.table in doc.tables)) out.push(`controls[${i}] ${c.name}: table ${c.table} is not declared`);
+    if ('rearms' in c && typeof c.rearms !== 'boolean') out.push(`controls[${i}] ${c.name}: rearms ${JSON.stringify(c.rearms)} is not a boolean`);
+  }
+  for (const s of ['tables', 'aggregates', 'constants']) {
+    for (const [n, it] of Object.entries(doc[s] ?? {})) if (it && typeof it === 'object' && 'rearms' in it) out.push(`${s} ${n}: rearms is a control's flag, never a ${s.slice(0, -1)}'s`);
+  }
+  for (const [n, a] of Object.entries(doc.aggregates ?? {})) for (const f of a.fields ?? []) if (!seen.has(f)) out.push(`aggregate ${n}: field ${f} names no control`);
+  for (const [n, it] of Object.entries(doc.constants ?? {})) {
+    if (!['scalar', 'list', 'sheet'].includes(it?.kind)) out.push(`constant ${n}: kind ${JSON.stringify(it?.kind)} is not scalar, list or sheet (a travel or a set is a control)`);
+  }
+  return out;
+}
+
 /** The compiled schema validator. */
 export function schemaValidator() {
   if (!compiled) compiled = new Ajv2020({ allErrors: true, strict: true, strictRequired: false, allowUnionTypes: true }).compile(SCHEMA);
@@ -88,7 +126,10 @@ export function validateData(data) {
     const depth = f.rel.split('/').length - 1;
     const want = posix.join(...Array(depth).fill('..'), 'schema/omx-contract.schema.json');
     if (f.doc.$schema !== want) say(f.rel, '-', 'schema-path', `"$schema" must be "${want}"`);
-    if (!validate(f.doc)) {
+    for (const m of shapeProblems(f.rel, f.doc)) say(f.rel, '-', 'shape', m);
+    // The schema reads items: a kernel file is checked as the items it expands to, so no rule is lost.
+    const items = { $schema: f.doc.$schema, ...Object.fromEntries(entriesOf(f.rel, f.doc)) };
+    if (!validate(items)) {
       for (const e of validate.errors) {
         const item = e.instancePath.split('/')[1] || '-';
         say(f.rel, item, 'schema', `${e.instancePath || '/'} ${e.message}${e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : ''}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "description": "The FreeMixer declarations as data: a JSON Schema, the data, and one CLI that renders them into C, TypeScript and JSON",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/render/json.mjs

@@ -2,7 +2,9 @@
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
  * The `json` target: the resolved data (every reference and derivation evaluated) for readers in
- * other languages, which need no resolver of their own.
+ * other languages, which need no resolver of their own. Beside the items, `kernels` lists each
+ * kernel's controls in their declared order (name, kind, the global each resolves to, the table of a
+ * table field, `rearms` when changing it re-arms the kernel's state), so a reader needs no kernel file.
  */
 
 /** Every file of the `json` target: `[{ path, text }]`. */
@@ -12,5 +14,7 @@ export function renderJson(resolved, version) {
     const { name, ...rest } = r;
     items[name] = rest;
   }
-  return [{ path: 'omx-contract.json', text: `${JSON.stringify({ name: '@openmixer/omx-contract', version, items }, null, 2)}\n` }];
+  const doc = { name: '@openmixer/omx-contract', version, items };
+  if (resolved.kernels) doc.kernels = resolved.kernels;
+  return [{ path: 'omx-contract.json', text: `${JSON.stringify(doc, null, 2)}\n` }];
 }