Skip to content

Label errors with the kind of mistake they show - #418

Merged
CatarinaGamboa merged 1 commit into
mainfrom
feat/error-categories
Oct 24, 2026
Merged

Label errors with the kind of mistake they show#418
CatarinaGamboa merged 1 commit into
mainfrom
feat/error-categories

Conversation

@CatarinaGamboa

@CatarinaGamboa CatarinaGamboa commented Oct 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Description

Each error now carries a category, taken from the LiquidJava bug codebook, so explanations and visualizations can be targeted to the kind of mistake. It stays internal for now (not printed); clients get it through LJDiagnostic.getCategory().

Category Codebook Rule
Unprovable C4.2 State error where nothing is known about the receiver's state: every state is possible and no state is mentioned. Or a Refinement Error where what was found mentions none of the variables the expected refinement constrains
Path-dependent state C4.1 State error where the receiver can be in several states, for a class with a single state set
Out of order A1 State error where the receiver is in exactly one state
Out of domain A2 Any other Refinement Error (argument, return value, assignment or field)

Errors the rules can't decide get no category:

  • state errors on classes without a state machine;
  • states that differ only across several state sets.

A category describes the program according to its specification, so it can't tell whether the specification itself is wrong.

Example

State Refinement Error: found created(f) but expected open(f)

Hints:
  - Call f.open() before this call to move f from created to open
  - In state created, f can call: open()

Category: Out of order (A1).

The error message now also lists its hints in a Hints: section, one per line.

Hints follow the category

The category is decided first and picks the kind of state hints, so they can't disagree:

  • Unprovable: calls that lead to the needed state.
  • Path-dependent state: a sequence that fixes every path, or the path-dependent hint.
  • Out of order and no category: a call sequence or the unreachable hint, plus the calls available.

Before, the hints made their own decision, so a join of every state (ErrorStateHintJoinOfAllStates) was reported as path-dependent but hinted as unknown.

Measured against the codebook

Run on the codebook's corpus bugs and exercises, counting only errors reported at the recorded line:

  • Corpus: 91 of 99 right, 4 wrong, 4 with no category.
  • Exercises: 34 of 52 right, 14 wrong, 4 with no category.

15 of the 18 wrong labels are "Argument picks the state" bugs (C3.1), which come out as "Out of order"; a follow-up PR adds that category. The other 3 are exercises whose receiver's state is really unknown to the verifier, so they get "Unprovable".

Type of change

  • New feature

Checklist

  • Added tests: TestErrorCategories, plus ErrorOutOfDomainArgument, ErrorUnprovableArgument and ErrorPathDependentOtherStateSet
  • mvn test passes locally

🤖 Generated with Claude Code

@CatarinaGamboa CatarinaGamboa mentioned this pull request Oct 24, 2026
Merged
3 tasks done
@CatarinaGamboa @claude
Label errors with the kind of mistake they show
40e993a 
Each error now carries a category from the LiquidJava bug codebook, kept
internal for now (not printed):
- Out of order: a call in a single state that does not allow it
- Out of domain: a value outside its refinement
- Path-dependent state: a state that differs between branches, when the
  class has one state set
- Unprovable: nothing is known about the object's state or the value

Errors the rules cannot decide get no category. The category picks the
kind of state hints, so a hint never contradicts it: a join of every state
is now path-dependent rather than unknown.

The error message now lists its hints in a Hints section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CatarinaGamboa
CatarinaGamboa merged commit 628a9ef into main Oct 24, 2026
1 check passed
CatarinaGamboa added a commit that referenced this pull request Oct 24, 2026
@CatarinaGamboa @claude
Point out the argument that decided a state a call does not allow (#419)
d3e00be 
## Description
Adds the **Argument picks the state** category (codebook C3.1) and a
hint for it. These errors had no useful hint before: a transition that
depends on an argument isn't part of the state machine, so the existing
hints can't explain it.

- Each object instance now records the last call that changed its state
(`StateChange`). Method calls and constructors record their own call,
and state-preserving calls keep the previous record. A join of branches
records nothing, which ends the search below.
- `DecidingArgument` follows that chain back to the last call that
changed a state set the failing call checks. If that call's transition
depends on its arguments or result, the SMT solver looks for values that
would have allowed the failing call: the state before the call, the
call's `to` with its parameters left free, and the failing call's
`from`. The model gives the values for the hint.
- When such values exist, the category comes before the other state
categories. The error then gets only the deciding hint. If none exist,
the error keeps its other category (for example
`ErrorArgumentCannotPickTheState`).

## Example
```
State Refinement Error: found empty(buffer) but expected filled(buffer)

Hints:
  - buffer.reset(boolean) on line 20 decides the state of buffer: with keep == true, this call would be allowed
```
Category: Argument picks the state (C3.1).

## Measured against the codebook
Same runs as #418:
- **Corpus:** 94 of 99 right (91 before), 1 wrong, 4 with no category.
- **Exercises:** 42 of 52 right (34 before), 6 wrong, 4 with no
category.

The category now finds 12 of the 15 C3.1 cases. The ones it misses:
- a guard in `from` that changes no state;
- an earlier value that is the real cause;
- a returned value at a join.

## Type of change
- [x] New feature

## Checklist
- [x] Added tests:
- `ErrorArgumentPicksTheState`, `ErrorConstructorArgumentPicksTheState`
and `ErrorArgumentPicksTheStateEarlier` (the decider is found past a
call on another state set);
- `ErrorArgumentCannotPickTheState` (no value helps, so no category
change);
  - cases in `TestErrorCategories` and `TestStateHints`.
- [x] `mvn test` passes locally

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

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 27, 2026
Open
Merged
CatarinaGamboa added a commit to liquid-java/vscode-liquidjava 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>
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