scripts — Codegen & Tooling

🎯 Why This Module Exists

Without codegen, every protocol addition means touching four language repos, writing four type declarations, and hoping nobody typoed a field name. With codegen, a schema edit + one command updates all four SDKs atomically. The decision to commit the generated output rather than generate at build time is deliberate: PR reviewers can see the exact diff (does this method signature break users?); CI doesn't need Node.js to build the Go SDK; debuggers step into real code, not trampolines. The cost — occasional merge conflicts in generated files — is small compared to the reviewability win.

🏗️ Design Decisions

Codegen Pipeline

flowchart LR
  SCHEMA[api.schema.json
authoritative]
  PRE[Pre-processing
postProcessSchema
fixNullableRequiredRefs]
  CORR[corrections/
patch overrides]
  AST[Shared AST
utils.ts]

  subgraph emitters["Per-language emitters"]
    TS[typescript.ts
→ GeneratedRpc]
    PY[python.ts
→ _generated_rpc.py]
    GO[go.ts
→ generated_rpc.go]
    CS[csharp.ts
→ Generated/Rpc.cs]
  end

  SCHEMA --> PRE
  CORR --> PRE
  PRE --> AST
  AST --> TS
  AST --> PY
  AST --> GO
  AST --> CS
  TS -->|committed| NODE[nodejs/ sources]
  PY -->|committed| PYTHON[python/ sources]
  GO -->|committed| GOLANG[go/ sources]
  CS -->|committed| DOTNET[dotnet/ sources]

🚶 Codegen Walkthrough

Key Components

⚡ Algorithm Spotlight

postProcessSchema

A recursive walker that (a) inlines $refs under a size threshold, (b) tags numeric types with {kind: "integer" | "number"} from JSON-Schema's type + format + multipleOf, (c) flattens single-variant oneOf into the parent, (d) canonicalises nullable (explicit type: [T, null] becomes {nullable: true}). Visitor pattern; ~200 lines.

fixNullableRequiredRefsInApiSchema

Specific fix for a recurring schema pattern where a property is listed in required but its type is [T, null]. In TypeScript this is T | null (still required), in Go it is *T, in Python it is Optional[T], in C# it is T?. Without the correction, Go would emit T (no pointer, no nil representation) and silently lose null-carrying information.

Per-language emitter strategy

Each emitter: (1) pre-computes name mappings (camelCase→target convention), (2) emits top-of-file headers, (3) walks types in topological order (so referenced types appear before referencing ones), (4) emits methods, (5) emits events (or skips them if the SDK hand-writes them, as Go does for result_union.go).

⚠ Edge Cases & Pitfalls

📊 Performance

Codegen is a one-shot tool — runs in ~1.5s locally for all four SDKs. Not a hot path. Optimisation went into reviewability (deterministic output, stable ordering) not throughput.

Deep-Dive Highlights

Configuration Reference

Code Examples

utils.ts — name conversion

export function toPascalCase(s: string): string {
    return s.replace(/(^|[_-])([a-z])/g, (_, _sep, c) => c.toUpperCase());
}
export function toSnakeCase(s: string): string {
    return s.replace(/[A-Z]/g, c => "_" + c.toLowerCase()).replace(/^_/, "");
}

postProcessSchema structure

export function postProcessSchema(schema: JsonSchema): JsonSchema {
    schema = inlineSmallRefs(schema);
    schema = tagIntegers(schema);
    schema = canonicaliseNullable(schema);
    schema = flattenSingleUnions(schema);
    return schema;
}

csharp.ts — record emission (illustrative)

function emitRecord(t: TypeNode, out: Emitter): void {
    out.line(`public sealed record ${pascal(t.name)}(`);
    out.indent(() => {
        t.fields.forEach((f, i) => {
            const comma = i < t.fields.length - 1 ? "," : "";
            out.line(`${csType(f.type)} ${pascal(f.name)}${comma}`);
        });
    });
    out.line(`);`);
}

Directory Map

scripts/
├── codegen/
│   ├── index.ts                     ← Orchestrator entry
│   ├── utils.ts                     ← Shared helpers + AST walkers
│   ├── postProcess.ts               ← Schema normalisation pass
│   ├── typescript.ts                ← TS emitter
│   ├── python.ts                    ← Python emitter
│   ├── go.ts                        ← Go emitter
│   ├── csharp.ts                    ← C# emitter
│   └── corrections/                 ← Per-method/type patches
├── check-api-surface.ts             ← Node API-diff guard
├── validate-sdk-cli-versions.ts     ← Version coherence check
├── validate-samples.sh              ← Build-check every sample
└── package.json                     ← devDeps: tsx, prettier, etc.