Further adjustments

Author: cotti

README.md

@@ -25,8 +25,9 @@ Options:
   --force <bool?>            Force a full rebuild of the destination folder (Default: null)
 
 Commands:
-  generate    Converts a source markdown folder or file to an output folder
-  serve       Continuously serve a documentation folder at http://localhost:3000.
+  generate        Converts a source markdown folder or file to an output folder
+  serve           Continuously serve a documentation folder at http://localhost:3000.
+  diff validate   Validates redirect rules have been applied to the current branch.
     File systems changes will be reflected without having to restart the server.
 ```
 
@@ -118,6 +119,16 @@ https://github.com/elastic/{your-repository}/settings/pages
 
 ---
 
+## Validating redirection rules
+
+If documentation is moved, renamed or deleted, `docs-builder` can verify if changes in the working branch in relation to the default branch are reflected in the repository's `redirects.yml`. Verification in the local machine is currently supported.
+
+`docs-builder diff validate <path>`
+
+`<path>` is an optional parameter to customize the documentation folder path. It defaults to `docs`.
+
+---
+
 ## Run without docker
 
 You can use the .NET CLI to publish a self-contained `docs-builder` native code
@@ -140,7 +151,7 @@ existing surveyed tools
 
 # Local Development
 
-## Preqrequisites
+## Prerequisites
 
 - [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/9.0)
 - [Node.js 22.13.1 (LTS)](https://nodejs.org/en/blog/release/v22.13.1)

src/tooling/Elastic.Documentation.Tooling/ExternalCommands/ExternalCommandExecutor.cs

@@ -64,7 +64,9 @@ string[] CaptureOutput()
 	}
 
 
-	protected string Capture(string binary, params string[] args)
+	protected string Capture(string binary, params string[] args) => Capture(false, binary, args);
+
+	protected string Capture(bool muteExceptions, string binary, params string[] args)
 	{
 		// Try 10 times to capture the output of the command, if it fails, we'll throw an exception on the last try
 		Exception? e = null;
@@ -81,7 +83,7 @@ protected string Capture(string binary, params string[] args)
 			}
 		}
 
-		if (e is not null)
+		if (e is not null && !muteExceptions)
 			collector.EmitError("", "failure capturing stdout", e);
 
 		return string.Empty;
@@ -96,9 +98,11 @@ string CaptureOutput()
 				ConsoleOutWriter = NoopConsoleWriter.Instance
 			};
 			var result = Proc.Start(arguments);
-			var line = result.ExitCode != 0
-				? throw new Exception($"Exit code is not 0. Received {result.ExitCode} from {binary}: {workingDirectory}")
-				: result.ConsoleOut.FirstOrDefault()?.Line ?? throw new Exception($"No output captured for {binary}: {workingDirectory}");
+			var line = (result.ExitCode, muteExceptions) switch
+			{
+				(0, _) or (not 0, true) => result.ConsoleOut.FirstOrDefault()?.Line ?? throw new Exception($"No output captured for {binary}: {workingDirectory}"),
+				(not 0, false) => throw new Exception($"Exit code is not 0. Received {result.ExitCode} from {binary}: {workingDirectory}")
+			};
 			return line;
 		}
 	}

src/tooling/docs-builder/Cli/ValidationCommands.cs renamed to src/tooling/docs-builder/Cli/DiffCommands.cs

@@ -15,22 +15,25 @@
 
 namespace Documentation.Builder.Cli;
 
-internal sealed class ValidationCommands(ILoggerFactory logger, ICoreService githubActionsService)
+internal sealed class DiffCommands(ILoggerFactory logger, ICoreService githubActionsService)
 {
 	/// <summary>
 	/// Validates redirect updates in the current branch using the redirects file against changes reported by git.
 	/// </summary>
+	/// <param name="path">The baseline path to perform the check</param>
 	/// <param name="ctx"></param>
 	[SuppressMessage("Usage", "CA2254:Template should be a static expression")]
 	[Command("validate")]
 	[ConsoleAppFilter<StopwatchFilter>]
 	[ConsoleAppFilter<CatchExceptionFilter>]
-	public async Task<int> ValidateRedirects(Cancel ctx = default)
+	public async Task<int> ValidateRedirects([Argument] string? path = null, Cancel ctx = default)
 	{
 		var log = logger.CreateLogger<Program>();
 		ConsoleApp.Log = msg => log.LogInformation(msg);
 		ConsoleApp.LogError = msg => log.LogError(msg);
 
+		path ??= "docs";
+
 		await using var collector = new ConsoleDiagnosticsCollector(logger, githubActionsService).StartAsync(ctx);
 
 		var fs = new FileSystem();
@@ -51,11 +54,11 @@ public async Task<int> ValidateRedirects(Cancel ctx = default)
 			return collector.Errors;
 		}
 
-		var tracker = new GitRepositoryTracker(collector, root);
-		var changed = tracker.GetChangedFiles();
+		var tracker = new LocalGitRepositoryTracker(collector, root);
+		var changed = tracker.GetChangedFiles(path);
 
 		foreach (var notFound in changed.Where(c => !redirects.ContainsKey(c)))
-			collector.EmitError(notFound, $"{notFound} has been moved or deleted without a redirect rule being set for it. Please add a redirect rule in this project's {redirectFileInfo.Name}.");
+			collector.EmitError(notFound, $"{notFound} does not have a redirect rule set. Please add a redirect rule in this project's {redirectFileInfo.Name}.");
 
 		await collector.StopAsync(ctx);
 		return collector.Errors;

src/tooling/docs-builder/Program.cs

@@ -17,6 +17,6 @@
 var app = ConsoleApp.Create();
 app.Add<Commands>();
 app.Add<InboundLinkCommands>("inbound-links");
-app.Add<ValidationCommands>("diff");
+app.Add<DiffCommands>("diff");
 
 await app.RunAsync(args).ConfigureAwait(false);

src/tooling/docs-builder/Tracking/GitRepositoryTracker.cs

@@ -6,5 +6,5 @@ namespace Documentation.Builder.Tracking;
 
 public interface IRepositoryTracker
 {
-	IEnumerable<string> GetChangedFiles();
+	IEnumerable<string> GetChangedFiles(string lookupPath);
 }

src/tooling/docs-builder/Tracking/IRepositoryTracker.cs

@@ -0,0 +1,37 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.IO.Abstractions;
+using Elastic.Documentation.Diagnostics;
+using Elastic.Documentation.Tooling.ExternalCommands;
+namespace Documentation.Builder.Tracking;
+
+public partial class LocalGitRepositoryTracker(DiagnosticsCollector collector, IDirectoryInfo workingDirectory) : ExternalCommandExecutor(collector, workingDirectory), IRepositoryTracker
+{
+	public IEnumerable<string> GetChangedFiles(string lookupPath)
+	{
+		var defaultBranch = GetDefaultBranch();
+		var commitChanges = CaptureMultiple("git", "diff", "--name-status", $"{defaultBranch}...HEAD", "--", $"./{lookupPath}");
+		var localChanges = CaptureMultiple("git", "status", "--porcelain");
+		List<string> output = [
+			.. commitChanges
+			.Where(line => line.StartsWith('R') || line.StartsWith('D') || line.StartsWith('A'))
+			.Select(line => line.Split('\t')[1]),
+			.. localChanges
+			.Select(x => x.TrimStart())
+			.Where(line => line.StartsWith('R') || line.StartsWith('D') || line.StartsWith("A ", StringComparison.Ordinal) || line.StartsWith("??"))
+			.Select(line => line.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)[1])
+		];
+		return output.Where(line => line.StartsWith(lookupPath));
+	}
+
+	private string GetDefaultBranch()
+	{
+		if (!Capture(true, "git", "merge-base", "-a", "HEAD", "main").StartsWith("fatal", StringComparison.InvariantCulture))
+			return "main";
+		if (!Capture(true, "git", "merge-base", "-a", "HEAD", "master").StartsWith("fatal", StringComparison.InvariantCulture))
+			return "master";
+		return Capture("git", "symbolic-ref", "refs/remotes/origin/HEAD").Split('/').Last();
+	}
+}