Rearrange various API surfaces related to pathfinding.

The existing APIs surfaces for pathfinding are in a wonky shape. We rearrange various responsibilities to better locations and simplify some abstractions that aren't providing value.

- IPathSearch, BasePathSearch and PathSearch are combined into only PathSearch. Its role is now to run a search space over a graph, maintaining the open queue and evaluating the provided heuristic function. The builder-like methods (WithHeuristic, Reverse, FromPoint, etc) are removed in favour of optional parameters in static creation methods. This removes confusion between the builder-aspect and the search function itself. It also becomes responsible for applying the heuristic weight to the heuristic. This fixes an issue where an externally provided heuristic ignored the weighting adjustment, as previously the weight was baked into the default heuristic only.
- Reduce the IGraph interface to the concepts of nodes and edges. Make it non-generic as it is specifically for pathfinding, and rename to IPathGraph accordingly. This is sufficient for a PathSearch to perform a search over any given IGraph. The various customization options are concrete properties of PathGraph only.
- PathFinder does not need to deal with disposal of the search/graph, that is the caller's responsibility.
- Remove CustomBlock from PathGraph as it was unused.
- Remove FindUnitPathToRange as it was unused.
- Use PathFinder.NoPath as the single helper to represent no/empty paths.

OpenRA.Mods.Common/Pathfinder/IPathGraph.cs

@@ -0,0 +1,68 @@
+#region Copyright & License Information
+/*
+ * Copyright 2007-2021 The OpenRA Developers (see AUTHORS)
+ * This file is part of OpenRA, which is free software. It is made
+ * available to you under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version. For more
+ * information, see COPYING.
+ */
+#endregion
+
+using System;
+using System.Collections.Generic;
+
+namespace OpenRA.Mods.Common.Pathfinder
+{
+	/// <summary>
+	/// Represents a pathfinding graph with nodes and edges.
+	/// Nodes are represented as cells, and pathfinding information
+	/// in the form of <see cref="CellInfo"/> is attached to each one.
+	/// </summary>
+	public interface IPathGraph : IDisposable
+	{
+		/// <summary>
+		/// Given a source node, returns connections to all reachable destination nodes with their cost.
+		/// </summary>
+		List<GraphConnection> GetConnections(CPos source);
+
+		/// <summary>
+		/// Gets or sets the pathfinding information for a given node.
+		/// </summary>
+		CellInfo this[CPos node] { get; set; }
+	}
+
+	/// <summary>
+	/// Represents part of an edge in a graph, giving the cost to traverse to a node.
+	/// </summary>
+	public readonly struct GraphConnection
+	{
+		public static readonly CostComparer ConnectionCostComparer = CostComparer.Instance;
+
+		public sealed class CostComparer : IComparer<GraphConnection>
+		{
+			public static readonly CostComparer Instance = new CostComparer();
+			CostComparer() { }
+			public int Compare(GraphConnection x, GraphConnection y)
+			{
+				return x.Cost.CompareTo(y.Cost);
+			}
+		}
+
+		public readonly CPos Destination;
+		public readonly int Cost;
+
+		public GraphConnection(CPos destination, int cost)
+		{
+			if (cost < 0)
+				throw new ArgumentOutOfRangeException(nameof(cost), $"{nameof(cost)} cannot be negative");
+			if (cost == PathGraph.PathCostForInvalidPath)
+				throw new ArgumentOutOfRangeException(nameof(cost), $"{nameof(cost)} cannot be used for an unreachable path");
+
+			Destination = destination;
+			Cost = cost;
+		}
+
+		public override string ToString() => $"-> {Destination} = {Cost}";
+	}
+}