Introduce @codama-internal/spec-generators and regenerate @codama/node-types

Introduces the private `@codama-internal/spec-generators` workspace package and uses it to fully regenerate the `@codama/node-types` source surface from the encoded `@codama/spec` description.

The new generator package houses every code generator the monorepo needs behind a single orchestrator entrypoint. Each generator is self-contained — it knows which spec major it targets, which output directory it writes to, and which compatibility knobs it needs — and exposes a no-argument `generate()` from its `index.ts`. The orchestrator at `src/index.ts` runs every registered generator sequentially. This first cut ships only the gen-ts-node-types generator, ported from the spec repo with imports rewritten to consume `@codama/fragments/javascript`; the v1 driver supplies the legacy compatibility tables (`narrowableDataAttributes`, `genericParamOrder`) needed to keep the existing public type surface stable. Adding a future generator (migrators, JSON schema, …) is a matter of dropping a folder under `src/`, exposing its own `generate()`, and wiring it into the orchestrator.

The regenerated `@codama/node-types/src/` replaces the hand-maintained interfaces wholesale: the generator wipes its target `generated/` directory before writing, so stale files cannot survive. Hand-written content lives at the top of `src/` as siblings of `generated/`, never inside it. Two compatibility shims are added there — `Docs = Array<string>` and `ProgramVersion = Version` — to keep `@codama/nodes` and `@codama/nodes-from-anchor` compiling against the slimmer generated surface; both can be removed in a future major if desired.

Array fields are emitted as `Array<T>` rather than `T[]` so an inline-union element type like `array(literalUnion(true, false))` doesn't need extra parentheses to preserve precedence with `|`. The shape changes that fall out of regeneration are documented in the accompanying changeset.

Author: lorisleiva

.changeset/proud-queens-pull.md

@@ -0,0 +1,24 @@
+---
+'@codama/node-types': minor
+'@codama/nodes-from-anchor': patch
+---
+
+Regenerate the entire `@codama/node-types` source surface from the encoded `@codama/spec` description, via the new private `@codama-internal/spec-generators` package.
+
+The bulk of the surface lives under `src/generated/` and is produced by the `gen-ts-node-types` generator from the spec. The previously hand-maintained interfaces are gone; every node, union, enumeration, and per-spec shared type is rebuilt from the spec on every `pnpm generate` run.
+
+A small set of static helpers — the brand types, the `Docs` alias, and the `Version` template-literal type — live as hand-written sibling files at the top of `packages/node-types/src/`, alongside the existing `ProgramVersion` deprecated alias. They are imported by the generated surface but never regenerated, since their content doesn't depend on the spec. The generator wipes only `src/generated/` on every run; hand-written content at the top level survives. The per-spec `CodamaVersion` literal stays generated, in its own `src/generated/shared/codamaVersion.ts` file pinned to the spec version at generation time.
+
+Most of the rebuild is structural: imports now point at per-file paths (`./linkNodes/PdaLinkNode`) instead of subdirectory barrels, every interface and field carries a JSDoc block sourced from the spec, and array fields are emitted as `Array<T>` rather than `T[]` so an inline-union element type doesn't need extra parentheses to preserve precedence. A handful of named API differences also shake out from this:
+
+- `accountNode.size` is now typed as `number | undefined` (the previous `| null` arm had no consumer and is dropped).
+- `programNode.origin` is now typed as the named `ProgramOrigin` union (`'anchor' | 'shank'`) instead of an inline literal union.
+- `instructionAccountNode.isSigner` and `instructionRemainingAccountsNode.isSigner` now read `boolean | 'either'` instead of `true | false | 'either'` (a TypeScript-only readability normalisation; the encoded spec keeps the explicit `true | false` form so other codegen targets can still emit a multi-variant enum).
+- `numberTypeNode.format` and `stringTypeNode.encoding` are emitted as named `NumberFormat` / `BytesEncoding` aliases imported from `./shared/`, with the same generic-narrowing behaviour preserved.
+- `programNode.version` is now typed as the unified `Version` template-literal alias (`` `${number}.${number}.${number}` ``) — a tighter shape than the previous plain string, so non-conforming literal strings will now surface as TypeScript errors at the call site. The historical `ProgramVersion` name is preserved as a hand-written `@deprecated` re-export so existing consumers continue to compile; `@codama/nodes-from-anchor` is updated to import `Version` directly.
+- `docs?` fields use a `Docs = Array<string>` alias mirroring the `'docs'` `TypeExpr` kind in `@codama/spec`. The alias is hand-written and lives at `packages/node-types/src/Docs.ts`.
+- Documentation strings that ship as multiple paragraphs in the spec now render as multi-paragraph JSDoc blocks. Affected fields and types include `accountNode.discriminators`, `instructionNode.discriminators`, `instructionAccountNode.isSigner`, `instructionRemainingAccountsNode.isSigner`, `rootNode`, the `ConditionalValueNode` interface and its `condition`, `InstructionInputValueNode`, `ResolverValueNode`, `AmountTypeNode` and its `unit`, `MapTypeNode.size`, `NestedTypeNode`, `StringTypeNode.size`, `EnumValueNode.value`, and `NumberValueNode.number`.
+
+Alongside the per-node interfaces, the package now exports seven `Registered<Category>Node` category-registry unions (`RegisteredContextualValueNode`, `RegisteredCountNode`, `RegisteredDiscriminatorNode`, `RegisteredLinkNode`, `RegisteredPdaSeedNode`, `RegisteredTypeNode`, `RegisteredValueNode`) corresponding one-to-one with `@codama/spec`'s category registries, plus a `GetNodeFromKind<TKind extends NodeKind>` helper that resolves to the concrete interface for a given kind. The registry unions are the recommended extension point for downstream packages that need to introduce custom node kinds.
+
+The generator consumes `@codama/spec@1.6.0-rc.4`, which reshapes the spec into per-category groups (`spec.categories[]`) and renames the `nestedTypeNode` `TypeExpr` kind to `nestedUnion` (with an explicit `alias` field). All `docs?` fields throughout the spec are arrays of paragraph strings rather than single newline-separated strings — the renderer accepts the array shape directly. Internally, the generator's renderers are layout-agnostic: they emit `use(...)` calls keyed by symbolic module strings (e.g. `'node:numberTypeNode'`, `'enumeration:Endianness'`, `'brand:CamelCaseString'`), and a single per-spec `RenderScope` resolves those symbolic keys to concrete file locations at write time. Adding a new file kind to the generator means extending the `RenderScope` symbol map; renderers themselves stay free of file-layout knowledge.

package.json

@@ -3,6 +3,7 @@
     "private": true,
     "scripts": {
         "build": "turbo run build --log-order grouped",
+        "generate": "pnpm --filter @codama-internal/spec-generators generate",
         "lint": "turbo run lint --log-order grouped",
         "lint:fix": "turbo lint:fix --log-order grouped && pnpm prettier --ignore-unknown --write '{.,!packages}/*'",
         "test": "turbo run test --log-order grouped",

packages/node-types/src/AccountNode.ts

@@ -0,0 +1,12 @@
+/**
+ * Hand-written `Docs` alias used by every `docs?` field in the generated
+ * node-type surface.
+ *
+ * Lives outside `./generated/` because it's a static type alias — there's
+ * nothing the spec contributes beyond the array shape itself. The
+ * generator's symbol map points at this file when emitting `import type
+ * { Docs } from '../Docs';` lines.
+ */
+
+/** Markdown documentation for a node — one paragraph per array entry. */
+export type Docs = Array<string>;