From f5a146776e5d984d729b9f390538e8d8620f1f23 Mon Sep 17 00:00:00 2001 From: Hassan Abedi Date: Thu, 11 Jun 2026 16:00:58 +0200 Subject: [PATCH] WIP --- tools/plan-viewer/README.md | 31 +++++++------------------------ 1 file changed, 7 insertions(+), 24 deletions(-) diff --git a/tools/plan-viewer/README.md b/tools/plan-viewer/README.md index 5ab043c..63bb84d 100644 --- a/tools/plan-viewer/README.md +++ b/tools/plan-viewer/README.md @@ -1,37 +1,20 @@ ## Query Plan Viewer A static HTML viewer for `plan-runner` JSON files (the 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. +It evaluates a fixture in the browser and renders the plan DAG, the input facts, the relation computed at every plan node, and a per-row comparison against `expected_bindings`. -### Usag +### 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. -When the repository is served over HTTP, a fixture can also be loaded through a query parameter: +When the repository is served over HTTP (`make viewer`), a fixture can also be loaded through a query parameter: -```sh -make viewer # Or `VIEWER_PORT=9000 make viewer` -# Then open: -# http://localhost:8000/tools/plan-viewer/index.html?fixture=../../crates/plan-runner/fixtures/two_atom_join.json +```text +http://localhost:8000/tools/plan-viewer/index.html?fixture=../../crates/plan-runner/fixtures/two_atom_join.json ``` -## What It Shows - -- **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 viewer re-implements the operator semantics of `crates/query-ops` and `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 +Only `scan` and `join` actions are supported.