proposal: Re-architect RPC client generator around neutral model and emitter abstraction + Roslyn

[alsi-lawr]

Replace the current hand-rolled C#-specific generator model with a neutral API model and open-ended emitter abstraction.

Motivation

The generator should model Neovim RPC/API semantics, not C# method declarations. This enables cleaner C# emission, future F# emission, better type mapping, and better generated documentation.

Scope

• Introduce a neutral generator model:
  • API functions
  • API parameters
  • API types
  • API events
  • documentation
  • version/deprecation metadata
  • request/response specs
  • encoder/decoder specs
• Introduce emitter abstraction:
  • IApiEmitter
  • GeneratedFile
  • GeneratedFileSet
• Move C#-specific concerns into a C# emitter that uses Roslyn to build the AST.
• Avoid Roslyn leaking into the neutral model.
• Preserve current generated output shape as much as practical for the first pass.
• Move the generator to a separate library from the CLI tool. The internals stand on their own and shouldn't be tightly-coupled to it exposing a cli tool.

Out of scope

• F# emitter.
• Major client API redesign.
• Plugin SDK redesign.
• Namespace/package renames unless required internally.

Acceptance criteria

• Generator core no longer depends on C#-specific declaration models as the shared abstraction.
• Emitter abstraction exists.
• Existing C# generation is implemented through the emitter abstraction.
• Golden tests cover generated output.
• Neutral model has unit coverage.
• CSharpier formats generated C# output.

Blocked by

• proposal: Add enforced CSharpier formatting #27
• proposal: Remove vague utility types and migrate to System.Text.Json #28
• proposal: Rework test boundaries and migrate tests to xUnit/Shouldly #29
• proposal: Expand RPC transport and client boundary coverage #30

Architecture

flowchart TB
    subgraph Core["Nvim.Client.Generator"]
        direction TB

        Ingest["Neovim API ingestion"]
        Model["Neutral API model"]
        Emit["Emitter abstraction"]
        CSharp["C# emitter using Roslyn"]
        Future["Future emitters"]

        Ingest --> Model
        Model --> Emit
        Emit --> CSharp
        Emit -.-> Future
    end

    subgraph CLI["Nvim.Client.Generator.Cli"]
        direction TB

        Args["Parse command/options"]
        Wire["Wire inputs to generator core"]
        Write["Write generated files"]
        Diagnostics["Return diagnostics/exit code"]

        Args --> Wire
        Wire --> Core
        Core --> Write
        Write --> Diagnostics
    end

Loading

[alsi-lawr]

Possibly 2 separate issues:

• Rearchitect generator
• Roslyn emitter

Should probably start with just the rearchitecture and then a separate issue to implement a roslyn-based emitter

[justinmk]

Sounds good in theory, the PR will reveal the truth: 100s of lines of code, not 1000s.

[alsi-lawr]

Sounds good in theory, the PR will reveal the truth: 100s of lines of code, not 1000s.

Yeah, in general I like to keep PRs in collaborative environments as small as possible. I know how painful the review burden is for giant PRs, especially for OSS where you're not even paid to endure the burden

[justinmk]

Well, it's more like a design constraint that I think is very important for these clients. They end up being more useful if they are tiny because:

• the surface area is easier for users to understand
• they actually get maintained instead of bit-rotting
• they avoid a bunch of dumb half-working features

[alsi-lawr]

I have consolidated #31, #35, and #40 into one breaking replacement rather than maintaining the current split architecture through sequential migrations.

Product boundary

• One packable project/package/assembly: Nvim.Client.
• One public partial client type: Nvim.Client.NvimClient.
• No compatibility projects, forwarding namespaces, deprecated newest-generation API, or parallel old/new runtime.
• Generator library, generator CLI, and tests remain repository-internal and non-packable. Publishing/version alignment/nightly generation remain in proposal: Publish the RPC client package and align versions with Neovim #36.

The generator and CLI have a hard 2,000-production-line ceiling, targeting 1,400–1,800. Handwritten runtime code must be smaller than the current combined runtime/API baseline.

Runtime and lifecycle

NvimClient will expose borrowed stream/process/stdio attachment, owned synchronous Start, owned ConnectAsync for TCP/Unix sockets/Windows pipes, raw request/notification operations, async request/notification/UI registrations, Completion, StopAsync, and IDisposable.

The runtime uses MessagePack 3.1.8 low-level reader/writer APIs with untrusted-data security, one receive task, serialized frame writes, atomic request IDs, tracked handler tasks, and one terminal-state transition. It removes BlockingCollection, recursive async void, DynamicInvoke, ManualResetEvent, typeless/object-shaped serialization, and indefinite caller requests.

Owned transports/processes are closed deterministically. Supplied streams/processes and stdio remain borrowed. Because an arbitrary borrowed stream read cannot be forcibly cancelled without closing it, stop/dispose settles logical completion without awaiting such a read; any eventual continuation observes terminal state and performs no dispatch or write.

Cancellation cannot tear a MessagePack frame. Pre-write cancellation sends nothing. Post-write request cancellation cancels the caller while retaining correlation so a late response is consumed rather than treated as a protocol fault.

Wire values and generated API

A closed immutable NvimValue hierarchy covers nil, boolean, the complete MessagePack signed/unsigned integer domain, float, string, binary, array, ordered arbitrary-key maps, and raw extensions. Collections/binary inputs are copied and reading is through pattern matching or exhaustive typed Match.

Generated typed *Async methods live directly on the partial NvimClient. Buffer, Window, and Tabpage are immutable client-independent handles passed explicitly to overloads. Only non-deprecated metadata is generated; unsupported LuaRef functions produce visible diagnostics.

The current 69 CLR UI events become generated NvimUiEvent record cases delivered as ordered redraw batches through one registration API.

Generator architecture

Nvim.Client.Generator owns supplied-input metadata/documentation readers, an immutable neutral ApiDefinition, recursive API types, validation/diagnostics, IApiEmitter, GeneratedFileSet, and the C# emitter. The neutral model contains no RPC envelope, runtime codec, Roslyn node, filesystem, process, or C# declaration model.

Nvim.Client.Generator.Cli owns arguments, launching nvim --api-info, optional Doxygen acquisition, filesystem output, diagnostics, and exit codes.

IApiEmitter.Emit(ApiDefinition) returns a deterministic GeneratedFileSet. The C# emitter builds declarations with Roslyn 5.6.0 SyntaxFactory, then CSharpier 1.3.0 is the final formatter. There is no plugin registry, DI framework, Workspaces/source-generator infrastructure, or speculative F# emitter.

Generated files stay tracked under the runtime project, so ordinary builds need neither Neovim nor Doxygen. Tests use focused metadata/documentation fixtures, representative generated compilation, semantic assertions, and one compact formatting golden rather than a full live-metadata snapshot.

Delivery

The branch will contain three buildable logical commits:

1. neutral model, Roslyn emitter, CLI split, and generator fixtures;
2. NvimValue, RPC runtime/lifecycle, generated client surface, deletion of both old runtime projects, and minimum solution/test rewiring needed to stay buildable;
3. final solution/test renames, workflows, README/package metadata, local single-package proof, and deletion audit.

Review corrections will be amended into their owning logical commit rather than appended as fixups. Final verification includes wire/protocol/lifecycle/concurrency tests, owned/borrowed resource behavior, handler isolation and re-entrancy, ordered UI batches, real-Neovim request/inbound-handler/stdio/address paths, Roslyn compilation, CSharpier, all-target build/tests, local pack of exactly Nvim.Client, source-size ceilings, and zero legacy path/namespace/reference hits.

This PR will close #31, #35, and #40. It will not publish a package or absorb #36's release/version policy.