@finos/legend-application-studio 22.6.0 → 23.0.1

package/src/stores/editor/GraphEditFormModeState.ts

@@ -0,0 +1,605 @@
+/**
+ * Copyright (c) 2020-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 { TabState } from '@finos/legend-application';
+import {
+  type PackageableElement,
+  isElementReadOnly,
+  Package,
+  GRAPH_MANAGER_EVENT,
+  EngineError,
+  GraphBuilderError,
+  type CompilationResult,
+  CompilationError,
+  extractSourceInformationCoordinates,
+  reportGraphAnalytics,
+} from '@finos/legend-graph';
+import {
+  type GeneratorFn,
+  isNonNullable,
+  assertErrorThrown,
+  LogEvent,
+  ActionState,
+  assertType,
+  guaranteeNonNullable,
+  StopWatch,
+} from '@finos/legend-shared';
+import type { Entity } from '@finos/legend-storage';
+import { flowResult } from 'mobx';
+import type { DSL_LegendStudioApplicationPlugin_Extension } from '../LegendStudioApplicationPlugin.js';
+import { FormLocalChangesState } from './sidebar-state/LocalChangesState.js';
+import { GlobalTestRunnerState } from './sidebar-state/testable/GlobalTestRunnerState.js';
+import { LEGEND_STUDIO_APP_EVENT } from '../../application/LegendStudioEvent.js';
+import { GraphCompilationOutcome, type Problem } from './EditorGraphState.js';
+import { GRAPH_EDITOR_MODE, AUX_PANEL_MODE } from './EditorConfig.js';
+import {
+  graph_addElement,
+  graph_deleteElement,
+  graph_deleteOwnElement,
+  graph_dispose,
+  graph_renameElement,
+} from './shared/modifier/GraphModifierHelper.js';
+import { ElementEditorState } from './editor-state/element-editor-state/ElementEditorState.js';
+import { LegendStudioTelemetryHelper } from '../../application/LegendStudioTelemetryHelper.js';
+import { GraphEditorMode } from './GraphEditorMode.js';
+
+export class GraphEditFormModeState extends GraphEditorMode {
+  *initialize(): GeneratorFn<void> {
+    this.editorStore.localChangesState = new FormLocalChangesState(
+      this.editorStore,
+      this.editorStore.sdlcState,
+    );
+    this.editorStore.graphState.clearProblems();
+    if (
+      this.editorStore.graphState.mostRecentCompilationOutcome ===
+      GraphCompilationOutcome.SUCCEEDED
+    ) {
+      yield flowResult(
+        this.editorStore.graphEditorMode.updateGraphAndApplication(
+          this.editorStore.graphState.compilationResultEntities,
+        ),
+      );
+      this.editorStore.graphState.setMostRecentCompilationGraphHash(
+        this.editorStore.graphEditorMode.getCurrentGraphHash(),
+      );
+      this.editorStore.graphState.compilationResultEntities = [];
+      if (this.editorStore.tabManagerState.currentTab) {
+        this.editorStore.tabManagerState.openTab(
+          this.editorStore.tabManagerState.currentTab,
+        );
+      }
+    }
+  }
+
+  *addElement(
+    element: PackageableElement,
+    packagePath: string | undefined,
+    openAfterCreate: boolean,
+  ): GeneratorFn<void> {
+    graph_addElement(
+      this.editorStore.graphManagerState.graph,
+      element,
+      packagePath,
+      this.editorStore.changeDetectionState.observerContext,
+    );
+    this.editorStore.explorerTreeState.reprocess();
+
+    if (openAfterCreate) {
+      this.openElement(element);
+    }
+  }
+
+  *deleteElement(element: PackageableElement): GeneratorFn<void> {
+    if (
+      this.editorStore.graphState.checkIfApplicationUpdateOperationIsRunning() ||
+      isElementReadOnly(element)
+    ) {
+      return;
+    }
+    const generatedChildrenElements = (
+      this.editorStore.graphState.graphGenerationState.generatedEntities.get(
+        element.path,
+      ) ?? []
+    )
+      .map((genChildEntity) =>
+        this.editorStore.graphManagerState.graph.generationModel.allOwnElements.find(
+          (genElement) => genElement.path === genChildEntity.path,
+        ),
+      )
+      .filter(isNonNullable);
+    const elementsToDelete = [element, ...generatedChildrenElements];
+    this.editorStore.tabManagerState.tabs =
+      this.editorStore.tabManagerState.tabs.filter((elementState) => {
+        if (elementState instanceof ElementEditorState) {
+          if (elementState === this.editorStore.tabManagerState.currentTab) {
+            // avoid closing the current editor state as this will be taken care of
+            // by the `closeState()` call later
+            return true;
+          }
+          return !elementsToDelete.includes(elementState.element);
+        }
+        return true;
+      });
+    if (
+      this.editorStore.tabManagerState.currentTab &&
+      this.editorStore.tabManagerState.currentTab instanceof
+        ElementEditorState &&
+      elementsToDelete.includes(
+        this.editorStore.tabManagerState.currentTab.element,
+      )
+    ) {
+      this.editorStore.tabManagerState.closeTab(
+        this.editorStore.tabManagerState.currentTab,
+      );
+    }
+    // remove/retire the element's generated children before remove the element itself
+    generatedChildrenElements.forEach((el) =>
+      graph_deleteOwnElement(
+        this.editorStore.graphManagerState.graph.generationModel,
+        el,
+      ),
+    );
+    graph_deleteElement(this.editorStore.graphManagerState.graph, element);
+
+    const extraElementEditorPostDeleteActions = this.editorStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap(
+        (plugin) =>
+          (
+            plugin as DSL_LegendStudioApplicationPlugin_Extension
+          ).getExtraElementEditorPostDeleteActions?.() ?? [],
+      );
+    for (const postDeleteAction of extraElementEditorPostDeleteActions) {
+      postDeleteAction(this.editorStore, element);
+    }
+
+    // reprocess project explorer tree
+    this.editorStore.explorerTreeState.reprocess();
+    // recompile
+    yield flowResult(
+      this.globalCompile({
+        message: `Can't compile graph after deletion and error cannot be located in form mode. Redirected to text mode for debugging`,
+      }),
+    );
+  }
+
+  *renameElement(
+    element: PackageableElement,
+    newPath: string,
+  ): GeneratorFn<void> {
+    if (isElementReadOnly(element)) {
+      return;
+    }
+
+    graph_renameElement(
+      this.editorStore.graphManagerState.graph,
+      element,
+      newPath,
+      this.editorStore.changeDetectionState.observerContext,
+    );
+    const extraElementEditorPostRenameActions = this.editorStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap(
+        (plugin) =>
+          (
+            plugin as DSL_LegendStudioApplicationPlugin_Extension
+          ).getExtraElementEditorPostRenameActions?.() ?? [],
+      );
+    for (const postRenameAction of extraElementEditorPostRenameActions) {
+      postRenameAction(this.editorStore, element);
+    }
+
+    // reprocess project explorer tree
+    this.editorStore.explorerTreeState.reprocess();
+    if (element instanceof Package) {
+      this.editorStore.explorerTreeState.openNode(element);
+    } else if (element.package) {
+      this.editorStore.explorerTreeState.openNode(element.package);
+    }
+    // recompile
+    yield flowResult(
+      this.globalCompile({
+        message: `Can't compile graph after renaming and error cannot be located in form mode. Redirected to text mode for debugging`,
+      }),
+    );
+  }
+
+  getCurrentGraphHash(): string | undefined {
+    return this.editorStore.changeDetectionState.currentGraphHash;
+  }
+
+  get mode(): GRAPH_EDITOR_MODE {
+    return GRAPH_EDITOR_MODE.FORM;
+  }
+
+  /**
+   * NOTE: IMPORTANT! This method is both a savior and a sinner. It helps reprocessing the graph state to use a new graph
+   * built from the new model context data, it resets the graph properly. The bane here is that resetting the graph properly is
+   * not trivial, for example, in the cleanup phase, there are things we want to re-use, such as the one-time processed system
+   * metamodels or the `reusable` metamodels from project dependencies. There are also explorer states like the package tree,
+   * opened tabs, change detection, etc. to take care of. There are a lot of potential pitfalls. For these, we will add the
+   * marker:
+   *
+   * @risk memory-leak
+   *
+   * to indicate we should check carefully these pieces when we detect memory issue as it might still
+   * be referring to the old graph
+   *
+   * In the past, we have found that there are a few potential root causes for memory leak:
+   * 1. State management Mobx allows references, as such, it is sometimes hard to trace down which references can cause problem
+   *    We have to understand that the behind this updater is very simple (replace), yet to do it cleanly is not easy, since
+   *    so far it is tempting to refer to elements in the graph from various editor state. On top of that, change detection
+   *    sometimes obfuscate the investigation but we have cleared it out with explicit disposing of reaction
+   * 2. Reusable models, at this point in time, we haven't completed stabilize the logic for handling generated models, as well
+   *    as dependencies, we intended to save computation time by reusing these while updating the graph. This can pose potential
+   *    danger as well. Beware the way when we start to make system/project dependencies references elements of current graph
+   *    e.g. when we have a computed value in a immutable class that get all subclasses, etc.
+   * 3. We reprocess editor states to ensure good UX, e.g. find tabs to keep open, find tree nodes to expand, etc.
+   *    after updating the graph. These in our experience is the **MOST COMMON** source of memory leak. It is actually
+   *    quite predictable since structures like tabs and tree node embeds graph data, which are references to the old graph
+   *
+   * NOTE: One big obfuscating factor is overlapping graph refresh. Sometimes, we observed that calling this update graph
+   * method multiple times can throws Mobx off and causes reusing change detection state to cause memory-leak. As such,
+   * we have blocked the possibility of calling compilation/graph-update/generation simultaneously
+   *
+   * A note on how to debug memory-leak issue:
+   * 1. Open browser Memory monitor
+   * 2. Go to text mode and compile multiple times (triggering graph update)
+   * 3. Try to force garbage collection, if we see memory goes up after while, it's pretty clear that this is memory-leak
+   * (note that since we disallow stacking multiple compilation and graph update, we have simplify the detection a lot)
+   * See https://auth0.com/blog/four-types-of-leaks-in-your-javascript-code-and-how-to-get-rid-of-them/
+   */
+  *updateGraphAndApplication(entities: Entity[]): GeneratorFn<void> {
+    const startTime = Date.now();
+    this.editorStore.graphState.isUpdatingApplication = true;
+    this.editorStore.graphState.isUpdatingGraph = true;
+    try {
+      const newGraph = this.editorStore.graphManagerState.createEmptyGraph();
+      yield flowResult(
+        this.editorStore.graphState.rebuildDependencies(newGraph),
+      );
+
+      /**
+       * Backup and editor states info before resetting. Here we store the element paths of the
+       * elements editors as element paths don't refer to the actual graph. We can find the element
+       * from the new graph that is built by using element path and can reprocess the element editor states.
+       * The other kind of editors we reprocess are file generation editors, we store them as is as they don't
+       * hold any reference to the actual graph.
+       */
+      const openedTabPaths: string[] = [];
+      this.editorStore.tabManagerState.tabs.forEach((state: TabState) => {
+        if (state instanceof ElementEditorState) {
+          openedTabPaths.push(state.elementPath);
+        }
+      });
+      // Only stores editor state for file generation editors as they don't hold any references to the
+      // actual graph.
+      const currentTabState =
+        this.editorStore.tabManagerState.currentTab instanceof
+        ElementEditorState
+          ? undefined
+          : this.editorStore.tabManagerState.currentTab;
+      const currentTabElementPath =
+        this.editorStore.tabManagerState.currentTab instanceof
+        ElementEditorState
+          ? this.editorStore.tabManagerState.currentTab.elementPath
+          : undefined;
+      /**
+       * We remove the current editor state so that we no longer let React displays the element that belongs to the old graph
+       * NOTE: this causes an UI flash, but this is in many way, acceptable since the user probably should know that we are
+       * refreshing the memory graph anyway.
+       *
+       * If this is really bothering, we can handle it by building mocked replica of the current editor state using stub element
+       * e.g. if the current editor is a class, we stub the class, create a new class editor state around it and copy over
+       * navigation information, etc.
+       */
+      this.editorStore.tabManagerState.closeAllTabs();
+
+      this.editorStore.changeDetectionState.stop(); // stop change detection before disposing hash
+
+      yield flowResult(graph_dispose(this.editorStore.graphManagerState.graph));
+
+      const graphBuildState = ActionState.create();
+      yield this.editorStore.graphManagerState.graphManager.buildGraph(
+        newGraph,
+        entities,
+        graphBuildState,
+        {
+          TEMPORARY__preserveSectionIndex:
+            this.editorStore.applicationStore.config.options
+              .TEMPORARY__preserveSectionIndex,
+          strict: this.editorStore.graphState.enableStrictMode,
+        },
+      );
+
+      // Activity States
+      this.editorStore.globalTestRunnerState = new GlobalTestRunnerState(
+        this.editorStore,
+        this.editorStore.sdlcState,
+      );
+
+      // NOTE: build model generation entities every-time we rebuild the graph - should we do this?
+      const generationsBuildState = ActionState.create();
+      yield this.editorStore.graphManagerState.graphManager.buildGenerations(
+        newGraph,
+        this.editorStore.graphState.graphGenerationState.generatedEntities,
+        generationsBuildState,
+      );
+
+      this.editorStore.graphManagerState.graph = newGraph;
+      // NOTE: here we don't want to modify the current graph build state directly
+      // instead, we quietly run this in the background and then sync it with the current build state
+      this.editorStore.graphManagerState.graphBuildState.sync(graphBuildState);
+      this.editorStore.graphManagerState.generationsBuildState.sync(
+        generationsBuildState,
+      );
+
+      this.editorStore.explorerTreeState.reprocess();
+
+      /**
+       * Re-build the editor states which were opened before from the information we have stored before
+       * creating the new graph
+       */
+      this.editorStore.tabManagerState.recoverTabs(
+        openedTabPaths,
+        currentTabState,
+        currentTabElementPath,
+      );
+
+      this.editorStore.applicationStore.logService.info(
+        LogEvent.create(GRAPH_MANAGER_EVENT.UPDATE_AND_REBUILD_GRAPH__SUCCESS),
+        '[TOTAL]',
+        Date.now() - startTime,
+        'ms',
+      );
+      this.editorStore.graphState.isUpdatingGraph = false;
+
+      // ======= (RE)START CHANGE DETECTION =======
+
+      yield flowResult(this.editorStore.changeDetectionState.observeGraph());
+      yield this.editorStore.changeDetectionState.preComputeGraphElementHashes();
+      this.editorStore.changeDetectionState.start();
+      this.editorStore.applicationStore.logService.info(
+        LogEvent.create(
+          LEGEND_STUDIO_APP_EVENT.CHANGE_DETECTION_RESTART__SUCCESS,
+        ),
+        '[ASYNC]',
+      );
+
+      // ======= FINISHED (RE)START CHANGE DETECTION =======
+    } catch (error) {
+      assertErrorThrown(error);
+      this.editorStore.applicationStore.logService.error(
+        LogEvent.create(GRAPH_MANAGER_EVENT.GRAPH_BUILDER_FAILURE),
+        error,
+      );
+      this.editorStore.changeDetectionState.stop(true); // force stop change detection
+      this.editorStore.graphState.isUpdatingGraph = false;
+      // Note: in the future this function will probably be ideal to refactor when we have different classes for each mode
+      // as we would handle this error differently in `text` mode and `form` mode.
+      if (error instanceof GraphBuilderError) {
+        this.editorStore.applicationStore.alertService.setBlockingAlert({
+          message: `Can't build graph: ${error.message}`,
+          prompt: 'Refreshing full application...',
+          showLoading: true,
+        });
+        this.editorStore.tabManagerState.closeAllTabs();
+        this.editorStore.cleanUp();
+        yield flowResult(this.editorStore.buildGraph(entities));
+      }
+    } finally {
+      this.editorStore.graphState.isUpdatingApplication = false;
+      this.editorStore.applicationStore.alertService.setBlockingAlert(
+        undefined,
+      );
+    }
+  }
+
+  // TODO: when we support showing multiple notifications, we can take this options out as the only users of this
+  // is delete element flow, where we want to say `re-compiling graph after deletion`, but because sometimes, compilation
+  // is so fast, the message flashes, so we want to combine with the message in this method
+  *globalCompile(options?: {
+    message?: string;
+    disableNotificationOnSuccess?: boolean;
+    openConsole?: boolean;
+  }): GeneratorFn<void> {
+    if (
+      this.editorStore.graphState.checkIfApplicationUpdateOperationIsRunning()
+    ) {
+      this.editorStore.graphState.setMostRecentCompilationOutcome(
+        GraphCompilationOutcome.SKIPPED,
+      );
+      return;
+    }
+
+    const stopWatch = new StopWatch();
+    const report = reportGraphAnalytics(
+      this.editorStore.graphManagerState.graph,
+    );
+    LegendStudioTelemetryHelper.logEvent_GraphCompilationLaunched(
+      this.editorStore.applicationStore.telemetryService,
+    );
+
+    const currentGraphHash = this.getCurrentGraphHash();
+
+    try {
+      this.editorStore.graphState.isRunningGlobalCompile = true;
+      this.editorStore.graphState.clearProblems();
+      if (options?.openConsole) {
+        this.editorStore.setActiveAuxPanelMode(AUX_PANEL_MODE.CONSOLE);
+      }
+
+      // NOTE: here we always keep the source information while compiling in form mode
+      // so that the form parts where the user interacted with (i.e. where the lamdbas source
+      // information are populated), can reveal compilation error. If compilation errors
+      // show up in other parts, the user will get redirected to text-mode
+      const compilationResult =
+        (yield this.editorStore.graphManagerState.graphManager.compileGraph(
+          this.editorStore.graphManagerState.graph,
+          {
+            keepSourceInformation: true,
+          },
+          report,
+        )) as CompilationResult;
+
+      this.editorStore.graphState.warnings = compilationResult.warnings
+        ? this.editorStore.graphState.TEMPORARY__removeDependencyProblems(
+            compilationResult.warnings,
+          )
+        : [];
+
+      this.editorStore.graphState.setMostRecentCompilationGraphHash(
+        currentGraphHash,
+      );
+
+      if (!options?.disableNotificationOnSuccess) {
+        if (this.editorStore.graphState.warnings.length) {
+          this.editorStore.applicationStore.notificationService.notifyWarning(
+            `Compilation suceeded with warnings`,
+          );
+        } else {
+          if (!options?.disableNotificationOnSuccess) {
+            this.editorStore.applicationStore.notificationService.notifySuccess(
+              'Compiled successfully',
+            );
+          }
+        }
+      }
+
+      report.timings =
+        this.editorStore.applicationStore.timeService.finalizeTimingsRecord(
+          stopWatch,
+          report.timings,
+        );
+      LegendStudioTelemetryHelper.logEvent_GraphCompilationSucceeded(
+        this.editorStore.applicationStore.telemetryService,
+        report,
+      );
+
+      this.editorStore.graphState.setMostRecentCompilationOutcome(
+        GraphCompilationOutcome.SUCCEEDED,
+      );
+    } catch (error) {
+      assertErrorThrown(error);
+      // TODO: we probably should make this pattern of error the handling for all other exceptions in the codebase
+      // i.e. there should be a catch-all handler (we can use if-else construct to check error types)
+      assertType(error, EngineError, `Unhandled exception:\n${error}`);
+      this.editorStore.applicationStore.logService.error(
+        LogEvent.create(GRAPH_MANAGER_EVENT.COMPILATION_FAILURE),
+        error,
+      );
+      this.editorStore.graphState.setMostRecentCompilationGraphHash(
+        currentGraphHash,
+      );
+      let fallbackToTextModeForDebugging = true;
+      // if compilation failed, we try to reveal the error in form mode,
+      // if even this fail, we will fall back to show it in text mode
+      if (error instanceof CompilationError) {
+        const errorCoordinates = extractSourceInformationCoordinates(
+          error.sourceInformation,
+        );
+        if (errorCoordinates) {
+          const element =
+            this.editorStore.graphManagerState.graph.getNullableElement(
+              guaranteeNonNullable(
+                errorCoordinates[0],
+                `Can't reveal compilation error: element path is missing`,
+              ),
+              false,
+            );
+          if (element) {
+            this.openElement(element);
+            if (
+              this.editorStore.tabManagerState.currentTab instanceof
+              ElementEditorState
+            ) {
+              // check if we can reveal the error in the element editor state
+              fallbackToTextModeForDebugging =
+                !this.editorStore.tabManagerState.currentTab.revealCompilationError(
+                  error,
+                );
+            }
+          }
+        }
+      }
+
+      // decide if we need to fall back to text mode for debugging
+      if (fallbackToTextModeForDebugging) {
+        // TODO: when we support showing multiple notifications, we can split this into 2
+        this.editorStore.applicationStore.notificationService.notifyWarning(
+          options?.message ??
+            'Compilation failed and error cannot be located in form mode. Redirected to text mode for debugging.',
+        );
+        this.editorStore.graphState.setMostRecentCompilationOutcome(
+          GraphCompilationOutcome.FAILED,
+        );
+        yield flowResult(
+          this.editorStore.switchModes(GRAPH_EDITOR_MODE.GRAMMAR_TEXT, {
+            isCompilationFailure: true,
+          }),
+        );
+      } else {
+        this.editorStore.graphState.error = error;
+        this.editorStore.applicationStore.notificationService.notifyWarning(
+          `Compilation failed: ${error.message}`,
+        );
+        this.editorStore.graphState.setMostRecentCompilationOutcome(
+          GraphCompilationOutcome.FAILED,
+        );
+      }
+    } finally {
+      this.editorStore.graphState.isRunningGlobalCompile = false;
+    }
+  }
+
+  goToProblem(problem: Problem): void {
+    return;
+  }
+
+  *onLeave(): GeneratorFn<void> {
+    return;
+  }
+
+  *cleanupBeforeEntering(fallbackOptions?: {
+    isCompilationFailure?: boolean;
+    isGraphBuildFailure?: boolean;
+  }): GeneratorFn<void> {
+    return;
+  }
+
+  *handleCleanupFailure(error: unknown): GeneratorFn<void> {
+    return;
+  }
+
+  openElement(element: PackageableElement): void {
+    if (!(element instanceof Package)) {
+      const existingElementState = this.editorStore.tabManagerState.tabs.find(
+        (state) =>
+          state instanceof ElementEditorState && state.element === element,
+      );
+      const newTab =
+        existingElementState ??
+        this.editorStore.tabManagerState.createElementEditorState(element);
+      if (newTab) {
+        this.editorStore.tabManagerState.openTab(newTab);
+      } else {
+        this.editorStore.applicationStore.notificationService.notifyWarning(
+          `Can't open editor for element '${element.path}'`,
+        );
+      }
+    }
+  }
+}