flowquery 1.0.67 → 1.0.68

package/dist/parsing/statement_info_crawler.d.ts

@@ -1,22 +1,46 @@
 import ASTNode from "./ast_node";
 /**
  * Per-entity lineage for a node label: which properties the query
- * accesses on it, and which sources (URLs / file URIs / async-function
- * names) back the virtual definition for that label.
+ * accesses on it, the sources backing the virtual definition, and any
+ * literal values the query supplies for those properties.
  */
 export interface NodeInfo {
     properties: string[];
     sources: string[];
+    /**
+     * Literal values supplied for this label's properties at the call
+     * site. Collected from inline node-property assignments
+     * (`(u:User {id: 'rick.o'})`) and from equality / `IN` predicates
+     * (`WHERE u.id = 'rick.o'`, `WHERE u.id IN ['a', 'b']`).
+     *
+     * Only purely literal AST subtrees (no references, parameters,
+     * f-strings, or subqueries) are captured. Always present in objects
+     * produced by the crawler (defaults to `{}`); optional in the
+     * interface so externally-constructed `NodeInfo` literals remain
+     * valid.
+     */
+    literal_values?: Record<string, any[]>;
 }
 /**
  * Per-entity lineage for a relationship type: which properties the query
- * accesses on it, and which sources back the virtual definitions for
- * that type. A single type may have multiple sources when it spans
- * several `(:From)-[:Type]-(:To)` definitions.
+ * accesses on it, the sources backing the virtual definitions, and any
+ * literal values supplied for those properties. A single type may have
+ * multiple sources when it spans several `(:From)-[:Type]-(:To)` definitions.
  */
 export interface RelationshipInfo {
     properties: string[];
     sources: string[];
+    /** Literal values supplied for this type's properties at the call site. */
+    literal_values?: Record<string, any[]>;
+}
+/**
+ * Schema-level lineage: the full set of properties projected by a virtual
+ * definition (independent of whether the crawled statement consumes them)
+ * plus the sources that back the definition.
+ */
+export interface DeclaredEntityInfo {
+    properties: string[];
+    sources: string[];
 }
 /**
  * Structural information extracted from a parsed FlowQuery statement.
@@ -24,12 +48,18 @@ export interface RelationshipInfo {
  * Captures the node labels, relationship types, data sources, and properties
  * the query references — independent of whether/when it has been executed.
  * The properties listed are those accessed by the *query itself* (e.g.
- * `n.name` in a MATCH/RETURN/WHERE), not the columns produced by the
- * underlying virtual node/relationship definitions.
+ * `n.name` in a MATCH/RETURN/WHERE/ORDER BY), not the columns produced by
+ * the underlying virtual node/relationship definitions.
  *
  * To trace the full lineage from a property to its source, use the
  * {@link nodes} / {@link relationships} maps. Each entry there links a
- * label/type to its accessed properties and the sources that back it.
+ * label/type to its accessed properties, the sources that back it, and
+ * any literal values supplied at the call site.
+ *
+ * To validate a query against the registered schema (e.g. "is
+ * `User.phoneNumber` a declared property?"), use {@link declared}, which
+ * lists the *full* set of properties projected by each virtual's RETURN
+ * clause regardless of whether the query consumes them.
  */
 export interface StatementInfo {
     /** Unique node labels referenced by MATCH/CREATE/DELETE in the statement(s). */
@@ -50,14 +80,31 @@ export interface StatementInfo {
     relationship_properties: Record<string, string[]>;
     /**
      * Per-label lineage: each accessed node label mapped to the
-     * properties accessed on it and the sources that back it.
+     * properties accessed on it, the sources that back it, and any
+     * literal values supplied for those properties at the call site.
      */
     nodes: Record<string, NodeInfo>;
     /**
      * Per-type lineage: each accessed relationship type mapped to the
-     * properties accessed on it and the sources that back it.
+     * properties accessed on it, the sources that back it, and any
+     * literal values supplied for those properties at the call site.
      */
     relationships: Record<string, RelationshipInfo>;
+    /**
+     * Schema-declared lineage. Lists, per label / relationship type, the
+     * full set of properties projected by the virtual's RETURN clause
+     * (or final WITH if no RETURN is present) — independent of whether
+     * the crawled statement actually consumes them. Useful for validating
+     * that a query references only declared properties.
+     *
+     * Includes both inline `CREATE VIRTUAL` declarations in the crawled
+     * statements and any already-registered virtuals the statement
+     * touches.
+     */
+    declared: {
+        nodes: Record<string, DeclaredEntityInfo>;
+        relationships: Record<string, DeclaredEntityInfo>;
+    };
 }
 /**
  * Walks one or more parsed FlowQuery statement ASTs and extracts a
@@ -82,12 +129,18 @@ declare class StatementInfoCrawler {
     private _relProps;
     private _nodeSources;
     private _relSources;
+    private _nodeLiterals;
+    private _relLiterals;
+    private _nodeDeclaredProps;
+    private _relDeclaredProps;
+    private _nodeDeclaredSources;
+    private _relDeclaredSources;
     private _ownCreatedNodeLabels;
     private _ownCreatedRelTypes;
     /**
      * 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}.
      */
     private _ownNodeCreates;
     private _ownRelCreates;
@@ -102,12 +155,57 @@ declare class StatementInfoCrawler {
     private reset;
     private crawlStatement;
     private visitOperation;
-    private resolveRegisteredSources;
+    private resolveRegisteredDefinitions;
     private getOrCreate;
+    /**
+     * 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.
+     */
     private collectPropertyAccesses;
+    private handleLookupAccess;
+    /**
+     * 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.
+     */
+    private resolveLookupTarget;
+    private handleEqualityLiteral;
+    private tryRecordPropEquality;
+    private handleInLiteral;
+    /**
+     * 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.
+     */
+    private isLiteralAst;
+    private safeEvaluate;
+    private tryAddNodeLiteral;
+    private tryAddRelLiteral;
+    /**
+     * 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.
+     */
+    private collectDeclaredProps;
+    /**
+     * Yields the alias of every projected expression in a Projection.
+     * Mirrors the alias-resolution logic of `Projection.expressions()`
+     * (which is protected).
+     */
+    private projectionAliases;
     private collectSources;
     private addNodeProp;
     private addRelProp;
+    private addNodeLiteralValue;
+    private addRelLiteralValue;
+    private appendUniqueLiteral;
+    private literalsEqual;
+    private literalsSnapshot;
     private snapshot;
     /**
      * Returns a deep copy of a StatementInfo so callers can mutate it freely.

package/dist/parsing/statement_info_crawler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"statement_info_crawler.d.ts","sourceRoot":"","sources":["../../src/parsing/statement_info_crawler.ts"],"names":[],"mappings":"AAGA,OAAO,OAAO,MAAM,YAAY,CAAC;AAajC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC1B,gFAAgF;IAChF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uFAAuF;IACvF,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mEAAmE;IACnE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClD;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,cAAM,oBAAoB;IACtB,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,UAAU,CAAuC;IACzD,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,WAAW,CAAuC;IAC1D,OAAO,CAAC,qBAAqB,CAA0B;IACvD,OAAO,CAAC,mBAAmB,CAA0B;IACrD;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAoD;IAC3E,OAAO,CAAC,cAAc,CAAmD;IAEzE;;;;;OAKG;IACI,KAAK,CAAC,UAAU,EAAE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,aAAa;IAUpE,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,KAAK;IAab,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,cAAc;IA2DtB,OAAO,CAAC,wBAAwB;IAkChC,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,uBAAuB;IAoC/B,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,QAAQ;IA4ChB;;OAEG;WACW,KAAK,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa;CA4B1D;AAED,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"statement_info_crawler.d.ts","sourceRoot":"","sources":["../../src/parsing/statement_info_crawler.ts"],"names":[],"mappings":"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"}