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 CheckAdvisory(w io.Writer, st *store.Store, root string, files []string)
- 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 LessonsForFiles(st *store.Store, cfg *reviews.Config, files []string, budget int) ([]model.Lesson, int, error)
- 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 PrintLessonBlock(w io.Writer, header string, lessons []model.Lesson, trimmed int)
- 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
- type ProposalHealth
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 CheckAdvisory ¶ added in v0.2.0
CheckAdvisory prints the lessons governing a diff's files after a gate verdict — advisory by contract: it never contributes to the verdict, degrades to silence on any error, and is skipped entirely for machine-readable output. files comes from gate.ChangedPaths, so the advisory can never disagree with the verdict about what changed.
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 LessonsForFiles ¶ added in v0.2.0
func LessonsForFiles(st *store.Store, cfg *reviews.Config, files []string, budget int) ([]model.Lesson, int, error)
LessonsForFiles is the multi-file moment-of-change surface (RFC-002 §8): every file's applicable pins merged by identity, ranked by confidence ACROSS the whole set (a weak pin from the first file must not out-place a strong one from the last), restatements collapsed once globally, mined recurrence appended, all under one budget with an exact held-back count. The shared context — applied proposals, cluster coverage, finding metadata — is loaded once, not per file. Lines show regions, never triggering files: the caller supplied the file list, and a region is exactly the mapping back onto 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 PrintLessonBlock ¶ added in v0.2.0
PrintLessonBlock renders a compact lesson list for multi-file surfaces: the same [pin]/[×N] tags the hook uses, plus the region — on a surface spanning files, the region IS the map back to them.
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, health map[int64]ProposalHealth, )
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 with its evidence health, 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.
type ProposalHealth ¶ added in v0.2.0
type ProposalHealth struct {
Tier string
Facts string
Era string // e.g. "distilled under prompt v1, before the recurrence rule"
Retarget string // recomputed regions when they differ; "" when current
}
ProposalHealth is one proposal's evidence-health summary for the ledger (RFC-002 §7): the confidence tier with its facts, the prompt era when it predates the current recurrence rules, and the regions today's inference would assign when they differ from the stored ones. Computed by the caller (it needs the workspace root); the printer only renders.
Source Files