Plat 0.2.0

Plat

Plat is a .NET 8 global tool that scans a git repository for .NET projects and Angular applications and libraries and writes a deterministic Markdown catalog documenting each project's location, kind, ownership, and boundaries.

Facts that can be inferred from disk (project kind, path, target framework, Angular version) are scanned automatically. The things only a human knows — who owns a project and where its responsibilities begin and end — are author-declared in a small plat.json file committed next to each project and merged into the catalog.

The catalog is meant to be committed and kept honest in CI with plat check.

Install

Plat ships as a .NET global tool on NuGet. Requires the .NET 8 runtime.

dotnet tool install --global Plat

Or into a project-scoped tool manifest:

dotnet new tool-manifest       # once per repo
dotnet tool install Plat

Usage

# Scan the enclosing git repository and write CATALOG.md at its root
plat catalog

# Scan a specific repository and choose the output path
plat catalog --repo /path/to/repo --output docs/PROJECTS.md

# Fail CI if the committed catalog is out of date (exit 1 on drift)
plat check

# Show what changed since the catalog was generated (exit 1 if it differs)
plat diff

All commands accept --repo <path> (defaults to the enclosing git repository, else the current directory), --output <path> (relative to the repository root, default CATALOG.md), and --verbosity <level>.

What it discovers

• .NET projects — every .csproj, .fsproj, and .vbproj, with its target framework and kind (Library, Console, or Web). Test projects (xunit/NUnit/MSTest or <IsTestProject>true</IsTestProject>) and build output (bin, obj, node_modules) are skipped.
• Angular applications and libraries — every angular.json workspace entry whose projectType is application or library, plus standalone ng-package.json libraries. Non-Angular workspace entries (e.g. a Playwright/e2e project), node_modules, and dist are skipped.

Declaring ownership and boundaries

Drop a plat.json into any project's directory:

{
  "team": "Platform",
  "owner": "Jane Doe",
  "contact": "platform@acme.com",
  "boundary": "Authentication and authorization services.",
  "dependsOn": ["Acme.Core"],
  "tags": ["backend", "security"]
}

Every field is optional. Scanning never overwrites these values, and they never override scanned facts — the two are kept strictly separate. A malformed plat.json fails the run with exit code 2 so mistakes are caught, not silently ignored.

CI

- run: dotnet tool install --global Plat
- run: plat check        # exits 1 if CATALOG.md is stale

Development

Requires the .NET 8 SDK (pinned in global.json).

dotnet build
dotnet test

See CONTRIBUTING.md for the ATDD development loop and code style, and docs/specs for the L1/L2 requirements.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and follow our Code of Conduct.

Security

To report a security vulnerability, follow the process in SECURITY.md. Do not open public issues for security reports.

License

MIT — see LICENSE.