Accept a string for overlay/match by= on documents - #1022

Summary

Fixes #303.

The @overlay/match reference documents by= as Function|String on documents, map items and array items. A string is short-hand for overlay.map_key() with the same argument. On a document, the string form fails:

#@overlay/match by="kind"
---
kind: Deployment

Expected 'overlay/match' annotation keyword argument 'by' to be function, but was starlark.String

by=overlay.map_key("kind") works on the same document.

ArrayItemMatchAnnotation.MatchNodes (pkg/yttlibrary/overlay/array_item_match_annotation.go:96) and MapItemMatchAnnotation.MatchNodes (map_item_match_annotation.go:84) turn a string by= into overlay.map_key(<string>) before calling it. DocumentMatchAnnotation.MatchNodes (document_match_annotation.go:88) passed by= straight to its type switch, which only accepts a callable.

DocumentMatchAnnotation.MatchNodes now does the same conversion, copied from the array item version. by="kind" on a document now builds the same overlay.map_key_matcher that by=overlay.map_key("kind") builds. For any other type of by=, the error now reads to be either string (for map key) or function, but was ..., the same text the array item version uses. Exact matching, used when merging data values and data values schema documents, is unchanged because it returns before by= is read.

Testing

pkg/yamltemplate/filetests/ytt-library/overlay/doc-by-key.tpltest is the document counterpart of array-by-key.tpltest and map-by-key.tpltest. It overlays two left documents twice, once with by="kind" and once with by=overlay.map_key("kind"), and expects both to update only the Service document.

I have not compiled this change or run the tests: there was no Go toolchain where I made it, so CI will be the first build. What I checked by hand:

• Every identifier in the new block exists with the signature it is called with. The block is the array item one, with the same names.
• I traced the expected output through mergeDocument, mergeMapItem and the YAML printer, using a small Python model of those paths. No existing test or example asserts the old document error text.
• Added lines fit revive's line-length-limit (80 columns, tabs counted as 4), and the wrapped lines follow gofmt's continuation style. git diff --check is clean.

Branched from develop at c9dc038.

🤖 Generated with Claude Code