diff --git a/lode/dotnet/analyzers.md b/lode/dotnet/analyzers.md index 9da3a677..752347cc 100644 --- a/lode/dotnet/analyzers.md +++ b/lode/dotnet/analyzers.md @@ -1,5 +1,5 @@ # .NET 10 Roslyn Analyzers -*Updated: 2026-11-13T13:54:59Z* +*Updated: 2026-11-16T16:20:12Z* ## Strategy: Deny by Default @@ -33,13 +33,16 @@ In `Directory.Build.props`: ```xml latest-all All +All +All +All true true true ``` Key interactions: -- `AnalysisLevel=latest-all` and `AnalysisMode=All` both select mode `All` in every category. A compound `AnalysisLevel` wins over `AnalysisMode`, so the repo sets no category line. Do not set `AnalysisMode` below `All`, because the CA rules that are off in `Recommended` would stop running. +- `AnalysisLevel=latest-all` and `AnalysisMode=All` both select mode `All` in every category. The security, reliability, and performance category lines repeat that mode. They state the AI SDLC Readier policy explicitly. Do not set `AnalysisMode` below `All`, because the CA rules that are off in `Recommended` would stop running. - `EnforceCodeStyleInBuild` makes IDE rules (IDE*) fire during `dotnet build` - `TreatWarningsAsErrors` promotes all enabled warnings to errors diff --git a/lode/dotnet/architecture-testing.md b/lode/dotnet/architecture-testing.md index 4262305f..f87733a6 100644 --- a/lode/dotnet/architecture-testing.md +++ b/lode/dotnet/architecture-testing.md @@ -1,5 +1,5 @@ # Architecture Testing -*Updated: 2026-11-08T17:33:22Z* +*Updated: 2026-11-16T16:20:12Z* ## Overview @@ -9,7 +9,12 @@ - `TngTech.ArchUnitNET.xUnitV3`: xUnit v3 integration (includes core and assertions). Version pinned in `Directory.Packages.props`. -The test project references only `E128.Reference.Core`. The architecture model loads the Core assembly (`typeof(Greeter).Assembly`). To analyze additional layers (Web, Cli), add both a `ProjectReference` to those projects and their assemblies to `ArchitectureBaseline`. A project carrying a `ProjectReference` without a loaded assembly is dead weight (`/prune-deps` flags it). +The test project references every production project under `src/`. Two models exist: + +- `ArchitectureBaseline` loads only the Core assembly (`typeof(Greeter).Assembly`). The layer, naming, sealed, and service rules use it. +- `ProjectReferenceBaseline` loads every production assembly by name. `ProjectBoundaryTests` uses it. + +A `ProjectReference` without a loaded assembly is dead weight (`/prune-deps` flags it). ## How It Works @@ -66,10 +71,25 @@ Enforces dependency direction: Models depend on nothing, Services depend on Mode - Service classes must have "Service" suffix - Repository classes (in `Repositories` namespace) must implement `IGreetingRepository` +### Project Boundaries (`ProjectBoundaryTests`) + +Each production assembly has one rule. The rule forbids a dependency on a production assembly outside the transitive `ProjectReference` closure of the project. An analyzer reference with `ReferenceOutputAssembly="false"` is not a compile reference, so it is not in the closure. + +```mermaid +graph LR + CodeFixers[E128.Analyzers.CodeFixers] --> Analyzers[E128.Analyzers] + Cli[E128.Reference.Cli] --> Core[E128.Reference.Core] + Web[E128.Reference.Web] --> Core +``` + +The allowed graph is a literal baseline. The tests never compute it from the current graph. A new `ProjectReference` therefore fails a rule until a reviewer updates the baseline. + +Coverage instrumentation injects a tracker type with one full name into each instrumented assembly. ArchUnitNET merges that type across assemblies, so the rules exclude the `Microsoft.CodeCoverage.Instrumentation.Static.Tracker` namespace. Without the exclusion, `scripts/coverage.sh` fails the boundary rules. + ## Adding New Rules 1. Create a new test class in `tests/Architecture.Tests/` -2. Reference `ArchitectureBaseline.Instance` +2. Reference `ArchitectureBaseline.Instance`, or `ProjectReferenceBaseline.Instance` for a rule across assemblies 3. Define rules using `ArchRuleDefinition` fluent API 4. Tag with `[Trait("Category", "CI")]` 5. If analyzing additional assemblies, add a `ProjectReference` to the target project **and** load its assembly in `ArchitectureBaseline` diff --git a/lode/terminology.md b/lode/terminology.md index 947ae715..3effa27a 100644 --- a/lode/terminology.md +++ b/lode/terminology.md @@ -1,5 +1,5 @@ # Terminology -*Updated: 2026-11-12T00:54:46Z* +*Updated: 2026-11-16T16:20:12Z* - **CPM**: Central Package Management. NuGet feature where all package versions are declared in `Directory.Packages.props` rather than per-project. - **MTP**: Microsoft Testing Platform. The modern test execution platform used by xUnit v3, replacing the legacy vstest runner. @@ -12,7 +12,7 @@ - **Roslyn Analyzer**: A .NET compiler extension that provides real-time code analysis and diagnostics. This project ships `E128.Analyzers`, a custom analyzer package with design, style, and file-system rules. - **MCP**: Model Context Protocol. An open protocol that exposes tools, prompts, and resources to an AI client. This repository connects the Roslyn Navigator server over stdio. See `lode/infrastructure/roslyn-navigator-mcp.md`. - **Roslyn Navigator**: The `cwm-roslyn-navigator` .NET tool. It loads the solution with Roslyn and answers structural code questions over MCP. See `lode/infrastructure/roslyn-navigator-mcp.md`. -- **ArchUnitNET**: Architecture testing library for .NET. Used in `tests/Architecture.Tests/` to enforce layer dependencies, naming conventions, and sealed-class policies. +- **ArchUnitNET**: Architecture testing library for .NET. Used in `tests/Architecture.Tests/` to enforce project boundaries, layer dependencies, naming conventions, and sealed-class policies. - **Trusted Publishing**: OIDC-based NuGet publishing. The `publish.yml` workflow authenticates to NuGet via OIDC rather than long-lived API keys. - **OIDC**: OpenID Connect. The token protocol behind Trusted Publishing. It exchanges a short-lived token for a publish credential instead of a stored API key. - **Renovate**: Dependency management bot. Configured in `renovate.json` to group updates, auto-merge patch/minor, and flag majors for review. diff --git a/tests/Architecture.Tests/Architecture.Tests.csproj b/tests/Architecture.Tests/Architecture.Tests.csproj index 022d66d5..df5ef6bb 100644 --- a/tests/Architecture.Tests/Architecture.Tests.csproj +++ b/tests/Architecture.Tests/Architecture.Tests.csproj @@ -10,7 +10,11 @@ + + + + diff --git a/tests/Architecture.Tests/ProjectBoundaryTests.cs b/tests/Architecture.Tests/ProjectBoundaryTests.cs new file mode 100644 index 00000000..9282145c --- /dev/null +++ b/tests/Architecture.Tests/ProjectBoundaryTests.cs @@ -0,0 +1,101 @@ +using ArchUnitNET.Fluent; +using ArchUnitNET.xUnitV3; +using Xunit; +using static ArchUnitNET.Fluent.ArchRuleDefinition; + +namespace Architecture.Tests; + +/// +/// Generated from the project references. A production project must not use a first-party +/// production project outside its transitive references. +/// +public sealed class ProjectBoundaryTests +{ + // Coverage instrumentation injects a tracker type with one full name into every instrumented + // assembly. ArchUnitNET merges it across assemblies, so it is excluded from both sides. + private const string CoverageTrackerNamespace = "Microsoft.CodeCoverage.Instrumentation.Static.Tracker"; + + private static readonly ArchUnitNET.Domain.Architecture Architecture = ProjectReferenceBaseline.Instance; + + [Fact] + [Trait("Category", "CI")] + public void E128_Analyzers_ShouldNotDependOn_UnreferencedProjects() + { + IArchRule rule = Types() + .That().ResideInAssembly(ProjectReferenceBaseline.Load("E128.Analyzers")) + .Should().NotDependOnAny( + Types().That().ResideInAssembly( + ProjectReferenceBaseline.Load("E128.Analyzers.CodeFixers"), + ProjectReferenceBaseline.Load("E128.Reference.Cli"), + ProjectReferenceBaseline.Load("E128.Reference.Core"), + ProjectReferenceBaseline.Load("E128.Reference.Web")) + .And().DoNotResideInNamespace(CoverageTrackerNamespace)); + + rule.Check(Architecture); + } + + [Fact] + [Trait("Category", "CI")] + public void E128_Analyzers_CodeFixers_ShouldNotDependOn_UnreferencedProjects() + { + IArchRule rule = Types() + .That().ResideInAssembly(ProjectReferenceBaseline.Load("E128.Analyzers.CodeFixers")) + .Should().NotDependOnAny( + Types().That().ResideInAssembly( + ProjectReferenceBaseline.Load("E128.Reference.Cli"), + ProjectReferenceBaseline.Load("E128.Reference.Core"), + ProjectReferenceBaseline.Load("E128.Reference.Web")) + .And().DoNotResideInNamespace(CoverageTrackerNamespace)); + + rule.Check(Architecture); + } + + [Fact] + [Trait("Category", "CI")] + public void E128_Reference_Cli_ShouldNotDependOn_UnreferencedProjects() + { + IArchRule rule = Types() + .That().ResideInAssembly(ProjectReferenceBaseline.Load("E128.Reference.Cli")) + .Should().NotDependOnAny( + Types().That().ResideInAssembly( + ProjectReferenceBaseline.Load("E128.Analyzers"), + ProjectReferenceBaseline.Load("E128.Analyzers.CodeFixers"), + ProjectReferenceBaseline.Load("E128.Reference.Web")) + .And().DoNotResideInNamespace(CoverageTrackerNamespace)); + + rule.Check(Architecture); + } + + [Fact] + [Trait("Category", "CI")] + public void E128_Reference_Core_ShouldNotDependOn_UnreferencedProjects() + { + IArchRule rule = Types() + .That().ResideInAssembly(ProjectReferenceBaseline.Load("E128.Reference.Core")) + .Should().NotDependOnAny( + Types().That().ResideInAssembly( + ProjectReferenceBaseline.Load("E128.Analyzers"), + ProjectReferenceBaseline.Load("E128.Analyzers.CodeFixers"), + ProjectReferenceBaseline.Load("E128.Reference.Cli"), + ProjectReferenceBaseline.Load("E128.Reference.Web")) + .And().DoNotResideInNamespace(CoverageTrackerNamespace)); + + rule.Check(Architecture); + } + + [Fact] + [Trait("Category", "CI")] + public void E128_Reference_Web_ShouldNotDependOn_UnreferencedProjects() + { + IArchRule rule = Types() + .That().ResideInAssembly(ProjectReferenceBaseline.Load("E128.Reference.Web")) + .Should().NotDependOnAny( + Types().That().ResideInAssembly( + ProjectReferenceBaseline.Load("E128.Analyzers"), + ProjectReferenceBaseline.Load("E128.Analyzers.CodeFixers"), + ProjectReferenceBaseline.Load("E128.Reference.Cli")) + .And().DoNotResideInNamespace(CoverageTrackerNamespace)); + + rule.Check(Architecture); + } +} diff --git a/tests/Architecture.Tests/ProjectReferenceBaseline.cs b/tests/Architecture.Tests/ProjectReferenceBaseline.cs new file mode 100644 index 00000000..20392515 --- /dev/null +++ b/tests/Architecture.Tests/ProjectReferenceBaseline.cs @@ -0,0 +1,29 @@ +using System.Collections.Immutable; +using System.Linq; +using System.Reflection; +using ArchUnitNET.Loader; + +namespace Architecture.Tests; + +/// +/// Loads the first-party production assemblies once per test run. +/// +internal static class ProjectReferenceBaseline +{ + private static readonly ImmutableArray AssemblyNames = + [ + "E128.Analyzers", + "E128.Analyzers.CodeFixers", + "E128.Reference.Cli", + "E128.Reference.Core", + "E128.Reference.Web" + ]; + + public static readonly ArchUnitNET.Domain.Architecture Instance = + new ArchLoader().LoadAssemblies([.. AssemblyNames.Select(Load)]).Build(); + + public static Assembly Load(string name) + { + return Assembly.Load(new AssemblyName(name)); + } +}