Skip to content

Show the verifier's hints in the State Machine view - #172

Closed
CatarinaGamboa wants to merge 1 commit into
mainfrom
feat/fsm-ways-to-fix
Closed

Show the verifier's hints in the State Machine view#172
CatarinaGamboa wants to merge 1 commit into
mainfrom
feat/fsm-ways-to-fix

Conversation

@CatarinaGamboa

@CatarinaGamboa CatarinaGamboa commented Oct 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Part of #170. Stacked on #171, so review that one first.

Why

The State Machine view showed where a call is rejected but not how to fix it. The verifier's hints were only in the Verification tab.

What

A collapsed Ways to fix section under the legend lists the verifier's hints for the shown error, rendered as in the Verification tab, with several call sequences shown as options. The verifier's own "(and possibly others)" stays in its hints.

Nothing is read from the diagram. An earlier version also listed shortest paths along the diagram's transitions, but they ignore the transitions' conditions and the code, so they were dropped (see #171).

Other details:

Drawing a selected verifier hint on the diagram is #156. That issue now lists what it needs first.

Screenshots

Section opened, real verifier output (0.0.36).

UDP chat client. The verifier says the state depends on the path.

ImageWriteParam. The verifier names the argument that decided the state.

Tests

  • npm run test:unit: 127 passed. New tests cover the hints, the collapsed default and its key, an error that cannot be marked, no section without hints, and the open state across tabs.
  • tsc -p tsconfig.test.json and npm run lint: clean.
  • npm test (VS Code): 9 + 1 passing. Server mvn test: 35 passing.

🤖 Generated with Claude Code

@CatarinaGamboa CatarinaGamboa mentioned this pull request Oct 27, 2026
Open
CatarinaGamboa added a commit that referenced this pull request Oct 27, 2026
@CatarinaGamboa
Screenshots for #171 and #172 without the diagram's ways to fix
0ecc54c
@CatarinaGamboa CatarinaGamboa mentioned this pull request Oct 27, 2026
Merged
@CatarinaGamboa CatarinaGamboa changed the title List the ways to fix a state error in the State Machine view Show the verifier's hints in the State Machine view Oct 27, 2026
@CatarinaGamboa
CatarinaGamboa force-pushed the feat/focus-collapse branch 2 times, most recently from a92a0c9 to 782e902 Compare October 28, 2026 13:57
CatarinaGamboa added a commit that referenced this pull request Oct 28, 2026
@CatarinaGamboa @claude
Collapse the unrelated methods when focusing on a state error, listed…
80bed18 
… on hover (#171)

Part of #170.

## Why
Focus mode dimmed the methods unrelated to a state error but kept their
text, so the layout did not move (#158). On a large machine the dimmed
label stacks still took the space. In the UDP chat client the state the
error is about, `closed`, was below the fold.

## What
In focus mode:
- **Collapse.** The dimmed methods of each label become a count:
`receive` + `+9 more`, or `2 methods`. Overloads count once. A single
dimmed method keeps its name and conditions.
- **List on hover.** Hovering a count lists its methods, with their
conditions, next to the label. A click keeps the list open until the
next click, a pan or a zoom. The diagram is not laid out again, so the
list appears at once. The list goes right, left, above or below the
label, or beside the diagram at the label's height: wherever it covers
the fewest states, labels and transition lines, and the closest such
place on a tie.
- **Constructors.** The constructors of each state are merged into one
arrow, e.g. `4 constructors`.
- **Layout.** The diagram is laid out again. A tall diagram is shrunk to
fit the panel, but never below 60%.
- **Bright.** Only the failed method stays bright.
- **States.** No state is removed.

**Show all** is unchanged.

An earlier version of this PR also drew a dashed "way to an expected
state": a shortest path along the diagram's transitions. It was dropped.
The path ignores the transitions' conditions and the code, and for a
state that no call leaves (`closed`) it could only suggest creating a
new object. The ways to fix now come from the verifier's hints only
(#172).

Error categories (liquid-java/liquidjava#418) are not used to choose
what to show. #170 explains why.

## Screenshots
Real verifier output (0.0.36) in headless VS Code.

**UDP chat client** (`E_OSS_A1_22`): `receive` after an `if` that may
close the socket. In the screenshots, the three `from = "closed(this) &&
connected(old(this))"` preconditions are removed from the DatagramSocket
spec. With them, verifier 0.0.36 sends no state context or hints for
this error, and the view can only say "Invalid method call at line 28".
That is a verifier issue, separate from this PR.

| Before | After |
|---|---|
| <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/udp-before.png"
width="440"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/udp-after-v2.png"
width="440"> |

**On hover**, placed off the states and transitions: `+12 more` next to
`bound` goes beside the diagram, `+16 more` next to `connected` to its
right, and the `2 methods` of `ImageWriteParam` left of `tilingExplicit`
and right of `setTiling`.

| UDP, `bound` | UDP, `connected` |
|---|---|
| <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/udp-hover-bound.png"
width="440"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/udp-hover-connected.png"
width="440"> |

| ImageWriteParam, bottom | ImageWriteParam, middle |
|---|---|
| <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/iwp-hover-bottom.png"
width="440"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/iwp-hover-middle.png"
width="440"> |

**ImageWriteParam**: `setTiling` from `startTiling`.

| Before | After |
|---|---|
| <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/iwp-before.png"
width="440"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/iwp-after-v2.png"
width="440"> |

<details><summary>Show all (unchanged)</summary>

<img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/focus-collapse/udp-show-all.png"
width="440">
</details>

The collapsed "Ways to fix" section in the screenshots comes from the
stacked PR.

## Tests
- `npm run test:unit`: 123 passed. New tests cover collapsing, the list
on hover, pinning it with a click and closing it on a click, pan or
zoom, placing it off the states, labels and lines and inside the panel,
merging constructors and the entry transitions from #169, the fit to the
panel, and Show all being unchanged.
- `tsc -p tsconfig.test.json` and `npm run lint`: clean.
- `npm test` (VS Code): 9 + 1 passing, and server `mvn test`: 35
passing, both run on the stacked branch, which includes this one.

Rebased on #169. In focus mode, entry transitions are dimmed and merged
per state, the same way constructors are.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@CatarinaGamboa CatarinaGamboa mentioned this pull request Nov 4, 2026
Merged
CatarinaGamboa added a commit that referenced this pull request Nov 10, 2026
@CatarinaGamboa @claude
Show a subclass's call on the state set it inherits from a superclass…
123cda0 
…'s spec (#174)

Closes #173.

Uses liquidjava-fsm 0.2.3 (which includes
[liquidjava-fsm#16](liquid-java/liquidjava-fsm#16))
and verifier 0.0.37, both on main since #179. Rebased onto main on
2026-11-10: the `server/pom.xml` bump is gone; server tests pass (39
with #178 merged in too).

## Why
A state error can be on a method declared in a subclass's spec
(`Frame.setUndecorated`) while the state set is declared in a
superclass's spec (`Window`). In that case the State Machine view could
not explain the error:
- With verifier 0.0.36 (no state context), it showed `Window`'s diagram
without `setUndecorated` and marked no states (the issue's screenshot).
- With verifier main (liquid-java/liquidjava#464), the context names
`java.awt.Frame`. The parser then found `Frame`'s spec, which has no
`@StateSet`, so the error had no diagram at all.

## What
- **liquidjava-fsm#16.** The parser merges the specs of a class's
supertypes, following the rule from liquidjava#464: state sets of the
class and then of its supertypes, nearest first; for each method, the
class's own refinement, otherwise that of the nearest type that declares
it. The details are in that PR.
- **`StateRefinementErrorDTO`.** It parses the diagrams for the
context's `receiverClass`. It reads the declaration's file plus the
files of the state sets and state refinements the verifier registered
(`ContextHistory`), so specs split across files are found, including a
supertype spec with methods but no state set. Without a context it
behaves as before (first class of the declaration's file).
- **Known limit.** A project class that extends an unannotated project
class in a file the verifier registered nothing for stops the walk
there, so that class's diagram leaves out the states further up. The
parser only sees the spec files.

No verifier change is needed. liquidjava#464 already sends the context
with the receiver's states for this case. The view needs a verifier
release with #464 (after 0.0.36). With 0.0.36 nothing changes for this
case: that verifier sends no context, so the view still shows the first
class of the declaration's file (`Window` in the issue's file).

## Screenshots
Both columns use verifier main @ 9e4b5e64.

| | Before (main) | After |
|---|---|---|
| Issue reproducer (`host.pack(); host.setUndecorated(true);`) | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/174/before-issue.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/174/after-issue.png"
width="380"> |
| Study exercise A1_09 (LITIENGINE `GameWindow`) | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/174/before-a1-09.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/174/after-a1-09.png"
width="380"> |

In A1_09 the actual state shows as "unknown" because the verifier finds
both `displayable` and `notDisplayable` possible (it depends on the
path). `notDisplayable` is marked as the expected state, and
`setUndecorated` is the failing call.

I did not take a split-files screenshot. With `FrameRefinements.java`
read before `WindowRefinements.java`, the verifier stops with
liquid-java/liquidjava#461 before it reaches the state error.
`StateRefinementErrorDTOTest` covers that layout.

## Tests
- server `mvn test`: 39 passed, 0 failures (liquidjava-fsm 0.2.3 built
locally from #16, verifier 0.0.36). New `StateRefinementErrorDTOTest`:
- Specs in two files: the diagram is `java.awt.Frame`, with
`setUndecorated`, `dispose` and `pack` on `Window`'s states;
`displayable` is marked invalid and `notDisplayable` accepted.
- Without a context: the first class of the declaration's file, as
before.
- A `JFrame` spec over a method-only `Frame` spec and `Window`'s state
set: all their methods are drawn.
- The verifier run on that fixture: the files of all three specs are
selected.
- client `npm run test:unit`: 123 passed. `npm run test:typecheck`:
clean. `npm test` (VS Code): 9 + 1 passing.

## Overlap with #172
None. #172 changes only the client webview. This PR changes only the
server and its fsm dependency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
CatarinaGamboa added a commit that referenced this pull request Nov 10, 2026
@CatarinaGamboa @claude
Screenshots of the six study exercises with verifier 0.0.37
205cd41 
Build: vscode-liquidjava main 7292a64 (#179) + #178 (04246ac) + #174 (974043b),
merged locally; verifier 0.0.37, fsm 0.2.3 from Central. Files named
*-ways-to-fix-pr172.png add #172 (6d41838) on top. Exercises:
building-examples-liquidjava proposal-d-state-values, api 0.0.8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CatarinaGamboa CatarinaGamboa mentioned this pull request Nov 10, 2026
Merged
CatarinaGamboa added a commit that referenced this pull request Nov 11, 2026
@CatarinaGamboa @claude
State Machine view: show a multi-set state error in the set that is w…
a87b171 
…rong (#182)

Closes #180. Based on main (#178 and #174 are merged there); not stacked
on #172 (see below).

## What changes, per proposal

When a call needs the states of several state sets (Door: `d.lock();
d.open();`, `open` needs `doorState(this) == closed && lockState(this)
== unlocked`):

- **Failure marked where it is.** Which set is wrong comes from the
server's `errorContext` per diagram, not from message text: a set whose
`invalidStates` is not empty is in a wrong state; a set whose possible
states are all accepted, with another set in a wrong state, is "right".
In a right set, a transition of the call from the actual state whose
condition names the wrong set is drawn as usual (white, normal arrow)
and only the clause the actual state does not meet is red, also when
conditions are collapsed. In the wrong set the call is red as before.
Every other transition of the call stays red as now: when it has no
condition on the wrong set, when the condition is not only states, when
no set is wrong on its own (the verifier can only reject the
combination), or when the state is unknown.
- **Wrong set first.** `orderStateMachines` puts the sets in a wrong
state first, then the other sets of the error, then the rest. Focus mode
fits the first diagram as before, so the ✕ state is now on screen
(A1_38: `mark` first, the case from the IDE review).
- **Self-loops.** A transition that keeps its state is drawn as a round
loop (same ends, same side, as far out as before so it stays inside the
laid-out SVG, slightly thicker) instead of ELK's flat curl the size of
its arrowhead. It is redrawn after Mermaid renders, from a `%%
lj-self-loops:` comment like the existing dimmed-transitions one.
- **Conditions as in the spec, before and after the method.** A label
reads `[condition before] method [condition after]` on one line, e.g.
`[lockState(this) == unlocked] open`. Each condition is the spec text,
so it reads like the Expected box and the spec, and a condition with
other clauses stays readable: in `[lockState(this) == unlocked &&
size(this) > 0] open` only the clause the actual state does not meet is
red. Edge labels no longer wrap at Mermaid's 200px width, so a condition
stays on the line of its method.
- **Set names in the summary.** "expected doorState `closed`, lockState
`unlocked` · actual lockState `locked`": expected in declaration order;
actual lists only the sets in a wrong state (all known ones if none is).
A set in which every state allows the call is left out of both sides,
for named and unnamed sets (the A1_56 "(undoable or notUndoable) and
redoable" case). Unnamed sets keep the current wording.

Single-set classes are unchanged except for the round self-loops and the
summary naming a named set (`expected phase open · actual phase
closed`).

## Ways to fix and #172

Not in this PR. Highlighting `unlock` on the diagram needs to know which
calls a hint suggests, and `HintDTO` only has `kind` and `message`;
getting the calls from the message text, or from paths in the diagram
(judged unsound in #171), are both out. #172 lists the verifier's hints
in a "Ways to fix" section and does not draw them; drawing a hint is
#156, which needs a structured hint from the verifier first. So this PR
does not depend on #172 and does not touch the hints; the two only meet
in `fsm.ts`/`script.ts` call sites and should rebase cleanly in either
order.

## Screenshots

Headless VS Code, this branch's server (verifier 0.0.37, fsm 0.2.3).
Focus mode is what opens from the error.

**Door** (the spec from #178, `d.lock(); d.open();`):

| | Before (main) | After |
|---|---|---|
| Focus on error | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/door-focus-before.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/door-focus-after.png"
width="380"> |
| Show all | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/door-all-before.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/door-all-after.png"
width="380"> |

**Study exercise A1_38** (BufferedInputStream, sets `stream` and `mark`;
`buffered.reset()` without `mark()`; proposal-D-task-types with
liquidjava-api 0.0.8):

| | Before (main) | After |
|---|---|---|
| Focus on error | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/a138-focus-before.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/a138-focus-after.png"
width="380"> |
| Show all | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/a138-all-before.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/a138-all-after.png"
width="380"> |

The right set, scrolled down in focus mode (call drawn as usual, unmet
condition red). These two and the A1_38 shots are from before the change
to conditions as in the spec, which they still show as `[lockState:
unlocked]`; the Door shots above are current:

| Door `doorState` | A1_38 `stream` |
|---|---|
| <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/door-focus-second-after.png"
width="380"> | <img
src="https://raw.githubusercontent.com/liquid-java/vscode-liquidjava/pr-screenshots/180/a138-focus-second-after.png"
width="380"> |

## Not in this PR

- Marking states that are current and fine (`closed` in `doorState`,
`open` in `stream`), as agreed.
- Highlighting the ways to fix on the diagram (above).

## Reviews

- Codex: 5 rounds (comments below); rounds 1-4 found one or two issues
each, all fixed; round 5 found nothing.
- Clean-code audit: comment below; one fix, the rest declined with
reasons.

## Tests

- client: `npm run test:unit` 128 passed (5 new, each fails without the
change: order, call/condition marks with `!=` and collapsed conditions,
round loop, named summary without the any-state set; one existing
expectation gains the self-loop comment), `npm run test:typecheck` and
`npm run lint` clean.
- server: no change; `mvn -B test` 39 passed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@CatarinaGamboa
CatarinaGamboa changed the base branch from feat/focus-collapse to main November 11, 2026 14:31
@CatarinaGamboa @claude
Show the verifier's hints in the State Machine view
0479c75 
The State Machine view showed where a call is rejected but not how to
fix it, while the verifier's hints were only in the Verification tab.

A collapsed "Ways to fix" section under the legend now lists the hints
of the shown error, as in the Verification tab. Nothing is read from the
diagram, which ignores the transitions' conditions and the code. Its open
state is kept per error, apart from the Verification tab's hints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CatarinaGamboa

CatarinaGamboa commented Nov 11, 2026

Copy link
Copy Markdown
Collaborator Author

not a priority now

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@CatarinaGamboa