@finos/legend-cube-builder 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,304 @@
+/**
+ * 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 {
+  clsx,
+  Dialog,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalFooterButton,
+  ModalHeader,
+  PanelLoadingIndicator,
+} from '@finos/legend-art';
+import { getRelationalDisplayName } from '@finos/legend-cube';
+import { flowResult } from 'mobx';
+import { observer } from 'mobx-react-lite';
+import { useId } from 'react';
+import {
+  CUBE_PENDING_LABEL,
+  CUBE_TABLE_FLAG_LABELS,
+} from '../../__lib__/LegendCubeLabels.js';
+import type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { isTableSelectable } from '../../stores/CubeSourcePickerState.js';
+import { CubeButton } from '../CubeButton.js';
+
+/** One step of the picker: a labelled list of choices, read-only when the cube fixes it */
+const CubePickerStep: React.FC<{
+  label: string;
+  value: string | undefined;
+  options: readonly { value: string; label: string }[];
+  disabled?: boolean;
+  onChange: (value: string | undefined) => void;
+}> = ({ label, value, options, disabled, onChange }) => {
+  const id = useId();
+  return (
+    <div className="flex items-center gap-2">
+      <label className="w-20 shrink-0 text-base" htmlFor={id}>
+        {label}
+      </label>
+      <select
+        id={id}
+        className="h-7 min-w-0 flex-1 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base text-[var(--color-text-primary)] disabled:text-[var(--color-text-secondary)]"
+        value={value ?? ''}
+        disabled={Boolean(disabled) || !options.length}
+        onChange={(event) => onChange(event.target.value || undefined)}
+      >
+        {value === undefined && <option value="">Choose…</option>}
+        {options.map((option) => (
+          <option key={option.value} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+/**
+ * Adds a table to the cube (PLAN §6.2.7): a minimal dialog, which M3
+ * redesigns. The table lands with its schema; the first one fixes the cube's
+ * model and runtime.
+ */
+/** The Model option that offers a text box for Pure text */
+const PASTE_MODEL_OPTION = 'paste';
+
+export const CubeSourcePicker = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const picker = editorState.sourcePicker;
+    const { applicationStore } = editorState.host;
+    const darkMode =
+      !applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    const isFixed = picker.fixedContext !== undefined;
+    const fixedModelLabel =
+      picker.models.find(
+        (model) =>
+          JSON.stringify(model.model) ===
+          JSON.stringify(picker.fixedContext?.model),
+      )?.label ?? "The cube's model";
+    const confirm = (): void => {
+      flowResult(picker.confirm()).catch(applicationStore.alertUnhandledError);
+    };
+
+    return (
+      <Dialog open={picker.isOpen} onClose={() => picker.close()}>
+        <Modal darkMode={darkMode} className="w-[640px] max-w-full">
+          <ModalHeader>
+            <div className="modal__title">Add a table</div>
+          </ModalHeader>
+          <PanelLoadingIndicator
+            isLoading={picker.isLoadingModel || picker.isResolving}
+          />
+          <ModalBody>
+            <div className="flex flex-col gap-2">
+              <CubePickerStep
+                label="Model"
+                value={
+                  isFixed
+                    ? 'fixed'
+                    : picker.isPastingModel
+                      ? PASTE_MODEL_OPTION
+                      : picker.models.find(
+                          (model) => model.model === picker.model,
+                        )?.id
+                }
+                options={
+                  isFixed
+                    ? [{ value: 'fixed', label: fixedModelLabel }]
+                    : [
+                        ...picker.models.map((model) => ({
+                          value: model.id,
+                          label: model.label,
+                        })),
+                        {
+                          value: PASTE_MODEL_OPTION,
+                          label: 'Paste Pure model…',
+                        },
+                      ]
+                }
+                disabled={isFixed}
+                onChange={(id) => {
+                  if (id === PASTE_MODEL_OPTION) {
+                    picker.startPastingModel();
+                    return;
+                  }
+                  const model = picker.models.find(
+                    (candidate) => candidate.id === id,
+                  );
+                  if (model) {
+                    flowResult(picker.selectModel(model.model)).catch(
+                      applicationStore.alertUnhandledError,
+                    );
+                  }
+                }}
+              />
+              {picker.isPastingModel && !isFixed && (
+                <div className="flex flex-col gap-1">
+                  <textarea
+                    className="h-40 w-full resize-y rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] p-1 font-mono text-sm text-[var(--color-text-primary)]"
+                    aria-label="Pure model"
+                    placeholder={
+                      '###Relational\nDatabase my::Database ( … )\n\n###Runtime\nRuntime my::Runtime { … }'
+                    }
+                    spellCheck={false}
+                    value={picker.pastedModelText}
+                    onChange={(event) =>
+                      picker.setPastedModelText(event.target.value)
+                    }
+                  />
+                  <div className="flex items-center gap-2">
+                    <CubeButton
+                      disabled={
+                        !picker.pastedModelText.trim() || picker.isLoadingModel
+                      }
+                      onClick={() => {
+                        flowResult(picker.loadPastedModel()).catch(
+                          applicationStore.alertUnhandledError,
+                        );
+                      }}
+                    >
+                      Load model
+                    </CubeButton>
+                    <span className="text-sm text-[var(--color-text-muted)]">
+                      The cube keeps the model&apos;s text, which counts towards
+                      the 1 MiB a cube spec can hold.
+                    </span>
+                  </div>
+                </div>
+              )}
+              {picker.isLoadingModel && (
+                <div className="text-base text-[var(--color-text-secondary)]">
+                  {CUBE_PENDING_LABEL.LOADING_MODEL}
+                </div>
+              )}
+              <CubePickerStep
+                label="Database"
+                value={picker.databasePath}
+                options={picker.databases.map((database) => ({
+                  value: database.path,
+                  label: database.path,
+                }))}
+                disabled={picker.fixedDatabasePath !== undefined}
+                onChange={(path) => picker.selectDatabase(path)}
+              />
+              <CubePickerStep
+                label="Runtime"
+                value={picker.runtimePath}
+                options={picker.runtimes.map((runtime) => ({
+                  value: runtime.path,
+                  label: runtime.path,
+                }))}
+                disabled={picker.fixedContext?.runtime !== undefined}
+                onChange={(path) => picker.selectRuntime(path)}
+              />
+              <CubePickerStep
+                label="Schema"
+                value={picker.schemaName}
+                options={picker.schemas.map((schema) => ({
+                  value: schema.name,
+                  label: getRelationalDisplayName(schema.name),
+                }))}
+                onChange={(name) => picker.selectSchema(name)}
+              />
+              {picker.schemaName !== undefined && (
+                <div className="flex flex-col gap-1">
+                  <input
+                    className="h-7 rounded-sm border border-[var(--color-border-default)] bg-[var(--color-bg-input)] px-1 text-base text-[var(--color-text-primary)]"
+                    placeholder="Search tables"
+                    aria-label="Search tables"
+                    value={picker.tableSearch}
+                    onChange={(event) =>
+                      picker.setTableSearch(event.target.value)
+                    }
+                  />
+                  <ul
+                    className="h-56 overflow-auto rounded-sm border border-[var(--color-border-subtle)]"
+                    aria-label="Tables"
+                  >
+                    {picker.tables.map((table) => {
+                      const selectable = isTableSelectable(table);
+                      const isPicked = picker.tableName === table.name;
+                      return (
+                        <li key={table.name}>
+                          <button
+                            type="button"
+                            className={clsx(
+                              'flex w-full items-center gap-2 px-2 py-1 text-left text-base enabled:hover:bg-[var(--color-bg-hover)] disabled:cursor-not-allowed disabled:text-[var(--color-text-disabled)]',
+                              { 'bg-[var(--color-bg-selected)]': isPicked },
+                            )}
+                            aria-pressed={isPicked}
+                            disabled={!selectable}
+                            onClick={() => picker.selectTable(table.name)}
+                          >
+                            <span className="min-w-0 flex-1 truncate">
+                              {getRelationalDisplayName(table.name)}
+                            </span>
+                            {table.flags.map((flag) => (
+                              <span
+                                key={flag}
+                                className="rounded-sm bg-[var(--color-status-warn-bg)] px-1 text-sm text-[var(--color-status-warn)]"
+                                title={CUBE_TABLE_FLAG_LABELS[flag].description}
+                              >
+                                {CUBE_TABLE_FLAG_LABELS[flag].label}
+                              </span>
+                            ))}
+                            <span className="shrink-0 text-sm text-[var(--color-text-muted)]">
+                              {table.columnCount} columns
+                            </span>
+                          </button>
+                        </li>
+                      );
+                    })}
+                  </ul>
+                </div>
+              )}
+              {picker.isResolving && (
+                <div className="text-base text-[var(--color-text-secondary)]">
+                  {CUBE_PENDING_LABEL.RESOLVING_SOURCE}
+                </div>
+              )}
+              {picker.error !== undefined && (
+                <div
+                  className="text-base text-[var(--color-status-error)]"
+                  role="alert"
+                >
+                  {picker.error}
+                </div>
+              )}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              text="Add"
+              disabled={!picker.canConfirm}
+              onClick={confirm}
+            />
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text="Cancel"
+              onClick={() => picker.close()}
+            />
+          </ModalFooter>
+        </Modal>
+      </Dialog>
+    );
+  },
+);

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

@@ -0,0 +1,157 @@
+/**
+ * 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 type { CubeEditorState } from '../../stores/CubeEditorState.js';
+import { CUBE_SPEC_TRANSFER_MODE } from '../../stores/CubeSpecTransferState.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)]';
+
+/**
+ * Export and Import of the cube's saved spec, as text to copy, download,
+ * paste or read from a file (PLAN §10.3; developer tools until M8).
+ */
+export const CubeSpecTransferDialog = observer(
+  (props: { editorState: CubeEditorState }) => {
+    const { editorState } = props;
+    const transfer = editorState.specTransfer;
+    const { applicationStore } = editorState.host;
+    const darkMode =
+      !applicationStore.layoutService.TEMPORARY__isLightColorThemeEnabled;
+    const isExport = transfer.mode === CUBE_SPEC_TRANSFER_MODE.EXPORT;
+
+    return (
+      <Dialog
+        open={transfer.mode !== undefined}
+        onClose={() => transfer.close()}
+      >
+        <Modal darkMode={darkMode} className="w-[720px] max-w-full">
+          <ModalHeader>
+            <div className="modal__title">
+              {isExport ? 'Export spec (dev)' : 'Import spec (dev)'}
+            </div>
+          </ModalHeader>
+          <PanelLoadingIndicator isLoading={transfer.isReadingFile} />
+          <ModalBody>
+            <div className="flex flex-col gap-2">
+              {isExport ? (
+                transfer.exportText !== undefined && (
+                  <textarea
+                    className={TEXT_AREA_CLASS_NAME}
+                    aria-label="Cube spec"
+                    readOnly={true}
+                    value={transfer.exportText}
+                  />
+                )
+              ) : (
+                <>
+                  <div className="text-base text-[var(--color-text-secondary)]">
+                    Paste a cube spec, or choose a .cube.json file. The spec
+                    replaces this cube; Undo brings it back.
+                  </div>
+                  <input
+                    className="text-base"
+                    type="file"
+                    accept=".json,application/json"
+                    aria-label="Spec file"
+                    onChange={(event) => {
+                      const file = event.target.files?.[0];
+                      // the same file can be chosen again
+                      event.target.value = '';
+                      if (file) {
+                        flowResult(transfer.readImportFile(file)).catch(
+                          applicationStore.alertUnhandledError,
+                        );
+                      }
+                    }}
+                  />
+                  <textarea
+                    className={TEXT_AREA_CLASS_NAME}
+                    aria-label="Cube spec"
+                    placeholder="Cube spec"
+                    spellCheck={false}
+                    value={transfer.importText}
+                    onChange={(event) =>
+                      transfer.setImportText(event.target.value)
+                    }
+                  />
+                </>
+              )}
+              {transfer.error !== undefined && (
+                <div
+                  className="break-words text-base text-[var(--color-status-error)]"
+                  role="alert"
+                >
+                  {transfer.error}
+                </div>
+              )}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            {isExport ? (
+              <>
+                <ModalFooterButton
+                  darkMode={darkMode}
+                  formatText={false}
+                  text="Copy"
+                  disabled={transfer.exportText === undefined}
+                  onClick={() => {
+                    transfer
+                      .copyExport()
+                      .catch(applicationStore.alertUnhandledError);
+                  }}
+                />
+                <ModalFooterButton
+                  darkMode={darkMode}
+                  formatText={false}
+                  text="Download"
+                  disabled={transfer.exportText === undefined}
+                  onClick={() => transfer.downloadExport()}
+                />
+              </>
+            ) : (
+              <ModalFooterButton
+                darkMode={darkMode}
+                formatText={false}
+                text="Import"
+                disabled={!transfer.importText.trim() || transfer.isReadingFile}
+                onClick={() => transfer.importSpec()}
+              />
+            )}
+            <ModalFooterButton
+              darkMode={darkMode}
+              formatText={false}
+              type="secondary"
+              text={isExport ? 'Close' : 'Cancel'}
+              onClick={() => transfer.close()}
+            />
+          </ModalFooter>
+        </Modal>
+      </Dialog>
+    );
+  },
+);

package/src/graph-manager/CubeEngine.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { IR, ModelContext, Schema } from '@finos/legend-cube';
+
+// The engine port (PLAN §8.7): what Cube asks of an engine, in Cube's own
+// terms. Only its Legend implementation, under `protocol/pure/v1/`, knows the
+// protocol; nothing here names a V1_* type
+
+/** A query node's id */
+export type NodeId = string;
+
+/** A table's Database element path, schema name and table name, names as stored (quotes included) */
+export type AccessorPath = readonly [
+  database: string,
+  schema: string,
+  table: string,
+];
+
+/** Why a table can't be picked as it is, read from its definition (PLAN §6.2.6) */
+export enum CubeTableFlag {
+  /** a binary column: the engine can't type the table */
+  UNAVAILABLE = 'unavailable',
+  /** a CHAR(n) column: typed with a length of 1 */
+  LENGTH_UNKNOWN = 'lengthUnknown',
+  /** an OTHER or ARRAY column: typed as a bare String */
+  TYPE_UNKNOWN = 'typeUnknown',
+}
+
+export interface CubeOutlineTable {
+  /** As stored, quotes included */
+  readonly name: string;
+  /** Views are typed as text of length 0, so the picker hides them in v1 */
+  readonly isView: boolean;
+  readonly columnCount: number;
+  readonly flags: readonly CubeTableFlag[];
+  /**
+   * The columns typed as a bare String because Cube can't read their type
+   * (OTHER or ARRAY), unquoted as in the table's schema
+   */
+  readonly untypedColumns: readonly string[];
+}
+
+export interface CubeOutlineSchema {
+  readonly name: string;
+  readonly tables: readonly CubeOutlineTable[];
+}
+
+export interface CubeOutlineDatabase {
+  readonly path: string;
+  readonly schemas: readonly CubeOutlineSchema[];
+}
+
+export interface CubeOutlineRuntime {
+  readonly path: string;
+  /** The stores its connections are keyed by, exactly; includes are not followed (PLAN §6.2.5) */
+  readonly storePaths: readonly string[];
+}
+
+/** What a model offers the source picker: its databases and runtimes, as plain data */
+export interface CubeModelOutline {
+  readonly databases: readonly CubeOutlineDatabase[];
+  readonly runtimes: readonly CubeOutlineRuntime[];
+}
+
+export enum CubeEngineErrorKind {
+  /** the model or a lambda doesn't compile, or a table can't be typed */
+  COMPILE = 'compile',
+  /** the query failed while running, or its result can't be read */
+  EXECUTION = 'execution',
+  /** the cube's model is of a kind this version can't run */
+  UNSUPPORTED_MODEL = 'unsupportedModel',
+  /** the engine couldn't be reached, or answered with no readable error */
+  NETWORK = 'network',
+}
+
+/**
+ * An engine failure, placed on the node it concerns: the node a stamp in the
+ * error points to, else the source being typed or the node being run.
+ */
+export class CubeEngineError extends Error {
+  readonly kind: CubeEngineErrorKind;
+  readonly nodeId: NodeId | undefined;
+  /** The part of the node the error points to (an `EmitRole`), when it is located */
+  readonly role: string | undefined;
+  /** The first line of the engine's message, shown on the node */
+  readonly firstLine: string;
+  /** The engine's whole message, without its Java trace, shown in the panel */
+  readonly detail: string;
+
+  constructor(
+    kind: CubeEngineErrorKind,
+    detail: string,
+    nodeId?: NodeId,
+    role?: string,
+  ) {
+    const firstLine = detail.split('\n', 1)[0]?.trim() ?? '';
+    super(firstLine);
+    this.name = 'CubeEngineError';
+    this.kind = kind;
+    this.detail = detail;
+    this.firstLine = firstLine;
+    this.nodeId = nodeId;
+    this.role = role;
+  }
+}
+
+/** A value of a result cell: Integer and Decimal values as their exact text, Float values as numbers (PLAN §8.7) */
+export type CubeResultValue = string | number | boolean | null;
+
+export interface CubeResult {
+  /** Column names, in order; rows match them by position */
+  readonly columns: readonly string[];
+  /** As many rows as the engine sent, up to the row limit + 1 */
+  readonly rows: readonly (readonly CubeResultValue[])[];
+  /** The SQL statements the engine ran */
+  readonly sql: readonly string[];
+  readonly durationMs: number;
+}
+
+export interface CubeEngine {
+  /** The databases and runtimes of a model, parsed once */
+  loadModel(model: ModelContext): Promise<CubeModelOutline>;
+  /** The schema of each table, in one engine call: one entry per key, failures included */
+  resolveSchemas(
+    model: ModelContext,
+    accessors: ReadonlyMap<NodeId, AccessorPath>,
+  ): Promise<Map<NodeId, Schema | CubeEngineError>>;
+  /** The schema of each lambda, in one engine call: one entry per key, failures included */
+  typeLambdas(
+    model: ModelContext,
+    lambdas: ReadonlyMap<NodeId, IR>,
+  ): Promise<Map<NodeId, Schema | CubeEngineError>>;
+  /** Runs an execution lambda; rejects with a `CubeEngineError` */
+  execute(
+    model: ModelContext,
+    lambda: IR,
+    options?: { abortController?: AbortController | undefined },
+  ): Promise<CubeResult>;
+  /** The Pure text of a lambda, for display only: never parsed back */
+  renderPure(lambda: IR): Promise<string>;
+}

package/src/graph-manager/CubeModelOutlineHelper.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { CubeModelOutline, CubeOutlineRuntime } from './CubeEngine.js';
+
+/**
+ * The runtimes a query on the database can run with: those with a connection
+ * keyed by exactly that database. The engine matches stores by exact element
+ * and silently falls back to the first connection otherwise, so a runtime
+ * that only reaches the database through an include is not offered (PLAN
+ * §6.2.5).
+ */
+export const getRuntimesForDatabase = (
+  outline: CubeModelOutline,
+  databasePath: string,
+): CubeOutlineRuntime[] =>
+  outline.runtimes.filter((runtime) =>
+    runtime.storePaths.includes(databasePath),
+  );

package/src/graph-manager/protocol/pure/CubeEngineBuilder.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { TracerService } from '@finos/legend-shared';
+import type { CubeEngine } from '../../CubeEngine.js';
+import {
+  type V1_CubeEngineConfig,
+  V1_LegendCubeEngine,
+} from './v1/V1_LegendCubeEngine.js';
+
+/** The engine client's configuration, as the host gives it (e.g. Legend Query's engine server URL) */
+export type CubeEngineConfig = V1_CubeEngineConfig;
+
+/**
+ * The Cube engine of a host (PLAN §3.2): the only place that builds the
+ * Legend implementation, so hosts never name a V1_* symbol
+ */
+export const buildCubeEngine = (
+  config: CubeEngineConfig,
+  tracerService: TracerService,
+): CubeEngine => new V1_LegendCubeEngine(config, tracerService);