@finos/legend-cube-builder 0.0.3 → 0.0.4

package/src/__test-utils__/CubeOperationsTestUtils.ts

@@ -145,6 +145,89 @@ export const TEST__inferredSchema = (
   return schema as Schema;
 };
 
+/** A node of a query to type with the engine, under a key of its own */
+export interface TEST__TypingTarget {
+  key: string;
+  query: Query;
+  nodeId: string;
+}
+
+/**
+ * Every node of the query that can be emitted, keyed `<prefix>/<node id>`, in
+ * the query's node order
+ */
+export const TEST__emittableNodes = (
+  prefix: string,
+  query: Query,
+): TEST__TypingTarget[] => {
+  const emitter = new QueryEmitter(query);
+  return query.nodes
+    .filter((node) => emitter.canEmit(node.id))
+    .map((node) => ({ key: `${prefix}/${node.id}`, query, nodeId: node.id }));
+};
+
+/** The engine's schema of each target, in one engine call */
+export const TEST__engineSchemas = async (
+  engine: CubeEngine,
+  targets: readonly TEST__TypingTarget[],
+): Promise<Map<string, Schema | Error>> =>
+  engine.typeLambdas(
+    CUBE_NORTHWIND_MODEL,
+    new Map(
+      targets.map(({ key, query, nodeId }) => [
+        key,
+        new QueryEmitter(query).emitTypingLambda(nodeId),
+      ]),
+    ),
+  );
+
+/**
+ * How Cube's schema of a node differs from the engine's, one line per
+ * difference: names, positions and types with their parameters must be the
+ * same. Nullability must be the same too, except on the columns in
+ * `widerNullable`, where the engine misreports it (outer-join padding, the
+ * FULL merged key: PLAN §4.7, §11.5) and Cube must say nullable. With
+ * `oneWay`, Cube may be wider on any column.
+ */
+export const TEST__typingDifferences = (
+  key: string,
+  cube: Schema | undefined,
+  engineSchema: Schema | Error | undefined,
+  options: {
+    widerNullable?: readonly string[] | undefined;
+    oneWay?: boolean | undefined;
+  } = {},
+): string[] => {
+  if (!cube) {
+    return [`${key}: Cube infers no schema`];
+  }
+  if (!(engineSchema instanceof Schema)) {
+    return [`${key}: the engine gives no schema (${engineSchema?.message})`];
+  }
+  const describe = (schema: Schema): string[] =>
+    schema.columns.map((column) => `${column.name}: ${column.type.fullName}`);
+  if (describe(cube).join() !== describe(engineSchema).join()) {
+    return [
+      `${key}: columns [${describe(cube).join(', ')}], the engine's [${describe(engineSchema).join(', ')}]`,
+    ];
+  }
+  const wider = new Set(options.widerNullable ?? []);
+  return cube.columns.flatMap((column, index) => {
+    const engineNullable = engineSchema.columns[index]?.nullable === true;
+    if (wider.has(column.name)) {
+      return column.nullable
+        ? []
+        : [`${key}: ${column.name} should be nullable`];
+    }
+    return column.nullable === engineNullable ||
+      (options.oneWay && column.nullable)
+      ? []
+      : [
+          `${key}: ${column.name} is ${column.nullable ? '' : 'not '}nullable, the engine's ${engineNullable ? '' : 'not '}nullable`,
+        ];
+  });
+};
+
 /**
  * The engine types the node as Cube infers it: the same names, in the same
  * order, of the same types and parameters. Cube's nullability may only be
@@ -155,23 +238,15 @@ export const TEST__expectEngineTyping = async (
   query: Query,
   nodeId = query.selected ?? '',
 ): Promise<void> => {
-  const cube = TEST__inferredSchema(query, nodeId);
-  const typed = (
-    await engine.typeLambdas(
-      CUBE_NORTHWIND_MODEL,
-      new Map([[nodeId, new QueryEmitter(query).emitTypingLambda(nodeId)]]),
-    )
-  ).get(nodeId);
-  expect(typed).toBeInstanceOf(Schema);
-  const engineSchema = typed as Schema;
+  const typed = await TEST__engineSchemas(engine, [
+    { key: nodeId, query, nodeId },
+  ]);
   expect(
-    cube.columns.map((column) => [column.name, column.type.fullName]),
-  ).toEqual(
-    engineSchema.columns.map((column) => [column.name, column.type.fullName]),
-  );
-  cube.columns.forEach((column, index) => {
-    if (engineSchema.columns[index]?.nullable) {
-      expect([column.name, column.nullable]).toEqual([column.name, true]);
-    }
-  });
+    TEST__typingDifferences(
+      nodeId,
+      TEST__inferredSchema(query, nodeId),
+      typed.get(nodeId),
+      { oneWay: true },
+    ),
+  ).toEqual([]);
 };

package/src/__test-utils__/CubePageTestUtils.tsx

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { expect } from '@jest/globals';
 import {
   ApplicationFrameworkProvider,
   ApplicationStoreProvider,
@@ -23,10 +24,14 @@ import { TEST__BrowserEnvironmentProvider } from '@finos/legend-application/test
 import type { CubeDocument } from '@finos/legend-cube';
 import {
   act,
+  fireEvent,
   type RenderResult,
   render,
+  screen,
   waitFor,
+  within,
 } from '@testing-library/react';
+import { LEGEND_CUBE_TEST_ID } from '../__lib__/LegendCubeTesting.js';
 import type { CubeEditorState } from '../stores/CubeEditorState.js';
 
 /** React Flow watches the canvas with an IntersectionObserver, which jsdom lacks */
@@ -94,3 +99,33 @@ export const TEST__importDocument = async (
     }
   });
 };
+
+/** The graph header's 'Add Items' trigger */
+export const TEST__getAddItemsTrigger = (): HTMLButtonElement =>
+  within(screen.getByTestId(LEGEND_CUBE_TEST_ID.GRAPH_REGION)).getByRole(
+    'button',
+    { name: 'Add Items' },
+  );
+
+/** Opens 'Add Items' in the graph's header and returns its menu */
+export const TEST__openAddItems = async (): Promise<HTMLElement> => {
+  fireEvent.click(TEST__getAddItemsTrigger());
+  return screen.findByRole('menu');
+};
+
+/**
+ * Chooses an item of 'Add Items' by its label, as the menu shows it (e.g.
+ * 'Relational Database Table', 'Data Product (BETA)', 'Filter by Column'),
+ * and waits for the menu to close
+ */
+export const TEST__chooseAddItem = async (label: string): Promise<void> => {
+  const menu = await TEST__openAddItems();
+  fireEvent.click(within(menu).getByRole('menuitem', { name: label }));
+  await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+};
+
+/** Closes 'Add Items' without choosing an item, as Escape does */
+export const TEST__closeAddItems = async (): Promise<void> => {
+  fireEvent.keyDown(screen.getByRole('menu'), { key: 'Escape' });
+  await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+};

package/src/__test-utils__/CubeTestApplication.ts

@@ -29,6 +29,14 @@ import {
   type FakeCubeEngine,
   type FakeCubeEngineAnswers,
 } from './FakeCubeEngine.js';
+import {
+  createFakeCubeConnectionExplorer,
+  type FakeCubeConnectionExplorer,
+} from './FakeCubeConnectionExplorer.js';
+import {
+  createFakeCubeDataProductCatalog,
+  type FakeCubeDataProductCatalog,
+} from './FakeCubeDataProductCatalog.js';
 
 // A bare Legend application for Cube's jsdom tests, as the data-space viewer's
 // tests build theirs: the builder may not use the query builder's test helpers
@@ -65,18 +73,29 @@ export const TEST__createCubeApplicationStore = (
   );
 };
 
-/** A host over a fake engine, with the bundled models */
+/** A host over fakes of the engine, the connection explorer and the data product catalog, with the bundled models */
 export const TEST__createCubeHost = (
   answers?: FakeCubeEngineAnswers,
   applicationStore = TEST__createCubeApplicationStore(),
-): { host: CubeHost; fake: FakeCubeEngine } => {
+): {
+  host: CubeHost;
+  fake: FakeCubeEngine;
+  connections: FakeCubeConnectionExplorer;
+  dataProducts: FakeCubeDataProductCatalog;
+} => {
   const fake = createFakeCubeEngine(answers);
+  const connections = createFakeCubeConnectionExplorer();
+  const dataProducts = createFakeCubeDataProductCatalog();
   return {
     host: {
       applicationStore,
       engine: fake.engine,
       modelCatalog: new LocalModelCatalog(fake.engine),
+      connectionExplorer: connections.explorer,
+      dataProductCatalog: dataProducts.catalog,
     },
     fake,
+    connections,
+    dataProducts,
   };
 };

package/src/__test-utils__/FakeCubeConnectionExplorer.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 { jest } from '@jest/globals';
+import {
+  CubeConnectionDatasourceKind,
+  type CubeConnectionExplorer,
+  CubeDirectDatabaseType,
+  type CubeExploredTable,
+} from '../graph-manager/CubeConnectionExplorer.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+} from '../graph-manager/CubeEngine.js';
+
+// A connection explorer for jsdom tests: canned answers, no network. Each
+// method is a jest.fn, so tests can read its calls or change its answer. Any
+// connection is supported and summarized as an in-memory H2 database.
+
+/** A schema of two tables, one with a column Cube hides */
+export const FAKE_DIRECT_TABLES: readonly CubeExploredTable[] = [
+  {
+    name: 'ORDERS',
+    storedName: '"ORDERS"',
+    columnCount: 3,
+    hiddenColumnCount: 1,
+    flags: [],
+  },
+  {
+    name: 'ORDER.LINES',
+    storedName: '"ORDER.LINES"',
+    columnCount: 2,
+    hiddenColumnCount: 0,
+    flags: [],
+  },
+];
+
+export interface FakeCubeConnectionExplorerAnswers {
+  /** keyed by schema name; a schema not in it gets a compile error */
+  readonly tables?: ReadonlyMap<string, readonly CubeExploredTable[]>;
+}
+
+export interface FakeCubeConnectionExplorer {
+  readonly explorer: CubeConnectionExplorer;
+  readonly buildConnection: jest.Mock<
+    CubeConnectionExplorer['buildConnection']
+  >;
+  readonly describeConnection: jest.Mock<
+    CubeConnectionExplorer['describeConnection']
+  >;
+  readonly listSchemas: jest.Mock<CubeConnectionExplorer['listSchemas']>;
+  readonly listTables: jest.Mock<CubeConnectionExplorer['listTables']>;
+}
+
+/** A fresh fake: build one per test, since jest.fn keeps its calls across tests */
+export const createFakeCubeConnectionExplorer = (
+  answers: FakeCubeConnectionExplorerAnswers = {},
+): FakeCubeConnectionExplorer => {
+  const tables =
+    answers.tables ?? new Map([['CUBE_DIRECT', FAKE_DIRECT_TABLES]]);
+  const buildConnection = jest.fn<CubeConnectionExplorer['buildConnection']>(
+    (draft) => ({ _type: 'fake', ...draft }),
+  );
+  const describeConnection = jest.fn<
+    CubeConnectionExplorer['describeConnection']
+  >(() => ({
+    supported: true,
+    summary: {
+      databaseType: CubeDirectDatabaseType.H2,
+      datasourceKind: CubeConnectionDatasourceKind.LOCAL_H2,
+      setupSqlCount: 1,
+      authenticationKind: 'h2Default',
+    },
+  }));
+  const listSchemas = jest.fn<CubeConnectionExplorer['listSchemas']>(async () =>
+    Promise.resolve([...tables.keys()]),
+  );
+  const listTables = jest.fn<CubeConnectionExplorer['listTables']>(
+    async (_connection, schema) => {
+      const found = tables.get(schema);
+      return found
+        ? Promise.resolve(found)
+        : Promise.reject(
+            new CubeEngineError(
+              CubeEngineErrorKind.COMPILE,
+              `The schema "${schema}" can't be found`,
+            ),
+          );
+    },
+  );
+  return {
+    explorer: { buildConnection, describeConnection, listSchemas, listTables },
+    buildConnection,
+    describeConnection,
+    listSchemas,
+    listTables,
+  };
+};

package/src/__test-utils__/FakeCubeDataProductCatalog.ts

@@ -0,0 +1,227 @@
+/**
+ * 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 { jest } from '@jest/globals';
+import { PrimitiveType, Schema, SchemaColumn } from '@finos/legend-cube';
+import { CubeDataProductEnvironmentType } from '../graph-manager/CubeDataProduct.js';
+import {
+  CubeAccessPoint,
+  CubeAccessPointGroup,
+  CubeAccessPointGroupAccess,
+  type CubeDataProductCatalog,
+  CubeDataProductCandidate,
+  CubeDataProductDescription,
+} from '../graph-manager/CubeDataProductCatalog.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+} from '../graph-manager/CubeEngine.js';
+
+// A data product catalog for jsdom tests: canned products, no network. Each
+// method is a jest.fn, so tests can read its calls or change its answer
+
+const { PRODUCTION, PRODUCTION_PARALLEL } = CubeDataProductEnvironmentType;
+
+const column = (name: string, path: string, params: number[] = []) =>
+  new SchemaColumn(name, PrimitiveType.get(path, params), false);
+
+/** The orders product's daily access point */
+export const FAKE_DAILY_ORDERS_SCHEMA = new Schema([
+  column('ORDER_ID', 'meta::pure::precisePrimitives::BigInt'),
+  column('CUSTOMER_ID', 'meta::pure::precisePrimitives::Varchar', [10]),
+  column('REGION', 'meta::pure::precisePrimitives::Varchar', [20]),
+  column('AMOUNT', 'meta::pure::precisePrimitives::Numeric', [10, 2]),
+]);
+
+export const FAKE_CUSTOMERS_SCHEMA = new Schema([
+  column('CUSTOMER_ID', 'meta::pure::precisePrimitives::Varchar', [10]),
+  column('COUNTRY', 'meta::pure::precisePrimitives::Varchar', [40]),
+]);
+
+const candidate = (
+  id: string,
+  title: string,
+  environmentType: CubeDataProductEnvironmentType,
+  versionId = '1.4.0',
+): CubeDataProductCandidate =>
+  new CubeDataProductCandidate({
+    id,
+    deploymentId: `deployment-${id.toLowerCase()}`,
+    dataProductPath: `sales::products::${title.replace(/\s/gu, '')}`,
+    title,
+    description: `${title}, for tests`,
+    groupId: 'com.example.sales',
+    artifactId: 'orders-products',
+    versionId,
+    environmentType,
+    producerEnvironmentName: 'sales-producer',
+  });
+
+/** Products of each class Cube lists, one deployed from a moving version */
+export const FAKE_DATA_PRODUCT_CANDIDATES: readonly CubeDataProductCandidate[] =
+  [
+    candidate('ORDERS_PRODUCT', 'Orders Product', PRODUCTION),
+    candidate(
+      'RETURNS_PRODUCT',
+      'Returns Product',
+      PRODUCTION,
+      'feature-returns-SNAPSHOT',
+    ),
+    candidate('ORDERS_PRODUCT', 'Orders Product', PRODUCTION_PARALLEL),
+  ];
+
+/** Two groups: one with a pickable access point, and two that can't be picked */
+export const fakeDescriptionOf = (
+  product: CubeDataProductCandidate,
+): CubeDataProductDescription =>
+  new CubeDataProductDescription(product, [
+    new CubeAccessPointGroup({
+      id: 'core',
+      title: 'Core',
+      accessPoints: [
+        new CubeAccessPoint({
+          id: 'daily_orders',
+          title: 'Daily orders',
+          description: 'One row per order',
+          schema: FAKE_DAILY_ORDERS_SCHEMA,
+          sampleRows: [['1', 'ALFKI', 'EMEA', '12.34']],
+        }),
+        new CubeAccessPoint({
+          id: 'orders_as_of',
+          title: 'Orders as of a date',
+          schema: FAKE_DAILY_ORDERS_SCHEMA,
+          disabledReason:
+            'It takes parameters, which Cube does not support yet',
+        }),
+      ],
+    }),
+    new CubeAccessPointGroup({
+      id: 'reference',
+      title: 'Reference',
+      accessPoints: [
+        new CubeAccessPoint({ id: 'customers', schema: FAKE_CUSTOMERS_SCHEMA }),
+        new CubeAccessPoint({
+          id: 'raw_feed',
+          disabledReason: 'Its columns are not in the deployed artifact',
+        }),
+      ],
+    }),
+  ]);
+
+const SCHEMAS = new Map([
+  ['daily_orders', FAKE_DAILY_ORDERS_SCHEMA],
+  ['customers', FAKE_CUSTOMERS_SCHEMA],
+]);
+
+export interface FakeCubeDataProductCatalog {
+  readonly catalog: CubeDataProductCatalog;
+  readonly search: jest.Mock<CubeDataProductCatalog['search']>;
+  readonly describe: jest.Mock<CubeDataProductCatalog['describe']>;
+  readonly resolveSchemas: jest.Mock<CubeDataProductCatalog['resolveSchemas']>;
+  readonly getMarketplaceLink: jest.Mock<
+    CubeDataProductCatalog['getMarketplaceLink']
+  >;
+  readonly getAccess: jest.Mock<
+    NonNullable<CubeDataProductCatalog['getAccess']>
+  >;
+}
+
+/**
+ * A fresh fake: build one per test, since jest.fn keeps its calls across
+ * tests. One that searches on a server answers with its matches, as the
+ * lakehouse's list is answered, but read anew on each search, as a server's
+ * answer is
+ */
+export const createFakeCubeDataProductCatalog = (
+  candidates: readonly CubeDataProductCandidate[] = FAKE_DATA_PRODUCT_CANDIDATES,
+  options?: {
+    searchesOnServer?: boolean;
+    searchLimit?: number;
+    isCutShort?: CubeDataProductCatalog['isCutShort'];
+  },
+): FakeCubeDataProductCatalog => {
+  const search = jest.fn<CubeDataProductCatalog['search']>(
+    async ({ text, environmentType }) =>
+      Promise.resolve(
+        candidates
+          .filter(
+            (product) =>
+              product.environmentType === environmentType &&
+              `${product.title} ${product.id}`
+                .toLowerCase()
+                .includes(text.trim().toLowerCase()),
+          )
+          .map((product) =>
+            options?.searchesOnServer
+              ? new CubeDataProductCandidate({ ...product })
+              : product,
+          ),
+      ),
+  );
+  const describe = jest.fn<CubeDataProductCatalog['describe']>(
+    async (product) => Promise.resolve(fakeDescriptionOf(product)),
+  );
+  const resolveSchemas = jest.fn<CubeDataProductCatalog['resolveSchemas']>(
+    async (_project, sources) =>
+      Promise.resolve(
+        new Map(
+          [...sources].map(([nodeId, source]) => [
+            nodeId,
+            SCHEMAS.get(source.accessPoint) ??
+              new CubeEngineError(
+                CubeEngineErrorKind.COMPILE,
+                `The access point "${source.accessPoint}" can't be found`,
+                nodeId,
+              ),
+          ]),
+        ),
+      ),
+  );
+  const getMarketplaceLink = jest.fn<
+    CubeDataProductCatalog['getMarketplaceLink']
+  >(
+    (target) =>
+      `https://marketplace.test/dataProduct/deployed/${target.dataProductId}/${target.deploymentId}${target.accessPointGroup ? `#${target.accessPointGroup}` : ''}`,
+  );
+  // the viewer is entitled to the core group, and has never asked for the reference one
+  const getAccess = jest.fn<NonNullable<CubeDataProductCatalog['getAccess']>>(
+    async () =>
+      Promise.resolve(
+        new Map([
+          ['core', CubeAccessPointGroupAccess.APPROVED],
+          ['reference', CubeAccessPointGroupAccess.NO_ACCESS],
+        ]),
+      ),
+  );
+  return {
+    catalog: {
+      environmentTypes: [PRODUCTION, PRODUCTION_PARALLEL],
+      searchesOnServer: options?.searchesOnServer,
+      searchLimit: options?.searchLimit,
+      isCutShort: options?.isCutShort,
+      search,
+      describe,
+      resolveSchemas,
+      getMarketplaceLink,
+      getAccess,
+    },
+    search,
+    describe,
+    resolveSchemas,
+    getMarketplaceLink,
+    getAccess,
+  };
+};

package/src/__test-utils__/FakeCubeEngine.ts

@@ -99,6 +99,8 @@ export interface FakeCubeEngine {
   readonly typeLambdas: jest.Mock<CubeEngine['typeLambdas']>;
   readonly execute: jest.Mock<CubeEngine['execute']>;
   readonly renderPure: jest.Mock<CubeEngine['renderPure']>;
+  readonly parseExpression: jest.Mock<CubeEngine['parseExpression']>;
+  readonly planLambda: jest.Mock<CubeEngine['planLambda']>;
 }
 
 /** A fresh fake: build one per test, since jest.fn keeps its calls across tests */
@@ -134,12 +136,34 @@ export const createFakeCubeEngine = (
   const renderPure = jest.fn<CubeEngine['renderPure']>(async () =>
     Promise.resolve(answers.pure ?? ''),
   );
+  // a test that types expressions says how; by default, each parses to nothing
+  const parseExpression = jest.fn<CubeEngine['parseExpression']>(async () =>
+    Promise.reject(
+      new CubeEngineError(
+        CubeEngineErrorKind.COMPILE,
+        'The fake engine parses no expression',
+      ),
+    ),
+  );
+  const planLambda = jest.fn<CubeEngine['planLambda']>(async () =>
+    Promise.resolve(),
+  );
   return {
-    engine: { loadModel, resolveSchemas, typeLambdas, execute, renderPure },
+    engine: {
+      loadModel,
+      resolveSchemas,
+      typeLambdas,
+      execute,
+      renderPure,
+      parseExpression,
+      planLambda,
+    },
     loadModel,
     resolveSchemas,
     typeLambdas,
     execute,
     renderPure,
+    parseExpression,
+    planLambda,
   };
 };