@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/itIcons.js

@@ -0,0 +1,84 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * IT / infrastructure icon and type extensions for ArchiMate diagrams.
+ *
+ * ArchiMate itself does not define element types for every IT artefact an
+ * enterprise architect actually draws — firewall, laptop, database table,
+ * container, and so on. This module provides a small, well-known catalog of
+ * such concepts so they can be used as custom types in `archimateDiagram`
+ * while still behaving like real ArchiMate elements: they resolve to a layer
+ * (almost always `technology`), an aspect (`active-structure` for devices and
+ * services, `passive-structure` for data/files), and an icon. They are NOT
+ * part of the official ArchiMate specification, so `ArchimateValidator` treats
+ * them as extended/custom types rather than standard ones.
+ *
+ * The registry is intentionally separate from `src/archimate.js` so the
+ * official catalog stays pure and spec-aligned; `ArchimateNotation` optionally
+ * merges these in when an `itIcons` flag is passed.
+ */
+
+import { ArchimateLayer, ArchimateNotation } from './archimate.js';
+
+/** One IT/infrastructure element type — layer, aspect, icon, and an optional
+ *  notation shape. Layer is usually 'technology'; aspect follows ArchiMate's
+ *  own meaning (active-structure = performs/provides behavior, passive-structure
+ *  = is acted upon). */
+export class ITElementType {
+    constructor(name, layer, aspect, icon, notationShape, description) {
+        this.name = name;
+        this.layer = layer;
+        this.aspect = aspect;
+        this.icon = icon;
+        this.notationShape = notationShape;
+        this.description = description;
+    }
+}
+
+const IT_ELEMENT_TYPES = new Map();
+const IT_ELEMENT_ROWS = [
+    // Active-structure devices and hardware
+    ['firewall', 'technology', 'active-structure', '🧱', undefined, 'A network security device that monitors and filters incoming/outgoing network traffic.'],
+    ['router', 'technology', 'active-structure', '🌐', undefined, 'A networking device that forwards data packets between computer networks.'],
+    ['switch', 'technology', 'active-structure', '🔀', undefined, 'A networking device that connects devices together on a computer network.'],
+    ['load-balancer', 'technology', 'active-structure', '⚖️', undefined, 'A device or service that distributes network traffic across multiple servers.'],
+    ['laptop', 'technology', 'active-structure', '💻', undefined, 'A portable personal computer used by an end user.'],
+    ['workstation', 'technology', 'active-structure', '🖥️', undefined, 'A high-performance personal computer used for technical or professional work.'],
+    ['server', 'technology', 'active-structure', '🖥️', undefined, 'A computer or program that provides functionality to other computers or programs.'],
+    ['mobile-device', 'technology', 'active-structure', '📱', undefined, 'A handheld computing device such as a smartphone.'],
+    ['tablet', 'technology', 'active-structure', '📱', undefined, 'A portable touchscreen computing device.'],
+    ['printer', 'technology', 'active-structure', '🖨️', undefined, 'A device that produces a hard copy of documents.'],
+    ['iot-device', 'technology', 'active-structure', '📡', undefined, 'An Internet-of-Things device that connects and exchanges data over a network.'],
+    // Active-structure software/runtime
+    ['container', 'technology', 'active-structure', '📦', undefined, 'A lightweight, standalone, executable package of software.'],
+    ['pod', 'technology', 'active-structure', '🛞', undefined, 'A group of one or more containers in a Kubernetes cluster.'],
+    ['virtual-machine', 'technology', 'active-structure', '💻', undefined, 'A software emulation of a physical computer.'],
+    ['api-gateway', 'technology', 'active-structure', '🚪', undefined, 'A service that manages, routes, and secures API requests.'],
+    // Passive-structure data/files
+    ['database', 'technology', 'passive-structure', '🗄️', undefined, 'A structured collection of data stored and accessed electronically.'],
+    ['table', 'technology', 'passive-structure', '📊', undefined, 'A structured set of data held in a database, consisting of rows and columns.'],
+    ['file', 'technology', 'passive-structure', '📄', undefined, 'A named collection of data stored on a computer system.'],
+    ['folder', 'technology', 'passive-structure', '📁', undefined, 'A container for organising files.'],
+    ['bucket', 'technology', 'passive-structure', '🪣', undefined, 'A cloud-storage container for objects such as files and backups.'],
+    ['queue', 'technology', 'passive-structure', '📬', undefined, 'A temporary holding structure for messages or tasks waiting to be processed.'],
+    // Composite / other
+    ['cloud-region', 'technology', 'active-structure', '☁️', undefined, 'A geographic area of a cloud provider that contains one or more data centres.'],
+    ['datacentre', 'technology', 'active-structure', '🏢', undefined, 'A facility used to house computer systems and associated components.'],
+    ['network', 'technology', 'active-structure', '📡', undefined, 'A group of interconnected computers and devices that can exchange data.'],
+];
+
+for (const [name, layerKey, aspect, icon, notationShape, description] of IT_ELEMENT_ROWS) {
+    const layer = ArchimateNotation.layer(layerKey);
+    IT_ELEMENT_TYPES.set(name, new ITElementType(name, layer, aspect, icon, notationShape, description));
+}
+
+/** Registry for looking up IT/infrastructure element types. */
+export const ITIconNotation = {
+    /** Every IT element type, in catalog order. */
+    elementTypes() { return [...IT_ELEMENT_TYPES.values()]; },
+    /** Just the names. */
+    elementTypeNames() { return [...IT_ELEMENT_TYPES.keys()]; },
+    /** An IT element type by name, or undefined. */
+    elementType(name) { return IT_ELEMENT_TYPES.get(name); },
+    /** Whether a name is a known IT element type. */
+    has(name) { return IT_ELEMENT_TYPES.has(name); },
+};

package/src/kernelExpr.js

@@ -0,0 +1,243 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * A small scalar expression language for computed chart encodings — letting
+ * `colorCol`/similar options be a FORMULA over a data point's own fields
+ * ("value > threshold ? 1 : 0") instead of only a plain field name.
+ *
+ * This is renderengine's own copy of sqlengine's
+ * `src/compute/kernel/parseKernel.js` grammar, adapted to compile a single
+ * ROW at a time (one JS number per parameter in, one number out) rather than
+ * a whole column, since a chart evaluates an encoding once per data point,
+ * not once per query. Kept as a standalone copy rather than a shared
+ * dependency — the two repos have no package link today, and this grammar is
+ * small enough that duplicating it costs less than a cross-repo dependency
+ * would. See renderengine's own `tasks.md` for why this exists, and
+ * sqlengine's `documentation/kernel-language.md` for the full grammar
+ * reference this is a subset of.
+ *
+ * DELIBERATELY SMALL, same reasoning as the original: scalar arithmetic,
+ * comparisons, a fixed set of maths functions, and a conditional. No loops,
+ * no state, no calls out — anything outside that stays an ordinary
+ * JavaScript option (a function passed directly), which still works.
+ *
+ * NO GPU/WASM/WebNN TARGETS HERE, unlike the sqlengine original — renderengine
+ * has no compute-backend concept and nothing has measured a need for one for
+ * per-point chart encodings (see tasks.md's "Gated on a measurement" entry).
+ * This only ever emits JavaScript.
+ */
+
+/** The functions a formula may call, with how many arguments each takes. */
+export const KERNEL_FUNCTIONS = {
+  abs: 1, floor: 1, ceil: 1, round: 1, sign: 1, sqrt: 1,
+  exp: 1, log: 1, sin: 1, cos: 1, tanh: 1,
+  min: 2, max: 2, pow: 2, clamp: 3,
+};
+
+const FN_NAMES = {
+  abs: 'Math.abs', floor: 'Math.floor', ceil: 'Math.ceil', round: 'Math.round',
+  sign: 'Math.sign', sqrt: 'Math.sqrt', exp: 'Math.exp', log: 'Math.log',
+  sin: 'Math.sin', cos: 'Math.cos', tanh: 'Math.tanh', min: 'Math.min',
+  max: 'Math.max', pow: 'Math.pow', clamp: '__clamp',
+};
+
+/**
+ * Parse a formula into `{ast, params}`.
+ * @param {string} source — e.g. `value > threshold ? 1 : 0`
+ * @param {string[]} params — the names the formula may read
+ */
+export function parseKernelExpr(source, params) {
+  if (typeof source !== 'string' || source.trim() === '')
+    throw new Error('parseKernelExpr: the formula is empty');
+  if (!Array.isArray(params) || params.length === 0)
+    throw new Error('parseKernelExpr: at least one parameter name is required');
+  for (const p of params) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(p))
+      throw new Error(`parseKernelExpr: '${p}' is not a usable parameter name`);
+    if (p in KERNEL_FUNCTIONS)
+      throw new Error(`parseKernelExpr: '${p}' is the name of a built-in function`);
+  }
+
+  const tokens = _tokenize(source);
+  const state  = { tokens, at: 0, params: new Set(params) };
+  const ast    = _parseTernary(state);
+
+  if (state.at < tokens.length)
+    throw new Error(
+      `parseKernelExpr: unexpected '${tokens[state.at].value}' at position ${tokens[state.at].pos}. ` +
+      `This formula language is a single scalar expression — no statements, no assignment.`);
+
+  return { ast, params: [...params] };
+}
+
+// ── Tokenizer ───────────────────────────────────────────────────────────────
+
+const PUNCTUATION = ['<=', '>=', '==', '!=', '&&', '||',
+                     '+', '-', '*', '/', '%', '<', '>', '(', ')', ',', '?', ':', '!'];
+
+function _tokenize(src) {
+  const out = [];
+  let i = 0;
+  while (i < src.length) {
+    const ch = src[i];
+    if (/\s/.test(ch)) { i++; continue; }
+
+    if (/[0-9.]/.test(ch)) {
+      const m = /^\d*\.?\d+(?:[eE][+-]?\d+)?/.exec(src.slice(i));
+      if (!m) throw new Error(`parseKernelExpr: malformed number at position ${i}`);
+      out.push({ type: 'number', value: Number(m[0]), pos: i });
+      i += m[0].length;
+      continue;
+    }
+
+    if (/[A-Za-z_]/.test(ch)) {
+      const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(src.slice(i));
+      out.push({ type: 'name', value: m[0], pos: i });
+      i += m[0].length;
+      continue;
+    }
+
+    // Two-character operators listed first, so `<=` is never read as `<`
+    // followed by something the parser will not recognise.
+    const punct = PUNCTUATION.find(p => src.startsWith(p, i));
+    if (!punct)
+      throw new Error(`parseKernelExpr: '${ch}' at position ${i} is not part of this formula language`);
+    out.push({ type: 'punct', value: punct, pos: i });
+    i += punct.length;
+  }
+  return out;
+}
+
+// ── Recursive descent, lowest precedence outermost ──────────────────────────
+
+const _peek = (s) => s.tokens[s.at];
+const _eat  = (s, value) => {
+  const t = _peek(s);
+  if (t && t.type === 'punct' && t.value === value) { s.at++; return true; }
+  return false;
+};
+const _expect = (s, value) => {
+  if (!_eat(s, value)) {
+    const t = _peek(s);
+    throw new Error(
+      `parseKernelExpr: expected '${value}' but found ` +
+      (t ? `'${t.value}' at position ${t.pos}` : 'the end of the expression'));
+  }
+};
+
+function _parseTernary(s) {
+  const cond = _parseBinary(s, 0);
+  if (!_eat(s, '?')) return cond;
+  const then = _parseTernary(s);
+  _expect(s, ':');
+  const other = _parseTernary(s);
+  return { kind: 'cond', cond, then, else: other };
+}
+
+/** Precedence tiers, loosest first. */
+const TIERS = [['||'], ['&&'], ['==', '!='], ['<', '<=', '>', '>='], ['+', '-'], ['*', '/', '%']];
+
+function _parseBinary(s, tier) {
+  if (tier >= TIERS.length) return _parseUnary(s);
+  let left = _parseBinary(s, tier + 1);
+  for (;;) {
+    const t = _peek(s);
+    if (!t || t.type !== 'punct' || !TIERS[tier].includes(t.value)) return left;
+    s.at++;
+    const right = _parseBinary(s, tier + 1);
+    left = { kind: 'binary', op: t.value, left, right };
+  }
+}
+
+function _parseUnary(s) {
+  if (_eat(s, '-')) return { kind: 'neg', operand: _parseUnary(s) };
+  if (_eat(s, '!')) return { kind: 'not', operand: _parseUnary(s) };
+  return _parsePrimary(s);
+}
+
+function _parsePrimary(s) {
+  const t = _peek(s);
+  if (!t) throw new Error('parseKernelExpr: the expression ends where a value was expected');
+
+  if (_eat(s, '(')) {
+    const inner = _parseTernary(s);
+    _expect(s, ')');
+    return inner;
+  }
+
+  if (t.type === 'number') { s.at++; return { kind: 'literal', value: t.value }; }
+
+  if (t.type === 'name') {
+    s.at++;
+    const argCount = KERNEL_FUNCTIONS[t.value];
+    if (argCount != null) {
+      _expect(s, '(');
+      const args = [];
+      if (!_eat(s, ')')) {
+        do { args.push(_parseTernary(s)); } while (_eat(s, ','));
+        _expect(s, ')');
+      }
+      if (args.length !== argCount)
+        throw new Error(
+          `parseKernelExpr: ${t.value}() takes ${argCount} argument${argCount === 1 ? '' : 's'}, ` +
+          `not ${args.length}`);
+      return { kind: 'call', name: t.value, args };
+    }
+
+    if (!s.params.has(t.value))
+      throw new Error(
+        `parseKernelExpr: '${t.value}' is neither a parameter nor a built-in function. ` +
+        `Parameters here are ${[...s.params].join(', ')}; functions are ` +
+        `${Object.keys(KERNEL_FUNCTIONS).join(', ')}.`);
+    return { kind: 'param', name: t.value };
+  }
+
+  throw new Error(`parseKernelExpr: unexpected '${t.value}' at position ${t.pos}`);
+}
+
+// ── JavaScript emission ──────────────────────────────────────────────────────
+
+function _emitJs(node) {
+  const go = (n) => {
+    switch (n.kind) {
+      case 'literal': return `${n.value}`;
+      case 'param':   return n.name;
+      case 'neg':     return `(-${go(n.operand)})`;
+      case 'not':     return `(${go(n.operand)} === 0 ? 1 : 0)`;
+      case 'cond':    return `((${go(n.cond)}) !== 0 ? ${go(n.then)} : ${go(n.else)})`;
+      case 'binary': {
+        const l = go(n.left), r = go(n.right);
+        if (n.op === '&&' || n.op === '||')
+          return `(((${l}) !== 0 ${n.op} (${r}) !== 0) ? 1 : 0)`;
+        if (['<', '<=', '>', '>=', '==', '!='].includes(n.op))
+          return `((${l} ${n.op === '==' ? '===' : n.op === '!=' ? '!==' : n.op} ${r}) ? 1 : 0)`;
+        return `(${l} ${n.op} ${r})`;
+      }
+      case 'call': {
+        const args = n.args.map(go).join(', ');
+        return `${FN_NAMES[n.name]}(${args})`;
+      }
+      default: throw new Error(`_emitJs: unknown node '${n.kind}'`);
+    }
+  };
+  return go(node);
+}
+
+/**
+ * Compile a formula to a callable JavaScript function — `fn(...paramValues)
+ * -> number`. Built with `new Function` from an expression THIS module
+ * generated, not from anything a caller passed in directly: the parser
+ * accepts only its own small grammar, so arbitrary text never reaches the
+ * function body, the same reasoning sqlengine's compiled UDFs rely on.
+ *
+ * @param {string} source
+ * @param {string[]} params
+ * @returns {(...values: number[]) => number}
+ */
+export function compileFormula(source, params) {
+  const { ast } = parseKernelExpr(source, params);
+  const __clamp = (x, lo, hi) => Math.min(Math.max(x, lo), hi);
+  const body = `return ${_emitJs(ast)};`;
+  // eslint-disable-next-line no-new-func
+  const fn = new Function('__clamp', ...params, body);
+  return (...values) => fn(__clamp, ...values);
+}