@finos/legend-cube-builder 0.0.4 → 0.0.6

package/src/stores/CubeRunningStepLambda.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { lambda, needsDatabaseType } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import { flowResult } from 'mobx';
+import { formatDisabledReasons } from '../__lib__/LegendCubeLabels.js';
+import { serializeCubeLambdaForHost } from '../graph-manager/protocol/pure/CubeEngineBuilder.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+
+/**
+ * The query of the step that runs, as a lambda for a host to keep, e.g. as
+ * a materialized view of a Studio ingest definition: written for the
+ * database it runs on, as Execute writes it, but with no runtime and no row
+ * limit, which whoever runs it adds. Fails when Execute can't run.
+ */
+export const buildCubeRunningStepLambda = async (
+  editorState: CubeEditorState,
+): Promise<PlainObject> => {
+  const { execution, document, emitter } = editorState;
+  const { query, context } = document;
+  const captureId = query.selected;
+  const runtime = context?.runtime;
+  const model = context?.model;
+  if (
+    !execution.canExecute ||
+    captureId === undefined ||
+    runtime === undefined ||
+    model === undefined
+  ) {
+    throw new Error(formatDisabledReasons(execution.disabledReasons));
+  }
+  let databaseType: string | undefined;
+  if (needsDatabaseType(query, captureId)) {
+    await flowResult(editorState.loadModelOutline(model));
+    databaseType = editorState.getRunDatabaseType(
+      query,
+      captureId,
+      model,
+      runtime,
+    );
+  }
+  return serializeCubeLambdaForHost(
+    lambda(
+      [],
+      [emitter.emitRelation(captureId, { withRowOrder: true, databaseType })],
+    ),
+  );
+};

package/src/stores/CubeServiceRecheck.ts

@@ -0,0 +1,53 @@
+/**
+ * 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, Schema, ServiceSource } from '@finos/legend-cube';
+import { CUBE_SERVICE_MESSAGE } from '../__lib__/LegendCubeServiceLabels.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeServiceCatalog } from '../graph-manager/CubeServiceCatalog.js';
+
+/**
+ * Types a cube's services (PLAN §6.4), when they are added and whenever
+ * they are read again. One answer per source, failures included; never
+ * rejects.
+ *
+ * TODO: type each service, e.g. through the engine with the lambda its
+ * emitter will write (`#SQL{select * from service('/pattern')}#`). Until
+ * then every service fails, with why, so it is invalid and nothing runs.
+ */
+export const recheckCubeServiceSources = (
+  catalog: CubeServiceCatalog | undefined,
+  model: ModelContext,
+  sources: readonly ServiceSource[],
+): Promise<Map<NodeId, Schema | CubeEngineError>> =>
+  Promise.resolve(
+    new Map(
+      sources.map((source) => [
+        source.id,
+        new CubeEngineError(
+          CubeEngineErrorKind.UNSUPPORTED_MODEL,
+          catalog
+            ? CUBE_SERVICE_MESSAGE.NOT_READABLE
+            : CUBE_SERVICE_MESSAGE.NO_CATALOG,
+          source.id,
+        ),
+      ]),
+    ),
+  );

package/src/stores/CubeShowPureState.ts

@@ -22,6 +22,7 @@ import {
   CubeEngineErrorKind,
 } from '../graph-manager/CubeEngine.js';
 import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeRunStat } from './CubeRunStatsState.js';
 
 /**
  * Show Pure: the Pure text of what Execute would run, the capture node's
@@ -29,12 +30,15 @@ import type { CubeEditorState } from './CubeEditorState.js';
  * Execute adds (`limit(rowLimit + 1)`, how the grid knows there are more
  * rows), as Legend Query's own Show Pure does: only a Take or Drop the user
  * added shows (user, 2026-10-10). For display only: the text is never parsed
- * back (PLAN §8.7).
+ * back (PLAN §8.7). It also shows a run's lambda from the Runs panel as it
+ * ran, its row limit included, for debugging (PLAN §11.16).
  */
 export class CubeShowPureState {
   readonly editorState: CubeEditorState;
 
   isOpen = false;
+  /** The run shown, by its label; `undefined` for the cube's query */
+  run: string | undefined;
   text: string | undefined;
   /** Why the engine couldn't render the query; shown in the dialog */
   error: CubeEngineError | undefined;
@@ -45,10 +49,12 @@ export class CubeShowPureState {
   constructor(editorState: CubeEditorState) {
     makeObservable(this, {
       isOpen: observable,
+      run: observable,
       text: observable,
       error: observable.ref,
       isRendering: observable,
       open: flow,
+      openRun: flow,
       close: action,
     });
     this.editorState = editorState;
@@ -68,18 +74,14 @@ export class CubeShowPureState {
     if (!execution.canExecute || runtime === undefined || model === undefined) {
       return;
     }
-    const request = ++this.request;
-    this.isOpen = true;
-    this.text = undefined;
-    this.error = undefined;
-    this.isRendering = true;
-    try {
+    const request = this.start(undefined);
+    yield* this.render(request, async () => {
       let databaseType: string | undefined;
       if (needsDatabaseType(query, captureId)) {
-        yield flowResult(this.editorState.loadModelOutline(model));
+        await flowResult(this.editorState.loadModelOutline(model));
         // closed, or opened again, while the outline loaded
         if (request !== this.request) {
-          return;
+          return undefined;
         }
         databaseType = this.editorState.getRunDatabaseType(
           query,
@@ -88,10 +90,46 @@ export class CubeShowPureState {
           runtime,
         );
       }
-      const text = (yield host.engine.renderPure(
+      return host.engine.renderPure(
         emitter.emitExecutionLambda({ runtime, databaseType }),
-      )) as string;
-      if (request === this.request) {
+      );
+    });
+  }
+
+  /**
+   * Opens the dialog on a run of the Runs panel and renders the lambda it
+   * sent, as it ran (PLAN §11.16); does nothing for a run that failed before
+   * one was written
+   */
+  *openRun(run: CubeRunStat): GeneratorFn<void> {
+    const { lambda } = run;
+    if (lambda === undefined) {
+      return;
+    }
+    const request = this.start(run.label);
+    yield* this.render(request, () =>
+      this.editorState.host.engine.renderPure(lambda),
+    );
+  }
+
+  private start(run: string | undefined): number {
+    const request = ++this.request;
+    this.isOpen = true;
+    this.run = run;
+    this.text = undefined;
+    this.error = undefined;
+    this.isRendering = true;
+    return request;
+  }
+
+  /** Renders the text, unless the dialog was closed or opened again meanwhile */
+  private *render(
+    request: number,
+    rendering: () => Promise<string | undefined>,
+  ): GeneratorFn<void> {
+    try {
+      const text = (yield rendering()) as string | undefined;
+      if (request === this.request && text !== undefined) {
         this.text = text;
       }
     } catch (error) {
@@ -115,6 +153,7 @@ export class CubeShowPureState {
     this.request++;
     this.isOpen = false;
     this.isRendering = false;
+    this.run = undefined;
     this.text = undefined;
     this.error = undefined;
   }

package/src/stores/CubeSourcePickerState.ts

@@ -16,8 +16,10 @@
 
 import {
   DataProductAccessPointSource,
+  FunctionSource,
   IngestDatasetSource,
   RelationalTableSource,
+  ServiceSource,
 } from '@finos/legend-cube';
 import type { GeneratorFn } from '@finos/legend-shared';
 import {
@@ -36,8 +38,15 @@ import type { CubeEditorState } from './CubeEditorState.js';
 import { CubeDataProductTabState } from './source-picker/CubeDataProductTabState.js';
 import { CubeDirectConnectionTabState } from './source-picker/CubeDirectConnectionTabState.js';
 import { CubeIngestTabState } from './source-picker/CubeIngestTabState.js';
-import { CubeProjectTabState } from './source-picker/CubeProjectTabState.js';
-import { CubeInlineModelTabState } from './source-picker/CubeInlineModelTabState.js';
+import {
+  CubeProjectFunctionTabState,
+  CubeProjectTabState,
+} from './source-picker/CubeProjectTabState.js';
+import {
+  CubeInlineModelTabState,
+  CubeModelReadKind,
+} from './source-picker/CubeInlineModelTabState.js';
+import { CubeServiceTabState } from './source-picker/CubeServiceTabState.js';
 import {
   type CubeSourcePickerTab,
   CubeSourcePickerTabKey,
@@ -56,17 +65,22 @@ export class CubeSourcePickerState {
   readonly dataProductTab: CubeDataProductTabState;
   readonly ingestTab: CubeIngestTabState;
   readonly projectTab: CubeProjectTabState;
+  readonly projectFunctionTab: CubeProjectFunctionTabState;
+  readonly serviceTab: CubeServiceTabState;
 
   isOpen = false;
   activeTabKey = CubeSourcePickerTabKey.MODEL;
   /** Open with no tab chosen yet, from the empty canvas's link (U4(b)) */
   isChoosingTab = false;
+  /** Opened from the Examples dialog's dataset, so it offers a way back to it */
+  isFromExamples = false;
 
   constructor(editorState: CubeEditorState) {
     makeObservable(this, {
       isOpen: observable,
       activeTabKey: observable,
       isChoosingTab: observable,
+      isFromExamples: observable,
       tabs: computed,
       fixedTab: computed,
       activeTab: computed,
@@ -74,6 +88,9 @@ export class CubeSourcePickerState {
       canConfirm: computed,
       open: action,
       openToChoose: action,
+      openForSourceType: action,
+      openFromExamples: action,
+      backToExamples: action,
       selectTab: action,
       close: action,
       confirm: flow,
@@ -84,6 +101,8 @@ export class CubeSourcePickerState {
     this.dataProductTab = new CubeDataProductTabState(editorState);
     this.ingestTab = new CubeIngestTabState(editorState);
     this.projectTab = new CubeProjectTabState(editorState);
+    this.projectFunctionTab = new CubeProjectFunctionTabState(editorState);
+    this.serviceTab = new CubeServiceTabState(editorState);
   }
 
   /** The tabs that add their own kind of source, each from its palette item */
@@ -91,6 +110,7 @@ export class CubeSourcePickerState {
     return new Map<string, CubeSourcePickerTab>([
       [DataProductAccessPointSource.TYPE, this.dataProductTab],
       [IngestDatasetSource.TYPE, this.ingestTab],
+      [ServiceSource.TYPE, this.serviceTab],
     ]);
   }
 
@@ -99,9 +119,11 @@ export class CubeSourcePickerState {
     return [
       this.modelTab,
       this.projectTab,
+      this.projectFunctionTab,
       this.directTab,
       this.dataProductTab,
       this.ingestTab,
+      this.serviceTab,
     ].filter((tab) => tab.isAvailable);
   }
 
@@ -114,22 +136,27 @@ export class CubeSourcePickerState {
     return context
       ? ([
           this.projectTab,
+          this.projectFunctionTab,
           this.directTab,
           this.dataProductTab,
           this.ingestTab,
+          this.serviceTab,
         ].find((tab) => tab.ownsContext(context)) ?? this.modelTab)
       : undefined;
   }
 
+  /** The tab open last, else the first the host serves */
   get activeTab(): CubeSourcePickerTab {
     return (
-      this.tabs.find((tab) => tab.key === this.activeTabKey) ?? this.modelTab
+      this.tabs.find((tab) => tab.key === this.activeTabKey) ??
+      this.tabs[0] ??
+      this.modelTab
     );
   }
 
   /**
-   * The tab a palette item opens (DP-3): a data product's or an ingest data
-   * set's own tab, when the host serves it; for a table, the table tab the
+   * The tab a palette item opens (DP-3): a data product's, an ingest data
+   * set's or a service's own tab, when the host serves it; for a table, the table tab the
    * cube uses, else the table tab open last, else the Sample Data tab
    */
   tabForSourceType(type: string): CubeSourcePickerTab | undefined {
@@ -137,24 +164,57 @@ export class CubeSourcePickerState {
     if (dedicated) {
       return dedicated.isAvailable ? dedicated : undefined;
     }
-    if (type !== RelationalTableSource.TYPE) {
+    if (type !== RelationalTableSource.TYPE && type !== FunctionSource.TYPE) {
       return undefined;
     }
     const dedicatedTabs = [...this.dedicatedTabs.values()];
-    const tableTabs = this.tabs.filter((tab) => !dedicatedTabs.includes(tab));
-    const { fixedTab } = this;
-    return fixedTab
-      ? tableTabs.find((tab) => tab === fixedTab)
-      : (tableTabs.find((tab) => tab === this.activeTab) ?? this.modelTab);
+    // a table comes from a model or a connection, a function from a model:
+    // a project's tables and functions each have their own tab
+    const readers = this.tabs.filter((tab) =>
+      type === FunctionSource.TYPE
+        ? tab instanceof CubeInlineModelTabState &&
+          tab.readKinds.includes(CubeModelReadKind.FUNCTION)
+        : !dedicatedTabs.includes(tab) &&
+          (!(tab instanceof CubeInlineModelTabState) ||
+            tab.readKinds.includes(CubeModelReadKind.TABLE)),
+    );
+    return this.fixedTab
+      ? readers.find((tab) => this.isTabEnabled(tab))
+      : (readers.find((tab) => tab === this.activeTab) ?? readers[0]);
+  }
+
+  /**
+   * Opens the dialog on the tab a palette item's type opens; a model's tab
+   * reads tables or functions as the item asks
+   */
+  openForSourceType(type: string): void {
+    const tab = this.tabForSourceType(type);
+    if (tab instanceof CubeInlineModelTabState) {
+      tab.setReadKind(
+        type === FunctionSource.TYPE
+          ? CubeModelReadKind.FUNCTION
+          : CubeModelReadKind.TABLE,
+      );
+    }
+    this.open(tab?.key);
   }
 
   /**
    * A cube with a fixed context takes sources from its own tab only, and
-   * none when the host doesn't serve that tab
+   * none when the host doesn't serve that tab; a project cube from both of
+   * its tabs, Project Database and Project Function (PLAN §6.5)
    */
   isTabEnabled(tab: CubeSourcePickerTab): boolean {
+    const { fixedTab } = this;
+    const { context } = this.editorState.document;
     return (
-      tab.isAvailable && (this.fixedTab === undefined || tab === this.fixedTab)
+      tab.isAvailable &&
+      (fixedTab === undefined ||
+        tab === fixedTab ||
+        // a project cube's tables and functions, each from its tab
+        (context !== undefined &&
+          tab !== this.modelTab &&
+          tab.ownsContext(context)))
     );
   }
 
@@ -191,6 +251,7 @@ export class CubeSourcePickerState {
     const { fixedTab } = this;
     this.isOpen = true;
     this.isChoosingTab = false;
+    this.isFromExamples = false;
     const tab =
       fixedTab ??
       this.tabs.find((candidate) => candidate.key === tabKey) ??
@@ -230,15 +291,30 @@ export class CubeSourcePickerState {
     }
   }
 
+  /** Opens on a tab, as `open` does, offering a way back to the Examples dialog */
+  openFromExamples(tabKey: CubeSourcePickerTabKey): void {
+    this.open(tabKey);
+    this.isFromExamples = this.isOpen;
+  }
+
+  /** Closes the dialog and reopens the Examples dialog it came from */
+  backToExamples(): void {
+    this.close();
+    this.editorState.examples.open();
+  }
+
   /** Closes the dialog; a source still being typed is not added */
   close(): void {
     this.isOpen = false;
+    this.isFromExamples = false;
     this.isChoosingTab = false;
     this.modelTab.close();
     this.directTab.close();
     this.dataProductTab.close();
     this.ingestTab.close();
     this.projectTab.close();
+    this.projectFunctionTab.close();
+    this.serviceTab.close();
   }
 
   /** Adds the open tab's source, then closes the dialog */

package/src/stores/CubeTourState.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 { action, computed, flowResult, makeObservable, observable } from 'mobx';
+import {
+  CUBE_EDITOR_TOUR,
+  CUBE_TOUR_EXAMPLE_ID,
+  type CubeTourStep,
+} from '../__lib__/LegendCubeTour.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import { isCubeSampleDataOffered } from './CubeHost.js';
+
+/** Whether a step can be shown: its controls are on the page */
+export type CubeTourStepShown = (step: CubeTourStep) => boolean;
+
+/**
+ * The editor's guided tour (PLAN §11.21): one step at a time, each pointing
+ * at its controls; a step whose controls aren't on the page is skipped. It
+ * starts on the cube as it is, the node editor's edits applied first; on an
+ * empty cube, where examples are offered, it opens one to show (one undo
+ * step). Nothing starts it but the user.
+ */
+export class CubeTourState {
+  readonly editorState: CubeEditorState;
+  readonly steps: readonly CubeTourStep[] = CUBE_EDITOR_TOUR;
+
+  isOpen = false;
+  /** The step shown, an index into `steps` */
+  index = 0;
+  /** Whether this tour opened its example */
+  openedExample = false;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      isOpen: observable,
+      index: observable,
+      openedExample: observable,
+      step: computed,
+      start: action,
+      move: action,
+      close: action,
+    });
+    this.editorState = editorState;
+  }
+
+  get step(): CubeTourStep | undefined {
+    return this.isOpen ? this.steps[this.index] : undefined;
+  }
+
+  /**
+   * Starts the tour at its first step; not while the node editor keeps its
+   * edits open, as other actions wait for it
+   */
+  start(): void {
+    const { editorState } = this;
+    if (this.isOpen || !editorState.nodeEditor.finish()) {
+      return;
+    }
+    const example =
+      editorState.document.query.isEmpty &&
+      !editorState.readOnly &&
+      isCubeSampleDataOffered(editorState.host)
+        ? editorState.examples.examples.find(
+            (candidate) => candidate.id === CUBE_TOUR_EXAMPLE_ID,
+          )
+        : undefined;
+    this.openedExample = example !== undefined;
+    this.index = 0;
+    this.isOpen = true;
+    if (example) {
+      // the tour goes on while it opens and runs: its steps show as they can
+      flowResult(editorState.examples.openExample(example)).catch(
+        editorState.host.applicationStore.alertUnhandledError,
+      );
+    }
+  }
+
+  /**
+   * The step `by` steps on (1) or back (-1), skipping those not shown; past
+   * the last, the tour ends; before the first, it stays
+   */
+  move(by: 1 | -1, isShown: CubeTourStepShown): void {
+    for (
+      let index = this.index + by;
+      index >= 0 && index < this.steps.length;
+      index += by
+    ) {
+      const step = this.steps[index];
+      if (step && isShown(step)) {
+        this.index = index;
+        return;
+      }
+    }
+    if (by === 1) {
+      this.close();
+    }
+  }
+
+  close(): void {
+    this.isOpen = false;
+    this.index = 0;
+  }
+}