Merge branch 'main' into mkdocs

README.md

@@ -49,7 +49,7 @@ Both [Kyverno policies](https://kyverno.io/docs/kyverno-policies/) and policies
 
 [Kyverno policies](https://kyverno.io/docs/kyverno-policies/) use [Kubernetes](https://kubernetes.io) specific constructs for that matter that didn't map well with arbitrary payloads.
 
-This tool uses [assertion trees](#assertion-trees-replace-pattern-syntax) to implement `match` and `exclude` statements:
+This tool uses [assertion trees](#assertion-trees-replace-pattern-matching) to implement `match` and `exclude` statements:
 
 ```yaml
 apiVersion: json.kyverno.io/v1alpha1
@@ -104,7 +104,7 @@ spec:
                 Team: ($expectedTeam)
 ```
 
-Note that all context entries are lazily evaluated, a context entry will only be evaluated once. They can be used in all [assertion trees](#assertion-trees-replace-pattern-syntax), including `match` and `exclude` statements.
+Note that all context entries are lazily evaluated, a context entry will only be evaluated once. They can be used in all [assertion trees](#assertion-trees-replace-pattern-matching), including `match` and `exclude` statements.
 
 ### No preconditions, pattern operators, anchors or wildcards
 
@@ -113,7 +113,7 @@ Policies used by this tool don't support `preconditions`, pattern operators, anc
 Most of the time `preconditions` can be replaced by the more flexible `match` and `exclude` statements.
 
 Pattern operators, anchors and wildcards can be replaced with an improved pattern matching system.
-The new pattern matching system is called *assertion trees*, this is detailed [below](#assertion-trees-replace-pattern-syntax).
+The new pattern matching system is called *assertion trees*, this is detailed [below](#assertion-trees-replace-pattern-matching).
 
 ### Assertion trees replace pattern matching
 

docs/user/commands/kyverno-json.md

@@ -20,5 +20,6 @@ kyverno-json [flags]
 
 * [kyverno-json completion](kyverno-json_completion.md)	 - Generate the autocompletion script for the specified shell
 * [kyverno-json docs](kyverno-json_docs.md)	 - Generates reference documentation.
+* [kyverno-json jp](kyverno-json_jp.md)	 - Provides a command-line interface to JMESPath, enhanced with custom functions.
 * [kyverno-json scan](kyverno-json_scan.md)	 - scan
 

docs/user/commands/kyverno-json_docs.md

@@ -5,15 +5,25 @@ Generates reference documentation.
 ### Synopsis
 
 Generates reference documentation.
-
-  The docs command generates CLI reference documentation.
-
-  It can be used to generate simple markdown files or markdown to be used for the website.
+
+The docs command generates CLI reference documentation.
+It can be used to generate simple markdown files or markdown to be used for the website.
 
 ```
 kyverno-json docs [flags]
 ```
 
+### Examples
+
+```
+  # Generate simple markdown documentation
+  kyverno-json docs -o . --autogenTag=false
+
+  # Generate website documentation
+  kyverno-json docs -o . --website
+
+```
+
 ### Options
 
 ```

docs/user/commands/kyverno-json_jp.md

@@ -0,0 +1,40 @@
+## kyverno-json jp
+
+Provides a command-line interface to JMESPath, enhanced with custom functions.
+
+### Synopsis
+
+Provides a command-line interface to JMESPath, enhanced with custom functions.
+
+
+```
+kyverno-json jp [flags]
+```
+
+### Examples
+
+```
+  # List functions
+  kyverno-json jp function
+
+  # Evaluate query
+  kyverno-json jp query -i object.yaml 'request.object.metadata.name | truncate(@, `9`)'
+
+  # Parse expression
+  kyverno-json jp parse 'request.object.metadata.name | truncate(@, `9`)'
+
+```
+
+### Options
+
+```
+  -h, --help   help for jp
+```
+
+### SEE ALSO
+
+* [kyverno-json](kyverno-json.md)	 - kyverno-json
+* [kyverno-json jp function](kyverno-json_jp_function.md)	 - Provides function informations.
+* [kyverno-json jp parse](kyverno-json_jp_parse.md)	 - Parses jmespath expression and shows corresponding AST.
+* [kyverno-json jp query](kyverno-json_jp_query.md)	 - Provides a command-line interface to JMESPath, enhanced with Kyverno specific custom functions.
+

docs/user/commands/kyverno-json_jp_function.md

@@ -0,0 +1,34 @@
+## kyverno-json jp function
+
+Provides function informations.
+
+### Synopsis
+
+Provides function informations.
+
+
+```
+kyverno-json jp function [function_name]... [flags]
+```
+
+### Examples
+
+```
+  # List functions
+  jp function
+
+  # Get function infos
+  jp function truncate
+
+```
+
+### Options
+
+```
+  -h, --help   help for function
+```
+
+### SEE ALSO
+
+* [kyverno-json jp](kyverno-json_jp.md)	 - Provides a command-line interface to JMESPath, enhanced with custom functions.
+

docs/user/commands/kyverno-json_jp_parse.md

@@ -0,0 +1,23 @@
+## kyverno-json jp parse
+
+Parses jmespath expression and shows corresponding AST.
+
+### Synopsis
+
+Parses jmespath expression and shows corresponding AST.
+
+```
+kyverno-json jp parse [-f file|expression]... [flags]
+```
+
+### Options
+
+```
+  -f, --file strings   Read input from a JSON or YAML file instead of stdin
+  -h, --help           help for parse
+```
+
+### SEE ALSO
+
+* [kyverno-json jp](kyverno-json_jp.md)	 - Provides a command-line interface to JMESPath, enhanced with custom functions.
+

docs/user/commands/kyverno-json_jp_query.md

@@ -0,0 +1,26 @@
+## kyverno-json jp query
+
+Provides a command-line interface to JMESPath, enhanced with Kyverno specific custom functions.
+
+### Synopsis
+
+Provides a command-line interface to JMESPath, enhanced with Kyverno specific custom functions.
+
+```
+kyverno-json jp query [-i input] [-q query|query]... [flags]
+```
+
+### Options
+
+```
+  -c, --compact         Produce compact JSON output that omits non essential whitespace
+  -h, --help            help for query
+  -i, --input string    Read input from a JSON or YAML file instead of stdin
+  -q, --query strings   Read JMESPath expression from the specified file
+  -u, --unquoted        If the final result is a string, it will be printed without quotes
+```
+
+### SEE ALSO
+
+* [kyverno-json jp](kyverno-json_jp.md)	 - Provides a command-line interface to JMESPath, enhanced with custom functions.
+

go.mod

@@ -11,6 +11,7 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.28.2
 	sigs.k8s.io/kubectl-validate v0.0.0-20230927155409-3b3ca3ad91d0
+	sigs.k8s.io/yaml v1.3.0
 )
 
 require (
@@ -301,5 +302,4 @@ require (
 	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
 	sigs.k8s.io/release-utils v0.7.4 // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.3.0 // indirect
-	sigs.k8s.io/yaml v1.3.0 // indirect
 )

pkg/command/command.go

@@ -0,0 +1,72 @@
+package command
+
+import (
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+type Command struct {
+	parent       *cobra.Command
+	experimental bool
+	description  []string
+	websiteUrl   string
+	examples     []Example
+}
+
+func new(parent *cobra.Command, experimental bool, options ...option) Command {
+	cmd := Command{
+		parent:       parent,
+		experimental: experimental,
+	}
+	for _, opt := range options {
+		if opt != nil {
+			opt(&cmd)
+		}
+	}
+	return cmd
+}
+
+func New(parent *cobra.Command, options ...option) Command {
+	return new(parent, false, options...)
+}
+
+func NewExperimental(parent *cobra.Command, options ...option) Command {
+	return new(parent, true, options...)
+}
+
+func Description(c Command, short bool) string {
+	if len(c.description) == 0 {
+		return ""
+	}
+	var lines []string
+	lines = append(lines, c.description[0])
+	if !short {
+		lines = append(lines, "")
+		lines = append(lines, c.description[1:]...)
+		if c.experimental {
+			lines = append(lines, "", "NOTE: This is an experimental command.")
+		}
+		if c.websiteUrl != "" {
+			lines = append(lines, "", "For more information visit "+c.websiteUrl)
+		}
+	}
+	return strings.Join(lines, "\n")
+}
+
+func Examples(c Command) string {
+	if len(c.examples) == 0 {
+		return ""
+	}
+	var useLine string
+	if c.parent != nil {
+		useLine = c.parent.UseLine() + " "
+	}
+	var lines []string
+	for _, example := range c.examples {
+		lines = append(lines, "  # "+example.title)
+		lines = append(lines, "  "+useLine+example.command)
+		lines = append(lines, "")
+	}
+	return strings.Join(lines, "\n")
+}

pkg/command/example.go

@@ -0,0 +1,6 @@
+package command
+
+type Example struct {
+	title   string
+	command string
+}

pkg/command/option.go

@@ -0,0 +1,24 @@
+package command
+
+type option = func(*Command)
+
+func WithDescription(description ...string) option {
+	return func(d *Command) {
+		d.description = description
+	}
+}
+
+func WithWebsiteUrl(websiteUrl string) option {
+	return func(d *Command) {
+		d.websiteUrl = websiteUrl
+	}
+}
+
+func WithExample(title, command string) option {
+	return func(d *Command) {
+		d.examples = append(d.examples, Example{
+			title:   title,
+			command: command,
+		})
+	}
+}

pkg/commands/docs/command.go

@@ -3,19 +3,43 @@ package docs
 import (
 	"log"
 
-	"github.com/kyverno/kyverno/cmd/cli/kubectl-kyverno/command"
+	"github.com/kyverno/kyverno-json/pkg/command"
 	"github.com/spf13/cobra"
 )
 
-func Command(root *cobra.Command) *cobra.Command {
+func Command(parent *cobra.Command) *cobra.Command {
 	var options options
+	doc := command.New(
+		parent,
+		command.WithDescription(
+			"Generates reference documentation.",
+			"The docs command generates CLI reference documentation.",
+			"It can be used to generate simple markdown files or markdown to be used for the website.",
+		),
+		command.WithExample(
+			"Generate simple markdown documentation",
+			"docs -o . --autogenTag=false",
+		),
+		command.WithExample(
+			"Generate website documentation",
+			"docs -o . --website",
+		),
+	)
 	cmd := &cobra.Command{
 		Use:          "docs",
-		Short:        command.FormatDescription(true, websiteUrl, false, description...),
-		Long:         command.FormatDescription(false, websiteUrl, false, description...),
+		Short:        command.Description(doc, true),
+		Long:         command.Description(doc, false),
+		Example:      command.Examples(doc),
 		Args:         cobra.NoArgs,
 		SilenceUsage: true,
 		RunE: func(cmd *cobra.Command, _ []string) error {
+			root := cmd
+			for {
+				if !root.HasParent() {
+					break
+				}
+				root = root.Parent()
+			}
 			if err := options.validate(root); err != nil {
 				return err
 			}