Generates and verifies the manifest-backed package chooser markdown for the repository.
This generator is intentionally repository-aware. It expects the manifest, chooser sidecar, package README links, and release-surface links to resolve to files under the supplied repository root. Callers should validate repository layout drift through VerifyAsync in CI whenever package or docs paths change.
Task GenerateToFileAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates chooser markdown and writes it to the configured output path.
requestGeneration request describing the repository root, manifest path, and output path.cancellationTokenCancellation token used for manifest loading, metadata evaluation, and file writes.A task that completes when the chooser file has been written.
PackageIndexExceptionThrown when the repository layout is invalid, required docs are missing, or the manifest cannot be rendered safely.This method creates the output directory when it does not already exist and overwrites the chooser file atomically from the generated markdown payload.
Task<string> GenerateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates chooser markdown from the manifest and evaluated project metadata without writing it to disk.
requestGeneration request describing the repository root, manifest path, and output path context.cancellationTokenCancellation token used while loading the manifest and project metadata.The fully rendered chooser markdown.
PackageIndexExceptionThrown when repository layout, manifest content, or linked docs targets do not satisfy the chooser contract.Task VerifyAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Verifies that the checked-in chooser file matches the current repository truth.
requestVerification request describing the repository root, manifest path, and generated chooser file.cancellationTokenCancellation token used while regenerating and reading the existing chooser file.A task that completes when verification succeeds.
PackageIndexExceptionThrown when the generated chooser is missing or differs from the freshly generated markdown.Task<PackageGateReport> RunPackageGateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Runs release-readiness checks that protect the package manifest from drifting away from publishable packages.
requestGate request describing the repository root, manifest path, and generated chooser file.cancellationTokenCancellation token used while evaluating package metadata and scanning files.A report summarizing the package and source-file surfaces covered by the gate.
PackageIndexExceptionThrown when release metadata is missing, package class rules are violated, or stale brand strings remain.StringComparison RepositoryPathComparison { get; }
Source
Gets the path-comparison rule used when enforcing repository-boundary checks for chooser links.
Windows paths are treated case-insensitively. Other platforms stay ordinal so chooser validation does not assume a case-insensitive filesystem on Linux or macOS.
Describes one package chooser generation or verification request.
RepositoryRootAbsolute repository root that contains the manifest, docs, and project files.ManifestPathAbsolute path to the chooser manifest file.OutputPathAbsolute path to the generated chooser markdown file.Couples one manifest row with the evaluated package metadata used to render the chooser.
ManifestThe manifest row that provides classification, prose, and docs pointers.MetadataThe evaluated project metadata that provides package identity and install details.Summarizes the package gate coverage used by CI and local release checks.
PackageCountNumber of manifest entries validated by package class and release metadata rules.ScannedFileCountNumber of source files scanned for stale brand strings.Validates package release metadata, package-class invariants, and stale brand drift before packages are published.
PackageGateReport Validate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)
Source
Validates all gate rules against resolved package entries and repository files.
repositoryRootAbsolute repository root to scan.entriesResolved package entries from the chooser manifest.A compact report describing gate coverage.
Represents a package chooser generation or verification failure.
These exceptions are written directly to CLI stderr, so messages should stay actionable and user-facing.
Contract for evaluating one discovered project into package metadata suitable for chooser rendering.
Task<PackageProjectMetadata> GetMetadataAsync(string repositoryRoot, string projectPath, CancellationToken cancellationToken)
Source
Evaluates one project file and returns the package metadata used by the chooser.
repositoryRootAbsolute repository root used as the evaluation working directory.projectPathRepository-relative project path for the project being evaluated.cancellationTokenCancellation token that should abort the evaluation when possible.The evaluated project metadata for the supplied project.
Evaluated package metadata used by the chooser renderer.
ProjectPathRepository-relative path to the project that produced this metadata.PackageIdNuGet package identifier emitted by the project.TargetFrameworkResolved target framework summary used in chooser copy.IsPackableWhether the project reports itself as packable.IsToolWhether the project reports itself as a .NET tool package.OutputTypeResolved output type, such as Library or Exe.ProjectReferencesEvaluated project reference paths reported by MSBuild.string InstallCommand { get; }
Source
Gets the primary install command shown in the chooser for this package or tool.
Discovers candidate projects that should be classified by the package chooser manifest.
The scanner intentionally excludes tests, examples, tooling, and generated directories so the manifest only needs to classify packages that are meaningful to external adopters or package-surface maintainers.
IReadOnlyList<string> DiscoverProjects(string repositoryRoot)
Source
Enumerates candidate project files under the repository root.
repositoryRootAbsolute repository root to scan.Repository-relative project paths ordered for stable manifest validation.
bool IsCandidateProject(string relativePath)
Source
Determines whether a repository-relative project path belongs in the chooser manifest.
relativePathRepository-relative project path to evaluate.true when the path should be classified by the chooser manifest; otherwise, false.
Evaluates project metadata by invoking dotnet msbuild and reading JSON property output.
This provider depends on a functioning local .NET SDK and assumes the project can be evaluated from the repository root. Timeouts and malformed output are surfaced as PackageIndexException so CLI callers can fail fast in CI.
PackageProjectMetadata ParseMetadataJson(string projectPath, string standardOutput)
Source
Parses one dotnet msbuild JSON payload into package metadata.
projectPathRepository-relative project path used for error reporting.standardOutputRaw JSON payload captured from dotnet msbuild.The normalized package metadata derived from the JSON payload.
PackageIndexExceptionThrown when the JSON payload is malformed, missing required properties, or reports incomplete metadata.This parsing seam is intentionally internal so tests can verify malformed and incomplete metadata handling without depending on a real SDK invocation or using reflection against private helpers.
Loads the chooser manifest from YAML into strongly typed manifest models.
Task<PackageManifest> LoadAsync(string manifestPath, CancellationToken cancellationToken)
Source
Reads and parses the chooser manifest file.
manifestPathAbsolute path to the chooser manifest file.cancellationTokenCancellation token used while reading the manifest from disk.The parsed chooser manifest.
PackageIndexExceptionThrown when the manifest cannot be parsed or does not define any package rows.Root manifest model for the chooser YAML file.
List<PackageManifestEntry> Packages { get; init; }
Source
Gets the ordered manifest rows that describe each package, support surface, or excluded package entry.
One manifest row describing how a project should appear in the chooser.
Public rows must define install guidance and docs pointers. Non-public rows must define Note because their rendered bullets rely on that prose to explain why they are visible but not recommended as first installs.
string Project { get; init; }
Source
Gets the repository-relative project path classified by this manifest entry.
PackageClassification Classification { get; init; }
Source
Gets the chooser classification that controls which section renders the package.
PackagePublishDecision? PublishDecision { get; init; }
Source
Gets the publish decision consumed by the prerelease package artifact workflow.
string? PublishReason { get; init; }
Source
Gets the required maintainer-facing reason for entries that are intentionally not published.
int Order { get; init; }
Source
Gets the stable display order within the chooser section.
string? UseWhen { get; init; }
Source
Gets the adopter-focused “use when” guidance for public package rows.
string? Includes { get; init; }
Source
Gets the concise statement describing what the package includes for public rows.
string? DoesNotInclude { get; init; }
Source
Gets the concise statement describing what the package intentionally does not include for public rows.
string? StartHerePath { get; init; }
Source
Gets the repository-relative documentation file linked from this chooser row.
string? StartHereLabel { get; init; }
Source
Gets the optional chooser label used for the linked documentation target.
string? RecipeSummary { get; init; }
Source
Gets the optional recipe summary shown in the “Also building...” section.
string? Note { get; init; }
Source
Gets the explanatory note rendered for non-public package rows.
List<string> DependsOn { get; init; }
Source
Gets the optional package ids that this row depends on for install guidance.
List<string> ExpectedDependencyPackageIds { get; init; }
Source
Gets the exact package ids expected from project-reference dependencies in the produced package.
PackageReleaseStatus ReleaseStatus { get; init; }
Source
Gets the release status expected by package-gate for this package classification.
PackageCommercialStatus CommercialStatus { get; init; }
Source
Gets whether this package row is part of the commercial-ready public surface.
string? ReleaseNotesPath { get; init; }
Source
Gets the repository-relative release notes file that explains current readiness for this package.
Chooser section classifications for manifest entries.
Publish decisions for package artifact verification and later prerelease publishing.
Release status values package-gate expects for each chooser classification.
Commercial readiness status values used by package-gate.
Coordinates prerelease package artifact packing and validation without publishing to NuGet.
Task<PackageArtifactValidationReport> RunAsync(PackageArtifactRequest request, CancellationToken cancellationToken = default)
Source
Packs and validates prerelease package artifacts.
requestArtifact workflow request.cancellationTokenCancellation token propagated to external commands and file writes.Successful validation report.
Request for package artifact packing and validation.
RepositoryRootAbsolute repository root.ManifestPathAbsolute package manifest path.ArtifactsOutputPathDirectory that receives produced .nupkg artifacts.ReportPathMarkdown validation report path.PackageVersionExact prerelease package version to pack and validate.ArtifactManifestPathMachine-readable validation manifest path for the publish workflow.Runs external commands through CliWrap for protected package publishing and smoke-install workflows.
External command runner used by publish and smoke workflows when non-zero exit codes are meaningful results.
Task<ExternalCommandResult> RunAsync(ExternalCommandRequest request, CancellationToken cancellationToken)
Source
Runs a command and returns stdout, stderr, and exit code without throwing for non-zero exits.
requestCommand request.cancellationTokenCancellation token.Captured command result.
Command invocation for CliWrap-backed release automation.
Captured command result including non-zero exit codes.
Writes the machine-readable package artifact manifest consumed by protected publish jobs.
Task WriteAsync(PackageArtifactValidationReport report, string artifactsDirectory, string manifestPath, CancellationToken cancellationToken)
Source
Writes a manifest that binds validated package ids to artifact file names and SHA-512 hashes.
reportPackage artifact validation report.artifactsDirectoryDirectory containing the validated package artifacts.manifestPathDestination manifest path.cancellationTokenCancellation token.Reads and validates the artifact manifest written by the package artifact verifier.
Task<PackageArtifactManifest> ReadAsync(string manifestPath, CancellationToken cancellationToken)
Source
Reads a package artifact manifest from disk.
manifestPathManifest path.cancellationTokenCancellation token.Validated artifact manifest.
Publishes a validated prerelease package artifact set to NuGet in manifest order.
Task<PackagePublishLedger> RunAsync(PackagePrereleasePublishRequest request, CancellationToken cancellationToken)
Source
Publishes each artifact selected by the checked-in manifest and writes a markdown ledger.
requestPublish request.cancellationTokenCancellation token.Publish ledger.
Restores published public packages from a clean NuGet configuration after publish completes.
Task<PackageSmokeInstallReport> RunAsync(PackageSmokeInstallRequest request, CancellationToken cancellationToken)
Source
Restores each public package from the configured package source in an isolated workspace.
requestSmoke install request.cancellationTokenCancellation token.Smoke install report.
Renders protected publish outcomes for workflow artifacts.
Renders package smoke install outcomes for workflow artifacts.
Request for the protected NuGet prerelease publish workflow.
RepositoryRootRepository root used for plan resolution.ManifestPathChecked-in package manifest path.ArtifactsInputPathDirectory containing validated .nupkg files.ArtifactManifestPathMachine-readable artifact manifest path.PublishLogPathMarkdown publish ledger path.SourceNuGet source URL.ApiKeyEnvironmentVariableEnvironment variable that supplies the NuGet API key.Request for the post-publish smoke install workflow.
RepositoryRootRepository root used for path display and validation.ManifestPathChecked-in package manifest path used to revalidate the artifact manifest.ArtifactManifestPathMachine-readable artifact manifest path.WorkDirectoryIsolated smoke install work directory.ReportPathMarkdown smoke install report path.SourceNuGet source URL.Machine-readable artifact manifest that binds validated package artifacts to immutable hashes.
SchemaVersionManifest schema version.PackageVersionExact prerelease package version.GeneratedAtUtcUTC timestamp when the manifest was generated.EntriesManifest entries in package publish order.One package artifact selected from the checked-in package manifest.
PackageIdNuGet package id.ProjectPathRepository-relative project path.DecisionPublish decision string from the package plan.ArtifactFileNamePackage artifact file name without directory segments.Sha512Lowercase hexadecimal SHA-512 hash of the package artifact.IsToolWhether the artifact is a .NET tool package.Publish result for a coordinated prerelease package version.
PackageVersionExact prerelease package version.SourceNuGet source URL.EntriesPer-package publish outcomes.Publish outcome for one package artifact.
PackageIdNuGet package id.ProjectPathRepository-relative project path.ArtifactFileNamePackage artifact file name.StatusPublish status.ExitCodeExit code from dotnet nuget push, or zero for skipped packages.OutputCaptured publish output with secrets excluded.Smoke install result for packages restored after prerelease publishing.
PackageVersionExact prerelease package version.SourceNuGet source URL.EntriesPer-package smoke install outcomes.Smoke install outcome for one public package.
PackageIdNuGet package id.ProjectPathRepository-relative project path.IsToolWhether the package was installed as a .NET tool.StatusSmoke install status.ExitCodeExit code from the final restore or tool install attempt.OutputCaptured install output.Computes package artifact hashes for manifest generation and publish verification.
JSON serializer options shared by artifact manifest readers and writers.
Environment variables that make release automation quieter and deterministic.
Formats package publish decisions for machine-readable release artifacts.
Verifies that an artifact manifest still matches the checked-in package plan and validated artifacts.
Package artifact that has been matched to both the checked-in plan and artifact manifest.
ManifestEntryManifest entry for the artifact.ArtifactPathResolved artifact path on disk.Publish status values written to the protected publish ledger.
Smoke install status values written to the smoke report.
Resolves the checked-in package manifest into the exact package set that should be packed.
Task<PackagePublishPlan> ResolveAsync(string repositoryRoot, string manifestPath, CancellationToken cancellationToken)
Source
Resolves and validates the package publish plan.
repositoryRootAbsolute repository root.manifestPathAbsolute path to the package manifest.cancellationTokenCancellation token used while loading metadata.The ordered package publish plan.
Ordered package set selected for artifact packing and validation.
EntriesPackages that should be packed, in deterministic manifest order.One package selected for pack artifact production.
ProjectPathRepository-relative project path to pack.PackageIdExpected NuGet package id.DecisionPublish decision from the manifest.ExpectedDependencyPackageIdsExpected same-version package dependencies.IsToolWhether the package is a .NET tool package.Validates prerelease package artifacts against the resolved publish plan.
PackageArtifactValidationReport Validate(PackagePublishPlan plan, string artifactsDirectory, string packageVersion)
Source
Validates the package output directory and returns a markdown-ready report.
planResolved package publish plan.artifactsDirectoryDirectory containing produced .nupkg files.packageVersionExact package version expected in every artifact.A validation report for the inspected artifacts.
Renders package artifact validation results for workflow artifacts.
string RenderMarkdown(PackageArtifactValidationReport report)
Source
Renders the validation report as markdown.
reportValidation report to render.Markdown report content.
Ensures package versions used by the prerelease workflow are safe for NuGet identity.
void RequirePrerelease(string packageVersion)
Source
Validates that the package version is a prerelease SemVer identity without build metadata.
packageVersionPackage version to validate.Result of a successful package artifact validation run.
PackageVersionExact package version inspected.EntriesValidated package report rows.One validated package row in the artifact report.
PackageIdValidated package id.ProjectPathProject that produced the package.DecisionPublish decision from the manifest.ExpectedDependencyPackageIdsExpected same-version package dependency ids.ArtifactPathValidated .nupkg artifact path.IsToolWhether the package is a .NET tool package.Metadata and payload facts inspected from one NuGet package artifact.
PackagePathAbsolute or caller-supplied path to the inspected .nupkg file.PackageIdNuspec package id. Expected to be non-empty after inspection.PackageVersionNuspec package version. Expected to be non-empty after inspection.AuthorsNuspec authors metadata, or null when absent.DescriptionNuspec description metadata, or null when absent.LicenseNuspec license expression or value, or null when absent.RepositoryUrlNuspec repository URL, or null when absent.TagsNuspec package tags, or null when absent.ReadmeNuspec README path, or null when absent.PackageTypesDeclared nuspec package type names such as DotnetTool.DependenciesDependency ids mapped to all distinct nuspec versions observed across dependency groups.EntryPathsNormalized archive entry paths contained in the package.FirstPartyAssemblyVersionsFirst-party implementation assemblies and their informational versions.Informational version metadata read from a first-party assembly inside a package artifact.
EntryPathArchive path for the inspected assembly entry.InformationalVersionAssembly informational version value read from metadata.Runs external commands for repository validation workflows.
Task<CommandRunResult> RunAsync(CommandRunRequest request, CancellationToken cancellationToken)
Source
Runs the requested command and returns captured output when it exits successfully.
requestCommand request with process, timeout, and user-facing error context.cancellationTokenCancellation token used while waiting for command completion.Captured process output.
PackageIndexExceptionThrown when the process fails to start, times out, or exits unsuccessfully.Describes one external command invocation and the language to use when it fails.
FileNameExecutable name or path.ArgumentsCommand-line arguments supplied without shell interpolation.WorkingDirectoryWorking directory for the process.OperationNameHuman-readable operation name, such as dotnet pack.SubjectRepository item being processed, such as a project path.FailureVerbVerb phrase used in nonzero exit messages, such as pack or evaluate.TimeoutDescriptionGerund phrase used in timeout messages, such as packing.TimeoutMillisecondsTimeout applied to the process wait.EnvironmentOptional environment variable overrides.Captured stdout and stderr from a successful command.
StandardOutputCaptured standard output.StandardErrorCaptured standard error.Process-backed command runner with timeout and failure cleanup.
CLI entry point for generating or verifying the package chooser.
Task<int> Main(string[] args)
Source
Launches the package chooser CLI with the current process IO streams and working directory.
argsCommand-line arguments supplied to the process.Process exit code where 0 indicates success.
Task<int> RunAsync(string[] args, TextWriter standardOut, TextWriter standardError, string currentDirectory, CancellationToken cancellationToken = default, Func<PackageArtifactRequest, CancellationToken, Task<PackageArtifactValidationReport>>? verifyPackagesAsync = null, Func<PackagePrereleasePublishRequest, CancellationToken, Task<PackagePublishLedger>>? publishPrereleaseAsync = null, Func<PackageSmokeInstallRequest, CancellationToken, Task<PackageSmokeInstallReport>>? smokeInstallAsync = null)
Source
Runs the package chooser CLI against the supplied IO streams and working directory.
argsCommand-line arguments, including the command and optional path overrides. If any help argument is present, this method returns usage output before command or option parsing so help remains available from any working directory.standardOutWriter that receives success messages and help/usage output.standardErrorWriter that receives invalid invocation usage and failure messages.currentDirectoryWorking directory used to resolve default repository-relative paths after help handling.cancellationTokenCancellation token propagated to generator operations.verifyPackagesAsyncOptional package artifact workflow override used by tests.publishPrereleaseAsyncOptional prerelease publish workflow override used by tests.smokeInstallAsyncOptional smoke install workflow override used by tests.0 when the command succeeds; otherwise a non-zero exit code.
Parsed CLI options for one package chooser command invocation.
RequestResolved package chooser request derived from command-line options.ArtifactsOutputPathResolved package artifact output directory.ReportPathResolved package artifact validation report path.PackageVersionOptional package version supplied for package artifact verification.ArtifactsInputPathResolved package artifact input directory for protected publish jobs.ArtifactManifestPathResolved machine-readable package artifact manifest path.PublishLogPathResolved protected publish ledger path.SourceNuGet source URL used for publish and smoke install.ApiKeyEnvironmentVariableEnvironment variable name that supplies the NuGet API key.SmokeWorkDirectoryResolved isolated smoke install work directory.SmokeReportPathResolved smoke install report path.CommandLineOptions Parse(string[] args, string currentDirectory)
Source
Parses path-related CLI options into a resolved chooser request.
argsArguments after the command verb.currentDirectoryWorking directory used to resolve relative overrides.The parsed command-line options.
PackageIndexExceptionThrown when an option is unknown or missing its required value.PackageArtifactRequest CreatePackageArtifactRequest()
Source
Converts parsed CLI options into a package artifact request.
The package artifact request.
PackageIndexExceptionThrown when the required package version is missing.PackagePrereleasePublishRequest CreatePackagePrereleasePublishRequest()
Source
Converts parsed CLI options into a protected prerelease publish request.
The prerelease publish request.
PackageSmokeInstallRequest CreatePackageSmokeInstallRequest()
Source
Converts parsed CLI options into a package smoke install request.
The package smoke install request.