int SchemaVersion { get; init; }
Source
Gets the inventory schema version. Version 1 is the only supported v1 contract.
PackageIndex
ICommandRunner
SourceRuns external commands for repository validation workflows.
RunAsync
Task<CommandRunResult> RunAsync(CommandRunRequest request, CancellationToken cancellationToken)
Source
Runs the requested command and returns captured output when it exits successfully.
Parameters
requestCommand request with process, timeout, and user-facing error context.cancellationTokenCancellation token used while waiting for command completion.
Returns
Captured process output.
Exceptions
PackageIndexExceptionThrown when the process fails to start, times out, or exits unsuccessfully.
CommandRunRequest
SourceDescribes one external command invocation and the language to use when it fails.
Parameters
FileNameExecutable name or path.ArgumentsCommand-line arguments supplied without shell interpolation.WorkingDirectoryWorking directory for the process.OperationNameHuman-readable operation name, such asdotnet pack.SubjectRepository item being processed, such as a project path.FailureVerbVerb phrase used in nonzero exit messages, such aspackorevaluate.TimeoutDescriptionGerund phrase used in timeout messages, such aspacking.TimeoutMillisecondsTimeout applied to the process wait.EnvironmentOptional environment variable overrides.
CommandRunResult
SourceCaptured stdout and stderr from a successful command.
Parameters
StandardOutputCaptured standard output.StandardErrorCaptured standard error.
ProcessCommandRunner
SourceProcess-backed command runner with timeout and failure cleanup.
PackagePayloadInventoryLoader
SourceLoads the redistributed package payload inventory used by verify-packages.
LoadAsync
Task<PackagePayloadInventory> LoadAsync(string repositoryRoot, CancellationToken cancellationToken = default)
Source
Reads the repository-owned payload inventory from its default location.
Parameters
repositoryRootAbsolute repository root used to resolve the inventory path.cancellationTokenCancellation token used while reading the file.
Returns
The parsed redistributed payload inventory.
Parse
PackagePayloadInventory Parse(string content, string displayPath = DefaultRelativePath)
Source
Parses payload inventory YAML content.
Parameters
contentYAML inventory content.displayPathPath shown in validation errors.
Returns
The parsed inventory.
ResolveInventoryPath
string ResolveInventoryPath(string repositoryRoot, string relativePath)
Source
Resolves the repository-relative payload inventory path under the repository root.
Parameters
repositoryRootAbsolute repository root used to resolve the inventory path.relativePathRepository-relative inventory path.
Returns
The absolute inventory path.
PackagePayloadInventory
SourceRepository-owned contract for redistributed package payload notice, audit, and generated evidence.
Validate
void Validate(string displayPath)
Source
Validates the parsed inventory shape before package-specific evidence checks run.
Parameters
displayPathPath shown in validation errors.
SchemaVersion
Notices
List<PackagePayloadNoticeRecord> Notices { get; init; }
Source
Gets third-party payload declarations that require package notices and provenance evidence.
Audits
List<PackagePayloadAuditRecord> Audits { get; init; }
Source
Gets narrow audit records for generated-first-party or otherwise non-notice payload evidence.
PackagePayloadNoticeRecord
SourceThird-party redistributed payload evidence that requires package notice coverage.
Id
string Id { get; init; }
Source
Gets the stable inventory record id.
PackageId
string PackageId { get; init; }
Source
Gets the package id that must contain the declared payload.
Component
string Component { get; init; }
Source
Gets the redistributed component name shown in package reports.
Version
string Version { get; init; }
Source
Gets the redistributed component version.
License
string License { get; init; }
Source
Gets the redistributed component license expression or short name.
SourceUrl
string SourceUrl { get; init; }
Source
Gets the upstream source or project URL for maintainer review.
PayloadPatterns
List<string> PayloadPatterns { get; init; }
Source
Gets package entry glob patterns that identify the redistributed payload.
NoticePaths
List<string> NoticePaths { get; init; }
Source
Gets package entry paths that must contain the third-party notice text.
Markers
List<string> Markers { get; init; }
Source
Gets marker strings that must appear in at least one notice file.
SourcePaths
List<string> SourcePaths { get; init; }
Source
Gets optional source files that must exist in the repository for this evidence.
VersionSourcePath
string? VersionSourcePath { get; init; }
Source
Gets an optional repository file whose content must contain VersionSourceContains.
VersionSourceContains
string? VersionSourceContains { get; init; }
Source
Gets text that must appear in VersionSourcePath when the source is deterministic.
PackagePayloadAuditRecord
SourceAudit evidence for package payloads that are generated-first-party or otherwise not third-party notice records.
Id
string Id { get; init; }
Source
Gets the stable inventory record id.
PackageId
string PackageId { get; init; }
Source
Gets the package id covered by this audit record.
AppliesTo
List<string> AppliesTo { get; init; }
Source
Gets package entry glob patterns or evidence labels covered by this audit.
MatchedRule
string? MatchedRule { get; init; }
Source
Gets the suspicious classifier rule or evidence class that caused this audit.
EvidenceKind
string EvidenceKind { get; init; }
Source
Gets the audit evidence type, such as generated_first_party.
SourcePaths
List<string> SourcePaths { get; init; }
Source
Gets repository source paths that must exist for this audit to stay valid.
GeneratedPaths
List<string> GeneratedPaths { get; init; }
Source
Gets generated repository paths that must exist for generated-first-party evidence.
Reason
string Reason { get; init; }
Source
Gets the human-readable reason this record is not a third-party notice declaration.
ReviewedOn
string ReviewedOn { get; init; }
Source
Gets the date or versioned source used for the audit review.
Source
string Source { get; init; }
Source
Gets the reviewer, source document, or script that established this audit.
RevalidateWhen
string RevalidateWhen { get; init; }
Source
Gets the event that must force revalidation of the audit.
PackageIndexGenerator
SourceGenerates and verifies the manifest-backed package chooser markdown for the repository.
Remarks
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.
GenerateToFileAsync
Task GenerateToFileAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates package chooser and readiness dashboard markdown and writes both configured output paths.
Parameters
requestGeneration request describing the repository root, manifest path, chooser output, and readiness output.cancellationTokenCancellation token used for manifest loading, metadata evaluation, and file writes.
Returns
A task that completes when the generated files have been written.
Exceptions
PackageIndexExceptionThrown when the repository layout is invalid, required docs are missing, or the manifest cannot be rendered safely.
Remarks
This method creates output directories when they do not already exist and overwrites the generated files from the generated markdown payloads.
GenerateAsync
Task<string> GenerateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates chooser markdown from the manifest and evaluated project metadata without writing it to disk.
Parameters
requestGeneration request describing the repository root, manifest path, and output path context.cancellationTokenCancellation token used while loading the manifest and project metadata.
Returns
The fully rendered chooser markdown.
Exceptions
PackageIndexExceptionThrown when repository layout, manifest content, or linked docs targets do not satisfy the chooser contract.
GenerateDocumentsAsync
Task<PackageIndexDocuments> GenerateDocumentsAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates the package chooser and package-index evidence dashboard without writing either file to disk.
Parameters
requestGeneration request describing repository inputs and output path contexts.cancellationTokenCancellation token used while loading the manifest and project metadata.
Returns
Generated chooser and readiness markdown payloads.
VerifyAsync
Task VerifyAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Verifies that the checked-in chooser and readiness dashboard files match the current repository truth.
Parameters
requestVerification request describing the repository root, manifest path, and generated files.cancellationTokenCancellation token used while regenerating and reading the existing generated files.
Returns
A task that completes when verification succeeds.
Exceptions
PackageIndexExceptionThrown when either generated file is missing or differs from freshly generated markdown.
RunPackageGateAsync
Task<PackageGateReport> RunPackageGateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Runs release-readiness checks that protect the package manifest from drifting away from publishable packages.
Parameters
requestGate request describing the repository root, manifest path, and generated chooser file.cancellationTokenCancellation token used while evaluating package metadata and scanning files.
Returns
A report summarizing the package and source-file surfaces covered by the gate.
Exceptions
PackageIndexExceptionThrown when release metadata is missing, package class rules are violated, or stale brand strings remain.
ValidateWebPackageQuickstartTarget
void ValidateWebPackageQuickstartTarget(string repositoryRoot)
Source
Validates that the package-first chooser link resolves to the quickstart file and section anchor.
Parameters
repositoryRootRepository root that contains the Start Here quickstart.
Exceptions
PackageIndexExceptionThrown when the quickstart file is missing or no heading or explicit anchor produces the expected fragment target.
Remarks
The generated chooser deep links into this document. Checking the file alone is not enough, because a heading rename would otherwise ship a dead #package-first-path link while package verification still passes.
ValidateToolCommandName
void ValidateToolCommandName(PackageManifestEntry entry, PackageProjectMetadata metadata)
Source
Validates the manifest command-name contract against project metadata for one package row.
Parameters
entryManifest row that may declaretool_command_nameand a publish decision.metadataEvaluated project metadata that reports whether the project packs as a .NET tool.
Exceptions
PackageIndexExceptionThrown when a tool selected forPackagePublishDecision.PublishorPackagePublishDecision.SupportPublishomits or mis-shapestool_command_name, or when a non-tool project declares a command name despite not settingPackAsTool=true.
ValidateToolCommandNameValue
void ValidateToolCommandNameValue(string projectPath, string commandName)
Source
Validates the manifest-declared tool command token for one project.
Parameters
projectPathRepository-relative project path used in actionable error messages.commandNameCommand token read fromtool_command_name.
Exceptions
PackageIndexExceptionThrown when the command token is missing or uses a value that cannot safely resolve to one command shim file.
Remarks
The value must be a single file-name-safe token. It must not be blank, ., .., a Windows reserved device name or dotted alias such as con.txt, end with a period, or contain whitespace, path separators, control characters, or portable file-name-invalid characters.
RepositoryFileExists
bool RepositoryFileExists(string repositoryRoot, string repositoryRelativePath)
Source
Checks whether a known repository-relative chooser support file exists under the repository root.
Parameters
repositoryRootRepository root used as the path-resolution base; relative roots are normalized withPath.GetFullPath(string).repositoryRelativePathRepository-relative file path, conventionally using/separators.
Returns
true when the normalized file exists; otherwise, false.
Remarks
Use this only for trusted, optional chooser links. It normalizes separators and resolves .. segments before checking existence, but missing files are not errors. Manifest-supplied or required documentation targets should use ResolveRepositoryFilePath so rooted, escaping, or missing paths fail loudly.
MarkdownDefinesFragmentTarget
bool MarkdownDefinesFragmentTarget(string markdown, string fragment)
Source
Checks whether markdown defines an explicit anchor or slugified heading for a fragment.
Parameters
markdownMarkdown content to inspect.fragmentFragment id without a leading#.
Returns
true when the content defines the fragment; otherwise, false.
Remarks
The check intentionally covers the forms authors are likely to use in hand-written docs: GitHub-style generated heading ids, explicit {#id} heading anchors, and HTML anchor elements.
TryGetMarkdownHeadingText
string? TryGetMarkdownHeadingText(string line)
Source
Extracts the text from an ATX markdown heading line when the line uses one to six leading hash marks.
Parameters
lineSingle markdown line to inspect.
Returns
The heading text without closing hash marks or explicit anchor syntax, or null when not a heading.
SlugifyMarkdownHeading
string SlugifyMarkdownHeading(string heading)
Source
Produces the GitHub-style heading slug used by repository markdown anchors for simple heading text.
Parameters
headingHeading text to slugify.
Returns
A lowercase fragment id using hyphens for spaces and hyphens in the source text.
ResolveRepositoryFilePath
string ResolveRepositoryFilePath(string repositoryRoot, string repositoryRelativePath, string description)
Source
Resolves a required repository-relative documentation target and validates that it exists under the repository root.
Parameters
repositoryRootRepository root used as the resolution boundary; relative roots are normalized withPath.GetFullPath(string).repositoryRelativePathRepository-relative file path supplied by chooser metadata, conventionally using/separators.descriptionHuman-readable label included in validation errors.
Returns
The normalized absolute path to the validated file.
Exceptions
PackageIndexExceptionThrown whenrepositoryRelativePathis blank, rooted, escapes the repository root after normalization, or points at missing documentation.
Remarks
The resolver replaces / with Path.DirectorySeparatorChar and normalizes .. segments. Callers should keep inputs repository-relative and avoid leading separators, because absolute-looking paths are rejected before they can bypass the repository boundary.
RepositoryPathComparison
StringComparison RepositoryPathComparison { get; }
Source
Gets the path-comparison rule used when enforcing repository-boundary checks for chooser links.
Remarks
Windows paths are treated case-insensitively. Other platforms stay ordinal so chooser validation does not assume a case-insensitive filesystem on Linux or macOS.
PackageIndexRequest
SourceDescribes one package chooser and readiness dashboard generation or verification request.
Parameters
RepositoryRootAbsolute repository root that contains the manifest, docs, and project files.ManifestPathAbsolute path to the chooser manifest file.ChooserOutputPathAbsolute path to the generated chooser markdown file.ReadinessOutputPathAbsolute path to the generated package readiness dashboard markdown file.
OutputPath
string OutputPath { get; }
Source
Gets the chooser output path retained for compatibility with existing tests and callers.
PackageIndexDocuments
SourceGenerated markdown documents produced from one package index resolution pass.
Parameters
ChooserMarkdownGenerated adopter-facing package chooser markdown.ReadinessMarkdownGenerated maintainer-facing package readiness evidence markdown.
ResolvedPackageEntry
SourceCouples one manifest row with the evaluated package metadata used to render the chooser.
Parameters
ManifestThe manifest row that provides classification, prose, and docs pointers.MetadataThe evaluated project metadata that provides package identity and install details.
PackageReadinessEvaluator
SourceComputes package-index readiness evidence for the maintainer dashboard without treating the dashboard as live publish proof.
Evaluate
IReadOnlyList<PackageReadinessEvidence> Evaluate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)
Source
Evaluates package-index evidence for resolved package rows.
Parameters
repositoryRootAbsolute repository root used to validate release-note paths.entriesResolved package rows.
Returns
Per-package readiness evidence with blocking reasons and fix hints.
PackageReadinessEvidence
SourcePer-package readiness evidence rendered in the generated maintainer dashboard.
Parameters
ProjectPathRepository-relative project path from the package manifest.PackageIdEvaluated package id.StatusComputed package-index evidence status.EvidenceNon-blocking evidence that passed.BlockingReasonsReasons the package-index evidence is blocked.FixHintsMaintainer-facing fix hints for blocking reasons.
PackageGateReport
SourceSummarizes the package gate coverage used by CI and local release checks.
Parameters
PackageCountNumber of manifest entries validated by package class and release metadata rules.ScannedFileCountNumber of source files scanned for stale brand strings.
PackageGateValidator
SourceValidates package release metadata, package-class invariants, and stale brand drift before packages are published.
Validate
PackageGateReport Validate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)
Source
Validates all gate rules against resolved package entries and repository files.
Parameters
repositoryRootAbsolute repository root to scan.entriesResolved package entries from the chooser manifest.
Returns
A compact report describing gate coverage.
PackageIndexException
SourceRepresents a package chooser generation or verification failure.
Remarks
These exceptions are written directly to CLI stderr, so messages should stay actionable and user-facing.
IProjectMetadataProvider
SourceContract for evaluating one discovered project into package metadata suitable for chooser rendering.
GetMetadataAsync
Task<PackageProjectMetadata> GetMetadataAsync(string repositoryRoot, string projectPath, CancellationToken cancellationToken)
Source
Evaluates one project file and returns the package metadata used by the chooser.
Parameters
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.
Returns
The evaluated project metadata for the supplied project.
PackageProjectMetadata
SourceEvaluated package metadata used by the chooser renderer.
Parameters
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 asLibraryorExe.ProjectReferencesEvaluated project reference paths that contribute package dependency assets.
InstallCommand
string InstallCommand { get; }
Source
Gets the primary install command shown in the chooser for this package or tool.
PackageProjectScanner
SourceDiscovers candidate projects that should be classified by the package chooser manifest.
Remarks
The scanner intentionally excludes tests, examples, tooling, generated directories, and hidden local cache directories so the manifest only needs to classify packages that are meaningful to external adopters or package-surface maintainers.
DiscoverProjects
IReadOnlyList<string> DiscoverProjects(string repositoryRoot)
Source
Enumerates candidate project files under the repository root.
Parameters
repositoryRootAbsolute repository root to scan.
Returns
Repository-relative project paths ordered for stable manifest validation.
IsCandidateProject
bool IsCandidateProject(string relativePath)
Source
Determines whether a repository-relative project path belongs in the chooser manifest.
Parameters
relativePathRepository-relative project path to evaluate.
Returns
true when the path should be classified by the chooser manifest; otherwise, false.
DotNetProjectMetadataProvider
SourceEvaluates project metadata by invoking dotnet msbuild and reading JSON property output.
Remarks
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.
ParseMetadataJson
PackageProjectMetadata ParseMetadataJson(string projectPath, string standardOutput)
Source
Parses one dotnet msbuild JSON payload into package metadata.
Parameters
projectPathRepository-relative project path used for error reporting.standardOutputRaw JSON payload captured fromdotnet msbuild.
Returns
The normalized package metadata derived from the JSON payload.
Exceptions
PackageIndexExceptionThrown when the JSON payload is malformed, missing required properties, or reports incomplete metadata.
Remarks
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.
PackageManifestLoader
SourceLoads the chooser manifest from YAML into strongly typed manifest models.
LoadAsync
Task<PackageManifest> LoadAsync(string manifestPath, CancellationToken cancellationToken)
Source
Reads and parses the chooser manifest file.
Parameters
manifestPathAbsolute path to the chooser manifest file.cancellationTokenCancellation token used while reading the manifest from disk.
Returns
The parsed chooser manifest.
Exceptions
PackageIndexExceptionThrown when the manifest cannot be parsed or does not define any package rows.
PackageManifest
SourceRoot manifest model for the chooser YAML file.
Packages
List<PackageManifestEntry> Packages { get; init; }
Source
Gets the ordered manifest rows that describe each package, support surface, or excluded package entry.
PackageManifestEntry
SourceOne manifest row describing how a project should appear in the chooser.
Remarks
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.
Project
string Project { get; init; }
Source
Gets the repository-relative project path classified by this manifest entry.
Classification
PackageClassification Classification { get; init; }
Source
Gets the chooser classification that controls which section renders the package.
PublishDecision
PackagePublishDecision? PublishDecision { get; init; }
Source
Gets the publish decision consumed by the package artifact workflow.
ProductFamily
string? ProductFamily { get; init; }
Source
Gets the product family that owns this package row for maintainer readiness review.
PublishReason
string? PublishReason { get; init; }
Source
Gets the required maintainer-facing reason for entries that are intentionally not published.
ReadinessBlocker
string? ReadinessBlocker { get; init; }
Source
Gets the optional same-repository issue or pull request that blocks package-index evidence completion.
ReadinessNote
string? ReadinessNote { get; init; }
Source
Gets optional escaped plain-text maintainer context for package readiness evidence.
Order
int Order { get; init; }
Source
Gets the stable display order within the chooser section.
UseWhen
string? UseWhen { get; init; }
Source
Gets the adopter-focused “use when” guidance for public package rows.
Includes
string? Includes { get; init; }
Source
Gets the concise statement describing what the package includes for public rows.
DoesNotInclude
string? DoesNotInclude { get; init; }
Source
Gets the concise statement describing what the package intentionally does not include for public rows.
StartHerePath
string? StartHerePath { get; init; }
Source
Gets the repository-relative documentation file linked from this chooser row.
StartHereLabel
string? StartHereLabel { get; init; }
Source
Gets the optional chooser label used for the linked documentation target.
RecipeSummary
string? RecipeSummary { get; init; }
Source
Gets the optional recipe summary shown in the “Also building...” section.
ToolCommandName
string? ToolCommandName { get; init; }
Source
Gets the command shim expected from a .NET tool package.
Remarks
This field is only valid for projects that set PackAsTool=true. Public tool packages must provide a value so package validation, publish planning, and post-publish smoke tests can execute the command users type; non-tool packages must leave it unset. The value must be one file-name-safe command token rather than a path: no whitespace, path separators, reserved ./.. segments, trailing periods, Windows reserved device names or dotted aliases, control characters, or Windows-invalid file-name characters.
Note
string? Note { get; init; }
Source
Gets the explanatory note rendered for non-public package rows.
DependsOn
List<string> DependsOn { get; init; }
Source
Gets the optional package ids that this row depends on for install guidance.
ExpectedDependencyPackageIds
List<string> ExpectedDependencyPackageIds { get; init; }
Source
Gets the exact package ids expected from project-reference dependencies in the produced package.
ReleaseStatus
PackageReleaseStatus ReleaseStatus { get; init; }
Source
Gets the release status expected by package-gate for this package classification.
CommercialStatus
PackageCommercialStatus CommercialStatus { get; init; }
Source
Gets whether this package row is part of the commercial-ready public surface.
ReleaseNotesPath
string? ReleaseNotesPath { get; init; }
Source
Gets the repository-relative release notes file that explains current readiness for this package.
PackageReadinessStatus
SourcePackage-index evidence status rendered in the maintainer readiness dashboard.
PackageClassification
SourceChooser section classifications for manifest entries.
PackagePublishDecision
SourcePublish decisions for package artifact verification and later package publishing.
PackageReleaseStatus
SourceRelease status values package-gate expects for each chooser classification.
PackageCommercialStatus
SourceCommercial readiness status values used by package-gate.
CliWrapCommandRunner
SourceRuns external commands through CliWrap for protected package publishing and smoke-install workflows.
IExternalCommandRunner
SourceExternal command runner used by publish and smoke workflows when non-zero exit codes are meaningful results.
RunAsync
Task<ExternalCommandResult> RunAsync(ExternalCommandRequest request, CancellationToken cancellationToken)
Source
Runs a command and returns stdout, stderr, and exit code without throwing for non-zero exits.
Parameters
requestCommand request.cancellationTokenCancellation token.
Returns
Captured command result.
ExternalCommandRequest
SourceCommand invocation for CliWrap-backed release automation.
ExternalCommandResult
SourceCaptured command result including non-zero exit codes.
PackageArtifactManifestWriter
SourceWrites the machine-readable package artifact manifest consumed by protected publish jobs.
WriteAsync
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.
Parameters
reportPackage artifact validation report.artifactsDirectoryDirectory containing the validated package artifacts.manifestPathDestination manifest path.cancellationTokenCancellation token.
PackageArtifactManifestReader
SourceReads and validates the artifact manifest written by the package artifact verifier.
ReadAsync
Task<PackageArtifactManifest> ReadAsync(string manifestPath, CancellationToken cancellationToken)
Source
Reads a package artifact manifest from disk.
Parameters
manifestPathManifest path.cancellationTokenCancellation token.
Returns
Validated artifact manifest.
PackagePublishWorkflow
SourcePublishes a validated package artifact set to NuGet in manifest order.
RunAsync
Task<PackagePublishLedger> RunAsync(PackagePublishRequest request, CancellationToken cancellationToken)
Source
Publishes each artifact selected by the checked-in manifest and writes a markdown ledger.
Parameters
requestPublish request.cancellationTokenCancellation token.
Returns
Publish ledger.
PackageSmokeInstallWorkflow
SourceRestores published public packages and verifies published .NET tools from a clean NuGet configuration after publish completes.
RunAsync
Task<PackageSmokeInstallReport> RunAsync(PackageSmokeInstallRequest request, CancellationToken cancellationToken)
Source
Restores all non-tool publish entries in one aggregate smoke project, then verifies each tool package independently from isolated per-tool workspaces.
Parameters
requestSmoke install request containing the repository root, package index manifest path, artifact manifest path, smoke work directory, report output path, and package source URL.cancellationTokenCancellation token.
Returns
Smoke install report. Non-tool package entries share the aggregate restore result; tool entries report independent install and command-help results.
Remarks
Use this workflow for post-publish verification against a clean NuGet configuration. Non-tool packages share one generated Smoke.csproj restore to reduce total smoke time; tools are installed and run individually to keep command-shim verification isolated per package.
Restore, tool install, and tool help commands each use 180,000 ms timeouts. Aggregate restores and tool installs retry after 15s, 30s, 60s, and 120s delays. The package-restore directory and each per-tool directory under request.WorkDirectory are deleted and recreated on each run.
Pitfall: a failed aggregate package restore marks every non-tool package entry failed, but tool smoke still runs and is reported independently. Request validation and manifest or package-plan mismatches throw before a report is written; command failures are captured in the returned report unless the supplied cancellationToken cancels the workflow.
ResolveToolShimPath
string ResolveToolShimPath(string toolPath, string commandName)
Source
Resolves the installed tool shim path after proving the shim name cannot escape the tool directory.
Parameters
toolPathDirectory passed todotnet tool install --tool-path.commandNameValidated command token fromtool_command_name.
Returns
Full path to the command shim that should be executed.
Exceptions
ArgumentExceptionThrown when the command token cannot safely be treated as one file name undertoolPath.
PackagePublishLedgerRenderer
SourceRenders protected publish outcomes for workflow artifacts.
PackageSmokeInstallReportRenderer
SourceRenders package smoke install outcomes for workflow artifacts.
PackagePublishRequest
SourceRequest for a protected NuGet package publish workflow.
Parameters
RepositoryRootRepository root used for plan resolution.ManifestPathChecked-in package manifest path.ArtifactsInputPathDirectory containing validated.nupkgfiles.ArtifactManifestPathMachine-readable artifact manifest path.PublishLogPathMarkdown publish ledger path.SourceNuGet source URL.ApiKeyEnvironmentVariableEnvironment variable that supplies the NuGet API key.
PackageSmokeInstallRequest
SourceRequest for the post-publish smoke install and tool verification workflow.
Parameters
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.
PackageArtifactManifest
SourceMachine-readable artifact manifest that binds validated package artifacts to immutable hashes.
Parameters
SchemaVersionManifest schema version.PackageVersionExact stable or prerelease package version.GeneratedAtUtcUTC timestamp when the manifest was generated.EntriesManifest entries in package publish order.
PackageArtifactManifestEntry
SourceOne package artifact selected from the checked-in package manifest.
Parameters
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.ToolCommandNameValidated command shim token carried from the package index for tool smoke verification. The value must be empty whenIsToolisfalse. WhenIsToolistrue, it is required and must be the same single file-name-safe command token declared in the package indextool_command_namefield.
PackagePublishLedger
SourcePublish result for a coordinated package version.
Parameters
PackageVersionExact stable or prerelease package version.SourceNuGet source URL.EntriesPer-package publish outcomes.
PackagePublishLedgerEntry
SourcePublish outcome for one package artifact.
Parameters
PackageIdNuGet package id.ProjectPathRepository-relative project path.ArtifactFileNamePackage artifact file name.StatusPublish status.ExitCodeExit code fromdotnet nuget push, or zero for skipped packages.OutputCaptured publish output with secrets excluded.
PackageSmokeInstallReport
SourceSmoke install result for packages restored and tools verified after package publishing.
Parameters
PackageVersionExact stable or prerelease package version.SourceNuGet source URL.EntriesPer-package smoke install outcomes.
PackageSmokeInstallReportEntry
SourceSmoke install outcome for one public package or tool.
Parameters
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 command attempt.OutputCaptured restore, install, or command output.
PackageHash
SourceComputes package artifact hashes for manifest generation and publish verification.
PackageArtifactJson
SourceJSON serializer options shared by artifact manifest readers and writers.
ReleaseEnvironment
SourceEnvironment variables that make release automation quieter and deterministic.
PackagePublishDecisionFormatter
SourceFormats package publish decisions for machine-readable release artifacts.
PackageArtifactManifestPlanValidator
SourceVerifies that an artifact manifest still matches the checked-in package plan and validated artifacts.
PlannedPackageArtifact
SourcePackage artifact that has been matched to both the checked-in plan and artifact manifest.
Parameters
ManifestEntryManifest entry for the artifact.ArtifactPathResolved artifact path on disk.
PackagePublishStatus
SourcePublish status values written to the protected publish ledger.
PackageSmokeInstallStatus
SourceSmoke install status values written to the smoke report.
PackageArtifactWorkflow
SourceCoordinates package artifact packing and validation without publishing to NuGet.
RunAsync
Task<PackageArtifactValidationReport> RunAsync(PackageArtifactRequest request, CancellationToken cancellationToken = default)
Source
Packs and validates package artifacts.
Parameters
requestArtifact workflow request.cancellationTokenCancellation token propagated to external commands and file writes.
Returns
Successful validation report.
PackageArtifactRequest
SourceRequest for package artifact packing and validation.
Parameters
RepositoryRootAbsolute repository root.ManifestPathAbsolute package manifest path.ArtifactsOutputPathDirectory that receives produced.nupkgartifacts.ReportPathMarkdown validation report path.PackageVersionExact stable or prerelease package version to pack and validate. SemVer build metadata such as1.2.3+shais rejected because NuGet strips it from package identity.ArtifactManifestPathMachine-readable validation manifest path for the publish workflow.CoverageProofWorkDirectoryIsolated work directory for the packaged coverage CLI consumer proof.CoverageProofReportPathStandalone markdown report path for the packaged coverage CLI consumer proof.SourceNuGet source used for third-party dependencies while first-party packages map to local artifacts.
ICoverageCliConsumerProofWorkflow
SourceRuns the pre-publish consumer proof for the packaged AppSurface coverage CLI.
RunAsync
Task<CoverageCliConsumerProofReport> RunAsync(CoverageCliConsumerProofRequest request, PackageArtifactValidationReport validationReport, CancellationToken cancellationToken)
Source
Installs the validated CLI artifact into an isolated fixture and exercises the public coverage commands.
Parameters
requestProof request with repository, artifact, work-directory, and package-source settings.validationReportValidated package artifact report that selects the CLI tool artifact.cancellationTokenCancellation token.
Returns
Structured proof report. Command and artifact failures are represented in the report.
CoverageCliConsumerProofWorkflow
SourceVerifies that the packed ForgeTrust.AppSurface.Cli works from a clean package-consumer project.
Remarks
The proof runs before package publication. It selects the already validated CLI .nupkg, installs it with a local-first NuGet configuration, creates a clean xUnit fixture, and executes coverage run, coverage merge, a passing coverage gate, and an intentionally failing coverage gate.
Pitfall: the failing gate is considered successful only when the command exits non-zero and still writes coverage-gate.json and coverage-gate.md. This preserves the CLI contract that failures are visible in local diagnostics rather than only in the process exit code.
SelectCliToolPackage
CoverageCliConsumerProofSelectedArtifact SelectCliToolPackage(PackageArtifactValidationReport report, string packageVersion)
Source
Selects the validated ForgeTrust.AppSurface.Cli tool package that the consumer proof installs.
Parameters
reportPackage artifact validation report produced from the just-packed local artifacts.packageVersionExact package version that must be represented by the selected.nupkg.
Returns
Selected CLI package metadata plus a SHA-512 hash for diagnostics.
Exceptions
PackageIndexExceptionThrown when the validated report is missing the CLI package, contains more than one CLI row, marks it as a non-tool package, uses the wrong command name, points at a missing artifact, or points at a different version.
Remarks
The proof intentionally selects from the validation report instead of globbing the artifact directory so package publication cannot silently test an unvalidated file.
RenderMappedNuGetConfig
string RenderMappedNuGetConfig(string localSource, string nugetOrgSource)
Source
Renders the NuGet config used for local tool installation.
Parameters
localSourceDirectory containing locally packed AppSurface and RazorWire package artifacts.nugetOrgSourceNuGet source used for third-party dependency resolution.
Returns
NuGet configuration XML with package-source mapping.
Remarks
AppSurface and RazorWire package ids are mapped to the local artifact source with more-specific package patterns; the * mapping on the public source remains available for third-party dependencies such as xUnit and Coverlet. Keep this config separate from the fixture config so the consumer fixture itself does not restore first-party packages from local artifacts accidentally.
RenderNuGetOrgOnlyConfig
string RenderNuGetOrgOnlyConfig(string nugetOrgSource)
Source
Renders the NuGet config used by the generated consumer fixture for test-only dependencies.
Parameters
nugetOrgSourceNuGet source used bydotnet new xunitanddotnet add package coverlet.msbuild.
Returns
NuGet configuration XML containing only the supplied third-party source.
Remarks
This config deliberately excludes the local package artifact directory so the fixture exercises the packed CLI only through the local tool manifest installation path.
PrepareWorkDirectory
void PrepareWorkDirectory(string workDirectory, string repositoryRoot, string artifactsDirectory)
Source
Deletes and recreates the isolated coverage proof workspace after rejecting unsafe deletion targets.
Parameters
workDirectoryWorkspace that may be recursively deleted and recreated.repositoryRootRepository root that must not be deleted or contained by the work directory.artifactsDirectoryPackage artifact directory that must not be deleted or contained by the work directory.
Exceptions
PackageIndexExceptionThrown whenworkDirectoryis a filesystem root, the repository root, the artifact directory, the user's home directory, or a parent of the repository or artifact directory.
Remarks
All compared paths are normalized and trailing directory separators are trimmed before comparison. This prevents bypasses such as passing the repository root with a trailing slash before the recursive delete runs.
CoverageCliConsumerProofRequest
SourceRequest for the packaged coverage CLI consumer proof.
Parameters
RepositoryRootRepository root used for safety checks and reproduction instructions.ArtifactsDirectoryDirectory containing locally packed package artifacts.PackageVersionExact stable or prerelease package version under proof.WorkDirectoryIsolated proof workspace that can be deleted and recreated.SourceNuGet source for third-party dependencies.
CoverageCliConsumerProofSelectedArtifact
SourceSelected CLI artifact metadata captured before running the consumer proof.
Parameters
PackageIdSelected package id.ProjectPathProject that produced the artifact.ArtifactPathValidated local.nupkgpath.ToolCommandNameCommand shim expected after tool installation.Sha512SHA-512 hash of the selected artifact.
CoverageCliConsumerProofReport
SourceStructured packaged coverage CLI proof report.
Parameters
PackageVersionExact package version under proof.WorkDirectoryProof workspace path.SourceNuGet source used for third-party dependencies.SelectedArtifactSelected CLI artifact, if package selection succeeded.ToolNuGetConfigPathNuGet config used for tool installation.FixtureNuGetConfigPathNuGet config used for fixture dependencies.LogsDirectoryDirectory containing per-command stdout/stderr logs.CommandsExecuted command ledger.ArtifactsProduced and missing artifact checks.FirstFailureFirst failure summary, or empty when the proof passed.ReproduceCommandCommand that reruns the package verifier with the same proof workspace.
Succeeded
bool Succeeded { get; }
Source
Gets whether every command and artifact check matched the expected consumer contract.
CoverageCliConsumerProofCommandResult
SourceOne external command in the packaged coverage CLI proof ledger.
Parameters
OperationNameHuman-readable operation name.FileNameExecutable path or command name.ArgumentsCommand arguments.WorkingDirectoryCommand working directory.ExitCodeProcess exit code.ExpectedNonZeroExitCodeWhether a non-zero exit code was the expected outcome.SucceededWhether the command matched the expected exit-code contract.FailureReasonFailure details when the command did not match the expected contract.DurationMeasured command duration.StandardOutputPathPath where stdout was written.StandardErrorPathPath where stderr was written.StandardOutputCaptured stdout excerpt source.StandardErrorCaptured stderr excerpt source.
CoverageCliConsumerProofArtifactCheck
SourceOne artifact expected from the packaged coverage CLI consumer proof.
Parameters
DescriptionArtifact role.PathExpected or produced artifact path.ExistsWhether the artifact exists.
CoverageCliConsumerProofContext
SourceRuntime paths shared across the packaged coverage CLI consumer proof.
Parameters
RequestOriginal proof request and caller-supplied paths.SelectedArtifactValidated CLI package artifact selected for local tool installation.FixtureDirectoryClean consumer repository where solution, test projects, and local tool manifest are created.LogsDirectoryDirectory for per-command stdout and stderr logs.ToolNuGetConfigPathNuGet configuration used only for installing the AppSurface local tool package.FixtureNuGetConfigPathNuGet configuration used by the consumer fixture for third-party test dependencies.SharedPackagesPathIsolated global packages cache for all proof commands.DotNetHomePathIsolated .NET CLI home used to avoid host-machine state.
CoverageCliConsumerProofReportRenderer
SourceRenders packaged coverage CLI consumer proof reports for package validation artifacts.
RenderMarkdown
string RenderMarkdown(CoverageCliConsumerProofReport report)
Source
Renders a standalone markdown report.
Parameters
reportProof report.
Returns
Markdown report.
RenderSection
void RenderSection(StringBuilder builder, CoverageCliConsumerProofReport report)
Source
Appends the proof section to a larger package validation report.
Parameters
builderDestination markdown builder.reportProof report.
Program
SourceCLI entry point for generating or verifying the package chooser and maintainer readiness dashboard.
Main
Task<int> Main(string[] args)
Source
Launches the package chooser CLI with the current process IO streams and working directory.
Parameters
argsCommand-line arguments supplied to the process.
Returns
Process exit code where 0 indicates success.
RunAsync
Task<int> RunAsync(string[] args, TextWriter standardOut, TextWriter standardError, string currentDirectory, CancellationToken cancellationToken = default, Func<PackageArtifactRequest, CancellationToken, Task<PackageArtifactValidationReport>>? verifyPackagesAsync = null, Func<PackagePublishRequest, CancellationToken, Task<PackagePublishLedger>>? publishPrereleaseAsync = null, Func<PackagePublishRequest, CancellationToken, Task<PackagePublishLedger>>? publishStableAsync = null, Func<PackageSmokeInstallRequest, CancellationToken, Task<PackageSmokeInstallReport>>? smokeInstallAsync = null)
Source
Runs the package chooser CLI against the supplied IO streams and working directory.
Parameters
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.publishStableAsyncOptional stable publish workflow override used by tests.smokeInstallAsyncOptional smoke install workflow override used by tests.
Returns
0 when the command succeeds; otherwise a non-zero exit code.
CommandLineOptions
SourceParsed CLI options for a package-index command that may read and write package chooser and readiness dashboard outputs.
Parameters
RequestResolved package chooser manifest, chooser output, and readiness dashboard output 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.CoverageProofWorkDirectoryResolved packaged coverage CLI consumer proof work directory.CoverageProofReportPathResolved packaged coverage CLI consumer proof report 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.
Parse
CommandLineOptions Parse(string[] args, string currentDirectory)
Source
Parses path-related CLI options into a resolved chooser request.
Parameters
argsArguments after the command verb.currentDirectoryWorking directory used to resolve relative overrides.
Returns
The parsed command-line options.
Exceptions
PackageIndexExceptionThrown when an option is unknown or missing its required value.
CreatePackageArtifactRequest
PackageArtifactRequest CreatePackageArtifactRequest()
Source
Converts parsed CLI options into a package artifact request.
Returns
The package artifact request.
Exceptions
PackageIndexExceptionThrown when the required package version is missing.
CreatePackagePublishRequest
PackagePublishRequest CreatePackagePublishRequest()
Source
Converts parsed CLI options into a protected package publish request.
Returns
The package publish request.
CreatePackageSmokeInstallRequest
PackageSmokeInstallRequest CreatePackageSmokeInstallRequest()
Source
Converts parsed CLI options into a package smoke install request.
Returns
The package smoke install request.
PackageArtifactValidator
SourceValidates package artifacts against the resolved publish plan.
Validate
PackageArtifactValidationReport Validate(PackagePublishPlan plan, string artifactsDirectory, string packageVersion, string? repositoryRoot = null, PackagePayloadInventory? payloadInventory = null)
Source
Validates the package output directory and returns a markdown-ready report.
Parameters
planResolved package publish plan.artifactsDirectoryDirectory containing produced.nupkgfiles.packageVersionExact package version expected in every artifact.repositoryRootOptional repository root used to resolve source-path and version-source evidence when payload inventory validation is enabled.payloadInventoryOptional redistributed payload inventory to validate against the produced package artifacts.
Returns
A validation report for the inspected artifacts.
PackageArtifactReportRenderer
SourceRenders package artifact validation results for workflow artifacts.
RenderMarkdown
string RenderMarkdown(PackageArtifactValidationReport report, CoverageCliConsumerProofReport? coverageProofReport = null)
Source
Renders the validation report as markdown.
Parameters
reportValidation report to render.coverageProofReportOptional packaged coverage CLI proof details to append.
Returns
Markdown report content.
PackageVersionValidator
SourceEnsures package versions used by release workflows are safe for NuGet identity.
RequirePrerelease
void RequirePrerelease(string packageVersion)
Source
Validates that the package version is a prerelease SemVer identity without build metadata.
Parameters
packageVersionPackage version to validate.
Require
void Require(string packageVersion, PackageVersionPolicy policy)
Source
Validates a package version against the requested release classification policy.
Parameters
packageVersionPackage version to validate.policyVersion policy required by the calling workflow.
PackageArtifactValidationReport
SourceResult of a successful package artifact validation run.
Parameters
PackageVersionExact package version inspected.EntriesValidated package report rows.
PackageArtifactValidationReportEntry
SourceOne validated package row in the artifact report.
Parameters
PackageIdValidated package id.ProjectPathProject that produced the package.DecisionPublish decision from the manifest.ExpectedDependencyPackageIdsExpected same-version package dependency ids.ArtifactPathValidated.nupkgartifact path.IsToolWhether the package is a .NET tool package.ToolCommandNameValidated command shim token fromtool_command_name. It is empty for non-tool packages and required for tool packages so artifact reports show the exact command that publish smoke tests execute.PayloadResultsRedistributed package payload evidence rows validated for this package.SuspiciousPayloadCountNumber of suspicious package entries found in this artifact.CoveredSuspiciousPayloadCountNumber of suspicious package entries covered by notice or audit evidence.
PackagePayloadValidationResult
SourceOne redistributed package payload evidence row rendered into the artifact validation report.
Parameters
PackageIdPackage id whose artifact carried or embedded the payload evidence.RecordIdInventory record id frompackages/third-party-payloads.yml.ComponentOrRuleThird-party component name or audit rule shown to release reviewers.EvidenceKindEvidence type, such asnoticeorgenerated_first_party.StatusValidation status rendered for release evidence.PayloadEntriesPackage entries covered by this record.NoticePathsPackage notice paths checked by this record.VersionSourceRepository path or audit source that anchors the version/evidence.
InspectedPackage
SourceMetadata and payload facts inspected from one NuGet package artifact.
Parameters
PackagePathAbsolute or caller-supplied path to the inspected.nupkgfile.PackageIdNuspec package id. Expected to be non-empty after inspection.PackageVersionNuspec package version. Expected to be non-empty after inspection.AuthorsNuspec authors metadata, ornullwhen absent.DescriptionNuspec description metadata, ornullwhen absent.LicenseNuspec license expression or value, ornullwhen absent.ProjectUrlNuspec project URL, ornullwhen absent.RepositoryUrlNuspec repository URL, ornullwhen absent.TagsNuspec package tags, ornullwhen absent.ReadmeNuspec README path, ornullwhen absent.PackageTypesDeclared nuspec package type names such asDotnetTool.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.ToolCommandNamesCommand names declared by anyDotnetToolSettings.xmlfiles.ToolSettingsFilesTool command settings files with their package entry paths and declared commands.
InspectedToolSettingsFile
SourceTool command declarations found in one packaged DotnetToolSettings.xml file.
Parameters
EntryPathNormalized package entry path for the settings file.CommandNamesDistinct command names declared in the settings file.
InspectedAssemblyVersion
SourceInformational version metadata read from a first-party assembly inside a package artifact.
Parameters
EntryPathArchive path for the inspected assembly entry.InformationalVersionAssembly informational version value read from metadata.
PackageVersionPolicy
SourcePackage version policies used by release-classified package workflows.
PackagePublishPlanResolver
SourceResolves the checked-in package manifest into the exact package set that should be packed.
ResolveAsync
Task<PackagePublishPlan> ResolveAsync(string repositoryRoot, string manifestPath, CancellationToken cancellationToken)
Source
Resolves and validates the package publish plan.
Parameters
repositoryRootAbsolute repository root.manifestPathAbsolute path to the package manifest.cancellationTokenCancellation token used while loading metadata.
Returns
The ordered package publish plan.
PackagePublishPlan
SourceOrdered package set selected for artifact packing and validation.
Parameters
EntriesPackages that should be packed, in deterministic manifest order.
PackagePublishPlanEntry
SourceOne package selected for pack artifact production.
Parameters
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.ToolCommandNameValidated command shim token fromtool_command_name. It is empty for non-tool packages and required for tool packages so the pack/publish workflow can carry the exact command name into artifact validation and smoke tests.