docpack

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package docpack compiles authored documentation topics into a doc pack — the typed interchange artifact `pxf docs build` emits (issue #170).

The pipeline mirrors `pxf build`'s: sources in, one deterministic binary artifact out, `--check` for CI. What it compiles is prose and anchors rather than schemas, and its two data inputs are the lowered schema image (#164) and the appviewer registry export (trendvidia/appviewer#33) — data, never code. 

topics/*.pxf ─┐
schema image ─┼─► pxf docs build ─► doc pack
registry data ┘

Downstream: appviewer packages the pack as a bundle data section and serves runtime help and search (trendvidia/appviewer#364); goed drives the review states and runs this compiler on its diagnostics debounce (trendvidia/goed#321); the OpenAPI (#173) and static-HTML (#171) renderers read pack plus image.

The package is importable, not CLI-only (#185): goed links its compilers in-process, so the editor integration is Compile on a debounce rather than a subprocess. Three affordances exist for that caller and cost the CLI nothing: Options.Overlay splices unsaved editor buffers into the topic root (topic identity is (key, locale) across the whole root, so a single-buffer check would be unsound); Options.Image and Options.Catalog accept preloaded data inputs so a debounced rebuild does not re-read and re-index them from disk; and LoadImage/LoadCatalog expose the anchor-target sets — FQNs, canonical descriptor paths, widget/prop/event names — that anchor completion offers. The join key throughout is the canonical resolved-id spelling the pack records in `resolved_id`.

Index

Constants

View Source 
const (
	// CoverageWidgets checks registry widget types and @http-annotated
	// methods.
	CoverageWidgets = "widgets"
	// CoverageMembers additionally checks per-widget props and events
	// and the screen-transition vocabulary.
	CoverageMembers = "members"
)

Coverage granularities accepted by Options.Coverage.

View Source 
const (
	TopicFileMessage     = "protowire.docs.v1.TopicFile"
	DocPackMessage       = "protowire.docs.v1.DocPack"
	WidgetCatalogMessage = "protowire.docs.v1.WidgetCatalog"
)

Fully-qualified names of the messages the compiler binds to. Bound by name against the bundled schemas — the same resolution path `pxf` already uses for every other typed document.

Variables

View Source 
var BundledDocsSchemas = []string{
	"docs/v1/topic.proto",
	"docs/v1/pack.proto",
	"docs/v1/registry.proto",
}

BundledDocsSchemas are the canonical documentation schemas, as import paths into the repository's embedded proto/ tree. They are compiled on demand rather than added to schemaresolve.CompileBundledAll: only the docs pipeline needs them, and every other `pxf` subcommand would pay the compile cost for messages it never resolves.

Functions

func AudienceRank 

func AudienceRank(name string) (int, bool)

AudienceRank returns the restriction rank of a protowire.docs.v1 Audience value name ("AUDIENCE_PUBLIC" → 1 … "AUDIENCE_INTERNAL" → 5), with the empty string and AUDIENCE_UNSPECIFIED reading as public. The second result is false for a name outside the taxonomy.

func Digests 

func Digests(inputs []string) ([]TopicDigest, []Diagnostic, error)

Digests reports the content digest of every topic in the inputs.

The review gate compares an approval against a digest, and the translation check compares a translation against one. Both values have to be *recorded in the source* by whoever approves or translates — which means the authoring layer (trendvidia/goed#321) and anyone hand-editing a topic needs a way to compute what the compiler will compute. Without this, the canonical encoding would be knowable only by reading the compiler's source, and a gate nobody can satisfy is a gate everybody routes around.

func Schema 

func Schema() (*schemaresolve.Registry, error)

Schema returns the descriptor registry for the bundled documentation schemas. Compiled once per process: the sources are embedded and immutable, so a second compile could only produce the same answer more slowly.

Types

type Catalog 

type Catalog struct {
	Path   string
	Digest string

	SchemaVersion uint32
	WidgetCount   int
	// contains filtered or unexported fields
}

Catalog is the resolved view of one runtime's widget surface.

func LoadCatalog 

func LoadCatalog(path string) (*Catalog, error)

LoadCatalog reads a widget catalog in any accepted encoding. Compile calls it for Options.CatalogPath; a caller compiling repeatedly (the editor debounce) loads once and passes the result as Options.Catalog, and anchor completion reads the entry sets off it directly (Catalog.Widgets, Catalog.Props, Catalog.Events, Catalog.CommonProps).

func (*Catalog) CommonProps 

func (c *Catalog) CommonProps() []string

CommonProps returns the node-level property names every widget accepts, sorted. A prop anchor naming one resolves on any catalog widget.

func (*Catalog) CompositionProps 

func (c *Catalog) CompositionProps() []string

CompositionProps returns the template-composition attribute names (catalog schema v8), sorted. Like CommonProps, a prop anchor naming one resolves on every catalog widget (#199): the attributes are offered by context, and the context is any node under composition.

func (*Catalog) Events 

func (c *Catalog) Events(widgetType string) []string

Events returns the widget type's event names, sorted. Nil for a type the catalog does not carry.

func (*Catalog) Props 

func (c *Catalog) Props(widgetType string) []string

Props returns the property names a prop anchor on the widget type resolves against — the widget's own props and its structural parent duties (child_props), sorted. Common node props are not included; they resolve on every widget and come from Catalog.CommonProps. Nil for a type the catalog does not carry.

func (*Catalog) ResolveTransition added in v1.8.0 

func (c *Catalog) ResolveTransition(name string) error

ResolveTransition checks a transition anchor's name against the catalog's screen-transition vocabulary (#199). Transitions carry no since-version of their own; a topic states applicability through meta.since instead.

func (*Catalog) ResolveWidget 

func (c *Catalog) ResolveWidget(id string) (since string, err error)

ResolveWidget checks a widget anchor's canonical id against the catalog and returns the target's since-version. The error names what exists, because "no such prop" is only useful next to the props that do exist.

The id is the canonical resolved_id spelling the pack records: the PascalCase type alone ("Button"), or the type plus one member — "Button#prop:text", "Button#event:onTapped". Exported so an editor can validate a completed anchor against exactly the check the compiler will run (#185).

func (*Catalog) Transitions 

func (c *Catalog) Transitions() []string

Transitions returns the accepted screen-transition names (catalog schema v9) in the producer's canonical order (the default first — the order is load-bearing upstream). Each is a transition-anchor target (#199); Catalog.ResolveTransition is the membership check.

func (*Catalog) Widgets 

func (c *Catalog) Widgets() []string

Widgets returns the catalog's widget types, sorted.

type Diagnostic 

type Diagnostic struct {
	Severity Severity
	Loc      Loc
	Message  string
}

Diagnostic is one compiler finding.

func (Diagnostic) String 

func (d Diagnostic) String() string

type ElementKind added in v1.9.0 

type ElementKind string

ElementKind is what kind of schema element a fully-qualified name names in an image. The values are stable display spellings — "enum value", "type alias" — so a hover can render them verbatim, and constants, so a consumer switching on them cannot drift from what the index records. 

const (
	KindMessage   ElementKind = "message"
	KindField     ElementKind = "field"
	KindOneof     ElementKind = "oneof"
	KindEnum      ElementKind = "enum"
	KindEnumValue ElementKind = "enum value"
	KindService   ElementKind = "service"
	KindMethod    ElementKind = "method"
	KindTypeAlias ElementKind = "type alias"
)

type Image 

type Image struct {
	Path      string
	Digest    string
	FileCount int
	// contains filtered or unexported fields
}

Image is the resolved view of a lowered FileDescriptorSet.

func LoadImage 

func LoadImage(path string) (*Image, error)

LoadImage reads a lowered image and indexes everything anchors can point at. Compile calls it for Options.ImagePath; a caller compiling repeatedly (the editor debounce) loads once and passes the result as Options.Image, and anchor completion reads the target sets off it directly (Image.FQNs, Image.Paths, Image.AnnotationsOn), hover the element kinds (Image.Kind).

func (*Image) AnnotationsOn 

func (im *Image) AnnotationsOn(fqn string) []string

AnnotationsOn returns the annotation FQNs the image's source maps record on an element, in recorded order. Nil when the element carries none (or does not exist — distinguish with Has).

func (*Image) FQNs 

func (im *Image) FQNs() []string

FQNs returns every addressable schema element in the image — messages, fields, oneofs, enums, enum values, services, methods and v1.2 type aliases — sorted, one spelling per element.

func (*Image) HTTPMethods added in v1.8.0 

func (im *Image) HTTPMethods() []string

HTTPMethods returns the FQNs of methods carrying @http, sorted — the operation surface `pxf openapi` renders and the image half of the doc-coverage denominator (#200).

func (*Image) Has 

func (im *Image) Has(fqn string) bool

Has reports whether the image defines the fully-qualified name — the membership check behind schema anchors.

func (*Image) HasPath 

func (im *Image) HasPath(p string) bool

HasPath reports whether the image's source maps carry this canonical descriptor path — the membership check behind descriptor-path anchors.

func (*Image) Kind added in v1.9.0 

func (im *Image) Kind(fqn string) (ElementKind, bool)

Kind reports what the fully-qualified name is in the image — message, field, oneof, enum, enum value, service, method, or v1.2 type alias — and whether it exists at all. This is the same index resolution checks membership against, so a hover that renders the kind (#206) can never disagree with the compiler; it is also the only place type aliases are visible, since they live in the FileTypeDecls carrier (§8.2), not the descriptor tree.

func (*Image) Paths 

func (im *Image) Paths() []string

Paths returns the canonical §8.3.1 descriptor paths the image's source maps record, sorted.

type Loc 

type Loc struct {
	File   string
	Topic  string
	Line   int
	Column int
}

Loc is where a diagnostic happened: the topic source file, the topic within it when the problem is topic-scoped, and — when the compiler still holds the position — the source coordinates of the entry the check complained about.

File + topic key is the primary address (it is what the authoring layer navigates by); Line and Column exist so an editor placing squiggles does not have to re-parse the sources it just handed the compiler (#187, trendvidia/goed#321). They are 1-based; zero means unknown. The baseline for every topic-scoped diagnostic is the position of the topic's `key` entry; checks that know the offending entry — a review field, a translation digest, a topic-level anchor — point at that entry instead.

type Options 

type Options struct {
	// Inputs are topic roots or files, as given on the command line.
	Inputs []string

	// Overlay substitutes in-memory contents for topic sources, keyed by
	// the root-relative slash-separated path a source is collected under
	// (the path recorded in the pack's provenance and in diagnostics). A
	// key matching a collected file replaces that file's bytes; a key
	// matching nothing is compiled as a new source that exists only in
	// the overlay. Files on disk are otherwise read as usual.
	//
	// This is the editor seam (trendvidia/goed#321): topic identity is
	// (key, locale) across the whole root — duplicate keys, cross-topic
	// links and translation staleness are root-wide checks — so checking
	// one unsaved buffer in isolation would be unsound. The editor
	// compiles the full root with its dirty buffers spliced in.
	Overlay map[string][]byte

	// ImagePath is the lowered FileDescriptorSet schema anchors resolve
	// against. Optional: a corpus with no schema anchors needs no image.
	ImagePath string

	// Image, when non-nil, is an already-loaded image used instead of
	// reading ImagePath. [Compile] re-reads and re-indexes the image on
	// every call otherwise; a caller compiling on a debounce loads it
	// once with [LoadImage] and hands it in.
	Image *Image

	// CatalogPath is the appviewer registry export widget anchors
	// resolve against. Optional, on the same terms.
	CatalogPath string

	// Catalog, when non-nil, is an already-loaded registry export used
	// instead of reading CatalogPath, on the same terms as Image.
	Catalog *Catalog

	// SourceLocale is the locale topics are authored in. Defaults to "en".
	SourceLocale string

	// Release applies release policy: unreviewed topics, unset audience
	// tiers and approvals invalidated by later edits become errors.
	Release bool

	// Coverage enables the doc-coverage policy (#200): every element of
	// the documentable surface must have a documenting topic.
	// CoverageWidgets checks registry widget types and @http-annotated
	// methods; CoverageMembers additionally checks per-widget props and
	// events and the transition vocabulary. Warnings by default, errors
	// under Release. Empty disables the check — existing packs must not
	// start failing on upgrade.
	Coverage string

	// CoverageApproved raises the coverage bar from "documented" to
	// "documented and approved": only REVIEW_STATE_APPROVED topics
	// count toward coverage.
	CoverageApproved bool

	// StaleTranslationsFatal escalates translation drift from warning to
	// error independently of Release, for pipelines that ship no drift.
	StaleTranslationsFatal bool

	// ToolVersion is recorded in the pack's provenance.
	ToolVersion string
}

Options is the resolved input surface of one compilation.

type Result 

type Result struct {
	// Pack is the compiled DocPack, or nil when the build had errors.
	Pack proto.Message

	Diagnostics []Diagnostic
	Errors      int
}

Result is one compilation's output.

func Compile 

func Compile(opts Options) (*Result, error)

Compile runs the whole pipeline. It returns an error only for problems that prevent compiling at all — unreadable inputs, a corrupt image. Everything about the documentation itself comes back as diagnostics, so one bad topic never hides the rest.

type Severity 

type Severity int

Severity distinguishes what fails a build from what merely deserves saying. Errors always fail; warnings fail only when the caller opts into a stricter policy (release builds, --stale-translations=error). 

const (
	SeverityWarning Severity = iota
	SeverityError
)

func (Severity) String 

func (s Severity) String() string

type TopicDigest 

type TopicDigest struct {
	Key    string
	Locale string
	File   string
	Digest string
}

TopicDigest is one topic's identity and content digest.

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.