feat: ExcludeNavigationProperties on [GenerateDtos] — EF model-manifest driven

[dkattan]

Follow-up to #396. ORM entities carry navigation and back-reference properties (Tenant? Owner, List<Order> Orders, …) that don't belong in request DTOs — and today each one must be hand-listed in ExcludeProperties. On wide entities that means 30+ nameof(...) entries per attribute, kept in sync by hand as navigations are added.

Manifest shaping drops them automatically, following the EF Core model's own navigation designation — not a type-shape heuristic. And in a project that wires a model manifest into <AdditionalFiles>, shaping is the default: every [GenerateDtos] attribute that leaves ExcludeNavigationProperties unset is shaped, an explicit value wins in both directions, and = false is the per-type opt-out for non-entity source types.

[GenerateDtos(Types = DtoTypes.Create | DtoTypes.Update)]   // shaping needs no per-attribute flag
public class Schedule
{
    public int Id { get; set; }
    public int? TenantId { get; set; }              // kept (mapped scalar column)
    public Tenant? OwnerTenant { get; set; }        // dropped (navigation)
    public List<Job> Jobs { get; } = new();         // dropped (collection navigation)
}

The DTO keeps exactly the properties EF maps as data (scalar columns, complex/value-object members, primitive collections) and drops navigations, skip navigations, owned references, and [NotMapped] members. Because it reads the real model, it's correct where a type-shape guess can't be: a same-assembly class stored through a value converter is kept (the model maps it as a column), and a scalar-looking property the model ignores is dropped. IncludeProperties forces aggregate children (edited with their parent) back in.

How it works: the EF model manifest

Facet.Extensions.EFCore ships design-time services that write a manifest ({ContextName}.facetmodel.json) beside the migrations model snapshot on every dotnet ef migrations add/remove, by subclassing MigrationsScaffolder and walking the finalized IModel. Per entity it records which members EF maps as data (scalar/complex) and which are nav/owned/skipnav/ignored/service. It's committed like the snapshot and stays exactly as fresh as it — the same workflow that keeps migrations honest keeps DTO shapes honest. Register the services with one property in the DbContext project's csproj — the package ships a buildTransitive targets file that expands it to the assembly attribute below (EF reads that attribute from the DbContext project's assembly or the startup assembly, and de-duplicates, so either placement works):

<FacetEfDesignTime>true</FacetEfDesignTime>

[assembly: Microsoft.EntityFrameworkCore.Design.DesignTimeServicesReference(
    "Facet.Extensions.EFCore.Design.FacetDesignTimeServices, Facet.Extensions.EFCore")]

The same property also wires the project's own manifests into the compilation as AdditionalFiles, so a single-project setup has exactly one knob: write manifests, consume manifests, shaping on. It is deliberately opt-in — a package reference alone never changes what migrations write or what the compiler consumes — and a coded warning (FACET001) flags the property under GenerateAssemblyInfo=false, where assembly attributes cannot be emitted.

The generator consumes it as an AdditionalFile in the project that declares [GenerateDtos] — pre-wired by FacetEfDesignTime when that is the DbContext project itself, or one explicit cross-project glob otherwise (a cross-project manifest path is knowledge only the consuming project has, so that step cannot be automated away; duplicate wiring is a pinned no-op — the reader merges per file by union):

<AdditionalFiles Include="../MyApp.Persistence/Migrations/*.facetmodel.json" />

In a layered solution three different projects are involved (startup / migrations / [GenerateDtos]), so the glob usually reaches across projects — the README has a Mermaid diagram of the layout and a role table. The manifest is versioned JSON, written with Utf8JsonWriter and read with JsonDocument; each file is parsed atomically (a malformed or future-version file is ignored in full, never half-applied), unknown properties are skipped so the schema can grow, and reader equality is structural so formatting-only edits don't bust the incremental cache.

No heuristic, no silent fallback

There is deliberately no type-shape heuristic. An earlier revision of this branch shipped one as a zero-setup default; it was removed before merge because it's fragile in exactly the ways the manifest fixes (value-converted columns, cross-assembly entities, [NotMapped] scalars), and shipping a fragile default only to remove it later would strand adopters. EF is the ORM Facet users overwhelmingly reach for, so requiring its model up front is the right constraint. Consequently every failure is a diagnostic — nothing is ever silently guessed:

Rule	Severity	Fires when
FAC103	Error	a manifest file is malformed (ignored in full, and said so)
FAC104	Error	a manifest declares an unsupported version (package mismatch)
FAC105	Error	a shaped type — explicit or defaulted; the message says which — has no manifest entry. With an explicit = true this also catches a mistyped <AdditionalFiles> glob (matches-nothing is silently empty)
FAC106	Warning	a settable property on a listed type is unknown to the model — the manifest predates it, and it would otherwise silently vanish from the DTO

Wiring the manifest is the project-level switch: a project with a manifest shapes by default, a project without one copies properties as-is, and a rejected-only manifest set does not flip the default — FAC103/FAC104 stand alone instead of being buried under a FAC105 cascade. The obsolete [GenerateAuditableDtos] is exempt from the default; it cannot express the opt-out. One caveat is documented honestly with a tripwire: under the default, a glob that matches nothing means no wired manifest, no shaping, and no diagnostics — pinning = true on one representative entity turns that into a hard error.

To make FAC106 sound, the manifest records everything the model has an opinion on, including ignored (explicitly ignored members, recovered from the convention surface across the inheritance chain) and service (ILazyLoader-style). Computed get-only properties are exempt — the model never maps them. On a large real-world consumer model that recovered 69 ignored members across 128 entities, each a FAC106 false positive otherwise. FAC101–FAC106 anchor to the [GenerateDtos] attribute (a cache-safe location capture on the model), so they land as squiggles and are #pragma-suppressible. FAC105 is already an error; escalate FAC106 for CI with <WarningsAsErrors>$(WarningsAsErrors);FAC106</WarningsAsErrors> and a PR that changes the model without regenerating the manifest can't merge green.

Verified end to end against the real-world consumer: the design-time hook produces a 128-entity manifest; a wide entity's two ~37-entry ExcludeProperties lists collapse to a handful of scalar excludes; generated contracts match the model's designation exactly; and a deliberately broken <AdditionalFiles> path on an explicitly shaped type fails the build with FAC105 rather than silently mis-shaping DTOs. A separate cold-consumer end-to-end (local NuGet feed → fresh console app → dotnet ef → build) verified the packaged flow: the FacetEfDesignTime opt-in respected in both directions, the manifest written on migrations add and surviving remove, implicit shaping with zero AdditionalFiles in the csproj (-getItem:AdditionalFiles shows exactly the package glob's match), FAC105 with the defaulted-mode message on an uncovered type, the = false escape hatch, and identical output under double wiring.

Generator framework: SourceGenerator.Foundations

Reading JSON inside a netstandard2.0 analyzer is possible because this PR also adopts SourceGenerator.Foundations (2.0.16, PrivateAssets="all" — nothing leaks to consumers). SGF hoists the generator behind a generated wrapper and embeds referenced assemblies (System.Text.Json and friends, even Facet.Attributes.dll) into Facet.dll, resolving them at load time — the sanctioned way for an analyzer to carry NuGet dependencies into every compiler host, including VS's .NET Framework one — which also retires the manual <Analyzer Include> registration ProjectReference consumers previously needed for Facet.Attributes (cold builds died with CS8784). It brings exception isolation around every callback and a logger (SgfLogLevel). Embedding is trimmed to the runtime closure (Workspaces + System.Composition excluded — IDE hosts provide them; embedding Roslyn-family assemblies risks type identity), keeping the analyzer ~4 MB. Driver-based tests instantiate the generated internal hoist (InternalsVisibleTo).

Tests

Suite 962/962 (rebased onto master with #397 and #400 merged; includes two facts pinning the integration seam — an assembly-level [GenerateDtosFor] registration gets the same manifest-driven shaping through the shared pipeline, and an uncovered assembly-level type reports FAC105 anchored at the [assembly:] attribute — plus eleven pinning the wired-manifest default: unset-flag shaping with and without a manifest, implicit FAC105 naming the defaulted mode and the escape hatch, explicit-false opt-out, an empty-but-valid manifest still counting as wired, rejected-only manifests not flipping the default, FAC106 on implicitly shaped types, and the [GenerateAuditableDtos] exemption in both shape and diagnostics). Coverage: generator (driver + in-memory AdditionalFiles) — manifest keep-set drops navs and [NotMapped] scalars, value-converted entity-typed columns survive, IncludeProperties overrides a manifest drop, an uncovered type drops nothing (keeps all members) and is FAC105, malformed/unsupported files are ignored atomically with FAC103/FAC104 reported, multi-context manifests union per type; diagnostics — FAC105 error for no-manifest and type-absent (once per type despite flags expansion, attribute-anchored), FAC106 for stale manifest, quiet for computed properties / complete manifests / non-ExcludeNavigationProperties types; manifest writer (real Sqlite model) — scalars/complex/primitive collections kept, nav/owned/skipnav/ignored categorized, shadow members absent, deterministic output; end-to-end through EF's real design-time pipeline — FacetDesignTimeServices swaps in the scaffolder and ScaffoldMigration + Save produces the manifest beside the snapshot.

🤖 Generated with Claude Code

[dkattan]

Rebased onto #401's branch so the preview-publish guard applies here too — that's why this PR temporarily shows the one-line preview.yml commit. It falls away automatically on the next rebase once #401 lands on master; the feature diff is unchanged.

🤖 Addressed by Claude Code