Declare every code as a BuildDiagnosticDescriptor item

CHANGELOG.md

@@ -11,6 +11,7 @@ All notable changes to this project are documented here. The format follows [Kee
 ### Added
 
 - Every warning and error links to its section of the [code reference](./docs/reference/codes.md) (`HelpLink`, shown by the terminal logger and IDEs). `MSKit_CodesHelpBaseUrl` points the links at another copy of the page.
+- A machine-readable catalog of the codes: every part declares each code it reports as a `BuildDiagnosticDescriptor` item (`Title`, `MessageFormat`, `Description`, `Category`, `DefaultSeverity`, `HelpLink`) in its own `diagnostic.descriptors.props`, so a tool can read them with `dotnet msbuild -getItem:BuildDiagnosticDescriptor` and tell the owning part from the item's `DefiningProjectFullPath`. Each section of the [code reference](./docs/reference/codes.md) now opens with the code's title. See the [diagnostic catalog](./docs/reference/diagnostic-catalog.md).
 - `MSKit_DefaultPackageIconUrl`: when the kit packs its own icon, this URL is also written as `PackageIconUrl`, so clients that predate embedded icons show it; nuget.org keeps showing the embedded one. Empty by default; an owner sets it in its owner layer. `MSKITPKG008` now reports only a `PackageIconUrl` the project sets itself. See [docs/packaging.md](./docs/packaging.md#package-metadata).
 - `manager/`: the first build of `mskit-manager`, the `DragoAnt.MSBuildKit.Manager` .NET tool (`net8.0`, `net10.0`, `RollForward=Major`) that will install, update and migrate the kit. This build has one command, `status [--json]`, which prints the tool version; the logo goes to stderr, only on a terminal and never with `--no-logo`, so `--json` output always parses. Each run writes a log under `<system temp>/mskit-manager/logs/`, named after the command, newest 20 kept. Not published yet.
 

CONTRIBUTING.md

@@ -41,7 +41,7 @@ Both scripts restore into a global-packages folder of their own, `dist/selftest-
 ## Changing the kit
 
 - A new property defaults with `Condition="'$(Name)'==''"`, so a consumer's value always wins, and gets a row in [docs/reference/properties.md](./docs/reference/properties.md) plus a mention on its topic page.
-- A new check gets an `MSKIT<AREA><nnn>` code with no separator (a shipped code is never renumbered or reused), a `HelpLink="$(MSKit_CodesHelpBaseUrl)#<code, lower case>"`, a message that says how to fix it, a section in [docs/reference/codes.md](./docs/reference/codes.md) headed by the code, a fixture that triggers it and a line in `tests/run.sh`.
+- A new check gets an `MSKIT<AREA><nnn>` code with no separator (a shipped code is never renumbered or reused), a `HelpLink="$(MSKit_CodesHelpBaseUrl)#<code, lower case>"`, a message that says how to fix it, a section in [docs/reference/codes.md](./docs/reference/codes.md) headed by the code, a `BuildDiagnosticDescriptor` item in its part's `diagnostic.descriptors.props` ([diagnostic catalog](./docs/reference/diagnostic-catalog.md)), a fixture that triggers it and a line in `tests/run.sh`.
 - `sh tools/docs-check.sh` fails on a property, item or code without its reference entry, on a name the docs mention that the kit lacks, and on a broken relative link; `--list properties|items|codes` prints the kit's inventory with the file and line of each.
 - The README stays short: key features, install, links. Detail goes to the topic page in `docs/`.
 - A new part needs a line in `kit/.toolkit/kit.parts` and its `init.props` / `init.targets` imports in the entry points.

docs/README.md

@@ -19,6 +19,7 @@ Read in this order; each page stands on its own, so jump to the one you need.
 | 13 | [Troubleshooting](./troubleshooting.md) | fix a failing build or update |
 | 14 | [Code reference](./reference/codes.md) | look up any warning or error the kit reports |
 | 15 | [Property reference](./reference/properties.md) | look up any property the kit sets or reads |
-| 16 | [Migrating from MSBuild.Routine](./migrating-from-msbuild-routine.md) | move a repository off the older submodule |
+| 16 | [Diagnostic catalog](./reference/diagnostic-catalog.md) | read the kit's codes from a tool, or add your own to the catalog |
+| 17 | [Migrating from MSBuild.Routine](./migrating-from-msbuild-routine.md) | move a repository off the older submodule |
 
 Contributing to the kit itself: [CONTRIBUTING.md](../CONTRIBUTING.md).

docs/parts.md

@@ -27,7 +27,7 @@ The kit is split into parts, one folder each under `.toolkit/msbuild/` (`DragoAn
 
 | Phase | Order |
 | --- | --- |
-| props | `MSKit_BeforeInitProps` → owner layer (`init.company.props`) → Core → Vcs.GitHub → Locals.Compile → Locals.DirectorySecrets → Locals.Secrets → Project.RoslynComponent → Project.CodeFixer → Project.CodeAnalyzer → Project.SourceGenerator → TfmConstants → Trunk → Packaging → Testing → Testing.XUnit.v3 → EF → Trunk `init.last.props` (version engine) → `MSKit_AfterInitProps` |
+| props | `MSKit_BeforeInitProps` → owner layer (`init.company.props`) → Core → Vcs.GitHub → Locals.Compile → Locals.DirectorySecrets → Locals.Secrets → Project.RoslynComponent → Project.CodeFixer → Project.CodeAnalyzer → Project.SourceGenerator → TfmConstants → Trunk → Packaging → Testing → Testing.XUnit.v3 → EF → PackageAsProj → Trunk `init.last.props` (version engine) → `MSKit_AfterInitProps` |
 | targets | `MSKit_BeforeInitTargets` → TfmConstants → owner layer (`init.company.targets`) → Core → Locals.* → Project.CodeAnalyzer → Project.SourceGenerator → Trunk → Packaging → Testing → Testing.XUnit.v3 → the `init.last.targets` of Trunk, Project.RoslynComponent, Testing.XUnit.v3, Testing, Project.CodeAnalyzer, PrivateAssets, PackageAsProj, ProjMetadata → every part's `audit/*.targets` → `MSKit_AfterInitTargets` |
 
 In the props phase a default is written as `<X Condition="'$(X)'==''">`, so the **first** writer wins: a value you set in `Directory.Build.props` above the kit import beats the owner layer, which beats the parts. The exceptions are the owner layer's `ManufacturerName`, `FullManufacturerName` and `NoWarn`, which it sets unconditionally ([Customizing](./customizing.md#the-owner-layer)). The csproj body runs after all props, so a value set there wins too, except for the few properties the kit reads in the props phase (the test-project switches, `TargetFramework` detection); those pages say so. How to hook in your own files: [Customizing](./customizing.md).