@malloydata/motly-ts-parser 0.0.1 → 0.2.0

package/build/ast.d.ts

@@ -15,6 +15,11 @@ export type ScalarValue = {
     kind: "reference";
     ups: number;
     path: RefPathSegment[];
+} | {
+    kind: "none";
+} | {
+    kind: "env";
+    name: string;
 };
 /** A segment in a reference path: either a named property or an array index. */
 export type RefPathSegment = {
@@ -43,12 +48,15 @@ export type Statement = {
     path: string[];
     value: TagValue;
     properties: Statement[] | null;
-    preserveProperties: boolean;
+} | {
+    kind: "assignBoth";
+    path: string[];
+    value: TagValue;
+    properties: Statement[] | null;
 } | {
     kind: "replaceProperties";
     path: string[];
     properties: Statement[];
-    preserveValue: boolean;
 } | {
     kind: "updateProperties";
     path: string[];

package/build/clone.d.ts

@@ -0,0 +1,3 @@
+import { MOTLYValue } from "motly-ts-interface";
+/** Deep clone a MOTLYValue. */
+export declare function cloneValue(value: MOTLYValue): MOTLYValue;

package/build/clone.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneValue = cloneValue;
+const motly_ts_interface_1 = require("motly-ts-interface");
+/** Deep clone a MOTLYValue. */
+function cloneValue(value) {
+    const result = {};
+    if (value.deleted)
+        result.deleted = true;
+    if (value.eq !== undefined) {
+        if (value.eq instanceof Date) {
+            result.eq = new Date(value.eq.getTime());
+        }
+        else if (Array.isArray(value.eq)) {
+            result.eq = value.eq.map(cloneValue);
+        }
+        else if ((0, motly_ts_interface_1.isRef)(value.eq)) {
+            result.eq = { linkTo: value.eq.linkTo };
+        }
+        else if ((0, motly_ts_interface_1.isEnvRef)(value.eq)) {
+            result.eq = { env: value.eq.env };
+        }
+        else {
+            result.eq = value.eq;
+        }
+    }
+    if (value.properties) {
+        const props = {};
+        for (const key of Object.keys(value.properties)) {
+            props[key] = cloneValue(value.properties[key]);
+        }
+        result.properties = props;
+    }
+    return result;
+}

package/build/index.d.ts

@@ -1,2 +1,3 @@
-export type { MOTLYScalar, MOTLYRef, MOTLYValue, MOTLYNode, MOTLYError, MOTLYSchemaError, MOTLYValidationError, } from "motly-ts-interface";
+export type { MOTLYScalar, MOTLYRef, MOTLYEnvRef, MOTLYValue, MOTLYNode, MOTLYError, MOTLYSchemaError, MOTLYValidationError, } from "motly-ts-interface";
+export { isRef, isEnvRef } from "motly-ts-interface";
 export { MOTLYSession } from "./session";

package/build/index.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MOTLYSession = void 0;
+exports.MOTLYSession = exports.isEnvRef = exports.isRef = void 0;
+var motly_ts_interface_1 = require("motly-ts-interface");
+Object.defineProperty(exports, "isRef", { enumerable: true, get: function () { return motly_ts_interface_1.isRef; } });
+Object.defineProperty(exports, "isEnvRef", { enumerable: true, get: function () { return motly_ts_interface_1.isEnvRef; } });
 var session_1 = require("./session");
 Object.defineProperty(exports, "MOTLYSession", { enumerable: true, get: function () { return session_1.MOTLYSession; } });

package/build/interpreter.d.ts

@@ -1,4 +1,4 @@
 import { Statement } from "./ast";
-import { MOTLYValue } from "motly-ts-interface";
+import { MOTLYValue, MOTLYError } from "motly-ts-interface";
 /** Execute a list of parsed statements against an existing MOTLYValue. */
-export declare function execute(statements: Statement[], root: MOTLYValue): MOTLYValue;
+export declare function execute(statements: Statement[], root: MOTLYValue): MOTLYError[];

package/build/interpreter.js

@@ -1,93 +1,123 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execute = execute;
+const motly_ts_interface_1 = require("motly-ts-interface");
+const clone_1 = require("./clone");
 /** Execute a list of parsed statements against an existing MOTLYValue. */
 function execute(statements, root) {
+    const errors = [];
     for (const stmt of statements) {
-        executeStatement(stmt, root);
+        executeStatement(stmt, root, errors);
     }
-    return root;
+    return errors;
 }
-function executeStatement(stmt, node) {
+function executeStatement(stmt, node, errors) {
     switch (stmt.kind) {
         case "setEq":
-            executeSetEq(node, stmt.path, stmt.value, stmt.properties, stmt.preserveProperties);
+            executeSetEq(node, stmt.path, stmt.value, stmt.properties, errors);
+            break;
+        case "assignBoth":
+            executeAssignBoth(node, stmt.path, stmt.value, stmt.properties, errors);
             break;
         case "replaceProperties":
-            executeReplaceProperties(node, stmt.path, stmt.properties, stmt.preserveValue);
+            executeReplaceProperties(node, stmt.path, stmt.properties, errors);
             break;
         case "updateProperties":
-            executeUpdateProperties(node, stmt.path, stmt.properties);
+            executeUpdateProperties(node, stmt.path, stmt.properties, errors);
             break;
         case "define":
             executeDefine(node, stmt.path, stmt.deleted);
             break;
         case "clearAll":
+            delete node.eq;
             node.properties = {};
             break;
     }
 }
-function executeSetEq(node, path, value, properties, preserveProperties) {
-    // Reference without properties → produce a link
-    if (value.kind === "scalar" &&
-        value.value.kind === "reference" &&
-        properties === null &&
-        !preserveProperties) {
-        const [writeKey, parent] = buildAccessPath(node, path);
-        const props = getOrCreateProperties(parent);
-        props[writeKey] = {
-            linkTo: formatRefString(value.value.ups, value.value.path),
-        };
-        return;
-    }
+/**
+ * `name = value` — set eq, preserve existing properties.
+ * `name = value { props }` — set eq, then merge properties.
+ */
+function executeSetEq(node, path, value, properties, errors) {
     const [writeKey, parent] = buildAccessPath(node, path);
+    const props = getOrCreateProperties(parent);
+    // Get or create target (preserves existing node and its properties)
+    let target = props[writeKey];
+    if (target === undefined) {
+        target = {};
+        props[writeKey] = target;
+    }
+    // Set the value slot
+    setEqSlot(target, value);
+    // If properties block present, MERGE them
     if (properties !== null) {
-        // name = value { new_properties } - set value and replace properties
-        const result = createValueNode(value);
         for (const s of properties) {
-            executeStatement(s, result);
-        }
-        const props = getOrCreateProperties(parent);
-        props[writeKey] = result;
-    }
-    else if (preserveProperties) {
-        // name = value { ... } - update value, preserve existing properties
-        const props = getOrCreateProperties(parent);
-        const existing = props[writeKey];
-        if (existing !== undefined && !isRef(existing)) {
-            const result = createValueNode(value);
-            if (existing.properties) {
-                result.properties = existing.properties;
+            executeStatement(s, target, errors);
+        }
+    }
+}
+/**
+ * `name := value` — assign value + clear properties.
+ * `name := value { props }` — assign value + replace properties.
+ * `name := $ref` — clone the referenced subtree.
+ * `name := $ref { props }` — clone + replace properties.
+ */
+function executeAssignBoth(node, path, value, properties, errors) {
+    if (value.kind === "scalar" &&
+        value.value.kind === "reference") {
+        // CLONE semantics: resolve + deep copy the target
+        let cloned;
+        try {
+            cloned = resolveAndClone(node, path, value.value.ups, value.value.path);
+        }
+        catch (err) {
+            if (err && typeof err === "object" && "code" in err) {
+                errors.push(err);
             }
-            props[writeKey] = result;
+            return;
         }
-        else {
-            props[writeKey] = createValueNode(value);
+        // Check for relative references that escape the clone boundary
+        sanitizeClonedRefs(cloned, 0, errors);
+        if (properties !== null) {
+            cloned.properties = {};
+            for (const s of properties) {
+                executeStatement(s, cloned, errors);
+            }
         }
+        const [writeKey, parent] = buildAccessPath(node, path);
+        getOrCreateProperties(parent)[writeKey] = cloned;
     }
     else {
-        // name = value - simple assignment
-        const props = getOrCreateProperties(parent);
-        props[writeKey] = createValueNode(value);
+        // Literal value: create fresh node (replaces everything)
+        const result = {};
+        setEqSlot(result, value);
+        if (properties !== null) {
+            for (const s of properties) {
+                executeStatement(s, result, errors);
+            }
+        }
+        const [writeKey, parent] = buildAccessPath(node, path);
+        getOrCreateProperties(parent)[writeKey] = result;
     }
 }
-function executeReplaceProperties(node, path, properties, preserveValue) {
+/**
+ * `name: { props }` — preserve existing value, replace properties.
+ */
+function executeReplaceProperties(node, path, properties, errors) {
     const [writeKey, parent] = buildAccessPath(node, path);
     const result = {};
-    if (preserveValue) {
-        const props = getOrCreateProperties(parent);
-        const existing = props[writeKey];
-        if (existing !== undefined && !isRef(existing)) {
-            result.eq = existing.eq;
-        }
+    // Always preserve the existing value
+    const parentProps = getOrCreateProperties(parent);
+    const existing = parentProps[writeKey];
+    if (existing !== undefined) {
+        result.eq = existing.eq;
     }
     for (const stmt of properties) {
-        executeStatement(stmt, result);
+        executeStatement(stmt, result, errors);
     }
-    const props = getOrCreateProperties(parent);
-    props[writeKey] = result;
+    parentProps[writeKey] = result;
 }
-function executeUpdateProperties(node, path, properties) {
+function executeUpdateProperties(node, path, properties, errors) {
     const [writeKey, parent] = buildAccessPath(node, path);
     const props = getOrCreateProperties(parent);
     let target = props[writeKey];
@@ -95,17 +125,8 @@ function executeUpdateProperties(node, path, properties) {
         target = {};
         props[writeKey] = target;
     }
-    if (isRef(target)) {
-        const newNode = {};
-        for (const stmt of properties) {
-            executeStatement(stmt, newNode);
-        }
-        props[writeKey] = newNode;
-    }
-    else {
-        for (const stmt of properties) {
-            executeStatement(stmt, target);
-        }
+    for (const stmt of properties) {
+        executeStatement(stmt, target, errors);
     }
 }
 function executeDefine(node, path, deleted) {
@@ -115,7 +136,10 @@ function executeDefine(node, path, deleted) {
         props[writeKey] = { deleted: true };
     }
     else {
-        props[writeKey] = {};
+        // Get-or-create: if node already exists, leave it alone
+        if (props[writeKey] === undefined) {
+            props[writeKey] = {};
+        }
     }
 }
 /** Navigate to the parent of the final path segment, creating intermediate nodes. */
@@ -129,77 +153,54 @@ function buildAccessPath(node, path) {
             entry = {};
             props[segment] = entry;
         }
-        if (isRef(entry)) {
-            entry = {};
-            props[segment] = entry;
-        }
         current = entry;
     }
     return [path[path.length - 1], current];
 }
-/** Convert an AST TagValue to a MOTLYValue. */
-function createValueNode(value) {
+/** Set the eq slot on a target node from a TagValue. */
+function setEqSlot(target, value, errors) {
     if (value.kind === "array") {
-        return { eq: resolveArray(value.elements) };
-    }
-    const sv = value.value;
-    switch (sv.kind) {
-        case "string":
-            return { eq: sv.value };
-        case "number":
-            return { eq: sv.value };
-        case "boolean":
-            return { eq: sv.value };
-        case "date":
-            return { eq: new Date(sv.value) };
-        case "reference":
-            // Should not be reached for simple ref assignments (handled above).
-            return {};
+        target.eq = resolveArray(value.elements, errors ?? []);
+    }
+    else {
+        const sv = value.value;
+        switch (sv.kind) {
+            case "string":
+                target.eq = sv.value;
+                break;
+            case "number":
+                target.eq = sv.value;
+                break;
+            case "boolean":
+                target.eq = sv.value;
+                break;
+            case "date":
+                target.eq = new Date(sv.value);
+                break;
+            case "reference":
+                target.eq = { linkTo: formatRefString(sv.ups, sv.path) };
+                break;
+            case "env":
+                target.eq = { env: sv.name };
+                break;
+            case "none":
+                delete target.eq;
+                break;
+        }
     }
 }
 /** Resolve an array of AST elements to MOTLYNodes. */
-function resolveArray(elements) {
-    return elements.map(resolveArrayElement);
-}
-function resolveArrayElement(el) {
-    // Reference without properties becomes a link
-    if (el.value !== null &&
-        el.value.kind === "scalar" &&
-        el.value.value.kind === "reference" &&
-        el.properties === null) {
-        return {
-            linkTo: formatRefString(el.value.value.ups, el.value.value.path),
-        };
-    }
+function resolveArray(elements, errors) {
+    return elements.map((el) => resolveArrayElement(el, errors));
+}
+function resolveArrayElement(el, errors) {
     const node = {};
     if (el.value !== null) {
-        if (el.value.kind === "array") {
-            node.eq = resolveArray(el.value.elements);
-        }
-        else {
-            const sv = el.value.value;
-            switch (sv.kind) {
-                case "string":
-                    node.eq = sv.value;
-                    break;
-                case "number":
-                    node.eq = sv.value;
-                    break;
-                case "boolean":
-                    node.eq = sv.value;
-                    break;
-                case "date":
-                    node.eq = new Date(sv.value);
-                    break;
-                case "reference":
-                    // Reference with properties: ignore the reference value
-                    break;
-            }
-        }
+        setEqSlot(node, el.value);
     }
     if (el.properties !== null) {
         for (const stmt of el.properties) {
-            executeStatement(stmt, node);
+            executeStatement(stmt, node, errors);
         }
     }
     return node;
@@ -223,9 +224,97 @@ function formatRefString(ups, path) {
     }
     return s;
 }
-/** Check if a MOTLYNode is a MOTLYRef. */
-function isRef(node) {
-    return "linkTo" in node;
+/** Resolve a reference path in the tree and return a deep clone. */
+function resolveAndClone(root, stmtPath, ups, refPath) {
+    const refStr = formatRefString(ups, refPath);
+    let start;
+    if (ups === 0) {
+        // Absolute reference: start at root
+        start = root;
+    }
+    else {
+        // Relative reference: go up from the current context.
+        // stmtPath is the full write path (including the key being assigned to).
+        // Current context = parent of write target = stmtPath[0..len-2].
+        // Going up `ups` levels: stmtPath[0..len-2-ups].
+        const contextLen = stmtPath.length - 1 - ups;
+        if (contextLen < 0) {
+            throw cloneError(`Clone reference ${refStr} goes ${ups} level(s) up but only ${stmtPath.length - 1} ancestor(s) available`);
+        }
+        start = root;
+        for (let i = 0; i < contextLen; i++) {
+            if (!start.properties || !start.properties[stmtPath[i]]) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: path segment "${stmtPath[i]}" not found`);
+            }
+            start = start.properties[stmtPath[i]];
+        }
+    }
+    // Follow refPath segments
+    let current = start;
+    for (const seg of refPath) {
+        if (seg.kind === "name") {
+            if (!current.properties || !current.properties[seg.name]) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: property "${seg.name}" not found`);
+            }
+            current = current.properties[seg.name];
+        }
+        else {
+            if (!current.eq || !Array.isArray(current.eq)) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: index [${seg.index}] used on non-array`);
+            }
+            if (seg.index >= current.eq.length) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: index [${seg.index}] out of bounds (array length ${current.eq.length})`);
+            }
+            current = current.eq[seg.index];
+        }
+    }
+    return (0, clone_1.cloneValue)(current);
+}
+function cloneError(message) {
+    const zero = { line: 0, column: 0, offset: 0 };
+    return { code: "unresolved-clone-reference", message, begin: zero, end: zero };
+}
+/**
+ * Walk a cloned subtree and null out any relative (^) references that
+ * escape the clone boundary. A reference at depth D with N ups escapes
+ * if N > D. Absolute references (ups=0) are left alone.
+ */
+function sanitizeClonedRefs(node, depth, errors) {
+    if ((0, motly_ts_interface_1.isRef)(node.eq)) {
+        const parsed = parseRefUps(node.eq.linkTo);
+        if (parsed.ups > 0 && parsed.ups > depth) {
+            const zero = { line: 0, column: 0, offset: 0 };
+            errors.push({
+                code: "clone-reference-out-of-scope",
+                message: `Cloned reference "${node.eq.linkTo}" escapes the clone boundary (${parsed.ups} level(s) up from depth ${depth})`,
+                begin: zero,
+                end: zero,
+            });
+            delete node.eq;
+        }
+    }
+    if (node.eq !== undefined && Array.isArray(node.eq)) {
+        for (const elem of node.eq) {
+            sanitizeClonedRefs(elem, depth + 1, errors);
+        }
+    }
+    if (node.properties) {
+        for (const key of Object.keys(node.properties)) {
+            sanitizeClonedRefs(node.properties[key], depth + 1, errors);
+        }
+    }
+}
+/** Extract the ups count from a linkTo string like "$^^name". */
+function parseRefUps(linkTo) {
+    let i = 0;
+    if (i < linkTo.length && linkTo[i] === "$")
+        i++;
+    let ups = 0;
+    while (i < linkTo.length && linkTo[i] === "^") {
+        ups++;
+        i++;
+    }
+    return { ups };
 }
 /** Get or create the properties object on a MOTLYValue. */
 function getOrCreateProperties(node) {

package/build/parser.js

@@ -7,9 +7,6 @@ class Parser {
         this.pos = 0;
     }
     // ── Helpers ──────────────────────────────────────────────────────
-    remaining() {
-        return this.input.substring(this.pos);
-    }
     peekChar() {
         return this.pos < this.input.length ? this.input[this.pos] : undefined;
     }
@@ -80,13 +77,25 @@ class Parser {
             }
         }
     }
+    /**
+     * Like `skipWs`, but also eats commas. Used in statement-list
+     * contexts (top-level document and properties blocks) so commas
+     * can serve as optional separators between statements.
+     */
+    skipWsAndCommas() {
+        this.skipWs();
+        while (this.peekChar() === ",") {
+            this.advance(1);
+            this.skipWs();
+        }
+    }
     // ── Statement Dispatch ──────────────────────────────────────────
     parseStatements() {
         const statements = [];
-        this.skipWs();
+        this.skipWsAndCommas();
         while (this.pos < this.input.length) {
             statements.push(this.parseStatement());
-            this.skipWs();
+            this.skipWsAndCommas();
         }
         return statements;
     }
@@ -106,87 +115,40 @@ class Parser {
         const path = this.parsePropName();
         this.skipWs();
         const ch = this.peekChar();
+        // Check := first (MUST check before : alone)
+        if (ch === ":" && this.startsWith(":=")) {
+            this.advance(2);
+            this.skipWs();
+            const value = this.parseEqValue();
+            this.skipWs();
+            if (this.peekChar() === "{") {
+                const props = this.parsePropertiesBlock();
+                return { kind: "assignBoth", path, value, properties: props };
+            }
+            return { kind: "assignBoth", path, value, properties: null };
+        }
         if (ch === "=") {
             this.advance(1);
             this.skipWs();
-            // Check for `= ... {` (replaceProperties with preserveValue)
-            if (this.startsWith("...")) {
-                const saved = this.pos;
-                this.advance(3);
-                this.skipWs();
-                if (this.peekChar() === "{") {
-                    const props = this.parsePropertiesBlock();
-                    return {
-                        kind: "replaceProperties",
-                        path,
-                        properties: props,
-                        preserveValue: true,
-                    };
-                }
-                this.pos = saved;
-            }
-            // Check for `= {` (replaceProperties without preserveValue)
+            // = { is now a parse error (= requires a value)
             if (this.peekChar() === "{") {
-                const props = this.parsePropertiesBlock();
-                return {
-                    kind: "replaceProperties",
-                    path,
-                    properties: props,
-                    preserveValue: false,
-                };
+                throw this.errorPoint("'=' requires a value; use ': { ... }' to replace properties");
             }
-            // `= value` (setEq)
+            // = value
             const value = this.parseEqValue();
             this.skipWs();
-            // Optionally followed by `{ ... }` or `{ statements }`
+            // Optional { props } block (MERGE semantics)
             if (this.peekChar() === "{") {
-                const saved = this.pos;
-                this.advance(1);
-                this.skipWs();
-                if (this.startsWith("...")) {
-                    const saved2 = this.pos;
-                    this.advance(3);
-                    this.skipWs();
-                    if (this.peekChar() === "}") {
-                        this.advance(1);
-                        return {
-                            kind: "setEq",
-                            path,
-                            value,
-                            properties: null,
-                            preserveProperties: true,
-                        };
-                    }
-                    this.pos = saved2;
-                }
-                this.pos = saved;
                 const props = this.parsePropertiesBlock();
-                return {
-                    kind: "setEq",
-                    path,
-                    value,
-                    properties: props,
-                    preserveProperties: false,
-                };
+                return { kind: "setEq", path, value, properties: props };
             }
-            return {
-                kind: "setEq",
-                path,
-                value,
-                properties: null,
-                preserveProperties: false,
-            };
+            return { kind: "setEq", path, value, properties: null };
         }
         if (ch === ":") {
             this.advance(1);
             this.skipWs();
             const props = this.parsePropertiesBlock();
-            return {
-                kind: "replaceProperties",
-                path,
-                properties: props,
-                preserveValue: false,
-            };
+            return { kind: "replaceProperties", path, properties: props };
         }
         if (ch === "{") {
             const props = this.parsePropertiesBlock();
@@ -211,55 +173,16 @@ class Parser {
         return this.parseBareString();
     }
     // ── Values ──────────────────────────────────────────────────────
-    parseEqValue() {
+    parseEqValue(allowArrays = true) {
         const ch = this.peekChar();
-        if (ch === "[")
+        if (allowArrays && ch === "[")
             return { kind: "array", elements: this.parseArray() };
-        if (ch === "@")
-            return { kind: "scalar", value: this.parseAtValue() };
-        if (ch === "$")
-            return { kind: "scalar", value: this.parseReference() };
-        if (ch === '"') {
-            if (this.startsWith('"""')) {
-                return {
-                    kind: "scalar",
-                    value: { kind: "string", value: this.parseTripleString() },
-                };
-            }
+        if (this.startsWith("<<<")) {
             return {
                 kind: "scalar",
-                value: { kind: "string", value: this.parseDoubleQuotedString() },
+                value: { kind: "string", value: this.parseHeredoc() },
             };
         }
-        if (ch === "'") {
-            if (this.startsWith("'''")) {
-                return {
-                    kind: "scalar",
-                    value: {
-                        kind: "string",
-                        value: this.parseTripleSingleQuotedString(),
-                    },
-                };
-            }
-            return {
-                kind: "scalar",
-                value: { kind: "string", value: this.parseSingleQuotedString() },
-            };
-        }
-        if (ch !== undefined &&
-            (ch === "-" || (ch >= "0" && ch <= "9") || ch === ".")) {
-            return this.parseNumberOrString();
-        }
-        if (ch !== undefined && isBareChar(ch)) {
-            return {
-                kind: "scalar",
-                value: { kind: "string", value: this.parseBareString() },
-            };
-        }
-        throw this.errorPoint("Expected a value");
-    }
-    parseScalarValue() {
-        const ch = this.peekChar();
         if (ch === "@")
             return { kind: "scalar", value: this.parseAtValue() };
         if (ch === "$")
@@ -292,7 +215,7 @@ class Parser {
             };
         }
         if (ch !== undefined &&
-            ((ch >= "0" && ch <= "9") || ch === "." || ch === "-")) {
+            (ch === "-" || (ch >= "0" && ch <= "9") || ch === ".")) {
             return this.parseNumberOrString();
         }
         if (ch !== undefined && isBareChar(ch)) {
@@ -303,7 +226,7 @@ class Parser {
         }
         throw this.errorPoint("Expected a value");
     }
-    /** Parse `@true`, `@false`, or `@date` */
+    /** Parse `@true`, `@false`, `@none`, `@env.NAME`, or `@date` */
     parseAtValue() {
         const begin = this.position();
         this.expectChar("@");
@@ -315,6 +238,15 @@ class Parser {
             this.advance(5);
             return { kind: "boolean", value: false };
         }
+        if (this.startsWith("none") && !this.isBareCharAt(4)) {
+            this.advance(4);
+            return { kind: "none" };
+        }
+        if (this.startsWith("env.")) {
+            this.advance(4);
+            const name = this.parseBareString();
+            return { kind: "env", name };
+        }
         const ch = this.peekChar();
         if (ch !== undefined && ch >= "0" && ch <= "9") {
             return this.parseDate(begin);
@@ -325,11 +257,11 @@ class Parser {
             this.pos++;
         }
         const token = this.pos > tokenStart ? this.input.substring(tokenStart, this.pos) : "";
-        throw this.errorSpan(`Illegal constant @${token}; expected @true, @false, or @date`, begin);
+        throw this.errorSpan(`Illegal constant @${token}; expected @true, @false, @none, @env.NAME, or @date`, begin);
     }
     isBareCharAt(offset) {
-        const rem = this.remaining();
-        return offset < rem.length && isBareChar(rem[offset]);
+        const absPos = this.pos + offset;
+        return absPos < this.input.length && isBareChar(this.input[absPos]);
     }
     parseDate(begin) {
         const start = this.pos;
@@ -710,6 +642,79 @@ class Parser {
                 return ch;
         }
     }
+    // ── Heredoc ─────────────────────────────────────────────────────
+    parseHeredoc() {
+        const begin = this.position();
+        this.advance(3); // past <<<
+        // Skip spaces/tabs on the same line
+        while (this.pos < this.input.length) {
+            const ch = this.input[this.pos];
+            if (ch === " " || ch === "\t") {
+                this.pos++;
+            }
+            else {
+                break;
+            }
+        }
+        // Allow \r before \n
+        if (this.pos < this.input.length && this.input[this.pos] === "\r") {
+            this.advance(1);
+        }
+        // Expect newline
+        if (this.pos >= this.input.length || this.input[this.pos] !== "\n") {
+            throw this.errorSpan("Expected newline after <<<", begin);
+        }
+        this.advance(1);
+        // Collect lines until we find >>> on its own line
+        const lines = [];
+        let foundClose = false;
+        while (this.pos < this.input.length) {
+            // Read a line (break only on \n)
+            const lineStart = this.pos;
+            while (this.pos < this.input.length && this.input[this.pos] !== "\n") {
+                this.pos++;
+            }
+            // Strip trailing \r for CRLF compatibility
+            let lineContent = this.input.substring(lineStart, this.pos);
+            if (lineContent.endsWith("\r")) {
+                lineContent = lineContent.substring(0, lineContent.length - 1);
+            }
+            // Consume the \n
+            if (this.pos < this.input.length && this.input[this.pos] === "\n") {
+                this.advance(1);
+            }
+            // Check if this is the closing >>> line
+            if (lineContent.trim() === ">>>") {
+                foundClose = true;
+                break;
+            }
+            lines.push(lineContent);
+        }
+        if (!foundClose) {
+            throw this.errorSpan("Unterminated heredoc (expected >>>)", begin);
+        }
+        if (lines.length === 0) {
+            return "";
+        }
+        // Determine strip amount from first line containing a non-space character
+        let strip = 0;
+        for (const line of lines) {
+            const trimmed = line.trimStart();
+            if (trimmed.length > 0) {
+                strip = line.length - trimmed.length;
+                break;
+            }
+        }
+        // Strip indentation and join; whitespace-only lines become empty
+        const stripped = lines.map((line) => {
+            if (line.trimStart().length === 0)
+                return "";
+            if (strip <= line.length)
+                return line.substring(strip);
+            return line;
+        });
+        return stripped.join("\n") + "\n";
+    }
     // ── Arrays ──────────────────────────────────────────────────────
     parseArray() {
         const begin = this.position();
@@ -750,7 +755,7 @@ class Parser {
             const elements = this.parseArray();
             return { value: { kind: "array", elements }, properties: null };
         }
-        const value = this.parseScalarValue();
+        const value = this.parseEqValue(false);
         this.skipWs();
         if (this.peekChar() === "{") {
             const props = this.parsePropertiesBlock();
@@ -762,20 +767,9 @@ class Parser {
     parsePropertiesBlock() {
         const begin = this.position();
         this.expectChar("{");
-        this.skipWs();
-        if (this.startsWith("...")) {
-            const saved = this.pos;
-            this.advance(3);
-            this.skipWs();
-            if (this.peekChar() === "}") {
-                this.advance(1);
-                return [];
-            }
-            this.pos = saved;
-        }
         const stmts = [];
         for (;;) {
-            this.skipWs();
+            this.skipWsAndCommas();
             if (this.eatChar("}"))
                 return stmts;
             if (this.pos >= this.input.length) {

package/build/session.js

@@ -4,6 +4,7 @@ exports.MOTLYSession = void 0;
 const parser_1 = require("./parser");
 const interpreter_1 = require("./interpreter");
 const validate_1 = require("./validate");
+const clone_1 = require("./clone");
 /**
  * A stateful MOTLY parsing session.
  *
@@ -24,8 +25,8 @@ class MOTLYSession {
         this.ensureAlive();
         try {
             const stmts = (0, parser_1.parse)(source);
-            this.value = (0, interpreter_1.execute)(stmts, this.value);
-            return [];
+            const errors = (0, interpreter_1.execute)(stmts, this.value);
+            return errors;
         }
         catch (e) {
             if (isMotlyError(e))
@@ -41,8 +42,10 @@ class MOTLYSession {
         this.ensureAlive();
         try {
             const stmts = (0, parser_1.parse)(source);
-            this.schema = (0, interpreter_1.execute)(stmts, {});
-            return [];
+            const fresh = {};
+            const errors = (0, interpreter_1.execute)(stmts, fresh);
+            this.schema = fresh;
+            return errors;
         }
         catch (e) {
             if (isMotlyError(e))
@@ -62,7 +65,7 @@ class MOTLYSession {
      */
     getValue() {
         this.ensureAlive();
-        return deepClone(this.value);
+        return (0, clone_1.cloneValue)(this.value);
     }
     /**
      * Validate the session's value against its stored schema.
@@ -103,33 +106,3 @@ function isMotlyError(e) {
         "begin" in e &&
         "end" in e);
 }
-function deepClone(value) {
-    const result = {};
-    if (value.deleted)
-        result.deleted = true;
-    if (value.eq !== undefined) {
-        if (value.eq instanceof Date) {
-            result.eq = new Date(value.eq.getTime());
-        }
-        else if (Array.isArray(value.eq)) {
-            result.eq = value.eq.map(cloneNode);
-        }
-        else {
-            result.eq = value.eq;
-        }
-    }
-    if (value.properties) {
-        const props = {};
-        for (const key of Object.keys(value.properties)) {
-            props[key] = cloneNode(value.properties[key]);
-        }
-        result.properties = props;
-    }
-    return result;
-}
-function cloneNode(node) {
-    if ("linkTo" in node) {
-        return { linkTo: node.linkTo };
-    }
-    return deepClone(node);
-}

package/build/validate.js

@@ -2,15 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateReferences = validateReferences;
 exports.validateSchema = validateSchema;
-// ── Helpers ─────────────────────────────────────────────────────
-function isRef(node) {
-    return "linkTo" in node;
-}
+const motly_ts_interface_1 = require("motly-ts-interface");
 function getEqString(node) {
     return typeof node.eq === "string" ? node.eq : undefined;
 }
 function valueEqString(node) {
-    if (isRef(node))
+    if ((0, motly_ts_interface_1.isRef)(node.eq) || (0, motly_ts_interface_1.isEnvRef)(node.eq))
         return undefined;
     return getEqString(node);
 }
@@ -18,7 +15,7 @@ function extractSection(node, name) {
     if (!node.properties)
         return undefined;
     const section = node.properties[name];
-    if (section === undefined || isRef(section))
+    if (section === undefined || (0, motly_ts_interface_1.isRef)(section.eq) || (0, motly_ts_interface_1.isEnvRef)(section.eq))
         return undefined;
     return section.properties;
 }
@@ -37,10 +34,12 @@ function walkRefs(node, path, ancestors, root, errors) {
     }
     if (node.properties) {
         for (const key of Object.keys(node.properties)) {
-            const value = node.properties[key];
+            const child = node.properties[key];
             path.push(key);
-            if (isRef(value)) {
-                const errMsg = checkLink(value, ancestors, root);
+            // Check if child's eq is a reference (checked at property level
+            // to maintain correct ancestor depth for reference resolution)
+            if ((0, motly_ts_interface_1.isRef)(child.eq)) {
+                const errMsg = checkLink(child.eq, ancestors, root);
                 if (errMsg !== null) {
                     errors.push({
                         message: errMsg,
@@ -49,11 +48,10 @@ function walkRefs(node, path, ancestors, root, errors) {
                     });
                 }
             }
-            else {
-                ancestors.push(node);
-                walkRefs(value, path, ancestors, root, errors);
-                ancestors.pop();
-            }
+            // Recurse into child
+            ancestors.push(node);
+            walkRefs(child, path, ancestors, root, errors);
+            ancestors.pop();
             path.pop();
         }
     }
@@ -63,8 +61,9 @@ function walkArrayRefs(arr, path, ancestors, parentNode, root, errors) {
         const elem = arr[i];
         const idxKey = `[${i}]`;
         path.push(idxKey);
-        if (isRef(elem)) {
-            const errMsg = checkLink(elem, ancestors, root);
+        // Check if element's eq is a reference
+        if ((0, motly_ts_interface_1.isRef)(elem.eq)) {
+            const errMsg = checkLink(elem.eq, ancestors, root);
             if (errMsg !== null) {
                 errors.push({
                     message: errMsg,
@@ -73,16 +72,17 @@ function walkArrayRefs(arr, path, ancestors, parentNode, root, errors) {
                 });
             }
         }
-        else {
-            ancestors.push(parentNode);
-            walkRefs(elem, path, ancestors, root, errors);
-            ancestors.pop();
-        }
+        // Recurse into element
+        ancestors.push(parentNode);
+        walkRefs(elem, path, ancestors, root, errors);
+        ancestors.pop();
         path.pop();
     }
 }
 function checkLink(link, ancestors, root) {
-    const { ups, segments } = parseLinkString(link.linkTo);
+    const { ups, segments, error } = parseLinkString(link.linkTo);
+    if (error !== null)
+        return error;
     let start;
     if (ups === 0) {
         start = root;
@@ -130,9 +130,10 @@ function parseLinkString(s) {
             if (i < s.length)
                 i++; // skip ']'
             const idx = parseInt(idxBuf, 10);
-            if (!isNaN(idx) && idx >= 0) {
-                segments.push({ kind: "index", index: idx });
+            if (isNaN(idx) || idx < 0) {
+                return { ups, segments, error: `Reference "${s}" has invalid array index [${idxBuf}]` };
             }
+            segments.push({ kind: "index", index: idx });
         }
         else {
             nameBuf += ch;
@@ -142,44 +143,29 @@ function parseLinkString(s) {
     if (nameBuf.length > 0) {
         segments.push({ kind: "name", name: nameBuf });
     }
-    return { ups, segments };
+    return { ups, segments, error: null };
 }
 function resolvePath(start, segments, linkStr) {
-    let current = { kind: "node", node: start };
+    let current = start;
     for (const seg of segments) {
-        if (current.kind === "terminal") {
-            return `Reference "${linkStr}" could not be resolved: cannot follow path through a link`;
-        }
-        const node = current.node;
         if (seg.kind === "name") {
-            if (!node.properties) {
+            if (!current.properties) {
                 return `Reference "${linkStr}" could not be resolved: property "${seg.name}" not found (node has no properties)`;
             }
-            const child = node.properties[seg.name];
+            const child = current.properties[seg.name];
             if (child === undefined) {
                 return `Reference "${linkStr}" could not be resolved: property "${seg.name}" not found`;
             }
-            if (isRef(child)) {
-                current = { kind: "terminal" };
-            }
-            else {
-                current = { kind: "node", node: child };
-            }
+            current = child;
         }
         else {
-            if (node.eq === undefined || !Array.isArray(node.eq)) {
+            if (current.eq === undefined || !Array.isArray(current.eq)) {
                 return `Reference "${linkStr}" could not be resolved: index [${seg.index}] used on non-array`;
             }
-            if (seg.index >= node.eq.length) {
-                return `Reference "${linkStr}" could not be resolved: index [${seg.index}] out of bounds (array length ${node.eq.length})`;
-            }
-            const elem = node.eq[seg.index];
-            if (isRef(elem)) {
-                current = { kind: "terminal" };
-            }
-            else {
-                current = { kind: "node", node: elem };
+            if (seg.index >= current.eq.length) {
+                return `Reference "${linkStr}" could not be resolved: index [${seg.index}] out of bounds (array length ${current.eq.length})`;
             }
+            current = current.eq[seg.index];
         }
     }
     return null;
@@ -197,7 +183,7 @@ function getAdditionalPolicy(schema) {
     const additional = schema.properties["Additional"];
     if (additional === undefined)
         return { kind: "reject" };
-    if (isRef(additional))
+    if ((0, motly_ts_interface_1.isRef)(additional.eq))
         return { kind: "reject" };
     const eqStr = getEqString(additional);
     if (eqStr !== undefined) {
@@ -276,12 +262,12 @@ function makeTypeSpecNode(typeName) {
     return { eq: typeName };
 }
 function validateValueType(value, typeSpec, types, path, errors) {
-    if (isRef(typeSpec))
+    if ((0, motly_ts_interface_1.isRef)(typeSpec.eq))
         return;
     // Check for union type (oneOf)
     if (typeSpec.properties) {
         const oneOf = typeSpec.properties["oneOf"];
-        if (oneOf !== undefined && !isRef(oneOf)) {
+        if (oneOf !== undefined && !(0, motly_ts_interface_1.isRef)(oneOf.eq)) {
             validateUnion(value, oneOf, types, path, errors);
             return;
         }
@@ -289,14 +275,14 @@ function validateValueType(value, typeSpec, types, path, errors) {
     // Check for enum (eq) or pattern (matches)
     if (typeSpec.properties) {
         const eqProp = typeSpec.properties["eq"];
-        if (eqProp !== undefined && !isRef(eqProp)) {
+        if (eqProp !== undefined && !(0, motly_ts_interface_1.isRef)(eqProp.eq)) {
             if (Array.isArray(eqProp.eq)) {
                 validateEnum(value, eqProp.eq, path, errors);
                 return;
             }
         }
         const matchesProp = typeSpec.properties["matches"];
-        if (matchesProp !== undefined && !isRef(matchesProp)) {
+        if (matchesProp !== undefined && !(0, motly_ts_interface_1.isRef)(matchesProp.eq)) {
             const baseType = getEqString(typeSpec);
             if (baseType !== undefined) {
                 validateBaseType(value, baseType, types, path, errors);
@@ -313,7 +299,7 @@ function validateValueType(value, typeSpec, types, path, errors) {
             ("Required" in typeSpec.properties ||
                 "Optional" in typeSpec.properties ||
                 "Additional" in typeSpec.properties)) {
-            if (isRef(value)) {
+            if ((0, motly_ts_interface_1.isRef)(value.eq)) {
                 errors.push({
                     message: "Expected a tag but found a link",
                     path: [...path],
@@ -382,7 +368,7 @@ function validateBaseType(value, typeName, types, path, errors) {
     }
 }
 function validateTypeString(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "string" but found a link',
             path: [...path],
@@ -399,7 +385,7 @@ function validateTypeString(value, path, errors) {
     }
 }
 function validateTypeNumber(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "number" but found a link',
             path: [...path],
@@ -416,7 +402,7 @@ function validateTypeNumber(value, path, errors) {
     }
 }
 function validateTypeBoolean(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "boolean" but found a link',
             path: [...path],
@@ -433,7 +419,7 @@ function validateTypeBoolean(value, path, errors) {
     }
 }
 function validateTypeDate(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "date" but found a link',
             path: [...path],
@@ -450,7 +436,7 @@ function validateTypeDate(value, path, errors) {
     }
 }
 function validateTypeTag(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "tag" but found a link',
             path: [...path],
@@ -459,7 +445,7 @@ function validateTypeTag(value, path, errors) {
     }
 }
 function validateTypeFlag(value, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: 'Expected type "flag" but found a link',
             path: [...path],
@@ -468,7 +454,7 @@ function validateTypeFlag(value, path, errors) {
     }
 }
 function validateArrayType(value, innerType, types, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: `Expected type "${innerType}[]" but found a link`,
             path: [...path],
@@ -490,7 +476,7 @@ function validateArrayType(value, innerType, types, path, errors) {
     }
 }
 function validateEnum(value, allowed, path, errors) {
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: "Expected an enum value but found a link",
             path: [...path],
@@ -512,7 +498,7 @@ function validateEnum(value, allowed, path, errors) {
         return;
     }
     const matches = allowed.some((a) => {
-        if (isRef(a))
+        if ((0, motly_ts_interface_1.isRef)(a.eq))
             return false;
         const aeq = a.eq;
         if (aeq instanceof Date && nodeEq instanceof Date) {
@@ -522,7 +508,7 @@ function validateEnum(value, allowed, path, errors) {
     });
     if (!matches) {
         const allowedStrs = allowed
-            .filter((a) => !isRef(a))
+            .filter((a) => !(0, motly_ts_interface_1.isRef)(a.eq))
             .map((a) => {
             const aeq = a.eq;
             return JSON.stringify(String(aeq));
@@ -538,7 +524,7 @@ function validatePattern(value, matchesNode, path, errors) {
     const pattern = getEqString(matchesNode);
     if (pattern === undefined)
         return;
-    if (isRef(value)) {
+    if ((0, motly_ts_interface_1.isRef)(value.eq)) {
         errors.push({
             message: "Expected a value matching a pattern but found a link",
             path: [...path],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/motly-ts-parser",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "MOTLY text to wire format parser — pure TypeScript",
   "license": "MIT",
   "main": "build/index.js",