Restore three source files my own .gitignore was swallowing

A `catalog/` rule, meant for the generated DevExpress catalog, matches a
directory of that name at ANY depth -- so it silently excluded
src/XafLogicExplainer.Core/Catalog/. XafCatalog, XafCatalogStore and
CatalogEnricher were never committed. Every clean checkout failed to compile
while my local build kept passing, because the files were still on disk.

That is the same shape as the bug I fixed in the analyzers a few commits ago:
matching by name where the match should have been specific. The generated catalog
is now excluded by its extension, and it lives outside any repository anyway.

Verified by building a fresh clone rather than the working tree, which is the
only check that could have caught this.

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

Author: peopleworks

.gitignore

@@ -52,7 +52,12 @@ coverage*.xml
 # The DevExpress ground-truth catalog is generated locally by licensees from
 # their own installation (see tools/XafLogicExplainer.DxCatalog). Nothing
 # derived from DevExpress sources is ever committed to this repository.
-catalog/
+#
+# Matched by file extension, NOT by a `catalog/` directory rule. That rule matched
+# any directory of that name at any depth, so it silently swallowed
+# src/XafLogicExplainer.Core/Catalog/ -- three source files were never committed,
+# and every clean checkout failed to compile while the local build sailed on
+# because the files were still sitting on disk.
 *.dxcatalog.json
 
 # Working notes and scratch. One `git add -A` from the root is all it takes to

src/XafLogicExplainer.Core/Catalog/CatalogEnricher.cs

@@ -0,0 +1,155 @@
+using XafLogicExplainer.Core.Models;
+
+namespace XafLogicExplainer.Core.Catalog;
+
+/// <summary>
+/// Annotates an extracted application with what the framework, rather than the team, provides.
+/// </summary>
+/// <remarks>
+/// Runs after extraction rather than inside the analyzers, so the catalog stays entirely optional:
+/// with none present nothing here executes and the result is what it always was.
+/// <para>
+/// It answers one question the source alone cannot: which of these names came with XAF? A
+/// controller deriving from <c>DeleteObjectsViewController</c> is extending shipped behavior; one
+/// deriving from a class in the same project is not, and an agent asked to change the first should
+/// know it is looking at framework code.
+/// </para>
+/// </remarks>
+public static class CatalogEnricher
+{
+    /// <summary>
+    /// Applies catalog knowledge to an extracted project.
+    /// </summary>
+    /// <param name="project">The project to annotate, modified in place.</param>
+    /// <param name="catalog">The catalog, or null to do nothing.</param>
+    public static void Enrich(ExtractedProject project, XafCatalog? catalog)
+    {
+        if (catalog is null)
+            return;
+
+        project.CatalogVersion = catalog.DevExpressVersion;
+
+        EnrichControllers(project, catalog);
+        EnrichAttributes(project, catalog);
+    }
+
+    /// <summary>
+    /// The generic entry points every XAF controller starts from.
+    /// </summary>
+    /// <remarks>
+    /// Deriving from one of these carries no information: it says "this is a controller", which
+    /// the reader already knows from the word Controller in its name. Reporting them turned the
+    /// section into a list of every controller in the application, each annotated "A View
+    /// Controller" — noise that buries the one case worth noticing.
+    /// </remarks>
+    private static readonly HashSet<string> GenericControllerBases = new(StringComparer.Ordinal)
+    {
+        "Controller",
+        "ViewController",
+        "ObjectViewController",
+        "WindowController",
+    };
+
+    private static void EnrichControllers(ExtractedProject project, XafCatalog catalog)
+    {
+        var ownControllers = project.Controllers
+            .Select(c => c.ClassName)
+            .ToHashSet(StringComparer.Ordinal);
+
+        foreach (var controller in project.Controllers)
+        {
+            // A base type defined in this same project is the team's own layering, not framework
+            // behavior, even when the catalog happens to hold a type of that name.
+            if (ownControllers.Contains(StripGenerics(controller.BaseControllerType)))
+                continue;
+
+            var frameworkBase = catalog.FindController(controller.BaseControllerType);
+
+            if (frameworkBase is null || GenericControllerBases.Contains(frameworkBase.Name))
+                continue;
+
+            // What remains is a controller extending a specific piece of shipped behavior --
+            // DeleteObjectsViewController, ExportController -- which changes how an existing
+            // feature works rather than adding a new one.
+            controller.FrameworkBaseType = frameworkBase.Name;
+            controller.FrameworkBaseSummary = frameworkBase.Summary;
+            controller.FrameworkBaseDocumentationUrl = frameworkBase.DocumentationUrl;
+        }
+    }
+
+    /// <summary>
+    /// Separates the attributes XAF defines from the ones this application defines itself.
+    /// </summary>
+    /// <remarks>
+    /// A custom attribute is a signal worth surfacing: it usually marks a convention the team
+    /// invented, which an agent has no other way to learn about and cannot look up in any
+    /// documentation.
+    /// </remarks>
+    private static void EnrichAttributes(ExtractedProject project, XafCatalog catalog)
+    {
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+        var custom = new SortedSet<string>(StringComparer.Ordinal);
+
+        foreach (var entity in project.Entities)
+        {
+            foreach (var attributeName in entity.Properties.SelectMany(p => p.CustomAttributes))
+            {
+                var name = NormalizeAttributeName(attributeName);
+
+                if (name.Length == 0 || !seen.Add(name))
+                    continue;
+
+                if (catalog.FindAttribute(name) is null && !IsFrameworkNamespace(name))
+                    custom.Add(name);
+            }
+        }
+
+        project.CustomAttributes = [.. custom];
+    }
+
+    /// <summary>
+    /// Reduces an attribute as written in source to its bare name.
+    /// </summary>
+    private static string NormalizeAttributeName(string attribute)
+    {
+        var name = attribute.Trim();
+
+        // "[RuleRequiredField("id", DefaultContexts.Save)]" -> "RuleRequiredField"
+        var parenthesis = name.IndexOf('(');
+        if (parenthesis > 0)
+            name = name[..parenthesis];
+
+        name = name.Trim('[', ']', ' ');
+
+        var lastDot = name.LastIndexOf('.');
+        if (lastDot >= 0)
+            name = name[(lastDot + 1)..];
+
+        return name.Trim();
+    }
+
+    /// <summary>
+    /// Whether a name is a .NET attribute that no XAF catalog would list.
+    /// </summary>
+    /// <remarks>
+    /// EF Core applications annotate with <c>System.ComponentModel.DataAnnotations</c>, which is
+    /// part of .NET rather than of XAF. Reporting those as "your own" would be wrong and would
+    /// bury the handful that genuinely are.
+    /// </remarks>
+    private static bool IsFrameworkNamespace(string attributeName) =>
+        attributeName is
+            "Required" or "StringLength" or "MaxLength" or "MinLength" or "Range" or
+            "Key" or "ForeignKey" or "NotMapped" or "Column" or "Table" or "InverseProperty" or
+            "Description" or "DisplayName" or "Browsable" or "DefaultValue" or "Obsolete" or
+            "DataType" or "Display" or "Editable" or "Compare" or "RegularExpression" or
+            "EmailAddress" or "Phone" or "Url" or "CreditCard" or "Timestamp" or "ConcurrencyCheck";
+
+    private static string StripGenerics(string? typeName)
+    {
+        if (string.IsNullOrWhiteSpace(typeName))
+            return string.Empty;
+
+        var generic = typeName.IndexOf('<');
+        return generic > 0 ? typeName[..generic] : typeName;
+    }
+}

src/XafLogicExplainer.Core/Catalog/XafCatalog.cs

@@ -0,0 +1,152 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace XafLogicExplainer.Core.Catalog;
+
+/// <summary>
+/// What the XAF framework itself provides: its attributes, controllers, model interfaces and modules.
+/// </summary>
+/// <remarks>
+/// Extraction reads an application's source without knowing anything about the framework it is
+/// written against. That makes one question unanswerable: is <c>DeleteObjectsViewController</c>
+/// something this team wrote, or something DevExpress ships? Without an answer, generated
+/// documentation presents framework behavior and the application's own logic as though they were
+/// the same thing — and an agent asked to change the former will happily try.
+/// <para>
+/// The catalog supplies that ground truth. It is generated locally by a licensee from their own
+/// DevExpress installation (see <c>xaflogic catalog build</c>) and written outside the repository.
+/// <strong>Nothing derived from DevExpress is distributed with this project.</strong>
+/// </para>
+/// <para>
+/// It is entirely optional. With no catalog present, extraction behaves exactly as it did before
+/// one existed.
+/// </para>
+/// </remarks>
+public sealed class XafCatalog
+{
+    /// <summary>Version of the DevExpress installation this was generated from, e.g. "26.1".</summary>
+    public string DevExpressVersion { get; init; } = string.Empty;
+
+    /// <summary>When it was generated, in round-trip format.</summary>
+    public string GeneratedAt { get; init; } = string.Empty;
+
+    /// <summary>Assemblies that were read.</summary>
+    public List<string> Assemblies { get; init; } = [];
+
+    /// <summary>XAF attributes, keyed by simple type name.</summary>
+    public Dictionary<string, XafCatalogType> Attributes { get; init; } = [];
+
+    /// <summary>Framework controllers, keyed by simple type name.</summary>
+    public Dictionary<string, XafCatalogType> Controllers { get; init; } = [];
+
+    /// <summary>Application Model interfaces, keyed by simple type name.</summary>
+    public Dictionary<string, XafCatalogType> ModelInterfaces { get; init; } = [];
+
+    /// <summary>Framework modules, keyed by simple type name.</summary>
+    public Dictionary<string, XafCatalogType> Modules { get; init; } = [];
+
+    /// <summary>Total number of framework types recorded.</summary>
+    [JsonIgnore]
+    public int TypeCount =>
+        Attributes.Count + Controllers.Count + ModelInterfaces.Count + Modules.Count;
+
+    /// <summary>
+    /// Looks up an attribute by the name as written in source, with or without the suffix.
+    /// </summary>
+    /// <remarks>
+    /// C# lets <c>[Description]</c> stand for <c>DescriptionAttribute</c>, and source is written
+    /// both ways, so both must resolve.
+    /// </remarks>
+    /// <param name="attributeName">Name as it appears in the attribute list.</param>
+    public XafCatalogType? FindAttribute(string? attributeName)
+    {
+        if (string.IsNullOrWhiteSpace(attributeName))
+            return null;
+
+        var name = attributeName.Trim();
+
+        if (Attributes.TryGetValue(name, out var exact))
+            return exact;
+
+        return Attributes.TryGetValue(name + "Attribute", out var suffixed) ? suffixed : null;
+    }
+
+    /// <summary>
+    /// Looks up a controller by name, ignoring any generic arguments.
+    /// </summary>
+    /// <param name="typeName">A base type as written in source, e.g. <c>ViewController&lt;DetailView&gt;</c>.</param>
+    public XafCatalogType? FindController(string? typeName)
+    {
+        if (string.IsNullOrWhiteSpace(typeName))
+            return null;
+
+        var name = typeName.Trim();
+
+        var generic = name.IndexOf('<');
+        if (generic > 0)
+            name = name[..generic];
+
+        var lastDot = name.LastIndexOf('.');
+        if (lastDot >= 0)
+            name = name[(lastDot + 1)..];
+
+        return Controllers.TryGetValue(name, out var controller) ? controller : null;
+    }
+
+    /// <summary>Serialization settings shared by the generator and the loader.</summary>
+    public static JsonSerializerOptions JsonOptions { get; } = new()
+    {
+        WriteIndented = true,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNameCaseInsensitive = true,
+    };
+
+    /// <summary>Serializes the catalog.</summary>
+    public string ToJson() => JsonSerializer.Serialize(this, JsonOptions);
+
+    /// <summary>Deserializes a catalog, returning null when the text is not one.</summary>
+    /// <param name="json">Catalog JSON.</param>
+    public static XafCatalog? FromJson(string json)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize<XafCatalog>(json, JsonOptions);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+}
+
+/// <summary>
+/// One type the XAF framework provides.
+/// </summary>
+public sealed class XafCatalogType
+{
+    /// <summary>Simple type name, e.g. <c>DeleteObjectsViewController</c>.</summary>
+    public string Name { get; init; } = string.Empty;
+
+    /// <summary>Namespace it lives in.</summary>
+    public string Namespace { get; init; } = string.Empty;
+
+    /// <summary>Assembly it ships in, without the version suffix.</summary>
+    public string Assembly { get; init; } = string.Empty;
+
+    /// <summary>Immediate base type, for controllers.</summary>
+    public string? BaseType { get; init; }
+
+    /// <summary>First sentence of the official documentation, when the XML docs supplied one.</summary>
+    public string? Summary { get; init; }
+
+    /// <summary>Official documentation URL, when the XML docs linked one.</summary>
+    public string? DocumentationUrl { get; init; }
+
+    /// <summary>Whether the type is abstract, which for a controller means it is meant to be derived from.</summary>
+    public bool IsAbstract { get; init; }
+
+    /// <summary>Full name, for display.</summary>
+    [JsonIgnore]
+    public string FullName => string.IsNullOrEmpty(Namespace) ? Name : $"{Namespace}.{Name}";
+}