report

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

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

View Source
const CompanionsTitle = "history suggests also reviewing"

CompanionsTitle heads the closing list in change_set and in check. The trace and the skills read the label, so it is one string.

View Source
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

func ChangeSet(w io.Writer, st *store.Store, root string, files []string) error

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

func CheckAdvisory(w io.Writer, st *store.Store, root string, files []string)

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 CheckCompanions added in v0.6.0

func CheckCompanions(w io.Writer, st *store.Store, root string, files []string)

CheckCompanions prints, after a gate verdict, the files history says usually change with the diff's files but that the diff leaves untouched. A forgotten companion is the omission history can see and a policy over effects cannot. The list is advisory and never part of the verdict; files comes from gate.ChangedPaths, like the lessons advisory, so the section can never disagree with the verdict about what changed. It degrades to silence on any error.

func Decision

func Decision(w io.Writer, d *gate.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

func Expand(w io.Writer, st *store.Store, root, ref string) error

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

func FixCount(decisions []model.Decision) int

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

func LedgerForRegion(st *store.Store, region string) ([]model.Lesson, error)

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

func LessonScope(file string) string

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

func Orient(w io.Writer, st *store.Store, root string) error

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,
	notes map[int64][]string, scopeFlagged []string,
)

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). notes carries caller-rendered annotation lines per proposal id — trigger confirmations and scope advisories (report does not import distill). scopeFlagged lists the pN ids whose delivery may miss the trigger; they get the tail hint. Nil for both: the plan prints exactly as before.

func PrintFiringSummary

func PrintFiringSummary(w io.Writer, s reviews.Summary)

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

func PrintLessonBlock(w io.Writer, header string, lessons []model.Lesson, trimmed int)

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

func PrintLessonLedger(w io.Writer, lessons []model.Lesson, cfg *reviews.Config, scope string)

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

func PrintLessonReminder(w io.Writer, file string, lessons []model.Lesson, morePins int) error

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 PrintOutcomes added in v0.3.0

func PrintOutcomes(w io.Writer, applied []model.Proposal, readings map[int64]outcome.Reading)

PrintOutcomes renders the passive loop's verdicts under --stats: an aggregate count line, then one verdict sentence per measured pin. Not-landing pins print first because they are the ones that need action. When nothing was measured it prints nothing, not an empty header.

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.

func Why

func Why(w io.Writer, st *store.Store, root, query string) error

Why resolves query as a file or symbol and writes the full report: definition, callers/callees with derivation, co-change, decisions.

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
	// Scope is the trigger-scope advisory (RFC-004 Phase 1): the note
	// names a path outside the pin's regions and co-change evidence
	// agrees. Empty when the signals do not agree — the common case.
	Scope string
	// Blocked reports confirmed triggers that cannot become delivery
	// scopes (region cap or vanished path). Without it a confirmed
	// miss would be invisible: no drift, no advisory.
	Blocked string
	// Outcome is the passive loop's verdict sentence (outcome.Line)
	// for applied pins. Empty when the pin cannot be measured: pending
	// proposals, pruned pins, hand-written pins without citations.
	Outcome string
	// Escalate is true for not-landing pins: the pin fires and the
	// mistake recurs anyway. Drives the escalation hint in the ledger.
	Escalate bool
	// Pruned is true for applied rows whose pin is not in
	// .seamark/lessons.yaml (hand-pruned, or an apply block never
	// pasted). The pin delivers nothing, so region advice is
	// suppressed — a retarget hint here would name a pin the command
	// cannot find.
	Pruned bool
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL