Machine readable API list

[o-]

There have been some attempts in the past to specify the API exposed by ecma262 in a machine readable form. These attempts have revealed a large design space and debates on the best approach. At the same time there are various usecases where basically any machine readable list of the APIs would be extremely beneficial:

• Documentation (provide a quick overview of the whole api)
• Test coverage (check that each API function is covered by a test262)
• Fuzzing (discover new API to generate code for)
• Tooling (IDE support, languages compiling to JS, ...)
• Interop (verifying availability of the whole API surface)

And probably many more. Incidentally we happen to need such a list in V8 soon and we wondered if there was a pragmatic way of providing such a machine readable list of the whole API surface in ecma262. It does not have to be perfect and does not have to solve all the problems. It could be as simple as an appendix that lists all functions. Slightly more useful would be to additionally list arguments and some information about them. For instance option bags, or conversions or type checks which are unconditionally applied to them. Anything that can be done with low effort now is better than nothing and imho does not stand in the way of having a proper solution (IDL yada yada) longterm.

[nicolo-ribaudo]

Maybe https://www.npmjs.com/package/@tc39/ecma262-biblio (which is auto-generated from this repo) with some filtering would be a good starting point?

[bakkot]

I assume the ask is for user-exposed functions, whereas the biblio is only internal stuff.

See some discussion of previous efforts here. We never did make any efforts to make this easier to derive from the spec but we probably should. You can get a decent first approximation by running [...document.querySelectorAll('emu-clause, emu-annex')].filter(x => { let h1 = x.querySelector('h1').innerText; return /(\d|[A-Z])+(\.\d+)+ \S+ (\[ %\S+% \] )?\( /.test(h1) && !x.hasAttribute('type'); }).map(x => x.querySelector('h1').innerText).join('\n') on the spec, but that probably has some false positives and negatives.

[jmdyck]

PR #2592 consistified some of the prose used to 'declare' built-in functions, making it kind of feasible to programmatically extract the user-exposed API from the spec-text. See #2592 (comment) and the following discussion re possible next steps to make it more feasible.

[o-]

Thanks for the pointers. Yes, I was talking about user exposed functions. A combination of explicitly adding some metadata in the spec text and an automatic extraction seems like a good idea to me. Happy to help out with the implementation if there is interest in doing this upstream.