H-4747: HashQL: Specialize HIR Graph Expressions (#7433)

Co-authored-by: Tim Diekmann <[email protected]>

Author: indietyp

libs/@local/hashql/ast/tests/ui/lowering/type-extractor/definition/identity-nominal.stdout

@@ -0,0 +1,29 @@
+//@ run: pass
+//@ description: Test that the types are correctly extracted from a graph pipeline with inferred closure.
+[
+  "::core::graph::tail::collect",
+  [
+    "::core::graph::body::filter",
+    [
+      "::core::graph::head::entities",
+      ["::core::graph::tmp::decision_time_now"]
+    ],
+    [
+      "fn",
+      { "#tuple": [] },
+      { "#struct": { "vertex": "_" } },
+      "_",
+      [
+        "==",
+        "vertex.id.entity_id.entity_uuid",
+        [
+          "::core::graph::types::knowledge::entity::EntityUuid",
+          [
+            "::core::uuid::Uuid",
+            { "#literal": "e2851dbb-7376-4959-9bca-f72cafc4448f" }
+          ]
+        ]
+      ]
+    ]
+  ]
+]

libs/@local/hashql/ast/tests/ui/lowering/type-extractor/definition/result.stdout

@@ -94,8 +94,12 @@ impl Suite for HirLowerSpecializationSuite {
         let (mut residual, checking_diagnostics) = checking.finish();
         process_diagnostics(diagnostics, checking_diagnostics)?;
 
-        let mut specialisation =
-            Specialization::new(&interner, &mut residual.types, residual.intrinsics);
+        let mut specialisation = Specialization::new(
+            &environment,
+            &interner,
+            &mut residual.types,
+            residual.intrinsics,
+        );
 
         let node = match specialisation.fold_node(node) {
             Ok(node) => node,

libs/@local/hashql/ast/tests/ui/lowering/type-extractor/graph-pipeline-inferred-closure.jsonc

@@ -333,7 +333,14 @@ impl<'heap> PrettyPrint<'heap> for OpaqueType<'heap> {
         env: &Environment<'heap>,
         boundary: &mut PrettyPrintBoundary,
     ) -> RcDoc<'heap, anstyle::Style> {
-        RcDoc::text(self.name.unwrap())
+        // Remove the module from the name (if exists) this increases readability during
+        // pretty-printing.
+        let name = self.name.unwrap();
+        let name = name
+            .rsplit_once("::")
+            .map_or_else(|| name, |(_, name)| name);
+
+        RcDoc::text(name)
             .append(RcDoc::text("["))
             .append(boundary.pretty_type(env, self.repr).group())
             .append(RcDoc::text("]"))

libs/@local/hashql/ast/tests/ui/lowering/type-extractor/graph-pipeline-inferred-closure.stdout

@@ -1,6 +1,10 @@
 use alloc::borrow::Cow;
 
-use hashql_core::span::SpanId;
+use hashql_core::{
+    pretty::{PrettyOptions, PrettyPrint as _},
+    span::SpanId,
+    r#type::environment::Environment,
+};
 use hashql_diagnostics::{
     Diagnostic,
     category::{DiagnosticCategory, TerminalDiagnosticCategory},
@@ -10,13 +14,9 @@ use hashql_diagnostics::{
     severity::Severity,
 };
 
-pub type SpecializationDiagnostic = Diagnostic<SpecializationDiagnosticCategory, SpanId>;
+use crate::node::Node;
 
-#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
-pub enum SpecializationDiagnosticCategory {
-    UnsupportedIntrinsic,
-    UnknownIntrinsic,
-}
+pub type SpecializationDiagnostic = Diagnostic<SpecializationDiagnosticCategory, SpanId>;
 
 const UNSUPPORTED_INTRINSIC: TerminalDiagnosticCategory = TerminalDiagnosticCategory {
     id: "unsupported-intrinsic",
@@ -28,6 +28,30 @@ const UNKNOWN_INTRINSIC: TerminalDiagnosticCategory = TerminalDiagnosticCategory
     name: "Unknown intrinsic operation",
 };
 
+const INVALID_GRAPH_CHAIN: TerminalDiagnosticCategory = TerminalDiagnosticCategory {
+    id: "invalid-graph-chain",
+    name: "Invalid graph operation chain",
+};
+
+const NON_INTRINSIC_GRAPH_OPERATION: TerminalDiagnosticCategory = TerminalDiagnosticCategory {
+    id: "non-intrinsic-graph-operation",
+    name: "Non-intrinsic function in graph operation",
+};
+
+const NON_GRAPH_INTRINSIC: TerminalDiagnosticCategory = TerminalDiagnosticCategory {
+    id: "non-graph-intrinsic",
+    name: "Non-graph intrinsic in graph operation",
+};
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub enum SpecializationDiagnosticCategory {
+    UnsupportedIntrinsic,
+    UnknownIntrinsic,
+    InvalidGraphChain,
+    NonIntrinsicGraphOperation,
+    NonGraphIntrinsic,
+}
+
 impl DiagnosticCategory for SpecializationDiagnosticCategory {
     fn id(&self) -> Cow<'_, str> {
         Cow::Borrowed("specialization")
@@ -41,6 +65,9 @@ impl DiagnosticCategory for SpecializationDiagnosticCategory {
         match *self {
             Self::UnsupportedIntrinsic => Some(&UNSUPPORTED_INTRINSIC),
             Self::UnknownIntrinsic => Some(&UNKNOWN_INTRINSIC),
+            Self::InvalidGraphChain => Some(&INVALID_GRAPH_CHAIN),
+            Self::NonIntrinsicGraphOperation => Some(&NON_INTRINSIC_GRAPH_OPERATION),
+            Self::NonGraphIntrinsic => Some(&NON_GRAPH_INTRINSIC),
         }
     }
 }
@@ -113,3 +140,105 @@ pub(crate) fn unknown_intrinsic(span: SpanId, intrinsic_name: &str) -> Specializ
 
     diagnostic
 }
+
+/// Creates a diagnostic for an invalid graph operation chain.
+///
+/// This occurs when following a graph chain but encountering a specialized operation
+/// that is not a graph operation (e.g., a math operation that was already processed).
+pub(crate) fn invalid_graph_chain<'heap>(
+    env: &Environment<'heap>,
+    span: SpanId,
+    node: Node<'heap>,
+) -> SpecializationDiagnostic {
+    let mut diagnostic = Diagnostic::new(
+        SpecializationDiagnosticCategory::InvalidGraphChain,
+        Severity::Error,
+    );
+
+    diagnostic
+        .labels
+        .push(Label::new(span, "Expected a graph operation here").with_order(0));
+
+    diagnostic.add_help(Help::new(format!(
+        "{} is not a graph operation. Graph chains can only contain operations that work with \
+         graph data, such as filtering, entity selection, or other graph transformations. \
+         Operations like math, comparisons, or other non-graph functions cannot be part of a \
+         graph chain.",
+        node.pretty_print(env, PrettyOptions::default().with_max_width(60))
+    )));
+
+    diagnostic.add_note(Note::new(
+        "Graph operation chains work by passing graph objects through a sequence of \
+         graph-specific operations. Each operation in the chain must accept a graph and return a \
+         modified graph. Non-graph operations like math, comparisons, or boolean logic should be \
+         used within closures or separate expressions, not as part of the main graph chain.",
+    ));
+
+    diagnostic
+}
+
+/// Creates a diagnostic for using a non-intrinsic function in graph operations.
+///
+/// This occurs when a graph operation chain contains a function call that is not
+/// mapped to an intrinsic operation.
+pub(crate) fn non_intrinsic_graph_operation<'heap>(
+    env: &Environment<'heap>,
+    span: SpanId,
+    function: Node<'heap>,
+) -> SpecializationDiagnostic {
+    let mut diagnostic = Diagnostic::new(
+        SpecializationDiagnosticCategory::NonIntrinsicGraphOperation,
+        Severity::Error,
+    );
+
+    let label_text = "This is not a graph intrinsic operation";
+
+    diagnostic
+        .labels
+        .push(Label::new(span, label_text).with_order(0));
+
+    diagnostic.add_help(Help::new(format!(
+        "{} is not a valid graph operation. Graph operation chains can only contain intrinsic \
+         functions that are part of the HashQL graph API. Higher-order functions (HOFs) and \
+         user-defined functions are not supported yet. To track support for user-defined \
+         functions see https://linear.app/hash/issue/H-4776/hashql-allow-user-defined-functions-in-graph-pipelines",
+         function.pretty_print(env, PrettyOptions::default().with_max_width(60)))));
+
+    diagnostic.add_note(Note::new(
+        "Graph intrinsics are built-in operations like `::core::graph::head::entities`, \
+         `::core::graph::body::filter`, and `::core::graph::tail::collect` that can be optimized \
+         during compilation. Only these predefined operations can be used to build graph query \
+         chains.",
+    ));
+
+    diagnostic
+}
+
+/// Creates a diagnostic for an unknown graph intrinsic operation.
+///
+/// This indicates a compiler bug where a graph intrinsic that should be mapped is missing.
+#[coverage(off)] // compiler bugs should never be hit
+pub(crate) fn non_graph_intrinsic(span: SpanId, intrinsic_name: &str) -> SpecializationDiagnostic {
+    let mut diagnostic = Diagnostic::new(
+        SpecializationDiagnosticCategory::NonGraphIntrinsic,
+        Severity::Bug,
+    );
+
+    diagnostic.labels.push(
+        Label::new(span, format!("unknown graph intrinsic `{intrinsic_name}`")).with_order(0),
+    );
+
+    diagnostic.add_help(Help::new(format!(
+        "The graph intrinsic `{intrinsic_name}` is missing from the graph specialization phase \
+         mapping. Add this intrinsic to the match statement in the `fold_graph_read` method to \
+         resolve this compiler bug."
+    )));
+
+    diagnostic.add_note(Note::new(
+        "This error indicates that a new graph intrinsic was added to the standard library but \
+         the graph specialization phase wasn't updated to handle it. The compiler should be kept \
+         in sync with stdlib changes.",
+    ));
+
+    diagnostic
+}