@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/components/source-picker/CubeTablePreview.tsx

@@ -0,0 +1,49 @@
+/**
+ * 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 { Schema } from '@finos/legend-cube';
+import { CubeSchemaColumnsTable } from '../CubeSchemaColumnsTable.js';
+
+/**
+ * The columns of the table picked last, under the source dialog's list, as
+ * an access point's preview shows them (the review of the demo, 2026-10-13):
+ * loading, then the columns, or why they couldn't be read. A failure doesn't
+ * keep the table from being added: Add asks the engine again.
+ */
+export const CubeTablePreview: React.FC<{
+  /** The table's name, as the list shows it */
+  name: string;
+  /** Its columns, or why they couldn't be read; `undefined` while they load */
+  columns: Schema | string | undefined;
+}> = ({ name, columns }) => (
+  <section
+    className="flex max-h-48 flex-col gap-1 overflow-auto rounded-sm border border-[var(--color-border-default)] p-2"
+    aria-label="Table preview"
+  >
+    <span className="font-medium">{`Columns of ${name}`}</span>
+    {columns === undefined ? (
+      <span className="text-base text-[var(--color-text-secondary)]">
+        loading columns
+      </span>
+    ) : typeof columns === 'string' ? (
+      <span className="text-base text-[var(--color-status-error)]">
+        {columns}
+      </span>
+    ) : (
+      <CubeSchemaColumnsTable schema={columns} />
+    )}
+  </section>
+);

package/src/components/spec-transfer/CubeImportPureDialog.tsx

@@ -0,0 +1,122 @@
+/**
+ * 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 {
+  Dialog,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalFooterButton,
+  ModalHeader,
+  PanelLoadingIndicator,
+} from '@finos/legend-art';
+import { flowResult } from 'mobx';
+import { observer } from 'mobx-react-lite';
+import { LEGEND_CUBE_TEST_ID } from '../../__lib__/LegendCubeTesting.js';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { CUBE_PRIMARY_BUTTON_DARK_MODE } from '../CubeDialogTheme.js';
+
+const TEXT_AREA_CLASS_NAME =
+  'h-80 w-full resize-none rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] p-1 font-mono text-sm text-[var(--color-text-primary)]';
+
+/**
+ * Import Pure (PLAN §11.18): a lambda pasted as Pure, as Show Pure shows one,
+ * or as the engine's JSON, read into the steps Cube writes it with, in
+ * place of this cube
+ */
+export const CubeImportPureDialog = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const { lambdaImport } = editorState;
+    const { applicationStore } = editorState.host;
+    const darkMode =
+      !applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    const importText = (): void => {
+      flowResult(lambdaImport.importText()).catch(
+        applicationStore.alertUnhandledError,
+      );
+    };
+    return (
+      <Dialog
+        open={lambdaImport.isDialogOpen}
+        onClose={() => lambdaImport.closeDialog()}
+      >
+        <Modal darkMode={darkMode} className="w-[720px] max-w-full">
+          <ModalHeader>
+            <div className="modal__title">Import Pure</div>
+          </ModalHeader>
+          <PanelLoadingIndicator isLoading={lambdaImport.isImporting} />
+          <ModalBody>
+            <div
+              className="flex flex-col gap-2"
+              data-testid={LEGEND_CUBE_TEST_ID.IMPORT_PURE}
+            >
+              <div className="text-base text-[var(--color-text-secondary)]">
+                Paste a query, as Show Pure shows one, e.g.{' '}
+                <code>
+                  {'|#>{db::Store.SCHEMA.TABLE}#->filter(x | $x.ID > 1)'}
+                </code>
+                , or its JSON. Cube reads it into steps that replace this cube;
+                Undo brings it back. Its sources are read where the source
+                dialog reads them.
+              </div>
+              <textarea
+                className={TEXT_AREA_CLASS_NAME}
+                aria-label="Pure query"
+                placeholder="Pure query"
+                spellCheck={false}
+                value={lambdaImport.text}
+                onChange={(event) => lambdaImport.setText(event.target.value)}
+              />
+              {lambdaImport.dialogError !== undefined && (
+                <div
+                  className="break-words text-base text-[var(--color-status-error)]"
+                  role="alert"
+                >
+                  {lambdaImport.dialogError.message}
+                  {lambdaImport.dialogError.detail !== undefined && (
+                    <details>
+                      <summary className="cursor-pointer">Details</summary>
+                      <pre className="whitespace-pre-wrap text-sm">
+                        {lambdaImport.dialogError.detail}
+                      </pre>
+                    </details>
+                  )}
+                </div>
+              )}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <ModalFooterButton
+              darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
+              formatText={false}
+              text="Import"
+              disabled={!lambdaImport.text.trim() || lambdaImport.isImporting}
+              onClick={importText}
+            />
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text="Cancel"
+              onClick={() => lambdaImport.closeDialog()}
+            />
+          </ModalFooter>
+        </Modal>
+      </Dialog>
+    );
+  },
+);

package/src/components/spec-transfer/CubeSpecTransferDialog.tsx

@@ -23,10 +23,15 @@ import {
   ModalHeader,
   PanelLoadingIndicator,
 } from '@finos/legend-art';
+import { CodeEditor } from '@finos/legend-lego/code-editor';
 import { flowResult } from 'mobx';
 import { observer } from 'mobx-react-lite';
 import type { CubeEditorState } from '../../stores/CubeEditorState.js';
 import { CUBE_SPEC_TRANSFER_MODE } from '../../stores/CubeSpecTransferState.js';
+import { CUBE_PRIMARY_BUTTON_DARK_MODE } from '../CubeDialogTheme.js';
+
+/** The code editor's language: legend-code-editor's `CODE_EDITOR_LANGUAGE.JSON` */
+const JSON_LANGUAGE = 'json';
 
 const TEXT_AREA_CLASS_NAME =
   'h-80 w-full resize-none rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] p-1 font-mono text-sm text-[var(--color-text-primary)]';
@@ -52,7 +57,7 @@ export const CubeSpecTransferDialog = observer(
         <Modal darkMode={darkMode} className="w-[720px] max-w-full">
           <ModalHeader>
             <div className="modal__title">
-              {isExport ? 'Export spec (dev)' : 'Import spec (dev)'}
+              {isExport ? 'Export spec' : 'Import spec'}
             </div>
           </ModalHeader>
           <PanelLoadingIndicator isLoading={transfer.isReadingFile} />
@@ -60,12 +65,20 @@ export const CubeSpecTransferDialog = observer(
             <div className="flex flex-col gap-2">
               {isExport ? (
                 transfer.exportText !== undefined && (
-                  <textarea
-                    className={TEXT_AREA_CLASS_NAME}
+                  // a code editor, so each object and list folds from the gutter
+                  <div
+                    className="h-80 w-full overflow-hidden rounded-sm border border-[var(--color-border-default)]"
                     aria-label="Cube spec"
-                    readOnly={true}
-                    value={transfer.exportText}
-                  />
+                  >
+                    <CodeEditor
+                      inputValue={transfer.exportText}
+                      language={JSON_LANGUAGE}
+                      isReadOnly={true}
+                      hideMinimap={true}
+                      hideActionBar={true}
+                      extraEditorOptions={{ scrollBeyondLastLine: false }}
+                    />
+                  </div>
                 )
               ) : (
                 <>
@@ -115,7 +128,7 @@ export const CubeSpecTransferDialog = observer(
             {isExport ? (
               <>
                 <ModalFooterButton
-                  darkMode={darkMode}
+                  darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                   formatText={false}
                   text="Copy"
                   disabled={transfer.exportText === undefined}
@@ -126,7 +139,7 @@ export const CubeSpecTransferDialog = observer(
                   }}
                 />
                 <ModalFooterButton
-                  darkMode={darkMode}
+                  darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                   formatText={false}
                   text="Download"
                   disabled={transfer.exportText === undefined}
@@ -135,7 +148,7 @@ export const CubeSpecTransferDialog = observer(
               </>
             ) : (
               <ModalFooterButton
-                darkMode={darkMode}
+                darkMode={CUBE_PRIMARY_BUTTON_DARK_MODE}
                 formatText={false}
                 text="Import"
                 disabled={!transfer.importText.trim() || transfer.isReadingFile}

package/src/graph-manager/CubeConnectionExplorer.ts

@@ -0,0 +1,106 @@
+/**
+ * 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';
+import type { CubeTableFlag } from './CubeEngine.js';
+
+// Direct connections (PLAN §6.8), in Cube's own terms: what the connection
+// form gives, what the page shows of a saved connection, and what reading its
+// database finds. The connection itself stays opaque JSON outside
+// `protocol/pure/v1/`, which alone reads it
+
+/** The databases a direct connection can reach this round */
+export enum CubeDirectDatabaseType {
+  H2 = 'H2',
+  DUCKDB = 'DuckDB',
+}
+
+/** What the connection form gives, before it becomes a connection */
+export interface CubeConnectionDraft {
+  databaseType: CubeDirectDatabaseType;
+  /** Statements the engine runs on each connection, e.g. to create test tables */
+  setupSqls: readonly string[];
+  /** DuckDB only: a database file on the engine's host, or '' for an in-memory database */
+  path?: string | undefined;
+}
+
+/** How a database is reached, as the page shows it */
+export enum CubeConnectionDatasourceKind {
+  /** An H2 database the engine creates in its own H2 server */
+  LOCAL_H2 = 'LOCAL_H2',
+  DUCKDB_IN_MEMORY = 'DUCKDB_IN_MEMORY',
+  DUCKDB_FILE = 'DUCKDB_FILE',
+}
+
+/** What the page shows of a saved connection: never its setup SQL */
+export interface CubeConnectionSummary {
+  databaseType: CubeDirectDatabaseType;
+  datasourceKind: CubeConnectionDatasourceKind;
+  /** The DuckDB file, for a DuckDB file database */
+  path?: string | undefined;
+  setupSqlCount: number;
+  /** The authentication strategy, as the engine names it */
+  authenticationKind: string;
+}
+
+/** A table read from a connection's database, for the picker */
+export interface CubeExploredTable {
+  /** As the database stores it, e.g. `ORDER.LINES` */
+  name: string;
+  /** As a table's coordinates store it: always quoted, e.g. `"ORDER.LINES"` */
+  storedName: string;
+  /** The columns Cube can use */
+  columnCount: number;
+  /** The columns left out because the engine can't type them; Cube shows how many */
+  hiddenColumnCount: number;
+  flags: readonly CubeTableFlag[];
+}
+
+/**
+ * A direct connection as a cube saves it: protocol JSON, which only the
+ * engine's implementation reads
+ */
+export type CubeDirectConnection = PlainObject;
+
+/** What the page knows of a connection without calling the engine */
+export type CubeConnectionDescription =
+  | { supported: true; summary: CubeConnectionSummary }
+  /** Why Cube can't use the connection, in words a user can act on */
+  | { supported: false; problems: readonly string[] };
+
+/**
+ * Reading a direct connection's database (PLAN §6.8), for the picker: its own
+ * port, beside the `CubeEngine`, so hosts without direct connections need
+ * neither. Calls fail with a `CubeEngineError`, with no node
+ */
+export interface CubeConnectionExplorer {
+  /** The connection the connection form describes */
+  buildConnection(draft: CubeConnectionDraft): CubeDirectConnection;
+
+  /** Whether Cube can use a connection, and what the page shows of it: no engine call */
+  describeConnection(
+    connection: CubeDirectConnection,
+  ): CubeConnectionDescription;
+
+  /** The schemas of the connection's database, without the database's own; tests the connection */
+  listSchemas(connection: CubeDirectConnection): Promise<readonly string[]>;
+
+  /** A schema's tables and views, with how many columns Cube can use and hides */
+  listTables(
+    connection: CubeDirectConnection,
+    schema: string,
+  ): Promise<readonly CubeExploredTable[]>;
+}

package/src/graph-manager/CubeDataProduct.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 { ModelContext } from '@finos/legend-cube';
+
+// A data product cube (PLAN §6.8, DP-1) saves its project once, as its
+// model: the project and the version its data products were deployed from,
+// the environment type and, once picked, the warehouse. The engine's
+// implementation builds, for each run, the project at that version and a
+// lakehouse runtime at a fixed path, which the saved runtime names
+
+/** The kind of a data product cube's model: Cube's own, never an engine model kind */
+export const CUBE_DATA_PRODUCT_MODEL_TYPE = 'cubeDataProduct';
+
+/** The runtime a data product cube runs with, in a package of Cube's own */
+export const CUBE_DATA_PRODUCT_RUNTIME_PATH = 'cube::dataProduct::Runtime';
+
+/** The warehouse a run uses when neither the cube nor the viewer has one (PLAN §6.8) */
+export const CUBE_DEFAULT_CONSUMER_WAREHOUSE = 'LAKEHOUSE_CONSUMER_DEFAULT_WH';
+
+/**
+ * The deployment classes Cube reads data products from: production and
+ * production-parallel, as Data Cube's selection offers. Development
+ * deployments are not supported in this phase (user, 2026-10-09)
+ */
+export enum CubeDataProductEnvironmentType {
+  PRODUCTION = 'PRODUCTION',
+  PRODUCTION_PARALLEL = 'PRODUCTION_PARALLEL',
+}
+
+/** The wire name of the development class, which Cube refuses by name */
+const DEVELOPMENT_ENVIRONMENT_TYPE = 'DEVELOPMENT';
+
+/** What a data product cube's model holds */
+export interface CubeDataProductProject {
+  readonly groupId: string;
+  readonly artifactId: string;
+  /** The version the data products were deployed from, as the catalog gave it */
+  readonly versionId: string;
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** The warehouse the cube runs on; none until one is picked */
+  readonly warehouse?: string | undefined;
+}
+
+const ENVIRONMENT_TYPES = Object.values(
+  CubeDataProductEnvironmentType,
+) as string[];
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+/** The model of a data product cube */
+export const createCubeDataProductModel = (
+  project: CubeDataProductProject,
+): ModelContext =>
+  ({
+    _type: CUBE_DATA_PRODUCT_MODEL_TYPE,
+    groupId: project.groupId,
+    artifactId: project.artifactId,
+    versionId: project.versionId,
+    environmentType: project.environmentType,
+    ...(project.warehouse !== undefined
+      ? { warehouse: project.warehouse }
+      : {}),
+  }) as ModelContext;
+
+export const isCubeDataProductModel = (model: ModelContext): boolean =>
+  model._type === CUBE_DATA_PRODUCT_MODEL_TYPE;
+
+/** Whether a version moves: a SNAPSHOT's data and columns may change under a cube */
+export const isCubeSnapshotVersion = (versionId: string): boolean =>
+  versionId.endsWith('-SNAPSHOT');
+
+/**
+ * The model with another warehouse; every other key is kept, including ones
+ * a later version saved, which a cube keeps as they are
+ */
+export const withCubeDataProductWarehouse = (
+  model: ModelContext,
+  warehouse: string,
+): ModelContext => ({ ...model, warehouse });
+
+/**
+ * Why Cube can't run a data product model, in words a user can act on; none
+ * when it can. A saved model is checked before every use: it may have been
+ * written by hand or by a later version
+ */
+export const checkCubeDataProductModel = (
+  model: ModelContext,
+): readonly string[] => {
+  const problems: string[] = [];
+  (['groupId', 'artifactId', 'versionId'] as const).forEach((key) => {
+    if (!isNonEmptyString(model[key])) {
+      problems.push(`The data product's project has no ${key}`);
+    }
+  });
+  if (model.environmentType === DEVELOPMENT_ENVIRONMENT_TYPE) {
+    problems.push(`Cube doesn't read development data products yet`);
+  } else if (!ENVIRONMENT_TYPES.includes(model.environmentType as string)) {
+    problems.push(
+      `Cube doesn't know the environment type "${String(model.environmentType)}"`,
+    );
+  }
+  if (model.warehouse !== undefined && !isNonEmptyString(model.warehouse)) {
+    problems.push(`The cube's warehouse must be a name`);
+  }
+  return problems;
+};
+
+/** The project of a data product model Cube can run; undefined for any other model */
+export const getCubeDataProductProject = (
+  model: ModelContext,
+): CubeDataProductProject | undefined =>
+  isCubeDataProductModel(model) && !checkCubeDataProductModel(model).length
+    ? {
+        groupId: model.groupId as string,
+        artifactId: model.artifactId as string,
+        versionId: model.versionId as string,
+        environmentType:
+          model.environmentType as CubeDataProductEnvironmentType,
+        warehouse: model.warehouse as string | undefined,
+      }
+    : undefined;
+
+/**
+ * The warehouse a run uses (PLAN §6.8, DP-2): the cube's own, else the one
+ * the viewer last picked, else the default consumer warehouse. Shown and sent
+ * alike, so the page shows what runs
+ */
+export const getEffectiveCubeWarehouse = (
+  project: Pick<CubeDataProductProject, 'warehouse'>,
+  rememberedWarehouse: string | undefined,
+): string =>
+  project.warehouse ??
+  (isNonEmptyString(rememberedWarehouse)
+    ? rememberedWarehouse
+    : CUBE_DEFAULT_CONSUMER_WAREHOUSE);