feat(yaml)!: add createmissingkey and appendtoarray to the yaml resource - #10193

Fix #60

Add two attributes to the yaml resource, so that a target can write a key that
does not exist yet, and can grow a sequence instead of replacing it.

createmissingkey creates the key when the document does not hold it,
building the missing intermediate keys as nested maps and matching the
indentation of the surrounding document.

targets:
  tag:
    kind: yaml
    spec:
      file: values.yaml
      key: $.image.tag
      createmissingkey: true

appendtoarray appends the value as a new entry of the sequence addressed by
key. It is idempotent: appending a value the sequence already holds reports no
change. Combined with createmissingkey, a missing sequence is created holding
the value as its sole entry.

targets:
  allowedTags:
    kind: yaml
    spec:
      file: values.yaml
      key: $.allowedTags
      appendtoarray: true

Both are supported by the default go-yaml engine only, and are rejected at
validation time when engine: yamlpath is set. createmissingkey also rejects a
key holding a wildcard or a recursive selector ($.agents[*].tag, $..tag),
since there is no way to create the key under each selected position.

Getting there surfaced a handful of pre-existing defects in the shared code
paths, fixed in their own commits: a key selecting several nodes resolves to a
detached wrapper rather than to the matched node itself, which was mistaken for a
key present everywhere; and the yamlpath engine counted processed keys per
document, which left its missing-key check unreachable.

⚠️ Breaking changes

Both affect the yaml resource used as a target, and both apply to manifests
that do not use the new attributes.

1. A wildcard key must now be held by every position it selects.

A key such as $.agents[*].tag used to update the entries carrying tag and
report a success, silently leaving the others untouched:

agents:
  - name: first
    tag: v1       # updated
  - name: second  # ignored, target reported success

It now fails instead, so a target never reports a success for an update it only
partially made. This matches the rule already applied to documents: a key missing
from one document of a multi-document file has always been an error.

Set searchpattern: true to keep the previous behaviour and update the positions
holding the key.

A recursive selector ($..tag) is unaffected: it searches for the key itself, so
it only ever selects positions already holding it and cannot match partially.

2. engine: yamlpath now fails when the key is missing from every document.

The check existed but was unreachable, so the target was silently reported as
skipped. It now errors, as the default go-yaml engine already did. Set
searchpattern: true to ignore files that do not carry the key.

Test

To test this pull request, you can run the following commands:

cd pkg/plugins/resources/yaml
go test

An end to end manifest covering both attributes is added in
e2e/updatecli.d/success.d/yaml/createandappend.yaml.

Additional Information

Checklist

• I have updated the documentation via pull request om/updatecli/website) repository.
• I have tested this pull request manually with a cuorks as expected.

Tradeoff

createmissingkey creates the key in every document of a multi-document file
when documentindex is not set, and in every file matched by file/files when
searchpattern is set. This follows the existing rule that a target evaluate
documents, but it means a key can land on documents that were never meant t
it. Set documentindex to narrow it down.

A missing sequence index ($.agents[0].name) is not created: materialising e
N of a sequence that does not have one has no sensible answer.

Potential improvement

Rejecting createmissingkey combined with searchpattern at validation time,
since the combination turns every glob match into a write rather than a sea