feat: add field for retaining first doc separator

Author: grothej

kyaml/kio/byteio_reader.go

@@ -160,6 +160,9 @@ type ByteReader struct {
 	// AnchorsAweigh set to true attempts to replace all YAML anchor aliases
 	// with their definitions (anchor values) immediately after the read.
 	AnchorsAweigh bool
+
+	// PreserveInitialDocSep if true adds the kioutil.PreserveInitialDocSep annotation to the first resource
+	PreserveInitialDocSep bool
 }
 
 var _ Reader = &ByteReader{}
@@ -333,6 +336,10 @@ func (r *ByteReader) decode(originalYAML string, index int, decoder *yaml.Decode
 				r.SetAnnotations[kioutil.SeqIndentAnnotation] = seqIndentStyle
 			}
 		}
+
+		if index == 0 && r.PreserveInitialDocSep && node.Kind == yaml.DocumentNode {
+			r.SetAnnotations[kioutil.InitialDocSepAnnotation] = "true"
+		}
 	}
 	var keys []string
 	for k := range r.SetAnnotations {

kyaml/kio/kioutil/kioutil.go

@@ -30,6 +30,9 @@ const (
 	// SeqIndentAnnotation records the sequence nodes indentation of the input resource
 	SeqIndentAnnotation AnnotationKey = internalPrefix + "seqindent"
 
+	// InitialDocSepAnnotation indicates that the initial document separator should be kept
+	InitialDocSepAnnotation AnnotationKey = internalPrefix + "initial-doc-sep"
+
 	// IdAnnotation records the id of the resource to map inputs to outputs
 	IdAnnotation AnnotationKey = internalPrefix + "id"