AppSurface Search
API Reference

PackageIndex

Type

Program

Source

CLI entry point for generating or verifying the package chooser and maintainer readiness dashboard.

Method

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.

Method

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.

Type

CommandLineOptions

Source

Parsed 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.
  • 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.
Method

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.
Method

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.
Method

CreatePackagePublishRequest

PackagePublishRequest CreatePackagePublishRequest() Source

Converts parsed CLI options into a protected package publish request.

Returns

The package publish request.

Method

CreatePackageSmokeInstallRequest

PackageSmokeInstallRequest CreatePackageSmokeInstallRequest() Source

Converts parsed CLI options into a package smoke install request.

Returns

The package smoke install request.

Method

CreateReleasePreparationWitnessRequest

ReleasePreparationWitnessRequest CreateReleasePreparationWitnessRequest() Source

Validates the dedicated read-only release-preparation witness options.

Returns

Resolved witness inputs.

Exceptions

  • PackageIndexExceptionThrown when either required witness option is absent.
Type

ReleasePreparationWitnessRequest

Source

Resolved inputs for the read-only package release-preparation witness command.

Parameters

  • 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.
Type

StableDocsDependencyContract

Source

Defines the exact parser and sanitizer identities approved for stable AppSurface Docs packages.

Remarks

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.

Method

ExactVersionRange

string ExactVersionRange(StableDocsPackageDependency dependency) Source

Gets the exact NuGet dependency declaration required for the supplied stable dependency.

Parameters

  • dependencyApproved parser or sanitizer dependency.

Returns

An exact bracketed NuGet version range.

Property

Dependencies

IReadOnlyList<StableDocsPackageDependency> Dependencies { get; } Source

Gets the approved parser and sanitizer package identities in reader-facing order.

Property

MarkdownDependencyList

string MarkdownDependencyList { get; } Source

Gets the Markdown-formatted dependency list used in maintainer guidance.

Property

PlainTextDependencyList

string PlainTextDependencyList { get; } Source

Gets a plain-text dependency list used in actionable diagnostics.

Type

StableDocsPackageDependency

Source

One approved stable Docs parser or sanitizer dependency identity.

Parameters

  • IdNuGet package id.
  • VersionExact resolved stable version.
Type

CoverageCliConsumerProofSemanticValidator

Source

Validates the bounded Cobertura contract used by the packaged default-collector consumer proof.

Remarks

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.

Method

ValidateRaw

CoverageCliConsumerProofSemanticProof ValidateRaw(string coverageRunDirectory) Source

Selects and validates the raw artifact belonging to the known default-collector fixture project.

Parameters

  • coverageRunDirectoryThe default collector's coverage-run output directory.

Returns

Raw selection, parsed semantic facts, and deterministic failures.

Method

ValidateMerged

CoverageCliConsumerProofSemanticProof ValidateMerged(CoverageCliConsumerProofSemanticProof rawProof, string copiedShardPath, string mergedCoveragePath) Source

Verifies the byte-preserved selected shard and independently validates the merged fan-in report.

Parameters

  • 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.

Returns

Raw and merged semantic proof with raw-first deterministic failure ordering.

Type

CoverageCliConsumerProofRawArtifact

Source

Manifest-bound raw report selected for the packaged default-collector proof.

Type

CoverageCliConsumerProofSemanticOutcome

Source

Public-safe outcome of one semantic coverage artifact validation stage.

Type

CoverageCliConsumerProofCoverageFacts

Source

Bounded semantic facts retained by the package proof. These are intentionally not raw XML.

Type

CoverageCliConsumerProofFailure

Source

One coded package coverage proof failure.

Type

CoverageCliConsumerProofSemanticProof

Source

Complete semantic default-collector proof state, including a selected raw artifact when selection succeeded.

Type

ICommandRunner

Source

Runs external commands for repository validation workflows.

Method

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.
Type

CommandRunRequest

Source

Describes 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 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.
Type

CommandRunResult

Source

Captured stdout and stderr from a successful command.

Parameters

  • StandardOutputCaptured standard output.
  • StandardErrorCaptured standard error.
Type

ProcessCommandRunner

Source

Process-backed command runner with timeout and failure cleanup.

Type

PackagePayloadInventoryLoader

Source

Loads the redistributed package payload inventory used by verify-packages.

Method

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.

Method

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.

Method

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.

Type

PackagePayloadInventory

Source

Repository-owned contract for redistributed package payload notice, audit, and generated evidence.

Method

Validate

void Validate(string displayPath) Source

Validates the parsed inventory shape before package-specific evidence checks run.

Parameters

  • displayPathPath shown in validation errors.
Property

SchemaVersion

int SchemaVersion { get; init; } Source

Gets the inventory schema version. Version 1 is the only supported v1 contract.

Property

Notices

List<PackagePayloadNoticeRecord> Notices { get; init; } Source

Gets third-party payload declarations that require package notices and provenance evidence.

Property

Audits

List<PackagePayloadAuditRecord> Audits { get; init; } Source

Gets narrow audit records for generated-first-party or otherwise non-notice payload evidence.

Type

PackagePayloadNoticeRecord

Source

Third-party redistributed payload evidence that requires package notice coverage.

Property

Id

string Id { get; init; } Source

Gets the stable inventory record id.

Property

PackageId

string PackageId { get; init; } Source

Gets the package id that must contain the declared payload.

Property

Component

string Component { get; init; } Source

Gets the redistributed component name shown in package reports.

Property

Version

string Version { get; init; } Source

Gets the redistributed component version.

Property

License

string License { get; init; } Source

Gets the redistributed component license expression or short name.

Property

SourceUrl

string SourceUrl { get; init; } Source

Gets the upstream source or project URL for maintainer review.

Property

PayloadPatterns

List<string> PayloadPatterns { get; init; } Source

Gets package entry glob patterns that identify the redistributed payload.

Property

NoticePaths

List<string> NoticePaths { get; init; } Source

Gets package entry paths that must contain the third-party notice text.

Property

Markers

List<string> Markers { get; init; } Source

Gets marker strings that must appear in at least one notice file.

Property

SourcePaths

List<string> SourcePaths { get; init; } Source

Gets optional source files that must exist in the repository for this evidence.

Property

VersionSourcePath

string? VersionSourcePath { get; init; } Source

Gets an optional repository file whose content must contain VersionSourceContains.

Property

VersionSourceContains

string? VersionSourceContains { get; init; } Source

Gets text that must appear in VersionSourcePath when the source is deterministic.

Type

PackagePayloadAuditRecord

Source

Audit evidence for package payloads that are generated-first-party or otherwise not third-party notice records.

Property

Id

string Id { get; init; } Source

Gets the stable inventory record id.

Property

PackageId

string PackageId { get; init; } Source

Gets the package id covered by this audit record.

Property

AppliesTo

List<string> AppliesTo { get; init; } Source

Gets package entry glob patterns or evidence labels covered by this audit.

Property

MatchedRule

string? MatchedRule { get; init; } Source

Gets the suspicious classifier rule or evidence class that caused this audit.

Property

EvidenceKind

string EvidenceKind { get; init; } Source

Gets the audit evidence type, such as generated_first_party.

Property

SourcePaths

List<string> SourcePaths { get; init; } Source

Gets repository source paths that must exist for this audit to stay valid.

Property

GeneratedPaths

List<string> GeneratedPaths { get; init; } Source

Gets generated repository paths that must exist for generated-first-party evidence.

Property

Reason

string Reason { get; init; } Source

Gets the human-readable reason this record is not a third-party notice declaration.

Property

ReviewedOn

string ReviewedOn { get; init; } Source

Gets the date or versioned source used for the audit review.

Property

Source

string Source { get; init; } Source

Gets the reviewer, source document, or script that established this audit.

Property

RevalidateWhen

string RevalidateWhen { get; init; } Source

Gets the event that must force revalidation of the audit.

Type

ReleaseGuidanceRenderer

Source

Renders the finite package README release-guidance variants declared by the package manifest.

Remarks

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.

Method

CreateUpdatesAsync

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.

Parameters

  • 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.

Returns

All managed README updates, including no-op updates used by verification.

Exceptions

  • PackageIndexExceptionThrown when the finite variant, template, marker, or README contract is invalid.
Method

ApplyUpdatesAsync

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.

Parameters

  • updatesFully rendered generated-file and README updates created before the first target write.
  • cancellationTokenCancellation token used while staging replacement content.

Returns

The number of target files changed.

Remarks

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.

Method

VerifyUpdates

void VerifyUpdates(IReadOnlyList<ReleaseGuidanceUpdate> updates) Source

Verifies every managed README is already identical to the current rendered release-guidance variant.

Parameters

  • updatesFully rendered README updates created without writing files.

Exceptions

  • PackageIndexExceptionThrown when any managed README is stale.
Method

ExtractManagedRegionBody

string ExtractManagedRegionBody(string content, string displayPath) Source

Extracts the body owned by the release-guidance marker pair without rewriting the README.

Parameters

  • contentComplete README content.
  • displayPathRepository-relative README path used in actionable failures.

Returns

The exact bytes between the ordered marker lines, including their line endings.

Exceptions

  • PackageIndexExceptionThrown when the README does not contain exactly one ordered marker pair.

Remarks

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.

Type

ReleaseGuidanceUpdate

Source

Describes one rendered package README policy region without changing the checked-in file.

Type

PackageArtifactWorkflow

Source

Coordinates package artifact packing and validation without publishing to NuGet.

Method

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.

Method

TryDeleteProofWorkspace

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.

Parameters

  • proofWorkDirectoryTemporary workspace to delete.
  • directoryExistsDirectory existence probe.
  • deleteDirectoryRecursive directory deletion operation.
Method

WriteCoverageProofEvidenceAsync

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.

Parameters

  • 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.

Returns

A task that completes after the temporary file has replaced a regular destination.

Type

PackageArtifactRequest

Source

Request for package artifact packing and validation.

Parameters

  • 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.
Type

PackagePublishPlanResolver

Source

Resolves the checked-in package manifest into the exact package set that should be packed.

Method

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.

Type

PackagePublishPlan

Source

Ordered package set selected for artifact packing and validation.

Parameters

  • EntriesPackages that should be packed, in deterministic manifest order.
Type

PackagePublishPlanEntry

Source

One 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 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.
Type

PackageProofWorkDirectory

Source

Safely recreates isolated package-consumer proof workspaces.

Method

RequireDisjoint

void RequireDisjoint(string firstDirectory, string secondDirectory) Source

Requires two package-consumer proof workspaces to be disjoint before either is recreated.

Parameters

  • firstDirectoryFirst proof workspace.
  • secondDirectorySecond proof workspace.

Exceptions

  • PackageIndexExceptionThrown when either workspace is the other workspace or one contains the other.
Method

Prepare

void Prepare(string workDirectory, string repositoryRoot, string artifactsDirectory) Source

Deletes and recreates an isolated package-consumer 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 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.

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. 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.

Type

CliWrapCommandRunner

Source

Runs external commands through CliWrap for protected package publishing and smoke-install workflows.

Type

IExternalCommandRunner

Source

External command runner used by publish and smoke workflows when non-zero exit codes are meaningful results.

Method

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.

Type

ExternalCommandRequest

Source

Command invocation for CliWrap-backed release automation.

Type

ExternalCommandResult

Source

Captured command result including non-zero exit codes.

Type

PackageArtifactManifestWriter

Source

Writes the machine-readable package artifact manifest consumed by protected publish jobs.

Method

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.
Type

PackageArtifactManifestReader

Source

Reads and validates the artifact manifest written by the package artifact verifier.

Method

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.

Type

PackagePublishWorkflow

Source

Publishes a validated package artifact set to NuGet in manifest order.

Method

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.

Type

PackageSmokeInstallWorkflow

Source

Restores published public packages and verifies published .NET tools from a clean NuGet configuration after publish completes.

Method

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.

Method

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 to dotnet tool install --tool-path.
  • commandNameValidated command token from tool_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 under toolPath.
Type

PackagePublishLedgerRenderer

Source

Renders protected publish outcomes for workflow artifacts.

Type

PackageSmokeInstallReportRenderer

Source

Renders package smoke install outcomes for workflow artifacts.

Type

PackagePublishRequest

Source

Request for a protected NuGet package publish workflow.

Parameters

  • 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.
Type

PackageSmokeInstallRequest

Source

Request 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.
Type

PackageArtifactManifest

Source

Machine-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.
Type

PackageArtifactManifestEntry

Source

One 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 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.
Type

PackagePublishLedger

Source

Publish result for a coordinated package version.

Parameters

  • PackageVersionExact stable or prerelease package version.
  • SourceNuGet source URL.
  • EntriesPer-package publish outcomes.
Type

PackagePublishLedgerEntry

Source

Publish outcome for one package artifact.

Parameters

  • 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.
Type

PackageSmokeInstallReport

Source

Smoke 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.
Type

PackageSmokeInstallReportEntry

Source

Smoke 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.
Type

PackageHash

Source

Computes package artifact hashes for manifest generation and publish verification.

Type

PackageArtifactJson

Source

JSON serializer options shared by artifact manifest readers and writers.

Type

ReleaseEnvironment

Source

Environment variables that make release automation quieter and deterministic.

Type

PackagePublishDecisionFormatter

Source

Formats package publish decisions for machine-readable release artifacts.

Type

PackageArtifactManifestPlanValidator

Source

Verifies that an artifact manifest still matches the checked-in package plan and validated artifacts.

Type

PlannedPackageArtifact

Source

Package 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.
Enum

PackagePublishStatus

Source

Publish status values written to the protected publish ledger.

Enum

PackageSmokeInstallStatus

Source

Smoke install status values written to the smoke report.

Type

PackageArtifactValidator

Source

Validates package artifacts against the resolved publish plan.

Method

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 .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.

Returns

A validation report for the inspected artifacts.

Method

ReadPackageEntryBytes

byte[] ReadPackageEntryBytes(string packagePath, string entryPath, string packageId) Source

Reads the bytes of a required package archive entry.

Parameters

  • packagePathPath to the package archive.
  • entryPathRepository-style path of the required archive entry.
  • packageIdPackage identifier used in a validation failure message.

Returns

The archive entry bytes.

Exceptions

  • PackageIndexExceptionThrown when the archive does not contain the required entry or its uncompressed contents exceed the validation limit.
Type

PackageArtifactReportRenderer

Source

Renders package artifact validation results for workflow artifacts.

Method

RenderMarkdown

string RenderMarkdown(PackageArtifactValidationReport report, CoverageCliConsumerProofReport? coverageProofReport = null, DocsPackageConsumerProofReport? docsProofReport = null) Source

Renders the validation report as markdown.

Parameters

  • reportValidation report to render.
  • coverageProofReportOptional packaged coverage CLI proof details to append.
  • docsProofReportOptional packed Docs consumer proof details to append.

Returns

Markdown report content.

Type

PackageVersionValidator

Source

Ensures package versions used by release workflows are safe for NuGet identity.

Method

RequirePrerelease

void RequirePrerelease(string packageVersion) Source

Validates that the package version is a prerelease SemVer identity without build metadata.

Parameters

  • packageVersionPackage version to validate.
Method

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.
Type

PackageArtifactValidationReport

Source

Result of a successful package artifact validation run.

Parameters

  • PackageVersionExact package version inspected.
  • EntriesValidated package report rows.
Type

PackageArtifactValidationReportEntry

Source

One 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 .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.
Type

PackagePayloadValidationResult

Source

One 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 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.
Type

InspectedPackage

Source

Metadata and payload facts inspected from one NuGet package artifact.

Parameters

  • 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.
Type

InspectedDependencyContainer

Source

One dependency container preserved from a package nuspec.

Parameters

  • 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.
Type

InspectedDependency

Source

One raw dependency occurrence preserved from a package nuspec.

Parameters

  • IdRaw dependency id, or null when omitted.
  • VersionRaw dependency version, or null when omitted.
Type

DependencyContainerInspection

Source

Dependency-container facts collected from a package nuspec.

Parameters

  • ContainersContainers in declaration order.
  • HasMixedRootAndGroupsWhether root dependencies and groups coexist.
Type

StableDocsDependencyViolation

Source

One stable Docs dependency-contract violation.

Parameters

  • ContainerLabelDependency container label.
  • DependencyIdRequired dependency or metadata field.
  • ObservedObserved artifact value.
  • ExpectedExact required value.
Type

InspectedToolSettingsFile

Source

Tool 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.
Type

InspectedAssemblyVersion

Source

Informational 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.
Enum

PackageVersionPolicy

Source

Package version policies used by release-classified package workflows.

Type

ICoverageCliConsumerProofWorkflow

Source

Runs the pre-publish consumer proof for the packaged AppSurface CLI.

Method

RunAsync

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.

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.

Type

CoverageCliConsumerProofWorkflow

Source

Verifies 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 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.

Method

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.

Method

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.

Method

RenderNuGetOrgOnlyConfig

string RenderNuGetOrgOnlyConfig(string nugetOrgSource) Source

Renders the NuGet config used by the generated consumer fixture for test-only dependencies.

Parameters

  • nugetOrgSourceNuGet source used by dotnet new xunit and the Coverlet collector/MSBuild fixture packages.

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.

Type

CanaryProofFixture

Source

Provides a protected named-canary fixture through a loopback HTTP server.

Method

Start

CanaryProofFixture Start() Source

Starts and returns a newly initialized loopback canary fixture.

Method

DisposeAsync

ValueTask DisposeAsync() Source

Stops the loopback server and releases the fixture's resources.

Property

BaseUrl

string BaseUrl { get; } Source

Gets the loopback HTTP server URL used by the packaged CLI proof.

Property

ValidRequestCount

int ValidRequestCount { get; } Source

Gets the number of fully valid requests accepted by the loopback server.

Type

CoverageCliConsumerProofRequest

Source

Request 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.
Type

CoverageCliConsumerProofSelectedArtifact

Source

Selected CLI artifact metadata captured before running the consumer proof.

Parameters

  • 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.
Type

CoverageCliConsumerProofReport

Source

Structured 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.
  • SemanticProofManifest-bound default-collector raw-to-merged semantic proof.
Property

Succeeded

bool Succeeded { get; } Source

Gets whether every command and artifact check matched the expected consumer contract.

Type

CoverageCliConsumerProofCommandResult

Source

One 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.
Type

CoverageCliConsumerProofArtifactCheck

Source

One artifact expected from the packaged coverage CLI consumer proof.

Parameters

  • DescriptionArtifact role.
  • PathExpected or produced artifact path.
  • ExistsWhether the artifact exists.
Type

CoverageCliConsumerProofContext

Source

Runtime 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.
Type

CoverageCliConsumerProofReportRenderer

Source

Renders packaged coverage CLI consumer proof reports for package validation artifacts.

Method

RenderMarkdown

string RenderMarkdown(CoverageCliConsumerProofReport report) Source

Renders a standalone markdown report.

Parameters

  • reportProof report.

Returns

Markdown report.

Method

RenderSection

void RenderSection(StringBuilder builder, CoverageCliConsumerProofReport report) Source

Appends the proof section to a larger package validation report.

Parameters

  • builderDestination markdown builder.
  • reportProof report.
Type

IDocsPackageConsumerProofWorkflow

Source

Runs the pre-publish restore proof for the packed AppSurface Docs package.

Method

RunAsync

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.

Parameters

  • requestProof paths, package version, and third-party package source.
  • validationReportValidated artifacts produced by the package artifact workflow.
  • cancellationTokenCancellation token.

Returns

A structured report containing command and graph-verification evidence.

Type

DocsPackageConsumerProofWorkflow

Source

Proves that a clean package consumer resolves the packed Docs artifact and the reviewed stable parser and sanitizer graph.

Remarks

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.

Method

SelectDocsPackage

DocsPackageConsumerProofSelectedArtifact SelectDocsPackage(PackageArtifactValidationReport report, string packageVersion) Source

Selects the validated Docs artifact that the consumer proof restores.

Parameters

  • reportValidation report produced from the just-packed artifact directory.
  • packageVersionExact package version expected in the selected artifact file name.

Returns

The selected artifact and its SHA-512 hash.

Exceptions

  • PackageIndexExceptionThrown when the report does not contain exactly one existing Docs package artifact matching packageVersion.
Method

RenderConsumerDirectoryPackagesProps

string RenderConsumerDirectoryPackagesProps() Source

Renders the isolated consumer's central package-management boundary.

Returns

Props that disable inherited central package management and enable the consumer lock file.

Method

RenderConsumerProject

string RenderConsumerProject(string packageVersion) Source

Renders the clean package consumer project.

Parameters

  • packageVersionExact Docs package version to restore.

Returns

Consumer project XML.

Method

RenderMappedNuGetConfig

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.

Parameters

  • 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.

Returns

NuGet configuration XML with package-source mapping.

Exceptions

  • ArgumentExceptionThrown when no third-party package ids are supplied or an id is a package-source mapping pattern.
Method

ReadPackedDocsThirdPartyPackageIds

IReadOnlyList<string> ReadPackedDocsThirdPartyPackageIds(string repositoryRoot, PackageArtifactValidationReport validationReport) Source

Reads the public package identities for the validated, packed Docs first-party closure.

Parameters

  • repositoryRootRepository root that contains the committed lock files for packed first-party projects.
  • validationReportValidated package report that establishes the first-party package closure.

Returns

Sorted, deduplicated third-party package ids.

Exceptions

  • PackageIndexExceptionThrown when the report does not contain the complete Docs closure, or a required committed lock file is absent or malformed.

Remarks

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.

Method

ReadThirdPartyPackageIdsFromLockFile

IReadOnlyList<string> ReadThirdPartyPackageIdsFromLockFile(string lockFilePath) Source

Reads package (not project) identities from one committed project lock file.

Parameters

  • lockFilePathCommitted lock file path.

Returns

Third-party package identities represented by lock entries.

Exceptions

  • PackageIndexExceptionThrown when the lock file is absent or malformed.
Method

VerifyConsumerGraph

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.

Parameters

  • assetsFilePathGenerated project.assets.json path.
  • lockFilePathGenerated consumer lock file path.
  • packageVersionExpected Docs package version.

Returns

Verified resolved package identities and paths.

Exceptions

  • PackageIndexExceptionThrown when either generated input is absent, malformed, or resolves a wrong package identity.
Type

DocsPackageConsumerProofRequest

Source

Request for an isolated packed Docs consumer restore proof.

Parameters

  • 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.
Type

DocsPackageConsumerProofSelectedArtifact

Source

Identity and hash of the validated Docs artifact selected for consumer restore.

Parameters

  • PackageIdDocs package id.
  • ProjectPathProject that produced the selected artifact.
  • ArtifactPathValidated local package artifact path.
  • Sha512Base64 SHA-512 hash of the selected artifact.
Type

DocsPackageConsumerProofResolvedPackage

Source

One resolved package identity verified in the generated consumer's assets graph.

Parameters

  • IdPackage id.
  • VersionExact resolved package version.
Type

DocsPackageConsumerGraphVerification

Source

Structural proof that the generated consumer resolved all required package identities.

Parameters

  • 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.
Type

DocsPackageConsumerProofCommandResult

Source

One command in the packed Docs consumer proof ledger.

Parameters

  • 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.
Type

DocsPackageConsumerProofReport

Source

Structured evidence emitted by the packed Docs consumer proof.

Parameters

  • 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.
Method

Failed

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.

Parameters

  • packageVersionPackage version under proof.
  • workDirectoryRequested proof directory.
  • sourceRequested public source.
  • firstFailureFailure message.
  • selectedArtifactSelected artifact, if selection already succeeded.

Returns

Failed proof report.

Property

Succeeded

bool Succeeded { get; } Source

Gets whether every command and graph verification succeeded.

Type

DocsPackageConsumerProofReportRenderer

Source

Renders packed Docs consumer proof evidence for standalone and aggregate package reports.

Method

RenderMarkdown

string RenderMarkdown(DocsPackageConsumerProofReport report) Source

Renders a standalone markdown report.

Parameters

  • reportProof report.

Returns

Markdown content.

Method

RenderSection

void RenderSection(StringBuilder builder, DocsPackageConsumerProofReport report) Source

Appends proof evidence to an aggregate package report.

Parameters

  • builderDestination markdown builder.
  • reportProof report.
Type

DocsPackageConsumerProofContext

Source

Runtime paths and inputs shared by the packed Docs consumer proof.

Type

PackageIndexGenerator

Source

Generates 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.

Method

GenerateToFileAsync

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.

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 report describing the generated package-index documents and managed README reconciliation.

Exceptions

  • PackageIndexExceptionThrown when the repository layout is invalid, required docs are missing, or the manifest cannot be rendered safely.

Remarks

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.

Method

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.
Method

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.

Method

GenerateDocuments

PackageIndexDocuments GenerateDocuments(PackageIndexRequest request, IReadOnlyList<ResolvedPackageEntry> entries) Source

Renders the package chooser and readiness documents from entries already resolved for the same request.

Parameters

  • requestGeneration request that supplies output and repository context.
  • entriesCanonical entries resolved by ResolveGenerationEntriesAsync.

Returns

In-memory document content without reading or writing repository files.

Method

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.
Method

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.
Method

ResolveGenerationEntriesAsync

Task<IReadOnlyList<ResolvedPackageEntry>> ResolveGenerationEntriesAsync(PackageIndexRequest request, CancellationToken cancellationToken) Source

Resolves the validated package entries used by every canonical package-index rendering path.

Remarks

This is exposed internally so read-only provenance consumers can reuse the exact renderer inputs instead of reconstructing manifest or project metadata rules.

Method

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.

Method

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 declare tool_command_name and a publish decision.
  • metadataEvaluated project metadata that reports whether the project packs as a .NET tool.

Exceptions

  • 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.
Method

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 from tool_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.

Method

GetSharedPublicReleaseNotePath

string? GetSharedPublicReleaseNotePath(PackageIndexRequest request, IReadOnlyList<ResolvedPackageEntry> publicEntries) Source

Finds the release note all publishable public package rows currently share.

Parameters

  • requestGeneration request that supplies the chooser output context used to validate release-note links.
  • publicEntriesPublic chooser rows resolved from the package manifest.

Returns

The shared release-note path, or null when rows point at mixed or missing release notes.

Method

GetRelativeRepositoryPath

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.

Remarks

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.

Method

GetCanonicalRepositoryUrl

string GetCanonicalRepositoryUrl(string repositoryRelativePath) Source

Builds a canonical GitHub URL for repository-owned maintainer documentation that is not served by AppSurface Docs.

Parameters

  • repositoryRelativePathA non-empty, slash-separated GitHub repository path whose segments do not contain direct or percent-encoded dot traversal or path separators.

Returns

The canonical main-branch GitHub URL with each documentation-path segment URI-escaped.

Remarks

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.

Method

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 with Path.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.

Method

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.

Method

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.

Method

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.

Method

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 with Path.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 when repositoryRelativePath is 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.

Property

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.

Type

PackageIndexRequest

Source

Describes 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.
Property

OutputPath

string OutputPath { get; } Source

Gets the chooser output path retained for compatibility with existing tests and callers.

Type

PackageIndexDocuments

Source

Generated markdown documents produced from one package index resolution pass.

Parameters

  • ChooserMarkdownGenerated adopter-facing package chooser markdown.
  • ReadinessMarkdownGenerated maintainer-facing package readiness evidence markdown.
Type

PackageIndexGenerationReport

Source

Summarizes the managed package README work performed by PackageIndexGenerator.GenerateToFileAsync.

Parameters

  • ManagedReleaseGuidanceCountNumber of package READMEs that declare a managed release-guidance region.
  • ChangedReleaseGuidanceCountNumber of managed package READMEs whose region was rewritten.
Type

ResolvedPackageEntry

Source

Couples 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.
Type

PackageReadinessEvaluator

Source

Computes package-index readiness evidence for the maintainer dashboard without treating the dashboard as live publish proof.

Method

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.

Type

PackageReadinessEvidence

Source

Per-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.
Type

PackageGateReport

Source

Summarizes 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.
Type

PackageGateValidator

Source

Validates package release metadata, package-class invariants, and stale brand drift before packages are published.

Method

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.

Type

PackageIndexException

Source

Represents a package chooser generation or verification failure.

Remarks

These exceptions are written directly to CLI stderr, so messages should stay actionable and user-facing.

Type

IProjectMetadataProvider

Source

Contract for evaluating one discovered project into package metadata suitable for chooser rendering.

Method

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.

Type

PackageProjectMetadata

Source

Evaluated 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 as Library or Exe.
  • ProjectReferencesEvaluated project reference paths that contribute package dependency assets.
Property

InstallCommand

string InstallCommand { get; } Source

Gets the primary install command shown in the chooser for this package or tool.

Type

PackageProjectScanner

Source

Discovers candidate projects that should be classified by the package chooser manifest.

Remarks

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.

Method

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.

Method

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.

Type

DotNetProjectMetadataProvider

Source

Evaluates 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.

Method

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 from dotnet 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.

Type

PackageManifestLoader

Source

Loads the chooser manifest from YAML into strongly typed manifest models.

Method

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.
Type

PackageManifest

Source

Root manifest model for the chooser YAML file.

Property

Packages

List<PackageManifestEntry> Packages { get; init; } Source

Gets the ordered manifest rows that describe each package, support surface, or excluded package entry.

Type

PackageManifestEntry

Source

One 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.

Property

Project

string Project { get; init; } Source

Gets the repository-relative project path classified by this manifest entry.

Property

Classification

PackageClassification Classification { get; init; } Source

Gets the chooser classification that controls which section renders the package.

Property

PublishDecision

PackagePublishDecision? PublishDecision { get; init; } Source

Gets the publish decision consumed by the package artifact workflow.

Property

ProductFamily

string? ProductFamily { get; init; } Source

Gets the product family that owns this package row for maintainer readiness review.

Property

PublishReason

string? PublishReason { get; init; } Source

Gets the required maintainer-facing reason for entries that are intentionally not published.

Property

ReadinessBlocker

string? ReadinessBlocker { get; init; } Source

Gets the optional same-repository issue or pull request that blocks package-index evidence completion.

Property

ReadinessNote

string? ReadinessNote { get; init; } Source

Gets optional escaped plain-text maintainer context for package readiness evidence.

Property

Order

int Order { get; init; } Source

Gets the stable display order within the chooser section.

Property

UseWhen

string? UseWhen { get; init; } Source

Gets the adopter-focused “use when” guidance for public package rows.

Property

Includes

string? Includes { get; init; } Source

Gets the concise statement describing what the package includes for public rows.

Property

DoesNotInclude

string? DoesNotInclude { get; init; } Source

Gets the concise statement describing what the package intentionally does not include for public rows.

Property

StartHerePath

string? StartHerePath { get; init; } Source

Gets the repository-relative documentation file linked from this chooser row.

Property

StartHereLabel

string? StartHereLabel { get; init; } Source

Gets the optional chooser label used for the linked documentation target.

Property

RecipeSummary

string? RecipeSummary { get; init; } Source

Gets the optional recipe summary shown in the “Also building...” section.

Property

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.

Property

Note

string? Note { get; init; } Source

Gets the explanatory note rendered for non-public package rows.

Property

DependsOn

List<string> DependsOn { get; init; } Source

Gets the optional package ids that this row depends on for install guidance.

Property

ExpectedDependencyPackageIds

List<string> ExpectedDependencyPackageIds { get; init; } Source

Gets the exact package ids expected from project-reference dependencies in the produced package.

Property

ReleaseStatus

PackageReleaseStatus ReleaseStatus { get; init; } Source

Gets the release status expected by package-gate for this package classification.

Property

CommercialStatus

PackageCommercialStatus CommercialStatus { get; init; } Source

Gets whether this package row is part of the commercial-ready public surface.

Property

ReleaseTrack

string? ReleaseTrack { get; init; } Source

Gets the release-link policy. coordinated resolves to the frozen tree-local releases/current.md pointer; explicit uses ReleaseNotesPath.

Property

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.

Property

ReleaseGuidanceVariant

string? ReleaseGuidanceVariant { get; init; } Source

Gets the finite generated release-guidance variant for a package README that contains a managed release-policy region.

Remarks

Valid values are default, apphost, and experimental. This field is intentionally absent for manifest entries whose documentation target has no managed release-guidance region.

Enum

PackageReadinessStatus

Source

Package-index evidence status rendered in the maintainer readiness dashboard.

Enum

PackageClassification

Source

Chooser section classifications for manifest entries.

Enum

PackagePublishDecision

Source

Publish decisions for package artifact verification and later package publishing.

Enum

PackageReleaseStatus

Source

Release status values package-gate expects for each chooser classification.

Enum

PackageCommercialStatus

Source

Commercial readiness status values used by package-gate.

Type

ReleasePreparationWitnessBuilder

Source

Produces a deterministic, read-only description of generated package documentation for release-preparation review.

Remarks

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.

Method

CreateAsync

Task<ReleasePreparationWitness> CreateAsync(PackageIndexRequest request, string baseRef, CancellationToken cancellationToken = default) Source

Calculates a JSON witness for package documentation that is generated at HEAD.

Parameters

  • 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.

Returns

A strictly ordered witness with identity, semantic source inputs, and expected generated output hashes.

Method

WriteAsync

Task WriteAsync(ReleasePreparationWitness witness, string path, CancellationToken cancellationToken = default) Source

Writes a witness as UTF-8 JSON without modifying any repository-owned package surface.

Parameters

  • witnessWitness to serialize.
  • pathExplicit destination, normally a CI temporary path.
  • cancellationTokenCancellation token for the write.
Type

ReleasePreparationWitness

Source

Immutable JSON contract emitted by ReleasePreparationWitnessBuilder.

Type

ReleasePreparationWitnessInput

Source

One changed semantic source that authorizes specific generated package surfaces.

Type

ReleasePreparationWitnessSurface

Source

One generated package surface and the SHA-256 digest the canonical renderer expects at HEAD.

Type

CoverageCliConsumerProofEvidenceRenderer

Source

Renders the public-safe, versioned evidence companion for the packaged coverage proof.

Remarks

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.

Method

RenderJson

string RenderJson(CoverageCliConsumerProofReport report) Source

Renders one public-safe evidence document.

Parameters

  • reportComplete private proof report from which safe semantic facts are selected.

Returns

Indented JSON with a terminating newline.