Optionally, fetch source code information from a definitive source

[SteveGilham]

Allow an opt in --source-style to permit linking to a selection of (in preference order)

• Exact source & commit from symbols + source link, but for a limited subset of types
• Exact source name from symbols, but for a limited subset of types
• Heuristic .cs source name, for all types

Testing is the obvious generalization of that for the existing --source option.

[ProphetLamb]

Ive developed two tools which combined allow extraction of exact information of the assembly, from the compilation image or pdb. This works with embedded sources and any sourcelink. For example, in the following project https://github.com/ProphetLamb/Surreal.Net/tree/master/src/Abstractions
Have the file src/Abstractions/Database.cs which defines IDatabase and IDatabase\u00601. This currently is not referenced correctly. Given the pdb, the tools generate the following output:

[
  {
    "type": "SurrealDB.Abstractions.IDatabase\u00601",
    "link": "https://raw.githubusercontent.com/ProphetLamb/Surreal.Net/9050c906117c795ca385fd52b75062771a2a8816/src/Abstractions/Database.cs",
    "path": "src/Abstractions/Database.cs",
    "start": 6,
    "end": 141
  },
  {
    "type": "SurrealDB.Abstractions.IDatabase",
    "link": "https://raw.githubusercontent.com/ProphetLamb/Surreal.Net/9050c906117c795ca385fd52b75062771a2a8816/src/Abstractions/Database.cs",
    "path": "src/Abstractions/Database.cs",
    "start": 141,
    "end": 295
  }
]

• typename is the qualified name of the type
• link is the preferred sourcelink, or file reference (if embedded).
• start is the first line containing the class (used for the GitHub references #L123.
• end is the last line containing the class.

For each file, a partial type is defined in a separate entry is written.

I am going to fork and modify XmlDocMarkdown to accept the above symbols.json.

I intend the tools for CI, so I was very uncreative with the naming ^^:

dotnet tool install --global SourceLinkExtract
dotnet tool install --global SourceSymbolMapper

extract test.pdb meta.json out
mapper meta.json out symbols.json 

(Note: there will be messages about CompilationUnit being an unknown type, for constructing a typename, but that is ok, since it doesn't influence the logic)
(Note: out contains the sourcecode form either embedded or sourcelink)

The issue with using debug symbols for instructions (SequencePoints) to map type is simply that types without instruction are invisble; this includes all interfaces, marker classes, and many abstract types. We dont have this issue with this approach.

See:

• https://github.com/ProphetLamb/SourceLinkExtract
• https://github.com/ProphetLamb/SourceSymbolMapper