@finos/legend-cube-builder 0.0.2 → 0.0.4

package/src/__lib__/LegendCubeLabels.ts

@@ -30,9 +30,19 @@ export const MAX_UNDO_STEPS = 100;
 export enum LEGEND_CUBE_USER_DATA_KEY {
   ROW_LIMIT = 'legend-cube.row-limit',
   PALETTE_COLLAPSED = 'legend-cube.palette-collapsed',
+  /** The warehouse the viewer last picked for a data product cube (PLAN §6.8) */
+  DATA_PRODUCT_WAREHOUSE = 'legend-cube.data-product-warehouse',
 }
 
 export const UNSAVED_CUBE_NAME = 'Unsaved Query';
+/** Why a source is disabled on a cube: it reads database tables or data products, never both (PLAN §6.8) */
+export const OTHER_SOURCE_KIND_TITLE =
+  "This cube's sources are of another kind: a cube reads database tables or data products, never both";
+
+/** Why no source can be added to a cube: the host doesn't serve the cube's kind of source (PLAN §6.8) */
+export const UNSERVED_SOURCE_KIND_TITLE =
+  "This Legend deployment doesn't serve this cube's kind of source, so no source can be added to it";
+
 /** Why a cube's edits are disabled: it was saved by a newer version (Settled before M1.8) */
 export const READ_ONLY_CUBE_TITLE =
   "This cube was saved by a newer version of Legend Cube, so it can't be changed or exported";
@@ -46,6 +56,7 @@ export enum CUBE_PENDING_LABEL {
   EXECUTING_QUERY = 'executing query',
   RENDERING_QUERY = 'rendering query',
   REFRESHING_SOURCE = 'refreshing source',
+  TYPING_COLUMNS = 'typing new columns',
 }
 
 export const getRowLimitError = (text: string): string | undefined => {
@@ -87,8 +98,8 @@ const listColumns = (columns: readonly SchemaColumn[]): string =>
 export const formatDisabledReasons = (reasons: readonly string[]): string =>
   reasons.map((reason) => `• ${reason}`).join('\n');
 
-/** The warning on a source whose table changed since the cube was saved; the table's new columns are used */
-export const getSchemaDriftWarning = (diff: SchemaDiff): string => {
+/** A source's changes since the cube was saved, as its drift warning lists them */
+export const getSchemaChangeList = (diff: SchemaDiff): string => {
   const changes = [
     ...(diff.added.length ? [`added ${listColumns(diff.added)}`] : []),
     ...(diff.removed.length ? [`removed ${listColumns(diff.removed)}`] : []),
@@ -104,13 +115,43 @@ export const getSchemaDriftWarning = (diff: SchemaDiff): string => {
       : []),
     ...(diff.reordered ? ['reordered its columns'] : []),
   ];
-  return `This table changed since the cube was saved: ${changes.join('; ')}`;
+  return changes.join('; ');
+};
+
+/** The warning on a source whose table changed since the cube was saved; the table's new columns are used */
+export const getSchemaDriftWarning = (diff: SchemaDiff): string =>
+  `This table changed since the cube was saved: ${getSchemaChangeList(diff)}`;
+
+/** Why the Sort editor's picker doesn't offer a column, after its type */
+export const CUBE_SORT_COLUMN_DISABLED_REASON = {
+  NOT_SORTABLE: "can't be sorted",
+  TAKEN: 'already sorted on',
+};
+
+/** Why the grid's quick actions (spec §12.4) can't be used */
+export const CUBE_QUICK_ACTION_DISABLED_REASON = {
+  STALE_ROWS:
+    'Execute again: these rows are from an earlier version of the query.',
+  RUNNING: 'Wait for the run to finish.',
+  EDITING:
+    "Close the node editor first: these rows don't show the changes in it.",
+  UNREADABLE_VALUE: "This value can't be used in a filter.",
+  notSortable: (typeName: string): string =>
+    `Values of type ${typeName} can't be sorted.`,
+  notGroupable: (typeName: string): string =>
+    `Values of type ${typeName} can't be grouped.`,
+  notComparable: (typeName: string): string =>
+    `Values of type ${typeName} can't be compared.`,
 };
 
 /** Beside a condition comparing a floating-point column for equality (R133) */
 export const FILTER_FLOAT_COMPARISON_HINT =
   'exact comparison on floating-point columns may not match';
 
+/** The Filter and Join editors' warning on a column that can hold both dates and timestamps (PLAN §11.5) */
+export const DATE_OR_TIMESTAMP_WARNING =
+  'this column can hold both dates and timestamps, as Convert types made it a Date: a date reads as midnight, so it matches a timestamp only at midnight';
+
 /** The Filter editor's note on NULLs (D4): negated conditions keep them */
 export const FILTER_NULL_NOTE =
   'A negated condition (is not, does not contain, is not in list of, Not) also keeps the rows where its column is empty (NULL).';
@@ -120,6 +161,7 @@ export enum CUBE_EDITOR_CLOSED_REASON {
   NODE_CHANGED = 'nodeChanged',
   NODE_REMOVED = 'nodeRemoved',
   CUBE_REPLACED = 'cubeReplaced',
+  CANNOT_APPLY = 'cannotApply',
 }
 
 /** The notice of a node editor that closed by itself, dropping its edits (M1.8b) */
@@ -132,10 +174,156 @@ export const getEditorClosedNotice = (
       ? `${nodeId} changed`
       : reason === CUBE_EDITOR_CLOSED_REASON.NODE_REMOVED
         ? `${nodeId} was removed`
-        : 'Another cube was opened';
+        : reason === CUBE_EDITOR_CLOSED_REASON.CANNOT_APPLY
+          ? `The query can't take the changes to ${nodeId}`
+          : 'Another cube was opened';
   return `${cause}, so the editor of ${nodeId} closed without applying its changes.`;
 };
 
 /** The warning on a source with saved columns that the engine couldn't type again */
 export const getSourceRecheckWarning = (firstLine: string): string =>
   `Could not re-check this table, so it keeps its saved columns: ${firstLine}`;
+
+/** Under the Slice editor's fields: the range counts from 0, and leaves out its stop row (D5) */
+export const SLICE_RANGE_HINT =
+  'Rows count from 0: the start row is kept, the stop row is not.';
+
+/** The Distinct editor's text: it has nothing to set (spec §17.6) */
+export const DISTINCT_EDITOR_TEXT =
+  'Keeps one row of each set of identical rows. There is nothing to set.';
+
+/** The Concat editor's text: what Concat requires of its inputs (PLAN §11.5) */
+export const CONCAT_EDITOR_TEXT =
+  'Gives the rows of both inputs, keeping duplicates, in no particular order. Both must have the same columns, matched by position: the same names, in the same order, with the same types.';
+
+/** What the Concat editor's Convert types setting does (PLAN §11.5, Q5) */
+export const CONCAT_CONVERT_TYPES_HINT =
+  'Converts types that differ within numbers, strings or dates to the type they share, e.g. Varchar(15) and Varchar(40) to String.';
+
+/** What the Concat editor says when a fix would make its inputs match only with Convert types ticked (PLAN §11.5) */
+export const CONCAT_FIX_NEEDS_CONVERT_TEXT =
+  'With Convert types ticked, Cube can rename or drop columns to make the inputs match.';
+
+/** What the Concat editor says when Convert types would make its inputs match (PLAN §11.5, Q5) */
+export const CONCAT_CONVERT_FIX_TEXT =
+  'The types differ, but converting them to the type they share makes the inputs match:';
+export const CONCAT_CONVERT_FIX_TITLE = 'Tick Convert types; Apply stores it';
+
+/** What the Concat editor's Rename autofix says it will do (PLAN §11.5, Q6) */
+export const CONCAT_RENAME_FIX_TEXT =
+  "The second input's columns can take the first input's names:";
+export const CONCAT_RENAME_FIX_TITLE =
+  "Add a Rename before the second input that gives these columns the first input's names, as one step to undo";
+
+/** What the Concat editor's Restrict autofix says it will do, for the input it drops columns from (PLAN §11.5, Q6) */
+export const getConcatRestrictFixText = (
+  input: string,
+  other: string,
+): string =>
+  `The ${input} input has columns the ${other} doesn't, which can be dropped:`;
+export const getConcatRestrictFixTitle = (
+  input: string,
+  other: string,
+): string =>
+  `Add a Restrict before the ${input} input that keeps only the ${other} input's columns, as one step to undo`;
+
+/** The Concat editor's warning on columns whose real type Cube doesn't know (PLAN §8.7) */
+export const getConcatUntypedWarning = (columns: readonly string[]): string =>
+  `${CUBE_TABLE_FLAG_LABELS[CubeTableFlag.TYPE_UNKNOWN].label}: Cube doesn't know the real type of ${columns.join(', ')}, so the database may not combine the inputs' values`;
+
+/** Why the Group editor can't take a column as a key (PLAN §11.5) */
+export const CUBE_GROUP_COLUMN_DISABLED_REASON = "can't be grouped";
+
+/** What the Group editor says about its aggregations (PLAN §11.5; Count counts non-empty values, D4) */
+export const GROUP_EDITOR_NOTES = [
+  'Count counts the values that are not empty; Count Rows counts every row.',
+  'Distinct Value is the value when the group has exactly one distinct value that is not empty, and empty otherwise.',
+  'With no group column, the result is one row, even when there are no rows.',
+];
+
+/** Why the Partition editor won't tick a column that can't be compared (PLAN §11.6) */
+export const CUBE_PARTITION_COLUMN_DISABLED_REASON = "can't be partitioned by";
+
+/** What a Partition row shows in the column's place for a function that takes none (PLAN §11.6) */
+export const getPartitionNoColumnText = (fn: string): string =>
+  fn === 'CountRows' ? 'Every row' : 'By the sort columns';
+
+/** What the Partition editor says about its window functions (PLAN §11.6: D5's frames, Q2, Q3; §11.9) */
+export const PARTITION_EDITOR_NOTES = [
+  'With sort columns, the aggregations (Count to Max, and Count Rows) run from the first row of the partition to the current row, and rows that tie on the sort columns count together: a Distinct Value is then the one value so far. Without sort columns, they cover the whole partition.',
+  "Rank, Dense Rank and Row Number need a sort column. Tied rows share a rank: Rank then skips numbers and Dense Rank doesn't. Row Number numbers every row, and rows tied on this node's sort columns get their numbers in no set order: add a sort column that tells them apart, such as an id, for a stable top N.",
+  'NTile, Percent Rank and Cumulative Distribution need a sort column too. NTile splits each partition into buckets of near-equal size, numbered from 1 in the sort order; Percent Rank and Cumulative Distribution give each row its place in its partition, from 0 to 1.',
+  "Lag and Lead read a column from the row so many rows before or after in the sort order, and are empty at the partition's edges. First and Last read it from the partition's first and last rows, the same on every row. They need a sort column, and rows tied on it may give any of them.",
+  "On ClickHouse, First and Last skip empty values, and Lag and Lead show a column's default, such as 0, at the partition's edges instead of empty, unless the column can be empty there.",
+  "Their sort columns also make this node's other functions run. For totals over the whole partition, add another Apply Window Functions without sort columns.",
+  'Empty sort values come last when ascending and first when descending on H2; other databases may differ.',
+  "A Sort before this node doesn't order the window: its sort columns do. The rows keep the order they came in.",
+  'Count counts the values that are not empty; Count Rows counts every row.',
+  'Some databases, such as Postgres, SQL Server, Databricks and Trino, refuse Distinct Count and Distinct Value in a window.',
+];
+
+/** Why a column of the Left input can't be a difference column (PLAN §11.7) */
+export const CUBE_DIFFERENCE_COLUMN_REASONS = Object.freeze({
+  JOIN_COLUMN: 'a join column',
+  NOT_NUMERIC: 'not a number',
+  NOT_IN_RIGHT: 'not in the Right input',
+  TYPE_DIFFERS: (rightType: string): string =>
+    `${rightType} in the Right input`,
+});
+
+/** What the Difference editor says about its output (spec §7.12, PLAN §11.7) */
+export const DIFFERENCE_EDITOR_NOTES = [
+  "For each difference column x, the output has x_1, the Left input's value, x_2, the Right input's value, and x_valueDifference, x_1 minus x_2.",
+  'Rows only one input has are kept, with empty values for the other input, and an empty value counts as 0 in the difference.',
+  'A difference column needs the same number type in both inputs; the difference of integers is an Integer, of floats a Float, and of decimals a Number.',
+];
+
+/** What the Extend editor says about its expressions (PLAN §11.7) */
+export const EXTEND_EDITOR_NOTES = [
+  'Write each expression as a lambda of one row, such as x | $x.PRICE * $x.QTY: $x.PRICE reads the column PRICE. A column can use the new columns above it.',
+  'A column that can be empty needs ->toOne() before arithmetic, such as $x.QTY->toOne() * 2; an empty value still gives an empty result. Every new column can be empty.',
+  "Validate (F10) checks the expressions with the engine, types them, and plans them for this cube's database: some functions type, but not every database runs them.",
+];
+
+/** Why the Extend editor's Apply waits (PLAN §11.7) */
+export const EXTEND_APPLY_DISABLED_REASON = Object.freeze({
+  NOT_VALIDATED: 'Validate the expressions first (F10)',
+  VALIDATING: 'Validating the expressions',
+});
+
+/** The warning on an Extend whose saved types the engine couldn't check again, e.g. offline (PLAN §11.7) */
+export const getExtendRetypeWarning = (firstLine: string): string =>
+  `Could not check these columns' types again, so they keep their saved ones: ${firstLine}`;
+
+/** The notice of a node editor kept open, since its changes can't be applied yet, e.g. an Extend's expressions not validated */
+export const getEditorKeptOpenNotice = (
+  nodeId: string,
+  waiting: string,
+): string =>
+  `The editor of ${nodeId} stays open, since its changes can't be applied yet: ${waiting}, or Cancel to drop them.`;
+
+/** The hint after an engine error on a column that can be empty, in arithmetic (PLAN §11.7) */
+export const EXTEND_TO_ONE_HINT =
+  'A column that can be empty needs ->toOne() first, such as $x.QTY->toOne() + 1.';
+
+/** The problem a database refusing an Extend's plan gives (PLAN §11.7) */
+export const getExtendPlanProblem = (
+  databaseType: string | undefined,
+  detail: string,
+): string =>
+  `${databaseType ? `${databaseType} can't run it` : "The database can't run it"}: ${detail}`;
+
+/** Under the Rename editor's rows: the rule for new column names (PLAN §11.4) */
+export const COLUMN_NAME_RULES_HINT =
+  'Names can\'t start or end with a space, or contain " or \\ or control characters, and have at most 128 characters.';
+
+/**
+ * A node type's label as the node editor's title shows it, each word
+ * capitalised (QUESTIONS.md U1(a)), e.g. 'Take First <x> Rows'; the registry
+ * keeps its own wording
+ */
+export const toEditorTitle = (label: string): string =>
+  label.replace(/(?<=^|\s)[a-z]/gu, (letter) => letter.toUpperCase());
+
+/** The source dialog's body until a tab is chosen, opened from the empty canvas (spec §17.8, U4(b)) */
+export const SELECT_SOURCE_TYPE_PROMPT = 'Select source type above';

package/src/__lib__/LegendCubeProjectLabels.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// The words of Legend Cube's Project Database tab (PLAN §6.3)
+
+export const CUBE_PROJECT_LABEL = Object.freeze({
+  LOADING_PROJECTS: "Listing the depot's projects…",
+  LOADING_VERSIONS: "Listing the project's versions…",
+  LATEST: '(latest)',
+  NO_RUNTIME:
+    "No runtime of this project connects to this Database, so its tables can't be read. Pick another Database.",
+});

package/src/__lib__/LegendCubeTesting.ts

@@ -25,6 +25,7 @@ export enum LEGEND_CUBE_TEST_ID {
   PALETTE_ITEM = 'legend-cube__palette-item',
   NODE_EDITOR = 'legend-cube__node-editor',
   EDITOR_NOTICE = 'legend-cube__editor-notice',
+  ENTRY_SOURCE_ERROR = 'legend-cube__entry-source-error',
   FILTER_CONDITION = 'legend-cube__filter-condition',
   RESULT_GRID = 'legend-cube__result-grid',
   GRID_TOOLBAR = 'legend-cube__grid-toolbar',

package/src/__test-utils__/CubeCanvasTestUtils.ts

@@ -50,4 +50,4 @@ export const TEST__getCanvasNodes = (): HTMLElement[] =>
 
 /** The node's tooltip, one line an item: errors, warnings, description, id */
 export const TEST__getCanvasNodeTooltip = (node: HTMLElement): string[] =>
-  (node.getAttribute('title') ?? '').split('\n');
+  (node.getAttribute('aria-description') ?? '').split('\n');

package/src/__test-utils__/CubeConnectionTestSupport.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import axios, { type AxiosResponse } from 'axios';
+import {
+  ContentType,
+  HttpHeader,
+  type PlainObject,
+} from '@finos/legend-shared';
+import { ENGINE_TEST_SUPPORT_API_URL } from '@finos/legend-graph/test';
+
+// Engine calls for the engine tests of direct connections (PLAN §6.8), as
+// plain JSON: the connection must reach the engine exactly as it is saved,
+// which legend-graph's connection serializers don't do (they drop a DuckDB
+// connection's setup SQL)
+
+/**
+ * Reads a database through a connection: the engine introspects it and
+ * returns a model holding one Database, `{_type: 'data', elements}`
+ */
+export const CUBE_ENGINE_TEST__schemaExploration = async (
+  input: object,
+): Promise<PlainObject> =>
+  (
+    await axios.post<unknown, AxiosResponse<PlainObject>>(
+      `${ENGINE_TEST_SUPPORT_API_URL}/pure/v1/utilities/database/schemaExploration`,
+      input,
+      {
+        headers: { [HttpHeader.CONTENT_TYPE]: ContentType.APPLICATION_JSON },
+      },
+    )
+  ).data;

package/src/__test-utils__/CubeDirectConnectionFixtures.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { PlainObject } from '@finos/legend-shared';
+
+// Connections to small, self-contained test databases, as the protocol JSON a
+// direct-connection cube saves (PLAN §6.8). Each setup first drops what it
+// creates, because the engine keeps an H2 server and a DuckDB connection
+// between calls, and uses its own schema, so tests can share an engine
+
+export const DIRECT_H2_SCHEMA = 'CUBE_DIRECT';
+export const DIRECT_DUCKDB_SCHEMA = 'cube_direct';
+
+/**
+ * An H2 database the engine creates in its own H2 server, in the schema given:
+ * each test file uses its own, as files run at once against one engine
+ */
+export const directH2Connection = (schema: string): PlainObject => ({
+  _type: 'RelationalDatabaseConnection',
+  type: 'H2',
+  databaseType: 'H2',
+  datasourceSpecification: {
+    _type: 'h2Local',
+    testDataSetupSqls: [
+      `drop schema if exists ${schema} cascade`,
+      `create schema ${schema}`,
+      `create table ${schema}.ORDERS (ORDER_ID INT PRIMARY KEY, CUSTOMER_ID VARCHAR(5) NOT NULL, AMOUNT DECIMAL(10,2))`,
+      `insert into ${schema}.ORDERS values (1, 'ALFKI', 12.34), (2, 'ANATR', 5.00)`,
+    ],
+  },
+  authenticationStrategy: { _type: 'h2Default' },
+});
+
+/**
+ * An in-memory DuckDB database (an empty path), so no file is read or
+ * written, in the schema given
+ */
+export const directDuckDBConnection = (schema: string): PlainObject => ({
+  _type: 'RelationalDatabaseConnection',
+  type: 'DuckDB',
+  databaseType: 'DuckDB',
+  datasourceSpecification: {
+    _type: 'duckDB',
+    path: '',
+    testDataSetupSqls: [
+      `drop schema if exists ${schema} cascade`,
+      `create schema ${schema}`,
+      `create table ${schema}.orders (order_id INTEGER PRIMARY KEY, customer_id VARCHAR(5) NOT NULL, amount DECIMAL(10,2))`,
+      `insert into ${schema}.orders values (1, 'ALFKI', 12.34), (2, 'ANATR', 5.00)`,
+    ],
+  },
+  authenticationStrategy: { _type: 'test' },
+});
+
+export const DIRECT_H2_CONNECTION = directH2Connection(DIRECT_H2_SCHEMA);
+export const DIRECT_DUCKDB_CONNECTION =
+  directDuckDBConnection(DIRECT_DUCKDB_SCHEMA);

package/src/__test-utils__/CubeEngineTestSupport.ts

@@ -135,3 +135,76 @@ export const CUBE_ENGINE_TEST__execute = async (
     text: async () => response.data,
   };
 };
+
+/**
+ * Generates the execution plan of a query, never running it, and gives the
+ * SQL of its nodes, outermost first; a body given as text (with lossless
+ * numbers) is sent as it is
+ */
+export const CUBE_ENGINE_TEST__generatePlanSql = async (
+  input: object | string,
+): Promise<string[]> => {
+  const { data } = await axios.post<unknown, AxiosResponse<string>>(
+    `${PURE_API}/execution/generatePlan`,
+    input,
+    {
+      headers: JSON_HEADERS,
+      responseType: 'text',
+      transformResponse: (text: string) => text,
+    },
+  );
+  const sql: string[] = [];
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+    } else if (node && typeof node === 'object') {
+      Object.entries(node).forEach(([key, value]) => {
+        if (key === 'sqlQuery' && typeof value === 'string') {
+          sql.push(value);
+        } else {
+          visit(value);
+        }
+      });
+    }
+  };
+  visit(parseLosslessJSON(data));
+  return sql;
+};
+/**
+ * The protocol JSON of a value specification's text, parsed with its source
+ * information under the source id, given as the client's unread response
+ * (an Extend column's expression, PLAN §11.7), so it is read losslessly
+ */
+export const CUBE_ENGINE_TEST__grammarToJson_valueSpecification = async (
+  code: string,
+  sourceId: string,
+): Promise<{ ok: boolean; status: number; text: () => Promise<string> }> => {
+  const response = await axios.post<unknown, AxiosResponse<string>>(
+    `${PURE_API}/grammar/grammarToJson/valueSpecification`,
+    code,
+    {
+      headers: { [HttpHeader.CONTENT_TYPE]: ContentType.TEXT_PLAIN },
+      params: { sourceId, returnSourceInformation: true },
+      responseType: 'text',
+      transformResponse: (data: string) => data,
+      validateStatus: () => true,
+    },
+  );
+  return {
+    ok: response.status >= 200 && response.status < 300,
+    status: response.status,
+    text: async () => response.data,
+  };
+};
+
+/** Generates the execution plan of a query, never running it; a body given as text is sent as it is */
+export const CUBE_ENGINE_TEST__generatePlan = async (
+  input: object | string,
+): Promise<PlainObject> =>
+  (
+    await axios.post<unknown, AxiosResponse<PlainObject>>(
+      `${PURE_API}/execution/generatePlan`,
+      input,
+      { headers: JSON_HEADERS },
+    )
+  ).data;

package/src/__test-utils__/CubeExpressionTestUtils.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  buildSchemasAndValidity,
+  Extend,
+  getExtendSignature,
+  type JsonObject,
+  PrimitiveType,
+  type Query,
+} from '@finos/legend-cube';
+
+// Extend columns for tests (PLAN §11.7), written as the engine's JSON, as a
+// column stores it: number literals as their digits
+
+/** `x | <body>` and the pieces of a body */
+export const TEST__expression = {
+  lambda: (body: JsonObject): JsonObject => ({
+    _type: 'lambda',
+    parameters: [{ _type: 'var', name: 'x' }],
+    body: [body],
+  }),
+  /** `$x.<name>` */
+  column: (name: string): JsonObject => ({
+    _type: 'property',
+    property: name,
+    parameters: [{ _type: 'var', name: 'x' }],
+  }),
+  call: (name: string, ...parameters: JsonObject[]): JsonObject => ({
+    _type: 'func',
+    function: name,
+    parameters,
+  }),
+  /** The two operands of `+`, `*`, … */
+  pair: (first: JsonObject, second: JsonObject): JsonObject => ({
+    _type: 'collection',
+    multiplicity: { lowerBound: 2, upperBound: 2 },
+    values: [first, second],
+  }),
+  integer: (value: number): JsonObject => ({
+    _type: 'integer',
+    value: String(value),
+  }),
+};
+
+/** A new column: its name, its lambda, and the type the engine gives it */
+export type TEST__ExtendColumn = readonly [string, JsonObject, string];
+
+/**
+ * An Extend of these columns, typed as given for the input Cube infers for
+ * `input`'s selected node, so it is valid without the engine; the engine
+ * tests check the types are the engine's. With an invalid input, untyped.
+ */
+export const TEST__typedExtend = (
+  id: string,
+  input: Query,
+  columns: readonly TEST__ExtendColumn[],
+): Extend => {
+  const schema = buildSchemasAndValidity(input).schemas.get(
+    input.selected ?? '',
+  );
+  const extendColumns = columns.map(([name, lambda]) => ({
+    name,
+    code: name,
+    lambda,
+  }));
+  // an invalid input, e.g. a table not resolved yet: nothing to type it for
+  if (!schema) {
+    return new Extend(id, extendColumns);
+  }
+  return new Extend(id, extendColumns, {
+    kind: 'typed',
+    signature: getExtendSignature(schema, extendColumns),
+    types: columns.map(([, , type]) => PrimitiveType.get(type)),
+  });
+};
+
+/** `a: x | $x.ORDER_ID + 1` and `b: x | $x.a * 2`, the second using the first, both Integer */
+export const TEST__ORDER_ID_EXTEND_COLUMNS: readonly TEST__ExtendColumn[] = [
+  [
+    'a',
+    TEST__expression.lambda(
+      TEST__expression.call(
+        'plus',
+        TEST__expression.pair(
+          TEST__expression.column('ORDER_ID'),
+          TEST__expression.integer(1),
+        ),
+      ),
+    ),
+    'Integer',
+  ],
+  [
+    'b',
+    TEST__expression.lambda(
+      TEST__expression.call(
+        'times',
+        TEST__expression.pair(
+          TEST__expression.column('a'),
+          TEST__expression.integer(2),
+        ),
+      ),
+    ),
+    'Integer',
+  ],
+];