Documentation
¶
Overview ¶
Package diff produces structured, prose-aware diffs between two versions of a Contexo page. Pages are markdown with optional YAML frontmatter; the differ splits each version into {frontmatter, preamble, ## sections} and reports changes per-field and per-section so prose changes are legible in a way `git diff` is not.
Index ¶
Constants ¶
const ( StatusUnchanged = "unchanged" StatusAdded = "added" StatusRemoved = "removed" StatusModified = "modified" StatusRenamed = "renamed" )
Section status values used in SectionChange.Status and on Preamble.
Variables ¶
This section is empty.
Functions ¶
func ParseHeadings ¶
ParseHeadings returns the ## headings present in the page bytes in occurrence order. Used by blame walks where the caller only needs the heading set per revision (not section bodies). Pages with malformed or missing frontmatter return nil.
Types ¶
type Commit ¶
type Commit struct {
SHA string `json:"sha"`
Author string `json:"author"`
Email string `json:"email"`
Time time.Time `json:"time"`
Message string `json:"message"`
}
Commit is a minimal commit-metadata shape used by the diff package for blame annotation. Mirrors gitstore.CommitMeta on the wire so the JSON shape is stable across packages.
type FrontmatterDiff ¶
type FrontmatterDiff struct {
Changed []FrontmatterFieldChange `json:"changed,omitempty"`
Added []FrontmatterFieldChange `json:"added,omitempty"`
Removed []FrontmatterFieldChange `json:"removed,omitempty"`
}
FrontmatterDiff captures structured changes to YAML frontmatter fields. Scalar changes appear in Changed; list-valued fields use set semantics and surface their adds/removes in Added/Removed with Field+To or Field+From.
type FrontmatterFieldChange ¶
type FrontmatterFieldChange struct {
Field string `json:"field"`
From any `json:"from,omitempty"`
To any `json:"to,omitempty"`
}
FrontmatterFieldChange is one entry in a FrontmatterDiff.
type SectionChange ¶
type SectionChange struct {
Heading string `json:"heading"`
OldHeading string `json:"old_heading,omitempty"`
Status string `json:"status"`
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
LineDiff string `json:"line_diff,omitempty"`
IntroducedBy *Commit `json:"introduced_by,omitempty"`
}
SectionChange is one ## section's diff entry. Status determines which of From/To/LineDiff/OldHeading are populated. OldHeading is set only on StatusRenamed and carries the section's previous heading. IntroducedBy is set only when blame annotation is requested by the caller (e.g. ?blame=true on the HTTP endpoint) — it points to the earliest commit in the page's history where this section heading appeared.
type SectionDiff ¶
type SectionDiff struct {
FromSHA string `json:"from_sha"`
ToSHA string `json:"to_sha"`
Frontmatter FrontmatterDiff `json:"frontmatter"`
Preamble *SectionChange `json:"preamble,omitempty"`
Sections []SectionChange `json:"sections"`
ParseFallback bool `json:"parse_fallback,omitempty"`
}
SectionDiff is the structured diff between two page versions. It is the single value the differ produces; HTTP, CLI, and MCP each render it differently (see format.go).
func PageSections ¶
func PageSections(from, to []byte, fromSHA, toSHA string) SectionDiff
PageSections computes the structured diff between two page byte slices. fromSHA/toSHA are passed through verbatim onto the result; they are not inspected. Returns a SectionDiff with ParseFallback=true and a single preamble entry when frontmatter is malformed on either side.
func (SectionDiff) ToJSON ¶
func (d SectionDiff) ToJSON() ([]byte, error)
ToJSON marshals d for transport over HTTP or MCP. Indent is two spaces.
func (SectionDiff) ToText ¶
func (d SectionDiff) ToText(slug string) string
ToText renders d as a terminal-friendly summary. Designed for `ctx diff` output: leads with the SHA range, then frontmatter changes, then section changes. Modified sections show a count of changed lines rather than the full body to keep typical output short; users can pass --json for the raw data.
Source Files