Generalize CodeBlocker into a code-generation substrate

CodeBlocker.Test/CodeBlockerExtensionsTests.cs

@@ -0,0 +1,146 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace CodeBlocker.Tests;
+
+using ktsu.CodeBlocker;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+/// <summary>
+/// Covers the file-level preamble helpers.
+/// </summary>
+[TestClass]
+public sealed class CodeBlockerExtensionsTests
+{
+	private static CodeBlocker Create() => CodeBlocker.Create(CodeBlocker.DefaultIndentString, NewLines.Lf);
+
+	[TestMethod]
+	public void AutoGeneratedHeaderWithoutCopyrightIsJustTheMarker()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker.WriteAutoGeneratedHeader();
+
+		Assert.AreEqual("// <auto-generated />\n\n", codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void AutoGeneratedHeaderPutsTheCopyrightAboveTheMarker()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker.WriteAutoGeneratedHeader("Copyright (c) 2023-2026 ktsu-dev contributors");
+
+		Assert.AreEqual(
+			"// Copyright (c) 2023-2026 ktsu-dev contributors\n// <auto-generated />\n\n",
+			codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void NullableDirectivesAreWrittenVerbatim()
+	{
+		using CodeBlocker enable = Create();
+		using CodeBlocker disable = Create();
+
+		enable.WriteNullableEnable();
+		disable.WriteNullableDisable();
+
+		Assert.AreEqual("#nullable enable\n", enable.ToString());
+		Assert.AreEqual("#nullable disable\n", disable.ToString());
+	}
+
+	[TestMethod]
+	public void FileScopedNamespaceIsFollowedByABlankLine()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker.WriteFileScopedNamespace("Contoso.Widgets");
+
+		Assert.AreEqual("namespace Contoso.Widgets;\n\n", codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void AnEmptyNamespaceWritesNothing()
+	{
+		using CodeBlocker nullNamespace = Create();
+		using CodeBlocker emptyNamespace = Create();
+
+		nullNamespace.WriteFileScopedNamespace(null);
+		emptyNamespace.WriteFileScopedNamespace(string.Empty);
+
+		Assert.AreEqual(string.Empty, nullNamespace.ToString());
+		Assert.AreEqual(string.Empty, emptyNamespace.ToString());
+	}
+
+	[TestMethod]
+	public void UsingsAreWrittenOnePerLineAndFollowedByABlankLine()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker.WriteUsings("System", "System.Collections.Generic");
+
+		Assert.AreEqual("using System;\nusing System.Collections.Generic;\n\n", codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void UsingsAreWrittenVerbatimSoAliasesAndStaticImportsWork()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker.WriteUsings("static System.Math", "Text = System.Text");
+
+		Assert.AreEqual("using static System.Math;\nusing Text = System.Text;\n\n", codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void NoUsingsWritesNothingIncludingTheBlankLine()
+	{
+		// Both overloads, because a generator calls this unconditionally and either spelling has to
+		// come out empty rather than leaving a stray blank line at the top of the file.
+		using CodeBlocker noArguments = Create();
+		using CodeBlocker emptySequence = Create();
+
+		noArguments.WriteUsings();
+		emptySequence.WriteUsings(Enumerable.Empty<string>());
+
+		Assert.AreEqual(string.Empty, noArguments.ToString());
+		Assert.AreEqual(string.Empty, emptySequence.ToString());
+	}
+
+	[TestMethod]
+	public void APreambleComposesWithConsistentSpacing()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		codeBlocker
+			.WriteAutoGeneratedHeader("Copyright (c) 2023-2026 ktsu-dev contributors")
+			.WriteNullableEnable()
+			.WriteFileScopedNamespace("Contoso.Widgets")
+			.WriteUsings("System");
+
+		Assert.AreEqual(
+			"""
+			// Copyright (c) 2023-2026 ktsu-dev contributors
+			// <auto-generated />
+
+			#nullable enable
+			namespace Contoso.Widgets;
+
+			using System;
+
+
+			""".ReplaceLineEndings("\n"),
+			codeBlocker.ToString());
+	}
+
+	[TestMethod]
+	public void NullArgumentsThrow()
+	{
+		using CodeBlocker codeBlocker = Create();
+
+		Assert.ThrowsExactly<ArgumentNullException>(() => CodeBlockerExtensions.WriteAutoGeneratedHeader(null!));
+		Assert.ThrowsExactly<ArgumentNullException>(() => CodeBlockerExtensions.WriteNullableEnable(null!));
+		Assert.ThrowsExactly<ArgumentNullException>(() => CodeBlockerExtensions.WriteNullableDisable(null!));
+		Assert.ThrowsExactly<ArgumentNullException>(() => CodeBlockerExtensions.WriteFileScopedNamespace(null!, "N"));
+		Assert.ThrowsExactly<ArgumentNullException>(() => codeBlocker.WriteUsings((IEnumerable<string>)null!));
+	}
+}

CodeBlocker.Test/DocCommentTests.cs

@@ -0,0 +1,244 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace CodeBlocker.Tests;
+
+using ktsu.CodeBlocker;
+using ktsu.CodeBlocker.Templates;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+/// <summary>
+/// Covers XML documentation modelled as data: escaping, tag order, multi-line layout, and
+/// validation against the documented member.
+/// </summary>
+[TestClass]
+public sealed class DocCommentTests
+{
+	private static string Render(Action<CodeBlocker> write)
+	{
+		using CodeBlocker codeBlocker = CodeBlocker.Create(CodeBlocker.DefaultIndentString, NewLines.Lf);
+		write(codeBlocker);
+		return codeBlocker.ToString();
+	}
+
+	private static string Render(DocComment documentation) => Render(documentation.WriteTo);
+
+	[TestMethod]
+	public void AnEmptyCommentWritesNothing()
+	{
+		DocComment documentation = new();
+
+		Assert.IsTrue(documentation.IsEmpty);
+		Assert.AreEqual(string.Empty, Render(documentation));
+	}
+
+	[TestMethod]
+	public void ASingleLineSummaryStaysOnOneLine() =>
+		Assert.AreEqual(
+			"/// <summary>How many widgets.</summary>\n",
+			Render(new DocComment { Summary = "How many widgets." }));
+
+	[TestMethod]
+	public void AMultiLineSummaryPrefixesEveryLine()
+	{
+		DocComment documentation = new()
+		{
+			Summary = "How many widgets.\nCounted lazily.",
+		};
+
+		Assert.AreEqual(
+			"""
+			/// <summary>
+			/// How many widgets.
+			/// Counted lazily.
+			/// </summary>
+
+			""".ReplaceLineEndings("\n"),
+			Render(documentation));
+	}
+
+	[TestMethod]
+	public void ABlankLineInsideATagIsWrittenWithoutTrailingWhitespace()
+	{
+		DocComment documentation = new() { Remarks = "First.\n\nSecond." };
+
+		Assert.AreEqual(
+			"/// <remarks>\n/// First.\n///\n/// Second.\n/// </remarks>\n",
+			Render(documentation));
+	}
+
+	[TestMethod]
+	public void EitherLineTerminatorSplitsTheText()
+	{
+		Assert.AreEqual(
+			Render(new DocComment { Summary = "a\nb" }),
+			Render(new DocComment { Summary = "a\r\nb" }));
+	}
+
+	[TestMethod]
+	public void TextContentIsEscapedByDefault()
+	{
+		// "values in the range <0, 1>" is an entirely ordinary thing for metadata to say, and it
+		// used to emit malformed XML.
+		DocComment documentation = new() { Summary = "Values in the range <0, 1> & beyond." };
+
+		Assert.AreEqual(
+			"/// <summary>Values in the range &lt;0, 1&gt; &amp; beyond.</summary>\n",
+			Render(documentation));
+	}
+
+	[TestMethod]
+	public void EscapingCanBeTurnedOffForTextThatEmbedsMarkup()
+	{
+		DocComment documentation = new()
+		{
+			EscapeText = false,
+			Summary = "Wraps <see cref=\"System.Int32\"/>.",
+		};
+
+		Assert.AreEqual(
+			"/// <summary>Wraps <see cref=\"System.Int32\"/>.</summary>\n",
+			Render(documentation));
+	}
+
+	[TestMethod]
+	public void AttributeValuesAreAlwaysEscaped()
+	{
+		DocComment documentation = new() { EscapeText = false };
+		documentation.Params.Add(new DocTag { Name = "a<b", Text = "x" });
+
+		Assert.AreEqual("/// <param name=\"a&lt;b\">x</param>\n", Render(documentation));
+	}
+
+	[TestMethod]
+	public void TagsAreWrittenInCanonicalOrder()
+	{
+		DocComment documentation = new()
+		{
+			Remarks = "Remarks.",
+			Returns = "The sum.",
+			Value = "The value.",
+			Summary = "Adds.",
+		};
+		documentation.SeeAlso.Add("System.Math");
+		documentation.Exceptions.Add(new DocTag { Name = "System.OverflowException", Text = "It overflowed." });
+		documentation.Params.Add(new DocTag { Name = "a", Text = "First." });
+		documentation.TypeParams.Add(new DocTag { Name = "T", Text = "The type." });
+
+		Assert.AreEqual(
+			"""
+			/// <summary>Adds.</summary>
+			/// <typeparam name="T">The type.</typeparam>
+			/// <param name="a">First.</param>
+			/// <returns>The sum.</returns>
+			/// <value>The value.</value>
+			/// <exception cref="System.OverflowException">It overflowed.</exception>
+			/// <remarks>Remarks.</remarks>
+			/// <seealso cref="System.Math"/>
+
+			""".ReplaceLineEndings("\n"),
+			Render(documentation));
+	}
+
+	[TestMethod]
+	public void InheritDocIsWrittenFirst()
+	{
+		DocComment bare = new() { InheritDoc = true };
+		DocComment withCref = new() { InheritDoc = true, InheritDocCref = "IWidget.Count", Summary = "Count." };
+
+		Assert.AreEqual("/// <inheritdoc/>\n", Render(bare));
+		Assert.AreEqual(
+			"/// <inheritdoc cref=\"IWidget.Count\"/>\n/// <summary>Count.</summary>\n",
+			Render(withCref));
+	}
+
+	[TestMethod]
+	public void ValidationAcceptsAMatchingComment()
+	{
+		DocComment documentation = new();
+		documentation.Params.Add(new DocTag { Name = "a", Text = "First." });
+		documentation.TypeParams.Add(new DocTag { Name = "T", Text = "The type." });
+
+		Assert.IsEmpty(documentation.Validate(["a"], ["T"]));
+	}
+
+	[TestMethod]
+	public void ValidationReportsATagThatNamesNothing()
+	{
+		DocComment documentation = new();
+		documentation.Params.Add(new DocTag { Name = "typo", Text = "First." });
+
+		IReadOnlyList<string> issues = documentation.Validate(["a"], []);
+
+		Assert.HasCount(2, issues);
+		Assert.Contains("typo", issues[0]);
+		Assert.Contains("'a' has no <param> entry", issues[1]);
+	}
+
+	[TestMethod]
+	public void ValidationReportsADuplicateTag()
+	{
+		DocComment documentation = new();
+		documentation.Params.Add(new DocTag { Name = "a", Text = "First." });
+		documentation.Params.Add(new DocTag { Name = "a", Text = "Again." });
+
+		IReadOnlyList<string> issues = documentation.Validate(["a"], []);
+
+		Assert.HasCount(1, issues);
+		Assert.Contains("more than once", issues[0]);
+	}
+
+	[TestMethod]
+	public void ValidationRejectsNullArguments()
+	{
+		DocComment documentation = new();
+
+		Assert.ThrowsExactly<ArgumentNullException>(() => documentation.Validate(null!, []));
+		Assert.ThrowsExactly<ArgumentNullException>(() => documentation.Validate([], null!));
+	}
+
+	[TestMethod]
+	public void ATemplateWritesItsDocumentationAboveItsAttributes()
+	{
+		MethodTemplate method = new()
+		{
+			Type = "int",
+			Name = "Add",
+			Keywords = { "public" },
+			Attributes = { "Pure" },
+			Comments = { "// Runs in constant time." },
+			Parameters =
+			{
+				new ParameterTemplate { Type = "int", Name = "a" },
+				new ParameterTemplate { Type = "int", Name = "b" },
+			},
+			Documentation = new DocComment
+			{
+				Summary = "Adds two numbers.",
+				Returns = "Their sum.",
+				Params =
+				{
+					new DocTag { Name = "a", Text = "The first." },
+					new DocTag { Name = "b", Text = "The second." },
+				},
+			},
+			BodyFactory = codeBlocker => codeBlocker.Write("=> a + b;"),
+		};
+
+		Assert.AreEqual(
+			"""
+			/// <summary>Adds two numbers.</summary>
+			/// <param name="a">The first.</param>
+			/// <param name="b">The second.</param>
+			/// <returns>Their sum.</returns>
+			// Runs in constant time.
+			[Pure]
+			public int Add(int a, int b) => a + b;
+
+			""".ReplaceLineEndings("\n"),
+			Render(method.WriteTo));
+	}
+
+	[TestMethod]
+	public void NullCodeBlockerIsRejected() =>
+		Assert.ThrowsExactly<ArgumentNullException>(() => new DocComment().WriteTo(null!));
+}