Es/ref data code gen

.github/instructions/namespace_readme_template.md

@@ -0,0 +1,124 @@
+# NAMESPACE README TEMPLATE
+
+This file is an authoring guide and template for creating `README.md` files across the `CoreEx` library projects. Every `<instruction>` block below is guidance for the author and must be removed from the final output. All placeholder text in `[square brackets]` must be replaced with real content.
+
+---
+
+## Research checklist (do this before writing)
+
+Before authoring any README, gather the following context:
+
+1. **Read all source files** in the target namespace/folder — XML doc comments are the primary source of truth for descriptions.
+2. **Check usages in other `src\` projects** — frequent references reveal which types are most important.
+3. **Check usages in `samples\`** — especially the Contoso domains; use this to inform importance, relevance, and accurate descriptions, but do not reference or link to samples in the README output itself.
+4. **Read the `.csproj`** — NuGet dependencies (non-Microsoft ones in particular) to determine if they should be linked in Additional Resources.
+5. **Check child folders** — decide which sub-namespaces have enough public surface to warrant their own README.
+
+---
+
+## Agreed authoring conventions
+
+These conventions apply to every README created from this template:
+
+- **No NuGet badges or install snippets.** The root `README.md` holds all package badges and `dotnet add package` commands; do not repeat them here.
+- **No code blocks, usage examples, or sample references.** READMEs document the namespace/package — they do not demonstrate usage. The Contoso samples under `samples/` have their own dedicated READMEs for that purpose. Do not link to or mention samples anywhere in a namespace README.
+- **Type table formatting:**
+  - **`Bold link`** — concrete/public classes and structs.
+  - _`Italic link`_ — abstract base classes.
+  - [`Plain link`] — interfaces.
+  - Enums and static utility classes use **bold** like concrete types.
+- **`Abstractions` sub-folders** — contain internal or foundational base types; only create a child README if the public surface is large enough to warrant one.
+- **README depth** — always create READMEs for first-level child namespaces. Only recurse into deeper levels (child-child and beyond) where there is genuinely material content — thin wrappers, single-file folders, or purely internal helpers do not need a README.
+- **Related Namespaces** — always annotate test-only relationships with `_(test only)_` after the description.
+- **Omit empty sections** — if a section has no material content (e.g., no external resources, no child namespaces), omit the section heading and body entirely rather than leaving a placeholder.
+- **Proceed project by project** — complete all namespace READMEs for one project before starting the next.
+
+---
+
+## Template (copy everything below this line into the new README.md)
+
+---
+
+<!-- <instruction> Replace `[Namespace]` in the title with the actual namespace or package name, e.g. `CoreEx.Events`. </instruction> -->
+
+# CoreEx.[Namespace]
+
+<!-- <instruction> Write 1-2 sentences that precisely describe what this namespace/package provides. Be specific — avoid vague phrases like "provides utilities for". </instruction> -->
+
+> Brief description of what this namespace/package provides.
+
+## Overview
+
+<!-- <instruction>
+Write 2-3 paragraphs covering:
+- The concrete problem or gap this namespace addresses.
+- The primary scenarios and patterns where it is used.
+- How it relates to and fits into the broader CoreEx ecosystem.
+</instruction> -->
+
+## Motivation
+
+<!-- <instruction>
+Include this section ONLY at the project (top-level package) README — not in child-namespace READMEs.
+Explain why this project exists: what gaps in .NET or other frameworks it addresses, the design principles that shaped it, and why it was built the way it was. Prefer concise dot-pointed lists over dense paragraphs.
+</instruction> -->
+
+- Motivation point 1.
+- Motivation point 2.
+
+## Key capabilities
+
+<!-- <instruction>
+List the headline capabilities. Each bullet should start with a relevant emoji, a **bold capability name**, then a brief plain-English description of the benefit to the user. Aim for 4–8 bullets at the project level; 3–5 at child-namespace level.
+</instruction> -->
+
+- 🔷 **Capability name**: Description of the capability and its benefit.
+
+## Key types
+
+<!-- <instruction>
+List the most important public types in this namespace. Derive importance from: XML doc comment content, how widely they are referenced across `src\` and `samples\`, and whether they form part of the public contract or extension points.
+
+Formatting rules:
+- **`Bold link`** — concrete classes and structs.
+- _`Italic link`_ — abstract base classes.
+- [`Plain link`] — interfaces.
+- Enums and static utility classes use **bold** like concrete types.
+
+Only include types from this specific namespace folder — child-namespace types are covered in their own README.
+</instruction> -->
+
+| Type | Description |
+|------|-------------|
+| **[`ClassName`](./ClassName.cs)** | What this class does. |
+| _[`AbstractBase`](./AbstractBase.cs)_ | What this abstract class provides. |
+| [`IInterface`](./IInterface.cs) | What this interface defines. |
+
+## Namespaces
+
+<!-- <instruction>
+Include this section ONLY at the project (top-level package) README — not in child-namespace READMEs, unless that namespace itself has notable sub-namespaces with material content.
+List all first-level child namespaces. For each, create the corresponding child README and link to it. Only include deeper levels (child-child) where there is material content worth documenting.
+</instruction> -->
+
+| Namespace | Description | Documentation |
+|-----------|-------------|---------------|
+| **`CoreEx.[Child]`** | Brief description of what this child namespace contains. | [📖 README](./[Child]/README.md) |
+
+## Related Namespaces
+
+<!-- <instruction>
+List other CoreEx namespaces/packages that have a strong relationship to this one — including sibling packages, packages that extend this one, or packages this one commonly works alongside. Use relative links. Annotate test-only relationships with `_(test only)_`.
+Omit this section if there are no meaningful relationships to document.
+</instruction> -->
+
+- **[`CoreEx.RelatedNamespace`](../RelatedNamespace/README.md)** - Brief description of the relationship.
+- **[`CoreEx.TestHelper`](../../CoreEx.UnitTesting/README.md)** - Brief description. _(test only)_
+
+## Additional Resources
+
+<!-- <instruction>
+Include this section only if there are genuinely useful external resources — non-Microsoft NuGet dependencies, relevant RFCs, specification documents, or authoritative external docs. Omit entirely if there is nothing material to link.
+</instruction> -->
+
+- [Resource name](https://example.com) - Brief description of why it is relevant.

.github/workflows/CI.yml

@@ -93,6 +93,14 @@ jobs:
     - name: Build samples
       run: dotnet build CoreEx.Samples.Build.slnf --no-restore --configuration Release
 
+    - name: CodeGen tool (samples/src/Contoso.Products.CodeGen)
+      working-directory: samples/src/Contoso.Products.CodeGen
+      run: dotnet run refdata --no-build --configuration Release -f net10.0 --expect-no-changes
+
+    - name: CodeGen tool (samples/src/Contoso.Shopping.CodeGen)
+      working-directory: samples/src/Contoso.Shopping.CodeGen
+      run: dotnet run refdata --no-build --configuration Release -f net10.0 --expect-no-changes
+
     - name: Database tool (samples/src/Contoso.Products.Database)
       working-directory: samples/src/Contoso.Products.Database
       run: dotnet run all --no-build --configuration Release -f net10.0 --expect-no-changes

CoreEx.Samples.Build.slnf

@@ -13,13 +13,15 @@
       "samples/src/Contoso.Orders.Infrastructure/Contoso.Orders.Infrastructure.csproj",
       "samples/src/Contoso.Products.Api/Contoso.Products.Api.csproj",
       "samples/src/Contoso.Products.Application/Contoso.Products.Application.csproj",
+      "samples/src/Contoso.Products.CodeGen/Contoso.Products.CodeGen.csproj",
       "samples/src/Contoso.Products.Contracts/Contoso.Products.Contracts.csproj",
       "samples/src/Contoso.Products.Database/Contoso.Products.Database.csproj",
       "samples/src/Contoso.Products.Infrastructure/Contoso.Products.Infrastructure.csproj",
       "samples/src/Contoso.Products.Outbox.Relay/Contoso.Products.Outbox.Relay.csproj",
       "samples/src/Contoso.Products.Subscribe/Contoso.Products.Subscribe.csproj",
       "samples/src/Contoso.Shopping.Api/Contoso.Shopping.Api.csproj",
       "samples/src/Contoso.Shopping.Application/Contoso.Shopping.Application.csproj",
+      "samples/src/Contoso.Shopping.CodeGen/Contoso.Shopping.CodeGen.csproj",
       "samples/src/Contoso.Shopping.Contracts/Contoso.Shopping.Contracts.csproj",
       "samples/src/Contoso.Shopping.Database/Contoso.Shopping.Database.csproj",
       "samples/src/Contoso.Shopping.Domain/Contoso.Shopping.Domain.csproj",

CoreEx.sln

@@ -19,6 +19,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		README.md = README.md
 		SECURITY.md = SECURITY.md
 		strong-name-key.snk = strong-name-key.snk
+		Version.props = Version.props
 	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.RefData", "src\CoreEx.RefData\CoreEx.RefData.csproj", "{F3F98268-80E9-4441-B6C9-8D384EE9C857}"
@@ -33,6 +34,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{F31B53BC-66D
 	ProjectSection(SolutionItems) = preProject
 		src\Directory.Build.props = src\Directory.Build.props
 		src\Directory.Build.targets = src\Directory.Build.targets
+		NAMESPACE_README_TEMPLATE.md = NAMESPACE_README_TEMPLATE.md
 	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Data.Test.Unit", "tests\CoreEx.Data.Test.Unit\CoreEx.Data.Test.Unit.csproj", "{E2348CBC-7FF4-4A35-9154-8CE4A2BD8D08}"
@@ -78,6 +80,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{5B5342D2-2392-4EB8-9933-A21DB9416534}"
 	ProjectSection(SolutionItems) = preProject
 		samples\Directory.Build.props = samples\Directory.Build.props
+		samples\README.md = samples\README.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Products", "Products", "{3467DBAC-5C5C-4FED-8EB5-95F5D3FE12EC}"
@@ -203,6 +206,35 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Database.Postgres.Te
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Database.Postgres.Test.Unit", "tests\CoreEx.Database.Postgres.Test.Unit\CoreEx.Database.Postgres.Test.Unit.csproj", "{6C876E5E-5972-4801-9565-E314545BBB06}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.CodeGen", "src\CoreEx.CodeGen\CoreEx.CodeGen.csproj", "{DCC0817E-82E5-F60F-672D-BF676943856B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Contoso.Products.CodeGen", "samples\src\Contoso.Products.CodeGen\Contoso.Products.CodeGen.csproj", "{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Contoso.Shopping.CodeGen", "samples\src\Contoso.Shopping.CodeGen\Contoso.Shopping.CodeGen.csproj", "{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tools", "tools", "{7B24A1A9-1C76-4248-BB63-9D5C4328F5BD}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Tooling.Console", "tools\CoreEx.Tooling.Console\CoreEx.Tooling.Console.csproj", "{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "schema", "schema", "{7868FB2C-9E74-42AB-9A65-A1E3C3BC9B3D}"
+	ProjectSection(SolutionItems) = preProject
+		schema\coreex-refdata.json = schema\coreex-refdata.json
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{4BE535E8-747F-4CC5-85D6-CF1460964AA3}"
+	ProjectSection(SolutionItems) = preProject
+		samples\docs\application-layer.md = samples\docs\application-layer.md
+		samples\docs\aspire.md = samples\docs\aspire.md
+		samples\docs\contracts-layer.md = samples\docs\contracts-layer.md
+		samples\docs\domain-layer.md = samples\docs\domain-layer.md
+		samples\docs\hosts-layer.md = samples\docs\hosts-layer.md
+		samples\docs\infrastructure-layer.md = samples\docs\infrastructure-layer.md
+		samples\docs\layers.md = samples\docs\layers.md
+		samples\docs\patterns.md = samples\docs\patterns.md
+		samples\docs\testing.md = samples\docs\testing.md
+		samples\docs\tooling.md = samples\docs\tooling.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -1005,6 +1037,54 @@ Global
 		{6C876E5E-5972-4801-9565-E314545BBB06}.Release|x64.Build.0 = Release|Any CPU
 		{6C876E5E-5972-4801-9565-E314545BBB06}.Release|x86.ActiveCfg = Release|Any CPU
 		{6C876E5E-5972-4801-9565-E314545BBB06}.Release|x86.Build.0 = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|x64.Build.0 = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Debug|x86.Build.0 = Debug|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|x64.ActiveCfg = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|x64.Build.0 = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|x86.ActiveCfg = Release|Any CPU
+		{DCC0817E-82E5-F60F-672D-BF676943856B}.Release|x86.Build.0 = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|x64.Build.0 = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Debug|x86.Build.0 = Debug|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|x64.ActiveCfg = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|x64.Build.0 = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|x86.ActiveCfg = Release|Any CPU
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1}.Release|x86.Build.0 = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|x64.Build.0 = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Debug|x86.Build.0 = Debug|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|x64.ActiveCfg = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|x64.Build.0 = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|x86.ActiveCfg = Release|Any CPU
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC}.Release|x86.Build.0 = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|x64.Build.0 = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Debug|x86.Build.0 = Debug|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|Any CPU.Build.0 = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|x64.ActiveCfg = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|x64.Build.0 = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|x86.ActiveCfg = Release|Any CPU
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -1092,6 +1172,11 @@ Global
 		{1855A84E-4876-49A4-AC22-3881ECAB2534} = {F31B53BC-66DD-4844-8349-D4B0CB04EA12}
 		{06B73659-3DFE-41B2-B8DF-42C25CD547D6} = {D37F89FC-A03D-4501-8414-34AE0C6FC765}
 		{6C876E5E-5972-4801-9565-E314545BBB06} = {D37F89FC-A03D-4501-8414-34AE0C6FC765}
+		{DCC0817E-82E5-F60F-672D-BF676943856B} = {F31B53BC-66DD-4844-8349-D4B0CB04EA12}
+		{D7B0D852-BEE1-4CFE-9369-C487858A4DE1} = {3CEF11D5-9320-4BDA-A7A8-5D1FCE868FE3}
+		{902CF0FC-5CF1-404F-ABFA-F6008E29C8CC} = {83C087DA-703F-41A5-994B-C132EB812835}
+		{ABDC084E-26B9-4900-9BFF-A26D9D8542D0} = {7B24A1A9-1C76-4248-BB63-9D5C4328F5BD}
+		{4BE535E8-747F-4CC5-85D6-CF1460964AA3} = {5B5342D2-2392-4EB8-9933-A21DB9416534}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {99046729-5A7F-41B6-9415-F77D8E9C44F1}

Directory.Packages.props

@@ -65,12 +65,13 @@
   <ItemGroup>
     <PackageVersion Include="AwesomeAssertions" Version="9.4.0" />
     <PackageVersion Include="coverlet.collector" Version="6.0.4" />
-    <PackageVersion Include="DbEx.Postgres" Version="3.0.1" />
-    <PackageVersion Include="DbEx.SqlServer" Version="3.0.1" />
+    <PackageVersion Include="DbEx.Postgres" Version="3.0.2" />
+    <PackageVersion Include="DbEx.SqlServer" Version="3.0.2" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
     <PackageVersion Include="NUnit" Version="4.3.2" />
     <PackageVersion Include="NUnit.Analyzers" Version="4.9.0" />
     <PackageVersion Include="NUnit3TestAdapter" Version="5.0.0" />
+    <PackageVersion Include="OnRamp" Version="2.2.4" />
     <PackageVersion Include="UnitTestEx" Version="5.11.0" />
     <PackageVersion Include="UnitTestEx.NUnit" Version="5.11.0" />
   </ItemGroup>