@malloydata/malloy-tag 0.0.335 → 0.0.336

package/dist/tags.js

@@ -22,34 +22,48 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tag = void 0;
-const tree_1 = require("antlr4ts/tree");
-const MalloyTagLexer_1 = require("./lib/Malloy/MalloyTagLexer");
-const MalloyTagParser_1 = require("./lib/Malloy/MalloyTagParser");
-const antlr4ts_1 = require("antlr4ts");
-const util_1 = require("./util");
+exports.RefTag = exports.Tag = void 0;
+exports.interfaceFromTag = interfaceFromTag;
+exports.interfaceFromDict = interfaceFromDict;
 /**
  * Class for interacting with the parsed output of an annotation
  * containing the Malloy tag language. Used by the parser to
  * generate parsed data, and as an API to that data.
  * ```
  * tag.text(p?)         => string value of tag.p or undefined
- * tag.array(p?)        => Tag[] value of tag.p or undefined
  * tag.numeric(p?)      => numeric value of tag.p or undefined
- * tag.textArray(p ?)   => string[] value of elements in tag.p or undefined
- * tag.numericArray(p?) => string[] value of elements in tag.p or undefined
- * tag.tag(p?)           => Tag value of tag.p
- * tag.has(p?)           => boolean "tag contains tag.p"
- * tag.bare(p?)          => tag.p exists and has no properties
+ * tag.boolean(p?)      => boolean value of tag.p or undefined
+ * tag.isTrue(p?)       => true if tag.p is boolean true
+ * tag.isFalse(p?)      => true if tag.p is boolean false
+ * tag.date(p?)         => Date value of tag.p or undefined
+ * tag.array(p?)        => Tag[] value of tag.p or undefined
+ * tag.textArray(p?)    => string[] value of elements in tag.p or undefined
+ * tag.numericArray(p?) => number[] value of elements in tag.p or undefined
+ * tag.tag(p?)          => Tag value of tag.p
+ * tag.has(p?)          => boolean "tag contains tag.p"
+ * tag.bare(p?)         => tag.p exists and has no properties
  * tag.dict             => Record<string,Tag> of tag properties
+ * tag.toObject()       => Plain JS object representation
  * ```
  */
 class Tag {
-    static tagFrom(from = {}) {
-        if (from instanceof Tag) {
-            return from;
+    /**
+     * Get the parent tag, if this tag is part of a tree.
+     */
+    get parent() {
+        return this._parent;
+    }
+    /**
+     * Get the root tag by traversing up the parent chain.
+     * Returns this tag if it has no parent.
+     */
+    get root() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let current = this;
+        while (current._parent !== undefined) {
+            current = current._parent;
         }
-        return new Tag(from);
+        return current;
     }
     static id(t) {
         let thisTagId = Tag.ids.get(t);
@@ -69,62 +83,43 @@ class Tag {
             return str + `=${this.eq}`;
         }
         str += ' {';
-        if (this.eq) {
-            if (typeof this.eq === 'string') {
-                str += `\n${spaces}  =: ${this.eq}`;
-            }
-            else {
+        if (this.eq !== undefined) {
+            if (Array.isArray(this.eq)) {
                 str += `\n${spaces}  =: [\n${spaces}    ${this.eq
-                    .map(el => Tag.tagFrom(el).peek(indent + 4))
+                    .map(el => el.peek(indent + 4))
                     .join(`\n${spaces}    `)}\n${spaces}  ]`;
             }
+            else {
+                str += `\n${spaces}  =: ${this.eq}`;
+            }
         }
         if (this.properties) {
             for (const k in this.properties) {
-                const val = Tag.tagFrom(this.properties[k]);
-                str += `\n${spaces}  ${k}: ${val.peek(indent + 2)}`;
+                str += `\n${spaces}  ${k}: ${this.properties[k].peek(indent + 2)}`;
             }
         }
         str += `\n${spaces}}`;
         return str;
     }
-    /**
-     * Parse a line of Malloy tag language into a Tag which can be queried
-     * @param source -- The source line to be parsed. If the string starts with #, then it skips
-     *   all characters up to the first space.
-     * @param lineNumber -- A line number to be associated with the parse errors.
-     * @param extending A tag which this line will be extending
-     * @param importing Outer "scopes" for $() references
-     * @returns Something shaped like { tag: Tag, log: ParseErrors[] }
-     */
-    static fromTagLine(source, lineNumber = 0, extending, ...importing) {
-        return parseTagLine(source, extending, importing, lineNumber);
-    }
-    /**
-     * Parse multiple lines of Malloy tag language, merging them into a single Tag
-     * @param lines -- The source line to be parsed. If the string starts with #, then it skips
-     *   all characters up to the first space.
-     * @param extending A tag which this line will be extending
-     * @param importing Outer "scopes" for $() references
-     * @returns Something shaped like { tag: Tag, log: ParseErrors[] }
-     */
-    static fromTagLines(lines, extending, ...importing) {
-        const allErrs = [];
-        let current = extending;
-        for (let i = 0; i < lines.length; i++) {
-            const text = lines[i];
-            const noteParse = parseTagLine(text, current, importing, i);
-            current = noteParse.tag;
-            allErrs.push(...noteParse.log);
+    constructor(from = {}, parent) {
+        if (parent !== undefined) {
+            this._parent = parent;
         }
-        return { tag: current, log: allErrs };
-    }
-    constructor(from = {}) {
-        if (from.eq) {
-            this.eq = from.eq;
+        if (from.eq !== undefined) {
+            if (Array.isArray(from.eq)) {
+                // Convert array elements to Tags
+                this.eq = from.eq.map(el => el instanceof Tag ? el : new Tag(el, this));
+            }
+            else {
+                this.eq = from.eq;
+            }
         }
         if (from.properties) {
-            this.properties = from.properties;
+            // Convert property values to Tags
+            this.properties = {};
+            for (const [key, val] of Object.entries(from.properties)) {
+                this.properties[key] = val instanceof Tag ? val : new Tag(val, this);
+            }
         }
         if (from.deleted) {
             this.deleted = from.deleted;
@@ -141,62 +136,149 @@ class Tag {
     }
     text(...at) {
         var _a;
-        const str = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.eq;
-        if (typeof str === 'string') {
-            return str;
+        const val = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq();
+        if (val === undefined || Array.isArray(val)) {
+            return undefined;
+        }
+        if (val instanceof Date) {
+            return val.toISOString();
         }
+        return String(val);
     }
     numeric(...at) {
         var _a;
-        const str = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.eq;
-        if (typeof str === 'string') {
-            const num = Number.parseFloat(str);
+        const val = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq();
+        if (typeof val === 'number') {
+            return val;
+        }
+        if (typeof val === 'string') {
+            const num = Number.parseFloat(val);
             if (!Number.isNaN(num)) {
                 return num;
             }
         }
+        return undefined;
+    }
+    boolean(...at) {
+        var _a;
+        const val = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq();
+        if (typeof val === 'boolean') {
+            return val;
+        }
+        return undefined;
+    }
+    isTrue(...at) {
+        var _a;
+        return ((_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq()) === true;
+    }
+    isFalse(...at) {
+        var _a;
+        return ((_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq()) === false;
+    }
+    date(...at) {
+        var _a;
+        const val = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.getEq();
+        if (val instanceof Date) {
+            return val;
+        }
+        return undefined;
     }
     bare(...at) {
         const p = this.find(at);
         if (p === undefined) {
             return;
         }
-        return (p.properties === undefined || Object.entries(p.properties).length === 0);
+        return !p.hasProperties();
+    }
+    /** Virtual accessor for eq - overridden in RefTag to resolve */
+    getEq() {
+        return this.eq;
+    }
+    /** Virtual accessor for a property - overridden in RefTag to resolve */
+    getProperty(name) {
+        var _a;
+        return (_a = this.properties) === null || _a === void 0 ? void 0 : _a[name];
+    }
+    /** Virtual accessor for an array element - overridden in RefTag to resolve */
+    getArrayElement(index) {
+        if (Array.isArray(this.eq) && index < this.eq.length) {
+            return this.eq[index];
+        }
+        return undefined;
     }
     get dict() {
-        const newDict = {};
+        var _a;
+        return (_a = this.properties) !== null && _a !== void 0 ? _a : {};
+    }
+    /** Iterate over [name, Tag] pairs for each property */
+    *entries() {
+        if (this.properties) {
+            for (const key in this.properties) {
+                yield [key, this.properties[key]];
+            }
+        }
+    }
+    /** Iterate over property names */
+    *keys() {
         if (this.properties) {
             for (const key in this.properties) {
-                newDict[key] = Tag.tagFrom(this.properties[key]);
+                yield key;
             }
         }
-        return newDict;
+    }
+    /** Check if this tag has any properties */
+    hasProperties() {
+        return (this.properties !== undefined && Object.keys(this.properties).length > 0);
     }
     array(...at) {
-        var _a;
-        const array = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.eq;
-        if (array === undefined || typeof array === 'string') {
+        const found = this.find(at);
+        if (found === undefined) {
+            return undefined;
+        }
+        const arr = found.getEq();
+        if (!Array.isArray(arr)) {
             return undefined;
         }
-        return array.map(el => typeof el === 'string' ? new Tag({ eq: el }) : Tag.tagFrom(el));
+        return arr.map((_, i) => found.getArrayElement(i));
     }
     textArray(...at) {
-        var _a;
-        const array = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.eq;
-        if (array === undefined || typeof array === 'string') {
+        const found = this.find(at);
+        if (found === undefined) {
+            return undefined;
+        }
+        const arr = found.getEq();
+        if (!Array.isArray(arr)) {
             return undefined;
         }
-        return array.reduce((allStrs, el) => typeof el.eq === 'string' ? allStrs.concat(el.eq) : allStrs, []);
+        return arr.reduce((allStrs, _, i) => {
+            const el = found.getArrayElement(i);
+            const val = el === null || el === void 0 ? void 0 : el.getEq();
+            if (val === undefined || Array.isArray(val)) {
+                return allStrs;
+            }
+            if (val instanceof Date) {
+                return allStrs.concat(val.toISOString());
+            }
+            return allStrs.concat(String(val));
+        }, []);
     }
     numericArray(...at) {
-        var _a;
-        const array = (_a = this.find(at)) === null || _a === void 0 ? void 0 : _a.eq;
-        if (array === undefined || typeof array === 'string') {
+        const found = this.find(at);
+        if (found === undefined) {
+            return undefined;
+        }
+        const arr = found.getEq();
+        if (!Array.isArray(arr)) {
             return undefined;
         }
-        return array.reduce((allNums, el) => {
-            if (typeof el.eq === 'string') {
-                const num = Number.parseFloat(el.eq);
+        return arr.reduce((allNums, _, i) => {
+            const el = found.getArrayElement(i);
+            const val = el === null || el === void 0 ? void 0 : el.getEq();
+            if (typeof val === 'number') {
+                return allNums.concat(val);
+            }
+            if (typeof val === 'string') {
+                const num = Number.parseFloat(val);
                 if (!Number.isNaN(num)) {
                     return allNums.concat(num);
                 }
@@ -204,15 +286,178 @@ class Tag {
             return allNums;
         }, []);
     }
-    // Has the sometimes desireable side effect of initalizing properties
+    // Has the sometimes desirable side effect of initializing properties
     getProperties() {
         if (this.properties === undefined) {
             this.properties = {};
         }
         return this.properties;
     }
-    clone() {
-        return new Tag(structuredClone(this));
+    clone(newParent) {
+        const cloned = new Tag({}, newParent);
+        cloned.prefix = this.prefix;
+        cloned.deleted = this.deleted;
+        if (this.eq !== undefined) {
+            if (Array.isArray(this.eq)) {
+                cloned.eq = this.eq.map(el => el.clone(cloned));
+            }
+            else {
+                // Scalar value - copy directly (Date needs special handling)
+                cloned.eq = this.eq instanceof Date ? new Date(this.eq) : this.eq;
+            }
+        }
+        if (this.properties) {
+            cloned.properties = {};
+            for (const [key, val] of Object.entries(this.properties)) {
+                cloned.properties[key] = val.clone(cloned);
+            }
+        }
+        return cloned;
+    }
+    static scalarToObject(val) {
+        return val;
+    }
+    static tagToObject(tag) {
+        const hasProps = tag.properties !== undefined && Object.keys(tag.properties).length > 0;
+        const hasValue = tag.eq !== undefined;
+        // Bare tag (no value, no properties)
+        if (!hasValue && !hasProps) {
+            return true;
+        }
+        // Properties only
+        if (!hasValue && hasProps) {
+            const result = {};
+            for (const [key, val] of Object.entries(tag.properties)) {
+                if (!val.deleted) {
+                    result[key] = Tag.tagToObject(val);
+                }
+            }
+            return result;
+        }
+        // Value only
+        if (hasValue && !hasProps) {
+            if (Array.isArray(tag.eq)) {
+                return tag.eq.map(el => Tag.tagToObject(el));
+            }
+            return Tag.scalarToObject(tag.eq);
+        }
+        // Both value and properties
+        const result = {};
+        if (Array.isArray(tag.eq)) {
+            result['='] = tag.eq.map(el => Tag.tagToObject(el));
+        }
+        else {
+            result['='] = Tag.scalarToObject(tag.eq);
+        }
+        for (const [key, val] of Object.entries(tag.properties)) {
+            if (!val.deleted) {
+                result[key] = Tag.tagToObject(val);
+            }
+        }
+        return result;
+    }
+    /**
+     * Convert to a plain JS object. References are resolved to actual
+     * object pointers (which may be circular in JS - that's fine).
+     * @param resolving - RefTags currently being resolved (for cycle detection)
+     */
+    toObject(resolving = new Set()) {
+        const result = {};
+        if (this.properties) {
+            for (const [key, prop] of Object.entries(this.properties)) {
+                if (!prop.deleted) {
+                    result[key] = prop.toObjectValue(resolving);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Convert this tag's value to a plain JS object.
+     * Override in RefTag to resolve references.
+     * @param resolving - RefTags currently being resolved (for cycle detection)
+     */
+    toObjectValue(resolving) {
+        const hasProps = this.properties !== undefined && Object.keys(this.properties).length > 0;
+        const hasValue = this.eq !== undefined;
+        // Bare tag (no value, no properties)
+        if (!hasValue && !hasProps) {
+            return true;
+        }
+        // Properties only
+        if (!hasValue && hasProps) {
+            return this.toObject(resolving);
+        }
+        // Value only
+        if (hasValue && !hasProps) {
+            if (Array.isArray(this.eq)) {
+                return this.eq.map(el => el.toObjectValue(resolving));
+            }
+            return this.eq;
+        }
+        // Both value and properties
+        const result = this.toObject(resolving);
+        if (Array.isArray(this.eq)) {
+            result['='] = this.eq.map(el => el.toObjectValue(resolving));
+        }
+        else {
+            result['='] = this.eq;
+        }
+        return result;
+    }
+    /**
+     * Custom JSON serialization that excludes _parent to avoid circular references.
+     * This is called automatically by JSON.stringify().
+     */
+    toJSON() {
+        const result = {};
+        if (this.eq !== undefined) {
+            if (Array.isArray(this.eq)) {
+                result.eq = this.eq.map(el => el.toJSON());
+            }
+            else {
+                result.eq = this.eq;
+            }
+        }
+        if (this.properties !== undefined) {
+            result.properties = {};
+            for (const [key, val] of Object.entries(this.properties)) {
+                result.properties[key] = val.toJSON();
+            }
+        }
+        if (this.deleted) {
+            result.deleted = true;
+        }
+        if (this.prefix) {
+            result.prefix = this.prefix;
+        }
+        return result;
+    }
+    /**
+     * Validate all references in this tag tree.
+     * Returns an array of error messages for unresolved references.
+     */
+    validateReferences() {
+        const errors = [];
+        this.collectReferenceErrors(errors, []);
+        return errors;
+    }
+    /**
+     * Recursively collect reference errors.
+     */
+    collectReferenceErrors(errors, path) {
+        if (this.properties) {
+            for (const [key, prop] of Object.entries(this.properties)) {
+                if (!prop.deleted) {
+                    prop.collectReferenceErrors(errors, [...path, key]);
+                }
+            }
+        }
+        if (Array.isArray(this.eq)) {
+            this.eq.forEach((el, i) => {
+                el.collectReferenceErrors(errors, [...path, `[${i}]`]);
+            });
+        }
     }
     static escapeString(str) {
         return str
@@ -231,6 +476,18 @@ class Tag {
         // TODO consider choosing the quote character based on which quotes appear in the string
         return `"${Tag.escapeString(str)}"`;
     }
+    static serializeScalar(val) {
+        if (typeof val === 'boolean') {
+            return val ? '@true' : '@false';
+        }
+        if (val instanceof Date) {
+            return `@${val.toISOString()}`;
+        }
+        if (typeof val === 'number') {
+            return String(val);
+        }
+        return Tag.quoteAndEscape(val);
+    }
     toString() {
         var _a;
         let annotation = (_a = this.prefix) !== null && _a !== void 0 ? _a : '# ';
@@ -258,7 +515,7 @@ class Tag {
                     annotation += ']';
                 }
                 else {
-                    annotation += Tag.quoteAndEscape(`${child.eq}`);
+                    annotation += Tag.serializeScalar(child.eq);
                 }
             }
             if (child.properties) {
@@ -292,26 +549,20 @@ class Tag {
         return annotation;
     }
     find(path) {
-        var _a;
-        let currentTag = Tag.tagFrom(this);
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let currentTag = this;
         for (const segment of path) {
+            let next;
             if (typeof segment === 'number') {
-                if (currentTag.eq === undefined ||
-                    !Array.isArray(currentTag.eq) ||
-                    currentTag.eq.length <= segment) {
-                    return;
-                }
-                currentTag = Tag.tagFrom(currentTag.eq[segment]);
+                next = currentTag.getArrayElement(segment);
             }
             else {
-                const properties = (_a = currentTag.properties) !== null && _a !== void 0 ? _a : {};
-                if (segment in properties) {
-                    currentTag = Tag.tagFrom(properties[segment]);
-                }
-                else {
-                    return;
-                }
+                next = currentTag.getProperty(segment);
+            }
+            if (next === undefined) {
+                return undefined;
             }
+            currentTag = next;
         }
         return currentTag.deleted ? undefined : currentTag;
     }
@@ -319,16 +570,20 @@ class Tag {
         return this.find(path) !== undefined;
     }
     set(path, value = null) {
-        const copy = Tag.tagFrom(this);
-        let currentTag = copy;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let currentTag = this;
+        let parentTag;
+        let lastSegment;
         for (const segment of path) {
+            parentTag = currentTag;
+            lastSegment = segment;
             if (typeof segment === 'number') {
                 if (currentTag.eq === undefined || !Array.isArray(currentTag.eq)) {
-                    currentTag.eq = Array.from({ length: segment + 1 }).map(_ => ({}));
+                    currentTag.eq = Array.from({ length: segment + 1 }).map(() => new Tag({}, currentTag));
                 }
                 else if (currentTag.eq.length <= segment) {
                     const values = currentTag.eq;
-                    const newVal = Array.from({ length: segment + 1 }).map((_, i) => i < values.length ? values[i] : {});
+                    const newVal = Array.from({ length: segment + 1 }).map((_, i) => i < values.length ? values[i] : new Tag({}, currentTag));
                     currentTag.eq = newVal;
                 }
                 currentTag = currentTag.eq[segment];
@@ -336,7 +591,7 @@ class Tag {
             else {
                 const properties = currentTag.properties;
                 if (properties === undefined) {
-                    currentTag.properties = { [segment]: {} };
+                    currentTag.properties = { [segment]: new Tag({}, currentTag) };
                     currentTag = currentTag.properties[segment];
                 }
                 else if (segment in properties) {
@@ -346,7 +601,7 @@ class Tag {
                     }
                 }
                 else {
-                    properties[segment] = {};
+                    properties[segment] = new Tag({}, currentTag);
                     currentTag = properties[segment];
                 }
             }
@@ -354,18 +609,30 @@ class Tag {
         if (value === null) {
             currentTag.eq = undefined;
         }
-        else if (typeof value === 'string') {
-            currentTag.eq = value;
+        else if (value instanceof Tag) {
+            // Clone the tag with correct parent and replace in parent's slot
+            const cloned = value.clone(parentTag);
+            if (parentTag && lastSegment !== undefined) {
+                if (typeof lastSegment === 'number' && Array.isArray(parentTag.eq)) {
+                    parentTag.eq[lastSegment] = cloned;
+                }
+                else if (typeof lastSegment === 'string' && parentTag.properties) {
+                    parentTag.properties[lastSegment] = cloned;
+                }
+            }
         }
-        else if (typeof value === 'number') {
-            currentTag.eq = value.toString(); // TODO big numbers?
+        else if (typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean' ||
+            value instanceof Date) {
+            currentTag.eq = value;
         }
         else if (Array.isArray(value)) {
             currentTag.eq = value.map((v) => {
-                return { eq: typeof v === 'string' ? v : v.toString() };
+                return new Tag({ eq: v }, currentTag);
             });
         }
-        return copy;
+        return this;
     }
     delete(...path) {
         return this.remove(path, false);
@@ -375,20 +642,20 @@ class Tag {
     }
     remove(path, hard = false) {
         var _a;
-        const origCopy = Tag.tagFrom(this);
-        let currentTag = origCopy;
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let currentTag = this;
         for (const segment of path.slice(0, path.length - 1)) {
             if (typeof segment === 'number') {
                 if (currentTag.eq === undefined || !Array.isArray(currentTag.eq)) {
                     if (!hard)
-                        return origCopy;
-                    currentTag.eq = Array.from({ length: segment }).map(_ => ({}));
+                        return this;
+                    currentTag.eq = Array.from({ length: segment }).map(() => new Tag({}, currentTag));
                 }
                 else if (currentTag.eq.length <= segment) {
                     if (!hard)
-                        return origCopy;
+                        return this;
                     const values = currentTag.eq;
-                    const newVal = Array.from({ length: segment }).map((_, i) => i < values.length ? values[i] : {});
+                    const newVal = Array.from({ length: segment }).map((_, i) => i < values.length ? values[i] : new Tag({}, currentTag));
                     currentTag.eq = newVal;
                 }
                 currentTag = currentTag.eq[segment];
@@ -397,8 +664,8 @@ class Tag {
                 const properties = currentTag.properties;
                 if (properties === undefined) {
                     if (!hard)
-                        return origCopy;
-                    currentTag.properties = { [segment]: {} };
+                        return this;
+                    currentTag.properties = { [segment]: new Tag({}, currentTag) };
                     currentTag = currentTag.properties[segment];
                 }
                 else if (segment in properties) {
@@ -406,8 +673,8 @@ class Tag {
                 }
                 else {
                     if (!hard)
-                        return origCopy;
-                    properties[segment] = {};
+                        return this;
+                    properties[segment] = new Tag({}, currentTag);
                     currentTag = properties[segment];
                 }
             }
@@ -419,7 +686,7 @@ class Tag {
             }
             else if (hard) {
                 (_a = currentTag.properties) !== null && _a !== void 0 ? _a : (currentTag.properties = {});
-                currentTag.properties[segment] = { deleted: true };
+                currentTag.properties[segment] = new Tag({ deleted: true }, currentTag);
             }
         }
         else {
@@ -427,249 +694,173 @@ class Tag {
                 currentTag.eq.splice(segment, 1);
             }
         }
-        return origCopy;
+        return this;
     }
 }
 exports.Tag = Tag;
 // --- Just for debugging ---
 Tag.ids = new Map();
 Tag.nextTagId = 1000;
-class TagErrorListener {
-    constructor(line) {
-        this.line = line;
-        this.log = [];
-    }
-    syntaxError(recognizer, offendingSymbol, line, charPositionInLine, msg, _e) {
-        const logMsg = {
-            code: 'tag-parse-syntax-error',
-            message: msg,
-            line: this.line,
-            offset: charPositionInLine,
-        };
-        this.log.push(logMsg);
-    }
-    semanticError(cx, code, msg) {
-        const logMsg = {
-            code,
-            message: msg,
-            line: this.line,
-            offset: cx.start.charPositionInLine,
-        };
-        this.log.push(logMsg);
-    }
-}
-function getBuildOn(ctx) {
-    const buildOn = ctx['buildOn'];
-    if (buildOn instanceof Tag) {
-        return buildOn;
-    }
-    return new Tag();
-}
 /**
- * When chasing a path reference, the two interesting gestures are to
- * find the path-ed tag so it can be extended, or to find the path tag
- * so it can be deleted. This returns the parent and the final tag
- * so that the caller can delete the tag with delete parent.tagName
- * or assign to it with parent[tagName] = new_value
+ * A tag that references another location in the tag tree.
+ * When accessed, it dereferences to the target tag.
+ *
+ * Reference syntax:
+ *   $path.to.thing     - absolute from root
+ *   $^thing            - up one level, then 'thing'
+ *   $^^thing           - up two levels, then 'thing'
+ *   $items[0].name     - with array indexing
  */
-function buildAccessPath(buildOn, path) {
-    var _a;
-    var _b;
-    let parentPropertyObject = buildOn.getProperties();
-    for (const p of path.slice(0, path.length - 1)) {
-        let next;
-        if (parentPropertyObject[p] === undefined) {
-            next = new Tag({});
-            parentPropertyObject[p] = next;
-        }
-        else {
-            // The access that we are performing requires that `.properties` be the
-            // same JS object (not equal, but identical), and `Tag.tagFrom` only copies
-            // the exact object in if it is actually present.
-            (_a = (_b = parentPropertyObject[p]).properties) !== null && _a !== void 0 ? _a : (_b.properties = {});
-            next = Tag.tagFrom(parentPropertyObject[p]);
-        }
-        parentPropertyObject = next.getProperties();
-    }
-    return [path[path.length - 1], parentPropertyObject];
-}
-function getString(ctx) {
-    if (ctx.SQ_STRING() || ctx.DQ_STRING()) {
-        return (0, util_1.parseString)(ctx.text, ctx.text[0]);
+class RefTag extends Tag {
+    constructor(ups, refPath, parent) {
+        super({}, parent);
+        this.ups = ups;
+        this.refPath = refPath;
     }
-    return ctx.text;
-}
-function parseTagLine(source, extending, outerScope, onLine) {
-    if (source[0] === '#') {
-        const skipTo = source.indexOf(' ');
-        if (skipTo > 0) {
-            source = source.slice(skipTo);
+    /**
+     * Resolve this reference to the target tag.
+     * Returns undefined if the reference cannot be resolved.
+     */
+    resolve() {
+        // Start from the appropriate point based on ups
+        let current;
+        if (this.ups === 0) {
+            // Absolute reference from root
+            current = this.root;
         }
         else {
-            source = '';
-        }
-    }
-    const inputStream = antlr4ts_1.CharStreams.fromString(source);
-    const lexer = new MalloyTagLexer_1.MalloyTagLexer(inputStream);
-    const tokenStream = new antlr4ts_1.CommonTokenStream(lexer);
-    const pLog = new TagErrorListener(onLine);
-    const taglineParser = new MalloyTagParser_1.MalloyTagParser(tokenStream);
-    taglineParser.removeErrorListeners();
-    taglineParser.addErrorListener(pLog);
-    const tagTree = taglineParser.tagLine();
-    const treeWalker = new TagLineParser(outerScope, pLog);
-    const tag = treeWalker.tagLineToTag(tagTree, extending);
-    return { tag, log: pLog.log };
-}
-class TagLineParser extends tree_1.AbstractParseTreeVisitor {
-    constructor(outerScopes = [], msgLog) {
-        super();
-        this.scopes = [];
-        this.msgLog = msgLog;
-        this.scopes.unshift(...outerScopes);
-    }
-    defaultResult() {
-        return new Tag();
-    }
-    visitString(ctx) {
-        return new Tag({ eq: getString(ctx) });
-    }
-    getPropName(ctx) {
-        return ctx
-            .identifier()
-            .map(cx => cx.BARE_STRING() ? cx.text : (0, util_1.parseString)(cx.text, cx.text[0]));
-    }
-    getTags(tags, tagLine) {
-        for (const tagSpec of tags) {
-            // Stash the current state of this tag in the context and then visit it
-            // visit functions should alter the tagLine
-            tagSpec['buildOn'] = tagLine;
-            this.visit(tagSpec);
-        }
-        return tagLine;
-    }
-    tagLineToTag(ctx, extending) {
-        extending = (extending === null || extending === void 0 ? void 0 : extending.clone()) || new Tag({});
-        this.scopes.unshift(extending);
-        this.getTags(ctx.tagSpec(), extending);
-        return extending;
-    }
-    visitTagLine(_ctx) {
-        throw new Error('INTERNAL: ERROR: Call tagLineToTag, not vistTagLine');
-        return this.defaultResult();
-    }
-    visitProperties(ctx) {
-        return this.getTags(ctx.tagSpec(), getBuildOn(ctx));
-    }
-    visitArrayValue(ctx) {
-        return new Tag({ eq: this.getArray(ctx) });
-    }
-    getArray(ctx) {
-        return ctx.arrayElement().map(v => this.visit(v));
-    }
-    visitArrayElement(ctx) {
-        const propCx = ctx.properties();
-        const properties = propCx ? this.visitProperties(propCx) : undefined;
-        const strCx = ctx.string();
-        let value = strCx ? getString(strCx) : undefined;
-        const arrayCx = ctx.arrayValue();
-        if (arrayCx) {
-            value = this.getArray(arrayCx);
-        }
-        if (properties) {
-            if (value !== undefined) {
-                properties.eq = value;
-            }
-            return properties;
-        }
-        const refCx = ctx.reference();
-        if (refCx) {
-            return this.visitReference(refCx);
-        }
-        return new Tag({ eq: value });
-    }
-    visitReference(ctx) {
-        const path = this.getPropName(ctx.propName());
-        for (const scope of this.scopes) {
-            // first scope which has the first component gets to resolve the whole path
-            if (scope.has(path[0])) {
-                const refTo = scope.tag(...path);
-                if (refTo) {
-                    return refTo.clone();
-                }
-                break;
+            // Relative reference - go up 'ups' levels from parent
+            // $^ means go up 1 level from the containing scope
+            current = this.parent;
+            for (let i = 0; i < this.ups && current !== undefined; i++) {
+                current = current.parent;
             }
         }
-        this.msgLog.semanticError(ctx, 'tag-property-not-found', `Reference to undefined property ${path.join('.')}`);
-        return this.defaultResult();
+        if (current === undefined) {
+            return undefined;
+        }
+        // Follow the path
+        return current.find(this.refPath);
     }
-    visitTagEq(ctx) {
-        const buildOn = getBuildOn(ctx);
-        const name = this.getPropName(ctx.propName());
-        const [writeKey, writeInto] = buildAccessPath(buildOn, name);
-        const eq = this.visit(ctx.eqValue());
-        const propCx = ctx.properties();
-        if (propCx) {
-            // a.b.c { -y } means i want to do -y on
-            if (propCx.DOTTY() === undefined) {
-                const properties = this.visitProperties(propCx).dict;
-                // Add new properties old value
-                writeInto[writeKey] = { ...eq, properties };
-            }
-            else {
-                // preserve old properties, add new value
-                writeInto[writeKey] = { ...writeInto[writeKey], ...eq };
+    /**
+     * Quote an identifier if it contains special characters.
+     */
+    quoteSegment(seg) {
+        // Match bareString from peggy grammar: [0-9A-Za-z_\u00C0-\u024F\u1E00-\u1EFF]+
+        if (/^[0-9A-Za-z_\u00C0-\u024F\u1E00-\u1EFF]+$/.test(seg)) {
+            return seg;
+        }
+        // Otherwise, backquote it (escaping backslashes and backquotes)
+        return '`' + seg.replace(/\\/g, '\\\\').replace(/`/g, '\\`') + '`';
+    }
+    /**
+     * Convert this reference to its string representation.
+     */
+    toRefString() {
+        const prefix = '$' + '^'.repeat(this.ups);
+        const pathStr = this.refPath
+            .map((seg, i) => {
+            if (typeof seg === 'number') {
+                return `[${seg}]`;
             }
+            const quoted = this.quoteSegment(seg);
+            return i === 0 ? quoted : `.${quoted}`;
+        })
+            .join('');
+        return prefix + pathStr;
+    }
+    // Override virtual accessors to resolve the reference
+    getEq() {
+        var _a;
+        return (_a = this.resolve()) === null || _a === void 0 ? void 0 : _a.getEq();
+    }
+    getProperty(name) {
+        var _a;
+        return (_a = this.resolve()) === null || _a === void 0 ? void 0 : _a.getProperty(name);
+    }
+    getArrayElement(index) {
+        var _a;
+        return (_a = this.resolve()) === null || _a === void 0 ? void 0 : _a.getArrayElement(index);
+    }
+    hasProperties() {
+        var _a, _b;
+        return (_b = (_a = this.resolve()) === null || _a === void 0 ? void 0 : _a.hasProperties()) !== null && _b !== void 0 ? _b : false;
+    }
+    /**
+     * For toObject, resolve the reference and return the target's object value.
+     * This creates actual object pointers (circular references are allowed).
+     * Detects cycles in the reference chain to prevent infinite recursion.
+     */
+    toObjectValue(resolving) {
+        // Check for cycle in reference chain
+        if (resolving.has(this)) {
+            // We're in a cycle - return undefined to break it
+            // (The cycle will be completed when the outer resolution finishes)
+            return undefined;
         }
-        else {
-            writeInto[writeKey] = eq;
+        const resolved = this.resolve();
+        if (resolved === undefined) {
+            return undefined;
         }
-        return buildOn;
+        // Track that we're resolving this RefTag
+        resolving.add(this);
+        const result = resolved.toObjectValue(resolving);
+        resolving.delete(this);
+        return result;
     }
-    visitTagReplaceProperties(ctx) {
-        const buildOn = getBuildOn(ctx);
-        const name = this.getPropName(ctx.propName());
-        const [writeKey, writeInto] = buildAccessPath(buildOn, name);
-        const propCx = ctx.properties();
-        const props = this.visitProperties(propCx);
-        if (ctx.DOTTY() === undefined) {
-            // No dots, thropw away the value
-            writeInto[writeKey] = { properties: props.dict };
+    /**
+     * For JSON serialization, return a marker object instead of resolving.
+     */
+    toJSON() {
+        return { linkTo: this.toRefString() };
+    }
+    /**
+     * Check if this reference resolves, add error if not.
+     */
+    collectReferenceErrors(errors, path) {
+        if (this.resolve() === undefined) {
+            const location = path.length > 0 ? path.join('.') : 'root';
+            errors.push(`Unresolved reference at ${location}: ${this.toRefString()}`);
         }
-        else {
-            /// DOTS, just update the properties
-            writeInto[writeKey].properties = props.dict;
-        }
-        return buildOn;
-    }
-    visitTagUpdateProperties(ctx) {
-        const buildOn = getBuildOn(ctx);
-        const name = this.getPropName(ctx.propName());
-        const [writeKey, writeInto] = buildAccessPath(buildOn, name);
-        const propCx = ctx.properties();
-        propCx['buildOn'] = Tag.tagFrom(writeInto[writeKey]);
-        const props = this.visitProperties(propCx);
-        const thisObj = writeInto[writeKey] || new Tag({});
-        const properties = { ...thisObj.properties, ...props.dict };
-        writeInto[writeKey] = { ...thisObj, properties };
-        return buildOn;
-    }
-    visitTagDef(ctx) {
-        const buildOn = getBuildOn(ctx);
-        const path = this.getPropName(ctx.propName());
-        const [writeKey, writeInto] = buildAccessPath(buildOn, path);
-        if (ctx.MINUS()) {
-            writeInto[writeKey] = { deleted: true };
+    }
+    /**
+     * Clone this RefTag, preserving the reference information.
+     */
+    clone(newParent) {
+        return new RefTag(this.ups, [...this.refPath], newParent);
+    }
+}
+exports.RefTag = RefTag;
+/**
+ * Convert a Tag to a plain TagInterface without internal fields like _parent.
+ * Useful for test comparisons.
+ */
+function interfaceFromTag(tag) {
+    const result = {};
+    if (tag.eq !== undefined) {
+        if (Array.isArray(tag.eq)) {
+            result.eq = tag.eq.map(el => interfaceFromTag(el));
         }
         else {
-            writeInto[writeKey] = new Tag({});
+            result.eq = tag.eq;
         }
-        return buildOn;
     }
-    visitTagEmpty(ctx) {
-        const tagList = ctx['buildOn'];
-        tagList.properties = {};
-        return tagList;
+    if (tag.properties !== undefined) {
+        result.properties = interfaceFromDict(tag.properties);
+    }
+    if (tag.deleted) {
+        result.deleted = true;
+    }
+    return result;
+}
+/**
+ * Convert a TagDict to a plain TagDict without internal fields.
+ */
+function interfaceFromDict(dict) {
+    const result = {};
+    for (const [key, val] of Object.entries(dict)) {
+        result[key] = interfaceFromTag(val);
     }
+    return result;
 }
 //# sourceMappingURL=tags.js.map