Require readme to stay up to date with --help output

Author: jnm2

Readme.md

@@ -30,24 +30,29 @@ This tool is offered **as-is** for a notoriously complex problem. We hope (witho
 
 ```
 Usage:
-  TFVCmigrator [options] <project-collection-url> <root-path>
+  TfvcMigrator <project-collection-url> <root-path> [options]
 
 Arguments:
-  <project-collection-url>    The URL of the Azure DevOps project collection.
-  <root-path>                 The source path within the TFVC repository to migrate as a Git repository.
+  <project-collection-url>  The URL of the Azure DevOps project collection.
+  <root-path>               The source path within the TFVC repository to migrate as a Git repository.
 
 Options:
-  --authors <authors> (REQUIRED)             Path to an authors file with lines mapping TFVC usernames to Git authors,
-                                             e.g.: DOMAIN\John = John Doe <john@doe.com>
-  --out-dir <out-dir>                        The directory path at which to create a new Git repository. Defaults to
-                                             the last segment in the root path under the current directory.
-  --min-changeset <min-changeset>            The changeset defining the initial commit. Defaults to the first
-                                             changeset under the given source path.
-  --max-changeset <max-changeset>            The last changeset to migrate. Defaults to the most recent changeset
-                                             under the given source path.
-  --root-path-changes <root-path-changes>    Followed by one or more arguments with the format CS1234:$/New/Path.
-                                             Changes the path that is mapped as the Git repository root to a new path
-                                             during a specified changeset.
-  --version                                  Show version information
-  -?, -h, --help                             Show help and usage information
+  --authors <authors> (REQUIRED)           Path to an authors file with lines mapping TFVC usernames to
+                                           Git authors, e.g.: DOMAIN\John = John Doe <john@doe.com>
+  --out-dir <out-dir>                      The directory path at which to create a new Git repository.
+                                           Defaults to the last segment in the root path under the
+                                           current directory.
+  --min-changeset <min-changeset>          The changeset defining the initial commit. Defaults to the
+                                           first changeset under the given source path.
+  --max-changeset <max-changeset>          The last changeset to migrate. Defaults to the most recent
+                                           changeset under the given source path.
+  --root-path-changes <root-path-changes>  Followed by one or more arguments with the format
+                                           CS1234:$/New/Path. Changes the path that is mapped as the Git
+                                           repository root to a new path during a specified changeset.
+  --pat <pat>                              Optional PAT, required to access TFVC repositories hosted on
+                                           Azure DevOps Services. If not provided Default Client
+                                           Credentials will be used, these are only suitable for
+                                           on-premise TFS/Azure DevOps Server.
+  --version                                Show version information
+  -?, -h, --help                           Show help and usage information
 ```

TfvcMigrator.sln

@@ -9,6 +9,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		.editorconfig = .editorconfig
 		src\Directory.Build.props = src\Directory.Build.props
+		Readme.md = Readme.md
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TfvcMigrator.Tests", "src\TfvcMigrator.Tests\TfvcMigrator.Tests.csproj", "{2EA6C987-0EFC-4C95-8593-663730B40F18}"

src/TfvcMigrator.Tests/ReadmeTests.cs

@@ -0,0 +1,29 @@
+using System.Reflection;
+using System.Text.RegularExpressions;
+
+namespace TfvcMigrator.Tests;
+
+public static class ReadmeTests
+{
+    [Test]
+    public static void Command_line_arguments_section_is_up_to_date()
+    {
+        var helpOutput = TestUtils.CaptureConsoleOutput(() => Program.Main(new[] { "--help" }))
+            .Replace(Assembly.GetEntryAssembly()!.GetName().Name!, typeof(Program).Assembly.GetName().Name);
+
+        var expectedReadmeCodeBlock = Regex.Replace(helpOutput, @"\ADescription:\s*\n[^\n]*\n\s*\n", "");
+
+        var readmeContents = File.ReadAllText(Path.Join(TestUtils.DetectSolutionDirectory(), "Readme.md"));
+        var actualReadmeCodeBlock = Regex.Match(readmeContents, @"^## Command-line arguments(?:\s*\n)+```\s*\n(?<contents>.*)\s*\n```", RegexOptions.Singleline | RegexOptions.Multiline).Groups["contents"].Value;
+
+        if (Normalize(actualReadmeCodeBlock) != Normalize(expectedReadmeCodeBlock))
+        {
+            Assert.Fail("Update the ‘Command-line arguments’ section in Readme.md using the program output for the --help.");
+        }
+    }
+
+    private static string Normalize(string possiblyWrappedText)
+    {
+        return Regex.Replace(possiblyWrappedText.Trim(), @"\s+", " ");
+    }
+}

src/TfvcMigrator.Tests/TestUtils.cs

@@ -0,0 +1,33 @@
+namespace TfvcMigrator.Tests;
+
+internal static class TestUtils
+{
+    public static string CaptureConsoleOutput(Action action)
+    {
+        var writer = new StringWriter();
+
+        var originalConsoleOut = Console.Out;
+        Console.SetOut(writer);
+        try
+        {
+            action.Invoke();
+        }
+        finally
+        {
+            Console.SetOut(originalConsoleOut);
+        }
+
+        return writer.ToString();
+    }
+
+    public static string DetectSolutionDirectory()
+    {
+        for (var current = AppContext.BaseDirectory; current is not null; current = Path.GetDirectoryName(current))
+        {
+            if (Directory.EnumerateFiles(current, "*.sln").Any())
+                return current;
+        }
+
+        throw new InvalidOperationException("Unable to locate the solution directory.");
+    }
+}