@malloydata/motly-ts-parser 0.0.2 → 0.2.1

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

@@ -0,0 +1,69 @@
+/** A MOTLY scalar: string, number, boolean, or Date. */
+export type MOTLYScalar = string | number | boolean | Date;
+/** A reference to another node in the MOTLY tree (e.g. `$^parent.name`). */
+export interface MOTLYRef {
+    linkTo: string;
+}
+/** An environment variable reference (e.g. `@env.API_KEY`). */
+export interface MOTLYEnvRef {
+    env: string;
+}
+/**
+ * A value 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")
+ * - `deleted` — true if this node was explicitly deleted with `-name`
+ */
+export interface MOTLYValue {
+    eq?: MOTLYScalar | MOTLYRef | MOTLYEnvRef | MOTLYNode[];
+    properties?: Record<string, MOTLYNode>;
+    deleted?: boolean;
+}
+/**
+ * A node in the MOTLY tree. Every node is a {@link MOTLYValue}.
+ * References are represented as `eq: { linkTo: "..." }` inside a value node.
+ */
+export type MOTLYNode = MOTLYValue;
+/** A parse error with source location span. */
+export interface MOTLYError {
+    /** Machine-readable error code (e.g. `"tag-parse-syntax-error"`). */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Start of the offending region (0-based line, column, and byte offset). */
+    begin: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+    /** End of the offending region (0-based, exclusive). */
+    end: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+}
+/** An error from schema validation. */
+export interface MOTLYSchemaError {
+    /** Machine-readable error code (e.g. `"missing-required"`, `"wrong-type"`). */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /** 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 eq value an env reference? */
+export declare function isEnvRef(eq: MOTLYValue["eq"]): eq is MOTLYEnvRef;
+/** An error from reference validation. */
+export interface MOTLYValidationError {
+    /** Machine-readable error code (e.g. `"unresolved-reference"`). */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /** Path to the offending reference (e.g. `["spec", "ref"]`). */
+    path: string[];
+}

package/build/interface/src/types.js

@@ -0,0 +1,12 @@
+"use strict";
+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 eq value an env reference? */
+function isEnvRef(eq) {
+    return typeof eq === "object" && eq !== null && "env" in eq && !Array.isArray(eq) && !(eq instanceof Date);
+}

package/build/{ast.d.ts → parser/src/ast.d.ts}

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

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

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

package/build/parser/src/clone.js

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

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

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

package/build/parser/src/index.js

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

package/build/{interpreter.d.ts → parser/src/interpreter.d.ts}

@@ -1,4 +1,4 @@
 import { Statement } from "./ast";
-import { MOTLYValue } from "motly-ts-interface";
+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): MOTLYValue;
+export declare function execute(statements: Statement[], root: MOTLYValue): MOTLYError[];

package/build/parser/src/interpreter.js

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