Documentation
¶
Overview ¶
Changelog rendering (§9.4/§9.6 of docs/TECHNICAL_PLAN.md). Lives in the same render package as review's Artifact/Render — a second artifact type and a second render function, not a second package: the md/text/json mechanics (stripMarkdown, indented JSON encoding) are already format-agnostic and are reused as-is.
Digest rendering (§10.3/§10.5/§10.6 of docs/TECHNICAL_PLAN.md). Same package as review/changelog rendering, for the same reason: a new artifact type and a new render function, reusing the existing format-agnostic mechanics (stripMarkdown, indented JSON encoding).
Package render turns a computed review artifact into output.
It supports three formats (§7.4): "md" (the model's Markdown with a short risk header prepended), "json" (the versioned, documented external contract — field names matter, schema_version bumps only on breaking changes), and "text" (the same content as Markdown with #/**/backtick markup crudely stripped — intentionally rough, no real Markdown parser).
Index ¶
- Constants
- func Render(w io.Writer, art Artifact, format Format) error
- func RenderChangelog(w io.Writer, art ChangelogArtifact, format Format) error
- func RenderDigest(w io.Writer, art DigestArtifact, format Format) error
- func RenderWithTemplate(w io.Writer, art Artifact, format Format, outputTemplateFile string) error
- func RiskHeaderLine(level, summary string, heuristic bool) string
- func TemplateFuncs() template.FuncMap
- type Artifact
- type ChangelogArtifact
- type ChangelogEntry
- type Commit
- type DigestArtifact
- type DigestAuthorStat
- type DigestFileStat
- type DigestTopicStat
- type Format
- type RepoDigest
- type Stats
Constants ¶
const ChangelogSchemaVersion = 1
ChangelogSchemaVersion is the changelog JSON schema version — a separate counter from review's SchemaVersion (§9.4): the two commands have structurally unrelated JSON contracts and unrelated consumers, so a shared numbering space would bump one command's version on a change that touches only the other.
const DigestSchemaVersion = 1
DigestSchemaVersion is the digest JSON schema version — its own counter, independent of review's and changelog's (§9.4/§10.3): unrelated wire contract, unrelated consumers.
const SchemaVersion = 1
SchemaVersion is the JSON output schema version (§7.4). Bumped only on a breaking change (renaming/removing a field or changing a type); adding an optional field does not change it.
Variables ¶
This section is empty.
Functions ¶
func RenderChangelog ¶
func RenderChangelog(w io.Writer, art ChangelogArtifact, format Format) error
RenderChangelog writes the changelog artifact in the requested format to w. A separate function from Render (not an overload/shared interface) — there are exactly two format-agnostic renderers so far, review's and this one; per the project's "interface at the second implementation" rule, no shared abstraction is introduced until a third, genuinely interchangeable consumer appears.
func RenderDigest ¶
func RenderDigest(w io.Writer, art DigestArtifact, format Format) error
RenderDigest writes the digest artifact in the requested format to w.
func RenderWithTemplate ¶ added in v0.2.1
RenderWithTemplate behaves like Render, but uses a custom text/template file for the md format when outputTemplateFile is non-empty. For text/json, outputTemplateFile is ignored (a warning is logged via slog.Warn when a path was set, since it has no effect on those formats).
func RiskHeaderLine ¶ added in v0.3.0
RiskHeaderLine returns the formatted risk header line for the given risk fields. Used by the streaming path, which renders the header after [DONE] rather than through the full Artifact renderer.
func TemplateFuncs ¶ added in v0.3.0
TemplateFuncs returns the FuncMap available to output and system templates. Callers (config validation, prompt building) use this to register the same functions so template parse errors surface at load time, not at render time.
Types ¶
type Artifact ¶
type Artifact struct {
GeneratedAt time.Time
Range string
Offline bool
Provider string
Model string
RiskLevel string
RiskSummary string
// RiskHeuristic is true when RiskLevel/RiskSummary came from the deterministic
// heuristic rather than the model's own risk block (offline mode, or the model
// omitted a valid risk block). Surfaced in all three output formats.
RiskHeuristic bool
Stats Stats
Commits []Commit
// ReviewMarkdown is the model's review body with the trailing risk block
// already stripped.
ReviewMarkdown string
}
Artifact is the fully-computed review, carrying everything the renderers need (§7.4). RiskLevel/RiskSummary are always populated (offline and the heuristic fallback guarantee a value).
type ChangelogArtifact ¶
type ChangelogArtifact struct {
GeneratedAt time.Time
Range string
// Categories holds every gitlog.CategoryOrder name, always present
// (possibly with a nil/empty slice) — §9.4 JSON contract.
Categories map[string][]ChangelogEntry
// Breaking is the ordered "⚠ BREAKING CHANGES" list, using each entry's
// BreakingText as Subject (§9.2).
Breaking []ChangelogEntry
// MissingRequiredCategories are the policy.required_changelog_categories
// names with zero entries (§9.3) — always a (possibly empty) slice.
MissingRequiredCategories []string
}
ChangelogArtifact is the fully-computed changelog, carrying everything the renderers need (§9.4).
func NewChangelogArtifact ¶
func NewChangelogArtifact(generatedAt time.Time, revRange string, cl gitlog.Changelog, missingRequired []string) ChangelogArtifact
NewChangelogArtifact builds a ChangelogArtifact from a categorized gitlog.Changelog (§9.5) for the given range and required-category check.
type ChangelogEntry ¶
ChangelogEntry is one changelog line, ready for rendering.
type DigestArtifact ¶
type DigestArtifact struct {
GeneratedAt time.Time
Days int
Since time.Time
Until time.Time
Repos []RepoDigest
}
DigestArtifact is the fully-computed digest, single- or multi-repo (§10.5): a single-repo digest is simply Repos with one element, so there is exactly one Go type and one JSON schema for both cases.
type DigestAuthorStat ¶
DigestAuthorStat, DigestTopicStat and DigestFileStat mirror gitlog.AuthorStat/TopicStat/FileStat as plain render-owned types, so internal/render does not need to import gitlog's aggregation internals beyond the data it actually renders.
type DigestFileStat ¶
type DigestTopicStat ¶
type RepoDigest ¶
type RepoDigest struct {
Path string
Ok bool
Err string
Commits int
FilesChanged int
LinesAdded int
LinesRemoved int
ByAuthor []DigestAuthorStat
ByTopic []DigestTopicStat
TopFiles []DigestFileStat
}
RepoDigest is one repository's digest result, or an error (§10.5). When Err is non-empty, the aggregate fields are the zero value and must not be treated as "zero activity" — Ok distinguishes the two cases explicitly in JSON output.