Merge pull request #46 from peopleworks/feat/report-rendering

Write the reports down, and say what the list is

Author: peopleworks

CHANGELOG.md

@@ -9,6 +9,31 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **The reports are written down, and the list says what it is** ([#37], the rendering half). They
+  now appear in the Markdown pages, in `AGENTS.md`, and through a new `xaf_reports` MCP tool — each
+  with what it is over, the filter inside its layout, its calculated fields and bound expressions,
+  and the parameters dialog it opens with, including the `GetCriteria()` that turns the answers into
+  a filter.
+
+  **The sentence under the heading carries more than the list.** With `ReportsModuleV2` registered,
+  users design reports at run time and those are stored as database rows, so an application with
+  forty of them and none in its repository is the ordinary case: checked against a production
+  application that registers the module, sets `ReportStoreMode.XML`, and contains no report in
+  source at all. Printing "no reports" there is not an incomplete answer but a wrong one, and the
+  more use an application makes of reports the wronger it gets. Three states are told apart — the
+  module absent and the list complete, the module present and the list a **lower bound**, and the
+  module present with nothing in source, where the number is reported as *unknown rather than zero*.
+  An application that registers nothing and ships no layout gets no section, because there "no
+  reports" is the default rather than a finding.
+
+  Two things the generated document showed that reading the code would not have. A layout kept
+  beside the module rather than inside it was cited by its **absolute path** — the drive of whichever
+  machine ran the extraction, in a file meant to be committed; citations now fall back to the
+  solution root and then to the file name, never to a path that is wrong everywhere but here. And
+  two registrations sharing one `.repx` printed the filter, the bindings and the whole of
+  `GetCriteria()` twice, burying the only thing that differs between them; the second now points at
+  the first.
+
 - **The reports an application declares are read** ([#37], phases 1–3 — the extraction; the
   Markdown and MCP rendering follow separately). Reports V2 leaves four kinds of trace in a
   repository, all syntax, and none of them was read: the registration

README.md

@@ -186,6 +186,7 @@ Started from a solution directory it finds the XAF module by itself, so neither
 | `xaf_model` | Model Editor customizations, which exist in no C# file |
 | `xaf_editors` | Custom editors, the JavaScript they need, and built-in editors changed at run time |
 | `xaf_migrations` | What ran once against a live database, and the comment explaining why |
+| `xaf_reports` | What each report is over, the filter inside it, and the dialog it opens with |
 | `xaf_view` | Everything loaded onto one screen — which controllers activate, and why |
 | `xaf_walkthrough` | **How one process works end to end** — what runs, in what order, and what it could not follow |
 | `xaf_refresh` | Re-read the source (changes are detected automatically) |
@@ -388,9 +389,9 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | **`AGENTS.md` / `CLAUDE.md` / Copilot instructions** — zero infrastructure, works for everyone |
 | ✅ | **`xaflogic explain`** — one self-contained HTML page, for a person rather than an agent |
 | ✅ | Pluggable publishing targets (`IDocumentationSink`) |
-| ✅ | **MCP server** — 11 tools, live against your source |
+| ✅ | **MCP server** — 12 tools, live against your source |
 | ✅ | **Installable Claude Code plugin** with skill and MCP server |
-| ✅ | **445 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
+| ✅ | **457 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/AgentContextGenerator.cs

@@ -74,6 +74,7 @@ public string GenerateIndex(ExtractedProject project, IReadOnlyList<string> deta
         WriteCriteriaExamples(sb, conventions);
         WriteEditors(sb, project);
         WriteMigrations(sb, project);
+        WriteReports(sb, project);
         WriteConventions(sb, project, conventions);
         WriteRecipes(sb, project, conventions);
         WriteDetailPointers(sb, detailFiles);
@@ -547,6 +548,67 @@ private static void WriteEditors(StringBuilder sb, ExtractedProject project)
     /// column holds what it holds, an agent will reason from code that runs today and invent a
     /// cause. The real one ran once, years ago, and only the updater remembers it.
     /// </remarks>
+    /// <summary>
+    /// The reports, and the reason their number may be larger than it looks.
+    /// </summary>
+    /// <remarks>
+    /// The bound is the point of this block, not the list. An agent that reads "no reports" builds
+    /// as though none exist, and with <c>ReportsModuleV2</c> registered that is the normal state of
+    /// an application whose users design their reports at run time — stored as database rows, which
+    /// nothing reading source can reach. The list is worth having; the sentence is worth more.
+    /// </remarks>
+    private static void WriteReports(StringBuilder sb, ExtractedProject project)
+    {
+        if (!project.ReferencesReportsModule && project.Reports.Count == 0)
+            return;
+
+        sb.AppendLine("## Reports");
+        sb.AppendLine();
+
+        if (project.Reports.Count == 0)
+        {
+            sb.AppendLine("This application registers `ReportsModuleV2` and declares **no report in source**.");
+            sb.AppendLine("That is not the same as having none: users design reports at run time and they are");
+            sb.AppendLine("stored in the database, out of reach of anything reading this repository. The number");
+            sb.AppendLine("is unknown, not zero — do not tell anyone this application has no reports.");
+            sb.AppendLine();
+
+            return;
+        }
+
+        foreach (var report in project.Reports)
+        {
+            var opens = report.ParametersType is { Length: > 0 } parameters
+                ? $", after a `{parameters}` dialog"
+                : "";
+
+            sb.AppendLine($"- **{report.DisplayName}** — over `{report.DataType}`{opens}"
+                + FilterClause(report));
+        }
+
+        sb.AppendLine();
+
+        if (project.ReferencesReportsModule)
+        {
+            sb.AppendLine("`ReportsModuleV2` is registered, so users can also design reports at run time.");
+            sb.AppendLine("Those live in the database and are not listed here: **this is a lower bound**.");
+            sb.AppendLine();
+        }
+
+        if (project.UnregisteredReportLayouts.Count > 0)
+        {
+            sb.AppendLine($"{project.UnregisteredReportLayouts.Count} more layout"
+                + (project.UnregisteredReportLayouts.Count == 1 ? " is" : "s are")
+                + " in the repository that no registration names — usually exported from the running");
+            sb.AppendLine("application and imported by hand. Ask `xaf_reports` for them.");
+            sb.AppendLine();
+        }
+    }
+
+    /// <summary>The filter a report carries, which is the business decision inside it.</summary>
+    private static string FilterClause(ExtractedReport report) =>
+        report.Layout?.FilterString is { Length: > 0 } filter ? $", filtered to `{filter}`" : "";
+
     private static void WriteMigrations(StringBuilder sb, ExtractedProject project)
     {
         if (project.Migrations.Count == 0)