toLeopard: Desirable & satisfying traits

[towerofnix]

Resolves #123. Related to leopard-js/leopard-mentors#4 and #149.

This PR implements the alternate proposal outlined in the second half of #123 (comment). Both PRs should be equally effective in generally fixing issues to do with surprise NaN in converted projects; however, we expect this one will lend to nicer and more intuitive reporter and input definitions. Either way, behavior-testing Scratch projects are much needed.

This code is all brand new, from July 2024. Thanks to @adroitwhiz for TypeScript tips!

[towerofnix]

@PullJosh We've requested review on both this pull request and #149, but our hope is that if you don't see any stand-out issues, we'll merge this one and not the other. They're opposing pull requests:

#149 is more conservative and uses very similar code language, so has a smaller diff, but it introduces conceptual baggage that we've seen is hard to explain and tricky to reason about. This PR (#150) includes all of the exact same meaning (or at least is meant to), and so if you want to get a sense ofr how the two PRs express that meaning differently, you can compare the opcodes whose definitions were in #149 with the same ops in this pull request.

This PR changes the language we use to represent input shapes, splitting it into "desired" and "satisfied" definitions, which look similar but have distinct meaning. That meaning is all described in the DesirableTraits and SatisfyingTraits enums. Although we had to edit literally every block definition, they are virtually all just different representations of the same meaning - we just think that meaning is expressed more clearly, now.

In this PR, the code at the bottom of blockToJS for helping the satisfied traits meet the desired traits is a bit more complicated. But we think it's quite easy to reason about if you give it a read through. We chose to represent the logic mainly in terms of what traits are desired: after all, we're about to fill in casting code if needed, because the job of this code is to make the satisfied code (variable based on the block) meet the desired code (constant for any given input).

[towerofnix]

Also, we haven't created any proper behavior testing projects, yet—specifically for behavior to do with NaN (which is changed, in the same ways, in both pull requests). Those are coming soon™, and should be prepared before merging either PR!

We did test the project in leopard-js/leopard-mentors#4, which appears to be fixed the same way in this pull request as in the other. That was a good sign, LOL. Similarly, only a single change in the "compilesb3" snapshot test, not that it was automatically testing nearly any NaN-related cases, to begin with. (Those are the only cases intended to change with the merging of either PR.)

We also filed a couple follow-up issues #152 and #153 addressing particular concerns we noticed while updating all the opcodes' definitions for this PR.

I regret doing all the block updating work in one commit. If I'd thought better, I'd have converted all the definitions word for word identically to their current Leopard behavior, and only afterwards implemented the special NaN handling. Sorry this makes for a less nice-to-read diff! However, you should still get the idea from the diff pretty quickly: anything that doesn't involve NaN has a very simple conversion between the old style and the new one.

-satisfiesInputShape = InputShape.String;
+satisfiesTraits = [SatisfyingTraits.IsString];

-const string1 = inputToJS(block.inputs.STRING1, InputShape.String);
+const string1 = inputToJS(block.inputs.STRING1, [DesirableTraits.IsString]);

[PullJosh]

I just read through the changes and this looks really good. I love the split into desired vs satisfying traits. (#149 also looks good, but lesser in exactly the ways you described.)

Also, we haven't created any proper behavior testing projects, yet—specifically for behavior to do with NaN (which is changed, in the same ways, in both pull requests). Those are coming soon™, and should be prepared before merging either PR!

I strongly agree! This is the perfect opportunity to buff up our testing quite a bit. Would you like me to create a test project myself, or wait for yours?

[towerofnix]

Thanks @PullJosh! Glad you enjoy this direction, it feels good to us too. There will probably be some neat ways to build on it as a basic framework for more dynamic behavior, but if you prefer it for the NaN-handling implemented in both these PRs, then that's perfect for us right now.

We're recovering from a pretty uncomfortable bout of illness ATM - if you'd like to, we would appreciate if you make a test project yourself. It needs to test these things:

• The correct blocks indicate they may be NaN (and are casted as needed).
• The correct blocks cast NaN to zero (or cast NaN strictly).
• Leopard's runtime behavior surrounding NaN matches Scratch (in a project generated by sb-edit).

We are pretty confident the code we have implemented works like it's supposed to, so our concerns in testing are mainly about making sure we match Scratch behavior. (And use a snapshot test to catch potential regressions.) This mostly means reviewing Scratch's own implementations for all blocks that have number inputs, which means reading through a bunch of scratch-vm code (this stuff), and writing a Scratch project to validate the expected behavior.

We're happy to add the project into this PR when it is ready. And it's OK if that's too big of a project to take on yourself right now, too - we can come back to this when we're a bit more recovered!

---

Also, we still need to flie the corresponding leopard PR that implements toNumber(value, true) ("strict" toNumber). Should have that ready in a minute so you can actually test Leopard runtime behavior!