code

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package code renders a code artifact body into the server-side, line numbered, syntax-highlighted HTML fragment the app shell drops into its body slot, together with a navigable symbol outline and the facts the metadata panel shows — the code-viewer analogue of internal/markdown (SPEC-0003 REQ "Code Viewer").

Highlighting is done entirely on the server with a pure-Go lexer (github.com/alecthomas/chroma/v2), so a viewer with JavaScript disabled still gets a highlighted, line-numbered, readable rendering — only the interactive line-comment/react affordances are JS-layered (SPEC-0003 REQ "Progressive Enhancement"). chroma's HTML formatter HTML-escapes every token's text, so the rendered fragment can never execute source content as markup (SPEC-0003 Security: "source is escaped, never executed") — the same "trusted because already-escaped" contract internal/markdown's sanitizer establishes for its own package.

Governing: ADR-0011 (server-rendered viewer fragments, no build step), ADR-0006 (deterministic, stable anchors), SPEC-0003 REQ "Code Viewer", REQ "Code Annotation Anchors", REQ "Progressive Enhancement", Security Requirements.

Index

Constants

View Source 
const PlainTextKey = "text"

PlainTextKey is Language.Key when detection found no lexer. Callers deciding whether a body is highlightable at all compare against this rather than the bare string, so the sentinel has one definition.

Variables

This section is empty.

Functions

func Fragment 

func Fragment(r *Rendered) (template.HTML, error)

Fragment renders a previously-parsed code body into the body-slot HTML fragment. The result is trusted template output: the per-line HTML was escaped by chroma in Render, and the chrome is auto-escaped here, so the shell emits it verbatim into its body slot.

func RenderFragment 

func RenderFragment(source []byte, mediaType, title, langOverride string) (template.HTML, error)

RenderFragment is the one-shot convenience the BodyViewer capability uses: highlight a code body and render its body-slot fragment in a single call.

Types

type Language 

type Language struct {
	Lexer   chroma.Lexer
	Display string
	// Key is a normalized (lowercased) form of the lexer's canonical name,
	// used to select the symbol-outline heuristic (symbols.go) — kept
	// separate from Display so a future rename of the shown label never
	// silently changes which outline heuristic runs.
	Key string
}

Language is the resolved highlighting language for a code artifact: the chroma lexer that tokenises it plus the human-readable name shown in the STATS line and the metadata panel (SPEC-0003 REQ "Code Viewer": "supplies its metadata-panel fields (e.g. language, line count)").

func Detect 

func Detect(override, mediaType, title string) Language

Detect resolves a code artifact's highlighting language from an explicit override, its title's file extension, and its media type, in that precedence order (SPEC-0003 REQ "Code Viewer": "Language detected from media_type/title/extension, overridable"). The title's extension is checked before the media type because a filename is a deliberate, high-signal choice while the media type is frequently a generic "text/plain" that carries no language information at all. Detection never fails: an unrecognized combination degrades to chroma's plaintext lexer, so highlighting is always attempted and a code artifact always renders.

type Line 

type Line struct {
	Num  int
	HTML template.HTML
}

Line is one highlighted, line-numbered row of source: its 1-based line number and its chroma-highlighted, already-escaped HTML.

type Rendered 

type Rendered struct {
	Lines     []Line
	Language  Language
	Outline   []Symbol
	Source    string
	LineCount int
}

Rendered is the full result of rendering a code body: the highlighted lines, the resolved language, the derived symbol outline, and the raw source text (so the client's select-to-comment affordance can compute text_selection offsets against the canonical body — unlike markdown's goldmark transform, highlighting never rewrites the source text, so these offsets land on the exact same characters the stored body carries).

func Render 

func Render(source []byte, mediaType, title, langOverride string) (*Rendered, error)

Render highlights a code body into its line-numbered rows, resolves its language (Detect's override/title/media-type precedence), and derives its symbol outline. Rendering never fails on adversarial or binary-ish input — an unrecoverable lex degrades to the plaintext lexer rather than an error — so a code artifact of any content always renders (mirrors internal/markdown.Render's "never fails" contract).

type Symbol 

type Symbol struct {
	Name string
	Kind string
	Line int
}

Symbol is one entry in the navigable outline: a named declaration and the 1-based source line it starts on, so an outline entry can link straight to its line anchor (SPEC-0003 REQ "Code Viewer": "a navigable list of top-level symbols that jump to their line").

func Outline 

func Outline(source, language string) []Symbol

Outline derives the navigable symbol list for a code body using a per-language heuristic pass (SPEC-0003 REQ "Code Viewer"): declKeyRe plus (for the languages it cannot fully cover) a small set of shape-specific extra passes, applied line by line. language is the lowercased chroma lexer name (Language.Key); unrecognized languages still get the generic pass, which is deliberately keyword-driven so it degrades gracefully rather than finding nothing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.