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 ¶
- func DocJiraKey(path string) (string, error)
- func ParseMappedDir(dir string, cfg *Config) ([]*markdown.IssueFile, error)
- func ParseMappedFile(path string, cfg *Config, tempCounter *int) (*markdown.IssueFile, error)
- func ParseMappedFiles(paths []string, cfg *Config) ([]*markdown.IssueFile, error)
- func SetFrontmatterFields(path string, pairs [][2]string) error
- func WriteBack(path, key, syncedAt string) error
- type Config
- type FieldMapping
- type IssueTypes
- type Link
- type Pull
- type StatusMap
- type Stream
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DocJiraKey ¶
DocJiraKey reads just the jira_key from a document's frontmatter (empty if absent).
func ParseMappedDir ¶
ParseMappedDir recursively parses and maps all .md files in dir, sorted by path.
func ParseMappedFile ¶
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 ¶
ParseMappedFiles parses and maps an explicit list of files.
func SetFrontmatterFields ¶
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`.
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 ¶
LoadConfig reads and validates a jira-sync.yaml mapping config.
func (*Config) MapStatus ¶
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).
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 ¶
IssueTypes names the JIRA issue types epics and stories map to.
type Link ¶
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).