Find entities through a base class the project wrote itself

Classification matched a class's own base list against the root names and
stopped there. An application with a shared base -- auditing, a key convention,
a display-name property -- lost every business object below it.

The inversion is what makes it severe rather than incomplete. The abstract base
does match, so the inventory reports the one class that is not a table and omits
the ones that are, while AGENTS.md goes on to say the inventory is complete and
that anything absent does not exist.

Selection now repeats until a round changes nothing, which is what
SelectControllers already does on the controller side and for the same reasons:
a base may be read after the class deriving from it, and a chain can be any
depth.

A base name is resolved through the deriving file's own scope rather than by
simple name. A name is not an identity -- the reason the DbSet roster carries
scopes -- so a Contracts.Order beside a BusinessObjects.Order still resolves to
the base it actually named, not to any accepted class wearing that name.

Acceptance is keyed on (namespace, name), so every part of a partial class is
selected once any part of it is.

On the demos shipped with 26.1:

  FeatureCenter.NET.XPO            43 -> 140
  MainDemo.NET.XPO                 14 -> 17
  OutlookInspiredDemo.NET.EFCore   23 -> 24
  MainDemo.NET.EFCore              14 -> 14  (unchanged)

The OutlookInspired one is an EF Core application: TaxRate derives through a
shared base and is not registered as a DbSet, so neither the roster nor the base
match saw it.

Fixes #6

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Brekhof

CHANGELOG.md

@@ -7,6 +7,20 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+
+- **Entities are found through a base class the project wrote itself.** Classification matched a
+  class's own base list against the root names and stopped there, so an application with a shared
+  base — auditing, a key convention, a display-name property — lost every business object below it.
+  The inversion is what makes it severe: the abstract base *is* matched, so the inventory reported
+  the one class that is not a table and omitted the ones that are. Selection now repeats until a
+  round changes nothing, exactly as `SelectControllers` does, and resolves a base name through the
+  deriving file's own scope rather than by simple name, so a `Contracts.Order` beside a
+  `BusinessObjects.Order` still resolves to the base it actually named. On the demos shipped with
+  26.1: `FeatureCenter.NET.XPO` 43 → 140 entities, `MainDemo.NET.XPO` 14 → 17, and
+  `OutlookInspiredDemo.NET.EFCore` 23 → 24 — the last of which is an EF Core application, where an
+  entity that is not registered as a `DbSet<T>` had no fallback either.
+
 ## [0.12.1] — 2026-08-13
 
 Entities the application declares, rather than the ones that inherit from the right class.

README.md

@@ -317,7 +317,7 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | Pluggable publishing targets (`IDocumentationSink`) |
 | ✅ | **MCP server** — 10 tools, live against your source |
 | ✅ | **Installable Claude Code plugin** with skill and MCP server |
-| ✅ | **279 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
+| ✅ | **283 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
 | ✅ | **DevExpress ground-truth catalog**, generated locally by licensees |
 
 PeopleWorks Copilot, where this tool grew up, is now one sink among several rather than the

src/XafLogicExplainer.Core/Analyzers/EntityAnalyzer.cs

@@ -44,13 +44,14 @@ public List<ExtractedEntity> AnalyzeEntities(string sourceDirectory, ExtractionO
 
         var roster = DbSetRoster.Read(parsedFiles.Select(parsed => parsed.Root));
 
+        var persistent = SelectPersistentClasses(parsedFiles.Select(parsed => parsed.Root), roster, options);
+
         foreach (var (file, root) in parsedFiles)
         {
             var classDeclarations = root.DescendantNodes().OfType<ClassDeclarationSyntax>();
             foreach (var classDecl in classDeclarations)
             {
-                if (IsXafBusinessObject(classDecl, options.BaseTypeNames)
-                    || roster.Registers(GetNamespace(classDecl), classDecl.Identifier.Text))
+                if (persistent.Contains((GetNamespace(classDecl), classDecl.Identifier.Text)))
                 {
                     var entity = ExtractEntity(classDecl, file, options);
                     entities.Add(entity);
@@ -472,6 +473,159 @@ private static List<ExtractedAppearanceRule> ExtractAppearanceRules(ClassDeclara
 
     #region Helper Methods
 
+    /// <summary>
+    /// Decides which classes are persistent, following base classes to a fixed point.
+    /// </summary>
+    /// <remarks>
+    /// Matching a class's own base list against a list of root names stops one hop short. An
+    /// application that writes a shared base — auditing, a key convention, a display name — puts
+    /// every business object below it out of reach, and the loss is silent in the worst way: the
+    /// abstract base is extracted in their place, so the inventory reports the one class that is
+    /// not a table and omits the ones that are.
+    /// <para>
+    /// Repeating until a round changes nothing is what the controller side already does in
+    /// <c>SelectControllers</c>, and for the same reason: a base class may be read after the class
+    /// deriving from it, and a chain can be any depth.
+    /// </para>
+    /// <para>
+    /// A base name is resolved through the deriving file's own scope rather than by simple name,
+    /// because a name is not an identity — the reason the DbSet roster carries scopes. An
+    /// application may keep a <c>Contracts.Order</c> beside its <c>BusinessObjects.Order</c>, each
+    /// deriving from a different <c>NamedBaseObject</c>, and only one of those is a table.
+    /// </para>
+    /// <para>
+    /// Acceptance is keyed on <c>(namespace, name)</c>, so every part of a <c>partial</c> class is
+    /// selected once any part of it is — the hand-written part that carries the base list and the
+    /// generated part that carries the mapping are the same class.
+    /// </para>
+    /// </remarks>
+    private static HashSet<(string Namespace, string Name)> SelectPersistentClasses(
+        IEnumerable<SyntaxNode> roots, DbSetRoster roster, ExtractionOptions options)
+    {
+        var trees = roots.ToList();
+        var globalUsings = GlobalUsings(trees);
+
+        var candidates = new List<(ClassDeclarationSyntax Declaration, string Namespace, string Name, HashSet<string> Scopes)>();
+
+        foreach (var root in trees)
+        {
+            var fileScopes = new HashSet<string>(globalUsings, StringComparer.Ordinal);
+
+            foreach (var directive in root.DescendantNodes().OfType<UsingDirectiveSyntax>())
+            {
+                if (directive.Alias is null && directive.Name is not null)
+                    fileScopes.Add(directive.Name.ToString());
+            }
+
+            foreach (var classDecl in root.DescendantNodes().OfType<ClassDeclarationSyntax>())
+            {
+                var @namespace = GetNamespace(classDecl);
+                var scopes = new HashSet<string>(fileScopes, StringComparer.Ordinal);
+
+                // Its own namespace and every one enclosing it: C# resolves an unqualified name
+                // outwards, so a base one level up needs no using directive.
+                for (var scope = @namespace; ; )
+                {
+                    scopes.Add(scope);
+                    var dot = scope.LastIndexOf('.');
+                    if (dot < 0) break;
+                    scope = scope[..dot];
+                }
+
+                candidates.Add((classDecl, @namespace, classDecl.Identifier.Text, scopes));
+            }
+        }
+
+        var accepted = new HashSet<(string Namespace, string Name)>();
+
+        foreach (var candidate in candidates)
+        {
+            if (IsXafBusinessObject(candidate.Declaration, options.BaseTypeNames)
+                || roster.Registers(candidate.Namespace, candidate.Name))
+                accepted.Add((candidate.Namespace, candidate.Name));
+        }
+
+        // Each round can accept a class whose base was accepted in the previous one, so it repeats
+        // until a round changes nothing. Bounded by the number of classes.
+        bool changed;
+
+        do
+        {
+            changed = false;
+
+            foreach (var candidate in candidates)
+            {
+                if (accepted.Contains((candidate.Namespace, candidate.Name)))
+                    continue;
+
+                if (!DerivesFromAccepted(candidate.Declaration, candidate.Scopes, accepted))
+                    continue;
+
+                accepted.Add((candidate.Namespace, candidate.Name));
+                changed = true;
+            }
+        }
+        while (changed);
+
+        return accepted;
+    }
+
+    /// <summary>
+    /// Whether any name in this class's base list resolves to a class already accepted.
+    /// </summary>
+    /// <remarks>
+    /// Every entry is tried rather than the first, because syntax cannot tell a base class from an
+    /// interface. An interface name only matches if a class of that name was itself accepted, which
+    /// an interface never is.
+    /// </remarks>
+    private static bool DerivesFromAccepted(
+        ClassDeclarationSyntax classDecl,
+        HashSet<string> scopes,
+        HashSet<(string Namespace, string Name)> accepted)
+    {
+        foreach (var baseType in classDecl.BaseList?.Types ?? default)
+        {
+            var written = baseType.Type.ToString();
+
+            var generic = written.IndexOf('<');
+            if (generic > 0) written = written[..generic];
+
+            var dot = written.LastIndexOf('.');
+            var simpleName = dot < 0 ? written : written[(dot + 1)..];
+
+            foreach (var (@namespace, name) in accepted)
+            {
+                if (!string.Equals(name, simpleName, StringComparison.Ordinal)) continue;
+
+                if (dot < 0)
+                {
+                    // Unqualified: it named something this file can actually see.
+                    if (scopes.Contains(@namespace)) return true;
+                    continue;
+                }
+
+                // Qualified: the tail it wrote is more specific than any using directive.
+                var qualifier = written[..dot];
+                if (@namespace.Equals(qualifier, StringComparison.Ordinal)
+                    || @namespace.EndsWith("." + qualifier, StringComparison.Ordinal))
+                    return true;
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// The <c>global using</c> namespaces, which reach every file however they are declared.
+    /// </summary>
+    private static HashSet<string> GlobalUsings(IEnumerable<SyntaxNode> trees) => trees
+        .SelectMany(root => root.DescendantNodes().OfType<UsingDirectiveSyntax>())
+        .Where(directive => !directive.GlobalKeyword.IsKind(SyntaxKind.None))
+        .Select(directive => directive.Name?.ToString())
+        .Where(name => name is not null)
+        .Select(name => name!)
+        .ToHashSet(StringComparer.Ordinal);
+
     /// <summary>
     /// Detects ORM mode by scanning file contents for EF-specific namespaces.
     /// </summary>

tests/XafLogicExplainer.Tests/DeepInheritanceTests.cs

@@ -0,0 +1,55 @@
+namespace XafLogicExplainer.Tests;
+
+/// <summary>
+/// Entities that reach a persistent base through another class in the same project.
+/// </summary>
+/// <remarks>
+/// Matching a class's own base list against a list of root names stops one hop short, and an
+/// application that writes a shared base — auditing, a key convention, a display-name property —
+/// puts every one of its business objects out of reach. It is the same defect the controller side
+/// fixed by repeating until a round changes nothing.
+/// <para>
+/// Under EF Core the DbSet roster hides this: a registered class is found whatever it derives
+/// from. XPO has no such fallback, and an EF Core class that is not registered has none either.
+/// </para>
+/// </remarks>
+public class DeepInheritanceTests
+{
+    [Fact]
+    public void FindsAnEntityTwoHopsFromAPersistentRoot()
+    {
+        var names = SampleProjects.DeepXpo.Entities.Select(entity => entity.ClassName);
+
+        Assert.Contains("Order", names);
+    }
+
+    [Fact]
+    public void FindsAnEntityThreeHopsFromAPersistentRoot()
+    {
+        // Only resolvable after Order has been accepted, which is what makes this a fixed point
+        // rather than one more hop.
+        var names = SampleProjects.DeepXpo.Entities.Select(entity => entity.ClassName);
+
+        Assert.Contains("PriorityOrder", names);
+    }
+
+    [Fact]
+    public void ResolvesTheBaseThatWasActuallyNamedRatherThanAnyClassOfThatName()
+    {
+        // Contracts.Order derives from Contracts.NamedBaseObject, which is persistent in no sense.
+        // Both namespaces declare a NamedBaseObject, and only one of them is an entity.
+        var orders = SampleProjects.DeepXpo.Entities.Where(entity => entity.ClassName == "Order").ToList();
+
+        Assert.Equal(["SampleDeep.Module.BusinessObjects"], orders.Select(entity => entity.Namespace));
+    }
+
+    [Fact]
+    public void ReadsTheRulesOfAnEntityFoundThroughItsBase()
+    {
+        // The class was invisible, so everything declared on it was too.
+        var order = SampleProjects.DeepXpo.Entity("Order");
+
+        Assert.Equal("Sales", order.NavigationGroup);
+        Assert.Contains(order.Properties, property => property.Name == "Number");
+    }
+}

tests/XafLogicExplainer.Tests/Fixtures/DeepXpoSolution/SampleDeep.Module/BusinessObjects/NamedBaseObject.cs

@@ -0,0 +1,22 @@
+using DevExpress.Persistent.BaseImpl;
+using DevExpress.Xpo;
+
+namespace SampleDeep.Module.BusinessObjects;
+
+/// <summary>
+/// The shared base an application writes once and derives everything from.
+/// </summary>
+/// <remarks>
+/// This is the shape FeatureCenter uses throughout: one abstract class holding the convention,
+/// and the real business objects two or three hops below it.
+/// </remarks>
+public abstract class NamedBaseObject : BaseObject
+{
+    public NamedBaseObject(Session session) : base(session) { }
+
+    public string Name
+    {
+        get => GetPropertyValue<string>(nameof(Name));
+        set => SetPropertyValue(nameof(Name), value);
+    }
+}

tests/XafLogicExplainer.Tests/Fixtures/DeepXpoSolution/SampleDeep.Module/BusinessObjects/Order.cs

@@ -0,0 +1,20 @@
+using DevExpress.Persistent.Base;
+using DevExpress.Persistent.Validation;
+using DevExpress.Xpo;
+
+namespace SampleDeep.Module.BusinessObjects;
+
+/// <summary>Two hops from a persistent root: Order -> NamedBaseObject -> BaseObject.</summary>
+[DefaultClassOptions]
+[NavigationItem("Sales")]
+public class Order : NamedBaseObject
+{
+    public Order(Session session) : base(session) { }
+
+    [RuleRequiredField("Order_Number_Required", DefaultContexts.Save)]
+    public string Number
+    {
+        get => GetPropertyValue<string>(nameof(Number));
+        set => SetPropertyValue(nameof(Number), value);
+    }
+}

tests/XafLogicExplainer.Tests/Fixtures/DeepXpoSolution/SampleDeep.Module/BusinessObjects/PriorityOrder.cs

@@ -0,0 +1,21 @@
+using DevExpress.Persistent.Base;
+using DevExpress.Xpo;
+
+namespace SampleDeep.Module.BusinessObjects;
+
+/// <summary>Three hops: PriorityOrder -> Order -> NamedBaseObject -> BaseObject.</summary>
+/// <remarks>
+/// Here so the walk is a fixed point rather than one extra hop. It only resolves once
+/// <see cref="Order"/> has been accepted, which may be in a later round.
+/// </remarks>
+[DefaultClassOptions]
+public class PriorityOrder : Order
+{
+    public PriorityOrder(Session session) : base(session) { }
+
+    public int Rank
+    {
+        get => GetPropertyValue<int>(nameof(Rank));
+        set => SetPropertyValue(nameof(Rank), value);
+    }
+}

tests/XafLogicExplainer.Tests/Fixtures/DeepXpoSolution/SampleDeep.Module/Contracts/NamedBaseObject.cs

@@ -0,0 +1,13 @@
+namespace SampleDeep.Module.Contracts;
+
+/// <summary>
+/// A wire shape that happens to share a name with the persistent base.
+/// </summary>
+/// <remarks>
+/// Nothing here is persistent. It exists so the walk has to answer *which* NamedBaseObject a
+/// class derives from rather than whether some class of that name was accepted.
+/// </remarks>
+public abstract class NamedBaseObject
+{
+    public string Name { get; set; }
+}

tests/XafLogicExplainer.Tests/Fixtures/DeepXpoSolution/SampleDeep.Module/Contracts/Order.cs

@@ -0,0 +1,15 @@
+namespace SampleDeep.Module.Contracts;
+
+/// <summary>
+/// The DTO an integration posts. Same simple name as the entity, same base name as the entity's
+/// base, and persistent in neither sense.
+/// </summary>
+/// <remarks>
+/// There is no using directive for the BusinessObjects namespace here, so
+/// <c>NamedBaseObject</c> resolves to the one beside it. A walk that asked only "was a class
+/// called NamedBaseObject accepted" would answer yes and turn this into a table.
+/// </remarks>
+public class Order : NamedBaseObject
+{
+    public string Number { get; set; }
+}

tests/XafLogicExplainer.Tests/SampleProjects.cs

@@ -31,6 +31,9 @@ internal static class SampleProjects
     /// <summary>Path to the legacy EF Core fixture module.</summary>
     public static string LegacyEfPath => Path.Combine(FixturesRoot, "LegacyEfSolution", "SampleLegacy.Module");
 
+    /// <summary>Path to the XPO fixture whose entities derive through a shared base.</summary>
+    public static string DeepXpoPath => Path.Combine(FixturesRoot, "DeepXpoSolution", "SampleDeep.Module");
+
     /// <summary>Path to the fourteen-entity demo module.</summary>
     public static string DemoPath => Path.Combine(FixturesRoot, "DemoSolution", "PharmacyDemo.Module");
 
@@ -83,6 +86,7 @@ private static string FixturesRoot
     private static readonly Lazy<ExtractedProject> LazyDemo = new(() => Extract(DemoPath));
     private static readonly Lazy<ExtractedProject> LazyEfCore = new(() => Extract(EfCorePath));
     private static readonly Lazy<ExtractedProject> LazyLegacyEf = new(() => Extract(LegacyEfPath));
+    private static readonly Lazy<ExtractedProject> LazyDeepXpo = new(() => Extract(DeepXpoPath));
 
     /// <summary>The XPO sample: Customer, Order, OrderLine, one controller, seed data, xafml.</summary>
     public static ExtractedProject Xpo => LazyXpo.Value;
@@ -100,6 +104,9 @@ private static string FixturesRoot
     /// </remarks>
     public static ExtractedProject LegacyEf => LazyLegacyEf.Value;
 
+    /// <summary>An XPO application whose entities reach BaseObject through a shared base.</summary>
+    public static ExtractedProject DeepXpo => LazyDeepXpo.Value;
+
     /// <summary>
     /// The fourteen-entity demo, with a custom editor in a sibling platform project.
     /// </summary>