IReadOnlyList<StableDocsPackageDependency> Dependencies { get; }
Source
Gets the approved parser and sanitizer package identities in reader-facing order.
CLI entry point for generating or verifying the package chooser and maintainer readiness dashboard.
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<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.
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.0 when the command succeeds; otherwise a non-zero exit code.
Parsed CLI options for a package-index command that may read and write package chooser and readiness dashboard outputs.
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.DocsProofWorkDirectoryResolved packed Docs consumer proof work directory.DocsProofReportPathResolved packed Docs 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.BaseRefOptional fetched base ref or commit used only by the release-preparation witness command.WitnessPathOptional explicit JSON witness destination used only by the release-preparation witness command.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.PackagePublishRequest CreatePackagePublishRequest()
Source
Converts parsed CLI options into a protected package publish request.
The package publish request.
PackageSmokeInstallRequest CreatePackageSmokeInstallRequest()
Source
Converts parsed CLI options into a package smoke install request.
The package smoke install request.
ReleasePreparationWitnessRequest CreateReleasePreparationWitnessRequest()
Source
Validates the dedicated read-only release-preparation witness options.
Resolved witness inputs.
PackageIndexExceptionThrown when either required witness option is absent.Resolved inputs for the read-only package release-preparation witness command.
RequestPackage-index generation request rooted at the checked-out repository.BaseRefFetched base ref or immutable base commit used to calculate the merge base.WitnessPathExplicit JSON output path, normally outside the repository.Defines the exact parser and sanitizer identities approved for stable AppSurface Docs packages.
This is the single source of truth for the stable-exit package contract tracked by issue #682. Package archive validation, isolated consumer graph verification, and generated proof guidance all consume these identities so a future dependency update cannot change one proof surface without changing the others.
string ExactVersionRange(StableDocsPackageDependency dependency)
Source
Gets the exact NuGet dependency declaration required for the supplied stable dependency.
dependencyApproved parser or sanitizer dependency.An exact bracketed NuGet version range.
IReadOnlyList<StableDocsPackageDependency> Dependencies { get; }
Source
Gets the approved parser and sanitizer package identities in reader-facing order.
string MarkdownDependencyList { get; }
Source
Gets the Markdown-formatted dependency list used in maintainer guidance.
string PlainTextDependencyList { get; }
Source
Gets a plain-text dependency list used in actionable diagnostics.
One approved stable Docs parser or sanitizer dependency identity.
IdNuGet package id.VersionExact resolved stable version.Validates the bounded Cobertura contract used by the packaged default-collector consumer proof.
This validator deliberately does not reuse the CLI's private project-slug allocator. The CLI emits one adjacent coverage-project.json manifest for every selected project; this reader binds the known consumer project to its sibling raw report, preserves that exact report into the merge input, and verifies retained semantic facts in the fan-in result. It is not a general Cobertura parser or an assertion about the MSBuild compatibility driver.
CoverageCliConsumerProofSemanticProof ValidateRaw(string coverageRunDirectory)
Source
Selects and validates the raw artifact belonging to the known default-collector fixture project.
coverageRunDirectoryThe default collector's coverage-run output directory.Raw selection, parsed semantic facts, and deterministic failures.
CoverageCliConsumerProofSemanticProof ValidateMerged(CoverageCliConsumerProofSemanticProof rawProof, string copiedShardPath, string mergedCoveragePath)
Source
Verifies the byte-preserved selected shard and independently validates the merged fan-in report.
rawProofThe result returned from ValidateRaw.copiedShardPathThe shard copied from the selected raw report into fan-in input.mergedCoveragePathThe merged Cobertura report produced by coverage merge.Raw and merged semantic proof with raw-first deterministic failure ordering.
Manifest-bound raw report selected for the packaged default-collector proof.
Public-safe outcome of one semantic coverage artifact validation stage.
Bounded semantic facts retained by the package proof. These are intentionally not raw XML.
One coded package coverage proof failure.
Complete semantic default-collector proof state, including a selected raw artifact when selection succeeded.
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.
Loads the redistributed package payload inventory used by verify-packages.
Task<PackagePayloadInventory> LoadAsync(string repositoryRoot, CancellationToken cancellationToken = default)
Source
Reads the repository-owned payload inventory from its default location.
repositoryRootAbsolute repository root used to resolve the inventory path.cancellationTokenCancellation token used while reading the file.The parsed redistributed payload inventory.
PackagePayloadInventory Parse(string content, string displayPath = DefaultRelativePath)
Source
Parses payload inventory YAML content.
contentYAML inventory content.displayPathPath shown in validation errors.The parsed inventory.
string ResolveInventoryPath(string repositoryRoot, string relativePath)
Source
Resolves the repository-relative payload inventory path under the repository root.
repositoryRootAbsolute repository root used to resolve the inventory path.relativePathRepository-relative inventory path.The absolute inventory path.
Repository-owned contract for redistributed package payload notice, audit, and generated evidence.
void Validate(string displayPath)
Source
Validates the parsed inventory shape before package-specific evidence checks run.
displayPathPath shown in validation errors.int SchemaVersion { get; init; }
Source
Gets the inventory schema version. Version 1 is the only supported v1 contract.
List<PackagePayloadNoticeRecord> Notices { get; init; }
Source
Gets third-party payload declarations that require package notices and provenance evidence.
List<PackagePayloadAuditRecord> Audits { get; init; }
Source
Gets narrow audit records for generated-first-party or otherwise non-notice payload evidence.
Third-party redistributed payload evidence that requires package notice coverage.
string Id { get; init; }
Source
Gets the stable inventory record id.
string PackageId { get; init; }
Source
Gets the package id that must contain the declared payload.
string Component { get; init; }
Source
Gets the redistributed component name shown in package reports.
string Version { get; init; }
Source
Gets the redistributed component version.
string License { get; init; }
Source
Gets the redistributed component license expression or short name.
string SourceUrl { get; init; }
Source
Gets the upstream source or project URL for maintainer review.
List<string> PayloadPatterns { get; init; }
Source
Gets package entry glob patterns that identify the redistributed payload.
List<string> NoticePaths { get; init; }
Source
Gets package entry paths that must contain the third-party notice text.
List<string> Markers { get; init; }
Source
Gets marker strings that must appear in at least one notice file.
List<string> SourcePaths { get; init; }
Source
Gets optional source files that must exist in the repository for this evidence.
string? VersionSourcePath { get; init; }
Source
Gets an optional repository file whose content must contain VersionSourceContains.
string? VersionSourceContains { get; init; }
Source
Gets text that must appear in VersionSourcePath when the source is deterministic.
Audit evidence for package payloads that are generated-first-party or otherwise not third-party notice records.
string Id { get; init; }
Source
Gets the stable inventory record id.
string PackageId { get; init; }
Source
Gets the package id covered by this audit record.
List<string> AppliesTo { get; init; }
Source
Gets package entry glob patterns or evidence labels covered by this audit.
string? MatchedRule { get; init; }
Source
Gets the suspicious classifier rule or evidence class that caused this audit.
string EvidenceKind { get; init; }
Source
Gets the audit evidence type, such as generated_first_party.
List<string> SourcePaths { get; init; }
Source
Gets repository source paths that must exist for this audit to stay valid.
List<string> GeneratedPaths { get; init; }
Source
Gets generated repository paths that must exist for generated-first-party evidence.
string Reason { get; init; }
Source
Gets the human-readable reason this record is not a third-party notice declaration.
string ReviewedOn { get; init; }
Source
Gets the date or versioned source used for the audit review.
string Source { get; init; }
Source
Gets the reviewer, source document, or script that established this audit.
string RevalidateWhen { get; init; }
Source
Gets the event that must force revalidation of the audit.
Renders the finite package README release-guidance variants declared by the package manifest.
The renderer owns only the explicit marker region in a package README. It deliberately does not normalize or infer package-specific documentation outside that region, so operational and adoption guidance stays authored by the package owner. See tools/ForgeTrust.AppSurface.PackageIndex/README.md#release-guidance for the maintainer workflow and recovery commands.
Task<IReadOnlyList<ReleaseGuidanceUpdate>> CreateUpdatesAsync(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries, CancellationToken cancellationToken = default)
Source
Builds the complete, validated set of package README replacements without writing any files.
repositoryRootRepository root that contains the manifest-selected package README files.entriesResolved manifest entries whose documentation targets have already passed path validation.cancellationTokenCancellation token used while reading the template and README files.All managed README updates, including no-op updates used by verification.
PackageIndexExceptionThrown when the finite variant, template, marker, or README contract is invalid.Task<int> ApplyUpdatesAsync(IReadOnlyList<ReleaseGuidanceUpdate> updates, CancellationToken cancellationToken = default)
Source
Replaces validated generated documents and managed README regions using sibling staging files and ordinary-failure rollback.
updatesFully rendered generated-file and README updates created before the first target write.cancellationTokenCancellation token used while staging replacement content.The number of target files changed.
Staging makes malformed input fail before target replacement begins. A rollback journal restores targets if a normal replacement fails. Before each replacement, the target is re-read and must match the initial snapshot. A process or machine crash cannot be made globally atomic; verify detects resulting drift and reports the repository command that repairs it.
void VerifyUpdates(IReadOnlyList<ReleaseGuidanceUpdate> updates)
Source
Verifies every managed README is already identical to the current rendered release-guidance variant.
updatesFully rendered README updates created without writing files.PackageIndexExceptionThrown when any managed README is stale.string ExtractManagedRegionBody(string content, string displayPath)
Source
Extracts the body owned by the release-guidance marker pair without rewriting the README.
contentComplete README content.displayPathRepository-relative README path used in actionable failures.The exact bytes between the ordered marker lines, including their line endings.
PackageIndexExceptionThrown when the README does not contain exactly one ordered marker pair.Release-preparation provenance verification uses this method to bind a changed README only to the generated region. It intentionally preserves line endings and does not trim whitespace: a hash of this value must prove the exact generated body that will be committed.
Describes one rendered package README policy region without changing the checked-in file.
Coordinates package artifact packing and validation without publishing to NuGet.
Task<PackageArtifactValidationReport> RunAsync(PackageArtifactRequest request, CancellationToken cancellationToken = default)
Source
Packs and validates package artifacts.
requestArtifact workflow request.cancellationTokenCancellation token propagated to external commands and file writes.Successful validation report.
void TryDeleteProofWorkspace(string proofWorkDirectory, Func<string, bool> directoryExists, Action<string> deleteDirectory)
Source
Deletes a temporary proof workspace and tolerates cleanup failures after proof evidence has been published.
proofWorkDirectoryTemporary workspace to delete.directoryExistsDirectory existence probe.deleteDirectoryRecursive directory deletion operation.Task WriteCoverageProofEvidenceAsync(string evidencePath, string contents, string trustedRootDirectory, CancellationToken cancellationToken, Action<string>? temporaryFileCreated = null)
Source
Atomically publishes scrubbed coverage proof evidence without following an existing symbolic-link destination.
evidencePathFinal evidence path below the trusted artifact output directory.contentsAlready-scrubbed JSON payload.trustedRootDirectoryRegular artifact output directory that bounds every evidence directory component.cancellationTokenCancellation token for temporary-file creation.temporaryFileCreatedOptional narrow test seam invoked after the temporary file is closed and before the destination is replaced.A task that completes after the temporary file has replaced a regular destination.
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 stable or prerelease package version to pack and validate. SemVer build metadata such as 1.2.3+sha is 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.DocsProofWorkDirectoryIsolated work directory for the packed Docs consumer proof.DocsProofReportPathStandalone markdown report path for the packed Docs consumer proof.SourceNuGet source used for third-party dependencies while first-party packages map to local artifacts.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.ToolCommandNameValidated command shim token from tool_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.ReadinessBlockerMaintainer blocker that prevents publishing the coordinated artifact set while still allowing artifacts to be packed and validated.ReleaseGuidanceVariantFinite package README release-guidance variant whose canonical absolute links must survive package packing. It is empty for package entries without a managed release-guidance region.Safely recreates isolated package-consumer proof workspaces.
void RequireDisjoint(string firstDirectory, string secondDirectory)
Source
Requires two package-consumer proof workspaces to be disjoint before either is recreated.
firstDirectoryFirst proof workspace.secondDirectorySecond proof workspace.PackageIndexExceptionThrown when either workspace is the other workspace or one contains the other.void Prepare(string workDirectory, string repositoryRoot, string artifactsDirectory)
Source
Deletes and recreates an isolated package-consumer proof workspace after rejecting unsafe deletion targets.
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.PackageIndexExceptionThrown when workDirectory is a filesystem root, the repository root, the artifact directory, the user's home directory, a non-artifact directory inside the repository, or a parent of the repository or artifact directory.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. A repository-local proof workspace is allowed only beneath the configured artifact directory, which preserves the default proof layout without allowing cleanup to remove source or Git metadata.
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 package artifact set to NuGet in manifest order.
Task<PackagePublishLedger> RunAsync(PackagePublishRequest 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 and verifies published .NET tools from a clean NuGet configuration after publish completes.
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.
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.Smoke install report. Non-tool package entries share the aggregate restore result; tool entries report independent install and command-help results.
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.
string ResolveToolShimPath(string toolPath, string commandName)
Source
Resolves the installed tool shim path after proving the shim name cannot escape the tool directory.
toolPathDirectory passed to dotnet tool install --tool-path.commandNameValidated command token from tool_command_name.Full path to the command shim that should be executed.
ArgumentExceptionThrown when the command token cannot safely be treated as one file name under toolPath.Renders protected publish outcomes for workflow artifacts.
Renders package smoke install outcomes for workflow artifacts.
Request for a protected NuGet package 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 and tool verification 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 stable or 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.ToolCommandNameValidated command shim token carried from the package index for tool smoke verification. The value must be empty when IsTool is false. When IsTool is true, it is required and must be the same single file-name-safe command token declared in the package index tool_command_name field.Publish result for a coordinated package version.
PackageVersionExact stable or 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 and tools verified after package publishing.
PackageVersionExact stable or prerelease package version.SourceNuGet source URL.EntriesPer-package smoke install outcomes.Smoke install outcome for one public package or tool.
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.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.
Validates package artifacts against the resolved publish plan.
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.
planResolved package publish plan.artifactsDirectoryDirectory containing produced .nupkg files.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.A validation report for the inspected artifacts.
byte[] ReadPackageEntryBytes(string packagePath, string entryPath, string packageId)
Source
Reads the bytes of a required package archive entry.
packagePathPath to the package archive.entryPathRepository-style path of the required archive entry.packageIdPackage identifier used in a validation failure message.The archive entry bytes.
PackageIndexExceptionThrown when the archive does not contain the required entry or its uncompressed contents exceed the validation limit.Renders package artifact validation results for workflow artifacts.
string RenderMarkdown(PackageArtifactValidationReport report, CoverageCliConsumerProofReport? coverageProofReport = null, DocsPackageConsumerProofReport? docsProofReport = null)
Source
Renders the validation report as markdown.
reportValidation report to render.coverageProofReportOptional packaged coverage CLI proof details to append.docsProofReportOptional packed Docs consumer proof details to append.Markdown report content.
Ensures package versions used by release workflows 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.void Require(string packageVersion, PackageVersionPolicy policy)
Source
Validates a package version against the requested release classification policy.
packageVersionPackage version to validate.policyVersion policy required by the calling workflow.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.ToolCommandNameValidated command shim token from tool_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.One redistributed package payload evidence row rendered into the artifact validation report.
PackageIdPackage id whose artifact carried or embedded the payload evidence.RecordIdInventory record id from packages/third-party-payloads.yml.ComponentOrRuleThird-party component name or audit rule shown to release reviewers.EvidenceKindEvidence type, such as notice or generated_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.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.ProjectUrlNuspec project URL, 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.DependencyContainersRaw nuspec dependency containers retained in document order for package-specific validation.HasMixedRootAndGroupsWhether the nuspec declares both root dependencies and target-framework groups.EntryPathsNormalized archive entry paths contained in the package.FirstPartyAssemblyVersionsFirst-party implementation assemblies and their informational versions.ToolCommandNamesCommand names declared by any DotnetToolSettings.xml files.ToolSettingsFilesTool command settings files with their package entry paths and declared commands.One dependency container preserved from a package nuspec.
LabelDeterministic label used in diagnostics.TargetFrameworkRaw target framework value for a group, or null for root dependencies.IsGroupWhether this container originated from a nuspec group element.DependenciesRaw dependency occurrences in source order.One raw dependency occurrence preserved from a package nuspec.
IdRaw dependency id, or null when omitted.VersionRaw dependency version, or null when omitted.Dependency-container facts collected from a package nuspec.
ContainersContainers in declaration order.HasMixedRootAndGroupsWhether root dependencies and groups coexist.One stable Docs dependency-contract violation.
ContainerLabelDependency container label.DependencyIdRequired dependency or metadata field.ObservedObserved artifact value.ExpectedExact required value.Tool command declarations found in one packaged DotnetToolSettings.xml file.
EntryPathNormalized package entry path for the settings file.CommandNamesDistinct command names declared in the settings file.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.Package version policies used by release-classified package workflows.
Runs the pre-publish consumer proof for the packaged AppSurface CLI.
Task<CoverageCliConsumerProofReport> RunAsync(CoverageCliConsumerProofRequest request, PackageArtifactValidationReport validationReport, CancellationToken cancellationToken)
Source
Installs the validated CLI artifact into an isolated fixture and exercises public release-note, coverage, and canary-poll commands.
requestProof request with repository, artifact, work-directory, and package-source settings.validationReportValidated package artifact report that selects the CLI tool artifact.cancellationTokenCancellation token.Structured proof report. Command and artifact failures are represented in the report.
Verifies that the packed ForgeTrust.AppSurface.Cli works from a clean package-consumer project.
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 plus an excluded failing sentinel, composes one consumer-owned release note, and executes coverage run, coverage merge, a passing coverage gate, a patch-target gate plus nonpatch stale-target cleanup, an intentionally failing coverage gate, and canary poll --help, then runs the packed command against a local protected fixture for one pass and one stale result to prove its environment-only credential and operator-result paths are packed.
Pitfall: the failing gate is considered successful only when the command exits non-zero and still writes coverage-gate.json and coverage-gate.md. The patch-target gate separately proves the target JSON and Markdown contract. This preserves the CLI contract that failures are visible in local diagnostics rather than only in the process exit code.
CoverageCliConsumerProofSelectedArtifact SelectCliToolPackage(PackageArtifactValidationReport report, string packageVersion)
Source
Selects the validated ForgeTrust.AppSurface.Cli tool package that the consumer proof installs.
reportPackage artifact validation report produced from the just-packed local artifacts.packageVersionExact package version that must be represented by the selected .nupkg.Selected CLI package metadata plus a SHA-512 hash for diagnostics.
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.The proof intentionally selects from the validation report instead of globbing the artifact directory so package publication cannot silently test an unvalidated file.
string RenderMappedNuGetConfig(string localSource, string nugetOrgSource)
Source
Renders the NuGet config used for local tool installation.
localSourceDirectory containing locally packed AppSurface and RazorWire package artifacts.nugetOrgSourceNuGet source used for third-party dependency resolution.NuGet configuration XML with package-source mapping.
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.
string RenderNuGetOrgOnlyConfig(string nugetOrgSource)
Source
Renders the NuGet config used by the generated consumer fixture for test-only dependencies.
nugetOrgSourceNuGet source used by dotnet new xunit and the Coverlet collector/MSBuild fixture packages.NuGet configuration XML containing only the supplied third-party source.
This config deliberately excludes the local package artifact directory so the fixture exercises the packed CLI only through the local tool manifest installation path.
Provides a protected named-canary fixture through a loopback HTTP server.
CanaryProofFixture Start()
Source
Starts and returns a newly initialized loopback canary fixture.
ValueTask DisposeAsync()
Source
Stops the loopback server and releases the fixture's resources.
string BaseUrl { get; }
Source
Gets the loopback HTTP server URL used by the packaged CLI proof.
int ValidRequestCount { get; }
Source
Gets the number of fully valid requests accepted by the loopback server.
Request for the packaged coverage CLI consumer proof.
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.Selected CLI artifact metadata captured before running the consumer proof.
PackageIdSelected package id.ProjectPathProject that produced the artifact.ArtifactPathValidated local .nupkg path.ToolCommandNameCommand shim expected after tool installation.Sha512SHA-512 hash of the selected artifact.Structured packaged coverage CLI proof report.
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.SemanticProofManifest-bound default-collector raw-to-merged semantic proof.bool Succeeded { get; }
Source
Gets whether every command and artifact check matched the expected consumer contract.
One external command in the packaged coverage CLI proof ledger.
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.One artifact expected from the packaged coverage CLI consumer proof.
DescriptionArtifact role.PathExpected or produced artifact path.ExistsWhether the artifact exists.Runtime paths shared across the packaged coverage CLI consumer proof.
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.Renders packaged coverage CLI consumer proof reports for package validation artifacts.
string RenderMarkdown(CoverageCliConsumerProofReport report)
Source
Renders a standalone markdown report.
reportProof report.Markdown report.
void RenderSection(StringBuilder builder, CoverageCliConsumerProofReport report)
Source
Appends the proof section to a larger package validation report.
builderDestination markdown builder.reportProof report.Runs the pre-publish restore proof for the packed AppSurface Docs package.
Task<DocsPackageConsumerProofReport> RunAsync(DocsPackageConsumerProofRequest request, PackageArtifactValidationReport validationReport, CancellationToken cancellationToken)
Source
Restores the validated Docs package from local artifacts in a clean consumer project and verifies its resolved graph.
requestProof paths, package version, and third-party package source.validationReportValidated artifacts produced by the package artifact workflow.cancellationTokenCancellation token.A structured report containing command and graph-verification evidence.
Proves that a clean package consumer resolves the packed Docs artifact and the reviewed stable parser and sanitizer graph.
The generated consumer is intentionally independent of the repository Docs consumer fixture, which uses project references. It has its own package lock file and configuration with a local-only mapping for first-party packages. The public source is restricted to the exact non-first-party package ids represented by the committed locks for the validated Docs first-party closure, so a newly published or unintended first-party package cannot satisfy the restore. Empty local Directory.Build.props and Directory.Build.targets files also prevent repository-wide build policy from affecting the generated consumer.
The proof does not build an application: restoring and inspecting project.assets.json is the relevant package contract. It confirms that Docs, AngleSharp, AngleSharp.Css, and HtmlSanitizer resolve as packages at their exact expected versions.
DocsPackageConsumerProofSelectedArtifact SelectDocsPackage(PackageArtifactValidationReport report, string packageVersion)
Source
Selects the validated Docs artifact that the consumer proof restores.
reportValidation report produced from the just-packed artifact directory.packageVersionExact package version expected in the selected artifact file name.The selected artifact and its SHA-512 hash.
PackageIndexExceptionThrown when the report does not contain exactly one existing Docs package artifact matching packageVersion.string RenderConsumerDirectoryPackagesProps()
Source
Renders the isolated consumer's central package-management boundary.
Props that disable inherited central package management and enable the consumer lock file.
string RenderConsumerProject(string packageVersion)
Source
Renders the clean package consumer project.
packageVersionExact Docs package version to restore.Consumer project XML.
string RenderMappedNuGetConfig(string localSource, string nugetOrgSource, IEnumerable<string> thirdPartyPackageIds)
Source
Renders source mapping that permits first-party packages only from local artifacts and enumerates allowed public packages.
localSourceDirectory containing freshly packed first-party artifacts.nugetOrgSourceSource used for reviewed third-party package identities.thirdPartyPackageIdsExact third-party package ids allowed from the public source.NuGet configuration XML with package-source mapping.
ArgumentExceptionThrown when no third-party package ids are supplied or an id is a package-source mapping pattern.IReadOnlyList<string> ReadPackedDocsThirdPartyPackageIds(string repositoryRoot, PackageArtifactValidationReport validationReport)
Source
Reads the public package identities for the validated, packed Docs first-party closure.
repositoryRootRepository root that contains the committed lock files for packed first-party projects.validationReportValidated package report that establishes the first-party package closure.Sorted, deduplicated third-party package ids.
PackageIndexExceptionThrown when the report does not contain the complete Docs closure, or a required committed lock file is absent or malformed.The traversal follows the validator-confirmed first-party dependency graph from Docs and scans each participating project's lock file for package entries. This captures public dependencies introduced by packed first-party packages (for example Microsoft.Extensions.*) that do not appear in the Docs project's source-only lock graph.
IReadOnlyList<string> ReadThirdPartyPackageIdsFromLockFile(string lockFilePath)
Source
Reads package (not project) identities from one committed project lock file.
lockFilePathCommitted lock file path.Third-party package identities represented by lock entries.
PackageIndexExceptionThrown when the lock file is absent or malformed.DocsPackageConsumerGraphVerification VerifyConsumerGraph(string assetsFilePath, string lockFilePath, string packageVersion)
Source
Inspects a generated consumer's assets and lock files for the packed Docs package and stable dependency graph.
assetsFilePathGenerated project.assets.json path.lockFilePathGenerated consumer lock file path.packageVersionExpected Docs package version.Verified resolved package identities and paths.
PackageIndexExceptionThrown when either generated input is absent, malformed, or resolves a wrong package identity.Request for an isolated packed Docs consumer restore proof.
RepositoryRootRepository root used for safety checks and lock-graph discovery.ArtifactsDirectoryDirectory containing freshly validated local package artifacts.PackageVersionExact Docs package version under proof.WorkDirectoryIsolated work directory that can be deleted and recreated.SourcePublic source used only for reviewed third-party package ids.Identity and hash of the validated Docs artifact selected for consumer restore.
PackageIdDocs package id.ProjectPathProject that produced the selected artifact.ArtifactPathValidated local package artifact path.Sha512Base64 SHA-512 hash of the selected artifact.One resolved package identity verified in the generated consumer's assets graph.
IdPackage id.VersionExact resolved package version.Structural proof that the generated consumer resolved all required package identities.
AssetsFilePathGenerated NuGet assets file inspected by the proof.LockFilePathGenerated consumer lock file verified in locked mode.ResolvedPackagesDocs and parser/sanitizer package identities verified as packages.One command in the packed Docs consumer proof ledger.
OperationNameHuman-readable operation name.FileNameExecutable name.ArgumentsCommand arguments.WorkingDirectoryCommand working directory.ExitCodeObserved exit code.SucceededWhether the command exited successfully.FailureReasonFailure details when the command did not succeed.DurationMeasured command duration.StandardOutputPathCaptured stdout log path.StandardErrorPathCaptured stderr log path.StandardOutputCaptured stdout.StandardErrorCaptured stderr.Structured evidence emitted by the packed Docs consumer proof.
PackageVersionExact Docs package version under proof.WorkDirectoryIsolated proof workspace.SourcePublic package source.SelectedArtifactValidated Docs package selected for restore.NuGetConfigPathGenerated source-mapping configuration.ConsumerProjectPathGenerated consumer project.ConsumerLockFilePathGenerated consumer lock file.AssetsFilePathGenerated consumer assets file.ThirdPartyPackageIdsExact third-party package ids permitted from the public source.LogsDirectoryCommand stdout and stderr log directory.CommandsCommand ledger.GraphVerificationResolved graph evidence, when restore and inspection succeeded.FirstFailureFirst failure, or empty when proof succeeded.ReproduceCommandCommand that reruns the package verifier with the same proof directory.DocsPackageConsumerProofReport Failed(string packageVersion, string workDirectory, string source, string firstFailure, DocsPackageConsumerProofSelectedArtifact? selectedArtifact = null)
Source
Builds a report for failures that occur before the proof workspace is fully initialized.
packageVersionPackage version under proof.workDirectoryRequested proof directory.sourceRequested public source.firstFailureFailure message.selectedArtifactSelected artifact, if selection already succeeded.Failed proof report.
bool Succeeded { get; }
Source
Gets whether every command and graph verification succeeded.
Renders packed Docs consumer proof evidence for standalone and aggregate package reports.
string RenderMarkdown(DocsPackageConsumerProofReport report)
Source
Renders a standalone markdown report.
reportProof report.Markdown content.
void RenderSection(StringBuilder builder, DocsPackageConsumerProofReport report)
Source
Appends proof evidence to an aggregate package report.
builderDestination markdown builder.reportProof report.Runtime paths and inputs shared by the packed Docs consumer proof.
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<PackageIndexGenerationReport> GenerateToFileAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates package chooser and readiness dashboard markdown, then reconciles the managed release-guidance region in every qualifying package README.
requestGeneration request describing the repository root, manifest path, chooser output, and readiness output.cancellationTokenCancellation token used for manifest loading, metadata evaluation, and file writes.A report describing the generated package-index documents and managed README reconciliation.
PackageIndexExceptionThrown when the repository layout is invalid, required docs are missing, or the manifest cannot be rendered safely.This method stages the generated markdown payloads and all managed README replacements before replacing any target. An ordinary replacement failure rolls back every prior replacement, and a target that changed after its initial read is rejected rather than overwritten. It creates output directories when they do not already exist.
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<PackageIndexDocuments> GenerateDocumentsAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Generates the package chooser and package-index evidence dashboard without writing either file to disk.
requestGeneration request describing repository inputs and output path contexts.cancellationTokenCancellation token used while loading the manifest and project metadata.Generated chooser and readiness markdown payloads.
PackageIndexDocuments GenerateDocuments(PackageIndexRequest request, IReadOnlyList<ResolvedPackageEntry> entries)
Source
Renders the package chooser and readiness documents from entries already resolved for the same request.
requestGeneration request that supplies output and repository context.entriesCanonical entries resolved by ResolveGenerationEntriesAsync.In-memory document content without reading or writing repository files.
Task VerifyAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)
Source
Verifies that the checked-in chooser and readiness dashboard files match the current repository truth.
requestVerification request describing the repository root, manifest path, and generated files.cancellationTokenCancellation token used while regenerating and reading the existing generated files.A task that completes when verification succeeds.
PackageIndexExceptionThrown when either generated file is missing or differs from 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.Task<IReadOnlyList<ResolvedPackageEntry>> ResolveGenerationEntriesAsync(PackageIndexRequest request, CancellationToken cancellationToken)
Source
Resolves the validated package entries used by every canonical package-index rendering path.
This is exposed internally so read-only provenance consumers can reuse the exact renderer inputs instead of reconstructing manifest or project metadata rules.
void ValidateWebPackageQuickstartTarget(string repositoryRoot)
Source
Validates that the package-first chooser link resolves to the quickstart file and section anchor.
repositoryRootRepository root that contains the Start Here quickstart.PackageIndexExceptionThrown when the quickstart file is missing or no heading or explicit anchor produces the expected fragment target.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.
PackageReleaseLink ResolveReleaseLink(PackageManifestEntry entry)
Source
Resolves the package's release documentation link from its manifest fields.
entryPackage manifest entry to validate.A normalized release-link contract.
Keep this thin adapter around the shared resolver so package-index diagnostics retain the project path that a maintainer can correct. Callers must still validate that the resulting repository-relative file exists.
void ValidateToolCommandName(PackageManifestEntry entry, PackageProjectMetadata metadata)
Source
Validates the manifest command-name contract against project metadata for one package row.
entryManifest row that may declare tool_command_name and a publish decision.metadataEvaluated project metadata that reports whether the project packs as a .NET tool.PackageIndexExceptionThrown when a tool selected for PackagePublishDecision.Publish or PackagePublishDecision.SupportPublish omits or mis-shapes tool_command_name, or when a non-tool project declares a command name despite not setting PackAsTool=true.void ValidateToolCommandNameValue(string projectPath, string commandName)
Source
Validates the manifest-declared tool command token for one project.
projectPathRepository-relative project path used in actionable error messages.commandNameCommand token read from tool_command_name.PackageIndexExceptionThrown when the command token is missing or uses a value that cannot safely resolve to one command shim file.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.
string GetRelativeRepositoryPath(PackageIndexRequest request, string repositoryRelativePath, string? outputPath = null)
Source
Gets a safe relative repository link for generated maintainer guidance that may not be copied into minimal test fixtures.
Unlike the existing GetRelativeDocPath helpers, this helper does not require the target to exist. The checked-in generated output still names a repository-owned guide, while isolated callers can generate a package dashboard without recreating every guide. Package manifest entries continue to use the GetRelativeDocPath helpers and therefore require existing targets.
string GetCanonicalRepositoryUrl(string repositoryRelativePath)
Source
Builds a canonical GitHub URL for repository-owned maintainer documentation that is not served by AppSurface Docs.
repositoryRelativePathA non-empty, slash-separated GitHub repository path whose segments do not contain direct or percent-encoded dot traversal or path separators.The canonical main-branch GitHub URL with each documentation-path segment URI-escaped.
Generated package documents are also harvested by AppSurface Docs. Repository-relative paths that escape the generated document's directory can be interpreted as Docs routes and produce a reader-facing 404. This helper validates GitHub URI path semantics independently of the build host and escapes URI-significant characters so a path segment cannot alter the target URL. Use it for maintainer guides that intentionally remain repository-owned rather than Docs-hosted.
bool RepositoryFileExists(string repositoryRoot, string repositoryRelativePath)
Source
Checks whether a known repository-relative chooser support file exists under the repository root.
repositoryRootRepository root used as the path-resolution base; relative roots are normalized with Path.GetFullPath(string).repositoryRelativePathRepository-relative file path, conventionally using / separators.true when the normalized file exists; otherwise, false.
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.
bool MarkdownDefinesFragmentTarget(string markdown, string fragment)
Source
Checks whether markdown defines an explicit anchor or slugified heading for a fragment.
markdownMarkdown content to inspect.fragmentFragment id without a leading #.true when the content defines the fragment; otherwise, false.
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.
string? TryGetMarkdownHeadingText(string line)
Source
Extracts the text from an ATX markdown heading line when the line uses one to six leading hash marks.
lineSingle markdown line to inspect.The heading text without closing hash marks or explicit anchor syntax, or null when not a heading.
string SlugifyMarkdownHeading(string heading)
Source
Produces the GitHub-style heading slug used by repository markdown anchors for simple heading text.
headingHeading text to slugify.A lowercase fragment id using hyphens for spaces and hyphens in the source text.
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.
repositoryRootRepository root used as the resolution boundary; relative roots are normalized with Path.GetFullPath(string).repositoryRelativePathRepository-relative file path supplied by chooser metadata, conventionally using / separators.descriptionHuman-readable label included in validation errors.The normalized absolute path to the validated file.
PackageIndexExceptionThrown when repositoryRelativePath is blank, rooted, escapes the repository root after normalization, or points at missing documentation.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.
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 and readiness dashboard generation or verification request.
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.string OutputPath { get; }
Source
Gets the chooser output path retained for compatibility with existing tests and callers.
Generated markdown documents produced from one package index resolution pass.
ChooserMarkdownGenerated adopter-facing package chooser markdown.ReadinessMarkdownGenerated maintainer-facing package readiness evidence markdown.Summarizes the managed package README work performed by PackageIndexGenerator.GenerateToFileAsync.
ManagedReleaseGuidanceCountNumber of package READMEs that declare a managed release-guidance region.ChangedReleaseGuidanceCountNumber of managed package READMEs whose region was rewritten.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.Computes package-index readiness evidence for the maintainer dashboard without treating the dashboard as live publish proof.
IReadOnlyList<PackageReadinessEvidence> Evaluate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)
Source
Evaluates package-index evidence for resolved package rows.
repositoryRootAbsolute repository root used to validate release-note paths.entriesResolved package rows.Per-package readiness evidence with blocking reasons and fix hints.
Per-package readiness evidence rendered in the generated maintainer dashboard.
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.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 that contribute package dependency assets.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, executable 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. ForgeTrust.AppSurface.ReleaseContracts is the one transitive support package stored below tools; it remains discoverable because published Docs consumers restore it as a dependency.
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 package artifact workflow.
string? ProductFamily { get; init; }
Source
Gets the product family that owns this package row for maintainer readiness review.
string? PublishReason { get; init; }
Source
Gets the required maintainer-facing reason for entries that are intentionally not published.
string? ReadinessBlocker { get; init; }
Source
Gets the optional same-repository issue or pull request that blocks package-index evidence completion.
string? ReadinessNote { get; init; }
Source
Gets optional escaped plain-text maintainer context for package readiness evidence.
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? ToolCommandName { get; init; }
Source
Gets the command shim expected from a .NET tool package.
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.
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? ReleaseTrack { get; init; }
Source
Gets the release-link policy. coordinated resolves to the frozen tree-local releases/current.md pointer; explicit uses ReleaseNotesPath.
string? ReleaseNotesPath { get; init; }
Source
Gets the repository-relative release notes file for explicit links. Legacy rows without ReleaseTrack also retain this explicit-path meaning.
string? ReleaseGuidanceVariant { get; init; }
Source
Gets the finite generated release-guidance variant for a package README that contains a managed release-policy region.
Valid values are default, apphost, and experimental. This field is intentionally absent for manifest entries whose documentation target has no managed release-guidance region.
Package-index evidence status rendered in the maintainer readiness dashboard.
Chooser section classifications for manifest entries.
Publish decisions for package artifact verification and later package publishing.
Release status values package-gate expects for each chooser classification.
Commercial readiness status values used by package-gate.
Produces a deterministic, read-only description of generated package documentation for release-preparation review.
The witness is deliberately a statement of repository truth at one merge base and HEAD. It never calls generate and never changes package documentation; the Release tool validates this JSON before accepting a generated package surface in an otherwise narrowly-scoped release preparation pull request.
Task<ReleasePreparationWitness> CreateAsync(PackageIndexRequest request, string baseRef, CancellationToken cancellationToken = default)
Source
Calculates a JSON witness for package documentation that is generated at HEAD.
requestResolved package-index request rooted at the checked-out repository.baseRefFetched base ref or immutable base commit used to derive the merge base.cancellationTokenCancellation token for file, renderer, and Git work.A strictly ordered witness with identity, semantic source inputs, and expected generated output hashes.
Task WriteAsync(ReleasePreparationWitness witness, string path, CancellationToken cancellationToken = default)
Source
Writes a witness as UTF-8 JSON without modifying any repository-owned package surface.
witnessWitness to serialize.pathExplicit destination, normally a CI temporary path.cancellationTokenCancellation token for the write.Immutable JSON contract emitted by ReleasePreparationWitnessBuilder.
One changed semantic source that authorizes specific generated package surfaces.
One generated package surface and the SHA-256 digest the canonical renderer expects at HEAD.
Renders the public-safe, versioned evidence companion for the packaged coverage proof.
The Markdown proof remains a private maintainer diagnostic with paths, command details, and bounded logs. This renderer intentionally emits only retained semantic outcomes and relative artifact references, so it is safe to publish beside package validation artifacts without exposing NuGet configuration, command arguments, credentials, raw XML, or host filesystem paths.
string RenderJson(CoverageCliConsumerProofReport report)
Source
Renders one public-safe evidence document.
reportComplete private proof report from which safe semantic facts are selected.Indented JSON with a terminating newline.