yamlkit

func AddMutations ¶

func AddMutations(mutations, newMutations api.ResourceMutationList) (api.ResourceMutationList, bool)

AddMutations merges newMutations into mutations and returns the result, accumulating changes over sequential edits to produce a compiled history of all modifications. The accumulated form is what's stored as a Unit's MutationSources and what feeds the protection map passed into PatchMutations.

Algorithm:

1. Resource matching: by current ResourceTypeAndName, then by AliasesWithoutScopes (handling renames). Unmatched new mutations are appended as new resource entries.

2. Resource-level merge:

   | Existing Type | New Type | Result | |------------------|-----------------------|---------------------| | Any | None | Keep existing | | Any | Delete or Replace | Replace with new | | None | Any (non-None) | Replace with new | | Delete | Any (non-Delete) | Change to Replace | | Add/Update | Add/Update | Merge path mutations|

3. Path-level merge: process newMutations' paths sorted least-specific to most-specific so parent paths land before children. Paths are keyed canonically -- see canonicalPathKeys. For each new path:

   - Exact match in existing: replace the existing entry, taking the new MutationType (so a later edit's intent — e.g., an Update on a previously-Added field — is reflected). Exception: Delete → non-Delete becomes Replace, since the field was previously erased and is now being re-set. - Existing path is a child of the new path AND new path is Delete or Replace: drop the now-superseded child paths. - Otherwise: insert the new path verbatim, dropping any existing children it supersedes.

   Because the new MutationType replaces the existing one on exact match, when this accumulated record is later used as a patch, PatchMutations sees the latest intent (e.g., Update to merge with the target's value rather than wholesale Replace). Both branches take the whole incoming MutationInfo, Patch included: an accumulated entry should describe the change the same way whether or not the path had been written before, and a line-level patch that survives on a fresh path and is dropped on a repeated one is a difference nothing means.

4. Alias tracking: union of both sides' Aliases / AliasesWithoutScopes so a resource can still be matched after another rename.

Key behaviors:

• Accumulative: designed to be called repeatedly as changes occur.
• Last-write-wins for values and types on exact-path matches.
• Alias awareness: handles resources renamed between mutation sets.

func AnchorMutationPath ¶ added in v0.2.22

func AnchorMutationPath(doc *gaby.YamlDoc, path api.ResolvedPath) (api.ResolvedPath, bool)

AnchorMutationPath re-attaches the positional fallback to every associative segment of a path, resolved against doc, and reports whether anything changed. It is CanonicalMutationPath undone against a particular document, for the one caller that needs the stored form back: a migration rolling the canonical keying of MutationSources backwards.

The index it writes is where the element sits in doc, which is what a diff computed against doc would have recorded, not necessarily what the path carried before it was canonicalized. Nothing is written when the path does not fully resolve, since a fallback pointing at the wrong element is worse than none.

func AnchoredPathSegment ¶ added in v0.2.12

func AnchoredPathSegment(elements []*gaby.YamlDoc, index int, withContext bool) string

AnchoredPathSegment builds the path segment naming an element of an array that has no declared merge key: the positional index, as before, plus a digest of the element's content.

The index alone says where the element sat in the configuration the patch was computed against, which is only where it sits in the target if the target has not drifted. The digest says which element it was, so a target that inserted, removed, or reordered elements around it can still be patched in the right place. Where the target has edited the element itself the digest no longer matches and resolution falls back to the index, which is where it was before anchors — the anchor can only improve the outcome.

The digest is taken from the element as it stood on the side the path names it from: the previous revision for a matched pair or a removal, the new content for an insertion. Both sides of a three-way merge diff against the same base, so their anchors for the same element agree and subtraction still recognizes them as the same path.

withContext adds the shape of the array around the element: digests of the elements on either side and the array's length. All of it describes the array the patch was computed against, so it is recorded for a path that names an element of that array — a matched element or a removal — and not for an insertion, whose index names a position in the array that only exists once the patch has been applied.

func AppendCommentLines ¶ added in v0.1.25

func AppendCommentLines(result []string, indent string, text string) []string

AppendCommentLines appends comment text as #-prefixed lines to the result slice, using the given indentation prefix to match surrounding lines.

func ApplyLinePatch ¶ added in v0.1.14

func ApplyLinePatch(target, patch string) (string, bool)

ApplyLinePatch applies a line-level patch (produced by ComputeLinePatch) to a target string. Returns the patched string and true if all hunks applied cleanly. If any hunk fails to apply, returns the partially patched string and false.

func ApplyScalarPatch ¶ added in v0.1.14

func ApplyScalarPatch(target, patch string) (string, bool)

ApplyScalarPatch applies a patch (produced by ComputeScalarPatch) to a target string. It auto-detects the patch format: structural patches (JSON-encoded, start with '{') are applied structurally; line-level text patches (unified diff) are applied with fuzzy context matching.

Returns the patched string and true if the patch applied cleanly. On failure, returns the original target string and false.

func AssociativePathSegment ¶

func AssociativePathSegment(mergeKeys []string, mergeKeyValues []string, index int) string

AssociativePathSegment builds a path segment encoding the merge key values and the positional index, using the syntax ?key=value;@index — or, for an array whose elements are identified by more than one field, ?key1=value1,key2=value2;@index. Keys and values are escaped to handle dots.

func AttributeDetailsEqual ¶

func AttributeDetailsEqual(details1, details2 *api.AttributeDetails) bool

AttributeDetailsEqual reports whether two sets of attribute details, optionally including getter and setter invocations, match.

Needs/provides properties are compared for compatibility rather than equality: a path registered twice with different required values accepts either, and registerPaths unions them. A reference field naming any workload controller is registered once per controller, and those registrations agreeing about everything except which type they name is the normal case, not a mismatch to report.

func AttributeValueForPath ¶

func AttributeValueForPath(resourceProvider ResourceProvider, path api.ResolvedPath, resourceInfo *api.ResourceInfo, value any) api.AttributeValue

func CanonicalMutationPath ¶ added in v0.2.12

func CanonicalMutationPath(path api.ResolvedPath) api.ResolvedPath

CanonicalMutationPath drops the positional fallback from every associative segment of a path, turning ?key=value;@index into ?key=value.

The index in an associative segment is a fallback for resolution, not part of the element's identity: it records where the element sat in the configuration the path was computed against. Two paths that name the same element by merge key are the same path even when the element sits at different positions on either side — which it will whenever one side has added or removed an earlier element. Comparing paths between two independently computed diffs has to be done on this form; applying a path does not, since the fallback is useful there.

Splitting on "." is safe: dots within a segment are escaped as ~1.

func CanonicalizeStoredMutationPaths ¶ added in v0.4.10

func CanonicalizeStoredMutationPaths(mutations api.ResourceMutationList, parsedData gaby.Container,
	resourceProvider ResourceProvider) (api.ResourceMutationList, bool)

CanonicalizeStoredMutationPaths rewrites the path keys of a stored mutation record into the form today's merge keys produce, resolving positional segments against parsedData. It returns the record unchanged, and false, when there is nothing to rewrite.

Two entries that rewrite to one key are folded: they are the same element recorded at two positions, and the later one by MutationNum wins except that Protected survives from either, since a lost Protected silently reopens a path its owner had closed.

func CommentKey ¶ added in v0.1.25

func CommentKey(ct CommentType, targetKey string) string

CommentKey builds a comment map key from a comment type and target key name. For example, CommentKey(CommentHead, "server") returns "$comment$head$server". An empty targetKey refers to the containing object/document itself.

func CommentKeysForDataKey ¶ added in v0.1.25

func CommentKeysForDataKey(targetKey string) []string

CommentKeysForDataKey returns the $comment$ keys that could be associated with a given data key (head, line, and foot).

func ComputeLinePatch ¶ added in v0.1.14

func ComputeLinePatch(previous, modified string) string

ComputeLinePatch computes a line-level diff between two multi-line strings and returns a patch in unified diff text format. The patch can be serialized as a string in MutationInfo.Patch and later applied with ApplyLinePatch.

This uses the Myers diff algorithm via go-diff's DiffLinesToChars to tokenize at line boundaries, producing a minimal edit script that correctly identifies inserted, deleted, and unchanged lines.

func ComputeMutations ¶

func ComputeMutations(previousParsedData, modifiedParsedData gaby.Container, functionIndex int64, resourceProvider ResourceProvider) (api.ResourceMutationList, error)

ComputeMutations performs a kind of diff between two configuration Units where it determines what modifications were made at the resource/element level and at the path level. They are recorded in a way that can be accumulated and updated over subsequent edits and transformations.

func ComputeMutationsForDocs ¶

func ComputeMutationsForDocs(rootPath string, previousDoc *gaby.YamlDoc, modifiedDoc *gaby.YamlDoc, functionIndex int64, pathMutationMap api.MutationMap, mergeKeyLookup MergeKeyLookup, arrayOrders api.ArrayOrderMap, arrayElementAliases api.ArrayElementAliasMap)

arrayElementAliases, if non-nil, is populated with element-level renames detected inside merge-keyed arrays. When an unmatched modified element and an unmatched previous element are similar enough, the pair is treated as a rename: child paths are emitted under the previous merge-key value (so they align with target-side paths in SubtractMutations) and the alias is recorded so PatchMutations rewrites the merge-key field at apply time.

func ComputeScalarPatch ¶ added in v0.1.14

func ComputeScalarPatch(previous, modified string) string

ComputeScalarPatch computes a patch for a changed multi-line scalar string value. It tries to parse both values as JSON, then YAML, and computes a structural patch (sub-path mutations) for those formats. Falls back to a line-level text diff.

Structural patches give true three-way merge for embedded JSON/YAML: individual field changes are tracked by path, so independent changes to different fields merge correctly. Line-level patches handle unstructured text (markdown, config files, etc.) with context-based fuzzy matching.

func DeletePaths ¶

func DeletePaths(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) error

func DiffPatch ¶

func DiffPatch(original, modified, targetData []byte, resourceProvider ResourceProvider) ([]byte, bool, error)

DiffPatch compares original and modified YAML content, generates a patch, and applies it to target data

func DiffPatchWithOptions ¶

func DiffPatchWithOptions(original, modified, targetData []byte, resourceProvider ResourceProvider, omitAdditions bool, options *api.FunctionOptions) ([]byte, bool, error)

DiffPatchWithOptions compares original and modified YAML content, generates a patch, and applies it to target data If omitAdditions is true, mutations of type MutationTypeAdd are filtered out before applying the patch

func ElementDigest ¶ added in v0.2.12

func ElementDigest(element *gaby.YamlDoc) string

ElementDigest returns a short digest of an array element's content, over the parsed subtree in canonical form rather than its text: comments, key order, indentation, and quoting style do not change it, so an element that was only reformatted still matches.

func ElementIdentity ¶ added in v0.2.12

func ElementIdentity(element *gaby.YamlDoc) string

ElementIdentity returns a projection of an array element that identifies it independently of its current value, or "" when the element offers none.

Two sources, the person's first:

• A structured comment, which is the only mechanism here that lets someone *correct* the engine rather than work around it. Where a person has said which element this is, that is what it is. See identityDirective.
• A scalar holding a command-line flag with an inline value, whose identity is the flag name. An args list is the most common unkeyed array in a Kubernetes workload, and `--log.level=INFO` and `--log.level=DEBUG` are the same flag.

Either way the point is the same: an element the target has *edited* can still be found, which no digest can do, however either side has since reordered the list.

Both sides of a merge have to carry the markup for it to do anything — the source records it in the path, and the target is matched against it — so it belongs upstream, where a clone inherits it, rather than only on the variant that needed it.

func EnrichMergeKeysFromDoc ¶ added in v0.1.15

func EnrichMergeKeysFromDoc(doc *gaby.YamlDoc, resourceProvider ResourceProvider, attr *api.AttributeValue)

EnrichMergeKeysFromDoc extracts merge keys from the resolved path of an AttributeValue and adds them as NeededPreferred properties. For each numeric array index in the path, it looks up the merge key via MergeKeyForPath and reads the value from the document. For example, path "spec.template.spec.volumes.1.configMap.name" with merge key "name"="config" at volumes[1] yields NeededPreferred["Name"] = "config".

func EscapeDotsInPathSegment ¶

func EscapeDotsInPathSegment(segment string) string

EscapeDotsInPathSegment escapes any dots in a path segment for use in whole-path searches because path segments are separated by dots. TODO: Escape more special characters?

func ExtractCommentKeys ¶ added in v0.1.25

func ExtractCommentKeys(data map[string]any) map[string]string

ExtractCommentKeys removes comment keys from the top level of a map, returning them as a separate map from comment key to comment text. The input map is modified in place.

func ExtractCommentsFromData ¶ added in v0.1.25

func ExtractCommentsFromData(data any) (any, map[string]string)

ExtractCommentsFromData recursively extracts all comment keys from a data tree, returning the cleaned data and a flat map of dot-path to comment text.

func FindMutationIndex ¶

func FindMutationIndex(parsedData gaby.Container, mutationSources api.ResourceMutationList,
	resource api.ResourceInfo, path api.ResolvedPath, resourceProvider ResourceProvider) (int64, bool)

FindMutationIndex looks up the mutation index for a specific resource and path in a ResourceMutationList. It matches the resource by ResourceTypeAndName, handling aliases and scope changes (same pattern as AddMutations). For the path, it walks up parent paths to find the most specific mutation index, falling back to the resource-level index if no path-level match is found. Returns the mutation index and true if found.

parsedData and resourceProvider locate the resource's document, which is what turns a stored path into the positional form callers look up by -- NeededPaths addresses array elements by index. Both may be nil; the lookup then covers only the paths that match textually.

func FindResourceDoc ¶ added in v0.1.15

func FindResourceDoc(
	parsedData gaby.Container,
	resourceProvider ResourceProvider,
	target *api.ResourceInfo,
) (*gaby.YamlDoc, *api.ResourceInfo)

FindResourceDoc finds the document in parsedData that best matches the given target ResourceInfo. It uses the same matching hierarchy as ComputeMutations:

1. Exact ResourceName or ResourceNameWithoutScope match
2. ResourceTypesAreSimilar as a prerequisite for any match

Returns the matching doc and its ResourceInfo, or (nil, nil) if no match is found.

func FindYAMLPathsByValue ¶

func FindYAMLPathsByValue(parsedData gaby.Container, resourceProvider ResourceProvider, matcher ValueMatcher, options *api.FunctionOptions) api.AttributeValueList

FindYAMLPathsByValue searches for all paths whose scalar value is matched by matcher in a YAML structure and returns an api.AttributeValueList. The matched value stored in each AttributeValue is the actual value found at the path, so callers (e.g. search-replace) can transform it.

func FunctionInvocationsEqual ¶

func FunctionInvocationsEqual(fi1, fi2 *api.FunctionInvocation) bool

FunctionInvocationsEqual reports whether two function invocations match.

func GetMutationOptions ¶

func GetMutationOptions(doc *gaby.YamlDoc, resourceProvider ResourceProvider) []string

GetMutationOptions reads the MutationOptions value from a YAML document using the resource provider's context path.

func GetNeededPaths ¶

func GetNeededPaths[T api.Scalar](
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetNeededPaths traverses the specified path patterns of the specified resource types and returns an api.AttributeValueList containing the values and registered information about all of the found attributes matching the path patterns that Need values. Currently "Need" is determined using placeholder values, 999999999 (9 9s) for integers. Use only for ints. Bools have no placeholder value. Use GetNeededStringPaths for strings.

func GetNeededStringPaths ¶

func GetNeededStringPaths(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetNeededStringPaths traverses the specified path patterns of the specified resource types and returns an api.AttributeValueList containing the values and registered information about all of the found string attributes matching the path patterns that Need values. Currently "Need" is determined using placeholder values, "confighubplaceholder" for strings. It can also extract fields embedded in strings using registered embedded accessors.

func GetPathRegistryForAttributeName ¶

func GetPathRegistryForAttributeName(
	resourceProvider ResourceProvider,
	attributeName api.AttributeName,
) api.ResourceTypeToPathToVisitorInfoType

GetPathRegistryForAttributeName returns the registry for the specified attribute to pass to a visitor function. If the attribute has a non-empty AttributeGroup, the registries for all attributes in the group are combined and returned.

func GetPathRegistryForAttributeNameByProperty ¶ added in v0.4.8

func GetPathRegistryForAttributeNameByProperty(
	resourceProvider ResourceProvider,
	attributeName api.AttributeName,
	propertyKey string,
	propertyValue string,
) api.ResourceTypeToPathToVisitorInfoType

GetPathRegistryForAttributeNameByProperty returns the paths registered under an attribute whose needs/provides properties carry propertyKey with propertyValue, on either side: a provided path offering it, or a needed path requiring it.

This is how a reference selects the paths that point at one resource type. Splitting the attribute into a name per target would answer the same question by string convention, which is a second encoding of what the properties already say -- and a convention spelled differently in two places matches nothing, silently.

func GetPathVisitorInfo ¶

func GetPathVisitorInfo(resourceProvider ResourceProvider, resourceType api.ResourceType, path api.UnresolvedPath) *api.PathVisitorInfo

GetPathVisitorInfo returns the path visitor specification for the specified path within the specified resource type to pass to a visitor function. It searches all attribute names in the path registry for the normalized path. GetPathVisitorInfo returns the PathVisitorInfo for the specified path. It searches all attribute names in the path registry, checking the specific resource type across all attributes first, then falling back to ResourceTypeAny. This ensures a specific resource type match always takes priority. The first match provides the base Details (getter/setter invocations). IsNeeded/IsProvided flags and Enricher are collected from all matches. Getter/setter invocations are NOT merged across attribute names because they carry resource-type-specific arguments.

func GetPaths ¶

func GetPaths[T api.Scalar](
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetPaths traverses the specified path patterns of the specified resource types and returns an api.AttributeValueList containing the values and registered information about all of the found attributes matching the path patterns. Use only for int and bool attributes. Use GetStringPaths for string attributes.

func GetPathsAnyType ¶

func GetPathsAnyType(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	dataType api.DataType,
	neededValuesOnly bool,
	providedValuesOnly bool,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetPathsAnyType traverses the specified path patterns of the specified resource types and returns an api.AttributeValueList containing the values and registered information about all of the found attributes matching the path patterns.

func GetRegisteredNeededPaths ¶

func GetRegisteredNeededPaths(resourceProvider ResourceProvider) api.ResourceTypeToPathToVisitorInfoType

GetRegisteredNeededPaths returns a combined registry of all paths marked as IsNeeded across all attributes in the path registry.

func GetRegisteredNeededPathsByProperty ¶ added in v0.1.42

func GetRegisteredNeededPathsByProperty(resourceProvider ResourceProvider, neededRequired []string) api.ResourceTypeToPathToVisitorInfoType

GetRegisteredNeededPathsByProperty returns a combined registry of all paths marked as IsNeeded whose Details.NeededRequired map contains every key listed in neededRequired. Values of those required keys are not checked — only presence. This is useful for finding paths that participate in a particular kind of match (e.g., all resource references via the "ResourceType" key) regardless of whether the current value at the path is a placeholder.

func GetRegisteredNeededStringPaths ¶

func GetRegisteredNeededStringPaths(
	parsedData gaby.Container,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetRegisteredNeededStringPaths retrieves Needed values by scanning all attributes for paths marked as IsNeeded.

func GetRegisteredProvidedPaths ¶

func GetRegisteredProvidedPaths(resourceProvider ResourceProvider) api.ResourceTypeToPathToVisitorInfoType

GetRegisteredProvidedPaths returns a combined registry of all paths marked as IsProvided across all attributes in the path registry.

func GetRegisteredProvidedStringPaths ¶

func GetRegisteredProvidedStringPaths(
	parsedData gaby.Container,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetRegisteredProvidedStringPaths retrieves Provided values by scanning all attributes for paths marked as IsProvided. Resources with IgnoreProvided annotation are skipped.

func GetResourceCategoryTypeName ¶

func GetResourceCategoryTypeName(doc *gaby.YamlDoc, resourceProvider ResourceProvider) (api.ResourceCategory, api.ResourceType, api.ResourceName, error)

func GetResourceInfo ¶

func GetResourceInfo(doc *gaby.YamlDoc, resourceProvider ResourceProvider) (*api.ResourceInfo, error)

func GetStringPaths ¶

func GetStringPaths(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.AttributeValueList, error)

GetStringPaths traverses the specified path patterns of the specified resource types and returns an api.AttributeValueList containing the values and registered information about all of the found string attributes matching the path patterns. It can also extract fields embedded in strings using registered embedded accessors.

func GetToolchainPath ¶

func GetToolchainPath(rp ResourceProvider) string

func GetVisitorMapForPath ¶

func GetVisitorMapForPath(resourceProvider ResourceProvider, rt api.ResourceType, path api.UnresolvedPath) api.ResourceTypeToPathToVisitorInfoType

GetVisitorMapForPath is used to get visitor info for a resolved path.

func GetVisitorOptions ¶ added in v0.1.15

func GetVisitorOptions(doc *gaby.YamlDoc, resourceProvider ResourceProvider) []string

GetVisitorOptions reads the VisitorOptions value from a YAML document using the resource provider's context path.

func InjectCommentKeys ¶ added in v0.1.25

func InjectCommentKeys(data map[string]any, comments map[string]string)

InjectCommentKeys adds comment entries into a map.

func IsCommentKey ¶ added in v0.1.25

func IsCommentKey(key string) bool

IsCommentKey returns true if the key matches the $comment$TYPE$TARGET pattern where TYPE is head, line, or foot. Equivalent to gaby.IsCommentKey.

func IsEmptyOrPlaceHolder ¶ added in v0.1.25

func IsEmptyOrPlaceHolder(s string) bool

func IsIntPlaceHolderValue ¶ added in v0.1.32

func IsIntPlaceHolderValue(v int) bool

func IsMultiLineString ¶ added in v0.1.14

func IsMultiLineString(s string) bool

IsMultiLineString returns true if the string contains embedded newlines (not just a trailing newline), indicating it is a multi-line string value that may benefit from line-level diffing. YAML scalar serialization via gaby appends a trailing newline, so a single-line value like "alice" becomes "alice\n" — this function correctly returns false for such values.

func IsNumber ¶

func IsNumber(s string) bool

IsNumber reports whether a strings characters are all within ['0'-'9'].

func IsNumeric ¶

func IsNumeric(c rune) bool

IsNumeric reports whether a character is within ['0'-'9'].

func IsPatchableString ¶ added in v0.1.14

func IsPatchableString(s string) bool

IsPatchableString returns true if the string may benefit from structured or line-level patching rather than wholesale replacement. This includes:

• Multi-line strings (for line-level text diff)
• JSON objects or arrays (for structural JSON diff)
• Strings with YAML structure (for structural YAML diff)

func IsPlaceholderValue ¶ added in v0.1.32

func IsPlaceholderValue(value any) bool

IsPlaceholderValue returns true if the value is a placeholder that should be replaced with a default.

func IsStringPlaceHolderValue ¶ added in v0.1.32

func IsStringPlaceHolderValue(v string) bool

func JoinPathSegments ¶

func JoinPathSegments(segments []string) string

JoinPathSegments escapes any dots in path segments and joins them for use in whole-path searches.

func JoinRelativePath ¶ added in v0.4.8

func JoinRelativePath(prefix, relative string) string

JoinRelativePath joins a relative path to the prefix it sits under. Either may be empty.

func LeadingWhitespace ¶ added in v0.1.25

func LeadingWhitespace(line string) string

LeadingWhitespace returns the leading whitespace prefix of a line.

func LowerFirst ¶

func LowerFirst(s string) string

LowerFirst lowercases the first character, which is useful for converting PascalCase to camelCase

func MarshalSpecSet ¶ added in v0.4.8

func MarshalSpecSet(set SpecSet) ([]byte, error)

MarshalSpecSet renders a spec set as YAML, the form LoadSpecSet reads.

func MatchesWhereResourceExpressions ¶

func MatchesWhereResourceExpressions(doc *gaby.YamlDoc, resourceInfo *api.ResourceInfo, expressions []*api.VisitorRelationalExpression) (bool, error)

MatchesWhereResourceExpressions evaluates each expression against a resource. For paths with the "ConfigHub." prefix, values are resolved from ResourceInfo metadata. For other paths, values are resolved from the resource's YAML document using YamlSafePathGetValueAnyType. Returns false if any expression doesn't match. Keep consistent with ValidWhereResourcePaths.

func MergeCommentsIntoData ¶ added in v0.1.25

func MergeCommentsIntoData(data any, comments map[string]string) any

MergeCommentsIntoData walks a parsed data tree and inserts comment keys at the corresponding map levels based on a flat comment map. The flat map uses dot-separated paths to indicate where in the nested structure the comment belongs. For example, "database.$comment$head$server" places the comment key "$comment$head$server" inside the "database" map.

func MergeKeyIdentity ¶ added in v0.2.12

func MergeKeyIdentity(values []string) string

MergeKeyIdentity joins merge-key values into the single string used to match an element between two revisions and to record array ordering.

func MergeKeyValues ¶ added in v0.2.12

func MergeKeyValues(element *gaby.YamlDoc, mergeKeys []string) ([]string, bool)

MergeKeyValues returns the merge-key values of an array element, in the order of keys. It reports false when the element is missing any of them, or when a value contains a character the path segment uses as punctuation: either way the element has no usable identity and the caller falls back to matching it by position.

func NameArrayElementsByMergeKey ¶ added in v0.2.22

func NameArrayElementsByMergeKey(doc *gaby.YamlDoc, path api.ResolvedPath,
	mergeKeyLookup MergeKeyLookup) (api.ResolvedPath, bool)

NameArrayElementsByMergeKey rewrites the bare numeric segments of a path into associative segments naming each element by its merge keys, resolved against doc. It is the inverse of what ResolveAssociativeSegments does, and reports whether anything changed.

It exists for the records written before the associative encoding did. An entry that says containers.0.image names whatever is first in line rather than the container, so it drifts with every insertion ahead of it, and no string rewrite can repair that: recovering the element's identity needs the document the entry was computed against, which only the caller can supply.

A segment is left numeric when the array declares no merge keys, when the element does not carry them, or when the document has nothing at that position. Positional resolution still works for such a path, which is what makes leaving it alone the safe answer rather than a failure. Segments are resolved against the path as it arrived, so a rewrite that could not be made never costs the ones after it.

func NormalizeStructurePath ¶ added in v0.4.8

func NormalizeStructurePath(path string) string

NormalizeStructurePath replaces numeric array indices and associative segments in a dot-separated path with "*", which is the form the structure lookups are keyed by.

This is deliberately narrower than normalizePath: the structure lookups are what decide whether a segment is a dynamic map key in the first place, so consulting them here would make their key function depend on their contents.

func PatchMutations ¶

func PatchMutations(parsedData gaby.Container, mutationsProtection, mutationsPatch, mutationsToSubtract api.ResourceMutationList, resourceProvider ResourceProvider, options *api.FunctionOptions) (gaby.Container, api.MutationConflictList, error)

PatchMutations applies a patch with no guard filtering. Equivalent to PatchMutationsGuarded with no filter, and the form every caller that predates guards uses.

func PatchMutationsGuarded ¶ added in v0.2.22

func PatchMutationsGuarded(parsedData gaby.Container, mutationsProtection, mutationsPatch, mutationsToSubtract api.ResourceMutationList, guards *GuardFilter, resourceProvider ResourceProvider, options *api.FunctionOptions) (gaby.Container, api.MutationConflictList, error)

PatchMutationsGuarded is PatchMutations with the guard filter applied: a path whose guards the operation's clearance does not cover is not written, and the withheld change is reported as a ConflictReasonGuarded carrying the guard that stopped it.

The guard check sits beside the protection check rather than replacing it. The two say different things -- protection says the target claimed a path and gives no reason, a guard names the reason and can be cleared by an operation that knows it -- and Protected does not migrate onto a guard key until guards carry the traffic.

func PathIsResolved ¶

func PathIsResolved(path string, includeAt bool) bool

func RegisterAttributeGroup ¶ added in v0.4.8

func RegisterAttributeGroup(
	resourceProvider ResourceProvider,
	groupName api.AttributeName,
	members ...api.AttributeName,
)

RegisterAttributeGroup declares that one attribute name stands for the union of others, so a function reading it through GetPathRegistryForAttributeName sees every member's paths. The group itself owns no paths and appears in no spec; it exists so attributes that must be distinguishable when written can still be read together.

func RegisterDeclaredAttributePaths ¶ added in v0.4.8

func RegisterDeclaredAttributePaths(
	resourceProvider ResourceProvider,
	compiled *CompiledSpecs,
	toolchainType workerapi.ToolchainType,
	descriptors map[api.AttributeName]AttributeDescriptor,
	enrich PathEnricher,
) error

RegisterDeclaredAttributePaths registers every attribute path the compiled specs declare for a toolchain, pairing each with the descriptor registered for its attribute name. It is the data-driven replacement for hand-rolled loops over per-concern tables.

Registration order is deterministic: resource types and attribute names are both sorted, so two runs of the same specs produce the same registry.

func RegisterPathsByAttributeName ¶

func RegisterPathsByAttributeName(
	resourceProvider ResourceProvider,
	attributeName api.AttributeName,
	resourceType api.ResourceType,
	pathInfos api.PathToVisitorInfoType,
	details *AttributeRegistrationDetails,
	isNeeded bool,
	isProvided bool,
)

RegisterPathsByAttributeName registers the specified path visitor specifications under the designated attribute name and resource type, and adds the provided getter and setter invocations, merging with existing registrations at the same paths, if any. If requested, the registered paths will be normalized so that associative lookups and array indices will be converted to wildcards, which is desired when matching all paths to the attribute. AttributeNameResourceName is used for references to resource names. Other attribute names are used for specific setters and/or getters, especially for attributes that appear in multiple resource types and/or locations. Provided values are special in that they represent sources of values for attributes of the specified attribute name, though they are logically distinct kinds of attributes.

func ReplaceStringPlaceholder ¶ added in v0.1.76

func ReplaceStringPlaceholder(s, replacement string) string

ReplaceStringPlaceholder replaces all occurrences of the placeholder string PlaceHolderBlockApplyString in s with replacement, including named placeholders that consist of the placeholder string followed by additional alphabetic characters. Surrounding text is preserved, so "confighubplaceholder-http" becomes replacement + "-http" and "confighubplaceholdersubdomain.test.example.com" becomes replacement + ".test.example.com".

func Reset ¶

func Reset(parsedData gaby.Container, mutationsProtection api.ResourceMutationList, resourceProvider ResourceProvider, options *api.FunctionOptions) error

Reset walks each path in mutationsProtection and, where Protected is false and the value at the corresponding location in parsedData is a string or int, sets the value back to the toolchain's placeholder marker (PlaceHolderBlockApplyString / PlaceHolderBlockApplyInt). Used by the "reset" function to revert the leaves last touched by a chosen subset of historical mutations to their unset state, leaving everything else alone.

func ResolveAssociativeSegments ¶

func ResolveAssociativeSegments(doc *gaby.YamlDoc, path string) (string, bool)

ResolveAssociativeSegments resolves ?key=value;@index segments in a path to numeric indices by looking up elements in the document. An array whose elements are identified by more than one field carries one pair per key — ?key1=value1,key2=value2;@index — and an element matches only when it has all of them. If no element matches, it considers the positional index:

• Out of bounds: the index is used as-is. This preserves Add-as-append semantics (e.g., a new element being appended to an array) and is harmless for Delete since the caller checks existence before deleting.
• In bounds, element has no merge-key field: legacy data — fall back positionally.
• In bounds, element has a different merge-key value: a different element. The segment is left unresolved so the caller can skip the operation.

Returns the resolved path and a bool that is true only when every associative segment was resolved (by merge-key match, by out-of-bounds index, or by legacy fallback).

func ResolveAssociativeSegmentsForInsertion ¶ added in v0.2.22

func ResolveAssociativeSegmentsForInsertion(doc *gaby.YamlDoc, path string) (string, bool)

ResolveAssociativeSegmentsForInsertion is ResolveAssociativeSegments for the path of an element a patch adds to a positional array, whose last segment is an anchor.

The anchor on such a segment digests the element the patch is about to create, not one to go looking for. Matching it against the target finds an element that merely has the same content — a repeated argument, a duplicated list entry — and puts the new element beside that one instead of at the position the patch named. So the last segment keeps its recorded index, which is the only thing that says where an insertion goes. Everything ahead of it is a path to an element that does exist, and resolves as usual.

func ResolveConfigHubPath ¶ added in v0.1.28

func ResolveConfigHubPath(path string, resourceInfo *api.ResourceInfo) (any, error)

ResolveConfigHubPath resolves a ConfigHub.* metadata path against a ResourceInfo struct. Returns the resolved value, or an error if the path is unsupported. Keep consistent with ValidWhereResourcePaths in api.go.

func ResourceAndCategoryTypeMaps ¶

func ResourceAndCategoryTypeMaps(parsedData gaby.Container, resourceProvider ResourceProvider) (
	resourceMap ResourceNameToCategoryTypesMap,
	categoryTypeMap ResourceCategoryTypeToNamesMap,
	err error,
)

ResourceAndCategoryTypeMaps returns maps of all resources in the provided list of parsed YAML documents, from from names to categories+types and categories+types to names.

func ResourceTypesForAttribute ¶

func ResourceTypesForAttribute(attributeName api.AttributeName, resourceProvider ResourceProvider) []api.ResourceType

ResourceTypesForAttribute returns a list of resource types associated with the specified attribute.

func ResourceTypesForPathMap ¶

func ResourceTypesForPathMap(pathMap map[api.ResourceType][]string) []api.ResourceType

ResourceTypesForPathMap returns a list of resource types from a path map.

func SetProtection ¶ added in v0.2.15

func SetProtection(parsedData gaby.Container, mutations api.ResourceMutationList, resource api.ResourceInfo, protection map[api.ResolvedPath]bool, resourceProvider ResourceProvider) (api.ResourceMutationList, []api.ResolvedPath)

SetProtection sets the Protected flag on path-level mutations of a single resource in mutations (typically a Unit's accumulated MutationSources), returning the updated list and the paths that could not be resolved.

The Protected flag records whether the path is a local override a merge must not overwrite: true protects it, false leaves it the merge's to update. A merge consumes these stored values, so editing them changes what a subsequent upgrade/merge will overwrite.

For each (path, value) in protection:

• Exact match: the entry at path has its Protected set to value; its other fields (including Value) are left intact.
• No exact match: the closest ancestor present in the resource's PathMutationMap (or, failing that, the resource-level mutation) supplies the MutationType and Index, so the new, more-specific entry keeps the same provenance. The entry's Value is taken from the data at path (via YamlSafePathGetDoc) — NOT copied from the ancestor, whose Value is a broader block — and Patch is left empty (it is a line-diff that does not apply to a freshly-set value). Because the protection lookup during PatchMutations walks to the most specific ancestor, this scopes the setting to path without disturbing the ancestor. This mirrors the parent-splitting in SubtractMutations' Case 3.

A path is returned in unresolved (and left unchanged) when its resource is absent, when it has neither an ancestor path nor a resource-level mutation to inherit from, or when it does not exist in the resource's data (so no Value can be extracted). parsedData and resourceProvider are used to locate the resource's document and read the value at each path. mutations is modified in place and also returned for convenience.

func SplitInlineComment ¶ added in v0.1.25

func SplitInlineComment(value string) (string, string)

SplitInlineComment splits a value string into the clean value and inline comment. An inline comment is text after " #" (space-hash). Quoted values are not split. Returns the clean value and the comment text (without the # prefix). If there is no inline comment, comment is empty.

func StoredMutationPathsNeedRewriting ¶ added in v0.4.10

func StoredMutationPathsNeedRewriting(mutations api.ResourceMutationList, resourceProvider ResourceProvider) bool

StoredMutationPathsNeedRewriting reports whether CanonicalizeStoredMutationPaths would have anything to do, without a document. It is the same question the canonicalization asks first, exported for a caller holding a record whose configuration data is not parsed yet: parsing it to discover there is nothing to rewrite is the cost worth avoiding.

func StripAssociativeSegments ¶

func StripAssociativeSegments(path string) string

StripAssociativeSegments converts ?key=value;@index segments to just the numeric index. For ?key=@index (direct index), extracts just the index. Non-associative segments are passed through as-is.

func StripCommentKeys ¶ added in v0.1.25

func StripCommentKeys(data any) any

StripCommentKeys returns a deep copy of data with all comment keys removed. Works recursively on map[string]any and []any. Non-map, non-slice values are returned as-is.

func StripComments ¶

func StripComments(yamlData []byte) ([]byte, error)

StripComments removes all comments from YAML data while preserving the structure and values. This is useful when comparing YAML documents where comments should be ignored.

func SubtractMutations ¶

func SubtractMutations(mutations, subtractMutations api.ResourceMutationList) (api.ResourceMutationList, api.MutationConflictList)

SubtractMutations removes from mutations any changes that overlap with subtractMutations, implementing the "preserve target-side changes" half of three-way merging. Typically invoked from PatchMutations via its mutationsToSubtract argument.

Use case:

source : ComputeMutations(base, sourceEnd)  // upstream changes
target : ComputeMutations(base, target)     // local customizations
patch  : SubtractMutations(source, target)  // source changes that don't conflict

When PatchMutations applies patch to target, target-side customizations remain because the source paths that would have overwritten them have been removed.

Both operands are expected to be diffs produced by ComputeMutations: Add, Delete, Update, or None at the resource level. (Replace, which AddMutations may produce when accumulating, is handled here defensively but not expected.) Update at the resource level has an empty Value — all changes live in PathMutationMap.

Algorithm:

1. Resource matching: by ResourceTypeAndName, then AliasesWithoutScopes from either side (so renamed resources subtract correctly).

2. Resource-level subtraction:

   | Subtract Type | Mutation Type | Result | |---------------|---------------|-------------------------------------------------| | Delete | Any | Drop (target removed the resource) | | Replace | Any | Drop (target redefined the resource) | | None | Any | Keep (target didn't change it) | | Any | None | Keep (source didn't change it) | | Update/Add | Delete | Keep source Delete; emit DeleteShadowed for | | | | each target mutation under it (the target's | | | | edits have nowhere to live once the resource | | | | is gone) | | Update/Add | Update/Add | Path-level subtraction |

3. Path-level subtraction: paths are walked using a NewPathPrefixIndex (binary search over a sorted path list) so prefix relationships are O(log n + k):

   - Case 1 (exact match): subtract has the same path → drop the source path. - Case 2 (subtract is ancestor): subtract has spec.containers.0 and source has spec.containers.0.image → drop the source path (parent was changed in target). - Case 3 (subtract is descendant): subtract has spec.containers.0.image and source has spec.containers.0 (whole block). If the source path is a Delete, keep it and emit a DeleteShadowed conflict for each target child path that's being erased — once the parent is gone the child changes can't apply. Otherwise keep the source path and splice in subtract's more-specific paths so PatchMutations' parent-before-child processing lets target's change win.

4. If subtraction empties an Update's PathMutationMap, the resource-level type downgrades to None.

Returns the patch with subtractions applied, plus a MutationConflictList recording every drop (resource-level and path-level) so callers can surface them as merge conflicts. The conflicts are advisory — the returned ResourceMutationList already reflects the drops.

Key behaviors:

• Target precedence: subtractMutations always wins where it overlaps.
• Alias awareness: matches resources across renames.
• Partial expansion: only splits a parent path when subtract has finer-grained conflicts under it; unaffected branches stay whole.

func TransformConfig ¶

func TransformConfig(
	originalData []byte,
	resourceProvider ResourceProvider,
	transform func(parsedData gaby.Container) ([]byte, error),
	options *api.FunctionOptions,
) ([]byte, bool, error)

TransformConfig applies a mutation function to configuration data, preserving YAML comments by diffing the changes and patching them onto the original data. This is a general-purpose mechanism that can be reused for any config transformation that operates on comment-stripped data (Starlark, CEL, etc.).

The transform function receives comment-stripped parsed YAML and returns modified YAML bytes. If the transform function returns nil bytes, the original data is returned unchanged.

func UpdatePathsFunction ¶

func UpdatePathsFunction[T api.Scalar](
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	updater func(T, VisitorContext) T,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdatePathsFunction traverses the specified path patterns of the specified resource types. The updater function simply needs to return the new attribute value, which must be of the type of the generic type parameter.

func UpdatePathsFunctionDoc ¶

func UpdatePathsFunctionDoc(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	updater func(*gaby.YamlDoc, VisitorContext) *gaby.YamlDoc,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdatePathsFunctionDoc traverses the specified path patterns of the specified resource types. The updater function simply needs to return the new attribute value, which must be a YamlDoc.

func UpdatePathsSetterArgument ¶

func UpdatePathsSetterArgument(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdatePathsSetterArgument traverses the specified path patterns of the specified resource types. For each path whose Details carry a DefaultValue, the value at the path is set to it. Supports string, int, and bool values. Skips paths where the current value is already set to a non-placeholder value. Otherwise, the path is not updated.

func UpdatePathsValue ¶

func UpdatePathsValue[T api.Scalar](
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	newValue T,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdatePathsValue traverses the specified path patterns of the specified resource types and updates the attributes with the provided value.

func UpdateStringPaths ¶

func UpdateStringPaths(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	newValue string,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdateStringPaths traverses the specified path patterns of the specified resource types and updates the attributes with the provided value. It can also inject fields embedded in strings using registered embedded accessors.

func UpdateStringPathsFunction ¶

func UpdateStringPathsFunction(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	updater func(string) string,
	upsert bool,
	options *api.FunctionOptions,
) error

UpdateStringPathsFunction traverses the specified path patterns of the specified resource types. The updater function simply needs to return the new attribute value. It can also inject fields embedded in strings using registered embedded accessors.

func VetPathsSetterArgument ¶

func VetPathsSetterArgument(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	resourceProvider ResourceProvider,
	options *api.FunctionOptions,
) (api.ValidationResult, error)

VetPathsSetterArgument traverses the specified path patterns and validates that current values match the DefaultValue their Details carry. Returns a ValidationResult with Passed=false and FailedAttributes listing any mismatched paths.

func VisitPaths ¶

func VisitPaths[T api.Scalar](
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	output any,
	resourceProvider ResourceProvider,
	visitor VisitorFunc[T],
	upsert bool,
	options *api.FunctionOptions,
) (any, error)

VisitPaths is a simple wrapper of the base visitor function. It traverses the specified path patterns of the specified resource types within the parsed configuration YAML document list.

func VisitPathsAnyType ¶

func VisitPathsAnyType(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	output any,
	resourceProvider ResourceProvider,
	visitor VisitorFuncAnyType,
	upsert bool,
	options *api.FunctionOptions,
) (any, error)

VisitPathsAnyType is a simple wrapper of the base visitor function. It traverses the specified path patterns of the specified resource types within the parsed configuration YAML document list.

func VisitPathsDoc ¶

func VisitPathsDoc(
	parsedData gaby.Container,
	resourceTypeToPaths api.ResourceTypeToPathToVisitorInfoType,
	keys []any,
	output any,
	resourceProvider ResourceProvider,
	visitor VisitorFuncDoc,
	upsert bool,
	options *api.FunctionOptions,
) (any, error)

VisitPathsDoc is the base visitor function. It traverses the specified path patterns of the specified resource types within the parsed configuration YAML document list.

func VisitResources ¶

func VisitResources(parsedData gaby.Container, output any, resourceProvider ResourceProvider, visitor ResourceVisitorFunc) (any, error)

VisitResources iterates over all of the resources/elements in a configuration unit and passes metadata about the resource as well as the document itself to a visitor function.

func VisitResourcesFiltered ¶

func VisitResourcesFiltered(parsedData gaby.Container, output any, resourceProvider ResourceProvider, options *api.FunctionOptions, visitor ResourceVisitorFunc) (any, error)

VisitResourcesFiltered iterates over resources, skipping those that don't match the WhereResourceExpressions in options or that fall outside its ResourceIndexes. The two restrictions are AND-ed. When options has neither, it behaves identically to VisitResources.

func VisitorInfoEqual ¶

func VisitorInfoEqual(pathVisitorInfo1, pathVisitorInfo2 *api.PathVisitorInfo) bool

VisitorInfoEqual reports whether two path visitor specifications, optionally including getter and setter invocations, match.

func YamlSafePathGetDoc ¶

func YamlSafePathGetDoc(
	doc *gaby.YamlDoc,
	resolvedPath api.ResolvedPath,
	notFoundOk bool,
) (*gaby.YamlDoc, bool, error)

YamlSafePathGetDoc returns a document node at a fully resolved path and whether it was found. An error indicates a parsing error. An error is also returned if the path is expected to exist.

func YamlSafePathGetValue ¶

func YamlSafePathGetValue[T api.Scalar](
	doc *gaby.YamlDoc,
	resolvedPath api.ResolvedPath,
	notFoundOk bool,
) (T, bool, error)

YamlSafePathGetValue returns a value at a fully resolved path and whether it was found. An error indicates a parsing error or that the value was not of the expected type.

func YamlSafePathGetValueAnyType ¶

func YamlSafePathGetValueAnyType(
	doc *gaby.YamlDoc,
	resolvedPath api.ResolvedPath,
	notFoundOk bool,
) (any, bool, error)

YamlSafePathGetValueAnyType returns a value at a fully resolved path and whether it was found. An error indicates a parsing error.