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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   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.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @finos/legend-cube-builder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The UI and the Legend engine adapter of Legend Cube, a canvas-based visual query builder. The domain model lives in the
+host-free [`@finos/legend-cube`](../legend-cube).
+
+It holds the page (the canvas, the palette, the side-panel editors, the source picker and the results grid), its MobX
+stores, the engine port with its `v1/` adapter, and the bundled model catalog. Legend Query hosts the page at
+`/query/cube`.
+
+**Status:** work in progress, version 0.0.x. This version has relational tables, Join, Sort, Filter, Restrict, Rename, Distinct, Drop, Limit and Slice, with one model, one
+runtime and one database per query. A cube is kept only through Export and Import of its spec, marked "(dev)", until
+the Cube store exists. A pasted model is kept in the cube. Nothing links to the page yet, there is no redo, and Cube sends no telemetry.
+
+## Layout
+
+| Folder                                | Holds                                                                                                                                                   |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/components/`                     | the page, `CubeEditor`, and its parts: `canvas/`, `palette/`, `editors/`, `source-picker/`, `grid/`, `show-pure/`, `spec-transfer/`                     |
+| `src/stores/`                         | the MobX state of the page, its parts and the side panel; `editors/` (node drafts); `LocalModelCatalog` and `fixtures/` (the bundled model); `CubeHost` |
+| `src/graph-manager/`                  | the engine port (`CubeEngine.ts`) and `buildCubeEngine`                                                                                                 |
+| `src/graph-manager/protocol/pure/v1/` | the engine adapter, `V1_LegendCubeEngine`: the lambda serializer, the result and relation-type readers, the error mapping                               |
+| `src/__lib__/`                        | labels, help text, the command config and test ids                                                                                                      |
+| `src/__test-utils__/`                 | the fake engine and the helpers of the tests                                                                                                            |
+| `style/`                              | the stylesheet, built to `lib/index.css`                                                                                                                |
+
+It depends on `@finos/legend-cube`, legend-graph, legend-application, legend-art, legend-lego and legend-shared, never
+on an application package (`legend-application-*`) or on legend-query-builder.
+
+**The V1 rule:** `V1_*` protocol code lives under `src/graph-manager/protocol/pure/v1/`. The one product file outside
+it that names `V1_*` is the seam `src/graph-manager/protocol/pure/CubeEngineBuilder.ts`: `buildCubeEngine` is the only
+product code that makes a `V1_LegendCubeEngine`, so hosts never name a `V1_*` symbol. The repo's
+`enforce-module-import-hierarchy` lint rule forbids imports between `stores/` or `components/` and `v1/`, both ways.
+The engine-backed tests in `src/__tests__/` are an exception: they need both the adapter and `stores/`.
+
+## Public API
+
+`src/index.ts` exports:
+
+- `CubeEditor`, the page, and `CubeHost`, what a host gives it;
+- the engine port, everything in `CubeEngine.ts` (`CubeEngine`, `CubeEngineError`, `CubeEngineErrorKind`,
+  `CubeResult`, `CubeModelOutline`, …), with `buildCubeEngine` and `CubeEngineConfig`;
+- `LocalModelCatalog` and `BUNDLED_MODELS`;
+- `LEGEND_CUBE_COMMAND_CONFIG` and `LEGEND_CUBE_COMMAND_KEY`, the page's shortcuts;
+- `LEGEND_CUBE_TEST_ID`;
+- helpers that 0.0.2 published and nothing outside the package uses yet: `getRuntimesForDatabase`, `createTextModel`,
+  `BundledModel`, and the bundled model's `CUBE_NORTHWIND_MODEL`, `CUBE_NORTHWIND_DATABASE` and
+  `CUBE_NORTHWIND_RUNTIME`.
+
+The node-type registries (drafts, editors, help text and icons) are internal: there is no plugin API for node types
+yet.
+
+## New source kinds
+
+Adding a kind of source (beyond relational tables) is not a registration yet. The builder is wired to relational
+tables in `CubeEditorState` (re-checking tables, opening the picker), `CubeSourcePickerState`, `CubeJoinDraft`,
+`CubeSourceEditor`, and the port's `resolveSchemas` and `CubeModelOutline`. New sources wait on the design of the
+sources dialog.
+
+## Documentation
+
+- [Hosting the page](./docs/hosting.md): what a host gives the page, the shortcuts, the stylesheet, and the dev loop.
+- [Testing](./docs/testing.md): the test groups, the fake engine, and the tests against a real engine.
+- [Adding an operation](./docs/adding-an-operation.md): the builder half of a new transform. The core half is in
+  [`@finos/legend-cube`](../legend-cube/docs/adding-an-operation.md).
+- [The plan](../../docs/wip/legend-cube/PLAN.md) and [the known issues](../../docs/wip/legend-cube/ISSUES.md).

package/docs/adding-an-operation.md

@@ -0,0 +1,92 @@
+# Adding an operation: the builder half
+
+Start with the core half, in [`@finos/legend-cube`'s guide](../../legend-cube/docs/adding-an-operation.md): the
+node, its messages, emitter and codec, and its entry in the node registry. The palette, the context menu and the
+canvas read that registry, so the new type shows there with no change here.
+
+The builder adds four pieces: a draft, an editor and help text, in registries keyed by node type, and an icon, keyed by
+the icon name the node's definition gives. Join and Filter are the examples to follow.
+
+## 1. A draft
+
+The side panel never edits the document: an editor edits a draft, and the panel's **Apply** stores the draft's node
+as one undo step (**Cancel** drops it).
+
+- In `src/stores/editors/Cube<Type>Draft.ts`, extend `CubeNodeDraft<Type>`: observable fields for the settings being
+  edited, actions that change them, and `build()`. `build()` returns `original` itself while nothing was edited, and
+  otherwise a new node with the same id and `rest`. The panel also treats a node that saves the same as `original`
+  as no change.
+- Register a factory in `CUBE_NODE_DRAFT_FACTORIES` (`src/stores/editors/CubeNodeDraftRegistry.ts`).
+- A transform with nothing to set, such as Distinct, has no draft: it registers an editor that only describes it
+  (`CubeDistinctEditor`) and is listed in `CUBE_NODE_TYPES_WITHOUT_SETTINGS`, which the registry test skips when it
+  asks for a factory. The panel then shows no Apply or Cancel (PLAN §7.4 item 2).
+
+## 2. An editor
+
+- In `src/components/editors/Cube<Type>Editor.tsx`, an `observer` component taking `CubeNodeEditorProps`:
+  `editorState`, `draft`, `inputSchemas` (the inputs' schemas in port order; the panel shows the editor only once all
+  are there) and `readOnly` (a cube saved by a newer version: show, don't edit).
+- It changes only the draft. An action on the document, such as Join's Swap Inputs, goes through
+  `editorState.nodeEditor`, which applies the draft first.
+- `CubeColumnPicker` picks a column from a schema, and `CubeValueEditor` takes a value as a column's type wants it.
+  `isColumnDisabled` gives the reason a column can't be picked, shown after its type, as Sort does for a type that can't
+  be sorted (`isSortableType`) and a column another row has; the column stays shown.
+- A whole-number setting (a size, a row index) is a `CubeIntegerField` over text the draft keeps as typed, read with
+  `parseWholeNumberText` (`src/stores/editors/CubeIntegerText.ts`): an optional sign and digits, nothing else, and empty
+  text gives `undefined`, which the node reports. Never `Number()` the raw text (it reads `''` as 0, `0x10` as 16 and
+  `1e3` as 1000) and never fall back to a default. `CubeRowCountDraft` and `CubeRowCountEditor` (Limit's) are the
+  example.
+- Give each control a stable `aria-label` (numbered per row in a list, e.g. `Sort column 2`): the tests and the
+  browser rehearsal find controls by it.
+- An editor must work in either host: today's side panel, or a floating editor anchored under the node, which M3
+  decides on (PLAN §11.4, §12.2 question 1). Don't rely on the panel's height: a list scrolls on its own (a
+  `max-height` with `overflow: auto`), column and direction pickers stay native `<select>` elements, as
+  `CubeColumnPicker` is, and no editor measures the panel or reads its size.
+- A Tailwind class no other file uses yet, such as an arbitrary `grid-cols-[…]`, does nothing in the dev server until
+  the deployment's Tailwind build runs again ([hosting.md](./hosting.md)); jsdom tests don't see it either way, so
+  check a new layout in the browser.
+- Register it in `CUBE_NODE_EDITORS` (`src/components/editors/CubeNodeEditorRegistry.ts`).
+
+## 3. Help text
+
+An entry in `CUBE_NODE_HELP_TEXT` (`src/__lib__/LegendCubeHelpText.ts`), shown in the panel's header. Use the spec's
+text (§17.9) where it has one.
+
+## 4. An icon
+
+Map the icon name of the node's definition to a legend-art icon in `NODE_ICONS` (`src/components/CubeNodeIcon.tsx`).
+
+## Warnings
+
+A warning is never an error: it doesn't make the node invalid or keep Execute from running. A warning worked out from
+the query, as the Sort warning is (`findLostSortOrders` in the core), goes in `CubeEditorState.derivedWarnings`, by
+node id, so it follows every edit and undo and is never stored; one about the outside world, such as a table that
+changed, is stored in `CubeEditorState.warnings`, by node key. `getNodeWarnings(node)` gives both: the canvas marks the
+node (`legend-cube__node--warning`) and lists them in its tooltip after its errors, and the panel shows each one as a
+`role="status"` line above the editor. A derived warning waits until the nodes it names have no errors of their own.
+
+## Columns that change name
+
+The Join editor warns when a join key's column has no type in the model, tracing the column back to its table and the
+table's own name for it with `findColumnOrigins` (`src/stores/editors/CubeJoinDraft.ts`). It requires each node's
+output to have the column, maps a Rename's new name back to its old one, and follows a Join's same-named keys to the
+side the join keeps. Every other node is taken to pass its input's columns through under the same name. If a new
+transform's output columns aren't its inputs' under the same name (a computed column, say), teach `findColumnOrigins`
+how they map back, or the warning goes missing or shows on the wrong column.
+
+## Tests
+
+- `src/components/editors/__tests__/CubeNodeEditorRegistry.test.ts` fails for a type missing a piece: it checks every
+  registered type for help text, an icon and an editor, and that each transform's draft gives back its node until
+  edited. Add the new help text to its exact list.
+- Add the new item, in the spec's menu order, to the lists in `src/components/palette/__tests__/CubePalette.test.tsx`
+  and to `TRANSFORMS` in `src/components/canvas/__tests__/CubeCanvasContextMenu.test.tsx`.
+- A draft test (`src/stores/editors/__tests__/`) and an editor test (`src/components/editors/__tests__/`), as Join's
+  and Filter's are.
+- An engine test of the operation in `src/__tests__/LegendCubeOperations.engine-roundtrip-test.ts` (see
+  [Testing](./testing.md)): its lambda as the engine parses the printed Pure, its typing against Cube's inferred
+  schema, and what it returns, not its text.
+
+The `v1/` adapter (`V1_CubeLambdaSerializer`) needs no change while the operation's emitter uses only IR and literal
+kinds it already writes. A new kind of IR node or literal needs its own case there, with a test in
+`src/graph-manager/protocol/pure/v1/__tests__/`.

package/docs/hosting.md

@@ -0,0 +1,79 @@
+# Hosting the Cube page
+
+A Legend application hosts the page by giving it a `CubeHost` and contributing its shortcuts. Legend Query is the
+host today: `LegendQueryCubeHost` (`src/stores/cube/`), and the lazy route and page (`src/components/cube/`) of
+`@finos/legend-application-query`.
+
+## The host
+
+```ts
+interface CubeHost {
+  readonly applicationStore: GenericLegendApplicationStore;
+  readonly engine: CubeEngine;
+  readonly modelCatalog: LocalModelCatalog;
+}
+```
+
+- **The application store** gives the page its commands, user data, clipboard, theme, notifications and alerts, and
+  its telemetry service, which Cube doesn't use yet: it sends no events. Cube keeps no auth or config of its own.
+- **The engine:** `buildCubeEngine(config, tracerService)` builds Legend's implementation of the `CubeEngine` port.
+  `config` is the engine client's configuration (`CubeEngineConfig`); Legend Query passes its own engine server URL
+  and options, so Cube talks to the engine its query editor uses.
+- **The models:** `new LocalModelCatalog(engine)`. It offers `BUNDLED_MODELS` (the "Northwind (Cube fixture)" model)
+  and caches each model's outline: its tables, for the source picker, and its runtimes' connections with their
+  database types, which Drop, Slice, Limit and Distinct need on some databases (PLAN §11.4). Users can also paste a Pure
+  model.
+
+Render the page with `<CubeEditor host={host} />`, and pass `initialDocument` to open a given cube. The page's state
+lives as long as the page; Legend Query makes a new host on each visit.
+
+**The bundled model runs only on an engine that allows LocalH2.** It sets up Northwind in an in-memory H2 database
+through its connection's `testDataSetupSqls`. On an engine that forbids LocalH2, its queries don't run.
+
+## Shortcuts
+
+A Legend application binds keys only through its plugins. The host returns the page's commands from one of its
+plugins:
+
+```ts
+override getExtraKeyedCommandConfigEntries(): KeyedCommandConfigEntry[] {
+  return collectKeyedCommandConfigEntriesFromConfig(LEGEND_CUBE_COMMAND_CONFIG);
+}
+```
+
+The page registers the commands while it is open: F9 runs the query, and Ctrl+Z or Cmd+Z undoes.
+
+## The stylesheet
+
+- Import `@finos/legend-cube-builder/lib/index.css` in the host's stylesheet (Legend Query does it in
+  `legend-application-query-bootstrap/style/index.scss`). The page's root element has the class `legend-cube`.
+- The page uses Tailwind classes. The host's Tailwind build must scan the builder's sources: Legend Query's deployment
+  scans `../legend-*/src/**/*.tsx`. So Tailwind classes go in `.tsx` files only.
+- React Flow's stylesheet comes with the canvas. Load the page lazily, as Legend Query does, to keep it and the page's
+  libraries out of the host's main bundle.
+
+## The dev loop
+
+1. Start an engine on `localhost:6300` that allows LocalH2: legend-engine's `org.finos.legend.engine.server.Server`
+   from an IDE, or the repo's docker compose
+   (`fixtures/legend-docker-setup/grammar-test-setup/grammar-test-setup-docker-compose.yml`). Check it with
+   `curl -s localhost:6300/api/server/v1/info`.
+2. Run `yarn build` once: `yarn dev:ts` doesn't build the stylesheets.
+3. Run `yarn dev:ts` and `yarn dev:query`, and open `http://localhost:9001/query/cube`.
+4. Run `yarn workspace @finos/legend-cube-builder dev:sass` to rebuild the stylesheet as you change it (the root
+   `yarn dev:ts` already rebuilds the TypeScript).
+
+If Tailwind classes seem to do nothing, the deployment's Tailwind watcher may have stopped: it exits when
+`yarn dev:query` runs without a terminal. Restart it in a terminal of its own with
+`yarn workspace @finos/legend-application-query-deployment dev:tailwindcss`, or rebuild once with `build:tailwindcss`
+(again after each new class).
+
+**A second checkout.** To run a second copy next to the first (another git worktree, say), give it its own port and
+skip the watchers you don't need: in that checkout, run `yarn install`, `yarn build` and
+`yarn workspace @finos/legend-application-query-deployment setup` once, then
+`yarn workspace @finos/legend-application-query-deployment build:tailwindcss` and
+`yarn workspace @finos/legend-application-query-deployment dev:webpack --port 9002`, and open
+`http://localhost:9002/query/cube`. The dev server serves the packages' built `lib/`, so rebuild what you change
+(`yarn workspace @finos/legend-cube-builder build:ts`, and `@finos/legend-cube`'s) before looking, or run `yarn dev:ts`.
+
+The manual check of the whole page is the plan's Part B (PLAN §11.2).

package/docs/testing.md

@@ -0,0 +1,83 @@
+# Testing Legend Cube's builder
+
+The builder has two test groups:
+
+- **`core`** (the default group): unit tests and jsdom page tests against a fake engine. No engine needed:
+  `TEST_GROUP=core yarn workspace @finos/legend-cube-builder test`.
+- **`engine-roundtrip`**: tests against a real engine on `localhost:6300`, in files named
+  `*.engine-roundtrip-test.ts`: `TEST_GROUP=engine-roundtrip yarn workspace @finos/legend-cube-builder test`.
+
+A plain `yarn workspace @finos/legend-cube-builder test` runs both, so it fails without an engine. Add a path pattern to
+run some files, e.g. `TEST_GROUP=core yarn workspace @finos/legend-cube-builder test source-picker`. The core
+(`@finos/legend-cube`) has no engine tests.
+
+## Page tests, against a fake engine
+
+- `const { host, fake } = TEST__createCubeHost()` gives a host over `createFakeCubeEngine()`'s engine, and `fake`,
+  its Jest mocks, answering from `FAKE_NORTHWIND_OUTLINE` and `FAKE_NORTHWIND_SCHEMAS`. Override an answer per test,
+  e.g. `fake.execute.mockRejectedValueOnce(…)`, or pass answers to `TEST__createCubeHost(answers)`.
+- `TEST__renderInCubeApplication(<CubeEditor host={host} />, host.applicationStore, LEGEND_CUBE_TEST_ID.EDITOR)`
+  renders the page in a Legend application and waits for it.
+- A test of one part of the page makes the state itself, `new CubeEditorState(host, document)`, and renders the part
+  with it, e.g. `<CubeCanvas editorState={editorState} />` and `<CubeNodeEditorPanel editorState={editorState} />`
+  (as `CubeJoinEditor.test.tsx` does). `TEST__importDocument(editorState, document)` then imports a cube and waits
+  for its tables to be typed again, so nothing changes after the test. A `<CubeEditor>` test has no handle on the
+  state, so it imports through the Import dialog.
+- `TEST__findCanvasNode(id)`, `TEST__getCanvasNodes()` and `TEST__getCanvasNodeTooltip(node)` read the canvas.
+- `src/__test-utils__/CubeNorthwindTestQueries.ts` has the Northwind tables' columns and ready-made queries, e.g.
+  `sliceQuery()`.
+
+What jsdom can't do:
+
+- **Fit the canvas.** jsdom measures nothing, so React Flow never reports the nodes measured and the refit never runs.
+  Check fitting in a browser (PLAN §11.2 Part B).
+- **Show Chrome's own behaviour**, e.g. its date input sending React no Enter key.
+- **Print a failing comparison of two queries.** A query holds `BigInt`s, which Jest can't print, so a failing
+  `toBe` between queries crashes the worker. Compare them as booleans: `expect(a === b).toBe(true)`.
+
+Drag and drop goes through react-dnd's HTML5 backend: fire `dragStart`, `dragEnter`, `dragOver`, `drop` and
+`dragEnd` on the elements.
+
+**Proving a test.** To show a new test fails without the code it covers, change the code in a copy of the package
+outside the checkout, never in place: a running `yarn dev:ts` rebuilds `lib/` from the changed file, and the dev server
+would serve it.
+
+## Engine tests
+
+- **The engine:** a local legend-engine, or the repo's docker compose
+  (`fixtures/legend-docker-setup/grammar-test-setup/grammar-test-setup-docker-compose.yml`), on `localhost:6300`. CI
+  runs the group on that docker image.
+- **No `fetch` in Jest:** the repo's Jest setup blocks it. Engine tests reach the engine through axios: the
+  `CUBE_ENGINE_TEST__*` helpers (`src/__test-utils__/CubeEngineTestSupport.ts`) for direct calls, and
+  `V1_createEngineBackedCubeEngine()` (`src/graph-manager/protocol/pure/v1/__test-utils__/`). The latter returns
+  `{ engine, calls }`: a real `V1_LegendCubeEngine` whose client calls are spied onto those helpers (and legend-graph's
+  `ENGINE_TEST_SUPPORT__grammarToJSON_model`), and the spies. Make it in `beforeEach` or in the test: the repo's Jest
+  config restores mocks before each test, so an engine made in `beforeAll` would call the real client, and the
+  blocked `fetch`.
+- **Assert meaning, not text.** The CI engine image changes with every engine merge, so assert row counts, the set of
+  keys returned, types and nullability, not SQL or Pure formatting, and never an engine answer that is a known
+  defect.
+- **Rows come back in the database's order** unless a Sort reaches the node that runs, and H2's order changes between
+  queries, so compare counts and sets, never positions, without a Sort. Facts of the Cube Northwind data a test may
+  rely on: ORDERS has 830 orders, `ORDER_ID` running from 10248 to 11077 with no gap. Avoid comparing or sorting on its
+  32-bit `REAL` columns (`FREIGHT`, `UNIT_PRICE`, `DISCOUNT`), where exact equality silently matches nothing.
+- `src/__tests__/LegendCubeNorthwind.engine-roundtrip-test.ts` is the slice's automated acceptance (PLAN §11.2 Part
+  A). It logs the engine's commit.
+- `src/__tests__/LegendCubeOperations.engine-roundtrip-test.ts` checks each operation: its lambda as the engine parses
+  the printed Pure, its typing against Cube's inferred schema, and its rows. Its helpers are in
+  `src/__test-utils__/CubeOperationsTestUtils.ts`; they take any `CubeEngine` and import no `V1_*` class.
+- **Sort descending in order tests.** H2 scans ORDERS in ascending `ORDER_ID` order, so a test that sorts ascending,
+  or numbers rows by `ORDER_ID`, passes without the sort; the operations tests sort descending, with a control test
+  pinning H2's own order.
+- **Database workarounds** (PLAN §11.4) are checked two ways. The operations tests write them for `SqlServer` and run
+  them on the fixture's H2, which takes both forms, so their rows can be compared with the native forms'.
+  `src/__tests__/LegendCubeDialects.engine-roundtrip-test.ts` plans them, never running anything, on a test-only copy
+  of the fixture model with a static connection per database type (`CUBE_ENGINE_TEST__generatePlanSql`), and checks
+  facts about the SQL: row numbers in the Sort's order, no `limit m,n`, no `top N distinct`. A check that should catch
+  a missing workaround must fail without it: run it once with the workaround off before relying on it.
+- `src/__tests__/CubeNorthwindRelationTypes.json` records the engine's relation type for every table of the bundled
+  model. If the test comparing with it fails, the engine's typing changed: check the change, then record the file
+  again by hand.
+
+The engine tests in `src/__tests__/` import `V1_*` classes there, as an exception to the V1 rule: they need both the
+`v1/` adapter and `stores/`, which the import-hierarchy lint rule keeps apart.

package/lib/__lib__/LegendCubeCommand.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 { CommandConfigData } from '@finos/legend-application';
+export declare enum LEGEND_CUBE_COMMAND_KEY {
+    EXECUTE = "legend-cube.execute",
+    UNDO = "legend-cube.undo"
+}
+/** Keys as `KeyboardEvent.code` names */
+export declare const LEGEND_CUBE_COMMAND_CONFIG: CommandConfigData;
+/** How the buttons' tooltips name the shortcuts */
+export declare const EXECUTE_SHORTCUT_LABEL = "F9";
+export declare const UNDO_SHORTCUT_LABEL = "Ctrl+Z / Cmd+Z";
+//# sourceMappingURL=LegendCubeCommand.d.ts.map

package/lib/__lib__/LegendCubeCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegendCubeCommand.d.ts","sourceRoot":"","sources":["../../src/__lib__/LegendCubeCommand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAOnE,oBAAY,uBAAuB;IACjC,OAAO,wBAAwB;IAC/B,IAAI,qBAAqB;CAC1B;AAED,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,EAAE,iBAUxC,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,mBAAmB,mBAAmB,CAAC"}

package/lib/__lib__/LegendCubeCommand.js

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+// The Cube page's keyboard shortcuts (spec §17.12, PLAN §3.5). A Legend
+// application binds keys only through its plugins, so the host contributes
+// this config from one of its plugins (`getExtraKeyedCommandConfigEntries`);
+// the page registers the commands while it is open.
+export var LEGEND_CUBE_COMMAND_KEY;
+(function (LEGEND_CUBE_COMMAND_KEY) {
+    LEGEND_CUBE_COMMAND_KEY["EXECUTE"] = "legend-cube.execute";
+    LEGEND_CUBE_COMMAND_KEY["UNDO"] = "legend-cube.undo";
+})(LEGEND_CUBE_COMMAND_KEY || (LEGEND_CUBE_COMMAND_KEY = {}));
+/** Keys as `KeyboardEvent.code` names */
+export const LEGEND_CUBE_COMMAND_CONFIG = {
+    [LEGEND_CUBE_COMMAND_KEY.EXECUTE]: {
+        title: 'Execute the query',
+        defaultKeyboardShortcut: 'F9',
+    },
+    [LEGEND_CUBE_COMMAND_KEY.UNDO]: {
+        title: 'Undo the last change',
+        defaultKeyboardShortcut: 'Control+KeyZ',
+        additionalKeyboardShortcuts: ['Meta+KeyZ'],
+    },
+};
+/** How the buttons' tooltips name the shortcuts */
+export const EXECUTE_SHORTCUT_LABEL = 'F9';
+export const UNDO_SHORTCUT_LABEL = 'Ctrl+Z / Cmd+Z';
+//# sourceMappingURL=LegendCubeCommand.js.map

package/lib/__lib__/LegendCubeCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegendCubeCommand.js","sourceRoot":"","sources":["../../src/__lib__/LegendCubeCommand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,oDAAoD;AAEpD,MAAM,CAAN,IAAY,uBAGX;AAHD,WAAY,uBAAuB;IACjC,0DAA+B,CAAA;IAC/B,oDAAyB,CAAA;AAC3B,CAAC,EAHW,uBAAuB,KAAvB,uBAAuB,QAGlC;AAED,yCAAyC;AACzC,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,CAAC,uBAAuB,CAAC,OAAO,CAAC,EAAE;QACjC,KAAK,EAAE,mBAAmB;QAC1B,uBAAuB,EAAE,IAAI;KAC9B;IACD,CAAC,uBAAuB,CAAC,IAAI,CAAC,EAAE;QAC9B,KAAK,EAAE,sBAAsB;QAC7B,uBAAuB,EAAE,cAAc;QACvC,2BAA2B,EAAE,CAAC,WAAW,CAAC;KAC3C;CACF,CAAC;AAEF,mDAAmD;AACnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC"}

package/lib/__lib__/LegendCubeHelpText.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export declare const CUBE_NODE_HELP_TEXT: Readonly<Record<string, string>>;
+/** The tooltip of the editor's Select link (spec §17.9) */
+export declare const SELECT_NODE_TOOLTIP = "Selects this node as active and its output will be shown in the grid once query is executed.";
+//# sourceMappingURL=LegendCubeHelpText.d.ts.map

package/lib/__lib__/LegendCubeHelpText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LegendCubeHelpText.d.ts","sourceRoot":"","sources":["../../src/__lib__/LegendCubeHelpText.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhE,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,iGACgE,CAAC"}