Documentation section: Project
Contributing
This page covers the repository layout and the day-to-day commands for working on
Purview.Aspire.ResourceKit. It is aimed at contributors, not consumers.
Repository layout
Section titled “Repository layout”src/src/ResourceKit— runtime APIs consumed by AppHost projects (the packable project).src/src/SourceGeneration— the Roslyn incremental generator, analyzers, suppressor, and attributes.src/src/SourceGeneration.CodeFixes— the SG0020 IDE code fix provider.src/src/Example.*— sample Aspire applications:Example.Pre17.AppHost/Example.Pre17.ManualAppHost— Aspire 13.6 (Aspire.AppHost.Sdk,AddProject<T>) generated and manual patterns.Example.AppHost17/Example.ManualAppHost17— Aspire 17 Project V2 (Microsoft.NET.Sdk,AddDotnetProject) generated and manual patterns.Example.Service/Example.ServiceDefaults— the shared service and constants both families use.
src/tests/*— unit and integration tests for the runtime and the generator.docs/wiki— this documentation suite, one topic folder per area.
The NuGet package is produced from src/src/ResourceKit/ResourceKit.csproj and includes the runtime
APIs plus the analyzer/code-fix assemblies.
Building and testing
Section titled “Building and testing”The repository uses Just recipes (see Justfile). All recipes run from the
repository root.
just build # build the solution (Debug)just test # run all testsjust test-unit # run unit tests only (TUnit [Category=Unit] filter)just restore # restore dependenciesjust pack # produce NuGet packages into ./artifactsjust verify-consumers # pack, assert the package shape, build a real consumer against itjust lint-check # CSharpier formatting checkjust lint-fix # CSharpier formatjust scrub # delete bin/obj and artifacts, stop the build servers, restore from scratchjust version # show the current version from package.jsonjust bump patch # bump package.json's version (major, minor or patch)The shared recipes live in .build/just/ and are copied verbatim from the purview-buildsdk-justfile
skill; the root Justfile sets this repository’s variables and adds its own recipes.
The two example families have different build contracts:
-
The Pre17 examples use
Aspire.AppHost.Sdk13.6.5 withAspireUseCliBundle=false, so they build against the NuGet-delivered DCP and dashboard packages (Aspire.Dashboard.Sdk.<rid>/Aspire.Hosting.Orchestration.<rid>) and need no Aspire CLI. Do not opt them into the bundle: resolving one is a network install performed mid-build, once per AppHost, and two of them race on the NuGet cache and fail with ASPIRE009. -
The Aspire 17 examples use
Microsoft.NET.Sdk+Aspire.Hosting.AppHostandAddDotnetProject. ASPIRE013 makes the Aspire CLI bundle a hard build requirement. Install the pinned CLI before building:Terminal window dotnet tool install --global Aspire.Cli --version "$(cat .config/aspire-version)"aspire setupBoth pipelines do this before the build.
ExampleAppHostTestsguards both contracts and that.config/aspire-versionmatchesDirectory.Packages.props’Aspire17Version.
Testing conventions
Section titled “Testing conventions”- Tests use TUnit (and TUnit.Mocks); do not introduce NUnit, xUnit, or MSTest patterns.
- All tests follow AAA with explicit
// Arrange,// Act,// Assertcomments. - Test names mirror production structure:
{ClassUnderTest}Testsand{SubjectOrMethodUnderTest}_{Scenario}_{Expectation}. - When a method under test accepts a
CancellationToken, pass one and make it the final argument. - The project name sets the tier:
Purview.BuildSdkderivesCategory=Unitfor*.UnitTests. Both PR validation and the release run the full suite, so the tier is a local convenience for the fast loop (just test-unit), not a CI gate. A test added to an integration project runs in CI. Do not narrowBuild:TestFilteror passtest-filterfrom a workflow;PipelineTestsfails if you do.
Test projects:
src/tests/ResourceKit.UnitTests— runtime behavior (host app resources,OptionsHelper, run modes).src/tests/ResourceKit.IntegrationTests— starts the example AppHosts via TUnit.Aspire.src/tests/SourceGeneration.UnitTests— generator diagnostics/severity and attributes.src/tests/SourceGeneration.IntegrationTests— generated source content, caching, diagnostics, suppression, and the SG0020 code fix.src/tests/Repository.UnitTests— asserts things about this repository itself: the conformance of the authored skills inskills/, the architecture policy in.config/architecture-policy.json, thePurview.BuildSdkfeature opt-ins (BuildSdkAdoptionTests), and the example AppHosts’ build contract (no machine-global Aspire CLI).src/tests/SharedTestingInfra— a shared-testing library, referenced rather than executed.
Reports are written to TestResults/.
Documentation
Section titled “Documentation”docs/wiki holds plain Markdown and nothing else — no mkdocs.yml, no theme or plugin list. The site
at https://purview.dev/docs/aspire-resourcekit/ renders these files; adding site configuration here
would be ignored and drift, so don’t “restore” the mkdocs scaffolding (see CHANGELOG.md).
The tree is hierarchical because a folder is a URL segment and a sidebar section:
concepts/Hierarchies.md publishes at /docs/aspire-resourcekit/concepts/hierarchies/.
| Path | Holds |
|---|---|
docs/wiki/*.md |
the landing page and the two pages the catalogue deep-links from a use case |
docs/wiki/concepts/ |
how the model works: hierarchies, lifecycle, enablement, groups, project resources |
docs/wiki/reference/ |
what the generator emits and what every attribute, helper and diagnostic means |
docs/wiki/testing/ |
testing a resource kit |
docs/wiki/project/ |
working on this repository: contributing, releases, versioning, toolchain, skills |
docs/wiki/_Sidebar.md |
the reading order the site’s navigation follows |
docs/wiki/_redirects.yml |
every URL a moved page used to have |
Four rules keep it publishable:
- Three pages stay at the root.
Getting-Started.mdisdocs.rootPagein.config/purview-docs.yml, so it renders the project’s index;Examples.mdandConfiguration-and-Options.mdareuseCases[].docsPagedeep links in that same file, and adocsPageis a single URL segment. Moving either means moving its catalogue reference in the same change. _Sidebar.mdlists every page once, grouped in reading order. A page missing from it has no place in the navigation.- A moved page adds a line to
_redirects.ymlin the same commit. Never delete one: the old URL is in a bookmark somewhere. - A new page is linked from another page, and anything a consumer is told about the package is a
claim
just verify-consumersor the package’s own tests should be able to falsify.
Agent skills and workflows
Section titled “Agent skills and workflows”Skills this repository authors live in skills/<name>/SKILL.md, are named with the
purview-resourcekit prefix, and are validated on every test run by
src/tests/Repository.UnitTests/SkillTests.cs. Add or change one there, not in an agent directory.
.agents/skills/ and .claude/skills/ are the skills CLI’s install locations for skills from other
repositories. They are gitignored, and this repository’s own skills are never installed into them — two
copies would drift. skills-lock.json is committed: it pins what this repository resolved.
npx skills add purview-dev/aspire-resourcekitMaintain the installed set through the skills recipes, which run the skills CLI from the repository root and need no restore:
just skills-install # restore exactly what skills-lock.json records - how a fresh clone startsjust skills-update # re-add every source in skills-lock.json at its latest, then fixjust skills-check # fail if an agent directory other than .agents/skills and .claude/skills existsSkills.Agents in .config/purview-build-sdk.json names the one agent thus allowed (universal,
the .agents/skills store); just skills-fix removes a directory it does not select. These are run
on purpose, never from a build, a git hook or a CI job that commits.
Architecture
Section titled “Architecture”The dependency direction between the three layers is a policy, not a diagram:
.config/architecture-policy.json declares each project’s responsibility and what it may reference, and
src/tests/Repository.UnitTests/ArchitectureTests.cs turns that into a failing build. The rule worth
knowing before you touch a project file: ResourceKit reaches the Roslyn components through
OutputItemType="Analyzer" / ReferenceOutputAssembly="false", and no component may reference the
runtime — a consumer’s compiler loads these assemblies, so dragging Aspire.Hosting into one would
break every consumer’s build.
Widen mayDependOn only as a reviewed policy change; that is the whole point of the file.
Releases
Section titled “Releases”Releases are produced by the shared pipeline when a version bump is merged to main; see
Release Flow. When preparing a release:
- Update
package.json(the authoritative version) and alignglobal.jsonandDirectory.Packages.propswith stable dependency versions. - Move new diagnostics from
src/src/SourceGeneration/AnalyzerReleases.Unshipped.mdintosrc/src/SourceGeneration/AnalyzerReleases.Shipped.mdunder the released version, leaving the unshipped file empty. - Add a
CHANGELOG.mdentry and update the release notes. - Validate with
just lint-checkandjust pipeline-pack-validatebefore merging.
Pull requests
Section titled “Pull requests”Pull requests target main and are validated by .github/workflows/pr.yml, which delegates to the
shared Purview.Build pipeline (restore, build, CSharpier lint,
the full test suite including the AppHost integration tests, pack, package-content validation). The
integration tests need a Docker-capable runner; GitHub’s ubuntu-latest is one. See
Release Flow.
Commits follow Conventional Commits, enforced by commitlint and Lefthook hooks.