Documentation
¶
Overview ¶
Package docmaintain implements an explicitly enabled, bounded local session that keeps one human documentation page's generated blocks in sync with immutable Git source, per the IPR-05 slice of docs/plans/integrated-product-roadmap-2026-09-12.md and the maintenance requirements in docs/specs/source-documentation-draft-v0.md (SDD-V0-007+).
A session never renders a document (docs/specs/human-documentation-compiler-v0.md remains not-started) and never promotes generated prose to accepted intent (AGENTS.md invariant 8); it only refreshes source-pinned Markdown blocks that the same native corvint.docs_draft compiler (internal/doccompiler.DraftSources over internal/contextindex.BuildContext) already produces, inside explicit begin/end markers, leaving every other byte of the page untouched.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BlockOutcome ¶
type BlockOutcome struct {
Selector Selector
Existed bool // a generated block for this selector was already in the page
Eligible bool // its content digest differs from the page's recorded digest (or it did not exist)
Applied bool // this session actually rewrote it
Skipped string
OldSHA256 string
NewSHA256 string
Commit string
Tree string
}
BlockOutcome reports what happened to one selector's generated block.
type Policy ¶
type Policy struct {
Enabled bool
Apply bool
MaxWrites int
MaxWallClock time.Duration
// contains filtered or unexported fields
}
Policy bounds one session. Enabled must be true or Run refuses outright. Apply authorizes writing; false always previews only, regardless of what eligible changes are found. MaxWrites and MaxWallClock bound how much of a multi-selector session executes before it stops cleanly.
type Receipt ¶
type Receipt struct {
Page string
Selectors []Selector
StartedAt time.Time
FinishedAt time.Time
PageExistedAtStart bool
PageDigestBefore string
PageDigestAfter string
Applied bool
PreviewOnly bool
Conflict bool
ConflictDetail string
Blocks []BlockOutcome
StoppedReason string // "", "max-writes", "max-wall-clock"
}
Receipt is the durable session record: source identities, page digest before/after, and whether the session previewed or applied.
type Refusal ¶
type Refusal struct{ Code string }
Refusal is a closed, sanitized session refusal (disabled policy, invalid selector, unauthorized apply, or a write-time conflict). It never carries underlying process output.
type Result ¶
Result is what Run returns: the proposed page content, a unified diff against the bytes read at session start, and the session Receipt.
func Apply ¶
Apply authorizes and performs the write a prior Preview proposed. It refuses unless policy.Apply is true, and it refuses — writing nothing — if the page's bytes on disk no longer equal exactly what Preview started from: that is the session's whole conflict boundary, and it never applies part of a proposal. Applying a Preview that found nothing eligible is a harmless no-op (Applied stays false).
func Preview ¶
func Preview(ctx context.Context, root, page string, selectors []Selector, policy Policy) (*Result, error)
Preview computes, but never writes, the proposed page content for page (repository-relative to root) over selectors, in order: it detects which generated blocks are eligible for refresh (missing, or whose recorded markdown_sha256 differs from a fresh redraft), skips ineligible/unchanged blocks untouched, and stops accepting further writes once policy.MaxWrites or policy.MaxWallClock is reached — remaining selectors are recorded as skipped, not silently dropped. It requires policy.Enabled but never checks or requires policy.Apply.
func Run ¶
func Run(ctx context.Context, root, page string, selectors []Selector, policy Policy) (*Result, error)
Run is the convenience path: Preview, then Apply when policy.Apply is true. Callers that need to inspect or gate the preview before authorizing the write (e.g. an operator confirmation step) should call Preview and Apply directly instead.
type Selector ¶
Selector names one (owner Markdown source, Go package directory) pair, the same shape corvint.docs_draft accepts (docsbridge.draftInput).
type WatchReceipt ¶
type WatchReceipt struct {
Profile string `json:"profile"`
Cycles int `json:"cycles"`
Writes int `json:"writes"`
StoppedReason string `json:"stopped_reason"`
Complete bool `json:"complete"`
Summaries []WatchSummary `json:"summaries"`
OmittedSummaries int `json:"omitted_summaries"`
}
WatchReceipt is a bounded aggregate for the explicit foreground profile.
Source Files