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

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,169 @@
+/**
+ * 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[];
+}
+
+/** A relational connection of a runtime, for the operations some databases take another way (PLAN §11.4) */
+export interface CubeOutlineConnection {
+  /** The store it is keyed by */
+  readonly storePath: string;
+  /** The engine's name for its database type, e.g. `H2` or `SqlServer` */
+  readonly databaseType: string;
+}
+
+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[];
+  /**
+   * Its relational connections that name a database type, a list rather
+   * than a record keyed by a store path from the model; optional, as an
+   * outline from before M2 has none
+   */
+  readonly connections?: readonly CubeOutlineConnection[];
+}
+
+/** 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,58 @@
+/**
+ * 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),
+  );
+
+/**
+ * The database type a query on these databases runs on with the runtime, for
+ * the operations some databases take another way (PLAN §11.4): the type of
+ * the runtime's connections to them. None when the runtime isn't in the
+ * outline, a database has no typed connection, or the databases' types
+ * differ: the native forms are written then.
+ */
+export const getDatabaseType = (
+  outline: CubeModelOutline,
+  runtimePath: string,
+  databasePaths: readonly string[],
+): string | undefined => {
+  const runtime = outline.runtimes.find(({ path }) => path === runtimePath);
+  const types = new Set<string>();
+  for (const databasePath of new Set(databasePaths)) {
+    const databaseTypes = (runtime?.connections ?? [])
+      .filter(({ storePath }) => storePath === databasePath)
+      .map(({ databaseType }) => databaseType);
+    if (!databaseTypes.length) {
+      return undefined;
+    }
+    databaseTypes.forEach((databaseType) => types.add(databaseType));
+  }
+  return types.size === 1 ? [...types][0] : undefined;
+};

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);

package/src/graph-manager/protocol/pure/v1/V1_CubeEngineErrors.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { NetworkClientError, type PlainObject } from '@finos/legend-shared';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../../../CubeEngine.js';
+import { V1_parseCubeSourceId } from './V1_CubeLambdaSerializer.js';
+
+// Engine errors → `CubeEngineError`s on canvas nodes (PLAN §8.7). A compile
+// error echoes the stamp of the innermost failing protocol node, so it goes on
+// that node; plan-time, database and network errors carry no stamp, so they
+// go on the node being typed or run.
+
+const COMPILATION_ERROR_TYPES = new Set(['COMPILATION', 'PARSER']);
+
+/** The engine's error payload: `{message, errorType?, sourceInformation?, trace?}` */
+const readPayload = (
+  payload: unknown,
+): { message: string; errorType?: string; sourceId?: string } | undefined => {
+  if (!payload || typeof payload !== 'object') {
+    return undefined;
+  }
+  const { message, errorType, sourceInformation } = payload as PlainObject;
+  if (typeof message !== 'string' || !message.trim()) {
+    return undefined;
+  }
+  const sourceId =
+    sourceInformation && typeof sourceInformation === 'object'
+      ? (sourceInformation as PlainObject).sourceId
+      : undefined;
+  return {
+    message,
+    ...(typeof errorType === 'string' ? { errorType } : {}),
+    ...(typeof sourceId === 'string' ? { sourceId } : {}),
+  };
+};
+
+/**
+ * The error of an engine payload (a failed call's, or a batch key's), placed
+ * on the stamped node, or else on the fallback node. Its Java trace is dropped.
+ */
+export const V1_buildCubeEngineError = (
+  payload: unknown,
+  fallbackNodeId: NodeId | undefined,
+  kind: CubeEngineErrorKind,
+): CubeEngineError | undefined => {
+  const read = readPayload(payload);
+  if (!read) {
+    return undefined;
+  }
+  const origin = V1_parseCubeSourceId(read.sourceId);
+  return new CubeEngineError(
+    read.errorType && COMPILATION_ERROR_TYPES.has(read.errorType)
+      ? CubeEngineErrorKind.COMPILE
+      : kind,
+    read.message,
+    origin?.nodeId ?? fallbackNodeId,
+    origin?.role,
+  );
+};
+
+/**
+ * The error of a failed engine call: the engine's own message when it sent
+ * one, else a network error
+ */
+export const V1_toCubeEngineError = (
+  error: unknown,
+  fallbackNodeId: NodeId | undefined,
+  kind: CubeEngineErrorKind,
+): CubeEngineError => {
+  if (error instanceof CubeEngineError) {
+    return error.nodeId !== undefined || fallbackNodeId === undefined
+      ? error
+      : new CubeEngineError(error.kind, error.detail, fallbackNodeId);
+  }
+  if (error instanceof NetworkClientError) {
+    const fromPayload = V1_buildCubeEngineError(
+      error.payload,
+      fallbackNodeId,
+      kind,
+    );
+    if (fromPayload) {
+      return fromPayload;
+    }
+  }
+  return new CubeEngineError(
+    CubeEngineErrorKind.NETWORK,
+    error instanceof Error && error.message
+      ? error.message
+      : `The engine couldn't be reached`,
+    fallbackNodeId,
+  );
+};

package/src/graph-manager/protocol/pure/v1/V1_CubeExecutionResultReader.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { resolveCubeType, TypeFamily } from '@finos/legend-cube';
+import { parseLosslessJSON, type PlainObject } from '@finos/legend-shared';
+import type { CubeResultValue } from '../../../CubeEngine.js';
+
+// An execution response (DEFAULT format, relation result) read losslessly
+// (PLAN §8.7). Each column's values keep one JS type, decided by the type the
+// result builder gives it: Float values are numbers; any other number, an
+// Integer or Decimal value above all, is its exact text ("9007199254740993",
+// "12.30"). Nothing is inferred from the kind of JSON token, since a Float
+// column may hold 5124 and a String column 32.38.
+
+const RELATIONAL_ACTIVITY_TYPE = 'relational';
+
+export interface V1_CubeExecutionResult {
+  readonly columns: readonly string[];
+  readonly rows: readonly (readonly CubeResultValue[])[];
+  readonly sql: readonly string[];
+}
+
+/** Thrown when the body can't be read, e.g. a stack trace streamed into a 200 */
+export class V1_CubeUnreadableResultError extends Error {}
+
+const isLosslessNumber = (
+  value: unknown,
+): value is { isLosslessNumber: true; value: string } =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { isLosslessNumber?: unknown }).isLosslessNumber === true;
+
+const asObject = (value: unknown): PlainObject =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as PlainObject)
+    : {};
+
+const readCell = (value: unknown, asNumber: boolean): CubeResultValue => {
+  if (isLosslessNumber(value)) {
+    return asNumber ? Number(value.value) : value.value;
+  }
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  throw new V1_CubeUnreadableResultError(
+    `A result value is not a scalar: ${JSON.stringify(value)}`,
+  );
+};
+
+/** The columns, rows and SQL of an execution response's text */
+export const V1_readCubeExecutionResult = (
+  text: string,
+): V1_CubeExecutionResult => {
+  let json: PlainObject;
+  try {
+    json = asObject(parseLosslessJSON(text));
+  } catch (error) {
+    throw new V1_CubeUnreadableResultError(
+      `The engine's response can't be read: ${(error as Error).message}`,
+    );
+  }
+  const result = asObject(json.result);
+  if (!Array.isArray(result.columns) || !Array.isArray(result.rows)) {
+    throw new V1_CubeUnreadableResultError(
+      `The engine's response has no relation result`,
+    );
+  }
+  const columns = result.columns.map((name) => String(name));
+  const builderTypes = new Map(
+    (Array.isArray(asObject(json.builder).columns)
+      ? (asObject(json.builder).columns as unknown[])
+      : []
+    ).map((column) => [
+      String(asObject(column).name),
+      String(asObject(column).type ?? ''),
+    ]),
+  );
+  const asNumber = columns.map((name) => {
+    const type = builderTypes.get(name);
+    return type ? resolveCubeType(type).family === TypeFamily.FLOAT : false;
+  });
+  const rows = result.rows.map((row) => {
+    const values = asObject(row).values;
+    if (!Array.isArray(values) || values.length !== columns.length) {
+      throw new V1_CubeUnreadableResultError(
+        `A result row doesn't have one value per column`,
+      );
+    }
+    return values.map((value, index) =>
+      readCell(value, asNumber[index] ?? false),
+    );
+  });
+  const sql = (Array.isArray(json.activities) ? json.activities : [])
+    .map(asObject)
+    .filter((activity) => activity._type === RELATIONAL_ACTIVITY_TYPE)
+    .map((activity) => String(activity.sql));
+  return { columns, rows, sql };
+};