mapping

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package mapping applies a declarative field-map (jira-sync.yaml) that lets `jira issue import --map` translate documents whose frontmatter uses hub keys (name, jira_key, jira_issue_type, initiative, stream, …) into the canonical markdown.Frontmatter the import pipeline already understands.

The mapping is opt-in: without --map, import behaves exactly as before.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DocJiraKey

func DocJiraKey(path string) (string, error)

DocJiraKey reads just the jira_key from a document's frontmatter (empty if absent).

func ParseMappedDir

func ParseMappedDir(dir string, cfg *Config) ([]*markdown.IssueFile, error)

ParseMappedDir recursively parses and maps all .md files in dir, sorted by path.

func ParseMappedFile

func ParseMappedFile(path string, cfg *Config, tempCounter *int) (*markdown.IssueFile, error)

ParseMappedFile reads a hub-style markdown file and maps its frontmatter into the canonical markdown.Frontmatter the import pipeline expects. tempCounter is incremented to mint a unique temp key (PROJECT-NEW-N) for documents without a jira_key (which therefore create rather than update).

func ParseMappedFiles

func ParseMappedFiles(paths []string, cfg *Config) ([]*markdown.IssueFile, error)

ParseMappedFiles parses and maps an explicit list of files.

func SetFrontmatterFields

func SetFrontmatterFields(path string, pairs [][2]string) error

SetFrontmatterFields sets (or inserts) the given frontmatter fields in order, touching only the frontmatter region (before the closing ---) and preserving everything else — including any trailing # comment on a replaced line. An empty value is written as the literal `null`.

func WriteBack

func WriteBack(path, key, syncedAt string) error

WriteBack rewrites a mapped file's frontmatter after a push: it sets jira_key (for a fresh create) and last_synced_at, preserving everything else.

Types

type Config

type Config struct {
	Project     string            `yaml:"project"`
	IssueTypes  IssueTypes        `yaml:"issue_types"`
	Links       map[string]Link   `yaml:"links"`
	PriorityMap map[string]string `yaml:"priority_map"`
	// ComponentMap translates a doc's `component:` frontmatter (an ownership-area
	// key) to a JIRA component name. Components is a required create-screen field
	// in some projects, so this is pushed like priority — see setCommonFields.
	ComponentMap map[string]string `yaml:"component_map"`
	Streams      map[string]Stream `yaml:"streams"`
	// CreateFields sets constant custom fields per document type ("epic" or
	// "story") on create only. A stream can add or override them (see Stream). Keys are Jira field names, normalized like
	// frontmatter custom fields (e.g. "Investment Category" → investment_category);
	// object-type values resolve through the .jira-field-values.json sidecar.
	CreateFields map[string]map[string]interface{} `yaml:"create_fields"`
	// FieldMap declares how document fields feed JIRA fields. Only summary is
	// configurable; the other keys document fixed behavior (see fixedFieldMap).
	FieldMap map[string]FieldMapping `yaml:"field_map"`
	Pull     Pull                    `yaml:"pull"`
}

Config is the subset of jira-sync.yaml that the push (import) side consumes. Blocks used only by other consumers (pull, transitions, attachments) are ignored here — yaml.v3 tolerates unknown keys.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads and validates a jira-sync.yaml mapping config.

func (*Config) MapStatus

func (c *Config) MapStatus(name, categoryKey string) string

MapStatus resolves a JIRA status name + category key to the hub status. Explicit name mapping wins; otherwise falls back to the category. Returns "" when neither maps (caller leaves the hub value unchanged).

func (*Config) Summary added in v0.12.0

func (c *Config) Summary(raw map[string]interface{}, path string) (string, error)

Summary builds the JIRA summary from a document's frontmatter per field_map.summary: a template ("[{id}] {title}"), a source key (from: title), or the default source key "name".

func (*Config) WantsPull

func (c *Config) WantsPull(field string) bool

WantsPull reports whether the given field is in the pull set.

type FieldMapping added in v0.12.0

type FieldMapping struct {
	From     string `yaml:"from,omitempty"`
	Via      string `yaml:"via,omitempty"`
	Format   string `yaml:"format,omitempty"`
	Template string `yaml:"template,omitempty"` // summary only, e.g. "[{id}] {title}"
}

FieldMapping is one field_map entry.

func (FieldMapping) String added in v0.12.0

func (m FieldMapping) String() string

String renders a mapping in flow-YAML form for error messages.

type IssueTypes

type IssueTypes struct {
	Epic  string `yaml:"epic"`
	Story string `yaml:"story"`
}

IssueTypes names the JIRA issue types epics and stories map to.

type Link struct {
	Via string `yaml:"via"`
}

Link declares the mechanism used to attach a parent (e.g. via: parent). The target (which initiative / which epic) comes from the document's frontmatter.

type Pull

type Pull struct {
	Fields     []string  `yaml:"fields"`
	AssigneeAs string    `yaml:"assignee_as"` // "email" (default) or "account_id"
	StatusMap  StatusMap `yaml:"status_map"`
}

Pull configures the JIRA-first reconciliation (status + assignee → hub).

type StatusMap

type StatusMap struct {
	ByCategory map[string]string `yaml:"by_category"`
	ByName     map[string]string `yaml:"by_name"`
}

StatusMap maps a JIRA status to a hub status, by category (stable) then by explicit name (override).

type Stream

type Stream struct {
	Label        string                 `yaml:"stream_label"`
	CreateFields map[string]interface{} `yaml:"create_fields,omitempty"`
}

Stream holds the per-stream JIRA label and optional create_fields. A stream's create_fields override the per-type create_fields for the same field.

Jump to

Keyboard shortcuts

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