Add use-mapping-file to coverlet.console

Adds the option --use-mapping-file to coverlet.console that allows the caller to specify a custom source mapping file to use. This is used to then maps paths located in an assembly's debug symbols to local path when collecting coverage.

Author: jborean93

Documentation/GlobalTool.md

@@ -37,6 +37,7 @@ Options:
  --use-source-link Specifies whether to use SourceLink URIs in place of file system paths.
  --does-not-return-attribute Attributes that mark methods that do not return.
  --exclude-assemblies-without-sources Specifies behaviour of heuristic to ignore assemblies with missing source documents.
+ --use-mapping-file Specifies the path to a SourceRootsMappings file.
  --version Show version information
  -?, -h, --help Show help and usage information
 ```
@@ -237,6 +238,18 @@ You can also include coverage of the test assembly itself by specifying the `--i
 
 Coverlet supports [SourceLink](https://github.com/dotnet/sourcelink) custom debug information contained in PDBs. When you specify the `--use-source-link` flag, Coverlet will generate results that contain the URL to the source files in your source control instead of local file paths.
 
+## Path Mappings
+
+Coverlet has the ability to map the paths contained inside the debug sources into a local path where the source is currently located using the option `--source-mapping-file`. This is useful if the source was built using a deterministic build which sets the path to `/_/` or if it was built on a different host where the source is located in a different path.
+
+The value for `--source-mapping-file` should be a file with each line being in the format `|path to map to=path in debug symbol`. For example to map the local checkout of a project `C:\git\coverlet` to project that was built with `<Deterministic>true</Deterministic>` which sets the sources to `/_/*` the following line must be in the mapping file.
+
+```
+|C:\git\coverlet\=/_/
+```
+
+During coverage collection, Coverlet will translate any path that starts with `/_/` to `C:\git\coverlet\` allowing the collector to find the source file.
+
 ## Exit Codes
 
 Coverlet outputs specific exit codes to better support build automation systems for determining the kind of failure so the appropriate action can be taken.

src/coverlet.console/Program.cs

@@ -48,6 +48,7 @@ static int Main(string[] args)
  var useSourceLink = new Option<bool>("--use-source-link", "Specifies whether to use SourceLink URIs in place of file system paths.") { Arity = ArgumentArity.Zero };
  var doesNotReturnAttributes = new Option<string[]>("--does-not-return-attribute", "Attributes that mark methods that do not return") { Arity = ArgumentArity.ZeroOrMore };
  var excludeAssembliesWithoutSources = new Option<string>("--exclude-assemblies-without-sources", "Specifies behaviour of heuristic to ignore assemblies with missing source documents.") { Arity = ArgumentArity.ZeroOrOne };
+ var sourceMappingFile = new Option<string>("--source-mapping-file", "Specifies the path to a SourceRootsMappings file.") { Arity = ArgumentArity.ZeroOrOne };
 
  RootCommand rootCommand = new()
  {
@@ -71,7 +72,8 @@ static int Main(string[] args)
  mergeWith,
  useSourceLink,
  doesNotReturnAttributes,
- excludeAssembliesWithoutSources
+ excludeAssembliesWithoutSources,
+ sourceMappingFile
  };
 
  rootCommand.Description = "Cross platform .NET Core code coverage tool";
@@ -99,6 +101,7 @@ static int Main(string[] args)
  bool useSourceLinkValue = context.ParseResult.GetValueForOption(useSourceLink);
  string[] doesNotReturnAttributesValue = context.ParseResult.GetValueForOption(doesNotReturnAttributes);
  string excludeAssembliesWithoutSourcesValue = context.ParseResult.GetValueForOption(excludeAssembliesWithoutSources);
+ string sourceMappingFileValue = context.ParseResult.GetValueForOption(sourceMappingFile);
 
  if (string.IsNullOrEmpty(moduleOrAppDirectoryValue) || string.IsNullOrWhiteSpace(moduleOrAppDirectoryValue))
  throw new ArgumentException("No test assembly or application directory specified.");
@@ -123,7 +126,8 @@ static int Main(string[] args)
  mergeWithValue,
  useSourceLinkValue,
  doesNotReturnAttributesValue,
- excludeAssembliesWithoutSourcesValue);
+ excludeAssembliesWithoutSourcesValue,
+ sourceMappingFileValue);
  context.ExitCode = taskStatus;
 
  });
@@ -149,7 +153,8 @@ private static Task<int> HandleCommand(string moduleOrAppDirectory,
  string mergeWith,
  bool useSourceLink,
  string[] doesNotReturnAttributes,
- string excludeAssembliesWithoutSources
+ string excludeAssembliesWithoutSources,
+ string sourceMappingFile
  )
  {
 
@@ -160,7 +165,7 @@ string excludeAssembliesWithoutSources
  serviceCollection.AddTransient<ILogger, ConsoleLogger>();
  // We need to keep singleton/static semantics
  serviceCollection.AddSingleton<IInstrumentationHelper, InstrumentationHelper>();
- serviceCollection.AddSingleton<ISourceRootTranslator, SourceRootTranslator>(provider => new SourceRootTranslator(provider.GetRequiredService<ILogger>(), provider.GetRequiredService<IFileSystem>()));
+ serviceCollection.AddSingleton<ISourceRootTranslator, SourceRootTranslator>(provider => new SourceRootTranslator(sourceMappingFile, provider.GetRequiredService<ILogger>(), provider.GetRequiredService<IFileSystem>()));
  serviceCollection.AddSingleton<ICecilSymbolHelper, CecilSymbolHelper>();
 
  ServiceProvider serviceProvider = serviceCollection.BuildServiceProvider();

src/coverlet.core/Helpers/SourceRootTranslator.cs

@@ -22,7 +22,6 @@ internal class SourceRootTranslator : ISourceRootTranslator
  private readonly IFileSystem _fileSystem;
  private readonly Dictionary<string, List<SourceRootMapping>> _sourceRootMapping;
  private readonly Dictionary<string, List<string>> _sourceToDeterministicPathMapping;
- private readonly string _mappingFileName;
  private Dictionary<string, string> _resolutionCacheFiles;
 
  public SourceRootTranslator(ILogger logger, IFileSystem fileSystem)
@@ -32,6 +31,13 @@ public SourceRootTranslator(ILogger logger, IFileSystem fileSystem)
  _sourceRootMapping = new Dictionary<string, List<SourceRootMapping>>();
  }
 
+ public SourceRootTranslator(string sourceMappingFile, ILogger logger, IFileSystem fileSystem)
+ {
+ _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+ _fileSystem = fileSystem ?? throw new ArgumentNullException(nameof(fileSystem));
+ _sourceRootMapping = LoadSourceRootMapping(sourceMappingFile);
+ }
+
  public SourceRootTranslator(string moduleTestPath, ILogger logger, IFileSystem fileSystem, IAssemblyAdapter assemblyAdapter)
  {
  _logger = logger ?? throw new ArgumentNullException(nameof(logger));
@@ -46,9 +52,9 @@ public SourceRootTranslator(string moduleTestPath, ILogger logger, IFileSystem f
  }
 
  string assemblyName = assemblyAdapter.GetAssemblyName(moduleTestPath);
- _mappingFileName = $"CoverletSourceRootsMapping_{assemblyName}";
+ string mappingFileName = $"CoverletSourceRootsMapping_{assemblyName}";
 
- _sourceRootMapping = LoadSourceRootMapping(Path.GetDirectoryName(moduleTestPath));
+ _sourceRootMapping = LoadSourceRootMapping(Path.Combine(Path.GetDirectoryName(moduleTestPath), mappingFileName));
  _sourceToDeterministicPathMapping = LoadSourceToDeterministicPathMapping(_sourceRootMapping);
  }
 
@@ -75,11 +81,10 @@ private static Dictionary<string, List<string>> LoadSourceToDeterministicPathMap
  return sourceToDeterministicPathMapping;
  }
 
- private Dictionary<string, List<SourceRootMapping>> LoadSourceRootMapping(string directory)
+ private Dictionary<string, List<SourceRootMapping>> LoadSourceRootMapping(string mappingFilePath)
  {
  var mapping = new Dictionary<string, List<SourceRootMapping>>();
 
- string mappingFilePath = Path.Combine(directory, _mappingFileName);
  if (!_fileSystem.Exists(mappingFilePath))
  {
  return mapping;

test/coverlet.core.tests/Helpers/SourceRootTranslatorTests.cs

@@ -51,6 +51,25 @@ public void TranslatePathRoot_Success()
  Assert.Equal(@"C:\git\coverlet\", translator.ResolvePathRoot("/_/")[0].OriginalPath);
  }
 
+ [ConditionalFact]
+ [SkipOnOS(OS.Linux, "Windows path format only")]
+ [SkipOnOS(OS.MacOS, "Windows path format only")]
+ public void TranslateWithDirectFile_Success()
+ {
+ var logger = new Mock<ILogger>();
+ var assemblyAdapter = new Mock<IAssemblyAdapter>();
+ assemblyAdapter.Setup(x => x.GetAssemblyName(It.IsAny<string>())).Returns("testLib");
+ var fileSystem = new Mock<IFileSystem>();
+ fileSystem.Setup(f => f.Exists(It.IsAny<string>())).Returns((string p) =>
+ {
+ if (p == "testLib.dll" || p == @"C:\git\coverlet\src\coverlet.core\obj\Debug\netstandard2.0\coverlet.core.pdb" || p == "CoverletSourceRootsMapping_testLib") return true;
+ return false;
+ });
+ fileSystem.Setup(f => f.ReadAllLines(It.IsAny<string>())).Returns(File.ReadAllLines(@"TestAssets/CoverletSourceRootsMappingTest"));
+ var translator = new SourceRootTranslator("CoverletSourceRootsMapping_testLib", logger.Object, fileSystem.Object);
+ Assert.Equal(@"C:\git\coverlet\", translator.ResolvePathRoot("/_/")[0].OriginalPath);
+ }
+
  [Fact]
  public void Translate_EmptyFile()
  {