refactor(errors): support our assert conventions

[erights]

closes: #XXXX
refs: Agoric/agoric-sdk#8781 (review)

Description

At Agoric/agoric-sdk#8781 (review) @turadg reacts to

import { quote as q, throwRedacted as Fail } from '@endo/errors';

with

This pattern is what I was trying to get away from with making a package at all. There's no export of Fail so there's no autocomplete when someone wants to import Fail.

IMO quite right. At Agoric/agoric-sdk#8781 I tried following the agreement from which the current @endo/errors API was born, where the exported explanatory names would be renamed to the conventionally used names on import. Even though I did not notice the autocomplete problem myself, I found Agoric/agoric-sdk#8781 unpleasant enough that I consider the current @endo/errors API to be a failed experiment.

This PR in its current state splits the difference. It does not withdraw the explanatory names. It simply exports aliases to their conventional names. Reviewers: Should I instead delete the explanatory names, since we don't intend to use them anyway? If so, it is ok if that deletion happens in a separate PR?

I needed to make two additional changes to switch things to @endo/errors. Unlike the assert global, the assert exported by @endo/errors does not include error (aka makeError) and note, instead making them separate exports of the module. This is good. But is requires changing the affected occurrences of assert.error to makeError and assert.note to something. For the latter, I first tried just using the name @endo/errors already exports, note, but found it too mysterious by itself. So I added an alias to errorNote and universally used that instead.

Finally, I had to omit completely those packages that were too low level to get assert by importing it from @endo/assert. I left them continuing to use the assert global.

Security Considerations

none

Scaling Considerations

none

Documentation Considerations

We should document the new @endo/assert convention as we use it, to encourage others to adopt the same conventions.

Testing Considerations

none, I think

Compatibility Considerations

If this PR continues to not withdraw the explanatory names, then none. Otherwise we'd need to fix existing uses, of which there appears to be none.

Upgrade Considerations

Without withdrawing the explanatory names, there should be no breaking change. I still need to write a NEWS.md entry and check that box. But I'll wait until I get feedback on this PR before writing that.

• Includes *BREAKING*: in the commit message with migration instructions for any breaking change.
• Updates NEWS.md for user-facing changes.

[kriskowal]

I dislike this change and recognize that my hard line (that a reviewer should not have to look beyond the file they’re reading to expand an abbreviation to a name that describes the function’s behavior) is mutually exclusive with @turadg’s hard line (that the name used at the call site in our style should allow the IDE to automatically draw forth the correct import statement.) Using descriptive names at the call sites would break that log jam but is mutually exclusive with @erights preference for brevity (and mine, for q and b in particular).

So, I would appeal to arbitration (by any member of the team) and will abide whatever choice is favored by the arbiter.

[turadg]

mutually exclusive with @turadg’s hard line (that the name used at the call site in our style should allow the IDE to automatically draw forth the correct import statement.)

I don't have a position on how it's factored in Endo. My position is just for consumer of @agoric packages.

I'm fine with leaving @endo/errors as it is and putting these convenience exports only into @agoric/assert.

[kriskowal]

mutually exclusive with @turadg’s hard line (that the name used at the call site in our style should allow the IDE to automatically draw forth the correct import statement.)

I don't have a position on how it's factored in Endo. My position is just for consumer of @agoric packages.

I'm fine with leaving @endo/errors as it is and putting these convenience exports only into @agoric/assert.

I think it would be a pity to have an adapter package in @agoric to settle a disagreement over policy about concerns that apply equally to both @endo and @agoric packages.

[kriskowal]

Out of band, @erights has made the value judgement that abbreviating the exports and using consistent abbreviations between Endo and Agoric is the better value for cost than making those conventional abbreviations explicit in every module that uses them. I respect @turadg’s preference and this choice.

I would like to continue exporting the descriptive names that these abbreviations alias.