needsUpdate may be wrong when the branch changes; these ones are now so
fast thanks to being pure JS that we can just always run their contents
and be sure that the outputs are right.
This file is pretty much the same as it was when it was committed in
2017; these days, we can write clearer code with async/await and new FS
APIs.
Additionally, we can improve the performance of this script by using a
newer/faster/maintained XML library. This will enable us to run the
script unconditionally in a later commit.
Profiling the build roughly half of the time spent loading the
build is spent importing typescript.js, for this one function.
Since this stack is already adding required devDependencies, switch
readJson to use jsonc-parser (published by the VS Code team), rather
than importing the entire LKG typescript.js library.
This eliminates a significant number of dependencies, eliminating all
npm audit issues, speeding up `npm ci` by 20%, and overall making the
build faster (faster startup, direct code is faster than streams, etc)
and clearer to understand.
I'm finding it much easier to make build changes for the module
transform with this; I can more clearly indicate task dependencies and
prevent running tasks that don't need to be run.
Given we're changing our build process entirely (new deps, new steps),
it seems like this is a good time to change things up.
This adds a "small" d.ts bundler script. This script is very basic,
using Node printing to produce its output. Generally speaking, this is
inadvisable as it completely disregards name shadowing, globals, etc.
However, in our case, we don't care about the globals, and we can opt to
restructure our codebase in order to avoid conflict, which we largely
had to do anyway when we were namespaces and everything was in scope.
This configures the existing build tasks to use esbuild by default. If
using the plain files is desired, passing `--bundle=false` will build
using plain files and still produce a runnable system.
This is only a basic build; a more efficient build is provided later
when gulp is replaced by hereby.
If these are regular comments, then they won't appear in our d.ts files.
But, now we are relying on an external d.ts bundler to produce our final
merged, so they need to be present in the "input" d.ts files, meaning
they have to be JSDoc comments.
These comments only work today because all of our builds load their TS
files from scratch, so they see the actual source files and their
non-JSDoc comments.
The comments also need to be attached to a declaration, not floating,
otherwise they won't be used by api-extractor, so move them if needed.
Now that we are modules, there's no reason to ban multiple namespaces
per file; each file is its own scope and declaring a namespace won't
merge it into any other files.
