@malloydata/motly-ts-parser 0.2.1 → 0.3.0

package/build/interface/src/types.d.ts

@@ -8,24 +8,28 @@ export interface MOTLYRef {
 export interface MOTLYEnvRef {
     env: string;
 }
+/** What goes to the right of = (the eq slot). */
+export type MOTLYValue = MOTLYScalar | MOTLYEnvRef | MOTLYPropertyValue[];
 /**
- * A value node in the MOTLY tree.
+ * A node in the MOTLY tree.
  *
- * - `eq` — the node's assigned value: a scalar, a reference ({@link MOTLYRef}),
- *   or an array of child nodes
- * - `properties` — named child nodes (the node's "tags")
+ * - `eq` — the node's assigned value: a scalar, an env ref ({@link MOTLYEnvRef}),
+ *   or an array of property values
+ * - `properties` — named child property values
  * - `deleted` — true if this node was explicitly deleted with `-name`
  */
-export interface MOTLYValue {
-    eq?: MOTLYScalar | MOTLYRef | MOTLYEnvRef | MOTLYNode[];
-    properties?: Record<string, MOTLYNode>;
+export interface MOTLYNode {
+    eq?: MOTLYValue;
+    properties?: Record<string, MOTLYPropertyValue>;
     deleted?: boolean;
 }
 /**
- * A node in the MOTLY tree. Every node is a {@link MOTLYValue}.
- * References are represented as `eq: { linkTo: "..." }` inside a value node.
+ * What a property or array element leads to: either a node or a link reference.
+ *
+ * A `MOTLYRef` means "this IS that other node" — no own value, no own properties.
+ * A `MOTLYNode` is a full node with optional eq, properties, and deleted flag.
  */
-export type MOTLYNode = MOTLYValue;
+export type MOTLYPropertyValue = MOTLYNode | MOTLYRef;
 /** A parse error with source location span. */
 export interface MOTLYError {
     /** Machine-readable error code (e.g. `"tag-parse-syntax-error"`). */
@@ -54,10 +58,10 @@ export interface MOTLYSchemaError {
     /** Path to the offending node (e.g. `["metadata", "name"]`). */
     path: string[];
 }
-/** Type guard: is this eq value a link reference? */
-export declare function isRef(eq: MOTLYValue["eq"]): eq is MOTLYRef;
+/** Type guard: is this property value a link reference? */
+export declare function isRef(pv: MOTLYPropertyValue | undefined): pv is MOTLYRef;
 /** Type guard: is this eq value an env reference? */
-export declare function isEnvRef(eq: MOTLYValue["eq"]): eq is MOTLYEnvRef;
+export declare function isEnvRef(eq: MOTLYNode["eq"]): eq is MOTLYEnvRef;
 /** An error from reference validation. */
 export interface MOTLYValidationError {
     /** Machine-readable error code (e.g. `"unresolved-reference"`). */

package/build/interface/src/types.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isRef = isRef;
 exports.isEnvRef = isEnvRef;
-/** Type guard: is this eq value a link reference? */
-function isRef(eq) {
-    return typeof eq === "object" && eq !== null && "linkTo" in eq && !Array.isArray(eq) && !(eq instanceof Date);
+/** Type guard: is this property value a link reference? */
+function isRef(pv) {
+    return typeof pv === "object" && pv !== null && "linkTo" in pv && !Array.isArray(pv) && !(pv instanceof Date);
 }
 /** Type guard: is this eq value an env reference? */
 function isEnvRef(eq) {

package/build/parser/src/clone.d.ts

@@ -1,3 +1,7 @@
-import { MOTLYValue } from "../../interface/src/types";
-/** Deep clone a MOTLYValue. */
-export declare function cloneValue(value: MOTLYValue): MOTLYValue;
+import { MOTLYNode, MOTLYPropertyValue } from "../../interface/src/types";
+/** Deep clone a MOTLYNode. */
+export declare function cloneNode(value: MOTLYNode): MOTLYNode;
+/** Deep clone a MOTLYPropertyValue (either a node or a ref). */
+export declare function clonePropertyValue(pv: MOTLYPropertyValue): MOTLYPropertyValue;
+/** @deprecated Use cloneNode instead. */
+export declare const cloneValue: typeof cloneNode;

package/build/parser/src/clone.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cloneValue = cloneValue;
+exports.cloneValue = void 0;
+exports.cloneNode = cloneNode;
+exports.clonePropertyValue = clonePropertyValue;
 const types_1 = require("../../interface/src/types");
-/** Deep clone a MOTLYValue. */
-function cloneValue(value) {
+/** Deep clone a MOTLYNode. */
+function cloneNode(value) {
     const result = {};
     if (value.deleted)
         result.deleted = true;
@@ -12,10 +14,7 @@ function cloneValue(value) {
             result.eq = new Date(value.eq.getTime());
         }
         else if (Array.isArray(value.eq)) {
-            result.eq = value.eq.map(cloneValue);
-        }
-        else if ((0, types_1.isRef)(value.eq)) {
-            result.eq = { linkTo: value.eq.linkTo };
+            result.eq = value.eq.map(clonePropertyValue);
         }
         else if ((0, types_1.isEnvRef)(value.eq)) {
             result.eq = { env: value.eq.env };
@@ -27,9 +26,18 @@ function cloneValue(value) {
     if (value.properties) {
         const props = {};
         for (const key of Object.keys(value.properties)) {
-            props[key] = cloneValue(value.properties[key]);
+            props[key] = clonePropertyValue(value.properties[key]);
         }
         result.properties = props;
     }
     return result;
 }
+/** Deep clone a MOTLYPropertyValue (either a node or a ref). */
+function clonePropertyValue(pv) {
+    if ((0, types_1.isRef)(pv)) {
+        return { linkTo: pv.linkTo };
+    }
+    return cloneNode(pv);
+}
+/** @deprecated Use cloneNode instead. */
+exports.cloneValue = cloneNode;

package/build/parser/src/index.d.ts

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

package/build/parser/src/interpreter.d.ts

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

package/build/parser/src/interpreter.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.execute = execute;
 const types_1 = require("../../interface/src/types");
 const clone_1 = require("./clone");
-/** Execute a list of parsed statements against an existing MOTLYValue. */
+/** Execute a list of parsed statements against an existing MOTLYNode. */
 function execute(statements, root) {
     const errors = [];
     for (const stmt of statements) {
@@ -37,16 +37,37 @@ function executeStatement(stmt, node, errors) {
 /**
  * `name = value` — set eq, preserve existing properties.
  * `name = value { props }` — set eq, then merge properties.
+ *
+ * Special case: `name = $ref` inserts a MOTLYRef directly.
+ * `name = $ref { props }` produces a non-fatal error (ref created, props ignored).
  */
 function executeSetEq(node, path, value, properties, errors) {
+    // Special case: reference value → insert as MOTLYRef
+    if (value.kind === "scalar" && value.value.kind === "reference") {
+        const refStr = formatRefString(value.value.ups, value.value.path);
+        if (properties !== null) {
+            const zero = { line: 0, column: 0, offset: 0 };
+            errors.push({
+                code: "ref-with-properties",
+                message: "Cannot add properties to a reference. Did you mean := (clone)?",
+                begin: zero,
+                end: zero,
+            });
+        }
+        const [writeKey, parent] = buildAccessPath(node, path);
+        getOrCreateProperties(parent)[writeKey] = { linkTo: refStr };
+        return;
+    }
     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;
+    let targetPv = props[writeKey];
+    if (targetPv === undefined) {
+        targetPv = {};
+        props[writeKey] = targetPv;
     }
+    // If it was a ref, convert to empty node
+    const target = ensureNode(props, writeKey);
     // Set the value slot
     setEqSlot(target, value);
     // If properties block present, MERGE them
@@ -106,10 +127,10 @@ function executeAssignBoth(node, path, value, properties, errors) {
 function executeReplaceProperties(node, path, properties, errors) {
     const [writeKey, parent] = buildAccessPath(node, path);
     const result = {};
-    // Always preserve the existing value
+    // Always preserve the existing value (if it's a node, not a ref)
     const parentProps = getOrCreateProperties(parent);
     const existing = parentProps[writeKey];
-    if (existing !== undefined) {
+    if (existing !== undefined && !(0, types_1.isRef)(existing)) {
         result.eq = existing.eq;
     }
     for (const stmt of properties) {
@@ -120,11 +141,11 @@ function executeReplaceProperties(node, path, properties, errors) {
 function executeUpdateProperties(node, path, properties, errors) {
     const [writeKey, parent] = buildAccessPath(node, path);
     const props = getOrCreateProperties(parent);
-    let target = props[writeKey];
-    if (target === undefined) {
-        target = {};
-        props[writeKey] = target;
+    // Get or create the target node (merging semantics - preserves existing)
+    if (props[writeKey] === undefined) {
+        props[writeKey] = {};
     }
+    const target = ensureNode(props, writeKey);
     for (const stmt of properties) {
         executeStatement(stmt, target, errors);
     }
@@ -148,19 +169,17 @@ function buildAccessPath(node, path) {
     for (let i = 0; i < path.length - 1; i++) {
         const segment = path[i];
         const props = getOrCreateProperties(current);
-        let entry = props[segment];
-        if (entry === undefined) {
-            entry = {};
-            props[segment] = entry;
+        if (props[segment] === undefined) {
+            props[segment] = {};
         }
-        current = entry;
+        current = ensureNode(props, segment);
     }
     return [path[path.length - 1], current];
 }
 /** Set the eq slot on a target node from a TagValue. */
-function setEqSlot(target, value, errors) {
+function setEqSlot(target, value) {
     if (value.kind === "array") {
-        target.eq = resolveArray(value.elements, errors ?? []);
+        target.eq = resolveArray(value.elements, []);
     }
     else {
         const sv = value.value;
@@ -178,8 +197,8 @@ function setEqSlot(target, value, errors) {
                 target.eq = new Date(sv.value);
                 break;
             case "reference":
-                target.eq = { linkTo: formatRefString(sv.ups, sv.path) };
-                break;
+                // References are handled by the caller — should not reach here
+                throw new Error("References should be handled before calling setEqSlot");
             case "env":
                 target.eq = { env: sv.name };
                 break;
@@ -189,11 +208,25 @@ function setEqSlot(target, value, errors) {
         }
     }
 }
-/** Resolve an array of AST elements to MOTLYNodes. */
+/** Resolve an array of AST elements to MOTLYPropertyValues. */
 function resolveArray(elements, errors) {
     return elements.map((el) => resolveArrayElement(el, errors));
 }
 function resolveArrayElement(el, errors) {
+    // Check if the element value is a reference → becomes MOTLYRef
+    if (el.value !== null && el.value.kind === "scalar" && el.value.value.kind === "reference") {
+        const refStr = formatRefString(el.value.value.ups, el.value.value.path);
+        if (el.properties !== null) {
+            const zero = { line: 0, column: 0, offset: 0 };
+            errors.push({
+                code: "ref-with-properties",
+                message: "Cannot add properties to a reference. Did you mean := (clone)?",
+                begin: zero,
+                end: zero,
+            });
+        }
+        return { linkTo: refStr };
+    }
     const node = {};
     if (el.value !== null) {
         setEqSlot(node, el.value);
@@ -233,30 +266,40 @@ function resolveAndClone(root, stmtPath, ups, refPath) {
         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]]) {
+            if (!start.properties) {
                 throw cloneError(`Clone reference ${refStr} could not be resolved: path segment "${stmtPath[i]}" not found`);
             }
-            start = start.properties[stmtPath[i]];
+            const pv = start.properties[stmtPath[i]];
+            if (pv === undefined) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: path segment "${stmtPath[i]}" not found`);
+            }
+            if ((0, types_1.isRef)(pv)) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: path segment "${stmtPath[i]}" is a link reference`);
+            }
+            start = pv;
         }
     }
     // Follow refPath segments
     let current = start;
     for (const seg of refPath) {
         if (seg.kind === "name") {
-            if (!current.properties || !current.properties[seg.name]) {
+            if (!current.properties) {
                 throw cloneError(`Clone reference ${refStr} could not be resolved: property "${seg.name}" not found`);
             }
-            current = current.properties[seg.name];
+            const pv = current.properties[seg.name];
+            if (pv === undefined) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: property "${seg.name}" not found`);
+            }
+            if ((0, types_1.isRef)(pv)) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: property "${seg.name}" is a link reference`);
+            }
+            current = pv;
         }
         else {
             if (!current.eq || !Array.isArray(current.eq)) {
@@ -265,10 +308,14 @@ function resolveAndClone(root, stmtPath, ups, refPath) {
             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];
+            const elemPv = current.eq[seg.index];
+            if ((0, types_1.isRef)(elemPv)) {
+                throw cloneError(`Clone reference ${refStr} could not be resolved: index [${seg.index}] is a link reference`);
+            }
+            current = elemPv;
         }
     }
-    return (0, clone_1.cloneValue)(current);
+    return (0, clone_1.cloneNode)(current);
 }
 function cloneError(message) {
     const zero = { line: 0, column: 0, offset: 0 };
@@ -280,29 +327,60 @@ function cloneError(message) {
  * if N > D. Absolute references (ups=0) are left alone.
  */
 function sanitizeClonedRefs(node, depth, errors) {
-    if ((0, types_1.isRef)(node.eq)) {
-        const parsed = parseRefUps(node.eq.linkTo);
+    // Check array elements
+    if (node.eq !== undefined && Array.isArray(node.eq)) {
+        for (let i = 0; i < node.eq.length; i++) {
+            sanitizeClonedPv(node.eq, i, depth + 1, errors);
+        }
+    }
+    // Check properties
+    if (node.properties) {
+        for (const key of Object.keys(node.properties)) {
+            sanitizeClonedPvInProps(node.properties, key, depth + 1, errors);
+        }
+    }
+}
+/** Sanitize a single property value within a cloned subtree (in an array context). */
+function sanitizeClonedPv(arr, index, depth, errors) {
+    const pv = arr[index];
+    if ((0, types_1.isRef)(pv)) {
+        const parsed = parseRefUps(pv.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})`,
+                message: `Cloned reference "${pv.linkTo}" escapes the clone boundary (${parsed.ups} level(s) up from depth ${depth})`,
                 begin: zero,
                 end: zero,
             });
-            delete node.eq;
+            // Convert to empty node
+            arr[index] = {};
         }
     }
-    if (node.eq !== undefined && Array.isArray(node.eq)) {
-        for (const elem of node.eq) {
-            sanitizeClonedRefs(elem, depth + 1, errors);
-        }
+    else {
+        sanitizeClonedRefs(pv, depth, errors);
     }
-    if (node.properties) {
-        for (const key of Object.keys(node.properties)) {
-            sanitizeClonedRefs(node.properties[key], depth + 1, errors);
+}
+/** Sanitize a single property value within a cloned subtree (in a properties context). */
+function sanitizeClonedPvInProps(props, key, depth, errors) {
+    const pv = props[key];
+    if ((0, types_1.isRef)(pv)) {
+        const parsed = parseRefUps(pv.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 "${pv.linkTo}" escapes the clone boundary (${parsed.ups} level(s) up from depth ${depth})`,
+                begin: zero,
+                end: zero,
+            });
+            // Convert to empty node
+            props[key] = {};
         }
     }
+    else {
+        sanitizeClonedRefs(pv, depth, errors);
+    }
 }
 /** Extract the ups count from a linkTo string like "$^^name". */
 function parseRefUps(linkTo) {
@@ -316,10 +394,24 @@ function parseRefUps(linkTo) {
     }
     return { ups };
 }
-/** Get or create the properties object on a MOTLYValue. */
+/** Get or create the properties object on a MOTLYNode. */
 function getOrCreateProperties(node) {
     if (!node.properties) {
         node.properties = {};
     }
     return node.properties;
 }
+/**
+ * Ensure the property value at props[key] is a MOTLYNode (not a MOTLYRef).
+ * If it's a ref, replace it with an empty node.
+ * Returns a mutable reference to the node.
+ */
+function ensureNode(props, key) {
+    const pv = props[key];
+    if ((0, types_1.isRef)(pv)) {
+        const node = {};
+        props[key] = node;
+        return node;
+    }
+    return pv;
+}

package/build/parser/src/session.d.ts

@@ -1,4 +1,4 @@
-import { MOTLYValue, MOTLYError, MOTLYSchemaError, MOTLYValidationError } from "../../interface/src/types";
+import { MOTLYNode, MOTLYError, MOTLYSchemaError, MOTLYValidationError } from "../../interface/src/types";
 /**
  * A stateful MOTLY parsing session.
  *
@@ -26,7 +26,7 @@ export declare class MOTLYSession {
     /**
      * Return a deep clone of the session's current value.
      */
-    getValue(): MOTLYValue;
+    getValue(): MOTLYNode;
     /**
      * Validate the session's value against its stored schema.
      * Returns an empty array if no schema has been set.

package/build/parser/src/session.js

@@ -65,7 +65,7 @@ class MOTLYSession {
      */
     getValue() {
         this.ensureAlive();
-        return (0, clone_1.cloneValue)(this.value);
+        return (0, clone_1.cloneNode)(this.value);
     }
     /**
      * Validate the session's value against its stored schema.

package/build/parser/src/validate.d.ts

@@ -1,3 +1,3 @@
-import { MOTLYValue, MOTLYSchemaError, MOTLYValidationError } from "../../interface/src/types";
-export declare function validateReferences(root: MOTLYValue): MOTLYValidationError[];
-export declare function validateSchema(tag: MOTLYValue, schema: MOTLYValue): MOTLYSchemaError[];
+import { MOTLYNode, MOTLYSchemaError, MOTLYValidationError } from "../../interface/src/types";
+export declare function validateReferences(root: MOTLYNode): MOTLYValidationError[];
+export declare function validateSchema(tag: MOTLYNode, schema: MOTLYNode): MOTLYSchemaError[];

package/build/parser/src/validate.js

@@ -6,18 +6,18 @@ const types_1 = require("../../interface/src/types");
 function getEqString(node) {
     return typeof node.eq === "string" ? node.eq : undefined;
 }
-function valueEqString(node) {
-    if ((0, types_1.isRef)(node.eq) || (0, types_1.isEnvRef)(node.eq))
+function pvEqString(pv) {
+    if ((0, types_1.isRef)(pv))
         return undefined;
-    return getEqString(node);
+    return getEqString(pv);
 }
 function extractSection(node, name) {
     if (!node.properties)
         return undefined;
-    const section = node.properties[name];
-    if (section === undefined || (0, types_1.isRef)(section.eq) || (0, types_1.isEnvRef)(section.eq))
+    const pv = node.properties[name];
+    if (pv === undefined || (0, types_1.isRef)(pv))
         return undefined;
-    return section.properties;
+    return pv.properties;
 }
 // ── Reference Validation ────────────────────────────────────────
 function validateReferences(root) {
@@ -34,12 +34,11 @@ function walkRefs(node, path, ancestors, root, errors) {
     }
     if (node.properties) {
         for (const key of Object.keys(node.properties)) {
-            const child = node.properties[key];
+            const childPv = node.properties[key];
             path.push(key);
-            // Check if child's eq is a reference (checked at property level
-            // to maintain correct ancestor depth for reference resolution)
-            if ((0, types_1.isRef)(child.eq)) {
-                const errMsg = checkLink(child.eq, ancestors, root);
+            if ((0, types_1.isRef)(childPv)) {
+                // This property is a reference — check it
+                const errMsg = checkLink(childPv.linkTo, ancestors, root);
                 if (errMsg !== null) {
                     errors.push({
                         message: errMsg,
@@ -48,22 +47,23 @@ function walkRefs(node, path, ancestors, root, errors) {
                     });
                 }
             }
-            // Recurse into child
-            ancestors.push(node);
-            walkRefs(child, path, ancestors, root, errors);
-            ancestors.pop();
+            else {
+                // Recurse into child node
+                ancestors.push(node);
+                walkRefs(childPv, path, ancestors, root, errors);
+                ancestors.pop();
+            }
             path.pop();
         }
     }
 }
 function walkArrayRefs(arr, path, ancestors, parentNode, root, errors) {
     for (let i = 0; i < arr.length; i++) {
-        const elem = arr[i];
+        const elemPv = arr[i];
         const idxKey = `[${i}]`;
         path.push(idxKey);
-        // Check if element's eq is a reference
-        if ((0, types_1.isRef)(elem.eq)) {
-            const errMsg = checkLink(elem.eq, ancestors, root);
+        if ((0, types_1.isRef)(elemPv)) {
+            const errMsg = checkLink(elemPv.linkTo, ancestors, root);
             if (errMsg !== null) {
                 errors.push({
                     message: errMsg,
@@ -72,15 +72,17 @@ function walkArrayRefs(arr, path, ancestors, parentNode, root, errors) {
                 });
             }
         }
-        // Recurse into element
-        ancestors.push(parentNode);
-        walkRefs(elem, path, ancestors, root, errors);
-        ancestors.pop();
+        else {
+            // Recurse into element node
+            ancestors.push(parentNode);
+            walkRefs(elemPv, path, ancestors, root, errors);
+            ancestors.pop();
+        }
         path.pop();
     }
 }
-function checkLink(link, ancestors, root) {
-    const { ups, segments, error } = parseLinkString(link.linkTo);
+function checkLink(linkTo, ancestors, root) {
+    const { ups, segments, error } = parseLinkString(linkTo);
     if (error !== null)
         return error;
     let start;
@@ -90,11 +92,11 @@ function checkLink(link, ancestors, root) {
     else {
         const idx = ancestors.length - ups;
         if (idx < 0 || idx >= ancestors.length) {
-            return `Reference "${link.linkTo}" goes ${ups} level(s) up but only ${ancestors.length} ancestor(s) available`;
+            return `Reference "${linkTo}" goes ${ups} level(s) up but only ${ancestors.length} ancestor(s) available`;
         }
         start = ancestors[idx];
     }
-    return resolvePath(start, segments, link.linkTo);
+    return resolvePath(start, segments, linkTo);
 }
 function parseLinkString(s) {
     let i = 0;
@@ -148,15 +150,23 @@ function parseLinkString(s) {
 function resolvePath(start, segments, linkStr) {
     let current = start;
     for (const seg of segments) {
+        if (current === "terminal") {
+            return `Reference "${linkStr}" could not be resolved: cannot follow path through a link`;
+        }
         if (seg.kind === "name") {
             if (!current.properties) {
                 return `Reference "${linkStr}" could not be resolved: property "${seg.name}" not found (node has no properties)`;
             }
-            const child = current.properties[seg.name];
-            if (child === undefined) {
+            const childPv = current.properties[seg.name];
+            if (childPv === undefined) {
                 return `Reference "${linkStr}" could not be resolved: property "${seg.name}" not found`;
             }
-            current = child;
+            if ((0, types_1.isRef)(childPv)) {
+                current = "terminal";
+            }
+            else {
+                current = childPv;
+            }
         }
         else {
             if (current.eq === undefined || !Array.isArray(current.eq)) {
@@ -165,7 +175,13 @@ function resolvePath(start, segments, linkStr) {
             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];
+            const elemPv = current.eq[seg.index];
+            if ((0, types_1.isRef)(elemPv)) {
+                current = "terminal";
+            }
+            else {
+                current = elemPv;
+            }
         }
     }
     return null;
@@ -180,12 +196,10 @@ function validateSchema(tag, schema) {
 function getAdditionalPolicy(schema) {
     if (!schema.properties)
         return { kind: "reject" };
-    const additional = schema.properties["Additional"];
-    if (additional === undefined)
-        return { kind: "reject" };
-    if ((0, types_1.isRef)(additional.eq))
+    const additionalPv = schema.properties["Additional"];
+    if (additionalPv === undefined || (0, types_1.isRef)(additionalPv))
         return { kind: "reject" };
-    const eqStr = getEqString(additional);
+    const eqStr = getEqString(additionalPv);
     if (eqStr !== undefined) {
         if (eqStr === "allow")
             return { kind: "allow" };
@@ -204,8 +218,8 @@ function validateNodeAgainstSchema(tag, schema, types, path, errors) {
     if (required) {
         for (const key of Object.keys(required)) {
             const propPath = [...path, key];
-            const tagValue = tagProps ? tagProps[key] : undefined;
-            if (tagValue === undefined) {
+            const tagValuePv = tagProps ? tagProps[key] : undefined;
+            if (tagValuePv === undefined) {
                 errors.push({
                     message: `Missing required property "${key}"`,
                     path: propPath,
@@ -213,16 +227,16 @@ function validateNodeAgainstSchema(tag, schema, types, path, errors) {
                 });
             }
             else {
-                validateValueType(tagValue, required[key], types, propPath, errors);
+                validateValueType(tagValuePv, required[key], types, propPath, errors);
             }
         }
     }
     // Check optional properties that exist
     if (optional && tagProps) {
         for (const key of Object.keys(optional)) {
-            const tagValue = tagProps[key];
-            if (tagValue !== undefined) {
-                validateValueType(tagValue, optional[key], types, [...path, key], errors);
+            const tagValuePv = tagProps[key];
+            if (tagValuePv !== undefined) {
+                validateValueType(tagValuePv, optional[key], types, [...path, key], errors);
             }
         }
     }
@@ -261,29 +275,83 @@ function validateNodeAgainstSchema(tag, schema, types, path, errors) {
 function makeTypeSpecNode(typeName) {
     return { eq: typeName };
 }
-function validateValueType(value, typeSpec, types, path, errors) {
-    if ((0, types_1.isRef)(typeSpec.eq))
+function validateValueType(valuePv, typeSpecPv, types, path, errors) {
+    // Skip ref type specs in schema
+    if ((0, types_1.isRef)(typeSpecPv))
         return;
+    const specNode = typeSpecPv;
+    // If value is a ref, generate appropriate "found a link" error
+    if ((0, types_1.isRef)(valuePv)) {
+        pushRefTypeError(specNode, path, errors);
+        return;
+    }
+    // Value is a node
+    const value = valuePv;
+    validateNodeAgainstTypeSpec(value, specNode, types, path, errors);
+}
+function pushRefTypeError(specNode, path, errors) {
+    // Check for enum
+    if (specNode.properties) {
+        const eqProp = specNode.properties["eq"];
+        if (eqProp !== undefined && !(0, types_1.isRef)(eqProp)) {
+            if (Array.isArray(eqProp.eq)) {
+                errors.push({
+                    message: "Expected an enum value but found a link",
+                    path: [...path],
+                    code: "wrong-type",
+                });
+                return;
+            }
+        }
+        if (specNode.properties["matches"] !== undefined) {
+            errors.push({
+                message: "Expected a value matching a pattern but found a link",
+                path: [...path],
+                code: "wrong-type",
+            });
+            return;
+        }
+    }
+    const typeName = getEqString(specNode);
+    if (typeName !== undefined) {
+        errors.push({
+            message: `Expected type "${typeName}" but found a link`,
+            path: [...path],
+            code: "wrong-type",
+        });
+    }
+    else if (specNode.properties &&
+        ("Required" in specNode.properties ||
+            "Optional" in specNode.properties ||
+            "Additional" in specNode.properties)) {
+        errors.push({
+            message: "Expected a tag but found a link",
+            path: [...path],
+            code: "wrong-type",
+        });
+    }
+}
+function validateNodeAgainstTypeSpec(value, specNode, types, path, errors) {
     // Check for union type (oneOf)
-    if (typeSpec.properties) {
-        const oneOf = typeSpec.properties["oneOf"];
-        if (oneOf !== undefined && !(0, types_1.isRef)(oneOf.eq)) {
-            validateUnion(value, oneOf, types, path, errors);
+    if (specNode.properties) {
+        const oneOfPv = specNode.properties["oneOf"];
+        if (oneOfPv !== undefined && !(0, types_1.isRef)(oneOfPv)) {
+            validateUnion(value, oneOfPv, types, path, errors);
             return;
         }
     }
     // Check for enum (eq) or pattern (matches)
-    if (typeSpec.properties) {
-        const eqProp = typeSpec.properties["eq"];
-        if (eqProp !== undefined && !(0, types_1.isRef)(eqProp.eq)) {
+    if (specNode.properties) {
+        const eqProp = specNode.properties["eq"];
+        if (eqProp !== undefined && !(0, types_1.isRef)(eqProp)) {
             if (Array.isArray(eqProp.eq)) {
                 validateEnum(value, eqProp.eq, path, errors);
                 return;
             }
         }
-        const matchesProp = typeSpec.properties["matches"];
-        if (matchesProp !== undefined && !(0, types_1.isRef)(matchesProp.eq)) {
-            const baseType = getEqString(typeSpec);
+        const matchesProp = specNode.properties["matches"];
+        if (matchesProp !== undefined && !(0, types_1.isRef)(matchesProp)) {
+            const baseType = getEqString(specNode);
             if (baseType !== undefined) {
                 validateBaseType(value, baseType, types, path, errors);
             }
@@ -292,23 +360,14 @@ function validateValueType(value, typeSpec, types, path, errors) {
         }
     }
     // Get the type name from the spec's eq value
-    const typeName = getEqString(typeSpec);
+    const typeName = getEqString(specNode);
     if (typeName === undefined) {
         // Nested schema (has Required/Optional/Additional)
-        if (typeSpec.properties &&
-            ("Required" in typeSpec.properties ||
-                "Optional" in typeSpec.properties ||
-                "Additional" in typeSpec.properties)) {
-            if ((0, types_1.isRef)(value.eq)) {
-                errors.push({
-                    message: "Expected a tag but found a link",
-                    path: [...path],
-                    code: "wrong-type",
-                });
-            }
-            else {
-                validateNodeAgainstSchema(value, typeSpec, types, path, errors);
-            }
+        if (specNode.properties &&
+            ("Required" in specNode.properties ||
+                "Optional" in specNode.properties ||
+                "Additional" in specNode.properties)) {
+            validateNodeAgainstSchema(value, specNode, types, path, errors);
         }
         return;
     }
@@ -335,19 +394,22 @@ function validateBaseType(value, typeName, types, path, errors) {
             validateTypeDate(value, path, errors);
             break;
         case "tag":
-            validateTypeTag(value, path, errors);
-            break;
+            break; // tag — node exists, always valid for a non-ref
         case "flag":
-            validateTypeFlag(value, path, errors);
-            break;
+            break; // flag — presence-only, always valid for a non-ref
         case "any":
-            break;
+            break; // any — always valid
         default: {
             // Custom type
             if (types) {
-                const typeDef = types[typeName];
-                if (typeDef !== undefined) {
-                    validateValueType(value, typeDef, types, path, errors);
+                const typeDefPv = types[typeName];
+                if (typeDefPv !== undefined) {
+                    if ((0, types_1.isRef)(typeDefPv)) {
+                        // Type definition is a ref — skip
+                    }
+                    else {
+                        validateNodeAgainstTypeSpec(value, typeDefPv, types, path, errors);
+                    }
                 }
                 else {
                     errors.push({
@@ -368,14 +430,6 @@ function validateBaseType(value, typeName, types, path, errors) {
     }
 }
 function validateTypeString(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "string" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (typeof value.eq !== "string") {
         errors.push({
             message: 'Expected type "string"',
@@ -385,14 +439,6 @@ function validateTypeString(value, path, errors) {
     }
 }
 function validateTypeNumber(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "number" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (typeof value.eq !== "number") {
         errors.push({
             message: 'Expected type "number"',
@@ -402,14 +448,6 @@ function validateTypeNumber(value, path, errors) {
     }
 }
 function validateTypeBoolean(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "boolean" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (typeof value.eq !== "boolean") {
         errors.push({
             message: 'Expected type "boolean"',
@@ -419,14 +457,6 @@ function validateTypeBoolean(value, path, errors) {
     }
 }
 function validateTypeDate(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "date" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (!(value.eq instanceof Date)) {
         errors.push({
             message: 'Expected type "date"',
@@ -435,33 +465,7 @@ function validateTypeDate(value, path, errors) {
         });
     }
 }
-function validateTypeTag(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "tag" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-    }
-}
-function validateTypeFlag(value, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: 'Expected type "flag" but found a link',
-            path: [...path],
-            code: "wrong-type",
-        });
-    }
-}
 function validateArrayType(value, innerType, types, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: `Expected type "${innerType}[]" but found a link`,
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (!Array.isArray(value.eq)) {
         errors.push({
             message: `Expected type "${innerType}[]" but value is not an array`,
@@ -472,18 +476,20 @@ function validateArrayType(value, innerType, types, path, errors) {
     }
     for (let i = 0; i < value.eq.length; i++) {
         const elemPath = [...path, `[${i}]`];
-        validateBaseType(value.eq[i], innerType, types, elemPath, errors);
+        const elemPv = value.eq[i];
+        if ((0, types_1.isRef)(elemPv)) {
+            errors.push({
+                message: `Expected type "${innerType}" but found a link`,
+                path: elemPath,
+                code: "wrong-type",
+            });
+        }
+        else {
+            validateBaseType(elemPv, innerType, types, elemPath, errors);
+        }
     }
 }
 function validateEnum(value, allowed, path, errors) {
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: "Expected an enum value but found a link",
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     const nodeEq = value.eq;
     if (nodeEq === undefined ||
         (typeof nodeEq !== "string" &&
@@ -498,7 +504,7 @@ function validateEnum(value, allowed, path, errors) {
         return;
     }
     const matches = allowed.some((a) => {
-        if ((0, types_1.isRef)(a.eq))
+        if ((0, types_1.isRef)(a))
             return false;
         const aeq = a.eq;
         if (aeq instanceof Date && nodeEq instanceof Date) {
@@ -508,7 +514,7 @@ function validateEnum(value, allowed, path, errors) {
     });
     if (!matches) {
         const allowedStrs = allowed
-            .filter((a) => !(0, types_1.isRef)(a.eq))
+            .filter((a) => !(0, types_1.isRef)(a))
             .map((a) => {
             const aeq = a.eq;
             return JSON.stringify(String(aeq));
@@ -524,14 +530,6 @@ function validatePattern(value, matchesNode, path, errors) {
     const pattern = getEqString(matchesNode);
     if (pattern === undefined)
         return;
-    if ((0, types_1.isRef)(value.eq)) {
-        errors.push({
-            message: "Expected a value matching a pattern but found a link",
-            path: [...path],
-            code: "wrong-type",
-        });
-        return;
-    }
     if (typeof value.eq !== "string") {
         errors.push({
             message: `Expected a string matching pattern "${pattern}"`,
@@ -561,18 +559,20 @@ function validatePattern(value, matchesNode, path, errors) {
 function validateUnion(value, oneOfNode, types, path, errors) {
     if (!Array.isArray(oneOfNode.eq))
         return;
-    for (const typeVal of oneOfNode.eq) {
-        const typeName = valueEqString(typeVal);
+    // We need to wrap value as a MOTLYPropertyValue for validate_value_type
+    const valuePv = value;
+    for (const typePv of oneOfNode.eq) {
+        const typeName = pvEqString(typePv);
         if (typeName === undefined)
             continue;
         const trialErrors = [];
         const synthetic = makeTypeSpecNode(typeName);
-        validateValueType(value, synthetic, types, path, trialErrors);
+        validateValueType(valuePv, synthetic, types, path, trialErrors);
         if (trialErrors.length === 0)
             return;
     }
     const typeStrs = oneOfNode.eq
-        .map((v) => valueEqString(v))
+        .map((v) => pvEqString(v))
         .filter((s) => s !== undefined);
     errors.push({
         message: `Value does not match any type in oneOf: [${typeStrs.join(", ")}]`,

package/package.json

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