From 362d5d1917b200c82b58143bfcb0f651d7dc408c Mon Sep 17 00:00:00 2001 From: Hassan Abedi Date: Thu, 11 Jun 2026 15:58:24 +0200 Subject: [PATCH] Add a Makefile target for plan viewer --- Makefile | 12 ++++++++++++ tools/plan-viewer/README.md | 37 +++++++++-------------------------- tools/plan-viewer/index.html | Bin 26085 -> 26536 bytes 3 files changed, 21 insertions(+), 28 deletions(-) diff --git a/Makefile b/Makefile index 3af3df8..207384a 100644 --- a/Makefile +++ b/Makefile @@ -99,6 +99,18 @@ export-fixtures: ## Regenerate plan JSON for every tools/exporter/examples/*.sce examples: export-fixtures ## Regenerate fixtures from scenarios and run them through plan-runner against their oracles. @cargo test -p plan-runner --test examples +VIEWER_PORT ?= 8000 + +.PHONY: viewer +viewer: ## Serve the repository over HTTP for the plan viewer (override the port with VIEWER_PORT=...) + @if ! command -v python3 >/dev/null 2>&1; then \ + echo "python3 not found. Enter the dev shell with 'make shell' (or 'nix develop') first."; \ + exit 1; \ + fi + @echo "Plan viewer: http://localhost:$(VIEWER_PORT)/tools/plan-viewer/index.html" + @echo "Example: http://localhost:$(VIEWER_PORT)/tools/plan-viewer/index.html?fixture=../../crates/plan-runner/fixtures/two_atom_join.json" + @python3 -m http.server $(VIEWER_PORT) + .PHONY: shell shell: ## Enter the Nix dev shell defined in flake.nix @nix develop diff --git a/tools/plan-viewer/README.md b/tools/plan-viewer/README.md index b1e2d51..6917959 100644 --- a/tools/plan-viewer/README.md +++ b/tools/plan-viewer/README.md @@ -1,37 +1,18 @@ -# Plan Viewer +## Query Plan Viewer -A static HTML viewer for `plan-runner` fixtures. -It renders the plan DAG, the input facts, and the relation computed at every plan node, so a fixture can be inspected without reading raw JSON. +A static HTML viewer for `plan-runner` JSON files (the fixtures). -## Usage +### Usage -Open [`index.html`](index.html) in a browser, then drop a fixture from `crates/plan-runner/fixtures/` onto the page or pick one with the file input. +Open [`index.html`](index.html) in a browser, then drop a JSON file from [`crates/plan-runner/fixtures/`](../../crates/plan-runner/fixtures) onto the page. -When the repository is served over HTTP, a fixture can also be loaded through a query parameter: +Alternatively, you can run the commands below to serve the viewer locally: ```sh -python3 -m http.server 8000 -# then open: -# http://localhost:8000/tools/plan-viewer/index.html?fixture=../../crates/plan-runner/fixtures/two_atom_join.json +make shell # Go into the Nix shells +make viewer ``` -## What It Shows +Then open the following URL in your browser (replace `two_atom_join.json` with the name of the plan you want to view) -- **Plan DAG**: one box per plan node, laid out left to right by join depth, with `L` and `R` labels on join inputs and the root node marked. - Each box shows the node's output columns and row count. -- **Selected Node**: a plain-language description of the operator, its output columns, and the full relation computed at that node. - Wildcard columns (names starting with an underscore) are dimmed. -- **Result Bindings**: the root relation projected to the fixture's `expected_bindings` columns, with a per-row check against the oracle and a list of any expected rows the plan did not produce. -- **Input Facts**: one table per relation in the fixture's schema. - -The header badge reports whether the evaluated bindings match the fixture's `expected_bindings` as a multiset, mirroring `plan_runner::verify`. - -## Scope - -The viewer re-implements the scan, semijoin, and natural join semantics of `crates/query-ops` and the execution order of `crates/plan-runner` in JavaScript, for display only. -The Rust crates and their tests remain the correctness oracle; if the two ever disagree, the Rust behavior wins and the viewer has a bug. - -Unsupported cases: - -- plan node actions other than `scan` and `join` -- fixtures without a `query` and `schema` block +http://localhost:8000/tools/plan-viewer/index.html?fixture=../../crates/plan-runner/fixtures/two_atom_join.json diff --git a/tools/plan-viewer/index.html b/tools/plan-viewer/index.html index de59322ef03709ee0895d61bc61a8c5eac7e918a..3965e010d4b4a7e82b6864fd89d11bc1edb63c3c 100644 GIT binary patch delta 788 zcmaEQnsLQ>#tj@6YQdgPKAwK=@$QZR3bqPH7S>$J`FX`93OyGlR_<7C{`0 z#*?cZ>=}(W?{=8TIC-&?h-kQiwnA=VMQ~1jiGr2_)TqggPD+z~oMfau6top`5-amd zOZ0LRD_l|wN-`9*AO=r9;dEf~8D}YOkO?q-tDKc4cQ{LPg7kr{-~86umytz5U%_ay zm8*)1HJ1VyKpa?Mq+qL1l30|UTB28>psnEN@8TLCK6#<51c#xSf|Y`yndanLS7|9! zUAdJCwh9`Rh6>sWm6LC}#)(!K)+(q}=T_G0D5z9d7(qCbecbFPGrEa->*gdTrRFH< zKy6k~sIXF~FjCM~&?wGKNma15wN+5^QBts1&^0ttuu?G7M5wH^Qm8ai&{Z&j3T@uz zwotr2GfhFGASW?TFR>&)w^%_2DkSD9q*fH<7nP(IDHJEC<|P(o<|}BF%%1UQ!5g43vyD6^|kb1 zYU=f}iu3a{brh5ov=OG4XJjU4C}boSE9B)XfL)>ha+E@4YKfjgP-&h*LT+MqD%3{Z zw9JZ<(xTMj1ck)B6os7p#1w^+447V)4PwtD8ltS?&ic2O}rO0q0?BBd8&X^ql`-bTE delta 436 zcmZ2+p7H5v#tj@63eNsM@$QZR3bqR72G(53`FX`93PJwiP%$I3&3YC=9E>KD8y)N! zO*S8Nn8-MJu9J*pxPrDqPGV(#X^CELVued;K}m*!7Ra#4)lN#2gPcSJJruMRauX|p zbMi|Rv_M8qzT$LX@@;2nc933Yf1k-aos}j}ah75SsSNTD-~8X%mvM4{t4h6szJif8 zmjW0-TvTDCV5?A)Sd^YxqE~?`Rf!~3si3Xk=kMYg?*TGGL0dtiI5Q;d&h*2smO)aX7QBp|EOHqhXDo)Nw%}tC^Qb@|lPtGo$ER!I~ Vot9ZqQd*R%r=)4UxirC;9RLP;gL41?