📝 Document extended paths (go doc)

go.mod

@@ -6,7 +6,6 @@ require (
 	github.com/go-git/go-git/v5 v5.5.2
 	github.com/lithammer/dedent v1.1.0
 	github.com/stretchr/testify v1.8.1
-	golang.org/x/text v0.6.0
 	golang.org/x/tools v0.5.0
 	sigs.k8s.io/kustomize/api v0.12.1
 	sigs.k8s.io/kustomize/kyaml v0.13.10
@@ -56,6 +55,7 @@ require (
 	golang.org/x/mod v0.7.0 // indirect
 	golang.org/x/net v0.5.0 // indirect
 	golang.org/x/sys v0.4.0 // indirect
+	golang.org/x/text v0.6.0 // indirect
 	google.golang.org/protobuf v1.28.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect

main.go

@@ -5,8 +5,8 @@ import (
 	"os"
 
 	"github.com/kaweezle/krmfnbuiltin/pkg/plugins"
+	"github.com/kaweezle/krmfnbuiltin/pkg/utils"
 
-	"sigs.k8s.io/kustomize/api/konfig"
 	"sigs.k8s.io/kustomize/api/resmap"
 	"sigs.k8s.io/kustomize/api/resource"
 	"sigs.k8s.io/kustomize/kyaml/errors"
@@ -18,42 +18,6 @@ import (
 	"sigs.k8s.io/kustomize/kyaml/yaml"
 )
 
-const (
-	// build annotations
-	BuildAnnotationPreviousKinds      = konfig.ConfigAnnoDomain + "/previousKinds"
-	BuildAnnotationPreviousNames      = konfig.ConfigAnnoDomain + "/previousNames"
-	BuildAnnotationPrefixes           = konfig.ConfigAnnoDomain + "/prefixes"
-	BuildAnnotationSuffixes           = konfig.ConfigAnnoDomain + "/suffixes"
-	BuildAnnotationPreviousNamespaces = konfig.ConfigAnnoDomain + "/previousNamespaces"
-	BuildAnnotationsRefBy             = konfig.ConfigAnnoDomain + "/refBy"
-	BuildAnnotationsGenBehavior       = konfig.ConfigAnnoDomain + "/generatorBehavior"
-	BuildAnnotationsGenAddHashSuffix  = konfig.ConfigAnnoDomain + "/needsHashSuffix"
-)
-
-var BuildAnnotations = []string{
-	BuildAnnotationPreviousKinds,
-	BuildAnnotationPreviousNames,
-	BuildAnnotationPrefixes,
-	BuildAnnotationSuffixes,
-	BuildAnnotationPreviousNamespaces,
-	BuildAnnotationsRefBy,
-	BuildAnnotationsGenBehavior,
-	BuildAnnotationsGenAddHashSuffix,
-}
-
-func RemoveBuildAnnotations(r *resource.Resource) {
-	annotations := r.GetAnnotations()
-	if len(annotations) == 0 {
-		return
-	}
-	for _, a := range BuildAnnotations {
-		delete(annotations, a)
-	}
-	if err := r.SetAnnotations(annotations); err != nil {
-		panic(err)
-	}
-}
-
 func main() {
 
 	var processor framework.ResourceListProcessorFunc = func(rl *framework.ResourceList) error {
@@ -95,7 +59,7 @@ func main() {
 			}
 
 			for _, r := range rm.Resources() {
-				RemoveBuildAnnotations(r)
+				utils.RemoveBuildAnnotations(r)
 			}
 
 			rl.Items = rm.ToRNodeSlice()

pkg/extras/GitConfigMapGenerator.go

@@ -11,13 +11,28 @@ import (
 	"sigs.k8s.io/yaml"
 )
 
+// GitConfigMapGeneratorPlugin Generates a config map that includes two
+// properties of the current git repository:
+//
+//   - repoURL contains the URL or the remote specified by remoteName. by
+//     default, it takes the URL of the remote named "origin".
+//   - targetRevision contains the name of the current branch.
+//
+// This generator is useful in transformations that use those values, like for
+// instance Argo CD application customization.
+//
+// Information about the configuration can be found in the [kustomize doc].
+//
+// [kustomize doc]: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_
 type GitConfigMapGeneratorPlugin struct {
 	h                *resmap.PluginHelpers
 	types.ObjectMeta `json:"metadata,omitempty" yaml:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
 	types.ConfigMapArgs
+	// The name of the remote which URL to include. defaults to "origin".
 	RemoteName string `json:"remoteName,omitempty" yaml:"remoteName,omitempty"`
 }
 
+// Config configures the generator with the functionConfig passed in config.
 func (p *GitConfigMapGeneratorPlugin) Config(h *resmap.PluginHelpers, config []byte) (err error) {
 	p.ConfigMapArgs = types.ConfigMapArgs{}
 	err = yaml.Unmarshal(config, p)
@@ -31,6 +46,7 @@ func (p *GitConfigMapGeneratorPlugin) Config(h *resmap.PluginHelpers, config []b
 	return
 }
 
+// Generate generates the config map
 func (p *GitConfigMapGeneratorPlugin) Generate() (resmap.ResMap, error) {
 	// Add git repository properties
 
@@ -63,6 +79,7 @@ func (p *GitConfigMapGeneratorPlugin) Generate() (resmap.ResMap, error) {
 		kv.NewLoader(p.h.Loader(), p.h.Validator()), p.ConfigMapArgs)
 }
 
+// NewGitConfigMapGeneratorPlugin returns a newly created GitConfigMapGenerator.
 func NewGitConfigMapGeneratorPlugin() resmap.GeneratorPlugin {
 	return &GitConfigMapGeneratorPlugin{}
 }

pkg/extras/doc.go

@@ -0,0 +1,49 @@
+/*
+Package extras contains additional utility transformers and generators.
+
+[GitConfigMapGeneratorPlugin] is identical to ConfigMapGeneratorPlugin
+but automatically creates two properties when run inside a git repository:
+
+  - repoURL gives the URL of the origin remote.
+  - targetRevision gives the current branch.
+
+[ExtendedReplacementTransformerPlugin] is a copy of ReplacementTransformerPlugin
+that provides extended target paths into embedded data structures. For instance,
+consider the following resource snippet:
+
+	helm:
+	  parameters:
+	    - name: common.targetRevision
+	      # This resource is accessible by traditional transformer
+	      value: deploy/citest
+	    - name: common.repoURL
+	      value: https://github.com/antoinemartin/autocloud.git
+	  values: |
+	    uninode: true
+	    apps:
+	      enabled: true
+	    common:
+	      # This embedded resource is not accessible
+	      targetRevision: deploy/citest
+	      repoURL: https://github.com/antoinemartin/autocloud.git
+
+In the above, the common.targetRevision property of the yaml embedded in the
+spec.source.helm.values property is not accessible with the traditional
+ReplacementTransformerPlugin. With the extended transformer, you can target
+it with:
+
+	fieldPaths:
+	- spec.source.helm.parameters.[name=common.targetRevision].value
+	- spec.source.helm.values.!!yaml.common.targetRevision
+
+Note the use of !!yaml to designate the encoding of the embedded structure. The
+extended transformer supports the following encodings:
+
+  - YAML
+  - JSON
+  - TOML
+  - INI
+  - base64
+  - Plain text (with Regexp)
+*/
+package extras