miravo 0.4.0 → 0.6.0

package/src/lib/le/le-template-exporter.test.ts

@@ -0,0 +1,527 @@
+import { describe, expect, test } from "bun:test";
+import type { ApplyDesiredState } from "./le-apply.ts";
+import { LE_DRIVER_IDS, LE_DRIVER_NAMES } from "./le-drivers.ts";
+import { buildLeExport } from "./le-template-exporter.ts";
+
+// ---------------------------------------------------------------------------
+// Minimal desired state builders
+// ---------------------------------------------------------------------------
+
+function makeOpcuaDevice(): ApplyDesiredState["devices"][number] {
+  return {
+    instanceId: "pump-001",
+    modelName: "pump",
+    protocol: "opcua",
+    deviceName: "pump-001",
+    browsePath: "area/line/pump-001",
+    endpoint: { host: "miravo.local", port: 4840 },
+    properties: [
+      { Key: "ServerURL", Value: "opc.tcp://miravo.local:4840" },
+      { Key: "SecurityPolicy", Value: "0" },
+      { Key: "SecurityMode", Value: "0" },
+    ],
+    tags: [
+      {
+        name: "ns=1;s=area/line/pump-001/rpm",
+        tagName: "rpm",
+        valueType: "float32",
+        properties: [],
+        unsPath: "area/line/pump-001/rpm",
+        access: "read",
+      },
+      {
+        name: "ns=1;s=area/line/pump-001/running",
+        tagName: "running",
+        valueType: "boolean",
+        properties: [],
+        unsPath: "area/line/pump-001/running",
+        access: "read",
+      },
+    ],
+  };
+}
+
+function makeModbusDevice(): ApplyDesiredState["devices"][number] {
+  return {
+    instanceId: "tank-001",
+    modelName: "tank",
+    protocol: "modbus",
+    deviceName: "tank-001",
+    browsePath: "area/line/tank-001",
+    endpoint: { host: "miravo.local", port: 502 },
+    properties: [
+      { Key: "networkAddress", Value: "miravo.local" },
+      { Key: "networkPort", Value: "502" },
+      { Key: "stationId", Value: "1" },
+    ],
+    tags: [
+      {
+        name: "H",
+        tagName: "level",
+        valueType: "float32",
+        properties: [
+          { Key: "address", Value: "0" },
+          { Key: "count", Value: "1" },
+        ],
+        unsPath: "area/line/tank-001/level",
+        access: "read",
+      },
+    ],
+  };
+}
+
+function makeMqttDevice(): ApplyDesiredState["devices"][number] {
+  return {
+    instanceId: "motor-001",
+    modelName: "motor",
+    protocol: "mqtt",
+    deviceName: "motor-001",
+    browsePath: "area/line/motor-001",
+    endpoint: { host: "miravo.local", port: 1883 },
+    properties: [
+      { Key: "BrokerAddress", Value: "miravo.local" },
+      { Key: "Port", Value: "1883" },
+    ],
+    tags: [
+      {
+        name: "area/line/motor-001/speed",
+        tagName: "speed",
+        valueType: "float32",
+        properties: [],
+        unsPath: "area/line/motor-001/speed",
+        access: "read",
+      },
+    ],
+  };
+}
+
+const PUMP_MODEL_JSON = [
+  {
+    id: "aaaaaaaa-0000-0000-0000-000000000001",
+    name: "PUMP",
+    version: 3,
+    dynamicAttributes: [
+      {
+        id: "bbbbbbbb-0000-0000-0000-000000000001",
+        name: "rpm",
+        dataType: "float",
+        unit: "rpm",
+        skipParentKey: false,
+        topicExpression: "devicehub.alias.{device}.rpm",
+        topic: "",
+      },
+    ],
+    staticAttributes: [
+      { id: "cccccccc-0000-0000-0000-000000000001", key: "miravo_managed", value: "true", type: 0 },
+      {
+        id: "cccccccc-0000-0000-0000-000000000002",
+        key: "miravo_template",
+        value: "__miravo_placeholder__",
+        type: 0,
+      },
+      {
+        id: "cccccccc-0000-0000-0000-000000000003",
+        key: "miravo_model",
+        value: "__miravo_placeholder__",
+        type: 0,
+      },
+      {
+        id: "cccccccc-0000-0000-0000-000000000004",
+        key: "miravo_instance",
+        value: "__miravo_placeholder__",
+        type: 0,
+      },
+    ],
+    parameters: [{ name: "device", value: "" }],
+  },
+];
+
+function makeDesiredState(
+  devices: ApplyDesiredState["devices"],
+  modelJson: unknown[] = PUMP_MODEL_JSON,
+): ApplyDesiredState {
+  const modelName = devices[0]?.modelName ?? "pump";
+  return {
+    devices,
+    models: [{ name: modelName.toUpperCase(), leDtJson: modelJson }],
+    instances: devices.map((d) => ({
+      instanceId: d.instanceId,
+      modelName: d.modelName,
+      dtInstanceName: d.instanceId,
+      dtModelName: d.modelName.toUpperCase(),
+      boundDeviceName: d.deviceName,
+      browsePath: d.browsePath,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JSON template structure
+// ---------------------------------------------------------------------------
+
+describe("buildLeExport — JSON template", () => {
+  test("top-level keys are devicehub, dtwin, stats", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as Record<string, unknown>;
+    expect(Object.keys(tpl).sort()).toEqual(["devicehub", "dtwin", "stats"]);
+  });
+
+  test("device uses driverId (not driverName) for opcua", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Dev: Record<string, unknown> }> };
+    };
+    const [first] = tpl.devicehub.Devs;
+    expect(first?.Dev["driverId"]).toBe(LE_DRIVER_IDS.opcua);
+    expect(first?.Dev["driverName"]).toBeUndefined();
+  });
+
+  test("device uses driverId for modbus", () => {
+    const { templateJson } = buildLeExport(
+      makeDesiredState(
+        [makeModbusDevice()],
+        PUMP_MODEL_JSON.map((m) => ({ ...m, name: "TANK" })),
+      ),
+      "demo",
+    );
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Dev: Record<string, unknown> }> };
+    };
+    expect(tpl.devicehub.Devs[0]?.Dev["driverId"]).toBe(LE_DRIVER_IDS.modbus);
+  });
+
+  test("device uses driverId for mqtt", () => {
+    const mqttModel = PUMP_MODEL_JSON.map((m) => ({ ...m, name: "MOTOR" }));
+    const { templateJson } = buildLeExport(makeDesiredState([makeMqttDevice()], mqttModel), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Dev: Record<string, unknown> }> };
+    };
+    expect(tpl.devicehub.Devs[0]?.Dev["driverId"]).toBe(LE_DRIVER_IDS.mqtt);
+  });
+
+  test("registers count matches tag count", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Registers: unknown[] }> };
+    };
+    expect(tpl.devicehub.Devs[0]?.Registers).toHaveLength(2);
+  });
+
+  test("device is stopped by default", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Dev: Record<string, unknown> }> };
+    };
+    expect(tpl.devicehub.Devs[0]?.Dev["stopped"]).toBe(true);
+  });
+
+  test("stats devices match devicehub devices by name", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Dev: { name: string } }> };
+      stats: { devices: Array<{ name: string }> };
+    };
+    const dhNames = tpl.devicehub.Devs.map((d) => d.Dev.name);
+    const statNames = tpl.stats.devices.map((d) => d.name);
+    expect(statNames).toEqual(dhNames);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractModelObjects — version stripping + parameter upgrade + static values
+// ---------------------------------------------------------------------------
+
+describe("buildLeExport — model transformation", () => {
+  test("strips version from model objects", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as { dtwin: { models: Array<Record<string, unknown>> } };
+    const [model] = tpl.dtwin.models;
+    expect(model?.["version"]).toBeUndefined();
+  });
+
+  test("upgrades bare {name,value} parameters to full form with id/ownerId/ownerType", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ parameters: Array<Record<string, unknown>> }> };
+    };
+    const [model] = tpl.dtwin.models;
+    const [param] = model?.parameters ?? [];
+    expect(typeof param?.["id"]).toBe("string");
+    expect(param?.["ownerType"]).toBe(2);
+  });
+
+  test("resolves miravo_template placeholder in model static attrs", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "my-template");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ staticAttributes: Array<{ key: string; value: string }> }> };
+    };
+    const [model] = tpl.dtwin.models;
+    const templateAttr = model?.staticAttributes.find((a) => a.key === "miravo_template");
+    expect(templateAttr?.value).toBe("my-template");
+  });
+
+  test("resolves miravo_model placeholder using lowercased model name", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ staticAttributes: Array<{ key: string; value: string }> }> };
+    };
+    const [model] = tpl.dtwin.models;
+    const modelAttr = model?.staticAttributes.find((a) => a.key === "miravo_model");
+    expect(modelAttr?.value).toBe("pump");
+  });
+
+  test("keeps miravo_instance placeholder unresolved at model level", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ staticAttributes: Array<{ key: string; value: string }> }> };
+    };
+    const [model] = tpl.dtwin.models;
+    const instAttr = model?.staticAttributes.find((a) => a.key === "miravo_instance");
+    // Cannot resolve per-instance value at model level
+    expect(instAttr?.value).toBe("__miravo_placeholder__");
+  });
+
+  test("replaces $param.* references with N/A", () => {
+    const [pumpModelBase] = PUMP_MODEL_JSON;
+    const modelWithParam = [
+      {
+        ...pumpModelBase,
+        staticAttributes: [{ id: "x", key: "label", value: "$param.device", type: 0 }],
+      },
+    ];
+    const { templateJson } = buildLeExport(
+      makeDesiredState([makeOpcuaDevice()], modelWithParam),
+      "demo",
+    );
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ staticAttributes: Array<{ key: string; value: string }> }> };
+    };
+    expect(tpl.dtwin.models[0]?.staticAttributes[0]?.value).toBe("N/A");
+  });
+
+  test("strips topicExpression from model dynamicAttributes", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ dynamicAttributes: Array<Record<string, unknown>> }> };
+    };
+    const [model] = tpl.dtwin.models;
+    const [dynAttr] = model?.dynamicAttributes ?? [];
+    expect(dynAttr?.["topicExpression"]).toBeUndefined();
+  });
+
+  test("sanitizes unit chars rejected by LE (/, ^, %)", () => {
+    const [pumpModelBase] = PUMP_MODEL_JSON;
+    const modelWithBadUnit = [
+      {
+        ...pumpModelBase,
+        dynamicAttributes: [
+          {
+            id: "bb",
+            name: "flow",
+            dataType: "float",
+            unit: "m^3/h",
+            skipParentKey: false,
+            topic: "",
+          },
+        ],
+      },
+    ];
+    const { templateJson } = buildLeExport(
+      makeDesiredState([makeOpcuaDevice()], modelWithBadUnit),
+      "demo",
+    );
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { models: Array<{ dynamicAttributes: Array<{ unit: string }> }> };
+    };
+    expect(tpl.dtwin.models[0]?.dynamicAttributes[0]?.unit).toBe("m3h");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Instance objects
+// ---------------------------------------------------------------------------
+
+describe("buildLeExport — instance objects", () => {
+  test("instance resolves miravo_instance to the instance name", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { instances: Array<{ staticAttributes: Array<{ key: string; value: string }> }> };
+    };
+    const instAttr = tpl.dtwin.instances[0]?.staticAttributes.find(
+      (a) => a.key === "miravo_instance",
+    );
+    expect(instAttr?.value).toBe("pump-001");
+  });
+
+  test("instance topicExpression is reconstructed from devicehub alias formula", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: {
+        instances: Array<{ dynamicAttributes: Array<{ topicExpression: string; name: string }> }>;
+      };
+    };
+    const [instance] = tpl.dtwin.instances;
+    const [dynAttr] = instance?.dynamicAttributes ?? [];
+    expect(dynAttr?.topicExpression).toBe(`devicehub.alias.{device}.${dynAttr?.name}`);
+  });
+
+  test("instance {device} parameter is overridden with the bound device name", () => {
+    const { templateJson } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      dtwin: { instances: Array<{ parameters: Array<{ name: string; value: string }> }> };
+    };
+    const deviceParam = tpl.dtwin.instances[0]?.parameters.find((p) => p.name === "device");
+    expect(deviceParam?.value).toBe("pump-001");
+  });
+
+  test("throws when instance references a missing model", () => {
+    const desired: ApplyDesiredState = {
+      devices: [makeOpcuaDevice()],
+      models: [], // model missing
+      instances: [
+        {
+          instanceId: "pump-001",
+          modelName: "pump",
+          dtInstanceName: "pump-001",
+          dtModelName: "PUMP",
+          boundDeviceName: "pump-001",
+          browsePath: "area/line/pump-001",
+        },
+      ],
+    };
+    expect(() => buildLeExport(desired, "demo")).toThrow('Model "PUMP" not found');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CSV structure
+// ---------------------------------------------------------------------------
+
+const CSV_COLUMN_COUNT = 17;
+
+function parseCSVRow(row: string): string[] {
+  const cols: string[] = [];
+  let i = 0;
+  while (i <= row.length) {
+    if (row[i] === '"') {
+      let field = "";
+      i++;
+      while (i < row.length) {
+        if (row[i] === '"' && row[i + 1] === '"') {
+          field += '"';
+          i += 2;
+        } else if (row[i] === '"') {
+          i++;
+          break;
+        } else {
+          field += row[i++];
+        }
+      }
+      cols.push(field);
+      if (row[i] === ",") i++;
+    } else {
+      const end = row.indexOf(",", i);
+      if (end === -1) {
+        cols.push(row.slice(i));
+        break;
+      }
+      cols.push(row.slice(i, end));
+      i = end + 1;
+    }
+  }
+  return cols;
+}
+
+function parseCSV(csv: string): string[][] {
+  return csv.trim().split("\n").map(parseCSVRow);
+}
+
+describe("buildLeExport — CSV structure", () => {
+  test("header has 17 columns", () => {
+    const { tagsCSV } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const [header] = parseCSV(tagsCSV);
+    expect(header).toHaveLength(CSV_COLUMN_COUNT);
+  });
+
+  test("OPC-UA rows have 17 columns", () => {
+    const { tagsCSV } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const rows = parseCSV(tagsCSV).slice(1); // skip header
+    for (const row of rows) {
+      expect(row).toHaveLength(CSV_COLUMN_COUNT);
+    }
+  });
+
+  test("Modbus rows have 17 columns with address and count populated", () => {
+    const modbusModel = PUMP_MODEL_JSON.map((m) => ({ ...m, name: "TANK" }));
+    const { tagsCSV } = buildLeExport(makeDesiredState([makeModbusDevice()], modbusModel), "demo");
+    const rows = parseCSV(tagsCSV).slice(1);
+    expect(rows).toHaveLength(1);
+    const [row] = rows;
+    expect(row).toHaveLength(CSV_COLUMN_COUNT);
+    // address col (index 13) = "0", count col (index 14) = "1"
+    expect(row?.[13]).toBe("0");
+    expect(row?.[14]).toBe("1");
+  });
+
+  test("MQTT rows have 17 columns", () => {
+    const mqttModel = PUMP_MODEL_JSON.map((m) => ({ ...m, name: "MOTOR" }));
+    const { tagsCSV } = buildLeExport(makeDesiredState([makeMqttDevice()], mqttModel), "demo");
+    const rows = parseCSV(tagsCSV).slice(1);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toHaveLength(CSV_COLUMN_COUNT);
+  });
+
+  test("CSV driverName uses human-readable names, not IDs", () => {
+    const { tagsCSV } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const rows = parseCSV(tagsCSV).slice(1);
+    // driverName is col index 2
+    expect(rows[0]?.[2]).toBe(LE_DRIVER_NAMES.opcua);
+  });
+
+  test("deviceId in CSV matches the device id in the JSON template", () => {
+    const { templateJson, tagsCSV } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as { devicehub: { Devs: Array<{ Dev: { id: string } }> } };
+    const deviceId = tpl.devicehub.Devs[0]?.Dev.id;
+
+    const rows = parseCSV(tagsCSV).slice(1);
+    // deviceId is col index 0
+    expect(rows[0]?.[0]).toBe(deviceId);
+  });
+
+  test("registerId in CSV matches the register id in the JSON template", () => {
+    const { templateJson, tagsCSV } = buildLeExport(makeDesiredState([makeOpcuaDevice()]), "demo");
+    const tpl = JSON.parse(templateJson) as {
+      devicehub: { Devs: Array<{ Registers: Array<{ id: string }> }> };
+    };
+    const [firstDev] = tpl.devicehub.Devs;
+    const registerIds = firstDev?.Registers.map((r) => r.id) ?? [];
+
+    const rows = parseCSV(tagsCSV).slice(1);
+    // registerId is col index 7
+    const csvRegisterIds = rows.map((row) => row[7]);
+    expect(csvRegisterIds).toEqual(registerIds);
+  });
+
+  test("CSV value with comma is quoted", () => {
+    const deviceWithComma = {
+      ...makeOpcuaDevice(),
+      tags: [
+        {
+          name: "ns=1;s=area,line/pump/rpm",
+          tagName: "rpm",
+          valueType: "float32",
+          properties: [],
+          unsPath: "area,line/pump/rpm",
+          access: "read" as const,
+        },
+      ],
+    };
+    const { tagsCSV } = buildLeExport(makeDesiredState([deviceWithComma]), "demo");
+    const [, row] = parseCSV(tagsCSV);
+    // With the proper CSV parser, a quoted field still gives exactly 17 columns
+    expect(row).toHaveLength(CSV_COLUMN_COUNT);
+    // The raw CSV line must contain a quoted field
+    const lines = tagsCSV.trim().split("\n");
+    expect(lines[1]).toContain('"');
+  });
+});