@accordproject/template-engine 3.1.0 → 4.2.1

package/lib/TemplateMarkInterpreter.js

@@ -0,0 +1,689 @@
+"use strict";
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateMarkInterpreter = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const jsonpath_1 = __importDefault(require("jsonpath"));
+const traverse_1 = __importDefault(require("traverse"));
+const browser_or_node_1 = require("browser-or-node");
+const os_1 = __importDefault(require("os"));
+const concerto_core_1 = require("@accordproject/concerto-core");
+const drafting_1 = require("./drafting");
+const markdown_common_1 = require("@accordproject/markdown-common");
+const concerto_core_2 = require("@accordproject/concerto-core");
+const TemplateMarkNodes_1 = require("./TemplateMarkNodes");
+const TemplateMarkToJavaScriptCompiler_1 = require("./TemplateMarkToJavaScriptCompiler");
+const org_accordproject_templatemark_0_5_0_1 = require("./model-gen/org.accordproject.templatemark@0.5.0");
+const TypeScriptRuntime_1 = require("./TypeScriptRuntime");
+const utils_1 = require("./utils");
+const JavaScriptEvaluator_1 = require("./JavaScriptEvaluator");
+function checkCode(code) {
+    if (code.type !== org_accordproject_templatemark_0_5_0_1.CodeType.ES_2020) {
+        throw new Error(`Cannot run ${code.contents} as it is not ES_2020 JavaScript.`);
+    }
+}
+// this is a global because we don't want the user
+// to configure child processes at the TemplateMarkInterpreter instance level
+const javaScriptEvaluator = browser_or_node_1.isBrowser ? new JavaScriptEvaluator_1.JavaScriptEvaluator() : new JavaScriptEvaluator_1.JavaScriptEvaluator({
+    maxWorkers: process.env.MAX_WORKERS ? Number.parseInt(process.env.MAX_WORKERS) : os_1.default.availableParallelism(), // how many child processes
+    waitInterval: process.env.WAIT_INTERVAL ? Number.parseInt(process.env.WAIT_INTERVAL) : 50, // how long to wait before rescheduling work
+    maxQueueDepth: process.env.MAX_QUEUE_DEPTH ? Number.parseInt(process.env.MAX_QUEUE_DEPTH) : 1000 // max requests to queue
+});
+const TEMPLATEMARK_ROOT_NODES = [
+    'org.accordproject.templatemark@0.5.0.ClauseDefinition',
+    'org.accordproject.templatemark@0.5.0.ContractDefinition'
+];
+const DOCUMENT_ROOT = 'org.accordproject.commonmark@0.5.0.Document';
+/**
+ * Evaluates a JS expression
+ * @param {*} clauseLibrary the clause library
+ * @param {*} data the contract data
+ * @param {string} fn the JS function (including header)
+ * @param {GenerationOptions} options the generation options
+ * @returns {object} the result of evaluating the expression against the data
+ */
+async function evaluateJavaScript(clauseLibrary, data, fn, options) {
+    if (options?.disableJavaScriptEvaluation) {
+        throw new Error('JavaScript evaluation is disabled.');
+    }
+    if (!data || !fn) {
+        throw new Error(`Cannot evaluate JS ${fn} against ${data}`);
+    }
+    const functionArgNames = new Array();
+    functionArgNames.push('data');
+    functionArgNames.push('library');
+    functionArgNames.push('options');
+    const functionArgValues = new Array();
+    functionArgValues.push(data);
+    functionArgValues.push(clauseLibrary);
+    functionArgValues.push(options);
+    // chop the function header and closing
+    const expression = fn.substring(fn.indexOf('{') + 1, fn.lastIndexOf('}'));
+    if (expression.trim().length === 0) {
+        throw new Error('Empty expression');
+    }
+    try {
+        const request = { code: expression, argumentNames: functionArgNames, arguments: functionArgValues };
+        if (options?.childProcessJavaScriptEvaluation) {
+            if (browser_or_node_1.isBrowser) {
+                throw new Error('Child process evaluation is not supported inside web browser');
+            }
+            const evalOptions = options?.timeout ? { timeout: options.timeout } : undefined;
+            const r = await javaScriptEvaluator.evalChildProcess(request, evalOptions);
+            return r;
+        }
+        else {
+            const r = await javaScriptEvaluator.evalDangerously(request);
+            return r;
+        }
+    }
+    catch (err) {
+        throw new Error(`Caught error ${JSON.stringify(err)} evaluating ${expression} with arguments ${JSON.stringify(functionArgValues)}`);
+    }
+}
+/**
+ * Calculates a JSON path to use to retrieve data, based on a TemplatemMark tree.
+ * For example, if we hit a VariableDefinition {{city}} that is nested inside a
+ * WithDefinition {{#with address}} then the JSON path returned should be '$.address.city'.
+ * Similarly ListBlockDefinition, JoinDefinition and OptionalDefinition also include
+ * property names that must apply to their child nodes.
+ * @param {*} rootData the root of the JSON document, typically this is a TemplateMark JSON
+ * @param {*} currentNode the current TemplateMark node we are processing
+ * @param {string[]} paths the traverse path to the current node
+ * @returns {string} the JSON path to use to retrieve data
+ */
+function getJsonPath(rootData, currentNode, paths) {
+    if (!currentNode) {
+        throw new Error('Node must be supplied');
+    }
+    if (!currentNode.name) {
+        throw new Error(`Node must have a name: ${JSON.stringify(currentNode)}`);
+    }
+    if (currentNode.name.indexOf('.') >= 0) {
+        // prevent JSON path injection
+        throw new Error(`Invalid name property ${currentNode.name}`);
+    }
+    if (!paths || !paths.length || paths.length < 1) {
+        throw new Error('Paths must be supplied');
+    }
+    const withPath = [];
+    for (let n = 1; n < paths.length; n++) {
+        const sub = paths.slice(0, n);
+        const obj = traverse_1.default.get(rootData, sub);
+        // HACK
+        // if(obj===undefined) {
+        //     throw new Error(`Failed to find data with path ${sub} and data ${JSON.stringify(rootData, null, 2)}`);
+        // }
+        if (obj && obj.$class) {
+            if (TemplateMarkNodes_1.NAVIGATION_NODES.indexOf(obj.$class) >= 0) {
+                if (obj.name !== 'top') { // HACK!!
+                    withPath.push(`['${obj.name}']`);
+                }
+            }
+        }
+    }
+    if (currentNode.name !== 'this' && currentNode.name !== 'top') {
+        withPath.push(`['${currentNode.name}']`);
+    }
+    return withPath.length > 0 ? `$${withPath.join('')}` : '$';
+}
+/**
+ * Evaluates all the user code in a template mark document
+ * @param {*} clauseLibrary - the clause library
+ * @param {*} templateMark - the TemplateMark JSON document
+ * @param {*} data - the template data JSON
+ * @param {[GenerationOptions]} options - the generation options
+ * @returns {Promise<UserCodeResult>} a promise to a UserCodeResult
+ */
+async function evaluateUserCode(clauseLibrary, templateMark, data, options) {
+    const result = {};
+    const paths = (0, traverse_1.default)(templateMark).paths();
+    for (let n = 0; n < paths.length; n++) {
+        const path = paths[n];
+        const context = (0, traverse_1.default)(templateMark).get(path);
+        if (typeof context === 'object' && context.$class && typeof context.$class === 'string') {
+            const nodeClass = context.$class;
+            if (TemplateMarkNodes_1.FORMULA_DEFINITION_RE.test(nodeClass)) {
+                if (context.code) {
+                    checkCode(context.code);
+                    const evalResponse = await evaluateJavaScript(clauseLibrary, data, context.code.contents, options);
+                    result[path.join('/')] = JSON.stringify(evalResponse.result);
+                }
+                else {
+                    throw new Error('Formula node is missing code.');
+                }
+            }
+            else if (TemplateMarkNodes_1.CONDITIONAL_DEFINITION_RE.test(nodeClass) || TemplateMarkNodes_1.CLAUSE_DEFINITION_RE.test(nodeClass)) {
+                if (context.condition) {
+                    checkCode(context.condition);
+                    const evalResponse = await evaluateJavaScript(clauseLibrary, data, context.condition.contents, options);
+                    result[path.join('/')] = JSON.stringify(evalResponse.result);
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Generates agreementmark for all optional blocks with proper context switching
+ * Warning: this is async and recursive
+ * @param {ModelManager} modelManager - the template model
+ * @param {*} clauseLibrary - the clause library
+ * @param {*} templateMark - the TemplateMark JSON document
+ * @param {*} data - the template data JSON
+ * @param {[GenerationOptions]} options - the generation options
+ * @returns {*} the AgreementMark JSON for optional blocks
+ */
+async function generateOptionalBlocks(modelManager, clauseLibrary, templateMark, data, options) {
+    const result = {};
+    const paths = (0, traverse_1.default)(templateMark).paths();
+    for (let n = 0; n < paths.length; n++) {
+        const thisPath = paths[n];
+        const context = (0, traverse_1.default)(templateMark).get(thisPath);
+        if (typeof context === 'object' && context.$class && typeof context.$class === 'string') {
+            const nodeClass = context.$class;
+            // evaluate optional blocks, processing the whenSome content with the optional property value as context
+            if (TemplateMarkNodes_1.OPTIONAL_DEFINITION_RE.test(nodeClass)) {
+                const path = getJsonPath(templateMark, context, thisPath);
+                const variableValues = jsonpath_1.default.query(data, path, 1);
+                if (variableValues.length > 0) {
+                    // Optional property exists, process whenSome with the property value as context
+                    const optionalPropertyValue = variableValues[0];
+                    if (context.whenSome && context.whenSome.length > 0) {
+                        // Create a paragraph wrapper for the whenSome content
+                        const whenSomeParagraph = {
+                            $class: 'org.accordproject.commonmark@0.5.0.Paragraph',
+                            nodes: context.whenSome
+                        };
+                        // Process with the optional property value as the new data context
+                        const subResult = await generateAgreement(modelManager, clauseLibrary, whenSomeParagraph, optionalPropertyValue, options);
+                        result[thisPath.join('/')] = subResult.nodes ? subResult.nodes : [];
+                    }
+                    else {
+                        result[thisPath.join('/')] = [];
+                    }
+                }
+                // If optional property doesn't exist, we don't add anything to results
+                // and the normal processing will handle whenNone
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Generates agreementmark for all recursive blocks (list, foreach)
+ * Warning: this is async and recursive
+ * @param {ModelManager} modelManager - the template model
+ * @param {*} clauseLibrary - the clause library
+ * @param {*} templateMark - the TemplateMark JSON document
+ * @param {*} data - the template data JSON
+ * @param {RegExp} nodeRegExp - the regex used to match against $class of nodes
+ * @param {string} childNodeClass - the $class to use for the node that wraps child items
+ * @param {[GenerationOptions]} options - the generation options
+ * @returns {*} the AgreementMark JSON for the list block
+ */
+async function generateRecursiveBlocks(modelManager, clauseLibrary, templateMark, data, nodeRegExp, childNodeClass, options) {
+    const result = {};
+    const paths = (0, traverse_1.default)(templateMark).paths();
+    for (let n = 0; n < paths.length; n++) {
+        const thisPath = paths[n];
+        const context = (0, traverse_1.default)(templateMark).get(thisPath);
+        if (typeof context === 'object' && context.$class && typeof context.$class === 'string') {
+            const nodeClass = context.$class;
+            // evaluate nodes, recursing on each child item
+            if (nodeRegExp.test(nodeClass)) {
+                const path = getJsonPath(templateMark, context, thisPath);
+                const variableValues = jsonpath_1.default.query(data, path, 1);
+                if (variableValues.length === 0) {
+                    throw new Error(`No values found for path '${path}' in data ${JSON.stringify(data)}.`);
+                }
+                else {
+                    const arrayData = variableValues[0];
+                    if (!Array.isArray(arrayData)) {
+                        throw new Error(`Values found for path '${path}' in data ${data} is not an array: ${arrayData}.`);
+                    }
+                    else {
+                        // The shape of the ListBlockDefinition's children depends on whether
+                        // the markdown parser produced a CommonMark List/Item wrapping. That
+                        // wrapping is only emitted when the items have leading list markers
+                        // (e.g. `- ` for ulist, `1. ` for olist). When users put direct
+                        // variable references inside `{{#ulist}}` / `{{#olist}}` with no
+                        // leading marker (see #145), the body is parsed as a single Paragraph
+                        // directly under the ListBlockDefinition.
+                        const firstChild = context.nodes[0];
+                        const hasListWrapper = firstChild &&
+                            firstChild.$class === `${markdown_common_1.CommonMarkModel.NAMESPACE}.List` &&
+                            Array.isArray(firstChild.nodes) &&
+                            firstChild.nodes.length > 0;
+                        // When wrapped, the per-iteration template is the first Item inside
+                        // the List. Otherwise the ListBlockDefinition's first child IS the
+                        // per-iteration template (typically a Paragraph).
+                        const itemTemplate = hasListWrapper ? firstChild.nodes[0] : firstChild;
+                        const nodes = [];
+                        for (let n = 0; n < arrayData.length; n++) {
+                            const arrayItem = arrayData[n];
+                            // arrayItem is now the data for the nested generation
+                            const subResult = await generateAgreement(modelManager, clauseLibrary, itemTemplate, arrayItem, options);
+                            // When the template had a List/Item wrapper, the processed Item's
+                            // children (a Paragraph) become the children of the new output Item.
+                            // Otherwise the processed block itself becomes the sole child of
+                            // the new output node, preserving a valid block hierarchy.
+                            const childNodes = hasListWrapper
+                                ? (subResult.nodes ? subResult.nodes : [])
+                                : [subResult];
+                            nodes.push({
+                                $class: childNodeClass,
+                                nodes: childNodes
+                            });
+                        }
+                        result[thisPath.join('/')] = nodes;
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Generates an AgreementMark JSON document from a template plus data.
+ * @param {ModelManager} modelManager - the template model
+ * @param {*} clauseLibrary - the clause library
+ * @param {*} templateMark - the TemplateMark JSON document
+ * @param {*} data - the template data JSON
+ * @param {[GenerationOptions]} options - the generation options
+ * @returns {*} the AgreementMark JSON
+ */
+async function generateAgreement(modelManager, clauseLibrary, templateMark, data, options) {
+    const introspector = new concerto_core_1.Introspector(modelManager);
+    // evaluate all the user code (async)
+    const userCodeResults = await evaluateUserCode(clauseLibrary, templateMark, data, options);
+    // evaluate all recursive blocks (async)
+    const listBlockResults = await generateRecursiveBlocks(modelManager, clauseLibrary, templateMark, data, TemplateMarkNodes_1.LISTBLOCK_DEFINITION_RE, `${markdown_common_1.CommonMarkModel.NAMESPACE}.Item`, options);
+    const foreachBlockResults = await generateRecursiveBlocks(modelManager, clauseLibrary, templateMark, data, TemplateMarkNodes_1.FOREACH_DEFINITION_RE, `${markdown_common_1.CommonMarkModel.NAMESPACE}.Paragraph`, options);
+    // evaluate all optional blocks (async)
+    const optionalBlockResults = await generateOptionalBlocks(modelManager, clauseLibrary, templateMark, data, options);
+    // traverse the templatemark, creating an output agreementmark tree
+    return (0, traverse_1.default)(templateMark).map(function (context) {
+        let stopHere = false;
+        if (typeof context === 'object' && context.$class && typeof context.$class === 'string') {
+            const nodeClass = context.$class;
+            // rewrite node types, mapping from TemplateMark namespace to CiceroMark
+            const match = nodeClass.match(TemplateMarkNodes_1.TEMPLATEMARK_RE);
+            if (match && match.length > 1) {
+                context.$class = `${markdown_common_1.CiceroMarkModel.NAMESPACE}.${match[3]}`;
+            }
+            // convert a contract node to a clause node (HACK)
+            if (TemplateMarkNodes_1.CONTRACT_DEFINITION_RE.test(nodeClass)) {
+                context.$class = `${markdown_common_1.CommonMarkModel.NAMESPACE}.Paragraph`;
+                delete context.name;
+                delete context.elementType;
+            }
+            // convert a WithDefinition to a Paragraph in the output
+            // not 100% sure we want to do that ... we may need to process
+            // the child variable nodes and reparent them?
+            if (TemplateMarkNodes_1.WITH_DEFINITION_RE.test(nodeClass)) {
+                context.$class = `${markdown_common_1.CommonMarkModel.NAMESPACE}.Paragraph`;
+                delete context.name;
+                delete context.elementType;
+            }
+            // add a 'value' property to FormulaDefinition
+            // with the result of evaluating the JS code
+            else if (TemplateMarkNodes_1.FORMULA_DEFINITION_RE.test(nodeClass)) {
+                if (context.code) {
+                    const result = userCodeResults[this.path.join('/')];
+                    if (result === null) {
+                        context.value = '<null>';
+                    }
+                    else if (typeof result === 'string') {
+                        context.value = result;
+                    }
+                    else {
+                        context.value = JSON.stringify(result);
+                    }
+                    delete context.code;
+                }
+                else {
+                    throw new Error('Formula node is missing code.');
+                }
+            }
+            // evaluate lists, recursing on each list item
+            else if (TemplateMarkNodes_1.LISTBLOCK_DEFINITION_RE.test(nodeClass)) {
+                context.$class = `${markdown_common_1.CommonMarkModel.NAMESPACE}.List`;
+                delete context.elementType;
+                delete context.name;
+                context.nodes = listBlockResults[this.path.join('/')];
+                stopHere = true; // do not process child nodes, we've already done it above...
+            }
+            // map over an array of items, joining them into a Text node
+            else if (TemplateMarkNodes_1.JOIN_DEFINITION_RE.test(nodeClass)) {
+                const path = getJsonPath(templateMark, context, this.path);
+                const variableValues = jsonpath_1.default.query(data, path, 1);
+                if (variableValues.length === 0) {
+                    throw new Error(`No values found for path '${path}' in data ${JSON.stringify(data)}.`);
+                }
+                else {
+                    const arrayData = variableValues[0];
+                    if (!Array.isArray(arrayData)) {
+                        throw new Error(`Values found for path '${path}' in data ${data} is not an array: ${arrayData}.`);
+                    }
+                    else {
+                        context.$class = `${markdown_common_1.CommonMarkModel.NAMESPACE}.Text`;
+                        const drafter = (0, drafting_1.getDrafter)(context.elementType);
+                        context.text = (0, TypeScriptRuntime_1.joinList)(arrayData.map(arrayItem => {
+                            return drafter ? drafter(arrayItem, context.format) : arrayItem;
+                        }), context, options);
+                        delete context.elementType;
+                        delete context.name;
+                        delete context.separator;
+                        delete context.locale;
+                        delete context.type;
+                        delete context.style;
+                        delete context.nodes;
+                        stopHere = true; // do not process child nodes, we've already done it above...
+                    }
+                }
+            }
+            // map over an array of items, joining them into a Text node
+            else if (TemplateMarkNodes_1.FOREACH_DEFINITION_RE.test(nodeClass)) {
+                context.$class = `${markdown_common_1.CommonMarkModel.NAMESPACE}.Foreach`;
+                delete context.elementType;
+                delete context.name;
+                context.nodes = foreachBlockResults[this.path.join('/')];
+                stopHere = true; // do not process child nodes, we've already done it above...
+            }
+            // add a 'value' property to VariableDefinition
+            // with the value of the variable from 'data'
+            else if (TemplateMarkNodes_1.VARIABLE_DEFINITION_RE.test(nodeClass) ||
+                TemplateMarkNodes_1.ENUM_VARIABLE_DEFINITION_RE.test(nodeClass) ||
+                TemplateMarkNodes_1.FORMATTED_VARIABLE_DEFINITION_RE.test(nodeClass)) {
+                if (typeof data === 'object') {
+                    const path = getJsonPath(templateMark, context, this.path);
+                    const variableValues = jsonpath_1.default.query(data, path, 1);
+                    if (variableValues.length === 0) {
+                        throw new Error(`No values found for path '${path}' in data ${JSON.stringify(data)}.`);
+                    }
+                    else {
+                        // convert the value to a string, optionally using the formatter
+                        const variableValue = variableValues[0];
+                        const type = concerto_core_2.ModelUtil.isPrimitiveType(context.elementType) ? null : introspector.getClassDeclaration(context.elementType);
+                        // we want to draft Enums as strings, not objects
+                        const drafter = (0, drafting_1.getDrafter)(type && type.isEnum() ? 'String' : context.elementType);
+                        context.value = drafter ? drafter(variableValue, context.format) : JSON.stringify(variableValue);
+                    }
+                }
+                else {
+                    // a list of enum values or primitives brings us here
+                    const variableValue = data;
+                    const type = concerto_core_2.ModelUtil.isPrimitiveType(context.elementType) ? null : introspector.getClassDeclaration(context.elementType);
+                    // we want to draft Enums as strings, not objects
+                    const drafter = (0, drafting_1.getDrafter)(type && type.isEnum() ? 'String' : context.elementType);
+                    context.value = drafter ? drafter(variableValue, context.format) : JSON.stringify(variableValue);
+                }
+            }
+            // add a 'isTrue' property to ConditionDefinition
+            // with the result of evaluating the JS code or a boolean property
+            else if (TemplateMarkNodes_1.CONDITIONAL_DEFINITION_RE.test(nodeClass)) {
+                if (context.condition) {
+                    const key = this.path.join('/');
+                    const resultStr = userCodeResults[key];
+                    if (resultStr === undefined || resultStr === null) {
+                        // Treat missing result as false (e.g., condition didn't return a value)
+                        context.isTrue = false;
+                    }
+                    else {
+                        try {
+                            // Parse the JSON-stringified result to get the actual boolean value
+                            context.isTrue = !!JSON.parse(resultStr);
+                        }
+                        catch (err) {
+                            throw new Error(`Invalid JSON boolean result for condition '${key}': ${String(err)}`);
+                        }
+                    }
+                }
+                else {
+                    const path = getJsonPath(templateMark, context, this.path);
+                    const variableValues = jsonpath_1.default.query(data, path, 1);
+                    if (variableValues && variableValues.length) {
+                        if (variableValues.length === 1) {
+                            context.isTrue = !!variableValues[0];
+                        }
+                        else {
+                            throw new Error(`Multiple values found for path '${path}' in data ${data}.`);
+                        }
+                    }
+                    else {
+                        context.isTrue = false;
+                    }
+                }
+                context.nodes = context.isTrue ? context.whenTrue : context.whenFalse;
+                delete context.condition;
+                delete context.dependencies;
+                delete context.functionName;
+            }
+            // only include the children of a clause if its condition is true
+            else if (TemplateMarkNodes_1.CLAUSE_DEFINITION_RE.test(nodeClass)) {
+                const path = getJsonPath(templateMark, context, this.path);
+                const variableValues = jsonpath_1.default.query(data, path, 1);
+                // If there's an explicit condition, evaluate it first (takes precedence over implicit check).
+                // This allows conditions like "return address!==undefined" to work correctly when
+                // the optional field is missing - the condition controls whether to render the clause.
+                if (context.condition) {
+                    checkCode(context.condition);
+                    const key = this.path.join('/');
+                    const resultStr = userCodeResults[key];
+                    let result = false;
+                    if (resultStr === undefined || resultStr === null) {
+                        // Treat missing result as false (e.g., condition didn't return a value)
+                        result = false;
+                    }
+                    else {
+                        try {
+                            // Parse the JSON-stringified result to get the actual boolean value
+                            result = !!JSON.parse(resultStr);
+                        }
+                        catch (err) {
+                            throw new Error(`Invalid JSON boolean result for condition '${key}': ${String(err)}`);
+                        }
+                    }
+                    if (!result) {
+                        delete context.nodes;
+                        stopHere = true;
+                    }
+                }
+                // Otherwise, apply implicit undefined check: skip clause block if scoped variable is undefined/null.
+                // Skip this check for the root template clause (name === 'top') since its data IS the root object.
+                else if (context.name !== 'top' && (variableValues.length === 0 || variableValues[0] === undefined || variableValues[0] === null)) {
+                    delete context.nodes;
+                    stopHere = true;
+                }
+                delete context.condition;
+                delete context.functionName;
+            }
+            // add a 'hasSome' property to OptionalDefinition
+            else if (TemplateMarkNodes_1.OPTIONAL_DEFINITION_RE.test(nodeClass)) {
+                const path = getJsonPath(templateMark, context, this.path);
+                const variableValues = jsonpath_1.default.query(data, path, 1);
+                if (variableValues && variableValues.length) {
+                    if (variableValues.length === 1) {
+                        context.hasSome = true;
+                        context.whenNone = [];
+                        // Check if we have processed optional blocks for this path
+                        if (optionalBlockResults[this.path.join('/')]) {
+                            context.nodes = optionalBlockResults[this.path.join('/')];
+                            // Set whenSome to empty since we've processed it, but keep the field for validation
+                            context.whenSome = [];
+                            stopHere = true; // do not process child nodes, we've already done it above...
+                        }
+                        else {
+                            context.nodes = context.whenSome;
+                        }
+                    }
+                    else {
+                        throw new Error(`Multiple values found for path '${path}' in data ${data}.`);
+                    }
+                }
+                else {
+                    context.hasSome = false;
+                    context.whenSome = [];
+                    context.nodes = context.whenNone;
+                }
+            }
+        }
+        this.update(context, stopHere);
+    });
+}
+/**
+ * A template engine: merges the markup and logic of a template with
+ * JSON data to produce JSON data.
+ */
+class TemplateMarkInterpreter {
+    constructor(modelManager, clauseLibrary, templateConceptFqn) {
+        this.modelManager = modelManager;
+        this.clauseLibrary = clauseLibrary;
+        this.templateClass = (0, utils_1.getTemplateClassDeclaration)(this.modelManager, templateConceptFqn);
+    }
+    /**
+     * Checks that a TemplateMark JSON document is valid with respect to the
+     * TemplateMark model, as well as the template model.
+     *
+     * Checks:
+     * 1. Variable names are valid properties in the template model
+     * 2. Optional properties have guards
+     * @param {*} templateMark the TemplateMark JSON object
+     * @returns {*} TemplateMark JSON that has been typed checked and has type metadata added
+     * @throws {Error} if the templateMark document is invalid
+     */
+    checkTypes(templateMark) {
+        const modelManager = new concerto_core_1.ModelManager();
+        modelManager.addCTOModel(markdown_common_1.ConcertoMetaModel.MODEL, 'concertometamodel.cto');
+        modelManager.addCTOModel(markdown_common_1.CommonMarkModel.MODEL, 'commonmark.cto');
+        modelManager.addCTOModel(markdown_common_1.TemplateMarkModel.MODEL, 'templatemark.cto');
+        const factory = new concerto_core_1.Factory(modelManager);
+        const serializer = new concerto_core_1.Serializer(factory, modelManager, {});
+        try {
+            serializer.fromJSON(templateMark, {});
+        }
+        catch (err) {
+            throw new Error(`Generated invalid agreement: ${err}: ${JSON.stringify(templateMark, null, 2)}`);
+        }
+        const errors = [];
+        const templateClass = this.templateClass;
+        const guardBlockPaths = new Map();
+        (0, traverse_1.default)(templateMark).forEach(function (node) {
+            if (!node || typeof node !== 'object' || !node.$class)
+                return;
+            const currentPath = this.path.join('/');
+            if (TemplateMarkNodes_1.OPTIONAL_DEFINITION_RE.test(node.$class) ||
+                TemplateMarkNodes_1.CONDITIONAL_DEFINITION_RE.test(node.$class) ||
+                TemplateMarkNodes_1.WITH_DEFINITION_RE.test(node.$class)) {
+                guardBlockPaths.set(node.name, currentPath);
+            }
+            if (TemplateMarkNodes_1.VARIABLE_DEFINITION_RE.test(node.$class) ||
+                TemplateMarkNodes_1.ENUM_VARIABLE_DEFINITION_RE.test(node.$class) ||
+                TemplateMarkNodes_1.FORMATTED_VARIABLE_DEFINITION_RE.test(node.$class)) {
+                const propName = node.name;
+                if (propName && propName !== 'this') {
+                    try {
+                        const property = templateClass.getProperty(propName);
+                        if (property && property.isOptional()) {
+                            const guardPath = guardBlockPaths.get(propName);
+                            const isGuarded = guardPath !== undefined &&
+                                (currentPath === guardPath || currentPath.startsWith(guardPath + '/'));
+                            if (!isGuarded) {
+                                errors.push({
+                                    propertyName: propName,
+                                    message: `Optional property '${propName}' is used without a guard. Wrap it in {{#optional ${propName}}}...{{/optional}} or {{#if ${propName}}}...{{/if}}.`
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // Property not found at root level, might be nested - skip
+                    }
+                }
+            }
+        });
+        if (errors.length > 0) {
+            const errorMessage = `Optional properties used without guards: ${errors.map(e => e.propertyName).join(', ')}`;
+            const error = new Error(errorMessage);
+            error.errors = errors;
+            throw error;
+        }
+        return templateMark;
+    }
+    /**
+     * Compiles the code nodes containing TS to code nodes containing JS.
+     * @param {*} templateMark the TemplateMark JSON object
+     * @returns {*} TemplateMark JSON with JS nodes
+     * @throws {Error} if the templateMark document is invalid
+     */
+    async compileTypeScriptToJavaScript(templateMark) {
+        const clazz = templateMark.$class;
+        if (clazz !== DOCUMENT_ROOT) {
+            throw new Error(`JSON is not CommonMark. $class is '${clazz}'. ${JSON.stringify(templateMark, null, 2)}`);
+        }
+        if (!templateMark.nodes || !templateMark.nodes.length || templateMark.nodes.length < 1) {
+            throw new Error(`CommonMark does not have nodes: ${JSON.stringify(templateMark, null, 2)}`);
+        }
+        const firstChild = templateMark.nodes[0];
+        const firstChildClazz = firstChild.$class;
+        if (!TEMPLATEMARK_ROOT_NODES.includes(firstChildClazz)) {
+            throw new Error(`First child is not templatemark. $class is '${firstChildClazz}'. ${JSON.stringify(templateMark, null, 2)}`);
+        }
+        const templateConcept = firstChild.elementType;
+        if (!templateConcept) {
+            throw new Error(`First child is not typed: ${JSON.stringify(templateMark, null, 2)}`);
+        }
+        if (firstChild.name !== 'top') {
+            throw new Error('First child is not named "top"!');
+        }
+        const compiler = new TemplateMarkToJavaScriptCompiler_1.TemplateMarkToJavaScriptCompiler(this.modelManager, templateConcept);
+        await compiler.initialize();
+        return compiler.compile(templateMark);
+    }
+    validateCiceroMark(ciceroMark) {
+        const modelManager = new concerto_core_1.ModelManager();
+        modelManager.addCTOModel(markdown_common_1.ConcertoMetaModel.MODEL, 'concertometamodel.cto');
+        modelManager.addCTOModel(markdown_common_1.CommonMarkModel.MODEL, 'commonmark.cto');
+        modelManager.addCTOModel(markdown_common_1.CiceroMarkModel.MODEL, 'ciceromark.cto');
+        const factory = new concerto_core_1.Factory(modelManager);
+        const serializer = new concerto_core_1.Serializer(factory, modelManager, {});
+        try {
+            return serializer.fromJSON(ciceroMark, {});
+        }
+        catch (err) {
+            throw new Error(`Generated invalid agreement: ${err}: ${JSON.stringify(ciceroMark, null, 2)}`);
+        }
+    }
+    async generate(templateMark, data, options) {
+        const factory = new concerto_core_1.Factory(this.modelManager);
+        const serializer = new concerto_core_1.Serializer(factory, this.modelManager, {});
+        const templateData = serializer.fromJSON(data, {});
+        if (templateData.getFullyQualifiedType() !== this.templateClass.getFullyQualifiedName()) {
+            throw new Error(`Template data must be of type '${this.templateClass.getFullyQualifiedName()}'.`);
+        }
+        const typedTemplateMark = this.checkTypes(templateMark);
+        const jsTemplateMark = await this.compileTypeScriptToJavaScript(typedTemplateMark);
+        // console.log('Compiled JS: ' + JSON.stringify(jsTemplateMark, null, 2));
+        const ciceroMark = await generateAgreement(this.modelManager, this.clauseLibrary, jsTemplateMark, data, options);
+        // console.log('Generated AgreementMark');
+        return this.validateCiceroMark(ciceroMark);
+    }
+}
+exports.TemplateMarkInterpreter = TemplateMarkInterpreter;
+//# sourceMappingURL=TemplateMarkInterpreter.js.map