Skip to content

feat: let a facet assembly reference nothing it was shaped from - #442

Open
kevin-mcmanus wants to merge 1 commit into
Tim-Maes:masterfrom
kevin-mcmanus:feature/contract-mode
Open

kevin-mcmanus wants to merge 1 commit into
Tim-Maes:masterfrom
kevin-mcmanus:feature/contract-mode

Conversation

@kevin-mcmanus

@kevin-mcmanus kevin-mcmanus commented Oct 12, 2026 •

Copy link
Copy Markdown

This addresses most of what #143 asks for, and the part that works without the second generator. Please refer to the issue for the background and motivation.

A facet in a contract or domain project drags that project's dependency on the source layer into the compiled output. Three independent things do it: the typeof in [Facet], which is serialised into the attribute blob; the generated *.Mappings.g.cs, where the constructor, FromSource and Projection all name the source type; and nested property types, which are copied with the source's type rather than the facet's.

Two properties close the first two:

<Facet_GenerateMappings>false</Facet_GenerateMappings>
<Facet_EmitAttributeMetadata>false</Facet_EmitAttributeMetadata>

The attributes become [Conditional(FACET_KEEP_ATTRIBUTES)]. The generator reads them from the semantic model either way, so generation is unaffected — only the emitted blob changes, and the compiler then elides the references that only those arguments were keeping alive. Facet.Attributes.targets defines the symbol by default, so every existing project is unchanged. It lives in that package rather than in Facet on purpose: the [Conditional] is on a type there, so a project referencing the attributes without the generator would otherwise lose its attributes with no targets file through which to ask for them back.

NestedFacets already closed the third — what it didn't do was say so when you'd forgotten. Two new warnings cover the silent failures, both only where Facet_GenerateMappings=false:

  • FAC116 — a generated property still typed from the layer the facet was shaped from. Anchored on the [Facet] attribute, where NestedFacets goes.
  • FAC117 — a Configuration, BeforeMapConfiguration, AfterMapConfiguration or ToSourceConfiguration on a facet whose mappings are suppressed. The members that would call the hook are never generated, so it compiles and does nothing.

Facet.Tests.ExternalLib now doubles as a contract assembly, so the result is tested rather than argued: ContractAssemblyReferenceTests reads the emitted metadata and asserts no source-typed constructor, no Projection, no FromSource, and no Facet.Attributes reference. Separately, I built a contract project whose facets include a nested one against the packed output, and its only assembly reference was System.Runtime.

What it doesn't do

It removes the mapping rather than relocating it. The mapping has to be written in a project that references both layers. Facet's facets already suit that — their members are settable and the generated projection is an object initializer, so a hand-written static class can both populate one and project to one in a query. docs/22_ContractAssemblies.md shows it. Generating that mapper is a follow-up PR (#443), which can be taken or left independently of this one.

Trade-offs

  • Facet.Extensions' single-generic overloads stop working in an assembly that opts out: ToFacet<TTarget>(object), ToSource<TSource>(object) and BackTo<TSource>(object) (which delegates to ToSource) all resolve the type by reading Facet.FacetAttribute at runtime. The two-generic overloads are unaffected — they go through the generated constructor and read no attribute — so the workaround is the variant the library already recommends for performance. In practice a contract assembly has no mapping members either, so it's mapped from outside regardless.
  • Both properties are per-project, not per-type — DefineConstants and generator configuration apply to the whole compilation.

Checklist

  • I read the contributing guide and followed the code of conduct.
  • I added or updated tests when behavior changed.
  • I updated documentation, samples, or release notes when needed.
  • I ran dotnet test locally.
  • My change is ready for review.

A facet in a contract or domain project drags that project's dependency
on the source layer into the compiled output, which is what makes Facet
awkward in a layered solution (Tim-Maes#143). Three separate things do it: the
typeof inside [Facet], the generated mapping members that name the source
type, and nested property types copied across as the source's own.

Two properties close the first two:

  Facet_GenerateMappings=false      omits the *.Mappings.g.cs half
  Facet_EmitAttributeMetadata=false keeps Facet's attributes, and so the
                                    typeof inside them, out of metadata

The attributes are now [Conditional(FACET_KEEP_ATTRIBUTES)]. The
generator reads them from the semantic model either way, so generation is
unaffected; only the emitted blob changes, and the compiler then elides
the references that only those arguments were keeping alive.
Facet.Attributes.targets defines the symbol by default, so every existing
project is unchanged — and it lives in that package rather than in Facet
because the [Conditional] is on a type there: a project referencing the
attributes without the generator would otherwise lose its attributes with
no targets file through which to ask for them back.

NestedFacets already closes the third, but silently. Two new diagnostics
cover the ways this quietly fails, both only where the project has
declared its facets to be contracts:

  FAC116  a generated property still typed from the source layer
  FAC117  a mapping hook that cannot run, because the members that would
          call it are the suppressed ones

Facet.Tests.ExternalLib doubles as a contract assembly so the claim is
tested rather than argued: ContractAssemblyReferenceTests reads the
emitted metadata and asserts no source-typed constructor, no Projection,
no FromSource and no Facet.Attributes reference.

Verified end to end through the built package: a contract project whose
facets include a nested one compiles to an assembly whose only reference
is System.Runtime.

This removes the mapping rather than relocating it — a partial type cannot
span assemblies, so the mapping has to be something free-standing, in a
project that references both layers. Facet's facets suit that already:
their members are settable and the projection is an object initializer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant