@malloydata/malloy-tag 0.0.335 → 0.0.336

package/src/tags.ts

@@ -21,29 +21,6 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import {AbstractParseTreeVisitor} from 'antlr4ts/tree';
-import {MalloyTagLexer} from './lib/Malloy/MalloyTagLexer';
-import type {
-  ArrayElementContext,
-  ArrayValueContext,
-  PropNameContext,
-  PropertiesContext,
-  ReferenceContext,
-  StringContext,
-  TagDefContext,
-  TagEmptyContext,
-  TagEqContext,
-  TagLineContext,
-  TagReplacePropertiesContext,
-  TagSpecContext,
-  TagUpdatePropertiesContext,
-} from './lib/Malloy/MalloyTagParser';
-import {MalloyTagParser} from './lib/Malloy/MalloyTagParser';
-import type {MalloyTagVisitor} from './lib/Malloy/MalloyTagVisitor';
-import type {ANTLRErrorListener, ParserRuleContext, Token} from 'antlr4ts';
-import {CharStreams, CommonTokenStream} from 'antlr4ts';
-import {parseString} from './util';
-
 export interface TagError {
   message: string;
   line: number;
@@ -51,20 +28,37 @@ export interface TagError {
   code: string;
 }
 
-// The distinction between the interface and the Tag class exists solely to
-// make it possible to write tests and specify expected results This
-// is why only TagDict interface is exported.
+// TagInterface exists for tests and serialization only.
+// Internally, Tag uses Tag instances for properties and array elements.
 export type TagDict = Record<string, TagInterface>;
 
-type TagValue = string | TagInterface[];
+export type TagScalar = string | number | boolean | Date;
+type TagValue = TagScalar | Tag[];
 
+// Input format - for tests and constructors (no links)
 export interface TagInterface {
-  eq?: TagValue;
+  eq?: TagScalar | TagInterface[];
   properties?: TagDict;
   deleted?: boolean;
   prefix?: string;
 }
 
+// Output format - for toJSON (can contain links)
+// This format is round-trippable: a Tag.fromJSON(TagJSON) could reconstruct
+// the original Tag tree, including RefTags from TagLink.linkTo strings.
+export interface TagLink {
+  linkTo: string;
+}
+
+export interface TagJSONInterface {
+  eq?: TagScalar | TagJSON[];
+  properties?: Record<string, TagJSON>;
+  deleted?: boolean;
+  prefix?: string;
+}
+
+export type TagJSON = TagJSONInterface | TagLink;
+
 export interface TagParse {
   tag: Tag;
   log: TagError[];
@@ -73,7 +67,15 @@ export interface TagParse {
 export type PathSegment = string | number;
 export type Path = PathSegment[];
 
-export type TagSetValue = string | number | string[] | number[] | null;
+export type TagSetValue =
+  | string
+  | number
+  | boolean
+  | Date
+  | string[]
+  | number[]
+  | Tag
+  | null;
 
 /**
  * Class for interacting with the parsed output of an annotation
@@ -81,27 +83,46 @@ export type TagSetValue = string | number | string[] | number[] | null;
  * 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
  * ```
  */
-export class Tag implements TagInterface {
+export class Tag {
   eq?: TagValue;
-  properties?: TagDict;
+  properties?: Record<string, Tag>;
   prefix?: string;
   deleted?: boolean;
+  private _parent?: Tag;
+
+  /**
+   * Get the parent tag, if this tag is part of a tree.
+   */
+  get parent(): Tag | undefined {
+    return this._parent;
+  }
 
-  static tagFrom(from: TagInterface = {}) {
-    if (from instanceof Tag) {
-      return from;
+  /**
+   * Get the root tag by traversing up the parent chain.
+   * Returns this tag if it has no parent.
+   */
+  get root(): Tag {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let current: Tag = this;
+    while (current._parent !== undefined) {
+      current = current._parent;
     }
-    return new Tag(from);
+    return current;
   }
 
   // --- Just for debugging ---
@@ -127,70 +148,45 @@ export class Tag implements TagInterface {
       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: string,
-    lineNumber = 0,
-    extending?: Tag,
-    ...importing: Tag[]
-  ): TagParse {
-    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: string[], extending?: Tag, ...importing: Tag[]) {
-    const allErrs: TagError[] = [];
-    let current: Tag | undefined = 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: TagInterface = {}, parent?: Tag) {
+    if (parent !== undefined) {
+      this._parent = parent;
     }
-    return {tag: current, log: allErrs};
-  }
-
-  constructor(from: TagInterface = {}) {
-    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;
@@ -209,20 +205,52 @@ export class Tag implements TagInterface {
   }
 
   text(...at: Path): string | undefined {
-    const str = this.find(at)?.eq;
-    if (typeof str === 'string') {
-      return str;
+    const val = this.find(at)?.getEq();
+    if (val === undefined || Array.isArray(val)) {
+      return undefined;
+    }
+    if (val instanceof Date) {
+      return val.toISOString();
     }
+    return String(val);
   }
 
   numeric(...at: Path): number | undefined {
-    const str = this.find(at)?.eq;
-    if (typeof str === 'string') {
-      const num = Number.parseFloat(str);
+    const val = this.find(at)?.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: Path): boolean | undefined {
+    const val = this.find(at)?.getEq();
+    if (typeof val === 'boolean') {
+      return val;
+    }
+    return undefined;
+  }
+
+  isTrue(...at: Path): boolean {
+    return this.find(at)?.getEq() === true;
+  }
+
+  isFalse(...at: Path): boolean {
+    return this.find(at)?.getEq() === false;
+  }
+
+  date(...at: Path): Date | undefined {
+    const val = this.find(at)?.getEq();
+    if (val instanceof Date) {
+      return val;
+    }
+    return undefined;
   }
 
   bare(...at: Path): boolean | undefined {
@@ -230,51 +258,107 @@ export class Tag implements TagInterface {
     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(): TagValue | undefined {
+    return this.eq;
+  }
+
+  /** Virtual accessor for a property - overridden in RefTag to resolve */
+  getProperty(name: string): Tag | undefined {
+    return this.properties?.[name];
+  }
+
+  /** Virtual accessor for an array element - overridden in RefTag to resolve */
+  getArrayElement(index: number): Tag | undefined {
+    if (Array.isArray(this.eq) && index < this.eq.length) {
+      return this.eq[index];
+    }
+    return undefined;
   }
 
   get dict(): Record<string, Tag> {
-    const newDict: Record<string, Tag> = {};
+    return this.properties ?? {};
+  }
+
+  /** Iterate over [name, Tag] pairs for each property */
+  *entries(): Generator<[string, Tag]> {
     if (this.properties) {
       for (const key in this.properties) {
-        newDict[key] = Tag.tagFrom(this.properties[key]);
+        yield [key, this.properties[key]];
       }
     }
-    return newDict;
+  }
+
+  /** Iterate over property names */
+  *keys(): Generator<string> {
+    if (this.properties) {
+      for (const key in this.properties) {
+        yield key;
+      }
+    }
+  }
+
+  /** Check if this tag has any properties */
+  hasProperties(): boolean {
+    return (
+      this.properties !== undefined && Object.keys(this.properties).length > 0
+    );
   }
 
   array(...at: Path): Tag[] | undefined {
-    const array = this.find(at)?.eq;
-    if (array === undefined || typeof array === 'string') {
+    const found = this.find(at);
+    if (found === undefined) {
       return undefined;
     }
-    return array.map(el =>
-      typeof el === 'string' ? new Tag({eq: el}) : Tag.tagFrom(el)
-    );
+    const arr = found.getEq();
+    if (!Array.isArray(arr)) {
+      return undefined;
+    }
+    return arr.map((_, i) => found.getArrayElement(i)!);
   }
 
   textArray(...at: Path): string[] | undefined {
-    const array = this.find(at)?.eq;
-    if (array === undefined || typeof array === 'string') {
+    const found = this.find(at);
+    if (found === undefined) {
       return undefined;
     }
-    return array.reduce<string[]>(
-      (allStrs, el) =>
-        typeof el.eq === 'string' ? allStrs.concat(el.eq) : allStrs,
-      []
-    );
+    const arr = found.getEq();
+    if (!Array.isArray(arr)) {
+      return undefined;
+    }
+    return arr.reduce<string[]>((allStrs, _, i) => {
+      const el = found.getArrayElement(i);
+      const val = 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: Path): number[] | undefined {
-    const array = this.find(at)?.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<number[]>((allNums, el) => {
-      if (typeof el.eq === 'string') {
-        const num = Number.parseFloat(el.eq);
+    return arr.reduce<number[]>((allNums, _, i) => {
+      const el = found.getArrayElement(i);
+      const val = 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);
         }
@@ -283,16 +367,197 @@ export class Tag implements TagInterface {
     }, []);
   }
 
-  // Has the sometimes desireable side effect of initalizing properties
-  getProperties(): TagDict {
+  // Has the sometimes desirable side effect of initializing properties
+  getProperties(): Record<string, Tag> {
     if (this.properties === undefined) {
       this.properties = {};
     }
     return this.properties;
   }
 
-  clone(): Tag {
-    return new Tag(structuredClone(this));
+  clone(newParent?: Tag): Tag {
+    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;
+  }
+
+  private static scalarToObject(
+    val: TagScalar
+  ): string | number | boolean | Date {
+    return val;
+  }
+
+  private static tagToObject(tag: TagInterface): unknown {
+    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: Record<string, unknown> = {};
+      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: Record<string, unknown> = {};
+    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: Set<RefTag> = new Set()): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    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: Set<RefTag>): unknown {
+    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: Record<string, unknown> = 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(): TagJSON {
+    const result: TagJSONInterface = {};
+    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(): string[] {
+    const errors: string[] = [];
+    this.collectReferenceErrors(errors, []);
+    return errors;
+  }
+
+  /**
+   * Recursively collect reference errors.
+   */
+  collectReferenceErrors(errors: string[], path: string[]): void {
+    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}]`]);
+      });
+    }
   }
 
   private static escapeString(str: string) {
@@ -313,6 +578,19 @@ export class Tag implements TagInterface {
     return `"${Tag.escapeString(str)}"`;
   }
 
+  private static serializeScalar(val: TagScalar): string {
+    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(): string {
     let annotation = this.prefix ?? '# ';
     function addChildren(tag: TagInterface) {
@@ -335,7 +613,7 @@ export class Tag implements TagInterface {
           }
           annotation += ']';
         } else {
-          annotation += Tag.quoteAndEscape(`${child.eq}`);
+          annotation += Tag.serializeScalar(child.eq);
         }
       }
       if (child.properties) {
@@ -370,25 +648,19 @@ export class Tag implements TagInterface {
   }
 
   find(path: Path): Tag | undefined {
-    let currentTag: Tag = Tag.tagFrom(this);
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let currentTag: Tag = this;
     for (const segment of path) {
+      let next: Tag | undefined;
       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 = currentTag.properties ?? {};
-        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;
   }
@@ -398,16 +670,23 @@ export class Tag implements TagInterface {
   }
 
   set(path: Path, value: TagSetValue = null): Tag {
-    const copy = Tag.tagFrom(this);
-    let currentTag: TagInterface = copy;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let currentTag: Tag = this;
+    let parentTag: Tag | undefined;
+    let lastSegment: PathSegment | undefined;
+
     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] : {}
+            i < values.length ? values[i] : new Tag({}, currentTag)
           );
           currentTag.eq = newVal;
         }
@@ -415,7 +694,7 @@ export class Tag implements TagInterface {
       } 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) {
           currentTag = properties[segment];
@@ -423,23 +702,37 @@ export class Tag implements TagInterface {
             currentTag.deleted = false;
           }
         } else {
-          properties[segment] = {};
+          properties[segment] = new Tag({}, currentTag);
           currentTag = properties[segment];
         }
       }
     }
+
     if (value === null) {
       currentTag.eq = undefined;
-    } else if (typeof value === 'string') {
+    } 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 === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean' ||
+      value instanceof Date
+    ) {
       currentTag.eq = value;
-    } else if (typeof value === 'number') {
-      currentTag.eq = value.toString(); // TODO big numbers?
     } else if (Array.isArray(value)) {
       currentTag.eq = value.map((v: string | number) => {
-        return {eq: typeof v === 'string' ? v : v.toString()};
+        return new Tag({eq: v}, currentTag);
       });
     }
-    return copy;
+    return this;
   }
 
   delete(...path: Path): Tag {
@@ -451,18 +744,20 @@ export class Tag implements TagInterface {
   }
 
   private remove(path: Path, hard = false): Tag {
-    const origCopy = Tag.tagFrom(this);
-    let currentTag: TagInterface = origCopy;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let currentTag: Tag = 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(_ => ({}));
+          if (!hard) return this;
+          currentTag.eq = Array.from({length: segment}).map(
+            () => new Tag({}, currentTag)
+          );
         } else if (currentTag.eq.length <= segment) {
-          if (!hard) return origCopy;
+          if (!hard) return this;
           const values = currentTag.eq;
           const newVal = Array.from({length: segment}).map((_, i) =>
-            i < values.length ? values[i] : {}
+            i < values.length ? values[i] : new Tag({}, currentTag)
           );
           currentTag.eq = newVal;
         }
@@ -470,14 +765,14 @@ export class Tag implements TagInterface {
       } else {
         const properties = currentTag.properties;
         if (properties === undefined) {
-          if (!hard) return origCopy;
-          currentTag.properties = {[segment]: {}};
+          if (!hard) return this;
+          currentTag.properties = {[segment]: new Tag({}, currentTag)};
           currentTag = currentTag.properties[segment];
         } else if (segment in properties) {
           currentTag = properties[segment];
         } else {
-          if (!hard) return origCopy;
-          properties[segment] = {};
+          if (!hard) return this;
+          properties[segment] = new Tag({}, currentTag);
           currentTag = properties[segment];
         }
       }
@@ -488,290 +783,194 @@ export class Tag implements TagInterface {
         delete currentTag.properties[segment];
       } else if (hard) {
         currentTag.properties ??= {};
-        currentTag.properties[segment] = {deleted: true};
+        currentTag.properties[segment] = new Tag({deleted: true}, currentTag);
       }
     } else {
       if (Array.isArray(currentTag.eq)) {
         currentTag.eq.splice(segment, 1);
       }
     }
-    return origCopy;
+    return this;
   }
 }
 
-class TagErrorListener implements ANTLRErrorListener<Token> {
-  log: TagError[] = [];
-  constructor(readonly line: number) {}
-
-  syntaxError(
-    recognizer: unknown,
-    offendingSymbol: Token | undefined,
-    line: number,
-    charPositionInLine: number,
-    msg: string,
-    _e: unknown
-  ): void {
-    const logMsg: TagError = {
-      code: 'tag-parse-syntax-error',
-      message: msg,
-      line: this.line,
-      offset: charPositionInLine,
-    };
-    this.log.push(logMsg);
-  }
-
-  semanticError(cx: ParserRuleContext, code: string, msg: string): void {
-    const logMsg: TagError = {
-      code,
-      message: msg,
-      line: this.line,
-      offset: cx.start.charPositionInLine,
-    };
-    this.log.push(logMsg);
-  }
-}
+/**
+ * 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
+ */
+export class RefTag extends Tag {
+  readonly ups: number;
+  readonly refPath: Path;
 
-function getBuildOn(ctx: ParserRuleContext): Tag {
-  const buildOn = ctx['buildOn'];
-  if (buildOn instanceof Tag) {
-    return buildOn;
+  constructor(ups: number, refPath: Path, parent?: Tag) {
+    super({}, parent);
+    this.ups = ups;
+    this.refPath = refPath;
   }
-  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
- */
-function buildAccessPath(buildOn: Tag, path: string[]): [string, TagDict] {
-  let parentPropertyObject = buildOn.getProperties();
-  for (const p of path.slice(0, path.length - 1)) {
-    let next: Tag;
-    if (parentPropertyObject[p] === undefined) {
-      next = new Tag({});
-      parentPropertyObject[p] = next;
+  /**
+   * Resolve this reference to the target tag.
+   * Returns undefined if the reference cannot be resolved.
+   */
+  resolve(): Tag | undefined {
+    // Start from the appropriate point based on ups
+    let current: Tag | undefined;
+    if (this.ups === 0) {
+      // Absolute reference from root
+      current = this.root;
     } 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.
-      parentPropertyObject[p].properties ??= {};
-      next = Tag.tagFrom(parentPropertyObject[p]);
+      // 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;
+      }
+    }
+
+    if (current === undefined) {
+      return undefined;
     }
-    parentPropertyObject = next.getProperties();
+
+    // Follow the path
+    return current.find(this.refPath);
   }
-  return [path[path.length - 1], parentPropertyObject];
-}
 
-function getString(ctx: StringContext) {
-  if (ctx.SQ_STRING() || ctx.DQ_STRING()) {
-    return parseString(ctx.text, ctx.text[0]);
+  /**
+   * Quote an identifier if it contains special characters.
+   */
+  private quoteSegment(seg: string): string {
+    // 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, '\\`') + '`';
   }
-  return ctx.text;
-}
 
-function parseTagLine(
-  source: string,
-  extending: Tag | undefined,
-  outerScope: Tag[],
-  onLine: number
-): TagParse {
-  if (source[0] === '#') {
-    const skipTo = source.indexOf(' ');
-    if (skipTo > 0) {
-      source = source.slice(skipTo);
-    } else {
-      source = '';
-    }
-  }
-  const inputStream = CharStreams.fromString(source);
-  const lexer = new MalloyTagLexer(inputStream);
-  const tokenStream = new CommonTokenStream(lexer);
-  const pLog = new TagErrorListener(onLine);
-  const taglineParser = new 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};
-}
+  /**
+   * Convert this reference to its string representation.
+   */
+  toRefString(): string {
+    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;
+  }
 
-class TagLineParser
-  extends AbstractParseTreeVisitor<Tag>
-  implements MalloyTagVisitor<Tag>
-{
-  scopes: Tag[] = [];
-  msgLog: TagErrorListener;
-  constructor(outerScopes: Tag[] = [], msgLog: TagErrorListener) {
-    super();
-    this.msgLog = msgLog;
-    this.scopes.unshift(...outerScopes);
+  // Override virtual accessors to resolve the reference
+  override getEq(): TagValue | undefined {
+    return this.resolve()?.getEq();
   }
 
-  defaultResult() {
-    return new Tag();
+  override getProperty(name: string): Tag | undefined {
+    return this.resolve()?.getProperty(name);
   }
 
-  visitString(ctx: StringContext): Tag {
-    return new Tag({eq: getString(ctx)});
+  override getArrayElement(index: number): Tag | undefined {
+    return this.resolve()?.getArrayElement(index);
   }
 
-  protected getPropName(ctx: PropNameContext): string[] {
-    return ctx
-      .identifier()
-      .map(cx =>
-        cx.BARE_STRING() ? cx.text : parseString(cx.text, cx.text[0])
-      );
+  override hasProperties(): boolean {
+    return this.resolve()?.hasProperties() ?? false;
   }
 
-  getTags(tags: TagSpecContext[], tagLine: Tag): Tag {
-    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);
+  /**
+   * 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.
+   */
+  override toObjectValue(resolving: Set<RefTag>): unknown {
+    // 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;
     }
-    return tagLine;
-  }
 
-  tagLineToTag(ctx: TagLineContext, extending: Tag | undefined): Tag {
-    extending = extending?.clone() || new Tag({});
-    this.scopes.unshift(extending);
-    this.getTags(ctx.tagSpec(), extending);
-    return extending;
-  }
+    const resolved = this.resolve();
+    if (resolved === undefined) {
+      return undefined;
+    }
 
-  visitTagLine(_ctx: TagLineContext): Tag {
-    throw new Error('INTERNAL: ERROR: Call tagLineToTag, not vistTagLine');
-    return this.defaultResult();
-  }
+    // Track that we're resolving this RefTag
+    resolving.add(this);
+    const result = resolved.toObjectValue(resolving);
+    resolving.delete(this);
 
-  visitProperties(ctx: PropertiesContext): Tag {
-    return this.getTags(ctx.tagSpec(), getBuildOn(ctx));
+    return result;
   }
 
-  visitArrayValue(ctx: ArrayValueContext): Tag {
-    return new Tag({eq: this.getArray(ctx)});
+  /**
+   * For JSON serialization, return a marker object instead of resolving.
+   */
+  override toJSON(): TagJSON {
+    return {linkTo: this.toRefString()};
   }
 
-  getArray(ctx: ArrayValueContext): Tag[] {
-    return ctx.arrayElement().map(v => this.visit(v));
+  /**
+   * Check if this reference resolves, add error if not.
+   */
+  override collectReferenceErrors(errors: string[], path: string[]): void {
+    if (this.resolve() === undefined) {
+      const location = path.length > 0 ? path.join('.') : 'root';
+      errors.push(`Unresolved reference at ${location}: ${this.toRefString()}`);
+    }
   }
 
-  visitArrayElement(ctx: ArrayElementContext): Tag {
-    const propCx = ctx.properties();
-    const properties = propCx ? this.visitProperties(propCx) : undefined;
-    const strCx = ctx.string();
-    let value: TagValue | undefined = strCx ? getString(strCx) : undefined;
-
-    const arrayCx = ctx.arrayValue();
-    if (arrayCx) {
-      value = this.getArray(arrayCx);
-    }
+  /**
+   * Clone this RefTag, preserving the reference information.
+   */
+  override clone(newParent?: Tag): RefTag {
+    return new RefTag(this.ups, [...this.refPath], newParent);
+  }
+}
 
-    if (properties) {
-      if (value !== undefined) {
-        properties.eq = value;
-      }
-      return properties;
-    }
+/**
+ * Convert a Tag to a plain TagInterface without internal fields like _parent.
+ * Useful for test comparisons.
+ */
+export function interfaceFromTag(tag: TagInterface): TagInterface {
+  const result: TagInterface = {};
 
-    const refCx = ctx.reference();
-    if (refCx) {
-      return this.visitReference(refCx);
+  if (tag.eq !== undefined) {
+    if (Array.isArray(tag.eq)) {
+      result.eq = tag.eq.map(el => interfaceFromTag(el));
+    } else {
+      result.eq = tag.eq;
     }
-    return new Tag({eq: value});
   }
 
-  visitReference(ctx: ReferenceContext): Tag {
-    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;
-      }
-    }
-    this.msgLog.semanticError(
-      ctx,
-      'tag-property-not-found',
-      `Reference to undefined property ${path.join('.')}`
-    );
-    return this.defaultResult();
-  }
-
-  visitTagEq(ctx: TagEqContext): Tag {
-    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};
-      }
-    } else {
-      writeInto[writeKey] = eq;
-    }
-    return buildOn;
+  if (tag.properties !== undefined) {
+    result.properties = interfaceFromDict(tag.properties);
   }
 
-  visitTagReplaceProperties(ctx: TagReplacePropertiesContext): Tag {
-    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};
-    } else {
-      /// DOTS, just update the properties
-      writeInto[writeKey].properties = props.dict;
-    }
-    return buildOn;
-  }
-
-  visitTagUpdateProperties(ctx: TagUpdatePropertiesContext): Tag {
-    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: TagDefContext): Tag {
-    const buildOn = getBuildOn(ctx);
-    const path = this.getPropName(ctx.propName());
-    const [writeKey, writeInto] = buildAccessPath(buildOn, path);
-    if (ctx.MINUS()) {
-      writeInto[writeKey] = {deleted: true};
-    } else {
-      writeInto[writeKey] = new Tag({});
-    }
-    return buildOn;
+  if (tag.deleted) {
+    result.deleted = true;
   }
 
-  visitTagEmpty(ctx: TagEmptyContext): Tag {
-    const tagList = ctx['buildOn'] as Tag;
-    tagList.properties = {};
-    return tagList;
+  return result;
+}
+
+/**
+ * Convert a TagDict to a plain TagDict without internal fields.
+ */
+export function interfaceFromDict(dict: TagDict): TagDict {
+  const result: TagDict = {};
+  for (const [key, val] of Object.entries(dict)) {
+    result[key] = interfaceFromTag(val);
   }
+  return result;
 }