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.AppHostgenerated pattern,Example.ManualAppHostmanual pattern,Example.Service,Example.ServiceDefaults).src/tests/*— unit and integration tests for the runtime and the generator.docs/wiki— this documentation suite.
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 # remove bin/obj, clean, restore, stop build serverjust version # show the current version from package.jsonNothing here needs the Aspire CLI installed. The example AppHosts build against the NuGet-delivered
DCP and dashboard packages (AspireUseCliBundle=false), which the AppHost SDK turns into
Aspire.Dashboard.Sdk.<rid> and Aspire.Hosting.Orchestration.<rid> references for the build machine’s
RID. Opting them into the CLI bundle instead (-p:AspireUseCliBundle=true) makes a build need a
resolvable bundle, and resolving one is a network install performed mid-build, once per AppHost — two of
which then race on the NuGet cache and fail each other with ASPIRE009. ExampleAppHostTests keeps the
opt-in out of the project files for exactly that reason.
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 the plain-Markdown topic pages and nothing else. There is deliberately no Home.md
hub, no _Sidebar.md navigation and no site configuration in this repository: the site at
https://purview.dev/docs/aspire-resourcekit/ generates its own navigation from the pages that are
here. Do not “restore” the mkdocs scaffolding — it was removed on purpose (see CHANGELOG.md), and a
page’s discoverability is decided by the site, not by a file in this repository.
Two rules that still apply: a page added or renamed here must be linked from at least one other page
or from README.md, and anything a consumer is told about the package is a claim
just verify-consumers or 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 BuildSdk targets, which run once for the whole solution:
just restore # the targets read the restore graph and never restore on their ownjust skills-update # re-add every source in skills-lock.jsonjust skills-check # fail if an agent directory other than .agents/skills and .claude/skills existsPurviewSkillsAgents in src/Directory.Build.props names the two agents thus allowed; 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.