bool HasErrors { get; }
Source
Gets whether the report contains errors.
Release
ICommandRunner
SourceCommand runner abstraction for git and GitHub CLI calls.
RunAsync
Task<CommandResult> RunAsync(CommandInvocation invocation, CancellationToken cancellationToken)
Source
Runs a process and captures stdout and stderr.
Parameters
invocationCommand invocation.cancellationTokenCancellation token.
Returns
Command result.
ProcessCommandRunner
SourceProcess command runner used by the default CLI.
IReleaseClock
SourceClock abstraction used by tests to make generated release dates deterministic.
TodayUtc
DateOnly TodayUtc()
Source
Gets today's UTC date.
Returns
UTC date.
SystemReleaseClock
SourceSystem clock used by the default CLI.
ReleaseSidecar
SourceMutable YAML sidecar metadata for release-note documentation pages.
Remarks
Sidecars are dictionary-backed so unknown fields are preserved. Tagged-release conversion overwrites release-owned keys (title, summary, order, breadcrumbs, and trust) and leaves unrelated keys untouched.
LoadAsync
Task<ReleaseSidecar> LoadAsync(string path, CancellationToken cancellationToken)
Source
Loads sidecar metadata from YAML.
Parameters
pathSidecar path. Expected content is a YAML mapping at the document root.cancellationTokenCancellation token honored during file I/O.
Returns
Loaded sidecar whose unknown keys are preserved for later serialization.
Remarks
The current release flow expects the unreleased sidecar to contain documentation keys such as title, summary, page_type, nav_group, order, breadcrumbs, and trust. Missing keys are tolerated because ToTaggedRelease writes the release-owned fields. Malformed YAML is wrapped in ReleaseToolException with release-sidecar-invalid; I/O and cancellation failures bubble to the shared command diagnostic layer.
ToTaggedRelease
string ToTaggedRelease(SemVer version, DateOnly date)
Source
Converts unreleased metadata into tagged-release metadata.
Parameters
versionTagged release version.dateRelease date.
Returns
Tagged release sidecar YAML using underscored key naming for generated CLR-backed values.
Remarks
This method mutates the loaded dictionary before serializing. It replaces release-owned metadata with final tagged-release values and preserves unrelated keys from the source sidecar. Callers should not reuse the instance for another version after conversion.
UnreleasedTemplate
string UnreleasedTemplate()
Source
Creates reset unreleased metadata for the next release cycle.
Returns
Canonical unreleased sidecar YAML with title, navigation, trust metadata, and source guidance.
Remarks
The template is complete enough for docs harvesting without requiring the previous sidecar. It intentionally resets release-specific trust metadata back to provisional language.
PackageIndexEditor
SourceUpdatePublicPublishedReleaseNotes
string UpdatePublicPublishedReleaseNotes(string content, string releasePath)
Source
Updates release note paths for rows classified as public and publishable.
Parameters
contentExisting package index YAML.releasePathNew repository-relative release note path.
Returns
Updated YAML content.
Remarks
This method edits YAML line-by-line so existing comments and ordering survive a release PR. It expects the package index's current shape: package entries begin with two spaces and - project:, fields are indented with four spaces, and classification, publish_decision, release_notes_path, and order stay inside one package block. Different indentation or nested structures require updating this editor. Output is normalized to LF line endings with one trailing LF so release PR diffs are stable across platforms.
CommandInvocation
SourceImmutable command invocation for release-owned external processes.
Parameters
ExecutableExecutable name or absolute path.ArgumentsArgument list passed without shell evaluation.WorkingDirectoryWorking directory used for the process.TimeoutOptional wall-clock timeout. When omitted, release commands use the default bounded timeout.
CommandResult
SourceCaptured command result.
ReleaseCheckResult
SourceRelease readiness result.
HasErrors
ReleasePreparationResult
SourceRelease preparation result.
ReleaseManifest
SourceMachine-readable release manifest.
PackagePathUpdate
SourcePackage release note path update recorded in the release manifest.
ReleaseDiagnosticRecord
SourceSerializable diagnostic record for release manifests.
FromDiagnostic
ReleaseDiagnosticRecord FromDiagnostic(ReleaseDiagnostic diagnostic)
Source
Creates a serializable diagnostic record.
Parameters
diagnosticSource diagnostic.
Returns
Serializable record.
PublishOutputs
SourceStructured publish outputs for GitHub Actions.
ReleaseEvidenceSummary
SourceMaintainer-facing release evidence summary rendered in command reports and workflow outputs.
Parameters
PathRepository-relative evidence bundle path.SchemaEvidence bundle schema.StatusDraft or tag-bound validation status.SubjectSha256Stable subject digest for the evidence bundle.DocsReleaseManifestSha256Optional AppSurface Docs archive manifest digest referenced by the evidence bundle.CatalogExactTreePathOptional catalog exact tree path referenced by the evidence bundle.TagCommitOptional tag commit validated at publish time.AttestationAttestation requirement state.
ReleaseOptions
SourceParsed release CLI options shared by every command.
SemVer
SourceMinimal SemVer 2.0 model used by release automation.
Parse
SemVer Parse(string value)
Source
Parses a release version and rejects leading-v tags, build metadata, and invalid SemVer shapes.
Parameters
valueVersion string supplied by the user.
Returns
The parsed version.
IsStable
bool IsStable { get; }
Source
Gets whether the version is a stable SemVer identity.
IsProtectedPrereleaseWorkflowCompatible
bool IsProtectedPrereleaseWorkflowCompatible { get; }
Source
Gets whether this prerelease version can trigger the protected prerelease package workflow.
TagName
string TagName { get; }
Source
Gets the annotated git tag expected for this version.
ReleaseNoteBuilder
SourceBuild
string Build(SemVer version, DateOnly date, string unreleased)
Source
Converts the living unreleased note into a tagged release note.
Parameters
versionRelease version rendered in the heading and generated comment.dateRelease date rendered with invariantyyyy-MM-ddformatting.unreleasedUnreleased Markdown content. Canonical input starts with an exact# Unreleasedheading.
Returns
Tagged release Markdown with a generated comment header and a trailing newline.
Remarks
The method first parses Markdown to catch syntax problems, but it does not use the returned syntax tree to rewrite content. It then replaces only the exact top-level # Unreleased heading and two known narrative phrases using ordinal matching. Variants in casing or wording are left unchanged. Output is deterministic apart from the supplied version and date, uses Environment.NewLine for generated sections, and trims trailing whitespace from the source body. Callers should run release readiness checks first because duplicate headings, missing phrases, or concurrently edited Markdown are not treated as errors.
ResetUnreleased
string ResetUnreleased(SemVer previousVersion)
Source
Creates the next-cycle unreleased proof artifact.
Parameters
previousVersionVersion that just moved into tagged release files.
Returns
Canonical unreleased Markdown for the next cycle, including the previous version reference and a trailing newline.
Remarks
This reset intentionally discards the prior living-release body after it has been copied into a tagged release note. It preserves the expected section order for future checks: overview, shaping work, included changes, and migration watch.
PackageIndexSummary
SourceLoadAsync
Task<PackageIndexSummary> LoadAsync(string path, CancellationToken cancellationToken)
Source
Loads a package index summary from YAML.
Parameters
pathPackage index path.cancellationTokenCancellation token.
Returns
Package index summary.
PublicPublishedPackages
IReadOnlyList<PackageIndexEntry> PublicPublishedPackages { get; }
Source
Gets public package rows whose publish decision is publish.
PackageIndexManifest
SourcePackage manifest root shape used by the release tool.
Packages
List<PackageIndexYamlEntry> Packages { get; init; }
Source
Gets the package rows.
PackageIndexYamlEntry
SourcePackage manifest row shape used by the release tool.
Project
string Project { get; init; }
Source
Gets the project path.
Classification
string Classification { get; init; }
Source
Gets the classification string.
PublishDecision
string? PublishDecision { get; init; }
Source
Gets the publish decision string.
ReleaseNotesPath
string? ReleaseNotesPath { get; init; }
Source
Gets the release notes path.
PackageIndexEntry
SourcePackage row included in a release manifest.
Program
SourceCLI entry point for AppSurface release preparation and publishing validation.
Main
Task<int> Main(string[] args)
Source
Launches the release CLI with process IO streams.
Parameters
argsCommand-line arguments supplied to the process.
Returns
Process exit code where 0 indicates success.
RunAsync
Task<int> RunAsync(string[] args, TextWriter standardOut, TextWriter standardError, string currentDirectory, CancellationToken cancellationToken = default, ICommandRunner? commandRunner = null, IReleaseClock? clock = null)
Source
Runs the release CLI against supplied IO streams and an explicit working directory.
Parameters
argsCommand-line arguments, including command and options.standardOutWriter that receives reports, structured output, and help.standardErrorWriter that receives diagnostic envelopes and invalid usage.currentDirectoryDirectory used to resolve repository-relative defaults.cancellationTokenCancellation token for file and process work.commandRunnerOptional command runner seam used by tests.clockOptional clock seam used by tests.
Returns
0 for success; otherwise a non-zero exit code.
ReleaseCliModule
SourceAppSurface Console root module for the release cockpit.
ReleaseExecutionContext
SourcePer-invocation execution context supplied by the CLI entry point.
Parameters
CurrentDirectoryDirectory used to resolve default repository-relative paths.
ReleaseReportRenderer
SourceRenderCheck
string RenderCheck(ReleaseCheckResult result)
Source
Renders a check report.
Parameters
resultCheck result.
Returns
Markdown report.
Remarks
The report shape is stable for workflow comments and maintainer review: # Release readiness report, a summary bullet list, ## Generated files, optional ## Release evidence bundle, ## Errors, then ## Warnings. Empty diagnostics render as - None. Generated file paths and diagnostic codes are wrapped in inline code; diagnostic text is not escaped beyond normal Markdown rendering. Consumers should key off headings and diagnostic codes rather than line numbers.
RenderPreparation
string RenderPreparation(ReleasePreparationResult result)
Source
Renders a prepare report.
Parameters
resultPreparation result.
Returns
Markdown report.
Remarks
Preparation reports begin with the check report contract, then append a manual review gate, optional evidence summary, and either ## Dry-run plan or ## Files written based on ReleasePreparationResult.DryRun. Paths are repository-relative bullets. This distinction is the only dry-run marker in the report, so callers that publish the report should preserve that heading.
ChangelogEditor
SourceRollForward
string RollForward(string changelog, SemVer version, DateOnly date, string releasePath)
Source
Resets the compact Unreleased ledger and inserts a tagged changelog section after it.
Parameters
changelogExisting changelog content. Canonical input contains a single## Unreleasedheading.versionRelease version inserted as## {version} - yyyy-MM-dd.dateRelease date rendered with invariantyyyy-MM-ddformatting.releasePathRepository-relative release note path linked from the new section.
Returns
Updated changelog content with a reset Unreleased section and the tagged section inserted or appended.
Remarks
The algorithm is intentionally text-based to preserve surrounding Markdown. The detailed release narrative lives in releases/unreleased.md before preparation and releases/v{version}.md after preparation; the changelog keeps only the durable compact ledger. If ## Unreleased is missing, the canonical compact section is appended before the new tagged section. If the first-release placeholder follows ## Unreleased, that placeholder block is replaced. Duplicate release sections are not de-duplicated; callers should run readiness checks before calling this method. Malformed heading hierarchies and concurrent changelog edits can therefore produce surprising placement, so this helper should only be used on the repository's canonical changelog shape.
ReleaseCheckCommand
SourceValidates release readiness without mutating repository files.
FailOnWarningsOption
bool FailOnWarningsOption { get; set; }
Source
Gets a value indicating whether check should fail on warning diagnostics.
AllowExistingTargetsOption
bool AllowExistingTargetsOption { get; set; }
Source
Gets a value indicating whether check may review already-generated release artifacts.
ReleasePrepareCommand
SourceGenerates the coordinated release pull request payload.
ReleasePublishCommand
SourceValidates tag state and emits GitHub Release workflow outputs.
Tag
string? Tag { get; set; }
Source
Gets the annotated release tag to publish.
GitHubOutputPath
string? GitHubOutputPath { get; set; }
Source
Gets an optional GitHub Actions output file.
ReleaseCommandBase
SourceShared CliFx option surface and diagnostic handling for release commands.
ExecuteWithDiagnosticsAsync
ValueTask ExecuteWithDiagnosticsAsync(IConsole console, Func<ReleaseOptions, CancellationToken, Task<int>> executeAsync)
Source
Runs command logic with release diagnostic rendering.
Parameters
consoleCliFx console.executeAsyncCommand implementation.
Returns
A task that completes after command execution.
CreateServices
ReleaseServices CreateServices(ReleaseOptions options)
Source
Creates service objects for the resolved repository root.
Parameters
optionsResolved command options.
Returns
Workspace, checker, preparation, and publishing services.
ResolveTag
string? ResolveTag(SemVer version)
Source
Resolves the command tag, when relevant.
Parameters
versionParsed release version.
Returns
The tag value, or null for commands that do not use a tag.
ResolveGitHubOutputPath
string? ResolveGitHubOutputPath(string repoRoot)
Source
Resolves the GitHub Actions output path, when relevant.
Parameters
repoRootResolved repository root.
Returns
The output path, or null for commands that do not write workflow outputs.
WriteReportAsync
Task WriteReportAsync(ReleaseOptions options, string rendered, TextWriter standardOut, CancellationToken cancellationToken)
Source
Writes the rendered command report to stdout and to the optional report path.
Parameters
optionsResolved command options.renderedRendered Markdown report.standardOutStandard output writer.cancellationTokenCancellation token.
Returns
A task that completes after the report is written.
VersionText
string? VersionText { get; set; }
Source
Gets the SemVer 2.0 release version without a leading v.
DateText
string? DateText { get; set; }
Source
Gets the release date for prepare, formatted as YYYY-MM-DD.
DryRun
bool DryRun { get; set; }
Source
Gets a value indicating whether the command should avoid repository mutations or publishing.
RepositoryRoot
string? RepositoryRoot { get; set; }
Source
Gets the repository root. Defaults to the current directory.
ReportPath
string? ReportPath { get; set; }
Source
Gets an optional readiness report output path.
CommandName
string CommandName { get; }
Source
Gets the command name used by release validation logic.
FailOnWarnings
bool FailOnWarnings { get; }
Source
Gets whether this command should turn warning diagnostics into a failing exit code.
AllowExistingTargets
bool AllowExistingTargets { get; }
Source
Gets whether this command may review already-generated release artifacts.
ReleaseServices
SourceCommand services bound to a resolved workspace.
Parameters
WorkspaceWorkspace path helper.CheckerReadiness checker.PreparationRelease preparation workflow.PublishingRelease publishing workflow.
ReleaseJson
SourceJSON serializer configuration for release artifacts.
Options
JsonSerializerOptions Options { get; }
Source
Gets indented camel-case JSON options.
ReleasePreparation
SourceCreates release artifacts from the living unreleased note.
PrepareAsync
Task<ReleasePreparationResult> PrepareAsync(ReleaseOptions options, CancellationToken cancellationToken)
Source
Generates release files or, in dry-run mode, returns the planned edits.
Parameters
optionsRelease command options. Date defaults to the injected clock when omitted.cancellationTokenCancellation token.
Returns
Preparation result containing readiness diagnostics and planned or written repository-relative paths.
Remarks
Preparation is a deterministic repository-file rewrite: it runs readiness checks, reads the unreleased note and sidecar, builds versioned release artifacts, rolls CHANGELOG.md, updates public published package note paths, resets unreleased files, and records diagnostics in the release manifest. Dry-run mode performs all reads and rendering but does not write files. The method does not create git branches, tags, commits, package artifacts, or GitHub Releases; workflows own those operations. Callers should treat any readiness errors as blocking and should avoid running against a dirty or concurrently modified tree. Writes are sequential rather than transactional. If the local process fails after some files are written, rerun git status and remove or revert the partial generated artifacts before retrying so create-only target checks do not stop the next run.
ReleaseEvidence
SourceCreates and validates checked-in release evidence bundles.
Remarks
Release evidence is repository consistency evidence, not a signature or hosted-build attestation. The bundle ties together release-owned files, package release-note paths, optional docs archive catalog fields, and split commit identities so release preparation can be reviewed in a pull request and publishing can validate the same bundle at the annotated tag commit.
BuildDraft
ReleaseEvidenceBundle BuildDraft(ReleaseWorkspace workspace, SemVer version, string releaseClassification, DateOnly date, string? contentSourceCommit, string releaseNoteContent, string releaseSidecarContent, string releaseManifestContent, IReadOnlyList<PackagePathUpdate> packagePathUpdates)
Source
Builds a draft release evidence bundle for release preparation.
ValidatePreparedAsync
Task<ReleaseEvidenceValidationResult> ValidatePreparedAsync(ReleaseWorkspace workspace, SemVer version, string releaseClassification, string? contentSourceCommit, CancellationToken cancellationToken)
Source
Validates a checked-in release evidence bundle in the current worktree.
ValidateTag
ReleaseEvidenceValidationResult ValidateTag(SemVer version, string releaseClassification, string tag, string tagCommit, string releaseNoteJson, string releaseSidecarJson, string releaseManifestJson, string evidenceJson)
Source
Validates release evidence read from an annotated tag.
ReleaseCliApp
SourceDI-backed execution runtime for release CliFx commands.
RunAsync
Task RunAsync(string[] args, Action<ConsoleOptions>? configureOptions = null)
Source
Runs release commands through the shared AppSurface command-service primitive.
Parameters
argsCommand-line arguments.configureOptionsOptional console configuration.
Returns
A task that completes when command execution finishes.
ReleaseChecker
SourceValidates release inputs and computes release readiness diagnostics.
CheckAsync
Task<ReleaseCheckResult> CheckAsync(ReleaseOptions options, CancellationToken cancellationToken)
Source
Runs local release readiness checks.
Parameters
optionsRelease command options.cancellationTokenCancellation token.
Returns
Readiness result with errors, warnings, and generated paths.
ReleaseWorkspace
SourceRepository path helper for release-owned files.
Remarks
Paths are rooted under RepositoryRoot and accept slash-separated repository-relative inputs. PathFor rejects rooted paths and traversal that would escape the repository. Use IsUnderPath when checking paths that come from command-line input, temporary files, or other untrusted sources.
ReleaseNotePath
string ReleaseNotePath(SemVer version)
Source
Gets the absolute path for a release note file.
Parameters
versionRelease version.
Returns
Absolute release note path.
ReleaseSidecarPath
string ReleaseSidecarPath(SemVer version)
Source
Gets the absolute path for a release note sidecar file.
Parameters
versionRelease version.
Returns
Absolute sidecar path.
ReleaseManifestPath
string ReleaseManifestPath(SemVer version)
Source
Gets the absolute path for a release manifest file.
Parameters
versionRelease version.
Returns
Absolute manifest path.
ReleaseEvidencePath
string ReleaseEvidencePath(SemVer version)
Source
Gets the absolute path for a release evidence bundle file.
Parameters
versionRelease version.
Returns
Absolute release evidence bundle path.
PathFor
string PathFor(string relativePath)
Source
Resolves a repository-relative path and verifies that the result stays inside the repository root.
Parameters
relativePathRepository-relative path using slash separators and no leading root.
Returns
Absolute path under RepositoryRoot.
Exceptions
ArgumentExceptionThrown whenrelativePathis rooted or traverses outside the repository.
DisplayPath
string DisplayPath(string path)
Source
Formats an absolute path as a slash-normalized repository-relative path.
Parameters
pathAbsolute path.
Returns
Repository-relative path when possible.
IsUnderPath
bool IsUnderPath(string root, string path)
Source
Determines whether a path is under the supplied root.
Parameters
rootRoot path.pathCandidate path.
Returns
true when the path is equal to or below the root.
RepositoryRoot
string RepositoryRoot { get; }
Source
Gets the absolute repository root.
ChangelogPath
string ChangelogPath { get; }
Source
Gets the absolute changelog path.
UnreleasedPath
string UnreleasedPath { get; }
Source
Gets the absolute unreleased note path.
UnreleasedSidecarPath
string UnreleasedSidecarPath { get; }
Source
Gets the absolute unreleased sidecar path.
PackageIndexPath
string PackageIndexPath { get; }
Source
Gets the absolute package index manifest path.
TemplatePath
string TemplatePath { get; }
Source
Gets the absolute tagged-release template path.
CoverageAnchor
SourcePrevents trimming coverage from depending on generated process-start wiring.
ReleasePublishing
SourceValidates tag state and produces GitHub Release workflow outputs.
PublishAsync
Task<PublishOutputs> PublishAsync(ReleaseOptions options, CancellationToken cancellationToken)
Source
Validates an existing annotated tag and extracts release notes from the tag commit.
Parameters
optionsPublish command options. The version and tag must match, and stable versions are blocked until stable package publishing is protected.cancellationTokenCancellation token.
Returns
Structured workflow outputs for GitHub Release creation.
Remarks
PublishAsync is create-only: it verifies annotated tag shape, reachability from origin/main, prerelease package publication, absence of an existing GitHub Release, and presence of releases/v{version}.md in the tag commit. The tag commit must also contain the release sidecar, release manifest, and release evidence bundle; missing or invalid tag-bound artifacts fail fast before a GitHub Release is created. The method writes the tag's release note to a temporary file so workflows can pass a stable notes path to GitHub's release action.
WriteOutputsAsync
Task WriteOutputsAsync(PublishOutputs outputs, ReleaseOptions options, CancellationToken cancellationToken)
Source
Writes publish outputs to a GitHub Actions output file when requested.
Parameters
outputsPublish outputs.optionsRelease command options.ReleaseOptions.GitHubOutputPathmust be a file path, not a root directory.cancellationTokenCancellation token.
Remarks
Scalar outputs use name=value. Multiline outputs use GitHub's delimiter form. Existing files are appended to match GITHUB_OUTPUT behavior.
ReleaseDiagnostic
SourceDiagnostic envelope with a stable code and reader-actionable context.
Error
ReleaseDiagnostic Error(string code, string problem, string cause, string fix, string docs)
Source
Creates an error diagnostic.
Warning
ReleaseDiagnostic Warning(string code, string problem, string cause, string fix, string docs)
Source
Creates a warning diagnostic.
Render
string Render()
Source
Renders the diagnostic envelope for CLI stderr.
Returns
Human-readable diagnostic envelope.
ReleaseToolException
SourceException that carries a structured release diagnostic.
Diagnostic
ReleaseDiagnostic Diagnostic { get; }
Source
Gets the structured diagnostic.