@openmixer/omx-contract 0.0.0 → 1.0.0

package/render/c.mjs

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The `c` target: `omxcontract/omx_contract_limits.h`, one `omxcontract/params/omx_<plugin>_params.h`
+ * per plugin item and the shape they fill, `omxcontract/params/omx_plugin_param.h`. Every define is
+ * spelled by openmixer's renderer, moved unchanged (c/contract-limits-render.mjs,
+ * c/params-generate.mjs); only the frame (banner, section comments) is this repository's.
+ */
+import { readFileSync } from 'node:fs';
+import {
+  genCoreLimitBlock, genDeclaredListsBlock, genDeclaredRates, genDeclaredScalarsBlock, genLimitBlock, renderContractLimits,
+} from './c/contract-limits-render.mjs';
+import { generate } from './c/params-generate.mjs';
+import { doors } from './doors.mjs';
+
+const PLUGIN_PARAM_H = readFileSync(new URL('./c/omx_plugin_param.h', import.meta.url), 'utf8');
+const defined = (text) => new Set([...text.matchAll(/^#define (OMX_\w+)/gm)].map((m) => m[1]));
+
+/** The rate tail of openmixer's header, outside the include guard, byte for byte. */
+function ratesTail(rates) {
+  return `
+/* The sample rates the console declares (core's STANDARD_SAMPLE_RATES, row-codecs.ts): the set a
+ * contract's rate-is-declared precondition accepts, through omx_rate_is_declared(), and the grid a
+ * native tool iterates. Guarded on its own so a tool built against a pinned copy of this header
+ * (lv2-inprocess-pin.sh) can include this tree's copy after it and gain the rates without mixing
+ * the pin's limits. */
+#ifndef OMX_DECLARED_RATE_COUNT
+${genDeclaredRates(rates)}
+/* The declared rates that are whole multiples of \`base\` (a tool's default grid: the 48 kHz family),
+ * in declaration order, at most \`cap\` of them; returns how many were written to \`out\`. */
+static inline int omx_declared_rates_multiple_of(unsigned base, int *out, int cap) {
+  int n = 0;
+  for (unsigned k = 0; k < OMX_DECLARED_RATE_COUNT && n < cap; k++)
+    if ((unsigned)OMX_DECLARED_RATES[k] % base == 0) out[n++] = (int)OMX_DECLARED_RATES[k];
+  return n;
+}
+#endif
+`;
+}
+
+/** The limits header of the resolved data. */
+export function renderLimitsHeader(resolved) {
+  const d = doors(resolved);
+  const tables = d.NATIVE_LIMIT_TABLES.map(([prefix, table]) => genLimitBlock(prefix, table)).join('\n\n');
+  const coreLimits = new Map(d.ALIASES);
+  const aliases = [...coreLimits.keys()].map((fact) => genCoreLimitBlock(coreLimits, fact)).join('\n\n');
+  const above = defined([tables, aliases].join('\n'));
+  const scalars = d.DECLARED_SCALARS.length ? genDeclaredScalarsBlock(d.DECLARED_SCALARS, above) : '';
+  const lists = d.DECLARED_LISTS.length ? genDeclaredListsBlock(d.DECLARED_LISTS, defined([tables, aliases, scalars].join('\n'))) : '';
+  const sections = [
+    [tables, `/* Per-parameter numeric travel, one block per \`travels\` table named <PREFIX>_LIMITS:
+ * OMX_<PREFIX>_<FIELD>_MIN/_MAX/_DEFAULT, float literals. */`],
+    [aliases, `/* The second C spelling of a travel, its item's \`c.alias\` { fact, field }:
+ * OMX_<FACT>_<FIELD>_MIN/_MAX/_DEFAULT. Removed by a MAJOR release once no consumer reads it. */`],
+    [scalars, `/* Every scalar, sheet leaf and single travel's numbers, one block sorted by macro. An integer value
+ * is an integer literal, any other a float literal AND its OMX_<macro>_DOUBLE spelling. */`],
+    [lists, `/* Every list rendered to C, sorted by list: OMX_<LIST>_COUNT and OMX_<LIST>_INIT { a, b, … }. */`],
+  ].filter(([body]) => body);
+  return `// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#ifndef OMX_CONTRACT_LIMITS_H
+#define OMX_CONTRACT_LIMITS_H
+/*
+ * GENERATED — DO NOT EDIT BY HAND.
+ * Produced by \`omx-contract render --target c\` from FreeMixer/omx-contract's data/, the declaration
+ * as data (each item's reason is its \`doc\`). Change the data, never this file: a consumer builds
+ * against the render of the omx-contract version it pins and commits none.
+ *
+ * A C contract (OMX_PRE/OMX_POST/OMX_INVARIANT) reads a limit from HERE, never a literal.
+ */
+
+${sections.map(([body, comment]) => `${comment}\n${body}`).join('\n\n')}
+
+#endif /* OMX_CONTRACT_LIMITS_H */
+${d.STANDARD_SAMPLE_RATES ? ratesTail(d.STANDARD_SAMPLE_RATES) : ''}`;
+}
+
+/** The banner lines of a plugin's params header rendered from the data. */
+const producedBy = (r) => ` * Produced by \`omx-contract render --target c\` from FreeMixer/omx-contract's ${r.rel}
+ * (${r.name}): ${r.source}.
+ * Change the data, never this file. Order is append-only (omx-contract spec §3.3).`;
+
+/** Every file of the `c` target: `[{ path, text }]`, paths relative to the output directory. */
+export function renderC(resolved) {
+  const files = [{ path: 'omxcontract/omx_contract_limits.h', text: renderLimitsHeader(resolved) }];
+  const plugins = doors(resolved).PLUGINS;
+  for (const r of plugins) {
+    files.push({ path: `omxcontract/params/${r.header}`, text: generate({ header: r.header, prefix: r.prefix, source: r.source, producedBy: producedBy(r) }, r.value) });
+  }
+  if (plugins.length) files.push({ path: 'omxcontract/params/omx_plugin_param.h', text: PLUGIN_PARAM_H });
+  return files;
+}
+
+/**
+ * The `c` target of a frozen openmixer sheet (test/fixtures/): `{ sheet, plugins: [{ header, prefix,
+ * source, params }] }` rendered by openmixer's own renderer, for the round-trip proof (spec §4.4 step 1).
+ */
+export function renderSheetC(fixture) {
+  const s = fixture.sheet;
+  const sheet = { ...s, CORE_LIMITS: new Map(Object.entries(s.CORE_LIMITS)) };
+  const files = [{ path: 'omxcontract/omx_contract_limits.h', text: renderContractLimits(sheet) }];
+  for (const p of fixture.plugins) files.push({ path: `omxcontract/params/${p.header}`, text: generate(p, p.params) });
+  return files;
+}

package/render/doors.mjs

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The resolved data cut into the C renderer's doors, as openmixer's discovery cut its barrels
+ * (packages/core/src/native-limit-tables.ts, declared-scalars.ts, declared-lists.ts): a `travels`
+ * table named <PREFIX>_LIMITS is a native table; every scalar, sheet and single travel is scalars
+ * (its finite-number leaves, a travel's `unit`/`defaultFrom` labels skipped); a list is a declared
+ * list unless its item says `"c": { "render": false }`; a `c.alias` is the core-limit spelling.
+ */
+
+const constantCase = (key) => key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+const isSheet = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && Object.keys(v).length > 0;
+const isTravel = (v) => typeof v.min === 'number' && typeof v.max === 'number';
+const TRAVEL_LABELS = new Set(['unit', 'defaultFrom']);
+
+/** Every leaf of `v` when ALL its leaves are finite numbers; `undefined` when any is not (declared-scalars.ts). */
+function numberLeaves(v, path, macro) {
+  if (typeof v === 'number') return Number.isFinite(v) ? [{ path, macro, value: v }] : undefined;
+  if (!isSheet(v)) return undefined;
+  const out = [];
+  for (const [key, leaf] of Object.entries(v)) {
+    if (TRAVEL_LABELS.has(key) && typeof leaf === 'string' && !path.includes('.') && isTravel(v)) continue;
+    const leaves = numberLeaves(leaf, `${path}.${key}`, `${macro}_${constantCase(key)}`);
+    if (leaves === undefined) return undefined;
+    out.push(...leaves);
+  }
+  return out;
+}
+
+/** True for a `travels` table that is a native limit table (its name ends `_LIMITS`). */
+export const isNativeTable = (r) => r.kind === 'travels' && r.shape === 'table' && r.name.endsWith('_LIMITS');
+
+/** The doors of the resolved items (a Map name -> resolved item). */
+export function doors(resolved) {
+  const items = [...resolved.values()];
+  const NATIVE_LIMIT_TABLES = items.filter(isNativeTable)
+    .map((r) => [r.name.slice(0, -'_LIMITS'.length), r.value])
+    .sort(([a], [b]) => a.localeCompare(b));
+  const byMacro = new Map();
+  for (const r of items) {
+    if (isNativeTable(r) || r.kind === 'plugin' || r.kind === 'list') continue;
+    const leaves = numberLeaves(r.value, r.name, r.name.replace(/_(KERNEL|LIMITS)$/, ''));
+    if (leaves === undefined) continue;
+    for (const s of leaves) {
+      const seen = byMacro.get(s.macro);
+      if (seen) throw new Error(`${seen.path} and ${s.path} both render as OMX_${s.macro} — rename one`);
+      byMacro.set(s.macro, s);
+    }
+  }
+  const DECLARED_SCALARS = [...byMacro.values()].sort((a, b) => (a.macro < b.macro ? -1 : a.macro > b.macro ? 1 : 0));
+  const DECLARED_LISTS = items.filter((r) => r.kind === 'list' && r.c?.render !== false)
+    .map((r) => ({ name: r.name, values: r.value }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const ALIASES = new Map();
+  for (const r of items) {
+    if (!r.c?.alias) continue;
+    const { fact, field } = r.c.alias;
+    if (!ALIASES.has(fact)) ALIASES.set(fact, {});
+    ALIASES.get(fact)[field] = r.value;
+  }
+  const PLUGINS = items.filter((r) => r.kind === 'plugin');
+  const STANDARD_SAMPLE_RATES = resolved.get('STANDARD_SAMPLE_RATES')?.value;
+  return { NATIVE_LIMIT_TABLES, DECLARED_SCALARS, DECLARED_LISTS, ALIASES, PLUGINS, STANDARD_SAMPLE_RATES };
+}

package/render/json.mjs

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// 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.
+ */
+
+/** Every file of the `json` target: `[{ path, text }]`. */
+export function renderJson(resolved, version) {
+  const items = {};
+  for (const r of resolved.values()) {
+    const { name, ...rest } = r;
+    items[name] = rest;
+  }
+  return [{ path: 'omx-contract.json', text: `${JSON.stringify({ name: '@openmixer/omx-contract', version, items }, null, 2)}\n` }];
+}

package/render/ts.mjs

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The `ts` target: one ESM module and its type declarations, every item exported under its own
+ * name with its literal type (`as const`), so a re-export in openmixer keeps names, values and types.
+ */
+
+/** The value a TypeScript reader sees for one resolved item. */
+export function tsValue(r) {
+  if (r.kind !== 'plugin') return r.value;
+  return { plugin: r.plugin, header: r.header, prefix: r.prefix, params: r.value };
+}
+
+/** The literal type of a JSON value, every member readonly. */
+export function tsType(v, indent = '') {
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (typeof v === 'string') return JSON.stringify(v);
+  const inner = `${indent}  `;
+  if (Array.isArray(v)) return v.length ? `readonly [${v.map((x) => tsType(x, indent)).join(', ')}]` : 'readonly []';
+  const keys = Object.keys(v);
+  if (!keys.length) return '{}';
+  const key = (k) => (/^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k));
+  return `{\n${keys.map((k) => `${inner}readonly ${key(k)}: ${tsType(v[k], inner)};`).join('\n')}\n${indent}}`;
+}
+
+const docComment = (r) => {
+  const text = [r.doc, r.why && `Why: ${r.why}`].filter(Boolean).join('\n\n').replace(/\*\//g, '*\\/');
+  return `/**\n${text.split('\n').map((l) => (l ? ` * ${l}` : ' *')).join('\n')}\n * @see ${r.rel}\n */`;
+};
+
+const BANNER = `// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+// GENERATED by \`omx-contract render --target ts\` from FreeMixer/omx-contract's data/ — do not edit.
+`;
+
+/** Every file of the `ts` target: `[{ path, text }]`. */
+export function renderTs(resolved) {
+  const items = [...resolved.values()];
+  const js = BANNER + items.map((r) => `\n${docComment(r)}\nexport const ${r.name} = ${JSON.stringify(tsValue(r), null, 2)};\n`).join('');
+  const dts = BANNER + items.map((r) => `\n${docComment(r)}\nexport declare const ${r.name}: ${tsType(tsValue(r))};\n`).join('');
+  return [{ path: 'omx-contract.js', text: js }, { path: 'omx-contract.d.ts', text: dts }];
+}

package/schema/omx-contract.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/FreeMixer/omx-contract/raw/main/schema/omx-contract.schema.json",
+  "title": "omx-contract data file",
+  "description": "A map from an export name to one item: a scalar, a travels table or travel, a sheet, a list or a plugin's parameter selection. GPL-3.0-or-later.",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" }
+  },
+  "propertyNames": { "anyOf": [{ "const": "$schema" }, { "pattern": "^[A-Z][A-Z0-9_]*$" }] },
+  "additionalProperties": { "$ref": "#/$defs/item" },
+  "$defs": {
+    "unit": {
+      "description": "The closed list of units the items use; \"\" is a ratio or a fraction.",
+      "enum": ["dB", "dBFS", "ms", "s", "min", "Hz", "oct", "cents", "%", ""]
+    },
+    "text": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+    "ref": {
+      "type": "object",
+      "properties": { "ref": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*(\\.[A-Za-z][A-Za-z0-9]*)*$" } },
+      "required": ["ref"],
+      "additionalProperties": false
+    },
+    "derive": {
+      "description": "The closed list of derivations; a new one is a renderer change with its own test.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "derive": { "const": "count" }, "of": { "$ref": "#/$defs/name" } },
+          "required": ["derive", "of"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": { "derive": { "const": "sqrt" }, "of": { "$ref": "#/$defs/number" } },
+          "required": ["derive", "of"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "derive": { "const": "lagrangeReadL1" },
+            "order": { "oneOf": [{ "type": "integer", "minimum": 1 }, { "$ref": "#/$defs/ref" }] }
+          },
+          "required": ["derive", "order"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "number": { "oneOf": [{ "type": "number" }, { "$ref": "#/$defs/ref" }, { "$ref": "#/$defs/derive" }] },
+    "travel": {
+      "type": "object",
+      "properties": {
+        "min": { "$ref": "#/$defs/number" },
+        "max": { "$ref": "#/$defs/number" },
+        "step": { "$ref": "#/$defs/number" },
+        "unit": { "$ref": "#/$defs/unit" },
+        "default": { "$ref": "#/$defs/number" },
+        "defaultFrom": { "enum": ["desk"] },
+        "byKind": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+          "additionalProperties": { "$ref": "#/$defs/number" },
+          "minProperties": 1
+        },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" }
+      },
+      "required": ["min", "max"],
+      "additionalProperties": false
+    },
+    "sheetValue": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+      "additionalProperties": { "oneOf": [{ "$ref": "#/$defs/number" }, { "$ref": "#/$defs/sheetValue" }] },
+      "minProperties": 1
+    },
+    "scalar": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "scalar" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "unit": { "$ref": "#/$defs/unit" },
+        "value": { "oneOf": [{ "$ref": "#/$defs/number" }, { "type": "boolean" }] }
+      },
+      "required": ["kind", "doc", "unit", "value"],
+      "additionalProperties": false
+    },
+    "travels": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "travels" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "fields": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][A-Za-z0-9]*$" },
+          "additionalProperties": { "$ref": "#/$defs/travel" },
+          "minProperties": 1
+        },
+        "travel": { "$ref": "#/$defs/travel" },
+        "c": {
+          "type": "object",
+          "properties": {
+            "alias": {
+              "type": "object",
+              "properties": {
+                "fact": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" },
+                "field": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" }
+              },
+              "required": ["fact", "field"],
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": ["kind", "doc"],
+      "oneOf": [{ "required": ["fields"] }, { "required": ["travel"] }],
+      "additionalProperties": false
+    },
+    "sheet": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "sheet" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "value": { "$ref": "#/$defs/sheetValue" }
+      },
+      "required": ["kind", "doc", "value"],
+      "additionalProperties": false
+    },
+    "list": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "list" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "unit": { "$ref": "#/$defs/unit" },
+        "values": { "type": "array", "items": { "type": "number" }, "minItems": 1 },
+        "c": {
+          "type": "object",
+          "properties": { "render": { "type": "boolean" } },
+          "additionalProperties": false
+        }
+      },
+      "required": ["kind", "doc", "unit", "values"],
+      "additionalProperties": false
+    },
+    "param": {
+      "type": "object",
+      "properties": {
+        "symbol": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" },
+        "from": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*(\\.[a-z][A-Za-z0-9]*)?$" },
+        "forKind": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]*$" },
+        "flags": { "type": "array", "items": { "enum": ["toggle"] }, "uniqueItems": true },
+        "scale": { "enum": ["linear", "log"] },
+        "since": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+        "doc": { "$ref": "#/$defs/text" }
+      },
+      "required": ["symbol", "from", "scale", "since"],
+      "additionalProperties": false
+    },
+    "plugin": {
+      "type": "object",
+      "properties": {
+        "kind": { "const": "plugin" },
+        "doc": { "$ref": "#/$defs/text" },
+        "why": { "$ref": "#/$defs/text" },
+        "plugin": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "header": { "type": "string", "pattern": "^omx_[a-z0-9_]+_params\\.h$" },
+        "prefix": { "type": "string", "pattern": "^OMX_[A-Z0-9_]+$" },
+        "source": { "$ref": "#/$defs/text" },
+        "params": { "type": "array", "items": { "$ref": "#/$defs/param" }, "minItems": 1 }
+      },
+      "required": ["kind", "doc", "plugin", "header", "prefix", "source", "params"],
+      "additionalProperties": false
+    },
+    "item": {
+      "type": "object",
+      "required": ["kind"],
+      "properties": { "kind": { "enum": ["scalar", "travels", "sheet", "list", "plugin"] } },
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "scalar" } } }, "then": { "$ref": "#/$defs/scalar" } },
+        { "if": { "properties": { "kind": { "const": "travels" } } }, "then": { "$ref": "#/$defs/travels" } },
+        { "if": { "properties": { "kind": { "const": "sheet" } } }, "then": { "$ref": "#/$defs/sheet" } },
+        { "if": { "properties": { "kind": { "const": "list" } } }, "then": { "$ref": "#/$defs/list" } },
+        { "if": { "properties": { "kind": { "const": "plugin" } } }, "then": { "$ref": "#/$defs/plugin" } }
+      ]
+    }
+  }
+}