Documentation
¶
Overview ¶
Package mutation provides utilities for reading and writing YAML frontmatter in Markdown note files while preserving key order, scalar styles, and line ending conventions.
Index ¶
- func AtomicWrite(absPath, relPath string, newContent []byte, preHash string) error
- func CommitMessage(req MutationRequest, id string) string
- func DetectLineEnding(raw []byte) string
- func DetectTrailingNewline(raw []byte) bool
- func FileHash(data []byte) string
- func GenerateDiff(path string, original, modified string) string
- func NormalizeDates(mapping *yaml.Node, stripTime bool)
- func ParseFrontmatterNode(raw []byte) (*yaml.Node, int, error)
- func ScalarToList(mapping *yaml.Node, key string) bool
- func SerializeFrontmatter(doc *yaml.Node, lineEnding string) ([]byte, error)
- func SetFileKey(path, key string, value interface{}) error
- func SetKey(mapping *yaml.Node, key string, value interface{}) error
- func SortKeys(mapping *yaml.Node)
- func SpliceFile(original []byte, newFrontmatter []byte, bodyOffset int) []byte
- func UnsetKey(mapping *yaml.Node, key string) bool
- func ValidateMutation(req MutationRequest, note ParsedNoteInfo, reg *schema.Registry) error
- type FixWikilinksResult
- type GitInfo
- type KeyRename
- type LinkFixDetail
- type MutationError
- type MutationRequest
- type MutationResult
- type Mutator
- type OpType
- type ParsedNoteInfo
- type PolicyWarning
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtomicWrite ¶ added in v0.10.13
AtomicWrite re-reads absPath and refuses when those bytes no longer match preHash, then replaces the file by renaming a temp file in the same directory. Callers pass a path they have already confined.
func CommitMessage ¶
func CommitMessage(req MutationRequest, id string) string
CommitMessage generates a structured commit message based on the operation.
func DetectLineEnding ¶
DetectLineEnding returns "\r\n" if CRLF detected, "\n" otherwise.
func DetectTrailingNewline ¶
DetectTrailingNewline returns true if raw bytes end with a newline.
func GenerateDiff ¶
GenerateDiff produces a unified diff string between original and modified.
func NormalizeDates ¶
NormalizeDates strips the time component from date-field scalar values. When stripTime is false, only midnight timestamps are stripped. When stripTime is true, all time components are removed regardless.
func ParseFrontmatterNode ¶
ParseFrontmatterNode parses raw file bytes into a yaml.Node tree. Returns the document node and the body byte offset (after closing ---\n).
func ScalarToList ¶
ScalarToList converts a scalar value at the given key into a single-element sequence node. Returns true if a conversion was performed, false otherwise (key absent, value already a sequence, etc.).
func SerializeFrontmatter ¶
SerializeFrontmatter marshals the yaml.Node back to YAML bytes, wrapped in --- delimiters, using the specified line ending convention.
func SetFileKey ¶ added in v0.9.3
SetFileKey sets one frontmatter key on the file at path, leaving the body and every other key as they were. It exists for files the index deliberately leaves out — episodes — which Mutator.Run cannot reach because it resolves its target through the index. The write is the same conflict-checked atomic write Run uses.
func SetKey ¶
SetKey sets or inserts a key in a yaml.Node mapping. Preserves position of existing keys. New keys are appended at the end.
func SortKeys ¶
SortKeys sorts the keys of a YAML mapping node: canonical keys first (in canonical order), then remaining keys alphabetically.
func SpliceFile ¶
SpliceFile replaces the frontmatter section in original bytes with newFrontmatter, preserving body bytes untouched. Normalizes gap to exactly one blank line when body has leading blank lines; otherwise preserves body as-is from its first character.
func ValidateMutation ¶
func ValidateMutation(req MutationRequest, note ParsedNoteInfo, reg *schema.Registry) error
ValidateMutation checks a MutationRequest against schema rules before any file is modified. It returns a *MutationError with a structured code on failure, or nil when the request is safe to apply.
Types ¶
type FixWikilinksResult ¶
type FixWikilinksResult struct {
FilesScanned int `json:"files_scanned"`
FilesChanged int `json:"files_changed"`
LinksFixed int `json:"links_fixed"`
Details []LinkFixDetail `json:"details,omitempty"`
// SkippedSymlinks holds vault-relative paths of *.md symlinks that were
// neither read nor written. On the result rather than in a log line: a file
// this run passed over still has whatever links it had, and the caller is
// the only one who can tell the operator so.
SkippedSymlinks []string `json:"skipped_symlinks,omitempty"`
}
FixWikilinksResult is the output of a FixWikilinks run.
func FixWikilinks ¶
FixWikilinks scans all .md files in vaultPath and rewrites [[Target]] to [[filename|Target]] (and [[Target|Display]] to [[filename|Display]]) wherever Target resolves to a note whose filename stem differs from the link target. When fix is false the function performs a dry-run: it counts and records changes but does not write any files.
type GitInfo ¶
type GitInfo struct {
RepoDetected bool `json:"repo_detected"`
WorkingTreeClean bool `json:"working_tree_clean"`
TargetFileClean bool `json:"target_file_clean"`
CommitSHA string `json:"commit_sha,omitempty"`
}
GitInfo reports git state in mutation responses.
type KeyRename ¶
KeyRename records a key rename performed by SnakeCaseKeys.
func SnakeCaseKeys ¶
SnakeCaseKeys converts camelCase key names in a mapping node to snake_case in-place and returns the list of renames performed.
type LinkFixDetail ¶
type LinkFixDetail struct {
Path string `json:"path"`
OldLink string `json:"old_link"`
NewLink string `json:"new_link"`
}
LinkFixDetail describes a single wikilink rewrite.
type MutationError ¶
MutationError is a structured error with an SRS error code.
func (*MutationError) Error ¶
func (e *MutationError) Error() string
type MutationRequest ¶
type MutationRequest struct {
Op OpType
Target string
Key string
Value interface{}
Fields map[string]interface{}
DryRun bool
Diff bool
Commit bool
AllowExtra bool
StripTime bool
}
MutationRequest describes what to mutate.
type MutationResult ¶
type MutationResult struct {
Path string `json:"path"`
ID string `json:"id"`
Operation string `json:"operation"`
Key string `json:"key,omitempty"`
OldValue interface{} `json:"old_value,omitempty"`
NewValue interface{} `json:"new_value,omitempty"`
DryRun bool `json:"dry_run"`
Diff string `json:"diff,omitempty"`
WriteHash string `json:"write_hash,omitempty"`
Git GitInfo `json:"git"`
ReindexRequired bool `json:"reindex_required"`
Warnings []PolicyWarning `json:"warnings"`
}
MutationResult is the JSON response for all mutation commands.
type Mutator ¶
type Mutator struct {
VaultPath string
Detector git.RepoStateDetector
Checker *git.PolicyChecker
Committer *git.Committer
Registry *schema.Registry
}
Mutator orchestrates the 7-step mutation pipeline: resolve target -> read file -> validate -> compute change -> generate diff -> atomic write -> post-write.
func (*Mutator) Run ¶
func (m *Mutator) Run(req MutationRequest) (*MutationResult, error)
Run executes the mutation pipeline for the given request.
type ParsedNoteInfo ¶
ParsedNoteInfo holds the minimal note info needed for validation.
type PolicyWarning ¶
PolicyWarning describes a git policy warning that was triggered but didn't block.
Source Files