feat: xml extension

Author: Spelkington

.github/hooks/hooks.json

@@ -10,13 +10,13 @@
     "Stop": [
       {
         "type": "command",
-        "command": "node .github/hooks/scripts/stop-build.js",
-        "timeout": 600
+        "command": "node .github/hooks/scripts/stop-test-coverage.js",
+        "timeout": 30
       },
       {
         "type": "command",
-        "command": "node .github/hooks/scripts/stop-test-coverage.js",
-        "timeout": 30
+        "command": "node .github/hooks/scripts/stop-build.js",
+        "timeout": 600
       }
     ]
   }

Flowthru.slnx

@@ -12,6 +12,7 @@
     <Project Path="src/core/Flowthru.Core.CodeFixes/Flowthru.Core.CodeFixes.csproj" />
     <Project Path="src/core/Flowthru.FUnit.CodeFixes/Flowthru.FUnit.CodeFixes.csproj" />
     <Project Path="src/extensions/Flowthru.Extensions.Csv/Flowthru.Extensions.Csv.csproj" />
+    <Project Path="src/extensions/Flowthru.Extensions.Xml/Flowthru.Extensions.Xml.csproj" />
     <Project Path="src/extensions/Flowthru.Extensions.Excel/Flowthru.Extensions.Excel.csproj" />
     <Project Path="src/extensions/Flowthru.Extensions.EFCore/Flowthru.Extensions.EFCore.csproj" />
     <Project Path="src/extensions/Flowthru.Extensions.GQL/Flowthru.Extensions.GQL.csproj" />
@@ -59,6 +60,7 @@
     <Project Path="tests/extensions/Flowthru.Extensions.EFCore.Bulk.Tests/Flowthru.Extensions.EFCore.Bulk.Tests.csproj" />
     <Project Path="tests/extensions/Flowthru.Extensions.Python.Tests/Flowthru.Extensions.Python.Tests.csproj" />
     <Project Path="tests/extensions/Flowthru.Extensions.Python.SourceGenerators.Tests/Flowthru.Extensions.Python.SourceGenerators.Tests.csproj" />
+    <Project Path="tests/extensions/Flowthru.Extensions.Xml.Tests/Flowthru.Extensions.Xml.Tests.csproj" />
   </Folder>
   <Folder Name="/tests/misc/">
     <Project Path="tests/misc/Flowthru.Misc.DataFrames.Tests/Flowthru.Misc.DataFrames.Tests.csproj" />
@@ -85,5 +87,6 @@
     <Project Path="examples/advanced/SpaceflightsDistributed/SpaceflightsDistributed/SpaceflightsDistributed.csproj" />
     <Project Path="examples/advanced/RetailDataSplitFlow/RetailDataSplitFlow.csproj" />
     <Project Path="examples/advanced/KedroSpaceflightsGQL/KedroSpaceflightsGQL.csproj" />
+    <Project Path="examples/advanced/FlowthruCoverage/FlowthruCoverage.csproj" />
   </Folder>
 </Solution>

examples/advanced/FlowthruCoverage/.gitignore

@@ -0,0 +1,16 @@
+# Generated metadata
+Metadata/
+
+# Ignore all generated data artifacts
+Data/**
+
+# Un-ignore layer directories and their Schemas subdirectories
+!Data/*/
+!Data/*/Schemas/
+!Data/_01_Raw/Datasets/
+
+# Un-ignore schema and catalog .cs files
+!Data/**/*.cs
+
+# Un-ignore .gitkeep files
+!**/.gitkeep

examples/advanced/FlowthruCoverage/.python-version

@@ -0,0 +1 @@
+3.13

examples/advanced/FlowthruCoverage/Data/Catalog.cs

@@ -0,0 +1,14 @@
+using Flowthru.Core.Data;
+
+namespace FlowthruCoverage.Data;
+
+public partial class Catalog : CatalogAbstract
+{
+  private readonly string _basePath;
+
+  public Catalog(string basePath)
+  {
+    _basePath = basePath;
+    InitializeCatalogProperties();
+  }
+}

examples/advanced/FlowthruCoverage/Data/_01_Raw/Catalog.Raw.cs

@@ -0,0 +1,21 @@
+using FlowthruCoverage.Data._01_Raw.Schemas;
+using Flowthru.Core.Data;
+
+namespace FlowthruCoverage.Data;
+
+public partial class Catalog
+{
+  /// <summary>
+  /// Staged Cobertura XML files, one per test or example project.
+  /// Run the <c>_stage-coverage-xml</c> NX target before executing the pipeline.
+  /// Each file is named <c>{ProjectName}.xml</c>.
+  /// </summary>
+  public IItem<IEnumerable<XmlDocument<CoberturaReport>>> CoverageXmlFiles =>
+    CreateItem(
+      () =>
+        ItemFactory.Enumerable.XmlDocuments<CoberturaReport>(
+          label: "CoverageXmlFiles",
+          directoryPath: $"{_basePath}/_01_Raw/Datasets"
+        )
+    );
+}

examples/advanced/FlowthruCoverage/Data/_01_Raw/Schemas/CoberturaReport.cs

@@ -0,0 +1,98 @@
+using System.Xml.Serialization;
+using Flowthru.Core.Abstractions;
+
+namespace FlowthruCoverage.Data._01_Raw.Schemas;
+
+/// <summary>Root element of a Cobertura XML coverage report.</summary>
+[XmlRoot("coverage")]
+public class CoberturaReport : IStructuredSerializable
+{
+  [XmlAttribute("line-rate")]
+  public double LineRate { get; set; }
+
+  [XmlAttribute("branch-rate")]
+  public double BranchRate { get; set; }
+
+  [XmlAttribute("lines-covered")]
+  public int LinesCovered { get; set; }
+
+  [XmlAttribute("lines-valid")]
+  public int LinesValid { get; set; }
+
+  [XmlAttribute("branches-covered")]
+  public int BranchesCovered { get; set; }
+
+  [XmlAttribute("branches-valid")]
+  public int BranchesValid { get; set; }
+
+  [XmlArray("packages")]
+  [XmlArrayItem("package")]
+  public List<CoberturaPackage> Packages { get; set; } = [];
+}
+
+/// <summary>A named package (assembly) within a Cobertura report.</summary>
+public class CoberturaPackage
+{
+  [XmlAttribute("name")]
+  public string Name { get; set; } = string.Empty;
+
+  [XmlAttribute("line-rate")]
+  public double LineRate { get; set; }
+
+  [XmlAttribute("branch-rate")]
+  public double BranchRate { get; set; }
+
+  [XmlArray("classes")]
+  [XmlArrayItem("class")]
+  public List<CoberturaClass> Classes { get; set; } = [];
+}
+
+/// <summary>A named class within a package.</summary>
+public class CoberturaClass
+{
+  [XmlAttribute("name")]
+  public string Name { get; set; } = string.Empty;
+
+  [XmlAttribute("filename")]
+  public string Filename { get; set; } = string.Empty;
+
+  [XmlAttribute("line-rate")]
+  public double LineRate { get; set; }
+
+  [XmlAttribute("branch-rate")]
+  public double BranchRate { get; set; }
+
+  [XmlArray("methods")]
+  [XmlArrayItem("method")]
+  public List<CoberturaMethod> Methods { get; set; } = [];
+}
+
+/// <summary>A named method within a class.</summary>
+public class CoberturaMethod
+{
+  [XmlAttribute("name")]
+  public string Name { get; set; } = string.Empty;
+
+  [XmlAttribute("signature")]
+  public string Signature { get; set; } = string.Empty;
+
+  [XmlAttribute("line-rate")]
+  public double LineRate { get; set; }
+
+  [XmlAttribute("branch-rate")]
+  public double BranchRate { get; set; }
+
+  [XmlArray("lines")]
+  [XmlArrayItem("line")]
+  public List<CoberturaLine> Lines { get; set; } = [];
+}
+
+/// <summary>A single instrumented line within a method.</summary>
+public class CoberturaLine
+{
+  [XmlAttribute("number")]
+  public int Number { get; set; }
+
+  [XmlAttribute("hits")]
+  public int Hits { get; set; }
+}

examples/advanced/FlowthruCoverage/Data/_02_Intermediate/Catalog.Intermediate.cs

@@ -0,0 +1,17 @@
+using FlowthruCoverage.Data._02_Intermediate.Schemas;
+using Flowthru.Core.Data;
+
+namespace FlowthruCoverage.Data;
+
+public partial class Catalog
+{
+  /// <summary>Flat line-level coverage rows, one row per instrumented line per test project.</summary>
+  public IItem<IEnumerable<LineCoverageRow>> LineCoverage =>
+    CreateItem(
+      () =>
+        ItemFactory.Enumerable.Csv<LineCoverageRow>(
+          label: "LineCoverage",
+          filePath: $"{_basePath}/_02_Intermediate/Datasets/line_coverage.csv"
+        )
+    );
+}

examples/advanced/FlowthruCoverage/Data/_02_Intermediate/Schemas/LineCoverageRow.cs

@@ -0,0 +1,37 @@
+using Flowthru.Core.Abstractions;
+
+namespace FlowthruCoverage.Data._02_Intermediate.Schemas;
+
+/// <summary>
+/// A single instrumented line from a coverage report, tagged with its origin test project.
+/// One row per source line per test project that exercised it.
+/// </summary>
+[FlowthruSchema]
+public partial record LineCoverageRow
+{
+  /// <summary>The test or example project that produced this coverage reading (derived from file name).</summary>
+  public required string TestProject { get; init; }
+
+  /// <summary>The assembly/package name as reported by Cobertura (e.g. "Flowthru.Core").</summary>
+  public required string SrcPackage { get; init; }
+
+  /// <summary>The source file path as recorded in the Cobertura XML.</summary>
+  public required string SourceFile { get; init; }
+
+  /// <summary>The fully-qualified class name.</summary>
+  public required string ClassName { get; init; }
+
+  /// <summary>The method name.</summary>
+  public required string MethodName { get; init; }
+
+  /// <summary>The method signature.</summary>
+  public required string MethodSignature { get; init; }
+
+  /// <summary>The source line number.</summary>
+  public required int LineNumber { get; init; }
+
+  /// <summary>
+  /// Number of times this line was executed. 0 = uncovered; &gt;0 = covered with that many hits.
+  /// </summary>
+  public required int Hits { get; init; }
+}

examples/advanced/FlowthruCoverage/Data/_03_Primary/Catalog.Primary.cs

@@ -0,0 +1,20 @@
+using FlowthruCoverage.Data._03_Primary.Schemas;
+using Flowthru.Core.Data;
+
+namespace FlowthruCoverage.Data;
+
+public partial class Catalog
+{
+  /// <summary>
+  /// Per-(TestProject, SrcPackage) coverage aggregates.
+  /// Pivot this CSV on TestProject vs SrcPackage to produce the coverage heatmap.
+  /// </summary>
+  public IItem<IEnumerable<PackageCoverageRow>> PackageCoverage =>
+    CreateItem(
+      () =>
+        ItemFactory.Enumerable.Csv<PackageCoverageRow>(
+          label: "PackageCoverage",
+          filePath: $"{_basePath}/_03_Primary/Datasets/package_coverage.csv"
+        )
+    );
+}