How to deprecate and/or remove unused runtime and JS library functions?

[sbc100]

We have had some issues over there years where emscripten itself stops using a runtime or JS library function and we would like to remove it because its now dead code and untested.

See the discussion on #14009.

It would be nice if we could find a way to avoid this in the future. I see two ways to improve the situation.

Avoid exposing internals going forward

The runtime and JS library system doesn't really have a good way to avoid exposing all of its internals to the user-level library.js code and EM_ASM code. Can we find a way to expose less to the user's library code so we can iterate on internals with impunity?

Create some kind of deprecation path

When a runtime function is up for removal/deprecation it would be good to have a plan for how long to keep it alive, and how to keep it tested.

[sbc100]

I was thinking about how to "Avoid exposing internals going forward". How about we add a new __internal library attribute that can be applied to library functions. Any symbols marked with e.g. Foo__internal: true would then only be available to library files within emscripten itself and not to outside libraries (e.g. those supplied via --library-js command line flags).

[kripken]

Interesting idea!

I think that makes sense. Variations could be to just warn if used outside of the code JS libraries, or to error, and whether those can be disabled. I don't have strong feelings on any of the options.

[sbc100]

Is there a reliable way to detect "usage" of a JS symbol? Does acorn have this information, for example? I would that it is hard/impossible to detect all types of symbol usage in JS because its so dynamic.

[sbc100]

Related: #15295

[kripken]

JS can definitely make things hard, but at the AST level you can do a lot if you do not have external code and you do not have eval. We make those assumptions in our Acorn optimization passes. With that you can find all the uses of a symbol in a reliable way.