@finos/legend-cube-builder 0.0.2 → 0.0.4

package/src/stores/CubeExtendTyping.ts

@@ -0,0 +1,291 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  buildSchemasAndValidity,
+  colSpec,
+  colSpecArray,
+  EmitRole,
+  ERR_TYPING,
+  Extend,
+  type ExtendTyping,
+  func,
+  getExtendSignature,
+  hashText,
+  type IR,
+  isTypingError,
+  type JsonObject,
+  lambda,
+  lambdaJson,
+  type ModelContext,
+  type NodeRegistry,
+  originOf,
+  printIR,
+  type Query,
+  QueryEmitter,
+  type QueryRule,
+  type Schema,
+  stableJsonText,
+} from '@finos/legend-cube';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+
+// Typing an Extend's columns with the engine (PLAN §11.7): its input's
+// relation, as Cube types any node, then one extend per column. The whole
+// chain gives every type; each shorter chain, typed with it, tells which
+// column the engine fails on, since a stored lambda has no locations.
+
+/** An engine message without the compiler's ` - Context:[…]` trail, which repeats what it was doing */
+export const withoutEngineContext = (message: string): string =>
+  message.replace(/ - Context:\[[^\n]*/gu, '');
+
+/** A column to type: its name, and its lambda, located in its text or not */
+export interface CubeExtendTypingColumn {
+  readonly name: string;
+  readonly lambda: JsonObject;
+}
+
+/** The key of the lambda that types the first `count` columns */
+const keyOf = (extendId: string, count: number): NodeId =>
+  `${extendId}#${count}`;
+
+/**
+ * The lambdas that type an Extend's columns, by key: the input's relation
+ * then the first k columns, for every k. A located lambda keeps its
+ * locations, so an error points into its text; a stored one is marked with
+ * the Extend, so an error lands on it. The input must be valid.
+ */
+export const buildCubeExtendTypingLambdas = (
+  query: Query,
+  extend: Extend,
+  columns: readonly CubeExtendTypingColumn[],
+  registry: NodeRegistry,
+  located: boolean,
+): Map<NodeId, IR> => {
+  const [inputId] = query.getInputIds(extend.id);
+  if (inputId === undefined) {
+    throw new Error(`Extend "${extend.id}" has no input to type it on`);
+  }
+  const input = new QueryEmitter(query, registry).emitRelation(inputId);
+  const lambdas = new Map<NodeId, IR>();
+  columns.reduce<IR>((relation, column, index) => {
+    const extended = func('extend', [
+      relation,
+      colSpecArray([
+        colSpec(
+          column.name,
+          lambdaJson(
+            column.lambda,
+            located ? undefined : originOf(extend.id, EmitRole.EXPRESSION),
+          ),
+        ),
+      ]),
+    ]);
+    lambdas.set(keyOf(extend.id, index + 1), lambda([], [extended]));
+    return extended;
+  }, input);
+  return lambdas;
+};
+
+/** Each model's digest, by the object, so a large model is digested once */
+const MODEL_DIGESTS = new WeakMap<ModelContext, string>();
+
+const digestModel = (model: ModelContext): string => {
+  let digest = MODEL_DIGESTS.get(model);
+  if (digest === undefined) {
+    digest = hashText(stableJsonText(model));
+    MODEL_DIGESTS.set(model, digest);
+  }
+  return digest;
+};
+
+/**
+ * What the engine is given for an Extend's input when it types it, digested
+ * (PLAN §11.7): the input's relation as emitted, and the model. A typing
+ * records it (`upstream`), since the engine sees more than Cube's schema
+ * does; `undefined` when the input can't be emitted, e.g. it is invalid.
+ */
+export const getCubeExtendUpstream = (
+  emitter: QueryEmitter,
+  extendId: string,
+  model: ModelContext,
+): string | undefined => {
+  const [inputId] = emitter.query.getInputIds(extendId);
+  if (inputId === undefined || !emitter.canEmit(inputId)) {
+    return undefined;
+  }
+  return hashText(
+    `${digestModel(model)}\n${printIR(emitter.emitRelation(inputId))}`,
+  );
+};
+
+/** The digest of what the engine was given for the input, which the typing recorded */
+export const getCubeExtendTypingUpstream = (
+  typing: ExtendTyping,
+): string | undefined =>
+  typing.kind === 'unresolved' ? undefined : typing.upstream;
+
+const upstreamOf = getCubeExtendTypingUpstream;
+
+/**
+ * Whether the Extend's typing gives its types for this input: typed, for
+ * this schema and these columns, and for this input as the engine is given
+ * it, or recorded without it, as when loaded
+ */
+export const isCubeExtendTypingCurrent = (
+  extend: Extend,
+  input: Schema,
+  upstream: string | undefined,
+): boolean => {
+  const { typing } = extend;
+  const recorded = upstreamOf(typing);
+  return (
+    typing.kind === 'typed' &&
+    extend.currentTyping(input) === typing &&
+    (recorded === undefined || recorded === upstream)
+  );
+};
+
+/**
+ * A query rule for the editor (PLAN §11.7): an Extend whose typing recorded
+ * another input than the engine would be given now waits to be typed again
+ * (`ERR_TYPING`), e.g. after an Extend above it gains `->toOne()`, which
+ * Cube's schema doesn't show. A typing that recorded nothing, as one loaded,
+ * is used as it is; an Extend that already waits, or whose input is invalid,
+ * is left to its own checks.
+ */
+export const createStaleCubeExtendTypingRule =
+  (
+    registry: NodeRegistry,
+    modelOf: () => ModelContext | undefined,
+  ): QueryRule =>
+  (query) => {
+    const stale = new Map<string, readonly string[]>();
+    const model = modelOf();
+    const recorded = query.nodes.filter(
+      (node): node is Extend =>
+        node instanceof Extend && upstreamOf(node.typing) !== undefined,
+    );
+    if (!model || !recorded.length) {
+      return stale;
+    }
+    const { validity } = buildSchemasAndValidity(query, registry.queryRules);
+    const emitter = new QueryEmitter(query, registry);
+    recorded.forEach((node) => {
+      if ((validity.get(node.id) ?? []).some(isTypingError)) {
+        return;
+      }
+      const upstream = getCubeExtendUpstream(emitter, node.id, model);
+      if (upstream !== undefined && upstream !== upstreamOf(node.typing)) {
+        stale.set(node.id, [ERR_TYPING]);
+      }
+    });
+    return stale;
+  };
+
+/** What typing an Extend gave: the typing to store, and the error the engine gave, if it failed */
+export interface CubeExtendTypingResult {
+  readonly typing: ExtendTyping;
+  readonly error?: CubeEngineError | undefined;
+}
+
+/**
+ * The typing the engine's answers give, for this input and these columns:
+ * every column's type, from the whole chain, else the first column whose
+ * chain fails, with the engine's error (a network failure on none)
+ */
+export const readCubeExtendTyping = (
+  answers: ReadonlyMap<NodeId, Schema | CubeEngineError>,
+  extend: Extend,
+  input: Schema,
+  columns: readonly CubeExtendTypingColumn[],
+  upstream: string | undefined,
+): CubeExtendTypingResult => {
+  const signature = getExtendSignature(input, extend.columns);
+  const whole = answers.get(keyOf(extend.id, columns.length));
+  if (whole !== undefined && !(whole instanceof CubeEngineError)) {
+    return {
+      typing: {
+        kind: 'typed',
+        signature,
+        types: whole.columns
+          .slice(-columns.length)
+          .map((column) => column.type),
+        upstream,
+      },
+    };
+  }
+  const failing = columns.findIndex(
+    (_, index) =>
+      answers.get(keyOf(extend.id, index + 1)) instanceof CubeEngineError,
+  );
+  const error =
+    (answers.get(keyOf(extend.id, failing + 1)) as
+      | CubeEngineError
+      | undefined) ??
+    new CubeEngineError(
+      CubeEngineErrorKind.NETWORK,
+      'The engine gave no type for these columns',
+      extend.id,
+    );
+  return {
+    typing: {
+      kind: 'failed',
+      signature,
+      message: withoutEngineContext(error.detail),
+      column:
+        failing < 0 || error.kind === CubeEngineErrorKind.NETWORK
+          ? undefined
+          : failing,
+      upstream,
+    },
+    error,
+  };
+};
+
+/**
+ * Whether two typings say the same: the same kind, signature and input as
+ * the engine was given it, and the same types, or the same failure
+ */
+export const isSameCubeExtendTyping = (
+  a: ExtendTyping,
+  b: ExtendTyping,
+): boolean => {
+  if (upstreamOf(a) !== upstreamOf(b)) {
+    return false;
+  }
+  if (a.kind === 'typed' && b.kind === 'typed') {
+    return (
+      a.signature === b.signature &&
+      a.types.length === b.types.length &&
+      a.types.every((type, index) => {
+        const other = b.types[index];
+        return other !== undefined && type.equals(other);
+      })
+    );
+  }
+  if (a.kind === 'failed' && b.kind === 'failed') {
+    return (
+      a.signature === b.signature &&
+      a.message === b.message &&
+      a.column === b.column
+    );
+  }
+  return a.kind === 'unresolved' && b.kind === 'unresolved';
+};

package/src/stores/CubeGridQuickActions.ts

@@ -0,0 +1,184 @@
+/**
+ * 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 {
+  AggregationFunction,
+  buildQuickFilterRule,
+  FilterOperator,
+  Filter,
+  foldColumnName,
+  getAggregationAutoName,
+  Group,
+  isOperatorAvailable,
+  isSortableType,
+  type Schema,
+  Sort,
+  TypeFamily,
+} from '@finos/legend-cube';
+import {
+  CUBE_QUICK_ACTION_DISABLED_REASON,
+  FILTER_FLOAT_COMPARISON_HINT,
+  READ_ONLY_CUBE_TITLE,
+} from '../__lib__/LegendCubeLabels.js';
+import type { CubeResultValue } from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/**
+ * The name of a Group by's Count rows: `Count Rows`, or with a number after it
+ * when an input column already has that name in any case, e.g. on a Group of
+ * a Group (PLAN §11.5)
+ */
+export const getGroupByCountName = (schema: Schema): string => {
+  const base = getAggregationAutoName(
+    AggregationFunction.COUNT_ROWS,
+    undefined,
+  ) as string;
+  const taken = new Set(schema.names().map(foldColumnName));
+  let name = base;
+  for (let suffix = 2; taken.has(foldColumnName(name)); suffix += 1) {
+    name = `${base} ${suffix}`;
+  }
+  return name;
+};
+
+/** One of the grid's quick actions on a cell (spec §12.4) */
+export interface CubeGridQuickAction {
+  /** e.g. `Sort by "SHIP_COUNTRY"` */
+  readonly label: string;
+  /** Why it can't be used, its tooltip then; `undefined` when it can */
+  readonly disabledReason: string | undefined;
+  /** A note shown as its tooltip when it can be used, e.g. on comparing floats */
+  readonly hint: string | undefined;
+  /** Adds its node after the node that runs, as one undo step; nothing runs */
+  readonly apply: () => void;
+}
+
+/**
+ * The quick actions on a cell of the shown rows (spec §12.4, PLAN §11.4 and
+ * §11.5): "Sort by" adds an ascending Sort on the cell's column, "Group by" a
+ * Group by it with Count rows, and "Filter by" an Equal on its value (Is
+ * Empty on a null), after the node that runs, which they replace as the node
+ * that runs. All need the rows to be from the current query, no run in
+ * flight, and a cube that can change; "Sort by" and "Group by" a type that
+ * compares, and "Filter by" a value its column's type can compare.
+ * Read when the menu opens; `[]` when the position is not a column of the
+ * shown rows.
+ */
+export const getCubeGridQuickActions = (
+  editorState: CubeEditorState,
+  position: number,
+  cell: CubeResultValue,
+): CubeGridQuickAction[] => {
+  const { execution, document } = editorState;
+  const { result } = execution;
+  const column = result?.schema.columns[position];
+  if (!result || !column) {
+    return [];
+  }
+  const { query } = document;
+  const afterId = query.selected;
+  const typeName = column.type.displayName;
+  const rule = buildQuickFilterRule(column.name, column.type, cell);
+  // what keeps both from being used, in order
+  const blocked =
+    result.query !== query || execution.isStale
+      ? CUBE_QUICK_ACTION_DISABLED_REASON.STALE_ROWS
+      : // choosing would apply the edits first, leaving these rows stale
+        editorState.hasEditsToApply || editorState.nodeEditor.hasPendingInput()
+        ? CUBE_QUICK_ACTION_DISABLED_REASON.EDITING
+        : execution.isRunning
+          ? CUBE_QUICK_ACTION_DISABLED_REASON.RUNNING
+          : editorState.readOnly
+            ? READ_ONLY_CUBE_TITLE
+            : undefined;
+  const sortReason =
+    blocked ??
+    (isSortableType(column.type)
+      ? undefined
+      : CUBE_QUICK_ACTION_DISABLED_REASON.notSortable(typeName));
+  const groupReason =
+    blocked ??
+    (isSortableType(column.type)
+      ? undefined
+      : CUBE_QUICK_ACTION_DISABLED_REASON.notGroupable(typeName));
+  const filterReason =
+    blocked ??
+    (rule
+      ? undefined
+      : isOperatorAvailable(FilterOperator.EQUAL, column.type)
+        ? CUBE_QUICK_ACTION_DISABLED_REASON.UNREADABLE_VALUE
+        : CUBE_QUICK_ACTION_DISABLED_REASON.notComparable(typeName));
+  return [
+    {
+      label: `Sort by "${column.name}"`,
+      disabledReason: sortReason,
+      hint: undefined,
+      apply: () => {
+        // as the menu found it: nothing changed since it opened
+        if (sortReason === undefined && editorState.document === document) {
+          editorState.addConfiguredNode(
+            Sort.byColumn(query.generateId(Sort.TYPE), column.name),
+            afterId,
+          );
+        }
+      },
+    },
+    {
+      label: `Group by "${column.name}"`,
+      disabledReason: groupReason,
+      hint: undefined,
+      apply: () => {
+        if (groupReason === undefined && editorState.document === document) {
+          editorState.addConfiguredNode(
+            new Group(
+              query.generateId(Group.TYPE),
+              [column.name],
+              [
+                {
+                  column: undefined,
+                  function: AggregationFunction.COUNT_ROWS,
+                  name: getGroupByCountName(result.schema),
+                },
+              ],
+            ),
+            afterId,
+          );
+        }
+      },
+    },
+    {
+      label: `Filter by "${column.name}"`,
+      disabledReason: filterReason,
+      hint:
+        rule?.operator === FilterOperator.EQUAL &&
+        column.type.family === TypeFamily.FLOAT
+          ? FILTER_FLOAT_COMPARISON_HINT
+          : undefined,
+      apply: () => {
+        if (
+          filterReason === undefined &&
+          rule &&
+          editorState.document === document
+        ) {
+          editorState.addConfiguredNode(
+            new Filter(query.generateId(Filter.TYPE), rule),
+            afterId,
+          );
+        }
+      },
+    },
+  ];
+};

package/src/stores/CubeHost.ts

@@ -15,7 +15,22 @@
  */
 
 import type { GenericLegendApplicationStore } from '@finos/legend-application';
-import type { CubeEngine } from '../graph-manager/CubeEngine.js';
+import type { ModelContext } from '@finos/legend-cube';
+import type { CubeConnectionExplorer } from '../graph-manager/CubeConnectionExplorer.js';
+import type { CubeDataProductCatalog } from '../graph-manager/CubeDataProductCatalog.js';
+import type { CubeIngestCatalog } from '../graph-manager/CubeIngestCatalog.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeEngine,
+  type CubeModelOutline,
+} from '../graph-manager/CubeEngine.js';
+import {
+  checkCubeProjectModel,
+  getCubeProjectCoordinates,
+  isCubeProjectModel,
+} from '../graph-manager/CubeProject.js';
+import type { CubeProjectCatalog } from '../graph-manager/CubeProjectCatalog.js';
 import type { LocalModelCatalog } from './LocalModelCatalog.js';
 
 /**
@@ -29,4 +44,59 @@ export interface CubeHost {
   readonly applicationStore: GenericLegendApplicationStore;
   readonly engine: CubeEngine;
   readonly modelCatalog: LocalModelCatalog;
+  /**
+   * Reads the databases behind direct connections (PLAN §6.8); without one,
+   * the source picker offers no database connection
+   */
+  readonly connectionExplorer?: CubeConnectionExplorer | undefined;
+  /**
+   * The deployed data products (PLAN §6.8); without one, the source dialog
+   * offers no data products
+   */
+  readonly dataProductCatalog?: CubeDataProductCatalog | undefined;
+  /**
+   * The deployed ingest definitions (PLAN §6.7); without one, the source
+   * dialog offers no ingest data sets
+   */
+  readonly ingestCatalog?: CubeIngestCatalog | undefined;
+  /**
+   * The published projects in the host's depot (PLAN §6.3); without one, the
+   * source dialog offers no projects
+   */
+  readonly projectCatalog?: CubeProjectCatalog | undefined;
 }
+
+/** Why the host can't list a project model's Databases */
+const NO_PROJECT_CATALOG =
+  "This page can't read published projects: its host has no depot";
+
+/**
+ * A model's databases and runtimes, wherever its kind keeps them: a
+ * project's in the host's depot (PLAN §6.3), any other through the model
+ * catalog's engine
+ */
+export const loadCubeModelOutline = (
+  host: CubeHost,
+  model: ModelContext,
+): Promise<CubeModelOutline> => {
+  if (!isCubeProjectModel(model)) {
+    return host.modelCatalog.loadOutline(model);
+  }
+  const project = getCubeProjectCoordinates(model);
+  if (!project) {
+    return Promise.reject(
+      new CubeEngineError(
+        CubeEngineErrorKind.UNSUPPORTED_MODEL,
+        checkCubeProjectModel(model).join('\n'),
+      ),
+    );
+  }
+  return host.projectCatalog
+    ? host.projectCatalog.loadOutline(project)
+    : Promise.reject(
+        new CubeEngineError(
+          CubeEngineErrorKind.UNSUPPORTED_MODEL,
+          NO_PROJECT_CATALOG,
+        ),
+      );
+};

package/src/stores/CubeIngestRecheck.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 {
+  IngestDatasetSource,
+  ModelContext,
+  Schema,
+} from '@finos/legend-cube';
+import { CUBE_INGEST_RECHECK_MESSAGE } from '../__lib__/LegendCubeIngestLabels.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+import {
+  checkCubeIngestModel,
+  getCubeIngestSettings,
+} from '../graph-manager/CubeIngest.js';
+import type { CubeIngestCatalog } from '../graph-manager/CubeIngestCatalog.js';
+
+/**
+ * Reads an ingest cube's data sets again (PLAN §6.7): their columns as their
+ * deployed definitions declare them, through the catalog, with no engine
+ * call; `fresh` reads the definitions again rather than what this page visit
+ * read. One answer per source, failures included; never rejects.
+ */
+export const recheckCubeIngestSources = async (
+  catalog: CubeIngestCatalog | undefined,
+  model: ModelContext,
+  sources: readonly IngestDatasetSource[],
+  fresh = false,
+): Promise<Map<NodeId, Schema | CubeEngineError>> => {
+  const failAll = (
+    kind: CubeEngineErrorKind,
+    detail: string,
+  ): Map<NodeId, Schema | CubeEngineError> =>
+    new Map(
+      sources.map((source) => [
+        source.id,
+        new CubeEngineError(kind, detail, source.id),
+      ]),
+    );
+  if (!catalog) {
+    return failAll(
+      CubeEngineErrorKind.UNSUPPORTED_MODEL,
+      CUBE_INGEST_RECHECK_MESSAGE.NO_CATALOG,
+    );
+  }
+  const settings = getCubeIngestSettings(model);
+  if (!settings) {
+    return failAll(
+      CubeEngineErrorKind.UNSUPPORTED_MODEL,
+      checkCubeIngestModel(model).join('\n'),
+    );
+  }
+  try {
+    return await catalog.resolveSchemas(
+      settings.environmentType,
+      new Map(
+        sources.map((source) => [
+          source.id,
+          {
+            ingestDefinitionUrn: source.ingestDefinitionUrn,
+            ingestDefinition: source.ingestDefinition,
+            dataSet: source.dataSet,
+          },
+        ]),
+      ),
+      { fresh },
+    );
+  } catch (error) {
+    return error instanceof CubeEngineError
+      ? failAll(error.kind, error.detail)
+      : failAll(
+          CubeEngineErrorKind.NETWORK,
+          error instanceof Error ? error.message : String(error),
+        );
+  }
+};