Documentation
¶
Overview ¶
Package report renders seamark's text reports — the shared surface behind the CLI, the MCP server, and anything else that answers questions from the index. Reports are deliberately plain, compact text: agents consume them verbatim, so every line costs tokens.
Index ¶
- Constants
- func ChangeSet(w io.Writer, st *store.Store, root string, files []string) error
- func Decision(w io.Writer, d *gate.Decision)
- func Expand(w io.Writer, st *store.Store, root, ref string) error
- func FixCount(decisions []model.Decision) int
- func LedgerForRegion(st *store.Store, region string) ([]model.Lesson, error)
- func LessonScope(file string) string
- func LessonsForScope(st *store.Store, cfg *reviews.Config, file string, limit int) ([]model.Lesson, error)
- func LessonsForScopeBudget(st *store.Store, cfg *reviews.Config, file string, limit, pinBudget int) ([]model.Lesson, int, error)
- func Orient(w io.Writer, st *store.Store, root string) error
- func PrintDistillPlan(w io.Writer, res DistillSummary, pending []model.Proposal)
- func PrintFiringSummary(w io.Writer, s reviews.Summary)
- func PrintLessonLedger(w io.Writer, lessons []model.Lesson, cfg *reviews.Config, scope string)
- func PrintLessonReminder(w io.Writer, file string, lessons []model.Lesson, morePins int) error
- func PrintProposalLedger(w io.Writer, pending, applied, dismissed []model.Proposal, ...)
- func Why(w io.Writer, st *store.Store, root, query string) error
- type DistillSummary
Constants ¶
const MinFixDensityHistory = 5
MinFixDensityHistory is the least history a fix-density figure needs before it is worth stating: "1 of the last 2 commits" is noise, not a 50% hotspot.
Variables ¶
This section is empty.
Functions ¶
func ChangeSet ¶
ChangeSet reports what a planned edit to the given files drags along: the files history says change together with them, the externally visible symbols whose callers will feel the edit, and the effect tags the change can ultimately reach. This is the pre-edit question — "what am I about to forget?" — answered from evidence, not vibes.
func Decision ¶
Decision writes the verdict block shared by `seamark gate`, `seamark check`, and the MCP check tool. Rule messages come from workspace policy files — untrusted in a cloned repo, hence the wash.
func Expand ¶
Expand resolves ref — a symbol name/FQN, "file:start[-end]", or "lessons:<dir>" — and writes what it names: source lines, or an area's raw review-lesson ledger. This is the second half of every other report's contract: they return refs, Expand turns a ref into content.
func FixCount ¶
FixCount reports how many of these decisions were corrections — reverts, plus every commit the fix miner would classify as a fix. Exported because more than one surface ranks files by it (the `why` fix-density line, the HTML report's heat colours), and two surfaces counting different commits would disagree about which file is hot.
func LedgerForRegion ¶
LedgerForRegion returns every mined lesson in a region's area: the region itself, everything beneath it, and the ancestor regions that cover it. An empty region is the whole repo. This is the raw-material view shared by `lessons --list/--region` and `expand lessons:<dir>`.
func LessonScope ¶
LessonScope is the area a file's raw-lesson hint points at: its directory, or the file itself at the repo root (root files stay file-scoped everywhere in the lessons layer). Exported because the hotspot map scopes a file's cell the same way — clicking a cell must find the lessons that would fire when editing it.
func LessonsForScope ¶
func LessonsForScope(st *store.Store, cfg *reviews.Config, file string, limit int) ([]model.Lesson, error)
LessonsForScope returns the lessons to surface for a file, after the config's mute/pin/threshold rules — the single path every surface (why, orient, the edit hook) shares, so they never disagree.
func LessonsForScopeBudget ¶
func LessonsForScopeBudget(st *store.Store, cfg *reviews.Config, file string, limit, pinBudget int) ([]model.Lesson, int, error)
LessonsForScopeBudget is LessonsForScope with a pin cap for ambient surfaces (the edit hook); trimmed reports how many applicable pins the budget held back, so the caller can point at them instead of hiding them.
func Orient ¶
Orient writes the repo overview an agent needs before its first edit: scale, module layout, the load-bearing API, the files whose changes travel in groups, and the recent decision trail. One screen, not a tour — every extra line here is paid on every onboarding.
func PrintDistillPlan ¶
func PrintDistillPlan(w io.Writer, res DistillSummary, pending []model.Proposal)
PrintDistillPlan renders a distillation run and the full pending plan: every proposal awaiting a decision, this run's newcomers included. Proposal text is model output — untrusted — so it is sanitized; notes are never truncated (they are the payload).
func PrintFiringSummary ¶
PrintFiringSummary renders the edit-hook firing log: how often lessons actually reached an agent, and which would surface but never have — the decay signal (a lesson whose region no edit touches is a pruning candidate). All lesson text is untrusted, hence sanitized.
func PrintLessonLedger ¶
PrintLessonLedger lists every mined lesson in scope ("" = repo-wide) — the raw material for tuning .seamark/lessons.yaml. Below-threshold one-offs are shown too (they are exactly what a reader might want to mute or pin), each marked if the current config already hides it, followed by copy-paste config syntax and the promotion nudge: spotting a pattern in this list is how a lesson becomes a pin.
func PrintLessonReminder ¶
PrintLessonReminder writes a compact standalone lessons block for one file — used by `seamark lessons` and the PreToolUse edit hook. Writes nothing when there are no lessons, so the hook stays silent. morePins is how many applicable pins the injection budget held back; they are pointed at, never silently dropped.
func PrintProposalLedger ¶
func PrintProposalLedger(w io.Writer, pending, applied, dismissed []model.Proposal, clusters [][]model.Proposal, )
PrintProposalLedger renders the distillation decision record: what is still pending (with the full note and the commands that decide it), then what was applied or dismissed, compactly. Read-only — unlike --distill, it never spends an agent call, so "what did I decide?" and "what is waiting?" cost nothing to ask.
Types ¶
type DistillSummary ¶
type DistillSummary struct {
GroupsTotal int
GroupsRead int
GroupsSkipped int
GroupsFailed int
GroupsPending int
PrunedStale int
Duplicates int
// TokensNote is the caller-rendered cost line ("~59k tokens sent …"),
// empty when nothing was sent.
TokensNote string
}
DistillSummary is the run-shape PrintDistillPlan reports; a mirror of distill.Result's counters, kept here so report does not import the distill package.
Source Files