doctor

Documentation

Overview

Package doctor diagnoses repository state issues that monorel's release planner won't catch on its own.

The motivating case: a stale-branch + squash-merge revival of a previously-consumed `.changeset/*.md` file. After a release ships, the `chore(release):` commit deletes the consumed changesets. If a contributor branched from main BEFORE that release commit and later squash-merges their PR, GitHub re-introduces the deleted files. The next release-pr cycle then re-ships the same content under a new version. monorel's planner is doing exactly what its spec says (changesets on main = stuff to release); the input is the bug. doctor catches the bad input.

monorel's CLI exposes Run via `monorel doctor`. Programmatic callers (custom CI checks, lint scripts) can invoke Run directly against any git seam by supplying a GitLog function.

Index

• Constants
• type Finding
  • func Run(opts Options) ([]Finding, error)
• type GitLog
• type Options
• type Severity

Constants

const CheckNameRevivedChangeset = "revived-changeset"

CheckNameRevivedChangeset is the [Finding.CheckName] value the revived-changeset diagnostic emits. Exported so callers can match findings by check name without hardcoding the string:

for _, f := range findings {
    if f.CheckName == doctor.CheckNameRevivedChangeset { ... }
}

const DefaultReleaseCommitGrep = "chore(release):"

DefaultReleaseCommitGrep is the substring Run uses when Options.ReleaseCommitGrep is empty. Matches every commit message monorel writes via `monorel apply` / `monorel release`.

Types

type Finding

type Finding struct {
	// Severity is the urgency classification.
	Severity Severity

	// CheckName names the diagnostic that produced the finding
	// (e.g. "revived-changeset"). Stable; safe to match in tests.
	CheckName string

	// Path is the repo-relative path the finding refers to.
	// May be empty for findings not tied to a single file.
	Path string

	// Message is a one-sentence human-readable explanation.
	Message string
}

Finding is one issue Run surfaced.

func Run

func Run(opts Options) ([]Finding, error)

Run executes every built-in check against the repository state described by opts. Returns the findings in deterministic order (sorted by CheckName, then Path) plus any error encountered while gathering inputs (e.g. failure to list previously-deleted files).

An empty findings slice with a nil error means "nothing wrong." A non-empty slice with a nil error means the checks ran cleanly and surfaced issues in the repository; callers decide whether to treat findings as blocking based on each finding's Severity.

type GitLog

type GitLog func(messageGrep string) ([]string, error)

GitLog is the slice of git history doctor needs. The function returns every file path deleted by a commit whose subject or body contains messageGrep as a literal substring. Match is case-sensitive; not a regex.

Implemented by `internal/git.Repo.DeletedFilesInCommitsMatching`; other callers can adapt any git library by supplying a function with this signature.

type Options

type Options struct {
	// RepoDir is the repository root (the directory containing
	// `monorel.toml` and `.changeset/`). Required.
	//
	// The doctor package only supports the canonical changeset
	// directory name `.changeset`. Two reasons: monorel itself
	// only writes that name, and the historical scan matches
	// against `git log --name-only` output, which always emits
	// repo-relative paths starting with that prefix. If a future
	// monorel version supports a different name, this option
	// would gain a sibling for the override.
	RepoDir string

	// GitLog returns previously-deleted files for a given commit-
	// message substring. Required.
	GitLog GitLog

	// ReleaseCommitGrep is the literal substring used to identify
	// release commits in the git log. Defaults to
	// "chore(release):" (matching monorel's own release commits).
	// Override only when integrating against a release-commit
	// convention monorel did not produce.
	ReleaseCommitGrep string
}

Options configures a Run invocation.

type Severity

type Severity string

Severity classifies a Finding's urgency. The string form is the JSON wire value; matches the constants the validate package uses for the same concept.

const (
	// SeverityError flags an issue that will produce a wrong
	// release if not fixed. Callers should fail closed.
	SeverityError Severity = "error"

	// SeverityWarning flags an issue that may not break a release
	// but usually indicates a mistake. Callers may surface as a
	// warning without failing the build.
	SeverityWarning Severity = "warning"
)