adf

package
v0.10.6 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyCompatibility 

func ApplyCompatibility(doc Document, schema FieldCompatibility, mode adfmode.Mode) (Document, []Warning, error)

ApplyCompatibility walks doc and reconciles Jira field compatibility. In best-effort mode, unsupported nodes are degraded and each degradation produces one Warning. In strict mode, the first incompatibility aborts with a CompatibilityError; no partial result.

func FromMarkdownLossy 

func FromMarkdownLossy(markdown string) (Document, []Warning, error)

FromMarkdownLossy converts GFM Markdown to an ADF document and reports every Markdown construct it could not represent faithfully in the supported ADF node set. Each unsupported construct yields one Warning (lossy=true) naming the construct and its source position so callers — and strict-mode abort gates — can act on the content loss instead of letting it slip through silently. 

func Hyperlink(url, text string) string

Hyperlink wraps text in an OSC 8 escape pointing at url, for UI chrome (issue keys, breadcrumbs) — terminals that support it make the text clickable; others show it unchanged. Shares osc8's control-byte hygiene.

func Marshal 

func Marshal(doc Document) ([]byte, error)

Marshal serializes a Document back to JSON, preserving opaque subtrees.

func Normalize added in v0.10.0 

func Normalize(d Document) (Document, []Warning)

Normalize repairs structurally-invalid but losslessly-fixable constructs that Jira's ADF validator rejects outright — an opaque INVALID_INPUT on the whole document — even though they carry no renderable content. It returns the cleaned document and one non-lossy Warning per class of repair, and is meant to run just before ValidateDoc so the submitted document is both valid and minimal. Every repair is provably lossless: it changes nothing the user can see, only "rejected by Jira" into "accepted", so it runs in every mode.

Repairs:

  • Empty text nodes. A text node's `text` must be a non-empty string; an empty (or absent) one is rejected by Jira yet renders as nothing. These are a common artifact of document generators that emit blank table cells. Removing them is lossless — the node carried no content — and a parent left with no inline children (e.g. an empty paragraph in a blank cell) is itself valid ADF.

func Parse 

func Parse(data []byte) (Document, []Warning, error)

Parse decodes ADF JSON into a typed Document and returns any best-effort warnings collected during the decode. Unknown nodes/marks are preserved opaquely and surface no warnings on parse — they only matter at render/submit time. A value of the wrong JSON shape (a string where the document object belongs) returns *InvalidDocumentError so the failure carries a stable identity instead of the raw json error text.

func RenderActivatable 

func RenderActivatable(doc Document, opts RenderOptions) string

RenderActivatable renders an ADF document as terminal text with issue keys and bare URLs marked as OSC 8 hyperlinks. When IsTerminal is false, the same call returns plain text without escapes.

func ToMarkdown 

func ToMarkdown(doc Document) string

func ToPlain 

func ToPlain(doc Document) string

Types

type Capabilities 

type Capabilities struct {
	Author   bool `json:"author"`
	Render   bool `json:"render"`
	Preserve bool `json:"preserve"`
	Validate bool `json:"validate"`
	Submit   bool `json:"submit"`
}

Capabilities is the shared envelope's per-row capability struct. All booleans default to false; explicit support is opt-in.

type CompatibilityError 

type CompatibilityError struct {
	Field    string
	NodeType string
	MarkType string
	Path     string
	Reason   string
}

CompatibilityError is the typed error returned by ApplyCompatibility in strict mode when a node would have to be degraded or dropped to fit the target field schema.

func (*CompatibilityError) Error 

func (e *CompatibilityError) Error() string

type Document 

type Document struct {
	Type    string `json:"type"`
	Version int    `json:"version"`
	Content []Node `json:"content,omitempty"`
}

Document is the canonical ADF root.

func (Document) Validate deprecated 

func (d Document) Validate() error

Validate is the legacy mode-unaware validator (kept for backwards compatibility with existing callers). It uses strict mode.

Deprecated: prefer ValidateDoc(doc, adfmode.ModeStrict).

type Entry 

type Entry struct {
	Kind              Kind            `json:"kind"`
	Name              string          `json:"name"`
	Status            Status          `json:"status"`
	Capabilities      Capabilities    `json:"capabilities"`
	InputShape        json.RawMessage `json:"input_shape,omitempty"`
	OutputShape       json.RawMessage `json:"output_shape,omitempty"`
	Warnings          []string        `json:"warnings,omitempty"`
	OfficialURL       string          `json:"official_url"`
	Notes             string          `json:"notes,omitempty"`
	SubmitDescription string          `json:"submit_description"`
}

Entry is one row in the registry — the shared envelope shape. input_shape and output_shape are JSON Schema 2020-12 fragments.

type FieldCompatibility 

type FieldCompatibility struct {
	Field               string
	InlineCardSupported bool
}

FieldCompatibility describes what a single Jira target field will accept. The zero value (no flags set) means "unknown" and unknown is treated as unsupported.

type InvalidDocumentError added in v0.10.0 

type InvalidDocumentError struct {
	// Got names the JSON shape that was supplied ("string", "number", ...).
	Got string
	// Field optionally names the payload key that carried the bad value;
	// callers that know the key tag it after Parse returns.
	Field string
}

InvalidDocumentError reports a value that is not an ADF document object — most commonly a plain string where {"type":"doc",...} is required. It is TYPED so the error mapper can emit a stable adf_invalid code with a clean message instead of leaking the raw json unmarshal error to the envelope.

func (*InvalidDocumentError) Code added in v0.10.0 

func (e *InvalidDocumentError) Code() errtax.Code

Code classifies the failure under the taxonomy's adf_invalid code.

func (*InvalidDocumentError) Error added in v0.10.0 

func (e *InvalidDocumentError) Error() string

type Kind 

type Kind int

Kind tags whether a registry row describes a node or a mark. 

const (
	KindNode Kind = iota
	KindMark
)

func (Kind) MarshalJSON 

func (k Kind) MarshalJSON() ([]byte, error)

func (Kind) String 

func (k Kind) String() string

type LossyConversionError added in v0.10.0 

type LossyConversionError struct {
	Warning Warning
}

LossyConversionError is the strict-mode abort for a lossy Markdown→ADF conversion: it carries the source-mapped warning so the error mapper can surface the offending Markdown line and a remediation hint instead of a bare message with none.

func (LossyConversionError) Code added in v0.10.0 

func (e LossyConversionError) Code() errtax.Code

Code classifies the strict-mode abort under markdown_lossy_conversion.

func (LossyConversionError) Error added in v0.10.0 

func (e LossyConversionError) Error() string

type LossyResult 

type LossyResult struct {
	Markdown        string
	LossyConstructs []string
}

LossyResult is the typed return for ToMarkdownLossy. Markdown is the best-effort GFM rendering; LossyConstructs is the sorted unique list of node/mark type names the renderer didn't fully round-trip.

func ToMarkdownLossy 

func ToMarkdownLossy(doc Document) LossyResult

ToMarkdownLossy renders doc to GFM Markdown and reports every node or mark type the renderer dropped or simplified. The returned LossyConstructs slice is sorted unique. A nil-or-empty doc yields an empty list.

type Mark 

type Mark struct {
	Type  string         `json:"type"`
	Attrs map[string]any `json:"attrs,omitempty"`
	// contains filtered or unexported fields
}

Mark is an inline annotation. Same opaque-preservation rules as Node.

func (Mark) MarshalJSON 

func (m Mark) MarshalJSON() ([]byte, error)

func (*Mark) UnmarshalJSON 

func (m *Mark) UnmarshalJSON(data []byte) error

type Node 

type Node struct {
	Type    string         `json:"type"`
	Text    string         `json:"text,omitempty"`
	Attrs   map[string]any `json:"attrs,omitempty"`
	Marks   []Mark         `json:"marks,omitempty"`
	Content []Node         `json:"content,omitempty"`
	// contains filtered or unexported fields
}

Node is one ADF block or inline element. Unknown JSON keys outside the well-known fields are preserved opaquely in extra so re-marshaling never loses semantics (lossless preservation).

func (Node) MarshalJSON 

func (n Node) MarshalJSON() ([]byte, error)

func (*Node) UnmarshalJSON 

func (n *Node) UnmarshalJSON(data []byte) error

type RegistryView 

type RegistryView struct {
	// contains filtered or unexported fields
}

RegistryView is the read-only handle commands and tests use.

func Registry 

func Registry() RegistryView

Registry returns the read-only registry view: the curated rows with computed capabilities, plus a synthesized preserve-only row for every validated node/mark that has no curated entry. The matrix therefore covers the validator's full universe by construction — it cannot under-report what the CLI accepts.

func (RegistryView) All 

func (r RegistryView) All() []Entry

func (RegistryView) Lookup 

func (r RegistryView) Lookup(kind Kind, name string) (Entry, bool)

type RenderOptions 

type RenderOptions struct {
	// IsTerminal toggles OSC 8 hyperlink emission. When false, the
	// renderer emits plain text.
	IsTerminal bool
	// BaseURL is the active profile's Jira base URL, used to expand
	// issue keys (JCT-7) into browseable links.
	BaseURL string
}

RenderOptions configure RenderActivatable.

type Segment 

type Segment struct {
	Text string
	Kind string
}

func ToFormatted 

func ToFormatted(doc Document) []Segment

type Status 

type Status string

Status tags the support tier a row currently sits in. New rows start at "preserve-only" and graduate to "mvp" or higher tiers as authoring lands. 

const (
	StatusMVP          Status = "mvp"
	StatusPreserveOnly Status = "preserve-only"
)

type Warning 

type Warning struct {
	Type     string `json:"type"`
	Message  string `json:"message"`
	Field    string `json:"field,omitempty"`
	Path     string `json:"path,omitempty"`
	NodeType string `json:"node_type,omitempty"`
	MarkType string `json:"mark_type,omitempty"`
	Lossy    bool   `json:"lossy"`
}

Warning is a structured non-fatal diagnostic emitted by best-effort ADF processing. Strict mode promotes warnings to errors. The shape matches cli.Warning byte-for-byte but the type lives here to avoid an import cycle; commands convert via cli.WarningFrom.

func ValidateDoc 

func ValidateDoc(doc Document, mode adfmode.Mode) ([]Warning, error)

ValidateDoc validates a parsed ADF Document according to the given mode.

Root shape (type="doc", version=1) is always enforced regardless of mode — a structurally invalid root cannot be sent to Jira in any mode.

Validation is registry-backed: the rules in schema_rules.go encode the pinned ADF JSON schema (@atlaskit/adf-schema 56.0.15). In ModeStrict (the mutation-submit default) every rule violation is a fatal error naming the offending field path. In ModeBestEffort every violation is a non-fatal Warning and the document is forwarded as-is.

Rules enforced:

  • root shape and root-child node types
  • unknown node / mark types
  • required attrs, attr types, attr enums, numeric ranges
  • content/nesting rules (inline-only nodes, child whitelists)
  • marks-on-block-nodes are illegal (marks are inline-only)
  • per-mark rules (link href, subsup type, color hex) and the code-mark mutual-exclusion group

Returns (warnings, nil) on success; (nil, err) on fatal validation failure.

func (Warning) WarningField 

func (w Warning) WarningField() string

func (Warning) WarningIsLossy 

func (w Warning) WarningIsLossy() bool

func (Warning) WarningMarkType 

func (w Warning) WarningMarkType() string

func (Warning) WarningMessage 

func (w Warning) WarningMessage() string

func (Warning) WarningNodeType 

func (w Warning) WarningNodeType() string

func (Warning) WarningPath 

func (w Warning) WarningPath() string

func (Warning) WarningType 

func (w Warning) WarningType() string

Implement cli.WarningSource so commands can do cli.WarningFrom(adfW) without either package importing the other's concrete type.

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.