[alexanderlinne]

Why MatchingWithPackages existed, and why it no longer has to

On main, a slice carries a single string, its name, plus an optional NameSpace. The PlantUML exporter works out everything from those strings:

• which slice is a package of another (StartsWith),
• which arrows to merge (Contains),
• how deep LimitDependencies goes (counting dots).

For that it needs fully qualified names such as App.Orders.Web. Rules need the opposite: short names for failure messages and freeze stores. Both requirements apply to the same string, so the choice has to be made when the slices are built, which is why there are two methods:

• Matching produces short names and draws flat.
• MatchingWithPackages produces prefix + name and draws nested.

The prefix is the literal pattern text before the capture group, so both methods group types the same way; only the names differ. In other words, a diagram option ends up in failure messages and frozen violations.

The exporter doesn't need anything from the pattern: it nests each slice in the deepest namespace its types share. So the flat vs. nested choice moves from slice creation to rendering, and one set of slices can be checked and drawn both ways.

This PR doesn't touch the matcher; it runs on main's. Since the layout depends only on the types, the next two PRs can change naming and matching without touching it.

What changes

• GenerationOptions.NestSlicesInPackages (default false) draws the namespace tree as package blocks.

• MatchingWithPackages is [Obsolete] and creates exactly Matching's slices, so rule descriptions, slices, names, violations and freeze keys are the same as with Matching. Its slices still nest by default. MatchingWithPackagesTests checks that both methods give the same slices, the same rule results and the same diagrams.

• Slices are boxes inside their namespaces. With nesting on, every slice is drawn under its name in the package of the deepest namespace that contains all of its types:

  • A package that holds no slice and only one other package is merged with it, top-down at every level, e.g. into Orders.Domain.
  • A slice whose types share no namespace is drawn outside any package.
  • This applies to every slice, also to SlicedBy slices and custom SliceAssignments.
  • No slice is drawn as a package any more, and there are no package arrows; arrows are the flat ones.
  

• Packages come from the types, not from the pattern text. With a leading .., MatchingWithPackages nested slices under the pattern text with one of its dots stripped. ..DuplicatePrefix.Sub.(**) thus got a package .DuplicatePrefix.Sub, which doesn't exist; the slice now sits in the namespace its types are in:

  

• A slice whose name is a prefix of another's is drawn. On main, with App.(*) over App.Order and App.Orders, "Orders".StartsWith("Order"), so Order was taken for the package of Orders and drawn neither as a slice nor with its dependency on Billing. That check is gone along with package-slices:

  

• Focus mode takes a namespace. WithDependenciesFromFocusOn and the fluent WithDependenciesFromSlices(slices, focusOnPackage) take an optional GenerationOptions for the nesting. A slice is focused when all of its types lie in the given namespace or below it, matched by segments; the slices it depends on, or that depend on it, are drawn as well. On main, the focus string was a substring of the slice names, so flat diagrams were focused with a bare name ("Slice1"), which also matched Slice10. Now flat and nested diagrams both take the full namespace and focus the same slices.

• LimitDependencies keeps arrows between slices at the same depth, i.e. whose types share an equally deep namespace, flat or nested. For (**) patterns that is exactly main's flat output. Nested, main drew a sibling overview with package arrows instead; it now keeps the same arrows as flat, inside the tree. The exporter decides which arrows to draw, so OneToOneCompact no longer checks dots when it renders. The namespace overload filters the same way, and its output doesn't change; a new snapshot pins it.

• Guide. Sections 5.2–5.6 use Matching with NestSlicesInPackages and describe the new layout, focus and depth rules, and a new section 5.7 explains the migration. 5.6 also gets a missing semicolon.

Every flat snapshot is unchanged. The nested snapshots were renamed (BuildUmlBySlicesMatchingWithPackages_* → BuildUmlBySlicesNested_*), switched to the option and regenerated.

Breaking changes

• MatchingWithPackages is obsolete. It creates Matching's slices, so its failure messages and frozen violations no longer use names qualified with the namespace before the capture group. Frozen violations of MatchingWithPackages rules have to be frozen again once.
• Slice.NameSpace, Slice.ContainsNamespace() and SliceIdentifier.NameSpace are removed, and SliceIdentifier.Of loses its nameSpace parameter.
• Nested slice diagrams change: every slice is a box at its types' common namespace; no slice is drawn as a package and there are no package arrows.
• Focus mode takes a namespace, also for flat diagrams, and matches it by segments.
• Nested LimitDependencies keeps same-depth arrows instead of a sibling overview.
• OneToOneCompact renders whatever the dots in its names; the exporter filters instead.

Migration: replace MatchingWithPackages(pattern) with Matching(pattern) and draw the slices with new GenerationOptions { NestSlicesInPackages = true }. Pass the full namespace to focus mode.

How the images were made

All images render PlantUML that the exporter produced. The "before" sides were produced on main (#512 doesn't touch slice diagrams), the "after" sides at this PR.

• Image 1 shows the .verified.txt snapshots of …MultipleSubnamespaces.(**) on either side.
• The "before" side of image 2 was produced with a throwaway test, because main has no snapshot for it; the "after" side is BuildUmlBySlicesNested_DuplicatePrefixSegment.
• Image 3 renders a small fixture that isn't part of this PR (App.Order, App.Orders, App.Billing).

They were rendered with PlantUML 1.2025.4 and Graphviz, with the remote !include of C4-PlantUML replaced by PlantUML's bundled copy (!include <C4/C4_Container>).

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.63033% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.36%. Comparing base (bf4efd7) to head (8a78006).

Files with missing lines	Patch %	Lines
...tNET/Domain/PlantUml/Export/PlantUmlFileBuilder.cs	98.14%	0 Missing and 3 partials ⚠️
...ntUml/PlantUmlFluentComponentDiagramInitializer.cs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@                          Coverage Diff                           @@
##           stop-deriving-namespace-from-slice     #513      +/-   ##
======================================================================
- Coverage                               86.53%   86.36%   -0.17%     
======================================================================
  Files                                     261      261              
  Lines                                   12713    12623      -90     
  Branches                                 1241     1226      -15     
======================================================================
- Hits                                    11001    10902      -99     
- Misses                                   1366     1374       +8     
- Partials                                  346      347       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.