flowquery 1.0.67 → 1.0.69

package/dist/parsing/statement_info_crawler.js

@@ -5,18 +5,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const database_1 = __importDefault(require("../graph/database"));
 const node_1 = __importDefault(require("../graph/node"));
+const node_reference_1 = __importDefault(require("../graph/node_reference"));
 const relationship_1 = __importDefault(require("../graph/relationship"));
 const ast_node_1 = __importDefault(require("./ast_node"));
 const lookup_1 = __importDefault(require("./data_structures/lookup"));
+const expression_1 = __importDefault(require("./expressions/expression"));
+const f_string_1 = __importDefault(require("./expressions/f_string"));
 const identifier_1 = __importDefault(require("./expressions/identifier"));
+const operator_1 = require("./expressions/operator");
+const parameter_reference_1 = __importDefault(require("./expressions/parameter_reference"));
 const reference_1 = __importDefault(require("./expressions/reference"));
 const subquery_expression_1 = __importDefault(require("./expressions/subquery_expression"));
+const aggregated_return_1 = __importDefault(require("./operations/aggregated_return"));
+const aggregated_with_1 = __importDefault(require("./operations/aggregated_with"));
 const create_node_1 = __importDefault(require("./operations/create_node"));
 const create_relationship_1 = __importDefault(require("./operations/create_relationship"));
 const delete_node_1 = __importDefault(require("./operations/delete_node"));
 const delete_relationship_1 = __importDefault(require("./operations/delete_relationship"));
 const load_1 = __importDefault(require("./operations/load"));
 const match_1 = __importDefault(require("./operations/match"));
+const order_by_1 = __importDefault(require("./operations/order_by"));
+const return_1 = __importDefault(require("./operations/return"));
+const with_1 = __importDefault(require("./operations/with"));
 /**
  * Walks one or more parsed FlowQuery statement ASTs and extracts a
  * `StatementInfo` describing the labels, relationship types, sources, and
@@ -41,12 +51,18 @@ class StatementInfoCrawler {
         this._relProps = new Map();
         this._nodeSources = new Map();
         this._relSources = new Map();
+        this._nodeLiterals = new Map();
+        this._relLiterals = new Map();
+        this._nodeDeclaredProps = new Map();
+        this._relDeclaredProps = new Map();
+        this._nodeDeclaredSources = new Map();
+        this._relDeclaredSources = new Map();
         this._ownCreatedNodeLabels = new Set();
         this._ownCreatedRelTypes = new Set();
         /**
          * For each inline CREATE VIRTUAL clause, the (label or type) it
          * declares and its inner statement AST. The label key receives the
-         * sources collected from the statement during {@link resolveRegisteredSources}.
+         * sources collected from the statement during {@link resolveRegisteredDefinitions}.
          */
         this._ownNodeCreates = [];
         this._ownRelCreates = [];
@@ -63,7 +79,7 @@ class StatementInfoCrawler {
         for (const root of roots) {
             this.crawlStatement(root);
         }
-        this.resolveRegisteredSources();
+        this.resolveRegisteredDefinitions();
         return this.snapshot();
     }
     toIterable(statements) {
@@ -79,6 +95,12 @@ class StatementInfoCrawler {
         this._relProps = new Map();
         this._nodeSources = new Map();
         this._relSources = new Map();
+        this._nodeLiterals = new Map();
+        this._relLiterals = new Map();
+        this._nodeDeclaredProps = new Map();
+        this._relDeclaredProps = new Map();
+        this._nodeDeclaredSources = new Map();
+        this._relDeclaredSources = new Map();
         this._ownCreatedNodeLabels = new Set();
         this._ownCreatedRelTypes = new Set();
         this._ownNodeCreates = [];
@@ -140,17 +162,26 @@ class StatementInfoCrawler {
             for (const pattern of op.patterns) {
                 for (const element of pattern.chain) {
                     if (element instanceof node_1.default) {
-                        for (const lbl of element.labels)
+                        // For a WITH-rebound `MATCH (u)`, the chain
+                        // element's own labels are empty; chase the
+                        // underlying binding so labels/properties land
+                        // on the original :User node.
+                        const effectiveLabels = element.labels.length > 0
+                            ? element.labels
+                            : this.effectiveLabelsFor(element);
+                        for (const lbl of effectiveLabels)
                             this._nodeLabels.add(lbl);
-                        for (const propKey of element.properties.keys()) {
-                            this.addNodeProp(element.labels, propKey);
+                        for (const [propKey, expr] of element.properties) {
+                            this.addNodeProp(effectiveLabels, propKey);
+                            this.tryAddNodeLiteral(effectiveLabels, propKey, expr);
                         }
                     }
                     else if (element instanceof relationship_1.default) {
                         for (const t of element.types)
                             this._relTypes.add(t);
-                        for (const propKey of element.properties.keys()) {
+                        for (const [propKey, expr] of element.properties) {
                             this.addRelProp(element.types, propKey);
+                            this.tryAddRelLiteral(element.types, propKey, expr);
                         }
                     }
                 }
@@ -166,16 +197,22 @@ class StatementInfoCrawler {
             this.collectPropertyAccesses(op);
         }
     }
-    resolveRegisteredSources() {
-        // Sources from inline CREATE VIRTUAL clauses in the crawled statements.
+    resolveRegisteredDefinitions() {
+        // Sources and declared properties from inline CREATE VIRTUAL clauses
+        // in the crawled statements.
         for (const { label, statement } of this._ownNodeCreates) {
             this.collectSources(statement, this.getOrCreate(this._nodeSources, label));
+            this.collectSources(statement, this.getOrCreate(this._nodeDeclaredSources, label));
+            this.collectDeclaredProps(statement, this.getOrCreate(this._nodeDeclaredProps, label));
         }
         for (const { type, statement } of this._ownRelCreates) {
             this.collectSources(statement, this.getOrCreate(this._relSources, type));
+            this.collectSources(statement, this.getOrCreate(this._relDeclaredSources, type));
+            this.collectDeclaredProps(statement, this.getOrCreate(this._relDeclaredProps, type));
         }
-        // Sources from already-registered virtuals that the crawled statements
-        // reference (e.g. MATCH/DELETE against a virtual registered earlier).
+        // Sources / declared properties from already-registered virtuals
+        // that the crawled statements reference (e.g. MATCH/DELETE against
+        // a virtual registered earlier).
         const db = database_1.default.getInstance();
         for (const label of this._nodeLabels) {
             if (this._ownCreatedNodeLabels.has(label))
@@ -183,6 +220,8 @@ class StatementInfoCrawler {
             const physical = db.nodes.get(label);
             if (physical === null || physical === void 0 ? void 0 : physical.statement) {
                 this.collectSources(physical.statement, this.getOrCreate(this._nodeSources, label));
+                this.collectSources(physical.statement, this.getOrCreate(this._nodeDeclaredSources, label));
+                this.collectDeclaredProps(physical.statement, this.getOrCreate(this._nodeDeclaredProps, label));
             }
         }
         for (const type of this._relTypes) {
@@ -194,6 +233,8 @@ class StatementInfoCrawler {
             for (const physical of typeMap.values()) {
                 if (physical.statement) {
                     this.collectSources(physical.statement, this.getOrCreate(this._relSources, type));
+                    this.collectSources(physical.statement, this.getOrCreate(this._relDeclaredSources, type));
+                    this.collectDeclaredProps(physical.statement, this.getOrCreate(this._relDeclaredProps, type));
                 }
             }
         }
@@ -206,6 +247,13 @@ class StatementInfoCrawler {
         }
         return set;
     }
+    /**
+     * Walks the AST rooted at `root` and records every property access
+     * (via `Lookup`) on a known node/relationship binding, every literal
+     * value supplied via equality / `IN` predicates, and descends into
+     * subqueries plus the privately-held WHERE / ORDER BY ASTs of
+     * RETURN-style operations.
+     */
     collectPropertyAccesses(root) {
         const visited = new Set();
         const stack = [root];
@@ -215,20 +263,13 @@ class StatementInfoCrawler {
                 continue;
             visited.add(node);
             if (node instanceof lookup_1.default) {
-                const variable = node.variable;
-                const index = node.index;
-                if (variable instanceof reference_1.default && index instanceof identifier_1.default) {
-                    const referred = variable.referred;
-                    const propName = index.value();
-                    if (typeof propName === "string" && propName.length > 0) {
-                        if (referred instanceof node_1.default) {
-                            this.addNodeProp(referred.labels, propName);
-                        }
-                        else if (referred instanceof relationship_1.default) {
-                            this.addRelProp(referred.types, propName);
-                        }
-                    }
-                }
+                this.handleLookupAccess(node);
+            }
+            if (node instanceof operator_1.Equals) {
+                this.handleEqualityLiteral(node);
+            }
+            else if (node instanceof operator_1.In) {
+                this.handleInLiteral(node);
             }
             for (const child of node.getChildren()) {
                 stack.push(child);
@@ -240,6 +281,269 @@ class StatementInfoCrawler {
                 if (inner !== undefined)
                     stack.push(inner);
             }
+            // RETURN / AggregatedReturn hold WHERE and ORDER BY clauses in
+            // private fields; descend into the ones with expression trees.
+            if (node instanceof return_1.default) {
+                const w = node._where;
+                const o = node._orderBy;
+                if (w)
+                    stack.push(w);
+                if (o)
+                    stack.push(o);
+            }
+            // OrderBy stores its sort expressions in a private array of
+            // SortField objects rather than as AST children; descend
+            // explicitly.
+            if (node instanceof order_by_1.default) {
+                for (const field of node.fields) {
+                    stack.push(field.expression);
+                }
+            }
+        }
+    }
+    handleLookupAccess(node) {
+        const target = this.resolveLookupTarget(node);
+        if (target === null)
+            return;
+        if (target.kind === "node") {
+            this.addNodeProp(target.labels, target.prop);
+        }
+        else {
+            this.addRelProp(target.types, target.prop);
+        }
+    }
+    /**
+     * Resolves a `Lookup` of the shape `alias.prop` to the labels/types
+     * of the bound entity and the property name. Returns `null` if the
+     * lookup isn't of that shape or its variable doesn't resolve to a
+     * Node/Relationship.
+     */
+    resolveLookupTarget(lookup) {
+        const variable = lookup.variable;
+        const index = lookup.index;
+        if (!(variable instanceof reference_1.default) || !(index instanceof identifier_1.default))
+            return null;
+        const propName = index.value();
+        if (typeof propName !== "string" || propName.length === 0)
+            return null;
+        const referred = this.resolveBoundEntity(variable.referred);
+        if (referred instanceof node_1.default) {
+            return { kind: "node", labels: referred.labels, prop: propName };
+        }
+        if (referred instanceof relationship_1.default) {
+            return { kind: "rel", types: referred.types, prop: propName };
+        }
+        return null;
+    }
+    /**
+     * Unwraps a binding chain to the underlying graph entity that
+     * carries the labels / types relevant for lineage. Handles the
+     * common WITH-rebind pattern:
+     *
+     * ```
+     * MATCH (u:User) ... WITH u MATCH (u) RETURN u.name
+     * ```
+     *
+     * After `WITH u`, the variable `u` is bound to the WITH's
+     * `Expression` (a passthrough Reference to the original Node). The
+     * second `MATCH (u)` then creates a `NodeReference` whose own
+     * `labels` are empty. Without unwrapping, `u.name` in `RETURN`
+     * resolves to that empty-labels rebind and the property is silently
+     * dropped from lineage. By chasing through `Reference.referred`,
+     * single-child `Expression` nodes, and `NodeReference.reference`
+     * (when the immediate labels are empty), we recover the original
+     * `Node(:User)` binding.
+     */
+    resolveBoundEntity(node) {
+        const seen = new Set();
+        let current = node;
+        while (current !== undefined && !seen.has(current)) {
+            seen.add(current);
+            // NodeReference subclasses Node and copies its base's
+            // labels at construction. When those copied labels are
+            // empty (`MATCH (u)` after a WITH-rebind), chase the
+            // underlying binding to recover the original labels.
+            if (current instanceof node_reference_1.default) {
+                if (current.labels.length > 0)
+                    return current;
+                const next = current.reference;
+                current = next === null ? undefined : next;
+                continue;
+            }
+            if (current instanceof node_1.default)
+                return current;
+            if (current instanceof relationship_1.default)
+                return current;
+            if (current instanceof reference_1.default) {
+                current = current.referred;
+                continue;
+            }
+            if (current instanceof expression_1.default) {
+                // Pass-through projections (`WITH u`, `RETURN u AS u`)
+                // wrap a single Reference; arbitrary computed
+                // expressions have no useful binding to attribute
+                // properties to.
+                const children = current.getChildren();
+                if (children.length === 1) {
+                    current = children[0];
+                    continue;
+                }
+                return null;
+            }
+            return null;
+        }
+        return null;
+    }
+    /**
+     * Returns the effective labels for a MATCH chain `Node` element.
+     * If the element itself is unlabeled (typical for a WITH-rebound
+     * `MATCH (u)`), unwrap its binding to inherit the original labels.
+     */
+    effectiveLabelsFor(element) {
+        if (element instanceof node_reference_1.default) {
+            const resolved = this.resolveBoundEntity(element);
+            if (resolved instanceof node_1.default) {
+                return resolved.labels;
+            }
+        }
+        return element.labels;
+    }
+    handleEqualityLiteral(op) {
+        const lhs = op.lhs;
+        const rhs = op.rhs;
+        // Try both orientations: `alias.prop = literal` and `literal = alias.prop`.
+        this.tryRecordPropEquality(lhs, rhs);
+        this.tryRecordPropEquality(rhs, lhs);
+    }
+    tryRecordPropEquality(side, other) {
+        if (!(side instanceof lookup_1.default))
+            return;
+        if (!this.isLiteralAst(other))
+            return;
+        const target = this.resolveLookupTarget(side);
+        if (target === null)
+            return;
+        const value = this.safeEvaluate(other);
+        if (value === undefined)
+            return;
+        if (target.kind === "node") {
+            this.addNodeLiteralValue(target.labels, target.prop, value);
+        }
+        else {
+            this.addRelLiteralValue(target.types, target.prop, value);
+        }
+    }
+    handleInLiteral(op) {
+        const lhs = op.lhs;
+        const rhs = op.rhs;
+        if (!(lhs instanceof lookup_1.default))
+            return;
+        if (!this.isLiteralAst(rhs))
+            return;
+        const target = this.resolveLookupTarget(lhs);
+        if (target === null)
+            return;
+        const value = this.safeEvaluate(rhs);
+        if (!Array.isArray(value))
+            return;
+        for (const item of value) {
+            if (target.kind === "node") {
+                this.addNodeLiteralValue(target.labels, target.prop, item);
+            }
+            else {
+                this.addRelLiteralValue(target.types, target.prop, item);
+            }
+        }
+    }
+    /**
+     * Returns true iff the AST subtree contains only literal nodes (no
+     * References, ParameterReferences, Lookups, FStrings, or
+     * SubqueryExpressions). Used to guard literal-value extraction
+     * against runtime-dependent expressions.
+     */
+    isLiteralAst(node) {
+        if (node instanceof reference_1.default ||
+            node instanceof parameter_reference_1.default ||
+            node instanceof lookup_1.default ||
+            node instanceof f_string_1.default ||
+            node instanceof subquery_expression_1.default) {
+            return false;
+        }
+        for (const child of node.getChildren()) {
+            if (!this.isLiteralAst(child))
+                return false;
+        }
+        return true;
+    }
+    safeEvaluate(node) {
+        try {
+            return node.value();
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    tryAddNodeLiteral(labels, prop, expr) {
+        if (!this.isLiteralAst(expr))
+            return;
+        const value = this.safeEvaluate(expr);
+        if (value === undefined)
+            return;
+        this.addNodeLiteralValue(labels, prop, value);
+    }
+    tryAddRelLiteral(types, prop, expr) {
+        if (!this.isLiteralAst(expr))
+            return;
+        const value = this.safeEvaluate(expr);
+        if (value === undefined)
+            return;
+        this.addRelLiteralValue(types, prop, value);
+    }
+    /**
+     * Walks a virtual definition's inner statement to find the final
+     * RETURN-style projection and records its aliases as the declared
+     * property set. Falls back to the last WITH if no RETURN exists.
+     */
+    collectDeclaredProps(statement, target) {
+        let op = null;
+        try {
+            op = statement.firstChild();
+        }
+        catch (_a) {
+            return;
+        }
+        let lastReturn = null;
+        let lastWith = null;
+        while (op !== null) {
+            if (op instanceof return_1.default || op instanceof aggregated_return_1.default) {
+                lastReturn = op;
+            }
+            else if (op instanceof with_1.default || op instanceof aggregated_with_1.default) {
+                lastWith = op;
+            }
+            op = op.next;
+        }
+        const projection = lastReturn !== null && lastReturn !== void 0 ? lastReturn : lastWith;
+        if (projection === null)
+            return;
+        for (const alias of this.projectionAliases(projection)) {
+            target.add(alias);
+        }
+    }
+    /**
+     * Yields the alias of every projected expression in a Projection.
+     * Mirrors the alias-resolution logic of `Projection.expressions()`
+     * (which is protected).
+     */
+    *projectionAliases(projection) {
+        var _a;
+        const children = projection.getChildren();
+        for (let i = 0; i < children.length; i++) {
+            const expr = children[i];
+            const alias = (_a = expr.alias) !== null && _a !== void 0 ? _a : `expr${i}`;
+            if (typeof alias === "string" && alias.length > 0) {
+                yield alias;
+            }
         }
     }
     collectSources(statement, target) {
@@ -297,6 +601,85 @@ class StatementInfoCrawler {
             set.add(prop);
         }
     }
+    addNodeLiteralValue(labels, prop, value) {
+        for (const label of labels) {
+            if (!label)
+                continue;
+            let propMap = this._nodeLiterals.get(label);
+            if (propMap === undefined) {
+                propMap = new Map();
+                this._nodeLiterals.set(label, propMap);
+            }
+            this.appendUniqueLiteral(propMap, prop, value);
+        }
+    }
+    addRelLiteralValue(types, prop, value) {
+        for (const type of types) {
+            if (!type)
+                continue;
+            let propMap = this._relLiterals.get(type);
+            if (propMap === undefined) {
+                propMap = new Map();
+                this._relLiterals.set(type, propMap);
+            }
+            this.appendUniqueLiteral(propMap, prop, value);
+        }
+    }
+    appendUniqueLiteral(propMap, prop, value) {
+        let arr = propMap.get(prop);
+        if (arr === undefined) {
+            arr = [];
+            propMap.set(prop, arr);
+        }
+        for (const existing of arr) {
+            if (this.literalsEqual(existing, value))
+                return;
+        }
+        arr.push(value);
+    }
+    literalsEqual(a, b) {
+        if (a === b)
+            return true;
+        if (a === null || b === null || a === undefined || b === undefined)
+            return false;
+        if (typeof a !== typeof b)
+            return false;
+        if (typeof a !== "object")
+            return false;
+        if (Array.isArray(a) !== Array.isArray(b))
+            return false;
+        if (Array.isArray(a)) {
+            if (a.length !== b.length)
+                return false;
+            for (let i = 0; i < a.length; i++) {
+                if (!this.literalsEqual(a[i], b[i]))
+                    return false;
+            }
+            return true;
+        }
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        for (const k of ka) {
+            if (!Object.prototype.hasOwnProperty.call(b, k))
+                return false;
+            if (!this.literalsEqual(a[k], b[k]))
+                return false;
+        }
+        return true;
+    }
+    literalsSnapshot(map, key) {
+        const propMap = map.get(key);
+        if (propMap === undefined || propMap.size === 0)
+            return {};
+        const out = {};
+        const sortedKeys = Array.from(propMap.keys()).sort();
+        for (const propKey of sortedKeys) {
+            out[propKey] = [...propMap.get(propKey)];
+        }
+        return out;
+    }
     snapshot() {
         const allSources = new Set();
         const nodes = {};
@@ -310,6 +693,7 @@ class StatementInfoCrawler {
             nodes[label] = {
                 properties: props ? Array.from(props).sort() : [],
                 sources: sources ? Array.from(sources).sort() : [],
+                literal_values: this.literalsSnapshot(this._nodeLiterals, label),
             };
         }
         const relationships = {};
@@ -323,8 +707,31 @@ class StatementInfoCrawler {
             relationships[type] = {
                 properties: props ? Array.from(props).sort() : [],
                 sources: sources ? Array.from(sources).sort() : [],
+                literal_values: this.literalsSnapshot(this._relLiterals, type),
             };
         }
+        const declaredNodes = {};
+        for (const label of this._nodeLabels) {
+            const props = this._nodeDeclaredProps.get(label);
+            const sources = this._nodeDeclaredSources.get(label);
+            if ((props && props.size > 0) || (sources && sources.size > 0)) {
+                declaredNodes[label] = {
+                    properties: props ? Array.from(props).sort() : [],
+                    sources: sources ? Array.from(sources).sort() : [],
+                };
+            }
+        }
+        const declaredRelationships = {};
+        for (const type of this._relTypes) {
+            const props = this._relDeclaredProps.get(type);
+            const sources = this._relDeclaredSources.get(type);
+            if ((props && props.size > 0) || (sources && sources.size > 0)) {
+                declaredRelationships[type] = {
+                    properties: props ? Array.from(props).sort() : [],
+                    sources: sources ? Array.from(sources).sort() : [],
+                };
+            }
+        }
         const info = {
             node_labels: Array.from(this._nodeLabels).sort(),
             relationship_types: Array.from(this._relTypes).sort(),
@@ -333,6 +740,10 @@ class StatementInfoCrawler {
             relationship_properties: {},
             nodes,
             relationships,
+            declared: {
+                nodes: declaredNodes,
+                relationships: declaredRelationships,
+            },
         };
         for (const [label, props] of this._nodeProps) {
             info.node_properties[label] = Array.from(props).sort();
@@ -346,13 +757,33 @@ class StatementInfoCrawler {
      * Returns a deep copy of a StatementInfo so callers can mutate it freely.
      */
     static clone(info) {
+        var _a, _b, _c, _d;
         const cloneProps = (props) => {
             const out = {};
             for (const [k, v] of Object.entries(props))
                 out[k] = [...v];
             return out;
         };
+        const cloneLiterals = (literals) => {
+            const out = {};
+            for (const [k, v] of Object.entries(literals)) {
+                out[k] = v.map((item) => typeof item === "object" && item !== null ? structuredClone(item) : item);
+            }
+            return out;
+        };
         const cloneEntities = (entities) => {
+            var _a;
+            const out = {};
+            for (const [k, v] of Object.entries(entities)) {
+                out[k] = {
+                    properties: [...v.properties],
+                    sources: [...v.sources],
+                    literal_values: cloneLiterals((_a = v.literal_values) !== null && _a !== void 0 ? _a : {}),
+                };
+            }
+            return out;
+        };
+        const cloneDeclared = (entities) => {
             const out = {};
             for (const [k, v] of Object.entries(entities)) {
                 out[k] = {
@@ -370,6 +801,10 @@ class StatementInfoCrawler {
             relationship_properties: cloneProps(info.relationship_properties),
             nodes: cloneEntities(info.nodes),
             relationships: cloneEntities(info.relationships),
+            declared: {
+                nodes: cloneDeclared((_b = (_a = info.declared) === null || _a === void 0 ? void 0 : _a.nodes) !== null && _b !== void 0 ? _b : {}),
+                relationships: cloneDeclared((_d = (_c = info.declared) === null || _c === void 0 ? void 0 : _c.relationships) !== null && _d !== void 0 ? _d : {}),
+            },
         };
     }
 }