Documentation
¶
Index ¶
- Constants
- func ExtractObjectDisplay(raw json.RawMessage) (string, bool)
- func IsBuiltinKey(key string) bool
- func IsTempKey(key string) bool
- func IssuePath(issue api.Issue, flat bool) string
- func IssueTreePath(issue api.Issue, flat bool) string
- func NormalizeFieldName(displayName string) string
- func SanitizeFilename(name string) string
- func SaveFieldValues(path string, fvm FieldValueMap) error
- func SplitFrontmatter(content, path string) (yamlContent, body string, err error)
- type FieldValueMap
- type Frontmatter
- type IssueFile
Constants ¶
const FieldValuesFileName = ".jira-field-values.json"
FieldValuesFileName is the conventional name for the sidecar file.
Variables ¶
This section is empty.
Functions ¶
func ExtractObjectDisplay ¶
func ExtractObjectDisplay(raw json.RawMessage) (string, bool)
ExtractObjectDisplay extracts a display value from a JSON object field value. Returns the display string and true if the value is an object with a .value or .name key. Returns "", false for non-objects, nil, or objects without displayable keys.
func IsBuiltinKey ¶
IsBuiltinKey returns true if key is a reserved frontmatter key.
func IssuePath ¶
IssuePath returns the relative file path for an issue markdown file. Format: {ProjectKey}/{IssueKey} - {SanitizedSummary}.md If Project is nil, the project key is extracted from the issue key prefix. When flat is true, the project key directory prefix is omitted.
func IssueTreePath ¶
IssueTreePath returns the relative file path for an issue in tree mode. Epics become directories containing _epic.md; children of any parent are placed inside the parent's directory. Orphans stay flat. When flat is true, the project key directory prefix is omitted.
func NormalizeFieldName ¶
NormalizeFieldName converts a Jira field display name to a YAML-safe key. It lowercases, replaces spaces with underscores, and strips all characters not in [a-z0-9_]. Returns empty string if nothing remains.
func SanitizeFilename ¶
SanitizeFilename replaces characters that are invalid in file names, collapses multiple spaces, trims whitespace, and enforces a max length of 100 chars.
func SaveFieldValues ¶
func SaveFieldValues(path string, fvm FieldValueMap) error
SaveFieldValues writes a FieldValueMap to the given path atomically.
func SplitFrontmatter ¶
SplitFrontmatter splits a markdown file's content into its YAML frontmatter and body. It returns the raw YAML (between the --- delimiters) and the trimmed body that follows. Returns a VALIDATION_ERROR CLIError if the delimiters are missing. Exported so callers that map non-standard frontmatter (see the mapping package) can reuse the exact same splitting rules as ParseFile.
Types ¶
type FieldValueMap ¶
type FieldValueMap map[string]map[string]json.RawMessage
FieldValueMap stores raw API objects for custom field values that need object wrapping during import. Structure:
normalizedFieldName → displayValue → rawJSON
Only populated for fields where the API returns an object (e.g. team, option, user). Scalar values (string, number, bool) don't need this.
func FindFieldValues ¶
func FindFieldValues(dir string) (FieldValueMap, string, error)
FindFieldValues searches for a .jira-field-values.json file starting from dir, then checking the parent directory (one level up). Returns the loaded map and the path found, or an empty map if not found.
func IssueToMarkdown ¶
func IssueToMarkdown(issue api.Issue, fields map[string]api.Field, warnWriter io.Writer) ([]byte, FieldValueMap, error)
IssueToMarkdown converts an api.Issue to markdown bytes with YAML frontmatter. The fields map (keyed by field ID, e.g. "customfield_10001") provides display names for custom field resolution. Pass nil to omit custom fields. Warnings (collisions, skipped values) are written to warnWriter; nil is safe.
Returns the markdown bytes and a FieldValueMap containing raw API objects for any custom fields whose values were extracted from objects (for sidecar).
The output has the form:
--- key: PROJ-123 summary: Issue title ... --- Markdown description body
func LoadFieldValues ¶
func LoadFieldValues(path string) (FieldValueMap, error)
LoadFieldValues reads a FieldValueMap from the given path. Returns an empty map (not nil) if the file does not exist.
func (FieldValueMap) Merge ¶
func (fvm FieldValueMap) Merge(other FieldValueMap) bool
Merge adds entries from other into fvm. Existing entries are preserved (first-write wins), so earlier exports don't lose values. Returns true if any new entries were added.
type Frontmatter ¶
type Frontmatter struct {
Key string `yaml:"key"`
ID string `yaml:"id,omitempty"`
Type string `yaml:"type,omitempty"`
Summary string `yaml:"summary"`
Status string `yaml:"status,omitempty"`
Priority string `yaml:"priority,omitempty"`
Labels []string `yaml:"labels,omitempty"`
Components []string `yaml:"components,omitempty"`
Parent string `yaml:"parent,omitempty"`
Assignee string `yaml:"assignee,omitempty"`
AssigneeID string `yaml:"assignee_id,omitempty"`
Reporter string `yaml:"reporter,omitempty"`
ReporterID string `yaml:"reporter_id,omitempty"`
Project string `yaml:"project,omitempty"`
Created string `yaml:"created,omitempty"`
Updated string `yaml:"updated,omitempty"`
// CustomFields holds custom field values keyed by normalized name.
// Excluded from default YAML marshal; appended by MarshalYAML.
CustomFields map[string]interface{} `yaml:"-"`
}
Frontmatter holds the YAML metadata for an issue markdown file.
func (Frontmatter) MarshalYAML ¶
func (fm Frontmatter) MarshalYAML() (interface{}, error)
MarshalYAML marshals built-in fields first, then appends custom fields in alphabetical order.
type IssueFile ¶
type IssueFile struct {
Path string
Frontmatter Frontmatter
Description string // raw markdown body after frontmatter
}
IssueFile represents a parsed markdown file with YAML frontmatter.
Source Files