API: what names introduce capture/shadowing if make a binding at a node

Description

This is a feature request.

Consider a frontend offering an action to insert or rename a binding. A human should be able to enter a custom name, but be warned/forbidden from chosing a name that would cause shadowing/capture. To avoid having to make an API call (about the current name) on every keystroke, it would be nice to have one call that returns all the bad names.

Dependencies

None

Spec

We need to know

these names are in scope, with these types (as currently returned by the "what variables are in scope?" call) (these are "would cause shadowing")
these names occur free in the focussed subtree (these would cause capture)
these names are bound in the focussed subtree (these would also cause shadowing)

Since the purpose of this call is different to the "what variables are in scope" question, I suggest handling it differently.

In fact, since it is only relevent when taking an action, I suggest bundling it with the offered actions which emenate from the backend anyway! Let's just extend the UserInput.ChooseOrEnterName constructor with a list (because lists are easy to serialise) of "bad names" (or, rather: two lists: one for capture and one for shadow, so we can (in the future) make one an error and one a warning).

Note that here we do not suggest changing anything about the submission mechanism. The backend will still be able to reject requests to introduce a binding that causes shadowing (due to, say, someone poking at the raw API).

Implementation details

See Spec

Not in spec

There are presumably some other names that we want to disallow (inappropriate words etc). We do not tackle this here, as we do not want to use the same mechanism -- if we did, our API results would verbatim contain such words, which is not acceptable! (Some thoughts about this feature, since I am on the topic: this list would not change often, so could be cached in the frontend easily; it could be rather large (compared to the list of "capturing names"); it may need to be configured per deployment (local slang etc); we want to avoid having a verbatim list of such words (perhaps match by a hash?); we need to be aware of the Scunthorpe problem)

What should happen if the frontend submits a capture/shadowing name anyway (perhaps due to someone manually poking the API). For the purposes of this FR, we will not change that behaviour.

Discussion

Future work

When/if we implement a "multi-player" session, we will need to be aware that this list could change dynamically due to actions another student is doing. However, since the set of available actions could also change, I don't think this poses any additional obstacle.

Thanks. Comments/requests for clarification:

Presumably the backend could still reject the submitted name, and that behavior is not changed by this feature request? (For example, a client could simply ignore the list of offered names and submit one of them anyway.) We should make it clear that this is effectively a hint for the client in the form of additional metadata, and that the submission mechanism is not actually changing here.
I think I agree with the idea of bundling these names with the offered actions, rather than requiring a separate API call. The separate call might save a bit of data exchange if the student ends up not performing the action, but presumably the list of names will not be so large that it makes a significant difference.
I also agree that we should separate the names into 2 lists (shadow vs. capture), even if we don't use it now.
I think perhaps we should mention that other "bad names" lists are not in spec for this change; e.g., inappropriate words. These will likely not change very often (perhaps they could be refreshed once every few hours or something like that), are potentially quite large, and may use a different matching mechanism altogether; e.g., a hash lookup, vs. a literal match such as this feature request would presumably use. (This would also mean that these two mechanisms could not be unified into a single "bad name" list from the backend, which is fine. I point it out only because, in our earlier discussion, we thought it might be possible to do so.)
In "Future work," we should mention that we will need to consider how this mechanism might work in a "multi-player" editing session, since the list of names offered by this mechanism would effectively be cached in the frontend indefinitely (from the time the student selects the node until the student either performs the action or selects another node), and the backend state could change in the interim in a multi-player session. (This is somewhat addressed by pointing out that this name metadata is simply a hint.)

Thanks. Comments/requests for clarification:

(I briefly respond to a few points here, and will edit the OP)

Presumably the backend could still reject the submitted name, and that behavior is not changed by this feature request? (For example, a client could simply ignore the list of offered names and submit one of them anyway.) We should make it clear that this is effectively a hint for the client in the form of additional metadata, and that the submission mechanism is not actually changing here.

Yes

I think perhaps we should mention that other "bad names" lists are not in spec for this change; e.g., inappropriate words. These will likely not change very often (perhaps they could be refreshed once every few hours or something like that), are potentially quite large, and may use a different matching mechanism altogether; e.g., a hash lookup, vs. a literal match such as this feature request would presumably use. (This would also mean that these two mechanisms could not be unified into a single "bad name" list from the backend, which is fine. I point it out only because, in our earlier discussion, we thought it might be possible to do so.)

Good point

In "Future work," we should mention that we will need to consider how this mechanism might work in a "multi-player" editing session, since the list of names offered by this mechanism would effectively be cached in the frontend indefinitely (from the time the student selects the node until the student either performs the action or selects another node), and the backend state could change in the interim in a multi-player session. (This is somewhat addressed by pointing out that this name metadata is simply a hint.)

I don't think that this feature makes anything more difficult -- the list of available actions could itself change!

hackworthltd / primer