NW.LibrarySurfaceArea 1.0.0

NW.LibrarySurfaceArea

NW.LibrarySurfaceArea is a library that evaluates the API Surface Area of a compiled .NET library (.dll).

Getting Started

If /home/nw.librarysurfacearea is the folder in which the .nupkg file is located, you can install it using this command:

dotnet add package NW.LibrarySurfaceArea --source /home/nw.librarysurfacearea

How API Surface Area Works

The API Surface Area is a metric that evaluates the breadth, shape, and cognitive load of an API's public-facing boundary. While traditional complexity metrics (like Cyclomatic Complexity or Lines of Code) measure how difficult code is to write or maintain internally, the API Surface Area measures how difficult a library is to learn, consume, and integrate safely.

The need behind NW.LibrarySurfaceArea is to have a heuristic way to measure the growth of a .NET library during its lifecycle and the ability to compare multiple libraries (assuming they are developed with the same coding style).

This metric is heuristic because, by definition, it is useful for estimating something but does not measure it perfectly.

To calculate the LSAScore, the number of public interfaces is added to the total number of accountable methods across all visible classes. Accountable methods include externally visible public and protected methods, while excluding inherited object members, property getters/setters and standard boilerplate (such as ToString or Equals).

While classes themselves are tracked in the resulting Summary object, only their accountable methods contribute to the final score, effectively allowing pure data structures (like DTOs) to add zero method weight to the API complexity score.

API Surface Area In Action

To calculate the API Surface Area, instantiate the LSAEvaluator object and invoke its Evaluate method against a locally stored .NET library assembly (.dll):

using System;
using NW.LibrarySurfaceArea;
using NW.LibrarySurfaceArea.Shared;

string name = "NW.NGramTextClassification";
string filePath = "/home/nw.librarysurfacearea/NW.NGramTextClassification.dll";

ILSAEvaluator lsaEvaluator = new LSAEvaluator();
Summary summary = lsaEvaluator.Evaluate(name, filePath);

string formatted = lsaEvaluator.Format(summary, true);
Console.WriteLine(formatted);

The output of the evaluation task will be a Summary object, which would look like the JSON payload example below when serialized:

{
  "TargetLibrary": {
    "Name": "NW.NGramTextClassification",
    "FilePath": "/home/nw.librarysurfacearea/NW.NGramTextClassification.dll"
  },
  "TargetClasses": [],
  "TargetInterfaces": [],
  "TargetClassCount": 25,
  "TargetInterfaceCount": 9,
  "TargetMethodCount": 31,
  "LSAScore": 40,
  "Version": "1.0.0"
}

LSAScore represents the API Surface Area of the .NET library called NW.NGramTextClassification.dll, while Version is the version of NW.LibrarySurfaceArea that produced the summary.

You can also run the evaluation process for a collection of .NET libraries using the EvaluateAll method:

...
List<(string Name, string FilePath)> libraries = new()
{
    (
        "NW.NGramTextClassification", 
        "/home/nw.librarysurfacearea/NW.NGramTextClassification.dll"
    ),
    (
        "NW.UnivariateForecasting", 
        "/home/nw.librarysurfacearea/NW.UnivariateForecasting.dll"
    )
};

ILSAEvaluator lsaEvaluator = new LSAEvaluator();
List<Summary> summaries = lsaEvaluator.EvaluateAll(libraries);

foreach (Summary summary in summaries)
{
    string formattedSummary = 
        lsaEvaluator.Format(summary: summary, compact: true);
    Console.WriteLine(formattedSummary);
}

When compact is true, the class and interface detail collections are omitted from the formatted output, while their aggregate counts remain available. This makes the output suitable for logs, automated comparisons, build reports, or historical measurements. To include the detailed lists of classes, methods, and interfaces, format the summary with compact set to false.

License

MIT