Dev Log: The first public API, and the type graph that wouldn't stay small

I’m reviving Munchausen, a C# NuGet package I started 9 years ago. This is part 4 of an 8-part series documenting both the development process and the engineering decisions behind bringing the project back to life.

This is the Dev Log: the practical work, cleanup, implementation steps, and day-to-day progress behind this part of the project.

M3 is a milestone with a flag on it: the first public surface. Lie.Define<T>(),
the fluent builder, the options records. Up to now everything was internal
plumbing nobody could call. Now I'm testing the API I designed by committing to
shapes that users will eventually depend on. Once a public member ships, changing
it becomes expensive.

The builder is deliberately lazy

The fun design decision here is that the builder does almost nothing. You call
.With(...), .Ignore(...), .Derive(...) and it just appends a little record
and hands you back this. No validation, no parsing. All of that is deferred to
Build(). It feels almost too lazy until you see why: you want all your
definition errors reported together, in one exception, not dribbled out one
throw at a time as you chain methods. So the builder's job is purely to remember
what you said, in order, and Build() is where judgment happens. Cheap builder,
smart compile.

"Wait, I have to declare half the library"

Here's the thing that caught me. To write the builder's method signatures, I need
the types they mention. With(...) takes a Func<GenerationContext, T>. Build()
returns a LieDefinition<T>. Explain() returns an InferenceReport. None of
those are built yet, they're milestones away. But you can't have a public method
whose parameter type doesn't exist.

So M3 quietly drags a chunk of the type graph into existence as stubs: public
types, fully documented, whose bodies just throw new NotImplementedException().
When I divided the work into stages, I allowed those placeholders until M6. It
still feels strange to add a GenerationContext that does nothing and a
Generate() that refuses to run, but it lets me test the complete API shape
before every behavior exists.

Falling in love with dotnet format

Maintaining the locked-surface text file by hand is miserable, you have to write
each entry in the analyzer's exact dialect, down to how int.MinValue is spelled
and where the ! nullability markers go. I discovered that
dotnet format analyzers --diagnostics RS0016 just generates all of it
correctly. Run it, review the generated surface against the API I designed, move
the lines into the shipped file. This will become a recurring character in the
story, including the episode two milestones from now where it inexplicably stops
working and I waste real time before figuring out why.

A small principled stand

The analyzer also complained (RS0026) about the two Generate overloads both
having optional parameters, a legitimate general warning, but it conflicted with
the API shape I had chosen. This forced me to revisit that choice rather than
blindly obey either side. I still preferred the overloads, so I suppressed the
rule with a comment explaining why. A linter is useful evidence, not the designer.

Where it leaves things

You can now write the fluent thing:

Lie.Define<Car>()
   .WithName("cars")
   .With(c => c.Make, "Saab")
   .With(c => c.Model, ctx => "900")
   .Derive(c => c.Year, (ctx, c) => 1989)
   .WithSeed(42);

…and it compiles, captures everything correctly, and rejects x => x.Owner.Name
with a clear LIE001. Build() still throws, there's no compiler yet, but the
ergonomics are real, and the public surface is locked and reviewed.

What's next

M4: inference. This is the milestone with opinions, the catalog that decides
FirstName should be a first name and Price should be money. It's also where I
find the first genuine contradiction in my design and have to decide which
behavior better serves the user.