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