@datamoc/mw_games 0.7.7 → 0.7.8

package/dist/mwl/runtime.js

@@ -1,10 +1,21 @@
 import { decodeSave, encodeSave } from './persistence.js';
 import { evaluateCondition } from './conditions.js';
 import { evaluateExpression } from './expression.js';
-import { booleanAttribute, integerAttribute, numberAttribute, requiredAttribute } from './utils.js';
+import { booleanAttribute, booleanValue, integerAttribute, numberAttribute, requiredAttribute } from './utils.js';
 import { endLevelCarryover } from './carryover.js';
 const required = requiredAttribute;
 const integer = (node, attribute, fallback) => integerAttribute(node, attribute, fallback) ?? fallback;
+/**
+ * A fresh, empty world: no sides, units, maps or variables, at turn 1 and `playing`.
+ *
+ * @example
+ * ```ts
+ * import { createWorld } from '@datamoc/mw_games/mwl';
+ *
+ * const world = createWorld();
+ * console.log(world.turn, world.status); // 1 'playing'
+ * ```
+ */
 export function createWorld() {
     return {
         variables: {},
@@ -24,6 +35,14 @@ export function createWorld() {
  * Parse map text: one row per line, comma-separated codes. A token may be
  * `<side> <code>` to mark that side's keep/start, which is how a leader knows
  * where to appear.
+ *
+ * @example
+ * ```ts
+ * import { parseTerrain } from '@datamoc/mw_games/mwl';
+ *
+ * const map = parseTerrain('Gg,Gg\nGg,1 Kh');
+ * console.log(map.width, map.starts['1']); // 2 [{ x: 1, y: 1 }]
+ * ```
  */
 export function parseTerrain(text) {
     const rows = text
@@ -57,6 +76,16 @@ export function parseTerrain(text) {
  * real data (pathfinding costs, combat formulas) stay in the engine adapter;
  * this runtime's `move` is a bounds and occupancy check, and `attack` applies
  * the amount the content asks for.
+ *
+ * @example
+ * ```ts
+ * import { compile, MwlRuntime } from '@datamoc/mw_games/mwl';
+ *
+ * const runtime = new MwlRuntime(compile('[game]\nschema=0.1\n[/game]'), {
+ *   resolveMap: () => 'Gg,Gg\nGg,Gg',
+ * });
+ * console.log(runtime.world.turn); // 1
+ * ```
  */
 export class MwlRuntime {
     constructor(game, options = {}) {
@@ -155,18 +184,39 @@ export class MwlRuntime {
         return !filter || this.filterMatches(filter);
     }
     executeEvent(event) {
-        for (const command of event.children.filter((child) => child.tag !== 'condition' && child.tag !== 'filter' && child.tag !== 'filter_condition')) {
-            if (command.tag === 'say') {
-                this.showSay(command);
+        this.runBlock(this.commandChildren(event));
+    }
+    /**
+     * Runs a sequence of commands, with `say` and `dialogue` taking the message path rather
+     * than `executeNode`. Shared by an event's top level, an `[if]`/`[else]` body and a
+     * dialogue branch, so all three treat a nested pair the same way.
+     */
+    runBlock(children) {
+        for (let index = 0; index < children.length; index++) {
+            const child = children[index];
+            if (this.isConsumedElse(children, index))
+                continue;
+            if (child.tag === 'say') {
+                this.showSay(child);
                 continue;
             }
-            if (command.tag === 'dialogue') {
-                this.showDialogue(command);
+            if (child.tag === 'dialogue') {
+                this.showDialogue(child);
                 continue;
             }
-            this.executeNode(command);
+            this.executeNode(child);
         }
     }
+    /**
+     * Whether an `[else]` at `index` is the branch its immediately preceding `[if]` already ran.
+     * A taken `[if]` runs its own body and owns the `[else]`, so the loop skips that `[else]`;
+     * a false `[if]` ran nothing, so the `[else]` is left for the loop to run as its fallback.
+     * A free-standing `[else]` with no `[if]` before it is never consumed.
+     */
+    isConsumedElse(children, index) {
+        const previous = children[index - 1];
+        return children[index]?.tag === 'else' && previous?.tag === 'if' && this.nodeConditionMatches(previous);
+    }
     executeTracedEvent(event, trigger) {
         const id = event.attributes.id ??
             `${event.attributes.on ?? event.attributes.trigger ?? 'event'}@${event.location?.line ?? 0}`;
@@ -212,7 +262,7 @@ export class MwlRuntime {
             if (child.tag !== 'choice' || !child.attributes.text)
                 continue;
             if (child.attributes.variable !== undefined &&
-                !sameValue(this.world.variables[child.attributes.variable], child.attributes.equals))
+                !sameValue(this.variableAt(child.attributes.variable), child.attributes.equals))
                 continue;
             const branches = child.children.filter((branch) => branch.tag === 'branch');
             if (branches.length) {
@@ -270,8 +320,7 @@ export class MwlRuntime {
             this.executeEvent(event);
         }
         else {
-            for (const command of choice.branch ?? [])
-                this.executeNode(command);
+            this.runBlock(choice.branch ?? []);
         }
         this.checkObjectives();
         return true;
@@ -419,9 +468,15 @@ export class MwlRuntime {
             const name = role.attributes.role ?? role.attributes.name;
             if (name === undefined)
                 continue;
-            (this.world.roles ??= {})[name] = Object.entries(this.world.units)
-                .filter(([id, unit]) => unit.alive && unitMatchesFilter(unit, id, role.attributes))
-                .map(([id]) => id);
+            //`role`/`name` on this tag name the role being assigned, not a unit to match, so the
+            //filter must not read either back as one - the same double duty `[store_unit]`'s
+            //`variable`/`name` has
+            const filter = withoutAttributes(role.attributes, 'role', 'name');
+            const matched = Object.entries(this.world.units).filter(([id, unit]) => unit.alive && unitMatchesFilter(unit, id, filter));
+            //a unit learns the role it was assigned, so a later `[filter] role=courier` finds it
+            for (const [, unit] of matched)
+                unit.role = name;
+            (this.world.roles ??= {})[name] = matched.map(([id]) => id);
         }
     }
     buildMap(id, node) {
@@ -459,6 +514,13 @@ export class MwlRuntime {
             }
             if (unit.attributes.side !== undefined)
                 entry.side = unit.attributes.side;
+            if (unit.attributes.name !== undefined)
+                entry.name = unit.attributes.name;
+            if (unit.attributes.role !== undefined)
+                entry.role = unit.attributes.role;
+            const can_recruit = booleanAttribute(unit, 'can_recruit');
+            if (can_recruit !== undefined)
+                entry.can_recruit = can_recruit;
             this.world.units[id] = entry;
         }
     }
@@ -486,6 +548,8 @@ export class MwlRuntime {
                     type: leader,
                     side: sideId,
                     moves: stats?.movement ?? 0,
+                    can_recruit: true,
+                    leader: true,
                 };
             }
         }
@@ -528,7 +592,7 @@ export class MwlRuntime {
             }
             case 'store_unit': {
                 const variable = node.attributes.variable ?? node.attributes.name ?? required(node, 'variable');
-                this.setVariableAt(variable, this.matchingUnits(node).map(([id, unit]) => ({ id, ...unitSnapshot(unit) })));
+                this.setVariableAt(variable, this.matchingUnits(node, ['variable', 'name']).map(([id, unit]) => ({ id, ...unitSnapshot(unit) })));
                 break;
             }
             case 'unstore_unit': {
@@ -598,7 +662,12 @@ export class MwlRuntime {
                 const name = node.attributes.role ?? node.attributes.name;
                 if (!name)
                     throw new Error('[role] requires role');
-                (this.world.roles ??= {})[name] = this.matchingUnits(node).map(([id]) => id);
+                //`role`/`name` here name the role being assigned, not a unit to match, so the filter
+                //must not read either back as one - the same exclusion the scenario-level role uses
+                const matched = this.matchingUnits(node, ['role', 'name']);
+                for (const [, unit] of matched)
+                    unit.role = name;
+                (this.world.roles ??= {})[name] = matched.map(([id]) => id);
                 break;
             }
             case 'attack':
@@ -618,8 +687,7 @@ export class MwlRuntime {
                 if (limit < 1 || limit > 100_000)
                     throw new Error('MWL while max_iterations must be between 1 and 100000');
                 for (let iteration = 0; iteration < limit && this.nodeConditionMatches(node); iteration++)
-                    for (const child of node.children)
-                        this.executeNode(child);
+                    this.runBlock(this.commandChildren(node));
                 break;
             }
             case 'foreach': {
@@ -639,8 +707,7 @@ export class MwlRuntime {
                 for (let index = 0; index < entries.length; index++) {
                     this.setVariableAt(item, entries[index][1]);
                     this.setVariableAt(indexName, index);
-                    for (const child of node.children)
-                        this.executeNode(child);
+                    this.runBlock(this.commandChildren(node));
                 }
                 break;
             }
@@ -650,8 +717,7 @@ export class MwlRuntime {
                     child.attributes.equals !== undefined &&
                     sameValue(value, child.attributes.equals));
                 const fallback = node.children.find((child) => child.tag === 'default');
-                for (const child of (selected ?? fallback)?.children ?? [])
-                    this.executeNode(child);
+                this.runBlock((selected ?? fallback)?.children ?? []);
                 break;
             }
             case 'end_turn':
@@ -677,15 +743,17 @@ export class MwlRuntime {
                 });
                 break;
             }
-            case 'if':
-                if (!this.nodeConditionMatches(node))
-                    break;
-                for (const child of node.children)
-                    this.executeNode(child);
+            case 'if': {
+                //an immediately following [else] is this branch's other half, not a separate
+                //command: the condition picks one body, and runBlock skips the [else] itself
+                const fallback = node.children.find((child) => child.tag === 'else');
+                const taken = this.nodeConditionMatches(node) ? node : fallback;
+                this.runBlock(taken ? this.commandChildren(taken) : []);
                 break;
+            }
             case 'else':
-                for (const child of node.children)
-                    this.executeNode(child);
+                //reachable at top level for a free-standing [else]; a paired one is run by its [if]
+                this.runBlock(this.commandChildren(node));
                 break;
             case 'hook':
                 this.runHook(node);
@@ -694,6 +762,15 @@ export class MwlRuntime {
                 throw new Error(`unknown MWL command: ${name}`);
         }
     }
+    /**
+     * A node's children that are commands to run, dropping the condition children the schema
+     * allows a branch to carry. A `[condition]` is read by the branch itself, never executed:
+     * `[if]`/`[while]` evaluate one through `nodeConditionMatches`, where running it as a command
+     * would be an unknown tag.
+     */
+    commandChildren(node) {
+        return node.children.filter((child) => child.tag !== 'condition' && child.tag !== 'filter' && child.tag !== 'filter_condition');
+    }
     runHook(node) {
         const reference = node.attributes.name ?? '';
         const hook = this.hooks?.command?.[reference];
@@ -741,8 +818,7 @@ export class MwlRuntime {
      * same interpolation WML authors expect in story and dialogue strings.
      */
     interpolate(text) {
-        const variables = this.world.variables;
-        const numeric = Object.fromEntries(Object.entries(variables).filter((entry) => typeof entry[1] === 'number'));
+        const numeric = Object.fromEntries(Object.entries(this.world.variables).filter((entry) => typeof entry[1] === 'number'));
         const expanded = text.replace(/\$\(([^)]*)\)/g, (_whole, expression) => {
             try {
                 return String(evaluateExpression(expression, numeric));
@@ -752,7 +828,7 @@ export class MwlRuntime {
             }
         });
         return expanded.replace(/\$([A-Za-z_][A-Za-z0-9_.]*)/g, (_whole, name) => {
-            const value = variables[name];
+            const value = this.variableAt(name);
             return value === undefined || typeof value === 'boolean' ? '' : String(value);
         });
     }
@@ -766,7 +842,7 @@ export class MwlRuntime {
         // so content can alias changing values without arithmetic.
         const reference = /^\$([A-Za-z_][A-Za-z0-9_.]*)$/.exec(raw.trim());
         if (reference) {
-            const value = this.world.variables[reference[1]];
+            const value = this.variableAt(reference[1]);
             this.setVariableAt(name, value === undefined ? '' : value);
             return;
         }
@@ -778,30 +854,11 @@ export class MwlRuntime {
         this.setVariableAt(name, raw);
     }
     variableAt(path) {
-        let value = this.world.variables;
-        for (const part of path.split('.')) {
-            if (!value || typeof value !== 'object' || Array.isArray(value))
-                return undefined;
-            value = value[part];
-        }
-        return value;
+        return variableAtPath(this.world.variables, path);
     }
     setVariableAt(path, value) {
         const previous = this.variableAt(path);
-        const parts = path.split('.');
-        if (parts.length === 1) {
-            this.world.variables[path] = value;
-            this.onTrace?.({ type: 'variable', name: path, ...(previous === undefined ? {} : { previous }), value });
-            return;
-        }
-        let current = this.world.variables;
-        for (const part of parts.slice(0, -1)) {
-            const child = current[part];
-            if (!child || typeof child !== 'object' || Array.isArray(child))
-                current[part] = {};
-            current = current[part];
-        }
-        current[parts.at(-1)] = value;
+        setVariableAtPath(this.world.variables, path, value);
         this.onTrace?.({ type: 'variable', name: path, ...(previous === undefined ? {} : { previous }), value });
     }
     spawnUnit(type, side, x, y, id, hp) {
@@ -828,14 +885,16 @@ export class MwlRuntime {
      * own attributes, read by the same `unitMatchesFilter` an event filter and `[kill]` use. An
      * empty filter matches every live unit, the rule `[kill]` already documents.
      */
-    matchingUnits(node) {
+    matchingUnits(node, exclude = []) {
         const filter = node.children.find((child) => child.tag === 'filter');
-        const attributes = filter?.attributes ?? node.attributes;
+        //a `[filter]` child is a real unit filter and keeps every attribute; the node's own
+        //attributes are the fallback, minus whatever they mean to this command instead of a unit
+        const attributes = filter ? filter.attributes : withoutAttributes(node.attributes, ...exclude);
         return Object.entries(this.world.units).filter(([id, unit]) => unit.alive && unitMatchesFilter(unit, id, attributes));
     }
     /** The unit snapshots `[store_unit]` wrote into a world variable, or a named content error. */
     storedUnits(variable) {
-        const stored = this.world.variables[variable];
+        const stored = this.variableAt(variable);
         if (!Array.isArray(stored))
             throw new Error(`MWL variable ${variable} is not a stored unit list; store one first`);
         return stored.filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry));
@@ -858,6 +917,14 @@ export class MwlRuntime {
             unit.side = side;
         if (typeof entry.moves === 'number')
             unit.moves = entry.moves;
+        if (typeof entry.name === 'string')
+            unit.name = entry.name;
+        if (typeof entry.role === 'string')
+            unit.role = entry.role;
+        if (typeof entry.can_recruit === 'boolean')
+            unit.can_recruit = entry.can_recruit;
+        if (typeof entry.leader === 'boolean')
+            unit.leader = entry.leader;
         this.world.units[id] = unit;
     }
     /** Changes one cell of the primary map, keeping the parsed grid and its size in step. */
@@ -925,7 +992,20 @@ export class MwlRuntime {
     conditionMatches(node) {
         return node.children
             .filter((child) => child.tag === 'condition')
-            .every((condition) => variableMatches(this.world.variables[condition.attributes.variable], condition.attributes, primitiveVariables(this.world.variables)));
+            .every((condition) => {
+            if (condition.attributes.condition === 'hook') {
+                const hookName = condition.attributes.hook;
+                const predicateName = hookName?.startsWith('predicate:')
+                    ? hookName.slice('predicate:'.length)
+                    : undefined;
+                const predicate = predicateName ? this.hooks?.predicate?.[predicateName] : undefined;
+                if (!predicate)
+                    throw new Error(`MWL predicate ${predicateName ?? '<missing>'} is not implemented`);
+                const { condition: _condition, hook: _hook, ...context } = condition.attributes;
+                return Boolean(predicate(this.worldView(), context));
+            }
+            return variableMatches(this.variableAt(condition.attributes.variable), condition.attributes, resolveVariable(this.world.variables));
+        });
     }
     nodeConditionMatches(node) {
         if (node.attributes.test !== undefined)
@@ -947,7 +1027,7 @@ export class MwlRuntime {
                 const name = child.attributes.name;
                 if (name === undefined)
                     return false;
-                return variableMatches(this.world.variables[name], child.attributes, primitiveVariables(this.world.variables));
+                return variableMatches(this.variableAt(name), child.attributes, resolveVariable(this.world.variables));
             }
             if (child.tag === 'predicate') {
                 const name = child.attributes.name;
@@ -1087,7 +1167,7 @@ export class MwlRuntime {
             kill: (unit) => this.killUnit(unit),
             gold: (side, delta) => this.addGold(side, delta),
             setVariable: (name, value) => {
-                this.world.variables[name] = value;
+                setVariableAtPath(this.world.variables, name, value);
             },
             message: (speaker, text) => this.onMessage?.({ text, ...(speaker ? { speaker } : {}) }),
             endTurn: () => this.endTurn(),
@@ -1120,12 +1200,24 @@ export class MwlRuntime {
         return result;
     }
 }
+/**
+ * Applies one already-validated `MwlCommand` to a world, without a runtime around it.
+ *
+ * @example
+ * ```ts
+ * import { createWorld, execute } from '@datamoc/mw_games/mwl';
+ *
+ * const world = createWorld();
+ * execute(world, { name: 'set_variable', target: 'gold', value: 50 });
+ * console.log(world.variables.gold); // 50
+ * ```
+ */
 export function execute(world, command) {
     if (world.status !== 'playing' && command.name !== 'win' && command.name !== 'lose')
         return;
     switch (command.name) {
         case 'set_variable':
-            world.variables[command.target] = command.value;
+            setVariableAtPath(world.variables, command.target, command.value);
             break;
         case 'modify_gold':
             world.gold[command.target] = (world.gold[command.target] ?? 0) + command.amount;
@@ -1234,6 +1326,14 @@ function unitSnapshot(unit) {
         snapshot.side = unit.side;
     if (unit.moves !== undefined)
         snapshot.moves = unit.moves;
+    if (unit.name !== undefined)
+        snapshot.name = unit.name;
+    if (unit.role !== undefined)
+        snapshot.role = unit.role;
+    if (unit.can_recruit !== undefined)
+        snapshot.can_recruit = unit.can_recruit;
+    if (unit.leader !== undefined)
+        snapshot.leader = unit.leader;
     return snapshot;
 }
 /** Applies `[modify_unit]`'s chosen attributes to one unit, ignoring anything it did not name. */
@@ -1248,8 +1348,16 @@ function applyUnitChanges(unit, changes) {
         unit.type = changes.type;
     if (changes.side !== undefined)
         unit.side = changes.side;
-    if (changes.alive !== undefined)
-        unit.alive = changes.alive === 'yes' || changes.alive === 'true';
+    const alive = booleanValue(changes.alive);
+    if (alive !== undefined)
+        unit.alive = alive;
+    if (changes.name !== undefined)
+        unit.name = changes.name;
+    if (changes.role !== undefined)
+        unit.role = changes.role;
+    const canRecruit = booleanValue(changes.can_recruit);
+    if (canRecruit !== undefined)
+        unit.can_recruit = canRecruit;
 }
 function finiteNumber(value) {
     if (value === undefined || value === '')
@@ -1270,12 +1378,19 @@ function optionalInteger(node, attribute) {
  * lists split on commas, comparisons coerce both sides with `Number` and
  * fail on anything non-numeric.
  */
-function variableMatches(value, attributes, variables = {}) {
-    const resolve = (expected) => expected.startsWith('$') ? variables[expected.slice(1)] : expected;
+function variableMatches(value, attributes, resolve) {
+    const expected = (text) => {
+        if (!text.startsWith('$'))
+            return text;
+        const resolved = resolve(text.slice(1));
+        return typeof resolved === 'string' || typeof resolved === 'number' || typeof resolved === 'boolean'
+            ? resolved
+            : undefined;
+    };
     if (attributes.equals !== undefined)
-        return sameValue(value, resolve(attributes.equals));
+        return sameValue(value, expected(attributes.equals));
     if (attributes.not_equals !== undefined)
-        return !sameValue(value, resolve(attributes.not_equals));
+        return !sameValue(value, expected(attributes.not_equals));
     if (attributes.in !== undefined) {
         const options = attributes.in.split(',').map((entry) => entry.trim());
         return options.some((option) => sameValue(value, option));
@@ -1306,22 +1421,38 @@ function variableMatches(value, attributes, variables = {}) {
 }
 /**
  * One alive unit against `filter`/`have_unit` attributes: side, type (with
- * comma-list `not_type` exclusion), world key (`unit`, or `id` on
- * `have_unit`), and coordinates all have to match when present.
+ * comma-list `not_type` exclusion), the unit's own name and role, whether it
+ * can recruit, whether it is its side's leader, world key (`unit`, or `id`
+ * on `have_unit`), and coordinates all have to match when present.
  */
 function unitMatchesFilter(unit, id, attributes) {
     const excluded = (attributes.not_type ?? '')
         .split(',')
         .map((entry) => entry.trim())
         .filter(Boolean);
+    const wantedCanRecruit = booleanValue(attributes.can_recruit);
+    const wantedLeader = booleanValue(attributes.leader);
     const key = attributes.unit ?? attributes.id;
     return ((key === undefined || id === key) &&
         (attributes.side === undefined || unit.side === attributes.side) &&
         (attributes.type === undefined || unit.type === attributes.type) &&
         (excluded.length === 0 || !excluded.includes(unit.type ?? '')) &&
+        (attributes.name === undefined || unit.name === attributes.name) &&
+        (attributes.role === undefined || unit.role === attributes.role) &&
+        (wantedCanRecruit === undefined || (unit.can_recruit ?? false) === wantedCanRecruit) &&
+        (wantedLeader === undefined || (unit.leader ?? false) === wantedLeader) &&
         (attributes.x === undefined || unit.x === Number(attributes.x)) &&
         (attributes.y === undefined || unit.y === Number(attributes.y)));
 }
+/** a copy of `attributes` without the given keys, for a command whose own attribute names are not a unit filter */
+function withoutAttributes(attributes, ...excluded) {
+    if (excluded.length === 0)
+        return { ...attributes };
+    const copy = { ...attributes };
+    for (const key of excluded)
+        delete copy[key];
+    return copy;
+}
 function sameValue(value, expected) {
     if (value === undefined || expected === undefined)
         return value === expected;
@@ -1335,6 +1466,73 @@ function sameValue(value, expected) {
 function primitiveVariables(variables) {
     return Object.fromEntries(Object.entries(variables).filter((entry) => typeof entry[1] === 'string' || typeof entry[1] === 'number' || typeof entry[1] === 'boolean'));
 }
+/** `a.b[0].c` -> `['a', 'b', { index: 0 }, 'c']`. */
+function variablePathParts(path) {
+    return path
+        .split('.')
+        .flatMap((segment) => {
+        const name = /^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(segment);
+        if (!name)
+            return [segment];
+        const parts = name[1] === '' ? [] : [name[1]];
+        for (const bracket of name[2].matchAll(/\[([^\]]*)\]/g)) {
+            const index = Number(bracket[1]);
+            parts.push({ index: /^\d+$/.test(bracket[1].trim()) ? index : undefined });
+        }
+        return parts;
+    })
+        .filter((part) => typeof part !== 'string' || part !== '');
+}
+/** The path parts of a write, with any bracketed index that is not a whole number refused by name. */
+function validVariablePathParts(path) {
+    const parts = variablePathParts(path);
+    if (parts.some((part) => typeof part !== 'string' && part.index === undefined))
+        throw new Error(`invalid variable path: ${path}`);
+    return parts;
+}
+function isIndexedStep(step) {
+    return typeof step !== 'string';
+}
+/**
+ * The one write of a variable path, so `execute()`, the hook host and the runtime's own
+ * `set_variable` all place a value at the same node a read walks to. A step after an index
+ * grows an array, so `a[0]`/`a[1]` build a real list rather than an object with numbered keys.
+ */
+function setVariableAtPath(variables, path, value) {
+    const parts = validVariablePathParts(path);
+    const key = (step) => (typeof step === 'string' ? step : step.index);
+    let current = variables;
+    for (let index = 0; index < parts.length - 1; index++) {
+        const step = key(parts[index]);
+        const child = current[step];
+        if (!child || typeof child !== 'object') {
+            current[step] = isIndexedStep(parts[index + 1]) ? [] : {};
+        }
+        current = current[step];
+    }
+    current[key(parts[parts.length - 1])] = value;
+}
+/** The one read of a variable path, used by every reader that takes a name. */
+function variableAtPath(variables, path) {
+    let value = variables;
+    for (const part of variablePathParts(path)) {
+        if (typeof part === 'string') {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                return undefined;
+            value = value[part];
+        }
+        else {
+            if (!Array.isArray(value) || part.index === undefined)
+                return undefined;
+            value = value[part.index];
+        }
+    }
+    return value;
+}
+/** Resolves a `$name` reference (a path, not only a top-level key) from a variable tree. */
+function resolveVariable(variables) {
+    return (reference) => variableAtPath(variables, reference);
+}
 function coordinateMatches(specification, coordinate) {
     return specification.split(',').some((part) => {
         const value = part.trim();