sql-code-graph 1.36.2__tar.gz → 1.37.0__tar.gz

{sql_code_graph-1.36.2 → sql_code_graph-1.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.36.2
+Version: 1.37.0
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph

sql_code_graph-1.37.0/plan/sprints/viz_usability_neighborhood_highlight.md

@@ -0,0 +1,443 @@
+# Feature Plan: `sqlcg viz` Usability — neighborhood-highlight, edge contrast, sane defaults
+
+**Status:** REVIEWED (plan-reviewer PASSED, no blockers; two required amendments folded in — see "Plan-reviewer required amendments" below)
+**Owner:** architect-planner
+**Branch (impl):** `feat/viz-usability-highlight`
+**Base:** `master` (v1.36.1 on disk; see version note below) / schema v11
+**Scope class:** PURE front-end / HTML-emitter change. No indexer / parser / graph-model / DB-schema change. **No re-index required.**
+
+> ⚠ **Version note for the developer:** the brief said v1.36.0 but the worktree's
+> [`pyproject.toml`](pyproject.toml) and [`src/sqlcg/__init__.py`](src/sqlcg/__init__.py)
+> are already at **`1.36.1`**. This is new interactive surface → **MINOR** bump →
+> ship as **`1.37.0`**. Reconcile against `master` HEAD at implementation time (if
+> master has advanced past 1.36.1, bump the minor from whatever the current value is).
+
+---
+
+## Plan-reviewer required amendments (folded in 2026-06-15)
+
+The plan-reviewer PASSED this plan with no blockers, conditional on TWO required
+amendments. Both are now binding for implementation:
+
+### Amendment 1 — AC2's highlight-wiring guard must be BEHAVIORAL, not substring
+
+`jsdom` is **NOT installed** in this repo, so AC2's "highlight is wired" guard
+**must NOT rely on a JSDOM hover test** and **must NOT be satisfiable by an
+orphaned `adj.get(` substring** (a dead reference would pass a naive substring
+grep while delivering nothing).
+
+The binding assertion is therefore:
+
+- The `linkColor` / `linkWidth` / directional-arrow accessors and the
+  `nodeCanvasObject` (`drawNodeCanvas`) **must REFERENCE the highlight state**
+  (`highlightSet` / `highlightId`).
+- `onNodeHover` / `onNodeClick` / `onBackgroundClick` **must ASSIGN that state**
+  (set `hoveredNode` / toggle `pinnedNode` / clear `pinnedNode`).
+- **Best path (adopted):** factor the 1-hop highlight-set derivation into a tiny
+  **pure helper** `computeHighlightSet(adj, id)` and assert it **directly in a
+  `uv run`-able Node harness** (the `node --eval` / `node --check` style the
+  project already uses — `node` is on PATH, used by the self-containment e2e).
+  The Python test extracts the helper source from the emitted HTML, evals it in
+  Node with a sample `adj`, and asserts the returned set equals focus ∪ its 1-hop
+  neighbors. **Substring presence alone is insufficient** and is explicitly
+  rejected as the AC2 guard.
+
+### Amendment 2 — highlight repaint must be styling-only (no layout re-seed)
+
+The hover / click highlight handlers **must NOT call `refresh()` or
+`Graph.graphData()`**. Both re-seed the force layout, causing the graph to "jump"
+at the live 3069-node / 6671-link scale on every hover.
+
+- Repaint must go through **styling-only accessors that close over `highlightId`
+  / `highlightSet`** (e.g. force-graph's per-frame canvas repaint, which re-reads
+  the closure-visible state every tick — no data rebuild). The handlers only
+  mutate `hoveredNode` / `pinnedNode`; the next animation frame repaints with the
+  new state.
+- This is stated explicitly in the code (a comment at the highlight handlers) and
+  is the reason `refresh()` (which calls `graphData(currentData())`) is reserved
+  exclusively for FILTER changes (facets / mindeg / search / ego), never for
+  highlight.
+
+---
+
+## Summary
+
+`sqlcg viz` (shipped #165, v1.35.0) emits a self-contained force-graph HTML from the
+live graph. At real scale (live reference [`table_graph.html`](table_graph.html):
+**3069 nodes / 6671 links**) it is a low-contrast hairball with no way to trace one
+table's lineage. This sprint wires the **already-baked `DATA.adj`** into a
+hover/click neighborhood-highlight, makes edges legible, and changes the default
+view to hide island nodes and `temp` clutter — all in the emitter template + a
+small amount of CLI/data wiring, with **zero data-model change**.
+
+---
+
+## Live-inspection findings (ground truth — verified this session)
+
+All numbers below come from (a) running `uv run sqlcg viz` against a seeded DuckDB
+in `/tmp` and inspecting the emitted HTML, and (b) parsing the live reference
+[`table_graph.html`](table_graph.html) at repo root (regenerated from the real DWH).
+
+| Question | Answer (verified) |
+|----------|-------------------|
+| **Where is the emitter template?** | [`src/sqlcg/viz/assets/template.html`](src/sqlcg/viz/assets/template.html) (12 KB). The JS is one `<script>` block (lines 40–273); the lib is the other `<script>` block (lines 3–5). Baked by [`render_html`](src/sqlcg/viz/render.py) via `/*__DATA__*/` etc. placeholders. |
+| **Where is the data built?** | [`src/sqlcg/viz/data.py`](src/sqlcg/viz/data.py) `build_viz_data()` → `{nodes, links, adj}`. |
+| **CLI entry** | [`src/sqlcg/cli/commands/viz.py`](src/sqlcg/cli/commands/viz.py) `viz_cmd`. |
+| **Does `DATA.links` carry direction?** | **YES.** Each link is `{"source": <source table>, "target": <write target>, "n": <count>}`. Direction is **source-table → consumer/write-target** (`data.py` `_Q_QUERY_LINKS`: `dst_key` of `SELECTS_FROM` is the source table; `q.target_table` is the write target). Live sample: `{"source":"ba.wtda_inkoop_order","target":"ia_analytics.ba_wtda_inkoop_order","n":33}`. **→ directional arrows are feasible (no data change needed).** |
+| **`DATA.adj` shape** | Undirected `{id: [neighbor, …]}` (sorted). Live: 2926 keys (nodes with ≥1 neighbor). Built in `data.py` from the collapsed link set. The template *also* rebuilds an identical `adj` Map client-side (lines 51–58) for ego-mode — **already present, used only by ego-mode today.** |
+| **Current default-visible kinds** | `table`, `view`, **`temp`** ON; `cte`, `derived` OFF. Asserted as a literal string in TWO tests (see "Tests that MUST change"). |
+| **Current `min deg` default** | `value="0"` (islands visible). |
+| **Current hover/click affordance** | `onNodeClick` sets `focusNode` (only used by ego-mode toggle); `onNodeHover` sets `hoveredNode` (only used to force a label). **There is NO neighborhood highlight today** — the headline gap. |
+| **Node-kind histogram (live)** | table 1150, **temp 804 (26%)**, view 582, cte 530, derived 3. Confirms the `temp`-clutter claim. |
+| **Island (deg==0) count (live)** | **143 of 3069 (~4.7%)**. Confirms islands exist; brief says keep them in DATA, hide by default. |
+| **Self-containment test** | [`tests/e2e/test_viz_cli_e2e.py::test_viz_html_is_self_contained_and_node_check_passes`](tests/e2e/test_viz_cli_e2e.py) — bans external-load tokens, asserts exactly **2** `<script>` blocks, runs `node --check` on each. **Adding a 3rd script block would break this** (the assertion `len(blocks) == 2`). All new JS goes inside the existing JS block. |
+
+**Total existing viz tests: 36** (e2e 9, integration/data 7, unit render 6, unit
+facets 8, unit config 6). The brief's "~36" is exact.
+
+---
+
+## Scope
+
+### In Scope
+1. **Neighborhood-highlight on hover + click-to-pin** using the existing `DATA.adj`
+   (client `adj` Map). Hover highlights transiently; click pins; click-elsewhere /
+   Escape clears. Highlight = focus node + direct (1-hop) neighbors + incident
+   edges bright; everything else dimmed. **Headline deliverable.**
+2. **Edge visibility / contrast** — raise base edge opacity/width so edges are
+   legible on `#0d1117`; highlighted edges bright + directional **arrows**
+   (producer→consumer; direction confirmed available); dimmed edges very faint.
+3. **Default `min deg` filter = 1** — hide deg-0 islands by default; existing
+   `min deg` number input stays the explicit "show isolated nodes" control (set its
+   default `value="1"`; user types `0` to reveal islands). Islands remain in `DATA`.
+4. **`temp` default-OFF** — default-visible kinds become `table` + `view` only;
+   `cte`/`derived`/`temp` OFF by default, all still toggleable chips.
+
+### Non-Goals (explicit boundaries)
+- **No data-model / `build_viz_data` query change.** `nodes/links/adj` shape is
+  unchanged. (Item 3 may add ONE derived convenience but see Step 2.3 — preferred
+  approach uses the existing `mindeg` input, no data change.)
+- **No new `<script>` block, no external resource, no CDN/fetch/import.**
+- **No multi-hop traversal UI** beyond an *optional* single "expand one more hop"
+  affordance (Step 1.4) — and even that is in-scope-optional, decided below as
+  **deferred** to keep the headline tight (see Decision D2).
+- **No tags/jobs source change.** Tags/jobs only exist when the user passes
+  `--tags`/`--jobs`. The legend/dropdown already render empty cleanly; this sprint
+  only confirms that and does not invent a source.
+- **No new CLI flag** unless a default needs to be overridable (none identified;
+  defaults are baked into the template, consistent with current design).
+- No indexer/parser/lineage/perf-hot-path code. The frozen perf-invariant suites
+  ([`test_perf_scaling_guard.py`](tests/unit/test_perf_scaling_guard.py),
+  [`test_bulk_upsert_invariant.py`](tests/unit/test_bulk_upsert_invariant.py),
+  [`test_upsert_batch_invariant.py`](tests/unit/test_upsert_batch_invariant.py),
+  [`test_T09_01_qualify_once.py`](tests/unit/test_T09_01_qualify_once.py)) are not
+  touched and must stay green unmodified.
+
+---
+
+## Design
+
+### Affordance specification (Item 1 — the core deliverable)
+
+State model (all client-side, inside the existing JS block in
+[`template.html`](src/sqlcg/viz/assets/template.html)):
+
+- New state: `let pinnedNode = null;` (the click-pinned focus for highlight).
+  Reuse existing `hoveredNode`. Do **not** overload `focusNode` (that is ego-mode's
+  variable — keep highlight independent of ego-mode so the two compose).
+- **`highlightId` = `pinnedNode ?? hoveredNode`** (pin wins; hover is transient).
+- Derived per-render: `highlightSet` = `highlightId` ∪ `adj.get(highlightId)`
+  (the 1-hop neighborhood) — computed from the **existing client `adj` Map**, which
+  is built from `DATA.adj`/`DATA.links` (no data change).
+- **Hover** (`onNodeHover(n)`): set `hoveredNode = n?.id ?? null`; if no pin, this
+  drives the highlight. Re-render via the graph's paint (no full `graphData`
+  rebuild needed for highlight — see "render mechanics" below).
+- **Click** (`onNodeClick(n)`): toggle pin — `pinnedNode = (pinnedNode === n.id) ? null : n.id`.
+  A pinned node stays highlighted after the cursor leaves.
+- **Clear:** click on empty background (`onBackgroundClick` → `pinnedNode = null`)
+  **and** `Escape` key → `pinnedNode = null`. Hover-away clears the transient hover.
+- **Compose with ego-mode:** ego-mode (existing) filters the node SET; highlight
+  only changes paint styling within whatever is visible. They are orthogonal.
+
+Render mechanics (decision, see D1): highlight is a **paint-time styling concern**,
+not a filter. When `highlightId` is set:
+- Nodes in `highlightSet` paint at full alpha + a focus ring on the
+  `highlightId` itself; nodes outside paint dimmed (low alpha).
+- Links with **both** endpoints in `highlightSet` (i.e. incident to the focus,
+  since highlightSet is focus+neighbors) paint bright + arrow; all other links
+  paint very faint.
+- When `highlightId` is null → normal styling (all at the new legible base level).
+
+This requires: a `linkColor`/`linkWidth`/`linkDirectionalArrowLength` accessor (or
+`linkCanvasObject`) that reads `highlightId`, and the existing `nodeCanvasObject`
+(`drawNodeCanvas`) extended to dim/brighten based on `highlightSet`. The graph is
+re-painted by calling a light `Graph.nodeColor`/refresh trigger on hover/click; we
+will trigger a repaint without rebuilding `graphData` (force-graph repaints every
+frame, so simply updating the closure-visible `highlightId`/`highlightSet` and
+nudging the engine — e.g. `Graph.nodeCanvasObject(drawNodeCanvas)` re-set, or a
+`Graph` refresh call — is sufficient; the developer picks the lightest force-graph
+1.49.5 API that re-renders without re-running the layout).
+
+### Edge visibility (Item 2)
+
+In [`template.html`](src/sqlcg/viz/assets/template.html):
+- Base edges: raise from the library default to a visible-but-quiet level
+  (e.g. `linkColor` → a mid-gray like `#3b4350` at moderate alpha, `linkWidth`
+  ≥ 1; exact values tuned at impl, must be visibly legible on `#0d1117`).
+- Highlighted edges: bright (e.g. near-white or the source schema color) + wider +
+  **directional arrow** (`linkDirectionalArrowLength`, `linkDirectionalArrowRelPos`)
+  pointing source→target (producer→consumer). Direction is available in `DATA.links`.
+- Dimmed edges (highlight active, not incident): very low alpha so the neighborhood
+  stands out.
+- **Arrows in the no-highlight base state:** decision D3 — keep base arrows OFF
+  (3069/6671 arrows is itself clutter); show arrows ONLY on highlighted edges. This
+  keeps the resting view clean and makes direction legible exactly when the user is
+  tracing.
+
+### Default filters (Items 3 & 4)
+
+- **Item 3 (islands):** change the `min deg` input default from `value="0"` to
+  `value="1"` in [`template.html`](src/sqlcg/viz/assets/template.html) line 32. The
+  existing `currentData()` already filters `if (n.deg < md) continue;`. The input
+  label is updated to make the "isolated nodes" meaning explicit (e.g.
+  `min deg` stays, plus the bottom `#info` hint mentions "set min deg 0 to show
+  isolated tables"). **No data change**; islands stay in `DATA.nodes`. Verified:
+  143 island nodes exist and have `deg: 0`.
+- **Item 4 (temp off):** change `KIND_DEFAULT_ON` from
+  `new Set(['table', 'view', 'temp'])` to `new Set(['table', 'view'])`. `KNOWN_KINDS`
+  stays `['table','view','temp','cte','derived']` so `temp` remains a toggleable chip.
+
+### Empty tags/jobs legend (confirmation only)
+
+No code change expected. Confirm via the existing
+`test_viz_html_is_self_contained` + a new assertion that with no `--tags/--jobs`
+the tag-facet div and job `<select>` render with no rows (the `buildFacet(... TAGS.labels || [])`
+and `JOBS.labels || []` paths already handle empty). If a stray empty `<b>tag</b>`
+header looks broken when empty, hide the facet container when its label list is
+empty (minor, decided at impl).
+
+### Decisions
+
+- **D1 — highlight is paint-styling, not a filter.** Dim-don't-remove keeps spatial
+  context (you see where the neighborhood sits in the whole graph). Rationale: the
+  whole point is to read lineage *out of* the hairball, not replace it with ego-mode
+  (which already exists and removes context).
+- **D2 — "expand one more hop" is DEFERRED** (out of this sprint). Keep the headline
+  tight: 1-hop hover/click/pin. A 2-hop expander can be a fast follow once 1-hop
+  ships and is eyeballed. (Documented so the developer does not build it.)
+- **D3 — base arrows OFF, highlight arrows ON** (see Edge visibility).
+- **D4 — no new CLI flag.** Defaults live in the template, matching the existing
+  design where kind/mindeg defaults are template-baked.
+
+### Data Models / API Changes
+**None.** `build_viz_data()` output unchanged; `render_html` signature unchanged;
+CLI signature unchanged. This is entirely [`template.html`](src/sqlcg/viz/assets/template.html)
+plus the two version-bump files.
+
+### Dependencies
+None added. force-graph 1.49.5 stays vendored/inlined.
+
+---
+
+## Tests that MUST change (and why that is correct, not a violation)
+
+The brief says "all ~36 existing viz tests must pass **unmodified**." Two of them
+**cannot** — they pin the *old* default-kind string by exact match, and Item 4
+deliberately changes that default. These are **expected, intended assertion
+updates**, not regressions:
+
+| Test | File:line | Current assertion | Why it must change |
+|------|-----------|-------------------|--------------------|
+| `test_viz_kind_defaults...` (e2e) | [`tests/e2e/test_viz_cli_e2e.py:202`](tests/e2e/test_viz_cli_e2e.py) | `"KIND_DEFAULT_ON = new Set(['table', 'view', 'temp'])" in html` | Item 4 changes the default set; this assertion now pins the NEW set `['table', 'view']`. |
+| `test_kind_defaults...` (unit) | [`tests/unit/test_viz_render_self_contained.py:107`](tests/unit/test_viz_render_self_contained.py) | same string | same — update to `['table', 'view']`. |
+
+The developer **updates these two assertions** to the new default and adds a
+regression assertion that `temp` is in `KNOWN_KINDS` (still toggleable). **All other
+34 viz tests pass unmodified, and all frozen perf-invariant suites pass unmodified.**
+Flag for plan-reviewer: this is the one place "unmodified" is impossible by design.
+
+---
+
+## Implementation Steps
+
+### Phase 1 — Defaults (lowest-risk, unblocks the contrast work)
+
+**Step 1.1 — `temp` default OFF + `min deg` default 1.**
+- Files: [`src/sqlcg/viz/assets/template.html`](src/sqlcg/viz/assets/template.html)
+  (`KIND_DEFAULT_ON` line 75; `mindeg` input `value` line 32).
+- Update the two kind-default assertions (see table above) to `['table', 'view']`.
+- Acceptance: emitted HTML contains `KIND_DEFAULT_ON = new Set(['table', 'view'])`;
+  the `temp` chip is still present (in `KNOWN_KINDS`) and rendered `off`; `mindeg`
+  input has `value="1"`; a seeded deg-0 node is absent from the default
+  `currentData()` keep-set but present in `DATA.nodes`.
+
+### Phase 2 — Edge visibility (Item 2)
+
+**Step 2.1 — Legible base edges + dim/bright tiers.**
+- Files: `template.html` (graph init link accessors `linkColor`/`linkWidth`, and
+  the link styling used during highlight).
+- Acceptance: emitted HTML wires `linkColor`/`linkWidth` accessors (not library
+  defaults); base color is a non-transparent legible hex on dark bg; a highlight-
+  aware branch exists (asserted by presence of the `highlightId`/`highlightSet`
+  reference inside the link accessor). Manual: regenerated `table_graph.html` shows
+  visibly legible edges.
+
+**Step 2.2 — Directional arrows on highlighted edges only.**
+- Files: `template.html` (`linkDirectionalArrowLength` accessor returning 0 when no
+  highlight or edge not incident, >0 when incident).
+- Acceptance: emitted HTML contains `linkDirectionalArrow` wiring; the accessor is
+  gated on `highlightId` (base state → no arrows). Asserted by HTML substring +
+  a JSDOM check if feasible (see Test Strategy).
+
+### Phase 3 — Neighborhood highlight (Item 1 — headline)
+
+**Step 3.1 — Highlight state + 1-hop set from `adj`.**
+- Files: `template.html` — add `pinnedNode`, `highlightId` derivation,
+  `highlightSet` from the existing client `adj` Map. Wire `onNodeHover` (transient),
+  `onNodeClick` (toggle pin), `onBackgroundClick` (clear pin), `Escape` (clear pin).
+- Acceptance: emitted HTML contains the highlight handlers AND a reference to `adj`
+  inside them (proving the bake is wired, not orphaned). HTML substring assertions:
+  `onBackgroundClick`, `pinnedNode`, and `adj.get(` used in a highlight context.
+
+**Step 3.2 — Paint dim/bright for nodes + incident edges.**
+- Files: `template.html` — extend `drawNodeCanvas` to dim non-`highlightSet` nodes
+  and ring the focus node; link accessors (Step 2.1/2.2) already read `highlightSet`.
+  Ensure a repaint is triggered on hover/click WITHOUT re-running the force layout
+  (no `graphData()` rebuild for highlight — pick the lightest force-graph 1.49.5
+  refresh API).
+- Acceptance: HTML wires the dim/bright branch in `drawNodeCanvas` keyed on
+  `highlightSet`. JSDOM check (if feasible): after dispatching a synthetic hover on
+  a known node, the link accessor returns the bright width for an incident edge and
+  the dim width for a non-incident edge. Manual: regenerated `table_graph.html` —
+  hovering `ba.wtda_inkoop_order` lights its neighbors and dims the rest.
+
+### Phase 4 — Empty-facet polish + manual regen + version bump
+
+**Step 4.1 — Empty tag/job legend renders cleanly.**
+- Files: `template.html` (only if an empty facet container looks broken — hide
+  container when its label list is empty).
+- Acceptance: viz run with no `--tags/--jobs` produces an HTML where the tag-facet
+  has no chip rows and the job `<select>` has only the `all jobs` option; no JS
+  error (`node --check` green; JSDOM construct-without-throw if feasible).
+
+**Step 4.2 — Manual regenerate the reference artifact.**
+- Re-emit repo-root [`table_graph.html`](table_graph.html) from the live graph
+  (`uv run sqlcg viz` with the user's tags/jobs CSVs if used) so the committed
+  reference reflects the new defaults + interaction. Confirm self-containment
+  (no external token) and the new defaults in the regenerated file.
+- **MANUAL step** — the developer regenerates and the user eyeballs on Windows.
+  Not gated by CI (the artifact is gitignored/untracked per repo memory).
+
+**Step 4.3 — Version bump + lockfile.**
+- [`pyproject.toml`](pyproject.toml) + [`src/sqlcg/__init__.py`](src/sqlcg/__init__.py)
+  → `1.37.0` (reconcile minor against master HEAD); `uv lock`.
+
+---
+
+## Test Strategy
+
+> Name tests `test_<unit>_<scenario>_<expected>` and link this plan in the docstring.
+
+**Automated (CI-gated):**
+- *Self-containment unchanged* — the existing
+  `test_viz_html_is_self_contained_and_node_check_passes` must stay green: still
+  exactly **2** `<script>` blocks (all new JS goes inside the existing block), no
+  external-load tokens, `node --check` passes. (Unmodified.)
+- *New default kinds* — assert emitted HTML wires `['table', 'view']` ON and `temp`
+  remains in `KNOWN_KINDS` (toggleable). (Updates the 2 existing kind-default tests
+  + may add one new assertion.)
+- *Island default-hidden* — assert `mindeg` input `value="1"`; assert a seeded
+  deg-0 node is in `DATA.nodes` but excluded from the default keep-set logic.
+- *Highlight wiring present* — assert emitted HTML contains the hover/click/pin
+  handlers (`pinnedNode`, `onBackgroundClick`) AND that the highlight logic
+  references the baked adjacency (`adj.get(`), proving `DATA.adj` is wired, not
+  orphaned. This is the behavioral guard against shipping "a picture".
+- *Edge-styling wiring present* — assert `linkColor`/`linkWidth` accessors and a
+  `linkDirectionalArrow…` accessor gated on `highlightId`.
+- *JSDOM behavioral check (attempt; mark manual if jsdom unavailable)* — load the
+  emitted HTML in a Node/jsdom harness, stub `canvas`/`ForceGraph` minimally,
+  dispatch a synthetic node-hover, and assert the highlightSet resolves to focus +
+  its `adj` neighbors and that the link accessor returns bright-vs-dim accordingly.
+  **If jsdom + a force-graph stub proves infeasible in CI**, downgrade this to the
+  HTML-substring guards above (automated) + the manual eyeball (4.2), and say so in
+  the PR. State explicitly in the PR which highlight assertions are automated.
+
+**Manual (developer-run, user-eyeballed):**
+- Regenerate `table_graph.html` (Step 4.2); open on Windows via `file://`; confirm:
+  edges legible; hover lights neighborhood + arrows; click pins; Escape/background
+  clears; islands hidden by default and revealed at `min deg 0`; `temp` hidden by
+  default and reveals on chip toggle.
+
+---
+
+## Acceptance Criteria
+
+- [ ] **AC1 (self-containment invariant holds):** emitted HTML has exactly 2
+      `<script>` blocks, no external-load token, `node --check` passes on both.
+      *Verified by the unchanged self-containment e2e test.*
+- [ ] **AC2 (highlight wired to `adj`):** emitted HTML contains hover + click-pin +
+      background/Escape-clear handlers, and the highlight set is derived from the
+      baked adjacency (`adj.get(`) — not a no-op. *Verified by automated HTML
+      assertion + (if feasible) JSDOM hover check showing neighbor set = `adj`
+      neighbors.*
+- [ ] **AC3 (edges legible + directional on highlight):** `linkColor`/`linkWidth`
+      accessors present (non-default), and a directional-arrow accessor gated on
+      highlight. *Verified by automated HTML assertion; manual eyeball confirms
+      legibility + producer→consumer arrow direction.*
+- [ ] **AC4 (islands hidden by default, one click away):** `mindeg` default `value="1"`;
+      deg-0 nodes remain in `DATA.nodes`; setting `min deg 0` reveals them.
+      *Verified by automated assertion on `value="1"` + DATA presence; manual eyeball
+      for the reveal.*
+- [ ] **AC5 (`temp` default OFF, toggleable):** `KIND_DEFAULT_ON = new Set(['table', 'view'])`;
+      `temp` still in `KNOWN_KINDS` and rendered as an `off` chip. *Verified by the
+      updated automated kind-default assertions.*
+- [ ] **AC6 (empty facets render cleanly):** with no `--tags/--jobs`, no tag chips /
+      empty job dropdown, no JS error. *Verified by `node --check` + automated
+      assertion that the facet rows are empty.*
+- [ ] **AC7 (all other viz + frozen perf tests green):** the 34 unchanged viz tests
+      and the frozen perf-invariant suites pass unmodified. *Verified by full
+      `uv run pytest`.*
+- [ ] **AC8 (version bumped):** `1.37.0` in pyproject + `__init__` + `uv.lock`.
+
+---
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Adding a 3rd `<script>` block breaks the `len(blocks) == 2` self-containment assertion. | All new JS goes **inside** the existing JS block. Step guidance + AC1 guard. |
+| Highlight repaint re-runs the force layout → graph "jumps" on every hover. | Trigger a repaint WITHOUT `graphData()` rebuild (highlight is paint-only, D1). Developer uses the lightest force-graph 1.49.5 refresh path. |
+| JSDOM + force-graph stub may be infeasible in CI → highlight only "looks" wired. | Mandatory automated HTML guard that the handler references `adj.get(` (proves the bake is used); JSDOM is best-effort on top; manual eyeball closes the loop. The risk is "ships a picture" — AC2 is the explicit guard against it. |
+| "All 36 tests unmodified" is impossible (2 pin the old kind default). | Documented as intended assertion updates (see "Tests that MUST change"); plan-reviewer to confirm this exception. |
+| Base arrows on 6671 edges would add clutter (defeats the goal). | D3: arrows only on highlighted edges. |
+| Regenerated `table_graph.html` is untracked/gitignored (repo memory). | Step 4.2 is explicitly MANUAL, user-eyeballed, not committed/CI-gated. |
+
+---
+
+## Rollout / Rollback
+- Rollout: ships in the `1.37.0` viz PR; no migration, no re-index (front-end only).
+  Existing emitted HTML files keep working; users re-run `sqlcg viz` to get the new
+  interaction.
+- Rollback: revert the `template.html` (+ version) change; no data or schema impact.
+
+---
+
+### Deviations
+
+#### Deviation 1: repo-root `table_graph.html` not regenerated in this PR
+- **Reason**: Step 4.2 (regenerate the reference artifact) requires emitting from
+  the **live DWH graph** (`uv run sqlcg viz` against the indexed DuckDB). This task
+  is explicitly **INDEX-FREE / front-end only** — no DWH index was created and the
+  shepherd directed "no DWH index, no gain snapshot needed". The repo-root
+  `table_graph.html` is **untracked** (not in git, not committed) and the plan marks
+  Step 4.2 as a MANUAL, user-eyeballed step that is not CI-gated.
+- **Change**: The emitter `template.html` — the single source of every future
+  regeneration — carries the new defaults (`KIND_DEFAULT_ON=['table','view']`,
+  `mindeg=1`) and the highlight/edge interaction. The standing untracked
+  `table_graph.html` working-copy file was left as-is; the user re-runs
+  `sqlcg viz` against the live graph to regenerate and eyeball on Windows.
+- **Impact**: No effect on the PR contents (the artifact was never committed). The
+  manual eyeball portion of AC2/AC3/AC4/AC5/AC6 (visual confirmation) is deferred to
+  the user; the automated behavioral guards (helper harness + accessor/handler
+  references) are all in the PR and green.
+- **Date**: 2026-06-15

{sql_code_graph-1.36.2 → sql_code_graph-1.37.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql-code-graph"
-version = "1.36.2"
+version = "1.37.0"
 description = "SQL code graph analyzer and lineage tracer"
 readme = "README.md"
 requires-python = ">=3.12"

{sql_code_graph-1.36.2 → sql_code_graph-1.37.0}/src/sqlcg/__init__.py

@@ -1,5 +1,5 @@
 """SQL Code Graph - SQL lineage and dependency analysis tool."""
 
-__version__ = "1.36.2"
+__version__ = "1.37.0"
 
 __all__ = ["__version__"]