Marginalia.Tool 0.1.0

Marginalia

Turn a codebase into a single Markdown table you can write in the margins of.

Marginalia scans a .NET project and writes a tidy Markdown inventory of every type it contains — classes, interfaces, enums, structs, records and delegates — with an empty Notes column waiting to be filled in.

The document is the point. A senior engineer runs the tool, opens the file, and writes a short refactoring note next to each type. The result is a ready-made checklist a junior developer can work straight down: one type, one instruction, one change at a time.

marginalia ./src/MyApp

The file is written, copied to your clipboard, and opened in VS Code — ready to annotate.

Why

Refactoring guidance usually lives in someone's head or scattered across review comments. Marginalia gives it a home:

1. Run it. Point Marginalia at a folder (or a project/solution file, whose folder is scanned).
2. Annotate it. Fill in the Notes column — "split this," "this belongs in the domain layer," "make this internal," "delete — dead code."
3. Hand it off. A junior developer follows the table top to bottom and makes the changes.

The generated file is plain, unremarkable Markdown with no tool fingerprints, so the annotated version reads as a document a person wrote.

Install

Marginalia is a .NET global tool.

dotnet tool install --global Marginalia.Tool

Update or remove it later with:

dotnet tool update --global Marginalia.Tool
dotnet tool uninstall --global Marginalia.Tool

Requires the .NET 10 runtime or newer.

Usage

marginalia [path] [options]

Examples

# Scan the current directory
marginalia

# Scan a specific project and choose the output file
marginalia ./src/MyApp --output docs/refactoring.md

# Scan a solution, give it a title, and skip the side effects (handy for CI)
marginalia MyApp.sln --title "MyApp — Refactoring Plan" --no-open --no-clipboard

Example output

Scanning a small project produces something like:

# MyApp

| Type | Kind | Namespace | File | Notes |
| --- | --- | --- | --- | --- |
| `OrderController` | class | `MyApp.Api` | `Api/OrderController.cs` |  |
| `IOrderService` | interface | `MyApp.Core` | `Core/IOrderService.cs` |  |
| `OrderService` | class | `MyApp.Core` | `Core/OrderService.cs` |  |
| `OrderStatus` | enum | `MyApp.Core` | `Core/OrderStatus.cs` |  |

After a quick pass, the Notes column carries the plan:

| Type | Kind | Namespace | File | Notes |
| --- | --- | --- | --- | --- |
| `OrderController` | class | `MyApp.Api` | `Api/OrderController.cs` | Thin out — move validation into the service. |
| `IOrderService` | interface | `MyApp.Core` | `Core/IOrderService.cs` | Good. |
| `OrderService` | class | `MyApp.Core` | `Core/OrderService.cs` | Split: pricing vs. fulfilment are two responsibilities. |
| `OrderStatus` | enum | `MyApp.Core` | `Core/OrderStatus.cs` | Add `Cancelled`. |

How it works

Marginalia parses each .cs file with the Roslyn syntax model — no compilation, no project loading — so it is fast and works on code that does not build. Point it at a directory and it scans that whole tree; point it at a .csproj or .sln/.slnx file and it scans the folder that contains it. It walks the tree, skipping bin, obj, generated files, and other noise, then renders the results into a single sorted table.

Nested types are reported with their containing type (Outer.Inner), generic types keep their parameters (Repository<T>), and types in the global namespace are grouped under (global).

Configuration

Sensible defaults are built in: bin, obj, .git, .vs, .vscode, .idea, node_modules, artifacts and TestResults directories are skipped, along with .g.cs, .g.i.cs and .Designer.cs generated files. These live in ScanOptions, supplied through the standard options pattern (IOptions<ScanOptions>).

Building from source

git clone https://github.com/quinntyne/Marginalia.git
cd Marginalia
dotnet build
dotnet test

Run the tool against your own code without installing it:

dotnet run --project src/Marginalia -- ./path/to/scan

Package it as a tool locally:

dotnet pack -c Release
dotnet tool install --global --add-source ./src/Marginalia/bin/Release Marginalia.Tool

Contributing

Contributions are welcome — see CONTRIBUTING.md. By participating you agree to abide by the Code of Conduct.

Security

Found a vulnerability? Please follow the process in SECURITY.md.

License

Marginalia is released under the MIT License.