Generate TypeScript error-code declarations from the registry

[lmars]

Summary

Adds errors/scripts/generate-ts.js, which turns the registry in errors/codes/ into TypeScript error-code declarations for the JavaScript SDKs. Nothing generated is committed here — this PR adds the generator, its tests, and the generate:errorcodes-ts script.

The JS SDKs currently name error codes themselves, and the names have drifted from the registry: 15 of ably-chat-js's 20 disagree with the code's identifier, and ably-js uses bare numeric literals at ~149 call sites (five of which had code and statusCode transposed). Generating the names makes identifier the single spelling every SDK uses, and makes registering a code here the only step needed before referring to it — which is also why identifier is a frozen contract rather than something to churn.

The two output formats

--format=type emits a bare union of numeric literals:

/** A registered Ably error code. */
export type ErrorCode =
  | 10000
  | 40000
  // ...

This is for ably-js, which gates PRs on bundle size. The type erases at compile time, so it costs zero bytes, and existing numeric literals already satisfy the union — so all ~149 call sites keep compiling untouched while gaining the checking. Because registry codes are 5–6 digits and HTTP statuses are 3, a transposed code/statusCode pair is caught exactly rather than heuristically.

--format=const emits one documented constant per code, then the union:

/**
 * Bad request.
 *
 * The request was rejected because it was invalid and could not be processed.
 * @see https://help.ably.io/error/40000
 */
export const BadRequest = 40000;

This is for the wrapper SDKs, which need the values at runtime. Individual consts rather than an aggregate object or a TS enum, because object properties and enum members don't tree-shake — a 260-member enum would land whole in the bundles those SDKs ship to browsers. The JSDoc carries the registry title, summary, and help link, so hovering a constant in an editor shows what the code means.

How consumers use it

Each SDK runs the generator against the ably-common submodule it already vendors, commits the output into its own src/, and adds a CI step that regenerates at the pinned commit and diffs — the same arrangement as ably/docs and its error pages. Two properties that buys: a developer can register a code and use it without publishing anything, and because CI regenerates at the pinned commit, an SDK can't merge a reference to a code that isn't merged here first.

Output is sorted by numeric code and byte-identical for a given registry state, as that drift check requires, and depends only on Node's standard library plus the local frontmatter.js — so it runs from a superproject with no npm install inside the submodule.

Failure behaviour

The generator refuses to emit rather than produce an unusable file, on a duplicate identifier, two identifiers colliding on one PascalCase name, or a name that isn't a valid JavaScript identifier. None of the three occurs in the registry today; the assertions are to keep it that way.

Those failures, a bad argument, an absent errors/codes/, and an unwritable --out all print as a plain message and exit 1. A stack trace there would only be noise, so one now indicates a bug in the generator rather than a problem with the input. The absent-registry message calls out an uninitialised or stale submodule specifically, since ably-js's pin predates errors/codes/ existing and that's the first thing anyone adopting this there will hit.

Verification

• 25 jest tests: the naming transform, numeric-vs-lexical ordering, byte-identical repeat runs, each of the three assertions, both rendered formats verbatim, one declaration and one union member per registry file, and four CLI-level tests that spawn the script and assert a clean message with no stack frames.
• Both formats compile under tsc --strict. const d: ErrorCode = 400 (a transposed HTTP status) and an unregistered 12345 are both rejected, which is the property ably-js wants. Not wired into the test suite, since TypeScript isn't a dependency here.
• All 17 names in the planned rename tables for ably-chat-js and ably-ai-transport-js are produced exactly as tabulated.

The .eslintrc.js change belongs to the tests: they assert through an expectCleanFailure helper, which jest/expect-expect reads as a test with no assertions, so assertFunctionNames is configured for test/** rather than disabling the rule.

Follow-ups, not in this PR

• Adoption in each SDK: bump the submodule pin, add the npm script, commit the generated file, add the drift check. ably-js needs its pin moved off 496da5e, which predates errors/codes/.
• The renames in ably-chat-js and ably-ai-transport-js are breaking, since both export ErrorCode as a TS enum from their public API — one major, or @deprecated aliases for a release.
• Whether to emit an opt-in isErrorCode(n): n is ErrorCode guard for narrowing a relayed wire code. It needs the full set as runtime data, so it can't be part of the type output.
• errors/scripts/generate-errors-json.js has the stack-trace-on-registry-fault behaviour that this generator now avoids; worth aligning separately.

🤖 Generated with Claude Code

[VeskeR]

LGTM overall. Only one genuine request below re running the scripts on Windows machine, and couple of nits below - up to you

---

Something pre-existing Claude flagged and I tested:
npm run generate:errorcodes-ts -- --format=type fails with:

> [email protected] generate:errorcodes-ts
> node errors/scripts/generate-ts.js --format=type

10000.md: missing opening `---` frontmatter fence

on Windows machines, presumably because:

frontmatter.js:17 errors/scripts/frontmatter.js
function parseFrontmatter(content) {
if (!content.startsWith('---\n')) {
return { error: 'missing opening --- frontmatter fence' };

With Git for Windows' default core.autocrlf=true and no .gitattributes, errors/codes/*.md land as CRLF, so every file fails that fence check. This is my actual output on the branch, and 6 of the 25 tests fail with it:

and the is to change it to:

function parseFrontmatter(rawContent) {
  const content = rawContent.replace(/\r\n/g, '\n');

I think it's worth fixing here (as a separate commit) so that it runs on every machine - we have people developing on Windows for some SDKs, so a good idea to make it work for them too.

[VeskeR]

fixed frontmatter parsing broken on Windows in ae180b4

[VeskeR]

Approving as I've addressed my feedback and otherwise is happy with a PR 👍