feat(templates): validate and warn on duplicate block definitions

Add TemplateBlockValidator to detect duplicate block definitions in theme
template overrides (e.g., multiple `{% block header %}`). Duplicate blocks
silently override, causing subtle bugs and confusing debugging.

The validator:
- Parses template files using regex to extract block names
- Warns (not errors) when duplicates are found
- Is case-insensitive (blocks are case-insensitive in Scriban)
- Integrates into TemplateEngine.GetTemplate() before parsing

This catches the issue at build time, preventing silent failures.

Includes 4 test cases covering: no duplicates, single duplicate, multiple
duplicates, and case-insensitive matching.

All 356 tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

src/Netdocs.Core/Templating/TemplateBlockValidator.cs

@@ -0,0 +1,63 @@
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.Logging;
+
+namespace Netdocs.Core.Templating;
+
+/// <summary>
+/// Validates template files for duplicate block definitions, which silently override
+/// and can cause subtle bugs. Emits warnings for each duplicate found.
+/// </summary>
+public sealed class TemplateBlockValidator
+{
+    private readonly ILogger _logger;
+
+    public TemplateBlockValidator(ILogger logger)
+    {
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>Validates a template file for duplicate block definitions.</summary>
+    /// <param name="templatePath">Absolute path to the template file.</param>
+    /// <param name="templateContent">Content of the template.</param>
+    public void Validate(string templatePath, string templateContent)
+    {
+        var blocks = ExtractBlockNames(templateContent);
+        var duplicates = blocks
+            .GroupBy(b => b, StringComparer.OrdinalIgnoreCase)
+            .Where(g => g.Count() > 1)
+            .Select(g => g.Key)
+            .ToList();
+
+        if (duplicates.Count == 0)
+            return;
+
+        var relPath = Path.GetFileName(templatePath);
+        foreach (var blockName in duplicates)
+        {
+            var count = blocks.Count(b => string.Equals(b, blockName, StringComparison.OrdinalIgnoreCase));
+            _logger.LogWarning("Template file '{TemplatePath}' has {Count} definitions of block '{BlockName}' " +
+                               "(only the last one will be used). Consolidate them into a single block.",
+                               relPath, count, blockName);
+        }
+    }
+
+    /// <summary>
+    /// Extracts all block names from a Scriban template using regex.
+    /// Matches `{% block name %}...{% endblock %}` patterns (case-insensitive).
+    /// </summary>
+    private static List<string> ExtractBlockNames(string templateContent)
+    {
+        var result = new List<string>();
+        // Match {% block <name> %} — capture the block name
+        var pattern = @"{%\s*block\s+(\w+)\s*%}";
+        var matches = Regex.Matches(templateContent, pattern, RegexOptions.IgnoreCase);
+
+        foreach (Match match in matches)
+        {
+            if (match.Groups[1].Value is { Length: > 0 } blockName)
+                result.Add(blockName);
+        }
+
+        return result;
+    }
+}

src/Netdocs.Core/Templating/TemplateEngine.cs

@@ -1,5 +1,7 @@
 using Scriban;
 using Scriban.Runtime;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
 
 namespace Netdocs.Core.Templating;
 
@@ -12,11 +14,13 @@ public sealed class TemplateEngine
     private readonly IReadOnlyList<string> _searchDirs;
     private readonly System.Collections.Concurrent.ConcurrentDictionary<string, Template> _cache = new(StringComparer.OrdinalIgnoreCase);
     private readonly ThemeTemplateLoader _loader;
+    private readonly TemplateBlockValidator _blockValidator;
 
-    public TemplateEngine(IEnumerable<string> searchDirsHighestPriorityFirst)
+    public TemplateEngine(IEnumerable<string> searchDirsHighestPriorityFirst, ILogger? logger = null)
     {
         _searchDirs = searchDirsHighestPriorityFirst.Where(Directory.Exists).ToList();
         _loader = new ThemeTemplateLoader(_searchDirs);
+        _blockValidator = new TemplateBlockValidator(logger ?? NullLogger.Instance);
     }
 
     public bool TryResolve(string templateName, out string path) => _loader.TryResolvePath(templateName, out path);
@@ -43,7 +47,9 @@ private Template GetTemplate(string name)
         {
             if (!_loader.TryResolvePath(key, out var path))
                 throw new FileNotFoundException($"Template '{key}' not found in: {string.Join(", ", _searchDirs)}");
-            var template = Template.Parse(File.ReadAllText(path), path);
+            var content = File.ReadAllText(path);
+            _blockValidator.Validate(path, content);
+            var template = Template.Parse(content, path);
             if (template.HasErrors)
                 throw new InvalidOperationException($"Template '{key}' has errors:\n{string.Join('\n', template.Messages)}");
             return template;

tests/Netdocs.Core.Tests/TemplateBlockValidatorTests.cs

@@ -0,0 +1,79 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Xunit;
+
+namespace Netdocs.Core.Tests;
+
+public class TemplateBlockValidatorTests
+{
+    private sealed class TestLogger : ILogger
+    {
+        public List<string> Warnings { get; } = new();
+
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+        public bool IsEnabled(LogLevel logLevel) => true;
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
+        {
+            if (logLevel == LogLevel.Warning)
+                Warnings.Add(formatter(state, exception));
+        }
+    }
+
+    [Fact]
+    public void DetectsNoDuplicates_EmitsNoWarning()
+    {
+        var logger = new TestLogger();
+        var validator = new Netdocs.Core.Templating.TemplateBlockValidator(logger);
+        var content = "{% block header %}...{% endblock %}\n{% block content %}...{% endblock %}";
+
+        validator.Validate("test.html", content);
+
+        Assert.Empty(logger.Warnings);
+    }
+
+    [Fact]
+    public void DetectsDuplicateBlocks_EmitsWarning()
+    {
+        var logger = new TestLogger();
+        var validator = new Netdocs.Core.Templating.TemplateBlockValidator(logger);
+        var content = "{% block header %}first{% endblock %}\n{% block header %}second{% endblock %}";
+
+        validator.Validate("test.html", content);
+
+        Assert.Single(logger.Warnings);
+        Assert.Contains("header", logger.Warnings[0]);
+        Assert.Contains("2 definitions", logger.Warnings[0]);
+    }
+
+    [Fact]
+    public void DetectsMultipleDuplicates_EmitsWarningPerBlock()
+    {
+        var logger = new TestLogger();
+        var validator = new Netdocs.Core.Templating.TemplateBlockValidator(logger);
+        var content = @"
+{% block header %}a{% endblock %}
+{% block header %}b{% endblock %}
+{% block footer %}x{% endblock %}
+{% block footer %}y{% endblock %}
+{% block footer %}z{% endblock %}
+";
+
+        validator.Validate("test.html", content);
+
+        Assert.Equal(2, logger.Warnings.Count);
+        Assert.Contains("header", logger.Warnings[0]);
+        Assert.Contains("footer", logger.Warnings[1]);
+    }
+
+    [Fact]
+    public void CaseInsensitive_TreatsHeaderAndHEADERAsIdentical()
+    {
+        var logger = new TestLogger();
+        var validator = new Netdocs.Core.Templating.TemplateBlockValidator(logger);
+        var content = "{% block header %}{% endblock %}\n{% block HEADER %}{% endblock %}";
+
+        validator.Validate("test.html", content);
+
+        Assert.Single(logger.Warnings);
+    }
+}