iobroker.statechart 0.1.1 → 0.2.0

package/lib/chart-structure.js

@@ -1,106 +0,0 @@
-"use strict";
-
-/*
- * The structure of a chart (hierarchy, transition order, kind of transitions) as the runtime executes it.
- * Shared by the runtime and the code generator, so the generated code always shows what is executed.
- */
-
-/**
- * @typedef {import("./chart-model").Chart} Chart
- * @typedef {import("./chart-model").ChartState} ChartState
- * @typedef {import("./chart-model").ChartTransition} ChartTransition
- */
-
-class ChartStructure {
-    /**
-     * @param {Chart} chart
-     */
-    constructor(chart) {
-        this.chart = chart;
-        /** @type {Map<string, ChartState>} */
-        this.statesById = new Map(chart.states.map(s => [s.id, s]));
-        /** @type {Map<string, ChartState[]>} children by parent ID, "" for the top level */
-        this.childrenByParent = new Map();
-        for (const state of chart.states) {
-            // states with an unknown parent are treated like top level states
-            const parent = state.parent && this.statesById.has(state.parent) ? state.parent : "";
-            this.childrenByParent.set(parent, [...(this.childrenByParent.get(parent) || []), state]);
-        }
-        /** @type {Map<string, ChartTransition[]>} transitions by source, sorted by priority */
-        this.transitionsBySource = new Map();
-        for (const transition of chart.transitions) {
-            const list = this.transitionsBySource.get(transition.source) || [];
-            this.transitionsBySource.set(transition.source, [...list, transition]);
-        }
-        for (const list of this.transitionsBySource.values()) {
-            // the sort is stable: transitions without priority keep their order, after the others
-            list.sort((a, b) => (a.priority ?? Number.MAX_SAFE_INTEGER) - (b.priority ?? Number.MAX_SAFE_INTEGER));
-        }
-    }
-
-    /**
-     * @param {string | null} parentId null for the top level
-     * @returns {ChartState[]}
-     */
-    getChildren(parentId) {
-        return this.childrenByParent.get(parentId || "") || [];
-    }
-
-    /**
-     * The initial state of a level: the configured one if it is a child of this level, otherwise the first child
-     *
-     * @param {string | null} parentId null for the top level
-     * @returns {string | undefined} undefined if the level has no states
-     */
-    getInitialChild(parentId) {
-        const children = this.getChildren(parentId);
-        const configured = parentId ? this.statesById.get(parentId)?.initial : this.chart.initial;
-        return children.some(s => s.id === configured) ? configured : children[0]?.id;
-    }
-
-    /**
-     * @param {string} stateId
-     * @returns {ChartTransition[]} the transitions starting at the state, sorted by priority
-     */
-    getTransitions(stateId) {
-        return this.transitionsBySource.get(stateId) || [];
-    }
-
-    /**
-     * @param {string} ancestorId
-     * @param {string} id
-     * @returns {boolean} true if the state "id" is a (direct or indirect) child of "ancestorId"
-     */
-    isDescendant(ancestorId, id) {
-        let parent = this.statesById.get(id)?.parent;
-        // the counter protects against cycles in invalid charts
-        for (let i = 0; parent && i < this.statesById.size; i++) {
-            if (parent === ancestorId) {
-                return true;
-            }
-            parent = this.statesById.get(parent)?.parent;
-        }
-        return false;
-    }
-
-    /**
-     * How a transition is executed
-     *
-     * @param {ChartTransition} transition
-     * @returns {{ inner: boolean; reenter: boolean }} inner: checked after the during action of the source,
-     *     the source stays active. reenter: the source state is left and entered again (XState "reenter").
-     */
-    getTransitionKind(transition) {
-        const { source, target } = transition;
-        const toChild = this.isDescendant(source, target);
-        // an inner transition stays in the source state, only its active child is left
-        const inner = toChild && !transition.reenterParent;
-        // Like Stateflow, the source state is left and entered again by self transitions, by transitions
-        // to an own child which should re-enter the parent, and by transitions from a child to its parent.
-        // Without "reenter", XState does not leave the source state if the target is a child of it.
-        const reenter = source === target || (toChild && !inner) || this.isDescendant(target, source);
-        return { inner, reenter };
-    }
-}
-
-module.exports = { ChartStructure };

package/lib/chart-validation.js

@@ -1,328 +0,0 @@
-"use strict";
-
-/*
- * Checks conditions and actions of a chart: JavaScript syntax, unknown variables and events.
- * Used by the editor (to underline errors) and by the runtime (to log them when a chart starts).
- */
-
-const acorn = require("acorn");
-const walk = require("acorn-walk");
-const { HELPERS } = require("./chart-helpers");
-const { LabelSyntaxError, formatMessage, parseTransitionLabelWithRanges } = require("./chart-model");
-
-/**
- * @typedef {import("./chart-model").Chart} Chart
- * @typedef {import("./chart-model").ChartSymbol} ChartSymbol
- */
-
-/** Names which can be used in conditions and actions besides the chart variables */
-const GLOBALS = new Set([
-    // the helper functions, e.g. log() and setState()
-    ...Object.keys(HELPERS),
-    "undefined",
-    "NaN",
-    "Infinity",
-    "Math",
-    "Date",
-    "JSON",
-    "Number",
-    "String",
-    "Boolean",
-    "Array",
-    "Object",
-    "RegExp",
-    "Map",
-    "Set",
-    "Error",
-    "parseInt",
-    "parseFloat",
-    "isNaN",
-    "isFinite",
-    "encodeURIComponent",
-    "decodeURIComponent",
-]);
-
-/** Fields of a state which contain actions */
-const STATE_ACTIONS = /** @type {const} */ (["entry", "during", "exit"]);
-
-/**
- * @typedef {object} Diagnostic
- * @property {number} from Position in the checked text
- * @property {number} to
- * @property {"error" | "warning"} severity
- * @property {string} message English message
- * @property {string} key Message with %s placeholders, used to translate it
- * @property {string[]} args
- */
-
-/**
- * @param {number} from
- * @param {number} to
- * @param {"error" | "warning"} severity
- * @param {string} key
- * @param {string[]} [args]
- * @returns {Diagnostic}
- */
-function createDiagnostic(from, to, severity, key, args = []) {
-    return { from, to, severity, key, args, message: formatMessage(key, args) };
-}
-
-/**
- * Parses JavaScript and converts syntax errors to diagnostics
- *
- * @param {string} code
- * @param {"expression" | "statements"} kind
- * @returns {{ ast: acorn.Node } | { diagnostic: Diagnostic }}
- */
-function parseCode(code, kind) {
-    try {
-        if (kind === "statements") {
-            return { ast: acorn.parse(code, { ecmaVersion: "latest", sourceType: "script" }) };
-        }
-        const ast = acorn.parseExpressionAt(code, 0, { ecmaVersion: "latest" });
-        const rest = code.substring(ast.end);
-        if (rest.trim()) {
-            const from = ast.end + rest.length - rest.trimStart().length;
-            return { diagnostic: createDiagnostic(from, code.length, "error", 'Unexpected "%s"', [rest.trim()]) };
-        }
-        return { ast };
-    } catch (err) {
-        const pos = typeof err.pos === "number" ? Math.min(err.pos, code.length) : 0;
-        // acorn adds the position "(line:column)" to its messages, it is shown by the underline anyway
-        const message = String(err.message).replace(/\s*\(\d+:\d+\)$/, "");
-        // underline the token at the error position, or the last character if the code ends unexpectedly
-        const from = pos < code.length ? pos : Math.max(0, code.length - 1);
-        const token = /^(\w+|\S)/.exec(code.substring(from));
-        const to = Math.min(code.length, from + (token ? token[0].length : 1));
-        return { diagnostic: createDiagnostic(from, to, "error", "Syntax error: %s", [message]) };
-    }
-}
-
-/**
- * Checks a condition or action
- *
- * @param {string | undefined} code
- * @param {"expression" | "statements"} kind Condition (expression) or action (statements)
- * @param {ChartSymbol[]} symbols
- * @param {number} [offset] Position of the code in the text, added to all positions
- * @param {string[]} [functionNames] Names declared in the function blocks of the chart
- * @returns {Diagnostic[]}
- */
-function validateCode(code, kind, symbols, offset = 0, functionNames = []) {
-    if (!code?.trim()) {
-        return [];
-    }
-    const parsed = parseCode(code, kind);
-    if ("diagnostic" in parsed) {
-        const d = parsed.diagnostic;
-        return [{ ...d, from: d.from + offset, to: d.to + offset }];
-    }
-
-    /** names declared in the code itself (let, const, function parameters, ...) */
-    const declared = new Set();
-    /** @type {{ node: any; write: boolean }[]} */
-    const references = [];
-    walk.fullAncestor(parsed.ast, (node, _state, ancestors, type) => {
-        if (node.type !== "Identifier") {
-            return;
-        }
-        /** @type {any} */
-        const parent = ancestors[ancestors.length - 2];
-        if (type === "VariablePattern") {
-            // acorn-walk uses "VariablePattern" for declarations and for assignment targets
-            if (parent?.type === "AssignmentExpression" && parent.left === node) {
-                references.push({ node, write: true });
-            } else {
-                declared.add(node.name);
-            }
-        } else {
-            references.push({ node, write: parent?.type === "UpdateExpression" });
-        }
-    });
-
-    const inputs = new Set(symbols.filter(s => s.scope === "input").map(s => s.name));
-    const known = new Set([...symbols.map(s => s.name), ...functionNames]);
-    /** @type {Diagnostic[]} */
-    const diagnostics = [];
-    for (const { node, write } of references) {
-        const from = node.start + offset;
-        const to = node.end + offset;
-        if (!known.has(node.name) && !declared.has(node.name) && !GLOBALS.has(node.name)) {
-            diagnostics.push(createDiagnostic(from, to, "error", 'Unknown variable "%s"', [node.name]));
-        } else if (write && inputs.has(node.name) && !declared.has(node.name)) {
-            diagnostics.push(
-                createDiagnostic(from, to, "warning", 'Input "%s" is overwritten on its next change', [node.name]),
-            );
-        }
-    }
-    return diagnostics;
-}
-
-/**
- * Checks a transition label: its structure, the event and the JavaScript of condition and action
- *
- * @param {string | undefined} label
- * @param {ChartSymbol[]} symbols
- * @param {string[]} [functionNames] Names declared in the function blocks of the chart
- * @returns {Diagnostic[]}
- */
-function validateTransitionLabel(label, symbols, functionNames = []) {
-    let parsed;
-    try {
-        parsed = parseTransitionLabelWithRanges(label);
-    } catch (err) {
-        if (err instanceof LabelSyntaxError) {
-            return [createDiagnostic(err.from, err.to, "error", err.key, err.args)];
-        }
-        throw err;
-    }
-    const { label: parts, ranges } = parsed;
-
-    /** @type {Diagnostic[]} */
-    const diagnostics = [];
-    if (parts.event && ranges.event && !symbols.some(s => s.scope === "input" && s.name === parts.event)) {
-        diagnostics.push(
-            createDiagnostic(
-                ranges.event.from,
-                ranges.event.to,
-                "error",
-                'Unknown event "%s", use the name of an input',
-                [parts.event],
-            ),
-        );
-    }
-    if (parts.condition && ranges.condition) {
-        diagnostics.push(...validateCode(parts.condition, "expression", symbols, ranges.condition.from, functionNames));
-    }
-    if (parts.action && ranges.action) {
-        diagnostics.push(...validateCode(parts.action, "statements", symbols, ranges.action.from, functionNames));
-    }
-    return diagnostics;
-}
-
-/**
- * @typedef {object} Declaration A name declared at the top level of a function block
- * @property {string} name
- * @property {string | null} signature e.g. "clamp(x, lo, hi)", null if it is no function
- * @property {number} from Position of the name in the code
- * @property {number} to
- */
-
-/**
- * Finds the names declared at the top level of a function block: functions, but also constants etc.
- *
- * @param {string | undefined} code
- * @returns {Declaration[]} empty if the code has syntax errors
- */
-function getDeclarations(code) {
-    if (!code?.trim()) {
-        return [];
-    }
-    const parsed = parseCode(code, "statements");
-    if ("diagnostic" in parsed) {
-        return [];
-    }
-    /**
-     * @param {any} fn Function node
-     * @param {string} name
-     */
-    const signature = (fn, name) => `${name}(${fn.params.map(p => code.substring(p.start, p.end)).join(", ")})`;
-
-    /** @type {Declaration[]} */
-    const declarations = [];
-    for (const node of /** @type {any} */ (parsed.ast).body) {
-        if (node.type === "FunctionDeclaration" && node.id) {
-            const { name, start, end } = node.id;
-            declarations.push({ name, signature: signature(node, name), from: start, to: end });
-        } else if (node.type === "VariableDeclaration") {
-            for (const declarator of node.declarations) {
-                if (declarator.id.type !== "Identifier") {
-                    continue;
-                }
-                const { name, start, end } = declarator.id;
-                const init = declarator.init;
-                const isFunction = init?.type === "ArrowFunctionExpression" || init?.type === "FunctionExpression";
-                declarations.push({ name, signature: isFunction ? signature(init, name) : null, from: start, to: end });
-            }
-        }
-    }
-    return declarations;
-}
-
-/**
- * Names declared in all function blocks of a chart
- *
- * @param {Chart} chart
- * @returns {string[]}
- */
-function getFunctionNames(chart) {
-    return (chart.functions || []).flatMap(fn => getDeclarations(fn.code).map(d => d.name));
-}
-
-/**
- * @typedef {object} ChartProblem
- * @property {"state" | "transition" | "function"} kind
- * @property {string} id ID of the state, transition or function block
- * @property {string} field "entry", "during", "exit", "label" or "code"
- * @property {Diagnostic} diagnostic
- */
-
-/**
- * Checks all actions, transition labels and function blocks of a chart
- *
- * @param {Chart} chart
- * @returns {ChartProblem[]}
- */
-function validateChart(chart) {
-    const functionNames = getFunctionNames(chart);
-    /** @type {ChartProblem[]} */
-    const problems = [];
-    for (const state of chart.states) {
-        for (const field of STATE_ACTIONS) {
-            for (const diagnostic of validateCode(state[field], "statements", chart.symbols, 0, functionNames)) {
-                problems.push({ kind: "state", id: state.id, field, diagnostic });
-            }
-        }
-    }
-    for (const transition of chart.transitions) {
-        for (const diagnostic of validateTransitionLabel(transition.label, chart.symbols, functionNames)) {
-            problems.push({ kind: "transition", id: transition.id, field: "label", diagnostic });
-        }
-    }
-
-    // a name may only be declared once in all function blocks, and not hide a variable
-    const symbolNames = new Set(chart.symbols.map(s => s.name));
-    const seen = new Set();
-    for (const fn of chart.functions || []) {
-        for (const diagnostic of validateCode(fn.code, "statements", chart.symbols, 0, functionNames)) {
-            problems.push({ kind: "function", id: fn.id, field: "code", diagnostic });
-        }
-        for (const { name, from, to } of getDeclarations(fn.code)) {
-            let key = null;
-            if (seen.has(name)) {
-                key = '"%s" is declared in more than one function block';
-            } else if (symbolNames.has(name) || GLOBALS.has(name)) {
-                key = '"%s" is already the name of a variable';
-            }
-            if (key) {
-                problems.push({
-                    kind: "function",
-                    id: fn.id,
-                    field: "code",
-                    diagnostic: createDiagnostic(from, to, "error", key, [name]),
-                });
-            }
-            seen.add(name);
-        }
-    }
-    return problems;
-}
-
-module.exports = {
-    GLOBALS,
-    getDeclarations,
-    getFunctionNames,
-    validateChart,
-    validateCode,
-    validateTransitionLabel,
-};

package/lib/chart-validation.test.js

@@ -1,149 +0,0 @@
-"use strict";
-
-const { expect } = require("chai");
-const { getDeclarations, validateChart, validateCode, validateTransitionLabel } = require("./chart-validation");
-
-/** @type {import("./chart-model").ChartSymbol[]} */
-const symbols = [
-    { name: "motion", scope: "input", stateId: "test.0.motion" },
-    { name: "light", scope: "output", stateId: "test.0.light" },
-    { name: "count", scope: "local", initial: 0 },
-];
-
-/**
- * @param {import("./chart-validation").Diagnostic[]} diagnostics
- * @param {string} text
- */
-const summarize = (diagnostics, text) =>
-    diagnostics.map(d => `${d.severity}: ${d.message} @${text.substring(d.from, d.to)}`);
-
-describe("chart-validation => validateCode", () => {
-    it("accepts valid code", () => {
-        expect(validateCode("light = motion && count > 1; log(Math.max(1, 2));", "statements", symbols)).to.deep.equal(
-            [],
-        );
-        expect(validateCode("", "statements", symbols)).to.deep.equal([]);
-    });
-
-    it("reports unknown variables with their position", () => {
-        const code = "light = motoin;";
-        expect(summarize(validateCode(code, "statements", symbols), code)).to.deep.equal([
-            'error: Unknown variable "motoin" @motoin',
-        ]);
-    });
-
-    it("knows variables declared in the code", () => {
-        const code = "let x = 1; const f = (a) => a + x; for (const i of [1]) { light = f(i); }";
-        expect(validateCode(code, "statements", symbols)).to.deep.equal([]);
-    });
-
-    it("ignores property names", () => {
-        expect(validateCode("light = { on: true }.on && JSON.parse('1').foo;", "statements", symbols)).to.deep.equal(
-            [],
-        );
-    });
-
-    it("warns when an input is assigned", () => {
-        const code = "motion = false; count++;";
-        expect(summarize(validateCode(code, "statements", symbols), code)).to.deep.equal([
-            'warning: Input "motion" is overwritten on its next change @motion',
-        ]);
-    });
-
-    it("reports syntax errors", () => {
-        const code = "light = = true;";
-        const diagnostics = validateCode(code, "statements", symbols);
-        expect(diagnostics).to.have.length(1);
-        expect(diagnostics[0].message).to.match(/^Syntax error: Unexpected token/);
-        expect(code.substring(diagnostics[0].from, diagnostics[0].to)).to.equal("=");
-    });
-
-    it("rejects statements in conditions", () => {
-        const code = "motion; light = 1";
-        expect(summarize(validateCode(code, "expression", symbols), code)).to.deep.equal([
-            'error: Unexpected "; light = 1" @; light = 1',
-        ]);
-    });
-});
-
-describe("chart-validation => validateTransitionLabel", () => {
-    it("accepts valid labels", () => {
-        expect(validateTransitionLabel("motion[motion && count < 3]{count++;}", symbols)).to.deep.equal([]);
-        expect(validateTransitionLabel("after(5, sec)", symbols)).to.deep.equal([]);
-    });
-
-    it("reports problems at their position in the label", () => {
-        const label = "motoin[motion && lightt]{light = tru;}";
-        expect(summarize(validateTransitionLabel(label, symbols), label)).to.deep.equal([
-            'error: Unknown event "motoin", use the name of an input @motoin',
-            'error: Unknown variable "lightt" @lightt',
-            'error: Unknown variable "tru" @tru',
-        ]);
-    });
-
-    it("finds problems in multi line labels", () => {
-        const label = "[motion]\n{\n  light = true;\n  cnt++;\n}";
-        expect(summarize(validateTransitionLabel(label, symbols), label)).to.deep.equal([
-            'error: Unknown variable "cnt" @cnt',
-        ]);
-    });
-
-    it("reports structural errors with key and arguments for translation", () => {
-        const [diagnostic] = validateTransitionLabel("[motion", symbols);
-        expect(diagnostic).to.include({ key: 'Missing "%s"', message: 'Missing "]"', from: 0, to: 7 });
-        expect(diagnostic.args).to.deep.equal(["]"]);
-    });
-});
-
-describe("chart-validation => validateChart", () => {
-    it("reports problems of states and transitions", () => {
-        const problems = validateChart({
-            version: 1,
-            name: "Test",
-            enabled: true,
-            symbols,
-            states: [{ id: "s1", name: "S1", entry: "lihgt = true;", x: 0, y: 0 }],
-            transitions: [{ id: "t1", source: "s1", target: "s1", label: "[x]" }],
-        });
-        expect(problems.map(p => `${p.kind} ${p.id} ${p.field}: ${p.diagnostic.message}`)).to.deep.equal([
-            'state s1 entry: Unknown variable "lihgt"',
-            'transition t1 label: Unknown variable "x"',
-        ]);
-    });
-
-    it("knows the functions of function blocks and checks the blocks", () => {
-        const problems = validateChart({
-            version: 1,
-            name: "Test",
-            enabled: true,
-            symbols,
-            states: [{ id: "s1", name: "S1", entry: "light = isOn(count) && LIMIT > 1;", x: 0, y: 0 }],
-            transitions: [{ id: "t1", source: "s1", target: "s1", label: "[clamp(count, 0, 5) > 1]" }],
-            functions: [
-                { id: "f1", code: "function clamp(x, lo, hi) { return Math.min(hi, Math.max(lo, x)); }", x: 0, y: 0 },
-                { id: "f2", code: "const LIMIT = 3;\nconst isOn = c => c > LIMIT && motoin;", x: 0, y: 0 },
-                { id: "f3", code: "function clamp() {}\nfunction count() {}", x: 0, y: 0 },
-            ],
-        });
-        expect(problems.map(p => `${p.kind} ${p.id} ${p.field}: ${p.diagnostic.message}`)).to.deep.equal([
-            'function f2 code: Unknown variable "motoin"',
-            'function f3 code: "clamp" is declared in more than one function block',
-            'function f3 code: "count" is already the name of a variable',
-        ]);
-    });
-});
-
-describe("chart-validation => getDeclarations", () => {
-    it("returns functions with their signature and other declarations", () => {
-        const code = "function clamp(x, lo = 0, ...rest) {}\nconst f = (a, b) => a + b;\nlet counter = 0;";
-        expect(getDeclarations(code).map(d => [d.name, d.signature, code.substring(d.from, d.to)])).to.deep.equal([
-            ["clamp", "clamp(x, lo = 0, ...rest)", "clamp"],
-            ["f", "f(a, b)", "f"],
-            ["counter", null, "counter"],
-        ]);
-    });
-
-    it("returns nothing for code with syntax errors", () => {
-        expect(getDeclarations("function (")).to.deep.equal([]);
-    });
-});