@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/stores/CubeEngineChecks.ts

@@ -0,0 +1,240 @@
+/**
+ * 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,
+  ERR_CHECKING,
+  ERR_TYPING,
+  ExpressionFilter,
+  Extend,
+  type IR,
+  isTypingError,
+  type JsonObject,
+  type ModelContext,
+  type NodeRegistry,
+  type Query,
+  QueryEmitter,
+  type QueryNode,
+  type QueryRule,
+  type Schema,
+} from '@finos/legend-cube';
+import {
+  getConditionRecheckWarning,
+  getExtendRetypeWarning,
+} from '../__lib__/LegendCubeLabels.js';
+import {
+  type CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+import {
+  buildCubeConditionCheckLambdas,
+  getCubeConditionCheckUpstream,
+  isCubeConditionCheckCurrent,
+  isSameCubeConditionCheck,
+  readCubeConditionCheck,
+} from './CubeExpressionFilterCheck.js';
+import {
+  buildCubeExtendTypingLambdas,
+  getCubeExtendTypingUpstream,
+  getCubeExtendUpstream,
+  isCubeExtendTypingCurrent,
+  isSameCubeExtendTyping,
+  readCubeExtendTyping,
+} from './CubeExtendTyping.js';
+
+// The nodes the engine checks in the background, outside the undo history:
+// an Extend, whose columns it types (PLAN §11.7), and a Filter by Expression,
+// whose condition it checks (PLAN §11.11). One path serves both, so what
+// M6.11's review fixed for Extends holds for filters too.
+
+/** A node the engine checks: an Extend or a Filter by Expression */
+export type CubeEngineCheckedNode = Extend | ExpressionFilter;
+
+export const isCubeEngineCheckedNode = (
+  node: QueryNode,
+): node is CubeEngineCheckedNode =>
+  node instanceof Extend || node instanceof ExpressionFilter;
+
+/** The digest of what the engine was given for the node's input, which its last check recorded */
+export const getCubeEngineCheckUpstream = (
+  node: CubeEngineCheckedNode,
+): string | undefined =>
+  node instanceof Extend
+    ? getCubeExtendTypingUpstream(node.typing)
+    : getCubeConditionCheckUpstream(node.check);
+
+/** What the engine's answers make of a node: the node to store, when they say anything new */
+export interface CubeEngineCheckOutcome {
+  /** The node with its new check, or `undefined` when the answers say what it says already */
+  readonly node: CubeEngineCheckedNode | undefined;
+  /** The engine's error, when the check failed */
+  readonly error?: CubeEngineError | undefined;
+  /**
+   * When the engine couldn't be reached and the node's last check still
+   * holds for this input, the warning that keeps it, as a source keeps its
+   * saved columns
+   */
+  readonly keptWarning?: string | undefined;
+}
+
+/** The lambdas that check one node, and how to read the engine's answers to them */
+export interface CubeEngineCheckRequest {
+  readonly node: CubeEngineCheckedNode;
+  readonly lambdas: ReadonlyMap<NodeId, IR>;
+  read(
+    answers: ReadonlyMap<NodeId, Schema | CubeEngineError>,
+  ): CubeEngineCheckOutcome;
+}
+
+/** What to make of a node's new check: kept with a warning, offline, when the last one holds; else stored if new */
+const outcomeOf = (
+  node: CubeEngineCheckedNode,
+  error: CubeEngineError | undefined,
+  stillCurrent: () => boolean,
+  isSame: boolean,
+  withCheck: () => CubeEngineCheckedNode,
+  warn: (firstLine: string) => string,
+): CubeEngineCheckOutcome =>
+  error?.kind === CubeEngineErrorKind.NETWORK && stillCurrent()
+    ? { node: undefined, error, keptWarning: warn(error.firstLine) }
+    : { node: isSame ? undefined : withCheck(), error };
+
+/**
+ * The request that checks a node for the input it has now, its lambdas
+ * marked with the node; `undefined` when it has nothing to send yet: an
+ * Extend column without a lambda, or a condition with a problem Cube finds
+ * itself. The input must be valid.
+ */
+export const buildCubeEngineCheckRequest = (
+  query: Query,
+  node: CubeEngineCheckedNode,
+  input: Schema,
+  upstream: string | undefined,
+  registry: NodeRegistry,
+): CubeEngineCheckRequest | undefined => {
+  if (node instanceof Extend) {
+    if (node.columns.some(({ lambda }) => lambda === undefined)) {
+      return undefined;
+    }
+    const columns = node.columns.map(({ name, lambda }) => ({
+      name,
+      lambda: lambda as JsonObject,
+    }));
+    return {
+      node,
+      lambdas: buildCubeExtendTypingLambdas(
+        query,
+        node,
+        columns,
+        registry,
+        false,
+      ),
+      read: (answers) => {
+        const { typing, error } = readCubeExtendTyping(
+          answers,
+          node,
+          input,
+          columns,
+          upstream,
+        );
+        return outcomeOf(
+          node,
+          error,
+          () => isCubeExtendTypingCurrent(node, input, upstream),
+          isSameCubeExtendTyping(typing, node.typing),
+          () => node.withTyping(typing),
+          getExtendRetypeWarning,
+        );
+      },
+    };
+  }
+  const { lambda } = node;
+  if (lambda === undefined || node.getConditionProblem() !== undefined) {
+    return undefined;
+  }
+  return {
+    node,
+    lambdas: buildCubeConditionCheckLambdas(
+      query,
+      node,
+      lambda,
+      input,
+      registry,
+      false,
+    ),
+    read: (answers) => {
+      const { check, error } = readCubeConditionCheck(
+        answers,
+        node,
+        input,
+        upstream,
+      );
+      return outcomeOf(
+        node,
+        error,
+        () => isCubeConditionCheckCurrent(node, input, upstream),
+        isSameCubeConditionCheck(check, node.check),
+        () => node.withCheck(check),
+        getConditionRecheckWarning,
+      );
+    },
+  };
+};
+
+/**
+ * A query rule for the editor (PLAN §11.7, §11.11): a node whose check
+ * recorded another input than the engine would be given now waits to be
+ * checked again (`ERR_TYPING` for an Extend, `ERR_CHECKING` for a filter),
+ * e.g. after an Extend above it gains `->toOne()`, which Cube's schema
+ * doesn't show. A check that recorded nothing, as one loaded, is used as it
+ * is; a node that already waits, or whose input is invalid, is left to its
+ * own checks.
+ */
+export const createStaleCubeEngineCheckRule =
+  (
+    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 CubeEngineCheckedNode =>
+        isCubeEngineCheckedNode(node) &&
+        getCubeEngineCheckUpstream(node) !== 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 !== getCubeEngineCheckUpstream(node)
+      ) {
+        stale.set(node.id, [
+          node instanceof Extend ? ERR_TYPING : ERR_CHECKING,
+        ]);
+      }
+    });
+    return stale;
+  };

package/src/stores/CubeEntrySource.ts

@@ -0,0 +1,278 @@
+/**
+ * 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 { DataProductAccessPointSource } from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import {
+  action,
+  flow,
+  flowResult,
+  makeObservable,
+  observable,
+  when,
+} from 'mobx';
+import {
+  CUBE_DEFAULT_CONSUMER_WAREHOUSE,
+  CubeDataProductEnvironmentType,
+} from '../graph-manager/CubeDataProduct.js';
+import type { CubeDataProductCandidate } from '../graph-manager/CubeDataProductCatalog.js';
+import { CubeEngineError } from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeDataProductTabError } from './source-picker/CubeDataProductTabState.js';
+
+/**
+ * A source a link from another screen asks the page to start with (spec
+ * §17.15, QUESTIONS.md U9): its kind and its id. Only data product access
+ * points can be named by ids alone (PLAN §11.8).
+ */
+export interface CubeEntrySource {
+  readonly sourceType: string;
+  readonly sourceId: string;
+}
+
+/** Where a data product access point's link points, read from its id */
+export interface CubeAccessPointEntry {
+  readonly environmentType: CubeDataProductEnvironmentType;
+  readonly dataProductId: string;
+  readonly deploymentId: string;
+  readonly accessPointGroup: string;
+  readonly accessPoint: string;
+}
+
+/** Why a linked source couldn't be added: a line, with the rest on demand */
+export interface CubeEntrySourceError {
+  readonly message: string;
+  readonly detail?: string | undefined;
+}
+
+/** A failure carrying the source dialog's error as it is */
+class CubeEntrySourceFailure extends Error {
+  readonly error: CubeEntrySourceError;
+
+  constructor(error: CubeEntrySourceError) {
+    super(error.message);
+    this.error = error;
+  }
+}
+
+const toEntrySourceError = (error: unknown): CubeEntrySourceError => {
+  if (error instanceof CubeEntrySourceFailure) {
+    return error.error;
+  }
+  if (error instanceof CubeEngineError) {
+    return {
+      message: error.firstLine,
+      detail: error.detail !== error.firstLine ? error.detail : undefined,
+    };
+  }
+  assertErrorThrown(error);
+  return { message: error.message };
+};
+
+/** The banner's title over the reason a linked source couldn't be added (spec §17.13) */
+export const CUBE_ENTRY_SOURCE_ERROR_TITLE = 'Error resolving source!';
+
+export const CUBE_ENTRY_SOURCE_MESSAGE = {
+  UNSUPPORTED_TYPE: (sourceType: string): string =>
+    `A link can't name a source of type "${sourceType}": only data product access points.`,
+  BAD_ID: (sourceId: string): string =>
+    `"${sourceId}" doesn't name an access point: it takes <class>/<data product id>/<deployment id>/<access point group>/<access point>.`,
+  NO_CATALOG: 'This page has no data products to open.',
+  NOT_NEW: 'A link opens a source on a new cube only.',
+  INTERRUPTED: 'Opening the linked source was interrupted; open it again.',
+  NOT_FOUND: (dataProductId: string, deploymentId: string): string =>
+    `No data product "${dataProductId}" is deployed as "${deploymentId}".`,
+  NO_ACCESS_POINT: (group: string, accessPoint: string): string =>
+    `The data product has no access point "${accessPoint}" in group "${group}".`,
+};
+
+/**
+ * The id a link gives a data product access point: its deployment class,
+ * the data product's id, its deployment id, the access point group and the
+ * access point, each URI-encoded, joined by '/'
+ */
+export const formatCubeAccessPointEntryId = (
+  entry: CubeAccessPointEntry,
+): string =>
+  [
+    entry.environmentType,
+    entry.dataProductId,
+    entry.deploymentId,
+    entry.accessPointGroup,
+    entry.accessPoint,
+  ]
+    .map(encodeURIComponent)
+    .join('/');
+
+/** The access point a link's id names, or undefined when it names none */
+export const parseCubeAccessPointEntryId = (
+  sourceId: string,
+): CubeAccessPointEntry | undefined => {
+  const parts = sourceId.split('/');
+  if (parts.length !== 5) {
+    return undefined;
+  }
+  let decoded: string[];
+  try {
+    decoded = parts.map(decodeURIComponent);
+  } catch {
+    return undefined;
+  }
+  const [environmentType, dataProductId, deploymentId, group, accessPoint] =
+    decoded as [string, string, string, string, string];
+  if (
+    !Object.values(CubeDataProductEnvironmentType).includes(
+      environmentType as CubeDataProductEnvironmentType,
+    ) ||
+    decoded.some((part) => part.trim().length === 0)
+  ) {
+    return undefined;
+  }
+  return {
+    environmentType: environmentType as CubeDataProductEnvironmentType,
+    dataProductId,
+    deploymentId,
+    accessPointGroup: group,
+    accessPoint,
+  };
+};
+
+/**
+ * Starts the page with the source a link names (spec §17.15, U9): resolved
+ * alone, as the cube's first and selected node, with no dialog or editor
+ * opened and nothing run. A source that can't be added leaves the cube
+ * empty and says why in a banner. A data product access point is added as
+ * its tab adds one, on the viewer's remembered warehouse.
+ */
+export class CubeEntrySourceState {
+  readonly editorState: CubeEditorState;
+  isOpening = false;
+  /** Why the linked source couldn't be added, until dismissed */
+  error: CubeEntrySourceError | undefined;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable(this, {
+      isOpening: observable,
+      error: observable.ref,
+      open: flow,
+      dismissError: action,
+    });
+    this.editorState = editorState;
+  }
+
+  /** The cube is still new: empty, editable and on no model */
+  private isNewCube(): boolean {
+    const { document, readOnly } = this.editorState;
+    return !readOnly && !document.context && document.query.isEmpty;
+  }
+
+  *open(entry: CubeEntrySource): GeneratorFn<void> {
+    if (this.isOpening) {
+      return;
+    }
+    this.isOpening = true;
+    this.error = undefined;
+    const tab = this.editorState.sourcePicker.dataProductTab;
+    let picked = false;
+    try {
+      if (!this.isNewCube()) {
+        throw new Error(CUBE_ENTRY_SOURCE_MESSAGE.NOT_NEW);
+      }
+      if (entry.sourceType !== DataProductAccessPointSource.TYPE) {
+        throw new Error(
+          CUBE_ENTRY_SOURCE_MESSAGE.UNSUPPORTED_TYPE(entry.sourceType),
+        );
+      }
+      const location = parseCubeAccessPointEntryId(entry.sourceId);
+      if (!location) {
+        throw new Error(CUBE_ENTRY_SOURCE_MESSAGE.BAD_ID(entry.sourceId));
+      }
+      const { catalog } = tab;
+      if (!catalog) {
+        throw new Error(CUBE_ENTRY_SOURCE_MESSAGE.NO_CATALOG);
+      }
+      const candidates = (yield catalog.search({
+        text: location.dataProductId,
+        environmentType: location.environmentType,
+      })) as readonly CubeDataProductCandidate[];
+      const candidate = candidates.find(
+        (found) =>
+          found.id === location.dataProductId &&
+          found.deploymentId === location.deploymentId,
+      );
+      if (!candidate) {
+        throw new Error(
+          CUBE_ENTRY_SOURCE_MESSAGE.NOT_FOUND(
+            location.dataProductId,
+            location.deploymentId,
+          ),
+        );
+      }
+      // the tab adds it, as a pick in the dialog would
+      tab.selectCandidate(candidate);
+      picked = true;
+      yield when(() => !tab.isDescribing);
+      if (tab.error) {
+        throw new CubeEntrySourceFailure(tab.error);
+      }
+      if (!tab.description || tab.candidate !== candidate) {
+        // e.g. the source dialog was opened meanwhile, and closed, or another
+        // product picked in it
+        throw new Error(CUBE_ENTRY_SOURCE_MESSAGE.INTERRUPTED);
+      }
+      tab.selectAccessPoint(location.accessPointGroup, location.accessPoint);
+      if (!tab.accessPoint) {
+        throw new Error(
+          CUBE_ENTRY_SOURCE_MESSAGE.NO_ACCESS_POINT(
+            location.accessPointGroup,
+            location.accessPoint,
+          ),
+        );
+      }
+      if (tab.accessPoint.disabledReason !== undefined) {
+        throw new Error(tab.accessPoint.disabledReason);
+      }
+      // the user may have added a source while the product was read
+      if (!this.isNewCube()) {
+        throw new Error(CUBE_ENTRY_SOURCE_MESSAGE.NOT_NEW);
+      }
+      tab.setWarehouse(
+        this.editorState.dataProductRuntime.rememberedWarehouse ??
+          CUBE_DEFAULT_CONSUMER_WAREHOUSE,
+      );
+      const added = (yield flowResult(tab.confirm())) as boolean;
+      if (!added) {
+        // the confirm may have set it since it was read above
+        const confirmError = tab.error as CubeDataProductTabError | undefined;
+        throw confirmError
+          ? new CubeEntrySourceFailure(confirmError)
+          : new Error(CUBE_ENTRY_SOURCE_MESSAGE.INTERRUPTED);
+      }
+    } catch (error) {
+      this.error = toEntrySourceError(error);
+      if (picked) {
+        // the dialog's tab opens clean, not on the link's product
+        tab.selectCandidate(undefined);
+      }
+    } finally {
+      this.isOpening = false;
+    }
+  }
+
+  dismissError(): void {
+    this.error = undefined;
+  }
+}