render

Documentation

Overview

Package render is the pure presentation layer for assent (P5-E8, ADR-0016).

decision.PresentationModel is the sole frozen render contract — renderers consume that type (validated against schemas/decision/v1alpha1/presentation-model.schema.json) and must not introduce parallel wire structs. Ephemeral render.Context bundles resolved Options, CEL activation, and pack-rule metadata at render time (D-096); it is never serialized.

Index

• Constants
• Variables
• func CatalogFor(opts Options) (locale.Catalog, []locale.Warning)
• func Chrome(opts Options, id string) (string, []locale.Warning)
• func Clamp(s string, maxRunes int) string
• func Envelope(m forge.Marker, body string) (string, error)
• func EscapeAndClamp(s string) string
• func EscapeMarkdown(s string) string
• func EvalDebugLine(ruleName string, index int, ctx Context) (string, error)
• func EvalDocsSummary(ruleName string, ctx Context) (string, error)
• func EvalMessage(tmpl string, ctx Context) (string, error)
• func EvalRuleMessage(ruleName string, ctx Context) (string, error)
• func FormatFactValue(f aggregate.Fact) string
• func FormatMarker(m forge.Marker) (string, error)
• func RedactFacts(facts map[string]map[string]aggregate.Fact) map[string]map[string]string
• func RenderFactsSection(facts map[string]map[string]aggregate.Fact, opts Options) string
• func RenderFindingThread(pm decision.PresentationModel, finding decision.Finding, ctx Context) (string, error)
• func RenderSummary(pm decision.PresentationModel, ctx Context) (string, error)
• type Context
  • func LoadRenderContext(raw []byte) (Context, error)
• type Fixture
  • func LoadPresentationModel(raw []byte) (Fixture, error)
• type Options
  • func DefaultOptions() Options
  • func OptionsForEnvironment(cfg *policy.Config, envName string) Options
• type RuleDocs
• type RuleMeta

Constants

const (
	// VerbosityMinimal omits evaluation details in rendered output (ADR-0016 §1).
	VerbosityMinimal = "minimal"
	// VerbosityStandard is the default renderer detail level (D-089).
	VerbosityStandard = "standard"
	// VerbosityFull shows all evaluation detail blocks.
	VerbosityFull = "full"

	// DefaultLocale is the shipped locale catalog id (D-089, ADR-0016 §5).
	DefaultLocale = "en"
	// DefaultCollapseThreshold hides detail bodies beyond N same-code findings (D-089).
	DefaultCollapseThreshold = 5
)

const ClampEllipsis = "…"

ClampEllipsis is the stable suffix appended when Clamp truncates (D-091).

const DefaultClampRunes = 500

DefaultClampRunes is the D-091 per-field rune limit for forge-facing markdown.

const MarkerSentinel = "assent:marker"

MarkerSentinel is the opening token of the hidden-HTML marker comment (docs/contracts/p3-e5-publication-protocol/marker-grammar.md).

const RedactedDisplay = "[redacted]"

RedactedDisplay is the forge-facing placeholder for sensitive fact values (D-090).

Variables

var (
	// ErrEmbeddedMarkerSentinel is returned when the body region carries the marker
	// sentinel and could forge or confuse reconciliation parsing.
	ErrEmbeddedMarkerSentinel = errors.New("render: body contains assent:marker sentinel")
	// ErrPrematureCommentClose is returned when the body region closes an HTML
	// comment prematurely and could truncate the envelope marker.
	ErrPrematureCommentClose = errors.New("render: body contains premature HTML comment close")
)

Functions

func CatalogFor

func CatalogFor(opts Options) (locale.Catalog, []locale.Warning)

CatalogFor resolves the full chrome catalog for opts.Locale.

func Chrome

func Chrome(opts Options, id string) (string, []locale.Warning)

Chrome resolves a fixed renderer string for opts.Locale. Unknown locales fail closed to the en catalog and return a non-fatal warning (E8-S03).

func Clamp

func Clamp(s string, maxRunes int) string

Clamp shortens s to at most maxRunes runes, appending ClampEllipsis when truncated. Values within the limit are returned unchanged.

func Envelope

func Envelope(m forge.Marker, body string) (string, error)

Envelope wraps markdown body content with exactly one renderer-owned marker comment outside the user/content region (ADR-0016 §1, D-094).

func EscapeAndClamp

func EscapeAndClamp(s string) string

EscapeAndClamp applies EscapeMarkdown then Clamp at DefaultClampRunes (D-091). Layout assembly for interpolated scalars must use this helper (or both steps).

func EscapeMarkdown

func EscapeMarkdown(s string) string

EscapeMarkdown renders a scalar safe for forge-facing markdown: raw HTML and markdown link syntax are neutralized so values cannot forge approvals or break renderer-owned <details> regions (ADR-0012 amendment, E8-S05).

Order is load-bearing: (1) backslash-escape markdown specials that enable links, emphasis, or headings; (2) HTML-entity-escape &, <, >. Numeric-entity encoding of brackets is insufficient — CommonMark/GitLab decode entities before inline parsing, reviving [text](url) links.

func EvalDebugLine

func EvalDebugLine(ruleName string, index int, ctx Context) (string, error)

EvalDebugLine renders one debug: line for ruleName from ctx.Rules.

func EvalDocsSummary

func EvalDocsSummary(ruleName string, ctx Context) (string, error)

EvalDocsSummary renders docs.summary for ruleName from ctx.Rules.

func EvalMessage

func EvalMessage(tmpl string, ctx Context) (string, error)

EvalMessage renders a message template whose {{ }} slots are CEL expressions over ctx.Activation using the same predicate-scope env as aggregate evaluation (D-095). Unknown fields fail at compile time; interpolated scalars are redacted (when a fact envelope is sensitive) then EscapeAndClamp'd (D-090/D-091).

func EvalRuleMessage

func EvalRuleMessage(ruleName string, ctx Context) (string, error)

EvalRuleMessage renders the pack rule message for ruleName from ctx.Rules.

func FormatFactValue

func FormatFactValue(f aggregate.Fact) string

FormatFactValue returns the forge-facing display string for one fact value: redaction decision first, then EscapeAndClamp (D-090 / D-091).

func FormatMarker

func FormatMarker(m forge.Marker) (string, error)

FormatMarker serialises a forge.Marker to the hidden-HTML comment form. JSON field order follows struct declaration for deterministic round-trips.

func RedactFacts

func RedactFacts(facts map[string]map[string]aggregate.Fact) map[string]map[string]string

RedactFacts builds a provider→name→semantic display map for presentation. Values are not escaped — apply FormatFactValue or EscapeAndClamp at layout assembly. CEL activation retains raw values (D-068 / D-090 handoff).

func RenderFactsSection

func RenderFactsSection(facts map[string]map[string]aggregate.Fact, opts Options) string

RenderFactsSection renders a minimal evaluation-details markdown block listing fact paths and display values. Full finding-thread layout lands in E8-S08; this API is the redaction seam exercised by S06 tests.

func RenderFindingThread

func RenderFindingThread(pm decision.PresentationModel, finding decision.Finding, ctx Context) (string, error)

RenderFindingThread renders one finding's ADR-0012 default-theme forge thread body (headline, resolve CTA, collapsible docs + evaluation details). The caller wraps the returned body with Envelope for forge markers (E8-S04).

func RenderSummary

func RenderSummary(pm decision.PresentationModel, ctx Context) (string, error)

RenderSummary renders the ADR-0012 default-theme per-MR summary comment body (decision headline, score vs threshold, finding index). The caller wraps the returned body with Envelope for forge markers (E8-S13); forge UpsertComment owns Envelope — do not double-wrap at buildDesired.

Types

type Context

type Context struct {
	Options       Options
	Activation    any
	Rules         map[string]RuleMeta
	RiskThreshold int // binding approve threshold for summary score line (E8-S13)
}

Context is the ephemeral render-time bundle (D-096): resolved Options, CEL activation, and pack-rule metadata. It is never serialized and is not a frozen contract beside PresentationModel.

func LoadRenderContext

func LoadRenderContext(raw []byte) (Context, error)

LoadRenderContext decodes render-context.json fixture bytes into the ephemeral render.Context (Options, CEL activation, pack-rule metadata — D-092/D-096). Pure — no filesystem I/O.

type Fixture

type Fixture struct {
	Presentation decision.PresentationModel
}

Fixture is a typed PresentationModel loaded for render tests and goldens. Bytes are decoded strictly against the frozen schema; no rendered output yet.

func LoadPresentationModel

func LoadPresentationModel(raw []byte) (Fixture, error)

LoadPresentationModel validates raw JSON against PresentationModelSchema and decodes it into decision.PresentationModel. Pure — no filesystem I/O.

type Options

type Options struct {
	Verbosity         string
	Emoji             bool
	CollapseThreshold int
	Locale            string
}

Options holds resolved presentation knobs (E8-S02 populates from config).

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns D-089 presentation defaults when config omits the block.

func OptionsForEnvironment

func OptionsForEnvironment(cfg *policy.Config, envName string) Options

OptionsForEnvironment resolves render.Options for envName from cfg's optional presentation block: global knobs first, then the first matching environment override (D-089).

type RuleDocs

type RuleDocs struct {
	Summary string
	URL     string
}

RuleDocs holds docs.* metadata from a pack rule.

type RuleMeta

type RuleMeta struct {
	Message string
	Docs    RuleDocs
	Debug   []string
}

RuleMeta holds pack-rule metadata used during message rendering (E8-S07).