Skip to content

Annotate SomeException with Graphula seed#108

Open
pbrisbin wants to merge 3 commits into
mainfrom
pb/annotate
Open

Annotate SomeException with Graphula seed#108
pbrisbin wants to merge 3 commits into
mainfrom
pb/annotate

Conversation

@pbrisbin

@pbrisbin pbrisbin commented Jun 16, 2026

Copy link
Copy Markdown
Member

Open Questions:

  1. Is this feature worth changing the exception type thrown?
  2. Is that change in exception type a major version bump?

You can see in my second commit the kind of thing our users might have to do. It's an unusual thing to be doing, but it will be broken by this "fix".


fix: annotate SomeException with Graphula seed

ad00327

The seed is useful to re-run in a deterministic way, which is why we
prepend it to any HUnitFailure exception messages. This commit adds
the same treatment to all other exceptions by catching SomeException
and using checkpoint to add it as an annotation.

Here is an example:

Before:

  uncaught exception: GenerationFailureMaxAttemptsToInsert
  GenerationFailureMaxAttemptsToInsert (Just "entity already exists by this key") School}

After:

  uncaught exception: AnnotatedException
  AnnotatedException {annotations = [Annotation @GraphulaSeed (GraphulaSeed (-8068470525722554834)),Annotation @CallStack [("checkpoint",SrcLoc {srcLocPackage = "graphula-2.0.0.0-ArtCvOVJMvo1gDWVYi6qKp", srcLocModule = "Graphula", srcLocFile = "src/Graphula.hs", srcLocStartLine = 272, srcLocStartCol = 8, srcLocEndLine = 272, srcLocEndCol = 18})]], exception = GenerationFailureMaxAttemptsToInsert (Just "entity already exists by this key") School}

Changing the thrown exception type is a risk, since any outer catches
our users (or other libraries) have in place may no longer catch it. But
using checkpoint and changing e to AnnotatedException e should be
tolerable, due to the fact that AnnotatedException.catch exists, which
catches both types at once.

That is why the output is relatively ugly, because we want to rely on
checkpoint and AnnotatedException, so this is what you get.

I also noticed that the existing code changes the HUnitFailure
constructor used (both Reason and ExpectedBotGot are turned into
Reason by way of formatFailureReason). Ideally, we would not do that
(and there's no real need), but I'm leaving it alone for now, erring on
the side of a smaller diff for this change.

Closes #44.

chore: update README to use annotated-exception's try

ad5f5b7

This is necessary because now the example throws an
AnnotatedException GenerationFailure and not a bare
GenerationFailure exception.

This is an example of the sort of change our users might have to make
because of the seed annotation feature.

pbrisbin added 2 commits June 16, 2026 09:45
The seed is useful to re-run in a deterministic way, which is why we
prepend it to any `HUnitFailure` exception messages. This commit adds
the same treatment to all other exceptions by catching `SomeException`
and using `checkpoint` to add it as an annotation.

Here is an example:

```
Before:

  uncaught exception: GenerationFailureMaxAttemptsToInsert
  GenerationFailureMaxAttemptsToInsert (Just "entity already exists by this key") School}

After:

  uncaught exception: AnnotatedException
  AnnotatedException {annotations = [Annotation @GraphulaSeed (GraphulaSeed (-8068470525722554834)),Annotation @callstack [("checkpoint",SrcLoc {srcLocPackage = "graphula-2.0.0.0-ArtCvOVJMvo1gDWVYi6qKp", srcLocModule = "Graphula", srcLocFile = "src/Graphula.hs", srcLocStartLine = 272, srcLocStartCol = 8, srcLocEndLine = 272, srcLocEndCol = 18})]], exception = GenerationFailureMaxAttemptsToInsert (Just "entity already exists by this key") School}
```

Changing the thrown exception type is a risk, since any outer `catch`es
our users (or other libraries) have in place may no longer catch it. But
using `checkpoint` and changing `e` to `AnnotatedException e` should be
tolerable, due to the fact that `AnnotatedException.catch` exists, which
catches both types at once.

That is why the output is relatively ugly, because we want to rely on
`checkpoint` and `AnnotatedException`, so this is what you get.

I also noticed that the existing code changes the `HUnitFailure`
constructor used (both `Reason` and `ExpectedBotGot` are turned into
`Reason` by way of `formatFailureReason`). Ideally, we would not do that
(and there's no real need), but I'm leaving it alone for now, erring on
the side of a smaller diff for this change.

Closes #44.
This is necessary because we now the example throws an
`AnnotatedException GenerationFailure` and not a bare
`GenerationFailure` exception.

This is an example of the sort of change our users might have to make
because of the seed annotation feature.
@pbrisbin pbrisbin changed the title chore: update README to use annotated-exception's try Annotate SomeException with Graphula seed Jun 16, 2026
@pbrisbin pbrisbin requested a review from chris-martin June 16, 2026 14:41
@pbrisbin pbrisbin marked this pull request as ready for review June 16, 2026 14:41
@pbrisbin pbrisbin requested a review from a team as a code owner June 16, 2026 14:41
@pbrisbin pbrisbin removed the request for review from a team June 16, 2026 14:41
@cdmren cdmren requested review from cdmren and removed request for chris-martin June 17, 2026 22:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Catch SomeException and decorate with seed

1 participant