LegacyLibAnalyzer 0.1.0

LegacyLibAnalyzer

Rule-agnostic MSBuild analyzer for NuGet package references.

LegacyLibAnalyzer reports matches as MSBuild errors/warnings/messages and can optionally write a SARIF report. The package does not require built-in defaults; define your own rules for the packages and versions your organization wants to flag.

Install

<PackageReference Include="LegacyLibAnalyzer" Version="0.1.0" PrivateAssets="all" />

Define rules

<ItemGroup>
  
  <LegacyLibraryRule Include="Moq"
                 Code="LegacyLib-Moq"
                 Severity="Error"
                 Message="Moq is forbidden; use NSubstitute." />

  <LegacyLibraryRule Include="xUnitV1"
                 Code="LegacyLib-xUnitV1"
                 IncludePattern="xunit*"
                 ExcludePattern="xunit.v3*"
                 MaxVersion="1"
                 Severity="Error"
                 Message="xUnit v1 is legacy; upgrade to xunit.v3." />
  <LegacyLibraryRule Include="xUnitV2"
                 Code="LegacyLib-xUnitV2"
                 IncludePattern="xunit*"
                 ExcludePattern="xunit.v3*"
                 MinVersion="2"
                 MaxVersion="2"
                 Severity="Warning"
                 Message="xUnit v2 is legacy; upgrade to xunit.v3." />
</ItemGroup>

Note: xunit.v3 is a separate package name (not just "version 3" of xunit), and it has since released its own major versions 3.x and 4.x. Don't confuse the package name with its version number when writing MinVersion/MaxVersion bounds.

Metadata:

• Include (required by MSBuild): identity/key of the rule, used to merge/override rules. In the common case this is simply the package name (e.g. Include="Moq") and doubles as the match value, so you don't need to set IncludePattern separately.
• Code: error/warning code reported to MSBuild and used as the SARIF rule id.
• IncludePattern (optional): the actual value matched against resolved package names. Can be a wildcard pattern (*/?, e.g. xunit*). Only needed when it differs from Include (for example, to keep a stable Include key for overrides while matching a pattern).
• Severity: Error, Warning or Note (defaults to Warning).
• Message: the message shown to the user.
• MinVersion / MaxVersion (optional): inclusive allowed version bounds. A partial version (e.g. 2) represents the whole range it covers: as MinVersion it means "2.0.0.0 or higher", as MaxVersion it means "any 2.x.x.x version" (so 2, 2.4 and 2.4.1 are all allowed by MaxVersion="2"). Pre-release versions are matched by their release version, so 2.2.0-rc1 is treated as 2.2.0.
• ExcludePattern (optional): a wildcard pattern of package names to still exclude, even if they match IncludePattern.

Two ways to use this package

• Directly: reference LegacyLibAnalyzer and declare <LegacyLibraryRule> items in your own .csproj, as shown above. Good for a single repo or project-specific policy.
• Via a company package: create a thin internal package (e.g. MyCompany.LegacyLibAnalyzer) that references LegacyLibAnalyzer (without PrivateAssets="all") and ships your organization's <LegacyLibraryRule> items in its own buildTransitive\*.targets file. Consumers then only reference your company package to get the shared policy automatically, and can still override or soften individual rules locally by declaring a <LegacyLibraryRule> with the same Include key. See the root repository README for the full walkthrough and an override example.

Optional SARIF output

<PropertyGroup>
  <LegacyLibGenerateSarif>true</LegacyLibGenerateSarif>
  <LegacyLibSarifOutputPath>$(MSBuildProjectDirectory)\legacylib.sarif</LegacyLibSarifOutputPath>
</PropertyGroup>

Minimal SARIF example:

{
  "version": "2.1.0",
  "runs": [
    {
      "tool": { "driver": { "name": "LegacyLibAnalyzer" } },
      "results": [
        { "ruleId": "LegacyLib-Moq", "level": "error", "message": { "text": "Moq is forbidden; use NSubstitute." } }
      ]
    }
  ]
}

Disable

<LegacyLibAnalyzerEnabled>false</LegacyLibAnalyzerEnabled>