Merge pull request peopleworks#39 from peopleworks/fix/escape-generic-types

Write a generic type as code, so the reader gets to see it

Author: peopleworks

CHANGELOG.md

@@ -7,6 +7,20 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+
+- **A generic base type reaches the reader** (found by [@MBrekhof] while running the Word route in
+  [#36]). `- **Base type:** ViewController<DetailView>` was printed bare, and `<DetailView>` is an
+  *inline* HTML tag to every CommonMark parser: an export drops it and github.com's sanitizer strips
+  it, so the page said the base class was `ViewController`. Not a missing answer — a different one.
+  Backticks at the three sites that print a type name outside code.
+  The guard from [#28] missed it because it scanned only lines that *opened* with `<`, which was the
+  shape of the `<details>` block it was written for. It now matches a tag anywhere on a line, with
+  fenced blocks and inline code spans excluded — the second because it is the remedy, and a guard
+  that rejected its own fix would be no guard at all. 392 tests.
+
+[#36]: https://github.com/peopleworks/XAFLogicExplainer/pull/36
+
 ## [0.15.0] — 2026-08-23
 
 How it works, not only what exists.

README.md

@@ -390,7 +390,7 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | Pluggable publishing targets (`IDocumentationSink`) |
 | ✅ | **MCP server** — 11 tools, live against your source |
 | ✅ | **Installable Claude Code plugin** with skill and MCP server |
-| ✅ | **391 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
+| ✅ | **392 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/Generators/MarkdownDocumentationGenerator.cs

@@ -496,7 +496,7 @@ private DocumentSection GenerateEntitiesSection(ExtractedProject project)
                 sb.AppendLine($"*{entity.Description}*");
 
             sb.AppendLine();
-            sb.AppendLine($"- **{_l.BaseType}:** {entity.BaseType}");
+            sb.AppendLine($"- **{_l.BaseType}:** `{entity.BaseType}`");
             if (!string.IsNullOrEmpty(entity.ModelCaption))
                 sb.AppendLine($"- **{_l.CaptionModelEditor}:** {entity.ModelCaption}");
             if (!string.IsNullOrEmpty(entity.NavigationGroup))
@@ -599,7 +599,7 @@ private DocumentSection GenerateControllersSection(ExtractedProject project)
         {
             sb.AppendLine($"## {controller.ClassName}");
             sb.AppendLine();
-            sb.AppendLine($"- **{_l.BaseType}:** {controller.BaseControllerType}");
+            sb.AppendLine($"- **{_l.BaseType}:** `{controller.BaseControllerType}`");
             if (!string.IsNullOrEmpty(controller.TargetObjectType))
                 sb.AppendLine($"- **{_l.TargetEntity}:** {controller.TargetObjectType}");
             if (!string.IsNullOrEmpty(controller.TargetViewType))
@@ -912,7 +912,7 @@ private DocumentSection GenerateNavigationSection(ExtractedProject project)
             sb.AppendLine();
             foreach (var entity in orphans)
             {
-                sb.AppendLine($"- **{entity.ClassName}** ({entity.BaseType})");
+                sb.AppendLine($"- **{entity.ClassName}** (`{entity.BaseType}`)");
             }
         }
 

tests/XafLogicExplainer.Tests/PortableMarkdownTests.cs

@@ -1,3 +1,4 @@
+using System.Text.RegularExpressions;
 using XafLogicExplainer.Core.Generators;
 using XafLogicExplainer.Core.Models;
 
@@ -19,6 +20,11 @@ namespace XafLogicExplainer.Tests;
 /// pipe tables, fenced code, lists, bold, inline code — maps to a real Word equivalent, so this one
 /// call site was the whole difference between an extraction and a document someone can hand over.
 /// </para>
+/// <para>
+/// The second offender was found the same way, by him, one release later: a generic base type was
+/// printed bare, and <c>&lt;DetailView&gt;</c> is an <em>inline</em> tag rather than a block. The
+/// guard below missed it because it was written to the shape of the first one.
+/// </para>
 /// </remarks>
 public class PortableMarkdownTests
 {
@@ -32,6 +38,7 @@ private static readonly (string Name, ExtractedProject Project)[] Samples =
         ("DeepXpo", SampleProjects.DeepXpo),
         ("AuditedXpo", SampleProjects.AuditedXpo),
         ("Demo", SampleProjects.Demo),
+        ("Walkthrough", SampleProjects.Walkthrough),
     ];
 
     private static string Markdown(ExtractedProject project, string language) =>
@@ -41,10 +48,20 @@ private static string Markdown(ExtractedProject project, string language) =>
             .Replace("\r", "");
 
     /// <summary>
-    /// Lines that begin a CommonMark HTML block: outside a fence, a line whose first character is
-    /// <c>&lt;</c>. Inside a fence the same line is source code and is left alone, which is why this
-    /// tracks the fence rather than matching the whole document at once.
+    /// Every tag CommonMark would treat as HTML, wherever on the line it sits.
     /// </summary>
+    /// <remarks>
+    /// The first version checked only whether a line <em>opened</em> with <c>&lt;</c>, which was the
+    /// shape of the <c>&lt;details&gt;</c> block it was written for. A generic type in the middle of
+    /// a sentence walked straight past it: <c>ViewController&lt;DetailView&gt;</c> is an inline HTML
+    /// tag to every CommonMark parser, so the reader was shown <c>ViewController</c> and nothing
+    /// else — on github.com, where the sanitizer strips the unknown tag, as much as in an export.
+    /// <para>
+    /// Two things are excluded rather than matched. A fenced block is source code, where
+    /// <c>CreateObject&lt;Customer&gt;()</c> is exactly right. An inline code span is the remedy
+    /// itself, so it has to be allowed or the guard would reject its own fix.
+    /// </para>
+    /// </remarks>
     private static List<string> RawHtmlLines(string markdown)
     {
         var offenders = new List<string>();
@@ -58,7 +75,12 @@ private static List<string> RawHtmlLines(string markdown)
                 continue;
             }
 
-            if (!insideFence && line.TrimStart().StartsWith('<'))
+            if (insideFence)
+                continue;
+
+            var bare = Regex.Replace(line, "`[^`]*`", "");
+
+            if (Regex.IsMatch(bare, "</?[A-Za-z][A-Za-z0-9-]*[^<>]*/?>"))
                 offenders.Add(line.Trim());
         }
 
@@ -75,11 +97,25 @@ public void NoGeneratedPageOpensALineWithRawHtml(string language)
             var offenders = RawHtmlLines(Markdown(project, language));
 
             Assert.True(offenders.Count == 0,
-                $"{name} ({language}) emits raw HTML outside a code fence, which renders as literal "
-                + $"text everywhere but a browser: {string.Join(" | ", offenders)}");
+                $"{name} ({language}) emits a tag CommonMark reads as HTML. A block renders as "
+                + "literal text everywhere but a browser; an inline tag is dropped and takes the "
+                + $"type name with it: {string.Join(" | ", offenders)}");
         }
     }
 
+    [Fact]
+    public void AGenericTypeSurvivesBecauseItIsWrittenAsCode()
+    {
+        // Found by @MBrekhof pointing a real Word converter at the output. `ViewController<DetailView>`
+        // was printed bare, and `<DetailView>` is an inline HTML tag to every CommonMark parser: an
+        // export drops it and github.com's sanitizer strips it, so the reader is told the base class
+        // is `ViewController`. That is a different answer rather than a missing one.
+        var english = Markdown(SampleProjects.Xpo, "en");
+
+        Assert.Contains("`ViewController<DetailView>`", english, StringComparison.Ordinal);
+        Assert.DoesNotContain("** ViewController<DetailView>", english, StringComparison.Ordinal);
+    }
+
     [Fact]
     public void TheSeedSourceIsIntroducedByAHeadingRatherThanAFold()
     {